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

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>;
+};

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

@@ -16,24 +16,33 @@
  *
  * Internal service — not exported as a `@noy-db/hub/*` subpath.
  */
-import { type EnclaveKey } from '../crypto.js';
-import { type EncryptedEnvelope, type CrdtMode, type CrdtStrategy, type VdigFieldPolicy, type SealedHandle } from '../../types.js';
-import { type RecordIdentity, type RecordRef } from '../record-aad.js';
-import { type StandardSchemaV1 } from '../../schema.js';
-import type { Lru } from '../../cache/index.js';
-import type { ViaCryptoCtx } from '../../via/index.js';
-import type { ViaPipeline } from '../../via/pipeline.js';
+import { type EncryptedEnvelope, type CrdtMode, type CrdtStrategy, type VdigFieldPolicy, type SealedHandle } from '../../kernel/types.js';
+import { type RecordIdentity, type RecordRef } from './record-aad.js';
+import { type StandardSchemaV1 } from '../../kernel/schema.js';
+import type { Lru } from '../../kernel/cache/index.js';
+import type { ViaCryptoCtx } from '../../kernel/via/index.js';
+import type { ViaPipeline } from '../../kernel/via/pipeline.js';
 /**
- * One classified per-slot verdict from {@link RecordCodec.classifySealedShred}.
+ * One classified per-slot verdict from {@link RecordCodecBase.classifySealedShred}.
  * `shreddable` — CEK-only, tombstone makes it undecryptable. `dekResidue` —
  * collection-DEK-keyed, survives in synced/backup copies. The third class is
  * BOTH: a `_bidx` blind-index tag is live-dropped by the tombstone yet retained
  * under the surviving DEK in any pre-forget backup (honest dual accounting).
  */
+import type { CapsuleKey, CapsulePrimitives } from '../contract.js';
+import type { makeSealedSlots } from './sealed-slots.js';
 export type SealedShredSlot = {
     readonly field: string;
     readonly class: 'shreddable' | 'dekResidue' | 'live-shreddable+dekResidue-in-backups';
 };
+/**
+ * The record codec, bound to a capsule.
+ *
+ * ⚠️ `RecordCodec` is a CLASS declared inside this factory, so the NAME is no
+ * longer a module-level type. Hub names it in ~40 places as a type, which is
+ * why `plumbing/index.ts` re-exports an `InstanceType<…>` alias under the same
+ * name — the type keeps working unchanged for every existing consumer.
+ */
 /** Everything the moving crypto methods touched on `this.*`, as a flat context. */
 export interface RecordCodecContext<T> {
     /** Collection name — the crypto AAD scope and schema-error context. */
@@ -75,13 +84,13 @@ export interface RecordCodecContext<T> {
      * `_dict_status` collection) so a binding's at-rest hook can address a
      * different collection's DEK without ever holding the resolver itself.
      */
-    getDEK(collection?: string): Promise<EnclaveKey>;
+    getDEK(collection?: string): Promise<CapsuleKey>;
     /**
      * The collection's per-record CEK cache (SHARED reference, not a copy).
      * Ownership/lifetime stays on Collection; codec reads+writes it in
      * resolveEnvelopeCek exactly as the inline code did. `null` → no caching.
      */
-    readonly cekCache: Lru<string, EnclaveKey> | null;
+    readonly cekCache: Lru<string, CapsuleKey> | null;
     /**
      * Compiled Via pipeline (money, i18n, …), or undefined for a collection
      * with none declared. `encryptRecord`/`decryptRecord` consult
@@ -92,15 +101,45 @@ export interface RecordCodecContext<T> {
      *
      * Mutable (not `readonly`, #638 Task 3): `Collection.via` can be
      * reassigned post-construction (the taint overlay, `via/graph-wiring.ts#
-     * applyTaintOverlay`) — `RecordCodec.setVia` below keeps this in sync so
+     * applyTaintOverlay`) — `RecordCodecBase.setVia` below keeps this in sync so
      * at-rest hooks read the LIVE pipeline, not a stale construction-time
      * snapshot.
      */
     via: ViaPipeline | undefined;
+    /**
+     * Read-coverage observer (#1363), resolved once per Collection from
+     * `strategies.coverage.observer(...)`. `undefined` for every un-opted-in
+     * deployment AND for every collection the sensor does not account for, so
+     * the decrypt path costs one `!== undefined` test.
+     *
+     * ⛔⛔ TELEMETRY, NOT A CONTROL: an insider holding the device and local keys
+     * holds the DEK, so this observes an extraction it cannot prevent. It exists
+     * to make one visible early, attributable and loud. It may never grow a
+     * return value — a decrypt is not gated on it, and nothing here may refuse.
+     */
+    readonly onDecrypt?: ((id: string) => void) | undefined;
 }
