@tearleads/client-sdk 0.1.14 → 0.1.16

package/workflows/principals/principalRecoveryLocalPreference.js

@@ -0,0 +1,28 @@
+import { KeyingVerificationError } from "../../internal/crypto/index.js";
+import { assertProjectionVerificationCurrent } from "../../data/keyingProjectionVerification/types.js";
+import { principalHeadMatchesReference } from "../../data/principals/organizationAuthorityDescriptor.js";
+import { PrincipalHistoryRecoveryRaceError } from "./principalHistoryRecoveryTypes.js";
+import { recoverWithPrincipalOutageFallback } from "./principalRecoveryOutage.js";
+/** Reuse authenticated local artifacts only for the exact current head a caller selected. */
+export async function recoverWithPrincipalLocalPreference(recover, options, preferLocalCurrent) {
+    if (preferLocalCurrent && !options.offline) {
+        try {
+            const local = await recover({
+                ...options,
+                offline: true,
+            });
+            assertProjectionVerificationCurrent(options.stillCurrent);
+            if (principalHeadMatchesReference(local.policy.state, options.reference))
+                return local;
+        }
+        catch (error) {
+            assertProjectionVerificationCurrent(options.stillCurrent);
+            if (!(error instanceof PrincipalHistoryRecoveryRaceError) &&
+                !(error instanceof KeyingVerificationError &&
+                    error.code === "missing_dependency"))
+                throw error;
+        }
+    }
+    return recoverWithPrincipalOutageFallback(recover, options);
+}
+//# sourceMappingURL=principalRecoveryLocalPreference.js.map

package/workflows/principals/principalRecoveryLocalPreference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalRecoveryLocalPreference.js","sourceRoot":"","sources":["principalRecoveryLocalPreference.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,mCAAmC,EAAE,MAAM,+CAA+C,CAAC;AACpG,OAAO,EAAE,6BAA6B,EAAE,MAAM,uDAAuD,CAAC;AACtG,OAAO,EAAE,iCAAiC,EAAE,MAAM,iCAAiC,CAAC;AACpF,OAAO,EAAE,kCAAkC,EAAE,MAAM,2BAA2B,CAAC;AAG/E,6FAA6F;AAC7F,MAAM,CAAC,KAAK,UAAU,mCAAmC,CACvD,OAAmD,EACnD,OAAkE,EAClE,kBAA2B;IAE3B,IAAI,kBAAkB,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3C,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC;gBAC1B,GAAG,OAAO;gBACV,OAAO,EAAE,IAAI;aACd,CAAC,CAAC;YACH,mCAAmC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;YAC1D,IAAI,6BAA6B,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC;gBACtE,OAAO,KAAK,CAAC;QACjB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,mCAAmC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;YAC1D,IACE,CAAC,CAAC,KAAK,YAAY,iCAAiC,CAAC;gBACrD,CAAC,CACC,KAAK,YAAY,uBAAuB;oBACxC,KAAK,CAAC,IAAI,KAAK,oBAAoB,CACpC;gBAED,MAAM,KAAK,CAAC;QAChB,CAAC;IACH,CAAC;IACD,OAAO,kCAAkC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC","sourcesContent":["import { KeyingVerificationError } from \"@tearleads/crypto\";\nimport { assertProjectionVerificationCurrent } from \"../../data/keyingProjectionVerification/types\";\nimport { principalHeadMatchesReference } from \"../../data/principals/organizationAuthorityDescriptor\";\nimport { PrincipalHistoryRecoveryRaceError } from \"./principalHistoryRecoveryTypes\";\nimport { recoverWithPrincipalOutageFallback } from \"./principalRecoveryOutage\";\nimport type { recoverScopedPrincipalPolicyHistory } from \"./recoverScopedPrincipalPolicyHistory\";\n\n/** Reuse authenticated local artifacts only for the exact current head a caller selected. */\nexport async function recoverWithPrincipalLocalPreference(\n  recover: typeof recoverScopedPrincipalPolicyHistory,\n  options: Parameters<typeof recoverScopedPrincipalPolicyHistory>[0],\n  preferLocalCurrent: boolean,\n) {\n  if (preferLocalCurrent && !options.offline) {\n    try {\n      const local = await recover({\n        ...options,\n        offline: true,\n      });\n      assertProjectionVerificationCurrent(options.stillCurrent);\n      if (principalHeadMatchesReference(local.policy.state, options.reference))\n        return local;\n    } catch (error) {\n      assertProjectionVerificationCurrent(options.stillCurrent);\n      if (\n        !(error instanceof PrincipalHistoryRecoveryRaceError) &&\n        !(\n          error instanceof KeyingVerificationError &&\n          error.code === \"missing_dependency\"\n        )\n      )\n        throw error;\n    }\n  }\n  return recoverWithPrincipalOutageFallback(recover, options);\n}\n"]}

package/workflows/principals/principalRecoveryMemo.d.ts

@@ -0,0 +1,16 @@
+import { type ReferencedPrincipalHead } from "../../internal/crypto/index.js";
+import type { RecoveredPrincipalPolicyHistory } from "./principalHistoryRecoveryTypes.js";
+import { type PrincipalRecoveryContext, type RecoveredPolicyDirectory } from "./principalRecoveryDirectory.js";
+type Memo<T> = Map<string, Promise<{
+    value: T;
+    stillCurrent: () => boolean;
+}>>;
+export interface PrincipalRecoveryMemo {
+    readonly directories: Memo<RecoveredPolicyDirectory>;
+    readonly admins: Memo<RecoveredPrincipalPolicyHistory>;
+}
+export declare function createPrincipalRecoveryReader(input: PrincipalRecoveryContext, memo?: PrincipalRecoveryMemo): {
+    directory: (references: readonly ReferencedPrincipalHead[]) => Promise<RecoveredPolicyDirectory>;
+    admins: (expectedHead: ReferencedPrincipalHead, retainedReferences?: readonly ReferencedPrincipalHead[]) => Promise<RecoveredPrincipalPolicyHistory>;
+};
+export {};

package/workflows/principals/principalRecoveryMemo.js

@@ -1,5 +1,6 @@
-import { serializeKeyingCanonicalJson, } from "../../internal/crypto/index.js";
+import { KeyingVerificationError, serializeKeyingCanonicalJson, } from "../../internal/crypto/index.js";
 import { assertProjectionVerificationCurrent } from "../../data/keyingProjectionVerification/types.js";
+import { principalHeadMatchesReference } from "../../data/principals/organizationAuthorityDescriptor.js";
 import { recoverPolicyDirectory, } from "./principalRecoveryDirectory.js";
 import { recoverPrincipalPolicyHistory } from "./recoverPrincipalPolicyHistory.js";
 /** Only share authenticated results within one projection collection lifetime. */
@@ -19,28 +20,99 @@ async function memoPrincipalRecovery(memo, key, stillCurrent, work) {
     assertProjectionVerificationCurrent(stillCurrent);
     return result.value;
 }
