@tearleads/client-sdk 0.0.0-stage → 0.1.13

package/workflows/principals/principalHistoryRecoveryPrefix.js

@@ -0,0 +1,65 @@
+import { restorePrincipalPolicyHistoryVerifier, serializeKeyingCanonicalJson, } from "../../internal/crypto/index.js";
+import { isReferencedPrincipalStateResponse } from "../../internal/validators/response/index.js";
+import { discardPrincipalHistoryPrefix, loadPrincipalHistoryPrefix, savePrincipalHistoryPrefix, } from "../../data/persistence/principalHistoryPrefixPersistence.js";
+import { principalHistoryPrefixProtection } from "../../data/principals/principalHistoryPrefixProtection.js";
+import { parsePrincipalHistoryStageCurrent } from "../../data/principals/principalHistoryStageProtection.js";
+export async function loadVerifiedPrincipalHistoryPrefix(options, historyInput, scopeId) {
+    const saved = await loadPrincipalHistoryPrefix(options.execSql, scopeId);
+    if (!saved)
+        return null;
+    let head;
+    try {
+        head = JSON.parse(saved.headJson);
+    }
+    catch {
+        head = null;
+    }
+    if (saved.organizationId === options.organizationId &&
+        isReferencedPrincipalStateResponse(head) &&
+        head.principalType === historyInput.principalType &&
+        head.principalId === historyInput.principalId &&
+        head.version === saved.version) {
+        const restored = await restorePrincipalPolicyHistoryVerifier(historyInput, saved.progress, await principalHistoryPrefixProtection(options.protection, saved));
+        const current = parsePrincipalHistoryStageCurrent({
+            currentJson: saved.currentJson,
+            afterVersion: saved.version - 1,
+        });
+        if (restored.ok && restored.value.finish(head).ok && current)
+            return { verifier: restored.value, head, current };
+    }
+    await discardPrincipalHistoryPrefix({
+        execSql: options.execSql,
+        prefix: saved,
+        stillCurrent: () => !options.signal?.aborted && options.stillCurrent(),
+    });
+    return null;
+}
+export async function restoreReusablePrincipalHistoryPrefix(options, historyInput, scopeId) {
+    const prefix = await loadVerifiedPrincipalHistoryPrefix(options, historyInput, scopeId);
+    if (!prefix || prefix.head.version > options.expectedHead.version)
+        return null;
+    if (prefix.head.version < options.expectedHead.version ||
+        prefix.verifier.finish(options.expectedHead).ok)
+        return { ...prefix, version: prefix.head.version };
+    // An incompatible target cannot erase an independently valid local hint.
+    return null;
+}
+/** The verifier must use stable empty selection/checkpoint inputs. */
+export async function publishReusablePrincipalHistoryPrefix(options, scopeId, verifier, current) {
+    const prefix = {
+        scopeId,
+        organizationId: options.organizationId,
+        version: options.expectedHead.version,
+        headJson: serializeKeyingCanonicalJson({ ...options.expectedHead }),
+        currentJson: JSON.stringify(current),
+    };
+    const sealed = await verifier.exportProgress(await principalHistoryPrefixProtection(options.protection, prefix));
+    if (!sealed.ok)
+        throw sealed.error;
+    await savePrincipalHistoryPrefix({
+        execSql: options.execSql,
+        prefix: { ...prefix, progress: sealed.value },
+        stillCurrent: () => !options.signal?.aborted && options.stillCurrent(),
+    });
+}
+//# sourceMappingURL=principalHistoryRecoveryPrefix.js.map

package/workflows/principals/principalHistoryRecoveryPrefix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalHistoryRecoveryPrefix.js","sourceRoot":"","sources":["principalHistoryRecoveryPrefix.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PrincipalPolicyPageCurrent } from \"@tearleads/api-client\";\nimport {\n  type PrincipalPolicyHistoryInput,\n  type PrincipalPolicyHistoryVerifier,\n  type ReferencedPrincipalHead,\n  restorePrincipalPolicyHistoryVerifier,\n  serializeKeyingCanonicalJson,\n} from \"@tearleads/crypto\";\nimport { isReferencedPrincipalStateResponse } from \"@tearleads/validators/response\";\nimport {\n  discardPrincipalHistoryPrefix,\n  loadPrincipalHistoryPrefix,\n  savePrincipalHistoryPrefix,\n} from \"../../data/persistence/principalHistoryPrefixPersistence\";\nimport { principalHistoryPrefixProtection } from \"../../data/principals/principalHistoryPrefixProtection\";\nimport { parsePrincipalHistoryStageCurrent } from \"../../data/principals/principalHistoryStageProtection\";\nimport type { RecoverPrincipalPolicyHistoryOptions } from \"./principalHistoryRecoveryTypes\";\n\nexport async function loadVerifiedPrincipalHistoryPrefix(\n  options: Omit<RecoverPrincipalPolicyHistoryOptions, \"expectedHead\">,\n  historyInput: PrincipalPolicyHistoryInput,\n  scopeId: string,\n): Promise<{\n  verifier: PrincipalPolicyHistoryVerifier;\n  head: ReferencedPrincipalHead;\n  current: PrincipalPolicyPageCurrent;\n} | null> {\n  const saved = await loadPrincipalHistoryPrefix(options.execSql, scopeId);\n  if (!saved) return null;\n  let head: unknown;\n  try {\n    head = JSON.parse(saved.headJson);\n  } catch {\n    head = null;\n  }\n  if (\n    saved.organizationId === options.organizationId &&\n    isReferencedPrincipalStateResponse(head) &&\n    head.principalType === historyInput.principalType &&\n    head.principalId === historyInput.principalId &&\n    head.version === saved.version\n  ) {\n    const restored = await restorePrincipalPolicyHistoryVerifier(\n      historyInput,\n      saved.progress,\n      await principalHistoryPrefixProtection(options.protection, saved),\n    );\n    const current = parsePrincipalHistoryStageCurrent({\n      currentJson: saved.currentJson,\n      afterVersion: saved.version - 1,\n    });\n    if (restored.ok && restored.value.finish(head).ok && current)\n      return { verifier: restored.value, head, current };\n  }\n  await discardPrincipalHistoryPrefix({\n    execSql: options.execSql,\n    prefix: saved,\n    stillCurrent: () => !options.signal?.aborted && options.stillCurrent(),\n  });\n  return null;\n}\n\nexport async function restoreReusablePrincipalHistoryPrefix(\n  options: RecoverPrincipalPolicyHistoryOptions,\n  historyInput: PrincipalPolicyHistoryInput,\n  scopeId: string,\n) {\n  const prefix = await loadVerifiedPrincipalHistoryPrefix(\n    options,\n    historyInput,\n    scopeId,\n  );\n  if (!prefix || prefix.head.version > options.expectedHead.version)\n    return null;\n  if (\n    prefix.head.version < options.expectedHead.version ||\n    prefix.verifier.finish(options.expectedHead).ok\n  )\n    return { ...prefix, version: prefix.head.version };\n  // An incompatible target cannot erase an independently valid local hint.\n  return null;\n}\n\n/** The verifier must use stable empty selection/checkpoint inputs. */\nexport async function publishReusablePrincipalHistoryPrefix(\n  options: RecoverPrincipalPolicyHistoryOptions,\n  scopeId: string,\n  verifier: PrincipalPolicyHistoryVerifier,\n  current: PrincipalPolicyPageCurrent,\n): Promise<void> {\n  const prefix = {\n    scopeId,\n    organizationId: options.organizationId,\n    version: options.expectedHead.version,\n    headJson: serializeKeyingCanonicalJson({ ...options.expectedHead }),\n    currentJson: JSON.stringify(current),\n  };\n  const sealed = await verifier.exportProgress(\n    await principalHistoryPrefixProtection(options.protection, prefix),\n  );\n  if (!sealed.ok) throw sealed.error;\n  await savePrincipalHistoryPrefix({\n    execSql: options.execSql,\n    prefix: { ...prefix, progress: sealed.value },\n    stillCurrent: () => !options.signal?.aborted && options.stillCurrent(),\n  });\n}\n"]}

