@tearleads/client-sdk 0.1.62 → 0.1.64

package/workflows/principals/acknowledgements/acknowledgedPrincipalCurrents.js

@@ -0,0 +1,140 @@
+import { KeyingVerificationError, } from "../../../internal/crypto/index.js";
+import { assertProjectionVerificationCurrent } from "../../../data/keyingProjectionVerification/types.js";
+import { PrincipalAcknowledgementChangedError, persistAcknowledgedPrincipalCurrents, } from "../../../data/persistence/principalCurrentAcknowledgementPersistence.js";
+import { preparePrincipalHistoryEvidencePage } from "../../../data/persistence/principalHistoryEvidencePersistence.js";
+import { ownPrincipalHistoryProtection } from "../../../data/principals/principalHistoryProtection.js";
+import { assertPrincipalHistoryVerificationMode, principalHistoryVerificationContext, } from "../historyRecovery/principalHistoryRecoveryVerification.js";
+import { collectPrincipalPolicySignerPublicKeys } from "../policyVerification.js";
+import { restoreAcknowledgedPrincipalPredecessor, } from "./acknowledgedPrincipalPredecessor.js";
+import { prepareInitialGroupCurrentPublication } from "./initialPrincipalCurrentPublication.js";
+import { sealPrincipalCurrentPublication, sealPrincipalCurrentStage, } from "./principalCurrentPublicationSeal.js";
+import { reconcileAcknowledgedPrincipalCurrent } from "./reconcileAcknowledgedPrincipalCurrent.js";
+async function preparePublication(options, request, response, predecessor, checks) {
+    options = {
+        ...options,
+        protection: {
+            ...options.protection,
+            context: principalHistoryVerificationContext(options),
+        },
+    };
+    const current = () => !options.signal?.aborted && options.stillCurrent();
+    assertProjectionVerificationCurrent(current);
+    const { scopeId, saved, artifacts, verifier, previous, predecessorIndexRootHash, } = await restoreAcknowledgedPrincipalPredecessor(options, predecessor);
+    const expectedHead = await checks.authoredHead(request);
+    checks.assertReceipt({ expectedHead, request, response });
+    const keys = await collectPrincipalPolicySignerPublicKeys({
+        bundle: { currentState: response.currentState, previousStates: [] },
+        resolveTrustedUserIdentity: options.resolveTrustedUserIdentity,
+    });
+    assertProjectionVerificationCurrent(current);
+    if ("error" in keys)
+        throw new KeyingVerificationError(keys.error === "not-found" ? "missing_dependency" : "signer_mismatch", "Acknowledged principal signer could not be authenticated");
+    const externalAuthority = await options.loadExternalAuthority?.(request.state.externalAuthority ? [request.state.externalAuthority] : []);
+    assertProjectionVerificationCurrent(current);
+    const policy = await checks.acknowledgeSuccessor({
+        verifiedCurrentPolicy: previous,
+        expectedHead,
+        request,
+        response: response.currentState,
+        signerPublicKeys: keys.signerPublicKeys,
+        externalAuthority,
+        stillCurrent: current,
+    });
+    const entry = {
+        state: response.currentState,
+        projection: response.currentProjection,
+        grants: response.currentGrants,
+    };
+    assertPrincipalHistoryVerificationMode(options, [entry]);
+    const predecessorStage = await sealPrincipalCurrentStage(options, previous.state, verifier, artifacts);
+    const appended = await verifier.append({
+        entries: [entry],
+        signerPublicKeys: keys.signerPublicKeys,
+        ...(externalAuthority ? { externalAuthority } : {}),
+    });
+    if (!appended.ok)
+        throw appended.error;
+    const sealed = await sealPrincipalCurrentPublication(options, scopeId, expectedHead, verifier, response);
+    assertProjectionVerificationCurrent(current);
+    return {
+        policy,
+        previousPrefixProgress: saved.progress,
+        predecessorStage,
+        predecessorIndexRootHash,
+        ...sealed,
+        evidence: await preparePrincipalHistoryEvidencePage({
+            indexRootHash: appended.value.indexRootHash,
+            scopeId,
+            organizationId: options.organizationId,
+            entries: [entry],
+            nodes: appended.value.indexNodes,
+        }),
+    };
+}
+/**
+ * Extend authenticated local progress and retain exact acknowledged artifacts
+ * atomically with pins, once `checks` accept each acknowledgement.
+ */
+export async function recordAcknowledgedPrincipalCurrents(input) {
+    const checks = input.checks;
+    const execSql = input.execSql;
+    const organizationId = input.organizationId;
+    const stillCurrent = input.stillCurrent;
+    const retirements = structuredClone(input.retirements ?? []);
+    const entries = [];
+    try {
+        assertProjectionVerificationCurrent(stillCurrent);
+        for (const entry of input.entries)
+            entries.push({
+                initialGroup: entry.initialGroup === true,
+                predecessor: structuredClone(entry.predecessor),
+                request: structuredClone(entry.request),
+                response: structuredClone(entry.response),
+                options: {
+                    ...entry.recovery,
+                    expectedHead: structuredClone(entry.recovery.expectedHead),
+                    protection: ownPrincipalHistoryProtection(entry.recovery.protection),
+                    execSql,
+                    organizationId,
+                    stillCurrent,
+                },
+            });
+        const publications = [];
+        for (const entry of entries)
+            publications.push(await (entry.initialGroup
+                ? prepareInitialGroupCurrentPublication
+                : preparePublication)(entry.options, entry.request, entry.response, entry.predecessor, checks));
+        checks.assertDirectoryBindings(organizationId, entries.map(({ response }) => response));
+        for (let attempt = 0;; attempt += 1) {
+            const reconciled = [];
+            for (const [index, publication] of publications.entries()) {
+                const entry = entries[index];
+                if (!entry)
+                    throw new Error("Missing acknowledgement entry");
+                reconciled.push(await reconcileAcknowledgedPrincipalCurrent(entry.options, publication));
+            }
+            try {
+                await persistAcknowledgedPrincipalCurrents({
+                    execSql,
+                    organizationId,
+                    entries: reconciled,
+                    retirements,
+                    stillCurrent: () => stillCurrent() &&
+                        entries.every((entry) => !entry.options.signal?.aborted),
+                });
+                break;
+            }
+            catch (error) {
+                if (!(error instanceof PrincipalAcknowledgementChangedError) ||
+                    attempt >= 7)
+                    throw error;
+            }
+        }
+        return publications.map(({ policy }) => policy);
+    }
+    finally {
+        for (const entry of entries)
+            entry.options.protection.localKey.fill(0);
+    }
+}
+//# sourceMappingURL=acknowledgedPrincipalCurrents.js.map

