@tearleads/client-sdk 0.0.0-stage → 0.1.11

package/internal/crypto/keying/containerKekKeyring.js

@@ -0,0 +1,236 @@
+import { base64ToBytes, bytesToBase64 } from "../../encoding/index.js";
+import { SEALED_CONTAINER_KEK_KEYRING_AEAD_OVERHEAD_BYTES, SEALED_CONTAINER_KEK_KEYRING_ENTRY_BYTES, SEALED_CONTAINER_KEK_KEYRING_HEADER_BYTES, sealedContainerKekKeyringBytes, } from "../../validators/util/index.js";
+import { bytesToHex, hexToBytes } from "../hex.js";
+import { AES_GCM_TAG_BYTES, assertAesGcmIv, decryptWithDek, encryptWithDek, } from "../symmetric.js";
+import { computeKeyingDomainHash, serializeKeyingCanonicalJson, } from "./canonical.js";
+import { computeContainerKekMaterialId, isContainerKekMaterialId, } from "./containerKekMaterial.js";
+import { assertExactKeys, readPositiveInteger, readString, throwVerification, } from "./shared.js";
+import { CONTAINER_KEK_KEYRING_SEAL_SUITE, CONTAINER_KEK_MATERIAL_ID_PREFIX, MAX_CONTAINER_KEY_EPOCH, } from "./types.js";
+const TEXT_ENCODER = new TextEncoder();
+/**
+ * Sealed-keyring plaintext layout, fixed width by construction:
+ * an 8-byte header (u32 BE format version, u32 BE entry count) followed by one
+ * 64-byte record per predecessor epoch in ascending epoch order (32-byte
+ * material-id hash, 32-byte key material). Entry ordinal i therefore IS key
+ * epoch i + 1, and the sealed byte length for key epoch n is an equality,
+ * never a bound. The arithmetic lives in @tearleads/validators so request
+ * and response guards share it.
+ */
+export const CONTAINER_KEK_KEYRING_FORMAT_VERSION = 1;
+export const CONTAINER_KEK_KEYRING_HEADER_BYTES = SEALED_CONTAINER_KEK_KEYRING_HEADER_BYTES;
+export const CONTAINER_KEK_KEYRING_ENTRY_BYTES = SEALED_CONTAINER_KEK_KEYRING_ENTRY_BYTES;
+if (SEALED_CONTAINER_KEK_KEYRING_AEAD_OVERHEAD_BYTES !== AES_GCM_TAG_BYTES) {
+    throw new Error("Container KEK keyring wire overhead does not match the AES-GCM tag size");
+}
+export function expectedSealedContainerKekKeyringBytes(keyEpoch) {
+    assertKeyringKeyEpoch(keyEpoch);
+    return sealedContainerKekKeyringBytes(keyEpoch);
+}
+function assertKeyringKeyEpoch(keyEpoch) {
+    if (!Number.isInteger(keyEpoch) ||
+        keyEpoch < 2 ||
+        keyEpoch > MAX_CONTAINER_KEY_EPOCH) {
+        throwVerification("invalid_shape", "container KEK keyring key epoch must be an integer in [2, MAX_CONTAINER_KEY_EPOCH]");
+    }
+}
+function keyringAdditionalData(input) {
+    return TEXT_ENCODER.encode(serializeKeyingCanonicalJson({
+        domain: "tearleads.container-kek-keyring.aad",
+        payload: {
+            version: 1,
+            sealingSuite: CONTAINER_KEK_KEYRING_SEAL_SUITE,
+            containerId: input.containerId,
+            containerKeyEpochId: input.containerKeyEpochId,
+        },
+    }));
+}
+function canonicalBase64(value, label) {
+    let bytes;
+    try {
+        bytes = base64ToBytes(value);
+    }
+    catch {
+        throwVerification("invalid_shape", `${label} must be base64`);
+    }
+    if (bytesToBase64(bytes) !== value) {
+        throwVerification("invalid_shape", `${label} must use canonical base64`);
+    }
+    return bytes;
+}
+function materialIdHashBytes(containerKeyEpochId, label) {
+    if (!isContainerKekMaterialId(containerKeyEpochId)) {
+        throwVerification("invalid_shape", `${label} must commit to key material`);
+    }
+    return hexToBytes(containerKeyEpochId.slice(CONTAINER_KEK_MATERIAL_ID_PREFIX.length));
+}
+function materialIdFromHashBytes(hashBytes) {
+    return `${CONTAINER_KEK_MATERIAL_ID_PREFIX}${bytesToHex(hashBytes)}`;
+}
+export function normalizeContainerKekKeyring(value) {
+    const record = assertExactKeys(value, [
+        "containerId",
+        "containerKeyEpochId",
+        "iv",
+        "sealed",
+        "sealingSuite",
+        "version",
+    ], "container KEK keyring");
+    const version = readPositiveInteger(record, "version", "container KEK keyring");
+    if (version !== 1) {
+        throwVerification("invalid_shape", "container KEK keyring version is unsupported");
+    }
+    const sealingSuite = readString(record, "sealingSuite", "container KEK keyring");
+    if (sealingSuite !== CONTAINER_KEK_KEYRING_SEAL_SUITE) {
+        throwVerification("invalid_shape", "container KEK keyring sealing suite is unsupported");
+    }
+    const keyring = {
+        version: 1,
+        sealingSuite: CONTAINER_KEK_KEYRING_SEAL_SUITE,
+        containerId: readString(record, "containerId", "container KEK keyring"),
+        containerKeyEpochId: readString(record, "containerKeyEpochId", "container KEK keyring"),
+        iv: readString(record, "iv", "container KEK keyring"),
+        sealed: readString(record, "sealed", "container KEK keyring"),
+    };
+    if (keyring.containerId.length === 0) {
+        throwVerification("invalid_shape", "container KEK keyring container id must not be empty");
+    }
+    if (!isContainerKekMaterialId(keyring.containerKeyEpochId)) {
+        throwVerification("invalid_shape", "container KEK keyring sealing epoch id must commit to key material");
+    }
+    const iv = canonicalBase64(keyring.iv, "container KEK keyring.iv");
+    assertAesGcmIv(iv, "Container KEK keyring IV must be 12 bytes");
+    const sealed = canonicalBase64(keyring.sealed, "container KEK keyring.sealed");
+    const bodyBytes = sealed.byteLength - CONTAINER_KEK_KEYRING_HEADER_BYTES - AES_GCM_TAG_BYTES;
+    if (bodyBytes < CONTAINER_KEK_KEYRING_ENTRY_BYTES ||
+        bodyBytes % CONTAINER_KEK_KEYRING_ENTRY_BYTES !== 0 ||
+        bodyBytes / CONTAINER_KEK_KEYRING_ENTRY_BYTES > MAX_CONTAINER_KEY_EPOCH - 1) {
+        throwVerification("invalid_shape", "container KEK keyring sealed length is not a whole entry count");
+    }
+    return keyring;
+}
+/** Enforces the exact-length equality for a keyring sealed at `keyEpoch`. */
+export function assertSealedContainerKekKeyringLength(keyring, keyEpoch) {
+    const sealed = base64ToBytes(keyring.sealed);
+    if (sealed.byteLength !== expectedSealedContainerKekKeyringBytes(keyEpoch)) {
+        throwVerification("invalid_shape", "container KEK keyring sealed length does not match its key epoch");
+    }
+}
+export async function computeContainerKekKeyringHash(value) {
+    const keyring = normalizeContainerKekKeyring(value);
+    return computeKeyingDomainHash("tearleads.keying.container-kek-keyring", {
+        version: keyring.version,
+        sealingSuite: keyring.sealingSuite,
+        containerId: keyring.containerId,
+        containerKeyEpochId: keyring.containerKeyEpochId,
+        iv: keyring.iv,
+        sealed: keyring.sealed,
+    });
+}
+function encodeKeyringEntries(entries) {
+    const plaintext = new Uint8Array(CONTAINER_KEK_KEYRING_HEADER_BYTES +
+        entries.length * CONTAINER_KEK_KEYRING_ENTRY_BYTES);
+    const view = new DataView(plaintext.buffer);
+    view.setUint32(0, CONTAINER_KEK_KEYRING_FORMAT_VERSION);
+    view.setUint32(4, entries.length);
+    for (const [index, entry] of entries.entries()) {
+        const offset = CONTAINER_KEK_KEYRING_HEADER_BYTES +
+            index * CONTAINER_KEK_KEYRING_ENTRY_BYTES;
+        plaintext.set(materialIdHashBytes(entry.containerKeyEpochId, `container KEK keyring entry ${index} epoch id`), offset);
+        plaintext.set(entry.keyMaterial, offset + 32);
+    }
+    return plaintext;
+}
+function assertSealableEntries(input) {
+    assertKeyringKeyEpoch(input.keyEpoch);
+    if (input.entries.length !== input.keyEpoch - 1) {
+        throwVerification("invalid_shape", "container KEK keyring must contain exactly one entry per predecessor epoch");
+    }
+    if (input.successorContainerKey.byteLength !== 32) {
+        throwVerification("invalid_shape", "container KEK keyring sealing key must be 32 bytes");
+    }
+    const seenMaterial = new Set([bytesToHex(input.successorContainerKey)]);
+    const seenEpochIds = new Set([input.successorContainerKeyEpochId]);
+    for (const [index, entry] of input.entries.entries()) {
+        if (entry.keyMaterial.byteLength !== 32) {
+            throwVerification("invalid_shape", `container KEK keyring entry ${index} key material must be 32 bytes`);
+        }
+        const materialHex = bytesToHex(entry.keyMaterial);
+        if (seenMaterial.has(materialHex) ||
+            seenEpochIds.has(entry.containerKeyEpochId)) {
+            throwVerification("key_epoch_reuse", `container KEK keyring entry ${index} reuses key material`);
+        }
+        seenMaterial.add(materialHex);
+        seenEpochIds.add(entry.containerKeyEpochId);
+    }
+}
+export async function sealContainerKekKeyring(input) {
+    assertSealableEntries(input);
+    const metadata = {
+        containerId: input.containerId,
+        containerKeyEpochId: input.successorContainerKeyEpochId,
+    };
+    const encrypted = await encryptWithDek(encodeKeyringEntries(input.entries), input.successorContainerKey, keyringAdditionalData(metadata));
+    const keyring = {
+        version: 1,
+        sealingSuite: CONTAINER_KEK_KEYRING_SEAL_SUITE,
+        containerId: input.containerId,
+        containerKeyEpochId: input.successorContainerKeyEpochId,
+        iv: bytesToBase64(encrypted.iv),
+        sealed: bytesToBase64(encrypted.ciphertext),
+    };
+    assertSealedContainerKekKeyringLength(keyring, input.keyEpoch);
+    const reopened = await openContainerKekKeyring({
+        keyEpoch: input.keyEpoch,
+        keyring,
+        successorContainerKey: input.successorContainerKey,
+    });
+    for (const [index, entry] of reopened.entries()) {
+        const sealedEntry = input.entries[index];
+        if (!sealedEntry ||
+            entry.containerKeyEpochId !== sealedEntry.containerKeyEpochId) {
+            throwVerification("hash_mismatch", "container KEK keyring failed local round-trip verification");
+        }
+    }
+    return keyring;
+}
+export async function openContainerKekKeyring(input) {
+    const keyring = normalizeContainerKekKeyring(input.keyring);
+    assertSealedContainerKekKeyringLength(keyring, input.keyEpoch);
+    const plaintext = await decryptWithDek({
+        iv: base64ToBytes(keyring.iv),
+        ciphertext: base64ToBytes(keyring.sealed),
+    }, input.successorContainerKey, keyringAdditionalData(keyring));
+    const view = new DataView(plaintext.buffer, plaintext.byteOffset, plaintext.byteLength);
+    if (view.getUint32(0) !== CONTAINER_KEK_KEYRING_FORMAT_VERSION) {
+        throwVerification("invalid_shape", "container KEK keyring format version is unsupported");
+    }
+    const entryCount = view.getUint32(4);
+    if (entryCount !== input.keyEpoch - 1) {
+        throwVerification("invalid_shape", "container KEK keyring entry count does not match its key epoch");
+    }
+    const entries = [];
+    for (let index = 0; index < entryCount; index += 1) {
+        const offset = CONTAINER_KEK_KEYRING_HEADER_BYTES +
+            index * CONTAINER_KEK_KEYRING_ENTRY_BYTES;
+        entries.push({
+            containerKeyEpochId: materialIdFromHashBytes(plaintext.subarray(offset, offset + 32)),
+            keyMaterial: plaintext.slice(offset + 32, offset + 64),
+        });
+    }
+    return entries;
+}
+/**
+ * A memoized material check: proves a recovered entry is THE key the
+ * manifest-anchored epoch id commits to. Entry ordinal i is key epoch i + 1.
+ */
+export async function verifyContainerKekKeyringEntry(input) {
+    const expectedId = await computeContainerKekMaterialId({
+        containerId: input.containerId,
+        keyEpoch: input.keyEpoch,
+        keyMaterial: input.entry.keyMaterial,
+    });
+    if (expectedId !== input.entry.containerKeyEpochId) {
+        throwVerification("hash_mismatch", "container KEK keyring entry does not match its committed epoch id");
+    }
+}
+//# sourceMappingURL=containerKekKeyring.js.map

