SeedPass/docs/seedpass_vault_identity_spec.md

SeedPass Vault & Identity Specification — v1 (draft)

Status: draft, extracted from working code — 2026-08-18 Reference implementations: Python (src/seedpass/), TypeScript (js/packages/core/) Conformance oracle: scripts/cross_impl_check.py (36 checks) + js/packages/test-vectors/

1. Purpose and scope

One deterministic account tree, multiple management interfaces. This document specifies the on-disk formats, derivation rules, and interoperability requirements that let independent applications operate the same vault — SeedPass as the sovereign superset (root management, recovery, all secret kinds), and narrower clients such as BitLogin (identity and managed-account administration) implementing a subset.

The core promise this spec exists to protect:

An entry index is a permanent cryptographic coordinate. "Alice is managed account #184" must deterministically identify the same derived identity for the life of the root — across implementations, devices, and decades.

Everything here is extracted from code that ships and is cross-verified, not aspiration. Where an implementation falls short of a requirement, that is listed in §12 rather than papered over.

Out of scope, deliberately: authentication protocols, signing services, policy/authorization engines, organizations, payments, workflows. Those are application features. They store their data in this format (§8) but are not part of it. A format that absorbed them would make every implementation carry every application's complexity.

2. Terminology

Term	Meaning
Parent seed	A BIP-39 mnemonic (12/18/24 English words). The root of everything.
Profile / fingerprint	One parent seed's vault. Identified by its fingerprint (§3.2).
Entry	One record in the vault index, keyed by its entry id.
Entry id / index	Decimal-string key of an entry; doubles as the derivation index for derived kinds (§6). Never reused (§7).
Managed account	A managed_account entry: a child BIP-39 seed derived at the entry id, with its own fingerprint — a delegable sub-identity.
Implementation	Any software reading/writing this format.

Normative words MUST / MUST NOT / SHOULD / MAY are used in the RFC-2119 sense.

3. Canonicalization and identity

3.1 Canonical mnemonic form

Before any validation, derivation, or fingerprinting, a mnemonic MUST be canonicalized:

NFKD → trim → lowercase → collapse internal whitespace to single spaces