package/workflows/principals/principalHistoryRecoveryReferences.js

@@ -0,0 +1,60 @@
+import { KeyingVerificationError, verifyPrincipalPolicyHistoryReferences, } from "../../internal/crypto/index.js";
+import { assertProjectionVerificationCurrent } from "../../data/keyingProjectionVerification/types.js";
+import { loadPrincipalHistoryReference } from "../../data/persistence/principalHistoryEvidencePersistence.js";
+import { principalHeadMatchesReference } from "../../data/principals/organizationAuthorityDescriptor.js";
+export class PrincipalHistoryEvidenceUnavailableError extends Error {
+    verificationError;
+    constructor(verificationError) {
+        super(verificationError.message);
+        this.verificationError = verificationError;
+        this.name = "PrincipalHistoryEvidenceUnavailableError";
+    }
+}
+async function selectReferences(input) {
+    const { options, scopeId, history } = input;
+    const current = () => !options.signal?.aborted && options.stillCurrent();
+    const base = { execSql: options.execSql, scopeId, history };
+    const references = [];
+    for (const reference of options.retainedReferences ?? []) {
+        assertProjectionVerificationCurrent(current);
+        references.push(await loadPrincipalHistoryReference({
+            ...base,
+            version: reference.version,
+        }));
+    }
+    assertProjectionVerificationCurrent(current);
+    const checkpointReference = input.checkpoint
+        ? await loadPrincipalHistoryReference({
+            ...base,
+            version: input.checkpoint.version,
+        })
+        : undefined;
+    const selected = await verifyPrincipalPolicyHistoryReferences({
+        history,
+        references,
+        checkpointReference,
+    });
+    if (!selected.ok)
+        throw selected.error;
+    assertProjectionVerificationCurrent(current);
+    return selected.value;
+}
+export async function selectRecoveredPrincipalHistory(input) {
+    let selected;
+    try {
+        selected = await selectReferences(input);
+    }
+    catch (error) {
+        if (error instanceof KeyingVerificationError)
+            throw new PrincipalHistoryEvidenceUnavailableError(error);
+        throw error;
+    }
+    // First authenticate the stored entry against the private root. Only then
+    // compare the caller's citation, so a bad request is not treated as cache loss.
+    for (const reference of input.options.retainedReferences ?? []) {
+        if (!selected.retainedEntries.some(({ state }) => principalHeadMatchesReference(state, reference)))
+            throw new KeyingVerificationError("object_mismatch", "Requested citation does not match the verified principal history");
+    }
+    return selected;
+}
+//# sourceMappingURL=principalHistoryRecoveryReferences.js.map

package/workflows/principals/principalHistoryRecoveryReferences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalHistoryRecoveryReferences.js","sourceRoot":"","sources":["principalHistoryRecoveryReferences.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EAIvB,sCAAsC,GACvC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mCAAmC,EAAE,MAAM,+CAA+C,CAAC;AACpG,OAAO,EAAE,6BAA6B,EAAE,MAAM,4DAA4D,CAAC;AAC3G,OAAO,EAAE,6BAA6B,EAAE,MAAM,uDAAuD,CAAC;AAGtG,MAAM,OAAO,wCAAyC,SAAQ,KAAK;IAC5C;IAArB,YAAqB,iBAA0C;QAC7D,KAAK,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;QADd,sBAAiB,GAAjB,iBAAiB,CAAyB;QAE7D,IAAI,CAAC,IAAI,GAAG,0CAA0C,CAAC;IACzD,CAAC;CACF;AAED,KAAK,UAAU,gBAAgB,CAAC,KAK/B;IACC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAC5C,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IACzE,MAAM,IAAI,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAC5D,MAAM,UAAU,GAA2C,EAAE,CAAC;IAC9D,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,kBAAkB,IAAI,EAAE,EAAE,CAAC;QACzD,mCAAmC,CAAC,OAAO,CAAC,CAAC;QAC7C,UAAU,CAAC,IAAI,CACb,MAAM,6BAA6B,CAAC;YAClC,GAAG,IAAI;YACP,OAAO,EAAE,SAAS,CAAC,OAAO;SAC3B,CAAC,CACH,CAAC;IACJ,CAAC;IACD,mCAAmC,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,mBAAmB,GAAG,KAAK,CAAC,UAAU;QAC1C,CAAC,CAAC,MAAM,6BAA6B,CAAC;YAClC,GAAG,IAAI;YACP,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,OAAO;SAClC,CAAC;QACJ,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,QAAQ,GAAG,MAAM,sCAAsC,CAAC;QAC5D,OAAO;QACP,UAAU;QACV,mBAAmB;KACpB,CAAC,CAAC;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,MAAM,QAAQ,CAAC,KAAK,CAAC;IACvC,mCAAmC,CAAC,OAAO,CAAC,CAAC;IAC7C,OAAO,QAAQ,CAAC,KAAK,CAAC;AACxB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,+BAA+B,CACnD,KAA6C;IAE7C,IAAI,QAAwC,CAAC;IAC7C,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,uBAAuB;YAC1C,MAAM,IAAI,wCAAwC,CAAC,KAAK,CAAC,CAAC;QAC5D,MAAM,KAAK,CAAC;IACd,CAAC;IACD,0EAA0E;IAC1E,gFAAgF;IAChF,KAAK,MAAM,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,kBAAkB,IAAI,EAAE,EAAE,CAAC;QAC/D,IACE,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAC3C,6BAA6B,CAAC,KAAK,EAAE,SAAS,CAAC,CAChD;YAED,MAAM,IAAI,uBAAuB,CAC/B,iBAAiB,EACjB,kEAAkE,CACnE,CAAC;IACN,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["import {\n  KeyingVerificationError,\n  type PrincipalPolicyCheckpoint,\n  type PrincipalPolicyHistoryReferenceProof,\n  type VerifiedPrincipalPolicyHistory,\n  verifyPrincipalPolicyHistoryReferences,\n} from \"@tearleads/crypto\";\nimport { assertProjectionVerificationCurrent } from \"../../data/keyingProjectionVerification/types\";\nimport { loadPrincipalHistoryReference } from \"../../data/persistence/principalHistoryEvidencePersistence\";\nimport { principalHeadMatchesReference } from \"../../data/principals/organizationAuthorityDescriptor\";\nimport type { RecoverPrincipalPolicyHistoryOptions } from \"./principalHistoryRecoveryTypes\";\n\nexport class PrincipalHistoryEvidenceUnavailableError extends Error {\n  constructor(readonly verificationError: KeyingVerificationError) {\n    super(verificationError.message);\n    this.name = \"PrincipalHistoryEvidenceUnavailableError\";\n  }\n}\n\nasync function selectReferences(input: {\n  readonly options: RecoverPrincipalPolicyHistoryOptions;\n  readonly scopeId: string;\n  readonly history: VerifiedPrincipalPolicyHistory;\n  readonly checkpoint: PrincipalPolicyCheckpoint | null;\n}): Promise<VerifiedPrincipalPolicyHistory> {\n  const { options, scopeId, history } = input;\n  const current = () => !options.signal?.aborted && options.stillCurrent();\n  const base = { execSql: options.execSql, scopeId, history };\n  const references: PrincipalPolicyHistoryReferenceProof[] = [];\n  for (const reference of options.retainedReferences ?? []) {\n    assertProjectionVerificationCurrent(current);\n    references.push(\n      await loadPrincipalHistoryReference({\n        ...base,\n        version: reference.version,\n      }),\n    );\n  }\n  assertProjectionVerificationCurrent(current);\n  const checkpointReference = input.checkpoint\n    ? await loadPrincipalHistoryReference({\n        ...base,\n        version: input.checkpoint.version,\n      })\n    : undefined;\n  const selected = await verifyPrincipalPolicyHistoryReferences({\n    history,\n    references,\n    checkpointReference,\n  });\n  if (!selected.ok) throw selected.error;\n  assertProjectionVerificationCurrent(current);\n  return selected.value;\n}\n\nexport async function selectRecoveredPrincipalHistory(\n  input: Parameters<typeof selectReferences>[0],\n): Promise<VerifiedPrincipalPolicyHistory> {\n  let selected: VerifiedPrincipalPolicyHistory;\n  try {\n    selected = await selectReferences(input);\n  } catch (error) {\n    if (error instanceof KeyingVerificationError)\n      throw new PrincipalHistoryEvidenceUnavailableError(error);\n    throw error;\n  }\n  // First authenticate the stored entry against the private root. Only then\n  // compare the caller's citation, so a bad request is not treated as cache loss.\n  for (const reference of input.options.retainedReferences ?? []) {\n    if (\n      !selected.retainedEntries.some(({ state }) =>\n        principalHeadMatchesReference(state, reference),\n      )\n    )\n      throw new KeyingVerificationError(\n        \"object_mismatch\",\n        \"Requested citation does not match the verified principal history\",\n      );\n  }\n  return selected;\n}\n"]}

