@tearleads/client-sdk 0.0.0-stage → 0.1.13

package/data/documents/shared/keyringLogWalk.d.ts

@@ -0,0 +1,45 @@
+import type { ContainerKekKeyringEntry } from "../../../internal/crypto/index.js";
+import type { ContainerKekLogEpochResponse } from "../../../internal/validators/response/index.js";
+/**
+ * A whole rotation log assembled from pages. Distinct from the wire type,
+ * which describes ONE bounded page and rejects more epochs than a page may
+ * carry — an aggregate legitimately exceeds that.
+ */
+export interface AggregatedContainerKekLog {
+    readonly containerId: string;
+    readonly epochs: ContainerKekLogEpochResponse[];
+}
+export interface KeyringRebuildResult {
+    /** Recovered entries in ascending epoch order, gaps omitted. */
+    readonly entries: ContainerKekKeyringEntry[];
+    /**
+     * Epoch ids the log could not reach — a severed bridge below them with no
+     * anchor supplied. A repair is only complete when this is empty; each id
+     * here is recoverable through `recoverKeyringEntryFromWraps` and can be
+     * fed back as an anchor.
+     */
+    readonly missingEpochIds: string[];
+}
+/**
+ * Rebuilds the container's keyring entries from the append-only bridge log —
+ * the recovery path when a served keyring fails verification. Each link was
+ * written once by the rotator that provably held both keys, so the walk
+ * depends only on server-persisted state plus the current KEK; every
+ * recovered key is checked against the material-id commitment its epoch id
+ * carries.
+ *
+ * A severed bridge does not abort the walk. Recovery resumes below the gap
+ * from any `anchorKeysByEpochId` entry the caller wrap-recovered, so a
+ * multi-epoch history with a damaged middle link is rebuilt segment by
+ * segment rather than lost wholesale. Unreachable epochs are reported in
+ * `missingEpochIds` instead of throwing, because a partial rebuild plus a
+ * named gap is strictly more useful to a repair than an exception.
+ */
+export declare function rebuildKeyringEntriesFromLog(input: {
+    /** Wrap-recovered keys that re-anchor the walk below a severed bridge. */
+    anchorKeysByEpochId?: ReadonlyMap<string, Uint8Array> | undefined;
+    containerId: string;
+    currentContainerKey: Uint8Array;
+    currentContainerKeyEpochId: string;
+    log: AggregatedContainerKekLog;
+}): Promise<KeyringRebuildResult>;

package/data/documents/shared/keyringLogWalk.js

