@tearleads/client-sdk 0.0.0-stage → 0.1.11

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

@@ -0,0 +1 @@
+{"version":3,"file":"containerKekPredecessor.js","sourceRoot":"","sources":["containerKekPredecessor.ts"],"names":[],"mappings":"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","sourcesContent":["import { base64ToBytes, bytesToBase64 } from \"@tearleads/encoding\";\nimport { assertAesGcmIv, decryptWithDek, encryptWithDek } from \"../symmetric\";\nimport {\n  computeKeyingDomainHash,\n  serializeKeyingCanonicalJson,\n} from \"./canonical\";\nimport { isContainerKekMaterialId } from \"./containerKekMaterial\";\nimport {\n  assertExactKeys,\n  readPositiveInteger,\n  readString,\n  throwVerification,\n} from \"./shared\";\nimport {\n  CONTAINER_KEK_PREDECESSOR_WRAP_SUITE,\n  type ContainerKekPredecessorBridge,\n} from \"./types\";\n\nconst TEXT_ENCODER = new TextEncoder();\n\nfunction sameKeyMaterial(left: Uint8Array, right: Uint8Array): boolean {\n  return (\n    left.byteLength === right.byteLength &&\n    left.every((value, index) => value === right[index])\n  );\n}\n\nfunction bridgeAdditionalData(input: {\n  containerId: string;\n  predecessorContainerKeyEpochId: string;\n  successorContainerKeyEpochId: string;\n}): Uint8Array<ArrayBuffer> {\n  return TEXT_ENCODER.encode(\n    serializeKeyingCanonicalJson({\n      domain: \"tearleads.container-kek-predecessor-bridge.aad\",\n      payload: {\n        version: 1,\n        wrappingSuite: CONTAINER_KEK_PREDECESSOR_WRAP_SUITE,\n        containerId: input.containerId,\n        predecessorContainerKeyEpochId: input.predecessorContainerKeyEpochId,\n        successorContainerKeyEpochId: input.successorContainerKeyEpochId,\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 assertBridgeMetadata(input: {\n  containerId: string;\n  predecessorContainerKeyEpochId: string;\n  successorContainerKeyEpochId: string;\n}): void {\n  if (input.containerId.length === 0) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK predecessor bridge container id must not be empty\",\n    );\n  }\n  if (\n    !isContainerKekMaterialId(input.predecessorContainerKeyEpochId) ||\n    !isContainerKekMaterialId(input.successorContainerKeyEpochId)\n  ) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK predecessor bridge epoch ids must commit to key material\",\n    );\n  }\n  if (\n    input.predecessorContainerKeyEpochId === input.successorContainerKeyEpochId\n  ) {\n    throwVerification(\n      \"key_epoch_reuse\",\n      \"container KEK predecessor bridge must connect distinct epochs\",\n    );\n  }\n}\n\nexport function normalizeContainerKekPredecessorBridge(\n  value: unknown,\n): ContainerKekPredecessorBridge {\n  const record = assertExactKeys(\n    value,\n    [\n      \"containerId\",\n      \"iv\",\n      \"predecessorContainerKeyEpochId\",\n      \"successorContainerKeyEpochId\",\n      \"version\",\n      \"wrappedKey\",\n      \"wrappingSuite\",\n    ],\n    \"container KEK predecessor bridge\",\n  );\n  const version = readPositiveInteger(\n    record,\n    \"version\",\n    \"container KEK predecessor bridge\",\n  );\n  if (version !== 1) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK predecessor bridge version is unsupported\",\n    );\n  }\n  const wrappingSuite = readString(\n    record,\n    \"wrappingSuite\",\n    \"container KEK predecessor bridge\",\n  );\n  if (wrappingSuite !== CONTAINER_KEK_PREDECESSOR_WRAP_SUITE) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK predecessor bridge wrapping suite is unsupported\",\n    );\n  }\n  const bridge: ContainerKekPredecessorBridge = {\n    version: 1,\n    wrappingSuite: CONTAINER_KEK_PREDECESSOR_WRAP_SUITE,\n    containerId: readString(\n      record,\n      \"containerId\",\n      \"container KEK predecessor bridge\",\n    ),\n    predecessorContainerKeyEpochId: readString(\n      record,\n      \"predecessorContainerKeyEpochId\",\n      \"container KEK predecessor bridge\",\n    ),\n    successorContainerKeyEpochId: readString(\n      record,\n      \"successorContainerKeyEpochId\",\n      \"container KEK predecessor bridge\",\n    ),\n    iv: readString(record, \"iv\", \"container KEK predecessor bridge\"),\n    wrappedKey: readString(\n      record,\n      \"wrappedKey\",\n      \"container KEK predecessor bridge\",\n    ),\n  };\n  assertBridgeMetadata(bridge);\n  const iv = canonicalBase64(bridge.iv, \"container KEK predecessor bridge.iv\");\n  assertAesGcmIv(iv, \"Container KEK predecessor bridge IV must be 12 bytes\");\n  const wrappedKey = canonicalBase64(\n    bridge.wrappedKey,\n    \"container KEK predecessor bridge.wrappedKey\",\n  );\n  if (wrappedKey.byteLength !== 48) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK predecessor bridge ciphertext must be 48 bytes\",\n    );\n  }\n  return bridge;\n}\n\nexport async function computeContainerKekPredecessorBridgeHash(\n  value: unknown,\n): Promise<string> {\n  const bridge = normalizeContainerKekPredecessorBridge(value);\n  return computeKeyingDomainHash(\n    \"tearleads.keying.container-kek-predecessor-bridge\",\n    {\n      version: bridge.version,\n      wrappingSuite: bridge.wrappingSuite,\n      containerId: bridge.containerId,\n      predecessorContainerKeyEpochId: bridge.predecessorContainerKeyEpochId,\n      successorContainerKeyEpochId: bridge.successorContainerKeyEpochId,\n      iv: bridge.iv,\n      wrappedKey: bridge.wrappedKey,\n    },\n  );\n}\n\nexport async function createContainerKekPredecessorBridge(input: {\n  containerId: string;\n  predecessorContainerKey: Uint8Array;\n  predecessorContainerKeyEpochId: string;\n  successorContainerKey: Uint8Array;\n  successorContainerKeyEpochId: string;\n}): Promise<ContainerKekPredecessorBridge> {\n  if (\n    input.predecessorContainerKey.byteLength !== 32 ||\n    input.successorContainerKey.byteLength !== 32\n  ) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK predecessor bridge keys must be 32 bytes\",\n    );\n  }\n  if (\n    sameKeyMaterial(input.predecessorContainerKey, input.successorContainerKey)\n  ) {\n    throwVerification(\n      \"key_epoch_reuse\",\n      \"container KEK predecessor bridge must use distinct key material\",\n    );\n  }\n  const metadata = {\n    version: 1,\n    wrappingSuite: CONTAINER_KEK_PREDECESSOR_WRAP_SUITE,\n    containerId: input.containerId,\n    predecessorContainerKeyEpochId: input.predecessorContainerKeyEpochId,\n    successorContainerKeyEpochId: input.successorContainerKeyEpochId,\n  } as const;\n  assertBridgeMetadata(metadata);\n  const encrypted = await encryptWithDek(\n    input.predecessorContainerKey,\n    input.successorContainerKey,\n    bridgeAdditionalData(metadata),\n  );\n  const roundTripped = await decryptWithDek(\n    encrypted,\n    input.successorContainerKey,\n    bridgeAdditionalData(metadata),\n  );\n  if (!sameKeyMaterial(roundTripped, input.predecessorContainerKey)) {\n    throwVerification(\n      \"hash_mismatch\",\n      \"container KEK predecessor bridge failed local round-trip verification\",\n    );\n  }\n  return {\n    ...metadata,\n    iv: bytesToBase64(encrypted.iv),\n    wrappedKey: bytesToBase64(encrypted.ciphertext),\n  };\n}\n\nexport async function unwrapContainerKekPredecessorBridge(input: {\n  bridge: ContainerKekPredecessorBridge;\n  successorContainerKey: Uint8Array;\n}): Promise<Uint8Array> {\n  const bridge = normalizeContainerKekPredecessorBridge(input.bridge);\n  const predecessorKey = await decryptWithDek(\n    {\n      iv: base64ToBytes(bridge.iv),\n      ciphertext: base64ToBytes(bridge.wrappedKey),\n    },\n    input.successorContainerKey,\n    bridgeAdditionalData(bridge),\n  );\n  if (predecessorKey.byteLength !== 32) {\n    throwVerification(\n      \"invalid_shape\",\n      \"container KEK predecessor bridge plaintext must be 32 bytes\",\n    );\n  }\n  return predecessorKey;\n}\n"]}

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

