filecoin-project / filecoin-project/filecoin-pin

Epic: wallet auth without raw private keys

Open
#457 7 comments 1 reaction 1 assignee Claimed by @SgtPooki View on GitHub
enhancement ready-for-work team/filecoin-pin team/fs-wg
Dominant language
TypeScript
Stars
26
Forks
21
Avg merge
5d 18h
Merged PRs (30d)
27

Description

### Description

`filecoin-pin` wallet auth is a raw private key handed over as an env var: `PRIVATE_KEY` everywhere, plus session-key secrets in CI and server configs. No encrypted-at-rest option, no OS keychain, and the recommended GitHub Actions setup stores the wallet key as a repo secret.

This is the tracking epic for the signer backends that replace raw-key auth. OpenWallet Standard (OWS) was evaluated as a backend (spike: #458) and rejected: as of 2026-08-17 its repo had no maintainer commit, review, or merge since 2026-06-19, the sole human maintainer had been removed from the npm packages on 2026-08-03, the SECURITY.md contact routed to that same removed identity, and a policy-bypass report ([open-wallet-standard/core#228](https://github.com/open-wallet-standard/core/issues/228)) had been open without response since May. Evidence: [OWS proof-of-life memo](https://gist.github.com/SgtPooki/c44b6a8a667bb2c80a48d5e0767b8cce). The OWS backend was removed from #458; the auth seam it was built on ships without it.

The seam this epic hangs on is in two PRs: #458 adds source-aware auth-mode resolution in `src/utils/cli-auth.ts`, and #687 added the injectable viem `Account` accepted by `initializeSynapse()`. That seam covers ordinary CLI commands only. The pinning server builds private-key/session-key configs directly, the upload action requires `walletPrivateKey` and calls `initializeSynapse({privateKey})`, and session owner commands call `privateKeyToAccount()`. Unifying those surfaces is its own child issue below.

We deliberately do not recommend cloud KMS (AWS/GCP) backends. filecoin-pin is a reference implementation for Filecoin Onchain Cloud; pointing users at centralized cloud HSMs is off-mission. The injectable `Account` seam means anyone who wants a KMS-backed signer can wire one up themselves; we document the seam, not a vendor.

### Impact

- CI users store the wallet's raw private key as a repo secret when a scoped, revocable session key would bound the blast radius.
- Server operators leave keys readable in process env and shell history, and the daemon holds the decrypted key in memory for its lifetime.
- Blocks adoption by teams with key-handling policies.

### Child issues

Each child is tagged with its primary beneficiary: `[agent]` agent runtimes, `[human]` operators and CLI users, `[risk]` containment for everyone.

- [ ] #681 `[human]` keystore v3: encrypted keystore files + passphrase prompt, the recommended CLI default (port from synapse-sdk [#554](https://github.com/FilOzone/synapse-sdk/pull/554)); prerequisite for keychain
- [ ] #682 `[agent]` session keys as the recommended CI path: upload-only permission profile (CreateDataSet+AddPieces only; the default permission set also grants SchedulePieceRemovals and TerminateService), upload-action `sessionKey` input, expiry/runway warnings, rotation story, secret redaction
- [ ] #679 `[agent]` unify auth surfaces: pinning server, upload action, and session owner commands consume the same signer resolution as the CLI; prerequisite for any hosted-MCP or daemon auth story
- [ ] #680 `[human]` OS keychain storage via `@napi-rs/keyring`; headless unlock for assistant-spawned local MCP tools is scoped to session-key material, never the owner keystore
- [ ] #589 `[human]` password-manager vaults (1Password/Bitwarden/LastPass); outside the agent mapping

### Out of scope

- OpenWallet Standard (OWS). The #458 spike integrated it; we evaluated upstream health and removed the backend from the PR rather than shipping it as experimental. Rationale with evidence: [OWS proof-of-life memo](https://gist.github.com/SgtPooki/c44b6a8a667bb2c80a48d5e0767b8cce). The source-aware precedence the spike built ships in #458 without it; the injectable viem `Account` landed in #687.
- Hardware wallets (Ledger/Trezor); separate issue if requested.
- First-party cloud KMS backends (AWS/GCP); the seam supports bring-your-own `Account`, documented in the session-key child.
- Devnet keeps auto-resolving from `devnet-info.json`.

Recommended posture regardless of backend: a dedicated hot wallet holding only working funds, capped via `payments setup` allowances (`setMaxAllowances`), funded from a cold wallet. Document this alongside whichever backend lands first.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.