@noy-db/hub 0.3.0-pre.10 → 0.3.0-pre.11

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

@@ -0,0 +1,301 @@
+/**
+ * RecordCodec — the per-record envelope build + encrypt/decrypt + per-record-CEK
+ * + sealed-field crypto.
+ *
+ * `Collection` holds one `RecordCodec` instance and delegates the crypto write
+ * path (`encryptRecord` / `encryptJsonString` / `buildDebugEnvelope`), the read
+ * path (`decryptRecord` / `decryptJsonString` / `resolveEnvelopeCek`), and the
+ * sealed-field helpers (`unsealField` / `makeSealedHandle` / `toCacheRecord` /
+ * `classifySealedShred`) to it. The codec receives every `this.*` dependency
+ * it needs via {@link RecordCodecContext}.
+ *
+ * The crux is `cekCache`: it is the SAME `Lru` reference `Collection` owns (not
+ * a copy). `resolveEnvelopeCek` reads/writes it, and tier methods +
+ * `vault.invalidateRecordCaches` keep mutating that same object — a copy would
+ * silently break the "single CEK delete kills the version chain" invariant.
+ *
+ * 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 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';
+/**
+ * One classified per-slot verdict from {@link RecordCodec.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).
+ */
+export type SealedShredSlot = {
+    readonly field: string;
+    readonly class: 'shreddable' | 'dekResidue' | 'live-shreddable+dekResidue-in-backups';
+};
+/** 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. */
+    readonly name: string;
+    /** Actor id stamped on `_by` (the collection's keyring.userId). */
+    readonly actor: string;
+    /** False on plaintext collections — selects the no-ciphertext envelope branch. */
+    readonly storeCiphertext: boolean;
+    /** keyring.debugPlaintext — debug-inline envelope on user collections. */
+    readonly debugPlaintext: boolean;
+    /** Emit `_source`/`_sourceTs` provenance fields when a source is supplied. */
+    readonly provenance: boolean;
+    /** Declared `sensitive` fields → sealed into `_sealed[field]`. */
+    readonly sensitiveFields: ReadonlySet<string>;
+    /** Declared deterministic-index fields, or null. */
+    readonly deterministicFields: ReadonlySet<string> | null;
+    /** Digest-only classified fields → verify policy (stage 2). Null when none. */
+    readonly vdigFields: ReadonlyMap<string, VdigFieldPolicy> | null;
+    /**
+     * C-A / R10 config-drift signal: the persisted `x-classified` marker's
+     * declared digest-only field set (empty when the collection carries no
+     * marker). Lazy, memoized (O(1) per handle after the first call). The R10
+     * superset guard refuses whenever a field in this set is absent from
+     * `vdigFields`. Consulted once per handle on any encrypted write path — the
+     * cross-session, prev-free signal a fully-naive create has no `prev` for.
+     * Undefined on codecs with no store access (direct-construction tests).
+     */
+    classifiedMarkerDigestOnly?(): Promise<readonly string[]>;
+    /** CRDT mode (decrypt resolves CrdtState→snapshot when set). */
+    readonly crdtMode: CrdtMode | undefined;
+    /** CRDT strategy seam (resolveCrdtSnapshot). */
+    readonly crdtStrategy: CrdtStrategy;
+    /** Output-schema validator, or undefined. */
+    readonly schema: StandardSchemaV1<unknown, T> | undefined;
+    /**
+     * Resolve a collection's DEK. Called with no argument for `this.name`'s
+     * own DEK (every ordinary codec use); `viaCryptoCtx`'s `reservedEnvelopes`
+     * door passes an explicit OTHER collection name (e.g. a reserved
+     * `_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>;
+    /**
+     * 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;
+    /**
+     * Compiled Via pipeline (money, i18n, …), or undefined for a collection
+     * with none declared. `encryptRecord`/`decryptRecord` consult
+     * `via?.hasAtRestHooks` at the sealed-slot sub-step to choose between a
+     * binding's `encodeAtRest`/`decodeAtRest` hooks and today's inline path.
+     * The zero-via fast path (`via` undefined, or no binding declares an
+     * at-rest hook) stays byte/behavior-identical (#629 Task 3).
+     *
+     * 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
+     * at-rest hooks read the LIVE pipeline, not a stale construction-time
+     * snapshot.
+     */
+    via: ViaPipeline | undefined;
+}
+export declare class RecordCodec<T> {
+    private readonly ctx;
+    constructor(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
+     * after it reassigns `Collection.via`, so `hasAtRestHooks`/`encodeAtRest`/
+     * `decodeAtRest` see the newly-added `taint` binding instead of the
+     * pipeline snapshot captured when this codec was constructed.
+     */
+    setVia(via: ViaPipeline | undefined): void;
+    /** Sealed-slot key material for this codec's collection, for a given per-record CEK (or none). */
+    private sealKeyMaterial;
+    /**
+     * Build the `ViaCryptoCtx` handed to a binding's `encodeAtRest`/
+     * `decodeAtRest` hook: `sealedSlots` pre-bound to `(this.ctx.name,
+     * recordId)` — always threading `cek` when the caller has one, so the
+     * capability's record-binding stays cryptographic rather than degrading
+     * to collection-scope. `reservedEnvelopes`'s DEK resolver forwards its
+     * `collection` argument straight to `this.ctx.getDEK` (#629 Task 4) — it
+     * resolves the RESERVED collection's own DEK (e.g. `_dict_status`), never
+     * `this.ctx.name`'s, matching `Vault.getDEK`'s per-collection-name
+     * resolution (the same resolver `DictionaryHandle` used pre-cutover).
+     */
+    private viaCryptoCtx;
+    /**
+     * Assemble a canonical ciphertext body envelope literal from already-computed
+     * parts. Pure, no crypto. Each call stamps its own `_ts` — provenance carries
+     * a SEPARATE timestamp (computed by the caller), so the two never share one.
+     */
+    static buildEnvelope(p: {
+        version: number;
+        iv: string;
+        data: string;
+        by?: string;
+        cek?: string;
+        provenance?: {
+            source: string;
+            sourceTs: string;
+        } | undefined;
+        extra?: Partial<Pick<EncryptedEnvelope, '_tier' | '_det' | '_sealed'>>;
+    }): EncryptedEnvelope;
+    /** Plaintext (`_iv:''`) body envelope — the `!storeCiphertext` shape. */
+    static buildPlaintextEnvelope(p: {
+        version: number;
+        data: string;
+        by?: string;
+        provenance?: {
+            source: string;
+            sourceTs: string;
+        } | undefined;
+    }): EncryptedEnvelope;
+    /**
+     * Build a debug-plaintext envelope: the record's own fields inlined as
+     * top-level keys beside the reserved `_`-metadata, with `_debug: 1` and an
+     * empty `_data`. Lets native store tooling read the record without
+     * unwrapping. Only reached for user collections under `debugPlaintext`
+     * (see {@link encryptRecord}). Rejects `_`-prefixed record fields, which
+     * would collide with the reserved metadata namespace.
+     */
+    buildDebugEnvelope(record: T, version: number, source?: string, sourceTs?: string): EncryptedEnvelope;
+    /**
+     * Encrypt a JSON body into an envelope.
+     *
+     * When `cek` is supplied (per-record CEK collections), the body is
+     * encrypted under the CEK and the CEK is AES-KW-wrapped under the
+     * collection DEK and stamped on `_cek`. When `cek` is omitted, the legacy
+     * path encrypts the body directly under the collection DEK — byte-identical
+     * to pre-CEK behaviour, so non-adopting collections pay nothing.
+     */
+    encryptJsonString(json: string, version: number, cek?: EnclaveKey, source?: string, sourceTs?: string): Promise<EncryptedEnvelope>;
+    encryptRecord(record: T, version: number, cek?: EnclaveKey, source?: string, sourceTs?: string, vdig?: {
+        readonly id: string;
+        readonly prev: EncryptedEnvelope | null;
+    }, id?: string): Promise<EncryptedEnvelope>;
+    /**
+     * Resolve the per-record CEK for a stored envelope, or `undefined` for a
+     * legacy (`_cek`-absent) envelope. Unwraps `_cek` under the collection DEK and
+     * memoises it in the CEK cache under `id` (when supplied) so repeated reads of
+     * the same record skip the unwrap. Shared by the body-decrypt path
+     * ({@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>;
+    /**
+     * Low-level: decrypt an envelope and return the raw JSON string.
+     *
+     * `_cek` presence is the format discriminant (NOT `this.perRecordCek`),
+     * so a mixed vault — and a recipient that never opted into
+     * `perRecordKeys` — decrypts both legacy and CEK records:
+     *  - `_cek` present → unwrap the CEK under the collection DEK, decrypt the
+     *    body under the CEK (cache the unwrapped CEK so repeated reads skip it).
+     *  - `_cek` absent → legacy path, body decrypts directly under the
+     *    collection DEK.
+     *
+     * The optional `id` lets reads populate the CEK cache; it is omitted by
+     * callers (history, conflict merge) that have only the envelope.
+     */
+    decryptJsonString(envelope: EncryptedEnvelope, id?: string): Promise<string | null>;
+    /**
+     * 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,
+     * and JSON-parse the result. Shared by both the inline-decrypt path and a
+     * {@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>;
+    /**
+     * Build the `ViaCryptoCtx` for forget()'s per-ref via-erase fold (#629
+     * Task 10) — resolves the live envelope's CEK exactly like
+     * `decryptRecord` does, then delegates to the same capability factory
+     * `encodeAtRest`/`decodeAtRest` use.
+     */
+    eraseCryptoCtx(id: string, live: EncryptedEnvelope): Promise<ViaCryptoCtx>;
+    /**
+     * Classify a live envelope's `_sealed` slots for crypto-shred completeness.
+     * `forget()` drops `_cek`/`_sealed` but
+     * RETAINS the collection DEK, so only a slot keyed off the per-record CEK is
+     * genuinely shredded by the tombstone; a legacy slot keyed off the
+     * collection DEK survives in any synced/backup copy.
+     *
+     * Mirrors {@link unsealField}'s dual-read split: try the CEK-derived key per
+     * slot — success → `shreddable`, AES-GCM auth failure → `dekResidue`. With no
+     * `_cek` (pure legacy collection-DEK sealing) ALL slots are residue.
+     */
+    classifySealedShred(live: EncryptedEnvelope): Promise<{
+        readonly slots: readonly SealedShredSlot[];
+    }>;
+    /**
+     * Build a non-leaking {@link Sealed} handle over a sealed field's ciphertext.
+     * The handle captures only the ciphertext `blob` and a closure to
+     * {@link unsealField}; the plaintext is never stored on it — so the handle
+     * 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>;
+    /**
+     * Replace every field the just-written envelope actually sealed with a
+     * {@link Sealed} handle, leaving every other field as its plaintext value.
+     * Used to populate the cache on the write path without ever materialising
+     * sealed plaintext into it. Returns `record` untouched when nothing was
+     * sealed. Keys off `envelope._sealed` itself (#642 fix) — NOT
+     * `this.ctx.sensitiveFields`, which only names the inline `sensitive:[...]`/
+     * classified-recoverable field set: a collection whose sealing comes
+     * entirely from the `taint` via-binding (a derivation/MV output or rollup
+     * target folded sealed from a classified SOURCE collection, #642) declares
+     * no local `sensitiveFields` at all, so that stale gate skipped this
+     * conversion and left a just-written taint-sealed field as cached
+     * plaintext — read back correctly ONLY after a cold cache miss (`get()`'s
+     * own `decodeAtRest` call, unaffected by this gate) forced a fresh decrypt.
+     */
+    toCacheRecord(record: T, envelope: EncryptedEnvelope, id?: string): Promise<T>;
+    /**
+     * Apply `_sealed`-slot post-processing to an ALREADY-DECRYPTED `record`:
+     * restore each `_sealed[field]` blob inline (`sealedAsHandles` falsy) or
+     * as an opaque {@link Sealed} handle (`sealedAsHandles: true`), routing
+     * through a via pipeline's `decodeAtRest` hook when one is declared.
+     * Extracted byte-parity from `decryptRecord`'s inline block (#635) so a
+     * caller that resolves its OWN per-record CEK under a DIFFERENT DEK than
+     * this codec's `this.ctx.getDEK()` — namely the tier>0 `getAtTier` leg in
+     * `with-audit/tiers/index.ts`, whose `_cek` is wrapped under the TIER DEK,
+     * not the collection DEK `decryptRecord`/`resolveEnvelopeCek` always
+     * unwrap under — can still get correct sealed-slot handling without
+     * routing its whole read through `decryptRecord` (which would resolve the
+     * wrong DEK for it).
+     *
+     * Zero-knowledge: takes only the already-resolved per-record `cek` (or
+     * `undefined` for a legacy/no-CEK record) — the same shape `makeSealedHandle`
+     * already takes above. Never the keyring, never a raw DEK: the legacy
+     * fallback key stays fully internal to `sealKeyMaterial`/`viaCryptoCtx`,
+     * which close over THIS codec's own `getDEK` (permanently bound to
+     * `this.ctx.name`'s tier-0 DEK at construction) — so even when called from
+     * a tier>0 context, the legacy-fallback key resolution is correct: sealed
+     * fields are always sealed under the CEK or the collection's tier-0 DEK,
+     * 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?: {
+        id?: string;
+        sealedAsHandles?: boolean;
+    }): Promise<T>;
+    /**
+     * Decrypt an envelope into a record of type `T`.
+     *
+     * When a schema is attached, the decrypted value is validated before
+     * being returned. A divergence between the stored bytes and the
+     * current schema throws `SchemaValidationError` with
+     * `direction: 'output'` — silently returning drifted data would
+     * propagate garbage into the UI and break the whole point of having
+     * a schema.
+     *
+     * `skipValidation` exists for history reads: when calling
+     * `getVersion()` the caller is explicitly asking for an old snapshot
+     * that may predate a schema change, so validating it would be a
+     * false positive. Every non-history read leaves this flag `false`.
+     */
+    decryptRecord(envelope: EncryptedEnvelope, opts?: {
+        skipValidation?: boolean;
+        id?: string;
+        sealedAsHandles?: boolean;
+    }): Promise<T | null>;
+}

package/dist/kernel/enclave/record-keys/sealed-slot.d.ts

@@ -0,0 +1,14 @@
+/** Parse an `iv:data` sealed slot (split on the FIRST `:`). */
+export declare function parseSealedSlot(blob: string): {
+    iv: string;
+    data: string;
+};
+/**
+ * Dual-read: decrypt a sealed slot trying the CEK-derived field key first,
+ * falling back to the collection-DEK field key. Legacy records
+ * (even ones whose body is CEK-encrypted) are sealed under the collection-DEK
+ * key; current writes seal under the per-record CEK. Try the CEK key first; on
+ * its AES-GCM auth failure, fall back to the DEK key. Throws only if BOTH fail.
+ * Returns the plaintext string (callers `JSON.parse` as needed).
+ */
+export declare function dualReadSealedSlot(blob: string, field: string, collection: string, cek: CryptoKey | undefined, dek: CryptoKey): Promise<string>;

package/dist/kernel/enclave/record-keys/sealed-slots.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Sealed-slot sub-step — the "seal these declared fields into their own
+ * `iv:data` slots" mechanism, extracted byte-parity from `RecordCodec`
+ * (#629 Task 1; see `.superpowers/sdd/seam-map-classified-blobs.md` §2).
+ *
+ * This is the ONE genuinely separable sub-step `RecordCodec.encryptRecord`/
+ * `decryptRecord` perform (the digest-only `_vdig`/`_bidx` mechanism is NOT
+ * separable the same way — it needs write-history `prev` context, see the
+ * seam map's separability verdict). `sealFields`/`unsealFields` are the
+ * natural shape of a `via` `encodeAtRest`/`decodeAtRest` hook for a "seal
+ * this field" via-feature, and `makeSealedSlotCapability`/
+ * `makeReservedEnvelopes` (below) are the `ViaCryptoCtx` capability
+ * factories built on top of them.
+ *
+ * The capability factories live here (rather than a sibling
+ * `kernel/via-crypto.ts`) so they can call `deriveSealedFieldKey`/
+ * `deriveSealedFieldKeyFromCek`/`encrypt`/`decrypt` directly — this file IS
+ * kernel enclave code (C3), so it is exempt from `enclave-barrel-only` the
+ * same way `record-codec.ts`/`sealing.ts` are. A file outside
+ * `kernel/enclave/**` would have had to go through the enclave barrel
+ * (`kernel/enclave/index.ts`), which does not (yet) export these symbols.
+ */
+import { type EnclaveKey } from '../crypto.js';
+import { SealedHandle } from '../../types.js';
+import type { ViaCryptoCtx } from '../../via/index.js';
+/**
+ * Key material for one collection's sealed-field derivation. `cek`, when
+ * supplied, is preferred (record-scoped); `getDEK` is the fallback (and,
+ * for legacy/no-CEK collections, the only key) — mirrors the dual-read
+ * `RecordCodec` has always done.
+ */
+export interface SealKeyMaterial {
+    readonly collection: string;
+    readonly cek?: EnclaveKey;
+    getDEK(): Promise<EnclaveKey>;
+}
+export interface SealFieldsResult {
+    readonly openRecord: Record<string, unknown>;
+    readonly sealed: Record<string, string> | undefined;
+}
+/**
+ * Peel declared `sensitiveFields` out of `record` BEFORE building `_data`,
+ * sealing each into its own `iv:data` slot. Extracted byte-parity from
+ * `RecordCodec.encryptRecord` step 2 (pre-#629 `record-codec.ts:261-288`).
+ * Returns `record` untouched (and `sealed: undefined`) when no declared
+ * field is present with a defined value — the envelope stays byte-identical
+ * to legacy output, exactly as before.
+ */
+export declare function sealFields(record: Record<string, unknown>, sensitiveFields: ReadonlySet<string>, keyMaterial: SealKeyMaterial): Promise<SealFieldsResult>;
+/**
+ * Unseal one `_sealed[field]` slot to its plaintext value: dual-read (try
+ * the CEK-derived key, fall back to the DEK-derived key for legacy
+ * records), AES-GCM-decrypt the `iv:data` blob, and JSON-parse the result.
+ * Extracted byte-parity from `RecordCodec.unsealField`
+ * (pre-#629 `record-codec.ts:485-493`).
+ */
+export declare function unsealOneField(field: string, blob: string, keyMaterial: SealKeyMaterial): Promise<unknown>;
+/**
+ * Build a non-leaking {@link SealedHandle} producer over sealed key
+ * material: each call captures only the ciphertext `blob` and a closure to
+ * {@link unsealOneField} — the plaintext is never stored on the handle, and
+ * (crucially) the DEK is fetched lazily on `reveal()`, never at handle-
+ * construction time. Extracted byte-parity from
+ * `RecordCodec.makeSealedHandle` (pre-#629 `record-codec.ts:552-554`).
+ */
+export declare function makeHandleProducer(keyMaterial: SealKeyMaterial): (field: string, blob: string) => SealedHandle<unknown>;
+/**
+ * Restore every `[field]: blob` entry in `sealed` onto `record` (mutated in
+ * place, matching the original's mutate-then-return shape): eagerly unseal
+ * to plaintext (`opts.asHandles` falsy) or wrap each in a
+ * {@link SealedHandle} (`opts.asHandles: true`) so the plaintext is never
+ * materialised. Extracted byte-parity from `RecordCodec.decryptRecord`'s
+ * sealed-handle block (pre-#629 `record-codec.ts:615-623`).
+ */
+export declare function unsealFields(record: Record<string, unknown>, sealed: Record<string, string>, keyMaterial: SealKeyMaterial, opts?: {
+    asHandles?: boolean;
+}): Promise<Record<string, unknown>>;
+/** What {@link makeSealedSlotCapability} needs — a subset of `RecordCodecContext`. */
+export interface SealedSlotCapabilityCtx {
+    readonly name: string;
+    getDEK(): Promise<EnclaveKey>;
+}
+/**
+ * Build a `ViaCryptoCtx.sealedSlots` capability pre-bound to one
+ * `(collection, recordId)`. The key material (`cek`/DEK resolver) is closed
+ * over and never placed on the returned object — `Object.keys`/
+ * `Object.values` of the capability expose only the three methods, never a
+ * key (zero-knowledge: capabilities never expose keys).
+ *
+ * `delete(field)` is **advisory and capability-instance-local, not real
+ * erasure** — it has no store to reach and never will by itself: it just
+ * adds `field` to a `Set` closed over by THIS ONE capability object, so a
+ * later `unseal` call on that SAME object refuses. No I/O happens. A fresh
+ * capability for the same record (e.g. `seal()`'d again, or a new
+ * `makeSealedSlotCapability(...)` call) has an empty set and sees no
+ * deletion at all — `seal()` on a given field also clears any prior mark
+ * for it. Do not build production logic on `delete()` persisting anything.
+ * The real erasure guarantee for a forgotten record is `vault.forget()`'s
+ * unconditional `_writeTombstone` call, which replaces the whole live
+ * envelope with a fresh, `_sealed`-free tombstone — `_sealed` disappears
+ * from the store regardless of what any capability's `delete()` marked.
+ * (#629 Task 10 traced this end-to-end; see task-10-report.md "sealedSlots
+ * .delete()" section. Removing/changing this method's shape is a phase-E
+ * decision, not implied by this comment.)
+ */
+export declare function makeSealedSlotCapability(ctx: SealedSlotCapabilityCtx, recordId: string, cek?: EnclaveKey): ViaCryptoCtx['sealedSlots'];
+/** Resolve the DEK for an arbitrary (possibly synthetic, e.g. `_dict_en`) collection name. */
+export type ReservedEnvelopeDekResolver = (collection: string) => Promise<EnclaveKey>;
+/**
+ * Build a `ViaCryptoCtx.reservedEnvelopes` capability: a whole-envelope
+ * encrypt/decrypt door scoped to collection names under a declared prefix
+ * (e.g. `_dict_`) — the shape `via/i18n/dictionary.ts`'s
+ * `DictionaryHandle` needs (seam map Part 3): build JSON → encrypt under a
+ * DEK → wrap in an `EncryptedEnvelope`; decrypt → JSON text. No per-record
+ * CEK — reserved envelopes are whole-DEK-encrypted, same as the dictionary
+ * grandfather.
+ *
+ * `reservedEnvelopes(prefix)` throws `ValidationError` immediately when
+ * `prefix` is not in `declaredPrefixes`; each `encrypt`/`decrypt` call
+ * throws `ValidationError` when its `collection` argument does not start
+ * with `prefix`.
+ */
+export declare function makeReservedEnvelopes(dekResolver: ReservedEnvelopeDekResolver, declaredPrefixes: readonly string[]): ViaCryptoCtx['reservedEnvelopes'];

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

@@ -0,0 +1,70 @@
+/**
+ * Record-scoped CEK sealing — grantor side.
+ *
+ * The **grantor** holds the collection DEK and seals ONE record's CEK to an
+ * `at-*` host so that host — and only that host — can decrypt exactly that
+ * record, with no access to the vault DEK and no ability to read any other
+ * record. This is the counterpart to the host-side `openSealedRecord`
+ * (`@noy-db/hub/sealed-record`), which holds no DEK.
+ *
+ * These functions are the orchestration behind `vault.sealRecordToHost` /
+ * `vault.revokeSealedRecord` / `vault.rotateRecordCek`, lifted off `Vault`
+ * behind a narrow {@link SealingContext} so the kernel file delegates. They
+ * live in `record-keys/` (the vault-side CEK policy layer), NOT in
+ * `sealed-record/`, so the host-side subpath stays DEK-free — the wire
+ * *types* they share are spine-owned (`kernel/types.ts`), not imported from
+ * `sealed-record/` directly.
+ */
+import { type EnclaveKey } from '../crypto.js';
+import { type NoydbStore, type RecipientSealer } from '../../types.js';
+/** The `_sealed_cek` delivery namespace (one envelope per `collection/id/pid`). */
+export declare const SEALED_CEK_NS = "_sealed_cek";
+/** What the grantor functions need from their `Vault`. */
+export interface SealingContext {
+    readonly adapter: NoydbStore;
+    /** Vault id (the adapter's first coordinate). */
+    readonly vault: string;
+    /** Resolve the DEK a record's CEK is wrapped under. */
+    getDEK(collection: string): Promise<EnclaveKey>;
+    /** Actor id stamped on `_by` (empty string → omit). */
+    readonly actor: string;
+    /** Evict the per-record CEK cache + decrypted-record cache after a rotation. */
+    invalidateRecordCaches(collection: string, id: string): Promise<void>;
+}
+/**
+ * Seal a record's CEK to a host. See `vault.sealRecordToHost` for the contract.
+ * Returns `{ pid, envelopeKey }`.
+ */
+export declare function sealRecordToHost(ctx: SealingContext, collection: string, id: string, hostSealer: RecipientSealer, opts: {
+    expiresAt: string;
+}): Promise<{
+    pid: string;
+    envelopeKey: string;
+}>;
+/**
+ * Revoke one sealed-CEK grant.
+ *
+ * **Default (`{ hard: false }`) is SOFT** — it only deletes the delivery
+ * envelope from the store. A host that already fetched (or cached the unsealed
+ * CEK from) that envelope KEEPS decrypt capability for the record; soft revoke
+ * is a "stop new fetches" control, not a cryptographic cutoff.
+ *
+ * **`{ hard: true }`** additionally rotates the record's CEK (via
+ * {@link rotateRecordCek}): the live body is re-encrypted under a fresh CEK and
+ * EVERY sealed-CEK delivery envelope for the record (all pids) is deleted, so
+ * any previously-sealed CEK fails the AES-GCM auth tag on the rotated body —
+ * future opens are cryptographically denied. (PRE-rotation history versions,
+ * which keep their old `_cek`, remain openable — same semantics as
+ * `rotateRecordCek`.)
+ */
+export declare function revokeSealedRecord(ctx: SealingContext, collection: string, id: string, pid: string, opts?: {
+    hard?: boolean;
+}): Promise<void>;
+/**
+ * HARD-rotate a record's CEK: re-encrypt the live body under a fresh CEK, evict
+ * caches, and delete EVERY sealed-CEK delivery envelope for the record. See
+ * `vault.rotateRecordCek` for why this bypasses `Collection.put` (no guards, no
+ * history bump — a key rotation must not re-encrypt prior history under the new
+ * CEK).
+ */
+export declare function rotateRecordCek(ctx: SealingContext, collection: string, id: string): Promise<void>;

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

@@ -0,0 +1,57 @@
+/**
+ * Tombstone shape + predicate for the per-record-key (CEK) layer.
+ *
+ * A *tombstone* is the residue a GDPR crypto-shred (`vault.forget()`)
+ * leaves on disk: the live envelope rewritten to `{ _noydb, _v, _ts, _by,
+ * _iv:'', _data:'' }`, dropping `_iv`/`_data`/`_cek`/`_det`. With the wrapped
+ * per-record CEK gone, the body — and every history version under the same
+ * CEK — is permanently undecryptable, while the record KEY survives so the
+ * version counter and "record existed and was erased" persist for the audit
+ * ledger.
+ *
+ * These two helpers are the pure, collection-independent core of that
+ * contract: {@link buildTombstone} mints the shape, {@link isTombstone}
+ * recognises it on the read path. The orchestration that *writes* a tombstone
+ * (`_writeTombstone`) and drives `vault.forget()` lives with the collection /
+ * vault; it calls into these.
+ */
+import { type EncryptedEnvelope } from '../../types.js';
+/**
+ * Shape-only tombstone recognition for layers that have no per-collection
+ * context (the sync engine, #590): a tombstone carries an empty `_data` and
+ * no wrapped CEK. No live envelope can match — record bodies never serialize
+ * to the empty string (the `_sync` meta envelope carries non-empty `_data`,
+ * and legacy migration envelopes carry non-empty `_iv`/`_data`).
+ */
+export declare function isTombstoneShape(envelope: EncryptedEnvelope): boolean;
+/**
+ * Is this envelope a crypto-shred tombstone?
+ *
+ * A tombstone carries no body (`_data` empty) and no wrapped CEK (`_cek`
+ * absent) — decrypting it would call `decrypt('', '', dek)` → an AES-GCM
+ * throw, so every read choke point must short-circuit to `null` instead.
+ *
+ * `encrypted` is the collection's encryption flag: on an unencrypted
+ * collection there are no envelopes to shred, so nothing is ever a tombstone.
+ * (Legacy migration envelopes carry non-empty `_iv`/`_data`, so they are not
+ * tombstones and stay readable.)
+ */
+export declare function isTombstone(envelope: EncryptedEnvelope, encrypted: boolean): boolean;
+/**
+ * Mint a tombstone envelope from a record's live version + actor.
+ *
+ * Keeps `_v` (the displaced version) so the counter is monotonic across the
+ * shred, stamps a fresh `_ts`, and records `_by` when an actor is supplied.
+ * Deliberately omits `_iv`/`_data`/`_cek`/`_det` — that omission *is* the
+ * erasure.
+ */
+export declare function buildTombstone(version: number, actor: string): EncryptedEnvelope;
+/** #589: is this envelope an ordinary-delete marker (version-ordered, reads as absent)? */
+export declare function isDeleteMarker(envelope: EncryptedEnvelope): boolean;
+/**
+ * Mint a delete marker from the deleted record's next version + actor (#589).
+ * Minted at the NEXT version (`existing._v + 1`) — unlike `buildTombstone`, which
+ * keeps the displaced `_v` — so it wins convergence over the pre-delete copy and a
+ * re-create can still win over it at a higher version.
+ */
+export declare function buildDeleteMarker(version: number, actor: string): EncryptedEnvelope;

package/dist/kernel/env-check.d.ts

@@ -0,0 +1 @@
+declare function checkEnvironment(): void;