@@ -0,0 +1,12 @@
+export declare function deriveContainerKekWrappingPublicKey(input: {
+    readonly containerId: string;
+    readonly keyMaterial: Uint8Array;
+}): Promise<string>;
+export declare function normalizeContainerKekWrappingPublicKey(value: unknown): string | null;
+/** Opens only the public-key parent wrapping protocol, including retained epochs. */
+export declare function unwrapContainerKekParentWrap(input: {
+    readonly parentContainerId: string;
+    readonly parentKeyMaterial: Uint8Array;
+    readonly kemCipherText: string;
+    readonly wrappedKey: string;
+}): Promise<Uint8Array>;

package/internal/crypto/keying/containerKekWrapping.js

@@ -0,0 +1,125 @@
+import { base64ToBytes, bytesToBase64 } from "../../encoding/index.js";
+import { generateKemKeyPair, ML_KEM1024_PUBLIC_KEY_BYTES, ML_KEM1024_SEED_BYTES, } from "../encapsulation/generateKeyPair.js";
+import { unwrapDek } from "../encapsulation/unwrapDek.js";
+import { toFingerprint } from "../fingerprint.js";
+import { containerKekCacheToken } from "./containerKekCacheToken.js";
+import { throwVerification } from "./shared.js";
+// Bounded public-only cache. A digest distinguishes mutable buffers without
+// retaining KEK bytes, private keys, or derivation seeds between calls.
+const publicWrappingKeys = new Map();
+const MAX_PUBLIC_WRAPPING_KEYS = 128;
+const utf8 = new TextEncoder();
+const wrappingKeyDomain = utf8.encode("tearleads.container-kek.parent-wrapping.ml-kem-1024.v1");
+/** A separate KEM key pair for each container KEK, without another secret to store. */
+async function deriveContainerKekWrappingKeyPair(input) {
+    if (!input.containerId || input.keyMaterial.byteLength !== 32) {
+        throw new Error("Container wrapping derivation requires an ID and 32-byte KEK");
+    }
+    const keyMaterialCopy = input.keyMaterial.slice();
+    let key;
+    try {
+        key = await crypto.subtle.importKey("raw", keyMaterialCopy, "HKDF", false, [
+            "deriveBits",
+        ]);
+    }
+    finally {
+        keyMaterialCopy.fill(0);
+    }
+    const seed = new Uint8Array(await crypto.subtle.deriveBits({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: wrappingKeyDomain,
+        info: utf8.encode(input.containerId),
+    }, key, ML_KEM1024_SEED_BYTES * 8));
+    try {
+        return generateKemKeyPair(seed);
+    }
+    finally {
+        seed.fill(0);
+    }
+}
+export async function deriveContainerKekWrappingPublicKey(input) {
+    if (!input.containerId || input.keyMaterial.byteLength !== 32) {
+        throw new Error("Container wrapping derivation requires an ID and 32-byte KEK");
+    }
+    const keyMaterial = input.keyMaterial.slice();
+    try {
+        const cacheKey = `${input.containerId}:${await containerKekCacheToken(keyMaterial)}`;
+        const cached = publicWrappingKeys.get(cacheKey);
+        if (cached) {
+            publicWrappingKeys.delete(cacheKey);
+            publicWrappingKeys.set(cacheKey, cached);
+            return cached;
+        }
+        const pair = await deriveContainerKekWrappingKeyPair({
+            ...input,
+            keyMaterial,
+        });
+        try {
+            const publicKey = bytesToBase64(pair.publicKey);
+            publicWrappingKeys.set(cacheKey, publicKey);
+            if (publicWrappingKeys.size > MAX_PUBLIC_WRAPPING_KEYS) {
+                const oldest = publicWrappingKeys.keys().next().value;
+                if (oldest !== undefined)
+                    publicWrappingKeys.delete(oldest);
+            }
+            return publicKey;
+        }
+        finally {
+            pair.secretKey.fill(0);
+        }
+    }
+    finally {
+        keyMaterial.fill(0);
+    }
+}
+export function normalizeContainerKekWrappingPublicKey(value) {
+    if (value === null)
+        return null;
+    if (typeof value !== "string") {
+        throwVerification("invalid_shape", "Container KEK public key must be base64");
+    }
+    let bytes;
+    try {
+        bytes = base64ToBytes(value);
+    }
+    catch {
+        throwVerification("invalid_shape", "Container KEK public key must be base64");
+    }
+    if (bytes.length !== ML_KEM1024_PUBLIC_KEY_BYTES ||
+        bytesToBase64(bytes) !== value) {
+        throwVerification("invalid_shape", "Container KEK public key must be canonical ML-KEM-1024");
+    }
+    // FIPS 203 section 7.2: each packed 12-bit coefficient precedes the
+    // final 32-byte public seed and must be less than q = 3329.
+    for (let offset = 0; offset < bytes.length - 32; offset += 3) {
+        const first = bytes[offset] ?? 0;
+        const middle = bytes[offset + 1] ?? 0;
+        const last = bytes[offset + 2] ?? 0;
+        if ((first | ((middle & 15) << 8)) >= 3329 ||
+            ((middle >> 4) | (last << 4)) >= 3329) {
+            throwVerification("invalid_shape", "Container KEK public key has invalid ML-KEM coefficients");
+        }
+    }
+    return value;
+}
+/** Opens only the public-key parent wrapping protocol, including retained epochs. */
+export async function unwrapContainerKekParentWrap(input) {
+    const pair = await deriveContainerKekWrappingKeyPair({
+        containerId: input.parentContainerId,
+        keyMaterial: input.parentKeyMaterial,
+    });
+    try {
+        return await unwrapDek([
+            {
+                keyFingerprint: await toFingerprint(pair.publicKey),
+                kemCipherText: base64ToBytes(input.kemCipherText),
+                wrappedKey: base64ToBytes(input.wrappedKey),
+            },
+        ], pair.secretKey);
+    }
+    finally {
+        pair.secretKey.fill(0);
+    }
+}
+//# sourceMappingURL=containerKekWrapping.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"containerKekWrapping.js","sourceRoot":"","sources":["containerKekWrapping.ts"],"names":[],"mappings":"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","sourcesContent":["import { base64ToBytes, bytesToBase64 } from \"@tearleads/encoding\";\nimport {\n  type EncapsulationKeyPair,\n  generateKemKeyPair,\n  ML_KEM1024_PUBLIC_KEY_BYTES,\n  ML_KEM1024_SEED_BYTES,\n} from \"../encapsulation/generateKeyPair\";\nimport { unwrapDek } from \"../encapsulation/unwrapDek\";\nimport { toFingerprint } from \"../fingerprint\";\nimport { containerKekCacheToken } from \"./containerKekCacheToken\";\nimport { throwVerification } from \"./shared\";\n\n// Bounded public-only cache. A digest distinguishes mutable buffers without\n// retaining KEK bytes, private keys, or derivation seeds between calls.\nconst publicWrappingKeys = new Map<string, string>();\nconst MAX_PUBLIC_WRAPPING_KEYS = 128;\nconst utf8 = new TextEncoder();\nconst wrappingKeyDomain = utf8.encode(\n  \"tearleads.container-kek.parent-wrapping.ml-kem-1024.v1\",\n);\n\n/** A separate KEM key pair for each container KEK, without another secret to store. */\nasync function deriveContainerKekWrappingKeyPair(input: {\n  readonly containerId: string;\n  readonly keyMaterial: Uint8Array;\n}): Promise<EncapsulationKeyPair> {\n  if (!input.containerId || input.keyMaterial.byteLength !== 32) {\n    throw new Error(\n      \"Container wrapping derivation requires an ID and 32-byte KEK\",\n    );\n  }\n  const keyMaterialCopy = input.keyMaterial.slice();\n  let key: CryptoKey;\n  try {\n    key = await crypto.subtle.importKey(\"raw\", keyMaterialCopy, \"HKDF\", false, [\n      \"deriveBits\",\n    ]);\n  } finally {\n    keyMaterialCopy.fill(0);\n  }\n  const seed = new Uint8Array(\n    await crypto.subtle.deriveBits(\n      {\n        name: \"HKDF\",\n        hash: \"SHA-256\",\n        salt: wrappingKeyDomain,\n        info: utf8.encode(input.containerId),\n      },\n      key,\n      ML_KEM1024_SEED_BYTES * 8,\n    ),\n  );\n  try {\n    return generateKemKeyPair(seed);\n  } finally {\n    seed.fill(0);\n  }\n}\n\nexport async function deriveContainerKekWrappingPublicKey(input: {\n  readonly containerId: string;\n  readonly keyMaterial: Uint8Array;\n}): Promise<string> {\n  if (!input.containerId || input.keyMaterial.byteLength !== 32) {\n    throw new Error(\n      \"Container wrapping derivation requires an ID and 32-byte KEK\",\n    );\n  }\n  const keyMaterial = input.keyMaterial.slice();\n  try {\n    const cacheKey = `${input.containerId}:${await containerKekCacheToken(keyMaterial)}`;\n    const cached = publicWrappingKeys.get(cacheKey);\n    if (cached) {\n      publicWrappingKeys.delete(cacheKey);\n      publicWrappingKeys.set(cacheKey, cached);\n      return cached;\n    }\n    const pair = await deriveContainerKekWrappingKeyPair({\n      ...input,\n      keyMaterial,\n    });\n    try {\n      const publicKey = bytesToBase64(pair.publicKey);\n      publicWrappingKeys.set(cacheKey, publicKey);\n      if (publicWrappingKeys.size > MAX_PUBLIC_WRAPPING_KEYS) {\n        const oldest = publicWrappingKeys.keys().next().value;\n        if (oldest !== undefined) publicWrappingKeys.delete(oldest);\n      }\n      return publicKey;\n    } finally {\n      pair.secretKey.fill(0);\n    }\n  } finally {\n    keyMaterial.fill(0);\n  }\n}\n\nexport function normalizeContainerKekWrappingPublicKey(\n  value: unknown,\n): string | null {\n  if (value === null) return null;\n  if (typeof value !== \"string\") {\n    throwVerification(\n      \"invalid_shape\",\n      \"Container KEK public key must be base64\",\n    );\n  }\n  let bytes: Uint8Array;\n  try {\n    bytes = base64ToBytes(value);\n  } catch {\n    throwVerification(\n      \"invalid_shape\",\n      \"Container KEK public key must be base64\",\n    );\n  }\n  if (\n    bytes.length !== ML_KEM1024_PUBLIC_KEY_BYTES ||\n    bytesToBase64(bytes) !== value\n  ) {\n    throwVerification(\n      \"invalid_shape\",\n      \"Container KEK public key must be canonical ML-KEM-1024\",\n    );\n  }\n  // FIPS 203 section 7.2: each packed 12-bit coefficient precedes the\n  // final 32-byte public seed and must be less than q = 3329.\n  for (let offset = 0; offset < bytes.length - 32; offset += 3) {\n    const first = bytes[offset] ?? 0;\n    const middle = bytes[offset + 1] ?? 0;\n    const last = bytes[offset + 2] ?? 0;\n    if (\n      (first | ((middle & 15) << 8)) >= 3329 ||\n      ((middle >> 4) | (last << 4)) >= 3329\n    ) {\n      throwVerification(\n        \"invalid_shape\",\n        \"Container KEK public key has invalid ML-KEM coefficients\",\n      );\n    }\n  }\n  return value;\n}\n\n/** Opens only the public-key parent wrapping protocol, including retained epochs. */\nexport async function unwrapContainerKekParentWrap(input: {\n  readonly parentContainerId: string;\n  readonly parentKeyMaterial: Uint8Array;\n  readonly kemCipherText: string;\n  readonly wrappedKey: string;\n}): Promise<Uint8Array> {\n  const pair = await deriveContainerKekWrappingKeyPair({\n    containerId: input.parentContainerId,\n    keyMaterial: input.parentKeyMaterial,\n  });\n  try {\n    return await unwrapDek(\n      [\n        {\n          keyFingerprint: await toFingerprint(pair.publicKey),\n          kemCipherText: base64ToBytes(input.kemCipherText),\n          wrappedKey: base64ToBytes(input.wrappedKey),\n        },\n      ],\n      pair.secretKey,\n    );\n  } finally {\n    pair.secretKey.fill(0);\n  }\n}\n"]}

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

