@tearleads/client-sdk 0.1.61 → 0.1.63

package/workflows/principals/publicHistory/recoverProjectionPolicyHistory.js

@@ -0,0 +1,98 @@
+import { KeyingVerificationError, } from "../../../internal/crypto/index.js";
+import { assertProjectionVerificationCurrent } from "../../../data/keyingProjectionVerification/types.js";
+import { principalHeadMatchesReference } from "../../../data/principals/organizationAuthorityDescriptor.js";
+import { publicProjectionDirectoryBindings } from "./publicProjectionDirectory.js";
+import { recoverPublicProjectionPrincipal, rejectPublicProjection, selectPublicProjectionPrincipal, } from "./publicProjectionPrincipal.js";
+function assertSourceCoverage(evidence, references) {
+    const sources = [evidence.organization, ...evidence.groups];
+    for (const reference of references)
+        if (!sources.some((source) => source &&
+            source.head.principalType === reference.principalType &&
+            source.head.principalId === reference.principalId &&
+            source.head.version >= reference.version))
+            rejectPublicProjection("required citation has no covering source");
+}
+async function externalAuthority(admins, references, cachedPrefix = false) {
+    const head = admins.options.source.head;
+    if (!references.length)
+        return undefined;
+    if (cachedPrefix &&
+        references.some((reference) => reference.version > head.version))
+        throw new KeyingVerificationError("missing_dependency", "Cached group history requires a newer Admins source");
+    if (references.some((reference) => reference.principalId !== head.principalId ||
+        reference.version > head.version))
+        rejectPublicProjection("external authority exceeds the bound Admins source");
+    const policies = await selectPublicProjectionPrincipal(admins, references);
+    const states = new Map(policies.flatMap((policy) => 
+    // Only this page's citations and the bound source head are authority for
+    // this verification step. A retained newer prefix is not another citation.
+    policy.retainedHistory
+        .filter(({ state }) => [head, ...references].some((reference) => principalHeadMatchesReference(state, reference)))
+        .map(({ state, projection }) => [
+        state.version,
+        {
+            head: {
+                principalType: "group",
+                principalId: state.principalId,
+                version: state.version,
+                stateHash: state.stateHash,
+                keyEpoch: state.keyEpoch,
+                keyFingerprint: state.keyFingerprint,
+            },
+            projection,
+        },
+    ])));
+    return {
+        currentHead: { ...head, principalType: "group" },
+        states: [...states.values()],
+    };
+}
+/** Public authorization only; no current-policy cache or checkpoint is written. */
+export async function recoverProjectionPolicyHistory(input) {
+    assertProjectionVerificationCurrent(() => !input.signal?.aborted && input.stillCurrent());
+    input = { ...input, references: structuredClone(input.references) };
+    const evidence = structuredClone(input.evidence);
+    assertSourceCoverage(evidence, input.references);
+    if (!evidence.organization) {
+        if (evidence.groups.length || evidence.organizationPayloads.length)
+            rejectPublicProjection("group evidence requires organization history");
+        return [];
+    }
+    if (evidence.organization.head.principalType !== "organization")
+        rejectPublicProjection("organization source has the wrong principal type");
+    const organization = await recoverPublicProjectionPrincipal({
+        ...input,
+        source: evidence.organization,
+    }, [
+        ...input.references,
+        ...evidence.organizationPayloads.map(({ reference }) => reference),
+    ]);
+    const bindings = await publicProjectionDirectoryBindings(evidence, organization);
+    const principals = new Map();
+    const adminHeads = [...bindings.values()].map(({ adminHead }) => adminHead);
+    for (const adminId of new Set(adminHeads.map((head) => head.principalId))) {
+        const source = evidence.groups.find((group) => group.head.principalId === adminId);
+        if (!source)
+            rejectPublicProjection("signed Admins source is missing");
+        principals.set(adminId, await recoverPublicProjectionPrincipal({ ...input, source, strictAdmins: true }, [...input.references, ...adminHeads]));
+    }
+    for (const source of evidence.groups) {
+        if (principals.has(source.head.principalId))
+            continue;
+        const binding = bindings.get(source.head.principalId);
+        const admins = binding && principals.get(binding.adminHead.principalId);
+        if (!admins)
+            rejectPublicProjection("verified Admins history is missing");
+        principals.set(source.head.principalId, await recoverPublicProjectionPrincipal({
+            ...input,
+            source,
+            authorityGroupId: admins.options.source.head.principalId,
+            loadExternalAuthority: (references, cachedPrefix) => externalAuthority(admins, references, cachedPrefix),
+        }, input.references));
+    }
+    const policies = [];
+    for (const principal of [organization, ...principals.values()])
+        policies.push(...(await selectPublicProjectionPrincipal(principal)));
+    return policies;
+}
+//# sourceMappingURL=recoverProjectionPolicyHistory.js.map

