@tearleads/client-sdk 0.0.0-stage → 0.1.11

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

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyHistoryIndex.js","sourceRoot":"","sources":["principalPolicyHistoryIndex.ts"],"names":[],"mappings":"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","sourcesContent":["import { computeKeyingDomainHash } from \"./canonical\";\nimport { readHashString, throwVerification } from \"./shared\";\nimport {\n  computeTransparencyNodeHash,\n  largestPowerOfTwoLessThan,\n} from \"./transparencyTree\";\nimport type {\n  PrincipalPolicySignedState,\n  TransparencyInclusionProof,\n} from \"./types\";\n\n/** Content-addressed, untrusted proof material; the verified root is authority. */\nexport interface PrincipalHistoryIndexNode {\n  readonly hash: string;\n  readonly leftHash: string;\n  readonly rightHash: string;\n}\n\nexport type PrincipalHistoryIndexFrontier = readonly (string | null)[];\n\nexport function normalizePrincipalHistoryIndexFrontier(\n  value: unknown,\n  size: number,\n): (string | null)[] {\n  if (\n    !Number.isSafeInteger(size) ||\n    size < 0 ||\n    !Array.isArray(value) ||\n    value.length > 53\n  )\n    throwVerification(\n      \"invalid_shape\",\n      \"invalid principal history index frontier\",\n    );\n  const frontier: (string | null)[] = [];\n  let remaining = size;\n  for (const item of value) {\n    if (\n      remaining === 0 ||\n      (remaining % 2 === 0 ? item !== null : item === null)\n    )\n      throwVerification(\n        \"invalid_shape\",\n        \"principal history frontier does not match its size\",\n      );\n    frontier.push(\n      item === null\n        ? null\n        : readHashString({ hash: item }, \"hash\", \"principal history frontier\"),\n    );\n    remaining = Math.floor(remaining / 2);\n  }\n  if (remaining !== 0)\n    throwVerification(\n      \"invalid_shape\",\n      \"principal history frontier is incomplete\",\n    );\n  return frontier;\n}\n\nexport function principalHistoryIndexLeaf(\n  state: PrincipalPolicySignedState,\n): Promise<string> {\n  return computeKeyingDomainHash(\"tearleads.keying.principal-history-leaf\", {\n    principalType: state.principalType,\n    principalId: state.principalId,\n    version: state.version,\n    keyEpoch: state.keyEpoch,\n    keyFingerprint: state.keyFingerprint,\n    stateHash: state.stateHash,\n    signature: state.signature,\n  });\n}\n\nasync function join(\n  leftHash: string,\n  rightHash: string,\n  nodes?: Map<string, PrincipalHistoryIndexNode>,\n): Promise<string> {\n  const hash = await computeTransparencyNodeHash(leftHash, rightHash);\n  nodes?.set(hash, { hash, leftHash, rightHash });\n  return hash;\n}\n\nexport async function principalHistoryIndexRoot(\n  frontier: PrincipalHistoryIndexFrontier,\n  nodes?: Map<string, PrincipalHistoryIndexNode>,\n): Promise<string | null> {\n  let root: string | null = null;\n  for (const hash of frontier) {\n    if (hash !== null)\n      root = root === null ? hash : await join(hash, root, nodes);\n  }\n  return root;\n}\n\n/** Build privately; the caller publishes this only with an accepted page. */\ninterface AppendedPrincipalHistoryIndex {\n  readonly frontier: PrincipalHistoryIndexFrontier;\n  readonly rootHash: string | null;\n  readonly nodes: readonly PrincipalHistoryIndexNode[];\n}\n\nexport async function appendPrincipalHistoryIndex(\n  previous: PrincipalHistoryIndexFrontier,\n  states: readonly PrincipalPolicySignedState[],\n): Promise<AppendedPrincipalHistoryIndex> {\n  const frontier = [...previous];\n  const nodes = new Map<string, PrincipalHistoryIndexNode>();\n  for (const state of states) {\n    let carry = await principalHistoryIndexLeaf(state);\n    let height = 0;\n    for (let left = frontier[height]; left; left = frontier[height]) {\n      carry = await join(left, carry, nodes);\n      frontier[height] = null;\n      height += 1;\n    }\n    frontier[height] = carry;\n  }\n  const rootHash = await principalHistoryIndexRoot(frontier, nodes);\n  return { frontier, rootHash, nodes: [...nodes.values()] };\n}\n\n/** Fetch at most one content-addressed node per level, never a history array. */\nexport async function createPrincipalHistoryIndexProof(input: {\n  readonly rootHash: string;\n  readonly treeSize: number;\n  readonly version: number;\n  readonly readNode: (\n    hash: string,\n  ) => Promise<PrincipalHistoryIndexNode | null>;\n}): Promise<TransparencyInclusionProof> {\n  const { treeSize, version } = input;\n  if (\n    !Number.isSafeInteger(treeSize) ||\n    treeSize < 1 ||\n    !Number.isSafeInteger(version) ||\n    version < 1 ||\n    version > treeSize\n  )\n    throwVerification(\n      \"invalid_shape\",\n      \"principal history proof version is out of range\",\n    );\n  let hash = readHashString(input, \"rootHash\", \"principal history proof\");\n  let size = treeSize;\n  let position = version - 1;\n  const siblings: string[] = [];\n  while (size > 1) {\n    const node = await input.readNode(hash);\n    if (!node || node.hash !== hash)\n      throwVerification(\n        \"missing_dependency\",\n        \"principal history index node is missing\",\n      );\n    const left = readHashString(\n      { leftHash: node.leftHash },\n      \"leftHash\",\n      \"principal history index node\",\n    );\n    const right = readHashString(\n      { rightHash: node.rightHash },\n      \"rightHash\",\n      \"principal history index node\",\n    );\n    if ((await join(left, right)) !== hash)\n      throwVerification(\n        \"hash_mismatch\",\n        \"principal history index node hash mismatch\",\n      );\n    const split = largestPowerOfTwoLessThan(size);\n    if (position < split) {\n      siblings.push(right);\n      hash = left;\n      size = split;\n    } else {\n      siblings.push(left);\n      hash = right;\n      position -= split;\n      size -= split;\n    }\n  }\n  return {\n    version: 1,\n    treeSize,\n    leafIndex: version - 1,\n    auditPath: siblings.reverse(),\n  };\n}\n"]}

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

@@ -0,0 +1,17 @@
+import type { PrincipalStateExternalAuthority } from "../principalState.js";
+import { type PrincipalPolicyHistoryPage } from "./principalPolicyHistoryTypes.js";
+import type { NormalizedPrincipalPolicyStateChainEntry, PrincipalPolicyCheckpoint, ReferencedPrincipalHead } from "./types.js";
+export declare const PRINCIPAL_HISTORY_VERIFICATION_REVISION = 2;
+export declare function verifyPrincipalHistoryPage(input: {
+    readonly page: PrincipalPolicyHistoryPage;
+    readonly principalId: string;
+    readonly principalType: ReferencedPrincipalHead["principalType"];
+    readonly previous: NormalizedPrincipalPolicyStateChainEntry | undefined;
+    readonly latestAuthority: PrincipalStateExternalAuthority | null;
+    readonly references: readonly ReferencedPrincipalHead[];
+    readonly checkpoint: PrincipalPolicyCheckpoint | null;
+}): Promise<{
+    entries: NormalizedPrincipalPolicyStateChainEntry[];
+    last: NormalizedPrincipalPolicyStateChainEntry;
+    latestAuthority: PrincipalStateExternalAuthority | null;
+}>;