@@ -0,0 +1,16 @@
+import type { VerifiedContainerAccessManifest } from "./types.js";
+/** Validate topology before combining grants from individually verified heads. */
+export declare function assertContainerPathIntegrity(path: readonly VerifiedContainerAccessManifest[], label: string): void;
+export declare function requireContainerPathLast(path: readonly VerifiedContainerAccessManifest[] | undefined, label: string): VerifiedContainerAccessManifest;
+export declare function requireContainerPathCurrentParent(input: {
+    readonly organizationId: string;
+    readonly parentContainerId: string | null;
+    readonly parentManifestHash: string | null;
+    readonly path: readonly VerifiedContainerAccessManifest[] | undefined;
+    readonly label: string;
+}): void;
+export declare function requirePathLastMatchesManifest(input: {
+    readonly path: readonly VerifiedContainerAccessManifest[] | undefined;
+    readonly manifest: VerifiedContainerAccessManifest;
+    readonly label: string;
+}): void;

package/internal/crypto/keying/containerParentAuthority.js

@@ -0,0 +1,53 @@
+import { throwVerification } from "./shared.js";
+/** Validate topology before combining grants from individually verified heads. */
+export function assertContainerPathIntegrity(path, label) {
+    const root = path[0];
+    // An empty path carries no authority; callers requiring a path reject it.
+    if (!root)
+        return;
+    if (root.state.parentContainerId !== null ||
+        root.state.parentManifestHash !== null) {
+        throwVerification("missing_dependency", `${label} path must start at a root`);
+    }
+    const seen = new Set();
+    for (const [index, manifest] of path.entries()) {
+        if (manifest.state.organizationId !== root.state.organizationId) {
+            throwVerification("object_mismatch", `${label} path crosses organizations`);
+        }
+        const parent = path[index - 1];
+        if (seen.has(manifest.state.containerId) ||
+            (parent && manifest.state.parentContainerId !== parent.state.containerId)) {
+            throwVerification("missing_dependency", `${label} path is not contiguous`);
+        }
+        seen.add(manifest.state.containerId);
+    }
+    // Do not compare creation-time parent hashes to served heads: an ancestor
+    // can advance while a descendant retains its older signed citation (F1).
+}
+export function requireContainerPathLast(path, label) {
+    const lastManifest = path?.at(-1);
+    if (!lastManifest) {
+        throwVerification("missing_dependency", `${label} path is required`);
+    }
+    return lastManifest;
+}
+export function requireContainerPathCurrentParent(input) {
+    if (!input.parentContainerId || !input.parentManifestHash) {
+        throwVerification("missing_dependency", `${input.label} parent manifest is required`);
+    }
+    const parentManifest = requireContainerPathLast(input.path, input.label);
+    if (input.path?.some((head) => head.state.organizationId !== input.organizationId)) {
+        throwVerification("object_mismatch", `${input.label} parent path belongs to another organization`);
+    }
+    if (parentManifest.state.containerId !== input.parentContainerId ||
+        parentManifest.manifestHash !== input.parentManifestHash) {
+        throwVerification("missing_dependency", `${input.label} parent manifest hash mismatch`);
+    }
+}
+export function requirePathLastMatchesManifest(input) {
+    const lastManifest = requireContainerPathLast(input.path, input.label);
+    if (lastManifest.manifestHash !== input.manifest.manifestHash) {
+        throwVerification("missing_dependency", `${input.label} path does not end at the expected manifest`);
+    }
+}
+//# sourceMappingURL=containerParentAuthority.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"containerParentAuthority.js","sourceRoot":"","sources":["containerParentAuthority.ts"],"names":[],"mappings":"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","sourcesContent":["import { throwVerification } from \"./shared\";\nimport type { VerifiedContainerAccessManifest } from \"./types\";\n\n/** Validate topology before combining grants from individually verified heads. */\nexport function assertContainerPathIntegrity(\n  path: readonly VerifiedContainerAccessManifest[],\n  label: string,\n): void {\n  const root = path[0];\n  // An empty path carries no authority; callers requiring a path reject it.\n  if (!root) return;\n  if (\n    root.state.parentContainerId !== null ||\n    root.state.parentManifestHash !== null\n  ) {\n    throwVerification(\n      \"missing_dependency\",\n      `${label} path must start at a root`,\n    );\n  }\n  const seen = new Set<string>();\n  for (const [index, manifest] of path.entries()) {\n    if (manifest.state.organizationId !== root.state.organizationId) {\n      throwVerification(\n        \"object_mismatch\",\n        `${label} path crosses organizations`,\n      );\n    }\n    const parent = path[index - 1];\n    if (\n      seen.has(manifest.state.containerId) ||\n      (parent && manifest.state.parentContainerId !== parent.state.containerId)\n    ) {\n      throwVerification(\n        \"missing_dependency\",\n        `${label} path is not contiguous`,\n      );\n    }\n    seen.add(manifest.state.containerId);\n  }\n  // Do not compare creation-time parent hashes to served heads: an ancestor\n  // can advance while a descendant retains its older signed citation (F1).\n}\n\nexport function requireContainerPathLast(\n  path: readonly VerifiedContainerAccessManifest[] | undefined,\n  label: string,\n): VerifiedContainerAccessManifest {\n  const lastManifest = path?.at(-1);\n  if (!lastManifest) {\n    throwVerification(\"missing_dependency\", `${label} path is required`);\n  }\n\n  return lastManifest;\n}\n\nexport function requireContainerPathCurrentParent(input: {\n  readonly organizationId: string;\n  readonly parentContainerId: string | null;\n  readonly parentManifestHash: string | null;\n  readonly path: readonly VerifiedContainerAccessManifest[] | undefined;\n  readonly label: string;\n}): void {\n  if (!input.parentContainerId || !input.parentManifestHash) {\n    throwVerification(\n      \"missing_dependency\",\n      `${input.label} parent manifest is required`,\n    );\n  }\n\n  const parentManifest = requireContainerPathLast(input.path, input.label);\n  if (\n    input.path?.some(\n      (head) => head.state.organizationId !== input.organizationId,\n    )\n  ) {\n    throwVerification(\n      \"object_mismatch\",\n      `${input.label} parent path belongs to another organization`,\n    );\n  }\n  if (\n    parentManifest.state.containerId !== input.parentContainerId ||\n    parentManifest.manifestHash !== input.parentManifestHash\n  ) {\n    throwVerification(\n      \"missing_dependency\",\n      `${input.label} parent manifest hash mismatch`,\n    );\n  }\n}\n\nexport function requirePathLastMatchesManifest(input: {\n  readonly path: readonly VerifiedContainerAccessManifest[] | undefined;\n  readonly manifest: VerifiedContainerAccessManifest;\n  readonly label: string;\n}): void {\n  const lastManifest = requireContainerPathLast(input.path, input.label);\n\n  if (lastManifest.manifestHash !== input.manifest.manifestHash) {\n    throwVerification(\n      \"missing_dependency\",\n      `${input.label} path does not end at the expected manifest`,\n    );\n  }\n}\n"]}

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