package/workflows/principals/principalHistoryRecoveryStage.js

@@ -0,0 +1,61 @@
+import { createPrincipalPolicyHistoryVerifier, restorePrincipalPolicyHistoryVerifier, } from "../../internal/crypto/index.js";
+import { discardPrincipalHistoryStage, loadPrincipalHistoryStage, } from "../../data/persistence/principalHistoryStagePersistence.js";
+import { principalHistoryEvidenceScopeId } from "../../data/principals/principalHistoryPrefixProtection.js";
+import { parsePrincipalHistoryStageCurrent, principalHistoryStageId, principalHistoryStageProtection, } from "../../data/principals/principalHistoryStageProtection.js";
+import { restoreReusablePrincipalHistoryPrefix } from "./principalHistoryRecoveryPrefix.js";
+export async function restorePrincipalHistoryRecoveryStage(input, historyInput, useReusablePrefix = true) {
+    const scopeId = await principalHistoryEvidenceScopeId({
+        organizationId: input.organizationId,
+        head: input.expectedHead,
+        protection: input.protection,
+    });
+    const id = await principalHistoryStageId(input.organizationId, input.expectedHead, input.protection.context, input.retainedReferences ?? []);
+    const saved = await loadPrincipalHistoryStage(input.execSql, id);
+    if (saved) {
+        const current = parsePrincipalHistoryStageCurrent(saved);
+        if (current && saved.organizationId === input.organizationId) {
+            const restored = await restorePrincipalPolicyHistoryVerifier(historyInput, saved.progress, await principalHistoryStageProtection(input.protection, input.expectedHead, saved));
+            if (restored.ok)
+                return {
+                    id,
+                    scopeId,
+                    verifier: restored.value,
+                    current,
+                    saved,
+                    complete: saved.complete,
+                    initialAfterVersion: saved.afterVersion,
+                    fromCache: true,
+                };
+        }
+        // Saved bytes are a disposable hint. Only a locally authenticated restore
+        // can skip signed history; missing keys or changed inputs replay genesis.
+        await discardPrincipalHistoryStage(input.execSql, saved, () => !input.signal?.aborted && input.stillCurrent());
+    }
+    const prefix = useReusablePrefix
+        ? await restoreReusablePrincipalHistoryPrefix(input, historyInput, scopeId)
+        : null;
+    if (prefix) {
+        const complete = prefix.version === input.expectedHead.version;
+        return {
+            id,
+            scopeId,
+            verifier: prefix.verifier,
+            current: complete ? prefix.current : null,
+            saved: null,
+            complete,
+            initialAfterVersion: prefix.version - (complete ? 1 : 0),
+            fromCache: true,
+        };
+    }
+    return {
+        id,
+        scopeId,
+        verifier: createPrincipalPolicyHistoryVerifier(historyInput),
+        current: null,
+        saved: null,
+        complete: false,
+        initialAfterVersion: 0,
+        fromCache: false,
+    };
+}
+//# sourceMappingURL=principalHistoryRecoveryStage.js.map

package/workflows/principals/principalHistoryRecoveryStage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalHistoryRecoveryStage.js","sourceRoot":"","sources":["principalHistoryRecoveryStage.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PrincipalPolicyPageCurrent } from \"@tearleads/api-client\";\nimport {\n  createPrincipalPolicyHistoryVerifier,\n  type PrincipalPolicyHistoryInput,\n  type PrincipalPolicyHistoryVerifier,\n  restorePrincipalPolicyHistoryVerifier,\n} from \"@tearleads/crypto\";\nimport {\n  discardPrincipalHistoryStage,\n  loadPrincipalHistoryStage,\n  type PrincipalHistoryStage,\n} from \"../../data/persistence/principalHistoryStagePersistence\";\nimport { principalHistoryEvidenceScopeId } from \"../../data/principals/principalHistoryPrefixProtection\";\nimport {\n  parsePrincipalHistoryStageCurrent,\n  principalHistoryStageId,\n  principalHistoryStageProtection,\n} from \"../../data/principals/principalHistoryStageProtection\";\nimport { restoreReusablePrincipalHistoryPrefix } from \"./principalHistoryRecoveryPrefix\";\nimport type { RecoverPrincipalPolicyHistoryOptions } from \"./principalHistoryRecoveryTypes\";\n\nexport interface PrincipalHistoryRecoveryStage {\n  readonly id: string;\n  readonly scopeId: string;\n  readonly verifier: PrincipalPolicyHistoryVerifier;\n  readonly initialAfterVersion: number;\n  readonly fromCache: boolean;\n  complete: boolean;\n  current: PrincipalPolicyPageCurrent | null;\n  saved: PrincipalHistoryStage | null;\n}\n\nexport async function restorePrincipalHistoryRecoveryStage(\n  input: RecoverPrincipalPolicyHistoryOptions,\n  historyInput: PrincipalPolicyHistoryInput,\n  useReusablePrefix = true,\n): Promise<PrincipalHistoryRecoveryStage> {\n  const scopeId = await principalHistoryEvidenceScopeId({\n    organizationId: input.organizationId,\n    head: input.expectedHead,\n    protection: input.protection,\n  });\n  const id = await principalHistoryStageId(\n    input.organizationId,\n    input.expectedHead,\n    input.protection.context,\n    input.retainedReferences ?? [],\n  );\n  const saved = await loadPrincipalHistoryStage(input.execSql, id);\n  if (saved) {\n    const current = parsePrincipalHistoryStageCurrent(saved);\n    if (current && saved.organizationId === input.organizationId) {\n      const restored = await restorePrincipalPolicyHistoryVerifier(\n        historyInput,\n        saved.progress,\n        await principalHistoryStageProtection(\n          input.protection,\n          input.expectedHead,\n          saved,\n        ),\n      );\n      if (restored.ok)\n        return {\n          id,\n          scopeId,\n          verifier: restored.value,\n          current,\n          saved,\n          complete: saved.complete,\n          initialAfterVersion: saved.afterVersion,\n          fromCache: true,\n        };\n    }\n    // Saved bytes are a disposable hint. Only a locally authenticated restore\n    // can skip signed history; missing keys or changed inputs replay genesis.\n    await discardPrincipalHistoryStage(\n      input.execSql,\n      saved,\n      () => !input.signal?.aborted && input.stillCurrent(),\n    );\n  }\n  const prefix = useReusablePrefix\n    ? await restoreReusablePrincipalHistoryPrefix(input, historyInput, scopeId)\n    : null;\n  if (prefix) {\n    const complete = prefix.version === input.expectedHead.version;\n    return {\n      id,\n      scopeId,\n      verifier: prefix.verifier,\n      current: complete ? prefix.current : null,\n      saved: null,\n      complete,\n      initialAfterVersion: prefix.version - (complete ? 1 : 0),\n      fromCache: true,\n    };\n  }\n  return {\n    id,\n    scopeId,\n    verifier: createPrincipalPolicyHistoryVerifier(historyInput),\n    current: null,\n    saved: null,\n    complete: false,\n    initialAfterVersion: 0,\n    fromCache: false,\n  };\n}\n"]}

