@tearleads/client-sdk 0.0.0-stage → 0.1.11

package/workflows/principals/principalHistoryRecoveryStage.js

@@ -0,0 +1,25 @@
+import { createPrincipalPolicyHistoryVerifier, restorePrincipalPolicyHistoryVerifier, } from "../../internal/crypto/index.js";
+import { discardPrincipalHistoryStage, loadPrincipalHistoryStage, } from "../../data/persistence/principalHistoryStagePersistence.js";
+import { parsePrincipalHistoryStageCurrent, principalHistoryStageId, principalHistoryStageProtection, } from "../../data/principals/principalHistoryStageProtection.js";
+export async function restorePrincipalHistoryRecoveryStage(input, historyInput) {
+    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, verifier: restored.value, current, saved };
+        }
+        // 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());
+    }
+    return {
+        id,
+        verifier: createPrincipalPolicyHistoryVerifier(historyInput),
+        current: null,
+        saved: null,
+    };
+}
+//# sourceMappingURL=principalHistoryRecoveryStage.js.map

package/workflows/principals/principalHistoryRecoveryStage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalHistoryRecoveryStage.js","sourceRoot":"","sources":["principalHistoryRecoveryStage.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oCAAoC,EAGpC,qCAAqC,GACtC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,4BAA4B,EAC5B,yBAAyB,GAE1B,MAAM,yDAAyD,CAAC;AACjE,OAAO,EACL,iCAAiC,EACjC,uBAAuB,EACvB,+BAA+B,GAChC,MAAM,uDAAuD,CAAC;AAU/D,MAAM,CAAC,KAAK,UAAU,oCAAoC,CACxD,KAA2C,EAC3C,YAAyC;IAEzC,MAAM,EAAE,GAAG,MAAM,uBAAuB,CACtC,KAAK,CAAC,cAAc,EACpB,KAAK,CAAC,YAAY,EAClB,KAAK,CAAC,UAAU,CAAC,OAAO,EACxB,KAAK,CAAC,kBAAkB,IAAI,EAAE,CAC/B,CAAC;IACF,MAAM,KAAK,GAAG,MAAM,yBAAyB,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACjE,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,OAAO,GAAG,iCAAiC,CAAC,KAAK,CAAC,CAAC;QACzD,IAAI,OAAO,IAAI,KAAK,CAAC,cAAc,KAAK,KAAK,CAAC,cAAc,EAAE,CAAC;YAC7D,MAAM,QAAQ,GAAG,MAAM,qCAAqC,CAC1D,YAAY,EACZ,KAAK,CAAC,QAAQ,EACd,MAAM,+BAA+B,CACnC,KAAK,CAAC,UAAU,EAChB,KAAK,CAAC,YAAY,EAClB,KAAK,CACN,CACF,CAAC;YACF,IAAI,QAAQ,CAAC,EAAE;gBAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC3E,CAAC;QACD,0EAA0E;QAC1E,0EAA0E;QAC1E,MAAM,4BAA4B,CAChC,KAAK,CAAC,OAAO,EACb,KAAK,EACL,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,IAAI,KAAK,CAAC,YAAY,EAAE,CACrD,CAAC;IACJ,CAAC;IACD,OAAO;QACL,EAAE;QACF,QAAQ,EAAE,oCAAoC,CAAC,YAAY,CAAC;QAC5D,OAAO,EAAE,IAAI;QACb,KAAK,EAAE,IAAI;KACZ,CAAC;AACJ,CAAC","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 {\n  parsePrincipalHistoryStageCurrent,\n  principalHistoryStageId,\n  principalHistoryStageProtection,\n} from \"../../data/principals/principalHistoryStageProtection\";\nimport type { RecoverPrincipalPolicyHistoryOptions } from \"./principalHistoryRecoveryTypes\";\n\nexport interface PrincipalHistoryRecoveryStage {\n  readonly id: string;\n  readonly verifier: PrincipalPolicyHistoryVerifier;\n  current: PrincipalPolicyPageCurrent | null;\n  saved: PrincipalHistoryStage | null;\n}\n\nexport async function restorePrincipalHistoryRecoveryStage(\n  input: RecoverPrincipalPolicyHistoryOptions,\n  historyInput: PrincipalPolicyHistoryInput,\n): Promise<PrincipalHistoryRecoveryStage> {\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) return { id, verifier: restored.value, current, saved };\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  return {\n    id,\n    verifier: createPrincipalPolicyHistoryVerifier(historyInput),\n    current: null,\n    saved: null,\n  };\n}\n"]}