package/internal/crypto/keying/containerKekKeyring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerKekKeyring.js","sourceRoot":"","sources":["containerKekKeyring.ts"],"names":[],"mappings":"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","sourcesContent":["import { base64ToBytes, bytesToBase64 } from \"@tearleads/encoding\";\nimport {\n  SEALED_CONTAINER_KEK_KEYRING_AEAD_OVERHEAD_BYTES,\n  SEALED_CONTAINER_KEK_KEYRING_ENTRY_BYTES,\n  SEALED_CONTAINER_KEK_KEYRING_HEADER_BYTES,\n  sealedContainerKekKeyringBytes,\n} from \"@tearleads/validators/util\";\nimport { bytesToHex, hexToBytes } from \"../hex\";\nimport {\n  AES_GCM_TAG_BYTES,\n  assertAesGcmIv,\n  decryptWithDek,\n  encryptWithDek,\n} from \"../symmetric\";\nimport {\n  computeKeyingDomainHash,\n  serializeKeyingCanonicalJson,\n} from \"./canonical\";\nimport {\n  computeContainerKekMaterialId,\n  isContainerKekMaterialId,\n} from \"./containerKekMaterial\";\nimport {\n  assertExactKeys,\n  readPositiveInteger,\n  readString,\n  throwVerification,\n} from \"./shared\";\nimport {\n  CONTAINER_KEK_KEYRING_SEAL_SUITE,\n  CONTAINER_KEK_MATERIAL_ID_PREFIX,\n  type ContainerKekKeyring,\n  type ContainerKekKeyringEntry,\n  MAX_CONTAINER_KEY_EPOCH,\n} from \"./types\";\n\nconst TEXT_ENCODER = new TextEncoder();\n\n/**\n * Sealed-keyring plaintext layout, fixed width by construction:\n * an 8-byte header (u32 BE format version, u32 BE entry count) followed by one\n * 64-byte record per predecessor epoch in ascending epoch order (32-byte\n * material-id hash, 32-byte key material). Entry ordinal i therefore IS key\n * epoch i + 1, and the sealed byte length for key epoch n is an equality,\n * never a bound. The arithmetic lives in @tearleads/validators so request\n * and response guards share it.\n */\nexport const CONTAINER_KEK_KEYRING_FORMAT_VERSION = 1;\nexport const CONTAINER_KEK_KEYRING_HEADER_BYTES =\n  SEALED_CONTAINER_KEK_KEYRING_HEADER_BYTES;\nexport const CONTAINER_KEK_KEYRING_ENTRY_BYTES =\n  SEALED_CONTAINER_KEK_KEYRING_ENTRY_BYTES;\n\nif (SEALED_CONTAINER_KEK_KEYRING_AEAD_OVERHEAD_BYTES !== AES_GCM_TAG_BYTES) {\n  throw new Error(\n    \"Container KEK keyring wire overhead does not match the AES-GCM tag size\",\n  );\n}\n\nexport function expectedSealedContainerKekKeyringBytes(\n  keyEpoch: number,\n): number {\n  assertKeyringKeyEpoch(keyEpoch);\n  return sealedContainerKekKeyringBytes(keyEpoch);\n}\n\nfunction assertKeyringKeyEpoch(keyEpoch: number): void {\n  if (\n    !Number.isInteger(keyEpoch) ||\n    keyEpoch < 2 ||\n    keyEpoch > MAX_CONTAINER_KEY_EPOCH\n  ) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK keyring key epoch must be an integer in [2, MAX_CONTAINER_KEY_EPOCH]\",\n    );\n  }\n}\n\nfunction keyringAdditionalData(input: {\n  containerId: string;\n  containerKeyEpochId: string;\n}): Uint8Array<ArrayBuffer> {\n  return TEXT_ENCODER.encode(\n    serializeKeyingCanonicalJson({\n      domain: \"tearleads.container-kek-keyring.aad\",\n      payload: {\n        version: 1,\n        sealingSuite: CONTAINER_KEK_KEYRING_SEAL_SUITE,\n        containerId: input.containerId,\n        containerKeyEpochId: input.containerKeyEpochId,\n      },\n    }),\n  );\n}\n\nfunction canonicalBase64(value: string, label: string): Uint8Array {\n  let bytes: Uint8Array;\n  try {\n    bytes = base64ToBytes(value);\n  } catch {\n    throwVerification(\"invalid_shape\", `${label} must be base64`);\n  }\n  if (bytesToBase64(bytes) !== value) {\n    throwVerification(\"invalid_shape\", `${label} must use canonical base64`);\n  }\n  return bytes;\n}\n\nfunction materialIdHashBytes(\n  containerKeyEpochId: string,\n  label: string,\n): Uint8Array {\n  if (!isContainerKekMaterialId(containerKeyEpochId)) {\n    throwVerification(\"invalid_shape\", `${label} must commit to key material`);\n  }\n  return hexToBytes(\n    containerKeyEpochId.slice(CONTAINER_KEK_MATERIAL_ID_PREFIX.length),\n  );\n}\n\nfunction materialIdFromHashBytes(hashBytes: Uint8Array): string {\n  return `${CONTAINER_KEK_MATERIAL_ID_PREFIX}${bytesToHex(hashBytes)}`;\n}\n\nexport function normalizeContainerKekKeyring(\n  value: unknown,\n): ContainerKekKeyring {\n  const record = assertExactKeys(\n    value,\n    [\n      \"containerId\",\n      \"containerKeyEpochId\",\n      \"iv\",\n      \"sealed\",\n      \"sealingSuite\",\n      \"version\",\n    ],\n    \"container KEK keyring\",\n  );\n  const version = readPositiveInteger(\n    record,\n    \"version\",\n    \"container KEK keyring\",\n  );\n  if (version !== 1) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK keyring version is unsupported\",\n    );\n  }\n  const sealingSuite = readString(\n    record,\n    \"sealingSuite\",\n    \"container KEK keyring\",\n  );\n  if (sealingSuite !== CONTAINER_KEK_KEYRING_SEAL_SUITE) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK keyring sealing suite is unsupported\",\n    );\n  }\n  const keyring: ContainerKekKeyring = {\n    version: 1,\n    sealingSuite: CONTAINER_KEK_KEYRING_SEAL_SUITE,\n    containerId: readString(record, \"containerId\", \"container KEK keyring\"),\n    containerKeyEpochId: readString(\n      record,\n      \"containerKeyEpochId\",\n      \"container KEK keyring\",\n    ),\n    iv: readString(record, \"iv\", \"container KEK keyring\"),\n    sealed: readString(record, \"sealed\", \"container KEK keyring\"),\n  };\n  if (keyring.containerId.length === 0) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK keyring container id must not be empty\",\n    );\n  }\n  if (!isContainerKekMaterialId(keyring.containerKeyEpochId)) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK keyring sealing epoch id must commit to key material\",\n    );\n  }\n  const iv = canonicalBase64(keyring.iv, \"container KEK keyring.iv\");\n  assertAesGcmIv(iv, \"Container KEK keyring IV must be 12 bytes\");\n  const sealed = canonicalBase64(\n    keyring.sealed,\n    \"container KEK keyring.sealed\",\n  );\n  const bodyBytes =\n    sealed.byteLength - CONTAINER_KEK_KEYRING_HEADER_BYTES - AES_GCM_TAG_BYTES;\n  if (\n    bodyBytes < CONTAINER_KEK_KEYRING_ENTRY_BYTES ||\n    bodyBytes % CONTAINER_KEK_KEYRING_ENTRY_BYTES !== 0 ||\n    bodyBytes / CONTAINER_KEK_KEYRING_ENTRY_BYTES > MAX_CONTAINER_KEY_EPOCH - 1\n  ) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK keyring sealed length is not a whole entry count\",\n    );\n  }\n  return keyring;\n}\n\n/** Enforces the exact-length equality for a keyring sealed at `keyEpoch`. */\nexport function assertSealedContainerKekKeyringLength(\n  keyring: ContainerKekKeyring,\n  keyEpoch: number,\n): void {\n  const sealed = base64ToBytes(keyring.sealed);\n  if (sealed.byteLength !== expectedSealedContainerKekKeyringBytes(keyEpoch)) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK keyring sealed length does not match its key epoch\",\n    );\n  }\n}\n\nexport async function computeContainerKekKeyringHash(\n  value: unknown,\n): Promise<string> {\n  const keyring = normalizeContainerKekKeyring(value);\n  return computeKeyingDomainHash(\"tearleads.keying.container-kek-keyring\", {\n    version: keyring.version,\n    sealingSuite: keyring.sealingSuite,\n    containerId: keyring.containerId,\n    containerKeyEpochId: keyring.containerKeyEpochId,\n    iv: keyring.iv,\n    sealed: keyring.sealed,\n  });\n}\n\nfunction encodeKeyringEntries(\n  entries: readonly ContainerKekKeyringEntry[],\n): Uint8Array {\n  const plaintext = new Uint8Array(\n    CONTAINER_KEK_KEYRING_HEADER_BYTES +\n      entries.length * CONTAINER_KEK_KEYRING_ENTRY_BYTES,\n  );\n  const view = new DataView(plaintext.buffer);\n  view.setUint32(0, CONTAINER_KEK_KEYRING_FORMAT_VERSION);\n  view.setUint32(4, entries.length);\n  for (const [index, entry] of entries.entries()) {\n    const offset =\n      CONTAINER_KEK_KEYRING_HEADER_BYTES +\n      index * CONTAINER_KEK_KEYRING_ENTRY_BYTES;\n    plaintext.set(\n      materialIdHashBytes(\n        entry.containerKeyEpochId,\n        `container KEK keyring entry ${index} epoch id`,\n      ),\n      offset,\n    );\n    plaintext.set(entry.keyMaterial, offset + 32);\n  }\n  return plaintext;\n}\n\nfunction assertSealableEntries(input: {\n  entries: readonly ContainerKekKeyringEntry[];\n  keyEpoch: number;\n  successorContainerKey: Uint8Array;\n  successorContainerKeyEpochId: string;\n}): void {\n  assertKeyringKeyEpoch(input.keyEpoch);\n  if (input.entries.length !== input.keyEpoch - 1) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK keyring must contain exactly one entry per predecessor epoch\",\n    );\n  }\n  if (input.successorContainerKey.byteLength !== 32) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK keyring sealing key must be 32 bytes\",\n    );\n  }\n  const seenMaterial = new Set([bytesToHex(input.successorContainerKey)]);\n  const seenEpochIds = new Set([input.successorContainerKeyEpochId]);\n  for (const [index, entry] of input.entries.entries()) {\n    if (entry.keyMaterial.byteLength !== 32) {\n      throwVerification(\n        \"invalid_shape\",\n        `container KEK keyring entry ${index} key material must be 32 bytes`,\n      );\n    }\n    const materialHex = bytesToHex(entry.keyMaterial);\n    if (\n      seenMaterial.has(materialHex) ||\n      seenEpochIds.has(entry.containerKeyEpochId)\n    ) {\n      throwVerification(\n        \"key_epoch_reuse\",\n        `container KEK keyring entry ${index} reuses key material`,\n      );\n    }\n    seenMaterial.add(materialHex);\n    seenEpochIds.add(entry.containerKeyEpochId);\n  }\n}\n\nexport async function sealContainerKekKeyring(input: {\n  containerId: string;\n  entries: readonly ContainerKekKeyringEntry[];\n  keyEpoch: number;\n  successorContainerKey: Uint8Array;\n  successorContainerKeyEpochId: string;\n}): Promise<ContainerKekKeyring> {\n  assertSealableEntries(input);\n  const metadata = {\n    containerId: input.containerId,\n    containerKeyEpochId: input.successorContainerKeyEpochId,\n  };\n  const encrypted = await encryptWithDek(\n    encodeKeyringEntries(input.entries),\n    input.successorContainerKey,\n    keyringAdditionalData(metadata),\n  );\n  const keyring: ContainerKekKeyring = {\n    version: 1,\n    sealingSuite: CONTAINER_KEK_KEYRING_SEAL_SUITE,\n    containerId: input.containerId,\n    containerKeyEpochId: input.successorContainerKeyEpochId,\n    iv: bytesToBase64(encrypted.iv),\n    sealed: bytesToBase64(encrypted.ciphertext),\n  };\n  assertSealedContainerKekKeyringLength(keyring, input.keyEpoch);\n  const reopened = await openContainerKekKeyring({\n    keyEpoch: input.keyEpoch,\n    keyring,\n    successorContainerKey: input.successorContainerKey,\n  });\n  for (const [index, entry] of reopened.entries()) {\n    const sealedEntry = input.entries[index];\n    if (\n      !sealedEntry ||\n      entry.containerKeyEpochId !== sealedEntry.containerKeyEpochId\n    ) {\n      throwVerification(\n        \"hash_mismatch\",\n        \"container KEK keyring failed local round-trip verification\",\n      );\n    }\n  }\n  return keyring;\n}\n\nexport async function openContainerKekKeyring(input: {\n  keyEpoch: number;\n  keyring: ContainerKekKeyring;\n  successorContainerKey: Uint8Array;\n}): Promise<ContainerKekKeyringEntry[]> {\n  const keyring = normalizeContainerKekKeyring(input.keyring);\n  assertSealedContainerKekKeyringLength(keyring, input.keyEpoch);\n  const plaintext = await decryptWithDek(\n    {\n      iv: base64ToBytes(keyring.iv),\n      ciphertext: base64ToBytes(keyring.sealed),\n    },\n    input.successorContainerKey,\n    keyringAdditionalData(keyring),\n  );\n  const view = new DataView(\n    plaintext.buffer,\n    plaintext.byteOffset,\n    plaintext.byteLength,\n  );\n  if (view.getUint32(0) !== CONTAINER_KEK_KEYRING_FORMAT_VERSION) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK keyring format version is unsupported\",\n    );\n  }\n  const entryCount = view.getUint32(4);\n  if (entryCount !== input.keyEpoch - 1) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK keyring entry count does not match its key epoch\",\n    );\n  }\n  const entries: ContainerKekKeyringEntry[] = [];\n  for (let index = 0; index < entryCount; index += 1) {\n    const offset =\n      CONTAINER_KEK_KEYRING_HEADER_BYTES +\n      index * CONTAINER_KEK_KEYRING_ENTRY_BYTES;\n    entries.push({\n      containerKeyEpochId: materialIdFromHashBytes(\n        plaintext.subarray(offset, offset + 32),\n      ),\n      keyMaterial: plaintext.slice(offset + 32, offset + 64),\n    });\n  }\n  return entries;\n}\n\n/**\n * A memoized material check: proves a recovered entry is THE key the\n * manifest-anchored epoch id commits to. Entry ordinal i is key epoch i + 1.\n */\nexport async function verifyContainerKekKeyringEntry(input: {\n  containerId: string;\n  entry: ContainerKekKeyringEntry;\n  keyEpoch: number;\n}): Promise<void> {\n  const expectedId = await computeContainerKekMaterialId({\n    containerId: input.containerId,\n    keyEpoch: input.keyEpoch,\n    keyMaterial: input.entry.keyMaterial,\n  });\n  if (expectedId !== input.entry.containerKeyEpochId) {\n    throwVerification(\n      \"hash_mismatch\",\n      \"container KEK keyring entry does not match its committed epoch id\",\n    );\n  }\n}\n"]}