@@ -0,0 +1,45 @@
+import type { ContainerAccessLevel, ContainerAccessManifestState, ContainerDirectGrant, PrincipalPolicyAuthorization, ReferencedPrincipalHead, VerifiedContainerAccessManifest } from "./types.js";
+export declare function containerAccessLevelRank(accessLevel: ContainerAccessLevel): number;
+export declare function mergeContainerAccessLevel(current: ContainerAccessLevel | null, incoming: ContainerAccessLevel): ContainerAccessLevel;
+export declare function principalPolicyMatchesReference(input: {
+    readonly policy: PrincipalPolicyAuthorization;
+    readonly reference: ReferencedPrincipalHead;
+}): boolean;
+export declare function grantAccessLevelForUser(input: {
+    readonly grant: ContainerDirectGrant;
+    readonly membershipAt: "current" | "referenced";
+    readonly principalPolicies: readonly PrincipalPolicyAuthorization[];
+    readonly state: Pick<ContainerAccessManifestState, "referencedPrincipalHeads">;
+    readonly userId: string;
+}): ContainerAccessLevel | null;
+declare function resolveContainerPathUserAccessLevelAt(input: {
+    readonly membershipAt: "current" | "referenced";
+    readonly path: readonly Pick<VerifiedContainerAccessManifest, "state">[];
+    readonly principalPolicies?: readonly PrincipalPolicyAuthorization[];
+    readonly userId: string;
+}): ContainerAccessLevel | null;
+export declare function resolveContainerPathUserAccessLevel(input: Omit<Parameters<typeof resolveContainerPathUserAccessLevelAt>[0], "membershipAt" | "path"> & {
+    readonly path: readonly VerifiedContainerAccessManifest[];
+}): ContainerAccessLevel | null;
+export declare function resolveHistoricalContainerPathUserAccessLevel(input: Omit<Parameters<typeof resolveContainerPathUserAccessLevelAt>[0], "membershipAt" | "path"> & {
+    readonly path: readonly VerifiedContainerAccessManifest[];
+}): ContainerAccessLevel | null;
+export declare function requireContainerPathUserAccess(input: {
+    readonly membershipAt?: "current" | "referenced";
+    readonly label: string;
+    readonly minimumAccessLevel: ContainerAccessLevel;
+    readonly path: readonly VerifiedContainerAccessManifest[] | undefined;
+    readonly principalPolicies: readonly PrincipalPolicyAuthorization[];
+    readonly userId: string;
+}): void;
+/**
+ * Calculates current access from already-trusted states. This does not verify
+ * signatures, brand manifests, or advance checkpoints. Locally acknowledged
+ * plans and verified projections can both supply those immutable states.
+ */
+export declare function resolveContainerStatePathUserAccessLevel(input: {
+    readonly states: readonly ContainerAccessManifestState[];
+    readonly principalPolicies: readonly PrincipalPolicyAuthorization[];
+    readonly userId: string;
+}): ContainerAccessLevel | null;
+export {};

