Skip to content

Add Sigma seed backup envelopes [sigma-auth#130] - #1

Merged
rohenaz merged 4 commits into
masterfrom
codex/seed-backup-contract
Sep 5, 2026
Merged

Add Sigma seed backup envelopes [sigma-auth#130]#1
rohenaz merged 4 commits into
masterfrom
codex/seed-backup-contract

Conversation

@rohenaz

@rohenaz rohenaz commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

Problem

Sigma needs portable mnemonic recovery without changing existing Type42, HD, account, WIF, or vault backups. Related: b-open-io/sigma-auth#130.

Change

Add SigmaSeedBackup as a separate encrypted payload. The normal plaintext shape is:

{
  format: 'sigma-seed',
  version: 1,
  mnemonic: '…',
  profiles: [{ index: 0, bapId: '…' }],
  nextProfileIndex: 1,
  createdAt: 0
}

Version 1 fixes BRC-157 peer derivation at m/0'/i' and an empty BIP39 passphrase. Word count supplies entropy length; no separate scheme, passphrase-policy, or entropy-length fields. The file's encryption password is independent.

Optional fields: envelope label, per-profile JSON metadata, and inventoryComplete: false for phrase-only recovery. Absence means the inventory and allocation cursor are complete as of this backup; false means consumers must not allocate/delete profiles or replace a complete cloud inventory. The cursor never rewinds when a profile is removed. This does not certify that an old backup is current.

Structural validation rejects ambiguous/unknown fields and malformed inventories. Sigma verifies mnemonic checksum and derived BAP IDs; the codec and CLI do not create seeds or discover profiles. Existing readers reject the new format. Encryption snapshots the validated payload before asynchronous key derivation.

CLI review adds version synchronization, matching custom iteration options for encryption/decryption/upgrade, private plaintext output permissions, and malformed-JSON error redaction. Upgrade preserves the payload and raises encryption strength; it does not migrate an identity or format.

Validation

bun run check: 154 tests / 673 assertions, lint and ESM/CJS/types/CLI builds pass. Seven built-CLI tests cover full/partial seed roundtrips and upgrades, all eight legacy families, default/custom KDF, metadata preservation, malformed payloads, wrong passwords, output permissions, and error redaction. Native Touch ID/keychain interactions are not certified; existing unit tests pass.

Release order

Version 0.0.14 is prepared, not published. First review and approve this format; then merge/release this package; then pin the published version and rerun clean-install checks in Sigma PR329. Production seed creation remains disabled. No merge or release is authorized by this draft.

@rohenaz
rohenaz merged commit 8ab6292 into master Sep 5, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant