@tearleads/client-sdk 0.1.62 → 0.1.64

package/workflows/principals/recoverPrincipalPolicyHistory.js

@@ -1,295 +0,0 @@
-import { createPrincipalPolicyHistoryVerifier, KeyingVerificationError, PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT, verifyPrincipalPolicyCheckpoint, verifyPrincipalPolicyCurrent, } from "../../internal/crypto/index.js";
-import { assertProjectionVerificationCurrent } from "../../data/keyingProjectionVerification/types.js";
-import { loadPrincipalPolicyCheckpoint } from "../../data/persistence/keyingCheckpointPersistence.js";
-import { preparePrincipalHistoryEvidencePage } from "../../data/persistence/principalHistoryEvidencePersistence.js";
-import { discardPrincipalHistoryStage, savePrincipalHistoryStage, } from "../../data/persistence/principalHistoryStagePersistence.js";
-import { ownPrincipalHistoryProtection } from "../../data/principals/principalHistoryProtection.js";
-import { principalHistoryStageProtection } from "../../data/principals/principalHistoryStageProtection.js";
-import { collectPrincipalPolicySignerPublicKeys } from "./policyVerification.js";
-import { validatePrincipalHistoryRecoveryAuthority } from "./principalHistoryRecoveryAuthority.js";
-import { publishReusablePrincipalHistoryPrefix } from "./principalHistoryRecoveryPrefix.js";
-import { PrincipalHistoryEvidenceUnavailableError, selectRecoveredPrincipalHistory, } from "./principalHistoryRecoveryReferences.js";
-import { restorePrincipalHistoryRecoveryStage, } from "./principalHistoryRecoveryStage.js";
-import { PrincipalHistoryRecoveryRaceError, PrincipalPolicyHistoryReadError, } from "./principalHistoryRecoveryTypes.js";
-import { assertPrincipalHistoryVerificationMode, principalHistoryVerificationContext, } from "./principalHistoryRecoveryVerification.js";
-class PrincipalHistoryPrefixDisconnectedError extends Error {
-    verificationError;
-    constructor(verificationError) {
-        super(verificationError.message);
-        this.verificationError = verificationError;
-        this.name = "PrincipalHistoryPrefixDisconnectedError";
-    }
-}
-/** Stored current artifacts of a completed stage failed their signed-history check. */
-class StoredPrincipalCurrentRejectedError extends Error {
-    verificationError;
-    constructor(verificationError) {
-        super(verificationError.message);
-        this.verificationError = verificationError;
-        this.name = "StoredPrincipalCurrentRejectedError";
-    }
-}
-function currentArtifacts(page) {
-    return {
-        currentState: page.currentState,
-        currentPayload: page.currentPayload,
-        currentProjection: page.currentProjection,
-        currentGrants: page.currentGrants,
-        currentMemberEnvelopes: page.currentMemberEnvelopes,
-    };
-}
-function recoveryIsCurrent(input) {
-    return !input.signal?.aborted && input.stillCurrent();
-}
-function assertCurrent(input) {
-    assertProjectionVerificationCurrent(() => recoveryIsCurrent(input));
-}
-function assertExpectedHead(current, expectedHead) {
-    for (const field of [
-        "principalType",
-        "principalId",
-        "version",
-        "stateHash",
-        "keyEpoch",
-        "keyFingerprint",
-    ]) {
-        if (current.currentState[field] !== expectedHead[field])
-            throw new KeyingVerificationError("object_mismatch", "Principal history page does not match its requested head");
-    }
-}
-async function acceptPage(input, stage, response) {
-    const page = structuredClone(response);
-    assertCurrent(input);
-    assertExpectedHead(page, input.expectedHead);
-    if (stage.complete) {
-        if (page.previousStates.length !== 0 ||
-            page.historyPage.nextAfterVersion !== null)
-            throw new KeyingVerificationError("invalid_shape", "Completed history returned additional entries");
-        stage.current = currentArtifacts(page);
-        return;
-    }
-    const complete = page.historyPage.nextAfterVersion === null;
-    const current = currentArtifacts(page);
-    const entries = [...page.previousStates];
-    if (complete)
-        entries.push({
-            state: current.currentState,
-            projection: current.currentProjection,
-            grants: current.currentGrants,
-        });
-    assertPrincipalHistoryVerificationMode(input, entries);
-    const keys = await collectPrincipalPolicySignerPublicKeys({
-        bundle: { ...current, previousStates: page.previousStates },
-        resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,
-    });
-    if ("error" in keys)
-        throw new KeyingVerificationError(keys.error === "not-found" ? "missing_dependency" : "signer_mismatch", "Principal history signer identity could not be authenticated");
-    const externalAuthority = await input.loadExternalAuthority?.(entries.flatMap(({ state }) => state.externalAuthority ? [state.externalAuthority] : []));
-    const appended = await stage.verifier.append({
-        entries,
-        signerPublicKeys: keys.signerPublicKeys,
-        ...(externalAuthority ? { externalAuthority } : {}),
-    });
-    if (!appended.ok) {
-        if (appended.error.code === "stale_predecessor")
-            throw new PrincipalHistoryPrefixDisconnectedError(appended.error);
-        throw appended.error;
-    }
-    const next = {
-        id: stage.id,
-        organizationId: input.organizationId,
-        currentJson: JSON.stringify(current),
-        afterVersion: appended.value.throughVersion - (complete ? 1 : 0),
-        complete,
-    };
-    const protectedProgress = await stage.verifier.exportProgress(await principalHistoryStageProtection(input.protection, input.expectedHead, next));
-    if (!protectedProgress.ok)
-        throw protectedProgress.error;
-    const saved = { ...next, progress: protectedProgress.value };
-    await savePrincipalHistoryStage({
-        execSql: input.execSql,
-        stage: saved,
-        evidence: await preparePrincipalHistoryEvidencePage({
-            indexRootHash: appended.value.indexRootHash,
-            scopeId: stage.scopeId,
-            organizationId: input.organizationId,
-            entries,
-            nodes: appended.value.indexNodes,
-        }),
-        previousProgress: stage.saved?.progress ?? null,
-        stillCurrent: () => recoveryIsCurrent(input),
-    });
-    stage.current = current;
-    stage.saved = saved;
-    stage.complete = complete;
-}
-async function finishRecovery(input, stage, checkpoint, storedCurrent) {
-    if (!stage.current || !stage.complete)
-        throw new KeyingVerificationError("missing_dependency", "Principal history ended before its pinned head");
-    const history = stage.verifier.finish(input.expectedHead);
-    if (!history.ok)
-        throw history.error;
-    const selected = await selectRecoveredPrincipalHistory({
-        options: input,
-        scopeId: stage.scopeId,
-        history: history.value,
-        checkpoint,
-    });
-    const current = await verifyPrincipalPolicyCurrent({
-        current: stage.current,
-        history: selected,
-    });
-    if (!current.ok) {
-        if (storedCurrent)
-            throw new StoredPrincipalCurrentRejectedError(current.error);
-        throw current.error;
-    }
-    verifyPrincipalPolicyCheckpoint({
-        chain: current.value.retainedHistory,
-        currentState: current.value.state,
-        localCheckpoint: checkpoint,
-    });
-    const latest = await loadPrincipalPolicyCheckpoint(input.execSql, input.expectedHead.principalType, input.expectedHead.principalId);
-    if (latest?.version !== checkpoint?.version ||
-        latest?.stateHash !== checkpoint?.stateHash)
-        throw new PrincipalHistoryRecoveryRaceError("Local principal checkpoint changed during history recovery");
-    assertCurrent(input);
-    if (!input.offline)
-        await publishReusablePrincipalHistoryPrefix(input, stage.scopeId, stage.verifier, stage.current);
-    assertCurrent(input);
-    return { current: stage.current, policy: current.value };
-}
-function completedStageMatchesHead(stage, expectedHead) {
-    if (!stage.complete || !stage.current)
-        return false;
-    try {
-        assertExpectedHead(stage.current, expectedHead);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Returns whether the stage's current artifacts came from local storage. A
- * completed stage already authenticates every signed entry through the exact
- * pinned head, so an online read of that head could only return the pinned
- * bytes or refuse. Server-current freshness belongs to the caller's discovery.
- */
-async function readRecoveryPages(input, stage) {
-    if (input.offline) {
-        if (!stage.complete || !stage.current)
-            throw new KeyingVerificationError("missing_dependency", "Completed principal history is unavailable offline");
-        assertExpectedHead(stage.current, input.expectedHead);
-        return true;
-    }
-    if (completedStageMatchesHead(stage, input.expectedHead))
-        return true;
-    let receivedFinalPage = false;
-    for await (const result of input.historyReader.getPrincipalPolicyPages(input.expectedHead.principalType, input.expectedHead.principalId, {
-        signal: input.signal,
-        stateHash: input.expectedHead.stateHash,
-        ...(stage.saved && stage.current
-            ? {
-                resume: {
-                    current: stage.current,
-                    afterVersion: stage.saved.afterVersion,
-                },
-            }
-            : { afterVersion: stage.initialAfterVersion }),
-    })) {
-        if (!result.ok) {
-            // A rejected transport pin cannot justify skipping history on retry.
-            // Discard only this operation's progress, then let a new call replay it.
-            if (result.kind === "shape" && stage.saved)
-                await discardPrincipalHistoryStage(input.execSql, stage.saved, () => recoveryIsCurrent(input));
-            throw new PrincipalPolicyHistoryReadError(result);
-        }
-        await acceptPage(input, stage, result.data);
-        receivedFinalPage = result.data.historyPage.nextAfterVersion === null;
-    }
-    if (!receivedFinalPage)
-        throw new KeyingVerificationError("missing_dependency", "Principal history transport did not complete");
-    return false;
-}
-async function recover(input, allowEvidenceRebuild = true) {
-    assertCurrent(input);
-    const checkpoint = await loadPrincipalPolicyCheckpoint(input.execSql, input.expectedHead.principalType, input.expectedHead.principalId);
-    if (checkpoint && input.expectedHead.version < checkpoint.version)
-        throw new KeyingVerificationError(input.offline ? "missing_dependency" : "rollback", "Requested principal history predates the local checkpoint");
-    // Validate the requested pin/selection before creating any disposable caches.
-    createPrincipalPolicyHistoryVerifier({
-        principalType: input.expectedHead.principalType,
-        principalId: input.expectedHead.principalId,
-        localCheckpoint: checkpoint,
-        retainedReferences: input.retainedReferences ?? [],
-    });
-    const historyInput = {
-        principalType: input.expectedHead.principalType,
-        principalId: input.expectedHead.principalId,
-    };
-    const stage = await restorePrincipalHistoryRecoveryStage(input, historyInput, allowEvidenceRebuild);
-    try {
-        if (stage.fromCache)
-            await validatePrincipalHistoryRecoveryAuthority(input, stage.verifier);
-        const stored = await readRecoveryPages(input, stage);
-        return await finishRecovery(input, stage, checkpoint, stored && !input.offline);
-    }
-    catch (error) {
-        const lostEvidence = error instanceof PrincipalHistoryEvidenceUnavailableError;
-        // Disposable stored artifacts never refuse an online reader: replay them.
-        const disposable = error instanceof PrincipalHistoryPrefixDisconnectedError ||
-            error instanceof StoredPrincipalCurrentRejectedError;
-        if (!lostEvidence && !disposable)
-            throw error;
-        if (stage.saved)
-            await discardPrincipalHistoryStage(input.execSql, stage.saved, () => recoveryIsCurrent(input));
-        if (!input.offline &&
-            allowEvidenceRebuild &&
-            (lostEvidence || stage.fromCache))
-            return recover(input, false);
-        throw error.verificationError;
-    }
-}
-/**
- * Recover one exact head with bounded retained history and durable checked progress.
- * The result is a sparse current-policy capability; this does not advance app checkpoints.
- * Retain organization version 1 when the result will establish founder binding.
- */
-export function recoverPrincipalPolicyHistory(options) {
-    return recoverPrincipalPolicyHistoryWithVersions(options, []);
-}
-/** Internal bounded display selection; missing proof rows use the normal single rebuild. */
-export async function recoverPrincipalPolicyHistoryWithVersions(options, retainedVersions) {
-    if (!Array.isArray(retainedVersions) ||
-        retainedVersions.length + (options.retainedReferences?.length ?? 0) >
-            PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT ||
-        retainedVersions.some((version) => !Number.isSafeInteger(version) ||
-            version < 1 ||
-            version > options.expectedHead.version))
-        throw new KeyingVerificationError("invalid_shape", "Principal display history selection exceeds its bounded range");
-    if (options.offline !== undefined && typeof options.offline !== "boolean")
-        throw new KeyingVerificationError("invalid_shape", "Invalid principal history transport mode");
-    if (!options.organizationId ||
-        (options.expectedHead.principalType === "organization" &&
-            options.expectedHead.principalId !== options.organizationId))
-        throw new KeyingVerificationError("object_mismatch", "Principal history organization scope is invalid");
-    if (options.retainedReferences?.some((reference) => reference.version > options.expectedHead.version))
-        throw new KeyingVerificationError("missing_dependency", "Requested history reference is beyond the recovery head");
-    const input = {
-        ...options,
-        historyVerification: options.historyVerification ?? "standard",
-        expectedHead: structuredClone(options.expectedHead),
-        retainedReferences: structuredClone(options.retainedReferences ?? []),
-        retainedVersions: [...retainedVersions],
-        protection: ownPrincipalHistoryProtection(options.protection),
-    };
-    try {
-        input.protection.context = principalHistoryVerificationContext(input);
-        return await recover(input);
-    }
-    finally {
-        input.protection.localKey.fill(0);
-    }
-}
-//# sourceMappingURL=recoverPrincipalPolicyHistory.js.map

package/workflows/principals/recoverPrincipalPolicyHistory.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"recoverPrincipalPolicyHistory.js","sourceRoot":"","sources":["recoverPrincipalPolicyHistory.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PrincipalPolicyPageCurrent } from \"@tearleads/api-client\";\nimport {\n  createPrincipalPolicyHistoryVerifier,\n  KeyingVerificationError,\n  PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT,\n  type PrincipalPolicyCheckpoint,\n  type PrincipalPolicyHistoryInput,\n  verifyPrincipalPolicyCheckpoint,\n  verifyPrincipalPolicyCurrent,\n} from \"@tearleads/crypto\";\nimport type { PrincipalPolicyPageResponse } from \"@tearleads/validators/response\";\nimport { assertProjectionVerificationCurrent } from \"../../data/keyingProjectionVerification/types\";\nimport { loadPrincipalPolicyCheckpoint } from \"../../data/persistence/keyingCheckpointPersistence\";\nimport { preparePrincipalHistoryEvidencePage } from \"../../data/persistence/principalHistoryEvidencePersistence\";\nimport {\n  discardPrincipalHistoryStage,\n  savePrincipalHistoryStage,\n} from \"../../data/persistence/principalHistoryStagePersistence\";\nimport { ownPrincipalHistoryProtection } from \"../../data/principals/principalHistoryProtection\";\nimport { principalHistoryStageProtection } from \"../../data/principals/principalHistoryStageProtection\";\nimport { collectPrincipalPolicySignerPublicKeys } from \"./policyVerification\";\nimport { validatePrincipalHistoryRecoveryAuthority } from \"./principalHistoryRecoveryAuthority\";\nimport { publishReusablePrincipalHistoryPrefix } from \"./principalHistoryRecoveryPrefix\";\nimport {\n  PrincipalHistoryEvidenceUnavailableError,\n  type PrincipalHistorySelectionOptions,\n  selectRecoveredPrincipalHistory,\n} from \"./principalHistoryRecoveryReferences\";\nimport {\n  type PrincipalHistoryRecoveryStage,\n  restorePrincipalHistoryRecoveryStage,\n} from \"./principalHistoryRecoveryStage\";\nimport {\n  PrincipalHistoryRecoveryRaceError,\n  PrincipalPolicyHistoryReadError,\n  type RecoveredPrincipalPolicyHistory,\n  type RecoverPrincipalPolicyHistoryOptions,\n} from \"./principalHistoryRecoveryTypes\";\nimport {\n  assertPrincipalHistoryVerificationMode,\n  principalHistoryVerificationContext,\n} from \"./principalHistoryRecoveryVerification\";\n\nclass PrincipalHistoryPrefixDisconnectedError extends Error {\n  constructor(readonly verificationError: KeyingVerificationError) {\n    super(verificationError.message);\n    this.name = \"PrincipalHistoryPrefixDisconnectedError\";\n  }\n}\n\n/** Stored current artifacts of a completed stage failed their signed-history check. */\nclass StoredPrincipalCurrentRejectedError extends Error {\n  constructor(readonly verificationError: KeyingVerificationError) {\n    super(verificationError.message);\n    this.name = \"StoredPrincipalCurrentRejectedError\";\n  }\n}\n\nfunction currentArtifacts(\n  page: PrincipalPolicyPageResponse,\n): PrincipalPolicyPageCurrent {\n  return {\n    currentState: page.currentState,\n    currentPayload: page.currentPayload,\n    currentProjection: page.currentProjection,\n    currentGrants: page.currentGrants,\n    currentMemberEnvelopes: page.currentMemberEnvelopes,\n  };\n}\n\nfunction recoveryIsCurrent(\n  input: RecoverPrincipalPolicyHistoryOptions,\n): boolean {\n  return !input.signal?.aborted && input.stillCurrent();\n}\n\nfunction assertCurrent(input: RecoverPrincipalPolicyHistoryOptions): void {\n  assertProjectionVerificationCurrent(() => recoveryIsCurrent(input));\n}\n\nfunction assertExpectedHead(\n  current: PrincipalPolicyPageCurrent,\n  expectedHead: RecoverPrincipalPolicyHistoryOptions[\"expectedHead\"],\n): void {\n  for (const field of [\n    \"principalType\",\n    \"principalId\",\n    \"version\",\n    \"stateHash\",\n    \"keyEpoch\",\n    \"keyFingerprint\",\n  ] as const) {\n    if (current.currentState[field] !== expectedHead[field])\n      throw new KeyingVerificationError(\n        \"object_mismatch\",\n        \"Principal history page does not match its requested head\",\n      );\n  }\n}\n\nasync function acceptPage(\n  input: RecoverPrincipalPolicyHistoryOptions,\n  stage: PrincipalHistoryRecoveryStage,\n  response: PrincipalPolicyPageResponse,\n): Promise<void> {\n  const page = structuredClone(response);\n  assertCurrent(input);\n  assertExpectedHead(page, input.expectedHead);\n  if (stage.complete) {\n    if (\n      page.previousStates.length !== 0 ||\n      page.historyPage.nextAfterVersion !== null\n    )\n      throw new KeyingVerificationError(\n        \"invalid_shape\",\n        \"Completed history returned additional entries\",\n      );\n    stage.current = currentArtifacts(page);\n    return;\n  }\n  const complete = page.historyPage.nextAfterVersion === null;\n  const current = currentArtifacts(page);\n  const entries = [...page.previousStates];\n  if (complete)\n    entries.push({\n      state: current.currentState,\n      projection: current.currentProjection,\n      grants: current.currentGrants,\n    });\n  assertPrincipalHistoryVerificationMode(input, entries);\n  const keys = await collectPrincipalPolicySignerPublicKeys({\n    bundle: { ...current, previousStates: page.previousStates },\n    resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,\n  });\n  if (\"error\" in keys)\n    throw new KeyingVerificationError(\n      keys.error === \"not-found\" ? \"missing_dependency\" : \"signer_mismatch\",\n      \"Principal history signer identity could not be authenticated\",\n    );\n  const externalAuthority = await input.loadExternalAuthority?.(\n    entries.flatMap(({ state }) =>\n      state.externalAuthority ? [state.externalAuthority] : [],\n    ),\n  );\n  const appended = await stage.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 PrincipalHistoryPrefixDisconnectedError(appended.error);\n    throw appended.error;\n  }\n  const next = {\n    id: stage.id,\n    organizationId: input.organizationId,\n    currentJson: JSON.stringify(current),\n    afterVersion: appended.value.throughVersion - (complete ? 1 : 0),\n    complete,\n  };\n  const protectedProgress = await stage.verifier.exportProgress(\n    await principalHistoryStageProtection(\n      input.protection,\n      input.expectedHead,\n      next,\n    ),\n  );\n  if (!protectedProgress.ok) throw protectedProgress.error;\n  const saved = { ...next, progress: protectedProgress.value };\n  await savePrincipalHistoryStage({\n    execSql: input.execSql,\n    stage: saved,\n    evidence: await preparePrincipalHistoryEvidencePage({\n      indexRootHash: appended.value.indexRootHash,\n      scopeId: stage.scopeId,\n      organizationId: input.organizationId,\n      entries,\n      nodes: appended.value.indexNodes,\n    }),\n    previousProgress: stage.saved?.progress ?? null,\n    stillCurrent: () => recoveryIsCurrent(input),\n  });\n  stage.current = current;\n  stage.saved = saved;\n  stage.complete = complete;\n}\n\nasync function finishRecovery(\n  input: PrincipalHistorySelectionOptions,\n  stage: PrincipalHistoryRecoveryStage,\n  checkpoint: PrincipalPolicyCheckpoint | null,\n  storedCurrent: boolean,\n): Promise<RecoveredPrincipalPolicyHistory> {\n  if (!stage.current || !stage.complete)\n    throw new KeyingVerificationError(\n      \"missing_dependency\",\n      \"Principal history ended before its pinned head\",\n    );\n  const history = stage.verifier.finish(input.expectedHead);\n  if (!history.ok) throw history.error;\n  const selected = await selectRecoveredPrincipalHistory({\n    options: input,\n    scopeId: stage.scopeId,\n    history: history.value,\n    checkpoint,\n  });\n  const current = await verifyPrincipalPolicyCurrent({\n    current: stage.current,\n    history: selected,\n  });\n  if (!current.ok) {\n    if (storedCurrent)\n      throw new StoredPrincipalCurrentRejectedError(current.error);\n    throw current.error;\n  }\n  verifyPrincipalPolicyCheckpoint({\n    chain: current.value.retainedHistory,\n    currentState: current.value.state,\n    localCheckpoint: checkpoint,\n  });\n  const latest = await loadPrincipalPolicyCheckpoint(\n    input.execSql,\n    input.expectedHead.principalType,\n    input.expectedHead.principalId,\n  );\n  if (\n    latest?.version !== checkpoint?.version ||\n    latest?.stateHash !== checkpoint?.stateHash\n  )\n    throw new PrincipalHistoryRecoveryRaceError(\n      \"Local principal checkpoint changed during history recovery\",\n    );\n  assertCurrent(input);\n  if (!input.offline)\n    await publishReusablePrincipalHistoryPrefix(\n      input,\n      stage.scopeId,\n      stage.verifier,\n      stage.current,\n    );\n  assertCurrent(input);\n  return { current: stage.current, policy: current.value };\n}\n\nfunction completedStageMatchesHead(\n  stage: PrincipalHistoryRecoveryStage,\n  expectedHead: RecoverPrincipalPolicyHistoryOptions[\"expectedHead\"],\n): boolean {\n  if (!stage.complete || !stage.current) return false;\n  try {\n    assertExpectedHead(stage.current, expectedHead);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Returns whether the stage's current artifacts came from local storage. A\n * completed stage already authenticates every signed entry through the exact\n * pinned head, so an online read of that head could only return the pinned\n * bytes or refuse. Server-current freshness belongs to the caller's discovery.\n */\nasync function readRecoveryPages(\n  input: RecoverPrincipalPolicyHistoryOptions,\n  stage: PrincipalHistoryRecoveryStage,\n): Promise<boolean> {\n  if (input.offline) {\n    if (!stage.complete || !stage.current)\n      throw new KeyingVerificationError(\n        \"missing_dependency\",\n        \"Completed principal history is unavailable offline\",\n      );\n    assertExpectedHead(stage.current, input.expectedHead);\n    return true;\n  }\n  if (completedStageMatchesHead(stage, input.expectedHead)) return true;\n  let receivedFinalPage = false;\n  for await (const result of input.historyReader.getPrincipalPolicyPages(\n    input.expectedHead.principalType,\n    input.expectedHead.principalId,\n    {\n      signal: input.signal,\n      stateHash: input.expectedHead.stateHash,\n      ...(stage.saved && stage.current\n        ? {\n            resume: {\n              current: stage.current,\n              afterVersion: stage.saved.afterVersion,\n            },\n          }\n        : { afterVersion: stage.initialAfterVersion }),\n    },\n  )) {\n    if (!result.ok) {\n      // A rejected transport pin cannot justify skipping history on retry.\n      // Discard only this operation's progress, then let a new call replay it.\n      if (result.kind === \"shape\" && stage.saved)\n        await discardPrincipalHistoryStage(input.execSql, stage.saved, () =>\n          recoveryIsCurrent(input),\n        );\n      throw new PrincipalPolicyHistoryReadError(result);\n    }\n    await acceptPage(input, stage, result.data);\n    receivedFinalPage = result.data.historyPage.nextAfterVersion === null;\n  }\n  if (!receivedFinalPage)\n    throw new KeyingVerificationError(\n      \"missing_dependency\",\n      \"Principal history transport did not complete\",\n    );\n  return false;\n}\n\nasync function recover(\n  input: PrincipalHistorySelectionOptions,\n  allowEvidenceRebuild = true,\n): Promise<RecoveredPrincipalPolicyHistory> {\n  assertCurrent(input);\n  const checkpoint = await loadPrincipalPolicyCheckpoint(\n    input.execSql,\n    input.expectedHead.principalType,\n    input.expectedHead.principalId,\n  );\n  if (checkpoint && input.expectedHead.version < checkpoint.version)\n    throw new KeyingVerificationError(\n      input.offline ? \"missing_dependency\" : \"rollback\",\n      \"Requested principal history predates the local checkpoint\",\n    );\n  // Validate the requested pin/selection before creating any disposable caches.\n  createPrincipalPolicyHistoryVerifier({\n    principalType: input.expectedHead.principalType,\n    principalId: input.expectedHead.principalId,\n    localCheckpoint: checkpoint,\n    retainedReferences: input.retainedReferences ?? [],\n  });\n  const historyInput: PrincipalPolicyHistoryInput = {\n    principalType: input.expectedHead.principalType,\n    principalId: input.expectedHead.principalId,\n  };\n  const stage = await restorePrincipalHistoryRecoveryStage(\n    input,\n    historyInput,\n    allowEvidenceRebuild,\n  );\n  try {\n    if (stage.fromCache)\n      await validatePrincipalHistoryRecoveryAuthority(input, stage.verifier);\n    const stored = await readRecoveryPages(input, stage);\n    return await finishRecovery(\n      input,\n      stage,\n      checkpoint,\n      stored && !input.offline,\n    );\n  } catch (error) {\n    const lostEvidence =\n      error instanceof PrincipalHistoryEvidenceUnavailableError;\n    // Disposable stored artifacts never refuse an online reader: replay them.\n    const disposable =\n      error instanceof PrincipalHistoryPrefixDisconnectedError ||\n      error instanceof StoredPrincipalCurrentRejectedError;\n    if (!lostEvidence && !disposable) throw error;\n    if (stage.saved)\n      await discardPrincipalHistoryStage(input.execSql, stage.saved, () =>\n        recoveryIsCurrent(input),\n      );\n    if (\n      !input.offline &&\n      allowEvidenceRebuild &&\n      (lostEvidence || stage.fromCache)\n    )\n      return recover(input, false);\n    throw error.verificationError;\n  }\n}\n\n/**\n * Recover one exact head with bounded retained history and durable checked progress.\n * The result is a sparse current-policy capability; this does not advance app checkpoints.\n * Retain organization version 1 when the result will establish founder binding.\n */\nexport function recoverPrincipalPolicyHistory(\n  options: RecoverPrincipalPolicyHistoryOptions,\n): Promise<RecoveredPrincipalPolicyHistory> {\n  return recoverPrincipalPolicyHistoryWithVersions(options, []);\n}\n\n/** Internal bounded display selection; missing proof rows use the normal single rebuild. */\nexport async function recoverPrincipalPolicyHistoryWithVersions(\n  options: RecoverPrincipalPolicyHistoryOptions,\n  retainedVersions: readonly number[],\n): Promise<RecoveredPrincipalPolicyHistory> {\n  if (\n    !Array.isArray(retainedVersions) ||\n    retainedVersions.length + (options.retainedReferences?.length ?? 0) >\n      PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT ||\n    retainedVersions.some(\n      (version) =>\n        !Number.isSafeInteger(version) ||\n        version < 1 ||\n        version > options.expectedHead.version,\n    )\n  )\n    throw new KeyingVerificationError(\n      \"invalid_shape\",\n      \"Principal display history selection exceeds its bounded range\",\n    );\n  if (options.offline !== undefined && typeof options.offline !== \"boolean\")\n    throw new KeyingVerificationError(\n      \"invalid_shape\",\n      \"Invalid principal history transport mode\",\n    );\n  if (\n    !options.organizationId ||\n    (options.expectedHead.principalType === \"organization\" &&\n      options.expectedHead.principalId !== options.organizationId)\n  )\n    throw new KeyingVerificationError(\n      \"object_mismatch\",\n      \"Principal history organization scope is invalid\",\n    );\n  if (\n    options.retainedReferences?.some(\n      (reference) => reference.version > options.expectedHead.version,\n    )\n  )\n    throw new KeyingVerificationError(\n      \"missing_dependency\",\n      \"Requested history reference is beyond the recovery head\",\n    );\n  const input = {\n    ...options,\n    historyVerification: options.historyVerification ?? \"standard\",\n    expectedHead: structuredClone(options.expectedHead),\n    retainedReferences: structuredClone(options.retainedReferences ?? []),\n    retainedVersions: [...retainedVersions],\n    protection: ownPrincipalHistoryProtection(options.protection),\n  };\n  try {\n    input.protection.context = principalHistoryVerificationContext(input);\n    return await recover(input);\n  } finally {\n    input.protection.localKey.fill(0);\n  }\n}\n"]}

package/workflows/principals/recoverProjectionPolicyHistory.d.ts

@@ -1,9 +0,0 @@
-import { type ReferencedPrincipalHead, type VerifiedPrincipalPolicySelection } from "../../internal/crypto/index.js";
-import type { ProjectionPolicyEvidenceResponse } from "../../internal/validators/response/index.js";
-import type { PublicPrincipalHistoryOptions } from "./publicPrincipalHistoryTypes.js";
-export interface ProjectionPolicyHistoryRecoveryOptions extends Omit<PublicPrincipalHistoryOptions, "source" | "loadExternalAuthority" | "strictAdmins" | "authorityGroupId" | "replay"> {
-    readonly evidence: ProjectionPolicyEvidenceResponse;
-    readonly references: readonly ReferencedPrincipalHead[];
-}
-/** Public authorization only; no current-policy cache or checkpoint is written. */
-export declare function recoverProjectionPolicyHistory(input: ProjectionPolicyHistoryRecoveryOptions): Promise<VerifiedPrincipalPolicySelection[]>;

package/workflows/principals/recoverProjectionPolicyHistory.js

@@ -1,98 +0,0 @@
-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/recoverProjectionPolicyHistory.js.map

@@ -1 +0,0 @@
-{"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"]}