package/workflows/principals/principalHistoryRecoveryTypes.d.ts

@@ -0,0 +1,34 @@
+import type { ApiClient, PrincipalPolicyPageCurrent, RequestFailure } from "../../internal/api-client/index.js";
+import { KeyingVerificationError, type PrincipalPolicyExternalAuthority, type PrincipalPolicyHistoryProgressOptions, type PrincipalPolicyStateChainEntry, type ReferencedPrincipalHead, type VerifiedPrincipalPolicyCurrent } from "../../internal/crypto/index.js";
+import type { ExecSql } from "../../data/sqlite/sqlSchema.js";
+import type { TrustedUserIdentityResolver } from "../../data/trustedUserIdentity/index.js";
+/** A locally observed race, distinct from a rejected signed predecessor. */
+export declare class PrincipalHistoryRecoveryRaceError extends KeyingVerificationError {
+    constructor(message: string);
+}
+export interface RecoverPrincipalPolicyHistoryOptions {
+    readonly apiClient: Pick<ApiClient, "getPrincipalPolicyPages">;
+    readonly execSql: ExecSql;
+    readonly organizationId: string;
+    readonly expectedHead: ReferencedPrincipalHead;
+    /** Only use locally authenticated completed evidence; never perform HTTP. */
+    readonly offline?: boolean | undefined;
+    /** Device-controlled key and stable identity/trust-policy context, never supplied by the API. */
+    readonly protection: PrincipalPolicyHistoryProgressOptions;
+    readonly retainedReferences?: readonly ReferencedPrincipalHead[] | undefined;
+    /** Strict Admins mode checks every historical projection in a separate cache scope. */
+    readonly historyVerification?: "standard" | "direct-admins" | undefined;
+    readonly resolveTrustedUserIdentity: TrustedUserIdentityResolver;
+    /** Return only authority already authenticated by this client. */
+    readonly loadExternalAuthority?: ((entries: readonly PrincipalPolicyStateChainEntry[]) => Promise<PrincipalPolicyExternalAuthority | undefined>) | undefined;
+    readonly stillCurrent: () => boolean;
+    readonly signal?: AbortSignal | undefined;
+}
+export interface RecoveredPrincipalPolicyHistory {
+    readonly current: PrincipalPolicyPageCurrent;
+    readonly policy: VerifiedPrincipalPolicyCurrent;
+}
+export declare class PrincipalPolicyHistoryReadError extends Error {
+    readonly failure: RequestFailure;
+    constructor(failure: RequestFailure);
+}

package/workflows/principals/principalHistoryRecoveryTypes.js

@@ -0,0 +1,16 @@
+import { KeyingVerificationError, } from "../../internal/crypto/index.js";
+/** A locally observed race, distinct from a rejected signed predecessor. */
+export class PrincipalHistoryRecoveryRaceError extends KeyingVerificationError {
+    constructor(message) {
+        super("stale_predecessor", message);
+    }
+}
+export class PrincipalPolicyHistoryReadError extends Error {
+    failure;
+    constructor(failure) {
+        super(failure.message);
+        this.failure = failure;
+        this.name = "PrincipalPolicyHistoryReadError";
+    }
+}
+//# sourceMappingURL=principalHistoryRecoveryTypes.js.map

package/workflows/principals/principalHistoryRecoveryTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalHistoryRecoveryTypes.js","sourceRoot":"","sources":["principalHistoryRecoveryTypes.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,uBAAuB,GAMxB,MAAM,mBAAmB,CAAC;AAI3B,4EAA4E;AAC5E,MAAM,OAAO,iCAAkC,SAAQ,uBAAuB;IAC5E,YAAY,OAAe;QACzB,KAAK,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;CACF;AA8BD,MAAM,OAAO,+BAAgC,SAAQ,KAAK;IACnC;IAArB,YAAqB,OAAuB;QAC1C,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QADJ,YAAO,GAAP,OAAO,CAAgB;QAE1C,IAAI,CAAC,IAAI,GAAG,iCAAiC,CAAC;IAChD,CAAC;CACF","sourcesContent":["import type {\n  ApiClient,\n  PrincipalPolicyPageCurrent,\n  RequestFailure,\n} from \"@tearleads/api-client\";\nimport {\n  KeyingVerificationError,\n  type PrincipalPolicyExternalAuthority,\n  type PrincipalPolicyHistoryProgressOptions,\n  type PrincipalPolicyStateChainEntry,\n  type ReferencedPrincipalHead,\n  type VerifiedPrincipalPolicyCurrent,\n} from \"@tearleads/crypto\";\nimport type { ExecSql } from \"../../data/sqlite/sqlSchema\";\nimport type { TrustedUserIdentityResolver } from \"../../data/trustedUserIdentity\";\n\n/** A locally observed race, distinct from a rejected signed predecessor. */\nexport class PrincipalHistoryRecoveryRaceError extends KeyingVerificationError {\n  constructor(message: string) {\n    super(\"stale_predecessor\", message);\n  }\n}\n\nexport interface RecoverPrincipalPolicyHistoryOptions {\n  readonly apiClient: Pick<ApiClient, \"getPrincipalPolicyPages\">;\n  readonly execSql: ExecSql;\n  readonly organizationId: string;\n  readonly expectedHead: ReferencedPrincipalHead;\n  /** Only use locally authenticated completed evidence; never perform HTTP. */\n  readonly offline?: boolean | undefined;\n  /** Device-controlled key and stable identity/trust-policy context, never supplied by the API. */\n  readonly protection: PrincipalPolicyHistoryProgressOptions;\n  readonly retainedReferences?: readonly ReferencedPrincipalHead[] | undefined;\n  /** Strict Admins mode checks every historical projection in a separate cache scope. */\n  readonly historyVerification?: \"standard\" | \"direct-admins\" | undefined;\n  readonly resolveTrustedUserIdentity: TrustedUserIdentityResolver;\n  /** Return only authority already authenticated by this client. */\n  readonly loadExternalAuthority?:\n    | ((\n        entries: readonly PrincipalPolicyStateChainEntry[],\n      ) => Promise<PrincipalPolicyExternalAuthority | undefined>)\n    | undefined;\n  readonly stillCurrent: () => boolean;\n  readonly signal?: AbortSignal | undefined;\n}\n\nexport interface RecoveredPrincipalPolicyHistory {\n  readonly current: PrincipalPolicyPageCurrent;\n  readonly policy: VerifiedPrincipalPolicyCurrent;\n}\n\nexport class PrincipalPolicyHistoryReadError extends Error {\n  constructor(readonly failure: RequestFailure) {\n    super(failure.message);\n    this.name = \"PrincipalPolicyHistoryReadError\";\n  }\n}\n"]}