+async function readMemoizedAdmins(input, memo, scope, expectedHead, retainedReferences) {
+    // Every recovered Current already retains its own exact head.
+    const references = retainedReferences.filter((reference) => !principalHeadMatchesReference(expectedHead, reference));
+    const key = (selected) => serializeKeyingCanonicalJson([
+        ...scope,
+        { ...expectedHead },
+        selected.map((reference) => ({ ...reference })),
+    ]);
+    const known = memo?.get(key([]));
+    let sourceCurrent = () => true;
+    const current = () => !input.signal?.aborted && input.stillCurrent() && sourceCurrent();
+    return memoPrincipalRecovery(memo, key(references), current, async () => {
+        const options = {
+            ...input,
+            expectedHead,
+            retainedReferences,
+            historyVerification: "direct-admins",
+            stillCurrent: current,
+        };
+        if (known) {
+            sourceCurrent = (await known).stillCurrent;
+            assertProjectionVerificationCurrent(current);
+            try {
+                // A freshly verified exact head only needs local proofs for additional
+                // citations; their signature and private-root checks still run.
+                return await recoverPrincipalPolicyHistory({
+                    ...options,
+                    offline: true,
+                });
+            }
+            catch (error) {
+                assertProjectionVerificationCurrent(current);
+                if (input.offline ||
+                    !(error instanceof KeyingVerificationError) ||
+                    error.code !== "missing_dependency")
+                    throw error;
+            }
+        }
+        return recoverPrincipalPolicyHistory(options);
+    });
+}
+async function readMemoizedDirectory(input, memo, key, references) {
+    const known = references.length > 0 ? memo?.get(key([])) : undefined;
+    let sourceCurrent = () => true;
+    const current = () => !input.signal?.aborted && input.stillCurrent() && sourceCurrent();
+    return memoPrincipalRecovery(memo, key(references), current, async () => {
+        if (!known)
+            return recoverPolicyDirectory(input, references);
+        const source = await known;
+        sourceCurrent = source.stillCurrent;
+        assertProjectionVerificationCurrent(current);
+        try {
+            // Add authenticated historical citations to this batch's exact directory
+            // view. A newer private prefix must not silently replace that view.
+            return await recoverPolicyDirectory({ ...input, offline: true, stillCurrent: current }, references, source.value);
+        }
+        catch (error) {
+            assertProjectionVerificationCurrent(current);
+            if (input.offline ||
+                !(error instanceof KeyingVerificationError) ||
+                error.code !== "missing_dependency")
+                throw error;
+        }
+        return recoverPolicyDirectory({ ...input, stillCurrent: current }, references, source.value);
+    });
+}
 export function createPrincipalRecoveryReader(input, memo) {
     const scope = [
         input.organizationId,
         input.protection.context,
         input.offline === true,
     ];
-    const current = () => !input.signal?.aborted && input.stillCurrent();
+    const directoryKey = (references) => serializeKeyingCanonicalJson([
+        ...scope,
+        references.map((reference) => ({ ...reference })),
+    ]);
     return {
-        directory: (references) => memoPrincipalRecovery(memo?.directories, serializeKeyingCanonicalJson([
-            ...scope,
-            references.map((reference) => ({ ...reference })),
-        ]), current, () => recoverPolicyDirectory(input, references)),
-        admins: (expectedHead, retainedReferences = []) => memoPrincipalRecovery(memo?.admins, serializeKeyingCanonicalJson([
-            ...scope,
-            { ...expectedHead },
-            retainedReferences.map((reference) => ({ ...reference })),
-        ]), current, () => recoverPrincipalPolicyHistory({
-            ...input,
-            expectedHead,
-            retainedReferences,
-            historyVerification: "direct-admins",
-        })),
+        directory: async (references) => {
+            const value = await readMemoizedDirectory(input, memo?.directories, directoryKey, references);
+            // Retaining extra citations does not prevent this authenticated directory
+            // from satisfying a later read with no selected historical references.
+            const unselectedKey = directoryKey([]);
+            const selected = memo?.directories.get(directoryKey(references));
+            if (memo &&
+                selected &&
+                references.length > 0 &&
+                !memo.directories.has(unselectedKey))
+                // Keep the original lease: its expiry requires a new batch, even if
+                // a later caller still has a live lease of its own.
+                memo.directories.set(unselectedKey, selected);
+            return value;
+        },
+        admins: (expectedHead, retainedReferences = []) => readMemoizedAdmins(input, memo?.admins, scope, expectedHead, retainedReferences),
     };
 }
 //# sourceMappingURL=principalRecoveryMemo.js.map

package/workflows/principals/principalRecoveryMemo.js.map

