feat(wallet): key custody through an external secret manager

CHANGELOG.md

@@ -8,6 +8,31 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 Nothing yet.
 
+## [0.3.0] — 2026-08-05
+
+External key custody. `foc-cli` can now hold a *reference* to a key kept in a secret manager instead of the key itself, closing the gap that left MCP and CI with no option but a key in the config file. Contains one behaviour change to `wallet init` (hence the minor bump).
+
+### Added
+
+- `wallet init --keyRef <provider>:<reference>` — a third custody mode alongside a raw key and a Foundry keystore. The config stores only the pointer; the key is fetched into memory per command and never written to disk. Nothing prompts, so unlike keystore mode this works under the MCP server and CI. `--keyProject` scopes the reference; omitted, the provider picks its own default. `clawdi` is the first provider. ([#33])
+- `wallet balance` now reports `keySource` (`keyRef` / `keystore` / `privateKey` / `none`), so a vault-backed setup is verifiable at a glance — the address proves which key signed, this proves where it came from. Never the key. ([#33])
+- Preflight checks on every wallet-touching command, covering all three custody modes: `WALLET_NOT_CONFIGURED`, `MALFORMED_KEY_REF`, `KEY_REF_PROVIDER_MISSING`, `KEYSTORE_INTERACTIVE_ONLY` and `KEYSTORE_TOOL_MISSING` now arrive as typed errors with actionable CTAs, instead of escaping as an untyped throw from inside key resolution or from `cast`. The preflight does not resolve the key — that needs an authenticated provider and a round trip, and belongs at use time. A missing provider or missing Foundry is reported as `retryable` and deliberately carries **no** command: the wallet is intact and the fix lies outside foc-cli, so the only thing worth suggesting would have been one that discards a working configuration. ([#33])
+- `wallet init --force`. ([#33])
+
+### Changed
+
+- **`wallet init` no longer silently replaces a configured wallet.** An explicit method used to overwrite whatever was configured, discarding a key that may have been the only copy. It now names what is at stake — the derived address for a private key, the path for a keystore, the reference for a key reference, never the key itself — and asks on a terminal, or fails with `WALLET_ALREADY_CONFIGURED` and a `--force` CTA in agent mode. The consequence stated is the one that actually applies: only a stored private key is destroyed by the swap, while a keystore file stays on disk and a vault key stays in the vault. Re-running the *same* method with the same value replaces nothing, and neither does adding or changing `--keyProject` on a configured reference — both are never blocked. That CTA replays the caller's own options minus the secret: a `--privateKey` passed on the refused invocation comes back as `0x...`, never the key. Automation that re-runs `wallet init --auto` expecting a fresh key must now pass `--force`. ([#33])
+- Call-to-action guidance only offers a key-reference method when that provider's CLI is actually installed on the machine — suggesting a tool the caller does not have is a dead end. The reference docs still describe every provider. ([#33])
+- Key resolution accepts a `0x` + 64 hex value only when it stands on its own, and refuses output holding more than one. A loose match was the dangerous case: every 32-byte value is a valid secp256k1 key, so the leading 64 hex digits of a longer blob would have been accepted and signed with — as a different address — rather than failing. ([#33])
+- Windows: an npm-installed provider helper is a `.cmd`, which is a script rather than an executable and cannot be launched directly (Node has refused to since the fix for CVE-2024-27980). Those are now run through `cmd.exe`, with references restricted to a character set the shell treats literally so a tampered config still cannot become command execution. Previously the PATH probe found the helper, the preflight passed, and the launch failed with `EINVAL` — reported as "not logged in / key missing / wrong project", none of which was true. ([#33])
+- A reference that is itself a private key (`clawdi:0x…` — the `--privateKey` mix-up with the provider prefix included) is refused at init and by the preflight rather than stored, and every message or result that quotes a reference redacts key-like runs first. A key is pure hex, so the character allowlist alone waved it through — stored under a field documented as safe to display, sent to the provider as a lookup name, and echoed verbatim into the use-time error envelope bound for the MCP result and the logs. ([#33])
+
+### Documentation
+
+- `references/key-injection.md` — identification table first (most of the time the answer is "already set up, run normally"), then setup, providers, what the mode does and does not protect, and the error catalog. ([#33])
+- `references/integrations/clawdi-vault.md` — the Clawdi recipe, including the per-project scoping that most often bites. ([#33])
+- `references/keystore-setup.md` now points at the key-reference mode as the automation-safe alternative it previously had no answer for. ([#33])
+
 ## [0.2.0] — 2026-07-23
 
 Agent-hardening release ([#30]), driven by a 609-invocation live smoke campaign on Calibration and a keystore field test. Contains one breaking change (hence the minor bump).
@@ -106,7 +131,8 @@ Initial public release.
 - MCP server mode and the two agent skills (`foc-cli`, `foc-docs`).
 - MCP client compatibility fixes.
 
-[Unreleased]: https://github.com/FIL-Builders/foc-cli/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/FIL-Builders/foc-cli/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/FIL-Builders/foc-cli/releases/tag/v0.3.0
 [0.2.0]: https://github.com/FIL-Builders/foc-cli/releases/tag/v0.2.0
 [0.1.1]: https://www.npmjs.com/package/foc-cli/v/0.1.1
 [0.1.0]: https://www.npmjs.com/package/foc-cli/v/0.1.0
@@ -130,3 +156,4 @@ Initial public release.
 [#28]: https://github.com/FIL-Builders/foc-cli/issues/28
 [#29]: https://github.com/FIL-Builders/foc-cli/issues/29
 [#30]: https://github.com/FIL-Builders/foc-cli/pull/30
+[#33]: https://github.com/FIL-Builders/foc-cli/pull/33

cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foc-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "CLI, MCP server, and AI agent skills for Filecoin Onchain Cloud — upload, verify (PDP), and pay for storage on Filecoin with USDFC.",
   "type": "module",
   "main": "dist/src/index.js",