package/workflows/principals/principalHistoryRecoveryVerification.js

@@ -0,0 +1,24 @@
+import { KeyingVerificationError, serializeKeyingCanonicalJson, } from "../../internal/crypto/index.js";
+export function principalHistoryVerificationContext(input) {
+    const mode = input.historyVerification ?? "standard";
+    if (mode !== "standard" && mode !== "direct-admins")
+        throw new KeyingVerificationError("invalid_shape", "Unknown principal history verification mode");
+    if (mode === "standard")
+        return input.protection.context;
+    if (input.expectedHead.principalType !== "group" ||
+        input.loadExternalAuthority)
+        throw new KeyingVerificationError("invalid_shape", "Strict Admins history requires a group without external authority fallback");
+    // Retire this local attestation domain whenever strict validation changes.
+    return serializeKeyingCanonicalJson([
+        "tearleads.sdk.principal-history.direct-admins.v1",
+        input.protection.context,
+    ]);
+}
+export function assertPrincipalHistoryVerificationMode(input, entries) {
+    if (input.historyVerification !== "direct-admins")
+        return;
+    if (entries.some((entry) => entry.projection.length === 0 ||
+        entry.projection.some((member) => member.role !== "admin")))
+        throw new KeyingVerificationError("invalid_shape", "Reserved Admins history must contain only direct admin users");
+}
+//# sourceMappingURL=principalHistoryRecoveryVerification.js.map

package/workflows/principals/principalHistoryRecoveryVerification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalHistoryRecoveryVerification.js","sourceRoot":"","sources":["principalHistoryRecoveryVerification.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EAEvB,4BAA4B,GAC7B,MAAM,mBAAmB,CAAC;AAG3B,MAAM,UAAU,mCAAmC,CACjD,KAA2C;IAE3C,MAAM,IAAI,GAAG,KAAK,CAAC,mBAAmB,IAAI,UAAU,CAAC;IACrD,IAAI,IAAI,KAAK,UAAU,IAAI,IAAI,KAAK,eAAe;QACjD,MAAM,IAAI,uBAAuB,CAC/B,eAAe,EACf,6CAA6C,CAC9C,CAAC;IACJ,IAAI,IAAI,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC;IACzD,IACE,KAAK,CAAC,YAAY,CAAC,aAAa,KAAK,OAAO;QAC5C,KAAK,CAAC,qBAAqB;QAE3B,MAAM,IAAI,uBAAuB,CAC/B,eAAe,EACf,4EAA4E,CAC7E,CAAC;IACJ,2EAA2E;IAC3E,OAAO,4BAA4B,CAAC;QAClC,kDAAkD;QAClD,KAAK,CAAC,UAAU,CAAC,OAAO;KACzB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,sCAAsC,CACpD,KAA2C,EAC3C,OAAkD;IAElD,IAAI,KAAK,CAAC,mBAAmB,KAAK,eAAe;QAAE,OAAO;IAC1D,IACE,OAAO,CAAC,IAAI,CACV,CAAC,KAAK,EAAE,EAAE,CACR,KAAK,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;QAC7B,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC,CAC7D;QAED,MAAM,IAAI,uBAAuB,CAC/B,eAAe,EACf,8DAA8D,CAC/D,CAAC;AACN,CAAC","sourcesContent":["import {\n  KeyingVerificationError,\n  type PrincipalPolicyStateChainEntry,\n  serializeKeyingCanonicalJson,\n} from \"@tearleads/crypto\";\nimport type { RecoverPrincipalPolicyHistoryOptions } from \"./principalHistoryRecoveryTypes\";\n\nexport function principalHistoryVerificationContext(\n  input: RecoverPrincipalPolicyHistoryOptions,\n): string {\n  const mode = input.historyVerification ?? \"standard\";\n  if (mode !== \"standard\" && mode !== \"direct-admins\")\n    throw new KeyingVerificationError(\n      \"invalid_shape\",\n      \"Unknown principal history verification mode\",\n    );\n  if (mode === \"standard\") return input.protection.context;\n  if (\n    input.expectedHead.principalType !== \"group\" ||\n    input.loadExternalAuthority\n  )\n    throw new KeyingVerificationError(\n      \"invalid_shape\",\n      \"Strict Admins history requires a group without external authority fallback\",\n    );\n  // Retire this local attestation domain whenever strict validation changes.\n  return serializeKeyingCanonicalJson([\n    \"tearleads.sdk.principal-history.direct-admins.v1\",\n    input.protection.context,\n  ]);\n}\n\nexport function assertPrincipalHistoryVerificationMode(\n  input: RecoverPrincipalPolicyHistoryOptions,\n  entries: readonly PrincipalPolicyStateChainEntry[],\n): void {\n  if (input.historyVerification !== \"direct-admins\") return;\n  if (\n    entries.some(\n      (entry) =>\n        entry.projection.length === 0 ||\n        entry.projection.some((member) => member.role !== \"admin\"),\n    )\n  )\n    throw new KeyingVerificationError(\n      \"invalid_shape\",\n      \"Reserved Admins history must contain only direct admin users\",\n    );\n}\n"]}

package/workflows/principals/principalPolicyCacheAdvance.js

@@ -0,0 +1,39 @@
+import { KeyingVerificationError } from "../../internal/crypto/index.js";
+import { persistVerifiedPrincipalPolicyBundlesAtomically } from "../../data/persistence/keyingCheckpointAdvancePersistence.js";
+class PolicyCacheAdvanceRace extends Error {
+    verificationError;
+    constructor(verificationError) {
+        super(verificationError.message);
+        this.verificationError = verificationError;
+    }
+}
+/** Only a fully verified candidate losing the atomic commit race can retry. */
+export async function persistPrincipalPolicyCacheEntries(input) {
+    try {
+        await persistVerifiedPrincipalPolicyBundlesAtomically(input);
+    }
+    catch (error) {
+        if (error instanceof KeyingVerificationError && error.code === "rollback")
+            throw new PolicyCacheAdvanceRace(error);
+        throw error;
+    }
+}
+/** Discard stale snapshots once; the replacement must pass every normal check. */
+export async function retryPrincipalPolicyCacheAdvance(operation) {
+    try {
+        return await operation(false);
+    }
+    catch (error) {
+        if (!(error instanceof PolicyCacheAdvanceRace))
+            throw error;
+    }
+    try {
+        return await operation(true);
+    }
+    catch (error) {
+        throw error instanceof PolicyCacheAdvanceRace
+            ? error.verificationError
+            : error;
+    }
+}
+//# sourceMappingURL=principalPolicyCacheAdvance.js.map