package/internal/crypto/keying/containerKekMaterial.d.ts

@@ -0,0 +1,13 @@
+import { CONTAINER_KEK_MATERIAL_ID_PREFIX } from "./types.js";
+/** Publicly verifiable commitment; KEK holders independently derive the key. */
+export declare function computeContainerKekPublicCommitment(input: {
+    readonly containerId: string;
+    readonly keyEpoch: number;
+    readonly containerKeyPublicKey: string;
+}): Promise<`${typeof CONTAINER_KEK_MATERIAL_ID_PREFIX}${string}`>;
+export declare function computeContainerKekMaterialId(input: {
+    readonly containerId: string;
+    readonly keyEpoch: number;
+    readonly keyMaterial: Uint8Array;
+}): Promise<`${typeof CONTAINER_KEK_MATERIAL_ID_PREFIX}${string}`>;
+export declare function isContainerKekMaterialId(value: string): boolean;

package/internal/crypto/keying/containerKekMaterial.js

@@ -0,0 +1,71 @@
+import { isSha256HexString, MAX_CONTAINER_KEY_EPOCH, } from "../../validators/util/index.js";
+import { computeKeyingDomainHash } from "./canonical.js";
+import { containerKekCacheToken } from "./containerKekCacheToken.js";
+import { deriveContainerKekWrappingPublicKey, normalizeContainerKekWrappingPublicKey, } from "./containerKekWrapping.js";
+import { CONTAINER_KEK_MATERIAL_ID_PREFIX } from "./types.js";
+/** Publicly verifiable commitment; KEK holders independently derive the key. */
+export async function computeContainerKekPublicCommitment(input) {
+    if (!input.containerId ||
+        !Number.isSafeInteger(input.keyEpoch) ||
+        input.keyEpoch < 1) {
+        throw new Error("Container KEK commitment requires an ID and positive epoch");
+    }
+    const publicKey = normalizeContainerKekWrappingPublicKey(input.containerKeyPublicKey);
+    if (publicKey === null)
+        throw new Error("Container KEK commitment requires a public key");
+    const hash = await computeKeyingDomainHash("tearleads.keying.container-kek-public-commitment", {
+        version: 2,
+        containerId: input.containerId,
+        keyEpoch: input.keyEpoch,
+        publicKey,
+    });
+    return `${CONTAINER_KEK_MATERIAL_ID_PREFIX}${hash}`;
+}
+// Compact public commitments survive longer than the much larger public keys.
+// Reopened keyrings use fresh byte arrays, so object-identity caching is unsafe.
+const materialIds = new Map();
+const MAX_CACHED_MATERIAL_IDS = MAX_CONTAINER_KEY_EPOCH;
+export async function computeContainerKekMaterialId(input) {
+    if (!input.containerId ||
+        !Number.isSafeInteger(input.keyEpoch) ||
+        input.keyEpoch < 1 ||
+        input.keyMaterial.length !== 32) {
+        throw new Error("Container KEK commitment requires an ID, positive epoch, and 32-byte KEK");
+    }
+    const keyMaterial = input.keyMaterial.slice();
+    try {
+        const token = await containerKekCacheToken(keyMaterial);
+        const cacheKey = JSON.stringify([input.containerId, input.keyEpoch, token]);
+        const cached = materialIds.get(cacheKey);
+        if (cached) {
+            materialIds.delete(cacheKey);
+            materialIds.set(cacheKey, cached);
+            return cached;
+        }
+        const result = await computeContainerKekPublicCommitment({
+            containerId: input.containerId,
+            keyEpoch: input.keyEpoch,
+            containerKeyPublicKey: await deriveContainerKekWrappingPublicKey({
+                ...input,
+                keyMaterial,
+            }),
+        });
+        materialIds.set(cacheKey, result);
+        if (materialIds.size > MAX_CACHED_MATERIAL_IDS) {
+            const oldest = materialIds.keys().next().value;
+            if (oldest !== undefined)
+                materialIds.delete(oldest);
+        }
+        return result;
+    }
+    finally {
+        keyMaterial.fill(0);
+    }
+}
+export function isContainerKekMaterialId(value) {
+    if (!value.startsWith(CONTAINER_KEK_MATERIAL_ID_PREFIX)) {
+        return false;
+    }
+    return isSha256HexString(value.slice(CONTAINER_KEK_MATERIAL_ID_PREFIX.length));
+}
+//# sourceMappingURL=containerKekMaterial.js.map

