Sealed cryptography and threat model
This page is for security reviewers and for developers who build their own client for sealed workspaces. It covers what sealing protects, what the instruction.md server still learns, and exactly how content and keys are encrypted, signed and unlocked, as @instruction.md/seal does it. How to use sealed workspaces is on Sealed instructions for developers.
Threat model
What is protected
Against the instruction.md server, its storage, its backups and anyone who reads them:
- the text of every sealed draft and version, and every item of a sealed agent conversation (an agent's lines, its questions and permission requests, people's answers and messages);
- each object's content key, the workspace keys, and every private key.
The server never holds a key that opens these. It stores public keys, keys wrapped to their holders, and unlock records that open only with their owner's secret.
What the server still learns
- From each envelope: the organization, workspace and instruction it belongs to, its object id (
v3,draft), its kind, the workspace key's epoch, the envelope before it in the chain, its padded size, and its author's fingerprint. - From the keys: each identity's public keys and kind, which keys hold each workspace's key at each epoch, and each unlock record's method, label, salt, cost and credential id.
- From using the product: instructions' names and titles (a title isn't encrypted), who reads and changes what and when, how many versions there are, which agents follow which instruction, and the people of each workspace.
What it doesn't protect against
- The model. The AI model that follows an instruction reads its text: that is its job. Choose your model provider with that in mind.
- Key holders. Anyone you gave the key can keep what they read. Rotating the key protects only what comes after.
- Rollback and withholding. The server checks that each new version names the latest one as its parent, but a reader can't tell, from one envelope alone, that the server served an older version or held back the newest. A reader that needs that tracks the chain and the latest version it has seen.
- The editor's code. The editor in your browser is served by instruction.md. A web page is only as trustworthy as the code it was served.
- The company proxy's trust in instruction.md. The proxy opens text for whoever instruction.md says the caller is: it takes the account and its verified email from instruction.md's answers. So a key service protects stored and delivered text, but it doesn't stop a server that impersonates one of your people to your proxy. Keep the proxy reachable only from your own network if that matters to you.
- Unlocked keys on a device. Code that holds an unlocked identity or a workspace key can read everything that key opens. Protect the process and the machine that run it.
- Lost keys. If a person loses every way to unlock and their recovery key, what only they could open is gone. Nobody at instruction.md can get it back.
The imd-seal/1 envelope
Every sealed object is an envelope of the suite imd-seal/1, stored as canonical JSON (keys sorted, no spaces). Its own digest, sha256: over that JSON, is the version's digest and what the next version names as its parent.
{
"seal": "imd-seal/1",
"kind": "version",
"orgId": "org_01JC4A7Q8Z2N5W9X3B6D1F0H2K",
"workspaceId": "ws_01JC4A9R3T5V7X9Z1B3D5F7H9K",
"instructionId": "ins_01JC4AB2C4E6G8J0L2N4Q6S8U0",
"objectId": "v2",
"epoch": 1,
"parent": "sha256:<the envelope digest of v1>",
"size": 1024,
"author": "<the author's fingerprint>",
"dek": "<the object's key, AES-256-GCM under the workspace key>",
"commit": "<HMAC-SHA256 key commitment>",
"body": "<the padded text, AES-256-GCM>",
"sig": "<Ed25519 over the header, commit and body>"
} | Field | What it is |
|---|---|
seal |
imd-seal/1 |
kind |
version, draft, snapshot, update, proposal, secret or message |
orgId, workspaceId, instructionId, objectId |
the ids it is bound to (v<N> for a version, draft for the draft, <deploymentId>/… for a conversation item) |
epoch |
the workspace key's epoch it was sealed with |
parent |
the envelope digest of the one before it, or null |
size |
the padded length: all the server learns of the size |
author |
the author's fingerprint |
dek |
the object's content key, encrypted with the workspace key |
commit |
the key commitment |
body |
the padded, encrypted text |
sig |
the author's outer signature |
Sealing
- The text's digest is
sha256:of its UTF-8 bytes. The author signs, with Ed25519, the canonical JSON of the kind, instruction, object, epoch, parent and that digest: the inner signature. - The text, its digest and the inner signature are put in one JSON object, then padded with zero bytes to the bucket size, less the nonce and tag.
- A fresh 256-bit content key is drawn for this object alone. HKDF-SHA256 splits it into an encryption key (info
imd-seal/1 content enc) and a commitment key (imd-seal/1 content commit). commitis HMAC-SHA256 with the commitment key over the header.bodyis AES-256-GCM with the encryption key, a random 12-byte nonce, and the header as associated data.- The content key itself is encrypted with the workspace key (AES-256-GCM, a random nonce, the header as associated data):
dek. - The author signs, with Ed25519, SHA-256 over the header,
commitandbody: the outer signature,sig.
The header bound as associated data is the canonical JSON of seal, kind, the four ids, epoch, parent, size and author. Moving an envelope to another instruction, object, epoch or place in the chain breaks the signature and the decryption.
Padding buckets. 1 KiB steps up to 64 KiB, then powers of two. A short instruction is 1,024 bytes, whatever its length. AES-GCM here uses 32-byte keys, 12-byte nonces and 16-byte tags.
Opening
A reader checks, in this order, and refuses at the first failure: the envelope's shape; that its key is for this workspace and epoch; that the author is a key the workspace knows (every key that ever held its key, so a version by someone who has left still opens); the outer signature; the content key; the key commitment, before the body is decrypted; the body; the text against its digest; and the inner signature.
What the server checks
Before it stores a sealed draft or version, the server checks what it can without reading anything:
- the outer signature, against the author's registered public key;
- the author is the caller's own key, or the organization's key service writing for them through its proxy, and that key holds the workspace's key at the current epoch;
- the ids name this instruction and the right object (
v<next number>for a release,draftfor the draft); - the epoch is the workspace's current one;
- a version's parent is the latest version's digest, so versions can't be reordered or dropped from the chain as stored;
- the envelope is at most about 2 MB.
The caller's permission to write is checked as for any instruction.
Identities and fingerprints
Each person, agent and key service has an identity: two key pairs from two 32-byte seeds.
| Part | Algorithm | Public key |
|---|---|---|
| receiving workspace keys | X-Wing (X25519 with ML-KEM-768), through HPKE | 1,216 bytes |
| signing what it writes | Ed25519 | 32 bytes |
The private part is the 64 bytes of the two seeds. That is what an agent's key file holds and what a person's unlock methods wrap. The kind is person, agent, key-service or recovery.
The fingerprint is the first 20 bytes of SHA-256 over the canonical JSON of the suite, kind and both public keys, as ten groups of four hex digits (5021 BB26 F3EB …). People compare it before they give someone the key. The server computes it again from the keys when a key is registered, and refuses one that doesn't match.
Workspace keys and epochs
A sealed workspace has one 256-bit key per epoch. Sealing the workspace makes epoch 1, and records pqRequired: true in the workspace's seal policy.
The key is wrapped to each holder with HPKE (RFC 9180) in single-shot mode: X-Wing as the KEM, HKDF-SHA256, AES-256-GCM. The info is imd-seal/1 workspace key, and the associated data is the canonical JSON of the suite, the workspace, the epoch and the recipient's fingerprint, so a wrap can't be moved to another workspace, epoch or key. X-Wing holds against a quantum computer, and against a flaw in either X25519 or ML-KEM-768 alone. X-Wing is an IETF Internet-Draft, not yet an RFC.
- Giving the key (
seal_wraps_add) wraps the current epoch's key to keys that don't hold it yet. Only someone who holds it can give it, and only to the key of someone with a role in the workspace (or an organization owner or admin), or to the organization's own key service. - Rotating (
seal_workspaces_rotate) makes epoch N+1 and wraps it to the keys that keep reading. An admin of the workspace who holds the current key does it. New objects use the new key. Objects sealed before keep the key they were sealed with. - A key given the key at epoch N can't open what was sealed at earlier epochs. A key left out of a rotation keeps opening what was sealed before it.
Author signatures
Every envelope is signed twice with the author's Ed25519 key:
- the outer signature, over the envelope as stored, which the server checks without reading anything;
- the inner signature, over the text's digest and the envelope's place (kind, instruction, object, epoch, parent), which only a reader who opens it can check.
Ed25519 is a classical signature, not a post-quantum one. A sealed version carries no platform signature: the server can't sign what it can't read. A follower that requires the platform's signature holds a sealed version as unsigned. See Signing and verification.
Unlocking a person's key
A person's identity is made in their browser (or by instruction-mcp key init) and is kept only as unlock records: the 64 private bytes, encrypted with AES-256-GCM under a key that one method gives. The associated data binds the suite, the method, the record's id, the fingerprint and the kind. Any one record opens the key.
| Method | Where it works | The key that wraps the private bytes |
|---|---|---|
| Passkey, security key | the browser | the authenticator's WebAuthn PRF output for a 32-byte salt, through HKDF-SHA256 (info imd-seal/1 unlock prf), never the PRF output itself |
| Passphrase | anywhere | Argon2id, 64 MiB, 3 passes, 1 lane, 16-byte salt, over the NFKC passphrase of at least 12 characters |
| Recovery key | anywhere | 256 random bits through HKDF-SHA256 (info imd-seal/1 unlock recovery), shown once as 52 Crockford base32 characters in groups of four |
| This device | one browser | a non-extractable AES-GCM key the browser keeps |
- A passkey for unlocking is its own credential, made for unlocking only, with user verification required. Some browsers, password managers and older keys don't support PRF; then a passphrase works instead.
- A passphrase record that asks for a cost out of range is refused, so a stored record can't freeze a page or weaken the cost.
- The server refuses a person's key without a recovery record, at most 20 unlock records per key, removing the last way to unlock, and removing the only recovery key.
- A connected AI app can't set up a key or change how it unlocks.
- In the editor, an unlocked key is kept only in the tab's memory, and locks after 30 minutes without use, or when the tab closes.
The @instruction.md/seal package
@instruction.md/seal (version 0.2.1, MIT) is the cryptography the editor, the CLI, @instruction.md/mcp and agents share. It makes no network requests and keeps no state. It runs in browsers with WebCrypto and on Node.js 20.19 or later. Its dependencies are @hpke/core, @hpke/hybridkem-x-wing, @noble/curves and @noble/hashes, pinned to exact versions; AES-GCM, HKDF, HMAC and SHA-256 come from the platform's WebCrypto.
npm install @instruction.md/seal This example seals two chained versions and opens one, with the ids a version is bound to:
// seal-and-open.mjs — node seal-and-open.mjs
import {
newIdentity, newWorkspaceKey, wrapTo, unwrap, sealText, openText, verifyEnvelope, envelopeDigest, SealError,
} from "@instruction.md/seal";
// The ids a version is bound to: its organization, workspace and instruction, and its object (v<N> for a version)
const ids = { orgId: "org_01JC4A7Q8Z2N5W9X3B6D1F0H2K", workspaceId: "ws_01JC4A9R3T5V7X9Z1B3D5F7H9K", instructionId: "ins_01JC4AB2C4E6G8J0L2N4Q6S8U0" };
// 1. Two people's keys, and the workspace key at epoch 1 wrapped to both
const ann = await newIdentity("person");
const bob = await newIdentity("person");
const wk = await newWorkspaceKey(ids.workspaceId, 1);
const wraps = await wrapTo(wk, [ann.public, bob.public]);
// 2. Ann seals v1, then v2 chained to it
const v1 = await sealText({ text: "# Refunds\n\nMUST: refund within 14 days.\n", kind: "version", ids: { ...ids, objectId: "v1" }, key: wk, author: ann });
const v2 = await sealText({
text: "# Refunds\n\nMUST: refund within 14 days.\nNEVER: refund a gift card.\n", kind: "version",
ids: { ...ids, objectId: "v2" }, key: wk, author: ann, parent: await envelopeDigest(v1),
});
console.log("v2:", v2.size, "bytes, epoch", v2.epoch, "parent", v2.parent === (await envelopeDigest(v1)));
// 3. What the server checks before it stores v2: Ann's outer signature, without reading anything
console.log("signed by Ann:", await verifyEnvelope(v2, ann.public));
// 4. Bob unwraps his copy of the workspace key and opens v2, checking its author
const bobsKey = await unwrap(wraps.find((w) => w.recipient === bob.public.fingerprint), bob);
const authors = new Map([[ann.public.fingerprint, ann.public]]);
const opened = await openText(v2, bobsKey, (fp) => authors.get(fp));
console.log(opened.text.trim().split("\n").pop(), "by", opened.author === ann.public.fingerprint ? "Ann" : "someone else");
// 5. A changed envelope is refused: here, moved to another instruction
try {
await openText({ ...v2, instructionId: "ins_01JC4AD5F7H9K1M3P5R7T9V1X3" }, bobsKey, (fp) => authors.get(fp));
} catch (e) {
console.log(e instanceof SealError ? `${e.code}: ${e.message}` : e);
} v2: 1024 bytes, epoch 1 parent true
signed by Ann: true
NEVER: refund a gift card. by Ann
integrity: its author's signature doesn't hold Everything it exports, read from the package's own index:
| Part | Functions and values | Types |
|---|---|---|
| Errors and encodings: base64url, canonical JSON, UTF-8 | SealError, b64u, fromB64u, canonical, utf8, fromUtf8 | |
| Identities: key pairs, fingerprints, Ed25519 signatures, HPKE to a recipient | SUITE, newIdentity, identityFrom, identityFromPrivate, checkPublic, fingerprintOf, sign, verify, sealTo, openFrom | Identity, PublicIdentity, RecipientKind |
| Unlock methods: passkey or security key (PRF), passphrase, recovery key, this device | ARGON2, lockWithPrf, unlockWithPrf, newPrfSalt, lockWithPassphrase, unlockWithPassphrase, lockWithRecovery, unlockWithRecovery, recoveryText, recoveryBytes, newDeviceKey, lockWithDevice, unlockWithDevice | UnlockMethod, UnlockRecord |
| Workspace keys and their wraps | newWorkspaceKey, wrapTo, unwrap | WorkspaceKey, Wrap |
| Envelopes: sealing, opening and checking text | sealText, openText, verifyEnvelope, envelopeDigest, envelopeOf, textDigest, bucket, MEDIA_TYPE | Envelope, Ids, ObjectKind, Opened |
| WebAuthn PRF ceremonies (browser only) | registerPrf, evaluatePrf, prfAvailable, credentialIdsOf, localChallenge | PrfResult |
A failure throws SealError, whose code says why: malformed (not an imd-seal/1 object), integrity (changed, or the wrong key), policy (the wrong workspace, epoch, recipient or author), locked (no key), or unsupported.
Review status
The design and its code haven't had an independent cryptographic review yet. That review comes before sealed workspaces leave beta. To report a weakness, use the contact form and choose Security, or see Security disclosure.