package/internal/crypto/keying/containerPathAccess.js

@@ -0,0 +1,111 @@
+import { assertContainerPathIntegrity } from "./containerParentAuthority.js";
+import { principalPolicyEntryForReference } from "./principalPolicyReference.js";
+import { throwVerification } from "./shared.js";
+export function containerAccessLevelRank(accessLevel) {
+    if (accessLevel === "admin") {
+        return 3;
+    }
+    if (accessLevel === "write") {
+        return 2;
+    }
+    return 1;
+}
+export function mergeContainerAccessLevel(current, incoming) {
+    if (current === null ||
+        containerAccessLevelRank(incoming) > containerAccessLevelRank(current)) {
+        return incoming;
+    }
+    return current;
+}
+export function principalPolicyMatchesReference(input) {
+    return principalPolicyEntryForReference(input) !== undefined;
+}
+export function grantAccessLevelForUser(input) {
+    if (input.grant.subjectType === "user") {
+        return input.grant.subjectId === input.userId
+            ? input.grant.accessLevel
+            : null;
+    }
+    const referencedHead = input.state.referencedPrincipalHeads.find((principalHead) => principalHead.principalType === input.grant.subjectType &&
+        principalHead.principalId === input.grant.subjectId);
+    if (!referencedHead) {
+        return null;
+    }
+    const verifiedPolicy = input.principalPolicies.find((policy) => principalPolicyMatchesReference({ policy, reference: referencedHead }));
+    if (!verifiedPolicy) {
+        return null;
+    }
+    const projection = input.membershipAt === "current"
+        ? verifiedPolicy.projection
+        : principalPolicyEntryForReference({
+            policy: verifiedPolicy,
+            reference: referencedHead,
+        })?.projection;
+    return projection?.some((member) => member.userId === input.userId)
+        ? input.grant.accessLevel
+        : null;
+}
+function resolveContainerPathUserAccessLevelAt(input) {
+    let accessLevel = null;
+    for (const containerManifest of input.path) {
+        for (const grant of containerManifest.state.directGrants) {
+            const grantAccessLevel = grantAccessLevelForUser({
+                grant,
+                membershipAt: input.membershipAt,
+                principalPolicies: input.principalPolicies ?? [],
+                state: containerManifest.state,
+                userId: input.userId,
+            });
+            if (grantAccessLevel) {
+                accessLevel = mergeContainerAccessLevel(accessLevel, grantAccessLevel);
+            }
+        }
+    }
+    return accessLevel;
+}
+export function resolveContainerPathUserAccessLevel(input) {
+    assertContainerPathIntegrity(input.path, "container authorization");
+    return resolveContainerPathUserAccessLevelAt({
+        ...input,
+        membershipAt: "current",
+    });
+}
+export function resolveHistoricalContainerPathUserAccessLevel(input) {
+    assertContainerPathIntegrity(input.path, "historical container authorization");
+    return resolveContainerPathUserAccessLevelAt({
+        ...input,
+        membershipAt: "referenced",
+    });
+}
+export function requireContainerPathUserAccess(input) {
+    const path = input.path;
+    if (!path || path.length === 0) {
+        throwVerification("missing_dependency", `${input.label} path is required`);
+    }
+    assertContainerPathIntegrity(path, input.label);
+    const accessLevel = resolveContainerPathUserAccessLevelAt({
+        membershipAt: input.membershipAt ?? "current",
+        path,
+        principalPolicies: input.principalPolicies,
+        userId: input.userId,
+    });
+    if (accessLevel === null ||
+        containerAccessLevelRank(accessLevel) <
+            containerAccessLevelRank(input.minimumAccessLevel)) {
+        throwVerification("unauthorized", `${input.label} signer lacks ${input.minimumAccessLevel} access`);
+    }
+}
+/**
+ * Calculates current access from already-trusted states. This does not verify
+ * signatures, brand manifests, or advance checkpoints. Locally acknowledged
+ * plans and verified projections can both supply those immutable states.
+ */
+export function resolveContainerStatePathUserAccessLevel(input) {
+    return resolveContainerPathUserAccessLevelAt({
+        membershipAt: "current",
+        path: input.states.map((state) => ({ state })),
+        principalPolicies: input.principalPolicies,
+        userId: input.userId,
+    });
+}
+//# sourceMappingURL=containerPathAccess.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"containerPathAccess.js","sourceRoot":"","sources":["containerPathAccess.ts"],"names":[],"mappings":"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","sourcesContent":["import { assertContainerPathIntegrity } from \"./containerParentAuthority\";\nimport { principalPolicyEntryForReference } from \"./principalPolicyReference\";\nimport { throwVerification } from \"./shared\";\nimport type {\n  ContainerAccessLevel,\n  ContainerAccessManifestState,\n  ContainerDirectGrant,\n  PrincipalPolicyAuthorization,\n  ReferencedPrincipalHead,\n  VerifiedContainerAccessManifest,\n} from \"./types\";\n\nexport function containerAccessLevelRank(\n  accessLevel: ContainerAccessLevel,\n): number {\n  if (accessLevel === \"admin\") {\n    return 3;\n  }\n\n  if (accessLevel === \"write\") {\n    return 2;\n  }\n\n  return 1;\n}\n\nexport function mergeContainerAccessLevel(\n  current: ContainerAccessLevel | null,\n  incoming: ContainerAccessLevel,\n): ContainerAccessLevel {\n  if (\n    current === null ||\n    containerAccessLevelRank(incoming) > containerAccessLevelRank(current)\n  ) {\n    return incoming;\n  }\n\n  return current;\n}\n\nexport function principalPolicyMatchesReference(input: {\n  readonly policy: PrincipalPolicyAuthorization;\n  readonly reference: ReferencedPrincipalHead;\n}): boolean {\n  return principalPolicyEntryForReference(input) !== undefined;\n}\n\nexport function grantAccessLevelForUser(input: {\n  readonly grant: ContainerDirectGrant;\n  readonly membershipAt: \"current\" | \"referenced\";\n  readonly principalPolicies: readonly PrincipalPolicyAuthorization[];\n  readonly state: Pick<\n    ContainerAccessManifestState,\n    \"referencedPrincipalHeads\"\n  >;\n  readonly userId: string;\n}): ContainerAccessLevel | null {\n  if (input.grant.subjectType === \"user\") {\n    return input.grant.subjectId === input.userId\n      ? input.grant.accessLevel\n      : null;\n  }\n\n  const referencedHead = input.state.referencedPrincipalHeads.find(\n    (principalHead) =>\n      principalHead.principalType === input.grant.subjectType &&\n      principalHead.principalId === input.grant.subjectId,\n  );\n\n  if (!referencedHead) {\n    return null;\n  }\n\n  const verifiedPolicy = input.principalPolicies.find((policy) =>\n    principalPolicyMatchesReference({ policy, reference: referencedHead }),\n  );\n  if (!verifiedPolicy) {\n    return null;\n  }\n  const projection =\n    input.membershipAt === \"current\"\n      ? verifiedPolicy.projection\n      : principalPolicyEntryForReference({\n          policy: verifiedPolicy,\n          reference: referencedHead,\n        })?.projection;\n\n  return projection?.some((member) => member.userId === input.userId)\n    ? input.grant.accessLevel\n    : null;\n}\n\nfunction resolveContainerPathUserAccessLevelAt(input: {\n  readonly membershipAt: \"current\" | \"referenced\";\n  readonly path: readonly Pick<VerifiedContainerAccessManifest, \"state\">[];\n  readonly principalPolicies?: readonly PrincipalPolicyAuthorization[];\n  readonly userId: string;\n}): ContainerAccessLevel | null {\n  let accessLevel: ContainerAccessLevel | null = null;\n\n  for (const containerManifest of input.path) {\n    for (const grant of containerManifest.state.directGrants) {\n      const grantAccessLevel = grantAccessLevelForUser({\n        grant,\n        membershipAt: input.membershipAt,\n        principalPolicies: input.principalPolicies ?? [],\n        state: containerManifest.state,\n        userId: input.userId,\n      });\n\n      if (grantAccessLevel) {\n        accessLevel = mergeContainerAccessLevel(accessLevel, grantAccessLevel);\n      }\n    }\n  }\n\n  return accessLevel;\n}\n\nexport function resolveContainerPathUserAccessLevel(\n  input: Omit<\n    Parameters<typeof resolveContainerPathUserAccessLevelAt>[0],\n    \"membershipAt\" | \"path\"\n  > & { readonly path: readonly VerifiedContainerAccessManifest[] },\n): ContainerAccessLevel | null {\n  assertContainerPathIntegrity(input.path, \"container authorization\");\n  return resolveContainerPathUserAccessLevelAt({\n    ...input,\n    membershipAt: \"current\",\n  });\n}\n\nexport function resolveHistoricalContainerPathUserAccessLevel(\n  input: Omit<\n    Parameters<typeof resolveContainerPathUserAccessLevelAt>[0],\n    \"membershipAt\" | \"path\"\n  > & { readonly path: readonly VerifiedContainerAccessManifest[] },\n): ContainerAccessLevel | null {\n  assertContainerPathIntegrity(\n    input.path,\n    \"historical container authorization\",\n  );\n  return resolveContainerPathUserAccessLevelAt({\n    ...input,\n    membershipAt: \"referenced\",\n  });\n}\n\nexport function requireContainerPathUserAccess(input: {\n  readonly membershipAt?: \"current\" | \"referenced\";\n  readonly label: string;\n  readonly minimumAccessLevel: ContainerAccessLevel;\n  readonly path: readonly VerifiedContainerAccessManifest[] | undefined;\n  readonly principalPolicies: readonly PrincipalPolicyAuthorization[];\n  readonly userId: string;\n}): void {\n  const path = input.path;\n  if (!path || path.length === 0) {\n    throwVerification(\"missing_dependency\", `${input.label} path is required`);\n  }\n\n  assertContainerPathIntegrity(path, input.label);\n  const accessLevel = resolveContainerPathUserAccessLevelAt({\n    membershipAt: input.membershipAt ?? \"current\",\n    path,\n    principalPolicies: input.principalPolicies,\n    userId: input.userId,\n  });\n\n  if (\n    accessLevel === null ||\n    containerAccessLevelRank(accessLevel) <\n      containerAccessLevelRank(input.minimumAccessLevel)\n  ) {\n    throwVerification(\n      \"unauthorized\",\n      `${input.label} signer lacks ${input.minimumAccessLevel} access`,\n    );\n  }\n}\n\n/**\n * Calculates current access from already-trusted states. This does not verify\n * signatures, brand manifests, or advance checkpoints. Locally acknowledged\n * plans and verified projections can both supply those immutable states.\n */\nexport function resolveContainerStatePathUserAccessLevel(input: {\n  readonly states: readonly ContainerAccessManifestState[];\n  readonly principalPolicies: readonly PrincipalPolicyAuthorization[];\n  readonly userId: string;\n}): ContainerAccessLevel | null {\n  return resolveContainerPathUserAccessLevelAt({\n    membershipAt: \"current\",\n    path: input.states.map((state) => ({ state })),\n    principalPolicies: input.principalPolicies,\n    userId: input.userId,\n  });\n}\n"]}