package/workflows/principals/publicHistory/recoverProjectionPolicyHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recoverProjectionPolicyHistory.js","sourceRoot":"","sources":["recoverProjectionPolicyHistory.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  KeyingVerificationError,\n  type PrincipalPolicyExternalAuthority,\n  type ReferencedPrincipalHead,\n  type VerifiedPrincipalPolicySelection,\n} from \"@tearleads/crypto\";\nimport type { ProjectionPolicyEvidenceResponse } from \"@tearleads/validators/response\";\nimport { assertProjectionVerificationCurrent } from \"../../../data/keyingProjectionVerification/types\";\nimport { principalHeadMatchesReference } from \"../../../data/principals/organizationAuthorityDescriptor\";\nimport type { PublicPrincipalHistoryOptions } from \"./publicPrincipalHistoryTypes\";\nimport { publicProjectionDirectoryBindings } from \"./publicProjectionDirectory\";\nimport {\n  type PublicProjectionPrincipal,\n  recoverPublicProjectionPrincipal,\n  rejectPublicProjection,\n  selectPublicProjectionPrincipal,\n} from \"./publicProjectionPrincipal\";\n\nexport interface ProjectionPolicyHistoryRecoveryOptions\n  extends Omit<\n    PublicPrincipalHistoryOptions,\n    | \"source\"\n    | \"loadExternalAuthority\"\n    | \"strictAdmins\"\n    | \"authorityGroupId\"\n    | \"replay\"\n  > {\n  readonly evidence: ProjectionPolicyEvidenceResponse;\n  readonly references: readonly ReferencedPrincipalHead[];\n}\n\nfunction assertSourceCoverage(\n  evidence: ProjectionPolicyEvidenceResponse,\n  references: readonly ReferencedPrincipalHead[],\n): void {\n  const sources = [evidence.organization, ...evidence.groups];\n  for (const reference of references)\n    if (\n      !sources.some(\n        (source) =>\n          source &&\n          source.head.principalType === reference.principalType &&\n          source.head.principalId === reference.principalId &&\n          source.head.version >= reference.version,\n      )\n    )\n      rejectPublicProjection(\"required citation has no covering source\");\n}\n\nasync function externalAuthority(\n  admins: PublicProjectionPrincipal,\n  references: readonly ReferencedPrincipalHead[],\n  cachedPrefix = false,\n): Promise<PrincipalPolicyExternalAuthority | undefined> {\n  const head = admins.options.source.head;\n  if (!references.length) return undefined;\n  if (\n    cachedPrefix &&\n    references.some((reference) => reference.version > head.version)\n  )\n    throw new KeyingVerificationError(\n      \"missing_dependency\",\n      \"Cached group history requires a newer Admins source\",\n    );\n  if (\n    references.some(\n      (reference) =>\n        reference.principalId !== head.principalId ||\n        reference.version > head.version,\n    )\n  )\n    rejectPublicProjection(\n      \"external authority exceeds the bound Admins source\",\n    );\n  const policies = await selectPublicProjectionPrincipal(admins, references);\n  const states = new Map(\n    policies.flatMap((policy) =>\n      // Only this page's citations and the bound source head are authority for\n      // this verification step. A retained newer prefix is not another citation.\n      policy.retainedHistory\n        .filter(({ state }) =>\n          [head, ...references].some((reference) =>\n            principalHeadMatchesReference(state, reference),\n          ),\n        )\n        .map(\n          ({ state, projection }) =>\n            [\n              state.version,\n              {\n                head: {\n                  principalType: \"group\" as const,\n                  principalId: state.principalId,\n                  version: state.version,\n                  stateHash: state.stateHash,\n                  keyEpoch: state.keyEpoch,\n                  keyFingerprint: state.keyFingerprint,\n                },\n                projection,\n              },\n            ] as const,\n        ),\n    ),\n  );\n  return {\n    currentHead: { ...head, principalType: \"group\" },\n    states: [...states.values()],\n  };\n}\n\n/** Public authorization only; no current-policy cache or checkpoint is written. */\nexport async function recoverProjectionPolicyHistory(\n  input: ProjectionPolicyHistoryRecoveryOptions,\n): Promise<VerifiedPrincipalPolicySelection[]> {\n  assertProjectionVerificationCurrent(\n    () => !input.signal?.aborted && input.stillCurrent(),\n  );\n  input = { ...input, references: structuredClone(input.references) };\n  const evidence = structuredClone(input.evidence);\n  assertSourceCoverage(evidence, input.references);\n  if (!evidence.organization) {\n    if (evidence.groups.length || evidence.organizationPayloads.length)\n      rejectPublicProjection(\"group evidence requires organization history\");\n    return [];\n  }\n  if (evidence.organization.head.principalType !== \"organization\")\n    rejectPublicProjection(\"organization source has the wrong principal type\");\n  const organization = await recoverPublicProjectionPrincipal(\n    {\n      ...input,\n      source: evidence.organization,\n    },\n    [\n      ...input.references,\n      ...evidence.organizationPayloads.map(({ reference }) => reference),\n    ],\n  );\n  const bindings = await publicProjectionDirectoryBindings(\n    evidence,\n    organization,\n  );\n  const principals = new Map<string, PublicProjectionPrincipal>();\n  const adminHeads = [...bindings.values()].map(({ adminHead }) => adminHead);\n  for (const adminId of new Set(adminHeads.map((head) => head.principalId))) {\n    const source = evidence.groups.find(\n      (group) => group.head.principalId === adminId,\n    );\n    if (!source) rejectPublicProjection(\"signed Admins source is missing\");\n    principals.set(\n      adminId,\n      await recoverPublicProjectionPrincipal(\n        { ...input, source, strictAdmins: true },\n        [...input.references, ...adminHeads],\n      ),\n    );\n  }\n  for (const source of evidence.groups) {\n    if (principals.has(source.head.principalId)) continue;\n    const binding = bindings.get(source.head.principalId);\n    const admins = binding && principals.get(binding.adminHead.principalId);\n    if (!admins) rejectPublicProjection(\"verified Admins history is missing\");\n    principals.set(\n      source.head.principalId,\n      await recoverPublicProjectionPrincipal(\n        {\n          ...input,\n          source,\n          authorityGroupId: admins.options.source.head.principalId,\n          loadExternalAuthority: (references, cachedPrefix) =>\n            externalAuthority(admins, references, cachedPrefix),\n        },\n        input.references,\n      ),\n    );\n  }\n  const policies: VerifiedPrincipalPolicySelection[] = [];\n  for (const principal of [organization, ...principals.values()])\n    policies.push(...(await selectPublicProjectionPrincipal(principal)));\n  return policies;\n}\n"]}

package/workflows/principals/publicHistory/recoverPublicPrincipalHistory.js