@@ -0,0 +1,204 @@
+import { computeContainerKekMaterialId, normalizeContainerKekKeyring, normalizeContainerKekPredecessorBridge, openContainerKekKeyring, unwrapContainerKekPredecessorBridge, } from "../../../internal/crypto/index.js";
+/**
+ * Recovers a predecessor key through one bridge, or null when the link is
+ * absent, malformed, undecryptable, or decrypts to material that contradicts
+ * the epoch id's commitment. The commitment check lives HERE, before the
+ * caller's anchor fallback, so a lying link can never mask a valid anchor.
+ */
+async function keyFromBridge(input) {
+    if (input.epoch.bridge === null) {
+        return null;
+    }
+    let key;
+    try {
+        const bridge = normalizeContainerKekPredecessorBridge(input.epoch.bridge);
+        if (bridge.containerId !== input.containerId ||
+            bridge.successorContainerKeyEpochId !== input.epoch.containerKeyEpochId ||
+            bridge.predecessorContainerKeyEpochId !==
+                input.predecessor.containerKeyEpochId) {
+            return null;
+        }
+        key = await unwrapContainerKekPredecessorBridge({
+            bridge,
+            successorContainerKey: input.successorKey,
+        });
+    }
+    catch {
+        return null;
+    }
+    const bridgedId = await computeContainerKekMaterialId({
+        containerId: input.containerId,
+        keyEpoch: input.predecessor.containerKeyEpoch,
+        keyMaterial: key,
+    });
+    return bridgedId === input.predecessor.containerKeyEpochId ? key : null;
+}
+/**
+ * Harvests one epoch's served keyring, given that epoch's key, recording every
+ * epoch it seals. This is the rung of the recovery ladder that crosses MORE
+ * THAN ONE severed bridge: the bridge walk can only step over a gap it holds
+ * an anchor for, while a keyring supplies the entire history beneath its epoch
+ * in a single decrypt.
+ *
+ * It is called for each epoch as that epoch BECOMES reachable — from the
+ * current key at the head, from a caller-supplied anchor, or from a key the
+ * bridge walk itself just recovered — because a keyring sitting below an
+ * intact prefix is only openable once the walk has descended to it. A one-shot
+ * pre-pass would miss exactly those.
+ *
+ * Each recovered entry must match the material-id commitment carried by the
+ * epoch id it claims, so a forged keyring contributes nothing. Failures are
+ * silent: this accelerates recovery, and the bridge walk remains the
+ * correctness-bearing path.
+ */
+async function harvestServedKeyring(input) {
+    if (input.epoch.keyring === null) {
+        return;
+    }
+    let entries;
+    try {
+        entries = await openContainerKekKeyring({
+            keyEpoch: input.epoch.containerKeyEpoch,
+            keyring: normalizeContainerKekKeyring(input.epoch.keyring),
+            successorContainerKey: input.epochKey,
+        });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const sealed = input.epochById.get(entry.containerKeyEpochId);
+        if (!sealed || input.recovered.has(entry.containerKeyEpochId)) {
+            continue;
+        }
+        const materialId = await computeContainerKekMaterialId({
+            containerId: input.containerId,
+            keyEpoch: sealed.containerKeyEpoch,
+            keyMaterial: entry.keyMaterial,
+        });
+        if (materialId === entry.containerKeyEpochId) {
+            input.recovered.set(entry.containerKeyEpochId, entry.keyMaterial);
+        }
+    }
+}
+/**
+ * The log's epochs in ascending order, once it is established that they are a
+ * complete history for this container: same container, rooted at epoch 1, and
+ * ending at the caller's current epoch. A rebuild that started mid-history
+ * would silently report the epochs below its start as unreachable, so the
+ * shape is checked up front rather than inferred from a thin result.
+ */
+async function sortedCompleteLogEpochs(input) {
+    if (input.log.containerId !== input.containerId) {
+        throw new Error("Container KEK log container is inconsistent");
+    }
+    const epochs = [...input.log.epochs].sort((left, right) => left.containerKeyEpoch - right.containerKeyEpoch);
+    const genesis = epochs[0];
+    const tail = epochs.at(-1);
+    if (genesis?.containerKeyEpoch !== 1) {
+        throw new Error("Container KEK log does not start at epoch 1");
+    }
+    if (!tail || tail.containerKeyEpochId !== input.currentContainerKeyEpochId) {
+        throw new Error("Container KEK log does not end at the current epoch");
+    }
+    if ((await computeContainerKekMaterialId({
+        containerId: input.containerId,
+        keyEpoch: tail.containerKeyEpoch,
+        keyMaterial: input.currentContainerKey,
+    })) !== input.currentContainerKeyEpochId) {
+        throw new Error("Container KEK log current key material does not match its epoch");
+    }
+    return epochs;
+}
+/**
+ * Rebuilds the container's keyring entries from the append-only bridge log —
+ * the recovery path when a served keyring fails verification. Each link was
+ * written once by the rotator that provably held both keys, so the walk
+ * depends only on server-persisted state plus the current KEK; every
+ * recovered key is checked against the material-id commitment its epoch id
+ * carries.
+ *
+ * A severed bridge does not abort the walk. Recovery resumes below the gap
+ * from any `anchorKeysByEpochId` entry the caller wrap-recovered, so a
+ * multi-epoch history with a damaged middle link is rebuilt segment by
+ * segment rather than lost wholesale. Unreachable epochs are reported in
+ * `missingEpochIds` instead of throwing, because a partial rebuild plus a
+ * named gap is strictly more useful to a repair than an exception.
+ */
+export async function rebuildKeyringEntriesFromLog(input) {
+    const epochs = await sortedCompleteLogEpochs(input);
+    const anchors = input.anchorKeysByEpochId ?? new Map();
+    const recovered = new Map();
+    const missingEpochIds = [];
+    let successorKey = input.currentContainerKey;
+    const epochById = new Map(epochs.map((epoch) => [epoch.containerKeyEpochId, epoch]));
+    for (let index = epochs.length - 1; index >= 1; index -= 1) {
+        const epoch = epochs[index];
+        const predecessor = epochs[index - 1];
+        if (!epoch ||
+            !predecessor ||
+            epoch.containerKeyEpoch !== predecessor.containerKeyEpoch + 1) {
+            throw new Error("Container KEK log is not contiguous");
+        }
+        // Harvest this epoch's keyring the moment the epoch is reachable — from
+        // the current key at the head, an anchor, or a key the walk just
+        // recovered. Doing it here rather than in a pre-pass is what lets a
+        // keyring BELOW an intact prefix repair severed bridges under itself.
+        const epochKey = successorKey ??
+            recovered.get(epoch.containerKeyEpochId) ??
+            anchors.get(epoch.containerKeyEpochId) ??
+            null;
+        if (epochKey) {
+            await harvestServedKeyring({
+                containerId: input.containerId,
+                epoch,
+                epochById,
+                epochKey,
+                recovered,
+            });
+        }
+        // Severed, poisoned, or lying links all degrade to "no key from the
+        // bridge"; the walk then picks back up from a wrap-recovered anchor if
+        // the caller supplied one, so only truly unreachable epochs are lost.
+        let predecessorKey = epochKey === null
+            ? null
+            : await keyFromBridge({
+                containerId: input.containerId,
+                epoch,
+                predecessor,
+                successorKey: epochKey,
+            });
+        predecessorKey ??= recovered.get(predecessor.containerKeyEpochId) ?? null;
+        predecessorKey ??= anchors.get(predecessor.containerKeyEpochId) ?? null;
+        if (predecessorKey === null) {
+            missingEpochIds.push(predecessor.containerKeyEpochId);
+            successorKey = null;
+            continue;
+        }
+        const expectedId = await computeContainerKekMaterialId({
+            containerId: input.containerId,
+            keyEpoch: predecessor.containerKeyEpoch,
+            keyMaterial: predecessorKey,
+        });
+        if (expectedId !== predecessor.containerKeyEpochId) {
+            // Only reachable when a supplied anchor is itself wrong.
+            missingEpochIds.push(predecessor.containerKeyEpochId);
+            successorKey = null;
+            continue;
+        }
+        recovered.set(predecessor.containerKeyEpochId, predecessorKey);
+        successorKey = predecessorKey;
+    }
+    const entries = [];
+    for (const epoch of epochs.slice(0, -1)) {
+        const keyMaterial = recovered.get(epoch.containerKeyEpochId);
+        if (keyMaterial) {
+            entries.push({
+                containerKeyEpochId: epoch.containerKeyEpochId,
+                keyMaterial,
+            });
+        }
+    }
+    return { entries, missingEpochIds: missingEpochIds.reverse() };
+}
+//# sourceMappingURL=keyringLogWalk.js.map