package/workflows/principals/acknowledgements/acknowledgedPrincipalCurrents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acknowledgedPrincipalCurrents.js","sourceRoot":"","sources":["acknowledgedPrincipalCurrents.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  KeyingVerificationError,\n  type VerifiedPrincipalPolicyCurrent,\n} from \"@tearleads/crypto\";\nimport type { PutPrincipalPolicyRequest } from \"@tearleads/validators/request\";\nimport type { PrincipalPolicyMutationResponse } from \"@tearleads/validators/response\";\nimport { assertProjectionVerificationCurrent } from \"../../../data/keyingProjectionVerification/types\";\nimport {\n  type AcknowledgedPrincipalCurrentPublication,\n  type AcknowledgedPrincipalCurrentRetirement,\n  PrincipalAcknowledgementChangedError,\n  persistAcknowledgedPrincipalCurrents,\n} from \"../../../data/persistence/principalCurrentAcknowledgementPersistence\";\nimport { preparePrincipalHistoryEvidencePage } from \"../../../data/persistence/principalHistoryEvidencePersistence\";\nimport { ownPrincipalHistoryProtection } from \"../../../data/principals/principalHistoryProtection\";\nimport type { ExecSql } from \"../../../data/sqlite/sqlSchema\";\nimport type { RecoverPrincipalPolicyHistoryOptions } from \"../historyRecovery/principalHistoryRecoveryTypes\";\nimport {\n  assertPrincipalHistoryVerificationMode,\n  principalHistoryVerificationContext,\n} from \"../historyRecovery/principalHistoryRecoveryVerification\";\nimport { collectPrincipalPolicySignerPublicKeys } from \"../policyVerification\";\nimport {\n  type AcknowledgedPrincipalPredecessor,\n  restoreAcknowledgedPrincipalPredecessor,\n} from \"./acknowledgedPrincipalPredecessor\";\nimport { prepareInitialGroupCurrentPublication } from \"./initialPrincipalCurrentPublication\";\nimport type { PrincipalAcknowledgementChecks } from \"./principalAcknowledgementChecks\";\nimport {\n  sealPrincipalCurrentPublication,\n  sealPrincipalCurrentStage,\n} from \"./principalCurrentPublicationSeal\";\nimport { reconcileAcknowledgedPrincipalCurrent } from \"./reconcileAcknowledgedPrincipalCurrent\";\n\nexport interface AcknowledgedPrincipalCurrentInput {\n  /** Capture before submitting the mutation; null only for a new group. */\n  readonly predecessor: AcknowledgedPrincipalPredecessor | null;\n  /** Only a newly authored group at version one; never skips a predecessor. */\n  readonly initialGroup?: boolean | undefined;\n  /** The same scoped protection and verification mode used to recover the predecessor. */\n  readonly recovery: Omit<\n    RecoverPrincipalPolicyHistoryOptions,\n    \"execSql\" | \"organizationId\" | \"stillCurrent\"\n  >;\n  readonly request: PutPrincipalPolicyRequest;\n  readonly response: PrincipalPolicyMutationResponse;\n}\n\nasync function preparePublication(\n  options: RecoverPrincipalPolicyHistoryOptions,\n  request: PutPrincipalPolicyRequest,\n  response: PrincipalPolicyMutationResponse,\n  predecessor: AcknowledgedPrincipalPredecessor | null,\n  checks: PrincipalAcknowledgementChecks,\n): Promise<AcknowledgedPrincipalCurrentPublication> {\n  options = {\n    ...options,\n    protection: {\n      ...options.protection,\n      context: principalHistoryVerificationContext(options),\n    },\n  };\n  const current = () => !options.signal?.aborted && options.stillCurrent();\n  assertProjectionVerificationCurrent(current);\n  const {\n    scopeId,\n    saved,\n    artifacts,\n    verifier,\n    previous,\n    predecessorIndexRootHash,\n  } = await restoreAcknowledgedPrincipalPredecessor(options, predecessor);\n  const expectedHead = await checks.authoredHead(request);\n  checks.assertReceipt({ expectedHead, request, response });\n  const keys = await collectPrincipalPolicySignerPublicKeys({\n    bundle: { currentState: response.currentState, previousStates: [] },\n    resolveTrustedUserIdentity: options.resolveTrustedUserIdentity,\n  });\n  assertProjectionVerificationCurrent(current);\n  if (\"error\" in keys)\n    throw new KeyingVerificationError(\n      keys.error === \"not-found\" ? \"missing_dependency\" : \"signer_mismatch\",\n      \"Acknowledged principal signer could not be authenticated\",\n    );\n  const externalAuthority = await options.loadExternalAuthority?.(\n    request.state.externalAuthority ? [request.state.externalAuthority] : [],\n  );\n  assertProjectionVerificationCurrent(current);\n  const policy = await checks.acknowledgeSuccessor({\n    verifiedCurrentPolicy: previous,\n    expectedHead,\n    request,\n    response: response.currentState,\n    signerPublicKeys: keys.signerPublicKeys,\n    externalAuthority,\n    stillCurrent: current,\n  });\n  const entry = {\n    state: response.currentState,\n    projection: response.currentProjection,\n    grants: response.currentGrants,\n  };\n  assertPrincipalHistoryVerificationMode(options, [entry]);\n  const predecessorStage = await sealPrincipalCurrentStage(\n    options,\n    previous.state,\n    verifier,\n    artifacts,\n  );\n  const appended = await verifier.append({\n    entries: [entry],\n    signerPublicKeys: keys.signerPublicKeys,\n    ...(externalAuthority ? { externalAuthority } : {}),\n  });\n  if (!appended.ok) throw appended.error;\n  const sealed = await sealPrincipalCurrentPublication(\n    options,\n    scopeId,\n    expectedHead,\n    verifier,\n    response,\n  );\n  assertProjectionVerificationCurrent(current);\n  return {\n    policy,\n    previousPrefixProgress: saved.progress,\n    predecessorStage,\n    predecessorIndexRootHash,\n    ...sealed,\n    evidence: await preparePrincipalHistoryEvidencePage({\n      indexRootHash: appended.value.indexRootHash,\n      scopeId,\n      organizationId: options.organizationId,\n      entries: [entry],\n      nodes: appended.value.indexNodes,\n    }),\n  };\n}\n\n/** The acknowledged currents of one mutation, recorded together. */\nexport interface AcknowledgedPrincipalCurrentBatch {\n  readonly execSql: ExecSql;\n  readonly organizationId: string;\n  readonly entries: readonly AcknowledgedPrincipalCurrentInput[];\n  readonly retirements?:\n    | readonly AcknowledgedPrincipalCurrentRetirement[]\n    | undefined;\n  readonly stillCurrent: () => boolean;\n}\n\n/**\n * Extend authenticated local progress and retain exact acknowledged artifacts\n * atomically with pins, once `checks` accept each acknowledgement.\n */\nexport async function recordAcknowledgedPrincipalCurrents(\n  input: AcknowledgedPrincipalCurrentBatch & {\n    readonly checks: PrincipalAcknowledgementChecks;\n  },\n): Promise<VerifiedPrincipalPolicyCurrent[]> {\n  const checks = input.checks;\n  const execSql = input.execSql;\n  const organizationId = input.organizationId;\n  const stillCurrent = input.stillCurrent;\n  const retirements = structuredClone(input.retirements ?? []);\n  const entries: {\n    initialGroup: boolean;\n    request: PutPrincipalPolicyRequest;\n    response: PrincipalPolicyMutationResponse;\n    options: RecoverPrincipalPolicyHistoryOptions;\n    predecessor: AcknowledgedPrincipalPredecessor | null;\n  }[] = [];\n  try {\n    assertProjectionVerificationCurrent(stillCurrent);\n    for (const entry of input.entries)\n      entries.push({\n        initialGroup: entry.initialGroup === true,\n        predecessor: structuredClone(entry.predecessor),\n        request: structuredClone(entry.request),\n        response: structuredClone(entry.response),\n        options: {\n          ...entry.recovery,\n          expectedHead: structuredClone(entry.recovery.expectedHead),\n          protection: ownPrincipalHistoryProtection(entry.recovery.protection),\n          execSql,\n          organizationId,\n          stillCurrent,\n        },\n      });\n    const publications: AcknowledgedPrincipalCurrentPublication[] = [];\n    for (const entry of entries)\n      publications.push(\n        await (entry.initialGroup\n          ? prepareInitialGroupCurrentPublication\n          : preparePublication)(\n          entry.options,\n          entry.request,\n          entry.response,\n          entry.predecessor,\n          checks,\n        ),\n      );\n    checks.assertDirectoryBindings(\n      organizationId,\n      entries.map(({ response }) => response),\n    );\n    for (let attempt = 0; ; attempt += 1) {\n      const reconciled = [];\n      for (const [index, publication] of publications.entries()) {\n        const entry = entries[index];\n        if (!entry) throw new Error(\"Missing acknowledgement entry\");\n        reconciled.push(\n          await reconcileAcknowledgedPrincipalCurrent(\n            entry.options,\n            publication,\n          ),\n        );\n      }\n      try {\n        await persistAcknowledgedPrincipalCurrents({\n          execSql,\n          organizationId,\n          entries: reconciled,\n          retirements,\n          stillCurrent: () =>\n            stillCurrent() &&\n            entries.every((entry) => !entry.options.signal?.aborted),\n        });\n        break;\n      } catch (error) {\n        if (\n          !(error instanceof PrincipalAcknowledgementChangedError) ||\n          attempt >= 7\n        )\n          throw error;\n      }\n    }\n    return publications.map(({ policy }) => policy);\n  } finally {\n    for (const entry of entries) entry.options.protection.localKey.fill(0);\n  }\n}\n"]}