package/internal/crypto/keying/principalPolicyHistoryPage.js

@@ -0,0 +1,87 @@
+import { normalizePrincipalPolicyStateChainEntry, verifyInitialPrincipalPolicyChainEntry, verifyPrincipalPolicyChainEntryIdentity, verifySuccessorPrincipalPolicyChainEntry, } from "./principalPolicyChainEntry.js";
+import { createPrincipalPolicyExternalAuthorityVerifier, verifyPrincipalPolicyExternalAuthorityProgress, } from "./principalPolicyExternalAuthority.js";
+import { PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT, } from "./principalPolicyHistoryTypes.js";
+import { principalPolicyStateMatchesReference } from "./principalPolicyReference.js";
+import { verifyPrincipalPolicyChainSignatures } from "./principalPolicySignatures.js";
+import { buildPrincipalPolicySignerKeyMap } from "./principalPolicySignerKeys.js";
+import { throwVerification } from "./shared.js";
+// Bump when page, chain, signer, or external-authority verification tightens.
+// Authenticated saved progress must then re-verify its omitted prefix.
+export const PRINCIPAL_HISTORY_VERIFICATION_REVISION = 2;
+function assertPageBudget(page) {
+    if (page.entries.length < 1 ||
+        page.entries.length > PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT ||
+        page.signerPublicKeys.length > PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT ||
+        (page.externalAuthority?.states.length ?? 0) >
+            PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT + 1)
+        throwVerification("invalid_shape", "principal history page exceeds its entry budget");
+}
+function ownPage(page) {
+    assertPageBudget(page);
+    // Own bytes before yielding, then bind the budget to those same bytes: a
+    // caller's getter may have returned different data during the first check.
+    const owned = structuredClone(page);
+    assertPageBudget(owned);
+    return owned;
+}
+function assertPageCheckpoint(entries, checkpoint) {
+    if (!checkpoint)
+        return;
+    const entry = entries.find((candidate) => candidate.state.version === checkpoint.version);
+    if (entry && entry.state.stateHash !== checkpoint.stateHash)
+        throwVerification("equivocation", "principal history conflicts with the local checkpoint");
+}
+export async function verifyPrincipalHistoryPage(input) {
+    const owned = ownPage(input.page);
+    const signerKeys = await buildPrincipalPolicySignerKeyMap(owned.signerPublicKeys);
+    const authority = createPrincipalPolicyExternalAuthorityVerifier({
+        authority: owned.externalAuthority,
+    });
+    authority.latestReference = input.latestAuthority;
+    let previous = input.previous;
+    const entries = [];
+    for (const entry of owned.entries) {
+        const current = await normalizePrincipalPolicyStateChainEntry(entry);
+        verifyPrincipalPolicyChainEntryIdentity({
+            currentState: {
+                principalId: input.principalId,
+                principalType: input.principalType,
+            },
+            expectedVersion: (previous?.state.version ?? 0) + 1,
+            normalizedEntry: current,
+        });
+        if (previous)
+            verifySuccessorPrincipalPolicyChainEntry({
+                authorityVerifier: authority,
+                normalizedEntry: current,
+                previousEntry: previous,
+            });
+        else
+            verifyInitialPrincipalPolicyChainEntry({
+                authorityVerifier: authority,
+                normalizedEntry: current,
+            });
+        verifyPrincipalPolicyExternalAuthorityProgress({
+            entry: current,
+            verifier: authority,
+        });
+        if (input.references.some((reference) => reference.version === current.state.version &&
+            !principalPolicyStateMatchesReference(current.state, reference)))
+            throwVerification("hash_mismatch", "principal history reference mismatch");
+        entries.push(current);
+        previous = current;
+    }
+    await verifyPrincipalPolicyChainSignatures({
+        chain: entries,
+        signerPublicKeyByUserAndFingerprint: signerKeys,
+    });
+    assertPageCheckpoint(entries, input.checkpoint);
+    if (!previous)
+        throwVerification("missing_dependency", "principal history page is empty");
+    return {
+        entries,
+        last: previous,
+        latestAuthority: authority.latestReference,
+    };
+}
+//# sourceMappingURL=principalPolicyHistoryPage.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyHistoryPage.js","sourceRoot":"","sources":["principalPolicyHistoryPage.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PrincipalStateExternalAuthority } from \"../principalState\";\nimport {\n  normalizePrincipalPolicyStateChainEntry,\n  verifyInitialPrincipalPolicyChainEntry,\n  verifyPrincipalPolicyChainEntryIdentity,\n  verifySuccessorPrincipalPolicyChainEntry,\n} from \"./principalPolicyChainEntry\";\nimport {\n  createPrincipalPolicyExternalAuthorityVerifier,\n  verifyPrincipalPolicyExternalAuthorityProgress,\n} from \"./principalPolicyExternalAuthority\";\nimport {\n  PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT,\n  type PrincipalPolicyHistoryPage,\n} from \"./principalPolicyHistoryTypes\";\nimport { principalPolicyStateMatchesReference } from \"./principalPolicyReference\";\nimport { verifyPrincipalPolicyChainSignatures } from \"./principalPolicySignatures\";\nimport { buildPrincipalPolicySignerKeyMap } from \"./principalPolicySignerKeys\";\nimport { throwVerification } from \"./shared\";\nimport type {\n  NormalizedPrincipalPolicyStateChainEntry,\n  PrincipalPolicyCheckpoint,\n  ReferencedPrincipalHead,\n} from \"./types\";\n\n// Bump when page, chain, signer, or external-authority verification tightens.\n// Authenticated saved progress must then re-verify its omitted prefix.\nexport const PRINCIPAL_HISTORY_VERIFICATION_REVISION = 2;\n\nfunction assertPageBudget(page: PrincipalPolicyHistoryPage): void {\n  if (\n    page.entries.length < 1 ||\n    page.entries.length > PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT ||\n    page.signerPublicKeys.length > PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT ||\n    (page.externalAuthority?.states.length ?? 0) >\n      PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT + 1\n  )\n    throwVerification(\n      \"invalid_shape\",\n      \"principal history page exceeds its entry budget\",\n    );\n}\n\nfunction ownPage(page: PrincipalPolicyHistoryPage): PrincipalPolicyHistoryPage {\n  assertPageBudget(page);\n  // Own bytes before yielding, then bind the budget to those same bytes: a\n  // caller's getter may have returned different data during the first check.\n  const owned = structuredClone(page);\n  assertPageBudget(owned);\n  return owned;\n}\n\nfunction assertPageCheckpoint(\n  entries: readonly NormalizedPrincipalPolicyStateChainEntry[],\n  checkpoint: PrincipalPolicyCheckpoint | null,\n): void {\n  if (!checkpoint) return;\n  const entry = entries.find(\n    (candidate) => candidate.state.version === checkpoint.version,\n  );\n  if (entry && entry.state.stateHash !== checkpoint.stateHash)\n    throwVerification(\n      \"equivocation\",\n      \"principal history conflicts with the local checkpoint\",\n    );\n}\n\nexport async function verifyPrincipalHistoryPage(input: {\n  readonly page: PrincipalPolicyHistoryPage;\n  readonly principalId: string;\n  readonly principalType: ReferencedPrincipalHead[\"principalType\"];\n  readonly previous: NormalizedPrincipalPolicyStateChainEntry | undefined;\n  readonly latestAuthority: PrincipalStateExternalAuthority | null;\n  readonly references: readonly ReferencedPrincipalHead[];\n  readonly checkpoint: PrincipalPolicyCheckpoint | null;\n}) {\n  const owned = ownPage(input.page);\n  const signerKeys = await buildPrincipalPolicySignerKeyMap(\n    owned.signerPublicKeys,\n  );\n  const authority = createPrincipalPolicyExternalAuthorityVerifier({\n    authority: owned.externalAuthority,\n  });\n  authority.latestReference = input.latestAuthority;\n  let previous = input.previous;\n  const entries: NormalizedPrincipalPolicyStateChainEntry[] = [];\n  for (const entry of owned.entries) {\n    const current = await normalizePrincipalPolicyStateChainEntry(entry);\n    verifyPrincipalPolicyChainEntryIdentity({\n      currentState: {\n        principalId: input.principalId,\n        principalType: input.principalType,\n      },\n      expectedVersion: (previous?.state.version ?? 0) + 1,\n      normalizedEntry: current,\n    });\n    if (previous)\n      verifySuccessorPrincipalPolicyChainEntry({\n        authorityVerifier: authority,\n        normalizedEntry: current,\n        previousEntry: previous,\n      });\n    else\n      verifyInitialPrincipalPolicyChainEntry({\n        authorityVerifier: authority,\n        normalizedEntry: current,\n      });\n    verifyPrincipalPolicyExternalAuthorityProgress({\n      entry: current,\n      verifier: authority,\n    });\n    if (\n      input.references.some(\n        (reference) =>\n          reference.version === current.state.version &&\n          !principalPolicyStateMatchesReference(current.state, reference),\n      )\n    )\n      throwVerification(\n        \"hash_mismatch\",\n        \"principal history reference mismatch\",\n      );\n    entries.push(current);\n    previous = current;\n  }\n  await verifyPrincipalPolicyChainSignatures({\n    chain: entries,\n    signerPublicKeyByUserAndFingerprint: signerKeys,\n  });\n  assertPageCheckpoint(entries, input.checkpoint);\n  if (!previous)\n    throwVerification(\"missing_dependency\", \"principal history page is empty\");\n  return {\n    entries,\n    last: previous,\n    latestAuthority: authority.latestReference,\n  };\n}\n"]}