package/data/documents/shared/keyringLogWalk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyringLogWalk.js","sourceRoot":"","sources":["keyringLogWalk.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ContainerKekKeyringEntry } from \"@tearleads/crypto\";\nimport {\n  computeContainerKekMaterialId,\n  normalizeContainerKekKeyring,\n  normalizeContainerKekPredecessorBridge,\n  openContainerKekKeyring,\n  unwrapContainerKekPredecessorBridge,\n} from \"@tearleads/crypto\";\nimport type { ContainerKekLogEpochResponse } from \"@tearleads/validators/response\";\n\n/**\n * A whole rotation log assembled from pages. Distinct from the wire type,\n * which describes ONE bounded page and rejects more epochs than a page may\n * carry — an aggregate legitimately exceeds that.\n */\nexport interface AggregatedContainerKekLog {\n  readonly containerId: string;\n  readonly epochs: ContainerKekLogEpochResponse[];\n}\n\n/**\n * Recovers a predecessor key through one bridge, or null when the link is\n * absent, malformed, undecryptable, or decrypts to material that contradicts\n * the epoch id's commitment. The commitment check lives HERE, before the\n * caller's anchor fallback, so a lying link can never mask a valid anchor.\n */\nasync function keyFromBridge(input: {\n  containerId: string;\n  epoch: ContainerKekLogEpochResponse;\n  predecessor: ContainerKekLogEpochResponse;\n  successorKey: Uint8Array;\n}): Promise<Uint8Array | null> {\n  if (input.epoch.bridge === null) {\n    return null;\n  }\n  let key: Uint8Array;\n  try {\n    const bridge = normalizeContainerKekPredecessorBridge(input.epoch.bridge);\n    if (\n      bridge.containerId !== input.containerId ||\n      bridge.successorContainerKeyEpochId !== input.epoch.containerKeyEpochId ||\n      bridge.predecessorContainerKeyEpochId !==\n        input.predecessor.containerKeyEpochId\n    ) {\n      return null;\n    }\n    key = await unwrapContainerKekPredecessorBridge({\n      bridge,\n      successorContainerKey: input.successorKey,\n    });\n  } catch {\n    return null;\n  }\n  const bridgedId = await computeContainerKekMaterialId({\n    containerId: input.containerId,\n    keyEpoch: input.predecessor.containerKeyEpoch,\n    keyMaterial: key,\n  });\n  return bridgedId === input.predecessor.containerKeyEpochId ? key : null;\n}\n\n/**\n * Harvests one epoch's served keyring, given that epoch's key, recording every\n * epoch it seals. This is the rung of the recovery ladder that crosses MORE\n * THAN ONE severed bridge: the bridge walk can only step over a gap it holds\n * an anchor for, while a keyring supplies the entire history beneath its epoch\n * in a single decrypt.\n *\n * It is called for each epoch as that epoch BECOMES reachable — from the\n * current key at the head, from a caller-supplied anchor, or from a key the\n * bridge walk itself just recovered — because a keyring sitting below an\n * intact prefix is only openable once the walk has descended to it. A one-shot\n * pre-pass would miss exactly those.\n *\n * Each recovered entry must match the material-id commitment carried by the\n * epoch id it claims, so a forged keyring contributes nothing. Failures are\n * silent: this accelerates recovery, and the bridge walk remains the\n * correctness-bearing path.\n */\nasync function harvestServedKeyring(input: {\n  containerId: string;\n  epoch: ContainerKekLogEpochResponse;\n  epochById: ReadonlyMap<string, ContainerKekLogEpochResponse>;\n  epochKey: Uint8Array;\n  recovered: Map<string, Uint8Array>;\n}): Promise<void> {\n  if (input.epoch.keyring === null) {\n    return;\n  }\n\n  let entries: ContainerKekKeyringEntry[];\n  try {\n    entries = await openContainerKekKeyring({\n      keyEpoch: input.epoch.containerKeyEpoch,\n      keyring: normalizeContainerKekKeyring(input.epoch.keyring),\n      successorContainerKey: input.epochKey,\n    });\n  } catch {\n    return;\n  }\n\n  for (const entry of entries) {\n    const sealed = input.epochById.get(entry.containerKeyEpochId);\n    if (!sealed || input.recovered.has(entry.containerKeyEpochId)) {\n      continue;\n    }\n    const materialId = await computeContainerKekMaterialId({\n      containerId: input.containerId,\n      keyEpoch: sealed.containerKeyEpoch,\n      keyMaterial: entry.keyMaterial,\n    });\n    if (materialId === entry.containerKeyEpochId) {\n      input.recovered.set(entry.containerKeyEpochId, entry.keyMaterial);\n    }\n  }\n}\n\n/**\n * The log's epochs in ascending order, once it is established that they are a\n * complete history for this container: same container, rooted at epoch 1, and\n * ending at the caller's current epoch. A rebuild that started mid-history\n * would silently report the epochs below its start as unreachable, so the\n * shape is checked up front rather than inferred from a thin result.\n */\nasync function sortedCompleteLogEpochs(input: {\n  currentContainerKey: Uint8Array;\n  containerId: string;\n  currentContainerKeyEpochId: string;\n  log: AggregatedContainerKekLog;\n}): Promise<ContainerKekLogEpochResponse[]> {\n  if (input.log.containerId !== input.containerId) {\n    throw new Error(\"Container KEK log container is inconsistent\");\n  }\n  const epochs = [...input.log.epochs].sort(\n    (left, right) => left.containerKeyEpoch - right.containerKeyEpoch,\n  );\n  const genesis = epochs[0];\n  const tail = epochs.at(-1);\n  if (genesis?.containerKeyEpoch !== 1) {\n    throw new Error(\"Container KEK log does not start at epoch 1\");\n  }\n  if (!tail || tail.containerKeyEpochId !== input.currentContainerKeyEpochId) {\n    throw new Error(\"Container KEK log does not end at the current epoch\");\n  }\n  if (\n    (await computeContainerKekMaterialId({\n      containerId: input.containerId,\n      keyEpoch: tail.containerKeyEpoch,\n      keyMaterial: input.currentContainerKey,\n    })) !== input.currentContainerKeyEpochId\n  ) {\n    throw new Error(\n      \"Container KEK log current key material does not match its epoch\",\n    );\n  }\n  return epochs;\n}\n\nexport interface KeyringRebuildResult {\n  /** Recovered entries in ascending epoch order, gaps omitted. */\n  readonly entries: ContainerKekKeyringEntry[];\n  /**\n   * Epoch ids the log could not reach — a severed bridge below them with no\n   * anchor supplied. A repair is only complete when this is empty; each id\n   * here is recoverable through `recoverKeyringEntryFromWraps` and can be\n   * fed back as an anchor.\n   */\n  readonly missingEpochIds: string[];\n}\n\n/**\n * Rebuilds the container's keyring entries from the append-only bridge log —\n * the recovery path when a served keyring fails verification. Each link was\n * written once by the rotator that provably held both keys, so the walk\n * depends only on server-persisted state plus the current KEK; every\n * recovered key is checked against the material-id commitment its epoch id\n * carries.\n *\n * A severed bridge does not abort the walk. Recovery resumes below the gap\n * from any `anchorKeysByEpochId` entry the caller wrap-recovered, so a\n * multi-epoch history with a damaged middle link is rebuilt segment by\n * segment rather than lost wholesale. Unreachable epochs are reported in\n * `missingEpochIds` instead of throwing, because a partial rebuild plus a\n * named gap is strictly more useful to a repair than an exception.\n */\nexport async function rebuildKeyringEntriesFromLog(input: {\n  /** Wrap-recovered keys that re-anchor the walk below a severed bridge. */\n  anchorKeysByEpochId?: ReadonlyMap<string, Uint8Array> | undefined;\n  containerId: string;\n  currentContainerKey: Uint8Array;\n  currentContainerKeyEpochId: string;\n  log: AggregatedContainerKekLog;\n}): Promise<KeyringRebuildResult> {\n  const epochs = await sortedCompleteLogEpochs(input);\n\n  const anchors = input.anchorKeysByEpochId ?? new Map<string, Uint8Array>();\n  const recovered = new Map<string, Uint8Array>();\n  const missingEpochIds: string[] = [];\n  let successorKey: Uint8Array | null = input.currentContainerKey;\n\n  const epochById = new Map(\n    epochs.map((epoch) => [epoch.containerKeyEpochId, epoch]),\n  );\n\n  for (let index = epochs.length - 1; index >= 1; index -= 1) {\n    const epoch = epochs[index];\n    const predecessor = epochs[index - 1];\n    if (\n      !epoch ||\n      !predecessor ||\n      epoch.containerKeyEpoch !== predecessor.containerKeyEpoch + 1\n    ) {\n      throw new Error(\"Container KEK log is not contiguous\");\n    }\n\n    // Harvest this epoch's keyring the moment the epoch is reachable — from\n    // the current key at the head, an anchor, or a key the walk just\n    // recovered. Doing it here rather than in a pre-pass is what lets a\n    // keyring BELOW an intact prefix repair severed bridges under itself.\n    const epochKey: Uint8Array | null =\n      successorKey ??\n      recovered.get(epoch.containerKeyEpochId) ??\n      anchors.get(epoch.containerKeyEpochId) ??\n      null;\n    if (epochKey) {\n      await harvestServedKeyring({\n        containerId: input.containerId,\n        epoch,\n        epochById,\n        epochKey,\n        recovered,\n      });\n    }\n\n    // Severed, poisoned, or lying links all degrade to \"no key from the\n    // bridge\"; the walk then picks back up from a wrap-recovered anchor if\n    // the caller supplied one, so only truly unreachable epochs are lost.\n    let predecessorKey: Uint8Array | null =\n      epochKey === null\n        ? null\n        : await keyFromBridge({\n            containerId: input.containerId,\n            epoch,\n            predecessor,\n            successorKey: epochKey,\n          });\n    predecessorKey ??= recovered.get(predecessor.containerKeyEpochId) ?? null;\n    predecessorKey ??= anchors.get(predecessor.containerKeyEpochId) ?? null;\n\n    if (predecessorKey === null) {\n      missingEpochIds.push(predecessor.containerKeyEpochId);\n      successorKey = null;\n      continue;\n    }\n    const expectedId = await computeContainerKekMaterialId({\n      containerId: input.containerId,\n      keyEpoch: predecessor.containerKeyEpoch,\n      keyMaterial: predecessorKey,\n    });\n    if (expectedId !== predecessor.containerKeyEpochId) {\n      // Only reachable when a supplied anchor is itself wrong.\n      missingEpochIds.push(predecessor.containerKeyEpochId);\n      successorKey = null;\n      continue;\n    }\n    recovered.set(predecessor.containerKeyEpochId, predecessorKey);\n    successorKey = predecessorKey;\n  }\n\n  const entries: ContainerKekKeyringEntry[] = [];\n  for (const epoch of epochs.slice(0, -1)) {\n    const keyMaterial = recovered.get(epoch.containerKeyEpochId);\n    if (keyMaterial) {\n      entries.push({\n        containerKeyEpochId: epoch.containerKeyEpochId,\n        keyMaterial,\n      });\n    }\n  }\n  return { entries, missingEpochIds: missingEpochIds.reverse() };\n}\n"]}