package/workflows/principals/principalHistoryRecoveryTypes.d.ts

@@ -0,0 +1,26 @@
+import type { ApiClient, PrincipalPolicyPageCurrent, RequestFailure } from "../../internal/api-client/index.js";
+import type { PrincipalPolicyExternalAuthority, PrincipalPolicyHistoryProgressOptions, PrincipalPolicyStateChainEntry, ReferencedPrincipalHead, VerifiedPrincipalPolicyCurrent } from "../../internal/crypto/index.js";
+import type { ExecSql } from "../../data/sqlite/sqlSchema.js";
+import type { TrustedUserIdentityResolver } from "../../data/trustedUserIdentity/index.js";
+export interface RecoverPrincipalPolicyHistoryOptions {
+    readonly apiClient: Pick<ApiClient, "getPrincipalPolicyPages">;
+    readonly execSql: ExecSql;
+    readonly organizationId: string;
+    readonly expectedHead: ReferencedPrincipalHead;
+    /** Device-controlled key and stable identity/trust-policy context, never supplied by the API. */
+    readonly protection: PrincipalPolicyHistoryProgressOptions;
+    readonly retainedReferences?: readonly ReferencedPrincipalHead[] | 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,9 @@
+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":"AAuCA,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 type {\n  PrincipalPolicyExternalAuthority,\n  PrincipalPolicyHistoryProgressOptions,\n  PrincipalPolicyStateChainEntry,\n  ReferencedPrincipalHead,\n  VerifiedPrincipalPolicyCurrent,\n} from \"@tearleads/crypto\";\nimport type { ExecSql } from \"../../data/sqlite/sqlSchema\";\nimport type { TrustedUserIdentityResolver } from \"../../data/trustedUserIdentity\";\n\nexport interface RecoverPrincipalPolicyHistoryOptions {\n  readonly apiClient: Pick<ApiClient, \"getPrincipalPolicyPages\">;\n  readonly execSql: ExecSql;\n  readonly organizationId: string;\n  readonly expectedHead: ReferencedPrincipalHead;\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  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/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"]}

package/workflows/principals/principalPolicyOrganizationScope.js