package/internal/crypto/keying/containerKekMaterial.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerKekMaterial.js","sourceRoot":"","sources":["containerKekMaterial.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  isSha256HexString,\n  MAX_CONTAINER_KEY_EPOCH,\n} from \"@tearleads/validators/util\";\nimport { computeKeyingDomainHash } from \"./canonical\";\nimport { containerKekCacheToken } from \"./containerKekCacheToken\";\nimport {\n  deriveContainerKekWrappingPublicKey,\n  normalizeContainerKekWrappingPublicKey,\n} from \"./containerKekWrapping\";\nimport { CONTAINER_KEK_MATERIAL_ID_PREFIX } from \"./types\";\n\n/** Publicly verifiable commitment; KEK holders independently derive the key. */\nexport async function computeContainerKekPublicCommitment(input: {\n  readonly containerId: string;\n  readonly keyEpoch: number;\n  readonly containerKeyPublicKey: string;\n}): Promise<`${typeof CONTAINER_KEK_MATERIAL_ID_PREFIX}${string}`> {\n  if (\n    !input.containerId ||\n    !Number.isSafeInteger(input.keyEpoch) ||\n    input.keyEpoch < 1\n  ) {\n    throw new Error(\n      \"Container KEK commitment requires an ID and positive epoch\",\n    );\n  }\n  const publicKey = normalizeContainerKekWrappingPublicKey(\n    input.containerKeyPublicKey,\n  );\n  if (publicKey === null)\n    throw new Error(\"Container KEK commitment requires a public key\");\n  const hash = await computeKeyingDomainHash(\n    \"tearleads.keying.container-kek-public-commitment\",\n    {\n      version: 2,\n      containerId: input.containerId,\n      keyEpoch: input.keyEpoch,\n      publicKey,\n    },\n  );\n  return `${CONTAINER_KEK_MATERIAL_ID_PREFIX}${hash}`;\n}\n\n// Compact public commitments survive longer than the much larger public keys.\n// Reopened keyrings use fresh byte arrays, so object-identity caching is unsafe.\nconst materialIds = new Map<\n  string,\n  `${typeof CONTAINER_KEK_MATERIAL_ID_PREFIX}${string}`\n>();\nconst MAX_CACHED_MATERIAL_IDS = MAX_CONTAINER_KEY_EPOCH;\n\nexport async function computeContainerKekMaterialId(input: {\n  readonly containerId: string;\n  readonly keyEpoch: number;\n  readonly keyMaterial: Uint8Array;\n}): Promise<`${typeof CONTAINER_KEK_MATERIAL_ID_PREFIX}${string}`> {\n  if (\n    !input.containerId ||\n    !Number.isSafeInteger(input.keyEpoch) ||\n    input.keyEpoch < 1 ||\n    input.keyMaterial.length !== 32\n  ) {\n    throw new Error(\n      \"Container KEK commitment requires an ID, positive epoch, and 32-byte KEK\",\n    );\n  }\n  const keyMaterial = input.keyMaterial.slice();\n  try {\n    const token = await containerKekCacheToken(keyMaterial);\n    const cacheKey = JSON.stringify([input.containerId, input.keyEpoch, token]);\n    const cached = materialIds.get(cacheKey);\n    if (cached) {\n      materialIds.delete(cacheKey);\n      materialIds.set(cacheKey, cached);\n      return cached;\n    }\n    const result = await computeContainerKekPublicCommitment({\n      containerId: input.containerId,\n      keyEpoch: input.keyEpoch,\n      containerKeyPublicKey: await deriveContainerKekWrappingPublicKey({\n        ...input,\n        keyMaterial,\n      }),\n    });\n    materialIds.set(cacheKey, result);\n    if (materialIds.size > MAX_CACHED_MATERIAL_IDS) {\n      const oldest = materialIds.keys().next().value;\n      if (oldest !== undefined) materialIds.delete(oldest);\n    }\n    return result;\n  } finally {\n    keyMaterial.fill(0);\n  }\n}\n\nexport function isContainerKekMaterialId(value: string): boolean {\n  if (!value.startsWith(CONTAINER_KEK_MATERIAL_ID_PREFIX)) {\n    return false;\n  }\n\n  return isSha256HexString(\n    value.slice(CONTAINER_KEK_MATERIAL_ID_PREFIX.length),\n  );\n}\n"]}

