@noy-db/hub 0.6.0-pre.8 → 0.6.0

package/dist/kernel/enclave/record-aad.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Record-identity AAD (#1041).
+ *
+ * AES-GCM authenticates its *additional authenticated data* alongside the
+ * ciphertext without encrypting it. Binding a record's identity here is what
+ * stops an untrusted store from silently **relocating** an envelope — moving
+ * it to another collection or id, re-tiering it, or rewriting who
+ * wrote it — while keeping a body whose auth tag still verifies.
+ *
+ * Scope, stated plainly: this closes cross-COLLECTION relocation, the `_tier`
+ * silent-hide, provenance forgery — and, since #1093, **version rollback**.
+ *
+ * ## `_v` is bound, and what it took to get there
+ *
+ * `_v` was deliberately left out at first, for a reason that was real rather
+ * than cautious: the sync engine re-stamped `_v` on existing ciphertext without
+ * holding a DEK (`advancePastRemote`), so binding it would have made every
+ * conflict-superseded record undecryptable. #1042's `MergeAuthority` removed
+ * that obstacle by giving the merge a DEK-holding capability, so advancing a
+ * version became a **re-seal** instead of a metadata edit — and only then could
+ * `_v` join the tuple.
+ *
+ * ⚠️ **What that buys, stated exactly** — the harness measured this, and the
+ * loose version ("rollback is prevented") is wrong.
+ *
+ * A body can no longer be presented at a version it was not sealed at. So the
+ * *restamped* rollback — take v1's bytes, label them v9, win the convergence
+ * comparison, overwrite the newer copy — is refused, and refused **before**
+ * `local.put`, so nothing is lost.
+ *
+ * A store re-serving the genuine v1 **at its own `_v: 1`** is still served, and
+ * has to be: that envelope is internally consistent, and a reader arriving
+ * fresh has nothing to compare it against. AAD binds a body to the version it
+ * claims; it cannot know which version *should* have arrived.
+ *
+ * So rollback stops being forgery and becomes **withholding** — hiding the newer
+ * version rather than faking one — which is `withVaultHead()`'s job (#1044).
+ *
+ * ## Why `vault` is not bound
+ *
+ * It was, briefly, and it broke `adoptPartition`. That path re-homes a whole
+ * partition into a new vault name by moving envelopes **verbatim** —
+ * `with-cargo/adopt-partition.ts:140` is a bare
+ * `destinationStore.saveAll(vaultName, backup.collections)` with no
+ * re-encryption, because it does not hold the keys to re-encrypt at that
+ * point. Binding the vault name makes every adopted record undecryptable.
+ *
+ * The uncomfortable truth behind that: **relocation is not purely an attack.**
+ * Adoption is a legitimate, supported relocation, and AAD cannot tell the two
+ * apart. So the vault boundary has to be defended by something that can
+ * distinguish intent — an authenticated head or an explicit re-key — rather
+ * than by sealing a name the product deliberately changes.
+ *
+ * Cross-*collection* relocation has no such legitimate counterpart, so it stays
+ * bound.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Where an envelope was fetched from — the **read** side's half of identity.
+ *
+ * A reader supplies only the address, because that is genuinely all it knows:
+ * `_tier`, `_by` and `_v` are read back off the envelope itself
+ * ({@link recordAadFor}). Splitting this out of {@link RecordIdentity} is what
+ * lets `version` be *required* on the write side without forcing dozens of read
+ * call sites to invent one.
+ */
+export interface RecordRef {
+    readonly collection: string;
+    readonly id: string;
+}
+/**
+ * The identity an envelope's body is sealed against — the **write** side.
+ *
+ * Every field here is stamped onto the envelope by `buildRecordEnvelope` from
+ * this one object, so what a writer *seals* and what it *stamps* cannot drift.
+ */
+export interface RecordIdentity extends RecordRef {
+    /**
+     * The `_v` this body is sealed at (#1093).
+     *
+     * Required, and required is the point: a version that could be omitted would
+     * be a version some writer forgets, and a record sealed at a version nobody
+     * chose is one a reader cannot open. The compiler asks the question at every
+     * write site instead of leaving it to review.
+     */
+    readonly version: number;
+    /** Absent is identical to `0` — the read paths treat them as one record. */
+    readonly tier?: number | undefined;
+    /** Absent (no `_by` on the envelope) is distinct from an empty string. */
+    readonly by?: string | undefined;
+}
+/**
+ * Length-prefixed, order-fixed encoding.
+ *
+ * The obvious `${collection}:${id}` is unsafe: an attacker who
+ * controls a collection name can choose one that re-splits the same joined
+ * string a different way, so two different identities produce identical AAD
+ * and the relocation this exists to prevent goes through. Every field is
+ * therefore written as a 4-byte big-endian length followed by its UTF-8 bytes,
+ * which no field content can imitate.
+ *
+ * A one-byte presence flag precedes `by` so that "no author recorded" and
+ * "author recorded as the empty string" cannot be swapped for one another.
+ */
+export declare function buildRecordAad(identity: RecordIdentity): Uint8Array;
+/**
+ * The AAD a **reader** must supply to open `envelope`, given where it fetched
+ * it from.
+ *
+ * This is the read-side counterpart of {@link buildRecordAad}, and the split
+ * exists because of one asymmetry: **a writer always knows what it is writing;
+ * a reader often does not.** Query execution, sync merge and backup restore
+ * hold an envelope that arrived from a map or a batch, having discarded the
+ * address it came from.
+ *
+ * What makes the read side tractable is that only `{collection, id}` has to be
+ * threaded — precisely what the caller passed to `store.get`. `_tier`, `_by`
+ * and `_v` are read back **off the envelope**, so no extra plumbing carries
+ * them.
+ *
+ * That is not a weakening. An attacker who edits `_tier` to hide a record,
+ * `_by` to forge provenance, or `_v` to pass an old body off as the current
+ * one, changes the AAD the reader computes — and AES-GCM then fails to
+ * authenticate. The tampered field defeats itself.
+ */
+export declare function recordAadFor(ref: RecordRef, envelope: {
+    readonly _v: number;
+    readonly _tier?: number | undefined;
+    readonly _by?: string | undefined;
+}): Uint8Array;

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

@@ -0,0 +1,76 @@
+import type { EncryptedEnvelope } from '../types.js';
+import type { RecordIdentity } from './record-aad.js';
+/** The body an envelope carries, independent of who is writing it. */
+export interface RecordEnvelopeBody {
+    /** AES-GCM IV, base64. Empty string for a plaintext or tombstone envelope. */
+    readonly iv: string;
+    /** Ciphertext (or plaintext JSON when the collection stores plaintext). */
+    readonly data: string;
+    /** ISO timestamp. Defaults to now — pass it when the caller has a real one. */
+    readonly ts?: string | undefined;
+    /** Wrapped per-record CEK, when the record has one. */
+    readonly cek?: string | undefined;
+    readonly provenance?: {
+        readonly source: string;
+        readonly sourceTs: string;
+    } | undefined;
+    /**
+     * Slots the envelope may additionally carry.
+     *
+     * `_tier`, `_by` and `_v` are deliberately NOT here — they come from
+     * `identity`, which is the single source for all three. See
+     * {@link buildRecordEnvelope}.
+     */
+    readonly extra?: Partial<Pick<EncryptedEnvelope, '_det' | '_sealed' | '_vdig' | '_bidx'>> | undefined;
+}
+/**
+ * Build an envelope for `identity`.
+ *
+ * ## `identity` is the SINGLE SOURCE for `_by`, `_tier` and `_v`
+ *
+ * All three are stamped from it, and `RecordEnvelopeBody` deliberately cannot
+ * carry them. That is not tidiness — it is what makes the AAD binding safe.
+ *
+ * The caller encrypts the body under AAD derived from `{collection, id, tier,
+ * by, version}`. A reader recomputes that AAD from the address it fetched from
+ * plus `_tier`/`_by`/`_v` read back **off the envelope** (`recordAadFor`). So if the
+ * identity a writer *declares* could differ from the fields it *stamps*, the
+ * AAD would not reproduce and the record would be undecryptable — silently, at
+ * write time, discoverable only on the next read, and invisible to every gate
+ * because the envelope is perfectly well-formed.
+ *
+ * An earlier draft took both and asserted they agreed. The assertion fired 230
+ * times on the existing tree, which is the argument against it: a rule that can
+ * be violated is a rule someone must remember. Taking one source removes the
+ * violation instead of reporting it.
+ */
+export declare function buildRecordEnvelope(identity: RecordIdentity, body: RecordEnvelopeBody): EncryptedEnvelope;
+/**
+ * Build an envelope from an already-sealed body — the output of
+ * `writeEnvelopeBody` — **without the caller ever naming `_iv`/`_data`/`_cek`**.
+ *
+ * This exists because of a guard, and the guard was right. Migrating
+ * `writeEnvelopeBody` callers to {@link buildRecordEnvelope} meant rewriting
+ * `...body` (a spread, which names nothing) into `iv: body._iv, data:
+ * body._data, cek: body._cek` — and `enclave-body-only` failed it: three new
+ * protected-body accesses in files that previously had zero.
+ *
+ * That is the correct outcome rather than an obstacle. #1051 exists to move
+ * knowledge of the envelope's shape *inward*; a migration that spreads the
+ * protected field names outward to every caller would have defeated its own
+ * purpose while looking like progress. The pairing belongs here.
+ *
+ * ## It takes a SEALER, not a sealed body — and that is load-bearing (#1041)
+ *
+ * The obvious shape is `(identity, alreadySealedBody, rest)`. That requires the
+ * caller to name the identity TWICE — once for `writeEnvelopeBody` and once
+ * here — and the two must agree byte for byte or the record is sealed under
+ * AAD no reader can reproduce.
+ *
+ * They did not agree. `with-party/broker/seed.ts` sealed against
+ * `{collection, id}` and stamped `{collection, id, by}`, so every broker seed
+ * became unreadable the moment AAD switched on. Taking the sealer means the
+ * identity is written once and handed to both — divergence stops being
+ * possible rather than being something to remember.
+ */
+export declare function buildSealedRecordEnvelope(identity: RecordIdentity, seal: (identity: RecordIdentity) => Promise<Pick<EncryptedEnvelope, '_iv' | '_data' | '_cek'>>, body: Omit<RecordEnvelopeBody, 'iv' | 'data' | 'cek'>): Promise<EncryptedEnvelope>;

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

@@ -13,6 +13,7 @@
  * 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';
 /**
@@ -27,7 +28,7 @@ import type { EncryptedEnvelope } from '../../types.js';
  *    (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?: {
+export declare function openEnvelopeJson(ref: RecordRef, env: EncryptedEnvelope, key: EnclaveKey, opts?: {
     encrypted?: boolean;
 }): Promise<string>;
 /**
@@ -43,7 +44,7 @@ export declare function openEnvelopeJson(env: EncryptedEnvelope, key: EnclaveKey
  *    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?: {
+export declare function writeEnvelopeBody(identity: RecordIdentity, json: string, key: EnclaveKey, opts?: {
     encrypted?: boolean;
     perRecordKey?: boolean;
 }): Promise<Pick<EncryptedEnvelope, '_iv' | '_data' | '_cek'>>;
@@ -85,3 +86,34 @@ export declare function hasPerRecordKey(env: EncryptedEnvelope): boolean;
  * `envelope-body.test.ts`).
  */
 export declare function envelopeBodyForHash(env: EncryptedEnvelope): string;
+/**
+ * Does `env` carry an AEAD-sealed body at all?
+ *
+ * The one question callers outside the enclave legitimately need to ask about
+ * `_iv` — a tombstone and a plaintext-collection record have none, so there is
+ * nothing to authenticate and nothing to re-seal. Both {@link
+ * verifyRecordIdentity} (which treats them as vacuously authentic) and the
+ * merge authority's `advance` (which stamps them without re-sealing) turn on
+ * it, and asking it here keeps `_iv` from leaking back out to the callers —
+ * which `enclave-body-only` refused, correctly, when `advance` tested it inline.
+ */
+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.
+ */
+export declare function verifyRecordIdentity(ref: RecordRef, env: EncryptedEnvelope, key: EnclaveKey): Promise<boolean>;

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

@@ -21,6 +21,7 @@
  */
 import { type EnclaveKey } from '../crypto.js';
 import type { EncryptedEnvelope } from '../../types.js';
+import { type RecordIdentity } from '../record-aad.js';
 import type { Lru } from '../../cache/index.js';
 /** Dependencies {@link resolveStableCek} needs from its collection. */
 export interface StableCekDeps {
@@ -46,15 +47,31 @@ export interface RewrappedBody {
     readonly cek: EnclaveKey | null;
 }
 /**
- * Move a record body from `fromDek` to `toDek`.
+ * Move a record body from `fromDek`/`from` to `toDek`/`to`.
  *
  * - 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.
+ *   directly.
+ *
+ * ## Why it takes TWO identities (#1041)
+ *
+ * A rewrap is the one operation where the identity genuinely **changes**. A
+ * tier move rewrites `_tier`; a history snapshot lands at a different
+ * `(collection, id)` entirely. Since AAD binds both, the body must be opened
+ * under the identity it currently has and re-sealed under the one it is moving
+ * to. A single identity would be wrong for one end or the other.
+ *
+ * ⚠️ **This retires an optimisation, deliberately.** Callers used to compute
+ * ONE rewrap and reuse the bytes for both a tier move's live write and its
+ * `_history` snapshot (#728). Those now have different destination identities,
+ * so they need different AAD and therefore different ciphertext — the same
+ * bytes cannot satisfy both. Reusing one rewrap for two destinations is now a
+ * silent corruption, not a saving: it produces a record that opens at one
+ * address and not the other.
  */
-export declare function rewrapBodyToDek(envelope: Pick<EncryptedEnvelope, '_iv' | '_data' | '_cek'>, fromDek: EnclaveKey, toDek: EnclaveKey): Promise<RewrappedBody>;
+export declare function rewrapBodyToDek(from: RecordIdentity, to: RecordIdentity, envelope: Pick<EncryptedEnvelope, '_iv' | '_data' | '_cek' | '_tier' | '_by'>, 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.
@@ -76,7 +93,7 @@ export declare function applyRewrappedBody(envelope: EncryptedEnvelope, body: Re
  * 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>;
+export declare function rewrapEnvelope(identity: RecordIdentity, 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`)?
@@ -104,4 +121,4 @@ export declare function rewrapEnvelope(envelope: EncryptedEnvelope, fromDek: Enc
  * those fields themselves, preserving the check-architecture body-access
  * ratchet.
  */
-export declare function isRewrappedUnder(envelope: Pick<EncryptedEnvelope, '_iv' | '_data' | '_cek'>, dek: EnclaveKey): Promise<boolean>;
+export declare function isRewrappedUnder(identity: RecordIdentity, envelope: Pick<EncryptedEnvelope, '_iv' | '_data' | '_cek'>, dek: EnclaveKey): Promise<boolean>;

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

@@ -18,6 +18,7 @@
  */
 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';
@@ -127,11 +128,9 @@ export declare class RecordCodec<T> {
      * 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;
+    static buildEnvelope(identity: RecordIdentity, p: {
         iv: string;
         data: string;
-        by?: string;
         cek?: string;
         provenance?: {
             source: string;
@@ -140,10 +139,8 @@ export declare class RecordCodec<T> {
         extra?: Partial<Pick<EncryptedEnvelope, '_tier' | '_det' | '_sealed'>>;
     }): EncryptedEnvelope;
     /** Plaintext (`_iv:''`) body envelope — the `!storeCiphertext` shape. */
-    static buildPlaintextEnvelope(p: {
-        version: number;
+    static buildPlaintextEnvelope(identity: RecordIdentity, p: {
         data: string;
-        by?: string;
         provenance?: {
             source: string;
             sourceTs: string;
@@ -157,7 +154,7 @@ export declare class RecordCodec<T> {
      * (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;
+    buildDebugEnvelope(id: string, record: T, version: number, source?: string, sourceTs?: string): EncryptedEnvelope;
     /**
      * Encrypt a JSON body into an envelope.
      *
@@ -167,11 +164,41 @@ export declare class RecordCodec<T> {
      * 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?: {
+    /**
+     * `ref` is the identity the envelope is sealed against, and it is **the
+     * location the bytes are stored at** — not necessarily this codec's own
+     * collection (#1051).
+     *
+     * That distinction was discovered here rather than assumed. Several callers
+     * put the result somewhere else entirely: search's vector sidecar lands in
+     * `_vec` under `encodeVecId(name, id)`, the lexical index under `_ft/<name>`,
+     * indexing's entries under a synthetic `idxId`. A codec that supplied
+     * `this.ctx.name` for those would seal them against a collection they are not
+     * in, and once AAD binds identity every one of them would fail to verify.
+     *
+     * ⚠️ **`_history` is the open case, and it is #1041's to settle.** Snapshots
+     * are produced with the LIVE record's identity here and then re-homed by
+     * `saveHistory` into `_history/<historyId(collection,id,_v)>`. Both readings
+     * are defensible — bind where it lives, or bind what it is a copy of — and
+     * 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>;
+    /**
+     * `ref` is FIRST and required (#1051). It was previously a trailing optional
+     * `id?: string`, which TypeScript cannot promote to required because it sits
+     * after other optionals — so the migration would have needed an `id ?? ''`
+     * fallback. That is exactly the silent default this issue exists to remove:
+     * once identity is bound into the AEAD, every record written with an empty id
+     * binds to the SAME identity and becomes interchangeable with the others.
+     * An object, not a bare string, so a swap with `version`/`source` cannot
+     * 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?: {
         readonly id: string;
         readonly prev: EncryptedEnvelope | null;
-    }, id?: string): Promise<EncryptedEnvelope>;
+    }): 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
@@ -195,7 +222,14 @@ export declare class RecordCodec<T> {
      * 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>;
+    /**
+     * `ref` must be the SAME identity the writer sealed against — which is the
+     * storage address, not necessarily this codec's own collection. Search's
+     * vector sidecar lives in `_vec`, its lexical index in `_ft`; passing
+     * `this.ctx.name` for those would recompute the wrong AAD and fail to open a
+     * perfectly good record (#1041).
+     */
+    decryptJsonString(ref: RecordRef, envelope: EncryptedEnvelope): 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,
@@ -304,7 +338,7 @@ export declare class RecordCodec<T> {
      * output-recompute path, not the public per-record read surface schema
      * validation guards.
      */
-    decryptRecordAtDek(envelope: EncryptedEnvelope, dek: EnclaveKey, id?: string): Promise<T | null>;
+    decryptRecordAtDek(ref: RecordRef, envelope: EncryptedEnvelope, dek: EnclaveKey): Promise<T | null>;
     /**
      * Decrypt an envelope into a record of type `T`.
      *
@@ -320,9 +354,8 @@ export declare class RecordCodec<T> {
      * 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?: {
+    decryptRecord(ref: RecordRef, envelope: EncryptedEnvelope, opts?: {
         skipValidation?: boolean;
-        id?: string;
         sealedAsHandles?: boolean;
     }): Promise<T | null>;
 }

package/dist/kernel/enclave/record-keys/rekey-blob.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Re-key a vault's blob set from an old `_blob` DEK to a new one (#1122).
+ *
+ * ## The defect this closes
+ *
+ * `rotateKeys` re-keys `store.list(vault, <slot>)` plus the derived refs
+ * `derivedRefsFor` declares. That assumes a DEK slot named `X` protects data
+ * filed under collection `X`. For `_blob` it is false: the slot is `_blob`, but
+ * every byte it protects lives in `_blob_index` and `_blob_chunks`. So rotating
+ * `_blob` minted a fresh DEK, re-encrypted **nothing**, and made every blob in
+ * the vault permanently unreadable — reported to the user as `TamperedError`,
+ * i.e. as an attack, when it was self-inflicted. An ordinary `revoke` of a
+ * whole-vault grantee reaches it, because such a grantee's DEK map contains
+ * `_blob`.
+ *
+ * ## Why this cannot be done by `rekeyEnvelopeIfNeeded` alone
+ *
+ * Two of the three surfaces do not have the shape that helper assumes:
+ *
+ * - a **chunk** envelope is sealed over raw bytes under a bespoke AAD
+ *   (`{eTag}:{index}:{count}`), not under the record AAD, so the generic
+ *   helper cannot open it;
+ * - an **index** envelope's body is JSON that may itself carry a wrapped
+ *   per-blob content CEK (`_cek` / `_cekPending`). Re-encrypting the body under
+ *   the new DEK without re-wrapping that CEK leaves a blob whose metadata opens
+ *   and whose bytes never will.
+ *
+ * ## Why it lives in the enclave
+ *
+ * It reads and writes protected body slots and it unwraps/re-wraps keys — the
+ * two things `enclave-body-only` reserves to `kernel/enclave/**`, and the same
+ * reason `rekeyEnvelopeToDek` moved here in #1074. `with-party` orchestrates
+ * the rotation and must not touch a body to do it.
+ *
+ * The blob layout below is duplicated from its owner rather than imported:
+ * `with-shape/blobs/blob-set.ts` already imports `with-party/team/tiers.js`, so
+ * a `with-party → with-shape` import would close a cycle, and the kernel may
+ * not depend on a service. `BlobObject` itself is a kernel type, so only the
+ * three collection/id string layouts are copied, with their owner named.
+ *
+ * @packageDocumentation
+ */
+import { type EnclaveKey } from '../crypto.js';
+import type { NoydbStore } from '../../types.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;
+}
+/**
+ * Move every blob sealed under `oldDek` onto `newDek`.
+ *
+ * Chunks are re-encrypted BEFORE their index entry is re-sealed, and that order
+ * is the resume property: an index entry still readable under `oldDek` means
+ * its chunks may be half-moved (each one is probed individually), and an index
+ * entry readable under `newDek` means its chunks are already done. An
+ * interrupted rotation is finished by re-running it with the same `newDek`.
+ *
+ * `otherDeks` is what keeps a tier-elevated blob from being mistaken for a
+ * damaged one. Membership in `_blob_index` is by DEK, not by collection name:
+ * a record elevated to tier N has its blob metadata sealed under `_blob#N`. An
+ * envelope that opens under NONE of the keys the caller holds is genuinely
+ * unreadable and throws, exactly as `rekeyEnvelopeIfNeeded` does — silently
+ * walking past it would turn a loud failure into permanent quiet loss.
+ */
+export declare function rekeyBlobSet(adapter: NoydbStore, vault: string, oldDek: EnclaveKey, newDek: EnclaveKey, otherDeks?: readonly EnclaveKey[]): Promise<BlobRekeyReport>;

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

@@ -0,0 +1,91 @@
+/**
+ * Re-key one envelope from an old collection DEK to a new one (#1074).
+ *
+ * Lives in the enclave because it is envelope surgery: it reads and writes the
+ * protected body slots (`_iv`/`_data`/`_cek`), which `enclave-body-only`
+ * reserves to `kernel/enclave/**`. `rotateKeys` previously did this inline in
+ * `with-party/team/keyring.ts` and got it wrong in two ways that the guard
+ * would have caught had the code lived here.
+ *
+ * @packageDocumentation
+ */
+import { type EnclaveKey } from '../crypto.js';
+import type { EncryptedEnvelope } from '../../types.js';
+/**
+ * Produce the envelope `envelope` becomes once its collection's DEK rotates
+ * from `oldDek` to `newDek`.
+ *
+ * **Every slot is carried forward except `_bidx`.** The previous inline version
+ * built a fresh literal holding only `_noydb/_v/_ts/_iv/_data`, silently
+ * discarding `_by`, `_tier`, `_cek`, `_sealed`, `_vdig` and `_source`. Losing
+ * `_tier` was the worst of those: tier-0 reads treat elevated as missing, so an
+ * elevated record did not error after a rotation — it simply disappeared.
+ *
+ * `_bidx` is dropped deliberately. It is a DEK-rooted equality tag, so a tag
+ * carried across a DEK rotation can never be re-derived to match a query again
+ * while still leaking the old equality partition. Index coverage regrows
+ * per-record on the next `put()` under the new DEK.
+ *
+ * Two shapes, and picking the wrong one is why this needed a helper:
+ *
+ * - **per-record CEK** (`_cek` present) — the body is sealed under the CEK and
+ *   the CEK is wrapped under the collection DEK, so rotation re-wraps the CEK
+ *   and leaves the body **untouched**. The old inline code instead ran
+ *   `decrypt(body, oldDek)` on these, which throws: rotation could not complete
+ *   on a collection containing any CEK record.
+ * - **bare** — body sealed directly under the DEK, so decrypt and re-encrypt.
+ *
+ * Idempotence is the caller's problem, not this function's: it assumes
+ * `envelope` is still under `oldDek`. A resumable rotation must know which side
+ * of the migration each record is on before calling.
+ */
+export declare function rekeyEnvelopeToDek(ref: {
+    readonly collection: string;
+    readonly id: string;
+}, envelope: EncryptedEnvelope, oldDek: EnclaveKey, newDek: EnclaveKey): Promise<EncryptedEnvelope>;
+/**
+ * Resumable variant: returns the re-keyed envelope, or `null` when `envelope`
+ * is **already** under `newDek` and needs no work (#1074 part 2).
+ *
+ * A rotation interrupted mid-collection leaves records on both sides of the
+ * migration. Resuming means re-running the rotation with the *same* new DEK,
+ * which requires distinguishing "not yet moved" from "already moved" without
+ * the caller touching protected slots.
+ *
+ * Detection is by trial decryption under `oldDek`. There is no metadata that
+ * says which DEK sealed a record — deliberately, since such a marker would be
+ * store-writable and therefore a downgrade lever (the same reasoning that
+ * keeps the reader from branching on `_noydb`).
+ *
+ * A record that opens under *neither* key is genuinely damaged and rethrows,
+ * rather than being silently skipped: a rotation that quietly walked past
+ * unreadable records would convert a loud failure into permanent silent loss,
+ * which is the defect this whole issue is about.
+ */
+export declare function rekeyEnvelopeIfNeeded(ref: {
+    readonly collection: string;
+    readonly id: string;
+}, envelope: EncryptedEnvelope, oldDek: EnclaveKey, newDek: EnclaveKey): Promise<EncryptedEnvelope | null>;
+/**
+ * Does this envelope open under ANY of `keys`? A read-only probe — decrypts
+ * nothing into a caller-visible value and writes nothing.
+ *
+ * Exists so a rotation can tell *"this envelope belongs to a DIFFERENT DEK slot
+ * the caller also holds"* from *"this envelope is damaged"* (#1125). Those two
+ * look identical from a failed `rekeyEnvelopeIfNeeded`, and collapsing them
+ * either aborts a legitimate rotation or walks past unreadable data.
+ *
+ * **The question is deliberately asked of the KEY, not of the envelope's claimed
+ * `_tier`.** `_tier` is unencrypted — the store writes it — so routing a
+ * rotation on it would let a store mark a tier-0 record `_tier: 5` and have the
+ * rotation skip it, leaving a revoked member's DEK live on real data. That is
+ * #1115's defect wearing a different hat. A key either opens the body or it does
+ * not, and a store cannot forge that.
+ *
+ * Mirrors `rekeyBlobSet`'s `otherDeks` treatment, which asks the same question
+ * about the same kind of ambiguity.
+ */
+export declare function envelopeOpensUnderAny(ref: {
+    readonly collection: string;
+    readonly id: string;
+}, envelope: EncryptedEnvelope, keys: readonly EnclaveKey[]): Promise<boolean>;

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

@@ -16,6 +16,7 @@
  * vault; it calls into these.
  */
 import { type EncryptedEnvelope } from '../../types.js';
+import type { RecordRef } from '../record-aad.js';
 /**
  * Shape-only tombstone recognition for layers that have no per-collection
  * context (the sync engine, #590): a tombstone carries an empty `_data` and
@@ -45,7 +46,7 @@ export declare function isTombstone(envelope: EncryptedEnvelope, encrypted: bool
  * Deliberately omits `_iv`/`_data`/`_cek`/`_det` — that omission *is* the
  * erasure.
  */
-export declare function buildTombstone(version: number, actor: string): EncryptedEnvelope;
+export declare function buildTombstone(ref: RecordRef, 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;
 /**
@@ -54,4 +55,4 @@ export declare function isDeleteMarker(envelope: EncryptedEnvelope): boolean;
  * 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;
+export declare function buildDeleteMarker(ref: RecordRef, version: number, actor: string): EncryptedEnvelope;