@@ -0,0 +1,67 @@
+import { KeyingVerificationError, } from "../../internal/crypto/index.js";
+import { loadPrincipalPolicyCheckpoint } from "../../data/persistence/keyingCheckpointPersistence.js";
+import { principalPolicyHeadMeetsCheckpoint } from "../../data/persistence/principalPolicyCheckpointSelection.js";
+import { loadPrincipalPolicyBundle } from "../../data/persistence/principalPolicyPersistence.js";
+import { parseOrganizationAuthorityDescriptor, principalHeadMatchesReference, } from "../../data/principals/organizationAuthorityDescriptor.js";
+import { verifyOrganizationAdminPolicy } from "../../data/principals/principalPolicyAdminSigners.js";
+import { collectPrincipalPolicySignerPublicKeys } from "./policyVerification.js";
+export function directoryBindsGroupReference(directory, policy, reference) {
+    const head = directory?.descriptor.groupHeads.find((head) => head.principalId === reference.principalId);
+    // A newer directory head authenticates its verified predecessors too.
+    // Requiring equality with a historical manifest citation bricks old reads.
+    return (!!head &&
+        head.version >= reference.version &&
+        head.version === policy.version &&
+        [policy.state, ...(policy.history ?? []).map((entry) => entry.state)].some((state) => principalHeadMatchesReference(state, head)));
+}
+export function createPolicyDirectoryLoader(input) {
+    const memo = new Map();
+    const load = async (remote) => {
+        const checkpoint = await loadPrincipalPolicyCheckpoint(input.execSql, "organization", input.organizationId);
+        let bundle = remote
+            ? null
+            : await loadPrincipalPolicyBundle(input.execSql, "organization", input.organizationId);
+        if (bundle &&
+            !principalPolicyHeadMeetsCheckpoint(bundle.currentState, checkpoint))
+            bundle = null;
+        bundle ??= await input.getCurrentPrincipalPolicy("organization", input.organizationId);
+        if (!bundle)
+            return null;
+        const signers = await collectPrincipalPolicySignerPublicKeys({
+            bundle,
+            resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,
+        });
+        if ("error" in signers) {
+            if (signers.error === "fingerprint-mismatch")
+                throw new KeyingVerificationError("signer_mismatch", "organization directory signer fingerprint does not match");
+            return null;
+        }
+        const verified = await verifyOrganizationAdminPolicy({
+            bundle,
+            localCheckpoint: checkpoint,
+            organizationId: input.organizationId,
+            signerPublicKeys: signers.signerPublicKeys,
+        });
+        if (!verified.ok)
+            throw verified.error;
+        let descriptor;
+        try {
+            descriptor = parseOrganizationAuthorityDescriptor(bundle.currentPayload.ciphertext);
+        }
+        catch {
+            throw new KeyingVerificationError("invalid_shape", "organization directory payload is invalid");
+        }
+        if (descriptor.organizationId !== input.organizationId)
+            throw new KeyingVerificationError("object_mismatch", "organization directory scope does not match");
+        return { bundle, policy: verified.value, descriptor };
+    };
+    return (remote) => {
+        let pending = memo.get(remote);
+        if (!pending) {
+            pending = load(remote);
+            memo.set(remote, pending);
+        }
+        return pending;
+    };
+}
+//# sourceMappingURL=principalPolicyOrganizationScope.js.map

