@tearleads/client-sdk 0.1.62 → 0.1.64

package/workflows/principals/historyRecovery/loadRecoveredPrincipalHistoryPage.js

@@ -0,0 +1,119 @@
+import { KeyingVerificationError, verifyPrincipalPolicyHistoryReferences, } from "../../../internal/crypto/index.js";
+import { isPrincipalPolicyStateChainEntryResponse, PRINCIPAL_DISPLAY_HISTORY_PAGE_SIZE, } from "../../../internal/validators/response/index.js";
+import { assertProjectionVerificationCurrent } from "../../../data/keyingProjectionVerification/types.js";
+import { loadPrincipalPolicyCheckpoint } from "../../../data/persistence/keyingCheckpointPersistence.js";
+import { loadPrincipalHistoryReference } from "../../../data/persistence/principalHistoryEvidencePersistence.js";
+import { principalHistoryEvidenceScopeId } from "../../../data/principals/principalHistoryPrefixProtection.js";
+import { ownPrincipalHistoryProtection } from "../../../data/principals/principalHistoryProtection.js";
+import { loadVerifiedPrincipalHistoryPrefix } from "./principalHistoryRecoveryPrefix.js";
+import { PrincipalHistoryEvidenceUnavailableError } from "./principalHistoryRecoveryReferences.js";
+import { PrincipalHistoryRecoveryRaceError, } from "./principalHistoryRecoveryTypes.js";
+import { principalHistoryVerificationContext } from "./principalHistoryRecoveryVerification.js";
+/** Read a bounded historical window from an already recovered, exact private root. */
+export async function loadRecoveredPrincipalHistoryPage(options, beforeVersion = options.expectedHead.version + 1) {
+    const owned = {
+        ...options,
+        expectedHead: structuredClone(options.expectedHead),
+        protection: ownPrincipalHistoryProtection(options.protection),
+    };
+    try {
+        return await readPage(owned, beforeVersion);
+    }
+    finally {
+        owned.protection.localKey.fill(0);
+    }
+}
+async function readPage(options, beforeVersion) {
+    if (!Number.isSafeInteger(beforeVersion) ||
+        beforeVersion <= 1 ||
+        beforeVersion > options.expectedHead.version + 1)
+        throw new KeyingVerificationError("invalid_shape", "Principal history page cursor is outside the selected history");
+    const current = () => !options.signal?.aborted && options.stillCurrent();
+    assertProjectionVerificationCurrent(current);
+    const { scopeId, history } = await restoreReadRoot(options, current);
+    const checkpoint = await loadPrincipalPolicyCheckpoint(options.execSql, options.expectedHead.principalType, options.expectedHead.principalId);
+    if (checkpoint && checkpoint.version > options.expectedHead.version)
+        throw new PrincipalHistoryRecoveryRaceError("Principal checkpoint advanced beyond the selected display history");
+    const load = (version) => loadPageReference({
+        execSql: options.execSql,
+        scopeId,
+        history,
+        version,
+    });
+    const firstVersion = Math.max(1, beforeVersion - PRINCIPAL_DISPLAY_HISTORY_PAGE_SIZE);
+    const references = [];
+    for (let version = Math.max(1, firstVersion - 1); version < beforeVersion; version += 1) {
+        assertProjectionVerificationCurrent(current);
+        references.push(await load(version));
+    }
+    const checkpointReference = checkpoint
+        ? await load(checkpoint.version)
+        : undefined;
+    if (checkpointReference &&
+        checkpointReference.reference.stateHash !== checkpoint?.stateHash)
+        throw new KeyingVerificationError("equivocation", "Principal history page conflicts with its durable checkpoint");
+    const selected = await verifyPrincipalPolicyHistoryReferences({
+        history,
+        references,
+        checkpointReference,
+    });
+    if (!selected.ok)
+        throw new PrincipalHistoryEvidenceUnavailableError(selected.error);
+    await assertDisplayCheckpointCurrent(options, checkpoint);
+    assertProjectionVerificationCurrent(current);
+    // These exact rows passed inclusion and commitment verification above. Keep
+    // their display-only server timestamps, which the private current strips.
+    const retained = references.map(({ entry }) => responseEntry(entry));
+    return {
+        entries: retained.filter(({ state }) => state.version >= firstVersion && state.version < beforeVersion),
+        predecessor: retained.find(({ state }) => state.version === firstVersion - 1) ?? null,
+        nextBeforeVersion: firstVersion > 1 ? firstVersion : null,
+    };
+}
+async function assertDisplayCheckpointCurrent(options, checkpoint) {
+    const latest = await loadPrincipalPolicyCheckpoint(options.execSql, options.expectedHead.principalType, options.expectedHead.principalId);
+    if (latest?.version !== checkpoint?.version ||
+        latest?.stateHash !== checkpoint?.stateHash)
+        throw new PrincipalHistoryRecoveryRaceError("Principal checkpoint changed while reading display history");
+}
+async function loadPageReference(input) {
+    try {
+        return await loadPrincipalHistoryReference(input);
+    }
+    catch (error) {
+        if (error instanceof KeyingVerificationError)
+            throw new PrincipalHistoryEvidenceUnavailableError(error);
+        throw error;
+    }
+}
+function responseEntry(entry) {
+    if (!isPrincipalPolicyStateChainEntryResponse(entry))
+        throw new KeyingVerificationError("missing_dependency", "Principal history display metadata is unavailable");
+    return entry;
+}
+async function restoreReadRoot(options, current) {
+    const normalized = {
+        ...options,
+        protection: {
+            ...options.protection,
+            context: principalHistoryVerificationContext(options),
+        },
+    };
+    const scopeId = await principalHistoryEvidenceScopeId({
+        organizationId: options.organizationId,
+        head: options.expectedHead,
+        protection: normalized.protection,
+    });
+    const prefix = await loadVerifiedPrincipalHistoryPrefix(normalized, {
+        principalType: options.expectedHead.principalType,
+        principalId: options.expectedHead.principalId,
+    }, scopeId);
+    assertProjectionVerificationCurrent(current);
+    if (!prefix)
+        throw new KeyingVerificationError("missing_dependency", "Principal history page requires a recovered private prefix");
+    const finished = prefix.verifier.finish(options.expectedHead);
+    if (!finished.ok)
+        throw finished.error;
+    return { scopeId, history: finished.value };
+}
+//# sourceMappingURL=loadRecoveredPrincipalHistoryPage.js.map