package/workflows/principals/principalPolicyCacheAdvance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyCacheAdvance.js","sourceRoot":"","sources":["principalPolicyCacheAdvance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,+CAA+C,EAAE,MAAM,2DAA2D,CAAC;AAE5H,MAAM,sBAAuB,SAAQ,KAAK;IACnB;IAArB,YAAqB,iBAA0C;QAC7D,KAAK,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;QADd,sBAAiB,GAAjB,iBAAiB,CAAyB;IAE/D,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,kCAAkC,CACtD,KAA4E;IAE5E,IAAI,CAAC;QACH,MAAM,+CAA+C,CAAC,KAAK,CAAC,CAAC;IAC/D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,uBAAuB,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;YACvE,MAAM,IAAI,sBAAsB,CAAC,KAAK,CAAC,CAAC;QAC1C,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,kFAAkF;AAClF,MAAM,CAAC,KAAK,UAAU,gCAAgC,CACpD,SAA8C;IAE9C,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,sBAAsB,CAAC;YAAE,MAAM,KAAK,CAAC;IAC9D,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,KAAK,YAAY,sBAAsB;YAC3C,CAAC,CAAC,KAAK,CAAC,iBAAiB;YACzB,CAAC,CAAC,KAAK,CAAC;IACZ,CAAC;AACH,CAAC","sourcesContent":["import { KeyingVerificationError } from \"@tearleads/crypto\";\nimport { persistVerifiedPrincipalPolicyBundlesAtomically } from \"../../data/persistence/keyingCheckpointAdvancePersistence\";\n\nclass PolicyCacheAdvanceRace extends Error {\n  constructor(readonly verificationError: KeyingVerificationError) {\n    super(verificationError.message);\n  }\n}\n\n/** Only a fully verified candidate losing the atomic commit race can retry. */\nexport async function persistPrincipalPolicyCacheEntries(\n  input: Parameters<typeof persistVerifiedPrincipalPolicyBundlesAtomically>[0],\n): Promise<void> {\n  try {\n    await persistVerifiedPrincipalPolicyBundlesAtomically(input);\n  } catch (error) {\n    if (error instanceof KeyingVerificationError && error.code === \"rollback\")\n      throw new PolicyCacheAdvanceRace(error);\n    throw error;\n  }\n}\n\n/** Discard stale snapshots once; the replacement must pass every normal check. */\nexport async function retryPrincipalPolicyCacheAdvance<Result>(\n  operation: (fresh: boolean) => Promise<Result>,\n): Promise<Result> {\n  try {\n    return await operation(false);\n  } catch (error) {\n    if (!(error instanceof PolicyCacheAdvanceRace)) throw error;\n  }\n  try {\n    return await operation(true);\n  } catch (error) {\n    throw error instanceof PolicyCacheAdvanceRace\n      ? error.verificationError\n      : error;\n  }\n}\n"]}

package/workflows/principals/principalPolicyCacheScope.js

@@ -0,0 +1,34 @@
+import { validatePrincipalPolicyBundleForCache } from "./principalPolicyCacheValidation.js";
+import { directoryBindsGroupReference, } from "./principalPolicyOrganizationScope.js";
+export async function scopeReferencedPolicyForCache(input) {
+    const reference = input.validationInput.reference;
+    if (reference.principalType === "organization") {
+        return reference.principalId === input.organizationId
+            ? { ...input, directory: null }
+            : null;
+    }
+    let bundle = input.bundle;
+    let validation = input.validation;
+    let directory = await input.loadDirectory(false);
+    if (!directoryBindsGroupReference(directory, validation.policy, reference))
+        directory = await input.loadDirectory(true);
+    if (!directoryBindsGroupReference(directory, validation.policy, reference) &&
+        directory &&
+        input.reloadBundle) {
+        const current = await input.reloadBundle();
+        if (current) {
+            const checked = await validatePrincipalPolicyBundleForCache({
+                ...input.validationInput,
+                bundle: current,
+            });
+            if (!checked.ok)
+                throw checked.error;
+            bundle = current;
+            validation = checked;
+        }
+    }
+    return directoryBindsGroupReference(directory, validation.policy, reference)
+        ? { bundle, validation, directory }
+        : null;
+}
+//# sourceMappingURL=principalPolicyCacheScope.js.map

package/workflows/principals/principalPolicyCacheScope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyCacheScope.js","sourceRoot":"","sources":["principalPolicyCacheScope.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qCAAqC,EAAE,MAAM,kCAAkC,CAAC;AACzF,OAAO,EACL,4BAA4B,GAG7B,MAAM,oCAAoC,CAAC;AAU5C,MAAM,CAAC,KAAK,UAAU,6BAA6B,CAAC,KASnD;IAKC,MAAM,SAAS,GAAG,KAAK,CAAC,eAAe,CAAC,SAAS,CAAC;IAClD,IAAI,SAAS,CAAC,aAAa,KAAK,cAAc,EAAE,CAAC;QAC/C,OAAO,SAAS,CAAC,WAAW,KAAK,KAAK,CAAC,cAAc;YACnD,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE;YAC/B,CAAC,CAAC,IAAI,CAAC;IACX,CAAC;IACD,IAAI,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC1B,IAAI,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;IAClC,IAAI,SAAS,GAAG,MAAM,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IACjD,IAAI,CAAC,4BAA4B,CAAC,SAAS,EAAE,UAAU,CAAC,MAAM,EAAE,SAAS,CAAC;QACxE,SAAS,GAAG,MAAM,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAC9C,IACE,CAAC,4BAA4B,CAAC,SAAS,EAAE,UAAU,CAAC,MAAM,EAAE,SAAS,CAAC;QACtE,SAAS;QACT,KAAK,CAAC,YAAY,EAClB,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,YAAY,EAAE,CAAC;QAC3C,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,OAAO,GAAG,MAAM,qCAAqC,CAAC;gBAC1D,GAAG,KAAK,CAAC,eAAe;gBACxB,MAAM,EAAE,OAAO;aAChB,CAAC,CAAC;YACH,IAAI,CAAC,OAAO,CAAC,EAAE;gBAAE,MAAM,OAAO,CAAC,KAAK,CAAC;YACrC,MAAM,GAAG,OAAO,CAAC;YACjB,UAAU,GAAG,OAAO,CAAC;QACvB,CAAC;IACH,CAAC;IACD,OAAO,4BAA4B,CAAC,SAAS,EAAE,UAAU,CAAC,MAAM,EAAE,SAAS,CAAC;QAC1E,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE;QACnC,CAAC,CAAC,IAAI,CAAC;AACX,CAAC","sourcesContent":["import type { PrincipalPolicyBundleResponse } from \"@tearleads/validators/response\";\nimport { validatePrincipalPolicyBundleForCache } from \"./principalPolicyCacheValidation\";\nimport {\n  directoryBindsGroupReference,\n  type PolicyDirectoryLoader,\n  type VerifiedPolicyDirectory,\n} from \"./principalPolicyOrganizationScope\";\n\ntype ValidationInput = Parameters<\n  typeof validatePrincipalPolicyBundleForCache\n>[0];\ntype ValidatedPolicy = Extract<\n  Awaited<ReturnType<typeof validatePrincipalPolicyBundleForCache>>,\n  { ok: true }\n>;\n\nexport async function scopeReferencedPolicyForCache(input: {\n  readonly bundle: PrincipalPolicyBundleResponse;\n  readonly validation: ValidatedPolicy;\n  readonly validationInput: Omit<ValidationInput, \"bundle\">;\n  readonly loadDirectory: PolicyDirectoryLoader;\n  readonly organizationId: string;\n  readonly reloadBundle:\n    | (() => Promise<PrincipalPolicyBundleResponse | null>)\n    | null;\n}): Promise<{\n  readonly bundle: PrincipalPolicyBundleResponse;\n  readonly validation: ValidatedPolicy;\n  readonly directory: VerifiedPolicyDirectory | null;\n} | null> {\n  const reference = input.validationInput.reference;\n  if (reference.principalType === \"organization\") {\n    return reference.principalId === input.organizationId\n      ? { ...input, directory: null }\n      : null;\n  }\n  let bundle = input.bundle;\n  let validation = input.validation;\n  let directory = await input.loadDirectory(false);\n  if (!directoryBindsGroupReference(directory, validation.policy, reference))\n    directory = await input.loadDirectory(true);\n  if (\n    !directoryBindsGroupReference(directory, validation.policy, reference) &&\n    directory &&\n    input.reloadBundle\n  ) {\n    const current = await input.reloadBundle();\n    if (current) {\n      const checked = await validatePrincipalPolicyBundleForCache({\n        ...input.validationInput,\n        bundle: current,\n      });\n      if (!checked.ok) throw checked.error;\n      bundle = current;\n      validation = checked;\n    }\n  }\n  return directoryBindsGroupReference(directory, validation.policy, reference)\n    ? { bundle, validation, directory }\n    : null;\n}\n"]}