package/workflows/principals/principalPolicyOrganizationScope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyOrganizationScope.js","sourceRoot":"","sources":["principalPolicyOrganizationScope.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  KeyingVerificationError,\n  type ReferencedPrincipalHead,\n  type VerifiedPrincipalPolicy,\n} from \"@tearleads/crypto\";\nimport type { PrincipalPolicyBundleResponse } from \"@tearleads/validators/response\";\nimport { loadPrincipalPolicyCheckpoint } from \"../../data/persistence/keyingCheckpointPersistence\";\nimport { principalPolicyHeadMeetsCheckpoint } from \"../../data/persistence/principalPolicyCheckpointSelection\";\nimport { loadPrincipalPolicyBundle } from \"../../data/persistence/principalPolicyPersistence\";\nimport {\n  type OrganizationAuthorityDescriptor,\n  parseOrganizationAuthorityDescriptor,\n  principalHeadMatchesReference,\n} from \"../../data/principals/organizationAuthorityDescriptor\";\nimport { verifyOrganizationAdminPolicy } from \"../../data/principals/principalPolicyAdminSigners\";\nimport type { ExecSql } from \"../../data/sqlite/sqlSchema\";\nimport type { TrustedUserIdentityResolver } from \"../../data/trustedUserIdentity\";\nimport { collectPrincipalPolicySignerPublicKeys } from \"./policyVerification\";\n\nexport interface VerifiedPolicyDirectory {\n  readonly bundle: PrincipalPolicyBundleResponse;\n  readonly policy: VerifiedPrincipalPolicy;\n  readonly descriptor: OrganizationAuthorityDescriptor;\n}\n\nexport type PolicyDirectoryLoader = (\n  remote: boolean,\n) => Promise<VerifiedPolicyDirectory | null>;\n\nexport function directoryBindsGroupReference(\n  directory: VerifiedPolicyDirectory | null,\n  policy: VerifiedPrincipalPolicy,\n  reference: ReferencedPrincipalHead,\n): boolean {\n  const head = directory?.descriptor.groupHeads.find(\n    (head) => head.principalId === reference.principalId,\n  );\n  // A newer directory head authenticates its verified predecessors too.\n  // Requiring equality with a historical manifest citation bricks old reads.\n  return (\n    !!head &&\n    head.version >= reference.version &&\n    head.version === policy.version &&\n    [policy.state, ...(policy.history ?? []).map((entry) => entry.state)].some(\n      (state) => principalHeadMatchesReference(state, head),\n    )\n  );\n}\n\nexport function createPolicyDirectoryLoader(input: {\n  readonly execSql: ExecSql;\n  readonly organizationId: string;\n  readonly getCurrentPrincipalPolicy: (\n    kind: \"group\" | \"organization\",\n    id: string,\n  ) => Promise<PrincipalPolicyBundleResponse | null>;\n  readonly resolveTrustedUserIdentity: TrustedUserIdentityResolver;\n}): PolicyDirectoryLoader {\n  const memo = new Map<boolean, Promise<VerifiedPolicyDirectory | null>>();\n  const load = async (\n    remote: boolean,\n  ): Promise<VerifiedPolicyDirectory | null> => {\n    const checkpoint = await loadPrincipalPolicyCheckpoint(\n      input.execSql,\n      \"organization\",\n      input.organizationId,\n    );\n    let bundle = remote\n      ? null\n      : await loadPrincipalPolicyBundle(\n          input.execSql,\n          \"organization\",\n          input.organizationId,\n        );\n    if (\n      bundle &&\n      !principalPolicyHeadMeetsCheckpoint(bundle.currentState, checkpoint)\n    )\n      bundle = null;\n    bundle ??= await input.getCurrentPrincipalPolicy(\n      \"organization\",\n      input.organizationId,\n    );\n    if (!bundle) return null;\n    const signers = await collectPrincipalPolicySignerPublicKeys({\n      bundle,\n      resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,\n    });\n    if (\"error\" in signers) {\n      if (signers.error === \"fingerprint-mismatch\")\n        throw new KeyingVerificationError(\n          \"signer_mismatch\",\n          \"organization directory signer fingerprint does not match\",\n        );\n      return null;\n    }\n    const verified = await verifyOrganizationAdminPolicy({\n      bundle,\n      localCheckpoint: checkpoint,\n      organizationId: input.organizationId,\n      signerPublicKeys: signers.signerPublicKeys,\n    });\n    if (!verified.ok) throw verified.error;\n    let descriptor: OrganizationAuthorityDescriptor;\n    try {\n      descriptor = parseOrganizationAuthorityDescriptor(\n        bundle.currentPayload.ciphertext,\n      );\n    } catch {\n      throw new KeyingVerificationError(\n        \"invalid_shape\",\n        \"organization directory payload is invalid\",\n      );\n    }\n    if (descriptor.organizationId !== input.organizationId)\n      throw new KeyingVerificationError(\n        \"object_mismatch\",\n        \"organization directory scope does not match\",\n      );\n    return { bundle, policy: verified.value, descriptor };\n  };\n  return (remote) => {\n    let pending = memo.get(remote);\n    if (!pending) {\n      pending = load(remote);\n      memo.set(remote, pending);\n    }\n    return pending;\n  };\n}\n"]}

package/workflows/principals/recoverPrincipalPolicyHistory.d.ts

@@ -0,0 +1,6 @@
+import { type RecoveredPrincipalPolicyHistory, type RecoverPrincipalPolicyHistoryOptions } from "./principalHistoryRecoveryTypes.js";
+/**
+ * Recover one exact head with bounded retained history and durable checked progress.
+ * The result is a sparse current-policy capability; this does not advance app checkpoints.
+ */
+export declare function recoverPrincipalPolicyHistory(options: RecoverPrincipalPolicyHistoryOptions): Promise<RecoveredPrincipalPolicyHistory>;

package/workflows/principals/recoverPrincipalPolicyHistory.js