package/internal/crypto/keying/containerPrincipalReferences.js

@@ -0,0 +1,34 @@
+import { referencedPrincipalKey } from "./accessEvent.js";
+import { normalizeContainerGrantPrincipalHeads } from "./containerGrantPrincipalHead.js";
+import { throwVerification } from "./shared.js";
+export function upsertReferencedPrincipalHead(principalHeads, principalHead) {
+    const nextPrincipalHeads = principalHeads.filter((existingHead) => referencedPrincipalKey(existingHead) !==
+        referencedPrincipalKey(principalHead));
+    nextPrincipalHeads.push(principalHead);
+    return normalizeContainerGrantPrincipalHeads(nextPrincipalHeads);
+}
+export function removeReferencedPrincipalHead(principalHeads, revokedGrant) {
+    if (revokedGrant.subjectType === "user") {
+        return normalizeContainerGrantPrincipalHeads(principalHeads);
+    }
+    const revokedReferenceKey = `${revokedGrant.subjectType}:${revokedGrant.subjectId}`;
+    return normalizeContainerGrantPrincipalHeads(principalHeads.filter((principalHead) => referencedPrincipalKey(principalHead) !== revokedReferenceKey));
+}
+export function assertContainerPrincipalReferencesProgress(previous, next) {
+    const previousById = new Map(previous.map((head) => [referencedPrincipalKey(head), head]));
+    for (const head of next) {
+        const prior = previousById.get(referencedPrincipalKey(head));
+        if (!prior)
+            continue;
+        if (head.version < prior.version || head.keyEpoch < prior.keyEpoch) {
+            throwVerification("rollback", "Container principal reference regresses below its signed predecessor");
+        }
+        if (head.version === prior.version &&
+            (head.stateHash !== prior.stateHash ||
+                head.keyEpoch !== prior.keyEpoch ||
+                head.keyFingerprint !== prior.keyFingerprint)) {
+            throwVerification("equivocation", "Container principal reference conflicts at the same version");
+        }
+    }
+}
+//# sourceMappingURL=containerPrincipalReferences.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"containerPrincipalReferences.js","sourceRoot":"","sources":["containerPrincipalReferences.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,qCAAqC,EAAE,MAAM,+BAA+B,CAAC;AACtF,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAM7C,MAAM,UAAU,6BAA6B,CAC3C,cAAsD,EACtD,aAA0C;IAE1C,MAAM,kBAAkB,GAAG,cAAc,CAAC,MAAM,CAC9C,CAAC,YAAY,EAAE,EAAE,CACf,sBAAsB,CAAC,YAAY,CAAC;QACpC,sBAAsB,CAAC,aAAa,CAAC,CACxC,CAAC;IACF,kBAAkB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACvC,OAAO,qCAAqC,CAAC,kBAAkB,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,cAAsD,EACtD,YAAqE;IAErE,IAAI,YAAY,CAAC,WAAW,KAAK,MAAM,EAAE,CAAC;QACxC,OAAO,qCAAqC,CAAC,cAAc,CAAC,CAAC;IAC/D,CAAC;IAED,MAAM,mBAAmB,GAAG,GAAG,YAAY,CAAC,WAAW,IAAI,YAAY,CAAC,SAAS,EAAE,CAAC;IACpF,OAAO,qCAAqC,CAC1C,cAAc,CAAC,MAAM,CACnB,CAAC,aAAa,EAAE,EAAE,CAChB,sBAAsB,CAAC,aAAa,CAAC,KAAK,mBAAmB,CAChE,CACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,0CAA0C,CACxD,QAAgD,EAChD,IAA4C;IAE5C,MAAM,YAAY,GAAG,IAAI,GAAG,CAC1B,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,sBAAsB,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,CAC7D,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7D,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,IAAI,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;YACnE,iBAAiB,CACf,UAAU,EACV,sEAAsE,CACvE,CAAC;QACJ,CAAC;QACD,IACE,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO;YAC9B,CAAC,IAAI,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS;gBACjC,IAAI,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ;gBAChC,IAAI,CAAC,cAAc,KAAK,KAAK,CAAC,cAAc,CAAC,EAC/C,CAAC;YACD,iBAAiB,CACf,cAAc,EACd,6DAA6D,CAC9D,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC","sourcesContent":["import { referencedPrincipalKey } from \"./accessEvent\";\nimport { normalizeContainerGrantPrincipalHeads } from \"./containerGrantPrincipalHead\";\nimport { throwVerification } from \"./shared\";\nimport type {\n  ContainerDirectGrant,\n  ContainerGrantPrincipalHead,\n} from \"./types\";\n\nexport function upsertReferencedPrincipalHead(\n  principalHeads: readonly ContainerGrantPrincipalHead[],\n  principalHead: ContainerGrantPrincipalHead,\n): ContainerGrantPrincipalHead[] {\n  const nextPrincipalHeads = principalHeads.filter(\n    (existingHead) =>\n      referencedPrincipalKey(existingHead) !==\n      referencedPrincipalKey(principalHead),\n  );\n  nextPrincipalHeads.push(principalHead);\n  return normalizeContainerGrantPrincipalHeads(nextPrincipalHeads);\n}\n\nexport function removeReferencedPrincipalHead(\n  principalHeads: readonly ContainerGrantPrincipalHead[],\n  revokedGrant: Pick<ContainerDirectGrant, \"subjectId\" | \"subjectType\">,\n): ContainerGrantPrincipalHead[] {\n  if (revokedGrant.subjectType === \"user\") {\n    return normalizeContainerGrantPrincipalHeads(principalHeads);\n  }\n\n  const revokedReferenceKey = `${revokedGrant.subjectType}:${revokedGrant.subjectId}`;\n  return normalizeContainerGrantPrincipalHeads(\n    principalHeads.filter(\n      (principalHead) =>\n        referencedPrincipalKey(principalHead) !== revokedReferenceKey,\n    ),\n  );\n}\n\nexport function assertContainerPrincipalReferencesProgress(\n  previous: readonly ContainerGrantPrincipalHead[],\n  next: readonly ContainerGrantPrincipalHead[],\n): void {\n  const previousById = new Map(\n    previous.map((head) => [referencedPrincipalKey(head), head]),\n  );\n  for (const head of next) {\n    const prior = previousById.get(referencedPrincipalKey(head));\n    if (!prior) continue;\n    if (head.version < prior.version || head.keyEpoch < prior.keyEpoch) {\n      throwVerification(\n        \"rollback\",\n        \"Container principal reference regresses below its signed predecessor\",\n      );\n    }\n    if (\n      head.version === prior.version &&\n      (head.stateHash !== prior.stateHash ||\n        head.keyEpoch !== prior.keyEpoch ||\n        head.keyFingerprint !== prior.keyFingerprint)\n    ) {\n      throwVerification(\n        \"equivocation\",\n        \"Container principal reference conflicts at the same version\",\n      );\n    }\n  }\n}\n"]}