package/workflows/principals/principalPolicyCacheValidation.js

@@ -0,0 +1,149 @@
+import { KeyingVerificationError, } from "../../internal/crypto/index.js";
+import { verifyPrincipalPolicyBundleWithExternalOrganizationAdmins } from "../../data/principals/principalPolicyAdminSigners.js";
+import { collectPrincipalPolicySignerPublicKeys, principalPolicyStates, } from "./policyVerification.js";
+function getBundleReferenceFailure(reference, bundle) {
+    const states = principalPolicyStates(bundle);
+    const hasReferencedPrincipal = states.some((state) => state.principalType === reference.principalType &&
+        state.principalId === reference.principalId);
+    if (!hasReferencedPrincipal) {
+        return {
+            code: "object_mismatch",
+            message: "bundle principal does not match referenced principal",
+        };
+    }
+    if (!states.some((state) => state.principalType === reference.principalType &&
+        state.principalId === reference.principalId &&
+        state.version === reference.version &&
+        state.keyEpoch === reference.keyEpoch &&
+        state.stateHash === reference.stateHash &&
+        state.keyFingerprint === reference.keyFingerprint)) {
+        return {
+            code: "hash_mismatch",
+            message: "bundle chain does not contain referenced principal",
+        };
+    }
+    if (bundle.currentMemberEnvelopes.principalType !==
+        bundle.currentState.principalType ||
+        bundle.currentMemberEnvelopes.principalId !==
+            bundle.currentState.principalId) {
+        return {
+            code: "object_mismatch",
+            message: "member envelope principal does not match current principal",
+        };
+    }
+    if (bundle.currentMemberEnvelopes.stateHash !== bundle.currentState.stateHash) {
+        return {
+            code: "hash_mismatch",
+            message: "member envelope state hash does not match current principal",
+        };
+    }
+    if (bundle.currentMemberEnvelopes.epoch !== bundle.currentState.keyEpoch) {
+        return {
+            code: "hash_mismatch",
+            message: "member envelope epoch does not match current principal",
+        };
+    }
+    if (bundle.currentPayload.principalType !== bundle.currentState.principalType ||
+        bundle.currentPayload.principalId !== bundle.currentState.principalId) {
+        return {
+            code: "object_mismatch",
+            message: "payload principal does not match current principal",
+        };
+    }
+    if (bundle.currentPayload.stateHash !== bundle.currentState.stateHash) {
+        return {
+            code: "hash_mismatch",
+            message: "payload state hash does not match current principal",
+        };
+    }
+    return null;
+}
+function getCheckpointFailure(checkpoint, bundle) {
+    if (!checkpoint) {
+        return null;
+    }
+    const current = bundle.currentState;
+    if (current.version < checkpoint.version) {
+        return {
+            code: "rollback",
+            message: "principal policy state is older than the local checkpoint",
+        };
+    }
+    if (current.version === checkpoint.version &&
+        current.stateHash !== checkpoint.stateHash) {
+        return {
+            code: "equivocation",
+            message: "principal policy state conflicts with the local checkpoint",
+        };
+    }
+    if (current.version === checkpoint.version) {
+        return null;
+    }
+    const checkpointState = principalPolicyStates(bundle).find((state) => state.version === checkpoint.version);
+    return checkpointState?.stateHash === checkpoint.stateHash
+        ? null
+        : {
+            code: "stale_predecessor",
+            message: "principal policy chain does not extend the local checkpoint",
+        };
+}
+function signerPublicKeyLoadFailure(code) {
+    switch (code) {
+        case "fingerprint-mismatch":
+            return {
+                code: "signer_mismatch",
+                message: "signer key fingerprint does not match state signer",
+            };
+        case "not-found":
+            // The identity source throws for transport failures, so an absent
+            // signer here is the server asserting the cited user does not exist.
+            return {
+                code: "missing_dependency",
+                message: "signer identity is unknown to the server",
+            };
+    }
+}
+function verificationError(failure) {
+    return new KeyingVerificationError(failure.code, failure.message);
+}
+export async function validatePrincipalPolicyBundleForCache(input) {
+    const referenceFailure = getBundleReferenceFailure(input.reference, input.bundle);
+    if (referenceFailure) {
+        return { error: verificationError(referenceFailure), ok: false };
+    }
+    const checkpointFailure = getCheckpointFailure(input.localCheckpoint, input.bundle);
+    if (checkpointFailure) {
+        return { error: verificationError(checkpointFailure), ok: false };
+    }
+    const signerPublicKeys = await collectPrincipalPolicySignerPublicKeys({
+        bundle: input.bundle,
+        resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,
+    });
+    if ("error" in signerPublicKeys) {
+        return {
+            error: verificationError(signerPublicKeyLoadFailure(signerPublicKeys.error)),
+            ok: false,
+        };
+    }
+    let usedExternalAdminPolicy = false;
+    const verified = await verifyPrincipalPolicyBundleWithExternalOrganizationAdmins({
+        bundle: input.bundle,
+        expectedReference: input.reference,
+        loadExternalAuthority: async () => {
+            usedExternalAdminPolicy = true;
+            return ((await input.loadExternalAdminPolicy())?.externalAuthority ?? null);
+        },
+        localCheckpoint: input.localCheckpoint,
+        signerPublicKeys: signerPublicKeys.signerPublicKeys,
+    });
+    return verified.ok
+        ? {
+            externalAdminPolicy: usedExternalAdminPolicy
+                ? await input.loadExternalAdminPolicy()
+                : null,
+            ok: true,
+            policy: verified.value,
+        }
+        : { error: verified.error, ok: false };
+}
+//# sourceMappingURL=principalPolicyCacheValidation.js.map