package/workflows/principals/historyRecovery/loadRecoveredPrincipalHistoryPage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadRecoveredPrincipalHistoryPage.js","sourceRoot":"","sources":["loadRecoveredPrincipalHistoryPage.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  KeyingVerificationError,\n  type PrincipalPolicyHistoryReferenceProof,\n  type PrincipalPolicyStateChainEntry,\n  verifyPrincipalPolicyHistoryReferences,\n} from \"@tearleads/crypto\";\nimport {\n  isPrincipalPolicyStateChainEntryResponse,\n  PRINCIPAL_DISPLAY_HISTORY_PAGE_SIZE,\n  type PrincipalPolicyStateChainEntryResponse,\n} from \"@tearleads/validators/response\";\nimport { assertProjectionVerificationCurrent } from \"../../../data/keyingProjectionVerification/types\";\nimport { loadPrincipalPolicyCheckpoint } from \"../../../data/persistence/keyingCheckpointPersistence\";\nimport { loadPrincipalHistoryReference } from \"../../../data/persistence/principalHistoryEvidencePersistence\";\nimport { principalHistoryEvidenceScopeId } from \"../../../data/principals/principalHistoryPrefixProtection\";\nimport { ownPrincipalHistoryProtection } from \"../../../data/principals/principalHistoryProtection\";\nimport { loadVerifiedPrincipalHistoryPrefix } from \"./principalHistoryRecoveryPrefix\";\nimport { PrincipalHistoryEvidenceUnavailableError } from \"./principalHistoryRecoveryReferences\";\nimport {\n  PrincipalHistoryRecoveryRaceError,\n  type RecoverPrincipalPolicyHistoryOptions,\n} from \"./principalHistoryRecoveryTypes\";\nimport { principalHistoryVerificationContext } from \"./principalHistoryRecoveryVerification\";\n\nexport interface RecoveredPrincipalHistoryPage {\n  /** Ascending entries, with the immediate predecessor kept separately for diffs. */\n  readonly entries: readonly PrincipalPolicyStateChainEntryResponse[];\n  readonly predecessor: PrincipalPolicyStateChainEntryResponse | null;\n  readonly nextBeforeVersion: number | null;\n}\n\n/** Read a bounded historical window from an already recovered, exact private root. */\nexport async function loadRecoveredPrincipalHistoryPage(\n  options: RecoverPrincipalPolicyHistoryOptions,\n  beforeVersion = options.expectedHead.version + 1,\n): Promise<RecoveredPrincipalHistoryPage> {\n  const owned = {\n    ...options,\n    expectedHead: structuredClone(options.expectedHead),\n    protection: ownPrincipalHistoryProtection(options.protection),\n  };\n  try {\n    return await readPage(owned, beforeVersion);\n  } finally {\n    owned.protection.localKey.fill(0);\n  }\n}\n\nasync function readPage(\n  options: RecoverPrincipalPolicyHistoryOptions,\n  beforeVersion: number,\n): Promise<RecoveredPrincipalHistoryPage> {\n  if (\n    !Number.isSafeInteger(beforeVersion) ||\n    beforeVersion <= 1 ||\n    beforeVersion > options.expectedHead.version + 1\n  )\n    throw new KeyingVerificationError(\n      \"invalid_shape\",\n      \"Principal history page cursor is outside the selected history\",\n    );\n  const current = () => !options.signal?.aborted && options.stillCurrent();\n  assertProjectionVerificationCurrent(current);\n  const { scopeId, history } = await restoreReadRoot(options, current);\n  const checkpoint = await loadPrincipalPolicyCheckpoint(\n    options.execSql,\n    options.expectedHead.principalType,\n    options.expectedHead.principalId,\n  );\n  if (checkpoint && checkpoint.version > options.expectedHead.version)\n    throw new PrincipalHistoryRecoveryRaceError(\n      \"Principal checkpoint advanced beyond the selected display history\",\n    );\n  const load = (version: number) =>\n    loadPageReference({\n      execSql: options.execSql,\n      scopeId,\n      history,\n      version,\n    });\n  const firstVersion = Math.max(\n    1,\n    beforeVersion - PRINCIPAL_DISPLAY_HISTORY_PAGE_SIZE,\n  );\n  const references: PrincipalPolicyHistoryReferenceProof[] = [];\n  for (\n    let version = Math.max(1, firstVersion - 1);\n    version < beforeVersion;\n    version += 1\n  ) {\n    assertProjectionVerificationCurrent(current);\n    references.push(await load(version));\n  }\n  const checkpointReference = checkpoint\n    ? await load(checkpoint.version)\n    : undefined;\n  if (\n    checkpointReference &&\n    checkpointReference.reference.stateHash !== checkpoint?.stateHash\n  )\n    throw new KeyingVerificationError(\n      \"equivocation\",\n      \"Principal history page conflicts with its durable checkpoint\",\n    );\n  const selected = await verifyPrincipalPolicyHistoryReferences({\n    history,\n    references,\n    checkpointReference,\n  });\n  if (!selected.ok)\n    throw new PrincipalHistoryEvidenceUnavailableError(selected.error);\n  await assertDisplayCheckpointCurrent(options, checkpoint);\n  assertProjectionVerificationCurrent(current);\n  // These exact rows passed inclusion and commitment verification above. Keep\n  // their display-only server timestamps, which the private current strips.\n  const retained = references.map(({ entry }) => responseEntry(entry));\n  return {\n    entries: retained.filter(\n      ({ state }) =>\n        state.version >= firstVersion && state.version < beforeVersion,\n    ),\n    predecessor:\n      retained.find(({ state }) => state.version === firstVersion - 1) ?? null,\n    nextBeforeVersion: firstVersion > 1 ? firstVersion : null,\n  };\n}\n\nasync function assertDisplayCheckpointCurrent(\n  options: RecoverPrincipalPolicyHistoryOptions,\n  checkpoint: Awaited<ReturnType<typeof loadPrincipalPolicyCheckpoint>>,\n) {\n  const latest = await loadPrincipalPolicyCheckpoint(\n    options.execSql,\n    options.expectedHead.principalType,\n    options.expectedHead.principalId,\n  );\n  if (\n    latest?.version !== checkpoint?.version ||\n    latest?.stateHash !== checkpoint?.stateHash\n  )\n    throw new PrincipalHistoryRecoveryRaceError(\n      \"Principal checkpoint changed while reading display history\",\n    );\n}\n\nasync function loadPageReference(\n  input: Parameters<typeof loadPrincipalHistoryReference>[0],\n) {\n  try {\n    return await loadPrincipalHistoryReference(input);\n  } catch (error) {\n    if (error instanceof KeyingVerificationError)\n      throw new PrincipalHistoryEvidenceUnavailableError(error);\n    throw error;\n  }\n}\n\nfunction responseEntry(\n  entry: PrincipalPolicyStateChainEntry,\n): PrincipalPolicyStateChainEntryResponse {\n  if (!isPrincipalPolicyStateChainEntryResponse(entry))\n    throw new KeyingVerificationError(\n      \"missing_dependency\",\n      \"Principal history display metadata is unavailable\",\n    );\n  return entry;\n}\n\nasync function restoreReadRoot(\n  options: RecoverPrincipalPolicyHistoryOptions,\n  current: () => boolean,\n) {\n  const normalized = {\n    ...options,\n    protection: {\n      ...options.protection,\n      context: principalHistoryVerificationContext(options),\n    },\n  };\n  const scopeId = await principalHistoryEvidenceScopeId({\n    organizationId: options.organizationId,\n    head: options.expectedHead,\n    protection: normalized.protection,\n  });\n  const prefix = await loadVerifiedPrincipalHistoryPrefix(\n    normalized,\n    {\n      principalType: options.expectedHead.principalType,\n      principalId: options.expectedHead.principalId,\n    },\n    scopeId,\n  );\n  assertProjectionVerificationCurrent(current);\n  if (!prefix)\n    throw new KeyingVerificationError(\n      \"missing_dependency\",\n      \"Principal history page requires a recovered private prefix\",\n    );\n  const finished = prefix.verifier.finish(options.expectedHead);\n  if (!finished.ok) throw finished.error;\n  return { scopeId, history: finished.value };\n}\n"]}

