@noy-db/hub 0.8.0-pre.0 → 0.8.0

package/dist/capsule/enclave-aes/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/capsule/enclave-aes/broker/proof.ts","../../../src/capsule/enclave-aes/capabilities.ts","../../../src/capsule/enclave-aes/index.ts"],"sourcesContent":["/**\n * Credential-broker proof crypto (#479, credential-broker spec §3).\n *\n * The `_broker` seed (32 random bytes, decrypted from `_broker/<brokerId>` by\n * the party layer) is never transmitted. Instead, a **proof key** is\n * HKDF-derived from it, domain-separated per `(vaultId, brokerId)`, and the\n * derived bits are registered with the broker host once at enrol. Steady\n * state, the client re-derives the same key from the seed and signs a\n * **canonical** string binding the request's identity/context, so the broker\n * can verify a fresh HMAC on every mint without ever holding the seed itself.\n *\n * ## Derivation (spec §3, follow verbatim)\n *\n * ```\n * hkdf      = importKey('raw', seed, 'HKDF', false, ['deriveBits'])\n * proofBits = deriveBits({ name:'HKDF', hash:'SHA-256',\n *                          salt: utf8(BROKER_PROOF_DOMAIN),\n *                          info: utf8(JSON.stringify([BROKER_PROOF_DOMAIN, vaultId, brokerId])) },\n *                        hkdf, 256)\n * proofKey  = importKey('raw', proofBits, { name:'HMAC', hash:'SHA-256' }, false, ['sign'])\n * proof     = base64(sign('HMAC', proofKey, utf8(canonical)))\n * ```\n *\n * `BROKER_PROOF_DOMAIN` is both the HKDF salt and the first `info` array\n * element (the injective-JSON-array convention `deriveClassifyIndexKey`\n * established — see `classify/bidx.ts`). `BROKER_PROOF_VERSION` is the\n * separate MAC version tag, the first element of the `canonical` array.\n *\n * ## Canonical (spec §2 step 3)\n *\n * `JSON.stringify([BROKER_PROOF_VERSION, vaultId, endpointOrigin, brokerId,\n * profile ?? '', instancePid ?? '', challenge, expiresAt])` — every binding\n * field folded into ONE MAC input:\n *  - `vaultId` (V1), `challenge` (V3), `expiresAt` (V4) — verbatim strings,\n *    never reparsed/reformatted (F8): a byte-identical ISO string is\n *    required, so e.g. `Z` vs `+00:00` for the same instant fails.\n *  - `profile ?? ''` (F1) — a proof captured at one profile cannot be\n *    replayed at another.\n *  - `endpointOrigin` (F4) — a proof cannot be relayed to a different broker\n *    endpoint reusing the same `brokerId`.\n *  - `instancePid ?? ''` (F7) — an EMPTY STRING `instancePid` is forbidden in\n *    both {@link computeBrokerProof} and {@link verifyBrokerProof}: absent\n *    (the field omitted) and `''` must stay distinguishable, or `?? ''`\n *    would alias \"no instance\" onto a real registered instance.\n *\n * ## Verify order (spec §3, non-negotiable, F2/F6)\n *\n * {@link verifyBrokerProof} MUST, in this exact order: (1) burn the challenge\n * via `consumeChallenge` FIRST and short-circuit `false` before any MAC work\n * (F2 — burn-on-presentation, not burn-on-success); (2) recompute the\n * canonical and compare with `crypto.subtle.verify('HMAC', …)` — portable,\n * constant-time, never a manual byte compare or Node `timingSafeEqual` (F6);\n * (3) assert `now < expiresAt` — the client clock is never trusted, so this\n * check only matters once the MAC (which covers `expiresAt`) has verified.\n *\n * ## Zeroing (F5)\n *\n * `seed` and the transient HKDF output are raw, durable secret material —\n * the `recovery.ts:276-307` `try{}finally{secret.fill(0)}` discipline, not\n * the ephemeral-CEK happy-path zeroing elsewhere. {@link computeBrokerProof}\n * zeroes the `seed` argument in a `finally` on every path including a throw;\n * {@link deriveBrokerProofKey} zeroes its own transient HKDF-output bytes the\n * same way. {@link deriveBrokerProofBits} does not zero `seed` — it exists\n * so the party layer can register the raw bits at one-time enrol (the value\n * that must survive the call to be base64-encoded and POSTed).\n *\n * @module\n */\nimport type { EnclaveKey } from '../crypto.js'\nimport { base64ToBuffer, bufferToBase64 } from '../../plumbing/digest.js'\nimport { ValidationError } from '../../../kernel/errors.js'\n\nconst subtle = globalThis.crypto.subtle\n\n/** HKDF salt domain for the broker proof key — also the first `info` array element. */\nexport const BROKER_PROOF_DOMAIN = 'noydb-broker-proof'\n\n/** MAC version tag — the first element of the `canonical` array signed/verified. */\nexport const BROKER_PROOF_VERSION = 'noydb-broker-proof-v1'\n\n/** Default challenge TTL (spec §2 step 2: \"TTL ≤ 60 s\"). */\nconst DEFAULT_CHALLENGE_TTL_MS = 60_000\n\n/** The canonical-binding fields a client supplies alongside `vaultId`/`brokerId` (spec §2 step 3). */\nexport interface BrokerProofCanonicalParts {\n  readonly endpointOrigin: string\n  readonly profile?: string | undefined\n  readonly instancePid?: string | undefined\n  readonly challenge: string\n  readonly expiresAt: string\n}\n\n/** A freshly-minted, server-random single-use challenge (spec §2 step 2). */\nexport interface IssuedChallenge {\n  readonly challenge: string\n  readonly expiresAt: string\n}\n\n/** Arguments the broker host passes to verify a submitted proof (spec §3). */\nexport interface VerifyBrokerProofArgs {\n  /**\n   * Atomically test-and-delete the challenge, returning whether it was still\n   * fresh (unconsumed and unexpired-from-the-store's-perspective). MUST burn\n   * on presentation, not on successful verification (F2).\n   */\n  readonly consumeChallenge: (challenge: string) => Promise<boolean>\n  /** The registered proof key's raw bytes, already KMS-unwrapped by the host (§7). */\n  readonly registeredProofKey: Uint8Array\n  readonly vaultId: string\n  readonly endpointOrigin: string\n  readonly brokerId: string\n  readonly profile?: string | undefined\n  readonly instancePid?: string | undefined\n  readonly challenge: string\n  readonly expiresAt: string\n  /** base64(HMAC-SHA-256(proofKey, canonical)), as submitted by the client. */\n  readonly proof: string\n}\n\n/** Build the canonical MAC input verbatim — never reparses/reformats a field (F8). */\nfunction buildCanonical(vaultId: string, brokerId: string, parts: BrokerProofCanonicalParts): string {\n  return JSON.stringify([\n    BROKER_PROOF_VERSION,\n    vaultId,\n    parts.endpointOrigin,\n    brokerId,\n    parts.profile ?? '',\n    parts.instancePid ?? '',\n    parts.challenge,\n    parts.expiresAt,\n  ])\n}\n\n/**\n * The HKDF step: derive the 256-bit proof bits from the `_broker` seed,\n * domain-separated per `(vaultId, brokerId)`. Returns the raw bits — the\n * value registered with the broker host once at enrol (spec §2 step 2/3).\n * Does not mutate or zero `seed`; the caller owns the seed's lifecycle.\n */\nexport async function deriveBrokerProofBits(\n  seed: Uint8Array,\n  vaultId: string,\n  brokerId: string,\n): Promise<Uint8Array> {\n  const hkdfKey = await subtle.importKey('raw', seed as BufferSource, 'HKDF', false, ['deriveBits'])\n  const salt = new TextEncoder().encode(BROKER_PROOF_DOMAIN)\n  const info = new TextEncoder().encode(JSON.stringify([BROKER_PROOF_DOMAIN, vaultId, brokerId]))\n  const bits = await subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt, info }, hkdfKey, 256)\n  return new Uint8Array(bits)\n}\n\n/**\n * Derive the steady-state, non-extractable `['sign']` HMAC proof key from\n * the `_broker` seed. Zeroes the transient HKDF-output bytes in a `finally`\n * once the key has been imported (F5) — the raw bits never leave this\n * function in usable form after import.\n */\nexport async function deriveBrokerProofKey(\n  seed: Uint8Array,\n  vaultId: string,\n  brokerId: string,\n): Promise<EnclaveKey> {\n  const proofBits = await deriveBrokerProofBits(seed, vaultId, brokerId)\n  try {\n    return await subtle.importKey('raw', proofBits as BufferSource, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])\n  } finally {\n    proofBits.fill(0)\n  }\n}\n\n/**\n * Compose derive + sign for the client: re-derive the proof key from the\n * seed and sign the canonical over `canonicalParts` (spec §2 step 3).\n *\n * Rejects an empty-string `instancePid` (F7 — absent is fine, `''` is not).\n * Zeroes the `seed` argument in a `finally` on EVERY path including a throw\n * (F5, durable-secret discipline) — the transient HKDF bits are zeroed one\n * layer down, inside {@link deriveBrokerProofKey}.\n */\nexport async function computeBrokerProof(\n  seed: Uint8Array,\n  vaultId: string,\n  brokerId: string,\n  canonicalParts: BrokerProofCanonicalParts,\n): Promise<string> {\n  try {\n    if (canonicalParts.instancePid === '') {\n      throw new ValidationError(\n        \"computeBrokerProof: instancePid must not be an empty string — omit the field entirely for \" +\n          \"'no instance' (F7); '' would alias onto a registered instance.\",\n      )\n    }\n    const canonical = buildCanonical(vaultId, brokerId, canonicalParts)\n    const key = await deriveBrokerProofKey(seed, vaultId, brokerId)\n    const mac = await subtle.sign('HMAC', key, new TextEncoder().encode(canonical) as BufferSource)\n    return bufferToBase64(new Uint8Array(mac))\n  } finally {\n    seed.fill(0)\n  }\n}\n\n/**\n * Host-side nonce mint: 32 random bytes, base64-encoded, plus an ISO\n * `expiresAt` at most `ttlMs` (default 60 s) in the future. The caller\n * (the broker host) persists both returned strings **verbatim** and MACs\n * those exact bytes on verify — never a reparsed/reformatted copy (F8).\n */\nexport function issueChallenge(opts?: { ttlMs?: number }): IssuedChallenge {\n  const ttlMs = opts?.ttlMs ?? DEFAULT_CHALLENGE_TTL_MS\n  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(32))\n  return {\n    challenge: bufferToBase64(bytes),\n    expiresAt: new Date(Date.now() + ttlMs).toISOString(),\n  }\n}\n\n/**\n * Verify a submitted broker proof. Order is NON-NEGOTIABLE (spec §3):\n *\n * 1. `await consumeChallenge(challenge)` FIRST — burn-and-check-fresh; a\n *    not-fresh (already-consumed or unknown) challenge short-circuits to\n *    `false` before any MAC work (F2).\n * 2. Empty-string `instancePid` is rejected (F7), then the canonical is\n *    recomputed over the verbatim `endpointOrigin`/`brokerId`/`profile`/\n *    `instancePid`/`challenge`/`expiresAt` and compared via\n *    `crypto.subtle.verify('HMAC', …)` — portable, constant-time, never a\n *    manual compare or Node `timingSafeEqual` (F6).\n * 3. `now < expiresAt` — the client clock is never trusted; `expiresAt`\n *    rides inside the already-verified MAC (F4/F8).\n */\nexport async function verifyBrokerProof(args: VerifyBrokerProofArgs): Promise<boolean> {\n  const fresh = await args.consumeChallenge(args.challenge)\n  if (!fresh) return false\n\n  if (args.instancePid === '') return false\n\n  const canonical = buildCanonical(args.vaultId, args.brokerId, {\n    endpointOrigin: args.endpointOrigin,\n    profile: args.profile,\n    instancePid: args.instancePid,\n    challenge: args.challenge,\n    expiresAt: args.expiresAt,\n  })\n  const key = await subtle.importKey(\n    'raw',\n    args.registeredProofKey as BufferSource,\n    { name: 'HMAC', hash: 'SHA-256' },\n    false,\n    ['verify'],\n  )\n  const ok = await subtle.verify(\n    'HMAC',\n    key,\n    base64ToBuffer(args.proof) as BufferSource,\n    new TextEncoder().encode(canonical) as BufferSource,\n  )\n  if (!ok) return false\n\n  return Date.now() < Date.parse(args.expiresAt)\n}\n","import type { CapsuleGroup } from '../contract.js'\n\n/**\n * `enclave-aes` supports every group. It is the REFERENCE capsule — the\n * behaviour every other implementation is compared against, and the one hub\n * ships so that `npm install @noy-db/hub` alone is a working noy-db.\n *\n * An `exclave-*` refuses `authenticate` and `seal` (no secret, no key\n * hierarchy — the store's own IAM is the authority) and may refuse the\n * optional groups. That asymmetry is what the prefix means, and the\n * conformance suite asserts it from the package name rather than trusting a\n * declaration.\n *\n * Frozen so a caller cannot edit what a capsule claims to support: a mutable\n * set would let a service \"enable\" a group by adding to it, which is exactly\n * the confidently-wrong failure the typed refusal exists to prevent.\n */\n/**\n * ⛔ `Object.freeze` does NOT make a Set immutable — it guards own properties,\n * not internal slots, so `frozen.add(x)` still succeeds. Measured 2026-09-12,\n * against a test that asserted otherwise and failed. The mutators are replaced\n * so the refusal is real at runtime, not just in the type.\n *\n * Why it has to be real: a caller holding a mutable capability set can \"enable\"\n * a group the capsule does not implement, and the next thing that happens is a\n * primitive being called on a capsule that has none. `ReadonlySet` alone is a\n * compile-time claim, and a JS consumer never sees it.\n */\nfunction sealedSet<T>(items: readonly T[]): ReadonlySet<T> {\n  const set = new Set<T>(items)\n  const refuse = (): never => {\n    throw new TypeError(\n      'capabilities() is immutable — a capsule\\'s declared groups cannot be edited by a caller',\n    )\n  }\n  set.add = refuse as never\n  set.delete = refuse as never\n  set.clear = refuse as never\n  return Object.freeze(set)\n}\n\nconst ALL: ReadonlySet<CapsuleGroup> = sealedSet<CapsuleGroup>([\n  'authenticate',\n  'seal',\n  'cipher',\n  'digest',\n  'sign',\n  'codec',\n  'sealing',\n  'deterministic',\n  'classify',\n])\n\nexport function capabilities(): ReadonlySet<CapsuleGroup> {\n  return ALL\n}\n","/**\n * **capsule/enclave-aes** — the hub's crypto interior, behind one door.\n *\n * This barrel is **the fork-swap contract**: a sister project that wants a\n * different crypto engine (a different KDF, a hardware-backed keystore, a\n * post-quantum wrap algorithm, …) replaces the entire `capsule/enclave-aes/`\n * folder wholesale and only has to honor the exports below. Nothing outside\n * `capsule/enclave-aes/**` may deep-import `crypto.js` or `record-keys/*` directly\n * — `scripts/check-architecture.mjs`'s `enclave-barrel-only` check enforces\n * that mechanically. Import sites inside `capsule/enclave-aes/**` keep their\n * existing relative imports; this door is for everyone else.\n *\n * The export list is the OBSERVED contract — exactly the symbols consumed\n * from outside this folder today — grouped by the module that defines them:\n *\n *   - key type       — `crypto.ts`: `EnclaveKey`, the opaque key type every\n *                       barrel-facing signature traffics in (`= CryptoKey` in\n *                       noy-db's reference enclave; a fork redefines it to its\n *                       own key representation — see the type's own doc for\n *                       the fork contract).\n *   - crypto ops     — `crypto.ts`: AES-256-GCM encrypt/decrypt (+ bytes, AAD,\n *                       deterministic variants), SHA-256 / HMAC-SHA-256 hashing.\n *   - key lifecycle  — `crypto.ts` + `record-keys/lifecycle.ts`: KEK/DEK\n *                       derivation, AES-KW wrap/unwrap, per-record CEK\n *                       wrap/unwrap/import + resolution/re-wrap, HKDF-derived\n *                       presence/sealed-field keys, base64 helpers.\n *   - record codec   — `record-keys/record-codec.ts`: the per-record\n *                       encode/decode engine.\n *   - sealing        — `record-keys/sealing.ts`: the sealed-record grantor\n *                       primitives (seal/revoke/rotate to an `at-*` host).\n *   - deterministic  — `record-keys/deterministic.ts`: blind-equality lookup\n *                       over deterministically-encrypted fields.\n *   - tombstone      — `record-keys/tombstone.ts`: the erased-record residue.\n *   - envelope body  — `record-keys/envelope-body.ts`: the C1 protected-body\n *                       access contract (`openEnvelopeJson`,\n *                       `writeEnvelopeBody`, `hasPerRecordKey`,\n *                       `hasSealedBody`, `envelopeBodyForHash`) — the\n *                       sanctioned door onto\n *                       `_iv`/`_data`/`_cek`/`_sealed` for everyone outside\n *                       this folder.\n *   - reserved envelopes — `plumbing/sealed-slots.ts`: `makeReservedEnvelopes`,\n *                       the whole-envelope encrypt/decrypt door scoped to a\n *                       declared collection-name prefix (e.g. `_dict_`) —\n *                       `kernel/vault.ts` binds it for `DictionaryHandle`\n *                       (#629 Task 4).\n *\n * Additive changes only — removing or renaming an export here is breaking\n * for any fork. Frozen by `__tests__/enclave-surface-golden.test.ts`.\n *\n * **Refusal contract:** the barrel above is frozen — every symbol must\n * exist in any fork — but the optional groups (sealing, deterministic,\n * per-record-key lifecycle) MAY throw `EnclaveNotSupportedError` instead\n * of implementing the reference behavior. The core groups (crypto ops,\n * record codec, tombstone) MUST NOT throw it — they are load-bearing for\n * every consumer regardless of which enclave is wired in. noy-db's own\n * enclave supports every group, so it never throws this error.\n */\n\nimport { aesCapsule } from './bound.js'\n\n// ─── key type ──────────────────────────────────────────────────────\nexport type { EnclaveKey, EncryptResult } from './crypto.js'\n\n// ─── crypto ops ────────────────────────────────────────────────────\nexport {\n  encrypt,\n  decrypt,\n  encryptBytes,\n  decryptBytes,\n  encryptBytesWithAAD,\n  decryptBytesWithAAD,\n  encryptDeterministic,\n  decryptDeterministic,\n} from './crypto.js'\n\n// ─── key lifecycle ─────────────────────────────────────────────────\nexport {\n  deriveKey,\n  deriveSecretKey,\n  generateDEK,\n  generateEphemeralKey,\n  importTransferKey,\n  exportDekSet,\n  importDekSet,\n  wrapKey,\n  unwrapKey,\n  mintCanary,\n  checkCanary,\n  deriveDeterministicKey,\n  deriveSealedFieldKey,\n  deriveSealedFieldKeyFromCek,\n  wrapCek,\n  unwrapCek,\n  importCek,\n  deriveEchoKey,\n} from './crypto.js'\nexport type { SecretKeyUsage } from './crypto.js'\n// ─── shared plumbing ───────────────────────────────────────────────\n//\n// Everything from here to the end of this block used to be twelve modules\n// under `./record-keys/`. They now live once in `../plumbing/`, and this\n// capsule is one of two callers of `makeCapsule()`.\n//\n// The split below is not cosmetic. The cipher-FREE half is re-exported\n// straight from its module: it inspects envelope fields and derives hash\n// input, so there is nothing to bind and every capsule gets the identical\n// function. The cipher-BOUND half is destructured off `aesCapsule`, which is\n// `makeCapsule(aesPrimitives)` — one binding for the whole capsule, so a value\n// exported here and a value used inside `classify/**` are the SAME object.\nexport {\n  buildRecordAad,\n  recordAadFor,\n  buildRecordEnvelope,\n  isTombstone,\n  isTombstoneShape,\n  buildTombstone,\n  isDeleteMarker,\n  buildDeleteMarker,\n  requireSealedBody,\n  sealedBodyArgs,\n  envelopeBodySize,\n  hasPerRecordKey,\n  envelopeBodyForHash,\n  hasSealedBody,\n} from '../plumbing/index.js'\n// ─── digest group ──────────────────────────────────────────────────\n// Shared, not AES-specific: the seam design marks `digest` \"as today\" for every\n// capsule. Re-exported here so the barrel's surface is unchanged.\nexport {\n  sha256Hex,\n  sha256Bytes,\n  hmacSha256Hex,\n  hmacSignHex,\n  hkdfAesGcmKey,\n  deriveBlobAddressKey,\n  derivePresenceKey,\n  derivePresenceTagKey,\n  generateIV,\n  generateSalt,\n  generateRecoverySecret,\n  bufferToBase64,\n  base64ToBuffer,\n  encodeEchoParts,\n} from '../plumbing/digest.js'\nexport type { EchoSecretParts } from '../plumbing/digest.js'\nexport type { RecordIdentity, RecordRef } from '../plumbing/index.js'\nimport type { RecordCodecBase } from '../plumbing/record-codec.js'\n/**\n * `RecordCodec` is a VALUE (the capsule-bound subclass, destructured below) and\n * a TYPE (the module-level generic base). A type ALIAS can coexist with a value\n * of the same name; a `export type { RecordCodec }` RE-EXPORT cannot, which is\n * what `TS2323: Cannot redeclare exported variable` was saying.\n */\nexport type RecordCodec<T = Record<string, unknown>> = RecordCodecBase<T>\nexport { buildSealedRecordEnvelope } from '../plumbing/record-envelope.js'\nexport type { RecordEnvelopeBody } from '../plumbing/record-envelope.js'\nexport type { RewrappedBody } from '../plumbing/lifecycle.js'\nexport type { SealedShredSlot } from '../plumbing/record-codec.js'\nexport type { SealingContext } from '../plumbing/sealing.js'\nexport type { DeterministicContext } from '../plumbing/deterministic.js'\n\nexport const {\n  // envelope body\n  openEnvelopeJson,\n  writeEnvelopeBody,\n  verifyRecordIdentity,\n  // key lifecycle\n  resolveStableCek,\n  rewrapBodyToDek,\n  rewrapEnvelope,\n  applyRewrappedBody,\n  isRewrappedUnder,\n  // rekey\n  rekeyEnvelopeToDek,\n  rekeyEnvelopeIfNeeded,\n  envelopeOpensUnderAny,\n  rekeyBlobSet,\n  // record codec\n  RecordCodec,\n  // sealed slots — ONLY `makeReservedEnvelopes` is part of the frozen surface.\n  // The other seven are capsule-internal; destructuring the whole capsule here\n  // leaked them and widened the golden by 8 names. A surface is a contract, so\n  // the fix is to narrow the barrel, not to re-baseline the golden.\n  makeReservedEnvelopes,\n  // sealing\n  SEALED_CEK_NS,\n  sealRecordToHost,\n  revokeSealedRecord,\n  rotateRecordCek,\n  // deterministic\n  findByDet,\n  queryByDet,\n} = aesCapsule\n\n// ─── reserved envelopes (ViaCryptoCtx.reservedEnvelopes capability) ──\n\n// ─── classify (stage-2 verify oracle primitives) ────────────────────\n// ADDITIVE per Enclave Contract v1. A fork must provide these four; the\n// verify/matchGroup orchestration (classify/verify.ts) sits behind the\n// with-shape dynamic-import seam and is not part of the fork contract.\nexport { deriveVdigSlotKey } from './classify/vdig.js'\nexport { pbkdf2VerifyDigest } from './classify/digest.js'\nexport { ctEqualTags } from '../plumbing/ct-equal.js'\nexport { evaluateKofN } from '../plumbing/kofn.js'\n\n// ─── classify (slice-2b equatable blind index) ──────────────────────\n// ADDITIVE per Enclave Contract v1. A fork must provide these four; the\n// findByDigest orchestration (collection.ts) sits behind the with-shape\n// dynamic-import seam and is not part of the fork contract.\nexport { deriveClassifyIndexKey, deriveClassifyIndexSalt, mintBidxTag } from './classify/bidx.js'\nexport { computeBidxTarget } from './classify/find.js'\n\n// ─── broker (proof derivation + challenge/verify, #479 slice 2) ─────\n// ADDITIVE per Enclave Contract v1. A fork must provide these five; the\n// seed lifecycle + network/cache orchestration (with-party/broker/**) sits\n// behind its own dynamic-import seam and is not part of the fork contract.\nexport {\n  deriveBrokerProofBits,\n  deriveBrokerProofKey,\n  computeBrokerProof,\n  issueChallenge,\n  verifyBrokerProof,\n} from './broker/proof.js'\nexport type { BrokerProofCanonicalParts, VerifyBrokerProofArgs, IssuedChallenge } from './broker/proof.js'\n\n// ─── sign ─────────────────────────────────────────────────────────────\nexport { generateSigningKeyPair, signBytes, verifyBytes } from '../plumbing/sign.js'\n\n// ─── recipient sealing ────────────────────────────────────────────────\nexport type { EnclaveKeyPair } from './crypto.js'\nexport {\n  generateRecipientKeyPair,\n  exportRecipientPublicKeySpki,\n  importRecipientPublicKeySpki,\n  recipientWrap,\n  recipientUnwrap,\n} from './crypto.js'\n\n// ─── capabilities ─────────────────────────────────────────────────────\n// What THIS capsule supports. Part of the contract every capsule implements,\n// not an enclave-aes detail — an alternative declares its own, and a service\n// asserts against it at createNoydb() rather than failing on first write.\nexport { capabilities } from './capabilities.js'\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,IAAM,SAAS,WAAW,OAAO;AAG1B,IAAM,sBAAsB;AAG5B,IAAM,uBAAuB;AAGpC,IAAM,2BAA2B;AAuCjC,SAAS,eAAe,SAAiB,UAAkB,OAA0C;AACnG,SAAO,KAAK,UAAU;AAAA,IACpB;AAAA,IACA;AAAA,IACA,MAAM;AAAA,IACN;AAAA,IACA,MAAM,WAAW;AAAA,IACjB,MAAM,eAAe;AAAA,IACrB,MAAM;AAAA,IACN,MAAM;AAAA,EACR,CAAC;AACH;AAQA,eAAsB,sBACpB,MACA,SACA,UACqB;AACrB,QAAM,UAAU,MAAM,OAAO,UAAU,OAAO,MAAsB,QAAQ,OAAO,CAAC,YAAY,CAAC;AACjG,QAAM,OAAO,IAAI,YAAY,EAAE,OAAO,mBAAmB;AACzD,QAAM,OAAO,IAAI,YAAY,EAAE,OAAO,KAAK,UAAU,CAAC,qBAAqB,SAAS,QAAQ,CAAC,CAAC;AAC9F,QAAM,OAAO,MAAM,OAAO,WAAW,EAAE,MAAM,QAAQ,MAAM,WAAW,MAAM,KAAK,GAAG,SAAS,GAAG;AAChG,SAAO,IAAI,WAAW,IAAI;AAC5B;AAQA,eAAsB,qBACpB,MACA,SACA,UACqB;AACrB,QAAM,YAAY,MAAM,sBAAsB,MAAM,SAAS,QAAQ;AACrE,MAAI;AACF,WAAO,MAAM,OAAO,UAAU,OAAO,WAA2B,EAAE,MAAM,QAAQ,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;AAAA,EACpH,UAAE;AACA,cAAU,KAAK,CAAC;AAAA,EAClB;AACF;AAWA,eAAsB,mBACpB,MACA,SACA,UACA,gBACiB;AACjB,MAAI;AACF,QAAI,eAAe,gBAAgB,IAAI;AACrC,YAAM,IAAI;AAAA,QACR;AAAA,MAEF;AAAA,IACF;AACA,UAAM,YAAY,eAAe,SAAS,UAAU,cAAc;AAClE,UAAM,MAAM,MAAM,qBAAqB,MAAM,SAAS,QAAQ;AAC9D,UAAM,MAAM,MAAM,OAAO,KAAK,QAAQ,KAAK,IAAI,YAAY,EAAE,OAAO,SAAS,CAAiB;AAC9F,WAAO,eAAe,IAAI,WAAW,GAAG,CAAC;AAAA,EAC3C,UAAE;AACA,SAAK,KAAK,CAAC;AAAA,EACb;AACF;AAQO,SAAS,eAAe,MAA4C;AACzE,QAAM,QAAQ,MAAM,SAAS;AAC7B,QAAM,QAAQ,WAAW,OAAO,gBAAgB,IAAI,WAAW,EAAE,CAAC;AAClE,SAAO;AAAA,IACL,WAAW,eAAe,KAAK;AAAA,IAC/B,WAAW,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,EAAE,YAAY;AAAA,EACtD;AACF;AAgBA,eAAsB,kBAAkB,MAA+C;AACrF,QAAM,QAAQ,MAAM,KAAK,iBAAiB,KAAK,SAAS;AACxD,MAAI,CAAC,MAAO,QAAO;AAEnB,MAAI,KAAK,gBAAgB,GAAI,QAAO;AAEpC,QAAM,YAAY,eAAe,KAAK,SAAS,KAAK,UAAU;AAAA,IAC5D,gBAAgB,KAAK;AAAA,IACrB,SAAS,KAAK;AAAA,IACd,aAAa,KAAK;AAAA,IAClB,WAAW,KAAK;AAAA,IAChB,WAAW,KAAK;AAAA,EAClB,CAAC;AACD,QAAM,MAAM,MAAM,OAAO;AAAA,IACvB;AAAA,IACA,KAAK;AAAA,IACL,EAAE,MAAM,QAAQ,MAAM,UAAU;AAAA,IAChC;AAAA,IACA,CAAC,QAAQ;AAAA,EACX;AACA,QAAM,KAAK,MAAM,OAAO;AAAA,IACtB;AAAA,IACA;AAAA,IACA,eAAe,KAAK,KAAK;AAAA,IACzB,IAAI,YAAY,EAAE,OAAO,SAAS;AAAA,EACpC;AACA,MAAI,CAAC,GAAI,QAAO;AAEhB,SAAO,KAAK,IAAI,IAAI,KAAK,MAAM,KAAK,SAAS;AAC/C;;;ACvOA,SAAS,UAAa,OAAqC;AACzD,QAAM,MAAM,IAAI,IAAO,KAAK;AAC5B,QAAM,SAAS,MAAa;AAC1B,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,MAAI,MAAM;AACV,MAAI,SAAS;AACb,MAAI,QAAQ;AACZ,SAAO,OAAO,OAAO,GAAG;AAC1B;AAEA,IAAM,MAAiC,UAAwB;AAAA,EAC7D;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAEM,SAAS,eAA0C;AACxD,SAAO;AACT;;;AC0GO,IAAM;AAAA;AAAA,EAEX;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA;AAAA;AAAA;AAAA;AAAA,EAKA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AACF,IAAI;","names":[]}

package/dist/capsule/enclave-aes/primitives.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `enclave-aes` as a {@link CapsulePrimitives} — the 13 functions the shared
+ * plumbing binds to.
+ *
+ * ⭐ THE ASSIGNMENT BELOW IS A TEST, and it is the reason this file exists as
+ * a file rather than an inline object at the `makeCapsule()` call. Declaring
+ * the seam type and implementing it are two different acts; nothing checks a
+ * hand-written interface against the module it claims to describe unless
+ * something binds one to the other. This binding caught two errors in the
+ * declaration within minutes of it being written:
+ *
+ *   - `deriveDeterministicKey` was declared `(dek, context)`. It takes ONE
+ *     argument — the AES capsule derives the context into the IV, not the key.
+ *   - `bufferToBase64` was declared `(bytes: Uint8Array)`. It also accepts an
+ *     `ArrayBuffer`, which is what its callers actually pass.
+ *
+ * Both would have compiled here and failed at the far end of the refactor,
+ * where the cause is no longer visible. (The same lesson as `#16`: a
+ * structural declaration drifts silently from its implementation until an
+ * assignment pins the two together.)
+ *
+ * ⚠️ Method shorthand in `CapsulePrimitives` is checked BIVARIANTLY, so this
+ * assignment does NOT catch parameter-arity drift — that is exactly how the
+ * `deriveDeterministicKey` mistake survived the type and was caught by a call
+ * site instead. Keep the conformance kit's call-site coverage; this assignment
+ * is necessary, not sufficient.
+ */
+import type { CapsulePrimitives } from '../contract.js';
+export declare const aesPrimitives: CapsulePrimitives;

package/dist/capsule/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * THE DOOR. This is the ONLY hub file that may import the bound capsule.
+ * Everything else in hub imports THIS file.
+ *
+ * Enforced by `capsule-door-only` in `scripts/check-architecture.mjs`, which
+ * fails any other file naming `#capsule`. A door nothing enforces is not a
+ * door — the enclave barrel it replaces was reached around 38 times before a
+ * check existed.
+ *
+ * `#capsule` resolves through hub's `imports` map: `capsule/enclave-aes/` by
+ * default, or an alternative package when a consumer sets a build condition.
+ *
+ * ⛔ THE RE-EXPORTS BELOW ARE EXPLICIT, AND MUST STAY THAT WAY.
+ * `export * from '#capsule'` is the obvious spelling and it does not build:
+ * `#capsule` is EXTERNAL (it has to be, or the capsule choice bakes in at hub's
+ * build time), and esbuild cannot enumerate an external module's exports. Every
+ * named import through the door then fails with "No matching export". Measured
+ * 2026-09-12.
+ *
+ * Generated from `__tests__/enclave-surface.golden.json` — the same artefact
+ * the surface test freezes, so the door and the golden cannot drift. Adding a
+ * capsule primitive means adding it to the golden and regenerating.
+ */
+export { RecordCodec, SEALED_CEK_NS, applyRewrappedBody, base64ToBuffer, bufferToBase64, buildDeleteMarker, buildRecordAad, buildRecordEnvelope, buildSealedRecordEnvelope, buildTombstone, capabilities, checkCanary, computeBidxTarget, computeBrokerProof, ctEqualTags, decrypt, decryptBytes, decryptBytesWithAAD, decryptDeterministic, deriveBlobAddressKey, deriveBrokerProofBits, deriveBrokerProofKey, deriveClassifyIndexKey, deriveClassifyIndexSalt, deriveDeterministicKey, deriveEchoKey, deriveKey, derivePresenceKey, derivePresenceTagKey, deriveSealedFieldKey, deriveSealedFieldKeyFromCek, deriveSecretKey, deriveVdigSlotKey, encodeEchoParts, encrypt, encryptBytes, encryptBytesWithAAD, encryptDeterministic, envelopeBodyForHash, envelopeBodySize, envelopeOpensUnderAny, evaluateKofN, exportDekSet, exportRecipientPublicKeySpki, findByDet, generateDEK, generateEphemeralKey, generateIV, generateRecipientKeyPair, generateRecoverySecret, generateSalt, generateSigningKeyPair, hasPerRecordKey, hasSealedBody, requireSealedBody, sealedBodyArgs, hkdfAesGcmKey, hmacSha256Hex, hmacSignHex, importCek, importDekSet, importRecipientPublicKeySpki, importTransferKey, isDeleteMarker, isRewrappedUnder, isTombstone, isTombstoneShape, issueChallenge, makeReservedEnvelopes, mintBidxTag, mintCanary, openEnvelopeJson, pbkdf2VerifyDigest, queryByDet, recipientUnwrap, recipientWrap, recordAadFor, rekeyBlobSet, rekeyEnvelopeIfNeeded, rekeyEnvelopeToDek, resolveStableCek, revokeSealedRecord, rewrapBodyToDek, rewrapEnvelope, rotateRecordCek, sealRecordToHost, sha256Bytes, sha256Hex, signBytes, unwrapCek, unwrapKey, verifyBrokerProof, verifyBytes, verifyRecordIdentity, wrapCek, wrapKey, writeEnvelopeBody, } from '#capsule';
+export type { BrokerProofCanonicalParts, DeterministicContext, EchoSecretParts, EnclaveKey, EnclaveKeyPair, EncryptResult, IssuedChallenge, RecordEnvelopeBody, RecordIdentity, RecordRef, RewrappedBody, SealedShredSlot, SealingContext, SecretKeyUsage, VerifyBrokerProofArgs, } from '#capsule';
+export type { CapsuleKey, CapsuleKeyPair, CapsuleGroup } from './contract.js';
+export { CapsuleNotSupportedError } from './contract.js';

package/dist/capsule/plumbing/ct-equal.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Constant-time 32-byte tag comparison.
+ *
+ * Pure — no WebCrypto, no key material — so it is plumbing rather than a
+ * capsule primitive. It lived in `enclave-aes/classify/compare.ts` only
+ * because that is where its first caller was; leaving it there would have made
+ * `@noy-db/hub/capsule` import the AES capsule to reach it, which is precisely
+ * the coupling the seam exists to remove.
+ */
+/** Compare exactly-32-byte tags. XOR-accumulate over all 32 bytes, no early exit. */
+export declare function ctEqualTags(a: Uint8Array, b: Uint8Array): boolean;

package/dist/{kernel/enclave/record-keys → capsule/plumbing}/deterministic.d.ts

@@ -16,10 +16,10 @@
  *
  * Internal service — not exported as a `@noy-db/hub/*` subpath.
  */
-import { type EnclaveKey } from '../crypto.js';
-import type { NoydbStore } from '../../types.js';
-import type { RecordCodec } from './record-codec.js';
+import type { NoydbStore } from '../../kernel/types.js';
+import type { RecordCodec } from './index.js';
 /** Everything the moving deterministic-index methods touched on `this.*`. */
+import type { CapsuleKey, CapsulePrimitives } from '../contract.js';
 export interface DeterministicContext<T> {
     /** Collection name — the deterministic-encryption AAD scope. */
     readonly name: string;
@@ -32,24 +32,11 @@ export interface DeterministicContext<T> {
     /** False on plaintext collections — det lookups are encrypted-only. */
     readonly storeCiphertext: boolean;
     /** The collection DEK resolver. */
-    getDEK(): Promise<EnclaveKey>;
+    getDEK(): Promise<CapsuleKey>;
     /** The record codec — decrypts a matched envelope to T. */
     readonly codec: RecordCodec<T>;
 }
-/**
- * Find the first record whose deterministic field matches the given plaintext.
- * Returns `null` when no match exists.
- *
- * Reads every envelope via the adapter and compares the stored `_det[field]` to
- * a freshly computed deterministic ciphertext — no record bodies are decrypted
- * during the search.
- *
- * Throws when the field is not declared in `deterministicFields`, so a typo
- * fails loudly at the call site rather than silently returning null forever.
- */
-export declare function findByDet<T>(ctx: DeterministicContext<T>, field: string, value: unknown): Promise<T | null>;
-/**
- * Return every record whose deterministic field matches. Same semantics as
- * {@link findByDet} but without the short-circuit.
- */
-export declare function queryByDet<T>(ctx: DeterministicContext<T>, field: string, value: unknown): Promise<T[]>;
+export declare function makeDeterministic(p: CapsulePrimitives): {
+    findByDet: <T>(ctx: DeterministicContext<T>, field: string, value: unknown) => Promise<T | null>;
+    queryByDet: <T>(ctx: DeterministicContext<T>, field: string, value: unknown) => Promise<T[]>;
+};

package/dist/capsule/plumbing/digest.d.ts

@@ -0,0 +1,122 @@
+/** AES key size in bits. Shared: every capsule that derives an AES-GCM subkey
+ *  from the digest group produces a 256-bit key, or the derivations diverge. */
+export declare const KEY_BITS = 256;
+export declare const IV_BYTES = 12;
+/** The echo-secret typed parts. Encoding lives here with `encodeEchoParts`; the
+ *  KEK derivation that consumes it stays in the capsule's `authenticate` group. */
+export interface EchoSecretParts {
+    readonly prompt: string;
+    readonly echo: string;
+    readonly key: string;
+}
+/**
+ * AG-1 encoding: domain context + 4-byte big-endian length prefix per
+ * part. Two independent guarantees make a single typed string unable to
+ * derive an echo vault's KEK (spec AG-1):
+ *
+ *   1. The `0xFF` context prefix — UTF-8 never produces that byte, so the
+ *      encoding is provably not the encoding of ANY string (not merely of
+ *      no separator-joined form).
+ *   2. Structural length prefixes — part boundaries are key material, so
+ *      re-splitting the same characters changes the derived KEK.
+ *
+ * @throws ValidationError when any part is not a string — the single
+ * chokepoint every echo KEK derivation and block mint passes through, so a
+ * malformed parts object cannot be `TextEncoder`-coerced into key material.
+ */
+export declare function encodeEchoParts(parts: EchoSecretParts): Uint8Array;
+/**
+ * SHA-256 hex digest of raw bytes. Used to derive content-addressed
+ * eTags for blob deduplication. Computed on plaintext bytes
+ * before compression and encryption so the eTag identifies content, not
+ * ciphertext, and survives re-encryption (key rotation, re-upload).
+ */
+export declare function sha256Hex(data: Uint8Array): Promise<string>;
+/** SHA-256 of raw bytes, as bytes. */
+export declare function sha256Bytes(data: Uint8Array): Promise<Uint8Array>;
+/**
+ * Derive the blob CONTENT-ADDRESSING key for one tier (#1126).
+ *
+ * The blob eTag is an HMAC over the plaintext. It used to be keyed by the
+ * `_blob` DEK — the very key `rotateKeys` replaces — so after any rotation
+ * `HMAC(live DEK, plaintext) !== storedETag` for every blob written before it,
+ * permanently. `decryptResponse()` checks that unconditionally, so the
+ * presigned-URL read path raised `TamperedError` on legitimate data forever;
+ * dedup also split, minting a second address for identical bytes.
+ *
+ * The fix is a `root` that rotation never touches (`_blob_addr`, refused by
+ * `rotateKeys` exactly as `_roster` is). Rotation then re-keys chunk BODIES
+ * while every address stays stable, which is what makes the AAD
+ * `{eTag}:{i}:{count}` and every `_blob_index` / `_blob_slots_*` /
+ * `_blob_versions_*` row survive it untouched.
+ *
+ * **Derived PER TIER, deliberately.** A single vault-wide address would make an
+ * elevated blob and a tier-0 blob with identical content share an eTag,
+ * leaking equality across a boundary the tier system exists to enforce — and
+ * `rehomeForTier` re-addresses on a tier move precisely because the address is
+ * tier-scoped today. Domain separation keeps that property while removing the
+ * rotation coupling: the two are independent axes, and only one of them was
+ * ever meant to change the address.
+ *
+ * Same HKDF idiom as `asKwKey`, with its own salt so the addressing key can
+ * never coincide with a wrapping or encryption key.
+ */
+export declare function deriveBlobAddressKey(root: CryptoKey, tier: number): Promise<CryptoKey>;
+/**
+ * HMAC-SHA-256(key, data) as hex.
+ *
+ * Keyed, unlike {@link sha256Hex}: blob eTags derived with this are opaque to
+ * the store, so an attacker with store access cannot pre-compute the address of
+ * a file they guess at. Dedup still works inside a vault, where the key is shared.
+ */
+export declare function hmacSha256Hex(key: CryptoKey, data: Uint8Array): Promise<string>;
+/**
+ * Derive an AES-256-GCM presence key from a collection DEK using HKDF-SHA256.
+ *
+ * The presence key is domain-separated from the data DEK by the fixed salt
+ * `'noydb-presence'` and the `info` = collection name. This means:
+ *  - The adapter never sees the presence key.
+ *  - Presence payloads rotate automatically when the collection DEK is rotated.
+ *  - Revoked users cannot derive the new presence key after a DEK rotation.
+ *
+ * @param dek            The collection's AES-256-GCM DEK (extractable).
+ * @param collectionName Used as the HKDF `info` parameter for domain separation.
+ * @returns A non-extractable AES-256-GCM key suitable for presence payload encryption.
+ */
+export declare function derivePresenceKey(dek: CryptoKey, collectionName: string): Promise<CryptoKey>;
+/**
+ * Derive the presence-TAG key from a collection DEK: a non-extractable,
+ * sign-only HMAC-SHA256 key, HKDF-separated from the presence PAYLOAD key
+ * ({@link derivePresenceKey}) by its own salt. The tag is the adapter-opaque
+ * record id for storage-polled presence; the adapter never sees the userId.
+ */
+export declare function derivePresenceTagKey(dek: CryptoKey, collectionName: string): Promise<CryptoKey>;
+/**
+ * HMAC-SHA256 hex with a key that IS an HMAC key (e.g. from
+ * {@link derivePresenceTagKey}). {@link hmacSha256Hex} takes an AES-GCM
+ * carrier and re-imports its raw bytes, which needs an extractable key;
+ * this one signs directly and works with non-extractable keys.
+ */
+export declare function hmacSignHex(key: CryptoKey, data: Uint8Array): Promise<string>;
+/**
+ * HKDF-SHA256 → non-extractable AES-256-GCM key from caller-supplied input
+ * key material. The magic-link content key derives here from
+ * `(serverSecret, SHA-256(token), info)`; `salt`/`info` are the caller's
+ * domain separation, this function adds none.
+ */
+export declare function hkdfAesGcmKey(ikm: Uint8Array, salt: Uint8Array, info: Uint8Array): Promise<CryptoKey>;
+/** Generate a random 12-byte IV for AES-GCM. */
+export declare function generateIV(): Uint8Array;
+/** Generate a random 32-byte salt for PBKDF2. */
+export declare function generateSalt(): Uint8Array;
+/**
+ * Mint a fresh recovery secret — the high-entropy value a recovery profile
+ * wraps the DEK set under and then hands out (Shamir splits it into shares;
+ * paper prints it). Not a salt: a salt is public, this is not, and a fork
+ * may size them differently. The reference enclave returns 32 bytes.
+ *
+ * Callers must zero the buffer once it has been wrapped and split.
+ */
+export declare function generateRecoverySecret(): Uint8Array;
+export declare function bufferToBase64(buffer: ArrayBuffer | Uint8Array): string;
+export declare function base64ToBuffer(base64: string): Uint8Array<ArrayBuffer>;

package/dist/{kernel/enclave/record-keys → capsule/plumbing}/envelope-body.d.ts

@@ -5,7 +5,7 @@
  * `_v`, `_ts`, `_by`, `_source`, `_sourceTs`, `_tier`, `_elevatedBy`) and a
  * protected body (enclave-owned; `_iv`, `_data`, `_cek`, `_det`, `_sealed`,
  * `_debug`). The four helpers below are the ONLY sanctioned way for code
- * outside `kernel/enclave/**` to read or construct the protected body —
+ * outside `capsule/enclave-aes/**` to read or construct the protected body —
  * later migration batches move the ~121 direct `_iv`/`_data`/`_cek`/`_sealed`
  * access sites in `with-*` services onto these.
  *
@@ -13,41 +13,40 @@
  * per-function doc for its oracle call site) — this file introduces no new
  * crypto or semantics, only a narrower door onto what already runs.
  */
-import { type RecordIdentity, type RecordRef } from '../record-aad.js';
-import { type EnclaveKey } from '../crypto.js';
-import type { EncryptedEnvelope } from '../../types.js';
+import { type RecordIdentity, type RecordRef } from './record-aad.js';
+import type { CapsuleKey, CapsulePrimitives } from '../contract.js';
+import type { EncryptedEnvelope } from '../../kernel/types.js';
 /**
- * Open an envelope's protected body to its JSON text.
+ * The sealed body, or a typed refusal (#15).
  *
- * Mirrors the dominant direct-decrypt call-site shape (e.g.
- * `with-audit/consent/consent.ts`'s `decryptEntry`):
- *  - `opts.encrypted === false` (default `true`) → plaintext collection;
- *    returns `env._data` as-is, `key` untouched.
- *  - `env._cek` present → per-record-key envelope (mirrors
- *    `record-codec.ts`'s `resolveEnvelopeCek`): unwrap the CEK under `key`
- *    (the collection DEK), decrypt the body under the unwrapped CEK.
- *  - `env._cek` absent → legacy path, decrypt the body directly under `key`.
+ * Since `_iv`/`_data` became optional, every AES path that is about to call
+ * `decrypt()` needs this one narrowing. It is deliberately the ONLY place in
+ * the enclave that turns absence into an error: the alternative — a `!` or a
+ * `?? ''` at each of the two dozen decrypt sites — would have spelled the
+ * same decision twenty-four times and produced an AEAD failure (i.e. hub's
+ * tamper alert) instead of an honest one.
+ *
+ * Ask {@link hasSealedBody} FIRST when absence is a legitimate outcome; this
+ * helper is for the paths where it is not.
  */
-export declare function openEnvelopeJson(ref: RecordRef, env: EncryptedEnvelope, key: EnclaveKey, opts?: {
-    encrypted?: boolean;
-}): Promise<string>;
+export declare function requireSealedBody(env: Pick<EncryptedEnvelope, '_iv' | '_data'>, where: string): {
+    iv: string;
+    data: string;
+};
 /**
- * Produce the protected-body fields (`_iv`/`_data`/`_cek`) for an envelope a
- * caller is assembling.
+ * {@link requireSealedBody} shaped for the `decrypt(iv, data, …)` argument
+ * list, so a narrowing can be spliced into an existing call without
+ * restructuring the statement around it:
+ *
+ * ```ts
+ * await decrypt(...sealedBodyArgs(env, 'rekeyRecord'), dek, aad)
+ * ```
  *
- *  - `opts.encrypted === false` (default `true`) → plaintext collection;
- *    emits `{ _iv: '', _data: json }` (today's `buildPlaintextEnvelope`
- *    shape), `key` untouched.
- *  - `opts.perRecordKey === true` → mints a fresh per-record CEK, encrypts
- *    the body under it, and AES-KW-wraps the CEK under `key` (mirrors
- *    `encryptJsonString`'s `cek !== undefined` branch, except the CEK is
- *    generated here rather than supplied by the caller).
- *  - otherwise → legacy path, body encrypted directly under `key`.
+ * The tuple return type is load-bearing — it is what lets the spread satisfy
+ * two fixed positional parameters. Widening it to `string[]` would compile
+ * here and fail at every call site.
  */
-export declare function writeEnvelopeBody(identity: RecordIdentity, json: string, key: EnclaveKey, opts?: {
-    encrypted?: boolean;
-    perRecordKey?: boolean;
-}): Promise<Pick<EncryptedEnvelope, '_iv' | '_data' | '_cek'>>;
+export declare function sealedBodyArgs(env: Pick<EncryptedEnvelope, '_iv' | '_data'>, where: string): [string, string];
 /**
  * Approximate protected-body payload size for KPI/telemetry (#807's
  * period-scoped pull download counters): `_data` + `_iv` string length —
@@ -79,7 +78,7 @@ export declare function hasPerRecordKey(env: EncryptedEnvelope): boolean;
  *
  * Deliberately reimplements the two-key-object canonicalization inline
  * rather than importing `with-commit/history/ledger/entry.ts`'s general
- * `canonicalJson` — `kernel/enclave/**` may import only spine types (C3),
+ * `canonicalJson` — `capsule/enclave-aes/**` may import only spine types (C3),
  * never a `with-*` service. For this fixed `{ _data: string; _sealed:
  * Record<string, string> }` shape the two produce byte-identical output
  * (verified against that exact call site's oracle expression in
@@ -99,21 +98,18 @@ export declare function envelopeBodyForHash(env: EncryptedEnvelope): string;
  */
 export declare function hasSealedBody(env: Pick<EncryptedEnvelope, '_iv'>): boolean;
 /**
- * Does `env` authenticate at the identity `ref` claims, under `key`? (#1042)
- *
- * The merge's fail-closed check, living here because it is envelope surgery:
- * deciding "is there a sealed body at all" reads `_iv`, which
- * `enclave-body-only` reserves to this folder. An earlier draft did that test
- * in `kernel/noydb.ts` and the guard refused it — correctly, since a caller
- * outside the enclave inspecting protected fields is how envelope knowledge
- * leaks back out.
- *
- * Returns a boolean rather than throwing: `applyRemote` must be able to reject
- * one poisoned record without halting an entire sync, and a hostile store
- * would very much like the opposite.
- *
- * **A record with no sealed body is vacuously authentic** — a tombstone carries
- * none, and a plaintext collection has no AEAD to verify. Those are pass-through
- * by construction, not by omission.
+ * The cipher-dependent half: the three doors that actually reach the capsule's
+ * `encrypt`/`decrypt`. Everything above this line is cipher-FREE — it inspects
+ * envelope fields or derives hash input, so it stays a plain module export that
+ * both capsules share with nothing to bind.
  */
-export declare function verifyRecordIdentity(ref: RecordRef, env: EncryptedEnvelope, key: EnclaveKey): Promise<boolean>;
+export declare function makeEnvelopeBody(p: CapsulePrimitives): {
+    openEnvelopeJson: (ref: RecordRef, env: EncryptedEnvelope, key: CapsuleKey, opts?: {
+        encrypted?: boolean;
+    }) => Promise<string>;
+    writeEnvelopeBody: (identity: RecordIdentity, json: string, key: CapsuleKey, opts?: {
+        encrypted?: boolean;
+        perRecordKey?: boolean;
+    }) => Promise<Pick<EncryptedEnvelope, "_iv" | "_data" | "_cek">>;
+    verifyRecordIdentity: (ref: RecordRef, env: EncryptedEnvelope, key: CapsuleKey) => Promise<boolean>;
+};

package/dist/capsule/plumbing/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * `makeCapsule()` — hub's envelope plumbing, bound to one capsule's cipher.
+ *
+ * ⭐ WHY THIS EXISTS. `enclave-aes` is ~4,200 lines, but only ~1,200 touch
+ * `crypto.subtle`. The other ~3,000 — envelope assembly, record-identity AAD,
+ * tombstones, the record codec, sealed slots, rekeying — encode HUB'S ENVELOPE
+ * FORMAT, not anyone's cipher, so they are identical for every capsule. This
+ * module is the single copy; a capsule supplies {@link CapsulePrimitives} and
+ * gets the whole surface back.
+ *
+ * The alternative was copying the plumbing into each capsule. Rejected because
+ * nothing would fail when the copies drifted: a change to the tombstone shape
+ * or the AAD would have to be made twice, and the miss surfaces as an envelope
+ * one capsule writes and the other cannot read — at runtime, in a consumer.
+ *
+ * ⚠️ BINDING IS PER-CALL, NOT PER-PROCESS, and that is load-bearing. An
+ * earlier sketch bound primitives once into module state (`setPrimitives(p)`),
+ * which is simpler and wrong: the conformance kit runs two capsules in the
+ * same process, so a single global would make the second one silently inherit
+ * the first one's cipher — and both suites would still pass.
+ *
+ * Cipher-FREE helpers are NOT in here. They are plain exports of their own
+ * modules (`buildRecordAad`, `isTombstone`, `hasSealedBody`, …) because they
+ * inspect envelope fields and need nothing bound. Re-exported below so the
+ * capsule surface stays one import for consumers.
+ */
+import type { CapsulePrimitives } from '../contract.js';
+export { buildRecordAad, recordAadFor, type RecordIdentity, type RecordRef, } from './record-aad.js';
+export { buildRecordEnvelope } from './record-envelope.js';
+export { isTombstone, isTombstoneShape, buildTombstone, isDeleteMarker, buildDeleteMarker, } from './tombstone.js';
+export { normalizeForVerify } from './normalize.js';
+export { parseSealedSlot } from './sealed-slot.js';
+export { requireSealedBody, sealedBodyArgs, envelopeBodySize, hasPerRecordKey, envelopeBodyForHash, hasSealedBody, } from './envelope-body.js';
+/**
+ * Bind the plumbing to a capsule's primitives.
+ *
+ * Composition order is a real dependency order, not a style choice:
+ * `sealedSlot` feeds both `sealedSlots` and `sealing`; `sealedSlots` feeds the
+ * codec. Everything else depends only on `p`.
+ */
+export declare function makeCapsule(p: CapsulePrimitives): {
+    findByDet: <T>(ctx: import("./deterministic.js").DeterministicContext<T>, field: string, value: unknown) => Promise<T | null>;
+    queryByDet: <T>(ctx: import("./deterministic.js").DeterministicContext<T>, field: string, value: unknown) => Promise<T[]>;
+    SEALED_CEK_NS: string;
+    sealRecordToHost: (ctx: import("./sealing.js").SealingContext, collection: string, id: string, hostSealer: import("../../index.js").RecipientSealer, opts: {
+        expiresAt: string;
+    }) => Promise<{
+        pid: string;
+        envelopeKey: string;
+    }>;
+    revokeSealedRecord: (ctx: import("./sealing.js").SealingContext, collection: string, id: string, pid: string, opts?: {
+        hard?: boolean;
+    }) => Promise<void>;
+    rotateRecordCek: (ctx: import("./sealing.js").SealingContext, collection: string, id: string) => Promise<void>;
+    rekeyBlobSet: (adapter: import("../../index.js").NoydbStore, vault: string, oldDek: import("../contract.js").CapsuleKey, newDek: import("../contract.js").CapsuleKey, otherDeks?: readonly import("../contract.js").CapsuleKey[]) => Promise<import("./rekey-blob.js").BlobRekeyReport>;
+    rekeyEnvelopeToDek: (ref: {
+        readonly collection: string;
+        readonly id: string;
+    }, envelope: import("../../index.js").EncryptedEnvelope, oldDek: import("../contract.js").CapsuleKey, newDek: import("../contract.js").CapsuleKey) => Promise<import("../../index.js").EncryptedEnvelope>;
+    rekeyEnvelopeIfNeeded: (ref: {
+        readonly collection: string;
+        readonly id: string;
+    }, envelope: import("../../index.js").EncryptedEnvelope, oldDek: import("../contract.js").CapsuleKey, newDek: import("../contract.js").CapsuleKey) => Promise<import("../../index.js").EncryptedEnvelope | null>;
+    envelopeOpensUnderAny: (ref: {
+        readonly collection: string;
+        readonly id: string;
+    }, envelope: import("../../index.js").EncryptedEnvelope, keys: readonly import("../contract.js").CapsuleKey[]) => Promise<boolean>;
+    resolveStableCek: (deps: import("./lifecycle.js").StableCekDeps, id: string) => Promise<import("../contract.js").CapsuleKey>;
+    rewrapBodyToDek: (from: import("./record-aad.js").RecordIdentity, to: import("./record-aad.js").RecordIdentity, envelope: Pick<import("../../index.js").EncryptedEnvelope, "_iv" | "_data" | "_cek" | "_tier" | "_by">, fromDek: import("../contract.js").CapsuleKey, toDek: import("../contract.js").CapsuleKey) => Promise<import("./lifecycle.js").RewrappedBody>;
+    applyRewrappedBody: (envelope: import("../../index.js").EncryptedEnvelope, body: import("./lifecycle.js").RewrappedBody) => import("../../index.js").EncryptedEnvelope;
+    rewrapEnvelope: (identity: import("./record-aad.js").RecordIdentity, envelope: import("../../index.js").EncryptedEnvelope, fromDek: import("../contract.js").CapsuleKey, toDek: import("../contract.js").CapsuleKey) => Promise<import("../../index.js").EncryptedEnvelope>;
+    isRewrappedUnder: (identity: import("./record-aad.js").RecordIdentity, envelope: Pick<import("../../index.js").EncryptedEnvelope, "_iv" | "_data" | "_cek">, dek: import("../contract.js").CapsuleKey) => Promise<boolean>;
+    RecordCodec: import("./record-codec.js").BoundRecordCodec;
+    sealFields: (record: Record<string, unknown>, sensitiveFields: ReadonlySet<string>, keyMaterial: import("./sealed-slots.js").SealKeyMaterial) => Promise<import("./sealed-slots.js").SealFieldsResult>;
+    unsealOneField: (field: string, blob: string, keyMaterial: import("./sealed-slots.js").SealKeyMaterial) => Promise<unknown>;
+    makeHandleProducer: (keyMaterial: import("./sealed-slots.js").SealKeyMaterial) => (field: string, blob: string) => import("../../index.js").SealedHandle<unknown>;
+    unsealFields: (record: Record<string, unknown>, sealed: Record<string, string>, keyMaterial: import("./sealed-slots.js").SealKeyMaterial, opts?: {
+        asHandles?: boolean;
+    }) => Promise<Record<string, unknown>>;
+    makeSealedSlotCapability: (ctx: import("./sealed-slots.js").SealedSlotCapabilityCtx, recordId: string, cek?: import("../contract.js").CapsuleKey) => import("../../kernel/via/index.js").ViaCryptoCtx["sealedSlots"];
+    makeReservedEnvelopes: (dekResolver: import("./sealed-slots.js").ReservedEnvelopeDekResolver, declaredPrefixes: readonly string[]) => import("../../kernel/via/index.js").ViaCryptoCtx["reservedEnvelopes"];
+    dualReadSealedSlot: (blob: string, field: string, collection: string, cek: CryptoKey | undefined, dek: CryptoKey) => Promise<string>;
+    openEnvelopeJson: (ref: import("./record-aad.js").RecordRef, env: import("../../index.js").EncryptedEnvelope, key: import("../contract.js").CapsuleKey, opts?: {
+        encrypted?: boolean;
+    }) => Promise<string>;
+    writeEnvelopeBody: (identity: import("./record-aad.js").RecordIdentity, json: string, key: import("../contract.js").CapsuleKey, opts?: {
+        encrypted?: boolean;
+        perRecordKey?: boolean;
+    }) => Promise<Pick<import("../../index.js").EncryptedEnvelope, "_iv" | "_data" | "_cek">>;
+    verifyRecordIdentity: (ref: import("./record-aad.js").RecordRef, env: import("../../index.js").EncryptedEnvelope, key: import("../contract.js").CapsuleKey) => Promise<boolean>;
+};
+/**
+ * `RecordCodec` as a TYPE is the module-level generic base class; as a VALUE
+ * it is the capsule-bound subclass `makeCapsule()` returns. Hub parameterises
+ * the type in six places, and an `InstanceType<…>` alias would have dropped
+ * `T` at every one of them without an error — see the note in
+ * `record-codec.ts`.
+ */
+export type { RecordCodecBase as RecordCodec } from './record-codec.js';
+export type Capsule = ReturnType<typeof makeCapsule>;

package/dist/capsule/plumbing/lifecycle.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Per-record CEK lifecycle helpers for the WRITE path.
+ *
+ * These are the collection-coupled CEK operations, lifted off `Collection`
+ * behind narrow deps so the kernel file delegates instead of carrying the
+ * crypto inline:
+ *
+ *   - {@link resolveStableCek} — the stable-CEK rule: an update or history
+ *     snapshot reuses the record's existing CEK so a single CEK delete kills
+ *     the whole version chain; a genuine insert (or legacy record being
+ *     migrated) mints a fresh one.
+ *   - {@link rewrapBodyToDek} — move a record body's wrapping from one DEK to
+ *     another (tier elevate/demote, bundle re-key) WITHOUT changing the body
+ *     key: unwrap the CEK under the source DEK, re-encrypt the body under the
+ *     same CEK, re-wrap the CEK under the destination DEK. History-chain
+ *     identity is preserved because the body key never changes.
+ *
+ * Both are pure functions over their deps — the `cekCache` ownership stays on
+ * the collection (its lifetime is tied to `load()`), so callers cache the
+ * returned key themselves.
+ */
+import type { EncryptedEnvelope } from '../../kernel/types.js';
+import { type RecordIdentity } from './record-aad.js';
+import type { Lru } from '../../kernel/cache/index.js';
+/** Dependencies {@link resolveStableCek} needs from its collection. */
+import type { CapsuleKey, CapsulePrimitives } from '../contract.js';
+export interface StableCekDeps {
+    /** The collection's per-record CEK cache (`null` → no caching). */
+    readonly cache: Lru<string, CapsuleKey> | null;
+    /** Read the record's live envelope (to recover an existing `_cek`). */
+    getLive(id: string): Promise<EncryptedEnvelope | null>;
+    /** The DEK the CEK is wrapped under (the collection DEK on the normal path). */
+    getDEK(): Promise<CapsuleKey>;
+}
+/** Re-wrapped body bytes + the (optional) CEK to cache. */
+export interface RewrappedBody {
+    readonly _iv: string;
+    readonly _data: string;
+    /** Present iff the source envelope carried a CEK (per-record-key record). */
+    readonly _cek?: string;
+    /** The body key when one exists, so the caller can cache it; `null` for a legacy record. */
+    readonly cek: CapsuleKey | null;
+}
+export declare function makeLifecycle(p: CapsulePrimitives): {
+    resolveStableCek: (deps: StableCekDeps, id: string) => Promise<CapsuleKey>;
+    rewrapBodyToDek: (from: RecordIdentity, to: RecordIdentity, envelope: Pick<EncryptedEnvelope, "_iv" | "_data" | "_cek" | "_tier" | "_by">, fromDek: CapsuleKey, toDek: CapsuleKey) => Promise<RewrappedBody>;
+    applyRewrappedBody: (envelope: EncryptedEnvelope, body: RewrappedBody) => EncryptedEnvelope;
+    rewrapEnvelope: (identity: RecordIdentity, envelope: EncryptedEnvelope, fromDek: CapsuleKey, toDek: CapsuleKey) => Promise<EncryptedEnvelope>;
+    isRewrappedUnder: (identity: RecordIdentity, envelope: Pick<EncryptedEnvelope, "_iv" | "_data" | "_cek">, dek: CapsuleKey) => Promise<boolean>;
+};