package/internal/crypto/keying/principalPolicyHistoryProgress.js

@@ -0,0 +1,90 @@
+import { normalizeReferencedPrincipalHead } from "./accessEvent.js";
+import { normalizePrincipalHistoryIndexFrontier, principalHistoryIndexLeaf, principalHistoryIndexRoot, } from "./principalPolicyHistoryIndex.js";
+import { normalizeAuthenticatedPrincipalHistoryEntry } from "./principalPolicyHistoryProgressEntry.js";
+import { PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT } from "./principalPolicyHistoryTypes.js";
+import { principalPolicyStateMatchesReference } from "./principalPolicyReference.js";
+import { assertExactKeys, readNullableHashString, throwVerification, } from "./shared.js";
+export async function normalizeAuthenticatedPrincipalHistoryProgress(value, input) {
+    const record = assertExactKeys(value, [
+        "previous",
+        "latestAuthority",
+        "checkpointHash",
+        "retained",
+        "indexFrontier",
+    ], "principal history progress");
+    if (!Array.isArray(record.retained) ||
+        record.retained.length >
+            PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT + (input.checkpoint ? 1 : 0))
+        throwVerification("invalid_shape", "invalid retained principal progress");
+    const previous = record.previous === null
+        ? null
+        : await normalizeAuthenticatedPrincipalHistoryEntry(record.previous);
+    const checkpointHash = readNullableHashString(record, "checkpointHash", "principal history progress");
+    const authority = record.latestAuthority === null
+        ? null
+        : normalizeReferencedPrincipalHead(record.latestAuthority);
+    if (authority && authority.principalType !== "group")
+        throwVerification("invalid_shape", "invalid saved principal authority");
+    const latestAuthority = authority
+        ? { ...authority, principalType: "group" }
+        : null;
+    const retained = [];
+    for (const entry of record.retained)
+        retained.push(await normalizeAuthenticatedPrincipalHistoryEntry(entry));
+    const indexFrontier = normalizePrincipalHistoryIndexFrontier(record.indexFrontier, previous?.state.version ?? 0);
+    const progress = {
+        previous,
+        latestAuthority,
+        checkpointHash,
+        retained,
+        indexFrontier,
+        indexRootHash: await principalHistoryIndexRoot(indexFrontier),
+    };
+    assertProgressConsistency(progress, input);
+    assertRetainedReferences(progress, input);
+    // Authentication binds the omitted prefix. An odd-sized frontier also
+    // exposes its last leaf, so check that local structural link explicitly.
+    if (previous &&
+        previous.state.version % 2 === 1 &&
+        indexFrontier[0] !== (await principalHistoryIndexLeaf(previous.state)))
+        throwVerification("hash_mismatch", "saved principal frontier does not contain its last entry");
+    return progress;
+}
+function assertProgressConsistency(progress, input) {
+    const { previous, latestAuthority, checkpointHash, retained } = progress;
+    const entries = previous ? [...retained, previous] : retained;
+    if (entries.some((entry) => entry.state.principalId !== input.principalId ||
+        entry.state.principalType !== input.principalType))
+        throwVerification("object_mismatch", "saved principal history scope mismatch");
+    if (!previous && (latestAuthority || checkpointHash || retained.length > 0))
+        throwVerification("invalid_shape", "empty principal progress carries history");
+    if (previous?.state.externalAuthority &&
+        (!latestAuthority ||
+            !principalPolicyStateMatchesReference(previous.state.externalAuthority, latestAuthority)))
+        throwVerification("invalid_shape", "saved principal authority is inconsistent");
+    const expectedCheckpointHash = previous &&
+        input.checkpoint &&
+        previous.state.version >= input.checkpoint.version
+        ? input.checkpoint.stateHash
+        : null;
+    if (checkpointHash !== expectedCheckpointHash)
+        throwVerification("stale_predecessor", "saved principal checkpoint is inconsistent");
+}
+function assertRetainedReferences(progress, input) {
+    const { previous, retained } = progress;
+    const expectedReferences = input.references.filter((reference) => reference.version <= (previous?.state.version ?? 0));
+    const checkpoint = input.checkpoint &&
+        input.checkpoint.version <= (previous?.state.version ?? 0)
+        ? input.checkpoint
+        : null;
+    const expectedVersions = new Set(expectedReferences.map(({ version }) => version));
+    if (checkpoint)
+        expectedVersions.add(checkpoint.version);
+    if (retained.length !== expectedVersions.size ||
+        (checkpoint !== null &&
+            retained.filter(({ state }) => state.version === checkpoint.version &&
+                state.stateHash === checkpoint.stateHash).length !== 1) ||
+        expectedReferences.some((reference) => retained.filter((entry) => principalPolicyStateMatchesReference(entry.state, reference)).length !== 1))
+        throwVerification("missing_dependency", "saved principal references are incomplete");
+}
+//# sourceMappingURL=principalPolicyHistoryProgress.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyHistoryProgress.js","sourceRoot":"","sources":["principalPolicyHistoryProgress.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PrincipalStateExternalAuthority } from \"../principalState\";\nimport { normalizeReferencedPrincipalHead } from \"./accessEvent\";\nimport type { normalizePrincipalHistoryInput } from \"./principalPolicyHistoryChecks\";\nimport {\n  normalizePrincipalHistoryIndexFrontier,\n  principalHistoryIndexLeaf,\n  principalHistoryIndexRoot,\n} from \"./principalPolicyHistoryIndex\";\nimport { normalizeAuthenticatedPrincipalHistoryEntry } from \"./principalPolicyHistoryProgressEntry\";\nimport { PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT } from \"./principalPolicyHistoryTypes\";\nimport { principalPolicyStateMatchesReference } from \"./principalPolicyReference\";\nimport {\n  assertExactKeys,\n  readNullableHashString,\n  throwVerification,\n} from \"./shared\";\nimport type { NormalizedPrincipalPolicyStateChainEntry } from \"./types\";\n\nexport interface PrincipalHistoryProgress {\n  readonly indexFrontier: readonly (string | null)[];\n  readonly indexRootHash: string | null;\n  readonly previous: NormalizedPrincipalPolicyStateChainEntry | null;\n  readonly latestAuthority: PrincipalStateExternalAuthority | null;\n  readonly checkpointHash: string | null;\n  readonly retained: readonly NormalizedPrincipalPolicyStateChainEntry[];\n}\n\nexport async function normalizeAuthenticatedPrincipalHistoryProgress(\n  value: unknown,\n  input: ReturnType<typeof normalizePrincipalHistoryInput>,\n): Promise<PrincipalHistoryProgress> {\n  const record = assertExactKeys(\n    value,\n    [\n      \"previous\",\n      \"latestAuthority\",\n      \"checkpointHash\",\n      \"retained\",\n      \"indexFrontier\",\n    ],\n    \"principal history progress\",\n  );\n  if (\n    !Array.isArray(record.retained) ||\n    record.retained.length >\n      PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT + (input.checkpoint ? 1 : 0)\n  )\n    throwVerification(\"invalid_shape\", \"invalid retained principal progress\");\n  const previous =\n    record.previous === null\n      ? null\n      : await normalizeAuthenticatedPrincipalHistoryEntry(record.previous);\n  const checkpointHash = readNullableHashString(\n    record,\n    \"checkpointHash\",\n    \"principal history progress\",\n  );\n  const authority =\n    record.latestAuthority === null\n      ? null\n      : normalizeReferencedPrincipalHead(record.latestAuthority);\n  if (authority && authority.principalType !== \"group\")\n    throwVerification(\"invalid_shape\", \"invalid saved principal authority\");\n  const latestAuthority: PrincipalStateExternalAuthority | null = authority\n    ? { ...authority, principalType: \"group\" }\n    : null;\n  const retained: NormalizedPrincipalPolicyStateChainEntry[] = [];\n  for (const entry of record.retained)\n    retained.push(await normalizeAuthenticatedPrincipalHistoryEntry(entry));\n  const indexFrontier = normalizePrincipalHistoryIndexFrontier(\n    record.indexFrontier,\n    previous?.state.version ?? 0,\n  );\n  const progress = {\n    previous,\n    latestAuthority,\n    checkpointHash,\n    retained,\n    indexFrontier,\n    indexRootHash: await principalHistoryIndexRoot(indexFrontier),\n  };\n  assertProgressConsistency(progress, input);\n  assertRetainedReferences(progress, input);\n  // Authentication binds the omitted prefix. An odd-sized frontier also\n  // exposes its last leaf, so check that local structural link explicitly.\n  if (\n    previous &&\n    previous.state.version % 2 === 1 &&\n    indexFrontier[0] !== (await principalHistoryIndexLeaf(previous.state))\n  )\n    throwVerification(\n      \"hash_mismatch\",\n      \"saved principal frontier does not contain its last entry\",\n    );\n  return progress;\n}\n\nfunction assertProgressConsistency(\n  progress: PrincipalHistoryProgress,\n  input: ReturnType<typeof normalizePrincipalHistoryInput>,\n): void {\n  const { previous, latestAuthority, checkpointHash, retained } = progress;\n  const entries = previous ? [...retained, previous] : retained;\n  if (\n    entries.some(\n      (entry) =>\n        entry.state.principalId !== input.principalId ||\n        entry.state.principalType !== input.principalType,\n    )\n  )\n    throwVerification(\n      \"object_mismatch\",\n      \"saved principal history scope mismatch\",\n    );\n  if (!previous && (latestAuthority || checkpointHash || retained.length > 0))\n    throwVerification(\n      \"invalid_shape\",\n      \"empty principal progress carries history\",\n    );\n  if (\n    previous?.state.externalAuthority &&\n    (!latestAuthority ||\n      !principalPolicyStateMatchesReference(\n        previous.state.externalAuthority,\n        latestAuthority,\n      ))\n  )\n    throwVerification(\n      \"invalid_shape\",\n      \"saved principal authority is inconsistent\",\n    );\n  const expectedCheckpointHash =\n    previous &&\n    input.checkpoint &&\n    previous.state.version >= input.checkpoint.version\n      ? input.checkpoint.stateHash\n      : null;\n  if (checkpointHash !== expectedCheckpointHash)\n    throwVerification(\n      \"stale_predecessor\",\n      \"saved principal checkpoint is inconsistent\",\n    );\n}\n\nfunction assertRetainedReferences(\n  progress: PrincipalHistoryProgress,\n  input: ReturnType<typeof normalizePrincipalHistoryInput>,\n): void {\n  const { previous, retained } = progress;\n  const expectedReferences = input.references.filter(\n    (reference) => reference.version <= (previous?.state.version ?? 0),\n  );\n  const checkpoint =\n    input.checkpoint &&\n    input.checkpoint.version <= (previous?.state.version ?? 0)\n      ? input.checkpoint\n      : null;\n  const expectedVersions = new Set(\n    expectedReferences.map(({ version }) => version),\n  );\n  if (checkpoint) expectedVersions.add(checkpoint.version);\n  if (\n    retained.length !== expectedVersions.size ||\n    (checkpoint !== null &&\n      retained.filter(\n        ({ state }) =>\n          state.version === checkpoint.version &&\n          state.stateHash === checkpoint.stateHash,\n      ).length !== 1) ||\n    expectedReferences.some(\n      (reference) =>\n        retained.filter((entry) =>\n          principalPolicyStateMatchesReference(entry.state, reference),\n        ).length !== 1,\n    )\n  )\n    throwVerification(\n      \"missing_dependency\",\n      \"saved principal references are incomplete\",\n    );\n}\n"]}