package/internal/crypto/keying/containerSystemTopology.js

@@ -0,0 +1,18 @@
+import { deriveOrganizationMetadataContainerSystemSlot } from "../../validators/containerSystemSlot.js";
+import { throwVerification } from "./shared.js";
+/** Only organization metadata has an independent root; other slots stay children. */
+export async function assertContainerSystemTopology(body, organizationId) {
+    if (body.systemSlot === null)
+        return;
+    const metadataSlot = await deriveOrganizationMetadataContainerSystemSlot({
+        organizationId,
+    });
+    if (body.systemSlot === metadataSlot) {
+        if (body.parentContainerId !== null)
+            throwVerification("invalid_shape", "organization metadata must be an independent root");
+    }
+    else if (body.parentContainerId === null) {
+        throwVerification("invalid_shape", "root containers cannot have a system slot");
+    }
+}
+//# sourceMappingURL=containerSystemTopology.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"containerSystemTopology.js","sourceRoot":"","sources":["containerSystemTopology.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6CAA6C,EAAE,MAAM,2CAA2C,CAAC;AAC1G,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG7C,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,IAAoC,EACpC,cAAsB;IAEtB,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI;QAAE,OAAO;IACrC,MAAM,YAAY,GAAG,MAAM,6CAA6C,CAAC;QACvE,cAAc;KACf,CAAC,CAAC;IACH,IAAI,IAAI,CAAC,UAAU,KAAK,YAAY,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,iBAAiB,KAAK,IAAI;YACjC,iBAAiB,CACf,eAAe,EACf,mDAAmD,CACpD,CAAC;IACN,CAAC;SAAM,IAAI,IAAI,CAAC,iBAAiB,KAAK,IAAI,EAAE,CAAC;QAC3C,iBAAiB,CACf,eAAe,EACf,2CAA2C,CAC5C,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["import { deriveOrganizationMetadataContainerSystemSlot } from \"@tearleads/validators/containerSystemSlot\";\nimport { throwVerification } from \"./shared\";\nimport type { ContainerCreateAccessEventBody } from \"./types\";\n\n/** Only organization metadata has an independent root; other slots stay children. */\nexport async function assertContainerSystemTopology(\n  body: ContainerCreateAccessEventBody,\n  organizationId: string,\n): Promise<void> {\n  if (body.systemSlot === null) return;\n  const metadataSlot = await deriveOrganizationMetadataContainerSystemSlot({\n    organizationId,\n  });\n  if (body.systemSlot === metadataSlot) {\n    if (body.parentContainerId !== null)\n      throwVerification(\n        \"invalid_shape\",\n        \"organization metadata must be an independent root\",\n      );\n  } else if (body.parentContainerId === null) {\n    throwVerification(\n      \"invalid_shape\",\n      \"root containers cannot have a system slot\",\n    );\n  }\n}\n"]}