package/data/documents/shared/keyringRebuild.d.ts

@@ -0,0 +1,60 @@
+import type { ContainerKekKeyringEntry } from "../../../internal/crypto/index.js";
+import type { ContainerKekLogEpochResponse } from "../../../internal/validators/response/index.js";
+import type { ExecSql } from "../../sqlite/sqlSchema.js";
+/**
+ * Raised when the requester holds no envelope they can open for a historical
+ * epoch. Distinct from corruption: the log is intact, the caller simply is
+ * not an anchor for this epoch.
+ */
+export type HistoricalWrapUnavailableReason = 
+/** No envelope at this epoch is addressed to the requester at all. */
+"no-addressed-envelope"
+/** A direct user envelope exists for the requester but did not open. */
+ | "corrupt-envelope"
+/** Only principal-addressed envelopes, whose key epoch is unreachable. */
+ | "principal-key-unreachable"
+/** Only a parent-container envelope, and the parent KEK was not supplied. */
+ | "parent-key-unavailable";
+export declare class HistoricalWrapUnavailableError extends Error {
+    readonly containerKeyEpoch: number;
+    readonly reason: HistoricalWrapUnavailableReason;
+    constructor(containerKeyEpoch: number, reason: HistoricalWrapUnavailableReason, cause?: unknown);
+}
+/**
+ * The severed-bridge backstop: recovers one historical epoch's KEK from the
+ * requester's own retained recipient envelope served in the kek-log. Wraps
+ * are written by that epoch's rotator and never deleted, so this path is
+ * independent of every later rotation — it works even when the bridge chain
+ * above the epoch is destroyed. The recovered key is verified against the
+ * epoch id's material commitment before use.
+ *
+ * Scope bound: a direct user envelope is recoverable from identity keys
+ * alone, so a pristine client anchors on it. A group- or organization-
+ * addressed envelope additionally requires the current principal secret key.
+ * Principal rotation rematerializes every retained container grant against
+ * the new principal head, so a current reader never needs an older principal
+ * key to use this recovery path. Unreachable principal keys fail closed with
+ * `HistoricalWrapUnavailableError` rather than appearing to be corruption.
+ */
+export declare function recoverKeyringEntryFromWraps(input: {
+    containerId: string;
+    epoch: Pick<ContainerKekLogEpochResponse, "containerKeyEpoch" | "containerKeyEpochId" | "wraps">;
+    execSql?: ExecSql | undefined;
+    secretKey: Uint8Array;
+    /**
+     * Parent container KEKs by epoch id. An inherited-only child has no direct
+     * or principal envelope of its own; its anchor is the parent-container
+     * wrap, which opens under the parent epoch's KEK. Recover the parent's
+     * epoch first (recursively, through the parent's own log) and pass it here.
+     */
+    parentKeysByEpochId?: ReadonlyMap<string, Uint8Array> | undefined;
+    /**
+     * The requester's user id. Direct user envelopes are matched against it, so
+     * another member's envelope is never mistaken for an anchor — attempting it
+     * would only produce a misleading failure.
+     */
+    userId: string;
+}): Promise<ContainerKekKeyringEntry>;
+export { fetchContainerKekLog } from "./containerKekLogFetch.js";
+export type { AggregatedContainerKekLog, KeyringRebuildResult, } from "./keyringLogWalk.js";
+export { rebuildKeyringEntriesFromLog } from "./keyringLogWalk.js";

package/data/documents/shared/keyringRebuild.js

