thePR0M3TH3ANandClaude Opus 5
0c48c1f9dc
High-risk partitions move ssh/pgp/seed/nostr/managed_account records out of
the vault index into a separately encrypted file, so those kinds need a SECOND
factor beyond the master password. The index keeps a stub carrying kind, label
and archived — enough to list, nothing more.
Both file formats are byte-compatible with Python and verified bidirectionally:
TS unwraps a Python-written key envelope and reads a Python-written partition,
and Python unwraps a TS-written envelope and reads a TS-written partition. That
matters more than usual here — the entries are SSH keys, PGP keys and seeds, so
a partition only one implementation can open is lost secrets, not an
inconvenience. This required a Fernet encryptor in core, which had been
decrypt-only by design; the header now says why that exception exists and that
no other Fernet payload should ever be written.
**One deliberate divergence, and it is the reason this is not a straight port.**
Python records an unlock session in agent_high_risk_unlock.json, and that record
contains the partition_key_tag — the value the partition file's encryption key
is derived from. So for the life of any Python unlock session the partition is
decryptable from disk alone, with no factor, by anything that can read the app
directory; both files live in the same directory, so "can read one" implies "can
read the other". That voids the guarantee the partition exists to provide.
Verified empirically before writing any of this.
Here the tag lives only in the session agent's memory, beside the parent seeds
it already holds, with the same TTL discipline — and in the API process's memory
for the API. Nothing derived from the factor reaches disk, asserted by a test
that scans every file in the app directory for the tag, and confirmed on a live
install. No file format or interop changes; only where the live session lives.
Other properties the tests pin:
- a locked partition refuses reveal rather than deriving from the stub, which
would return a plausible wrong secret
- locking the vault drops the high-risk grant, which is scoped to it
- the grant expires on its own clock, typically much shorter than the seed's
- unlock is owner-gated: a scoped token cannot reach it
- the tag is absent from the audit log, which records only that an unlock
happened
- the factor comes from the environment, never argv
- factor-set refuses to replace an existing factor, since a new partition key
would make an existing partition permanently unreadable
- migrate writes the partition BEFORE the index, so a crash between them
cannot leave stubs pointing at records that were never stored
Approval gates port straight across: one-shot (or N-use) authorizations for
export / reveal_parent_seed / private_key_retrieval, consumed under the store
lock so two callers cannot both spend the last use, with every failure mode
getting its own reason string matching Python's. A corrupt store reads as empty,
which fails closed.
API: /api/v1/high-risk/{status,unlock,lock} are real rather than 501. Unlock
needs the bearer token, the master password header AND the factor header; a
wrong factor gets one indistinguishable reason so probing cannot tell failures
apart.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01Vtx94nXDmNgXEeThUZP4QN
seedpass-js
The SeedPass command-line interface, TypeScript port.
It reads and writes the same ~/.seedpass profiles as the Python
implementation — same derivations, same vault format, same Nostr sync — and
adds a session agent plus a scoped-token surface designed for AI agents and
automation.
Install
Requires Node.js 22 or newer.
# from a checkout
cd js && pnpm install && pnpm --filter @seedpass/cli build
node packages/cli/dist/seedpass-js.mjs --version
The build produces one self-contained file (dist/seedpass-js.mjs) plus a
.sha256 next to it. Copy it anywhere on your PATH; it has no runtime
dependencies beyond Node itself.
Quick start
export SEEDPASS_APP_DIR=~/.seedpass # omit to use the default
# Create a profile (mnemonic and password come from the environment,
# never from the command line)
export SEEDPASS_MNEMONIC="your twelve or twenty-four words"
export SEEDPASS_PASSWORD="your master password"
seedpass-js fingerprint add --name main
unset SEEDPASS_MNEMONIC # not needed again
# Unlock once per session through the agent
seedpass-js agent start &
seedpass-js vault unlock --ttl 900
seedpass-js entry add password github.com --length 20 --username you
seedpass-js entry reveal github.com
seedpass-js entry totp-codes
seedpass-js use github.com --clipboard
seedpass-js vault lock
Design: reference-first output
Default output never contains secret values. Entries are addressed by
reference (sp://entry/<id>), and secret-bearing fields are reported as
has_* flags:
$ seedpass-js entry get api-token
{ "id": "5", "ref": "sp://entry/5", "label": "api-token",
"kind": "key_value", "has_value": true, ... }
Plaintext leaves the vault only through commands that say so
(entry reveal, entry totp-codes, entry export-document,
util generate-password), or through a sink, which delivers a secret to its
destination without routing it through this process's output:
seedpass-js use api-token --exec ./deploy.sh # SEEDPASS_SECRET in the child env
seedpass-js use api-token --stdin-to "wc -c" # quote specs that contain flags
seedpass-js use api-token --clipboard
Scoped tokens for agents
An agent can be given a token that grants exactly what it needs and nothing else. Secrets are materialized inside the session agent, so the token holder never receives the seed and can never escalate to owner operations.
# As the owner:
seedpass-js agent token-issue --scope read use \
--kind key_value --label-regex '^api-' --uses 2 --ttl 600
# In the agent's process — no mnemonic, no password:
export SEEDPASS_TOKEN=<token>
seedpass-js entry list # metadata only
seedpass-js use api-token --exec ./deploy.sh # permitted
seedpass-js entry reveal api-token # denied: scope 'reveal' not granted
# Back as the owner — every grant, delivery and denial is recorded:
seedpass-js agent audit-verify
seedpass-js agent audit-tail -n 20
Environment
| Variable | Purpose |
|---|---|
SEEDPASS_APP_DIR |
Profile directory (default ~/.seedpass) |
SEEDPASS_MNEMONIC |
Parent seed; needed for profile creation, otherwise use the agent |
SEEDPASS_PASSWORD |
Master password, for fingerprint add and vault unlock |
SEEDPASS_TOKEN |
Scoped token; puts the CLI in token mode |
SEEDPASS_AGENT_SOCK |
Override the agent socket path |
SEEDPASS_SECRET |
Set by use --exec in the child process only |
Compatibility
Interoperability with the Python implementation is verified on every change
by scripts/cross_impl_check.py: each side opens the other's profiles,
backups round-trip, edits are mutually visible, conflict merges agree, and a
snapshot published by Python restores here with secrets intact. See
docs/typescript_port_compatibility_matrix.md.
Not yet ported: PGP RSA keys (not byte-reproducible; ed25519 is at parity),
and the semantic and api command groups.