package/internal/crypto/keying/containerUserRecipientKey.js

@@ -0,0 +1,15 @@
+import { assertExactKeys, readHashString, readString, throwVerification, } from "./shared.js";
+export function normalizeContainerUserRecipientKey(value) {
+    const record = assertExactKeys(value, ["recipientKeyEpochId", "recipientKeyFingerprint", "userId"], "container user recipient key");
+    const key = {
+        userId: readString(record, "userId", "container user recipient key"),
+        recipientKeyEpochId: readString(record, "recipientKeyEpochId", "container user recipient key"),
+        recipientKeyFingerprint: readHashString(record, "recipientKeyFingerprint", "container user recipient key"),
+    };
+    if (key.recipientKeyEpochId !==
+        `user:${key.userId}:encapsulation:${key.recipientKeyFingerprint}`) {
+        throwVerification("invalid_shape", "Container user recipient key epoch must match its user and fingerprint");
+    }
+    return key;
+}
+//# sourceMappingURL=containerUserRecipientKey.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"containerUserRecipientKey.js","sourceRoot":"","sources":["containerUserRecipientKey.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,cAAc,EACd,UAAU,EACV,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAGlB,MAAM,UAAU,kCAAkC,CAChD,KAAc;IAEd,MAAM,MAAM,GAAG,eAAe,CAC5B,KAAK,EACL,CAAC,qBAAqB,EAAE,yBAAyB,EAAE,QAAQ,CAAC,EAC5D,8BAA8B,CAC/B,CAAC;IAEF,MAAM,GAAG,GAAG;QACV,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,QAAQ,EAAE,8BAA8B,CAAC;QACpE,mBAAmB,EAAE,UAAU,CAC7B,MAAM,EACN,qBAAqB,EACrB,8BAA8B,CAC/B;QACD,uBAAuB,EAAE,cAAc,CACrC,MAAM,EACN,yBAAyB,EACzB,8BAA8B,CAC/B;KACF,CAAC;IACF,IACE,GAAG,CAAC,mBAAmB;QACvB,QAAQ,GAAG,CAAC,MAAM,kBAAkB,GAAG,CAAC,uBAAuB,EAAE,EACjE,CAAC;QACD,iBAAiB,CACf,eAAe,EACf,wEAAwE,CACzE,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["import {\n  assertExactKeys,\n  readHashString,\n  readString,\n  throwVerification,\n} from \"./shared\";\nimport type { ContainerUserRecipientKey } from \"./types\";\n\nexport function normalizeContainerUserRecipientKey(\n  value: unknown,\n): ContainerUserRecipientKey {\n  const record = assertExactKeys(\n    value,\n    [\"recipientKeyEpochId\", \"recipientKeyFingerprint\", \"userId\"],\n    \"container user recipient key\",\n  );\n\n  const key = {\n    userId: readString(record, \"userId\", \"container user recipient key\"),\n    recipientKeyEpochId: readString(\n      record,\n      \"recipientKeyEpochId\",\n      \"container user recipient key\",\n    ),\n    recipientKeyFingerprint: readHashString(\n      record,\n      \"recipientKeyFingerprint\",\n      \"container user recipient key\",\n    ),\n  };\n  if (\n    key.recipientKeyEpochId !==\n    `user:${key.userId}:encapsulation:${key.recipientKeyFingerprint}`\n  ) {\n    throwVerification(\n      \"invalid_shape\",\n      \"Container user recipient key epoch must match its user and fingerprint\",\n    );\n  }\n  return key;\n}\n"]}

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

@@ -0,0 +1,14 @@
+import type { AccessManifest, AttachmentAccessEventBody, DocumentLinkSetManifestState, DocumentLinkSetStructural, KeyingCanonicalJson, KeyingVerificationResult, VerifiedAttachmentBinding, VerifiedAttachmentDetach, VerifiedContainerParentEdge, VerifiedDocumentLinkSetManifest, VerifyAttachmentBindingEventInput, VerifyAttachmentDetachEventInput, VerifyContainerParentEdgeInput, VerifyDocumentLinkSetManifestInput } from "./types.js";
+export { requireEventDependency } from "./documentAccessAuthorization.js";
+export { normalizeDocumentAccessEventBody } from "./documentAccessBody.js";
+export { requireWriteAccessThroughCommittedBlobTarget, requireWriteAccessThroughCommittedDocumentTarget, } from "./documentContentWriteAuthority.js";
+export declare function normalizeDocumentLinkSetManifestState(value: unknown): DocumentLinkSetManifestState;
+export declare function computeDocumentLinkSetStructuralHash(structural: DocumentLinkSetStructural): Promise<string>;
+export declare function computeDocumentLinkSetGrantRoot(): Promise<string>;
+export declare function computeDocumentLinkSetKeyTargetHash(): Promise<string>;
+export declare function deriveDocumentLinkSetManifest(state: DocumentLinkSetManifestState): Promise<AccessManifest>;
+export declare function normalizeAttachmentAccessEventBody(value: KeyingCanonicalJson): AttachmentAccessEventBody;
+export declare function verifyAttachmentBindingEvent({ authorizationMembership, authorizingContainerPaths, documentManifest, expectedBindingId, expectedBlobId, expectedDocumentId, expectedDocumentManifestHash, expectedPreviousBindingId, principalPolicies, ...input }: VerifyAttachmentBindingEventInput): Promise<KeyingVerificationResult<VerifiedAttachmentBinding>>;
+export declare function verifyAttachmentDetachEvent({ authorizationMembership, authorizingContainerPaths, documentManifest, expectedBindingId, expectedBlobId, expectedDocumentId, expectedDocumentManifestHash, principalPolicies, ...input }: VerifyAttachmentDetachEventInput): Promise<KeyingVerificationResult<VerifiedAttachmentDetach>>;
+export declare function verifyDocumentLinkSetManifest({ authorizationMembership, authorizingContainerPaths, checkpointPredecessors, event, expectedManifestHash, localCheckpoint, manifest, previousManifest, principalPolicies, targetContainerPath, }: VerifyDocumentLinkSetManifestInput): Promise<KeyingVerificationResult<VerifiedDocumentLinkSetManifest>>;
+export declare function verifyContainerParentEdge({ child, parentHistory, }: VerifyContainerParentEdgeInput): KeyingVerificationResult<VerifiedContainerParentEdge>;