package/internal/crypto/keying/containerKekParent.js

@@ -0,0 +1,86 @@
+import { computeKeyingDomainHash } from "./canonical.js";
+import { throwVerification } from "./shared.js";
+function parentLineage(parent, manifests) {
+    const lineage = [];
+    const seen = new Set();
+    let hash = parent.accessManifestHash;
+    while (hash !== null) {
+        const manifest = manifests.get(hash);
+        if (!manifest ||
+            manifest.state.containerId !== parent.containerId ||
+            seen.has(hash)) {
+            throwVerification("missing_dependency", "historical parent KEK requires its complete verified lineage");
+        }
+        seen.add(hash);
+        lineage.push(manifest);
+        hash = manifest.manifest.previousManifestHash;
+    }
+    return lineage.reverse();
+}
+export function creationParentEpochId(manifest, manifests) {
+    const parentId = manifest.state.parentContainerId;
+    if (parentId === null)
+        return null;
+    const hash = manifest.state.parentManifestHash;
+    const parent = hash === null ? undefined : manifests.get(hash);
+    if (!hash ||
+        !manifest.event.event.dependencyManifestHashes.includes(hash) ||
+        !parent?.state.containerKeyEpochId ||
+        parent.manifestHash !== hash ||
+        parent.state.containerId !== parentId ||
+        parent.state.organizationId !== manifest.state.organizationId) {
+        throwVerification("missing_dependency", "container KEK creation requires its signed parent citation");
+    }
+    return parent.state.containerKeyEpochId;
+}
+/**
+ * Reconstruct the pinned epoch from public, verified signed lineage. This is
+ * read/recovery evidence: neither the server nor a direct child recipient
+ * needs the ancestor's secret key. Writes omit this history and still require
+ * the parent's current epoch.
+ */
+export async function resolveContainerKekParentBinding(input) {
+    const { parent } = input;
+    if (!parent ||
+        parent.containerKeyEpochId === input.pinnedEpochId ||
+        input.verifiedHistory === undefined) {
+        return parent;
+    }
+    const manifests = new Map(input.verifiedHistory.map((manifest) => [manifest.manifestHash, manifest]));
+    const lineage = parentLineage(parent, manifests);
+    let previousId = null;
+    let keyEpoch = 0;
+    let pinned;
+    const seenEpochIds = new Set();
+    for (const manifest of lineage) {
+        const id = manifest.state.containerKeyEpochId;
+        if (!id || id === previousId)
+            continue;
+        if (seenEpochIds.has(id)) {
+            throwVerification("key_epoch_reuse", "parent lineage reuses a KEK epoch");
+        }
+        seenEpochIds.add(id);
+        previousId = id;
+        keyEpoch += 1;
+        if (id === input.pinnedEpochId) {
+            pinned = {
+                id,
+                containerId: parent.containerId,
+                keyEpoch,
+                accessManifestHash: manifest.manifestHash,
+                createdByManifestHash: manifest.manifestHash,
+                createdByEventHash: manifest.event.eventHash,
+                parentContainerKeyEpochId: creationParentEpochId(manifest, manifests),
+            };
+        }
+    }
+    if (!pinned || previousId !== parent.containerKeyEpochId) {
+        throwVerification("key_epoch_reuse", "child KEK pin is absent from its parent's verified lineage");
+    }
+    return {
+        containerId: parent.containerId,
+        containerKeyEpochId: pinned.id,
+        keyEpochHash: await computeKeyingDomainHash("tearleads.keying.container-key-epoch", { ...pinned }),
+    };
+}
+//# sourceMappingURL=containerKekParent.js.map

