feat(auth): add OpenWallet Standard wallet support

[SgtPooki]

What changed

Wires the OpenWallet Standard (openwallet.sh) viem adapter into filecoin-pin's existing AccountConfig path. Users can now authenticate via an OWS-managed wallet, and the private key never leaves the OWS native core.

• New src/core/ows/index.ts builds a viem Account from an OWS wallet ID via @open-wallet-standard/adapters/viem.
• --wallet <id> / OWS_WALLET_ID and --wallet-passphrase / OWS_WALLET_PASSPHRASE flags added to CLI commands using the shared auth options (add, import, payments, data-set, provider, rm). The server daemon and session commands still require PRIVATE_KEY; OWS support there is follow-up work.
• parseCLIAuth() resolver: --wallet takes precedence over --private-key / PRIVATE_KEY. Devnet auto-resolve preserved.
• Synapse SDK is already viem-native (AccountConfig branch in initializeSynapse()), so no SDK plumbing changes are required.

Status

Ready for review. This started as a spike and is now opened for review and collaboration. The read path is validated end-to-end on Calibration (see Verification below). Real signing against synapse-sdk still needs to be exercised before merge.

The Haven team (@Apha205, @HavenCTO) raised this on #457 and offered to validate OWS for their use case, resolve conflicts, and exercise real signing on Calibration. Reviewers are flagged so they can test against their setup.

Before merge: a funded add upload or payments setup against Calibration, to confirm the OWS-backed Account signs correctly end-to-end (the read path is already validated below).

How to verify

1. Install OWS: npm i -g @open-wallet-standard/core
2. Create or import a wallet:
   • New: ows wallet create --name fil-test
   • Or import an existing EVM key: echo "$YOUR_TESTNET_KEY" | ows wallet import --name fil-test --private-key --chain ethereum
3. Run: OWS_WALLET_ID=fil-test pnpm exec tsx src/cli.ts payments status --network calibration
4. Confirm Synapse initializes and balances are returned without PRIVATE_KEY set.

Notes / risks

• Platform coverage: OWS prebuilt binaries published for linux-x64-gnu, linux-arm64-gnu, darwin-x64, darwin-arm64. No Windows or musl/Alpine target on npm today. Windows and Alpine users continue to use PRIVATE_KEY.
• @open-wallet-standard/core is Node-only (CJS, uses fs / child_process). Browser exports are unaffected, OWS only enters the CLI / server / Action paths.

Verification

Validated end-to-end on Calibration with an OWS-managed wallet imported from an existing testnet private key:

$ unset PRIVATE_KEY
$ OWS_WALLET_ID=fil-test pnpm exec tsx src/cli.ts payments status --network calibration

┌  Filecoin Onchain Cloud Payment Status
│
◇  ✓ Configuration loaded
◇  ✓ Data sets fetched
◇  ⚠ Actual storage calculated with N warning(s)
│
│  ━━━ Current Status ━━━
│  Wallet
│    Owner address: 0x<redacted>
│    Network: Filecoin - Calibration testnet
│    FIL: <redacted> tFIL
│    USDFC: <redacted> USDFC
│
│  Filecoin Pay
│    Balance: <redacted> USDFC
│    Locked: <redacted> USDFC (30-day reserve)
│    Available: <redacted> USDFC
│    ...
│
│  WarmStorage Usage
│    Stored: <redacted>
│    Runway: <redacted>
│    ...
│
└  Status check complete

Confirmed:

• Synapse SDK initialized through the OWS-backed viem Account (no SDK plumbing changes).
• parseCLIAuth() resolver picked --wallet / OWS_WALLET_ID over PRIVATE_KEY / dotenv-loaded keys.
• Owner address derived by OWS matches the address derived from the same private key by viem's privateKeyToAccount, so existing balances and data sets resolve unchanged.
• "Failed to fetch provider-side pieces" warnings are unrelated to auth (provider-side reporting).

Behavior notes

• Uses the Ethereum CAIP-2 namespace, not native Filecoin. filecoin-pin signs via FEVM through synapse-sdk's viem path, so getOwsAccount() always asks OWS for an eip155:<chainId> account (eip155:314 mainnet, eip155:314159 Calibration). OWS wallets typically also expose a native Filecoin entry (fil:mainnet → f1...) derived from the same seed, and that one is not used. When you run ows wallet list you'll see both; the 0x... EVM address is the one filecoin-pin authenticates with.
• The OWS viem adapter falls back to any eip155:* account on the wallet when the requested chain isn't explicitly registered (wallet.accounts.find((a) => a.chainId.startsWith("eip155:"))). OWS derives one secp256k1 key shared across all EVM chains, so the same address resolves on Calibration even when the wallet only lists eip155:1. Our chain: eip155:<id> parameter is best-effort.
• getOwsAccount() defensively rejects any account whose address isn't a 40-char EVM address, in case a future adapter version returns a non-eip155 account.
• Real signing (a funded add upload or payments setup) was not exercised in this run; only the read path through Synapse.create + balance/data-set queries.

Refs #457

Closes #457

[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

[SgtPooki]

ping @hugomrdias @Apha205 @BravoNatalie

[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]

@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}`)
  }