@tearleads/client-sdk 0.1.11 → 0.1.14

package/workflows/principals/principalHistoryRecoveryStage.js

@@ -1,7 +1,14 @@
 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";
-export async function restorePrincipalHistoryRecoveryStage(input, historyInput) {
+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, input.retainedReferences ?? []);
     const saved = await loadPrincipalHistoryStage(input.execSql, id);
     if (saved) {
@@ -9,17 +16,46 @@ export async function restorePrincipalHistoryRecoveryStage(input, historyInput)
         if (current && saved.organizationId === input.organizationId) {
             const restored = await restorePrincipalPolicyHistoryVerifier(historyInput, saved.progress, await principalHistoryStageProtection(input.protection, input.expectedHead, saved));
             if (restored.ok)
-                return { id, verifier: restored.value, current, saved };
+                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/principalHistoryRecoveryStage.js.map

@@ -1 +1 @@
-{"version":3,"file":"principalHistoryRecoveryStage.js","sourceRoot":"","sources":["principalHistoryRecoveryStage.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oCAAoC,EAGpC,qCAAqC,GACtC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,4BAA4B,EAC5B,yBAAyB,GAE1B,MAAM,yDAAyD,CAAC;AACjE,OAAO,EACL,iCAAiC,EACjC,uBAAuB,EACvB,+BAA+B,GAChC,MAAM,uDAAuD,CAAC;AAU/D,MAAM,CAAC,KAAK,UAAU,oCAAoC,CACxD,KAA2C,EAC3C,YAAyC;IAEzC,MAAM,EAAE,GAAG,MAAM,uBAAuB,CACtC,KAAK,CAAC,cAAc,EACpB,KAAK,CAAC,YAAY,EAClB,KAAK,CAAC,UAAU,CAAC,OAAO,EACxB,KAAK,CAAC,kBAAkB,IAAI,EAAE,CAC/B,CAAC;IACF,MAAM,KAAK,GAAG,MAAM,yBAAyB,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACjE,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,OAAO,GAAG,iCAAiC,CAAC,KAAK,CAAC,CAAC;QACzD,IAAI,OAAO,IAAI,KAAK,CAAC,cAAc,KAAK,KAAK,CAAC,cAAc,EAAE,CAAC;YAC7D,MAAM,QAAQ,GAAG,MAAM,qCAAqC,CAC1D,YAAY,EACZ,KAAK,CAAC,QAAQ,EACd,MAAM,+BAA+B,CACnC,KAAK,CAAC,UAAU,EAChB,KAAK,CAAC,YAAY,EAClB,KAAK,CACN,CACF,CAAC;YACF,IAAI,QAAQ,CAAC,EAAE;gBAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC3E,CAAC;QACD,0EAA0E;QAC1E,0EAA0E;QAC1E,MAAM,4BAA4B,CAChC,KAAK,CAAC,OAAO,EACb,KAAK,EACL,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,IAAI,KAAK,CAAC,YAAY,EAAE,CACrD,CAAC;IACJ,CAAC;IACD,OAAO;QACL,EAAE;QACF,QAAQ,EAAE,oCAAoC,CAAC,YAAY,CAAC;QAC5D,OAAO,EAAE,IAAI;QACb,KAAK,EAAE,IAAI;KACZ,CAAC;AACJ,CAAC","sourcesContent":["import type { PrincipalPolicyPageCurrent } from \"@tearleads/api-client\";\nimport {\n  createPrincipalPolicyHistoryVerifier,\n  type PrincipalPolicyHistoryInput,\n  type PrincipalPolicyHistoryVerifier,\n  restorePrincipalPolicyHistoryVerifier,\n} from \"@tearleads/crypto\";\nimport {\n  discardPrincipalHistoryStage,\n  loadPrincipalHistoryStage,\n  type PrincipalHistoryStage,\n} from \"../../data/persistence/principalHistoryStagePersistence\";\nimport {\n  parsePrincipalHistoryStageCurrent,\n  principalHistoryStageId,\n  principalHistoryStageProtection,\n} from \"../../data/principals/principalHistoryStageProtection\";\nimport type { RecoverPrincipalPolicyHistoryOptions } from \"./principalHistoryRecoveryTypes\";\n\nexport interface PrincipalHistoryRecoveryStage {\n  readonly id: string;\n  readonly verifier: PrincipalPolicyHistoryVerifier;\n  current: PrincipalPolicyPageCurrent | null;\n  saved: PrincipalHistoryStage | null;\n}\n\nexport async function restorePrincipalHistoryRecoveryStage(\n  input: RecoverPrincipalPolicyHistoryOptions,\n  historyInput: PrincipalPolicyHistoryInput,\n): Promise<PrincipalHistoryRecoveryStage> {\n  const id = await principalHistoryStageId(\n    input.organizationId,\n    input.expectedHead,\n    input.protection.context,\n    input.retainedReferences ?? [],\n  );\n  const saved = await loadPrincipalHistoryStage(input.execSql, id);\n  if (saved) {\n    const current = parsePrincipalHistoryStageCurrent(saved);\n    if (current && saved.organizationId === input.organizationId) {\n      const restored = await restorePrincipalPolicyHistoryVerifier(\n        historyInput,\n        saved.progress,\n        await principalHistoryStageProtection(\n          input.protection,\n          input.expectedHead,\n          saved,\n        ),\n      );\n      if (restored.ok) return { id, verifier: restored.value, current, saved };\n    }\n    // Saved bytes are a disposable hint. Only a locally authenticated restore\n    // can skip signed history; missing keys or changed inputs replay genesis.\n    await discardPrincipalHistoryStage(\n      input.execSql,\n      saved,\n      () => !input.signal?.aborted && input.stillCurrent(),\n    );\n  }\n  return {\n    id,\n    verifier: createPrincipalPolicyHistoryVerifier(historyInput),\n    current: null,\n    saved: null,\n  };\n}\n"]}
+{"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    input.retainedReferences ?? [],\n  );\n  const saved = await loadPrincipalHistoryStage(input.execSql, id);\n  if (saved) {\n    const current = parsePrincipalHistoryStageCurrent(saved);\n    if (current && saved.organizationId === input.organizationId) {\n      const restored = await restorePrincipalPolicyHistoryVerifier(\n        historyInput,\n        saved.progress,\n        await principalHistoryStageProtection(\n          input.protection,\n          input.expectedHead,\n          saved,\n        ),\n      );\n      if (restored.ok)\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/principalHistoryRecoveryTypes.d.ts

@@ -1,15 +1,23 @@
 import type { ApiClient, PrincipalPolicyPageCurrent, RequestFailure } from "../../internal/api-client/index.js";
-import type { PrincipalPolicyExternalAuthority, PrincipalPolicyHistoryProgressOptions, PrincipalPolicyStateChainEntry, ReferencedPrincipalHead, VerifiedPrincipalPolicyCurrent } from "../../internal/crypto/index.js";
+import { KeyingVerificationError, type PrincipalPolicyExternalAuthority, type PrincipalPolicyHistoryProgressOptions, type PrincipalPolicyStateChainEntry, 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";
+/** A locally observed race, distinct from a rejected signed predecessor. */
+export declare class PrincipalHistoryRecoveryRaceError extends KeyingVerificationError {
+    constructor(message: string);
+}
 export interface RecoverPrincipalPolicyHistoryOptions {
     readonly apiClient: Pick<ApiClient, "getPrincipalPolicyPages">;
     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;
     /** Return only authority already authenticated by this client. */
     readonly loadExternalAuthority?: ((entries: readonly PrincipalPolicyStateChainEntry[]) => Promise<PrincipalPolicyExternalAuthority | undefined>) | undefined;

package/workflows/principals/principalHistoryRecoveryTypes.js

@@ -1,3 +1,10 @@
+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) {

package/workflows/principals/principalHistoryRecoveryTypes.js.map

@@ -1 +1 @@
-{"version":3,"file":"principalHistoryRecoveryTypes.js","sourceRoot":"","sources":["principalHistoryRecoveryTypes.ts"],"names":[],"mappings":"AAuCA,MAAM,OAAO,+BAAgC,SAAQ,KAAK;IACnC;IAArB,YAAqB,OAAuB;QAC1C,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QADJ,YAAO,GAAP,OAAO,CAAgB;QAE1C,IAAI,CAAC,IAAI,GAAG,iCAAiC,CAAC;IAChD,CAAC;CACF","sourcesContent":["import type {\n  ApiClient,\n  PrincipalPolicyPageCurrent,\n  RequestFailure,\n} from \"@tearleads/api-client\";\nimport type {\n  PrincipalPolicyExternalAuthority,\n  PrincipalPolicyHistoryProgressOptions,\n  PrincipalPolicyStateChainEntry,\n  ReferencedPrincipalHead,\n  VerifiedPrincipalPolicyCurrent,\n} from \"@tearleads/crypto\";\nimport type { ExecSql } from \"../../data/sqlite/sqlSchema\";\nimport type { TrustedUserIdentityResolver } from \"../../data/trustedUserIdentity\";\n\nexport interface RecoverPrincipalPolicyHistoryOptions {\n  readonly apiClient: Pick<ApiClient, \"getPrincipalPolicyPages\">;\n  readonly execSql: ExecSql;\n  readonly organizationId: string;\n  readonly expectedHead: ReferencedPrincipalHead;\n  /** Device-controlled key and stable identity/trust-policy context, never supplied by the API. */\n  readonly protection: PrincipalPolicyHistoryProgressOptions;\n  readonly retainedReferences?: readonly ReferencedPrincipalHead[] | undefined;\n  readonly resolveTrustedUserIdentity: TrustedUserIdentityResolver;\n  /** Return only authority already authenticated by this client. */\n  readonly loadExternalAuthority?:\n    | ((\n        entries: readonly PrincipalPolicyStateChainEntry[],\n      ) => Promise<PrincipalPolicyExternalAuthority | undefined>)\n    | undefined;\n  readonly stillCurrent: () => boolean;\n  readonly signal?: AbortSignal | undefined;\n}\n\nexport interface RecoveredPrincipalPolicyHistory {\n  readonly current: PrincipalPolicyPageCurrent;\n  readonly policy: VerifiedPrincipalPolicyCurrent;\n}\n\nexport class PrincipalPolicyHistoryReadError extends Error {\n  constructor(readonly failure: RequestFailure) {\n    super(failure.message);\n    this.name = \"PrincipalPolicyHistoryReadError\";\n  }\n}\n"]}
+{"version":3,"file":"principalHistoryRecoveryTypes.js","sourceRoot":"","sources":["principalHistoryRecoveryTypes.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,uBAAuB,GAMxB,MAAM,mBAAmB,CAAC;AAI3B,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  ApiClient,\n  PrincipalPolicyPageCurrent,\n  RequestFailure,\n} from \"@tearleads/api-client\";\nimport {\n  KeyingVerificationError,\n  type PrincipalPolicyExternalAuthority,\n  type PrincipalPolicyHistoryProgressOptions,\n  type PrincipalPolicyStateChainEntry,\n  type ReferencedPrincipalHead,\n  type VerifiedPrincipalPolicyCurrent,\n} from \"@tearleads/crypto\";\nimport type { ExecSql } from \"../../data/sqlite/sqlSchema\";\nimport type { TrustedUserIdentityResolver } from \"../../data/trustedUserIdentity\";\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 apiClient: Pick<ApiClient, \"getPrincipalPolicyPages\">;\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  /** Return only authority already authenticated by this client. */\n  readonly loadExternalAuthority?:\n    | ((\n        entries: readonly PrincipalPolicyStateChainEntry[],\n      ) => Promise<PrincipalPolicyExternalAuthority | undefined>)\n    | undefined;\n  readonly stillCurrent: () => boolean;\n  readonly signal?: AbortSignal | undefined;\n}\n\nexport interface RecoveredPrincipalPolicyHistory {\n  readonly current: PrincipalPolicyPageCurrent;\n  readonly policy: VerifiedPrincipalPolicyCurrent;\n}\n\nexport class PrincipalPolicyHistoryReadError extends Error {\n  constructor(readonly failure: RequestFailure) {\n    super(failure.message);\n    this.name = \"PrincipalPolicyHistoryReadError\";\n  }\n}\n"]}

package/workflows/principals/principalHistoryRecoveryVerification.js

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

@@ -0,0 +1 @@
+{"version":3,"file":"principalHistoryRecoveryVerification.js","sourceRoot":"","sources":["principalHistoryRecoveryVerification.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EAEvB,4BAA4B,GAC7B,MAAM,mBAAmB,CAAC;AAG3B,MAAM,UAAU,mCAAmC,CACjD,KAA2C;IAE3C,MAAM,IAAI,GAAG,KAAK,CAAC,mBAAmB,IAAI,UAAU,CAAC;IACrD,IAAI,IAAI,KAAK,UAAU,IAAI,IAAI,KAAK,eAAe;QACjD,MAAM,IAAI,uBAAuB,CAC/B,eAAe,EACf,6CAA6C,CAC9C,CAAC;IACJ,IAAI,IAAI,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC;IACzD,IACE,KAAK,CAAC,YAAY,CAAC,aAAa,KAAK,OAAO;QAC5C,KAAK,CAAC,qBAAqB;QAE3B,MAAM,IAAI,uBAAuB,CAC/B,eAAe,EACf,4EAA4E,CAC7E,CAAC;IACJ,2EAA2E;IAC3E,OAAO,4BAA4B,CAAC;QAClC,kDAAkD;QAClD,KAAK,CAAC,UAAU,CAAC,OAAO;KACzB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,sCAAsC,CACpD,KAA2C,EAC3C,OAAkD;IAElD,IAAI,KAAK,CAAC,mBAAmB,KAAK,eAAe;QAAE,OAAO;IAC1D,IACE,OAAO,CAAC,IAAI,CACV,CAAC,KAAK,EAAE,EAAE,CACR,KAAK,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;QAC7B,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC,CAC7D;QAED,MAAM,IAAI,uBAAuB,CAC/B,eAAe,EACf,8DAA8D,CAC/D,CAAC;AACN,CAAC","sourcesContent":["import {\n  KeyingVerificationError,\n  type PrincipalPolicyStateChainEntry,\n  serializeKeyingCanonicalJson,\n} from \"@tearleads/crypto\";\nimport type { RecoverPrincipalPolicyHistoryOptions } from \"./principalHistoryRecoveryTypes\";\n\nexport function principalHistoryVerificationContext(\n  input: RecoverPrincipalPolicyHistoryOptions,\n): string {\n  const mode = input.historyVerification ?? \"standard\";\n  if (mode !== \"standard\" && mode !== \"direct-admins\")\n    throw new KeyingVerificationError(\n      \"invalid_shape\",\n      \"Unknown principal history verification mode\",\n    );\n  if (mode === \"standard\") return input.protection.context;\n  if (\n    input.expectedHead.principalType !== \"group\" ||\n    input.loadExternalAuthority\n  )\n    throw new KeyingVerificationError(\n      \"invalid_shape\",\n      \"Strict Admins history requires a group without external authority fallback\",\n    );\n  // Retire this local attestation domain whenever strict validation changes.\n  return serializeKeyingCanonicalJson([\n    \"tearleads.sdk.principal-history.direct-admins.v1\",\n    input.protection.context,\n  ]);\n}\n\nexport function assertPrincipalHistoryVerificationMode(\n  input: RecoverPrincipalPolicyHistoryOptions,\n  entries: readonly PrincipalPolicyStateChainEntry[],\n): void {\n  if (input.historyVerification !== \"direct-admins\") return;\n  if (\n    entries.some(\n      (entry) =>\n        entry.projection.length === 0 ||\n        entry.projection.some((member) => member.role !== \"admin\"),\n    )\n  )\n    throw new KeyingVerificationError(\n      \"invalid_shape\",\n      \"Reserved Admins history must contain only direct admin users\",\n    );\n}\n"]}

package/workflows/principals/principalRecoveryDirectory.d.ts

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

package/workflows/principals/principalRecoveryDirectory.js

@@ -0,0 +1,107 @@
+import { KeyingVerificationError, serializeKeyingCanonicalJson, verifyPrincipalPolicyHistoryReferences, } from "../../internal/crypto/index.js";
+import { assertProjectionVerificationCurrent } from "../../data/keyingProjectionVerification/types.js";
+import { loadPrincipalHistoryReference } from "../../data/persistence/principalHistoryEvidencePersistence.js";
+import { parseOrganizationAuthorityDescriptor, } from "../../data/principals/organizationAuthorityDescriptor.js";
+import { principalHistoryEvidenceScopeId } from "../../data/principals/principalHistoryPrefixProtection.js";
+import { loadVerifiedPrincipalHistoryPrefix } from "./principalHistoryRecoveryPrefix.js";
+import { PrincipalPolicyHistoryReadError, } from "./principalHistoryRecoveryTypes.js";
+import { recoverPrincipalPolicyHistory } from "./recoverPrincipalPolicyHistory.js";
+export class PrincipalRecoveryDirectoryAdvanced extends Error {
+}
+/** An unverified discovery read chooses a pin; recovery must authenticate it. */
+async function discoverDirectoryHead(input) {
+    assertProjectionVerificationCurrent(() => !input.signal?.aborted && input.stillCurrent());
+    if (input.offline) {
+        const principal = {
+            principalType: "organization",
+            principalId: input.organizationId,
+        };
+        const scopeId = await principalHistoryEvidenceScopeId({
+            organizationId: input.organizationId,
+            head: principal,
+            protection: input.protection,
+        });
+        const prefix = await loadVerifiedPrincipalHistoryPrefix(input, principal, scopeId);
+        if (!prefix)
+            throw new KeyingVerificationError("missing_dependency", "Organization directory is unavailable offline");
+        const history = prefix.verifier.finish(prefix.head);
+        if (!history.ok)
+            throw history.error;
+        const genesis = await loadPrincipalHistoryReference({
+            execSql: input.execSql,
+            scopeId,
+            history: history.value,
+            version: 1,
+        });
+        const selected = await verifyPrincipalPolicyHistoryReferences({
+            history: history.value,
+            references: [genesis],
+        });
+        if (!selected.ok)
+            throw selected.error;
+        return { head: prefix.head, genesis: genesis.reference };
+    }
+    for await (const result of input.apiClient.getPrincipalPolicyPages("organization", input.organizationId, { signal: input.signal })) {
+        if (!result.ok)
+            throw new PrincipalPolicyHistoryReadError(result);
+        assertProjectionVerificationCurrent(() => !input.signal?.aborted && input.stillCurrent());
+        const state = result.data.currentState;
+        const first = result.data.previousStates[0]?.state ?? state;
+        if (first.version !== 1 ||
+            first.principalType !== "organization" ||
+            first.principalId !== input.organizationId)
+            throw new KeyingVerificationError("missing_dependency", "Organization directory discovery requires genesis");
+        return {
+            genesis: {
+                principalType: first.principalType,
+                principalId: first.principalId,
+                version: first.version,
+                stateHash: first.stateHash,
+                keyEpoch: first.keyEpoch,
+                keyFingerprint: first.keyFingerprint,
+            },
+            head: {
+                principalType: "organization",
+                principalId: input.organizationId,
+                version: state.version,
+                stateHash: state.stateHash,
+                keyEpoch: state.keyEpoch,
+                keyFingerprint: state.keyFingerprint,
+            },
+        };
+    }
+    throw new KeyingVerificationError("missing_dependency", "Organization directory head is unavailable");
+}
+export async function recoverPolicyDirectory(input, references) {
+    const scoped = {
+        ...input,
+        protection: {
+            localKey: input.protection.localKey,
+            context: serializeKeyingCanonicalJson([
+                "tearleads.sdk.principal-history.directory.v1",
+                input.protection.context,
+            ]),
+        },
+    };
+    const { head: expectedHead, genesis } = await discoverDirectoryHead(scoped);
+    if (references.some((reference) => reference.version > expectedHead.version))
+        throw new PrincipalRecoveryDirectoryAdvanced();
+    const recovered = await recoverPrincipalPolicyHistory({
+        ...scoped,
+        expectedHead,
+        retainedReferences: references.some((reference) => reference.version === 1)
+            ? references
+            : [genesis, ...references],
+    });
+    let descriptor;
+    try {
+        descriptor = parseOrganizationAuthorityDescriptor(recovered.current.currentPayload.ciphertext);
+    }
+    catch {
+        throw new KeyingVerificationError("invalid_shape", "Organization directory payload is invalid");
+    }
+    if (descriptor.organizationId !== input.organizationId)
+        throw new KeyingVerificationError("object_mismatch", "Organization directory scope does not match");
+    return { ...recovered, descriptor };
+}
+//# sourceMappingURL=principalRecoveryDirectory.js.map

package/workflows/principals/principalRecoveryDirectory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalRecoveryDirectory.js","sourceRoot":"","sources":["principalRecoveryDirectory.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  KeyingVerificationError,\n  type ReferencedPrincipalHead,\n  serializeKeyingCanonicalJson,\n  verifyPrincipalPolicyHistoryReferences,\n} from \"@tearleads/crypto\";\nimport { assertProjectionVerificationCurrent } from \"../../data/keyingProjectionVerification/types\";\nimport { loadPrincipalHistoryReference } from \"../../data/persistence/principalHistoryEvidencePersistence\";\nimport {\n  type OrganizationAuthorityDescriptor,\n  parseOrganizationAuthorityDescriptor,\n} from \"../../data/principals/organizationAuthorityDescriptor\";\nimport { principalHistoryEvidenceScopeId } from \"../../data/principals/principalHistoryPrefixProtection\";\nimport { loadVerifiedPrincipalHistoryPrefix } from \"./principalHistoryRecoveryPrefix\";\nimport {\n  PrincipalPolicyHistoryReadError,\n  type RecoveredPrincipalPolicyHistory,\n  type RecoverPrincipalPolicyHistoryOptions,\n} from \"./principalHistoryRecoveryTypes\";\nimport { recoverPrincipalPolicyHistory } from \"./recoverPrincipalPolicyHistory\";\n\nexport type PrincipalRecoveryContext = Omit<\n  RecoverPrincipalPolicyHistoryOptions,\n  | \"expectedHead\"\n  | \"retainedReferences\"\n  | \"historyVerification\"\n  | \"loadExternalAuthority\"\n>;\n\nexport interface RecoveredPolicyDirectory\n  extends RecoveredPrincipalPolicyHistory {\n  readonly descriptor: OrganizationAuthorityDescriptor;\n}\n\nexport class PrincipalRecoveryDirectoryAdvanced extends Error {}\n\n/** An unverified discovery read chooses a pin; recovery must authenticate it. */\nasync function discoverDirectoryHead(input: PrincipalRecoveryContext): Promise<{\n  head: ReferencedPrincipalHead;\n  genesis: ReferencedPrincipalHead;\n}> {\n  assertProjectionVerificationCurrent(\n    () => !input.signal?.aborted && input.stillCurrent(),\n  );\n  if (input.offline) {\n    const principal = {\n      principalType: \"organization\" as const,\n      principalId: input.organizationId,\n    };\n    const scopeId = await principalHistoryEvidenceScopeId({\n      organizationId: input.organizationId,\n      head: principal,\n      protection: input.protection,\n    });\n    const prefix = await loadVerifiedPrincipalHistoryPrefix(\n      input,\n      principal,\n      scopeId,\n    );\n    if (!prefix)\n      throw new KeyingVerificationError(\n        \"missing_dependency\",\n        \"Organization directory is unavailable offline\",\n      );\n    const history = prefix.verifier.finish(prefix.head);\n    if (!history.ok) throw history.error;\n    const genesis = await loadPrincipalHistoryReference({\n      execSql: input.execSql,\n      scopeId,\n      history: history.value,\n      version: 1,\n    });\n    const selected = await verifyPrincipalPolicyHistoryReferences({\n      history: history.value,\n      references: [genesis],\n    });\n    if (!selected.ok) throw selected.error;\n    return { head: prefix.head, genesis: genesis.reference };\n  }\n  for await (const result of input.apiClient.getPrincipalPolicyPages(\n    \"organization\",\n    input.organizationId,\n    { signal: input.signal },\n  )) {\n    if (!result.ok) throw new PrincipalPolicyHistoryReadError(result);\n    assertProjectionVerificationCurrent(\n      () => !input.signal?.aborted && input.stillCurrent(),\n    );\n    const state = result.data.currentState;\n    const first = result.data.previousStates[0]?.state ?? state;\n    if (\n      first.version !== 1 ||\n      first.principalType !== \"organization\" ||\n      first.principalId !== input.organizationId\n    )\n      throw new KeyingVerificationError(\n        \"missing_dependency\",\n        \"Organization directory discovery requires genesis\",\n      );\n    return {\n      genesis: {\n        principalType: first.principalType,\n        principalId: first.principalId,\n        version: first.version,\n        stateHash: first.stateHash,\n        keyEpoch: first.keyEpoch,\n        keyFingerprint: first.keyFingerprint,\n      },\n      head: {\n        principalType: \"organization\",\n        principalId: input.organizationId,\n        version: state.version,\n        stateHash: state.stateHash,\n        keyEpoch: state.keyEpoch,\n        keyFingerprint: state.keyFingerprint,\n      },\n    };\n  }\n  throw new KeyingVerificationError(\n    \"missing_dependency\",\n    \"Organization directory head is unavailable\",\n  );\n}\n\nexport async function recoverPolicyDirectory(\n  input: PrincipalRecoveryContext,\n  references: readonly ReferencedPrincipalHead[],\n): Promise<RecoveredPolicyDirectory> {\n  const scoped = {\n    ...input,\n    protection: {\n      localKey: input.protection.localKey,\n      context: serializeKeyingCanonicalJson([\n        \"tearleads.sdk.principal-history.directory.v1\",\n        input.protection.context,\n      ]),\n    },\n  };\n  const { head: expectedHead, genesis } = await discoverDirectoryHead(scoped);\n  if (references.some((reference) => reference.version > expectedHead.version))\n    throw new PrincipalRecoveryDirectoryAdvanced();\n  const recovered = await recoverPrincipalPolicyHistory({\n    ...scoped,\n    expectedHead,\n    retainedReferences: references.some((reference) => reference.version === 1)\n      ? references\n      : [genesis, ...references],\n  });\n  let descriptor: OrganizationAuthorityDescriptor;\n  try {\n    descriptor = parseOrganizationAuthorityDescriptor(\n      recovered.current.currentPayload.ciphertext,\n    );\n  } catch {\n    throw new KeyingVerificationError(\n      \"invalid_shape\",\n      \"Organization directory payload is invalid\",\n    );\n  }\n  if (descriptor.organizationId !== input.organizationId)\n    throw new KeyingVerificationError(\n      \"object_mismatch\",\n      \"Organization directory scope does not match\",\n    );\n  return { ...recovered, descriptor };\n}\n"]}

package/workflows/principals/principalRecoveryMemo.js

@@ -0,0 +1,46 @@
+import { serializeKeyingCanonicalJson, } from "../../internal/crypto/index.js";
+import { assertProjectionVerificationCurrent } from "../../data/keyingProjectionVerification/types.js";
+import { recoverPolicyDirectory, } from "./principalRecoveryDirectory.js";
+import { recoverPrincipalPolicyHistory } from "./recoverPrincipalPolicyHistory.js";
+/** Only share authenticated results within one projection collection lifetime. */
+async function memoPrincipalRecovery(memo, key, stillCurrent, work) {
+    assertProjectionVerificationCurrent(stillCurrent);
+    let pending = memo?.get(key);
+    if (!pending) {
+        pending = work().then((value) => ({ value, stillCurrent }));
+        memo?.set(key, pending);
+    }
+    const result = await pending.catch((error) => {
+        if (memo?.get(key) === pending)
+            memo.delete(key);
+        throw error;
+    });
+    assertProjectionVerificationCurrent(result.stillCurrent);
+    assertProjectionVerificationCurrent(stillCurrent);
+    return result.value;
+}
+export function createPrincipalRecoveryReader(input, memo) {
+    const scope = [
+        input.organizationId,
+        input.protection.context,
+        input.offline === true,
+    ];
+    const current = () => !input.signal?.aborted && input.stillCurrent();
+    return {
+        directory: (references) => memoPrincipalRecovery(memo?.directories, serializeKeyingCanonicalJson([
+            ...scope,
+            references.map((reference) => ({ ...reference })),
+        ]), current, () => recoverPolicyDirectory(input, references)),
+        admins: (expectedHead, retainedReferences = []) => memoPrincipalRecovery(memo?.admins, serializeKeyingCanonicalJson([
+            ...scope,
+            { ...expectedHead },
+            retainedReferences.map((reference) => ({ ...reference })),
+        ]), current, () => recoverPrincipalPolicyHistory({
+            ...input,
+            expectedHead,
+            retainedReferences,
+            historyVerification: "direct-admins",
+        })),
+    };
+}
+//# sourceMappingURL=principalRecoveryMemo.js.map

package/workflows/principals/principalRecoveryMemo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalRecoveryMemo.js","sourceRoot":"","sources":["principalRecoveryMemo.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,4BAA4B,GAC7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mCAAmC,EAAE,MAAM,+CAA+C,CAAC;AAEpG,OAAO,EAGL,sBAAsB,GACvB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAShF,kFAAkF;AAClF,KAAK,UAAU,qBAAqB,CAClC,IAAyB,EACzB,GAAW,EACX,YAA2B,EAC3B,IAAsB;IAEtB,mCAAmC,CAAC,YAAY,CAAC,CAAC;IAClD,IAAI,OAAO,GAAG,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC;QAC5D,IAAI,EAAE,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC1B,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACpD,IAAI,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK,OAAO;YAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjD,MAAM,KAAK,CAAC;IACd,CAAC,CAAC,CAAC;IACH,mCAAmC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACzD,mCAAmC,CAAC,YAAY,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,KAA+B,EAC/B,IAA4B;IAE5B,MAAM,KAAK,GAAG;QACZ,KAAK,CAAC,cAAc;QACpB,KAAK,CAAC,UAAU,CAAC,OAAO;QACxB,KAAK,CAAC,OAAO,KAAK,IAAI;KACvB,CAAC;IACF,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;IACrE,OAAO;QACL,SAAS,EAAE,CAAC,UAA8C,EAAE,EAAE,CAC5D,qBAAqB,CACnB,IAAI,EAAE,WAAW,EACjB,4BAA4B,CAAC;YAC3B,GAAG,KAAK;YACR,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;SAClD,CAAC,EACF,OAAO,EACP,GAAG,EAAE,CAAC,sBAAsB,CAAC,KAAK,EAAE,UAAU,CAAC,CAChD;QACH,MAAM,EAAE,CACN,YAAqC,EACrC,qBAAyD,EAAE,EAC3D,EAAE,CACF,qBAAqB,CACnB,IAAI,EAAE,MAAM,EACZ,4BAA4B,CAAC;YAC3B,GAAG,KAAK;YACR,EAAE,GAAG,YAAY,EAAE;YACnB,kBAAkB,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;SAC1D,CAAC,EACF,OAAO,EACP,GAAG,EAAE,CACH,6BAA6B,CAAC;YAC5B,GAAG,KAAK;YACR,YAAY;YACZ,kBAAkB;YAClB,mBAAmB,EAAE,eAAe;SACrC,CAAC,CACL;KACJ,CAAC;AACJ,CAAC","sourcesContent":["import {\n  type ReferencedPrincipalHead,\n  serializeKeyingCanonicalJson,\n} from \"@tearleads/crypto\";\nimport { assertProjectionVerificationCurrent } from \"../../data/keyingProjectionVerification/types\";\nimport type { RecoveredPrincipalPolicyHistory } from \"./principalHistoryRecoveryTypes\";\nimport {\n  type PrincipalRecoveryContext,\n  type RecoveredPolicyDirectory,\n  recoverPolicyDirectory,\n} from \"./principalRecoveryDirectory\";\nimport { recoverPrincipalPolicyHistory } from \"./recoverPrincipalPolicyHistory\";\n\ntype Memo<T> = Map<string, Promise<{ value: T; stillCurrent: () => boolean }>>;\n\nexport interface PrincipalRecoveryMemo {\n  readonly directories: Memo<RecoveredPolicyDirectory>;\n  readonly admins: Memo<RecoveredPrincipalPolicyHistory>;\n}\n\n/** Only share authenticated results within one projection collection lifetime. */\nasync function memoPrincipalRecovery<T>(\n  memo: Memo<T> | undefined,\n  key: string,\n  stillCurrent: () => boolean,\n  work: () => Promise<T>,\n): Promise<T> {\n  assertProjectionVerificationCurrent(stillCurrent);\n  let pending = memo?.get(key);\n  if (!pending) {\n    pending = work().then((value) => ({ value, stillCurrent }));\n    memo?.set(key, pending);\n  }\n  const result = await pending.catch((error: unknown) => {\n    if (memo?.get(key) === pending) memo.delete(key);\n    throw error;\n  });\n  assertProjectionVerificationCurrent(result.stillCurrent);\n  assertProjectionVerificationCurrent(stillCurrent);\n  return result.value;\n}\n\nexport function createPrincipalRecoveryReader(\n  input: PrincipalRecoveryContext,\n  memo?: PrincipalRecoveryMemo,\n) {\n  const scope = [\n    input.organizationId,\n    input.protection.context,\n    input.offline === true,\n  ];\n  const current = () => !input.signal?.aborted && input.stillCurrent();\n  return {\n    directory: (references: readonly ReferencedPrincipalHead[]) =>\n      memoPrincipalRecovery(\n        memo?.directories,\n        serializeKeyingCanonicalJson([\n          ...scope,\n          references.map((reference) => ({ ...reference })),\n        ]),\n        current,\n        () => recoverPolicyDirectory(input, references),\n      ),\n    admins: (\n      expectedHead: ReferencedPrincipalHead,\n      retainedReferences: readonly ReferencedPrincipalHead[] = [],\n    ) =>\n      memoPrincipalRecovery(\n        memo?.admins,\n        serializeKeyingCanonicalJson([\n          ...scope,\n          { ...expectedHead },\n          retainedReferences.map((reference) => ({ ...reference })),\n        ]),\n        current,\n        () =>\n          recoverPrincipalPolicyHistory({\n            ...input,\n            expectedHead,\n            retainedReferences,\n            historyVerification: \"direct-admins\",\n          }),\n      ),\n  };\n}\n"]}

package/workflows/principals/principalRecoveryOutage.js

@@ -0,0 +1,40 @@
+import { KeyingVerificationError } from "../../internal/crypto/index.js";
+import { ProjectionDependencyUnavailableError } from "../../data/keyingProjectionVerification/dependencyUnavailable.js";
+import { assertProjectionVerificationCurrent } from "../../data/keyingProjectionVerification/types.js";
+import { PrincipalPolicyHistoryReadError } from "./principalHistoryRecoveryTypes.js";
+import { recoverScopedPrincipalPolicyHistory } from "./recoverScopedPrincipalPolicyHistory.js";
+/** Refusals and invalid evidence must never silently select a cached policy. */
+function isPrincipalRecoveryOutage(error) {
+    if (!(error instanceof PrincipalPolicyHistoryReadError))
+        return false;
+    const { failure } = error;
+    return (failure.kind === "network" ||
+        (failure.kind === "http" &&
+            failure.status !== null &&
+            failure.status >= 500) ||
+        (failure.kind === "cancelled" &&
+            failure.code === "principal_history_request_timed_out"));
+}
+export async function recoverWithPrincipalOutageFallback(recover, options) {
+    try {
+        return await recover(options);
+    }
+    catch (error) {
+        assertProjectionVerificationCurrent(options.stillCurrent);
+        if (options.offline || !isPrincipalRecoveryOutage(error))
+            throw error;
+        try {
+            return await recoverScopedPrincipalPolicyHistory({
+                ...options,
+                offline: true,
+            });
+        }
+        catch (localError) {
+            if (localError instanceof KeyingVerificationError &&
+                localError.code === "missing_dependency")
+                throw new ProjectionDependencyUnavailableError(localError.message);
+            throw localError;
+        }
+    }
+}
+//# sourceMappingURL=principalRecoveryOutage.js.map

package/workflows/principals/principalRecoveryOutage.js.map

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

package/workflows/principals/principalRecoveryQueue.js

@@ -0,0 +1,22 @@
+// Directory and Admins stages are shared by every reference in an organization.
+// Coordinate runtime callers across warmer instances; different databases and
+// organizations keep independent queues. Completed queues retain no work.
+// Queued work must not re-enter this queue for the same organization.
+const queues = new WeakMap();
+export function queuePrincipalRecovery(execSql, organizationId, work) {
+    let scoped = queues.get(execSql);
+    if (!scoped) {
+        scoped = new Map();
+        queues.set(execSql, scoped);
+    }
+    const operation = (scoped.get(organizationId) ?? Promise.resolve()).then(work);
+    const settled = operation.then(() => undefined, () => undefined);
+    scoped.set(organizationId, settled);
+    const owned = scoped;
+    void settled.then(() => {
+        if (owned.get(organizationId) === settled)
+            owned.delete(organizationId);
+    });
+    return operation;
+}
+//# sourceMappingURL=principalRecoveryQueue.js.map

package/workflows/principals/principalRecoveryQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalRecoveryQueue.js","sourceRoot":"","sources":["principalRecoveryQueue.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,8EAA8E;AAC9E,0EAA0E;AAC1E,sEAAsE;AACtE,MAAM,MAAM,GAAG,IAAI,OAAO,EAAuC,CAAC;AAElE,MAAM,UAAU,sBAAsB,CACpC,OAAgB,EAChB,cAAsB,EACtB,IAAsB;IAEtB,IAAI,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;QACnB,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC9B,CAAC;IACD,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CACtE,IAAI,CACL,CAAC;IACF,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAC5B,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CAChB,CAAC;IACF,MAAM,CAAC,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,MAAM,CAAC;IACrB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE;QACrB,IAAI,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,OAAO;YAAE,KAAK,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAC1E,CAAC,CAAC,CAAC;IACH,OAAO,SAAS,CAAC;AACnB,CAAC","sourcesContent":["import type { ExecSql } from \"../../data/sqlite/sqlSchema\";\n\n// Directory and Admins stages are shared by every reference in an organization.\n// Coordinate runtime callers across warmer instances; different databases and\n// organizations keep independent queues. Completed queues retain no work.\n// Queued work must not re-enter this queue for the same organization.\nconst queues = new WeakMap<ExecSql, Map<string, Promise<void>>>();\n\nexport function queuePrincipalRecovery<T>(\n  execSql: ExecSql,\n  organizationId: string,\n  work: () => Promise<T>,\n): Promise<T> {\n  let scoped = queues.get(execSql);\n  if (!scoped) {\n    scoped = new Map();\n    queues.set(execSql, scoped);\n  }\n  const operation = (scoped.get(organizationId) ?? Promise.resolve()).then(\n    work,\n  );\n  const settled = operation.then(\n    () => undefined,\n    () => undefined,\n  );\n  scoped.set(organizationId, settled);\n  const owned = scoped;\n  void settled.then(() => {\n    if (owned.get(organizationId) === settled) owned.delete(organizationId);\n  });\n  return operation;\n}\n"]}

package/workflows/principals/recoverPrincipalPolicyHistory.d.ts

@@ -2,5 +2,6 @@ import { type RecoveredPrincipalPolicyHistory, type RecoverPrincipalPolicyHistor
 /**
  * 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 declare function recoverPrincipalPolicyHistory(options: RecoverPrincipalPolicyHistoryOptions): Promise<RecoveredPrincipalPolicyHistory>;