package/internal/crypto/keying/containerKekParent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerKekParent.js","sourceRoot":"","sources":["containerKekParent.ts"],"names":[],"mappings":"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","sourcesContent":["import { computeKeyingDomainHash } from \"./canonical\";\nimport { throwVerification } from \"./shared\";\nimport type {\n  ContainerKeyEpoch,\n  VerifiedContainerAccessManifest,\n  VerifiedContainerKekState,\n} from \"./types\";\n\nexport type ContainerKekParentBinding = Pick<\n  VerifiedContainerKekState,\n  \"containerId\" | \"containerKeyEpochId\" | \"keyEpochHash\"\n>;\n\nfunction parentLineage(\n  parent: VerifiedContainerKekState,\n  manifests: ReadonlyMap<string, VerifiedContainerAccessManifest>,\n): VerifiedContainerAccessManifest[] {\n  const lineage: VerifiedContainerAccessManifest[] = [];\n  const seen = new Set<string>();\n  let hash: string | null = parent.accessManifestHash;\n  while (hash !== null) {\n    const manifest = manifests.get(hash);\n    if (\n      !manifest ||\n      manifest.state.containerId !== parent.containerId ||\n      seen.has(hash)\n    ) {\n      throwVerification(\n        \"missing_dependency\",\n        \"historical parent KEK requires its complete verified lineage\",\n      );\n    }\n    seen.add(hash);\n    lineage.push(manifest);\n    hash = manifest.manifest.previousManifestHash;\n  }\n  return lineage.reverse();\n}\n\nexport function creationParentEpochId(\n  manifest: VerifiedContainerAccessManifest,\n  manifests: ReadonlyMap<string, VerifiedContainerAccessManifest>,\n): string | null {\n  const parentId = manifest.state.parentContainerId;\n  if (parentId === null) return null;\n  const hash = manifest.state.parentManifestHash;\n  const parent = hash === null ? undefined : manifests.get(hash);\n  if (\n    !hash ||\n    !manifest.event.event.dependencyManifestHashes.includes(hash) ||\n    !parent?.state.containerKeyEpochId ||\n    parent.manifestHash !== hash ||\n    parent.state.containerId !== parentId ||\n    parent.state.organizationId !== manifest.state.organizationId\n  ) {\n    throwVerification(\n      \"missing_dependency\",\n      \"container KEK creation requires its signed parent citation\",\n    );\n  }\n  return parent.state.containerKeyEpochId;\n}\n\n/**\n * Reconstruct the pinned epoch from public, verified signed lineage. This is\n * read/recovery evidence: neither the server nor a direct child recipient\n * needs the ancestor's secret key. Writes omit this history and still require\n * the parent's current epoch.\n */\nexport async function resolveContainerKekParentBinding(input: {\n  parent: VerifiedContainerKekState | null;\n  pinnedEpochId: string | null;\n  verifiedHistory: readonly VerifiedContainerAccessManifest[] | undefined;\n}): Promise<ContainerKekParentBinding | null> {\n  const { parent } = input;\n  if (\n    !parent ||\n    parent.containerKeyEpochId === input.pinnedEpochId ||\n    input.verifiedHistory === undefined\n  ) {\n    return parent;\n  }\n  const manifests = new Map(\n    input.verifiedHistory.map((manifest) => [manifest.manifestHash, manifest]),\n  );\n  const lineage = parentLineage(parent, manifests);\n  let previousId: string | null = null;\n  let keyEpoch = 0;\n  let pinned: ContainerKeyEpoch | undefined;\n  const seenEpochIds = new Set<string>();\n  for (const manifest of lineage) {\n    const id = manifest.state.containerKeyEpochId;\n    if (!id || id === previousId) continue;\n    if (seenEpochIds.has(id)) {\n      throwVerification(\"key_epoch_reuse\", \"parent lineage reuses a KEK epoch\");\n    }\n    seenEpochIds.add(id);\n    previousId = id;\n    keyEpoch += 1;\n    if (id === input.pinnedEpochId) {\n      pinned = {\n        id,\n        containerId: parent.containerId,\n        keyEpoch,\n        accessManifestHash: manifest.manifestHash,\n        createdByManifestHash: manifest.manifestHash,\n        createdByEventHash: manifest.event.eventHash,\n        parentContainerKeyEpochId: creationParentEpochId(manifest, manifests),\n      };\n    }\n  }\n  if (!pinned || previousId !== parent.containerKeyEpochId) {\n    throwVerification(\n      \"key_epoch_reuse\",\n      \"child KEK pin is absent from its parent's verified lineage\",\n    );\n  }\n  return {\n    containerId: parent.containerId,\n    containerKeyEpochId: pinned.id,\n    keyEpochHash: await computeKeyingDomainHash(\n      \"tearleads.keying.container-key-epoch\",\n      { ...pinned },\n    ),\n  };\n}\n"]}

