@tearleads/client-sdk 0.1.63 → 0.1.65

package/data/documents/shared/containerKek/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/containerKek/containerKekPathHistory.js

@@ -0,0 +1,223 @@
+import { computeContainerKekKeyringHash, computeContainerKekMaterialId, isContainerKekMaterialId, KeyingVerificationError, normalizeContainerAccessEventBody, normalizeContainerKekKeyring, openContainerKekKeyring, } from "../../../../internal/crypto/index.js";
+import { readCanonicalJson, readCanonicalRecord, } from "../../../keying/canonicalJson.js";
+import { readContainerKeyEpoch } from "../../../keyingProjectionVerification/readers.js";
+import { readManifestContainerId } from "../readers.js";
+import { verifyContainerKekEntries } from "./containerKekEntryVerification.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/containerKek/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 \"../../../keying/canonicalJson\";\nimport { readContainerKeyEpoch } from \"../../../keyingProjectionVerification/readers\";\nimport { readManifestContainerId } from \"../readers\";\nimport type { UnwrappedContainerKek } from \"../types\";\nimport { verifyContainerKekEntries } from \"./containerKekEntryVerification\";\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"]}

package/data/documents/shared/containerKek/containerKekPathVerification.d.ts

@@ -0,0 +1,15 @@
+import type { VerifiedContainerAccessManifest } from "../../../../internal/crypto/index.js";
+import type { ContainerWriterProjectionResponse } from "../../../../internal/validators/response/index.js";
+import { type PrincipalPolicyCache } from "../../../keyingProjectionVerification/index.js";
+import type { ExecSql } from "../../../sqlite/sqlSchema.js";
+import type { ProjectionVerificationOptions } from "../types.js";
+export type UnwrapContainerKekPathInput = {
+    execSql?: ExecSql | undefined;
+    knownContainerKeks?: ReadonlyMap<string, Uint8Array> | undefined;
+    persistVerificationCheckpoints?: boolean | undefined;
+    principalPolicyCache?: PrincipalPolicyCache | undefined;
+    projection: ContainerWriterProjectionResponse;
+    secretKey: Uint8Array;
+    verifiedByHash?: Map<string, VerifiedContainerAccessManifest> | undefined;
+} & ProjectionVerificationOptions;
+export declare function verifyContainerKekPathProjection(input: UnwrapContainerKekPathInput): Promise<void>;

package/data/documents/shared/containerKek/containerKekPathVerification.js

@@ -0,0 +1,23 @@
+import { collectContainerWriterProjectionPrincipalPolicies, } from "../../../keyingProjectionVerification/index.js";
+import { resolveProjectionVerifier } from "../types.js";
+export async function verifyContainerKekPathProjection(input) {
+    if (input.projection.path.length !== input.projection.containerKeks.length) {
+        throw new Error("Container writer projection path and KEKs are inconsistent");
+    }
+    const resolveProjectionUserKey = resolveProjectionVerifier(input, "Container KEK unwrap");
+    if (input.trustedLocalProjection === true ||
+        resolveProjectionUserKey === null) {
+        return;
+    }
+    await collectContainerWriterProjectionPrincipalPolicies({
+        execSql: input.execSql,
+        persistVerificationCheckpoints: input.persistVerificationCheckpoints,
+        principalPolicyCache: input.principalPolicyCache,
+        projection: input.projection,
+        resolveUserKey: resolveProjectionUserKey,
+        stillCurrent: input.stillCurrent,
+        verifiedByHash: input.verifiedByHash,
+        warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,
+    });
+}
+//# sourceMappingURL=containerKekPathVerification.js.map