@@ -1 +1 @@
-{"version":3,"file":"principalRecoveryMemo.js","sourceRoot":"","sources":["principalRecoveryMemo.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,4BAA4B,GAC7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mCAAmC,EAAE,MAAM,+CAA+C,CAAC;AAEpG,OAAO,EAGL,sBAAsB,GACvB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAShF,kFAAkF;AAClF,KAAK,UAAU,qBAAqB,CAClC,IAAyB,EACzB,GAAW,EACX,YAA2B,EAC3B,IAAsB;IAEtB,mCAAmC,CAAC,YAAY,CAAC,CAAC;IAClD,IAAI,OAAO,GAAG,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC;QAC5D,IAAI,EAAE,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC1B,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACpD,IAAI,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK,OAAO;YAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjD,MAAM,KAAK,CAAC;IACd,CAAC,CAAC,CAAC;IACH,mCAAmC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACzD,mCAAmC,CAAC,YAAY,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,KAA+B,EAC/B,IAA4B;IAE5B,MAAM,KAAK,GAAG;QACZ,KAAK,CAAC,cAAc;QACpB,KAAK,CAAC,UAAU,CAAC,OAAO;QACxB,KAAK,CAAC,OAAO,KAAK,IAAI;KACvB,CAAC;IACF,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;IACrE,OAAO;QACL,SAAS,EAAE,CAAC,UAA8C,EAAE,EAAE,CAC5D,qBAAqB,CACnB,IAAI,EAAE,WAAW,EACjB,4BAA4B,CAAC;YAC3B,GAAG,KAAK;YACR,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;SAClD,CAAC,EACF,OAAO,EACP,GAAG,EAAE,CAAC,sBAAsB,CAAC,KAAK,EAAE,UAAU,CAAC,CAChD;QACH,MAAM,EAAE,CACN,YAAqC,EACrC,qBAAyD,EAAE,EAC3D,EAAE,CACF,qBAAqB,CACnB,IAAI,EAAE,MAAM,EACZ,4BAA4B,CAAC;YAC3B,GAAG,KAAK;YACR,EAAE,GAAG,YAAY,EAAE;YACnB,kBAAkB,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;SAC1D,CAAC,EACF,OAAO,EACP,GAAG,EAAE,CACH,6BAA6B,CAAC;YAC5B,GAAG,KAAK;YACR,YAAY;YACZ,kBAAkB;YAClB,mBAAmB,EAAE,eAAe;SACrC,CAAC,CACL;KACJ,CAAC;AACJ,CAAC","sourcesContent":["import {\n  type ReferencedPrincipalHead,\n  serializeKeyingCanonicalJson,\n} from \"@tearleads/crypto\";\nimport { assertProjectionVerificationCurrent } from \"../../data/keyingProjectionVerification/types\";\nimport type { RecoveredPrincipalPolicyHistory } from \"./principalHistoryRecoveryTypes\";\nimport {\n  type PrincipalRecoveryContext,\n  type RecoveredPolicyDirectory,\n  recoverPolicyDirectory,\n} from \"./principalRecoveryDirectory\";\nimport { recoverPrincipalPolicyHistory } from \"./recoverPrincipalPolicyHistory\";\n\ntype Memo<T> = Map<string, Promise<{ value: T; stillCurrent: () => boolean }>>;\n\nexport interface PrincipalRecoveryMemo {\n  readonly directories: Memo<RecoveredPolicyDirectory>;\n  readonly admins: Memo<RecoveredPrincipalPolicyHistory>;\n}\n\n/** Only share authenticated results within one projection collection lifetime. */\nasync function memoPrincipalRecovery<T>(\n  memo: Memo<T> | undefined,\n  key: string,\n  stillCurrent: () => boolean,\n  work: () => Promise<T>,\n): Promise<T> {\n  assertProjectionVerificationCurrent(stillCurrent);\n  let pending = memo?.get(key);\n  if (!pending) {\n    pending = work().then((value) => ({ value, stillCurrent }));\n    memo?.set(key, pending);\n  }\n  const result = await pending.catch((error: unknown) => {\n    if (memo?.get(key) === pending) memo.delete(key);\n    throw error;\n  });\n  assertProjectionVerificationCurrent(result.stillCurrent);\n  assertProjectionVerificationCurrent(stillCurrent);\n  return result.value;\n}\n\nexport function createPrincipalRecoveryReader(\n  input: PrincipalRecoveryContext,\n  memo?: PrincipalRecoveryMemo,\n) {\n  const scope = [\n    input.organizationId,\n    input.protection.context,\n    input.offline === true,\n  ];\n  const current = () => !input.signal?.aborted && input.stillCurrent();\n  return {\n    directory: (references: readonly ReferencedPrincipalHead[]) =>\n      memoPrincipalRecovery(\n        memo?.directories,\n        serializeKeyingCanonicalJson([\n          ...scope,\n          references.map((reference) => ({ ...reference })),\n        ]),\n        current,\n        () => recoverPolicyDirectory(input, references),\n      ),\n    admins: (\n      expectedHead: ReferencedPrincipalHead,\n      retainedReferences: readonly ReferencedPrincipalHead[] = [],\n    ) =>\n      memoPrincipalRecovery(\n        memo?.admins,\n        serializeKeyingCanonicalJson([\n          ...scope,\n          { ...expectedHead },\n          retainedReferences.map((reference) => ({ ...reference })),\n        ]),\n        current,\n        () =>\n          recoverPrincipalPolicyHistory({\n            ...input,\n            expectedHead,\n            retainedReferences,\n            historyVerification: \"direct-admins\",\n          }),\n      ),\n  };\n}\n"]}
+{"version":3,"file":"principalRecoveryMemo.js","sourceRoot":"","sources":["principalRecoveryMemo.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  KeyingVerificationError,\n  type ReferencedPrincipalHead,\n  serializeKeyingCanonicalJson,\n} from \"@tearleads/crypto\";\nimport { assertProjectionVerificationCurrent } from \"../../data/keyingProjectionVerification/types\";\nimport { principalHeadMatchesReference } from \"../../data/principals/organizationAuthorityDescriptor\";\nimport type { RecoveredPrincipalPolicyHistory } from \"./principalHistoryRecoveryTypes\";\nimport {\n  type PrincipalRecoveryContext,\n  type RecoveredPolicyDirectory,\n  recoverPolicyDirectory,\n} from \"./principalRecoveryDirectory\";\nimport { recoverPrincipalPolicyHistory } from \"./recoverPrincipalPolicyHistory\";\n\ntype Memo<T> = Map<string, Promise<{ value: T; stillCurrent: () => boolean }>>;\n\nexport interface PrincipalRecoveryMemo {\n  readonly directories: Memo<RecoveredPolicyDirectory>;\n  readonly admins: Memo<RecoveredPrincipalPolicyHistory>;\n}\n\n/** Only share authenticated results within one projection collection lifetime. */\nasync function memoPrincipalRecovery<T>(\n  memo: Memo<T> | undefined,\n  key: string,\n  stillCurrent: () => boolean,\n  work: () => Promise<T>,\n): Promise<T> {\n  assertProjectionVerificationCurrent(stillCurrent);\n  let pending = memo?.get(key);\n  if (!pending) {\n    pending = work().then((value) => ({ value, stillCurrent }));\n    memo?.set(key, pending);\n  }\n  const result = await pending.catch((error: unknown) => {\n    if (memo?.get(key) === pending) memo.delete(key);\n    throw error;\n  });\n  assertProjectionVerificationCurrent(result.stillCurrent);\n  assertProjectionVerificationCurrent(stillCurrent);\n  return result.value;\n}\n\nasync function readMemoizedAdmins(\n  input: PrincipalRecoveryContext,\n  memo: Memo<RecoveredPrincipalPolicyHistory> | undefined,\n  scope: readonly (string | boolean)[],\n  expectedHead: ReferencedPrincipalHead,\n  retainedReferences: readonly ReferencedPrincipalHead[],\n) {\n  // Every recovered Current already retains its own exact head.\n  const references = retainedReferences.filter(\n    (reference) => !principalHeadMatchesReference(expectedHead, reference),\n  );\n  const key = (selected: readonly ReferencedPrincipalHead[]) =>\n    serializeKeyingCanonicalJson([\n      ...scope,\n      { ...expectedHead },\n      selected.map((reference) => ({ ...reference })),\n    ]);\n  const known = memo?.get(key([]));\n  let sourceCurrent = () => true;\n  const current = () =>\n    !input.signal?.aborted && input.stillCurrent() && sourceCurrent();\n  return memoPrincipalRecovery(memo, key(references), current, async () => {\n    const options = {\n      ...input,\n      expectedHead,\n      retainedReferences,\n      historyVerification: \"direct-admins\" as const,\n      stillCurrent: current,\n    };\n    if (known) {\n      sourceCurrent = (await known).stillCurrent;\n      assertProjectionVerificationCurrent(current);\n      try {\n        // A freshly verified exact head only needs local proofs for additional\n        // citations; their signature and private-root checks still run.\n        return await recoverPrincipalPolicyHistory({\n          ...options,\n          offline: true,\n        });\n      } catch (error) {\n        assertProjectionVerificationCurrent(current);\n        if (\n          input.offline ||\n          !(error instanceof KeyingVerificationError) ||\n          error.code !== \"missing_dependency\"\n        )\n          throw error;\n      }\n    }\n    return recoverPrincipalPolicyHistory(options);\n  });\n}\n\nasync function readMemoizedDirectory(\n  input: PrincipalRecoveryContext,\n  memo: Memo<RecoveredPolicyDirectory> | undefined,\n  key: (references: readonly ReferencedPrincipalHead[]) => string,\n  references: readonly ReferencedPrincipalHead[],\n) {\n  const known = references.length > 0 ? memo?.get(key([])) : undefined;\n  let sourceCurrent = () => true;\n  const current = () =>\n    !input.signal?.aborted && input.stillCurrent() && sourceCurrent();\n  return memoPrincipalRecovery(memo, key(references), current, async () => {\n    if (!known) return recoverPolicyDirectory(input, references);\n    const source = await known;\n    sourceCurrent = source.stillCurrent;\n    assertProjectionVerificationCurrent(current);\n    try {\n      // Add authenticated historical citations to this batch's exact directory\n      // view. A newer private prefix must not silently replace that view.\n      return await recoverPolicyDirectory(\n        { ...input, offline: true, stillCurrent: current },\n        references,\n        source.value,\n      );\n    } catch (error) {\n      assertProjectionVerificationCurrent(current);\n      if (\n        input.offline ||\n        !(error instanceof KeyingVerificationError) ||\n        error.code !== \"missing_dependency\"\n      )\n        throw error;\n    }\n    return recoverPolicyDirectory(\n      { ...input, stillCurrent: current },\n      references,\n      source.value,\n    );\n  });\n}\n\nexport function createPrincipalRecoveryReader(\n  input: PrincipalRecoveryContext,\n  memo?: PrincipalRecoveryMemo,\n) {\n  const scope = [\n    input.organizationId,\n    input.protection.context,\n    input.offline === true,\n  ];\n  const directoryKey = (references: readonly ReferencedPrincipalHead[]) =>\n    serializeKeyingCanonicalJson([\n      ...scope,\n      references.map((reference) => ({ ...reference })),\n    ]);\n  return {\n    directory: async (references: readonly ReferencedPrincipalHead[]) => {\n      const value = await readMemoizedDirectory(\n        input,\n        memo?.directories,\n        directoryKey,\n        references,\n      );\n      // Retaining extra citations does not prevent this authenticated directory\n      // from satisfying a later read with no selected historical references.\n      const unselectedKey = directoryKey([]);\n      const selected = memo?.directories.get(directoryKey(references));\n      if (\n        memo &&\n        selected &&\n        references.length > 0 &&\n        !memo.directories.has(unselectedKey)\n      )\n        // Keep the original lease: its expiry requires a new batch, even if\n        // a later caller still has a live lease of its own.\n        memo.directories.set(unselectedKey, selected);\n      return value;\n    },\n    admins: (\n      expectedHead: ReferencedPrincipalHead,\n      retainedReferences: readonly ReferencedPrincipalHead[] = [],\n    ) =>\n      readMemoizedAdmins(\n        input,\n        memo?.admins,\n        scope,\n        expectedHead,\n        retainedReferences,\n      ),\n  };\n}\n"]}

package/workflows/principals/principalRecoveryOutage.js

@@ -4,7 +4,7 @@ import { assertProjectionVerificationCurrent } from "../../data/keyingProjection
 import { PrincipalPolicyHistoryReadError } from "./principalHistoryRecoveryTypes.js";
 import { recoverScopedPrincipalPolicyHistory } from "./recoverScopedPrincipalPolicyHistory.js";
 /** Refusals and invalid evidence must never silently select a cached policy. */
-function isPrincipalRecoveryOutage(error) {
+export function isPrincipalRecoveryOutage(error) {
     if (!(error instanceof PrincipalPolicyHistoryReadError))
         return false;
     const { failure } = error;

package/workflows/principals/principalRecoveryOutage.js.map

@@ -1 +1 @@
-{"version":3,"file":"principalRecoveryOutage.js","sourceRoot":"","sources":["principalRecoveryOutage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,oCAAoC,EAAE,MAAM,+DAA+D,CAAC;AACrH,OAAO,EAAE,mCAAmC,EAAE,MAAM,+CAA+C,CAAC;AACpG,OAAO,EAAE,+BAA+B,EAAE,MAAM,iCAAiC,CAAC;AAClF,OAAO,EAAE,mCAAmC,EAAE,MAAM,uCAAuC,CAAC;AAE5F,gFAAgF;AAChF,SAAS,yBAAyB,CAAC,KAAc;IAC/C,IAAI,CAAC,CAAC,KAAK,YAAY,+BAA+B,CAAC;QAAE,OAAO,KAAK,CAAC;IACtE,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAC1B,OAAO,CACL,OAAO,CAAC,IAAI,KAAK,SAAS;QAC1B,CAAC,OAAO,CAAC,IAAI,KAAK,MAAM;YACtB,OAAO,CAAC,MAAM,KAAK,IAAI;YACvB,OAAO,CAAC,MAAM,IAAI,GAAG,CAAC;QACxB,CAAC,OAAO,CAAC,IAAI,KAAK,WAAW;YAC3B,OAAO,CAAC,IAAI,KAAK,qCAAqC,CAAC,CAC1D,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kCAAkC,CACtD,OAAmD,EACnD,OAAkE;IAElE,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,mCAAmC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAC1D,IAAI,OAAO,CAAC,OAAO,IAAI,CAAC,yBAAyB,CAAC,KAAK,CAAC;YAAE,MAAM,KAAK,CAAC;QACtE,IAAI,CAAC;YACH,OAAO,MAAM,mCAAmC,CAAC;gBAC/C,GAAG,OAAO;gBACV,OAAO,EAAE,IAAI;aACd,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,UAAU,EAAE,CAAC;YACpB,IACE,UAAU,YAAY,uBAAuB;gBAC7C,UAAU,CAAC,IAAI,KAAK,oBAAoB;gBAExC,MAAM,IAAI,oCAAoC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YACrE,MAAM,UAAU,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC","sourcesContent":["import { KeyingVerificationError } from \"@tearleads/crypto\";\nimport { ProjectionDependencyUnavailableError } from \"../../data/keyingProjectionVerification/dependencyUnavailable\";\nimport { assertProjectionVerificationCurrent } from \"../../data/keyingProjectionVerification/types\";\nimport { PrincipalPolicyHistoryReadError } from \"./principalHistoryRecoveryTypes\";\nimport { recoverScopedPrincipalPolicyHistory } from \"./recoverScopedPrincipalPolicyHistory\";\n\n/** Refusals and invalid evidence must never silently select a cached policy. */\nfunction isPrincipalRecoveryOutage(error: unknown): boolean {\n  if (!(error instanceof PrincipalPolicyHistoryReadError)) return false;\n  const { failure } = error;\n  return (\n    failure.kind === \"network\" ||\n    (failure.kind === \"http\" &&\n      failure.status !== null &&\n      failure.status >= 500) ||\n    (failure.kind === \"cancelled\" &&\n      failure.code === \"principal_history_request_timed_out\")\n  );\n}\n\nexport async function recoverWithPrincipalOutageFallback(\n  recover: typeof recoverScopedPrincipalPolicyHistory,\n  options: Parameters<typeof recoverScopedPrincipalPolicyHistory>[0],\n) {\n  try {\n    return await recover(options);\n  } catch (error) {\n    assertProjectionVerificationCurrent(options.stillCurrent);\n    if (options.offline || !isPrincipalRecoveryOutage(error)) throw error;\n    try {\n      return await recoverScopedPrincipalPolicyHistory({\n        ...options,\n        offline: true,\n      });\n    } catch (localError) {\n      if (\n        localError instanceof KeyingVerificationError &&\n        localError.code === \"missing_dependency\"\n      )\n        throw new ProjectionDependencyUnavailableError(localError.message);\n      throw localError;\n    }\n  }\n}\n"]}
+{"version":3,"file":"principalRecoveryOutage.js","sourceRoot":"","sources":["principalRecoveryOutage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,oCAAoC,EAAE,MAAM,+DAA+D,CAAC;AACrH,OAAO,EAAE,mCAAmC,EAAE,MAAM,+CAA+C,CAAC;AACpG,OAAO,EAAE,+BAA+B,EAAE,MAAM,iCAAiC,CAAC;AAClF,OAAO,EAAE,mCAAmC,EAAE,MAAM,uCAAuC,CAAC;AAE5F,gFAAgF;AAChF,MAAM,UAAU,yBAAyB,CAAC,KAAc;IACtD,IAAI,CAAC,CAAC,KAAK,YAAY,+BAA+B,CAAC;QAAE,OAAO,KAAK,CAAC;IACtE,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAC1B,OAAO,CACL,OAAO,CAAC,IAAI,KAAK,SAAS;QAC1B,CAAC,OAAO,CAAC,IAAI,KAAK,MAAM;YACtB,OAAO,CAAC,MAAM,KAAK,IAAI;YACvB,OAAO,CAAC,MAAM,IAAI,GAAG,CAAC;QACxB,CAAC,OAAO,CAAC,IAAI,KAAK,WAAW;YAC3B,OAAO,CAAC,IAAI,KAAK,qCAAqC,CAAC,CAC1D,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kCAAkC,CACtD,OAAmD,EACnD,OAAkE;IAElE,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,mCAAmC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAC1D,IAAI,OAAO,CAAC,OAAO,IAAI,CAAC,yBAAyB,CAAC,KAAK,CAAC;YAAE,MAAM,KAAK,CAAC;QACtE,IAAI,CAAC;YACH,OAAO,MAAM,mCAAmC,CAAC;gBAC/C,GAAG,OAAO;gBACV,OAAO,EAAE,IAAI;aACd,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,UAAU,EAAE,CAAC;YACpB,IACE,UAAU,YAAY,uBAAuB;gBAC7C,UAAU,CAAC,IAAI,KAAK,oBAAoB;gBAExC,MAAM,IAAI,oCAAoC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YACrE,MAAM,UAAU,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC","sourcesContent":["import { KeyingVerificationError } from \"@tearleads/crypto\";\nimport { ProjectionDependencyUnavailableError } from \"../../data/keyingProjectionVerification/dependencyUnavailable\";\nimport { assertProjectionVerificationCurrent } from \"../../data/keyingProjectionVerification/types\";\nimport { PrincipalPolicyHistoryReadError } from \"./principalHistoryRecoveryTypes\";\nimport { recoverScopedPrincipalPolicyHistory } from \"./recoverScopedPrincipalPolicyHistory\";\n\n/** Refusals and invalid evidence must never silently select a cached policy. */\nexport function isPrincipalRecoveryOutage(error: unknown): boolean {\n  if (!(error instanceof PrincipalPolicyHistoryReadError)) return false;\n  const { failure } = error;\n  return (\n    failure.kind === \"network\" ||\n    (failure.kind === \"http\" &&\n      failure.status !== null &&\n      failure.status >= 500) ||\n    (failure.kind === \"cancelled\" &&\n      failure.code === \"principal_history_request_timed_out\")\n  );\n}\n\nexport async function recoverWithPrincipalOutageFallback(\n  recover: typeof recoverScopedPrincipalPolicyHistory,\n  options: Parameters<typeof recoverScopedPrincipalPolicyHistory>[0],\n) {\n  try {\n    return await recover(options);\n  } catch (error) {\n    assertProjectionVerificationCurrent(options.stillCurrent);\n    if (options.offline || !isPrincipalRecoveryOutage(error)) throw error;\n    try {\n      return await recoverScopedPrincipalPolicyHistory({\n        ...options,\n        offline: true,\n      });\n    } catch (localError) {\n      if (\n        localError instanceof KeyingVerificationError &&\n        localError.code === \"missing_dependency\"\n      )\n        throw new ProjectionDependencyUnavailableError(localError.message);\n      throw localError;\n    }\n  }\n}\n"]}

package/workflows/principals/publicPrincipalHistoryAuthority.js

@@ -0,0 +1,60 @@
+import { KeyingVerificationError, serializeKeyingCanonicalJson, } from "../../internal/crypto/index.js";
+import { isReferencedPrincipalStateResponse } from "../../internal/validators/response/index.js";
+import { principalHeadMatchesReference } from "../../data/principals/organizationAuthorityDescriptor.js";
+/** The greatest cited Admins head commits to the lineage of every earlier citation. */
+export function publicHistoryAuthorityReference(previous, references) {
+    return references.reduce((head, reference) => !head || reference.version > head.version ? reference : head, previous);
+}
+export function publicHistoryAuthorityJson(reference) {
+    return serializeKeyingCanonicalJson(reference ? { ...reference } : null);
+}
+export function parsePublicHistoryAuthority(input, json) {
+    try {
+        const value = JSON.parse(json);
+        if (value === null)
+            return null;
+        if (isReferencedPrincipalStateResponse(value) &&
+            value.principalType === "group" &&
+            value.principalId === input.authorityGroupId)
+            return value;
+    }
+    catch {
+        /* Invalid disposable metadata cannot restore verified progress. */
+    }
+    return undefined;
+}
+export async function loadPublicHistoryAuthority(input, references, cachedPrefix = false) {
+    if (!references.length)
+        return undefined;
+    const authority = await input.loadExternalAuthority?.(references, cachedPrefix);
+    if (authority &&
+        (authority.currentHead.principalId !== input.authorityGroupId ||
+            authority.states.some(({ head }) => head.principalId !== input.authorityGroupId)))
+        throw new KeyingVerificationError("object_mismatch", "Authority callback differs from the directory binding");
+    if (references.some((reference) => !authority?.states.some(({ head }) => principalHeadMatchesReference(head, reference))))
+        throw new KeyingVerificationError("stale_predecessor", "Public history authority differs from its verified Admins lineage");
+    return authority;
+}
+export async function validatePublicHistoryAuthority(input, reference, rejectedPrefix = null) {
+    try {
+        if (reference)
+            await loadPublicHistoryAuthority(input, [reference], true);
+    }
+    catch (error) {
+        if (error instanceof KeyingVerificationError)
+            throw new PublicHistoryAuthorityUnavailableError(error, rejectedPrefix);
+        throw error;
+    }
+}
+/** Only cache restoration can request a replay after an authority mismatch. */
+export class PublicHistoryAuthorityUnavailableError extends Error {
+    verificationError;
+    rejectedPrefix;
+    constructor(verificationError, rejectedPrefix) {
+        super(verificationError.message);
+        this.verificationError = verificationError;
+        this.rejectedPrefix = rejectedPrefix;
+        this.name = "PublicHistoryAuthorityUnavailableError";
+    }
+}
+//# sourceMappingURL=publicPrincipalHistoryAuthority.js.map

package/workflows/principals/publicPrincipalHistoryAuthority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publicPrincipalHistoryAuthority.js","sourceRoot":"","sources":["publicPrincipalHistoryAuthority.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  KeyingVerificationError,\n  type ReferencedPrincipalHead,\n  serializeKeyingCanonicalJson,\n} from \"@tearleads/crypto\";\nimport { isReferencedPrincipalStateResponse } from \"@tearleads/validators/response\";\nimport type { PrincipalHistoryPrefix } from \"../../data/persistence/principalHistoryPrefixPersistence\";\nimport { principalHeadMatchesReference } from \"../../data/principals/organizationAuthorityDescriptor\";\nimport type { PublicPrincipalHistoryOptions } from \"./publicPrincipalHistoryTypes\";\n\n/** The greatest cited Admins head commits to the lineage of every earlier citation. */\nexport function publicHistoryAuthorityReference(\n  previous: ReferencedPrincipalHead | null,\n  references: readonly ReferencedPrincipalHead[],\n) {\n  return references.reduce<ReferencedPrincipalHead | null>(\n    (head, reference) =>\n      !head || reference.version > head.version ? reference : head,\n    previous,\n  );\n}\n\nexport function publicHistoryAuthorityJson(\n  reference: ReferencedPrincipalHead | null,\n) {\n  return serializeKeyingCanonicalJson(reference ? { ...reference } : null);\n}\n\nexport function parsePublicHistoryAuthority(\n  input: PublicPrincipalHistoryOptions,\n  json: string,\n): ReferencedPrincipalHead | null | undefined {\n  try {\n    const value: unknown = JSON.parse(json);\n    if (value === null) return null;\n    if (\n      isReferencedPrincipalStateResponse(value) &&\n      value.principalType === \"group\" &&\n      value.principalId === input.authorityGroupId\n    )\n      return value;\n  } catch {\n    /* Invalid disposable metadata cannot restore verified progress. */\n  }\n  return undefined;\n}\n\nexport async function loadPublicHistoryAuthority(\n  input: PublicPrincipalHistoryOptions,\n  references: readonly ReferencedPrincipalHead[],\n  cachedPrefix = false,\n) {\n  if (!references.length) return undefined;\n  const authority = await input.loadExternalAuthority?.(\n    references,\n    cachedPrefix,\n  );\n  if (\n    authority &&\n    (authority.currentHead.principalId !== input.authorityGroupId ||\n      authority.states.some(\n        ({ head }) => head.principalId !== input.authorityGroupId,\n      ))\n  )\n    throw new KeyingVerificationError(\n      \"object_mismatch\",\n      \"Authority callback differs from the directory binding\",\n    );\n  if (\n    references.some(\n      (reference) =>\n        !authority?.states.some(({ head }) =>\n          principalHeadMatchesReference(head, reference),\n        ),\n    )\n  )\n    throw new KeyingVerificationError(\n      \"stale_predecessor\",\n      \"Public history authority differs from its verified Admins lineage\",\n    );\n  return authority;\n}\n\nexport async function validatePublicHistoryAuthority(\n  input: PublicPrincipalHistoryOptions,\n  reference: ReferencedPrincipalHead | null,\n  rejectedPrefix: PrincipalHistoryPrefix | null = null,\n): Promise<void> {\n  try {\n    if (reference) await loadPublicHistoryAuthority(input, [reference], true);\n  } catch (error) {\n    if (error instanceof KeyingVerificationError)\n      throw new PublicHistoryAuthorityUnavailableError(error, rejectedPrefix);\n    throw error;\n  }\n}\n\n/** Only cache restoration can request a replay after an authority mismatch. */\nexport class PublicHistoryAuthorityUnavailableError extends Error {\n  constructor(\n    readonly verificationError: KeyingVerificationError,\n    readonly rejectedPrefix: PrincipalHistoryPrefix | null,\n  ) {\n    super(verificationError.message);\n    this.name = \"PublicHistoryAuthorityUnavailableError\";\n  }\n}\n"]}

package/workflows/principals/publicPrincipalHistoryPage.js

@@ -0,0 +1,87 @@
+import { KeyingVerificationError, } from "../../internal/crypto/index.js";
+import { assertProjectionVerificationCurrent } from "../../data/keyingProjectionVerification/types.js";
+import { preparePrincipalHistoryEvidencePage } from "../../data/persistence/principalHistoryEvidencePersistence.js";
+import { savePrincipalHistoryStage } from "../../data/persistence/principalHistoryStagePersistence.js";
+import { principalHistoryStageProtection } from "../../data/principals/principalHistoryStageProtection.js";
+import { collectPrincipalPolicySignerPublicKeys } from "./policyVerification.js";
+import { loadPublicHistoryAuthority, publicHistoryAuthorityJson, publicHistoryAuthorityReference, } from "./publicPrincipalHistoryAuthority.js";
+export class PublicPrincipalHistoryPrefixDisconnectedError extends Error {
+    verificationError;
+    constructor(verificationError) {
+        super(verificationError.message);
+        this.verificationError = verificationError;
+        this.name = "PublicPrincipalHistoryPrefixDisconnectedError";
+    }
+}
+function assertPublicAuthorityScope(input, entries) {
+    if (input.strictAdmins &&
+        entries.some((entry) => entry.projection.length === 0 ||
+            entry.projection.some((member) => member.role !== "admin")))
+        throw new KeyingVerificationError("invalid_shape", "Public Admins history must contain only direct admin users");
+    if (entries.some(({ state }) => state.externalAuthority &&
+        state.externalAuthority.principalId !== input.authorityGroupId))
+        throw new KeyingVerificationError("object_mismatch", "Public history cites an authority outside its directory binding");
+}
+export async function appendPublicPrincipalHistoryPage(input, progress, page) {
+    const stillCurrent = () => !input.signal?.aborted && input.stillCurrent();
+    const complete = page.historyPage.nextAfterVersion === null;
+    const entries = [...page.previousStates];
+    if (complete)
+        entries.push({
+            state: page.currentState,
+            projection: page.currentProjection,
+            grants: page.currentGrants,
+        });
+    assertPublicAuthorityScope(input, entries);
+    const keys = await collectPrincipalPolicySignerPublicKeys({
+        bundle: page,
+        resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,
+    });
+    if ("error" in keys)
+        throw new KeyingVerificationError(keys.error === "not-found" ? "missing_dependency" : "signer_mismatch", "Public history signer identity is unavailable or mismatched");
+    const references = entries.flatMap(({ state }) => state.externalAuthority ? [state.externalAuthority] : []);
+    const externalAuthority = await loadPublicHistoryAuthority(input, references);
+    assertProjectionVerificationCurrent(stillCurrent);
+    const appended = await progress.verifier.append({
+        entries,
+        signerPublicKeys: keys.signerPublicKeys,
+        ...(externalAuthority ? { externalAuthority } : {}),
+    });
+    if (!appended.ok) {
+        if (appended.error.code === "stale_predecessor")
+            throw new PublicPrincipalHistoryPrefixDisconnectedError(appended.error);
+        throw appended.error;
+    }
+    const row = {
+        id: progress.id,
+        organizationId: input.organizationId,
+        currentJson: publicHistoryAuthorityJson(publicHistoryAuthorityReference(progress.authorityReference, references)),
+        afterVersion: appended.value.throughVersion - (complete ? 1 : 0),
+        complete,
+    };
+    const sealed = await progress.verifier.exportProgress(await principalHistoryStageProtection(input.protection, input.source.head, row));
+    if (!sealed.ok)
+        throw sealed.error;
+    const saved = { ...row, progress: sealed.value };
+    await savePrincipalHistoryStage({
+        execSql: input.execSql,
+        stage: saved,
+        evidence: await preparePrincipalHistoryEvidencePage({
+            scopeId: progress.scopeId,
+            organizationId: input.organizationId,
+            entries,
+            nodes: appended.value.indexNodes,
+        }),
+        previousProgress: progress.saved?.progress ?? null,
+        stillCurrent,
+    });
+    assertProjectionVerificationCurrent(stillCurrent);
+    return {
+        ...progress,
+        afterVersion: row.afterVersion,
+        saved,
+        authorityReference: publicHistoryAuthorityReference(progress.authorityReference, references),
+        completedHead: complete ? input.source.head : null,
+    };
+}
+//# sourceMappingURL=publicPrincipalHistoryPage.js.map

package/workflows/principals/publicPrincipalHistoryPage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publicPrincipalHistoryPage.js","sourceRoot":"","sources":["publicPrincipalHistoryPage.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  KeyingVerificationError,\n  type PrincipalPolicyStateChainEntry,\n} from \"@tearleads/crypto\";\nimport type { PrincipalPolicySnapshotPageResponse } from \"@tearleads/validators/response\";\nimport { assertProjectionVerificationCurrent } from \"../../data/keyingProjectionVerification/types\";\nimport { preparePrincipalHistoryEvidencePage } from \"../../data/persistence/principalHistoryEvidencePersistence\";\nimport { savePrincipalHistoryStage } from \"../../data/persistence/principalHistoryStagePersistence\";\nimport { principalHistoryStageProtection } from \"../../data/principals/principalHistoryStageProtection\";\nimport { collectPrincipalPolicySignerPublicKeys } from \"./policyVerification\";\nimport {\n  loadPublicHistoryAuthority,\n  publicHistoryAuthorityJson,\n  publicHistoryAuthorityReference,\n} from \"./publicPrincipalHistoryAuthority\";\nimport type {\n  PublicPrincipalHistoryOptions,\n  PublicPrincipalHistoryProgress,\n} from \"./publicPrincipalHistoryTypes\";\n\nexport class PublicPrincipalHistoryPrefixDisconnectedError extends Error {\n  constructor(readonly verificationError: KeyingVerificationError) {\n    super(verificationError.message);\n    this.name = \"PublicPrincipalHistoryPrefixDisconnectedError\";\n  }\n}\n\nfunction assertPublicAuthorityScope(\n  input: PublicPrincipalHistoryOptions,\n  entries: readonly PrincipalPolicyStateChainEntry[],\n): void {\n  if (\n    input.strictAdmins &&\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      \"Public Admins history must contain only direct admin users\",\n    );\n  if (\n    entries.some(\n      ({ state }) =>\n        state.externalAuthority &&\n        state.externalAuthority.principalId !== input.authorityGroupId,\n    )\n  )\n    throw new KeyingVerificationError(\n      \"object_mismatch\",\n      \"Public history cites an authority outside its directory binding\",\n    );\n}\n\nexport async function appendPublicPrincipalHistoryPage(\n  input: PublicPrincipalHistoryOptions,\n  progress: PublicPrincipalHistoryProgress,\n  page: PrincipalPolicySnapshotPageResponse,\n): Promise<PublicPrincipalHistoryProgress> {\n  const stillCurrent = () => !input.signal?.aborted && input.stillCurrent();\n  const complete = page.historyPage.nextAfterVersion === null;\n  const entries = [...page.previousStates];\n  if (complete)\n    entries.push({\n      state: page.currentState,\n      projection: page.currentProjection,\n      grants: page.currentGrants,\n    });\n  assertPublicAuthorityScope(input, entries);\n  const keys = await collectPrincipalPolicySignerPublicKeys({\n    bundle: page,\n    resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,\n  });\n  if (\"error\" in keys)\n    throw new KeyingVerificationError(\n      keys.error === \"not-found\" ? \"missing_dependency\" : \"signer_mismatch\",\n      \"Public history signer identity is unavailable or mismatched\",\n    );\n  const references = entries.flatMap(({ state }) =>\n    state.externalAuthority ? [state.externalAuthority] : [],\n  );\n  const externalAuthority = await loadPublicHistoryAuthority(input, references);\n  assertProjectionVerificationCurrent(stillCurrent);\n  const appended = await progress.verifier.append({\n    entries,\n    signerPublicKeys: keys.signerPublicKeys,\n    ...(externalAuthority ? { externalAuthority } : {}),\n  });\n  if (!appended.ok) {\n    if (appended.error.code === \"stale_predecessor\")\n      throw new PublicPrincipalHistoryPrefixDisconnectedError(appended.error);\n    throw appended.error;\n  }\n  const row = {\n    id: progress.id,\n    organizationId: input.organizationId,\n    currentJson: publicHistoryAuthorityJson(\n      publicHistoryAuthorityReference(progress.authorityReference, references),\n    ),\n    afterVersion: appended.value.throughVersion - (complete ? 1 : 0),\n    complete,\n  };\n  const sealed = await progress.verifier.exportProgress(\n    await principalHistoryStageProtection(\n      input.protection,\n      input.source.head,\n      row,\n    ),\n  );\n  if (!sealed.ok) throw sealed.error;\n  const saved = { ...row, progress: sealed.value };\n  await savePrincipalHistoryStage({\n    execSql: input.execSql,\n    stage: saved,\n    evidence: await preparePrincipalHistoryEvidencePage({\n      scopeId: progress.scopeId,\n      organizationId: input.organizationId,\n      entries,\n      nodes: appended.value.indexNodes,\n    }),\n    previousProgress: progress.saved?.progress ?? null,\n    stillCurrent,\n  });\n  assertProjectionVerificationCurrent(stillCurrent);\n  return {\n    ...progress,\n    afterVersion: row.afterVersion,\n    saved,\n    authorityReference: publicHistoryAuthorityReference(\n      progress.authorityReference,\n      references,\n    ),\n    completedHead: complete ? input.source.head : null,\n  };\n}\n"]}

