Local wallet storage and CLI
Local wallet storage and CLI
The local wallet is wired into stdio and the interactive CLI. HTTP remains keyless. Policy administration, backup/restore, validation, signing, authenticated journaling and retry/replacement handling are implemented. Signing happens only under the authenticated policy.
localWalletStore(config).createOrLoad() creates or authenticates the one wallet
at ~/.incentiv-mcp/wallet. It returns verified public metadata with
status: "locked", reason: "policy_not_configured", and a disabled, unconfigured
policy for a new wallet. Constructing the store or importing its modules does not access storage.
The production factory fixes the path within an explicit local startup profile and uses the live network verifier;
the injectable constructor is for isolated tests, not an MCP configuration option.
--wallet-profile NAME selects a separate wallet at
~/.incentiv-mcp-profile-NAME/wallet with credential service
io.incentiv.mcp.wallet.v1.profile.NAME. The default profile retains the original
path and io.incentiv.mcp.wallet.v1 service. Profile names cannot be paths, are
case-sensitive lowercase identifiers, and are fixed before CLI/MCP startup.
Selecting a profile never moves keys, copies policy, transfers funds, or removes
the original wallet. Each profile keeps its own immutable creation anchor and
operation journal. A restore into another profile still requires disabling every
other copy of that same account before enabling it.
Custody and permissions
The default wrapping-key backend is the native OS credential store through the
exact dependency @napi-rs/keyring@2.1.0: Windows Credential Manager, macOS
Keychain, or Linux Secret Service. Linux explicitly requests Secret Service;
there is no implicit fallback to the transient kernel keyring or a file.
An unavailable or locked service returns wallet_locked.
Setting INCENTIV_ALLOW_FILE_KEY=1 explicitly selects file-key mode for a new
wallet. An existing wallet keeps its recorded backend; this flag never migrates
it. Every load of a file-key wallet requires the flag. Its master.key is a
random 32-byte wrapping key, not the owner key. The public result warns that a
copy of the wallet directory contains everything needed to unlock it and that
file-key mode cannot protect against a shell-capable agent using the same OS user.
Every load checks the wallet tree’s permissions. POSIX paths must belong to the
current user and have mode 0700 for directories or 0600 for files. Windows
requires protected owner-only DACLs. Symlinks, junctions/reparse points, hard-linked
files, unexpected root artifacts, and unsafe parent aliases are rejected. Existing
permissions are never silently repaired. New secret files are protected before
secret bytes are written.
Windows ACL operations are in the inspectable
windows-permissions.ps1 asset, copied
alongside compiled code by npm run build. It receives only public paths/actions
on stdin and runs with -File under the normal execution policy. It does not use
encoded commands, execution-policy bypasses, or antivirus exclusions. A blocked
script or failed ACL check produces wallet_permissions_invalid.
Each Node process reuses one PowerShell helper over private stdin/stdout pipes; every request reads the current ACLs and reparse-point attributes again. Permission results are never cached. A malformed response, pipe failure, helper exit or 20-second request timeout rejects outstanding operations. The helper closes after 30 seconds idle or when its parent exits; it never keeps an idle CLI alive. No wallet keys, passwords, file contents or network requests enter this helper.
Keystore v1 and test vector
wallet upgrade-implementation is a local, password-confirmed transition for the
single reviewed IncentivAccount upgrade. It retains wallet ID, owner/account,
storage binding, wrapping key and all request IDs. An authenticated journal update
records the new network/manifest and the compatible pending-operation manifest
pair before the envelope is resealed. The journal retains its original network ID
and historical manifests, so an interruption between the two writes can be retried
with the same command. Pending signatures, replacement bytes and spending
reservations survive; all exception approvals are cleared and unsigned requests
are cancelled. Policy ends disabled. Ordinary loading and capability approval
still reject unrelated identity changes. The historical v1 cryptographic vector
is intentionally unchanged and authenticates against the previous configuration.
Old backups require wallet restore --in FILE --upgrade-implementation, recovery
and administration authentication, and an empty destination. The source backup is
never rewritten. New backups retain the authenticated network/manifest lineage.
The strict envelope schema is in keystore.ts.
It accepts only schema version 1, HKDF-SHA256, AES-256-GCM, salt "0", and a strict
disabled or configured policy. Configured policies include a separate scrypt
administration verifier authenticated by the envelope. Extra fields, unknown algorithms, and noncanonical
base64 or incorrect field lengths are rejected.
- Generate the 32-byte secp256k1 owner key and 32-byte wrapping key in memory.
- Derive a 32-byte AES key with HKDF-SHA256, a fresh 16-byte salt, and UTF-8 info
incentiv-mcp/wallet/v1. - Encrypt the owner key with AES-256-GCM, a fresh 12-byte nonce, and a 16-byte tag.
- Additional authenticated data is the UTF-8 RFC 8785 canonical serialization
of the entire envelope with
cipherreplaced by{"name":"AES-256-GCM"}. This binds the full network identity, approved manifest ID, wallet ID, owner, account, account salt, policy, key-storage kind/creation token, and KDF metadata. The GCM operation authenticates the nonce and ciphertext separately. - Before reading the wrapping key, verify network pins, approved capabilities, and the network identity. After decryption, recompute the owner and smart-account address locally, then compare them with the authenticated metadata.
test/fixtures/wallet-v1.json publishes the
exact AAD, public test keys, derived AES key, nonce, ciphertext, and tag for
interoperability. Those test keys are public; never fund their account.
Regenerate the fixture with
node --import tsx scripts/generate-wallet-vector.mjs.
Secret buffers are cleared after use and private keys never enter storage results, journals, subprocess arguments, or network requests. Node/V8, OpenSSL, and native credential APIs do not guarantee complete memory zeroization.
Creation, locking, and recovery
~/.incentiv-mcp/
wallet.create.lock # exclusive process lock with heartbeat
wallet.binding.json # durable creation identity; retained
wallet.commit.json # permanent commit barrier for CLI-initialized wallets
wallet.tmp-<wallet-id>/ # only during incomplete creation
wallet/
wallet.json # authenticated encrypted envelope
public.json # replaceable display cache
master.key # explicit file-key mode only
disabled # emergency-stop marker, when present
operations/
journal.json # authenticated atomic history and spend ledger
Creation first verifies the network, writes the immutable filesystem binding,
and, in OS-backed mode, writes a public wallet-binding-v1 anchor under service
io.incentiv.mcp.wallet.v1. The anchor detects a lost filesystem tree without
enumerating or exposing other credentials. Then creation writes the wrapping key
under pending:<wallet-id>:<creation-lock-token> and builds the encrypted wallet
in a private staging directory. File-key mode puts master.key inside that same
directory. Files are flushed before the directory is renamed to wallet;
directory metadata is flushed where supported.
OS-backed creation then copies the key to
wallet:<wallet-id>:<creation-lock-token>, reloads and authenticates the committed
wallet, and only then removes the pending credential. File-key creation also
reloads and authenticates the committed files. Only after this succeeds is public
metadata returned. Repeated calls preserve the encrypted wallet and its addresses;
public.json is regenerated from authenticated data and never selects an address.
A valid staged or committed wallet with its matching pending credential resumes without generating new keys. Incomplete/corrupt artifacts, conflicting credentials, and orphan bindings remain intact for explicit recovery. The implementation never automatically deletes an orphan key, repairs a keystore, or creates a replacement. A readable OS anchor also prevents enabling file-key mode from bypassing a lost OS-backed wallet. If all filesystem evidence is deleted and the OS store is unavailable, explicit file-key mode cannot establish whether an old wallet existed; this is not a backup or recovery mechanism.
The creation lock has a random token, host identity, PID, start timestamp, and
heartbeat. A timestamp older than 60 seconds permits recovery only if the lock
belongs to this host and the PID is provably absent. A live/reused PID is never
evicted. Recovery is serialized by an exclusive wallet.create.recover.lock.
Unverifiable ownership or an abandoned recovery lock requires inspection, not
automatic deletion. Contention is bounded and can return wallet_locked; retrying
uses the same wallet. The same root lock now serializes wallet sessions, policy
updates, backup snapshots and transaction/nonce handling. Sends reconcile pending
records before allocating a nonce. Emergency disable creates its marker without
waiting for this lock; sign and relay paths recheck it.
Error codes
| Code | Meaning |
|---|---|
wallet_locked |
Credential service unavailable or another creator/recovery lock owns the wallet. |
wallet_permissions_invalid |
Permission/ACL verification or Windows helper execution failed. |
wallet_path_unsafe |
Symlink, reparse point, hard link, or wrong filesystem object type. |
file_key_not_allowed |
Existing file-key wallet lacks explicit opt-in. |
keystore_missing |
Creation evidence exists but the encrypted wallet is missing. |
wrapping_key_missing / wrapping_key_invalid |
No matching key, or an invalid key length. |
unsupported_wallet_version |
An explicit format migration is required. |
keystore_authentication_failed |
Authentication tag or locally rederived addresses disagree. |
wallet_network_mismatch |
Wallet identity differs from configured/pinned identity. |
capability_manifest_unapproved |
Capabilities differ from the wallet’s approved manifest. |
wallet_recovery_required |
Other malformed, conflicting, incomplete, or inaccessible evidence. |
Storage errors do not include raw credential-provider or filesystem error payloads.
Policy and recovery commands
incentiv-mcp wallet policy configure
incentiv-mcp wallet doctor
incentiv-mcp wallet init
incentiv-mcp wallet capabilities approve --previous <config.json>
incentiv-mcp wallet recover
incentiv-mcp wallet approve <request-id>
incentiv-mcp wallet disable
incentiv-mcp wallet operation resolve <request-id>
incentiv-mcp wallet operation resolve <request-id> --replace
incentiv-mcp wallet backup --out <file>
incentiv-mcp wallet restore --in <file>
incentiv-mcp wallet migrate [1]
policy configure reads a policy JSON path interactively, displays its contents
and pending operations, asks for explicit confirmation, and requires the existing
administration passphrase (or establishes it on first setup). Copy and adjust
wallet-policy.example.json. Its empty recipient
allowlist permits no autonomous recipient; replace sample amounts with your explicit limits.
All amounts are integer raw token units: 1000000 is one unit of a 6-decimal token.
Token keys are native or pinned contract addresses. ERC-20 transfers need selector
0xa9059cbb under the token’s targets entry; swaps additionally need the exact
router/token selectors and either explicit trustedRpcOrigins or two
administrator-attested independently operated RPC origins. Add the gas token to
the token limits too.
For automated use of the public RPC, add
"trustedRpcOrigins": ["https://rpc.incentiv.io"] during authenticated policy
configuration. This trusts that source; it does not claim operator independence.
Missing or empty trust preserves the original independent-source rule. Existing
v1 envelopes and backups are not rewritten on load. Permitted operations need no
per-operation terminal prompt once policy signing is enabled.
wallet init reads and displays the policy and establishes its administration
factor before creating keys. It starts disabled and creates an empty authenticated
journal. The binding includes a recovery verifier; a permanent filesystem and OS
credential commit barrier is written before the directory is committed. Recovery
authenticates that verifier and only discards incomplete creation attempts with no
commit evidence or complete staged keystore. Legacy/MCP-created orphan bindings
have no such proof and remain preserved. Complete staged keystores resume with
their original keys through create_agent_wallet.
Capability approval takes the previous complete configuration and compares it to the currently configured proposal. It verifies all proposed pins/handshake before unlocking, requires the administration factor and unchanged displayed review, rejects pending signatures and any immutable identity change, and preserves all history and consumed spend. The journal records an approved manifest before the envelope activates it; interrupted updates remain retryable. Unsigned approvals are cancelled and policy is disabled until reviewed again.
wallet doctor checks the network and the bundler without reading credentials
or wallet storage.
Passphrases must be at least 12 bytes and are entered through a no-echo TTY.
Arguments, environment variables and piped stdin are never accepted for them.
The administration factor is required to loosen policy, re-enable, approve exact
exceptions, export an encrypted backup or resolve/rebroadcast a stuck operation.
disable may run without a TTY and does not need the network or a passphrase.
Exception approval displays and binds the canonical intent, exact unsigned operation/hash, gas/payment limits, and swap minimum/deadline for at most five minutes. Retrying the same request ID consumes that exact approval. Replacement review builds a zero-value self-transfer at the original nonce with native gas; either original or replacement may win. Both reservations remain until a verified receipt resolves the nonce. Disabling prevents either from being rebroadcast.
Backup refuses while any operation owns a nonce. The portable bundle encrypts
the envelope, wrapping key and complete authenticated journal using scrypt
N=131072,r=8,p=1,dkLen=32 and AES-256-GCM with fresh salt/nonce. It is reloaded,
decrypted and rederived before success is reported. It never overwrites an output
file. Restore refuses any existing wallet evidence, rechecks the network, uses
new local wrapping custody and the atomic creation protocol, and starts disabled.
Unsigned approvals are cancelled while preserving request IDs. Re-enable requires
acknowledging that source copies are disabled or destroyed and reconciling history
and the on-chain nonce. Cross-machine duplicate use cannot be prevented.
Migration to the already-current v1 format verifies it without changing the key or account; unsupported targets fail without a keystore rewrite. Actual future format migrations must retain a recoverable encrypted backup through verification.