package/data/documents/shared/containerKek/containerKekPathVerification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerKekPathVerification.js","sourceRoot":"","sources":["containerKekPathVerification.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,iDAAiD,GAElD,MAAM,uCAAuC,CAAC;AAG/C,OAAO,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAYrD,MAAM,CAAC,KAAK,UAAU,gCAAgC,CACpD,KAAkC;IAElC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,UAAU,CAAC,aAAa,CAAC,MAAM,EAAE,CAAC;QAC3E,MAAM,IAAI,KAAK,CACb,4DAA4D,CAC7D,CAAC;IACJ,CAAC;IACD,MAAM,wBAAwB,GAAG,yBAAyB,CACxD,KAAK,EACL,sBAAsB,CACvB,CAAC;IACF,IACE,KAAK,CAAC,sBAAsB,KAAK,IAAI;QACrC,wBAAwB,KAAK,IAAI,EACjC,CAAC;QACD,OAAO;IACT,CAAC;IAED,MAAM,iDAAiD,CAAC;QACtD,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,8BAA8B,EAAE,KAAK,CAAC,8BAA8B;QACpE,oBAAoB,EAAE,KAAK,CAAC,oBAAoB;QAChD,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,cAAc,EAAE,wBAAwB;QACxC,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,+BAA+B,EAAE,KAAK,CAAC,+BAA+B;KACvE,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { VerifiedContainerAccessManifest } from \"@tearleads/crypto\";\nimport type { ContainerWriterProjectionResponse } from \"@tearleads/validators/response\";\nimport {\n  collectContainerWriterProjectionPrincipalPolicies,\n  type PrincipalPolicyCache,\n} from \"../../../keyingProjectionVerification\";\nimport type { ExecSql } from \"../../../sqlite/sqlSchema\";\nimport type { ProjectionVerificationOptions } from \"../types\";\nimport { resolveProjectionVerifier } from \"../types\";\n\nexport type UnwrapContainerKekPathInput = {\n  execSql?: ExecSql | undefined;\n  knownContainerKeks?: ReadonlyMap<string, Uint8Array> | undefined;\n  persistVerificationCheckpoints?: boolean | undefined;\n  principalPolicyCache?: PrincipalPolicyCache | undefined;\n  projection: ContainerWriterProjectionResponse;\n  secretKey: Uint8Array;\n  verifiedByHash?: Map<string, VerifiedContainerAccessManifest> | undefined;\n} & ProjectionVerificationOptions;\n\nexport async function verifyContainerKekPathProjection(\n  input: UnwrapContainerKekPathInput,\n): Promise<void> {\n  if (input.projection.path.length !== input.projection.containerKeks.length) {\n    throw new Error(\n      \"Container writer projection path and KEKs are inconsistent\",\n    );\n  }\n  const resolveProjectionUserKey = resolveProjectionVerifier(\n    input,\n    \"Container KEK unwrap\",\n  );\n  if (\n    input.trustedLocalProjection === true ||\n    resolveProjectionUserKey === null\n  ) {\n    return;\n  }\n\n  await collectContainerWriterProjectionPrincipalPolicies({\n    execSql: input.execSql,\n    persistVerificationCheckpoints: input.persistVerificationCheckpoints,\n    principalPolicyCache: input.principalPolicyCache,\n    projection: input.projection,\n    resolveUserKey: resolveProjectionUserKey,\n    stillCurrent: input.stillCurrent,\n    verifiedByHash: input.verifiedByHash,\n    warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,\n  });\n}\n"]}

package/data/documents/shared/containerKek/containerKekWrapping.js