package/workflows/principals/principalPolicyCacheValidation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyCacheValidation.js","sourceRoot":"","sources":["principalPolicyCacheValidation.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type KeyingVerificationCode,\n  KeyingVerificationError,\n  type PrincipalPolicyCheckpoint,\n  type VerifiedPrincipalPolicy,\n} from \"@tearleads/crypto\";\nimport type {\n  PrincipalPolicyBundleResponse,\n  ReferencedPrincipalStateResponse,\n} from \"@tearleads/validators/response\";\nimport { verifyPrincipalPolicyBundleWithExternalOrganizationAdmins } from \"../../data/principals/principalPolicyAdminSigners\";\nimport type { TrustedUserIdentityResolver } from \"../../data/trustedUserIdentity\";\nimport type { VerifiedExternalAdminPolicy } from \"./externalAdminPolicy\";\nimport {\n  collectPrincipalPolicySignerPublicKeys,\n  type PrincipalPolicySignerPublicKeyLoadErrorCode,\n  principalPolicyStates,\n} from \"./policyVerification\";\n\ninterface PrincipalPolicyValidationFailure {\n  readonly code: KeyingVerificationCode;\n  readonly message: string;\n}\n\nfunction getBundleReferenceFailure(\n  reference: ReferencedPrincipalStateResponse,\n  bundle: PrincipalPolicyBundleResponse,\n): PrincipalPolicyValidationFailure | null {\n  const states = principalPolicyStates(bundle);\n  const hasReferencedPrincipal = states.some(\n    (state) =>\n      state.principalType === reference.principalType &&\n      state.principalId === reference.principalId,\n  );\n  if (!hasReferencedPrincipal) {\n    return {\n      code: \"object_mismatch\",\n      message: \"bundle principal does not match referenced principal\",\n    };\n  }\n  if (\n    !states.some(\n      (state) =>\n        state.principalType === reference.principalType &&\n        state.principalId === reference.principalId &&\n        state.version === reference.version &&\n        state.keyEpoch === reference.keyEpoch &&\n        state.stateHash === reference.stateHash &&\n        state.keyFingerprint === reference.keyFingerprint,\n    )\n  ) {\n    return {\n      code: \"hash_mismatch\",\n      message: \"bundle chain does not contain referenced principal\",\n    };\n  }\n  if (\n    bundle.currentMemberEnvelopes.principalType !==\n      bundle.currentState.principalType ||\n    bundle.currentMemberEnvelopes.principalId !==\n      bundle.currentState.principalId\n  ) {\n    return {\n      code: \"object_mismatch\",\n      message: \"member envelope principal does not match current principal\",\n    };\n  }\n  if (\n    bundle.currentMemberEnvelopes.stateHash !== bundle.currentState.stateHash\n  ) {\n    return {\n      code: \"hash_mismatch\",\n      message: \"member envelope state hash does not match current principal\",\n    };\n  }\n  if (bundle.currentMemberEnvelopes.epoch !== bundle.currentState.keyEpoch) {\n    return {\n      code: \"hash_mismatch\",\n      message: \"member envelope epoch does not match current principal\",\n    };\n  }\n  if (\n    bundle.currentPayload.principalType !== bundle.currentState.principalType ||\n    bundle.currentPayload.principalId !== bundle.currentState.principalId\n  ) {\n    return {\n      code: \"object_mismatch\",\n      message: \"payload principal does not match current principal\",\n    };\n  }\n  if (bundle.currentPayload.stateHash !== bundle.currentState.stateHash) {\n    return {\n      code: \"hash_mismatch\",\n      message: \"payload state hash does not match current principal\",\n    };\n  }\n  return null;\n}\n\nfunction getCheckpointFailure(\n  checkpoint: PrincipalPolicyCheckpoint | null,\n  bundle: PrincipalPolicyBundleResponse,\n): PrincipalPolicyValidationFailure | null {\n  if (!checkpoint) {\n    return null;\n  }\n  const current = bundle.currentState;\n  if (current.version < checkpoint.version) {\n    return {\n      code: \"rollback\",\n      message: \"principal policy state is older than the local checkpoint\",\n    };\n  }\n  if (\n    current.version === checkpoint.version &&\n    current.stateHash !== checkpoint.stateHash\n  ) {\n    return {\n      code: \"equivocation\",\n      message: \"principal policy state conflicts with the local checkpoint\",\n    };\n  }\n  if (current.version === checkpoint.version) {\n    return null;\n  }\n  const checkpointState = principalPolicyStates(bundle).find(\n    (state) => state.version === checkpoint.version,\n  );\n  return checkpointState?.stateHash === checkpoint.stateHash\n    ? null\n    : {\n        code: \"stale_predecessor\",\n        message: \"principal policy chain does not extend the local checkpoint\",\n      };\n}\n\nfunction signerPublicKeyLoadFailure(\n  code: PrincipalPolicySignerPublicKeyLoadErrorCode,\n): PrincipalPolicyValidationFailure {\n  switch (code) {\n    case \"fingerprint-mismatch\":\n      return {\n        code: \"signer_mismatch\",\n        message: \"signer key fingerprint does not match state signer\",\n      };\n    case \"not-found\":\n      // The identity source throws for transport failures, so an absent\n      // signer here is the server asserting the cited user does not exist.\n      return {\n        code: \"missing_dependency\",\n        message: \"signer identity is unknown to the server\",\n      };\n  }\n}\n\nfunction verificationError(\n  failure: PrincipalPolicyValidationFailure,\n): KeyingVerificationError {\n  return new KeyingVerificationError(failure.code, failure.message);\n}\n\nexport async function validatePrincipalPolicyBundleForCache(input: {\n  readonly bundle: PrincipalPolicyBundleResponse;\n  readonly loadExternalAdminPolicy: () => Promise<VerifiedExternalAdminPolicy | null>;\n  readonly localCheckpoint: PrincipalPolicyCheckpoint | null;\n  readonly reference: ReferencedPrincipalStateResponse;\n  readonly resolveTrustedUserIdentity: TrustedUserIdentityResolver;\n}): Promise<\n  | {\n      readonly externalAdminPolicy: VerifiedExternalAdminPolicy | null;\n      readonly ok: true;\n      readonly policy: VerifiedPrincipalPolicy;\n    }\n  | { readonly error: KeyingVerificationError; readonly ok: false }\n> {\n  const referenceFailure = getBundleReferenceFailure(\n    input.reference,\n    input.bundle,\n  );\n  if (referenceFailure) {\n    return { error: verificationError(referenceFailure), ok: false };\n  }\n  const checkpointFailure = getCheckpointFailure(\n    input.localCheckpoint,\n    input.bundle,\n  );\n  if (checkpointFailure) {\n    return { error: verificationError(checkpointFailure), ok: false };\n  }\n  const signerPublicKeys = await collectPrincipalPolicySignerPublicKeys({\n    bundle: input.bundle,\n    resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,\n  });\n  if (\"error\" in signerPublicKeys) {\n    return {\n      error: verificationError(\n        signerPublicKeyLoadFailure(signerPublicKeys.error),\n      ),\n      ok: false,\n    };\n  }\n\n  let usedExternalAdminPolicy = false;\n  const verified =\n    await verifyPrincipalPolicyBundleWithExternalOrganizationAdmins({\n      bundle: input.bundle,\n      expectedReference: input.reference,\n      loadExternalAuthority: async () => {\n        usedExternalAdminPolicy = true;\n        return (\n          (await input.loadExternalAdminPolicy())?.externalAuthority ?? null\n        );\n      },\n      localCheckpoint: input.localCheckpoint,\n      signerPublicKeys: signerPublicKeys.signerPublicKeys,\n    });\n  return verified.ok\n    ? {\n        externalAdminPolicy: usedExternalAdminPolicy\n          ? await input.loadExternalAdminPolicy()\n          : null,\n        ok: true,\n        policy: verified.value,\n      }\n    : { error: verified.error, ok: false };\n}\n"]}