@@ -0,0 +1,178 @@
+import { createPrincipalPolicyHistoryVerifier, KeyingVerificationError, serializeKeyingCanonicalJson, verifyPrincipalPolicyHistoryReferences, } from "../../../internal/crypto/index.js";
+import { isPrincipalPolicySnapshotPageResponse, } from "../../../internal/validators/response/index.js";
+import { assertProjectionVerificationCurrent } from "../../../data/keyingProjectionVerification/types.js";
+import { loadPrincipalHistoryReference } from "../../../data/persistence/principalHistoryEvidencePersistence.js";
+import { principalHeadMatchesReference } from "../../../data/principals/organizationAuthorityDescriptor.js";
+import { ownPrincipalHistoryProtection } from "../../../data/principals/principalHistoryProtection.js";
+import { PrincipalPolicyHistoryReadError } from "../historyRecovery/principalHistoryRecoveryTypes.js";
+import { PublicHistoryAuthorityUnavailableError } from "./publicPrincipalHistoryAuthority.js";
+import { appendPublicPrincipalHistoryPage, PublicPrincipalHistoryPrefixDisconnectedError, } from "./publicPrincipalHistoryPage.js";
+import { publishPublicPrincipalHistoryPrefix, restorePublicPrincipalHistoryProgress, } from "./publicPrincipalHistoryProgress.js";
+function assertPage(input, page, after) {
+    if (!isPrincipalPolicySnapshotPageResponse(page) ||
+        !principalHeadMatchesReference(page.currentState, input.source.head) ||
+        page.historyPage.afterVersion !== after)
+        throw new KeyingVerificationError("object_mismatch", "Public history page does not match its requested head and cursor");
+    const through = after + page.previousStates.length;
+    if (page.previousStates.some(({ state }, index) => state.version !== after + index + 1) ||
+        through >= input.source.head.version ||
+        (page.historyPage.nextAfterVersion === null
+            ? through !== input.source.head.version - 1
+            : through <= after || page.historyPage.nextAfterVersion !== through))
+        throw new KeyingVerificationError("invalid_shape", "Public history page has a gap or invalid continuation");
+}
+async function readPublicPages(input, initial) {
+    const current = () => !input.signal?.aborted && input.stillCurrent();
+    let progress = initial;
+    let lastPage;
+    // Completed progress already verified every signed entry through the cited
+    // head; a read pinned to that head could only repeat it or refuse.
+    if (!input.offline && !progress.completedHead) {
+        for await (const result of input.historyReader.getProjectionPolicyHistoryPages(input.source, { afterVersion: progress.afterVersion, signal: input.signal })) {
+            assertProjectionVerificationCurrent(current);
+            if (!result.ok)
+                throw new PrincipalPolicyHistoryReadError(result);
+            const page = result.data;
+            assertPage(input, page, progress.afterVersion);
+            if (progress.completedHead)
+                throw new KeyingVerificationError("invalid_shape", "Completed public history returned additional entries");
+            progress = await appendPublicPrincipalHistoryPage(input, progress, page);
+            lastPage = page;
+        }
+        if (lastPage?.historyPage.nextAfterVersion !== null)
+            throw new KeyingVerificationError("missing_dependency", "Public history transport did not complete");
+    }
+    return { progress, lastPage };
+}
+function finishPublicProgress(progress) {
+    if (!progress.completedHead)
+        throw new KeyingVerificationError("missing_dependency", "Completed public history is unavailable");
+    const finished = progress.verifier.finish(progress.completedHead);
+    if (!finished.ok)
+        throw finished.error;
+    return finished.value;
+}
+async function recoverAttempt(input, allowReuse = true, rejectedPrefix = null) {
+    const current = () => !input.signal?.aborted && input.stillCurrent();
+    assertProjectionVerificationCurrent(current);
+    const mayReplay = allowReuse && !input.offline;
+    const initial = await restorePublicPrincipalHistoryProgress(input, allowReuse);
+    let pages;
+    try {
+        pages = await readPublicPages(input, initial);
+    }
+    catch (error) {
+        if (!(error instanceof PublicPrincipalHistoryPrefixDisconnectedError))
+            throw error;
+        // A signed cached candidate need not belong to this requested chain. Only
+        // reused progress permits one replay; a fresh disconnected chain fails.
+        if (mayReplay && initial.afterVersion > 0)
+            return recover(input, false, initial.cachedPrefix);
+        throw error.verificationError;
+    }
+    const { progress, lastPage } = pages;
+    const history = finishPublicProgress(progress);
+    let proof;
+    try {
+        proof = await loadPrincipalHistoryReference({
+            execSql: input.execSql,
+            scopeId: progress.scopeId,
+            history,
+            version: input.source.head.version,
+        });
+        const selected = await verifyPrincipalPolicyHistoryReferences({
+            history,
+            references: [proof],
+        });
+        if (!selected.ok)
+            throw selected.error;
+    }
+    catch (error) {
+        if (error instanceof KeyingVerificationError && mayReplay)
+            return recover(input, false, initial.cachedPrefix);
+        throw error;
+    }
+    // Public prefixes memoize signatures; they are not admitted trust pins. A
+    // rejected projection may have left a valid but unrelated signed candidate.
+    // Rebuild the requested chain once online; callers still check durable pins
+    // and object authority before accepting it. Never reuse a mismatch offline.
+    if (!principalHeadMatchesReference(proof.entry.state, input.source.head)) {
+        if (mayReplay)
+            return recover(input, false, initial.cachedPrefix);
+        throw new KeyingVerificationError("object_mismatch", "Public history source differs from the verified prefix");
+    }
+    if (lastPage) {
+        const currentProof = {
+            ...proof,
+            entry: {
+                state: lastPage.currentState,
+                projection: lastPage.currentProjection,
+                grants: lastPage.currentGrants,
+            },
+        };
+        const checked = await verifyPrincipalPolicyHistoryReferences({
+            history,
+            references: [currentProof],
+        });
+        if (!checked.ok)
+            throw checked.error;
+    }
+    assertProjectionVerificationCurrent(current);
+    if (!input.offline)
+        await publishPublicPrincipalHistoryPrefix(input, progress, history, rejectedPrefix);
+    assertProjectionVerificationCurrent(current);
+    return { scopeId: progress.scopeId, history };
+}
+async function recover(input, allowReuse = true, rejectedPrefix = null) {
+    try {
+        return await recoverAttempt(input, allowReuse, rejectedPrefix);
+    }
+    catch (error) {
+        if (!(error instanceof PublicHistoryAuthorityUnavailableError))
+            throw error;
+        if (allowReuse && !input.offline)
+            return recoverAttempt(input, false, error.rejectedPrefix);
+        throw error.verificationError;
+    }
+}
+/** Private-key-backed public history recovery; never admits a current policy pin. */
+export async function recoverPublicPrincipalHistory(options) {
+    if (!options.organizationId ||
+        (options.historicalProof !== undefined &&
+            typeof options.historicalProof !== "boolean") ||
+        (options.offline !== undefined && typeof options.offline !== "boolean") ||
+        (options.strictAdmins !== undefined &&
+            typeof options.strictAdmins !== "boolean") ||
+        (options.strictAdmins &&
+            (options.source.head.principalType !== "group" ||
+                options.loadExternalAuthority)))
+        throw new KeyingVerificationError("invalid_shape", "Invalid public history verification scope");
+    if (options.source.head.principalType === "organization" &&
+        options.source.head.principalId !== options.organizationId)
+        throw new KeyingVerificationError("object_mismatch", "Public organization history is outside its scope");
+    // Validate the caller's pinned head before any cache or transport access.
+    createPrincipalPolicyHistoryVerifier({
+        principalType: options.source.head.principalType,
+        principalId: options.source.head.principalId,
+        retainedReferences: [options.source.head],
+    });
+    const protection = ownPrincipalHistoryProtection(options.protection);
+    protection.context = serializeKeyingCanonicalJson([
+        "tearleads.sdk.public-principal-history.v2",
+        protection.context,
+        options.strictAdmins === true,
+        options.authorityGroupId ?? null,
+    ]);
+    const input = {
+        ...options,
+        source: structuredClone(options.source),
+        protection,
+    };
+    try {
+        return await recover(input, options.replay !== true);
+    }
+    finally {
+        protection.localKey.fill(0);
+    }
+}
+//# sourceMappingURL=recoverPublicPrincipalHistory.js.map