package/workflows/principals/acknowledgements/acknowledgedPrincipalPredecessor.d.ts

@@ -0,0 +1,39 @@
+import { type PrincipalHistoryPrefix } from "../../../data/persistence/principalHistoryPrefixPersistence.js";
+import type { RecoverPrincipalPolicyHistoryOptions } from "../historyRecovery/principalHistoryRecoveryTypes.js";
+/** Sealed predecessor evidence, owned by a mutation before its request is sent. */
+export type AcknowledgedPrincipalPredecessor = Readonly<PrincipalHistoryPrefix>;
+/** Authenticate the entire prefix, including its scope and current artifacts. */
+export declare function restoreAcknowledgedPrincipalPrefix(options: RecoverPrincipalPolicyHistoryOptions, saved: AcknowledgedPrincipalPredecessor | null): Promise<{
+    scopeId: string;
+    saved: Readonly<{
+        version: number;
+        organizationId: string;
+        scopeId: string;
+        headJson: string;
+        currentJson: string;
+        progress: string;
+    }>;
+    artifacts: import("../../../internal/api-client/index.js").PrincipalPolicyPageCurrent;
+    verifier: import("../../../internal/crypto/index.js").PrincipalPolicyHistoryVerifier;
+    previous: import("../../../internal/crypto/index.js").VerifiedPrincipalPolicyCurrent;
+    history: import("../../../internal/crypto/index.js").VerifiedPrincipalPolicyHistory;
+    predecessorIndexRootHash: string;
+}>;
+/** Capture exact predecessor evidence while authoring, before HTTP can commit. */
+export declare function captureAcknowledgedPrincipalPredecessor(input: RecoverPrincipalPolicyHistoryOptions): Promise<AcknowledgedPrincipalPredecessor>;
+export declare function restoreAcknowledgedPrincipalPredecessor(options: RecoverPrincipalPolicyHistoryOptions, saved: AcknowledgedPrincipalPredecessor | null): Promise<{
+    scopeId: string;
+    saved: Readonly<{
+        version: number;
+        organizationId: string;
+        scopeId: string;
+        headJson: string;
+        currentJson: string;
+        progress: string;
+    }>;
+    artifacts: import("../../../internal/api-client/index.js").PrincipalPolicyPageCurrent;
+    verifier: import("../../../internal/crypto/index.js").PrincipalPolicyHistoryVerifier;
+    previous: import("../../../internal/crypto/index.js").VerifiedPrincipalPolicyCurrent;
+    history: import("../../../internal/crypto/index.js").VerifiedPrincipalPolicyHistory;
+    predecessorIndexRootHash: string;
+}>;

package/workflows/principals/acknowledgements/acknowledgedPrincipalPredecessor.js

@@ -0,0 +1,87 @@
+import { KeyingVerificationError, restorePrincipalPolicyHistoryVerifier, verifyPrincipalPolicyCurrent, } from "../../../internal/crypto/index.js";
+import { assertProjectionVerificationCurrent } from "../../../data/keyingProjectionVerification/types.js";
+import { loadPrincipalHistoryPrefix, } from "../../../data/persistence/principalHistoryPrefixPersistence.js";
+import { principalHeadMatchesReference } from "../../../data/principals/organizationAuthorityDescriptor.js";
+import { principalHistoryEvidenceScopeId, principalHistoryPrefixProtection, } from "../../../data/principals/principalHistoryPrefixProtection.js";
+import { ownPrincipalHistoryProtection } from "../../../data/principals/principalHistoryProtection.js";
+import { parsePrincipalHistoryStageCurrent } from "../../../data/principals/principalHistoryStageProtection.js";
+import { principalPolicyReferenceFromBundle } from "../../../data/principals/principalPolicyAdminSigners.js";
+import { principalHistoryVerificationContext } from "../historyRecovery/principalHistoryRecoveryVerification.js";
+/** Authenticate the entire prefix, including its scope and current artifacts. */
+export async function restoreAcknowledgedPrincipalPrefix(options, saved) {
+    const scopeId = await principalHistoryEvidenceScopeId({
+        organizationId: options.organizationId,
+        head: options.expectedHead,
+        protection: options.protection,
+    });
+    if (!saved ||
+        saved.scopeId !== scopeId ||
+        saved.organizationId !== options.organizationId)
+        throw new KeyingVerificationError("missing_dependency", "Acknowledgement requires its authenticated predecessor prefix");
+    const restored = await restorePrincipalPolicyHistoryVerifier({
+        principalId: options.expectedHead.principalId,
+        principalType: options.expectedHead.principalType,
+    }, saved.progress, await principalHistoryPrefixProtection(options.protection, saved));
+    if (!restored.ok)
+        throw restored.error;
+    const artifacts = parsePrincipalHistoryStageCurrent({
+        currentJson: saved.currentJson,
+        afterVersion: saved.version - 1,
+    });
+    if (!artifacts)
+        throw new KeyingVerificationError("invalid_shape", "Acknowledged predecessor artifacts are malformed");
+    const history = restored.value.finish(principalPolicyReferenceFromBundle(artifacts));
+    if (!history.ok)
+        throw history.error;
+    const previous = await verifyPrincipalPolicyCurrent({
+        current: artifacts,
+        history: history.value,
+    });
+    if (!previous.ok)
+        throw previous.error;
+    return {
+        scopeId,
+        saved,
+        artifacts,
+        verifier: restored.value,
+        previous: previous.value,
+        history: history.value,
+        predecessorIndexRootHash: history.value.indexRootHash,
+    };
+}
+/** Capture exact predecessor evidence while authoring, before HTTP can commit. */
+export async function captureAcknowledgedPrincipalPredecessor(input) {
+    const protection = ownPrincipalHistoryProtection(input.protection);
+    const options = {
+        ...input,
+        expectedHead: structuredClone(input.expectedHead),
+        protection: {
+            ...protection,
+            context: principalHistoryVerificationContext(input),
+        },
+    };
+    const current = () => !options.signal?.aborted && options.stillCurrent();
+    try {
+        assertProjectionVerificationCurrent(current);
+        const scopeId = await principalHistoryEvidenceScopeId({
+            organizationId: options.organizationId,
+            head: options.expectedHead,
+            protection: options.protection,
+        });
+        const restored = await restoreAcknowledgedPrincipalPrefix(options, await loadPrincipalHistoryPrefix(options.execSql, scopeId));
+        assertProjectionVerificationCurrent(current);
+        if (!principalHeadMatchesReference(restored.previous.state, options.expectedHead))
+            throw new Error("Principal policy changed before submission; retry the mutation");
+        return structuredClone(restored.saved);
+    }
+    finally {
+        protection.localKey.fill(0);
+    }
+}
+export async function restoreAcknowledgedPrincipalPredecessor(options, saved) {
+    const restored = await restoreAcknowledgedPrincipalPrefix(options, saved);
+    if (!principalHeadMatchesReference(restored.previous.state, options.expectedHead))
+        throw new KeyingVerificationError("object_mismatch", "Acknowledgement predecessor does not match the authored request");
+    return restored;
+}
+//# sourceMappingURL=acknowledgedPrincipalPredecessor.js.map

