@noy-db/hub 0.3.0-pre.9 → 0.3.0

package/dist/kernel/enclave/crypto.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Cryptographic primitives — thin wrappers around the Web Crypto API.
+ *
+ * ## Design principle
+ *
+ * **Zero npm crypto dependencies.** Every operation uses `globalThis.crypto.subtle`,
+ * which is available natively in Node.js ≥ 18, all modern browsers, and
+ * Deno/Bun. This avoids supply-chain risk from third-party crypto packages and
+ * ensures the library stays auditable.
+ *
+ * ## Algorithms
+ *
+ * | Use case | Algorithm | Parameters |
+ * |----------|-----------|------------|
+ * | Key derivation | PBKDF2-SHA256 | 600,000 iterations, 32-byte salt |
+ * | Record encryption | AES-256-GCM | 12-byte random IV per operation |
+ * | DEK wrapping | AES-KW (RFC 3394) | 256-bit KEK |
+ * | Binary encrypt | AES-256-GCM | same as record encryption |
+ * | Integrity | HMAC-SHA256 | for presence channels |
+ * | Content hash | SHA-256 | for ledger and bundle integrity |
+ *
+ * ## Key lifecycle
+ *
+ * ```
+ * passphrase + salt
+ *   └─► deriveKey()       → KEK (CryptoKey, extractable: false)
+ *         └─► wrapKey()   → wrapped DEK bytes  [stored in keyring]
+ *         └─► unwrapKey() → DEK (CryptoKey)    [memory only during session]
+ *               └─► encrypt() / decrypt()       → ciphertext / plaintext
+ * ```
+ *
+ * IVs are generated fresh by {@link generateIV} on every encrypt call.
+ * Reusing an IV with the same key would break GCM's authentication guarantee —
+ * this function should be the only place IVs are produced.
+ *
+ * @module
+ */
+/**
+ * **EnclaveKey** — the opaque key type at the enclave seam.
+ *
+ * In noy-db's reference enclave this is `CryptoKey` (the Web Crypto API's
+ * key handle). A fork's enclave redefines this alias to its own key
+ * representation (e.g. `type EnclaveKey = null` for a keyless HSM-backed
+ * fork) — outside `kernel/enclave/**`, every consumer must treat it as
+ * opaque: never construct, inspect, or serialize it directly, only pass it
+ * between barrel functions (`encrypt`/`decrypt`/`wrapKey`/`unwrapKey`/…).
+ */
+export type EnclaveKey = CryptoKey;
+/** Derive a KEK from a passphrase and salt using PBKDF2-SHA256. */
+export declare function deriveKey(passphrase: string, salt: Uint8Array): Promise<CryptoKey>;
+/**
+ * Which AES algorithm/usage a {@link derivePassphraseKey} result is for:
+ * `'aes-kw'` mints a key-wrapping key (`wrapKey`/`unwrapKey`, e.g. for
+ * KEK derivation); `'aes-gcm'` mints a direct encrypt/decrypt key (e.g.
+ * for the wrap-DEKs primitive in `with-party/team/wrapped-deks.ts`).
+ */
+export type PassphraseKeyUsage = 'aes-kw' | 'aes-gcm';
+/**
+ * Derive a non-extractable AES key from a passphrase/credential and salt
+ * via PBKDF2-SHA256, generalizing {@link deriveKey}'s AES-KW derivation to
+ * also cover AES-GCM-usage keys. Callers pin their own `iterations` and
+ * `keyUsage` so an existing call site's exact parameters (and thus its
+ * derived-key bytes) are preserved verbatim when migrated onto this
+ * shared primitive — this is call-site consolidation, not a KDF change.
+ */
+export declare function derivePassphraseKey(passphrase: string, salt: Uint8Array, params: {
+    iterations: number;
+    keyUsage: PassphraseKeyUsage;
+}): Promise<CryptoKey>;
+/** Generate a random AES-256-GCM data encryption key. */
+export declare function generateDEK(): Promise<CryptoKey>;
+/** Wrap (encrypt) a DEK with a KEK using AES-KW. Returns base64 string. */
+export declare function wrapKey(dek: CryptoKey, kek: CryptoKey): Promise<string>;
+/** Unwrap (decrypt) a DEK from base64 string using a KEK. */
+export declare function unwrapKey(wrappedBase64: string, kek: CryptoKey): Promise<CryptoKey>;
+/**
+ * AES-KW-wrap a per-record CEK under a collection/tier DEK. Returns base64.
+ * Deterministic over `(cek, dek)`.
+ */
+export declare function wrapCek(cek: CryptoKey, dek: CryptoKey): Promise<string>;
+/**
+ * Unwrap a per-record CEK from base64 under a collection/tier DEK. Throws
+ * `InvalidKeyError` if the wrapped bytes do not authenticate under the DEK.
+ */
+export declare function unwrapCek(wrappedBase64: string, dek: CryptoKey): Promise<CryptoKey>;
+/**
+ * Import a raw 32-byte AES-256-GCM record CEK (e.g. from a sealed-CEK
+ * delivery binding). Non-extractable, decrypt-only — the imported key is
+ * used solely to open the record's `_iv`/`_data` body under `decrypt()`.
+ */
+export declare function importCek(rawKey: Uint8Array): Promise<CryptoKey>;
+export interface EncryptResult {
+    iv: string;
+    data: string;
+}
+/** Encrypt plaintext JSON string with AES-256-GCM. Fresh IV per call. */
+export declare function encrypt(plaintext: string, dek: CryptoKey): Promise<EncryptResult>;
+/** Decrypt AES-256-GCM ciphertext. Throws on wrong key or tampered data. */
+export declare function decrypt(ivBase64: string, dataBase64: string, dek: CryptoKey): Promise<string>;
+/**
+ * Encrypt raw bytes with AES-256-GCM using a fresh random IV.
+ * Used by the attachment store so binary blobs avoid double base64 encoding
+ * (the existing `encrypt()` function calls `TextEncoder` on a string — here
+ * we pass the `Uint8Array` directly to `subtle.encrypt`).
+ */
+export declare function encryptBytes(data: Uint8Array, dek: CryptoKey): Promise<EncryptResult>;
+/**
+ * Decrypt AES-256-GCM ciphertext back to raw bytes.
+ * Counterpart to `encryptBytes`. Throws `TamperedError` on auth-tag failure.
+ */
+export declare function decryptBytes(ivBase64: string, dataBase64: string, dek: CryptoKey): Promise<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>;
+/**
+ * Compute HMAC-SHA-256(key, data) and return hex string.
+ *
+ * Used to derive content-addressed eTags that are opaque to the store:
+ * ```
+ * eTag = hmacSha256Hex(blobDEK, plaintext)
+ * ```
+ *
+ * Unlike a plain SHA-256, the HMAC is keyed by the vault-shared `_blob` DEK,
+ * so an attacker with store access cannot pre-compute eTags for known files.
+ * Deduplication still works within a vault (same key + same content = same eTag).
+ */
+export declare function hmacSha256Hex(key: CryptoKey, data: Uint8Array): Promise<string>;
+/**
+ * Encrypt raw bytes with AES-256-GCM using Additional Authenticated Data.
+ *
+ * The AAD binds each chunk to its parent blob and position, preventing
+ * chunk reorder, substitution, and truncation attacks:
+ * ```
+ * AAD = UTF-8("{eTag}:{chunkIndex}:{chunkCount}")
+ * ```
+ *
+ * The AAD is NOT stored — the reader reconstructs it from `BlobObject`
+ * metadata and passes it to `decryptBytesWithAAD`.
+ */
+export declare function encryptBytesWithAAD(data: Uint8Array, dek: CryptoKey, aad: Uint8Array): Promise<EncryptResult>;
+/**
+ * Decrypt AES-256-GCM ciphertext with AAD verification.
+ *
+ * If the AAD does not match the one used at encryption time (e.g. because
+ * a chunk was reordered or substituted from another blob), the GCM auth
+ * tag fails and this throws `TamperedError`.
+ */
+export declare function decryptBytesWithAAD(ivBase64: string, dataBase64: string, dek: CryptoKey, aad: Uint8Array): Promise<Uint8Array>;
+/**
+ * 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 a **per-field** AES-256-GCM key from a collection DEK using
+ * HKDF-SHA256, used to encrypt a single sensitive field into its own
+ * `_sealed[field]` envelope slot (structural group-encryption).
+ *
+ * Domain-separated from the data DEK (and from the presence/deterministic
+ * channels) by the fixed salt `'noydb-sealed'` and an `info` of
+ * `JSON.stringify(['noydb-sealed', collectionName, field])`. The JSON-array
+ * encoding is injective — each element is separately quoted/escaped — so
+ * collection `a/sealed/b` + field `c` cannot collide with collection `a` +
+ * field `b/sealed/c`. Each sensitive field gets a **distinct** key, so a
+ * `_sealed[a]` ciphertext does not authenticate under field `b`'s key —
+ * sealed fields are cryptographically isolated from one another. The
+ * collection name keeps the same field name in two collections from sharing a
+ * key, mirroring how `derivePresenceKey` / `encryptDeterministic` domain-separate.
+ *
+ * @param dek            The collection's AES-256-GCM DEK (extractable).
+ * @param collectionName Part of the HKDF `info` for domain separation.
+ * @param field          Sensitive field name — the rest of the `info`.
+ * @returns A non-extractable AES-256-GCM key for that field's sealed slot.
+ */
+export declare function deriveSealedFieldKey(dek: CryptoKey, collectionName: string, field: string): Promise<CryptoKey>;
+/**
+ * Derive a per-record sealed-field key from the record's **per-record CEK**
+ * rather than the collection DEK. Same HKDF construction as
+ * {@link deriveSealedFieldKey} but with salt `'noydb-sealed-cek'` (distinct
+ * from `'noydb-sealed'`), so a CEK-derived key can never collide with a
+ * DEK-derived one for the same `{collection, field}`.
+ *
+ * The point: the sealed ciphertext's only key now flows from the record's CEK.
+ * Dropping the record's wrapped `_cek` (crypto-shred / `forget`) makes the key
+ * — and thus `_sealed[field]` — unrecoverable, giving sealed fields the same
+ * erasure guarantee `_data` already has. The CEK must be extractable (it is —
+ * `unwrapCek`/`generateDEK` mint extractable keys).
+ *
+ * @param cek            The record's AES-256-GCM CEK (extractable).
+ * @param collectionName Part of the HKDF `info` for domain separation.
+ * @param field          Sensitive field name — the rest of the `info`.
+ * @returns A non-extractable AES-256-GCM key for that field's sealed slot.
+ */
+export declare function deriveSealedFieldKeyFromCek(cek: CryptoKey, collectionName: string, field: string): Promise<CryptoKey>;
+/**
+ * Derive the collection's **dedicated deterministic-index key** from its DEK
+ * via HKDF-SHA256 (L-1, #554).
+ *
+ * `_det` slots previously encrypted under the raw collection DEK — the same
+ * key `_data` uses with a *randomized*-IV regime while `_det` uses a
+ * *deterministic*-IV regime. Two IV regimes on one key is avoidable hygiene
+ * debt (~2^-96 theoretical collision), so the deterministic index now gets its
+ * own HKDF-separated key: salt `'noydb-det'`, info
+ * `JSON.stringify(['noydb-det'])` (the injective JSON-array domain tag, same
+ * convention as {@link deriveSealedFieldKey}). Per-field separation still
+ * comes from the `'<collection>/<field>'` context inside
+ * {@link encryptDeterministic}, exactly as before.
+ *
+ * The derived key stays **DEK-derived (collection-level)** on purpose: `_det`
+ * is carried verbatim through per-record CEK rotation (see
+ * `record-keys/sealing.ts`), so its key must not depend on the CEK. It rotates
+ * with the collection DEK, like the presence key.
+ *
+ * The key is minted **extractable** — {@link encryptDeterministic} derives its
+ * per-value IV via HKDF over the raw key bytes (an `exportKey` under the
+ * hood), which a non-extractable key would forbid. Same in-memory posture as
+ * the DEK itself (`generateDEK` mints extractable keys).
+ *
+ * @param dek The collection's AES-256-GCM DEK (extractable).
+ * @returns A dedicated AES-256-GCM key for the `_det` deterministic index.
+ */
+export declare function deriveDeterministicKey(dek: CryptoKey): Promise<CryptoKey>;
+/**
+ * Encrypt a plaintext string with AES-256-GCM and a deterministic,
+ * HKDF-derived IV.
+ *
+ * The same `{ dek, context, plaintext }` triple always produces the
+ * same `{ iv, data }` — call this twice and you can string-compare the
+ * ciphertexts to check equality of the inputs without decrypting them.
+ *
+ * @param context  Domain-separation string — by convention
+ *                 `'<collection>/<field>'`. Different contexts encrypt
+ *                 the same plaintext to different ciphertexts, so
+ *                 `email` in collection `users` does not collide with
+ *                 `email` in collection `customers`.
+ */
+export declare function encryptDeterministic(plaintext: string, dek: CryptoKey, context: string): Promise<EncryptResult>;
+/**
+ * Counterpart to {@link encryptDeterministic}. The IV is stored
+ * alongside the ciphertext (exactly like the randomized path), so
+ * decrypt uses the stored IV and verifies the GCM auth tag — a tampered
+ * ciphertext throws `TamperedError` just like randomized AES-GCM.
+ */
+export declare function decryptDeterministic(ivBase64: string, dataBase64: string, dek: CryptoKey): Promise<string>;
+/** 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;
+export declare function bufferToBase64(buffer: ArrayBuffer | Uint8Array): string;
+export declare function base64ToBuffer(base64: string): Uint8Array<ArrayBuffer>;

package/dist/kernel/enclave/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * **kernel/enclave** — the hub's crypto interior, behind one door.
+ *
+ * This barrel is **the fork-swap contract**: a sister project that wants a
+ * different crypto engine (a different KDF, a hardware-backed keystore, a
+ * post-quantum wrap algorithm, …) replaces the entire `kernel/enclave/`
+ * folder wholesale and only has to honor the exports below. Nothing outside
+ * `kernel/enclave/**` may deep-import `crypto.js` or `record-keys/*` directly
+ * — `scripts/check-architecture.mjs`'s `enclave-barrel-only` check enforces
+ * that mechanically. Import sites inside `kernel/enclave/**` keep their
+ * existing relative imports; this door is for everyone else.
+ *
+ * The export list is the OBSERVED contract — exactly the symbols consumed
+ * from outside this folder today — grouped by the module that defines them:
+ *
+ *   - key type       — `crypto.ts`: `EnclaveKey`, the opaque key type every
+ *                       barrel-facing signature traffics in (`= CryptoKey` in
+ *                       noy-db's reference enclave; a fork redefines it to its
+ *                       own key representation — see the type's own doc for
+ *                       the fork contract).
+ *   - crypto ops     — `crypto.ts`: AES-256-GCM encrypt/decrypt (+ bytes, AAD,
+ *                       deterministic variants), SHA-256 / HMAC-SHA-256 hashing.
+ *   - key lifecycle  — `crypto.ts` + `record-keys/lifecycle.ts`: KEK/DEK
+ *                       derivation, AES-KW wrap/unwrap, per-record CEK
+ *                       wrap/unwrap/import + resolution/re-wrap, HKDF-derived
+ *                       presence/sealed-field keys, base64 helpers.
+ *   - record codec   — `record-keys/record-codec.ts`: the per-record
+ *                       encode/decode engine.
+ *   - sealing        — `record-keys/sealing.ts`: the sealed-record grantor
+ *                       primitives (seal/revoke/rotate to an `at-*` host).
+ *   - deterministic  — `record-keys/deterministic.ts`: blind-equality lookup
+ *                       over deterministically-encrypted fields.
+ *   - tombstone      — `record-keys/tombstone.ts`: the erased-record residue.
+ *   - envelope body  — `record-keys/envelope-body.ts`: the C1 protected-body
+ *                       access contract (`openEnvelopeJson`,
+ *                       `writeEnvelopeBody`, `hasPerRecordKey`,
+ *                       `envelopeBodyForHash`) — the sanctioned door onto
+ *                       `_iv`/`_data`/`_cek`/`_sealed` for everyone outside
+ *                       this folder.
+ *   - reserved envelopes — `record-keys/sealed-slots.ts`: `makeReservedEnvelopes`,
+ *                       the whole-envelope encrypt/decrypt door scoped to a
+ *                       declared collection-name prefix (e.g. `_dict_`) —
+ *                       `kernel/vault.ts` binds it for `DictionaryHandle`
+ *                       (#629 Task 4).
+ *
+ * Additive changes only — removing or renaming an export here is breaking
+ * for any fork. Frozen by `__tests__/enclave-surface-golden.test.ts`.
+ *
+ * **Refusal contract:** the barrel above is frozen — every symbol must
+ * exist in any fork — but the optional groups (sealing, deterministic,
+ * per-record-key lifecycle) MAY throw `EnclaveNotSupportedError` instead
+ * of implementing the reference behavior. The core groups (crypto ops,
+ * record codec, tombstone) MUST NOT throw it — they are load-bearing for
+ * every consumer regardless of which enclave is wired in. noy-db's own
+ * enclave supports every group, so it never throws this error.
+ */
+export type { EnclaveKey } from './crypto.js';
+export { encrypt, decrypt, encryptBytes, decryptBytes, encryptBytesWithAAD, decryptBytesWithAAD, encryptDeterministic, decryptDeterministic, sha256Hex, hmacSha256Hex, } from './crypto.js';
+export { deriveKey, derivePassphraseKey, generateDEK, generateSalt, generateIV, wrapKey, unwrapKey, bufferToBase64, base64ToBuffer, derivePresenceKey, deriveDeterministicKey, deriveSealedFieldKey, deriveSealedFieldKeyFromCek, wrapCek, unwrapCek, importCek, } from './crypto.js';
+export type { PassphraseKeyUsage } from './crypto.js';
+export { resolveStableCek, rewrapBodyToDek, rewrapEnvelope, applyRewrappedBody, isRewrappedUnder } from './record-keys/lifecycle.js';
+export type { RewrappedBody } from './record-keys/lifecycle.js';
+export { RecordCodec } from './record-keys/record-codec.js';
+export type { SealedShredSlot } from './record-keys/record-codec.js';
+export { SEALED_CEK_NS, sealRecordToHost, revokeSealedRecord, rotateRecordCek } from './record-keys/sealing.js';
+export type { SealingContext } from './record-keys/sealing.js';
+export { findByDet, queryByDet } from './record-keys/deterministic.js';
+export type { DeterministicContext } from './record-keys/deterministic.js';
+export { isTombstone, isTombstoneShape, buildTombstone, isDeleteMarker, buildDeleteMarker } from './record-keys/tombstone.js';
+export { openEnvelopeJson, writeEnvelopeBody, hasPerRecordKey, envelopeBodyForHash } from './record-keys/envelope-body.js';
+export { makeReservedEnvelopes } from './record-keys/sealed-slots.js';
+export { deriveVdigSlotKey } from './classify/vdig.js';
+export { pbkdf2VerifyDigest } from './classify/digest.js';
+export { ctEqualTags } from './classify/compare.js';
+export { evaluateKofN } from './classify/kofn.js';
+export { deriveClassifyIndexKey, deriveClassifyIndexSalt, mintBidxTag } from './classify/bidx.js';
+export { computeBidxTarget } from './classify/find.js';
+export { deriveBrokerProofBits, deriveBrokerProofKey, computeBrokerProof, issueChallenge, verifyBrokerProof, } from './broker/proof.js';
+export type { BrokerProofCanonicalParts, VerifyBrokerProofArgs, IssuedChallenge } from './broker/proof.js';