package/workflows/principals/publicHistory/recoverPublicPrincipalHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recoverPublicPrincipalHistory.js","sourceRoot":"","sources":["recoverPublicPrincipalHistory.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  createPrincipalPolicyHistoryVerifier,\n  KeyingVerificationError,\n  type PrincipalPolicyHistoryReferenceProof,\n  serializeKeyingCanonicalJson,\n  verifyPrincipalPolicyHistoryReferences,\n} from \"@tearleads/crypto\";\nimport {\n  isPrincipalPolicySnapshotPageResponse,\n  type PrincipalPolicySnapshotPageResponse,\n} from \"@tearleads/validators/response\";\nimport { assertProjectionVerificationCurrent } from \"../../../data/keyingProjectionVerification/types\";\nimport { loadPrincipalHistoryReference } from \"../../../data/persistence/principalHistoryEvidencePersistence\";\nimport type { PrincipalHistoryPrefix } from \"../../../data/persistence/principalHistoryPrefixPersistence\";\nimport { principalHeadMatchesReference } from \"../../../data/principals/organizationAuthorityDescriptor\";\nimport { ownPrincipalHistoryProtection } from \"../../../data/principals/principalHistoryProtection\";\nimport { PrincipalPolicyHistoryReadError } from \"../historyRecovery/principalHistoryRecoveryTypes\";\nimport { PublicHistoryAuthorityUnavailableError } from \"./publicPrincipalHistoryAuthority\";\nimport {\n  appendPublicPrincipalHistoryPage,\n  PublicPrincipalHistoryPrefixDisconnectedError,\n} from \"./publicPrincipalHistoryPage\";\nimport {\n  publishPublicPrincipalHistoryPrefix,\n  restorePublicPrincipalHistoryProgress,\n} from \"./publicPrincipalHistoryProgress\";\nimport type {\n  PublicPrincipalHistoryOptions,\n  PublicPrincipalHistoryProgress,\n  RecoveredPublicPrincipalHistory,\n} from \"./publicPrincipalHistoryTypes\";\n\nfunction assertPage(\n  input: PublicPrincipalHistoryOptions,\n  page: PrincipalPolicySnapshotPageResponse,\n  after: number,\n): void {\n  if (\n    !isPrincipalPolicySnapshotPageResponse(page) ||\n    !principalHeadMatchesReference(page.currentState, input.source.head) ||\n    page.historyPage.afterVersion !== after\n  )\n    throw new KeyingVerificationError(\n      \"object_mismatch\",\n      \"Public history page does not match its requested head and cursor\",\n    );\n  const through = after + page.previousStates.length;\n  if (\n    page.previousStates.some(\n      ({ state }, index) => state.version !== after + index + 1,\n    ) ||\n    through >= input.source.head.version ||\n    (page.historyPage.nextAfterVersion === null\n      ? through !== input.source.head.version - 1\n      : through <= after || page.historyPage.nextAfterVersion !== through)\n  )\n    throw new KeyingVerificationError(\n      \"invalid_shape\",\n      \"Public history page has a gap or invalid continuation\",\n    );\n}\n\nasync function readPublicPages(\n  input: PublicPrincipalHistoryOptions,\n  initial: PublicPrincipalHistoryProgress,\n) {\n  const current = () => !input.signal?.aborted && input.stillCurrent();\n  let progress = initial;\n  let lastPage: PrincipalPolicySnapshotPageResponse | undefined;\n  // Completed progress already verified every signed entry through the cited\n  // head; a read pinned to that head could only repeat it or refuse.\n  if (!input.offline && !progress.completedHead) {\n    for await (const result of input.historyReader.getProjectionPolicyHistoryPages(\n      input.source,\n      { afterVersion: progress.afterVersion, signal: input.signal },\n    )) {\n      assertProjectionVerificationCurrent(current);\n      if (!result.ok) throw new PrincipalPolicyHistoryReadError(result);\n      const page = result.data;\n      assertPage(input, page, progress.afterVersion);\n      if (progress.completedHead)\n        throw new KeyingVerificationError(\n          \"invalid_shape\",\n          \"Completed public history returned additional entries\",\n        );\n      progress = await appendPublicPrincipalHistoryPage(input, progress, page);\n      lastPage = page;\n    }\n    if (lastPage?.historyPage.nextAfterVersion !== null)\n      throw new KeyingVerificationError(\n        \"missing_dependency\",\n        \"Public history transport did not complete\",\n      );\n  }\n  return { progress, lastPage };\n}\n\nfunction finishPublicProgress(progress: PublicPrincipalHistoryProgress) {\n  if (!progress.completedHead)\n    throw new KeyingVerificationError(\n      \"missing_dependency\",\n      \"Completed public history is unavailable\",\n    );\n  const finished = progress.verifier.finish(progress.completedHead);\n  if (!finished.ok) throw finished.error;\n  return finished.value;\n}\n\nasync function recoverAttempt(\n  input: PublicPrincipalHistoryOptions,\n  allowReuse = true,\n  rejectedPrefix: PrincipalHistoryPrefix | null = null,\n): Promise<RecoveredPublicPrincipalHistory> {\n  const current = () => !input.signal?.aborted && input.stillCurrent();\n  assertProjectionVerificationCurrent(current);\n  const mayReplay = allowReuse && !input.offline;\n  const initial = await restorePublicPrincipalHistoryProgress(\n    input,\n    allowReuse,\n  );\n  let pages: Awaited<ReturnType<typeof readPublicPages>>;\n  try {\n    pages = await readPublicPages(input, initial);\n  } catch (error) {\n    if (!(error instanceof PublicPrincipalHistoryPrefixDisconnectedError))\n      throw error;\n    // A signed cached candidate need not belong to this requested chain. Only\n    // reused progress permits one replay; a fresh disconnected chain fails.\n    if (mayReplay && initial.afterVersion > 0)\n      return recover(input, false, initial.cachedPrefix);\n    throw error.verificationError;\n  }\n  const { progress, lastPage } = pages;\n  const history = finishPublicProgress(progress);\n  let proof: PrincipalPolicyHistoryReferenceProof;\n  try {\n    proof = await loadPrincipalHistoryReference({\n      execSql: input.execSql,\n      scopeId: progress.scopeId,\n      history,\n      version: input.source.head.version,\n    });\n    const selected = await verifyPrincipalPolicyHistoryReferences({\n      history,\n      references: [proof],\n    });\n    if (!selected.ok) throw selected.error;\n  } catch (error) {\n    if (error instanceof KeyingVerificationError && mayReplay)\n      return recover(input, false, initial.cachedPrefix);\n    throw error;\n  }\n  // Public prefixes memoize signatures; they are not admitted trust pins. A\n  // rejected projection may have left a valid but unrelated signed candidate.\n  // Rebuild the requested chain once online; callers still check durable pins\n  // and object authority before accepting it. Never reuse a mismatch offline.\n  if (!principalHeadMatchesReference(proof.entry.state, input.source.head)) {\n    if (mayReplay) return recover(input, false, initial.cachedPrefix);\n    throw new KeyingVerificationError(\n      \"object_mismatch\",\n      \"Public history source differs from the verified prefix\",\n    );\n  }\n  if (lastPage) {\n    const currentProof = {\n      ...proof,\n      entry: {\n        state: lastPage.currentState,\n        projection: lastPage.currentProjection,\n        grants: lastPage.currentGrants,\n      },\n    };\n    const checked = await verifyPrincipalPolicyHistoryReferences({\n      history,\n      references: [currentProof],\n    });\n    if (!checked.ok) throw checked.error;\n  }\n  assertProjectionVerificationCurrent(current);\n  if (!input.offline)\n    await publishPublicPrincipalHistoryPrefix(\n      input,\n      progress,\n      history,\n      rejectedPrefix,\n    );\n  assertProjectionVerificationCurrent(current);\n  return { scopeId: progress.scopeId, history };\n}\n\nasync function recover(\n  input: PublicPrincipalHistoryOptions,\n  allowReuse = true,\n  rejectedPrefix: PrincipalHistoryPrefix | null = null,\n): Promise<RecoveredPublicPrincipalHistory> {\n  try {\n    return await recoverAttempt(input, allowReuse, rejectedPrefix);\n  } catch (error) {\n    if (!(error instanceof PublicHistoryAuthorityUnavailableError)) throw error;\n    if (allowReuse && !input.offline)\n      return recoverAttempt(input, false, error.rejectedPrefix);\n    throw error.verificationError;\n  }\n}\n\n/** Private-key-backed public history recovery; never admits a current policy pin. */\nexport async function recoverPublicPrincipalHistory(\n  options: PublicPrincipalHistoryOptions,\n): Promise<RecoveredPublicPrincipalHistory> {\n  if (\n    !options.organizationId ||\n    (options.historicalProof !== undefined &&\n      typeof options.historicalProof !== \"boolean\") ||\n    (options.offline !== undefined && typeof options.offline !== \"boolean\") ||\n    (options.strictAdmins !== undefined &&\n      typeof options.strictAdmins !== \"boolean\") ||\n    (options.strictAdmins &&\n      (options.source.head.principalType !== \"group\" ||\n        options.loadExternalAuthority))\n  )\n    throw new KeyingVerificationError(\n      \"invalid_shape\",\n      \"Invalid public history verification scope\",\n    );\n  if (\n    options.source.head.principalType === \"organization\" &&\n    options.source.head.principalId !== options.organizationId\n  )\n    throw new KeyingVerificationError(\n      \"object_mismatch\",\n      \"Public organization history is outside its scope\",\n    );\n  // Validate the caller's pinned head before any cache or transport access.\n  createPrincipalPolicyHistoryVerifier({\n    principalType: options.source.head.principalType,\n    principalId: options.source.head.principalId,\n    retainedReferences: [options.source.head],\n  });\n  const protection = ownPrincipalHistoryProtection(options.protection);\n  protection.context = serializeKeyingCanonicalJson([\n    \"tearleads.sdk.public-principal-history.v2\",\n    protection.context,\n    options.strictAdmins === true,\n    options.authorityGroupId ?? null,\n  ]);\n  const input = {\n    ...options,\n    source: structuredClone(options.source),\n    protection,\n  };\n  try {\n    return await recover(input, options.replay !== true);\n  } finally {\n    protection.localKey.fill(0);\n  }\n}\n"]}