package/workflows/principals/acknowledgements/acknowledgedPrincipalPredecessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acknowledgedPrincipalPredecessor.js","sourceRoot":"","sources":["acknowledgedPrincipalPredecessor.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  KeyingVerificationError,\n  restorePrincipalPolicyHistoryVerifier,\n  verifyPrincipalPolicyCurrent,\n} from \"@tearleads/crypto\";\nimport { assertProjectionVerificationCurrent } from \"../../../data/keyingProjectionVerification/types\";\nimport {\n  loadPrincipalHistoryPrefix,\n  type PrincipalHistoryPrefix,\n} from \"../../../data/persistence/principalHistoryPrefixPersistence\";\nimport { principalHeadMatchesReference } from \"../../../data/principals/organizationAuthorityDescriptor\";\nimport {\n  principalHistoryEvidenceScopeId,\n  principalHistoryPrefixProtection,\n} from \"../../../data/principals/principalHistoryPrefixProtection\";\nimport { ownPrincipalHistoryProtection } from \"../../../data/principals/principalHistoryProtection\";\nimport { parsePrincipalHistoryStageCurrent } from \"../../../data/principals/principalHistoryStageProtection\";\nimport { principalPolicyReferenceFromBundle } from \"../../../data/principals/principalPolicyAdminSigners\";\nimport type { RecoverPrincipalPolicyHistoryOptions } from \"../historyRecovery/principalHistoryRecoveryTypes\";\nimport { principalHistoryVerificationContext } from \"../historyRecovery/principalHistoryRecoveryVerification\";\n\n/** Sealed predecessor evidence, owned by a mutation before its request is sent. */\nexport type AcknowledgedPrincipalPredecessor = Readonly<PrincipalHistoryPrefix>;\n\n/** Authenticate the entire prefix, including its scope and current artifacts. */\nexport async function restoreAcknowledgedPrincipalPrefix(\n  options: RecoverPrincipalPolicyHistoryOptions,\n  saved: AcknowledgedPrincipalPredecessor | null,\n) {\n  const scopeId = await principalHistoryEvidenceScopeId({\n    organizationId: options.organizationId,\n    head: options.expectedHead,\n    protection: options.protection,\n  });\n  if (\n    !saved ||\n    saved.scopeId !== scopeId ||\n    saved.organizationId !== options.organizationId\n  )\n    throw new KeyingVerificationError(\n      \"missing_dependency\",\n      \"Acknowledgement requires its authenticated predecessor prefix\",\n    );\n  const restored = await restorePrincipalPolicyHistoryVerifier(\n    {\n      principalId: options.expectedHead.principalId,\n      principalType: options.expectedHead.principalType,\n    },\n    saved.progress,\n    await principalHistoryPrefixProtection(options.protection, saved),\n  );\n  if (!restored.ok) throw restored.error;\n  const artifacts = parsePrincipalHistoryStageCurrent({\n    currentJson: saved.currentJson,\n    afterVersion: saved.version - 1,\n  });\n  if (!artifacts)\n    throw new KeyingVerificationError(\n      \"invalid_shape\",\n      \"Acknowledged predecessor artifacts are malformed\",\n    );\n  const history = restored.value.finish(\n    principalPolicyReferenceFromBundle(artifacts),\n  );\n  if (!history.ok) throw history.error;\n  const previous = await verifyPrincipalPolicyCurrent({\n    current: artifacts,\n    history: history.value,\n  });\n  if (!previous.ok) throw previous.error;\n  return {\n    scopeId,\n    saved,\n    artifacts,\n    verifier: restored.value,\n    previous: previous.value,\n    history: history.value,\n    predecessorIndexRootHash: history.value.indexRootHash,\n  };\n}\n\n/** Capture exact predecessor evidence while authoring, before HTTP can commit. */\nexport async function captureAcknowledgedPrincipalPredecessor(\n  input: RecoverPrincipalPolicyHistoryOptions,\n): Promise<AcknowledgedPrincipalPredecessor> {\n  const protection = ownPrincipalHistoryProtection(input.protection);\n  const options = {\n    ...input,\n    expectedHead: structuredClone(input.expectedHead),\n    protection: {\n      ...protection,\n      context: principalHistoryVerificationContext(input),\n    },\n  };\n  const current = () => !options.signal?.aborted && options.stillCurrent();\n  try {\n    assertProjectionVerificationCurrent(current);\n    const scopeId = await principalHistoryEvidenceScopeId({\n      organizationId: options.organizationId,\n      head: options.expectedHead,\n      protection: options.protection,\n    });\n    const restored = await restoreAcknowledgedPrincipalPrefix(\n      options,\n      await loadPrincipalHistoryPrefix(options.execSql, scopeId),\n    );\n    assertProjectionVerificationCurrent(current);\n    if (\n      !principalHeadMatchesReference(\n        restored.previous.state,\n        options.expectedHead,\n      )\n    )\n      throw new Error(\n        \"Principal policy changed before submission; retry the mutation\",\n      );\n    return structuredClone(restored.saved);\n  } finally {\n    protection.localKey.fill(0);\n  }\n}\n\nexport async function restoreAcknowledgedPrincipalPredecessor(\n  options: RecoverPrincipalPolicyHistoryOptions,\n  saved: AcknowledgedPrincipalPredecessor | null,\n) {\n  const restored = await restoreAcknowledgedPrincipalPrefix(options, saved);\n  if (\n    !principalHeadMatchesReference(\n      restored.previous.state,\n      options.expectedHead,\n    )\n  )\n    throw new KeyingVerificationError(\n      \"object_mismatch\",\n      \"Acknowledgement predecessor does not match the authored request\",\n    );\n  return restored;\n}\n"]}

package/workflows/principals/acknowledgements/initialPrincipalCurrentPublication.js