package/internal/crypto/keying/principalPolicyHistoryProgressEntry.js

@@ -0,0 +1,107 @@
+import { isPlainObject } from "../../validators/isPlainObject.js";
+import { isPrincipalProjectionRole, toUnsignedPrincipalState, } from "../principalState.js";
+import { normalizePrincipalPolicyStateChainEntry } from "./principalPolicyChainEntry.js";
+import { assertExactKeys, throwVerification } from "./shared.js";
+export function capturePrincipalHistoryAuthority(authority) {
+    return {
+        principalType: authority.principalType,
+        principalId: authority.principalId,
+        version: authority.version,
+        keyEpoch: authority.keyEpoch,
+        stateHash: authority.stateHash,
+        keyFingerprint: authority.keyFingerprint,
+    };
+}
+/** Persist protocol fields only; caller metadata is not signed history. */
+export function capturePrincipalHistoryProgressEntry(entry) {
+    const { state } = entry;
+    return {
+        state: {
+            ...toUnsignedPrincipalState(state),
+            externalAuthority: state.externalAuthority
+                ? capturePrincipalHistoryAuthority(state.externalAuthority)
+                : null,
+            signature: state.signature,
+            stateHash: state.stateHash,
+        },
+        projection: entry.projection.map(({ userId, role }) => ({ userId, role })),
+        grants: entry.grants.map(({ containerId, accessLevel }) => ({
+            containerId,
+            accessLevel,
+        })),
+    };
+}
+function isAuthority(value) {
+    if (!isPlainObject(value))
+        return false;
+    const { principalType, principalId, version, keyEpoch, stateHash, keyFingerprint, } = value;
+    return (principalType === "group" &&
+        typeof principalId === "string" &&
+        typeof version === "number" &&
+        typeof keyEpoch === "number" &&
+        typeof stateHash === "string" &&
+        typeof keyFingerprint === "string");
+}
+function isSignedState(value) {
+    if (!isPlainObject(value))
+        return false;
+    const { principalType, membershipMode, prevStateHash, externalAuthority } = value;
+    const strings = [
+        "principalId",
+        "encapsulationPublicKey",
+        "keyFingerprint",
+        "membershipRoot",
+        "memberEnvelopesRoot",
+        "projectionRoot",
+        "grantRoot",
+        "payloadCiphertextHash",
+        "signedAt",
+        "signerUserId",
+        "signerUserKeyFingerprint",
+        "signature",
+        "stateHash",
+    ];
+    const numbers = ["version", "keyEpoch", "memberCount", "grantCount"];
+    return ((principalType === "group" || principalType === "organization") &&
+        membershipMode === "projection" &&
+        (prevStateHash === null || typeof prevStateHash === "string") &&
+        (externalAuthority === null || isAuthority(externalAuthority)) &&
+        strings.every((key) => typeof value[key] === "string") &&
+        numbers.every((key) => typeof value[key] === "number"));
+}
+function isMember(value) {
+    if (!isPlainObject(value))
+        return false;
+    const { userId, role } = value;
+    return (typeof userId === "string" &&
+        typeof role === "string" &&
+        isPrincipalProjectionRole(role));
+}
+function isGrant(value) {
+    if (!isPlainObject(value))
+        return false;
+    const { containerId, accessLevel } = value;
+    return (typeof containerId === "string" &&
+        (accessLevel === "admin" ||
+            accessLevel === "read" ||
+            accessLevel === "write"));
+}
+/** Decode only after local progress authentication, then recheck commitments. */
+export function normalizeAuthenticatedPrincipalHistoryEntry(value) {
+    const entry = assertExactKeys(value, ["state", "projection", "grants"], "saved history entry");
+    if (!isSignedState(entry.state) ||
+        !Array.isArray(entry.projection) ||
+        !entry.projection.every(isMember) ||
+        !Array.isArray(entry.grants) ||
+        !entry.grants.every(isGrant))
+        throwVerification("invalid_shape", "saved principal history entry is malformed");
+    // The normalizer enforces numeric domains, signing-time format and all
+    // commitments. This cannot replace prefix verification: the local envelope
+    // is what authenticates the earlier authorization and signature checks.
+    return normalizePrincipalPolicyStateChainEntry({
+        state: entry.state,
+        projection: entry.projection,
+        grants: entry.grants,
+    });
+}
+//# sourceMappingURL=principalPolicyHistoryProgressEntry.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyHistoryProgressEntry.js","sourceRoot":"","sources":["principalPolicyHistoryProgressEntry.ts"],"names":[],"mappings":"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","sourcesContent":["import { isPlainObject } from \"@tearleads/validators/isPlainObject\";\nimport type {\n  PrincipalContainerGrant,\n  PrincipalProjectionMember,\n  PrincipalStateExternalAuthority,\n} from \"../principalState\";\nimport {\n  isPrincipalProjectionRole,\n  toUnsignedPrincipalState,\n} from \"../principalState\";\nimport { normalizePrincipalPolicyStateChainEntry } from \"./principalPolicyChainEntry\";\nimport { assertExactKeys, throwVerification } from \"./shared\";\nimport type {\n  NormalizedPrincipalPolicyStateChainEntry,\n  PrincipalPolicySignedState,\n} from \"./types\";\n\nexport function capturePrincipalHistoryAuthority(\n  authority: PrincipalStateExternalAuthority,\n) {\n  return {\n    principalType: authority.principalType,\n    principalId: authority.principalId,\n    version: authority.version,\n    keyEpoch: authority.keyEpoch,\n    stateHash: authority.stateHash,\n    keyFingerprint: authority.keyFingerprint,\n  };\n}\n\n/** Persist protocol fields only; caller metadata is not signed history. */\nexport function capturePrincipalHistoryProgressEntry(\n  entry: NormalizedPrincipalPolicyStateChainEntry,\n) {\n  const { state } = entry;\n  return {\n    state: {\n      ...toUnsignedPrincipalState(state),\n      externalAuthority: state.externalAuthority\n        ? capturePrincipalHistoryAuthority(state.externalAuthority)\n        : null,\n      signature: state.signature,\n      stateHash: state.stateHash,\n    },\n    projection: entry.projection.map(({ userId, role }) => ({ userId, role })),\n    grants: entry.grants.map(({ containerId, accessLevel }) => ({\n      containerId,\n      accessLevel,\n    })),\n  };\n}\n\nfunction isAuthority(value: unknown): value is PrincipalStateExternalAuthority {\n  if (!isPlainObject(value)) return false;\n  const {\n    principalType,\n    principalId,\n    version,\n    keyEpoch,\n    stateHash,\n    keyFingerprint,\n  } = value;\n  return (\n    principalType === \"group\" &&\n    typeof principalId === \"string\" &&\n    typeof version === \"number\" &&\n    typeof keyEpoch === \"number\" &&\n    typeof stateHash === \"string\" &&\n    typeof keyFingerprint === \"string\"\n  );\n}\n\nfunction isSignedState(value: unknown): value is PrincipalPolicySignedState {\n  if (!isPlainObject(value)) return false;\n  const { principalType, membershipMode, prevStateHash, externalAuthority } =\n    value;\n  const strings = [\n    \"principalId\",\n    \"encapsulationPublicKey\",\n    \"keyFingerprint\",\n    \"membershipRoot\",\n    \"memberEnvelopesRoot\",\n    \"projectionRoot\",\n    \"grantRoot\",\n    \"payloadCiphertextHash\",\n    \"signedAt\",\n    \"signerUserId\",\n    \"signerUserKeyFingerprint\",\n    \"signature\",\n    \"stateHash\",\n  ];\n  const numbers = [\"version\", \"keyEpoch\", \"memberCount\", \"grantCount\"];\n  return (\n    (principalType === \"group\" || principalType === \"organization\") &&\n    membershipMode === \"projection\" &&\n    (prevStateHash === null || typeof prevStateHash === \"string\") &&\n    (externalAuthority === null || isAuthority(externalAuthority)) &&\n    strings.every((key) => typeof value[key] === \"string\") &&\n    numbers.every((key) => typeof value[key] === \"number\")\n  );\n}\n\nfunction isMember(value: unknown): value is PrincipalProjectionMember {\n  if (!isPlainObject(value)) return false;\n  const { userId, role } = value;\n  return (\n    typeof userId === \"string\" &&\n    typeof role === \"string\" &&\n    isPrincipalProjectionRole(role)\n  );\n}\n\nfunction isGrant(value: unknown): value is PrincipalContainerGrant {\n  if (!isPlainObject(value)) return false;\n  const { containerId, accessLevel } = value;\n  return (\n    typeof containerId === \"string\" &&\n    (accessLevel === \"admin\" ||\n      accessLevel === \"read\" ||\n      accessLevel === \"write\")\n  );\n}\n\n/** Decode only after local progress authentication, then recheck commitments. */\nexport function normalizeAuthenticatedPrincipalHistoryEntry(value: unknown) {\n  const entry = assertExactKeys(\n    value,\n    [\"state\", \"projection\", \"grants\"],\n    \"saved history entry\",\n  );\n  if (\n    !isSignedState(entry.state) ||\n    !Array.isArray(entry.projection) ||\n    !entry.projection.every(isMember) ||\n    !Array.isArray(entry.grants) ||\n    !entry.grants.every(isGrant)\n  )\n    throwVerification(\n      \"invalid_shape\",\n      \"saved principal history entry is malformed\",\n    );\n  // The normalizer enforces numeric domains, signing-time format and all\n  // commitments. This cannot replace prefix verification: the local envelope\n  // is what authenticates the earlier authorization and signature checks.\n  return normalizePrincipalPolicyStateChainEntry({\n    state: entry.state,\n    projection: entry.projection,\n    grants: entry.grants,\n  });\n}\n"]}