package/workflows/principals/publicHistory/selectPublicPrincipalHistory.js

@@ -0,0 +1,96 @@
+import { KeyingVerificationError, PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT, selectPrincipalPolicyAuthorization, verifyPrincipalPolicyCheckpoint, verifyPrincipalPolicyHistoryReferences, } from "../../../internal/crypto/index.js";
+import { assertProjectionVerificationCurrent } from "../../../data/keyingProjectionVerification/types.js";
+import { loadPrincipalHistoryReference } from "../../../data/persistence/principalHistoryEvidencePersistence.js";
+import { principalHeadMatchesReference } from "../../../data/principals/organizationAuthorityDescriptor.js";
+import { PrincipalHistoryEvidenceUnavailableError } from "../historyRecovery/principalHistoryRecoveryReferences.js";
+async function selectBatch(input, versions, checkpointReference) {
+    const proofs = [];
+    for (const version of versions) {
+        assertProjectionVerificationCurrent(input.stillCurrent);
+        proofs.push(await loadPrincipalHistoryReference({
+            execSql: input.execSql,
+            ...input.recovered,
+            version,
+        }));
+    }
+    const selected = await verifyPrincipalPolicyHistoryReferences({
+        history: input.recovered.history,
+        references: proofs,
+        checkpointReference,
+    });
+    if (!selected.ok)
+        throw selected.error;
+    return selected.value;
+}
+async function loadCheckpointProof(input, checkpoint) {
+    let checkpointReference;
+    try {
+        if (checkpoint)
+            checkpointReference = await loadPrincipalHistoryReference({
+                execSql: input.execSql,
+                ...input.recovered,
+                version: checkpoint.version,
+            });
+    }
+    catch (error) {
+        if (error instanceof KeyingVerificationError)
+            throw new PrincipalHistoryEvidenceUnavailableError(error);
+        throw error;
+    }
+    return checkpointReference;
+}
+function checkSelectedReferences(input, references, batch, selected, checkpoint) {
+    // Authenticate the disposable proof before comparing caller citations or pins.
+    for (const reference of references.filter(({ version }) => batch.includes(version)))
+        if (!selected.retainedEntries.some(({ state }) => principalHeadMatchesReference(state, reference)))
+            throw new KeyingVerificationError("object_mismatch", "Public history citation differs from its verified entry");
+    if (!input.deferCheckpointCheck)
+        verifyPrincipalPolicyCheckpoint({
+            chain: selected.retainedEntries.map((entry) => ({
+                ...entry,
+                projection: [...entry.projection],
+                grants: [...entry.grants],
+            })),
+            currentState: selected.currentEntry.state,
+            localCheckpoint: checkpoint,
+        });
+}
+/** Select bounded proof batches without admitting or advancing durable pins. */
+export async function selectPublicPrincipalHistory(input) {
+    const references = structuredClone(input.references);
+    const checkpoint = input.checkpoint && { ...input.checkpoint };
+    const head = input.recovered.history.currentEntry.state;
+    if (!input.deferCheckpointCheck &&
+        checkpoint &&
+        checkpoint.version > head.version)
+        throw new KeyingVerificationError("missing_dependency", "Public history cannot connect to the newer durable checkpoint");
+    if (references.some((reference) => reference.principalType !== head.principalType ||
+        reference.principalId !== head.principalId ||
+        reference.version > head.version))
+        throw new KeyingVerificationError("object_mismatch", "Public history reference is outside the verified prefix");
+    const versions = [
+        ...new Set([
+            ...(input.includeGenesis ? [1] : []),
+            ...references.map(({ version }) => version),
+            head.version,
+        ]),
+    ];
+    const policies = [];
+    const checkpointReference = await loadCheckpointProof(input, checkpoint && checkpoint.version <= head.version ? checkpoint : null);
+    for (let offset = 0; offset < versions.length; offset += PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT) {
+        const batch = versions.slice(offset, offset + PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT);
+        const selected = await selectBatch(input, batch, checkpointReference).catch((error) => {
+            if (error instanceof KeyingVerificationError)
+                throw new PrincipalHistoryEvidenceUnavailableError(error);
+            throw error;
+        });
+        checkSelectedReferences(input, references, batch, selected, checkpoint);
+        const policy = await selectPrincipalPolicyAuthorization(selected);
+        if (!policy.ok)
+            throw policy.error;
+        policies.push(policy.value);
+    }
+    assertProjectionVerificationCurrent(input.stillCurrent);
+    return policies;
+}
+//# sourceMappingURL=selectPublicPrincipalHistory.js.map