-export declare class RecordCodec<T> {
+/**
+ * The codec's capsule-provided surface: the 15 primitives + sealed-slot helpers
+ * its methods call.
+ */
+export type CapsuleBinding = CapsulePrimitives & ReturnType<typeof makeSealedSlots>;
+/**
+ * ⚠️ MODULE-LEVEL AND GENERIC ON PURPOSE. The obvious shape — declaring the
+ * class inside `makeRecordCodec` and exporting `InstanceType<…>` — compiles and
+ * silently DROPS `T`: `RecordCodec<Invoice>` degrades to `RecordCodec<unknown>`
+ * at the six places hub parameterises it, turning typed records into `unknown`
+ * with no error anywhere.
+ *
+ * The other way to keep `T` would be a hand-written `interface RecordCodec<T>`
+ * that the class implements — i.e. a second declaration of 15 signatures that
+ * nothing checks against the first. That is exactly the drift #16 was, so it
+ * was not done twice. A base class has one declaration and cannot drift.
+ */
+export declare class RecordCodecBase<T> {
+    protected readonly caps: CapsuleBinding;
     private readonly ctx;
-    constructor(ctx: RecordCodecContext<T>);
+    constructor(caps: CapsuleBinding, ctx: RecordCodecContext<T>);
     /**
      * @internal Update the live Via pipeline this codec's at-rest hooks read
      * (#638 Task 3) — called by `via/graph-wiring.ts#applyTaintOverlay` right
@@ -183,7 +222,7 @@ export declare class RecordCodec<T> {
      * the choice must be made before AAD is switched on, not inferred from this
      * migration.
      */
-    encryptJsonString(ref: RecordRef, json: string, version: number, cek?: EnclaveKey, source?: string, sourceTs?: string): Promise<EncryptedEnvelope>;
+    encryptJsonString(ref: RecordRef, json: string, version: number, cek?: CapsuleKey, source?: string, sourceTs?: string): Promise<EncryptedEnvelope>;
     /**
      * `ref` is FIRST and required (#1051). It was previously a trailing optional
      * `id?: string`, which TypeScript cannot promote to required because it sits
@@ -195,7 +234,7 @@ export declare class RecordCodec<T> {
      * compile on the hottest write path. Carries the collection too — see
      * {@link encryptJsonString} for why the codec must not assume its own.
      */
-    encryptRecord(ref: RecordRef, record: T, version: number, cek?: EnclaveKey, source?: string, sourceTs?: string, vdig?: {
+    encryptRecord(ref: RecordRef, record: T, version: number, cek?: CapsuleKey, source?: string, sourceTs?: string, vdig?: {
         readonly id: string;
         readonly prev: EncryptedEnvelope | null;
     }): Promise<EncryptedEnvelope>;
@@ -207,7 +246,7 @@ export declare class RecordCodec<T> {
      * ({@link decryptJsonString}) and the sealed-field path ({@link decryptRecord}
      * / {@link toCacheRecord}) so both agree on the record's key.
      */
-    resolveEnvelopeCek(envelope: EncryptedEnvelope, id?: string): Promise<EnclaveKey | undefined>;
+    resolveEnvelopeCek(envelope: EncryptedEnvelope, id?: string): Promise<CapsuleKey | undefined>;
     /**
      * Low-level: decrypt an envelope and return the raw JSON string.
      *
@@ -230,6 +269,19 @@ export declare class RecordCodec<T> {
      * perfectly good record (#1041).
      */
     decryptJsonString(ref: RecordRef, envelope: EncryptedEnvelope): Promise<string | null>;
+    /**
+     * Fire the read-coverage observer for a successful record decrypt (#1363).
+     *
+     * ⚠️ ONLY for this codec's OWN collection. `ref.collection` can be a storage
+     * identity that is not the live collection — a history/version address, the
+     * `_vec` vector sidecar, the `_ft` lexical index (#1041) — and their ids are
+     * not this corpus's ids, so counting them would corrupt the very estimate
+     * the sensor exists to produce. The cost is a deliberate UNDER-count: a
+     * principal reading the corpus through its history sidecar is not accounted.
+     * A sensor that under-counts is honest; one that inflates cries wolf and
+     * gets turned off. Recorded rather than papered over.
+     */
+    private observeDecrypt;
     /**
      * Unseal a single `_sealed[field]` slot to its plaintext value: derive the
      * per-field key off the collection DEK, AES-GCM-decrypt the `iv:data` blob,
@@ -237,7 +289,7 @@ export declare class RecordCodec<T> {
      * {@link Sealed} handle's `reveal()` — so the on-demand reveal and the eager
      * materialisation always agree byte-for-byte.
      */
-    unsealField(field: string, blob: string, cek?: EnclaveKey): Promise<unknown>;
+    unsealField(field: string, blob: string, cek?: CapsuleKey): Promise<unknown>;
     /**
      * Build the `ViaCryptoCtx` for forget()'s per-ref via-erase fold (#629
      * Task 10) — resolves the live envelope's CEK exactly like
@@ -266,7 +318,7 @@ export declare class RecordCodec<T> {
      * may sit in the working-set cache (or be logged/serialised) without
      * exposing the value, which decrypts only on `reveal()`.
      */
-    makeSealedHandle(field: string, blob: string, cek?: EnclaveKey): SealedHandle<unknown>;
+    makeSealedHandle(field: string, blob: string, cek?: CapsuleKey): SealedHandle<unknown>;
     /**
      * Replace every field the just-written envelope actually sealed with a
      * {@link Sealed} handle, leaving every other field as its plaintext value.
@@ -308,7 +360,7 @@ export declare class RecordCodec<T> {
      * never a tier DEK (tier writes don't seal fields; `_sealed` reaches a
      * tiered envelope only via a tier-0 write later elevated).
      */
-    applySealedSlots(record: T, sealed: Record<string, string>, cek: EnclaveKey | undefined, opts?: {
+    applySealedSlots(record: T, sealed: Record<string, string>, cek: CapsuleKey | undefined, opts?: {
         id?: string;
         sealedAsHandles?: boolean;
     }): Promise<T>;
@@ -338,7 +390,7 @@ export declare class RecordCodec<T> {
      * output-recompute path, not the public per-record read surface schema
      * validation guards.
      */
-    decryptRecordAtDek(ref: RecordRef, envelope: EncryptedEnvelope, dek: EnclaveKey): Promise<T | null>;
+    decryptRecordAtDek(ref: RecordRef, envelope: EncryptedEnvelope, dek: CapsuleKey): Promise<T | null>;
     /**
      * Decrypt an envelope into a record of type `T`.
      *
@@ -359,3 +411,11 @@ export declare class RecordCodec<T> {
         sealedAsHandles?: boolean;
     }): Promise<T | null>;
 }
+/**
+ * The capsule-bound codec constructor: same shape callers have always used
+ * (`new RecordCodec(ctx)`), with the capsule already closed over.
+ */
+export type BoundRecordCodec = (new <T>(ctx: RecordCodecContext<T>) => RecordCodecBase<T>) & Omit<typeof RecordCodecBase, never>;
+export declare function makeRecordCodec(p: CapsulePrimitives, slots: ReturnType<typeof makeSealedSlots>): {
+    RecordCodec: BoundRecordCodec;
+};

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

@@ -1,4 +1,4 @@
-import type { EncryptedEnvelope } from '../types.js';
+import type { EncryptedEnvelope } from '../../kernel/types.js';
 import type { RecordIdentity } from './record-aad.js';
 /** The body an envelope carries, independent of who is writing it. */
 export interface RecordEnvelopeBody {

package/dist/capsule/plumbing/rekey-blob.d.ts

@@ -0,0 +1,33 @@
+import type { NoydbStore } from '../../kernel/types.js';
+/** Blob metadata envelopes, keyed by eTag. owner: with-shape/blobs/blob-set.ts */
+import type { CapsuleKey, CapsulePrimitives } from '../contract.js';
+/**
+ * What a rotation did to the blob set.
+ *
+ * Deliberately NOT on the enclave barrel: no caller outside this module binds
+ * it, and that surface is the fork-swap trust boundary, so exporting a type
+ * nobody consumes is pure widening.
+ *
+ * It is a return value rather than a log line because `foreign` and `blobs`
+ * are the only way to tell "left alone, correctly" from "left alone, because
+ * the caller passed a wrong `otherDeks` set". Both re-key nothing and both
+ * return successfully. `rotate-preserves-blobs.test.ts` asserts these counts
+ * against a direct call for exactly that reason.
+ */
+export interface BlobRekeyReport {
+    /** Index envelopes moved onto the new DEK. */
+    readonly blobs: number;
+    /** Chunk envelopes re-encrypted under the new DEK. */
+    readonly chunks: number;
+    /**
+     * Index envelopes left alone because they open under a DEK the caller holds
+     * for a DIFFERENT slot — an elevated blob, sealed under `_blob#<tier>`. Those
+     * are that slot's rotation to do, not this one's.
+     */
+    readonly foreign: number;
+    /** Index envelopes already under the new DEK — a resumed rotation. */
+    readonly alreadyMoved: number;
+}
+export declare function makeRekeyBlob(p: CapsulePrimitives): {
+    rekeyBlobSet: (adapter: NoydbStore, vault: string, oldDek: CapsuleKey, newDek: CapsuleKey, otherDeks?: readonly CapsuleKey[]) => Promise<BlobRekeyReport>;
+};