feat(auth): auth-mode seam with injectable signer

[SgtPooki]

What changed

Adds the auth-mode seam the wallet-auth epic (#457) builds on: source-aware precedence resolution for the mutually exclusive auth flags (an explicit flag beats an env var; two explicit modes are a hard error), and an injectable viem Account accepted by initializeSynapse() so signer backends plug in without SDK changes.

This PR began as an OpenWallet Standard spike. The OWS backend was removed in 7928f6f after an upstream health check: no maintainer activity since 2026-06-19, the sole human maintainer removed from npm, and an unanswered policy-bypass report (open-wallet-standard/core#228). Evidence: OWS proof-of-life memo.

How to verify

pnpm install && pnpm run build && pnpm exec vitest run. Precedence behavior is covered in src/test/unit/cli-auth.test.ts (explicit-beats-env, lone session-key halves, conflict errors, devnet fallback).

Notes

No user-facing flags added or removed relative to master; the --wallet/OWS options that existed only on this branch are gone. First consumers of the seam: keystore (#681) and session keys in CI (#682).

[Copilot]

Pull request overview

This PR adds OpenWallet Standard (OWS) wallet authentication to filecoin-pin’s CLI auth resolver, allowing users to supply an OWS wallet ID (and optional passphrase) so signing can be performed by an OWS-managed viem Account instead of exposing raw private keys.

Changes:

• Added --wallet/OWS_WALLET_ID and --wallet-passphrase/OWS_WALLET_PASSPHRASE CLI options and wired them into the shared auth path.
• Introduced src/core/ows/index.ts to lazily load the OWS viem adapter and produce a viem Account.
• Updated CLI flows to await parseCLIAuth() after making it async to support OWS account resolution.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/utils/cli-options.ts	Adds new Commander options for OWS wallet ID + passphrase.
src/utils/cli-auth.ts	Makes auth parsing async; adds OWS account resolution and precedence.
src/core/ows/index.ts	New OWS integration module that builds a viem Account via dynamic import.
src/core/synapse/index.ts	Updates missing-auth error message to mention OWS wallet auth.
src/add/add.ts	Awaits async auth parsing before Synapse init.
src/import/import.ts	Awaits async auth parsing before Synapse init.
src/payments/auto.ts	Awaits async auth parsing before Synapse init.
src/payments/deposit.ts	Awaits async auth parsing before Synapse init.
src/payments/fund.ts	Awaits async auth parsing before Synapse init.
src/payments/status.ts	Awaits async auth parsing before Synapse init.
src/payments/withdraw.ts	Awaits async auth parsing before Synapse init.
src/rm/remove-all-pieces.ts	Awaits async auth parsing before Synapse init.
src/rm/remove-piece.ts	Awaits async auth parsing before Synapse init.
package.json	Adds OWS core + adapter dependencies.
pnpm-lock.yaml	Locks OWS dependencies and platform-specific optional packages.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[SgtPooki]

@HavenCTO @Apha205, updated the PR.. feel free to leave feedback

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 4 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

[rvagg]

continuing on my precedence suggestion below, the complexity in here now deserves a bunch of tests to show it does what you expect, and document what you expect too

[SgtPooki]

preferences should be much more clear now

[rvagg]

no more need for async in here, you can drop that and all of the await additions to make the diff shrink significantly

[rvagg]

@SgtPooki did your testing extend beyond the payments command into actual data onboarding? This JSON.stringify looks like a problem for our bigints in 712 payloads, does it get past this? https://github.com/open-wallet-standard/core/blob/76c8c67d6c73bf57805432fc15a2e48d12168c6c/bindings/node-adapters/src/viem.js#L36

[SgtPooki]

@SgtPooki did your testing extend beyond the payments command into actual data onboarding? This JSON.stringify looks like a problem for our bigints in 712 payloads, does it get past this? open-wallet-standard/core@76c8c67/bindings/node-adapters/src/viem.js#L36

I didn't do super thorough testing, but I have now. I fixed this in our implementation here, added unit tests, and also opened an upstream fix: github.com/open-wallet-standard/core#242

[Copilot]

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Comments suppressed due to low confidence (3)

src/utils/cli-auth.ts:187

• OWS mode precedence is determined only from the wallet option source (const owsSource = sourceOf('wallet', ...)). If OWS_WALLET_ID is set via env but the user passes --wallet-passphrase explicitly to disambiguate from an env PRIVATE_KEY, parseCLIAuth() will still treat both modes as env-sourced and throw a conflict. This also contradicts the comment that a mode spanning several options should take the strongest source (like the session-key mode does). Consider tracking walletPassphrase in AuthOptionSources and using strongest(walletSource, walletPassphraseSource) when computing the OWS candidate source.

  const walletAddressSource = sourceOf('walletAddress', walletAddress)
  const sessionKeySource = sourceOf('sessionKey', sessionKey)
  const sessionSource =
    walletAddressSource && sessionKeySource ? strongest(walletAddressSource, sessionKeySource) : undefined
  if (sessionSource)
    candidates.push({ mode: 'sessionKey', source: sessionSource, label: '--wallet-address/--session-key' })
  const owsSource = sourceOf('wallet', owsWalletId)
  if (owsSource) candidates.push({ mode: 'ows', source: owsSource, label: '--wallet/OWS_WALLET_ID' })

src/utils/cli-options.ts:20

• collectAuthOptionSources() tracks provenance for mutually exclusive auth options, but AUTH_OPTION_NAMES currently omits walletPassphrase. If a user relies on env OWS_WALLET_ID and provides --wallet-passphrase explicitly (or vice versa), parseCLIAuth can't treat the OWS mode as explicitly selected, which can cause avoidable "Conflicting authentication options" errors when other env auth (e.g. PRIVATE_KEY) is also set. Include walletPassphrase in the collected option names (and in AuthOptionSources) so OWS mode can apply the same "strongest source wins" rule as session-key mode.

 * Commander attribute names for the mutually exclusive auth flags whose
 * provenance {@link parseCLIAuth} needs to resolve precedence.
 */
const AUTH_OPTION_NAMES = ['privateKey', 'wallet', 'walletAddress', 'sessionKey', 'viewAddress'] as const

src/utils/cli-auth.ts:123

• The conflict error text says "Provide exactly one signing mode", but the candidate set includes read-only mode (--view-address), which is explicitly non-signing. This can be confusing when users hit a conflict involving view-only auth. Consider wording this as "authentication mode" (or similar) instead.

  const conflict = (modes: AuthModeCandidate[], envOnly: boolean): Error => {
    const labels = modes.map((c) => c.label).join(' and ')
    const hint = envOnly ? ' Pass an explicit flag to disambiguate.' : ''
    return new Error(`Conflicting authentication options: ${labels}. Provide exactly one signing mode.${hint}`)
  }

[rvagg]

what's going on here?

[SgtPooki]

just to prevent 0x-1 when trying to convert from any negative bigint passed through OWS. shouldn't happen based on looking through code in syanpse-sdk, but it could happen in the future..

[rvagg]

tbh this was a very light re-review; the only thing that stands out to my eye is the hex <0n thing, otherwise as long as this works in practice then it seems good to me to ship as an experimental feature
@jennijuju might like to try and integrate this into the skill(s) she's working on

[Apha205]

@SgtPooki @rvagg , tested against Haven CLI

The CLI can authenticate and sign transactions using an OWS-backed viem Account (OWS_WALLET_ID) without requiring access to a raw private key.

• OWS_WALLET_ID successfully resolved to EVM account address
• Synapse initialized using the OWS-backed viem Account path and selected two Calibration storage providers
• pieces_added transactions were submitted and signed by the OWS-managed wallet
• Upload completed successfully

No PRIVATE_KEY was set or used during the test.

Screenshots from the debug logs attached below.

[SgtPooki]

it seems good to me to ship as an experimental feature

@rvagg do you have any preference on how we communicate this as an "experimental feature" ?

[rvagg]

@SgtPooki nope; I'll leave that to you, I'm not demanding you even take action on making it "experimental", I'm just noting that "OpenWallet" is pretty young and not very well used and obviously has rough edges; it suggests some caution in enshrine it in a way that might be easy to yank it out in the future.

[SgtPooki]

Following up on the "pretty young and not very well used" concern: I dug into OWS upstream health and you were more right than either of us knew. No maintainer commit, review, or merge since 2026-06-19; the sole human maintainer was removed from the npm packages on 2026-08-03 and his GitHub account is gone; SECURITY.md routes to that same removed identity; and a policy-bypass report (#228, wallet delete --confirm skips the policy engine and all safety gates) has sat unanswered since May. Full evidence with dates: https://gist.github.com/SgtPooki/c44b6a8a667bb2c80a48d5e0767b8cce

So rather than enshrine it, or even flag it experimental, I removed the OWS backend from this PR entirely (7928f6f). What remains is the part worth merging: source-aware auth precedence resolution and the injectable viem Account seam in initializeSynapse, which the keystore and session-key work in #457 builds on. I'll update the PR title/description to match.

[rvagg]

approval pending removal of async and the awaits and renaming this before it lands as a misnamed commit