package/internal/crypto/keying/containerKekPredecessor.d.ts

@@ -0,0 +1,14 @@
+import { type ContainerKekPredecessorBridge } from "./types.js";
+export declare function normalizeContainerKekPredecessorBridge(value: unknown): ContainerKekPredecessorBridge;
+export declare function computeContainerKekPredecessorBridgeHash(value: unknown): Promise<string>;
+export declare function createContainerKekPredecessorBridge(input: {
+    containerId: string;
+    predecessorContainerKey: Uint8Array;
+    predecessorContainerKeyEpochId: string;
+    successorContainerKey: Uint8Array;
+    successorContainerKeyEpochId: string;
+}): Promise<ContainerKekPredecessorBridge>;
+export declare function unwrapContainerKekPredecessorBridge(input: {
+    bridge: ContainerKekPredecessorBridge;
+    successorContainerKey: Uint8Array;
+}): Promise<Uint8Array>;

package/internal/crypto/keying/containerKekPredecessor.js

@@ -0,0 +1,135 @@
+import { base64ToBytes, bytesToBase64 } from "../../encoding/index.js";
+import { assertAesGcmIv, decryptWithDek, encryptWithDek } from "../symmetric.js";
+import { computeKeyingDomainHash, serializeKeyingCanonicalJson, } from "./canonical.js";
+import { isContainerKekMaterialId } from "./containerKekMaterial.js";
+import { assertExactKeys, readPositiveInteger, readString, throwVerification, } from "./shared.js";
+import { CONTAINER_KEK_PREDECESSOR_WRAP_SUITE, } from "./types.js";
+const TEXT_ENCODER = new TextEncoder();
+function sameKeyMaterial(left, right) {
+    return (left.byteLength === right.byteLength &&
+        left.every((value, index) => value === right[index]));
+}
+function bridgeAdditionalData(input) {
+    return TEXT_ENCODER.encode(serializeKeyingCanonicalJson({
+        domain: "tearleads.container-kek-predecessor-bridge.aad",
+        payload: {
+            version: 1,
+            wrappingSuite: CONTAINER_KEK_PREDECESSOR_WRAP_SUITE,
+            containerId: input.containerId,
+            predecessorContainerKeyEpochId: input.predecessorContainerKeyEpochId,
+            successorContainerKeyEpochId: input.successorContainerKeyEpochId,
+        },
+    }));
+}
+function canonicalBase64(value, label) {
+    let bytes;
+    try {
+        bytes = base64ToBytes(value);
+    }
+    catch {
+        throwVerification("invalid_shape", `${label} must be base64`);
+    }
+    if (bytesToBase64(bytes) !== value) {
+        throwVerification("invalid_shape", `${label} must use canonical base64`);
+    }
+    return bytes;
+}
+function assertBridgeMetadata(input) {
+    if (input.containerId.length === 0) {
+        throwVerification("invalid_shape", "container KEK predecessor bridge container id must not be empty");
+    }
+    if (!isContainerKekMaterialId(input.predecessorContainerKeyEpochId) ||
+        !isContainerKekMaterialId(input.successorContainerKeyEpochId)) {
+        throwVerification("invalid_shape", "container KEK predecessor bridge epoch ids must commit to key material");
+    }
+    if (input.predecessorContainerKeyEpochId === input.successorContainerKeyEpochId) {
+        throwVerification("key_epoch_reuse", "container KEK predecessor bridge must connect distinct epochs");
+    }
+}
+export function normalizeContainerKekPredecessorBridge(value) {
+    const record = assertExactKeys(value, [
+        "containerId",
+        "iv",
+        "predecessorContainerKeyEpochId",
+        "successorContainerKeyEpochId",
+        "version",
+        "wrappedKey",
+        "wrappingSuite",
+    ], "container KEK predecessor bridge");
+    const version = readPositiveInteger(record, "version", "container KEK predecessor bridge");
+    if (version !== 1) {
+        throwVerification("invalid_shape", "container KEK predecessor bridge version is unsupported");
+    }
+    const wrappingSuite = readString(record, "wrappingSuite", "container KEK predecessor bridge");
+    if (wrappingSuite !== CONTAINER_KEK_PREDECESSOR_WRAP_SUITE) {
+        throwVerification("invalid_shape", "container KEK predecessor bridge wrapping suite is unsupported");
+    }
+    const bridge = {
+        version: 1,
+        wrappingSuite: CONTAINER_KEK_PREDECESSOR_WRAP_SUITE,
+        containerId: readString(record, "containerId", "container KEK predecessor bridge"),
+        predecessorContainerKeyEpochId: readString(record, "predecessorContainerKeyEpochId", "container KEK predecessor bridge"),
+        successorContainerKeyEpochId: readString(record, "successorContainerKeyEpochId", "container KEK predecessor bridge"),
+        iv: readString(record, "iv", "container KEK predecessor bridge"),
+        wrappedKey: readString(record, "wrappedKey", "container KEK predecessor bridge"),
+    };
+    assertBridgeMetadata(bridge);
+    const iv = canonicalBase64(bridge.iv, "container KEK predecessor bridge.iv");
+    assertAesGcmIv(iv, "Container KEK predecessor bridge IV must be 12 bytes");
+    const wrappedKey = canonicalBase64(bridge.wrappedKey, "container KEK predecessor bridge.wrappedKey");
+    if (wrappedKey.byteLength !== 48) {
+        throwVerification("invalid_shape", "container KEK predecessor bridge ciphertext must be 48 bytes");
+    }
+    return bridge;
+}
+export async function computeContainerKekPredecessorBridgeHash(value) {
+    const bridge = normalizeContainerKekPredecessorBridge(value);
+    return computeKeyingDomainHash("tearleads.keying.container-kek-predecessor-bridge", {
+        version: bridge.version,
+        wrappingSuite: bridge.wrappingSuite,
+        containerId: bridge.containerId,
+        predecessorContainerKeyEpochId: bridge.predecessorContainerKeyEpochId,
+        successorContainerKeyEpochId: bridge.successorContainerKeyEpochId,
+        iv: bridge.iv,
+        wrappedKey: bridge.wrappedKey,
+    });
+}
+export async function createContainerKekPredecessorBridge(input) {
+    if (input.predecessorContainerKey.byteLength !== 32 ||
+        input.successorContainerKey.byteLength !== 32) {
+        throwVerification("invalid_shape", "container KEK predecessor bridge keys must be 32 bytes");
+    }
+    if (sameKeyMaterial(input.predecessorContainerKey, input.successorContainerKey)) {
+        throwVerification("key_epoch_reuse", "container KEK predecessor bridge must use distinct key material");
+    }
+    const metadata = {
+        version: 1,
+        wrappingSuite: CONTAINER_KEK_PREDECESSOR_WRAP_SUITE,
+        containerId: input.containerId,
+        predecessorContainerKeyEpochId: input.predecessorContainerKeyEpochId,
+        successorContainerKeyEpochId: input.successorContainerKeyEpochId,
+    };
+    assertBridgeMetadata(metadata);
+    const encrypted = await encryptWithDek(input.predecessorContainerKey, input.successorContainerKey, bridgeAdditionalData(metadata));
+    const roundTripped = await decryptWithDek(encrypted, input.successorContainerKey, bridgeAdditionalData(metadata));
+    if (!sameKeyMaterial(roundTripped, input.predecessorContainerKey)) {
+        throwVerification("hash_mismatch", "container KEK predecessor bridge failed local round-trip verification");
+    }
+    return {
+        ...metadata,
+        iv: bytesToBase64(encrypted.iv),
+        wrappedKey: bytesToBase64(encrypted.ciphertext),
+    };
+}
+export async function unwrapContainerKekPredecessorBridge(input) {
+    const bridge = normalizeContainerKekPredecessorBridge(input.bridge);
+    const predecessorKey = await decryptWithDek({
+        iv: base64ToBytes(bridge.iv),
+        ciphertext: base64ToBytes(bridge.wrappedKey),
+    }, input.successorContainerKey, bridgeAdditionalData(bridge));
+    if (predecessorKey.byteLength !== 32) {
+        throwVerification("invalid_shape", "container KEK predecessor bridge plaintext must be 32 bytes");
+    }
+    return predecessorKey;
+}
+//# sourceMappingURL=containerKekPredecessor.js.map