thePR0M3TH3ANandClaude Fable 5
b0e2a309a4
Driving the CLI from an empty app directory turned up a gap that no test
covered: there was no way to create a vault. Every path assumed you already
had a seed and told you to export SEEDPASS_MNEMONIC, so a new user could not
get started at all. Python has generate_bip85_seed; the port did not.
fingerprint create fills that in with the same construction Python uses --
32 bytes of OS entropy through BIP-85 app 39 index 0. The entropy call sits
outside any try/catch on purpose, carried over from Python's entropy audit:
nothing may catch a CSPRNG failure and substitute a value.
Where the phrase goes is a deliberate choice rather than a default. This is
the one secret in SeedPass with no other copy, so:
- the destination is validated BEFORE generating, and delivery happens
BEFORE the profile is created -- a failure at either point leaves
nothing behind rather than a vault whose seed nobody has;
- --out writes 0600 with O_EXCL, so an existing file is never clobbered;
- with no destination and a non-TTY stdout it refuses outright, instead of
writing the only copy of a seed into a pipe -- a log, a transcript, an
agent's context.
Also fixed, all found the same way:
- use --exec always exited 0, so chaining a deploy command after it with
&& reported success even when the deploy failed. The sink child's exit
status is now the CLI's own.
- the sink command spec split on whitespace and ignored quotes, so
--exec 'sh -c "..."' -- the most common form there is -- handed sh the
fragments of the script and died on an unterminated string.
- --tags work,dev silently stored a single tag named "work,dev" that no
search would ever match. Commas and spaces both separate now.
Two normal states reported raw errno: a stopped agent said
'connect ENOENT /.../agent.sock', and an occupied --out path said EEXIST.
The capability map claimed ssh/pgp were unported. Both work and are at
parity with Python; automation branches on that list, so it now describes
this build.
Verified against Python on a TS-generated seed: same fingerprint, same
password, same TOTP code. 320 JS tests and 36/36 cross-impl checks pass.
Co-Authored-By: Claude Fable 5 <[email protected]>
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.