@@ -0,0 +1,61 @@
+import { deriveContainerKekWrappingPublicKey, unwrapContainerKekParentWrap, } from "../../../../internal/crypto/index.js";
+import { isPlainObject as isPlainRecord } from "../../../../internal/validators/isPlainObject.js";
+import { readManifestContainerId } from "../readers.js";
+import { projectionKekLabel } from "./containerKekPathHistory.js";
+export async function unwrapContainerKekFromParentWrap(input) {
+    if (!input.parentContainerKeyEpochId) {
+        return null;
+    }
+    const parentKek = input.parentKeksByEpochId.get(input.parentContainerKeyEpochId);
+    if (!parentKek) {
+        return null;
+    }
+    // The epoch-record fingerprint is a SELECTOR for picking the right envelope
+    // among several, not the security boundary — the AEAD tag below is what
+    // authenticates the parent key. Keyring-recovered historical KEKs carry no
+    // epoch record (only the material and the epoch id that commits to it), so
+    // for those the epoch id alone selects and decryption authenticates.
+    //
+    // Without this, an ancestor rotation would strand every descendant still
+    // pinned to the predecessor epoch: opening the descendant requires the
+    // parent's historical KEK, and that is exactly the key a lazy rekey needs in
+    // order to materialize a post-rotation epoch. A cold client would have no
+    // way back in.
+    const parentWrap = input.wraps.find((wrap) => wrap.recipientKind === "container" &&
+        wrap.recipientId === parentKek.containerId &&
+        wrap.recipientKeyEpochId === input.parentContainerKeyEpochId &&
+        (parentKek.keyEpochHash === null ||
+            wrap.recipientKeyFingerprint === parentKek.keyEpochHash));
+    if (!parentWrap) {
+        return null;
+    }
+    try {
+        return await unwrapContainerKekParentWrap({
+            parentContainerId: parentKek.containerId,
+            parentKeyMaterial: parentKek.keyMaterial,
+            kemCipherText: parentWrap.kemCipherText,
+            wrappedKey: parentWrap.wrappedKey,
+        });
+    }
+    catch (error) {
+        throw new Error(`${input.label} parent wrap could not be unwrapped`, {
+            cause: error,
+        });
+    }
+}
+export async function assertSignedWrappingPublicKey(projection, index, keyMaterial) {
+    const manifest = projection.path[index];
+    if (!manifest || !isPlainRecord(manifest.state))
+        throw new Error("Container manifest is missing");
+    const containerId = readManifestContainerId(manifest);
+    if (!containerId)
+        throw new Error("Container manifest ID is missing");
+    const publicKey = await deriveContainerKekWrappingPublicKey({
+        containerId,
+        keyMaterial,
+    });
+    if (Reflect.get(manifest.state, "containerKeyPublicKey") !== publicKey) {
+        throw new Error(`${projectionKekLabel(index)} wrapping public key does not match KEK material`);
+    }
+}
+//# sourceMappingURL=containerKekWrapping.js.map