package/workflows/principals/historyRecovery/principalHistoryRecoveryAuthority.js

@@ -0,0 +1,20 @@
+import { KeyingVerificationError, } from "../../../internal/crypto/index.js";
+import { principalHeadMatchesReference } from "../../../data/principals/organizationAuthorityDescriptor.js";
+import { PrincipalHistoryEvidenceUnavailableError } from "./principalHistoryRecoveryReferences.js";
+/** Reusable signatures remain conditional on their authenticated authority lineage. */
+export async function validatePrincipalHistoryRecoveryAuthority(input, verifier) {
+    const reference = verifier.getExternalAuthorityReference();
+    if (!reference)
+        return;
+    try {
+        const authority = await input.loadExternalAuthority?.([reference]);
+        if (!authority?.states.some(({ head }) => principalHeadMatchesReference(head, reference)))
+            throw new KeyingVerificationError("stale_predecessor", "Cached principal history has a different authority lineage");
+    }
+    catch (error) {
+        if (error instanceof KeyingVerificationError)
+            throw new PrincipalHistoryEvidenceUnavailableError(error);
+        throw error;
+    }
+}
+//# sourceMappingURL=principalHistoryRecoveryAuthority.js.map

package/workflows/principals/historyRecovery/principalHistoryRecoveryAuthority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalHistoryRecoveryAuthority.js","sourceRoot":"","sources":["principalHistoryRecoveryAuthority.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,GAExB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,6BAA6B,EAAE,MAAM,0DAA0D,CAAC;AACzG,OAAO,EAAE,wCAAwC,EAAE,MAAM,sCAAsC,CAAC;AAGhG,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,yCAAyC,CAC7D,KAA2C,EAC3C,QAAwC;IAExC,MAAM,SAAS,GAAG,QAAQ,CAAC,6BAA6B,EAAE,CAAC;IAC3D,IAAI,CAAC,SAAS;QAAE,OAAO;IACvB,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,qBAAqB,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;QACnE,IACE,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CACnC,6BAA6B,CAAC,IAAI,EAAE,SAAS,CAAC,CAC/C;YAED,MAAM,IAAI,uBAAuB,CAC/B,mBAAmB,EACnB,4DAA4D,CAC7D,CAAC;IACN,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,uBAAuB;YAC1C,MAAM,IAAI,wCAAwC,CAAC,KAAK,CAAC,CAAC;QAC5D,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["import {\n  KeyingVerificationError,\n  type PrincipalPolicyHistoryVerifier,\n} from \"@tearleads/crypto\";\nimport { principalHeadMatchesReference } from \"../../../data/principals/organizationAuthorityDescriptor\";\nimport { PrincipalHistoryEvidenceUnavailableError } from \"./principalHistoryRecoveryReferences\";\nimport type { RecoverPrincipalPolicyHistoryOptions } from \"./principalHistoryRecoveryTypes\";\n\n/** Reusable signatures remain conditional on their authenticated authority lineage. */\nexport async function validatePrincipalHistoryRecoveryAuthority(\n  input: RecoverPrincipalPolicyHistoryOptions,\n  verifier: PrincipalPolicyHistoryVerifier,\n): Promise<void> {\n  const reference = verifier.getExternalAuthorityReference();\n  if (!reference) return;\n  try {\n    const authority = await input.loadExternalAuthority?.([reference]);\n    if (\n      !authority?.states.some(({ head }) =>\n        principalHeadMatchesReference(head, reference),\n      )\n    )\n      throw new KeyingVerificationError(\n        \"stale_predecessor\",\n        \"Cached principal history has a different authority lineage\",\n      );\n  } catch (error) {\n    if (error instanceof KeyingVerificationError)\n      throw new PrincipalHistoryEvidenceUnavailableError(error);\n    throw error;\n  }\n}\n"]}