package/workflows/principals/publicHistory/selectPublicPrincipalHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectPublicPrincipalHistory.js","sourceRoot":"","sources":["selectPublicPrincipalHistory.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  KeyingVerificationError,\n  PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT,\n  type PrincipalPolicyCheckpoint,\n  type PrincipalPolicyHistoryReferenceProof,\n  type ReferencedPrincipalHead,\n  selectPrincipalPolicyAuthorization,\n  type VerifiedPrincipalPolicySelection,\n  verifyPrincipalPolicyCheckpoint,\n  verifyPrincipalPolicyHistoryReferences,\n} from \"@tearleads/crypto\";\nimport { assertProjectionVerificationCurrent } from \"../../../data/keyingProjectionVerification/types\";\nimport { loadPrincipalHistoryReference } from \"../../../data/persistence/principalHistoryEvidencePersistence\";\nimport { principalHeadMatchesReference } from \"../../../data/principals/organizationAuthorityDescriptor\";\nimport type { ExecSql } from \"../../../data/sqlite/sqlSchema\";\nimport { PrincipalHistoryEvidenceUnavailableError } from \"../historyRecovery/principalHistoryRecoveryReferences\";\nimport type { RecoveredPublicPrincipalHistory } from \"./publicPrincipalHistoryTypes\";\n\ninterface PublicHistorySelectionInput {\n  readonly execSql: ExecSql;\n  readonly recovered: RecoveredPublicPrincipalHistory;\n  readonly references: readonly ReferencedPrincipalHead[];\n  readonly checkpoint: PrincipalPolicyCheckpoint | null;\n  readonly deferCheckpointCheck?: boolean | undefined;\n  readonly includeGenesis?: boolean;\n  readonly stillCurrent: () => boolean;\n}\n\nasync function selectBatch(\n  input: PublicHistorySelectionInput,\n  versions: readonly number[],\n  checkpointReference: PrincipalPolicyHistoryReferenceProof | undefined,\n) {\n  const proofs: PrincipalPolicyHistoryReferenceProof[] = [];\n  for (const version of versions) {\n    assertProjectionVerificationCurrent(input.stillCurrent);\n    proofs.push(\n      await loadPrincipalHistoryReference({\n        execSql: input.execSql,\n        ...input.recovered,\n        version,\n      }),\n    );\n  }\n  const selected = await verifyPrincipalPolicyHistoryReferences({\n    history: input.recovered.history,\n    references: proofs,\n    checkpointReference,\n  });\n  if (!selected.ok) throw selected.error;\n  return selected.value;\n}\n\nasync function loadCheckpointProof(\n  input: PublicHistorySelectionInput,\n  checkpoint: PrincipalPolicyCheckpoint | null,\n): Promise<PrincipalPolicyHistoryReferenceProof | undefined> {\n  let checkpointReference: PrincipalPolicyHistoryReferenceProof | undefined;\n  try {\n    if (checkpoint)\n      checkpointReference = await loadPrincipalHistoryReference({\n        execSql: input.execSql,\n        ...input.recovered,\n        version: checkpoint.version,\n      });\n  } catch (error) {\n    if (error instanceof KeyingVerificationError)\n      throw new PrincipalHistoryEvidenceUnavailableError(error);\n    throw error;\n  }\n  return checkpointReference;\n}\n\nfunction checkSelectedReferences(\n  input: PublicHistorySelectionInput,\n  references: readonly ReferencedPrincipalHead[],\n  batch: readonly number[],\n  selected: Awaited<ReturnType<typeof selectBatch>>,\n  checkpoint: PrincipalPolicyCheckpoint | null,\n) {\n  // Authenticate the disposable proof before comparing caller citations or pins.\n  for (const reference of references.filter(({ version }) =>\n    batch.includes(version),\n  ))\n    if (\n      !selected.retainedEntries.some(({ state }) =>\n        principalHeadMatchesReference(state, reference),\n      )\n    )\n      throw new KeyingVerificationError(\n        \"object_mismatch\",\n        \"Public history citation differs from its verified entry\",\n      );\n  if (!input.deferCheckpointCheck)\n    verifyPrincipalPolicyCheckpoint({\n      chain: selected.retainedEntries.map((entry) => ({\n        ...entry,\n        projection: [...entry.projection],\n        grants: [...entry.grants],\n      })),\n      currentState: selected.currentEntry.state,\n      localCheckpoint: checkpoint,\n    });\n}\n\n/** Select bounded proof batches without admitting or advancing durable pins. */\nexport async function selectPublicPrincipalHistory(\n  input: PublicHistorySelectionInput,\n): Promise<VerifiedPrincipalPolicySelection[]> {\n  const references = structuredClone(input.references);\n  const checkpoint = input.checkpoint && { ...input.checkpoint };\n  const head = input.recovered.history.currentEntry.state;\n  if (\n    !input.deferCheckpointCheck &&\n    checkpoint &&\n    checkpoint.version > head.version\n  )\n    throw new KeyingVerificationError(\n      \"missing_dependency\",\n      \"Public history cannot connect to the newer durable checkpoint\",\n    );\n  if (\n    references.some(\n      (reference) =>\n        reference.principalType !== head.principalType ||\n        reference.principalId !== head.principalId ||\n        reference.version > head.version,\n    )\n  )\n    throw new KeyingVerificationError(\n      \"object_mismatch\",\n      \"Public history reference is outside the verified prefix\",\n    );\n  const versions = [\n    ...new Set([\n      ...(input.includeGenesis ? [1] : []),\n      ...references.map(({ version }) => version),\n      head.version,\n    ]),\n  ];\n  const policies: VerifiedPrincipalPolicySelection[] = [];\n  const checkpointReference = await loadCheckpointProof(\n    input,\n    checkpoint && checkpoint.version <= head.version ? checkpoint : null,\n  );\n  for (\n    let offset = 0;\n    offset < versions.length;\n    offset += PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT\n  ) {\n    const batch = versions.slice(\n      offset,\n      offset + PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT,\n    );\n    const selected = await selectBatch(input, batch, checkpointReference).catch(\n      (error: unknown) => {\n        if (error instanceof KeyingVerificationError)\n          throw new PrincipalHistoryEvidenceUnavailableError(error);\n        throw error;\n      },\n    );\n    checkSelectedReferences(input, references, batch, selected, checkpoint);\n    const policy = await selectPrincipalPolicyAuthorization(selected);\n    if (!policy.ok) throw policy.error;\n    policies.push(policy.value);\n  }\n  assertProjectionVerificationCurrent(input.stillCurrent);\n  return policies;\n}\n"]}