@@ -0,0 +1,173 @@
+import { KeyingVerificationError, verifyPrincipalPolicyCurrent, } from "../../internal/crypto/index.js";
+import { assertProjectionVerificationCurrent } from "../../data/keyingProjectionVerification/types.js";
+import { loadPrincipalPolicyCheckpoint } from "../../data/persistence/keyingCheckpointPersistence.js";
+import { discardPrincipalHistoryStage, savePrincipalHistoryStage, } from "../../data/persistence/principalHistoryStagePersistence.js";
+import { principalHistoryStageProtection } from "../../data/principals/principalHistoryStageProtection.js";
+import { collectPrincipalPolicySignerPublicKeys } from "./policyVerification.js";
+import { restorePrincipalHistoryRecoveryStage, } from "./principalHistoryRecoveryStage.js";
+import { PrincipalPolicyHistoryReadError, } from "./principalHistoryRecoveryTypes.js";
+function currentArtifacts(page) {
+    return {
+        currentState: page.currentState,
+        currentPayload: page.currentPayload,
+        currentProjection: page.currentProjection,
+        currentGrants: page.currentGrants,
+        currentMemberEnvelopes: page.currentMemberEnvelopes,
+    };
+}
+function assertCurrent(input) {
+    assertProjectionVerificationCurrent(() => !input.signal?.aborted && input.stillCurrent());
+}
+async function acceptPage(input, stage, response) {
+    const page = structuredClone(response);
+    assertCurrent(input);
+    for (const field of [
+        "principalType",
+        "principalId",
+        "version",
+        "stateHash",
+        "keyEpoch",
+        "keyFingerprint",
+    ]) {
+        if (page.currentState[field] !== input.expectedHead[field])
+            throw new KeyingVerificationError("object_mismatch", "Principal history page does not match its requested head");
+    }
+    if (stage.saved?.complete) {
+        if (page.previousStates.length !== 0 ||
+            page.historyPage.nextAfterVersion !== null)
+            throw new KeyingVerificationError("invalid_shape", "Completed history returned additional entries");
+        return;
+    }
+    const complete = page.historyPage.nextAfterVersion === null;
+    const current = currentArtifacts(page);
+    const entries = [...page.previousStates];
+    if (complete)
+        entries.push({
+            state: current.currentState,
+            projection: current.currentProjection,
+            grants: current.currentGrants,
+        });
+    const keys = await collectPrincipalPolicySignerPublicKeys({
+        bundle: { ...current, previousStates: page.previousStates },
+        resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,
+    });
+    if ("error" in keys)
+        throw new KeyingVerificationError(keys.error === "not-found" ? "missing_dependency" : "signer_mismatch", "Principal history signer identity could not be authenticated");
+    const externalAuthority = await input.loadExternalAuthority?.(entries);
+    const appended = await stage.verifier.append({
+        entries,
+        signerPublicKeys: keys.signerPublicKeys,
+        ...(externalAuthority ? { externalAuthority } : {}),
+    });
+    if (!appended.ok)
+        throw appended.error;
+    const next = {
+        id: stage.id,
+        organizationId: input.organizationId,
+        currentJson: JSON.stringify(current),
+        afterVersion: appended.value.throughVersion - (complete ? 1 : 0),
+        complete,
+    };
+    const protectedProgress = await stage.verifier.exportProgress(await principalHistoryStageProtection(input.protection, input.expectedHead, next));
+    if (!protectedProgress.ok)
+        throw protectedProgress.error;
+    const saved = { ...next, progress: protectedProgress.value };
+    await savePrincipalHistoryStage({
+        execSql: input.execSql,
+        stage: saved,
+        previousProgress: stage.saved?.progress ?? null,
+        stillCurrent: () => !input.signal?.aborted && input.stillCurrent(),
+    });
+    stage.current = current;
+    stage.saved = saved;
+}
+async function finishRecovery(input, stage, checkpoint) {
+    if (!stage.current || !stage.saved?.complete)
+        throw new KeyingVerificationError("missing_dependency", "Principal history ended before its pinned head");
+    const history = stage.verifier.finish(input.expectedHead);
+    if (!history.ok)
+        throw history.error;
+    const current = await verifyPrincipalPolicyCurrent({
+        current: stage.current,
+        history: history.value,
+    });
+    if (!current.ok)
+        throw current.error;
+    const latest = await loadPrincipalPolicyCheckpoint(input.execSql, input.expectedHead.principalType, input.expectedHead.principalId);
+    if (latest?.version !== checkpoint?.version ||
+        latest?.stateHash !== checkpoint?.stateHash)
+        throw new KeyingVerificationError("stale_predecessor", "Local principal checkpoint changed during history recovery");
+    assertCurrent(input);
+    return { current: stage.current, policy: current.value };
+}
+async function recover(input) {
+    assertCurrent(input);
+    const checkpoint = await loadPrincipalPolicyCheckpoint(input.execSql, input.expectedHead.principalType, input.expectedHead.principalId);
+    if (checkpoint && input.expectedHead.version < checkpoint.version)
+        throw new KeyingVerificationError("rollback", "Requested principal history predates the local checkpoint");
+    const historyInput = {
+        principalType: input.expectedHead.principalType,
+        principalId: input.expectedHead.principalId,
+        localCheckpoint: checkpoint,
+        retainedReferences: input.retainedReferences ?? [],
+    };
+    const stage = await restorePrincipalHistoryRecoveryStage(input, historyInput);
+    let receivedFinalPage = false;
+    for await (const result of input.apiClient.getPrincipalPolicyPages(input.expectedHead.principalType, input.expectedHead.principalId, {
+        signal: input.signal,
+        stateHash: input.expectedHead.stateHash,
+        ...(stage.saved && stage.current
+            ? {
+                resume: {
+                    current: stage.current,
+                    afterVersion: stage.saved.afterVersion,
+                },
+            }
+            : {}),
+    })) {
+        if (!result.ok) {
+            // A rejected transport pin cannot justify skipping history on retry.
+            // Discard only this operation's progress, then let a new call replay it.
+            if (result.kind === "shape" && stage.saved)
+                await discardPrincipalHistoryStage(input.execSql, stage.saved, () => !input.signal?.aborted && input.stillCurrent());
+            throw new PrincipalPolicyHistoryReadError(result);
+        }
+        await acceptPage(input, stage, result.data);
+        receivedFinalPage = result.data.historyPage.nextAfterVersion === null;
+    }
+    if (!receivedFinalPage)
+        throw new KeyingVerificationError("missing_dependency", "Principal history transport did not complete");
+    return finishRecovery(input, stage, checkpoint);
+}
+/**
+ * Recover one exact head with bounded retained history and durable checked progress.
+ * The result is a sparse current-policy capability; this does not advance app checkpoints.
+ */
+export async function recoverPrincipalPolicyHistory(options) {
+    if (!options.organizationId ||
+        (options.expectedHead.principalType === "organization" &&
+            options.expectedHead.principalId !== options.organizationId))
+        throw new KeyingVerificationError("object_mismatch", "Principal history organization scope is invalid");
+    if (options.retainedReferences?.some((reference) => reference.version > options.expectedHead.version))
+        throw new KeyingVerificationError("missing_dependency", "Requested history reference is beyond the recovery head");
+    if (!(options.protection.localKey instanceof Uint8Array) ||
+        options.protection.localKey.byteLength !== 32 ||
+        !options.protection.context)
+        throw new KeyingVerificationError("invalid_shape", "Principal history recovery requires a private 32-byte key and trust context");
+    const input = {
+        ...options,
+        expectedHead: structuredClone(options.expectedHead),
+        retainedReferences: structuredClone(options.retainedReferences ?? []),
+        protection: {
+            context: options.protection.context,
+            localKey: new Uint8Array(options.protection.localKey),
+        },
+    };
+    try {
+        return await recover(input);
+    }
+    finally {
+        input.protection.localKey.fill(0);
+    }
+}
+//# sourceMappingURL=recoverPrincipalPolicyHistory.js.map