package/workflows/principals/historyRecovery/principalHistoryRecoveryPrefix.js

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

package/workflows/principals/historyRecovery/principalHistoryRecoveryPrefix.js.map

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

package/workflows/principals/historyRecovery/principalHistoryRecoveryReferences.js

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

package/workflows/principals/historyRecovery/principalHistoryRecoveryReferences.js.map

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

package/workflows/principals/historyRecovery/principalHistoryRecoveryStage.js

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

package/workflows/principals/historyRecovery/principalHistoryRecoveryStage.js.map

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

package/workflows/principals/historyRecovery/principalHistoryRecoveryTypes.d.ts

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

package/workflows/principals/historyRecovery/principalHistoryRecoveryTypes.js

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

package/workflows/principals/historyRecovery/principalHistoryRecoveryTypes.js.map

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

package/workflows/principals/historyRecovery/principalHistoryRecoveryVerification.js

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

package/workflows/principals/historyRecovery/recoverCurrentOrganizationPolicy.js

@@ -0,0 +1,38 @@
+import { assertProjectionVerificationCurrent } from "../../../data/keyingProjectionVerification/types.js";
+import { ownPrincipalHistoryProtection } from "../../../data/principals/principalHistoryProtection.js";
+import { createPrincipalRecoveryReader, } from "../recoveryOperation/principalRecoveryMemo.js";
+import { isPrincipalRecoveryOutage } from "../recoveryOperation/principalRecoveryOutage.js";
+/** Discover and verify current directory artifacts, including protected offline recovery. */
+export async function recoverCurrentOrganizationPolicy(options, memo) {
+    const input = {
+        ...options,
+        protection: ownPrincipalHistoryProtection(options.protection),
+    };
+    try {
+        let directory;
+        let reader = createPrincipalRecoveryReader(input, memo);
+        try {
+            directory = await reader.directory([]);
+        }
+        catch (error) {
+            assertProjectionVerificationCurrent(input.stillCurrent);
+            if (input.offline || !isPrincipalRecoveryOutage(error))
+                throw error;
+            reader = createPrincipalRecoveryReader({ ...input, offline: true }, memo);
+            directory = await reader.directory([]);
+        }
+        // A reused directory keeps its producer's lifetime to the point of use.
+        const stillCurrent = () => input.stillCurrent() && reader.stillCurrent();
+        assertProjectionVerificationCurrent(stillCurrent);
+        return {
+            current: directory.current,
+            policy: directory.policy,
+            dependencies: [],
+            stillCurrent,
+        };
+    }
+    finally {
+        input.protection.localKey.fill(0);
+    }
+}
+//# sourceMappingURL=recoverCurrentOrganizationPolicy.js.map