package/workflows/principals/recoveryOperation/principalCurrentRecoveryBatch.js

@@ -0,0 +1,14 @@
+import { recoverCurrentOrganizationPolicy } from "../historyRecovery/recoverCurrentOrganizationPolicy.js";
+import { createScopedPrincipalPolicyHistoryBatch } from "../historyRecovery/recoverScopedPrincipalPolicyHistory.js";
+/** Discovery and selected references share one authenticated batch view. */
+export function createPrincipalCurrentRecoveryBatch() {
+    const memo = {
+        directories: new Map(),
+        admins: new Map(),
+    };
+    return {
+        recover: createScopedPrincipalPolicyHistoryBatch(memo),
+        discover: (input) => recoverCurrentOrganizationPolicy(input, memo),
+    };
+}
+//# sourceMappingURL=principalCurrentRecoveryBatch.js.map

package/workflows/principals/recoveryOperation/principalCurrentRecoveryBatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalCurrentRecoveryBatch.js","sourceRoot":"","sources":["principalCurrentRecoveryBatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gCAAgC,EAAE,MAAM,qDAAqD,CAAC;AACvG,OAAO,EAAE,uCAAuC,EAAE,MAAM,wDAAwD,CAAC;AAIjH,4EAA4E;AAC5E,MAAM,UAAU,mCAAmC;IACjD,MAAM,IAAI,GAA0B;QAClC,WAAW,EAAE,IAAI,GAAG,EAAE;QACtB,MAAM,EAAE,IAAI,GAAG,EAAE;KAClB,CAAC;IACF,OAAO;QACL,OAAO,EAAE,uCAAuC,CAAC,IAAI,CAAC;QACtD,QAAQ,EAAE,CAAC,KAA+B,EAAE,EAAE,CAC5C,gCAAgC,CAAC,KAAK,EAAE,IAAI,CAAC;KAChD,CAAC;AACJ,CAAC","sourcesContent":["import { recoverCurrentOrganizationPolicy } from \"../historyRecovery/recoverCurrentOrganizationPolicy\";\nimport { createScopedPrincipalPolicyHistoryBatch } from \"../historyRecovery/recoverScopedPrincipalPolicyHistory\";\nimport type { PrincipalRecoveryContext } from \"./principalRecoveryDirectory\";\nimport type { PrincipalRecoveryMemo } from \"./principalRecoveryMemo\";\n\n/** Discovery and selected references share one authenticated batch view. */\nexport function createPrincipalCurrentRecoveryBatch() {\n  const memo: PrincipalRecoveryMemo = {\n    directories: new Map(),\n    admins: new Map(),\n  };\n  return {\n    recover: createScopedPrincipalPolicyHistoryBatch(memo),\n    discover: (input: PrincipalRecoveryContext) =>\n      recoverCurrentOrganizationPolicy(input, memo),\n  };\n}\n"]}

package/workflows/principals/recoveryOperation/principalRecoveryDirectory.d.ts