package/internal/crypto/keying/principalPolicyHistoryProgressProtection.js

@@ -0,0 +1,76 @@
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { base64ToBytes, bytesToBase64 } from "../../encoding/index.js";
+import { AES_GCM_IV_BYTES, AES_GCM_TAG_BYTES, decryptWithDek, encryptWithDek, } from "../symmetric.js";
+import { normalizeCanonicalJsonValue, serializeKeyingCanonicalJson, } from "./canonical.js";
+import { PRINCIPAL_HISTORY_VERIFICATION_REVISION } from "./principalPolicyHistoryPage.js";
+import { throwVerification } from "./shared.js";
+// Format domain; accepted history rules carry the page verifier's revision.
+const DOMAIN = "tearleads.principal-policy-history-progress.v3";
+const utf8 = new TextEncoder();
+export function ownPrincipalHistoryProgressProtection(input, options, verificationRevision = PRINCIPAL_HISTORY_VERIFICATION_REVISION) {
+    const { localKey, context } = options;
+    if (!(localKey instanceof Uint8Array) ||
+        localKey.byteLength !== 32 ||
+        typeof context !== "string" ||
+        context.length === 0)
+        throwVerification("invalid_shape", "principal history progress requires a local 32-byte key and context");
+    const additionalData = utf8.encode(serializeKeyingCanonicalJson(normalizeCanonicalJsonValue([DOMAIN, verificationRevision, context, input], "principal progress protection")));
+    // Derive synchronously, before yielding to callers that own mutable buffers.
+    const ownedKey = new Uint8Array(localKey);
+    try {
+        const key = hkdf(sha256, ownedKey, utf8.encode(DOMAIN), 
+        // Separate each normalized operation/scope/revision into its own key.
+        sha256(additionalData), 32);
+        return { key, additionalData };
+    }
+    finally {
+        ownedKey.fill(0);
+    }
+}
+export async function sealPrincipalHistoryProgress(plaintext, protection) {
+    try {
+        const encrypted = await encryptWithDek(utf8.encode(plaintext), protection.key, protection.additionalData);
+        return `v3.${bytesToBase64(encrypted.iv)}.${bytesToBase64(encrypted.ciphertext)}`;
+    }
+    finally {
+        protection.key.fill(0);
+    }
+}
+function canonicalBytes(value) {
+    const bytes = base64ToBytes(value);
+    if (bytesToBase64(bytes) !== value)
+        throwVerification("invalid_shape", "noncanonical principal progress");
+    return bytes;
+}
+export async function openPrincipalHistoryProgress(progress, protection) {
+    try {
+        const [version, iv, ciphertext, extra] = progress.split(".");
+        if (version !== "v3" || !iv || !ciphertext || extra !== undefined)
+            throwVerification("invalid_shape", "invalid principal history progress");
+        const encrypted = {
+            iv: canonicalBytes(iv),
+            ciphertext: canonicalBytes(ciphertext),
+        };
+        if (encrypted.iv.length !== AES_GCM_IV_BYTES ||
+            encrypted.ciphertext.length < AES_GCM_TAG_BYTES)
+            throwVerification("invalid_shape", "invalid principal progress framing");
+        let plaintext;
+        try {
+            plaintext = await decryptWithDek(encrypted, protection.key, protection.additionalData);
+        }
+        catch {
+            throwVerification("hash_mismatch", "principal history progress authentication failed");
+        }
+        try {
+            return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(plaintext));
+        }
+        finally {
+            plaintext.fill(0);
+        }
+    }
+    finally {
+        protection.key.fill(0);
+    }
+}
+//# sourceMappingURL=principalPolicyHistoryProgressProtection.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyHistoryProgressProtection.js","sourceRoot":"","sources":["principalPolicyHistoryProgressProtection.ts"],"names":[],"mappings":"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","sourcesContent":["import { hkdf } from \"@noble/hashes/hkdf.js\";\nimport { sha256 } from \"@noble/hashes/sha2.js\";\nimport { base64ToBytes, bytesToBase64 } from \"@tearleads/encoding\";\nimport {\n  AES_GCM_IV_BYTES,\n  AES_GCM_TAG_BYTES,\n  decryptWithDek,\n  encryptWithDek,\n} from \"../symmetric\";\nimport {\n  normalizeCanonicalJsonValue,\n  serializeKeyingCanonicalJson,\n} from \"./canonical\";\nimport type { normalizePrincipalHistoryInput } from \"./principalPolicyHistoryChecks\";\nimport { PRINCIPAL_HISTORY_VERIFICATION_REVISION } from \"./principalPolicyHistoryPage\";\nimport type { PrincipalPolicyHistoryProgressOptions } from \"./principalPolicyHistoryTypes\";\nimport { throwVerification } from \"./shared\";\n\n// Format domain; accepted history rules carry the page verifier's revision.\nconst DOMAIN = \"tearleads.principal-policy-history-progress.v3\";\nconst utf8 = new TextEncoder();\n\nexport function ownPrincipalHistoryProgressProtection(\n  input: ReturnType<typeof normalizePrincipalHistoryInput>,\n  options: PrincipalPolicyHistoryProgressOptions,\n  verificationRevision = PRINCIPAL_HISTORY_VERIFICATION_REVISION,\n) {\n  const { localKey, context } = options;\n  if (\n    !(localKey instanceof Uint8Array) ||\n    localKey.byteLength !== 32 ||\n    typeof context !== \"string\" ||\n    context.length === 0\n  )\n    throwVerification(\n      \"invalid_shape\",\n      \"principal history progress requires a local 32-byte key and context\",\n    );\n  const additionalData = utf8.encode(\n    serializeKeyingCanonicalJson(\n      normalizeCanonicalJsonValue(\n        [DOMAIN, verificationRevision, context, input],\n        \"principal progress protection\",\n      ),\n    ),\n  );\n  // Derive synchronously, before yielding to callers that own mutable buffers.\n  const ownedKey = new Uint8Array(localKey);\n  try {\n    const key = hkdf(\n      sha256,\n      ownedKey,\n      utf8.encode(DOMAIN),\n      // Separate each normalized operation/scope/revision into its own key.\n      sha256(additionalData),\n      32,\n    );\n    return { key, additionalData };\n  } finally {\n    ownedKey.fill(0);\n  }\n}\n\ntype Protection = ReturnType<typeof ownPrincipalHistoryProgressProtection>;\n\nexport async function sealPrincipalHistoryProgress(\n  plaintext: string,\n  protection: Protection,\n): Promise<string> {\n  try {\n    const encrypted = await encryptWithDek(\n      utf8.encode(plaintext),\n      protection.key,\n      protection.additionalData,\n    );\n    return `v3.${bytesToBase64(encrypted.iv)}.${bytesToBase64(encrypted.ciphertext)}`;\n  } finally {\n    protection.key.fill(0);\n  }\n}\n\nfunction canonicalBytes(value: string): Uint8Array {\n  const bytes = base64ToBytes(value);\n  if (bytesToBase64(bytes) !== value)\n    throwVerification(\"invalid_shape\", \"noncanonical principal progress\");\n  return bytes;\n}\n\nexport async function openPrincipalHistoryProgress(\n  progress: string,\n  protection: Protection,\n): Promise<unknown> {\n  try {\n    const [version, iv, ciphertext, extra] = progress.split(\".\");\n    if (version !== \"v3\" || !iv || !ciphertext || extra !== undefined)\n      throwVerification(\"invalid_shape\", \"invalid principal history progress\");\n    const encrypted = {\n      iv: canonicalBytes(iv),\n      ciphertext: canonicalBytes(ciphertext),\n    };\n    if (\n      encrypted.iv.length !== AES_GCM_IV_BYTES ||\n      encrypted.ciphertext.length < AES_GCM_TAG_BYTES\n    )\n      throwVerification(\"invalid_shape\", \"invalid principal progress framing\");\n    let plaintext: Uint8Array;\n    try {\n      plaintext = await decryptWithDek(\n        encrypted,\n        protection.key,\n        protection.additionalData,\n      );\n    } catch {\n      throwVerification(\n        \"hash_mismatch\",\n        \"principal history progress authentication failed\",\n      );\n    }\n    try {\n      return JSON.parse(\n        new TextDecoder(\"utf-8\", { fatal: true }).decode(plaintext),\n      );\n    } finally {\n      plaintext.fill(0);\n    }\n  } finally {\n    protection.key.fill(0);\n  }\n}\n"]}

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

