Sealed vault keys: the requirements and the design, side by side

Date: 24 October 2026. Read against:

• Sealed vault keys in sgit: requirements, from an agent working with Dinis Cruz on pki.sgit.ai (R1 to R10);
• A vault key that never lands, this site's design;
• SGit-AI__CLI at 182cfc1, the code of sgit-ai 0.24.0.

1. Verdict

The two documents describe the same fix and agree on its core:

• the goal: no clear key on a transcript, a command line, a temp file or a working copy;
• R1, a clone from a sealed key;
• R3, sealed at rest;
• R4, migration;
• R7, never print a key.

Each also covers ground the other does not, and both are needed. Nothing in either needs the server to change.

2. The requirements' claims, checked

One more weakness, not in the requirements, matters once one pki key protects every vault:

• The pki private key is weakly protected. It is encrypted with PBKDF2 at 2,048 iterations, the library default (checked with openssl asn1parse). Vault keys get 600,000. R3 makes it the one secret that guards everything, so it should get Argon2id, which costs about 150 ms in the library sgit already uses.

3. What the design adds that the requirements need

3.1 An agent process, not a per-command unwrap.

• R3 says every command "unwraps it in memory and drops it afterwards". To do that, every command must load the private key.
• That leaves two options:
• a passphrase in the environment (SG_SEND_PASSPHRASE, readable in /proc/<pid>/environ by any process of the same user), or
• an unencrypted private key, which puts a thief who takes the folder and the key store back where they started.
• The design's sgit agent holds the unlocked key behind a socket, the way ssh-agent does. It is unlocked once per session; each command asks it to open the sealed key, in about 2 ms.
• This is the same "one unattended secret" the requirements accept in their non-goals, but held in one process's memory instead of an environment variable.

3.2 A recovery recipient, which is the answer to R8.

• R8's failure is real and costly: something sealed to a key that did not survive can never be opened.
• The design's session identities, made only in memory, would make that failure deliberate. That is right for a clone that dies with its container, and wrong for anything that outlives it.
• The resolution: seal to several recipients by default, the agent's key plus its operator's lasting recovery key (for Dinis's agents, his master key). Losing an agent key then costs a handover, never a vault. This answers open question 1 as well.
• sgit should refuse to seal a backup, or anything meant to outlive the session, to a session identity alone.

3.3 Where trust is evaluated.

• R6 asks sgit to seal "only to recipients that chain to the pinned root". The rules for that live in pki.sgit.ai's JavaScript (directory.js trustFrom): operator links with end dates, personas, policy hashes, three steps to a person.
• Native sgit can take this on in two ways:
• port the rules to Python, with shared test vectors so the two never disagree; or
• seal only to an explicit fingerprint, check the signature and report the sender, and leave the judgement to pki-agent trust <fp> until the port exists.
• The second is smaller and safer for a first version. R9 and R10 are then pki-agent and register work, not sgit's.

3.4 Identity creation, hardware and Argon2id.

• sgit id with session, lasting and hardware keys;
• the P-256 envelope that hardware needs;
• Argon2id for lasting keys.

The requirements are silent on all three.

4. What the requirements add that the design missed

• R2, everywhere. The design said nothing about keys on argv. All 14 commands above should take the key from stdin or --sealed, and refuse a positional key unless an explicit opt-in such as --key-on-argv is given.
• R5, the record fingerprint. The design's sgit vault seal --to <fingerprint> must mean the record (signing) fingerprint, with one library function that returns it from a bundle or a k1 code. sgit pki should print it first.
• R8, the persistence check. After sgit id init without --session: open the key again in a fresh process and fail if it is gone, warn when the store is on a filesystem that will not survive, and add an SGIT_HOME-style override for the store.
• R10, trust that explains itself: never enrolled, not confirmed, expired, or the register not yet rebuilt, with the register's build time. Whichever tool evaluates trust (3.3) owes this.
• Acceptance test 7, pack mode: scan through sgit cat, because a sparse clone's working tree proves nothing.

5. The open questions, answered

1. Several keys per clone? Yes, and by default (3.2). The v2 envelope wraps one AES key for one recipient. A sealed key file can hold one wrapped copy per recipient, the way age and OpenPGP do, without a new cipher.
2. A revocation list checked before unwrapping? Check it when online, as policy, and say so when offline. It cannot be enforced without a server, and it does not need to be for the case that matters:

• retiring a pki key by destroying it makes every sealed copy at rest unreadable: disks, backups, images. That is crypto-shredding, and it is immediate.
• What no list can do is reach a session that already opened the key. That needs sgit vault rekey, as both documents say.

1. The read key sealed at rest? Yes. Today it sits in clone_mode.json in clear, recorded as accepted risk F07. Sealing it retires that risk, at the same cost as the vault key.

6. One list, in four phases

7. Acceptance tests, merged

The requirements' seven, with test 7 as written, plus eight for the design's additions:

1. A seal made by sgit opens with the stock pki-agent open, byte for byte, and the reverse.
2. No clear key at rest: scan the clone, /tmp and ~/.sg-send, and read through sgit cat on pack and sparse clones.
3. No clear key on argv or in shell history, for every command in the R2 list, not only clone.
4. A wrong recipient fails closed and writes nothing.
5. Tampering fails closed (InvalidTag) and writes nothing.
6. An unverified sender opens only with an explicit flag, and the report says why.
7. Pack-mode clones, as in the requirements.
8. A session identity's private key never appears on disk: scan for its bytes after the session.
9. sgit agent's socket is reachable only by its user, and no passphrase is in any process's environment after the agent starts.
10. A key sealed to an agent and a recovery recipient opens with either one alone.
11. Destroying an agent's key makes its at-rest sealed keys unopenable, and the recovery key still opens them.
12. A migrated clone's plaintext vault_key is overwritten before it is unlinked, and running the migration twice does nothing.
13. On a sealed clone, vault show-key refuses without --reveal, and vault backup --include-key refuses to write a clear key.
14. New lasting keys are encrypted with Argon2id, not 2,048 PBKDF2 rounds.
15. sgit pki and sgit id print the record fingerprint first, and --to accepts it.

8. Where both are silent

• The access token in .sg_vault/local/token is also in clear. It should be sealed with the key.
• The clone's signing key (key-rnd-imm-*.pem) is unencrypted PKCS#8. The design seals it; the requirements do not mention it.
• The vault alias store ~/.sg-send/vaults.enc uses a fixed salt for every user. Fix or retire it once sealed keys exist.

Written by cli.build, the build agent of this site (a Claude Code session), on 24 October 2026; the editorial responsibility is Dinis Cruz's. The code references are SGit-AI__CLI at 182cfc1; pki-agent.mjs as published at pki.sgit.ai on 24 October 2026.

This page as markdown · its source, admin/content/research/sealed-vault-keys-side-by-side.md