@@ -0,0 +1,10 @@
+import { type ReferencedPrincipalHead } from "../../../internal/crypto/index.js";
+import { type OrganizationAuthorityDescriptor } from "../../../data/principals/organizationAuthorityDescriptor.js";
+import { type RecoveredPrincipalPolicyHistory, type RecoverPrincipalPolicyHistoryOptions } from "../historyRecovery/principalHistoryRecoveryTypes.js";
+export type PrincipalRecoveryContext = Omit<RecoverPrincipalPolicyHistoryOptions, "expectedHead" | "retainedReferences" | "historyVerification" | "loadExternalAuthority">;
+export interface RecoveredPolicyDirectory extends RecoveredPrincipalPolicyHistory {
+    readonly descriptor: OrganizationAuthorityDescriptor;
+}
+export declare class PrincipalRecoveryDirectoryAdvanced extends Error {
+}
+export declare function recoverPolicyDirectory(input: PrincipalRecoveryContext, references: readonly ReferencedPrincipalHead[], selected?: RecoveredPolicyDirectory): Promise<RecoveredPolicyDirectory>;

package/workflows/principals/recoveryOperation/principalRecoveryDirectory.js

@@ -0,0 +1,127 @@
+import { KeyingVerificationError, verifyPrincipalPolicyHistoryReferences, } from "../../../internal/crypto/index.js";
+import { assertProjectionVerificationCurrent } from "../../../data/keyingProjectionVerification/types.js";
+import { loadPrincipalHistoryReference } from "../../../data/persistence/principalHistoryEvidencePersistence.js";
+import { parseOrganizationAuthorityDescriptor, } from "../../../data/principals/organizationAuthorityDescriptor.js";
+import { principalHistoryEvidenceScopeId } from "../../../data/principals/principalHistoryPrefixProtection.js";
+import { directoryHistoryProtection } from "../../../data/principals/principalHistoryScopeProtection.js";
+import { loadVerifiedPrincipalHistoryPrefix } from "../historyRecovery/principalHistoryRecoveryPrefix.js";
+import { PrincipalPolicyHistoryReadError, } from "../historyRecovery/principalHistoryRecoveryTypes.js";
+import { recoverPrincipalPolicyHistory } from "../historyRecovery/recoverPrincipalPolicyHistory.js";
+import { reusePrincipalDiscoveryPage } from "./principalRecoveryDiscoveryPage.js";
+export class PrincipalRecoveryDirectoryAdvanced extends Error {
+}
+function exactHead(state) {
+    return {
+        principalType: state.principalType,
+        principalId: state.principalId,
+        version: state.version,
+        stateHash: state.stateHash,
+        keyEpoch: state.keyEpoch,
+        keyFingerprint: state.keyFingerprint,
+    };
+}
+/** An unverified discovery read chooses a pin; recovery must authenticate it. */
+async function discoverDirectoryHead(input) {
+    assertProjectionVerificationCurrent(() => !input.signal?.aborted && input.stillCurrent());
+    if (input.offline) {
+        const principal = {
+            principalType: "organization",
+            principalId: input.organizationId,
+        };
+        const scopeId = await principalHistoryEvidenceScopeId({
+            organizationId: input.organizationId,
+            head: principal,
+            protection: input.protection,
+        });
+        const prefix = await loadVerifiedPrincipalHistoryPrefix(input, principal, scopeId);
+        if (!prefix)
+            throw new KeyingVerificationError("missing_dependency", "Organization directory is unavailable offline");
+        const history = prefix.verifier.finish(prefix.head);
+        if (!history.ok)
+            throw history.error;
+        const genesis = await loadPrincipalHistoryReference({
+            execSql: input.execSql,
+            scopeId,
+            history: history.value,
+            version: 1,
+        });
+        const selected = await verifyPrincipalPolicyHistoryReferences({
+            history: history.value,
+            references: [genesis],
+        });
+        if (!selected.ok)
+            throw selected.error;
+        return {
+            head: prefix.head,
+            genesis: genesis.reference,
+            historyReader: input.historyReader,
+        };
+    }
+    for await (const result of input.historyReader.getPrincipalPolicyPages("organization", input.organizationId, { signal: input.signal })) {
+        if (!result.ok)
+            throw new PrincipalPolicyHistoryReadError(result);
+        assertProjectionVerificationCurrent(() => !input.signal?.aborted && input.stillCurrent());
+        const state = result.data.currentState;
+        const first = result.data.previousStates[0]?.state ?? state;
+        if (first.version !== 1 ||
+            first.principalType !== "organization" ||
+            first.principalId !== input.organizationId)
+            throw new KeyingVerificationError("missing_dependency", "Organization directory discovery requires genesis");
+        return {
+            historyReader: reusePrincipalDiscoveryPage(input.historyReader, result),
+            genesis: {
+                principalType: first.principalType,
+                principalId: first.principalId,
+                version: first.version,
+                stateHash: first.stateHash,
+                keyEpoch: first.keyEpoch,
+                keyFingerprint: first.keyFingerprint,
+            },
+            head: {
+                principalType: "organization",
+                principalId: input.organizationId,
+                version: state.version,
+                stateHash: state.stateHash,
+                keyEpoch: state.keyEpoch,
+                keyFingerprint: state.keyFingerprint,
+            },
+        };
+    }
+    throw new KeyingVerificationError("missing_dependency", "Organization directory head is unavailable");
+}
+export async function recoverPolicyDirectory(input, references, selected) {
+    const scoped = {
+        ...input,
+        protection: directoryHistoryProtection(input.protection),
+    };
+    const { head: expectedHead, genesis, historyReader, } = selected
+        ? {
+            head: exactHead(selected.policy.state),
+            genesis: selected.policy.retainedHistory[0]?.state,
+            historyReader: input.historyReader,
+        }
+        : await discoverDirectoryHead(scoped);
+    if (genesis?.version !== 1)
+        throw new KeyingVerificationError("missing_dependency", "Organization directory recovery requires verified genesis");
+    if (references.some((reference) => reference.version > expectedHead.version))
+        throw new PrincipalRecoveryDirectoryAdvanced();
+    const recovered = await recoverPrincipalPolicyHistory({
+        ...scoped,
+        historyReader,
+        expectedHead,
+        retainedReferences: references.some((reference) => reference.version === 1)
+            ? references
+            : [exactHead(genesis), ...references],
+    });
+    let descriptor;
+    try {
+        descriptor = parseOrganizationAuthorityDescriptor(recovered.current.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 { ...recovered, descriptor };
+}
+//# sourceMappingURL=principalRecoveryDirectory.js.map