@@ -0,0 +1,84 @@
+import { createPrincipalPolicyHistoryVerifier, KeyingVerificationError, verifyPrincipalPolicyCurrent, } from "../../../internal/crypto/index.js";
+import { assertProjectionVerificationCurrent } from "../../../data/keyingProjectionVerification/types.js";
+import { preparePrincipalHistoryEvidencePage } from "../../../data/persistence/principalHistoryEvidencePersistence.js";
+import { principalHeadMatchesReference } from "../../../data/principals/organizationAuthorityDescriptor.js";
+import { principalHistoryEvidenceScopeId } from "../../../data/principals/principalHistoryPrefixProtection.js";
+import { assertPrincipalHistoryVerificationMode, principalHistoryVerificationContext, } from "../historyRecovery/principalHistoryRecoveryVerification.js";
+import { collectPrincipalPolicySignerPublicKeys } from "../policyVerification.js";
+import { sealPrincipalCurrentPublication } from "./principalCurrentPublicationSeal.js";
+/** Verify a newly authored group from genesis before its atomic directory publication. */
+export async function prepareInitialGroupCurrentPublication(input, request, response, predecessor, checks) {
+    const current = () => !input.signal?.aborted && input.stillCurrent();
+    assertProjectionVerificationCurrent(current);
+    const expectedHead = await checks.authoredHead(request);
+    if (predecessor !== null ||
+        request.state.principalType !== "group" ||
+        request.state.version !== 1 ||
+        request.state.prevStateHash !== null ||
+        !principalHeadMatchesReference(expectedHead, input.expectedHead))
+        throw new KeyingVerificationError("object_mismatch", "Initial group publication must begin at its exact genesis");
+    checks.assertReceipt({ expectedHead, request, response });
+    const keys = await collectPrincipalPolicySignerPublicKeys({
+        bundle: { currentState: response.currentState, previousStates: [] },
+        resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,
+    });
+    if ("error" in keys)
+        throw new KeyingVerificationError("signer_mismatch", "Initial group signer could not be authenticated");
+    const externalAuthority = await input.loadExternalAuthority?.(request.state.externalAuthority ? [request.state.externalAuthority] : []);
+    assertProjectionVerificationCurrent(current);
+    const verifier = createPrincipalPolicyHistoryVerifier({
+        principalType: "group",
+        principalId: expectedHead.principalId,
+    });
+    const entry = {
+        state: response.currentState,
+        projection: response.currentProjection,
+        grants: response.currentGrants,
+    };
+    assertPrincipalHistoryVerificationMode(input, [entry]);
+    const appended = await verifier.append({
+        entries: [entry],
+        signerPublicKeys: keys.signerPublicKeys,
+        ...(externalAuthority ? { externalAuthority } : {}),
+    });
+    if (!appended.ok)
+        throw appended.error;
+    const history = verifier.finish(expectedHead);
+    if (!history.ok)
+        throw history.error;
+    const policy = await verifyPrincipalPolicyCurrent({
+        current: response,
+        history: history.value,
+    });
+    if (!policy.ok)
+        throw policy.error;
+    const options = {
+        ...input,
+        protection: {
+            ...input.protection,
+            context: principalHistoryVerificationContext(input),
+        },
+    };
+    const scopeId = await principalHistoryEvidenceScopeId({
+        organizationId: input.organizationId,
+        head: expectedHead,
+        protection: options.protection,
+    });
+    const sealed = await sealPrincipalCurrentPublication(options, scopeId, expectedHead, verifier, response);
+    assertProjectionVerificationCurrent(current);
+    return {
+        ...sealed,
+        policy: policy.value,
+        predecessorStage: null,
+        predecessorIndexRootHash: null,
+        previousPrefixProgress: null,
+        evidence: await preparePrincipalHistoryEvidencePage({
+            indexRootHash: appended.value.indexRootHash,
+            scopeId,
+            organizationId: input.organizationId,
+            entries: [entry],
+            nodes: appended.value.indexNodes,
+        }),
+    };
+}
+//# sourceMappingURL=initialPrincipalCurrentPublication.js.map

package/workflows/principals/acknowledgements/initialPrincipalCurrentPublication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"initialPrincipalCurrentPublication.js","sourceRoot":"","sources":["initialPrincipalCurrentPublication.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  createPrincipalPolicyHistoryVerifier,\n  KeyingVerificationError,\n  verifyPrincipalPolicyCurrent,\n} from \"@tearleads/crypto\";\nimport type { PutPrincipalPolicyRequest } from \"@tearleads/validators/request\";\nimport type { PrincipalPolicyMutationResponse } from \"@tearleads/validators/response\";\nimport { assertProjectionVerificationCurrent } from \"../../../data/keyingProjectionVerification/types\";\nimport type { AcknowledgedPrincipalCurrentPublication } from \"../../../data/persistence/principalCurrentAcknowledgementPersistence\";\nimport { preparePrincipalHistoryEvidencePage } from \"../../../data/persistence/principalHistoryEvidencePersistence\";\nimport { principalHeadMatchesReference } from \"../../../data/principals/organizationAuthorityDescriptor\";\nimport { principalHistoryEvidenceScopeId } from \"../../../data/principals/principalHistoryPrefixProtection\";\nimport type { RecoverPrincipalPolicyHistoryOptions } from \"../historyRecovery/principalHistoryRecoveryTypes\";\nimport {\n  assertPrincipalHistoryVerificationMode,\n  principalHistoryVerificationContext,\n} from \"../historyRecovery/principalHistoryRecoveryVerification\";\nimport { collectPrincipalPolicySignerPublicKeys } from \"../policyVerification\";\nimport type { AcknowledgedPrincipalPredecessor } from \"./acknowledgedPrincipalPredecessor\";\nimport type { PrincipalAcknowledgementChecks } from \"./principalAcknowledgementChecks\";\nimport { sealPrincipalCurrentPublication } from \"./principalCurrentPublicationSeal\";\n\n/** Verify a newly authored group from genesis before its atomic directory publication. */\nexport async function prepareInitialGroupCurrentPublication(\n  input: RecoverPrincipalPolicyHistoryOptions,\n  request: PutPrincipalPolicyRequest,\n  response: PrincipalPolicyMutationResponse,\n  predecessor: AcknowledgedPrincipalPredecessor | null,\n  checks: PrincipalAcknowledgementChecks,\n): Promise<AcknowledgedPrincipalCurrentPublication> {\n  const current = () => !input.signal?.aborted && input.stillCurrent();\n  assertProjectionVerificationCurrent(current);\n  const expectedHead = await checks.authoredHead(request);\n  if (\n    predecessor !== null ||\n    request.state.principalType !== \"group\" ||\n    request.state.version !== 1 ||\n    request.state.prevStateHash !== null ||\n    !principalHeadMatchesReference(expectedHead, input.expectedHead)\n  )\n    throw new KeyingVerificationError(\n      \"object_mismatch\",\n      \"Initial group publication must begin at its exact genesis\",\n    );\n  checks.assertReceipt({ expectedHead, request, response });\n  const keys = await collectPrincipalPolicySignerPublicKeys({\n    bundle: { currentState: response.currentState, previousStates: [] },\n    resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,\n  });\n  if (\"error\" in keys)\n    throw new KeyingVerificationError(\n      \"signer_mismatch\",\n      \"Initial group signer could not be authenticated\",\n    );\n  const externalAuthority = await input.loadExternalAuthority?.(\n    request.state.externalAuthority ? [request.state.externalAuthority] : [],\n  );\n  assertProjectionVerificationCurrent(current);\n  const verifier = createPrincipalPolicyHistoryVerifier({\n    principalType: \"group\",\n    principalId: expectedHead.principalId,\n  });\n  const entry = {\n    state: response.currentState,\n    projection: response.currentProjection,\n    grants: response.currentGrants,\n  };\n  assertPrincipalHistoryVerificationMode(input, [entry]);\n  const appended = await verifier.append({\n    entries: [entry],\n    signerPublicKeys: keys.signerPublicKeys,\n    ...(externalAuthority ? { externalAuthority } : {}),\n  });\n  if (!appended.ok) throw appended.error;\n  const history = verifier.finish(expectedHead);\n  if (!history.ok) throw history.error;\n  const policy = await verifyPrincipalPolicyCurrent({\n    current: response,\n    history: history.value,\n  });\n  if (!policy.ok) throw policy.error;\n  const options = {\n    ...input,\n    protection: {\n      ...input.protection,\n      context: principalHistoryVerificationContext(input),\n    },\n  };\n  const scopeId = await principalHistoryEvidenceScopeId({\n    organizationId: input.organizationId,\n    head: expectedHead,\n    protection: options.protection,\n  });\n  const sealed = await sealPrincipalCurrentPublication(\n    options,\n    scopeId,\n    expectedHead,\n    verifier,\n    response,\n  );\n  assertProjectionVerificationCurrent(current);\n  return {\n    ...sealed,\n    policy: policy.value,\n    predecessorStage: null,\n    predecessorIndexRootHash: null,\n    previousPrefixProgress: null,\n    evidence: await preparePrincipalHistoryEvidencePage({\n      indexRootHash: appended.value.indexRootHash,\n      scopeId,\n      organizationId: input.organizationId,\n      entries: [entry],\n      nodes: appended.value.indexNodes,\n    }),\n  };\n}\n"]}