@@ -0,0 +1,18 @@
+import { type VerifiedPrincipalPolicyHistory } from "./principalPolicyHistoryTypes.js";
+import type { KeyingVerificationResult, PrincipalPolicyStateChainEntry, ReferencedPrincipalHead, TransparencyInclusionProof } from "./types.js";
+/** Untrusted material to select an entry from a locally verified prefix. */
+export interface PrincipalPolicyHistoryReferenceProof {
+    readonly reference: ReferencedPrincipalHead;
+    readonly entry: PrincipalPolicyStateChainEntry;
+    readonly proof: TransparencyInclusionProof;
+}
+/**
+ * Select new retained references without replaying signatures. Inclusion is
+ * checked against the private root owned by a local verifier, never a peer's
+ * claimed root. Each leaf commits to the exact signed entry already accepted.
+ * Replaces the retained selection; the current entry is always included.
+ */
+export declare function verifyPrincipalPolicyHistoryReferences(input: {
+    readonly history: VerifiedPrincipalPolicyHistory;
+    readonly references: readonly PrincipalPolicyHistoryReferenceProof[];
+}): Promise<KeyingVerificationResult<VerifiedPrincipalPolicyHistory>>;

package/internal/crypto/keying/principalPolicyHistoryReferences.js

@@ -0,0 +1,64 @@
+import { normalizePrincipalPolicyStateChainEntry } from "./principalPolicyChainEntry.js";
+import { normalizePrincipalHistoryInput } from "./principalPolicyHistoryChecks.js";
+import { principalHistoryIndexLeaf } from "./principalPolicyHistoryIndex.js";
+import { makeVerifiedPrincipalPolicyHistory, ownVerifiedPrincipalPolicyHistory, PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT, } from "./principalPolicyHistoryTypes.js";
+import { principalPolicyStateMatchesReference } from "./principalPolicyReference.js";
+import { runVerifier, throwVerification } from "./shared.js";
+import { assertTransparencyInclusion, normalizeTransparencyInclusionProof, } from "./transparencyProofs.js";
+function assertProofBudget(references) {
+    if (!Array.isArray(references) ||
+        references.length > PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT)
+        throwVerification("invalid_shape", "too many principal history proofs");
+    const count = references.length;
+    for (let index = 0; index < count; index += 1) {
+        const path = references[index]?.proof.auditPath;
+        if (!Array.isArray(path) || path.length > 53)
+            throwVerification("invalid_shape", "principal history proof exceeds its budget");
+    }
+}
+/**
+ * Select new retained references without replaying signatures. Inclusion is
+ * checked against the private root owned by a local verifier, never a peer's
+ * claimed root. Each leaf commits to the exact signed entry already accepted.
+ * Replaces the retained selection; the current entry is always included.
+ */
+export function verifyPrincipalPolicyHistoryReferences(input) {
+    return runVerifier(async () => {
+        const history = ownVerifiedPrincipalPolicyHistory(input.history);
+        const supplied = input.references;
+        assertProofBudget(supplied);
+        const references = structuredClone(supplied);
+        assertProofBudget(references);
+        normalizePrincipalHistoryInput({
+            principalId: history.currentEntry.state.principalId,
+            principalType: history.currentEntry.state.principalType,
+            retainedReferences: references.map((item) => item.reference),
+        });
+        const entries = new Map();
+        const treeSize = history.currentEntry.state.version;
+        for (const item of references) {
+            const entry = await normalizePrincipalPolicyStateChainEntry(item.entry);
+            const proof = normalizeTransparencyInclusionProof(item.proof);
+            if (!principalPolicyStateMatchesReference(entry.state, item.reference) ||
+                entry.state.version > treeSize ||
+                proof.leafIndex !== entry.state.version - 1)
+                throwVerification("object_mismatch", "principal history proof reference mismatch");
+            await assertTransparencyInclusion({
+                leafHash: await principalHistoryIndexLeaf(entry.state),
+                checkpoint: {
+                    logId: "principal-history",
+                    rootHash: history.indexRootHash,
+                    treeSize,
+                },
+                proof,
+            });
+            entries.set(entry.state.version, entry);
+        }
+        entries.set(treeSize, history.currentEntry);
+        return makeVerifiedPrincipalPolicyHistory({
+            ...history,
+            retainedEntries: [...entries.values()].sort((left, right) => left.state.version - right.state.version),
+        });
+    });
+}
+//# sourceMappingURL=principalPolicyHistoryReferences.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyHistoryReferences.js","sourceRoot":"","sources":["principalPolicyHistoryReferences.ts"],"names":[],"mappings":"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","sourcesContent":["import { normalizePrincipalPolicyStateChainEntry } from \"./principalPolicyChainEntry\";\nimport { normalizePrincipalHistoryInput } from \"./principalPolicyHistoryChecks\";\nimport { principalHistoryIndexLeaf } from \"./principalPolicyHistoryIndex\";\nimport {\n  makeVerifiedPrincipalPolicyHistory,\n  ownVerifiedPrincipalPolicyHistory,\n  PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT,\n  type VerifiedPrincipalPolicyHistory,\n} from \"./principalPolicyHistoryTypes\";\nimport { principalPolicyStateMatchesReference } from \"./principalPolicyReference\";\nimport { runVerifier, throwVerification } from \"./shared\";\nimport {\n  assertTransparencyInclusion,\n  normalizeTransparencyInclusionProof,\n} from \"./transparencyProofs\";\nimport type {\n  KeyingVerificationResult,\n  PrincipalPolicyStateChainEntry,\n  ReferencedPrincipalHead,\n  TransparencyInclusionProof,\n} from \"./types\";\n\n/** Untrusted material to select an entry from a locally verified prefix. */\nexport interface PrincipalPolicyHistoryReferenceProof {\n  readonly reference: ReferencedPrincipalHead;\n  readonly entry: PrincipalPolicyStateChainEntry;\n  readonly proof: TransparencyInclusionProof;\n}\n\nfunction assertProofBudget(\n  references: readonly PrincipalPolicyHistoryReferenceProof[],\n): void {\n  if (\n    !Array.isArray(references) ||\n    references.length > PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT\n  )\n    throwVerification(\"invalid_shape\", \"too many principal history proofs\");\n  const count = references.length;\n  for (let index = 0; index < count; index += 1) {\n    const path = references[index]?.proof.auditPath;\n    if (!Array.isArray(path) || path.length > 53)\n      throwVerification(\n        \"invalid_shape\",\n        \"principal history proof exceeds its budget\",\n      );\n  }\n}\n\n/**\n * Select new retained references without replaying signatures. Inclusion is\n * checked against the private root owned by a local verifier, never a peer's\n * claimed root. Each leaf commits to the exact signed entry already accepted.\n * Replaces the retained selection; the current entry is always included.\n */\nexport function verifyPrincipalPolicyHistoryReferences(input: {\n  readonly history: VerifiedPrincipalPolicyHistory;\n  readonly references: readonly PrincipalPolicyHistoryReferenceProof[];\n}): Promise<KeyingVerificationResult<VerifiedPrincipalPolicyHistory>> {\n  return runVerifier(async () => {\n    const history = ownVerifiedPrincipalPolicyHistory(input.history);\n    const supplied = input.references;\n    assertProofBudget(supplied);\n    const references = structuredClone(supplied);\n    assertProofBudget(references);\n    normalizePrincipalHistoryInput({\n      principalId: history.currentEntry.state.principalId,\n      principalType: history.currentEntry.state.principalType,\n      retainedReferences: references.map((item) => item.reference),\n    });\n    const entries = new Map<number, PrincipalPolicyStateChainEntry>();\n    const treeSize = history.currentEntry.state.version;\n    for (const item of references) {\n      const entry = await normalizePrincipalPolicyStateChainEntry(item.entry);\n      const proof = normalizeTransparencyInclusionProof(item.proof);\n      if (\n        !principalPolicyStateMatchesReference(entry.state, item.reference) ||\n        entry.state.version > treeSize ||\n        proof.leafIndex !== entry.state.version - 1\n      )\n        throwVerification(\n          \"object_mismatch\",\n          \"principal history proof reference mismatch\",\n        );\n      await assertTransparencyInclusion({\n        leafHash: await principalHistoryIndexLeaf(entry.state),\n        checkpoint: {\n          logId: \"principal-history\",\n          rootHash: history.indexRootHash,\n          treeSize,\n        },\n        proof,\n      });\n      entries.set(entry.state.version, entry);\n    }\n    entries.set(treeSize, history.currentEntry);\n    return makeVerifiedPrincipalPolicyHistory({\n      ...history,\n      retainedEntries: [...entries.values()].sort(\n        (left, right) => left.state.version - right.state.version,\n      ),\n    });\n  });\n}\n"]}