@@ -0,0 +1,242 @@
+import { computeContainerKekMaterialId, unwrapContainerKekParentWrap, } from "../../../internal/crypto/index.js";
+import { unwrapKeyEnvelopesWithPrincipalPolicies } from "../../principals/principalPolicyCrypto.js";
+import { normalizeContainerKeyWrap } from "./readers.js";
+/**
+ * Splits an epoch's envelopes into the anchor kinds this requester could use:
+ * their own direct envelope, principal envelopes their policies may resolve,
+ * and parent-container envelopes. Anything else is not an identity anchor and
+ * is dropped, so it never produces a misleading failure.
+ */
+function partitionAnchorWraps(wraps, containerKeyEpochId, userId) {
+    const forEpoch = wraps
+        .map((wrap) => normalizeContainerKeyWrap(wrap))
+        .filter((wrap) => wrap.containerKeyEpochId === containerKeyEpochId);
+    const directWraps = forEpoch.filter((wrap) => wrap.recipientKind === "user" && wrap.recipientId === userId);
+    const principalWraps = forEpoch.filter((wrap) => wrap.recipientKind === "group");
+    const parentWraps = forEpoch.filter((wrap) => wrap.recipientKind === "container");
+    return {
+        directWraps,
+        epochWraps: [...directWraps, ...principalWraps, ...parentWraps],
+        parentWraps,
+        principalWraps,
+    };
+}
+/**
+ * Opens the first parent-container envelope whose parent epoch key the caller
+ * supplied. Reports whether any key was available, so a missing parent key is
+ * distinguishable from a corrupt envelope.
+ */
+async function openParentAnchor(parentWraps, parentKeys) {
+    let failure;
+    let keyWasAvailable = false;
+    for (const wrap of parentWraps) {
+        const parentKey = parentKeys.get(wrap.recipientKeyEpochId);
+        if (!parentKey) {
+            continue;
+        }
+        keyWasAvailable = true;
+        try {
+            return {
+                failure: undefined,
+                key: await unwrapContainerKekParentWrap({
+                    parentContainerId: wrap.recipientId,
+                    parentKeyMaterial: parentKey,
+                    kemCipherText: wrap.kemCipherText,
+                    wrappedKey: wrap.wrappedKey,
+                }),
+                keyWasAvailable,
+            };
+        }
+        catch (error) {
+            failure = error;
+        }
+    }
+    return { failure, key: null, keyWasAvailable };
+}
+/**
+ * Every anchor kind was tried; report the most specific reason. A wrap that
+ * was actually attempted and failed is corruption; one that could not be
+ * attempted names the key that was missing.
+ */
+function throwMostSpecificAnchorFailure(input) {
+    if (input.directFailure !== undefined || input.parentFailure !== undefined) {
+        throw new HistoricalWrapUnavailableError(input.containerKeyEpoch, "corrupt-envelope", input.directFailure ?? input.parentFailure);
+    }
+    if (input.principalFailure !== undefined) {
+        throw new HistoricalWrapUnavailableError(input.containerKeyEpoch, "principal-key-unreachable", input.principalFailure);
+    }
+    throw new HistoricalWrapUnavailableError(input.containerKeyEpoch, input.hadParentWraps && !input.parentKeyWasAvailable
+        ? "parent-key-unavailable"
+        : "no-addressed-envelope");
+}
+const HISTORICAL_WRAP_UNAVAILABLE_MESSAGES = {
+    "no-addressed-envelope": (epoch) => `Container KEK log has no envelope addressed to this requester at epoch ${epoch}`,
+    "corrupt-envelope": (epoch) => `Container KEK log envelope for this requester at epoch ${epoch} could not be opened`,
+    "principal-key-unreachable": (epoch) => `Container KEK log envelope at epoch ${epoch} is addressed to a principal key epoch this client cannot resolve`,
+    "parent-key-unavailable": (epoch) => `Container KEK log envelope at epoch ${epoch} is inherited from a parent container whose KEK was not supplied`,
+};
+export class HistoricalWrapUnavailableError extends Error {
+    containerKeyEpoch;
+    reason;
+    constructor(containerKeyEpoch, reason, cause) {
+        super(HISTORICAL_WRAP_UNAVAILABLE_MESSAGES[reason](containerKeyEpoch), cause === undefined ? undefined : { cause });
+        this.containerKeyEpoch = containerKeyEpoch;
+        this.reason = reason;
+        this.name = "HistoricalWrapUnavailableError";
+    }
+}
+/**
+ * The first candidate envelope that both decrypts AND matches the epoch's
+ * material-id commitment.
+ *
+ * Candidates are tried ONE AT A TIME. An envelope can be AEAD-valid and still
+ * carry the WRONG key — a stale or misaddressed wrap — so decrypting a batch
+ * together would let that one envelope answer for the whole group and mask a
+ * later envelope that would have opened the epoch. The reported failure is the
+ * first real decrypt failure, since a commitment mismatch is a wrong envelope
+ * rather than an unreachable one.
+ */
+async function firstCommittedAnchor(input) {
+    let firstFailure;
+    for (const candidate of input.candidates) {
+        const result = await input.attempt([candidate]);
+        if (result.key === null) {
+            firstFailure ??= result.failure;
+            continue;
+        }
+        const materialId = await computeContainerKekMaterialId({
+            containerId: input.containerId,
+            keyEpoch: input.containerKeyEpoch,
+            keyMaterial: result.key,
+        });
+        if (materialId === input.containerKeyEpochId) {
+            return result;
+        }
+        // An envelope that decrypts to the WRONG key is a misaddressed or stale
+        // envelope, not an unreachable principal. Recording it keeps the reported
+        // reason `corrupt-envelope`; dropping it silently would let the epoch
+        // report as unaddressed, which points a repair at the wrong problem.
+        //
+        // Only reachable when the server files a wrap under an epoch id its
+        // material does not hash to — the addressing filter already rejects a
+        // wrap whose epoch id simply differs.
+        firstFailure ??= new Error(`Container KEK envelope decrypts to material that is not epoch ${input.containerKeyEpochId}`);
+    }
+    return { failure: firstFailure, key: null };
+}
+/**
+ * Opens one group of envelopes with the requester's CURRENT policies, folding
+ * failure into a value rather than throwing.
+ *
+ * The caller tries several groups in order, and a failure in one is not the
+ * end of the search — so the failure has to travel back alongside the miss
+ * instead of unwinding the whole recovery.
+ */
+async function unwrapWrapsWithCurrentPolicies(input) {
+    if (input.wraps.length === 0) {
+        return { failure: undefined, key: null };
+    }
+    try {
+        return {
+            failure: undefined,
+            key: await unwrapKeyEnvelopesWithPrincipalPolicies({
+                envelopes: input.wraps.map((wrap) => ({
+                    keyFingerprint: wrap.recipientKeyFingerprint,
+                    kemCipherText: wrap.kemCipherText,
+                    wrappedKey: wrap.wrappedKey,
+                })),
+                execSql: input.execSql,
+                secretKey: input.secretKey,
+            }),
+        };
+    }
+    catch (error) {
+        return { failure: error, key: null };
+    }
+}
+/**
+ * The severed-bridge backstop: recovers one historical epoch's KEK from the
+ * requester's own retained recipient envelope served in the kek-log. Wraps
+ * are written by that epoch's rotator and never deleted, so this path is
+ * independent of every later rotation — it works even when the bridge chain
+ * above the epoch is destroyed. The recovered key is verified against the
+ * epoch id's material commitment before use.
+ *
+ * Scope bound: a direct user envelope is recoverable from identity keys
+ * alone, so a pristine client anchors on it. A group- or organization-
+ * addressed envelope additionally requires the current principal secret key.
+ * Principal rotation rematerializes every retained container grant against
+ * the new principal head, so a current reader never needs an older principal
+ * key to use this recovery path. Unreachable principal keys fail closed with
+ * `HistoricalWrapUnavailableError` rather than appearing to be corruption.
+ */
+export async function recoverKeyringEntryFromWraps(input) {
+    const { directWraps, epochWraps, parentWraps, principalWraps } = partitionAnchorWraps(input.epoch.wraps, input.epoch.containerKeyEpochId, input.userId);
+    if (epochWraps.length === 0) {
+        throw new HistoricalWrapUnavailableError(input.epoch.containerKeyEpoch, "no-addressed-envelope");
+    }
+    const attempt = (wraps) => unwrapWrapsWithCurrentPolicies({
+        execSql: input.execSql,
+        secretKey: input.secretKey,
+        wraps,
+    });
+    // A direct envelope is decryptable from identity keys alone, so its failure
+    // means corruption — not an unreachable principal key. Neither failure ends
+    // the search: a parent-container wrap may still anchor this epoch.
+    //
+    // Candidates are tried ONE AT A TIME, and each must match the epoch's
+    // material-id commitment rather than merely decrypt. An envelope can be
+    // AEAD-valid and still carry the WRONG key — a stale or misaddressed wrap —
+    // so batching would let that one envelope answer for the whole group and
+    // mask a later envelope that would have opened the epoch.
+    const attemptCommitted = (candidates) => firstCommittedAnchor({
+        attempt,
+        candidates,
+        containerId: input.containerId,
+        containerKeyEpoch: input.epoch.containerKeyEpoch,
+        containerKeyEpochId: input.epoch.containerKeyEpochId,
+    });
+    const direct = await attemptCommitted(directWraps);
+    let keyMaterial = direct.key;
+    const directFailure = direct.failure;
+    let principalFailure;
+    if (keyMaterial === null) {
+        const principal = await attemptCommitted(principalWraps);
+        keyMaterial = principal.key;
+        // Preserve the current-policy failure in case no inherited anchor opens.
+        principalFailure = principal.failure;
+    }
+    // The inherited-only path: a parent-container envelope opens under the
+    // parent epoch's KEK, which the caller recovers from the parent's own log.
+    const parent = keyMaterial === null
+        ? await openParentAnchor(parentWraps, input.parentKeysByEpochId ?? new Map())
+        : { failure: undefined, key: null, keyWasAvailable: false };
+    keyMaterial ??= parent.key;
+    const parentFailure = parent.failure;
+    const parentKeyWasAvailable = parent.keyWasAvailable;
+    if (keyMaterial === null) {
+        throwMostSpecificAnchorFailure({
+            containerKeyEpoch: input.epoch.containerKeyEpoch,
+            directFailure,
+            hadParentWraps: parentWraps.length > 0,
+            parentFailure,
+            parentKeyWasAvailable,
+            principalFailure,
+        });
+    }
+    const expectedId = await computeContainerKekMaterialId({
+        containerId: input.containerId,
+        keyEpoch: input.epoch.containerKeyEpoch,
+        keyMaterial,
+    });
+    if (expectedId !== input.epoch.containerKeyEpochId) {
+        throw new Error(`Container KEK log wrap does not match its committed epoch id at epoch ${input.epoch.containerKeyEpoch}`);
+    }
+    return {
+        containerKeyEpochId: input.epoch.containerKeyEpochId,
+        keyMaterial,
+    };
+}
+export { fetchContainerKekLog } from "./containerKekLogFetch.js";
+export { rebuildKeyringEntriesFromLog } from "./keyringLogWalk.js";
+//# sourceMappingURL=keyringRebuild.js.map