package/workflows/principals/acknowledgements/principalAcknowledgementChecks.d.ts

@@ -0,0 +1,30 @@
+import type { PrincipalPolicyExternalAuthority, PrincipalPolicySignerPublicKey, ReferencedPrincipalHead, VerifiedPrincipalPolicyCurrent } from "../../../internal/crypto/index.js";
+import type { PutPrincipalPolicyRequest } from "../../../internal/validators/request/index.js";
+import type { PrincipalPolicyMutationResponse } from "../../../internal/validators/response/index.js";
+/**
+ * The checks the code that authored a principal mutation makes on the
+ * server's acknowledgement of it. Recovery records an acknowledged current
+ * only after these accept it; the organization mutation workflows supply them.
+ */
+export interface PrincipalAcknowledgementChecks {
+    /** The head an authored request commits to. */
+    readonly authoredHead: (request: PutPrincipalPolicyRequest) => Promise<ReferencedPrincipalHead>;
+    /** The receipt carries exactly the authored state and artifacts. */
+    readonly assertReceipt: (input: {
+        readonly expectedHead: ReferencedPrincipalHead;
+        readonly request: PutPrincipalPolicyRequest;
+        readonly response: PrincipalPolicyMutationResponse;
+    }) => void;
+    /** The acknowledged state is the authored successor of the verified predecessor. */
+    readonly acknowledgeSuccessor: (input: {
+        readonly verifiedCurrentPolicy: VerifiedPrincipalPolicyCurrent;
+        readonly expectedHead: ReferencedPrincipalHead;
+        readonly request: PutPrincipalPolicyRequest;
+        readonly response: PrincipalPolicyMutationResponse["currentState"];
+        readonly signerPublicKeys: readonly PrincipalPolicySignerPublicKey[];
+        readonly externalAuthority?: PrincipalPolicyExternalAuthority | undefined;
+        readonly stillCurrent: () => boolean;
+    }) => Promise<VerifiedPrincipalPolicyCurrent>;
+    /** Acknowledged directory and group heads cite each other. */
+    readonly assertDirectoryBindings: (organizationId: string, responses: readonly PrincipalPolicyMutationResponse[]) => void;
+}

package/workflows/principals/acknowledgements/principalCurrentPublicationSeal.js

@@ -0,0 +1,51 @@
+import { serializeKeyingCanonicalJson, } from "../../../internal/crypto/index.js";
+import { principalHistoryPrefixProtection } from "../../../data/principals/principalHistoryPrefixProtection.js";
+import { principalHistoryStageId, principalHistoryStageProtection, } from "../../../data/principals/principalHistoryStageProtection.js";
+function exactHead(head) {
+    return {
+        principalType: head.principalType,
+        principalId: head.principalId,
+        version: head.version,
+        keyEpoch: head.keyEpoch,
+        stateHash: head.stateHash,
+        keyFingerprint: head.keyFingerprint,
+    };
+}
+export async function sealPrincipalCurrentStage(options, expectedHead, verifier, response) {
+    // Authentication uses the reference contract, never extra signed-state fields.
+    expectedHead = exactHead(expectedHead);
+    const currentJson = JSON.stringify({
+        currentState: response.currentState,
+        currentProjection: response.currentProjection,
+        currentGrants: response.currentGrants,
+        currentPayload: response.currentPayload,
+        currentMemberEnvelopes: response.currentMemberEnvelopes,
+    });
+    const stage = {
+        id: await principalHistoryStageId(options.organizationId, expectedHead, options.protection.context),
+        organizationId: options.organizationId,
+        afterVersion: expectedHead.version - 1,
+        complete: true,
+        currentJson,
+    };
+    const progress = await verifier.exportProgress(await principalHistoryStageProtection(options.protection, expectedHead, stage));
+    if (!progress.ok)
+        throw progress.error;
+    return { ...stage, progress: progress.value };
+}
+export async function sealPrincipalCurrentPublication(options, scopeId, expectedHead, verifier, response) {
+    expectedHead = exactHead(expectedHead);
+    const stage = await sealPrincipalCurrentStage(options, expectedHead, verifier, response);
+    const prefix = {
+        scopeId,
+        organizationId: options.organizationId,
+        version: expectedHead.version,
+        headJson: serializeKeyingCanonicalJson({ ...expectedHead }),
+        currentJson: stage.currentJson,
+    };
+    const progress = await verifier.exportProgress(await principalHistoryPrefixProtection(options.protection, prefix));
+    if (!progress.ok)
+        throw progress.error;
+    return { prefix: { ...prefix, progress: progress.value }, stage };
+}
+//# sourceMappingURL=principalCurrentPublicationSeal.js.map

