Sealed vault keys for sgit: a design pack

Status: design, 24 October 2026. Nothing here is built. Compatibility is a requirement, not a phase: with nothing switched on, sgit behaves exactly as 0.24.0 does, and every vault and agent keeps working unchanged (05). Every number marked measured was measured on 24 October 2026 in a Claude agent workspace (details in 04-environment-evidence.md). Everything else is a proposal.

Audience: the agents and engineers who will build this. Read in order.

1. The problem

The pki.sgit.ai handover protects a vault key while it travels: the sending agent seals it to the receiving agent's public key, and a person carries a QR image they cannot read. It stops protecting it the moment it arrives:

   travel                          arrival (sgit 0.24.0 today)
 ┌────────────────────┐   ┌──────────────────────────────────────────────────────┐
 │ QR: sealed to the  │──►│ pki-agent open --save  → vault-key-<id>.txt   CLEAR │
 │ receiving agent    │   │ sgit clone <vault key> → argv, shell history, CLEAR │
 │ (person can't read)│   │                          the agent's transcript     │
 └────────────────────┘   │ .sg_vault/local/vault_key            (0600)  CLEAR │
                          │ .sg_vault/local/key-rnd-imm-*.pem    (PKCS#8) CLEAR │
                          │ .sg_vault/local/token                         CLEAR │
                          └──────────────────────────────────────────────────────┘

For an AI agent the worst leak is not the disk. It is the transcript: every command line the agent writes and everything a command prints lands in the model's context and in conversation logs.

2. Goals

1. Nothing changes unless it is asked for. The default is today's sgit: one process, the vault key in .sg_vault/local/vault_key, every command, flag, output and workflow as in 0.24.0. The sealed path is switched on per clone, and sealed and plain clones of the same vault work side by side (05).
2. On a sealed clone, the clear vault key is never written to disk, never on a command line, never printed. It never enters the transcript.
3. One place holds the private key. A small KMS process (local, frozen between calls) or a remote one (serverless, Kubernetes, HSM-backed, or provided by the agent platform itself). Same protocol for all of them.
4. Each component does one job and can do nothing else. Four components (CLI, fs, net, kms), each under its own Process Behaviour Policy, enforced by the kernel and by mutual TLS.
5. Ephemeral. Nothing exists before the session starts or after it ends: identities, certificates, users and policies are all made for the session and die with it.
6. Policies come from outside the agent. The person supplies (or signs) the hash of the policy; the agent cannot widen it.
7. No server changes. What goes to the vault server is exactly what goes today.

3. Threat model

Trusted: the kernel, the hardware, the platform that runs the VM. Root and kernel compromise are out of scope: anything with root on the machine can read any process's memory, or make the process read it for them. The design shrinks where a key lives; it does not hide it from root.

Who is root matters. In the measured environment the agent itself is root. Every defence in the table that is enforced locally (the launcher, the policies, the KMS's binding) is therefore a Boundary against a prompt-injected sgit process but only a Setting against a prompt-injected agent, which could undo it. Those rows bind the agent only when the launcher and the KMS run outside it: a remote KMS (01 §5 D) or the platform (01 §5 E).

In scope:

Not claimed: Python cannot guarantee erasure of secrets (scrubbing bytes in place works in CPython, measured, but relies on its internals); expiry on a sealed key is policy enforced by the KMS, not cryptography; a session identity dies with its session, so a restarted session needs a new handover (by design).

4. Glossary

5. Decisions

6. End state: the platform provides it

The local sgit-kms user and a Lambda are stand-ins. The right owner of the KMS and of policy enforcement is the agent execution environment (Claude, ChatGPT, etc.):

• it already knows which session is calling, which solves caller authentication for an ephemeral container;
• it already sits outside the container (this environment's egress proxy is the precedent);
• it can bind key lifetime to session lifetime and keep decrypted results out of transcripts and logs.

The protocol in this pack is designed so that sgit doesn't change when the KMS moves from a local uid to a Lambda to a platform service. This is a proposal for what platforms should offer; no such service is known to exist today.

7. Sources

• A vault key that never lands: the original analysis (sgit 0.24.0 at 182cfc1), including its 24 Oct update: plain keys refused on all 14 commands that take one; --to is the record fingerprint; seal to a lasting recovery recipient too; trust an explicit fingerprint first.
• pki.sgit.ai handover: QR formats, refusal rules, root fingerprint.
• Agent Behaviour Policy: grant, mandate, delta, barrier.
• Sealed vault keys in sgit: requirements and the side-by-side review, 24 October 2026.
• This design session, 24 Oct 2026 (Dinis Cruz with Claude).

8. Review before publishing

The pack was written in a design session of Dinis Cruz's with a Claude agent on 24 October 2026, and reviewed the same day by cli.sgit.ai's build agent before it was published here. The review changed:

1. Compatibility made a requirement. At Dinis's instruction: the default is 0.24.0's behaviour, the new path is opt-in per clone, and the rollout is staged in production. New: goal 0, the first decision, and 05. The refactor path (01 §7) and the refusals (01 §2.1, 03 §8) now say which behaviour is the default.
2. The handover's expiry. A received m1 expires in a week (handover.md). Kept at rest as it is, a clone would stop opening after seven days. The KMS now checks expiry at intake and keeps a re-sealed copy (02 §1.2, §2, §3.3).
3. Trust without a network. The KMS has no network, yet it was asked to check the sender's chain to the root. It now checks against fingerprints pinned in the session policy first (02 §3.3).
4. The threat model says who is root. Local defences are Boundaries against sgit and Settings against a root agent. memfd_secret stops /proc/<pid>/mem and the kernel's direct map, not root acting through the process (§3, 02 §8).
5. Smaller points.

• rekey, move and show-key --reveal need the vault key, and have no KMS operation yet (§5).
• sgit-fs's clear-key detection is best-effort, because a vault key's passphrase can be chosen by its owner (01 §2.2).
• Scrubbing bytes relies on CPython internals (§3).

1. Publishing.

• The platform's egress proxy port is generalised, and 04 says that root inside the microVM is the platform's design.
• Em dashes are replaced, house style.
• Links point at this site.
• Nothing else in the text was changed.

This page as markdown · its source, admin/content/dev/sealed-vault-keys/index.md