package/workflows/principals/publicPrincipalHistoryProgress.js

@@ -0,0 +1,178 @@
+import { createPrincipalPolicyHistoryVerifier, KeyingVerificationError, restorePrincipalPolicyHistoryVerifier, serializeKeyingCanonicalJson, verifyPrincipalPolicyHistoryReferences, } from "../../internal/crypto/index.js";
+import { isReferencedPrincipalStateResponse } from "../../internal/validators/response/index.js";
+import { loadPrincipalHistoryReference } from "../../data/persistence/principalHistoryEvidencePersistence.js";
+import { discardPrincipalHistoryPrefix, loadPrincipalHistoryPrefix, savePrincipalHistoryPrefix, } from "../../data/persistence/principalHistoryPrefixPersistence.js";
+import { discardPrincipalHistoryStage, loadPrincipalHistoryStage, } from "../../data/persistence/principalHistoryStagePersistence.js";
+import { principalHeadMatchesReference } from "../../data/principals/organizationAuthorityDescriptor.js";
+import { principalHistoryEvidenceScopeId, principalHistoryPrefixProtection, } from "../../data/principals/principalHistoryPrefixProtection.js";
+import { principalHistoryStageId, principalHistoryStageProtection, } from "../../data/principals/principalHistoryStageProtection.js";
+import { PublicHistoryAuthorityUnavailableError, parsePublicHistoryAuthority, publicHistoryAuthorityJson, validatePublicHistoryAuthority, } from "./publicPrincipalHistoryAuthority.js";
+async function restorePublicPrefix(input, scopeId, id, prefix) {
+    const head = input.source.head;
+    const historyInput = {
+        principalType: head.principalType,
+        principalId: head.principalId,
+    };
+    const current = () => !input.signal?.aborted && input.stillCurrent();
+    if (prefix) {
+        const authorityReference = parsePublicHistoryAuthority(input, prefix.currentJson);
+        let prefixHead;
+        try {
+            prefixHead = JSON.parse(prefix.headJson);
+        }
+        catch {
+            prefixHead = null;
+        }
+        if (prefix.organizationId === input.organizationId &&
+            authorityReference !== undefined &&
+            isReferencedPrincipalStateResponse(prefixHead) &&
+            prefixHead.principalId === head.principalId &&
+            prefixHead.principalType === head.principalType &&
+            prefixHead.version === prefix.version) {
+            const restored = await restorePrincipalPolicyHistoryVerifier(historyInput, prefix.progress, await principalHistoryPrefixProtection(input.protection, prefix));
+            if (restored.ok && restored.value.finish(prefixHead).ok) {
+                await validatePublicHistoryAuthority(input, authorityReference, prefix);
+                return {
+                    id,
+                    scopeId,
+                    verifier: restored.value,
+                    completedHead: prefixHead.version >= head.version ? prefixHead : null,
+                    afterVersion: Math.min(prefixHead.version, head.version - 1),
+                    saved: null,
+                    cachedPrefix: prefix,
+                    authorityReference,
+                };
+            }
+        }
+        if (!input.offline)
+            await discardPrincipalHistoryPrefix({
+                execSql: input.execSql,
+                prefix,
+                stillCurrent: current,
+            });
+    }
+    return null;
+}
+export async function restorePublicPrincipalHistoryProgress(input, allowReuse) {
+    const head = input.source.head;
+    const historyInput = {
+        principalType: head.principalType,
+        principalId: head.principalId,
+    };
+    const scopeId = await principalHistoryEvidenceScopeId({
+        organizationId: input.organizationId,
+        head,
+        protection: input.protection,
+    });
+    const id = await principalHistoryStageId(input.organizationId, head, input.protection.context);
+    const current = () => !input.signal?.aborted && input.stillCurrent();
+    const saved = await loadPrincipalHistoryStage(input.execSql, id);
+    if (saved) {
+        const authorityReference = parsePublicHistoryAuthority(input, saved.currentJson);
+        if (allowReuse &&
+            saved.organizationId === input.organizationId &&
+            authorityReference !== undefined) {
+            const restored = await restorePrincipalPolicyHistoryVerifier(historyInput, saved.progress, await principalHistoryStageProtection(input.protection, head, saved));
+            if (restored.ok && (!saved.complete || restored.value.finish(head).ok)) {
+                await validatePublicHistoryAuthority(input, authorityReference);
+                return {
+                    id,
+                    scopeId,
+                    verifier: restored.value,
+                    completedHead: saved.complete ? head : null,
+                    afterVersion: saved.afterVersion,
+                    saved,
+                    cachedPrefix: null,
+                    authorityReference,
+                };
+            }
+        }
+        if (!input.offline)
+            await discardPrincipalHistoryStage(input.execSql, saved, current);
+    }
+    if (allowReuse) {
+        const prefix = await restorePublicPrefix(input, scopeId, id, await loadPrincipalHistoryPrefix(input.execSql, scopeId));
+        if (prefix)
+            return prefix;
+    }
+    return {
+        id,
+        scopeId,
+        verifier: createPrincipalPolicyHistoryVerifier(historyInput),
+        completedHead: null,
+        afterVersion: 0,
+        saved: null,
+        cachedPrefix: null,
+        authorityReference: null,
+    };
+}
+/** A resumed stage may finish after the reader that rejected the prefix exits. */
+async function rejectedCompletedPrefix(input, progress, history) {
+    const candidate = await loadPrincipalHistoryPrefix(input.execSql, progress.scopeId);
+    if (!candidate || candidate.version <= history.currentEntry.state.version)
+        return null;
+    try {
+        const cached = await restorePublicPrefix(input, progress.scopeId, progress.id, candidate);
+        if (!cached?.completedHead)
+            return null;
+        const finished = cached.verifier.finish(cached.completedHead);
+        if (!finished.ok)
+            throw finished.error;
+        const proof = await loadPrincipalHistoryReference({
+            execSql: input.execSql,
+            scopeId: progress.scopeId,
+            history: finished.value,
+            version: input.source.head.version,
+        });
+        const verified = await verifyPrincipalPolicyHistoryReferences({
+            history: finished.value,
+            references: [proof],
+        });
+        if (!verified.ok)
+            throw verified.error;
+        return principalHeadMatchesReference(proof.entry.state, input.source.head)
+            ? null
+            : candidate;
+    }
+    catch (error) {
+        if (error instanceof KeyingVerificationError ||
+            error instanceof PublicHistoryAuthorityUnavailableError)
+            return candidate;
+        throw error;
+    }
+}
+export async function publishPublicPrincipalHistoryPrefix(input, progress, history, rejectedPrefix) {
+    const state = history.currentEntry.state;
+    const head = {
+        principalType: state.principalType,
+        principalId: state.principalId,
+        version: state.version,
+        stateHash: state.stateHash,
+        keyEpoch: state.keyEpoch,
+        keyFingerprint: state.keyFingerprint,
+    };
+    const prefix = {
+        scopeId: progress.scopeId,
+        organizationId: input.organizationId,
+        version: head.version,
+        headJson: serializeKeyingCanonicalJson(head),
+        currentJson: publicHistoryAuthorityJson(progress.authorityReference),
+    };
+    const sealed = await progress.verifier.exportProgress(await principalHistoryPrefixProtection(input.protection, prefix));
+    if (!sealed.ok)
+        throw sealed.error;
+    const rejected = rejectedPrefix ??
+        (progress.cachedPrefix
+            ? null
+            : await rejectedCompletedPrefix(input, progress, history));
+    const stillCurrent = () => !input.signal?.aborted && input.stillCurrent();
+    await savePrincipalHistoryPrefix({
+        execSql: input.execSql,
+        prefix: { ...prefix, progress: sealed.value },
+        stillCurrent,
+        rejectedPrefix: rejected,
+    });
+    if (progress.saved)
+        await discardPrincipalHistoryStage(input.execSql, progress.saved, stillCurrent);
+}
+//# sourceMappingURL=publicPrincipalHistoryProgress.js.map