package/workflows/principals/acknowledgements/principalCurrentPublicationSeal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalCurrentPublicationSeal.js","sourceRoot":"","sources":["principalCurrentPublicationSeal.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,4BAA4B,GAC7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,gCAAgC,EAAE,MAAM,2DAA2D,CAAC;AAC7G,OAAO,EACL,uBAAuB,EACvB,+BAA+B,GAChC,MAAM,0DAA0D,CAAC;AAGlE,SAAS,SAAS,CAAC,IAA6B;IAC9C,OAAO;QACL,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,cAAc,EAAE,IAAI,CAAC,cAAc;KACpC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,OAA6C,EAC7C,YAAqC,EACrC,QAAwC,EACxC,QAAoC;IAEpC,+EAA+E;IAC/E,YAAY,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC;IACvC,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC;QACjC,YAAY,EAAE,QAAQ,CAAC,YAAY;QACnC,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;QAC7C,aAAa,EAAE,QAAQ,CAAC,aAAa;QACrC,cAAc,EAAE,QAAQ,CAAC,cAAc;QACvC,sBAAsB,EAAE,QAAQ,CAAC,sBAAsB;KACxD,CAAC,CAAC;IACH,MAAM,KAAK,GAAG;QACZ,EAAE,EAAE,MAAM,uBAAuB,CAC/B,OAAO,CAAC,cAAc,EACtB,YAAY,EACZ,OAAO,CAAC,UAAU,CAAC,OAAO,CAC3B;QACD,cAAc,EAAE,OAAO,CAAC,cAAc;QACtC,YAAY,EAAE,YAAY,CAAC,OAAO,GAAG,CAAC;QACtC,QAAQ,EAAE,IAAI;QACd,WAAW;KACZ,CAAC;IACF,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,cAAc,CAC5C,MAAM,+BAA+B,CACnC,OAAO,CAAC,UAAU,EAClB,YAAY,EACZ,KAAK,CACN,CACF,CAAC;IACF,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,MAAM,QAAQ,CAAC,KAAK,CAAC;IACvC,OAAO,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC;AAChD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,+BAA+B,CACnD,OAA6C,EAC7C,OAAe,EACf,YAAqC,EACrC,QAAwC,EACxC,QAAoC;IAEpC,YAAY,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,MAAM,yBAAyB,CAC3C,OAAO,EACP,YAAY,EACZ,QAAQ,EACR,QAAQ,CACT,CAAC;IACF,MAAM,MAAM,GAAG;QACb,OAAO;QACP,cAAc,EAAE,OAAO,CAAC,cAAc;QACtC,OAAO,EAAE,YAAY,CAAC,OAAO;QAC7B,QAAQ,EAAE,4BAA4B,CAAC,EAAE,GAAG,YAAY,EAAE,CAAC;QAC3D,WAAW,EAAE,KAAK,CAAC,WAAW;KAC/B,CAAC;IACF,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,cAAc,CAC5C,MAAM,gCAAgC,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,CAAC,CACnE,CAAC;IACF,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,MAAM,QAAQ,CAAC,KAAK,CAAC;IACvC,OAAO,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC;AACpE,CAAC","sourcesContent":["import type { PrincipalPolicyPageCurrent } from \"@tearleads/api-client\";\nimport {\n  type PrincipalPolicyHistoryVerifier,\n  type ReferencedPrincipalHead,\n  serializeKeyingCanonicalJson,\n} from \"@tearleads/crypto\";\nimport { principalHistoryPrefixProtection } from \"../../../data/principals/principalHistoryPrefixProtection\";\nimport {\n  principalHistoryStageId,\n  principalHistoryStageProtection,\n} from \"../../../data/principals/principalHistoryStageProtection\";\nimport type { RecoverPrincipalPolicyHistoryOptions } from \"../historyRecovery/principalHistoryRecoveryTypes\";\n\nfunction exactHead(head: ReferencedPrincipalHead): ReferencedPrincipalHead {\n  return {\n    principalType: head.principalType,\n    principalId: head.principalId,\n    version: head.version,\n    keyEpoch: head.keyEpoch,\n    stateHash: head.stateHash,\n    keyFingerprint: head.keyFingerprint,\n  };\n}\n\nexport async function sealPrincipalCurrentStage(\n  options: RecoverPrincipalPolicyHistoryOptions,\n  expectedHead: ReferencedPrincipalHead,\n  verifier: PrincipalPolicyHistoryVerifier,\n  response: PrincipalPolicyPageCurrent,\n) {\n  // Authentication uses the reference contract, never extra signed-state fields.\n  expectedHead = exactHead(expectedHead);\n  const currentJson = JSON.stringify({\n    currentState: response.currentState,\n    currentProjection: response.currentProjection,\n    currentGrants: response.currentGrants,\n    currentPayload: response.currentPayload,\n    currentMemberEnvelopes: response.currentMemberEnvelopes,\n  });\n  const stage = {\n    id: await principalHistoryStageId(\n      options.organizationId,\n      expectedHead,\n      options.protection.context,\n    ),\n    organizationId: options.organizationId,\n    afterVersion: expectedHead.version - 1,\n    complete: true,\n    currentJson,\n  };\n  const progress = await verifier.exportProgress(\n    await principalHistoryStageProtection(\n      options.protection,\n      expectedHead,\n      stage,\n    ),\n  );\n  if (!progress.ok) throw progress.error;\n  return { ...stage, progress: progress.value };\n}\n\nexport async function sealPrincipalCurrentPublication(\n  options: RecoverPrincipalPolicyHistoryOptions,\n  scopeId: string,\n  expectedHead: ReferencedPrincipalHead,\n  verifier: PrincipalPolicyHistoryVerifier,\n  response: PrincipalPolicyPageCurrent,\n) {\n  expectedHead = exactHead(expectedHead);\n  const stage = await sealPrincipalCurrentStage(\n    options,\n    expectedHead,\n    verifier,\n    response,\n  );\n  const prefix = {\n    scopeId,\n    organizationId: options.organizationId,\n    version: expectedHead.version,\n    headJson: serializeKeyingCanonicalJson({ ...expectedHead }),\n    currentJson: stage.currentJson,\n  };\n  const progress = await verifier.exportProgress(\n    await principalHistoryPrefixProtection(options.protection, prefix),\n  );\n  if (!progress.ok) throw progress.error;\n  return { prefix: { ...prefix, progress: progress.value }, stage };\n}\n"]}

package/workflows/principals/acknowledgements/reconcileAcknowledgedPrincipalCurrent.js

@@ -0,0 +1,68 @@
+import { KeyingVerificationError, verifyPrincipalPolicyCurrent, } from "../../../internal/crypto/index.js";
+import { loadPrincipalPolicyCheckpoint } from "../../../data/persistence/keyingCheckpointPersistence.js";
+import { loadPrincipalHistoryPrefix } from "../../../data/persistence/principalHistoryPrefixPersistence.js";
+import { principalHeadMatchesReference } from "../../../data/principals/organizationAuthorityDescriptor.js";
+import { PrincipalHistoryEvidenceUnavailableError, selectRecoveredPrincipalHistory, } from "../historyRecovery/principalHistoryRecoveryReferences.js";
+import { principalHistoryVerificationContext } from "../historyRecovery/principalHistoryRecoveryVerification.js";
+import { restoreAcknowledgedPrincipalPrefix } from "./acknowledgedPrincipalPredecessor.js";
+/** Only the receipt is proven; a newer local pin needs scoped history covering it. */
+function reconcileReceiptOnly(publication, observedPrefixProgress, checkpoint) {
+    // Other verified evidence, such as a document purge proof, can pin a newer
+    // head without advancing this scope's prefix. That is honest progress this
+    // receipt cannot prove membership in: retry after recovery, not a rollback.
+    // A genesis receipt has no predecessor, so any existing pin stays a conflict.
+    if (publication.predecessorStage &&
+        checkpoint &&
+        checkpoint.version > publication.policy.version)
+        throw new PrincipalHistoryEvidenceUnavailableError(new KeyingVerificationError("missing_dependency", "A newer local principal pin is not covered by scoped history"));
+    return {
+        ...publication,
+        preservePrefix: false,
+        observedPrefixProgress,
+        observedCheckpoint: checkpoint,
+        retainedPrefix: publication.prefix,
+        checkpointPolicy: publication.policy,
+    };
+}
+/** Prove an already observed successor contains this receipt before preserving it. */
+export async function reconcileAcknowledgedPrincipalCurrent(input, publication) {
+    const options = {
+        ...input,
+        protection: {
+            ...input.protection,
+            context: principalHistoryVerificationContext(input),
+        },
+    };
+    const checkpoint = await loadPrincipalPolicyCheckpoint(options.execSql, publication.policy.principalType, publication.policy.principalId);
+    const saved = await loadPrincipalHistoryPrefix(options.execSql, publication.prefix.scopeId);
+    const observedPrefixProgress = saved?.progress ?? null;
+    if (observedPrefixProgress === publication.previousPrefixProgress)
+        return reconcileReceiptOnly(publication, observedPrefixProgress, checkpoint);
+    const restored = await restoreAcknowledgedPrincipalPrefix(options, saved);
+    if (restored.previous.version < publication.policy.version) {
+        if (!principalHeadMatchesReference(restored.previous.state, options.expectedHead))
+            throw new KeyingVerificationError("stale_predecessor", "Acknowledgement does not extend the authenticated current prefix");
+        return reconcileReceiptOnly(publication, observedPrefixProgress, checkpoint);
+    }
+    const history = await selectRecoveredPrincipalHistory({
+        options: { ...options, retainedReferences: [publication.policy.state] },
+        scopeId: publication.prefix.scopeId,
+        history: restored.history,
+        checkpoint,
+    });
+    const policy = await verifyPrincipalPolicyCurrent({
+        current: restored.artifacts,
+        history,
+    });
+    if (!policy.ok)
+        throw policy.error;
+    return {
+        ...publication,
+        preservePrefix: true,
+        observedPrefixProgress,
+        observedCheckpoint: checkpoint,
+        retainedPrefix: restored.saved,
+        checkpointPolicy: policy.value,
+    };
+}
+//# sourceMappingURL=reconcileAcknowledgedPrincipalCurrent.js.map