package/data/documents/shared/containerKek/containerKekWrapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerKekWrapping.js","sourceRoot":"","sources":["containerKekWrapping.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,mCAAmC,EACnC,4BAA4B,GAC7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,IAAI,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAErF,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,MAAM,CAAC,KAAK,UAAU,gCAAgC,CAAC,KAKtD;IACC,IAAI,CAAC,KAAK,CAAC,yBAAyB,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,mBAAmB,CAAC,GAAG,CAC7C,KAAK,CAAC,yBAAyB,CAChC,CAAC;IACF,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IAED,4EAA4E;IAC5E,wEAAwE;IACxE,2EAA2E;IAC3E,2EAA2E;IAC3E,qEAAqE;IACrE,EAAE;IACF,yEAAyE;IACzE,uEAAuE;IACvE,6EAA6E;IAC7E,0EAA0E;IAC1E,eAAe;IACf,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CACjC,CAAC,IAAI,EAAE,EAAE,CACP,IAAI,CAAC,aAAa,KAAK,WAAW;QAClC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,WAAW;QAC1C,IAAI,CAAC,mBAAmB,KAAK,KAAK,CAAC,yBAAyB;QAC5D,CAAC,SAAS,CAAC,YAAY,KAAK,IAAI;YAC9B,IAAI,CAAC,uBAAuB,KAAK,SAAS,CAAC,YAAY,CAAC,CAC7D,CAAC;IACF,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,OAAO,MAAM,4BAA4B,CAAC;YACxC,iBAAiB,EAAE,SAAS,CAAC,WAAW;YACxC,iBAAiB,EAAE,SAAS,CAAC,WAAW;YACxC,aAAa,EAAE,UAAU,CAAC,aAAa;YACvC,UAAU,EAAE,UAAU,CAAC,UAAU;SAClC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,CAAC,KAAK,qCAAqC,EAAE;YACnE,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,UAA6C,EAC7C,KAAa,EACb,WAAuB;IAEvB,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxC,IAAI,CAAC,QAAQ,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACnD,MAAM,WAAW,GAAG,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IACtD,IAAI,CAAC,WAAW;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtE,MAAM,SAAS,GAAG,MAAM,mCAAmC,CAAC;QAC1D,WAAW;QACX,WAAW;KACZ,CAAC,CAAC;IACH,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,uBAAuB,CAAC,KAAK,SAAS,EAAE,CAAC;QACvE,MAAM,IAAI,KAAK,CACb,GAAG,kBAAkB,CAAC,KAAK,CAAC,kDAAkD,CAC/E,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["import {\n  type ContainerKeyWrap,\n  deriveContainerKekWrappingPublicKey,\n  unwrapContainerKekParentWrap,\n} from \"@tearleads/crypto\";\nimport { isPlainObject as isPlainRecord } from \"@tearleads/validators/isPlainObject\";\nimport type { ContainerWriterProjectionResponse } from \"@tearleads/validators/response\";\nimport { readManifestContainerId } from \"../readers\";\nimport type { UnwrappedContainerKek } from \"../types\";\nimport { projectionKekLabel } from \"./containerKekPathHistory\";\n\nexport async function unwrapContainerKekFromParentWrap(input: {\n  label: string;\n  parentContainerKeyEpochId: string | null;\n  parentKeksByEpochId: ReadonlyMap<string, UnwrappedContainerKek>;\n  wraps: readonly ContainerKeyWrap[];\n}): Promise<Uint8Array | null> {\n  if (!input.parentContainerKeyEpochId) {\n    return null;\n  }\n\n  const parentKek = input.parentKeksByEpochId.get(\n    input.parentContainerKeyEpochId,\n  );\n  if (!parentKek) {\n    return null;\n  }\n\n  // The epoch-record fingerprint is a SELECTOR for picking the right envelope\n  // among several, not the security boundary — the AEAD tag below is what\n  // authenticates the parent key. Keyring-recovered historical KEKs carry no\n  // epoch record (only the material and the epoch id that commits to it), so\n  // for those the epoch id alone selects and decryption authenticates.\n  //\n  // Without this, an ancestor rotation would strand every descendant still\n  // pinned to the predecessor epoch: opening the descendant requires the\n  // parent's historical KEK, and that is exactly the key a lazy rekey needs in\n  // order to materialize a post-rotation epoch. A cold client would have no\n  // way back in.\n  const parentWrap = input.wraps.find(\n    (wrap) =>\n      wrap.recipientKind === \"container\" &&\n      wrap.recipientId === parentKek.containerId &&\n      wrap.recipientKeyEpochId === input.parentContainerKeyEpochId &&\n      (parentKek.keyEpochHash === null ||\n        wrap.recipientKeyFingerprint === parentKek.keyEpochHash),\n  );\n  if (!parentWrap) {\n    return null;\n  }\n\n  try {\n    return await unwrapContainerKekParentWrap({\n      parentContainerId: parentKek.containerId,\n      parentKeyMaterial: parentKek.keyMaterial,\n      kemCipherText: parentWrap.kemCipherText,\n      wrappedKey: parentWrap.wrappedKey,\n    });\n  } catch (error) {\n    throw new Error(`${input.label} parent wrap could not be unwrapped`, {\n      cause: error,\n    });\n  }\n}\n\nexport async function assertSignedWrappingPublicKey(\n  projection: ContainerWriterProjectionResponse,\n  index: number,\n  keyMaterial: Uint8Array,\n): Promise<void> {\n  const manifest = projection.path[index];\n  if (!manifest || !isPlainRecord(manifest.state))\n    throw new Error(\"Container manifest is missing\");\n  const containerId = readManifestContainerId(manifest);\n  if (!containerId) throw new Error(\"Container manifest ID is missing\");\n  const publicKey = await deriveContainerKekWrappingPublicKey({\n    containerId,\n    keyMaterial,\n  });\n  if (Reflect.get(manifest.state, \"containerKeyPublicKey\") !== publicKey) {\n    throw new Error(\n      `${projectionKekLabel(index)} wrapping public key does not match KEK material`,\n    );\n  }\n}\n"]}

package/data/documents/shared/containerKek/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>;