thePR0M3TH3ANandClaude Opus 5
75e370d098
L-1 — three entry kinds derive from BIP-85 app 32 at the entry's index:
ssh@N -> 32 bytes of m/83696968'/32'/N'
pgp@N -> 32 bytes of m/83696968'/32'/N' (the SAME 32 bytes)
password@N -> 64 bytes of the same, then PBKDF2
So ssh@N and pgp@N are byte-for-byte the same Ed25519 private key, and
password@N takes that key as its entropy prefix. The password stays safe (256
unknown bits remain, PBKDF2 is one-way) but this is not key separation, and
SSH keys are exactly what gets exported to a server or uploaded to a forge.
Deliberately NOT fixing the derivation itself yet. Domain-separating the three
uses is a versioned protocol change in both implementations, i.e. a new
derivation path -- and the project's own note is that "a derivation bug does
not throw, it quietly produces a secret that cannot be recovered". Adding one
immediately before the first outside review inverts the point of the review.
The v2 design is written up in TODO.md instead, ready to implement after it.
What ships is the audit's short-term recommendation, which needs no derivation
change: notice the state and say so. findDerivationCollisions /
find_derivation_collisions report cross-kind clashes at one app-32 index,
worst first, in both implementations with identical message text -- a user
moving between the two must not be told different things about one vault.
Wired into every path the state can arrive by: vault import (CLI and TUI, both
implementations), nostr restore's merge, `vault import --inspect` before
anything is written, and a new `util check-derivation` for auditing an
existing vault (exit 1 when it finds something, for scripts).
Neither implementation can create the state -- index == vault id, ids unique,
watermark prevents reuse -- so this is about imported, foreign, and merged
data, which is also why it must never be the thing that fails an import: it
reports, never refuses, and tolerates malformed input.
The lead test in each implementation does not exercise the detector at all.
It derives the keys and compares the bytes, proving the property the detector
reports. Without that, the rest only checks that a written-down rule is
applied consistently, and a derivation change could falsify the rule with
everything still green.
L-8 (Python) — while wiring the above it turned out Python's import_backup had
the same unbound-plaintext-import gap the audit found in TypeScript: the
wrapper carries a `fingerprint` and nothing compared it. Now fixed there too,
with a new ProfileMismatchError so the TUI can offer the override instead of
reporting a generic failure.
The comparison is against the fingerprint DERIVED FROM THE SEED, not the
profile directory's name. In production they are the same string, but the
question worth asking is "was this backup made from my seed?", and only the
seed answers it -- comparing directory names refused a legitimate restore of
the same seed into a freshly named profile, which test_account_roundtrip_
restore caught immediately. It is enforced only when the wrapper records
something that is actually a fingerprint: a backup carrying some other label
offers no evidence about its source seed, and refusing on no evidence blocks
restores without making anyone safer.
All guards mutation-verified on both sides.
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.