package/workflows/principals/acknowledgements/reconcileAcknowledgedPrincipalCurrent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcileAcknowledgedPrincipalCurrent.js","sourceRoot":"","sources":["reconcileAcknowledgedPrincipalCurrent.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  KeyingVerificationError,\n  type PrincipalPolicyCheckpoint,\n  verifyPrincipalPolicyCurrent,\n} from \"@tearleads/crypto\";\nimport { loadPrincipalPolicyCheckpoint } from \"../../../data/persistence/keyingCheckpointPersistence\";\nimport type {\n  AcknowledgedPrincipalCurrentPublication,\n  ReconciledPrincipalCurrentPublication,\n} from \"../../../data/persistence/principalCurrentAcknowledgementPersistence\";\nimport { loadPrincipalHistoryPrefix } from \"../../../data/persistence/principalHistoryPrefixPersistence\";\nimport { principalHeadMatchesReference } from \"../../../data/principals/organizationAuthorityDescriptor\";\nimport {\n  PrincipalHistoryEvidenceUnavailableError,\n  selectRecoveredPrincipalHistory,\n} from \"../historyRecovery/principalHistoryRecoveryReferences\";\nimport type { RecoverPrincipalPolicyHistoryOptions } from \"../historyRecovery/principalHistoryRecoveryTypes\";\nimport { principalHistoryVerificationContext } from \"../historyRecovery/principalHistoryRecoveryVerification\";\nimport { restoreAcknowledgedPrincipalPrefix } from \"./acknowledgedPrincipalPredecessor\";\n\n/** Only the receipt is proven; a newer local pin needs scoped history covering it. */\nfunction reconcileReceiptOnly(\n  publication: AcknowledgedPrincipalCurrentPublication,\n  observedPrefixProgress: string | null,\n  checkpoint: PrincipalPolicyCheckpoint | null,\n): ReconciledPrincipalCurrentPublication {\n  // Other verified evidence, such as a document purge proof, can pin a newer\n  // head without advancing this scope's prefix. That is honest progress this\n  // receipt cannot prove membership in: retry after recovery, not a rollback.\n  // A genesis receipt has no predecessor, so any existing pin stays a conflict.\n  if (\n    publication.predecessorStage &&\n    checkpoint &&\n    checkpoint.version > publication.policy.version\n  )\n    throw new PrincipalHistoryEvidenceUnavailableError(\n      new KeyingVerificationError(\n        \"missing_dependency\",\n        \"A newer local principal pin is not covered by scoped history\",\n      ),\n    );\n  return {\n    ...publication,\n    preservePrefix: false,\n    observedPrefixProgress,\n    observedCheckpoint: checkpoint,\n    retainedPrefix: publication.prefix,\n    checkpointPolicy: publication.policy,\n  };\n}\n\n/** Prove an already observed successor contains this receipt before preserving it. */\nexport async function reconcileAcknowledgedPrincipalCurrent(\n  input: RecoverPrincipalPolicyHistoryOptions,\n  publication: AcknowledgedPrincipalCurrentPublication,\n): Promise<ReconciledPrincipalCurrentPublication> {\n  const options = {\n    ...input,\n    protection: {\n      ...input.protection,\n      context: principalHistoryVerificationContext(input),\n    },\n  };\n  const checkpoint = await loadPrincipalPolicyCheckpoint(\n    options.execSql,\n    publication.policy.principalType,\n    publication.policy.principalId,\n  );\n  const saved = await loadPrincipalHistoryPrefix(\n    options.execSql,\n    publication.prefix.scopeId,\n  );\n  const observedPrefixProgress = saved?.progress ?? null;\n  if (observedPrefixProgress === publication.previousPrefixProgress)\n    return reconcileReceiptOnly(\n      publication,\n      observedPrefixProgress,\n      checkpoint,\n    );\n  const restored = await restoreAcknowledgedPrincipalPrefix(options, saved);\n  if (restored.previous.version < publication.policy.version) {\n    if (\n      !principalHeadMatchesReference(\n        restored.previous.state,\n        options.expectedHead,\n      )\n    )\n      throw new KeyingVerificationError(\n        \"stale_predecessor\",\n        \"Acknowledgement does not extend the authenticated current prefix\",\n      );\n    return reconcileReceiptOnly(\n      publication,\n      observedPrefixProgress,\n      checkpoint,\n    );\n  }\n  const history = await selectRecoveredPrincipalHistory({\n    options: { ...options, retainedReferences: [publication.policy.state] },\n    scopeId: publication.prefix.scopeId,\n    history: restored.history,\n    checkpoint,\n  });\n  const policy = await verifyPrincipalPolicyCurrent({\n    current: restored.artifacts,\n    history,\n  });\n  if (!policy.ok) throw policy.error;\n  return {\n    ...publication,\n    preservePrefix: true,\n    observedPrefixProgress,\n    observedCheckpoint: checkpoint,\n    retainedPrefix: restored.saved,\n    checkpointPolicy: policy.value,\n  };\n}\n"]}

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

@@ -0,0 +1,10 @@
+import { type PrincipalPolicyStateChainEntryResponse } from "../../../internal/validators/response/index.js";
+import { type RecoverPrincipalPolicyHistoryOptions } from "./principalHistoryRecoveryTypes.js";
+export interface RecoveredPrincipalHistoryPage {
+    /** Ascending entries, with the immediate predecessor kept separately for diffs. */
+    readonly entries: readonly PrincipalPolicyStateChainEntryResponse[];
+    readonly predecessor: PrincipalPolicyStateChainEntryResponse | null;
+    readonly nextBeforeVersion: number | null;
+}
+/** Read a bounded historical window from an already recovered, exact private root. */
+export declare function loadRecoveredPrincipalHistoryPage(options: RecoverPrincipalPolicyHistoryOptions, beforeVersion?: number): Promise<RecoveredPrincipalHistoryPage>;