package/data/documents/shared/keyringRebuild.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyringRebuild.js","sourceRoot":"","sources":["keyringRebuild.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  ContainerKekKeyringEntry,\n  ContainerKeyWrap,\n} from \"@tearleads/crypto\";\nimport {\n  computeContainerKekMaterialId,\n  unwrapContainerKekParentWrap,\n} from \"@tearleads/crypto\";\nimport type { ContainerKekLogEpochResponse } from \"@tearleads/validators/response\";\nimport { unwrapKeyEnvelopesWithPrincipalPolicies } from \"../../principals/principalPolicyCrypto\";\nimport type { ExecSql } from \"../../sqlite/sqlSchema\";\nimport { normalizeContainerKeyWrap } from \"./readers\";\n\n/**\n * Splits an epoch's envelopes into the anchor kinds this requester could use:\n * their own direct envelope, principal envelopes their policies may resolve,\n * and parent-container envelopes. Anything else is not an identity anchor and\n * is dropped, so it never produces a misleading failure.\n */\nfunction partitionAnchorWraps(\n  wraps: readonly Record<string, unknown>[],\n  containerKeyEpochId: string,\n  userId: string,\n): {\n  directWraps: ContainerKeyWrap[];\n  epochWraps: ContainerKeyWrap[];\n  parentWraps: ContainerKeyWrap[];\n  principalWraps: ContainerKeyWrap[];\n} {\n  const forEpoch = wraps\n    .map((wrap) => normalizeContainerKeyWrap(wrap))\n    .filter((wrap) => wrap.containerKeyEpochId === containerKeyEpochId);\n  const directWraps = forEpoch.filter(\n    (wrap) => wrap.recipientKind === \"user\" && wrap.recipientId === userId,\n  );\n  const principalWraps = forEpoch.filter(\n    (wrap) => wrap.recipientKind === \"group\",\n  );\n  const parentWraps = forEpoch.filter(\n    (wrap) => wrap.recipientKind === \"container\",\n  );\n  return {\n    directWraps,\n    epochWraps: [...directWraps, ...principalWraps, ...parentWraps],\n    parentWraps,\n    principalWraps,\n  };\n}\n\n/**\n * Opens the first parent-container envelope whose parent epoch key the caller\n * supplied. Reports whether any key was available, so a missing parent key is\n * distinguishable from a corrupt envelope.\n */\nasync function openParentAnchor(\n  parentWraps: readonly ContainerKeyWrap[],\n  parentKeys: ReadonlyMap<string, Uint8Array>,\n): Promise<{\n  failure: unknown;\n  key: Uint8Array | null;\n  keyWasAvailable: boolean;\n}> {\n  let failure: unknown;\n  let keyWasAvailable = false;\n  for (const wrap of parentWraps) {\n    const parentKey = parentKeys.get(wrap.recipientKeyEpochId);\n    if (!parentKey) {\n      continue;\n    }\n    keyWasAvailable = true;\n    try {\n      return {\n        failure: undefined,\n        key: await unwrapContainerKekParentWrap({\n          parentContainerId: wrap.recipientId,\n          parentKeyMaterial: parentKey,\n          kemCipherText: wrap.kemCipherText,\n          wrappedKey: wrap.wrappedKey,\n        }),\n        keyWasAvailable,\n      };\n    } catch (error) {\n      failure = error;\n    }\n  }\n  return { failure, key: null, keyWasAvailable };\n}\n\n/**\n * Every anchor kind was tried; report the most specific reason. A wrap that\n * was actually attempted and failed is corruption; one that could not be\n * attempted names the key that was missing.\n */\nfunction throwMostSpecificAnchorFailure(input: {\n  containerKeyEpoch: number;\n  directFailure: unknown;\n  hadParentWraps: boolean;\n  parentFailure: unknown;\n  parentKeyWasAvailable: boolean;\n  principalFailure: unknown;\n}): never {\n  if (input.directFailure !== undefined || input.parentFailure !== undefined) {\n    throw new HistoricalWrapUnavailableError(\n      input.containerKeyEpoch,\n      \"corrupt-envelope\",\n      input.directFailure ?? input.parentFailure,\n    );\n  }\n  if (input.principalFailure !== undefined) {\n    throw new HistoricalWrapUnavailableError(\n      input.containerKeyEpoch,\n      \"principal-key-unreachable\",\n      input.principalFailure,\n    );\n  }\n  throw new HistoricalWrapUnavailableError(\n    input.containerKeyEpoch,\n    input.hadParentWraps && !input.parentKeyWasAvailable\n      ? \"parent-key-unavailable\"\n      : \"no-addressed-envelope\",\n  );\n}\n\n/**\n * Raised when the requester holds no envelope they can open for a historical\n * epoch. Distinct from corruption: the log is intact, the caller simply is\n * not an anchor for this epoch.\n */\nexport type HistoricalWrapUnavailableReason =\n  /** No envelope at this epoch is addressed to the requester at all. */\n  | \"no-addressed-envelope\"\n  /** A direct user envelope exists for the requester but did not open. */\n  | \"corrupt-envelope\"\n  /** Only principal-addressed envelopes, whose key epoch is unreachable. */\n  | \"principal-key-unreachable\"\n  /** Only a parent-container envelope, and the parent KEK was not supplied. */\n  | \"parent-key-unavailable\";\n\nconst HISTORICAL_WRAP_UNAVAILABLE_MESSAGES: Record<\n  HistoricalWrapUnavailableReason,\n  (epoch: number) => string\n> = {\n  \"no-addressed-envelope\": (epoch) =>\n    `Container KEK log has no envelope addressed to this requester at epoch ${epoch}`,\n  \"corrupt-envelope\": (epoch) =>\n    `Container KEK log envelope for this requester at epoch ${epoch} could not be opened`,\n  \"principal-key-unreachable\": (epoch) =>\n    `Container KEK log envelope at epoch ${epoch} is addressed to a principal key epoch this client cannot resolve`,\n  \"parent-key-unavailable\": (epoch) =>\n    `Container KEK log envelope at epoch ${epoch} is inherited from a parent container whose KEK was not supplied`,\n};\n\nexport class HistoricalWrapUnavailableError extends Error {\n  constructor(\n    readonly containerKeyEpoch: number,\n    readonly reason: HistoricalWrapUnavailableReason,\n    cause?: unknown,\n  ) {\n    super(\n      HISTORICAL_WRAP_UNAVAILABLE_MESSAGES[reason](containerKeyEpoch),\n      cause === undefined ? undefined : { cause },\n    );\n    this.name = \"HistoricalWrapUnavailableError\";\n  }\n}\n\n/**\n * The first candidate envelope that both decrypts AND matches the epoch's\n * material-id commitment.\n *\n * Candidates are tried ONE AT A TIME. An envelope can be AEAD-valid and still\n * carry the WRONG key — a stale or misaddressed wrap — so decrypting a batch\n * together would let that one envelope answer for the whole group and mask a\n * later envelope that would have opened the epoch. The reported failure is the\n * first real decrypt failure, since a commitment mismatch is a wrong envelope\n * rather than an unreachable one.\n */\nasync function firstCommittedAnchor(input: {\n  attempt: (\n    wraps: ContainerKeyWrap[],\n  ) => Promise<{ failure: unknown; key: Uint8Array | null }>;\n  candidates: ContainerKeyWrap[];\n  containerId: string;\n  containerKeyEpoch: number;\n  containerKeyEpochId: string;\n}): Promise<{ failure: unknown; key: Uint8Array | null }> {\n  let firstFailure: unknown;\n  for (const candidate of input.candidates) {\n    const result = await input.attempt([candidate]);\n    if (result.key === null) {\n      firstFailure ??= result.failure;\n      continue;\n    }\n    const materialId = await computeContainerKekMaterialId({\n      containerId: input.containerId,\n      keyEpoch: input.containerKeyEpoch,\n      keyMaterial: result.key,\n    });\n    if (materialId === input.containerKeyEpochId) {\n      return result;\n    }\n    // An envelope that decrypts to the WRONG key is a misaddressed or stale\n    // envelope, not an unreachable principal. Recording it keeps the reported\n    // reason `corrupt-envelope`; dropping it silently would let the epoch\n    // report as unaddressed, which points a repair at the wrong problem.\n    //\n    // Only reachable when the server files a wrap under an epoch id its\n    // material does not hash to — the addressing filter already rejects a\n    // wrap whose epoch id simply differs.\n    firstFailure ??= new Error(\n      `Container KEK envelope decrypts to material that is not epoch ${input.containerKeyEpochId}`,\n    );\n  }\n  return { failure: firstFailure, key: null };\n}\n\n/**\n * Opens one group of envelopes with the requester's CURRENT policies, folding\n * failure into a value rather than throwing.\n *\n * The caller tries several groups in order, and a failure in one is not the\n * end of the search — so the failure has to travel back alongside the miss\n * instead of unwinding the whole recovery.\n */\nasync function unwrapWrapsWithCurrentPolicies(input: {\n  execSql?: ExecSql | undefined;\n  secretKey: Uint8Array;\n  wraps: readonly ContainerKeyWrap[];\n}): Promise<{ failure: unknown; key: Uint8Array | null }> {\n  if (input.wraps.length === 0) {\n    return { failure: undefined, key: null };\n  }\n  try {\n    return {\n      failure: undefined,\n      key: await unwrapKeyEnvelopesWithPrincipalPolicies({\n        envelopes: input.wraps.map((wrap) => ({\n          keyFingerprint: wrap.recipientKeyFingerprint,\n          kemCipherText: wrap.kemCipherText,\n          wrappedKey: wrap.wrappedKey,\n        })),\n        execSql: input.execSql,\n        secretKey: input.secretKey,\n      }),\n    };\n  } catch (error) {\n    return { failure: error, key: null };\n  }\n}\n\n/**\n * The severed-bridge backstop: recovers one historical epoch's KEK from the\n * requester's own retained recipient envelope served in the kek-log. Wraps\n * are written by that epoch's rotator and never deleted, so this path is\n * independent of every later rotation — it works even when the bridge chain\n * above the epoch is destroyed. The recovered key is verified against the\n * epoch id's material commitment before use.\n *\n * Scope bound: a direct user envelope is recoverable from identity keys\n * alone, so a pristine client anchors on it. A group- or organization-\n * addressed envelope additionally requires the current principal secret key.\n * Principal rotation rematerializes every retained container grant against\n * the new principal head, so a current reader never needs an older principal\n * key to use this recovery path. Unreachable principal keys fail closed with\n * `HistoricalWrapUnavailableError` rather than appearing to be corruption.\n */\nexport async function recoverKeyringEntryFromWraps(input: {\n  containerId: string;\n  epoch: Pick<\n    ContainerKekLogEpochResponse,\n    \"containerKeyEpoch\" | \"containerKeyEpochId\" | \"wraps\"\n  >;\n  execSql?: ExecSql | undefined;\n  secretKey: Uint8Array;\n  /**\n   * Parent container KEKs by epoch id. An inherited-only child has no direct\n   * or principal envelope of its own; its anchor is the parent-container\n   * wrap, which opens under the parent epoch's KEK. Recover the parent's\n   * epoch first (recursively, through the parent's own log) and pass it here.\n   */\n  parentKeysByEpochId?: ReadonlyMap<string, Uint8Array> | undefined;\n  /**\n   * The requester's user id. Direct user envelopes are matched against it, so\n   * another member's envelope is never mistaken for an anchor — attempting it\n   * would only produce a misleading failure.\n   */\n  userId: string;\n}): Promise<ContainerKekKeyringEntry> {\n  const { directWraps, epochWraps, parentWraps, principalWraps } =\n    partitionAnchorWraps(\n      input.epoch.wraps,\n      input.epoch.containerKeyEpochId,\n      input.userId,\n    );\n  if (epochWraps.length === 0) {\n    throw new HistoricalWrapUnavailableError(\n      input.epoch.containerKeyEpoch,\n      \"no-addressed-envelope\",\n    );\n  }\n\n  const attempt = (wraps: typeof epochWraps) =>\n    unwrapWrapsWithCurrentPolicies({\n      execSql: input.execSql,\n      secretKey: input.secretKey,\n      wraps,\n    });\n\n  // A direct envelope is decryptable from identity keys alone, so its failure\n  // means corruption — not an unreachable principal key. Neither failure ends\n  // the search: a parent-container wrap may still anchor this epoch.\n  //\n  // Candidates are tried ONE AT A TIME, and each must match the epoch's\n  // material-id commitment rather than merely decrypt. An envelope can be\n  // AEAD-valid and still carry the WRONG key — a stale or misaddressed wrap —\n  // so batching would let that one envelope answer for the whole group and\n  // mask a later envelope that would have opened the epoch.\n  const attemptCommitted = (candidates: ContainerKeyWrap[]) =>\n    firstCommittedAnchor({\n      attempt,\n      candidates,\n      containerId: input.containerId,\n      containerKeyEpoch: input.epoch.containerKeyEpoch,\n      containerKeyEpochId: input.epoch.containerKeyEpochId,\n    });\n\n  const direct = await attemptCommitted(directWraps);\n  let keyMaterial = direct.key;\n  const directFailure = direct.failure;\n  let principalFailure: unknown;\n  if (keyMaterial === null) {\n    const principal = await attemptCommitted(principalWraps);\n    keyMaterial = principal.key;\n    // Preserve the current-policy failure in case no inherited anchor opens.\n    principalFailure = principal.failure;\n  }\n  // The inherited-only path: a parent-container envelope opens under the\n  // parent epoch's KEK, which the caller recovers from the parent's own log.\n  const parent =\n    keyMaterial === null\n      ? await openParentAnchor(\n          parentWraps,\n          input.parentKeysByEpochId ?? new Map(),\n        )\n      : { failure: undefined, key: null, keyWasAvailable: false };\n  keyMaterial ??= parent.key;\n  const parentFailure = parent.failure;\n  const parentKeyWasAvailable = parent.keyWasAvailable;\n  if (keyMaterial === null) {\n    throwMostSpecificAnchorFailure({\n      containerKeyEpoch: input.epoch.containerKeyEpoch,\n      directFailure,\n      hadParentWraps: parentWraps.length > 0,\n      parentFailure,\n      parentKeyWasAvailable,\n      principalFailure,\n    });\n  }\n  const expectedId = await computeContainerKekMaterialId({\n    containerId: input.containerId,\n    keyEpoch: input.epoch.containerKeyEpoch,\n    keyMaterial,\n  });\n  if (expectedId !== input.epoch.containerKeyEpochId) {\n    throw new Error(\n      `Container KEK log wrap does not match its committed epoch id at epoch ${input.epoch.containerKeyEpoch}`,\n    );\n  }\n  return {\n    containerKeyEpochId: input.epoch.containerKeyEpochId,\n    keyMaterial,\n  };\n}\n\nexport { fetchContainerKekLog } from \"./containerKekLogFetch\";\nexport type {\n  AggregatedContainerKekLog,\n  KeyringRebuildResult,\n} from \"./keyringLogWalk\";\nexport { rebuildKeyringEntriesFromLog } from \"./keyringLogWalk\";\n"]}