package/workflows/principals/historyRecovery/recoverCurrentOrganizationPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recoverCurrentOrganizationPolicy.js","sourceRoot":"","sources":["recoverCurrentOrganizationPolicy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mCAAmC,EAAE,MAAM,kDAAkD,CAAC;AACvG,OAAO,EAAE,6BAA6B,EAAE,MAAM,qDAAqD,CAAC;AAKpG,OAAO,EACL,6BAA6B,GAE9B,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAAE,yBAAyB,EAAE,MAAM,8CAA8C,CAAC;AAEzF,6FAA6F;AAC7F,MAAM,CAAC,KAAK,UAAU,gCAAgC,CACpD,OAAiC,EACjC,IAA4B;IAE5B,MAAM,KAAK,GAAG;QACZ,GAAG,OAAO;QACV,UAAU,EAAE,6BAA6B,CAAC,OAAO,CAAC,UAAU,CAAC;KAC9D,CAAC;IACF,IAAI,CAAC;QACH,IAAI,SAAmC,CAAC;QACxC,IAAI,MAAM,GAAG,6BAA6B,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACxD,IAAI,CAAC;YACH,SAAS,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,mCAAmC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YACxD,IAAI,KAAK,CAAC,OAAO,IAAI,CAAC,yBAAyB,CAAC,KAAK,CAAC;gBAAE,MAAM,KAAK,CAAC;YACpE,MAAM,GAAG,6BAA6B,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;YAC1E,SAAS,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QACzC,CAAC;QACD,wEAAwE;QACxE,MAAM,YAAY,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,YAAY,EAAE,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QACzE,mCAAmC,CAAC,YAAY,CAAC,CAAC;QAClD,OAAO;YACL,OAAO,EAAE,SAAS,CAAC,OAAO;YAC1B,MAAM,EAAE,SAAS,CAAC,MAAM;YACxB,YAAY,EAAE,EAAE;YAChB,YAAY;SACb,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC;AACH,CAAC","sourcesContent":["import { assertProjectionVerificationCurrent } from \"../../../data/keyingProjectionVerification/types\";\nimport { ownPrincipalHistoryProtection } from \"../../../data/principals/principalHistoryProtection\";\nimport type {\n  PrincipalRecoveryContext,\n  RecoveredPolicyDirectory,\n} from \"../recoveryOperation/principalRecoveryDirectory\";\nimport {\n  createPrincipalRecoveryReader,\n  type PrincipalRecoveryMemo,\n} from \"../recoveryOperation/principalRecoveryMemo\";\nimport { isPrincipalRecoveryOutage } from \"../recoveryOperation/principalRecoveryOutage\";\n\n/** Discover and verify current directory artifacts, including protected offline recovery. */\nexport async function recoverCurrentOrganizationPolicy(\n  options: PrincipalRecoveryContext,\n  memo?: PrincipalRecoveryMemo,\n) {\n  const input = {\n    ...options,\n    protection: ownPrincipalHistoryProtection(options.protection),\n  };\n  try {\n    let directory: RecoveredPolicyDirectory;\n    let reader = createPrincipalRecoveryReader(input, memo);\n    try {\n      directory = await reader.directory([]);\n    } catch (error) {\n      assertProjectionVerificationCurrent(input.stillCurrent);\n      if (input.offline || !isPrincipalRecoveryOutage(error)) throw error;\n      reader = createPrincipalRecoveryReader({ ...input, offline: true }, memo);\n      directory = await reader.directory([]);\n    }\n    // A reused directory keeps its producer's lifetime to the point of use.\n    const stillCurrent = () => input.stillCurrent() && reader.stillCurrent();\n    assertProjectionVerificationCurrent(stillCurrent);\n    return {\n      current: directory.current,\n      policy: directory.policy,\n      dependencies: [],\n      stillCurrent,\n    };\n  } finally {\n    input.protection.localKey.fill(0);\n  }\n}\n"]}