Deriving from a non-canonical string that merely passed a word-count check produces a vault no other implementation (or the user's written-down phrase) can reopen. Implementations MUST reject mnemonics that fail BIP-39 checksum validation after canonicalization — BIP-39 seed derivation itself accepts any string, so a typo silently creates an unrecoverable vault.

3.2 Profile fingerprint

fingerprint = uppercase( hex( SHA-256( utf8(canonical_mnemonic) ) )[0:16] )

16 uppercase hex characters. Identifies the profile directory and appears in managed_account.fingerprint for child seeds.

3.3 Master password normalization

Password-derived keys (§4.2) normalize the password as NFKD then strip Python's str.strip() whitespace set (which differs from JS trim(); the Python set is normative).

4. Container formats

4.1 Vault index file (seedpass_entries_db.json.enc)

Stored as either a bare ciphertext or a JSON wrapper {"kdf": {...}, "ct": "<base64>"}. The plaintext is the vault index (§5) as UTF-8 JSON.

Payload formats, by prefix:

Prefix	Format	Write?
V3|	12-byte nonce ‖ AES-256-GCM ciphertext‖tag	current — all writes
V2:	same construction, legacy prefix (with Fernet fallback on auth failure)	read-only
(none)	legacy Fernet token	read-only

Key: the index key (see docs/SPEC.md key hierarchy):

seed   = BIP39-seed(canonical_mnemonic)          # no passphrase
master = HKDF-SHA256(seed,   salt=∅, info="seedpass:v1:master",  32)
key    = HKDF-SHA256(master, salt=∅, info="seedpass:v1:storage", 32)

The index key derives from the seed, not the password — changing the master password re-wraps only the parent seed file.

4.2 Parent seed file (parent_seed.enc)

JSON wrapper {"kdf", "ct"}; ct is a V3 payload of the canonical mnemonic under a password-derived key:

salt = SHA-256(fingerprint)[0:16]
key  = PBKDF2-HMAC-SHA256(normalized_password, salt, iterations, 32)   # default 200 000

kdf records {name: "pbkdf2", version: 1, params: {iterations}, salt_b64}. Argon2id (name: "argon2id", params time_cost/memory_cost/parallelism) is also valid. Implementations MUST bound KDF parameters read from disk before running them (the block sits outside the AEAD; unbounded values are a denial-of-service).

4.3 Per-profile config (seedpass_config.json.enc)

Same encryption as the index, same key. Free-form JSON object; implementations MUST preserve keys they do not understand.

5. The vault index

{
  "schema_version": 4,
  "entries": { "<id>": { /* entry record, §5.2 */ } },
  "_sync_meta": {                  // sync + allocation metadata (§7, §9)
    "strategy": "modified_ts_hash_tombstone_v2",
    "last_merge_ts": 0,
    "next_index": 0,               // allocation watermark, §7
    "tombstones": { "<id>": { "deleted_ts", "entry_hash", "event_hash", "source" } },
    "sources": [], "source_count": 0
  },
  "_system": { "index0": { /* derived state; not part of this spec */ } }
}

• schema_version is currently 4. An implementation MUST refuse to open a version above what it supports (a newer writer may have written fields it would destroy) and MUST migrate older versions forward before writing.
• Entry ids are decimal strings matching ^(0|[1-9][0-9]*)$, within JavaScript's safe-integer range. Both constraints are normative: they are what makes the two reference implementations compute identical allocation floors from one payload (Unicode digits and leading zeros are rejected, not interpreted).

5.2 Entry records

Every entry carries the base fields:

type, kind        # equal strings; `kind` may be absent in pre-v2 data (fall back to `type`)
label             # human name
archived          # boolean (legacy alias: `blacklisted`)
date_added, date_modified   # ISO-8601
modified_ts       # unix seconds; drives sync conflict resolution
notes             # string
tags              # array of strings (freeform; `team:design` style encouraged)
links             # array (entry relationships)
custom_fields     # [{label, value, is_hidden?}]
origin            # optional provenance marker

Kind-specific fields (schema v4):

kind	fields	secret material
password	length (8–128), gen_version (absent ⇒ 1), username?, url?	derived (§6)
totp	deterministic?, period (30), digits (6), index? or secret?	derived or stored
ssh	index	derived
seed	index, word_count ∈ {12,18,24}	derived
pgp	index, key_type ("ed25519"), user_id	derived
nostr	index	derived
key_value	key, value	stored
managed_account	index, word_count, fingerprint (child's, §3.2)	derived
document	content, file_type	stored

Redaction rule: listing/metadata surfaces MUST NOT emit stored secret fields (value, secret, content, hidden custom fields); they are reported as has_* booleans. Plaintext appears only through operations whose stated purpose is producing it.

6. Deterministic derivation

All derived secrets come from BIP-85 over the canonical parent seed (BIP-32/SLIP-10 secp256k1 master; entropy = HMAC-SHA512(key="bip-entropy-from-k", child_private_key)).

What	Path	Entropy → secret
Child mnemonic (seed, managed_account)	m/83696968'/39'/0'/{word_count}'/{id}'	16/24/32 bytes → BIP-39 words
Password (password)	m/83696968'/32'/{id}'	64 bytes → generator v1/v2 (gen_version)
SSH key (ssh)	m/83696968'/32'/{index}'	32 bytes → Ed25519
PGP key (pgp)	m/83696968'/32'/{index}'	32 bytes → Ed25519 (RSA is not reproducible; refuse)
Nostr entry key (nostr)	m/83696968'/39'/0'/32'/{index}'	32 bytes → secp256k1 nsec
Deterministic TOTP	m/83696968'/39'/1414485072'/{totp_index}'	SHA-256(entropy[0:32])[0:20] → base32
Nostr sync identity	m/83696968'/1237'/{account}' (default account 0)	32 bytes → the profile's relay identity

Notes with teeth:

• Password generation v1 is frozen. A fix that would change v1 output goes into a new gen_version, never into v1. 18 frozen vectors enforce this; a failure there is never "update the expected value".
• The Nostr entry-key path is the app-39 path with word_count=32 — a historical quirk, now load-bearing. Do not "correct" it.
• ssh and pgp share app 32 with passwords — a known, shared-with-Python namespace collision. Changing it requires a coordinated versioned change in every implementation (§13); until then it is the standard.

6.1 The two index namespaces

• For password, seed, managed_account, and nostr entries, the derivation index IS the entry id.
• Deterministic TOTP has its own namespace: totp.index is allocated as max over existing totp entries' index + 1, independent of entry ids.

When a human says "account #N", that N is an entry id. Applications presenting managed accounts MUST display the entry id and SHOULD label it exactly "Account #N" so the recovery coordinate users memorize is the one that regenerates the identity.

7. Index allocation — the immutability rule

An id, once allocated, is never reallocated — not after deletion, not after archive, not after sync. Reissuing a deleted #184 would hand a new entry the departed identity's exact derived secrets.

Normative mechanism (implemented in both references, 2026-08-18):

floor(index) = max( _sync_meta.next_index        # persisted watermark, default 0
                  , max(live entry ids) + 1
                  , max(tombstoned ids)  + 1 )   # tombstones still in retention

• Allocation MUST return floor.
• Every insert (including at an explicitly chosen id) and every index save MUST raise the watermark to at least id + 1 / floor. The watermark never decreases.
• Merge (§9) MUST set next_index = max(both sides' watermarks, max(merged entry ids)+1, max(merged tombstone ids)+1) — byte-identical across implementations.
• Deletion of derived-kind entries SHOULD be discouraged in UIs in favor of archived: true; archive preserves the record, and the watermark protects the coordinate even when deletion happens anyway.

The watermark lives in _sync_meta because every implementation already round-trips that block (it carries the tombstones), so pre-watermark builds preserve it without a schema bump. Pre-watermark vaults heal on their next allocation via the tombstone term, and permanently once any save persists the watermark.

8. Interoperability rules for multiple applications

These are what let SeedPass and a narrower client (BitLogin) share one vault without requiring each other.

1. Preservation. An implementation MUST NOT drop or alter fields it does not understand — on entries, on the index top level, and in config — across a read-modify-write cycle. Backfilling the spec's own base fields (§5.2) with neutral defaults is permitted; losing or reinterpreting foreign data is not. Both references hold this today.
2. Unknown kinds. An implementation encountering an entry kind it does not understand MUST either (a) carry it through under rule 1, excluded from typed operations, or (b) refuse to write the vault. Silently dropping it is forbidden. (a) is strongly preferred and is what both references do as of 2026-08-18; (b) is the fail-closed floor. Records with no kind or type at all are garbage, not foreign data, and are rejected.
3. Namespacing. Application-specific metadata goes in namespaced fields on existing records (e.g. bitlogin: { permissions: {...} }) or in new record kinds with a namespaced prefix (e.g. kind: "bitlogin_org"). Core fields (§5.2) MUST NOT be repurposed.
4. No shadow identity. A subset client MUST NOT maintain its own mapping of "its" account numbers to derivation indexes. The entry id is the only account number. (This is the "no translation table" rule.)
5. Subset writing. A client MAY understand only some kinds (BitLogin: managed_account, nostr, its own namespaced kinds). It MUST NOT create entries of kinds it cannot correctly derive or validate.
6. Round-trip conformance. For any vault V and conforming implementations A and B: open(A, save(A, V)) and interleaved save(B, open(B, save(A, V))) MUST preserve all records, ids, and unknown fields. This is mechanically checkable and SHOULD be in CI for every new implementation (the Python↔TypeScript harness is the template).

8.1 Capability declaration

An implementation SHOULD be able to state its profile:

{
  "application": "bitlogin",
  "spec_version": 1,
  "capabilities": ["core", "identity.nostr", "identity.managed_accounts", "tags"],
  "kinds": ["nostr", "managed_account", "bitlogin_org"]
}

Capability groups: core (container, index, allocation, preservation) — mandatory; identity (nostr keys, managed accounts); secrets (passwords, TOTP, SSH, PGP, key-value, documents); advanced (nested roots, portable backup, sync). SeedPass implements all four; an identity client needs only core + identity.

9. Synchronization (Nostr)

Profile identity: BIP-85 app 1237 (§6). Events (NIP-01, BIP-340 signed):

kind	content
30070	manifest
30071	snapshot chunk (encrypted, gzip'd, chunked)
30072	delta (encrypted)

Merge strategy modified_ts_hash_tombstone_v2: higher modified_ts wins; equal timestamps break ties by canonical hash with field-level union; deletions propagate as tombstones which beat older entries and lose to newer ones; tombstone-vs-tombstone prefers newer deleted_ts then higher event hash. Tombstone retention is capped at 2048 (oldest evicted first) — which is why the allocation watermark (§7), not tombstone memory, carries the never-reuse guarantee. Merged _sync_meta fields (last_merge_ts, next_index, sources, tombstones) MUST be computed identically by every implementation: convergence is defined as byte-identical canonical state.

Payload bodies are encrypted with keys derived from the parent seed; relays hold ciphertext only. Applications MUST NOT publish plaintext business or personal data in event content or tags.

10. Portable backup

format_version: 1. Encrypted-by-default export (cipher, checksum = SHA-256 over canonical inner payload), decryptable from the parent seed alone ("seed-only"). Both references import/export it; Python verifies TS-written checksums in CI and vice versa.

11. Managed accounts for identity clients (informative)

The intended BitLogin-style flow, stated in this spec's terms:

• The management root is a SeedPass parent seed (possibly itself a seed/managed_account child of a personal root — delegate a subtree, never the main root).
• Creating "Alice" = creating a managed_account entry. Its entry id is her permanent account number; her child seed derives per §6; her Nostr identity derives from that child seed.
• The client provisions the child key into its online signer at creation time; the root returns to cold storage. Signing availability never requires the root online.
• Recovery: root + entry id regenerates the identity from nothing. This is why §7 is absolute.
• Roles, credentials, policies, org structure: the client's own data, stored under §8.3 namespacing. Not this spec.

11.1 Capsule unlock ("sign in with BitLogin") — informative flow, normative rules

SeedPass's vault key derives from the seed, not the password (§4.1), so any alternative sign-in is necessarily a way the parent seed reaches the client — not an authentication check in front of the login screen. The intended mechanism:

• An explicit owner action (requiring the master password, proving current unlock authority) writes a capsule beside the profile: the parent seed encrypted (NIP-44-style ECIES) to one or more authorized Nostr pubkeys.
• Sign-in = prove control of an authorized key via a fresh challenge, then decrypt the capsule locally. The capsule slots in as one more seed resolver at the existing boundary (env → agent → capsule → password prompt); the vault crypto, derivations, and formats are untouched.
• Revocation = delete or rotate the capsule. The password path always remains. Capsule creation, use, and revocation belong in the audit log.

Two rules are normative for any implementation of this flow:

1. Independence. The unlocking key MUST NOT derive from the vault it unlocks. A key at index #N of this seed cannot be a way into this seed — the circularity makes recovery impossible and the "protection" illusory.
2. Rank. An identity MAY only unlock roots at or below its own trust domain. A managed identity's private key lives in its organization's signer, so capsule decryption would hand the signer the seed: a managed identity MUST NOT be able to unlock the root that provisioned it (or any ancestor). Delegated subtree roots — already inside the signer's trust domain — are the intended scope.

And one rule of construction: a signature is never the unlock. Signatures are cheap, replayable artifacts; the challenge only proves freshness. Possession of the decryption capability is the gate.

12. Known conformance gaps (honest ledger)

Gap	Where	Consequence	Status
Base-field normalization differed on foreign records	—	—	resolved 2026-08-18: both implementations now carry foreign records byte-for-byte untouched (Python's legacy normalizer skips unknown kinds — its renames like blacklisted→archived would have reinterpreted foreign data); enforced by cross-impl Phase L
_system.index0 merge handles only the empty case	both	non-empty index0 refuses to merge (loudly)	by design until atlas milestone
ssh/pgp/password share BIP-85 app 32	both (spec-level)	namespace collision, shared with Python since v1	frozen; change requires coordinated version bump
RSA PGP not derivable	TypeScript	refuses rather than diverging	permanent (RSA generation is not reproducible)

13. Change control

• Any change to derivation output, container format, allocation, or merge semantics is a versioned change: it lands in every reference implementation in lockstep, behind a version field, with cross-impl tests proving old data still reads. The frozen-v1 password rule generalizes: never alter the output of a version that exists in the wild.
• Fixtures under js/packages/test-vectors/fixtures/ are generated by the Python reference (scripts/generate_ts_port_fixtures.py) and are the ground truth a new implementation tests against.
• This document is descriptive of the code; where they disagree, the code + cross-impl suite win, and the document gets fixed.