package/dist/kernel/enclave/record-keys/deterministic.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Deterministic-index lookups (`findByDet` / `queryByDet`).
+ *
+ * A collection that declares `deterministicFields` stamps a deterministic
+ * AES-GCM ciphertext for each such field on the envelope's `_det` slot at write
+ * time (the encrypt side lives in {@link RecordCodec.encryptRecord}). These
+ * helpers are the READ side: recompute the deterministic ciphertext for a query
+ * value and scan the adapter for envelopes whose `_det[field]` matches — no
+ * record bodies are decrypted during the scan, which is the whole point of a
+ * deterministic index.
+ *
+ * Both functions take a small {@link DeterministicContext} (the exact `this.*`
+ * the moving methods touched) instead of `this`, mirroring the `record-keys/`
+ * siblings. Behaviour is byte-identical to the inline code they replaced.
+ * Elevated records (_tier > 0) are skipped: invisible to tier-0 scans (#691).
+ *
+ * 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';
+/** Everything the moving deterministic-index methods touched on `this.*`. */
+export interface DeterministicContext<T> {
+    /** Collection name — the deterministic-encryption AAD scope. */
+    readonly name: string;
+    /** Vault namespace the records live under. */
+    readonly vault: string;
+    /** The ciphertext store (scanned envelope-by-envelope). */
+    readonly adapter: NoydbStore;
+    /** Declared deterministic-index fields, or null when the feature is off. */
+    readonly deterministicFields: ReadonlySet<string> | null;
+    /** False on plaintext collections — det lookups are encrypted-only. */
+    readonly storeCiphertext: boolean;
+    /** The collection DEK resolver. */
+    getDEK(): Promise<EnclaveKey>;
+    /** 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[]>;

package/dist/kernel/enclave/record-keys/envelope-body.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Enclave body helpers — the C1 protected-body access contract.
+ *
+ * `EncryptedEnvelope` splits into a protocol header (family-owned; `_noydb`,
+ * `_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 —
+ * later migration batches move the ~121 direct `_iv`/`_data`/`_cek`/`_sealed`
+ * access sites in `with-*` services onto these.
+ *
+ * Each helper reproduces an EXISTING behavior byte-for-byte (see the
+ * 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 EnclaveKey } from '../crypto.js';
+import type { EncryptedEnvelope } from '../../types.js';
+/**
+ * Open an envelope's protected body to its JSON text.
+ *
+ * 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`.
+ */
+export declare function openEnvelopeJson(env: EncryptedEnvelope, key: EnclaveKey, opts?: {
+    encrypted?: boolean;
+}): Promise<string>;
+/**
+ * Produce the protected-body fields (`_iv`/`_data`/`_cek`) for an envelope a
+ * caller is assembling.
+ *
+ *  - `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`.
+ */
+export declare function writeEnvelopeBody(json: string, key: EnclaveKey, opts?: {
+    encrypted?: boolean;
+    perRecordKey?: boolean;
+}): Promise<Pick<EncryptedEnvelope, '_iv' | '_data' | '_cek'>>;
+/**
+ * Discriminant: does this envelope carry a per-record key?
+ *
+ * Replaces raw `envelope._cek !== undefined` checks scattered across
+ * services — `_cek` presence is the format discriminant (see
+ * `record-codec.ts`'s `resolveEnvelopeCek` doc).
+ */
+export declare function hasPerRecordKey(env: EncryptedEnvelope): boolean;
+/**
+ * Canonical body string for the ledger hash chain — the exact bytes
+ * `with-commit/history/ledger/hash.ts`'s `envelopePayloadHash` derives from
+ * `_data` + `_sealed` + `_vdig` + `_bidx` before hashing:
+ *  - no `_sealed`, no `_vdig`, no `_bidx` → `_data` alone (back-compat: every
+ *    pre-existing ledger entry and non-sealed backup hashes byte-identically).
+ *  - any map present → canonical JSON of `{ _data, _sealed?, _vdig?, _bidx? }`
+ *    with sorted keys at every level, each map bound ONLY when present, so
+ *    the result is independent of the maps' field-insertion / store-
+ *    serialization order. `_bidx` is always the LAST segment, so a legacy
+ *    `_vdig`-only / `_bidx`-absent envelope hashes byte-identically to its
+ *    stage-2 value.
+ *
+ * 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),
+ * 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
+ * `envelope-body.test.ts`).
+ */
+export declare function envelopeBodyForHash(env: EncryptedEnvelope): string;

package/dist/kernel/enclave/record-keys/lifecycle.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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 EnclaveKey } from '../crypto.js';
+import type { EncryptedEnvelope } from '../../types.js';
+import type { Lru } from '../../cache/index.js';
+/** Dependencies {@link resolveStableCek} needs from its collection. */
+export interface StableCekDeps {
+    /** The collection's per-record CEK cache (`null` → no caching). */
+    readonly cache: Lru<string, EnclaveKey> | 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<EnclaveKey>;
+}
+/**
+ * Resolve the stable CEK for a record on the write path. Caches the resolved
+ * key under `id` so an update + its history snapshot share one CEK.
+ */
+export declare function resolveStableCek(deps: StableCekDeps, id: string): Promise<EnclaveKey>;
+/** 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: EnclaveKey | null;
+}
+/**
+ * Move a record body from `fromDek` to `toDek`.
+ *
+ * - Per-record-key record (`_cek` present): unwrap the CEK under `fromDek`,
+ *   re-encrypt the body under the SAME CEK, re-wrap the CEK under `toDek`. The
+ *   body key is unchanged → history-chain identity preserved.
+ * - Legacy record (no `_cek`): decrypt under `fromDek`, re-encrypt under `toDek`
+ *   directly — byte-for-byte the pre-CEK behaviour.
+ */
+export declare function rewrapBodyToDek(envelope: Pick<EncryptedEnvelope, '_iv' | '_data' | '_cek'>, fromDek: EnclaveKey, toDek: EnclaveKey): Promise<RewrappedBody>;
+/**
+ * Merge an ALREADY-rewrapped {@link RewrappedBody} into `envelope`, keeping
+ * every field but the re-keyed body (`_iv`/`_data`/`_cek`) unchanged.
+ *
+ * Body-field access (`_iv`/`_data`/`_cek`) is sanctioned inside the enclave;
+ * this lets callers outside it get back a ready-to-store envelope without
+ * reading those fields themselves. Takes a body the caller has ALREADY
+ * computed (vs. {@link rewrapEnvelope}, which also runs `rewrapBodyToDek`)
+ * so a caller building a SECOND envelope from the same rewrap — a tier
+ * move's live write AND its pre-move `_history` snapshot, #728 — pays the
+ * unwrap/decrypt/encrypt/wrap crypto once, not twice.
+ */
+export declare function applyRewrappedBody(envelope: EncryptedEnvelope, body: RewrappedBody): EncryptedEnvelope;
+/**
+ * Move a FULL stored envelope from `fromDek` to `toDek`, preserving every
+ * field other than the re-keyed body (`_iv`/`_data`/`_cek`) unchanged.
+ * Mirrors the spread-merge idiom `with-audit/tiers/index.ts`'s
+ * `elevate()`/`demote()` use to apply `rewrapBodyToDek`'s result to the live
+ * envelope, generalized to any envelope shape (history callers don't bump
+ * `_v`/`_ts`/`_tier` the way a tier move does).
+ */
+export declare function rewrapEnvelope(envelope: EncryptedEnvelope, fromDek: EnclaveKey, toDek: EnclaveKey): Promise<EncryptedEnvelope>;
+/**
+ * Is `envelope` ALREADY wrapped under `dek` (a per-record CEK wrapped under
+ * `dek`, or — legacy, no `_cek` — the body itself decryptable under `dek`)?
+ *
+ * A toDek-first idempotency check for retry-safe rewrap loops (#712 crash
+ * atomicity, `with-commit/history/history.ts`'s `rewrapHistory`): a crash
+ * mid-rewrap can strand some entries already moved to `toDek` while others
+ * remain under `fromDek`. Calling this with `toDek` before attempting the
+ * `fromDek` rewrap lets the caller skip an already-migrated entry instead of
+ * re-wrapping it (a re-wrap would be a correctness no-op but doubles as an
+ * unnecessary write) — and, more importantly, tells a retry loop that this
+ * entry needs no `fromDek` unwrap attempt at all, so a crash that landed some
+ * entries under `toDek` doesn't wedge on those already-moved entries.
+ *
+ * AES-KW (CEK unwrap) and AES-GCM (direct decrypt) are both authenticated —
+ * unwrap/decrypt under the wrong key throws, never silently returns garbage
+ * — so a caught error here reliably means "not wrapped under `dek`", not a
+ * corrupt envelope (a genuinely corrupt envelope also throws under the
+ * correct key, but callers that reach this helper only do so as a
+ * best-effort probe before their own decisive fromDek attempt, which still
+ * surfaces real corruption).
+ *
+ * Body-field access (`_iv`/`_data`/`_cek`) is sanctioned inside the enclave —
+ * this is the sanctioned door so callers outside it (history.ts) never read
+ * those fields themselves, preserving the check-architecture body-access
+ * ratchet.
+ */
+export declare function isRewrappedUnder(envelope: Pick<EncryptedEnvelope, '_iv' | '_data' | '_cek'>, dek: EnclaveKey): Promise<boolean>;