@tearleads/client-sdk 0.0.0-stage → 0.1.11

package/data/documents/shared/containerKekPath.js

@@ -0,0 +1,265 @@
+import { isPlainObject as isPlainRecord } from "../../../internal/validators/isPlainObject.js";
+import { unwrapKeyEnvelopesWithPrincipalPolicies } from "../../principals/principalPolicyCrypto.js";
+import { assertUnwrappedContainerKekMatchesMaterialId, projectedUnreachablePredecessorEpochIds, projectionKekLabel, unwrapKeyringContainerKeksAtIndex, } from "./containerKekPathHistory.js";
+import { verifyContainerKekPathProjection, } from "./containerKekPathVerification.js";
+import { assertSignedWrappingPublicKey, unwrapContainerKekFromParentWrap, } from "./containerKekWrapping.js";
+import { normalizeContainerKeyWrap, readManifestContainerId, readRecordNullableString, readRecordPositiveInteger, readRecordString, } from "./readers.js";
+function assertProjectionKekMatchesPath(projection, index) {
+    const manifest = projection.path[index];
+    const kek = projection.containerKeks[index];
+    if (!manifest || !kek) {
+        throw new Error("Container writer projection path and KEKs are incomplete");
+    }
+    if (readManifestContainerId(manifest) !== kek.containerId) {
+        throw new Error(`${projectionKekLabel(index)} container is inconsistent`);
+    }
+    if (kek.accessManifestHash !== manifest.manifestHash) {
+        throw new Error(`${projectionKekLabel(index)} manifest is stale`);
+    }
+    if (!isPlainRecord(kek.keyEpoch)) {
+        throw new Error(`${projectionKekLabel(index)} key epoch is invalid`);
+    }
+    if (readRecordString(kek.keyEpoch, "id", projectionKekLabel(index)) !==
+        kek.containerKeyEpochId ||
+        readRecordString(kek.keyEpoch, "containerId", projectionKekLabel(index)) !==
+            kek.containerId ||
+        readRecordPositiveInteger(kek.keyEpoch, "keyEpoch", projectionKekLabel(index)) !== kek.containerKeyEpoch ||
+        readRecordNullableString(kek.keyEpoch, "parentContainerKeyEpochId", projectionKekLabel(index)) !== kek.parentContainerKeyEpochId) {
+        throw new Error(`${projectionKekLabel(index)} key epoch is inconsistent`);
+    }
+}
+async function unwrapContainerKekFromPrincipalWraps(input) {
+    const envelopes = input.wraps
+        .filter((wrap) => wrap.recipientKind !== "container")
+        .map((wrap) => ({
+        keyFingerprint: wrap.recipientKeyFingerprint,
+        kemCipherText: wrap.kemCipherText,
+        wrappedKey: wrap.wrappedKey,
+    }));
+    if (envelopes.length === 0) {
+        return null;
+    }
+    try {
+        return await unwrapKeyEnvelopesWithPrincipalPolicies({
+            envelopes,
+            execSql: input.execSql,
+            secretKey: input.secretKey,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Admits caller-supplied keys that the projection also names.
+ *
+ * The projection match is deliberate: a seeded key is trusted only once its
+ * epoch is one this projection actually carries, which is what makes the
+ * material-id check below meaningful. Production seeds this with the epoch it
+ * just minted (see `registerIdentity`), never with recovered history — history
+ * arrives through the sealed keyring on each path instead, and is shared across
+ * authorizing paths through the common `keksByEpochId` map.
+ */
+async function seedKnownContainerKeks(input) {
+    const keksByEpochId = new Map();
+    for (const [containerKeyEpochId, keyMaterial] of input.knownContainerKeks ??
+        new Map()) {
+        const projected = findProjectedContainerKek(input.projection, containerKeyEpochId);
+        if (!projected) {
+            continue;
+        }
+        await assertUnwrappedContainerKekMatchesMaterialId({
+            label: projected.label,
+            kek: projected.kek,
+            keyMaterial,
+        });
+        await assertSignedWrappingPublicKey(input.projection, projected.index, keyMaterial);
+        keksByEpochId.set(containerKeyEpochId, {
+            containerId: projected.kek.containerId,
+            keyEpochHash: projected.kek.keyEpochHash,
+            keyMaterial,
+        });
+    }
+    return keksByEpochId;
+}
+function findProjectedContainerKek(projection, containerKeyEpochId) {
+    for (const [index, current] of projection.containerKeks.entries()) {
+        if (current.containerKeyEpochId === containerKeyEpochId) {
+            return { index, kek: current, label: projectionKekLabel(index) };
+        }
+    }
+    return null;
+}
+function successorKeyMaterial(keksByEpochId, kek, unwrapped) {
+    return keksByEpochId.get(kek.containerKeyEpochId)?.keyMaterial ?? unwrapped;
+}
+async function unwrapContainerKekAtIndex(input) {
+    assertProjectionKekMatchesPath(input.projection, input.index);
+    const kek = input.projection.containerKeks[input.index];
+    const currentManifest = input.projection.path[input.index];
+    if (!kek || !currentManifest) {
+        throw new Error(`${projectionKekLabel(input.index)} is missing`);
+    }
+    const wraps = [];
+    for (const rawWrap of kek.wraps) {
+        const wrap = normalizeContainerKeyWrap(rawWrap);
+        if (wrap.containerKeyEpochId === kek.containerKeyEpochId) {
+            wraps.push(wrap);
+        }
+    }
+    if (wraps.length !== kek.wraps.length) {
+        throw new Error(`${projectionKekLabel(input.index)} contains a stale wrap`);
+    }
+    const unwrapped = (await unwrapContainerKekFromPrincipalWraps({
+        execSql: input.execSql,
+        secretKey: input.secretKey,
+        wraps,
+    })) ??
+        (await unwrapContainerKekFromParentWrap({
+            label: projectionKekLabel(input.index),
+            parentContainerKeyEpochId: kek.parentContainerKeyEpochId,
+            parentKeksByEpochId: input.keksByEpochId,
+            wraps,
+        }));
+    if (unwrapped) {
+        await assertUnwrappedContainerKekMatchesMaterialId({
+            label: projectionKekLabel(input.index),
+            kek,
+            keyMaterial: unwrapped,
+        });
+        await assertSignedWrappingPublicKey(input.projection, input.index, unwrapped);
+        input.keksByEpochId.set(kek.containerKeyEpochId, {
+            containerId: kek.containerId,
+            keyEpochHash: kek.keyEpochHash,
+            keyMaterial: unwrapped,
+        });
+    }
+    try {
+        // Open the keyring immediately so descendants pinned to an older parent
+        // epoch can still unwrap during the same path walk.
+        await unwrapKeyringContainerKeksAtIndex({
+            currentManifest,
+            index: input.index,
+            kek,
+            keksByEpochId: input.keksByEpochId,
+            successorKeyMaterial: successorKeyMaterial(input.keksByEpochId, kek, unwrapped),
+            verifiedByHash: input.verifiedByHash,
+            verifyKeyringCommitment: input.verifyBridgeCommitment,
+        });
+        return null;
+    }
+    catch (error) {
+        // Historical keyring damage must not discard an independently verified
+        // current KEK. If the target still cannot be reached, the caller
+        // surfaces this integrity error; the bridge log remains the recovery
+        // path for the orphaned epochs.
+        return {
+            containerId: kek.containerId,
+            error: error instanceof Error
+                ? error
+                : new Error("Container predecessor KEK recovery failed", {
+                    cause: error,
+                }),
+            unreachableEpochIds: projectedUnreachablePredecessorEpochIds({
+                kek,
+                keksByEpochId: input.keksByEpochId,
+            }),
+        };
+    }
+}
+function recordPredecessorFailure(failuresByEpochId, unattributedFailuresByContainerId, failure) {
+    if (failure.unreachableEpochIds.length === 0) {
+        if (!unattributedFailuresByContainerId.has(failure.containerId)) {
+            unattributedFailuresByContainerId.set(failure.containerId, failure.error);
+        }
+        return;
+    }
+    for (const containerKeyEpochId of failure.unreachableEpochIds) {
+        if (!failuresByEpochId.has(containerKeyEpochId)) {
+            failuresByEpochId.set(containerKeyEpochId, failure.error);
+        }
+    }
+}
+/**
+ * No wrap on the path opens the target for this reader, and no recorded
+ * history failure explains it: the reader simply holds no key here. Distinct
+ * from keyring damage, which rethrows the underlying integrity error instead.
+ */
+export class ContainerKekTargetUnreachableError extends Error {
+    containerId;
+    constructor(containerId, label) {
+        super(`${label} could not be unwrapped`);
+        this.containerId = containerId;
+        this.name = "ContainerKekTargetUnreachableError";
+    }
+}
+function assertTargetKekUnwrapped(input) {
+    const targetKek = input.projection.containerKeks.at(-1);
+    if (!targetKek ||
+        input.keyMaterialByEpochId.has(targetKek.containerKeyEpochId)) {
+        return;
+    }
+    for (let index = input.projection.containerKeks.length - 1; index >= 0; index -= 1) {
+        const pathKek = input.projection.containerKeks[index];
+        if (!pathKek) {
+            continue;
+        }
+        const predecessorFailure = input.predecessorFailuresByEpochId.get(pathKek.containerKeyEpochId) ??
+            (pathKek.parentContainerKeyEpochId
+                ? input.predecessorFailuresByEpochId.get(pathKek.parentContainerKeyEpochId)
+                : undefined) ??
+            input.unattributedPredecessorFailuresByContainerId.get(pathKek.containerId);
+        if (predecessorFailure) {
+            throw predecessorFailure;
+        }
+    }
+    throw new ContainerKekTargetUnreachableError(targetKek.containerId, projectionKekLabel(input.projection.containerKeks.length - 1));
+}
+export async function unwrapContainerKekPathWithHistoryFailures(rawInput) {
+    // Kept for the keyring checks, which anchor to the verified lineage.
+    const input = {
+        ...rawInput,
+        verifiedByHash: rawInput.verifiedByHash ??
+            new Map(),
+    };
+    await verifyContainerKekPathProjection(input);
+    const keksByEpochId = await seedKnownContainerKeks({
+        knownContainerKeks: input.knownContainerKeks,
+        projection: input.projection,
+    });
+    const predecessorFailuresByEpochId = new Map();
+    const unattributedPredecessorFailuresByContainerId = new Map();
+    for (let index = 0; index < input.projection.containerKeks.length; index += 1) {
+        const currentFailure = await unwrapContainerKekAtIndex({
+            execSql: input.execSql,
+            index,
+            keksByEpochId,
+            projection: input.projection,
+            secretKey: input.secretKey,
+            verifiedByHash: input.verifiedByHash,
+            verifyBridgeCommitment: input.trustedLocalProjection !== true,
+        });
+        if (currentFailure) {
+            recordPredecessorFailure(predecessorFailuresByEpochId, unattributedPredecessorFailuresByContainerId, currentFailure);
+        }
+    }
+    const keyMaterialByEpochId = new Map();
+    for (const [containerKeyEpochId, kek] of keksByEpochId) {
+        keyMaterialByEpochId.set(containerKeyEpochId, kek.keyMaterial);
+    }
+    assertTargetKekUnwrapped({
+        keyMaterialByEpochId,
+        predecessorFailuresByEpochId,
+        projection: input.projection,
+        unattributedPredecessorFailuresByContainerId,
+    });
+    return {
+        keksByEpochId: keyMaterialByEpochId,
+        predecessorFailuresByEpochId,
+        unattributedPredecessorFailuresByContainerId,
+    };
+}
+export async function unwrapContainerKekPath(input) {
+    return (await unwrapContainerKekPathWithHistoryFailures(input)).keksByEpochId;
+}
+//# sourceMappingURL=containerKekPath.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"containerKekPath.js","sourceRoot":"","sources":["containerKekPath.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  ContainerKeyWrap,\n  VerifiedContainerAccessManifest,\n} from \"@tearleads/crypto\";\nimport { isPlainObject as isPlainRecord } from \"@tearleads/validators/isPlainObject\";\nimport type { ContainerWriterProjectionResponse } from \"@tearleads/validators/response\";\nimport { unwrapKeyEnvelopesWithPrincipalPolicies } from \"../../principals/principalPolicyCrypto\";\nimport type { ExecSql } from \"../../sqlite/sqlSchema\";\nimport {\n  assertUnwrappedContainerKekMatchesMaterialId,\n  projectedUnreachablePredecessorEpochIds,\n  projectionKekLabel,\n  unwrapKeyringContainerKeksAtIndex,\n} from \"./containerKekPathHistory\";\nimport {\n  type UnwrapContainerKekPathInput,\n  verifyContainerKekPathProjection,\n} from \"./containerKekPathVerification\";\nimport {\n  assertSignedWrappingPublicKey,\n  unwrapContainerKekFromParentWrap,\n} from \"./containerKekWrapping\";\nimport {\n  normalizeContainerKeyWrap,\n  readManifestContainerId,\n  readRecordNullableString,\n  readRecordPositiveInteger,\n  readRecordString,\n} from \"./readers\";\nimport type { UnwrappedContainerKek } from \"./types\";\n\nfunction assertProjectionKekMatchesPath(\n  projection: ContainerWriterProjectionResponse,\n  index: number,\n): void {\n  const manifest = projection.path[index];\n  const kek = projection.containerKeks[index];\n  if (!manifest || !kek) {\n    throw new Error(\"Container writer projection path and KEKs are incomplete\");\n  }\n  if (readManifestContainerId(manifest) !== kek.containerId) {\n    throw new Error(`${projectionKekLabel(index)} container is inconsistent`);\n  }\n  if (kek.accessManifestHash !== manifest.manifestHash) {\n    throw new Error(`${projectionKekLabel(index)} manifest is stale`);\n  }\n  if (!isPlainRecord(kek.keyEpoch)) {\n    throw new Error(`${projectionKekLabel(index)} key epoch is invalid`);\n  }\n  if (\n    readRecordString(kek.keyEpoch, \"id\", projectionKekLabel(index)) !==\n      kek.containerKeyEpochId ||\n    readRecordString(kek.keyEpoch, \"containerId\", projectionKekLabel(index)) !==\n      kek.containerId ||\n    readRecordPositiveInteger(\n      kek.keyEpoch,\n      \"keyEpoch\",\n      projectionKekLabel(index),\n    ) !== kek.containerKeyEpoch ||\n    readRecordNullableString(\n      kek.keyEpoch,\n      \"parentContainerKeyEpochId\",\n      projectionKekLabel(index),\n    ) !== kek.parentContainerKeyEpochId\n  ) {\n    throw new Error(`${projectionKekLabel(index)} key epoch is inconsistent`);\n  }\n}\n\nasync function unwrapContainerKekFromPrincipalWraps(input: {\n  execSql?: ExecSql | undefined;\n  secretKey: Uint8Array;\n  wraps: readonly ContainerKeyWrap[];\n}): Promise<Uint8Array | null> {\n  const envelopes = input.wraps\n    .filter((wrap) => wrap.recipientKind !== \"container\")\n    .map((wrap) => ({\n      keyFingerprint: wrap.recipientKeyFingerprint,\n      kemCipherText: wrap.kemCipherText,\n      wrappedKey: wrap.wrappedKey,\n    }));\n  if (envelopes.length === 0) {\n    return null;\n  }\n\n  try {\n    return await unwrapKeyEnvelopesWithPrincipalPolicies({\n      envelopes,\n      execSql: input.execSql,\n      secretKey: input.secretKey,\n    });\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Admits caller-supplied keys that the projection also names.\n *\n * The projection match is deliberate: a seeded key is trusted only once its\n * epoch is one this projection actually carries, which is what makes the\n * material-id check below meaningful. Production seeds this with the epoch it\n * just minted (see `registerIdentity`), never with recovered history — history\n * arrives through the sealed keyring on each path instead, and is shared across\n * authorizing paths through the common `keksByEpochId` map.\n */\nasync function seedKnownContainerKeks(input: {\n  knownContainerKeks?: ReadonlyMap<string, Uint8Array> | undefined;\n  projection: ContainerWriterProjectionResponse;\n}): Promise<Map<string, UnwrappedContainerKek>> {\n  const keksByEpochId = new Map<string, UnwrappedContainerKek>();\n\n  for (const [containerKeyEpochId, keyMaterial] of input.knownContainerKeks ??\n    new Map<string, Uint8Array>()) {\n    const projected = findProjectedContainerKek(\n      input.projection,\n      containerKeyEpochId,\n    );\n    if (!projected) {\n      continue;\n    }\n    await assertUnwrappedContainerKekMatchesMaterialId({\n      label: projected.label,\n      kek: projected.kek,\n      keyMaterial,\n    });\n    await assertSignedWrappingPublicKey(\n      input.projection,\n      projected.index,\n      keyMaterial,\n    );\n    keksByEpochId.set(containerKeyEpochId, {\n      containerId: projected.kek.containerId,\n      keyEpochHash: projected.kek.keyEpochHash,\n      keyMaterial,\n    });\n  }\n\n  return keksByEpochId;\n}\n\nfunction findProjectedContainerKek(\n  projection: ContainerWriterProjectionResponse,\n  containerKeyEpochId: string,\n) {\n  for (const [index, current] of projection.containerKeks.entries()) {\n    if (current.containerKeyEpochId === containerKeyEpochId) {\n      return { index, kek: current, label: projectionKekLabel(index) };\n    }\n  }\n  return null;\n}\n\nfunction successorKeyMaterial(\n  keksByEpochId: ReadonlyMap<string, UnwrappedContainerKek>,\n  kek: Pick<\n    ContainerWriterProjectionResponse[\"containerKeks\"][number],\n    \"containerKeyEpochId\"\n  >,\n  unwrapped: Uint8Array | null,\n): Uint8Array | null {\n  return keksByEpochId.get(kek.containerKeyEpochId)?.keyMaterial ?? unwrapped;\n}\n\nasync function unwrapContainerKekAtIndex(input: {\n  readonly execSql?: ExecSql | undefined;\n  readonly index: number;\n  readonly keksByEpochId: Map<string, UnwrappedContainerKek>;\n  readonly projection: ContainerWriterProjectionResponse;\n  readonly secretKey: Uint8Array;\n  readonly verifiedByHash: ReadonlyMap<string, VerifiedContainerAccessManifest>;\n  readonly verifyBridgeCommitment: boolean;\n}): Promise<{\n  readonly containerId: string;\n  readonly error: Error;\n  readonly unreachableEpochIds: readonly string[];\n} | null> {\n  assertProjectionKekMatchesPath(input.projection, input.index);\n  const kek = input.projection.containerKeks[input.index];\n  const currentManifest = input.projection.path[input.index];\n  if (!kek || !currentManifest) {\n    throw new Error(`${projectionKekLabel(input.index)} is missing`);\n  }\n\n  const wraps: ContainerKeyWrap[] = [];\n  for (const rawWrap of kek.wraps) {\n    const wrap = normalizeContainerKeyWrap(rawWrap);\n    if (wrap.containerKeyEpochId === kek.containerKeyEpochId) {\n      wraps.push(wrap);\n    }\n  }\n  if (wraps.length !== kek.wraps.length) {\n    throw new Error(`${projectionKekLabel(input.index)} contains a stale wrap`);\n  }\n\n  const unwrapped =\n    (await unwrapContainerKekFromPrincipalWraps({\n      execSql: input.execSql,\n      secretKey: input.secretKey,\n      wraps,\n    })) ??\n    (await unwrapContainerKekFromParentWrap({\n      label: projectionKekLabel(input.index),\n      parentContainerKeyEpochId: kek.parentContainerKeyEpochId,\n      parentKeksByEpochId: input.keksByEpochId,\n      wraps,\n    }));\n\n  if (unwrapped) {\n    await assertUnwrappedContainerKekMatchesMaterialId({\n      label: projectionKekLabel(input.index),\n      kek,\n      keyMaterial: unwrapped,\n    });\n    await assertSignedWrappingPublicKey(\n      input.projection,\n      input.index,\n      unwrapped,\n    );\n    input.keksByEpochId.set(kek.containerKeyEpochId, {\n      containerId: kek.containerId,\n      keyEpochHash: kek.keyEpochHash,\n      keyMaterial: unwrapped,\n    });\n  }\n\n  try {\n    // Open the keyring immediately so descendants pinned to an older parent\n    // epoch can still unwrap during the same path walk.\n    await unwrapKeyringContainerKeksAtIndex({\n      currentManifest,\n      index: input.index,\n      kek,\n      keksByEpochId: input.keksByEpochId,\n      successorKeyMaterial: successorKeyMaterial(\n        input.keksByEpochId,\n        kek,\n        unwrapped,\n      ),\n      verifiedByHash: input.verifiedByHash,\n      verifyKeyringCommitment: input.verifyBridgeCommitment,\n    });\n    return null;\n  } catch (error) {\n    // Historical keyring damage must not discard an independently verified\n    // current KEK. If the target still cannot be reached, the caller\n    // surfaces this integrity error; the bridge log remains the recovery\n    // path for the orphaned epochs.\n    return {\n      containerId: kek.containerId,\n      error:\n        error instanceof Error\n          ? error\n          : new Error(\"Container predecessor KEK recovery failed\", {\n              cause: error,\n            }),\n      unreachableEpochIds: projectedUnreachablePredecessorEpochIds({\n        kek,\n        keksByEpochId: input.keksByEpochId,\n      }),\n    };\n  }\n}\n\ninterface UnwrappedContainerKekPathResult {\n  readonly keksByEpochId: ReadonlyMap<string, Uint8Array>;\n  readonly predecessorFailuresByEpochId: ReadonlyMap<string, Error>;\n  readonly unattributedPredecessorFailuresByContainerId: ReadonlyMap<\n    string,\n    Error\n  >;\n}\n\nfunction recordPredecessorFailure(\n  failuresByEpochId: Map<string, Error>,\n  unattributedFailuresByContainerId: Map<string, Error>,\n  failure: NonNullable<Awaited<ReturnType<typeof unwrapContainerKekAtIndex>>>,\n): void {\n  if (failure.unreachableEpochIds.length === 0) {\n    if (!unattributedFailuresByContainerId.has(failure.containerId)) {\n      unattributedFailuresByContainerId.set(failure.containerId, failure.error);\n    }\n    return;\n  }\n  for (const containerKeyEpochId of failure.unreachableEpochIds) {\n    if (!failuresByEpochId.has(containerKeyEpochId)) {\n      failuresByEpochId.set(containerKeyEpochId, failure.error);\n    }\n  }\n}\n\n/**\n * No wrap on the path opens the target for this reader, and no recorded\n * history failure explains it: the reader simply holds no key here. Distinct\n * from keyring damage, which rethrows the underlying integrity error instead.\n */\nexport class ContainerKekTargetUnreachableError extends Error {\n  constructor(\n    readonly containerId: string,\n    label: string,\n  ) {\n    super(`${label} could not be unwrapped`);\n    this.name = \"ContainerKekTargetUnreachableError\";\n  }\n}\n\nfunction assertTargetKekUnwrapped(input: {\n  readonly keyMaterialByEpochId: ReadonlyMap<string, Uint8Array>;\n  readonly predecessorFailuresByEpochId: ReadonlyMap<string, Error>;\n  readonly projection: ContainerWriterProjectionResponse;\n  readonly unattributedPredecessorFailuresByContainerId: ReadonlyMap<\n    string,\n    Error\n  >;\n}): void {\n  const targetKek = input.projection.containerKeks.at(-1);\n  if (\n    !targetKek ||\n    input.keyMaterialByEpochId.has(targetKek.containerKeyEpochId)\n  ) {\n    return;\n  }\n  for (\n    let index = input.projection.containerKeks.length - 1;\n    index >= 0;\n    index -= 1\n  ) {\n    const pathKek = input.projection.containerKeks[index];\n    if (!pathKek) {\n      continue;\n    }\n    const predecessorFailure =\n      input.predecessorFailuresByEpochId.get(pathKek.containerKeyEpochId) ??\n      (pathKek.parentContainerKeyEpochId\n        ? input.predecessorFailuresByEpochId.get(\n            pathKek.parentContainerKeyEpochId,\n          )\n        : undefined) ??\n      input.unattributedPredecessorFailuresByContainerId.get(\n        pathKek.containerId,\n      );\n    if (predecessorFailure) {\n      throw predecessorFailure;\n    }\n  }\n  throw new ContainerKekTargetUnreachableError(\n    targetKek.containerId,\n    projectionKekLabel(input.projection.containerKeks.length - 1),\n  );\n}\n\nexport async function unwrapContainerKekPathWithHistoryFailures(\n  rawInput: UnwrapContainerKekPathInput,\n): Promise<UnwrappedContainerKekPathResult> {\n  // Kept for the keyring checks, which anchor to the verified lineage.\n  const input = {\n    ...rawInput,\n    verifiedByHash:\n      rawInput.verifiedByHash ??\n      new Map<string, VerifiedContainerAccessManifest>(),\n  };\n  await verifyContainerKekPathProjection(input);\n\n  const keksByEpochId = await seedKnownContainerKeks({\n    knownContainerKeks: input.knownContainerKeks,\n    projection: input.projection,\n  });\n  const predecessorFailuresByEpochId = new Map<string, Error>();\n  const unattributedPredecessorFailuresByContainerId = new Map<string, Error>();\n\n  for (\n    let index = 0;\n    index < input.projection.containerKeks.length;\n    index += 1\n  ) {\n    const currentFailure = await unwrapContainerKekAtIndex({\n      execSql: input.execSql,\n      index,\n      keksByEpochId,\n      projection: input.projection,\n      secretKey: input.secretKey,\n      verifiedByHash: input.verifiedByHash,\n      verifyBridgeCommitment: input.trustedLocalProjection !== true,\n    });\n    if (currentFailure) {\n      recordPredecessorFailure(\n        predecessorFailuresByEpochId,\n        unattributedPredecessorFailuresByContainerId,\n        currentFailure,\n      );\n    }\n  }\n\n  const keyMaterialByEpochId = new Map<string, Uint8Array>();\n  for (const [containerKeyEpochId, kek] of keksByEpochId) {\n    keyMaterialByEpochId.set(containerKeyEpochId, kek.keyMaterial);\n  }\n  assertTargetKekUnwrapped({\n    keyMaterialByEpochId,\n    predecessorFailuresByEpochId,\n    projection: input.projection,\n    unattributedPredecessorFailuresByContainerId,\n  });\n  return {\n    keksByEpochId: keyMaterialByEpochId,\n    predecessorFailuresByEpochId,\n    unattributedPredecessorFailuresByContainerId,\n  };\n}\n\nexport async function unwrapContainerKekPath(\n  input: UnwrapContainerKekPathInput,\n): Promise<ReadonlyMap<string, Uint8Array>> {\n  return (await unwrapContainerKekPathWithHistoryFailures(input)).keksByEpochId;\n}\n"]}

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

@@ -0,0 +1,61 @@
+import { type VerifiedContainerAccessManifest } from "../../../internal/crypto/index.js";
+import type { ContainerWriterProjectionResponse } from "../../../internal/validators/response/index.js";
+import type { UnwrappedContainerKek } from "./types.js";
+type ProjectionKek = ContainerWriterProjectionResponse["containerKeks"][number];
+type VerifiedManifests = ReadonlyMap<string, VerifiedContainerAccessManifest>;
+/** The projection proves a predecessor existed, but no retained keyring can recover it. */
+export declare class ContainerKekHistoryUnavailableError extends Error {
+    constructor(label: string);
+}
+export declare function projectionKekLabel(index: number): string;
+export declare function assertUnwrappedContainerKekMatchesMaterialId(input: {
+    label: string;
+    keyMaterial: Uint8Array;
+    kek: Pick<ProjectionKek, "containerId" | "containerKeyEpoch" | "containerKeyEpochId">;
+}): Promise<void>;
+/**
+ * Epoch ids named by verified historical manifest states for this container.
+ * Those states are signed, so an id they name is an epoch the container
+ * provably had — and a keyring that omits it in favor of a forged id for the
+ * same position is detectable even when no epoch RECORD was shipped.
+ */
+export declare function manifestHistoryEpochIds(kek: ProjectionKek): Set<string>;
+/**
+ * The epoch ids this KEK's own history names, plus every one its head's
+ * verified lineage names wherever the projection served it. Verification pools
+ * every KEK's history, so a server can serve a container's older manifests
+ * under another KEK; walking the lineage keeps a forged keyring id from passing
+ * because the real id it displaces moved (#2365 finding 32). The walk stops at
+ * the first manifest verification did not record, so it only ever adds ids.
+ */
+export declare function signedHistoryEpochIds(input: {
+    readonly headManifestHash: string;
+    readonly kek: ProjectionKek;
+    readonly verifiedByHash: VerifiedManifests;
+}): Set<string>;
+/**
+ * Opens the sealed keyring for one path index and admits every entry into
+ * `keksByEpochId` after verifying it against the material-id commitment its
+ * ordinal position implies (entry i is key epoch i + 1). No chain walk:
+ * one decrypt yields the container's complete retained history, and entry
+ * verification is independent per entry.
+ */
+export declare function unwrapKeyringContainerKeksAtIndex(input: {
+    currentManifest: ContainerWriterProjectionResponse["path"][number];
+    index: number;
+    kek: ProjectionKek;
+    keksByEpochId: Map<string, UnwrappedContainerKek>;
+    successorKeyMaterial: Uint8Array | null;
+    /** Every manifest projection verification recorded; anchors the keyring. */
+    verifiedByHash: VerifiedManifests;
+    verifyKeyringCommitment: boolean;
+}): Promise<void>;
+/**
+ * Epoch ids this projection implies exist but that were not recovered —
+ * used to attribute history failures to the material they orphan.
+ */
+export declare function projectedUnreachablePredecessorEpochIds(input: {
+    kek: ProjectionKek;
+    keksByEpochId: ReadonlyMap<string, UnwrappedContainerKek>;
+}): string[];
+export {};

package/data/documents/shared/containerKekPathHistory.js

@@ -0,0 +1,223 @@
+import { computeContainerKekKeyringHash, computeContainerKekMaterialId, isContainerKekMaterialId, KeyingVerificationError, normalizeContainerAccessEventBody, normalizeContainerKekKeyring, openContainerKekKeyring, } from "../../../internal/crypto/index.js";
+import { readCanonicalJson, readCanonicalRecord, } from "../../keyingCanonicalJson.js";
+import { readContainerKeyEpoch } from "../../keyingProjectionVerification/readers.js";
+import { verifyContainerKekEntries } from "./containerKekEntryVerification.js";
+import { readManifestContainerId } from "./readers.js";
+/** The projection proves a predecessor existed, but no retained keyring can recover it. */
+export class ContainerKekHistoryUnavailableError extends Error {
+    constructor(label) {
+        super(`${label} keyring is missing`);
+        this.name = "ContainerKekHistoryUnavailableError";
+    }
+}
+export function projectionKekLabel(index) {
+    return `Container writer projection KEK[${index}]`;
+}
+export async function assertUnwrappedContainerKekMatchesMaterialId(input) {
+    if (!isContainerKekMaterialId(input.kek.containerKeyEpochId)) {
+        throw new Error(`${input.label} KEK epoch id does not commit to key material`);
+    }
+    const expectedId = await computeContainerKekMaterialId({
+        containerId: input.kek.containerId,
+        keyEpoch: input.kek.containerKeyEpoch,
+        keyMaterial: input.keyMaterial,
+    });
+    if (expectedId !== input.kek.containerKeyEpochId) {
+        throw new Error(`${input.label} KEK material does not match committed epoch id`);
+    }
+}
+function sameContainerManifestHistory(kek) {
+    return kek.containerManifestHistory.filter((bundle) => readManifestContainerId(bundle) === kek.containerId);
+}
+/**
+ * Proves the served keyring is the one the rotation that minted the current
+ * epoch committed to in its signed event body.
+ */
+async function assertKeyringCommitment(input) {
+    const rotationManifestHash = readContainerKeyEpoch(input.kek.keyEpoch, `${projectionKekLabel(input.index)} key epoch`).accessManifestHash;
+    const rotationManifest = rotationManifestHash === input.currentManifest.manifestHash
+        ? input.currentManifest
+        : sameContainerManifestHistory(input.kek).find((bundle) => bundle.manifestHash === rotationManifestHash);
+    if (!rotationManifest) {
+        throw new Error(`${projectionKekLabel(input.index)} keyring signer is missing`);
+    }
+    const eventBundle = readCanonicalRecord(rotationManifest.event, `${projectionKekLabel(input.index)} keyring event`);
+    const eventBody = normalizeContainerAccessEventBody(readCanonicalJson(Reflect.get(eventBundle, "body"), `${projectionKekLabel(input.index)} keyring event body`));
+    if ((eventBody.eventType !== "container.move" &&
+        eventBody.eventType !== "container.rekey" &&
+        eventBody.eventType !== "container.revoke") ||
+        eventBody.keyringHash !==
+            (await computeContainerKekKeyringHash(input.keyring))) {
+        throw new Error(`${projectionKekLabel(input.index)} keyring does not match its signed event`);
+    }
+}
+async function openVerifiedKeyringEntries(input) {
+    const { kek } = input;
+    const keyring = normalizeContainerKekKeyring(kek.keyring);
+    if (keyring.containerId !== kek.containerId ||
+        keyring.containerKeyEpochId !== kek.containerKeyEpochId) {
+        throw new Error(`${projectionKekLabel(input.index)} keyring is inconsistent`);
+    }
+    if (input.verifyKeyringCommitment) {
+        await assertKeyringCommitment({
+            currentManifest: input.currentManifest,
+            index: input.index,
+            kek,
+            keyring,
+        });
+    }
+    let entries;
+    try {
+        entries = await openContainerKekKeyring({
+            keyEpoch: kek.containerKeyEpoch,
+            keyring,
+            successorContainerKey: input.successorKeyMaterial,
+        });
+    }
+    catch (error) {
+        if (error instanceof KeyingVerificationError) {
+            throw error;
+        }
+        // Label opaque AEAD failures; structural verification errors already
+        // carry their own diagnosis.
+        throw new Error(`${projectionKekLabel(input.index)} keyring could not be opened`, { cause: error });
+    }
+    // Per-entry material-id verification proves an entry's key matches the id
+    // it declares, but a poisoned keyring can declare a self-consistent FAKE
+    // id — fresh key, matching commitment — for an epoch the container never
+    // had. Anchor every entry the projection can name to the epoch id its
+    // signed history actually committed; anything else is a forged epoch.
+    await verifyContainerKekEntries(kek.containerId, entries);
+    // Every epoch id the signed manifest history names must be present in the
+    // keyring. A forged entry can be self-consistent, but it cannot also make
+    // the real epoch id — which a signed state already named — disappear.
+    const entryEpochIds = new Set(entries.map((entry) => entry.containerKeyEpochId));
+    const signedEpochIds = signedHistoryEpochIds({
+        headManifestHash: input.currentManifest.manifestHash,
+        kek,
+        verifiedByHash: input.verifiedByHash,
+    });
+    for (const historicalEpochId of signedEpochIds) {
+        if (!entryEpochIds.has(historicalEpochId)) {
+            throw new KeyingVerificationError("missing_dependency", `${projectionKekLabel(input.index)} keyring omits an epoch its manifest history commits to`);
+        }
+    }
+    return entries;
+}
+/**
+ * Epoch ids named by verified historical manifest states for this container.
+ * Those states are signed, so an id they name is an epoch the container
+ * provably had — and a keyring that omits it in favor of a forged id for the
+ * same position is detectable even when no epoch RECORD was shipped.
+ */
+export function manifestHistoryEpochIds(kek) {
+    const epochIds = new Set();
+    for (const bundle of sameContainerManifestHistory(kek)) {
+        const state = readCanonicalRecord(bundle.state, "Container writer projection historical manifest state");
+        const containerKeyEpochId = Reflect.get(state, "containerKeyEpochId");
+        if (typeof containerKeyEpochId === "string" &&
+            containerKeyEpochId !== kek.containerKeyEpochId) {
+            epochIds.add(containerKeyEpochId);
+        }
+    }
+    return epochIds;
+}
+/**
+ * The epoch ids this KEK's own history names, plus every one its head's
+ * verified lineage names wherever the projection served it. Verification pools
+ * every KEK's history, so a server can serve a container's older manifests
+ * under another KEK; walking the lineage keeps a forged keyring id from passing
+ * because the real id it displaces moved (#2365 finding 32). The walk stops at
+ * the first manifest verification did not record, so it only ever adds ids.
+ */
+export function signedHistoryEpochIds(input) {
+    const epochIds = manifestHistoryEpochIds(input.kek);
+    const visited = new Set();
+    let current = input.verifiedByHash.get(input.headManifestHash);
+    while (current &&
+        current.state.containerId === input.kek.containerId &&
+        !visited.has(current.manifestHash)) {
+        visited.add(current.manifestHash);
+        const epochId = current.state.containerKeyEpochId;
+        if (epochId !== null && epochId !== input.kek.containerKeyEpochId) {
+            epochIds.add(epochId);
+        }
+        const previousHash = current.state.previousManifestHash;
+        current =
+            previousHash === null
+                ? undefined
+                : input.verifiedByHash.get(previousHash);
+    }
+    return epochIds;
+}
+function admitKeyringEntry(input) {
+    const { entry, kek } = input;
+    const cached = input.keksByEpochId.get(entry.containerKeyEpochId);
+    if (cached) {
+        if (cached.containerId !== kek.containerId) {
+            throw new Error(`${projectionKekLabel(input.index)} cached historical KEK is inconsistent`);
+        }
+        return;
+    }
+    input.keksByEpochId.set(entry.containerKeyEpochId, {
+        containerId: kek.containerId,
+        // A keyring entry is key material plus the epoch id that commits to it —
+        // there is no epoch record, so no fingerprint. Selection falls back to the
+        // epoch id and AEAD authenticates; the commitment check above is what
+        // makes the material itself trustworthy.
+        keyEpochHash: null,
+        keyMaterial: entry.keyMaterial,
+    });
+}
+/**
+ * Opens the sealed keyring for one path index and admits every entry into
+ * `keksByEpochId` after verifying it against the material-id commitment its
+ * ordinal position implies (entry i is key epoch i + 1). No chain walk:
+ * one decrypt yields the container's complete retained history, and entry
+ * verification is independent per entry.
+ */
+export async function unwrapKeyringContainerKeksAtIndex(input) {
+    const { kek, successorKeyMaterial } = input;
+    if (!successorKeyMaterial) {
+        return;
+    }
+    if (kek.keyring === null) {
+        if (kek.containerKeyEpoch !== 1) {
+            throw new ContainerKekHistoryUnavailableError(projectionKekLabel(input.index));
+        }
+        return;
+    }
+    const entries = await openVerifiedKeyringEntries({
+        currentManifest: input.currentManifest,
+        index: input.index,
+        kek,
+        successorKeyMaterial,
+        verifiedByHash: input.verifiedByHash,
+        verifyKeyringCommitment: input.verifyKeyringCommitment,
+    });
+    for (const entry of entries) {
+        admitKeyringEntry({
+            entry,
+            index: input.index,
+            kek,
+            keksByEpochId: input.keksByEpochId,
+        });
+    }
+}
+/**
+ * Epoch ids this projection implies exist but that were not recovered —
+ * used to attribute history failures to the material they orphan.
+ */
+export function projectedUnreachablePredecessorEpochIds(input) {
+    const projectedEpochIds = new Set();
+    for (const bundle of sameContainerManifestHistory(input.kek)) {
+        const state = readCanonicalRecord(bundle.state, "Container writer projection historical manifest state");
+        const containerKeyEpochId = Reflect.get(state, "containerKeyEpochId");
+        if (typeof containerKeyEpochId === "string") {
+            projectedEpochIds.add(containerKeyEpochId);
+        }
+    }
+    projectedEpochIds.delete(input.kek.containerKeyEpochId);
+    return [...projectedEpochIds].filter((containerKeyEpochId) => !input.keksByEpochId.has(containerKeyEpochId));
+}
+//# sourceMappingURL=containerKekPathHistory.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"containerKekPathHistory.js","sourceRoot":"","sources":["containerKekPathHistory.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  computeContainerKekKeyringHash,\n  computeContainerKekMaterialId,\n  isContainerKekMaterialId,\n  KeyingVerificationError,\n  normalizeContainerAccessEventBody,\n  normalizeContainerKekKeyring,\n  openContainerKekKeyring,\n  type VerifiedContainerAccessManifest,\n} from \"@tearleads/crypto\";\nimport type { ContainerWriterProjectionResponse } from \"@tearleads/validators/response\";\nimport {\n  readCanonicalJson,\n  readCanonicalRecord,\n} from \"../../keyingCanonicalJson\";\nimport { readContainerKeyEpoch } from \"../../keyingProjectionVerification/readers\";\nimport { verifyContainerKekEntries } from \"./containerKekEntryVerification\";\nimport { readManifestContainerId } from \"./readers\";\nimport type { UnwrappedContainerKek } from \"./types\";\n\ntype ProjectionKek = ContainerWriterProjectionResponse[\"containerKeks\"][number];\ntype VerifiedManifests = ReadonlyMap<string, VerifiedContainerAccessManifest>;\n\n/** The projection proves a predecessor existed, but no retained keyring can recover it. */\nexport class ContainerKekHistoryUnavailableError extends Error {\n  constructor(label: string) {\n    super(`${label} keyring is missing`);\n    this.name = \"ContainerKekHistoryUnavailableError\";\n  }\n}\n\nexport function projectionKekLabel(index: number): string {\n  return `Container writer projection KEK[${index}]`;\n}\n\nexport async function assertUnwrappedContainerKekMatchesMaterialId(input: {\n  label: string;\n  keyMaterial: Uint8Array;\n  kek: Pick<\n    ProjectionKek,\n    \"containerId\" | \"containerKeyEpoch\" | \"containerKeyEpochId\"\n  >;\n}): Promise<void> {\n  if (!isContainerKekMaterialId(input.kek.containerKeyEpochId)) {\n    throw new Error(\n      `${input.label} KEK epoch id does not commit to key material`,\n    );\n  }\n  const expectedId = await computeContainerKekMaterialId({\n    containerId: input.kek.containerId,\n    keyEpoch: input.kek.containerKeyEpoch,\n    keyMaterial: input.keyMaterial,\n  });\n  if (expectedId !== input.kek.containerKeyEpochId) {\n    throw new Error(\n      `${input.label} KEK material does not match committed epoch id`,\n    );\n  }\n}\n\nfunction sameContainerManifestHistory(kek: ProjectionKek) {\n  return kek.containerManifestHistory.filter(\n    (bundle) => readManifestContainerId(bundle) === kek.containerId,\n  );\n}\n\n/**\n * Proves the served keyring is the one the rotation that minted the current\n * epoch committed to in its signed event body.\n */\nasync function assertKeyringCommitment(input: {\n  currentManifest: ContainerWriterProjectionResponse[\"path\"][number];\n  index: number;\n  kek: ProjectionKek;\n  keyring: ReturnType<typeof normalizeContainerKekKeyring>;\n}): Promise<void> {\n  const rotationManifestHash = readContainerKeyEpoch(\n    input.kek.keyEpoch,\n    `${projectionKekLabel(input.index)} key epoch`,\n  ).accessManifestHash;\n  const rotationManifest =\n    rotationManifestHash === input.currentManifest.manifestHash\n      ? input.currentManifest\n      : sameContainerManifestHistory(input.kek).find(\n          (bundle) => bundle.manifestHash === rotationManifestHash,\n        );\n  if (!rotationManifest) {\n    throw new Error(\n      `${projectionKekLabel(input.index)} keyring signer is missing`,\n    );\n  }\n  const eventBundle = readCanonicalRecord(\n    rotationManifest.event,\n    `${projectionKekLabel(input.index)} keyring event`,\n  );\n  const eventBody = normalizeContainerAccessEventBody(\n    readCanonicalJson(\n      Reflect.get(eventBundle, \"body\"),\n      `${projectionKekLabel(input.index)} keyring event body`,\n    ),\n  );\n  if (\n    (eventBody.eventType !== \"container.move\" &&\n      eventBody.eventType !== \"container.rekey\" &&\n      eventBody.eventType !== \"container.revoke\") ||\n    eventBody.keyringHash !==\n      (await computeContainerKekKeyringHash(input.keyring))\n  ) {\n    throw new Error(\n      `${projectionKekLabel(input.index)} keyring does not match its signed event`,\n    );\n  }\n}\n\nasync function openVerifiedKeyringEntries(input: {\n  currentManifest: ContainerWriterProjectionResponse[\"path\"][number];\n  index: number;\n  kek: ProjectionKek;\n  successorKeyMaterial: Uint8Array;\n  verifiedByHash: VerifiedManifests;\n  verifyKeyringCommitment: boolean;\n}): Promise<Awaited<ReturnType<typeof openContainerKekKeyring>>> {\n  const { kek } = input;\n  const keyring = normalizeContainerKekKeyring(kek.keyring);\n  if (\n    keyring.containerId !== kek.containerId ||\n    keyring.containerKeyEpochId !== kek.containerKeyEpochId\n  ) {\n    throw new Error(\n      `${projectionKekLabel(input.index)} keyring is inconsistent`,\n    );\n  }\n  if (input.verifyKeyringCommitment) {\n    await assertKeyringCommitment({\n      currentManifest: input.currentManifest,\n      index: input.index,\n      kek,\n      keyring,\n    });\n  }\n\n  let entries: Awaited<ReturnType<typeof openContainerKekKeyring>>;\n  try {\n    entries = await openContainerKekKeyring({\n      keyEpoch: kek.containerKeyEpoch,\n      keyring,\n      successorContainerKey: input.successorKeyMaterial,\n    });\n  } catch (error) {\n    if (error instanceof KeyingVerificationError) {\n      throw error;\n    }\n    // Label opaque AEAD failures; structural verification errors already\n    // carry their own diagnosis.\n    throw new Error(\n      `${projectionKekLabel(input.index)} keyring could not be opened`,\n      { cause: error },\n    );\n  }\n  // Per-entry material-id verification proves an entry's key matches the id\n  // it declares, but a poisoned keyring can declare a self-consistent FAKE\n  // id — fresh key, matching commitment — for an epoch the container never\n  // had. Anchor every entry the projection can name to the epoch id its\n  // signed history actually committed; anything else is a forged epoch.\n  await verifyContainerKekEntries(kek.containerId, entries);\n\n  // Every epoch id the signed manifest history names must be present in the\n  // keyring. A forged entry can be self-consistent, but it cannot also make\n  // the real epoch id — which a signed state already named — disappear.\n  const entryEpochIds = new Set(\n    entries.map((entry) => entry.containerKeyEpochId),\n  );\n  const signedEpochIds = signedHistoryEpochIds({\n    headManifestHash: input.currentManifest.manifestHash,\n    kek,\n    verifiedByHash: input.verifiedByHash,\n  });\n  for (const historicalEpochId of signedEpochIds) {\n    if (!entryEpochIds.has(historicalEpochId)) {\n      throw new KeyingVerificationError(\n        \"missing_dependency\",\n        `${projectionKekLabel(input.index)} keyring omits an epoch its manifest history commits to`,\n      );\n    }\n  }\n  return entries;\n}\n\n/**\n * Epoch ids named by verified historical manifest states for this container.\n * Those states are signed, so an id they name is an epoch the container\n * provably had — and a keyring that omits it in favor of a forged id for the\n * same position is detectable even when no epoch RECORD was shipped.\n */\nexport function manifestHistoryEpochIds(kek: ProjectionKek): Set<string> {\n  const epochIds = new Set<string>();\n  for (const bundle of sameContainerManifestHistory(kek)) {\n    const state = readCanonicalRecord(\n      bundle.state,\n      \"Container writer projection historical manifest state\",\n    );\n    const containerKeyEpochId = Reflect.get(state, \"containerKeyEpochId\");\n    if (\n      typeof containerKeyEpochId === \"string\" &&\n      containerKeyEpochId !== kek.containerKeyEpochId\n    ) {\n      epochIds.add(containerKeyEpochId);\n    }\n  }\n  return epochIds;\n}\n\n/**\n * The epoch ids this KEK's own history names, plus every one its head's\n * verified lineage names wherever the projection served it. Verification pools\n * every KEK's history, so a server can serve a container's older manifests\n * under another KEK; walking the lineage keeps a forged keyring id from passing\n * because the real id it displaces moved (#2365 finding 32). The walk stops at\n * the first manifest verification did not record, so it only ever adds ids.\n */\nexport function signedHistoryEpochIds(input: {\n  readonly headManifestHash: string;\n  readonly kek: ProjectionKek;\n  readonly verifiedByHash: VerifiedManifests;\n}): Set<string> {\n  const epochIds = manifestHistoryEpochIds(input.kek);\n  const visited = new Set<string>();\n  let current = input.verifiedByHash.get(input.headManifestHash);\n  while (\n    current &&\n    current.state.containerId === input.kek.containerId &&\n    !visited.has(current.manifestHash)\n  ) {\n    visited.add(current.manifestHash);\n    const epochId = current.state.containerKeyEpochId;\n    if (epochId !== null && epochId !== input.kek.containerKeyEpochId) {\n      epochIds.add(epochId);\n    }\n    const previousHash = current.state.previousManifestHash;\n    current =\n      previousHash === null\n        ? undefined\n        : input.verifiedByHash.get(previousHash);\n  }\n  return epochIds;\n}\n\nfunction admitKeyringEntry(input: {\n  entry: Awaited<ReturnType<typeof openContainerKekKeyring>>[number];\n  index: number;\n  kek: ProjectionKek;\n  keksByEpochId: Map<string, UnwrappedContainerKek>;\n}): void {\n  const { entry, kek } = input;\n  const cached = input.keksByEpochId.get(entry.containerKeyEpochId);\n  if (cached) {\n    if (cached.containerId !== kek.containerId) {\n      throw new Error(\n        `${projectionKekLabel(input.index)} cached historical KEK is inconsistent`,\n      );\n    }\n    return;\n  }\n  input.keksByEpochId.set(entry.containerKeyEpochId, {\n    containerId: kek.containerId,\n    // A keyring entry is key material plus the epoch id that commits to it —\n    // there is no epoch record, so no fingerprint. Selection falls back to the\n    // epoch id and AEAD authenticates; the commitment check above is what\n    // makes the material itself trustworthy.\n    keyEpochHash: null,\n    keyMaterial: entry.keyMaterial,\n  });\n}\n\n/**\n * Opens the sealed keyring for one path index and admits every entry into\n * `keksByEpochId` after verifying it against the material-id commitment its\n * ordinal position implies (entry i is key epoch i + 1). No chain walk:\n * one decrypt yields the container's complete retained history, and entry\n * verification is independent per entry.\n */\nexport async function unwrapKeyringContainerKeksAtIndex(input: {\n  currentManifest: ContainerWriterProjectionResponse[\"path\"][number];\n  index: number;\n  kek: ProjectionKek;\n  keksByEpochId: Map<string, UnwrappedContainerKek>;\n  successorKeyMaterial: Uint8Array | null;\n  /** Every manifest projection verification recorded; anchors the keyring. */\n  verifiedByHash: VerifiedManifests;\n  verifyKeyringCommitment: boolean;\n}): Promise<void> {\n  const { kek, successorKeyMaterial } = input;\n  if (!successorKeyMaterial) {\n    return;\n  }\n\n  if (kek.keyring === null) {\n    if (kek.containerKeyEpoch !== 1) {\n      throw new ContainerKekHistoryUnavailableError(\n        projectionKekLabel(input.index),\n      );\n    }\n    return;\n  }\n\n  const entries = await openVerifiedKeyringEntries({\n    currentManifest: input.currentManifest,\n    index: input.index,\n    kek,\n    successorKeyMaterial,\n    verifiedByHash: input.verifiedByHash,\n    verifyKeyringCommitment: input.verifyKeyringCommitment,\n  });\n  for (const entry of entries) {\n    admitKeyringEntry({\n      entry,\n      index: input.index,\n      kek,\n      keksByEpochId: input.keksByEpochId,\n    });\n  }\n}\n\n/**\n * Epoch ids this projection implies exist but that were not recovered —\n * used to attribute history failures to the material they orphan.\n */\nexport function projectedUnreachablePredecessorEpochIds(input: {\n  kek: ProjectionKek;\n  keksByEpochId: ReadonlyMap<string, UnwrappedContainerKek>;\n}): string[] {\n  const projectedEpochIds = new Set<string>();\n  for (const bundle of sameContainerManifestHistory(input.kek)) {\n    const state = readCanonicalRecord(\n      bundle.state,\n      \"Container writer projection historical manifest state\",\n    );\n    const containerKeyEpochId = Reflect.get(state, \"containerKeyEpochId\");\n    if (typeof containerKeyEpochId === \"string\") {\n      projectedEpochIds.add(containerKeyEpochId);\n    }\n  }\n  projectedEpochIds.delete(input.kek.containerKeyEpochId);\n  return [...projectedEpochIds].filter(\n    (containerKeyEpochId) => !input.keksByEpochId.has(containerKeyEpochId),\n  );\n}\n"]}