package/workflows/principals/historyRecovery/recoverPrincipalHistoryPage.js

@@ -0,0 +1,31 @@
+import { KeyingVerificationError } from "../../../internal/crypto/index.js";
+import { PRINCIPAL_DISPLAY_HISTORY_PAGE_SIZE } from "../../../internal/validators/response/index.js";
+import { loadRecoveredPrincipalHistoryPage } from "./loadRecoveredPrincipalHistoryPage.js";
+import { PrincipalHistoryEvidenceUnavailableError } from "./principalHistoryRecoveryReferences.js";
+import { recoverPrincipalPolicyHistoryWithVersions } from "./recoverPrincipalPolicyHistory.js";
+/** Disposable page proof loss may replay signed pages once online, preserving durable pins. */
+export async function recoverPrincipalHistoryPage(options, beforeVersion) {
+    try {
+        return await loadRecoveredPrincipalHistoryPage(options, beforeVersion);
+    }
+    catch (error) {
+        if (!(error instanceof PrincipalHistoryEvidenceUnavailableError))
+            throw error;
+        // A local-first display read must distinguish disposable proof damage
+        // from a durable fork or an invalid caller citation, which are not wrapped.
+        // Preserve that distinction so the online caller can replay signed pages.
+        if (options.offline)
+            throw new KeyingVerificationError("missing_dependency", "Principal history display proof is unavailable");
+    }
+    const first = Math.max(1, beforeVersion - PRINCIPAL_DISPLAY_HISTORY_PAGE_SIZE - 1);
+    await recoverPrincipalPolicyHistoryWithVersions(options, Array.from({ length: beforeVersion - first }, (_, index) => first + index));
+    try {
+        return await loadRecoveredPrincipalHistoryPage(options, beforeVersion);
+    }
+    catch (error) {
+        throw error instanceof PrincipalHistoryEvidenceUnavailableError
+            ? error.verificationError
+            : error;
+    }
+}
+//# sourceMappingURL=recoverPrincipalHistoryPage.js.map