@tearleads/client-sdk 0.1.62 → 0.1.64

package/workflows/organizations/rematerialization/principalContainerRematerialization.js

@@ -0,0 +1,321 @@
+import { MAX_ROTATION_CONTAINER_REKEYS } from "../../../internal/validators/util/index.js";
+import { rememberVerifiedContainerHeads } from "../../../data/containers/shared/heldContainerHeads.js";
+import { acknowledgeContainerMutationBatch } from "../../../data/containers/shared/mutationAcknowledgement.js";
+import { getTargetContainerContext, readContainerState, } from "../../../data/containers/shared/projection.js";
+import { verifyContainerWriterProjection, } from "../../../data/keyingProjectionVerification/index.js";
+import { createProjectionUserKeyResolver } from "../../../data/keyingProjectionVerification/userKeyResolver.js";
+import { scheduleHeldDescendantRecitations } from "../../containers/child/recite.js";
+import { buildMaterializedContainerRekeyPlan } from "../../containers/child/rekey/index.js";
+import { rebaseOnDeepestAncestor } from "../../containers/child/rekey/carriedDescendantRekeys.js";
+import { containerWriterProjectionFromRotationPlan, containerWriterProjectionFromSharePlan, isSpeculativeContainerWriterProjection, } from "../../containers/child/rekey/rekeyProjection.js";
+import { buildMaterializedContainerRevokePlan } from "../../containers/child/revoke.js";
+import { selectReplacementPrincipalPolicyReferences } from "../../containers/child/rotation/replacementPrincipalPolicyReferences.js";
+import { buildMaterializedContainerSharePlan } from "../../containers/child/share/shareMaterialization.js";
+import { withPrecedingRematerialization } from "./precedingPrincipalRematerialization.js";
+import { addPlan, carryLevel, staleLevelsAbove, } from "./principalContainerRematerializationPlanning.js";
+import { loadRematerializationTargets, loadServedProjection, seededPrincipalPolicyCache, } from "./principalContainerRematerializationTargets.js";
+function matchingGroupGrant(input) {
+    return (input.directGrants.find((grant) => grant.subjectType === "group" && grant.subjectId === input.groupId) ?? null);
+}
+function referencedGroupKeyEpoch(input) {
+    return (input.referencedPrincipalHeads.find((head) => head.principalType === "group" && head.principalId === input.groupId)?.keyEpoch ?? null);
+}
+async function loadGrantedContainerContext(input, grantRow, projection, principalPolicyCache) {
+    // A projection re-rooted on a rotation this batch has yet to commit must
+    // not pin anything: its heads are speculative until acknowledged, and a
+    // pin past the group's served head would refuse the other served paths.
+    await verifyContainerWriterProjection({
+        execSql: input.execSql,
+        persistVerificationCheckpoints: !isSpeculativeContainerWriterProjection(projection),
+        principalPolicyCache,
+        projection,
+        resolveUserKey: createProjectionUserKeyResolver({
+            resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,
+        }),
+        stillCurrent: input.stillCurrent,
+        warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,
+    });
+    const state = readContainerState(getTargetContainerContext(projection).manifest);
+    const grant = matchingGroupGrant({
+        directGrants: state.directGrants,
+        groupId: input.groupId,
+    });
+    if (grant && grant.accessLevel !== grantRow.accessLevel) {
+        const nextGrant = input.nextPolicy.grants.find((candidate) => candidate.containerId === grantRow.containerId);
+        if (!nextGrant || nextGrant.accessLevel !== grantRow.accessLevel) {
+            throw new Error(`Container ${grantRow.containerId} does not contain the expected group grant`);
+        }
+    }
+    const referencedKeyEpoch = referencedGroupKeyEpoch({
+        groupId: input.groupId,
+        referencedPrincipalHeads: state.referencedPrincipalHeads,
+    });
+    if (grant && referencedKeyEpoch === null) {
+        throw new Error(`Container ${grantRow.containerId} is missing its group reference`);
+    }
+    return { grant, projection, referencedKeyEpoch };
+}
+export async function buildPrincipalContainerRematerializationBatch(input) {
+    return (await buildPrincipalContainerRematerializationPlans(input)).entries.map((entry) => entry.planned.plan.request);
+}
+function authoredMutationHead(planned) {
+    return planned.plan;
+}
+async function buildPrincipalContainerRematerializationPlan(input) {
+    const { grantRow } = input;
+    const rematerialization = {
+        ...input.rematerialization,
+        nextPolicy: await selectReplacementPrincipalPolicyReferences({
+            policy: input.rematerialization.nextPolicy,
+            projection: input.projection,
+            principalPolicyCache: input.principalPolicyCache,
+            resolveAuthoredPolicyReferences: input.rematerialization.resolveAuthoredPolicyReferences,
+        }),
+    };
+    const { grant, projection, referencedKeyEpoch } = await loadGrantedContainerContext(rematerialization, grantRow, input.projection, input.principalPolicyCache);
+    const nextGrant = rematerialization.nextPolicy.grants.find((candidate) => candidate.containerId === grantRow.containerId);
+    const author = {
+        ...rematerialization.author,
+        organizationId: projection.organizationId,
+    };
+    const sharedInput = {
+        author,
+        execSql: rematerialization.execSql,
+        knownContainerKeks: input.knownContainerKeks,
+        // Planning against a path this batch has yet to commit pins nothing; the
+        // acknowledgement advances every head at once. The rekey planner applies
+        // this rule itself; revoke and grant planning take it from here.
+        persistVerificationCheckpoints: !isSpeculativeContainerWriterProjection(projection),
+        previousProjection: projection,
+        principalPolicyCache: input.principalPolicyCache,
+        resolveProjectionUserKey: input.resolveProjectionUserKey,
+        stillCurrent: rematerialization.stillCurrent,
+        targetSecretKey: rematerialization.targetSecretKey,
+        warmReferencedPrincipalPolicies: rematerialization.warmReferencedPrincipalPolicies,
+    };
+    if (grantRow.containerId === rematerialization.revokedContainerId) {
+        if (!grant) {
+            throw new Error(`Container ${grantRow.containerId} does not contain the revoked group grant`);
+        }
+        return buildMaterializedContainerRevokePlan({
+            ...sharedInput,
+            replacementPrincipalPolicy: rematerialization.nextPolicy,
+            revokedSubject: {
+                subjectId: rematerialization.groupId,
+                subjectType: "group",
+            },
+        });
+    }
+    if (!grant || grant.accessLevel !== nextGrant?.accessLevel) {
+        if (!nextGrant) {
+            throw new Error(`Container ${grantRow.containerId} is absent from the next group grant set`);
+        }
+        return buildMaterializedContainerSharePlan({
+            ...sharedInput,
+            accessLevel: nextGrant.accessLevel,
+            recipient: {
+                principalPolicy: rematerialization.nextPolicy,
+                subjectId: rematerialization.groupId,
+                subjectType: "group",
+            },
+        });
+    }
+    if (referencedKeyEpoch === rematerialization.nextPolicy.keyEpoch) {
+        return buildMaterializedContainerSharePlan({
+            ...sharedInput,
+            accessLevel: grant.accessLevel,
+            recipient: {
+                principalPolicy: rematerialization.nextPolicy,
+                subjectId: rematerialization.groupId,
+                subjectType: "group",
+            },
+        });
+    }
+    return buildMaterializedContainerRekeyPlan({
+        ...sharedInput,
+        replacementPrincipalPolicy: rematerialization.nextPolicy,
+    });
+}
+/**
+ * Plan one target against the paths already planned above it. A grant's
+ * rematerialization extends the served head; a rotation's, and every carried
+ * rekey, extends the epoch the batch mints above it.
+ */
+async function planRematerializationTarget(batch, target) {
+    const { rematerialization } = batch;
+    let rebased = rebaseOnDeepestAncestor(target.projection, batch.rotatedAbove);
+    const stale = rebased
+        ? staleLevelsAbove(rebased.projection, rebased.ancestor.containerKeks.at(-1)?.containerId ?? "")
+        : [];
+    for (const containerId of stale) {
+        await carryLevel(batch, await loadServedProjection(rematerialization.apiClient, containerId));
+    }
+    if (!target.grantRow) {
+        await carryLevel(batch, target.projection);
+        return;
+    }
+    // Each level carried above re-roots the target one step deeper.
+    if (stale.length > 0) {
+        rebased = rebaseOnDeepestAncestor(target.projection, batch.rotatedAbove);
+    }
+    const previousProjection = rebased?.projection ?? target.projection;
+    const planned = await buildPrincipalContainerRematerializationPlan({
+        grantRow: target.grantRow,
+        knownContainerKeks: batch.knownContainerKeks,
+        principalPolicyCache: batch.principalPolicyCache,
+        projection: previousProjection,
+        rematerialization,
+        resolveProjectionUserKey: batch.resolveProjectionUserKey,
+    });
+    const nextProjection = "keyring" in planned.plan
+        ? await containerWriterProjectionFromRotationPlan({
+            plan: planned.plan,
+            previousProjection,
+        })
+        : await containerWriterProjectionFromSharePlan({
+            plan: planned.plan,
+            previousProjection,
+        });
+    addPlan(batch, {
+        carried: false,
+        planned,
+        rotated: "keyring" in planned.plan ? nextProjection : null,
+        nextProjection,
+    });
+}
+/**
+ * Sign the batch parent-first. `carriedContainerIds` are the descendant rekeys
+ * a refused attempt was told to carry; woven in by depth, each sits under the
+ * rotation it rides, and a named container the batch rematerializes anyway is
+ * re-planned there rather than rotated twice.
+ */
+async function buildPrincipalContainerRematerializationPlans(input, carriedContainerIds = []) {
+    input = withPrecedingRematerialization(input);
+    if (input.revokedContainerId &&
+        !input.grants.some((grant) => grant.containerId === input.revokedContainerId)) {
+        throw new Error("Revoked container is not granted to the group");
+    }
+    const { targets, retiredContainerIds } = await loadRematerializationTargets({
+        apiClient: input.apiClient,
+        carriedContainerIds,
+        grants: input.grants,
+    });
+    const batch = {
+        knownContainerKeks: new Map(input.preceding?.knownContainerKeks),
+        plans: [],
+        // A rotation planned above cites the group at the head this batch commits,
+        // which no store holds yet; the cache is what lets a rebased path verify.
+        principalPolicyCache: new Map([
+            ...(input.preceding?.policies ?? []).flatMap((policy) => [
+                ...seededPrincipalPolicyCache(policy),
+            ]),
+            ...seededPrincipalPolicyCache(input.nextPolicy),
+        ]),
+        rematerialization: input,
+        resolveProjectionUserKey: createProjectionUserKeyResolver({
+            resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,
+        }),
+        rotatedAbove: [],
+    };
+    for (const target of targets) {
+        await planRematerializationTarget(batch, target);
+    }
+    return {
+        entries: batch.plans,
+        retiredContainerIds,
+        preceding: {
+            policies: [...(input.preceding?.policies ?? []), input.nextPolicy],
+            projections: [
+                ...(input.preceding?.projections ?? []),
+                ...batch.plans.flatMap((entry) => entry.nextProjection ? [entry.nextProjection] : []),
+            ],
+            knownContainerKeks: batch.knownContainerKeks,
+        },
+    };
+}
+/**
+ * The server names a level it found pinned to a retired epoch. A batch answers
+ * with a rotation of it: a carried rekey, or its own rematerialization when
+ * that is a rekey or revoke. A rematerialized grant rotates nothing, so a
+ * batch that both grants a container and must re-key it cannot be signed;
+ * no policy change the SDK builds combines the two.
+ */
+function assertNamedContainersRotated(plans, requiredContainerIds) {
+    const rotatedIds = new Set(plans.flatMap((entry) => entry.rotated ? [entry.planned.plan.containerId] : []));
+    const unrotated = requiredContainerIds
+        .slice(0, MAX_ROTATION_CONTAINER_REKEYS)
+        .find((containerId) => !rotatedIds.has(containerId));
+    if (unrotated !== undefined) {
+        throw new Error(`Container ${unrotated} needs a rekey this policy change only grants`);
+    }
+}
+export async function preparePrincipalContainerRematerializationBatch(input) {
+    let { entries, retiredContainerIds, preceding } = await buildPrincipalContainerRematerializationPlans(input);
+    const requests = () => entries.map((entry) => entry.planned.plan.request);
+    return {
+        get preceding() {
+            return preceding;
+        },
+        get retiredContainerIds() {
+            return retiredContainerIds;
+        },
+        get plans() {
+            return entries.map((entry) => entry.planned);
+        },
+        get requests() {
+            return requests();
+        },
+        carry: async (requiredContainerIds) => {
+            // The refused attempt rolled back whole, so every served head still
+            // stands; the batch is signed again from them with the named levels in.
+            const replanned = await buildPrincipalContainerRematerializationPlans(input, requiredContainerIds);
+            assertNamedContainersRotated(replanned.entries, requiredContainerIds);
+            entries = replanned.entries;
+            retiredContainerIds = replanned.retiredContainerIds;
+            preceding = replanned.preceding;
+            return requests();
+        },
+        acknowledge: async (responses, stillCurrent) => {
+            const isCurrent = () => input.stillCurrent?.() !== false && stillCurrent?.() !== false;
+            const heads = entries.map((entry) => authoredMutationHead(entry.planned));
+            const acknowledged = await acknowledgeContainerMutationBatch({
+                execSql: input.execSql,
+                plans: heads,
+                responses,
+                stillCurrent: isCurrent,
+            });
+            if (!acknowledged || !isCurrent())
+                return;
+            const plansByOrganization = new Map();
+            for (const head of heads) {
+                const organizationId = head.state.organizationId;
+                const group = plansByOrganization.get(organizationId) ?? [];
+                group.push(head);
+                plansByOrganization.set(organizationId, group);
+            }
+            for (const [organizationId, organizationPlans] of plansByOrganization) {
+                try {
+                    rememberVerifiedContainerHeads({
+                        organizationId,
+                        execSql: input.execSql,
+                        heads: [],
+                        policies: [input.nextPolicy],
+                    });
+                }
+                catch {
+                    // Cache failure must not invalidate the durably acknowledged batch.
+                    continue;
+                }
+                scheduleHeldDescendantRecitations({
+                    apiClient: input.apiClient,
+                    author: { ...input.author, organizationId },
+                    execSql: input.execSql,
+                    plans: organizationPlans,
+                    stillCurrent: input.recitationStillCurrent ?? isCurrent,
+                    reportSecurityIncident: input.reportSecurityIncident,
+                });
+            }
+        },
+    };
+}
+//# sourceMappingURL=principalContainerRematerialization.js.map

package/workflows/organizations/rematerialization/principalContainerRematerialization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalContainerRematerialization.js","sourceRoot":"","sources":["principalContainerRematerialization.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  ContainerDirectGrant,\n  PrincipalContainerGrant,\n} from \"@tearleads/crypto\";\nimport type { ContainerMutationRequest } from \"@tearleads/validators/request\";\nimport type {\n  ContainerMutationResponse,\n  ContainerWriterProjectionResponse,\n} from \"@tearleads/validators/response\";\nimport { MAX_ROTATION_CONTAINER_REKEYS } from \"@tearleads/validators/util\";\nimport { rememberVerifiedContainerHeads } from \"../../../data/containers/shared/heldContainerHeads\";\nimport type { AuthoredContainerMutationHead } from \"../../../data/containers/shared/mutationAcknowledgement\";\nimport { acknowledgeContainerMutationBatch } from \"../../../data/containers/shared/mutationAcknowledgement\";\nimport {\n  getTargetContainerContext,\n  readContainerState,\n} from \"../../../data/containers/shared/projection\";\nimport {\n  type PrincipalPolicyCache,\n  verifyContainerWriterProjection,\n} from \"../../../data/keyingProjectionVerification\";\nimport { createProjectionUserKeyResolver } from \"../../../data/keyingProjectionVerification/userKeyResolver\";\nimport { scheduleHeldDescendantRecitations } from \"../../containers/child/recite\";\nimport { buildMaterializedContainerRekeyPlan } from \"../../containers/child/rekey\";\nimport { rebaseOnDeepestAncestor } from \"../../containers/child/rekey/carriedDescendantRekeys\";\nimport {\n  containerWriterProjectionFromRotationPlan,\n  containerWriterProjectionFromSharePlan,\n  isSpeculativeContainerWriterProjection,\n} from \"../../containers/child/rekey/rekeyProjection\";\nimport { buildMaterializedContainerRevokePlan } from \"../../containers/child/revoke\";\nimport { selectReplacementPrincipalPolicyReferences } from \"../../containers/child/rotation/replacementPrincipalPolicyReferences\";\nimport { buildMaterializedContainerSharePlan } from \"../../containers/child/share/shareMaterialization\";\nimport { withPrecedingRematerialization } from \"./precedingPrincipalRematerialization\";\nimport {\n  addPlan,\n  type BatchPlanning,\n  carryLevel,\n  type PrincipalContainerRematerializationInput,\n  type PrincipalRematerializationPredecessor,\n  staleLevelsAbove,\n} from \"./principalContainerRematerializationPlanning\";\nimport {\n  loadRematerializationTargets,\n  loadServedProjection,\n  type MaterializedPrincipalContainerMutationPlan,\n  type PlannedRematerialization,\n  type RematerializationTarget,\n  seededPrincipalPolicyCache,\n} from \"./principalContainerRematerializationTargets\";\n\nfunction matchingGroupGrant(input: {\n  readonly directGrants: readonly ContainerDirectGrant[];\n  readonly groupId: string;\n}): ContainerDirectGrant | null {\n  return (\n    input.directGrants.find(\n      (grant) =>\n        grant.subjectType === \"group\" && grant.subjectId === input.groupId,\n    ) ?? null\n  );\n}\n\nfunction referencedGroupKeyEpoch(input: {\n  readonly groupId: string;\n  readonly referencedPrincipalHeads: ReturnType<\n    typeof readContainerState\n  >[\"referencedPrincipalHeads\"];\n}): number | null {\n  return (\n    input.referencedPrincipalHeads.find(\n      (head) =>\n        head.principalType === \"group\" && head.principalId === input.groupId,\n    )?.keyEpoch ?? null\n  );\n}\n\nasync function loadGrantedContainerContext(\n  input: PrincipalContainerRematerializationInput,\n  grantRow: PrincipalContainerGrant,\n  projection: ContainerWriterProjectionResponse,\n  principalPolicyCache: PrincipalPolicyCache,\n) {\n  // A projection re-rooted on a rotation this batch has yet to commit must\n  // not pin anything: its heads are speculative until acknowledged, and a\n  // pin past the group's served head would refuse the other served paths.\n  await verifyContainerWriterProjection({\n    execSql: input.execSql,\n    persistVerificationCheckpoints:\n      !isSpeculativeContainerWriterProjection(projection),\n    principalPolicyCache,\n    projection,\n    resolveUserKey: createProjectionUserKeyResolver({\n      resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,\n    }),\n    stillCurrent: input.stillCurrent,\n    warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,\n  });\n  const state = readContainerState(\n    getTargetContainerContext(projection).manifest,\n  );\n  const grant = matchingGroupGrant({\n    directGrants: state.directGrants,\n    groupId: input.groupId,\n  });\n  if (grant && grant.accessLevel !== grantRow.accessLevel) {\n    const nextGrant = input.nextPolicy.grants.find(\n      (candidate) => candidate.containerId === grantRow.containerId,\n    );\n    if (!nextGrant || nextGrant.accessLevel !== grantRow.accessLevel) {\n      throw new Error(\n        `Container ${grantRow.containerId} does not contain the expected group grant`,\n      );\n    }\n  }\n  const referencedKeyEpoch = referencedGroupKeyEpoch({\n    groupId: input.groupId,\n    referencedPrincipalHeads: state.referencedPrincipalHeads,\n  });\n  if (grant && referencedKeyEpoch === null) {\n    throw new Error(\n      `Container ${grantRow.containerId} is missing its group reference`,\n    );\n  }\n  return { grant, projection, referencedKeyEpoch };\n}\n\nexport async function buildPrincipalContainerRematerializationBatch(\n  input: PrincipalContainerRematerializationInput,\n): Promise<ContainerMutationRequest[]> {\n  return (\n    await buildPrincipalContainerRematerializationPlans(input)\n  ).entries.map((entry) => entry.planned.plan.request);\n}\n\nexport interface PreparedPrincipalContainerRematerializationBatch {\n  readonly preceding?: PrincipalRematerializationPredecessor | undefined;\n  readonly retiredContainerIds: readonly string[];\n  readonly acknowledge: (\n    responses: readonly ContainerMutationResponse[],\n    stillCurrent?: (() => boolean) | undefined,\n  ) => Promise<void>;\n  /**\n   * Re-sign the batch with the descendant rekeys the server named for its\n   * rotations woven in, parent-first, each against the path the batch will\n   * leave behind. A named container the batch already rotates is re-planned\n   * under what is carried above it, so no container rotates twice. Returns the\n   * whole request list, which replaces `requests`; `acknowledge` then expects\n   * the responses in that order.\n   */\n  readonly carry: (\n    requiredContainerIds: readonly string[],\n  ) => Promise<readonly ContainerMutationRequest[]>;\n  readonly plans: readonly MaterializedPrincipalContainerMutationPlan[];\n  readonly requests: readonly ContainerMutationRequest[];\n}\n\nfunction authoredMutationHead(\n  planned: MaterializedPrincipalContainerMutationPlan,\n): AuthoredContainerMutationHead {\n  return planned.plan;\n}\n\nasync function buildPrincipalContainerRematerializationPlan(input: {\n  readonly grantRow: PrincipalContainerGrant;\n  /** Keys the batch minted above this container; see `BatchPlanning`. */\n  readonly knownContainerKeks: ReadonlyMap<string, Uint8Array>;\n  /** Holds the policy this batch commits, which rebased paths already cite. */\n  readonly principalPolicyCache: PrincipalPolicyCache;\n  /** The served projection, re-rooted on any rotation planned above it. */\n  readonly projection: ContainerWriterProjectionResponse;\n  readonly rematerialization: PrincipalContainerRematerializationInput;\n  readonly resolveProjectionUserKey: ReturnType<\n    typeof createProjectionUserKeyResolver\n  >;\n}): Promise<MaterializedPrincipalContainerMutationPlan> {\n  const { grantRow } = input;\n  const rematerialization = {\n    ...input.rematerialization,\n    nextPolicy: await selectReplacementPrincipalPolicyReferences({\n      policy: input.rematerialization.nextPolicy,\n      projection: input.projection,\n      principalPolicyCache: input.principalPolicyCache,\n      resolveAuthoredPolicyReferences:\n        input.rematerialization.resolveAuthoredPolicyReferences,\n    }),\n  };\n  const { grant, projection, referencedKeyEpoch } =\n    await loadGrantedContainerContext(\n      rematerialization,\n      grantRow,\n      input.projection,\n      input.principalPolicyCache,\n    );\n  const nextGrant = rematerialization.nextPolicy.grants.find(\n    (candidate) => candidate.containerId === grantRow.containerId,\n  );\n  const author = {\n    ...rematerialization.author,\n    organizationId: projection.organizationId,\n  };\n  const sharedInput = {\n    author,\n    execSql: rematerialization.execSql,\n    knownContainerKeks: input.knownContainerKeks,\n    // Planning against a path this batch has yet to commit pins nothing; the\n    // acknowledgement advances every head at once. The rekey planner applies\n    // this rule itself; revoke and grant planning take it from here.\n    persistVerificationCheckpoints:\n      !isSpeculativeContainerWriterProjection(projection),\n    previousProjection: projection,\n    principalPolicyCache: input.principalPolicyCache,\n    resolveProjectionUserKey: input.resolveProjectionUserKey,\n    stillCurrent: rematerialization.stillCurrent,\n    targetSecretKey: rematerialization.targetSecretKey,\n    warmReferencedPrincipalPolicies:\n      rematerialization.warmReferencedPrincipalPolicies,\n  };\n  if (grantRow.containerId === rematerialization.revokedContainerId) {\n    if (!grant) {\n      throw new Error(\n        `Container ${grantRow.containerId} does not contain the revoked group grant`,\n      );\n    }\n    return buildMaterializedContainerRevokePlan({\n      ...sharedInput,\n      replacementPrincipalPolicy: rematerialization.nextPolicy,\n      revokedSubject: {\n        subjectId: rematerialization.groupId,\n        subjectType: \"group\",\n      },\n    });\n  }\n  if (!grant || grant.accessLevel !== nextGrant?.accessLevel) {\n    if (!nextGrant) {\n      throw new Error(\n        `Container ${grantRow.containerId} is absent from the next group grant set`,\n      );\n    }\n    return buildMaterializedContainerSharePlan({\n      ...sharedInput,\n      accessLevel: nextGrant.accessLevel,\n      recipient: {\n        principalPolicy: rematerialization.nextPolicy,\n        subjectId: rematerialization.groupId,\n        subjectType: \"group\",\n      },\n    });\n  }\n  if (referencedKeyEpoch === rematerialization.nextPolicy.keyEpoch) {\n    return buildMaterializedContainerSharePlan({\n      ...sharedInput,\n      accessLevel: grant.accessLevel,\n      recipient: {\n        principalPolicy: rematerialization.nextPolicy,\n        subjectId: rematerialization.groupId,\n        subjectType: \"group\",\n      },\n    });\n  }\n  return buildMaterializedContainerRekeyPlan({\n    ...sharedInput,\n    replacementPrincipalPolicy: rematerialization.nextPolicy,\n  });\n}\n\n/**\n * Plan one target against the paths already planned above it. A grant's\n * rematerialization extends the served head; a rotation's, and every carried\n * rekey, extends the epoch the batch mints above it.\n */\nasync function planRematerializationTarget(\n  batch: BatchPlanning,\n  target: RematerializationTarget,\n): Promise<void> {\n  const { rematerialization } = batch;\n  let rebased = rebaseOnDeepestAncestor(target.projection, batch.rotatedAbove);\n  const stale = rebased\n    ? staleLevelsAbove(\n        rebased.projection,\n        rebased.ancestor.containerKeks.at(-1)?.containerId ?? \"\",\n      )\n    : [];\n  for (const containerId of stale) {\n    await carryLevel(\n      batch,\n      await loadServedProjection(rematerialization.apiClient, containerId),\n    );\n  }\n  if (!target.grantRow) {\n    await carryLevel(batch, target.projection);\n    return;\n  }\n  // Each level carried above re-roots the target one step deeper.\n  if (stale.length > 0) {\n    rebased = rebaseOnDeepestAncestor(target.projection, batch.rotatedAbove);\n  }\n  const previousProjection = rebased?.projection ?? target.projection;\n  const planned = await buildPrincipalContainerRematerializationPlan({\n    grantRow: target.grantRow,\n    knownContainerKeks: batch.knownContainerKeks,\n    principalPolicyCache: batch.principalPolicyCache,\n    projection: previousProjection,\n    rematerialization,\n    resolveProjectionUserKey: batch.resolveProjectionUserKey,\n  });\n  const nextProjection =\n    \"keyring\" in planned.plan\n      ? await containerWriterProjectionFromRotationPlan({\n          plan: planned.plan,\n          previousProjection,\n        })\n      : await containerWriterProjectionFromSharePlan({\n          plan: planned.plan,\n          previousProjection,\n        });\n  addPlan(batch, {\n    carried: false,\n    planned,\n    rotated: \"keyring\" in planned.plan ? nextProjection : null,\n    nextProjection,\n  });\n}\n\n/**\n * Sign the batch parent-first. `carriedContainerIds` are the descendant rekeys\n * a refused attempt was told to carry; woven in by depth, each sits under the\n * rotation it rides, and a named container the batch rematerializes anyway is\n * re-planned there rather than rotated twice.\n */\nasync function buildPrincipalContainerRematerializationPlans(\n  input: PrincipalContainerRematerializationInput,\n  carriedContainerIds: readonly string[] = [],\n): Promise<{\n  entries: PlannedRematerialization[];\n  retiredContainerIds: readonly string[];\n  preceding: PrincipalRematerializationPredecessor;\n}> {\n  input = withPrecedingRematerialization(input);\n  if (\n    input.revokedContainerId &&\n    !input.grants.some(\n      (grant) => grant.containerId === input.revokedContainerId,\n    )\n  ) {\n    throw new Error(\"Revoked container is not granted to the group\");\n  }\n  const { targets, retiredContainerIds } = await loadRematerializationTargets({\n    apiClient: input.apiClient,\n    carriedContainerIds,\n    grants: input.grants,\n  });\n  const batch: BatchPlanning = {\n    knownContainerKeks: new Map(input.preceding?.knownContainerKeks),\n    plans: [],\n    // A rotation planned above cites the group at the head this batch commits,\n    // which no store holds yet; the cache is what lets a rebased path verify.\n    principalPolicyCache: new Map([\n      ...(input.preceding?.policies ?? []).flatMap((policy) => [\n        ...seededPrincipalPolicyCache(policy),\n      ]),\n      ...seededPrincipalPolicyCache(input.nextPolicy),\n    ]),\n    rematerialization: input,\n    resolveProjectionUserKey: createProjectionUserKeyResolver({\n      resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,\n    }),\n    rotatedAbove: [],\n  };\n  for (const target of targets) {\n    await planRematerializationTarget(batch, target);\n  }\n  return {\n    entries: batch.plans,\n    retiredContainerIds,\n    preceding: {\n      policies: [...(input.preceding?.policies ?? []), input.nextPolicy],\n      projections: [\n        ...(input.preceding?.projections ?? []),\n        ...batch.plans.flatMap((entry) =>\n          entry.nextProjection ? [entry.nextProjection] : [],\n        ),\n      ],\n      knownContainerKeks: batch.knownContainerKeks,\n    },\n  };\n}\n\n/**\n * The server names a level it found pinned to a retired epoch. A batch answers\n * with a rotation of it: a carried rekey, or its own rematerialization when\n * that is a rekey or revoke. A rematerialized grant rotates nothing, so a\n * batch that both grants a container and must re-key it cannot be signed;\n * no policy change the SDK builds combines the two.\n */\nfunction assertNamedContainersRotated(\n  plans: readonly PlannedRematerialization[],\n  requiredContainerIds: readonly string[],\n): void {\n  const rotatedIds = new Set(\n    plans.flatMap((entry) =>\n      entry.rotated ? [entry.planned.plan.containerId] : [],\n    ),\n  );\n  const unrotated = requiredContainerIds\n    .slice(0, MAX_ROTATION_CONTAINER_REKEYS)\n    .find((containerId) => !rotatedIds.has(containerId));\n  if (unrotated !== undefined) {\n    throw new Error(\n      `Container ${unrotated} needs a rekey this policy change only grants`,\n    );\n  }\n}\n\nexport async function preparePrincipalContainerRematerializationBatch(\n  input: PrincipalContainerRematerializationInput,\n): Promise<PreparedPrincipalContainerRematerializationBatch> {\n  let { entries, retiredContainerIds, preceding } =\n    await buildPrincipalContainerRematerializationPlans(input);\n  const requests = () => entries.map((entry) => entry.planned.plan.request);\n  return {\n    get preceding() {\n      return preceding;\n    },\n    get retiredContainerIds() {\n      return retiredContainerIds;\n    },\n    get plans() {\n      return entries.map((entry) => entry.planned);\n    },\n    get requests() {\n      return requests();\n    },\n    carry: async (requiredContainerIds) => {\n      // The refused attempt rolled back whole, so every served head still\n      // stands; the batch is signed again from them with the named levels in.\n      const replanned = await buildPrincipalContainerRematerializationPlans(\n        input,\n        requiredContainerIds,\n      );\n      assertNamedContainersRotated(replanned.entries, requiredContainerIds);\n      entries = replanned.entries;\n      retiredContainerIds = replanned.retiredContainerIds;\n      preceding = replanned.preceding;\n      return requests();\n    },\n    acknowledge: async (responses, stillCurrent) => {\n      const isCurrent = () =>\n        input.stillCurrent?.() !== false && stillCurrent?.() !== false;\n      const heads = entries.map((entry) => authoredMutationHead(entry.planned));\n      const acknowledged = await acknowledgeContainerMutationBatch({\n        execSql: input.execSql,\n        plans: heads,\n        responses,\n        stillCurrent: isCurrent,\n      });\n      if (!acknowledged || !isCurrent()) return;\n      const plansByOrganization = new Map<\n        string,\n        AuthoredContainerMutationHead[]\n      >();\n      for (const head of heads) {\n        const organizationId = head.state.organizationId;\n        const group = plansByOrganization.get(organizationId) ?? [];\n        group.push(head);\n        plansByOrganization.set(organizationId, group);\n      }\n      for (const [organizationId, organizationPlans] of plansByOrganization) {\n        try {\n          rememberVerifiedContainerHeads({\n            organizationId,\n            execSql: input.execSql,\n            heads: [],\n            policies: [input.nextPolicy],\n          });\n        } catch {\n          // Cache failure must not invalidate the durably acknowledged batch.\n          continue;\n        }\n        scheduleHeldDescendantRecitations({\n          apiClient: input.apiClient,\n          author: { ...input.author, organizationId },\n          execSql: input.execSql,\n          plans: organizationPlans,\n          stillCurrent: input.recitationStillCurrent ?? isCurrent,\n          reportSecurityIncident: input.reportSecurityIncident,\n        });\n      }\n    },\n  };\n}\n"]}

package/workflows/organizations/rematerialization/principalContainerRematerializationPlanning.js

@@ -0,0 +1,77 @@
+import { MAX_ROTATION_CONTAINER_REKEYS } from "../../../internal/validators/util/index.js";
+import { planCarriedDescendantRekey, } from "../../containers/child/rekey/carriedDescendantRekeys.js";
+/** How many rekeys the batch carries beyond its rematerializations. */
+function carriedCount(batch) {
+    return batch.plans.filter((entry) => entry.carried).length;
+}
+/**
+ * Sign a rekey of `served` under the batch's rotations above it, and add it.
+ * The server accepts at most `MAX_ROTATION_CONTAINER_REKEYS` carried entries;
+ * past that a rematerialization below them could not be signed on a current
+ * path, so the batch is refused here, before signing what the server would
+ * refuse anyway, and the policy change has to wait for a lazy repair of the
+ * tree. Groups granted that far apart on one chain are not a shape the SDK
+ * creates.
+ */
+export async function carryLevel(batch, served) {
+    const { rematerialization } = batch;
+    if (carriedCount(batch) >= MAX_ROTATION_CONTAINER_REKEYS) {
+        throw new Error(`Policy change would carry more than ${MAX_ROTATION_CONTAINER_REKEYS} descendant rekeys`);
+    }
+    const planned = await planCarriedDescendantRekey({
+        apiClient: rematerialization.apiClient,
+        author: rematerialization.author,
+        execSql: rematerialization.execSql,
+        knownContainerKeks: batch.knownContainerKeks,
+        principalPolicyCache: batch.principalPolicyCache,
+        // Its path cites the policy this batch commits, so like every
+        // rematerialized rotation it must cite the successor.
+        replacementPrincipalPolicy: rematerialization.nextPolicy,
+        resolveAuthoredPolicyReferences: rematerialization.resolveAuthoredPolicyReferences,
+        resolveProjectionUserKey: batch.resolveProjectionUserKey,
+        rotated: batch.rotatedAbove,
+        served,
+        stillCurrent: rematerialization.stillCurrent,
+        targetSecretKey: rematerialization.targetSecretKey,
+        warmReferencedPrincipalPolicies: rematerialization.warmReferencedPrincipalPolicies,
+    });
+    addPlan(batch, {
+        carried: true,
+        planned,
+        rotated: planned.writerProjection,
+        nextProjection: planned.writerProjection,
+    });
+}
+export function addPlan(batch, entry) {
+    batch.plans.push(entry);
+    if (!entry.rotated)
+        return;
+    batch.rotatedAbove.push(entry.rotated);
+    const minted = entry.rotated.containerKeks.at(-1)?.containerKeyEpochId;
+    if (minted)
+        batch.knownContainerKeks.set(minted, entry.planned.containerKey);
+}
+/**
+ * Levels of a re-rooted path pinned to an epoch the batch retires above them:
+ * those strictly between the rotated ancestor the path was re-rooted on and
+ * the target, parent-first, from the first stale one down. A rotation planned
+ * above a target strands every level between the two, and each must be
+ * re-keyed under the one above before the target can be signed. The batch
+ * carries them without waiting to be told: they are proper ancestors of a
+ * granted container, so the server would name them, and a refusal per level
+ * is a round trip each. Anything stale above the rotated ancestor is not this
+ * batch's doing and is left alone. `carryLevel` holds the count to the cap.
+ */
+export function staleLevelsAbove(projection, rotatedAncestorId) {
+    const keks = projection.containerKeks;
+    const ancestor = keks.findIndex((kek) => kek.containerId === rotatedAncestorId);
+    if (ancestor < 0)
+        return [];
+    const between = keks.slice(ancestor, -1);
+    const firstStale = between.findIndex((kek, index) => index > 0 &&
+        kek.parentContainerKeyEpochId !== between[index - 1]?.containerKeyEpochId);
+    return firstStale < 0
+        ? []
+        : between.slice(firstStale).map((kek) => kek.containerId);
+}
+//# sourceMappingURL=principalContainerRematerializationPlanning.js.map

package/workflows/organizations/rematerialization/principalContainerRematerializationPlanning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalContainerRematerializationPlanning.js","sourceRoot":"","sources":["principalContainerRematerializationPlanning.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ApiClient } from \"@tearleads/api-client\";\nimport type { PrincipalContainerGrant } from \"@tearleads/crypto\";\nimport type { ContainerWriterProjectionResponse } from \"@tearleads/validators/response\";\nimport { MAX_ROTATION_CONTAINER_REKEYS } from \"@tearleads/validators/util\";\nimport type { ContainerReciteApi } from \"../../../data/containers/shared/reciteApi\";\nimport type { ContainerMutationAuthor } from \"../../../data/containers/shared/types\";\nimport type {\n  PrincipalPolicyCache,\n  ReferencedPrincipalPolicyWarmer,\n} from \"../../../data/keyingProjectionVerification\";\nimport type { ResolvedPrincipalPolicyEvidence } from \"../../../data/keyingProjectionVerification/types\";\nimport type { createProjectionUserKeyResolver } from \"../../../data/keyingProjectionVerification/userKeyResolver\";\nimport type { CurrentPolicyReferenceResolver } from \"../../../data/principals/currentPolicyReferenceResolver\";\nimport type { PrincipalPolicyCurrentEvidence } from \"../../../data/principals/principalPolicyEvidence\";\nimport type { SecurityIncidentReporter } from \"../../../data/shared/securityIncidents\";\nimport type { ExecSql } from \"../../../data/sqlite/sqlSchema\";\nimport type { TrustedUserIdentityResolver } from \"../../../data/trustedUserIdentity\";\nimport {\n  planCarriedDescendantRekey,\n  type SpeculativePath,\n} from \"../../containers/child/rekey/carriedDescendantRekeys\";\nimport type { PlannedRematerialization } from \"./principalContainerRematerializationTargets\";\n\nexport interface RematerializationApi\n  extends ContainerReciteApi,\n    Pick<ApiClient, \"getContainerWriterProjectionResult\"> {\n  getContainerWriterProjection(\n    containerId: string,\n  ): Promise<ContainerWriterProjectionResponse | null>;\n}\n\nexport interface PrincipalRematerializationPredecessor {\n  readonly authored?: readonly ResolvedPrincipalPolicyEvidence[] | undefined;\n  readonly policies: readonly PrincipalPolicyCurrentEvidence[];\n  readonly projections: readonly ContainerWriterProjectionResponse[];\n  readonly knownContainerKeks: ReadonlyMap<string, Uint8Array>;\n}\n\nexport interface PrincipalContainerRematerializationInput {\n  readonly preceding?: PrincipalRematerializationPredecessor | undefined;\n  readonly reportSecurityIncident: SecurityIncidentReporter;\n  readonly apiClient: RematerializationApi;\n  readonly author: ContainerMutationAuthor;\n  readonly execSql: ExecSql;\n  readonly grants: readonly PrincipalContainerGrant[];\n  readonly groupId: string;\n  readonly nextPolicy: PrincipalPolicyCurrentEvidence;\n  readonly resolveAuthoredPolicyReferences?:\n    | CurrentPolicyReferenceResolver\n    | undefined;\n  readonly revokedContainerId?: string | undefined;\n  readonly resolveTrustedUserIdentity: TrustedUserIdentityResolver;\n  readonly stillCurrent?: (() => boolean) | undefined;\n  /** Session lifetime for best-effort work after durable acknowledgement. */\n  readonly recitationStillCurrent?: (() => boolean) | undefined;\n  readonly targetSecretKey: Uint8Array;\n  readonly warmReferencedPrincipalPolicies?:\n    | ReferencedPrincipalPolicyWarmer\n    | undefined;\n}\n\n/** What the batch has signed so far, in the order it will be submitted. */\nexport interface BatchPlanning {\n  /**\n   * Keys the batch minted, by epoch id. A rotation wraps its successor to the\n   * group at the head this batch commits, which no store can open yet; a\n   * level planned beneath it opens that epoch with the key minted here, and\n   * its keyring then opens the retired epoch the level below is pinned to.\n   */\n  readonly knownContainerKeks: Map<string, Uint8Array>;\n  readonly plans: PlannedRematerialization[];\n  readonly principalPolicyCache: PrincipalPolicyCache;\n  readonly rematerialization: PrincipalContainerRematerializationInput;\n  readonly resolveProjectionUserKey: ReturnType<\n    typeof createProjectionUserKeyResolver\n  >;\n  readonly rotatedAbove: SpeculativePath[];\n}\n\n/** How many rekeys the batch carries beyond its rematerializations. */\nfunction carriedCount(batch: BatchPlanning): number {\n  return batch.plans.filter((entry) => entry.carried).length;\n}\n\n/**\n * Sign a rekey of `served` under the batch's rotations above it, and add it.\n * The server accepts at most `MAX_ROTATION_CONTAINER_REKEYS` carried entries;\n * past that a rematerialization below them could not be signed on a current\n * path, so the batch is refused here, before signing what the server would\n * refuse anyway, and the policy change has to wait for a lazy repair of the\n * tree. Groups granted that far apart on one chain are not a shape the SDK\n * creates.\n */\nexport async function carryLevel(\n  batch: BatchPlanning,\n  served: ContainerWriterProjectionResponse,\n): Promise<void> {\n  const { rematerialization } = batch;\n  if (carriedCount(batch) >= MAX_ROTATION_CONTAINER_REKEYS) {\n    throw new Error(\n      `Policy change would carry more than ${MAX_ROTATION_CONTAINER_REKEYS} descendant rekeys`,\n    );\n  }\n  const planned = await planCarriedDescendantRekey({\n    apiClient: rematerialization.apiClient,\n    author: rematerialization.author,\n    execSql: rematerialization.execSql,\n    knownContainerKeks: batch.knownContainerKeks,\n    principalPolicyCache: batch.principalPolicyCache,\n    // Its path cites the policy this batch commits, so like every\n    // rematerialized rotation it must cite the successor.\n    replacementPrincipalPolicy: rematerialization.nextPolicy,\n    resolveAuthoredPolicyReferences:\n      rematerialization.resolveAuthoredPolicyReferences,\n    resolveProjectionUserKey: batch.resolveProjectionUserKey,\n    rotated: batch.rotatedAbove,\n    served,\n    stillCurrent: rematerialization.stillCurrent,\n    targetSecretKey: rematerialization.targetSecretKey,\n    warmReferencedPrincipalPolicies:\n      rematerialization.warmReferencedPrincipalPolicies,\n  });\n  addPlan(batch, {\n    carried: true,\n    planned,\n    rotated: planned.writerProjection,\n    nextProjection: planned.writerProjection,\n  });\n}\n\nexport function addPlan(\n  batch: BatchPlanning,\n  entry: PlannedRematerialization,\n): void {\n  batch.plans.push(entry);\n  if (!entry.rotated) return;\n  batch.rotatedAbove.push(entry.rotated);\n  const minted = entry.rotated.containerKeks.at(-1)?.containerKeyEpochId;\n  if (minted) batch.knownContainerKeks.set(minted, entry.planned.containerKey);\n}\n\n/**\n * Levels of a re-rooted path pinned to an epoch the batch retires above them:\n * those strictly between the rotated ancestor the path was re-rooted on and\n * the target, parent-first, from the first stale one down. A rotation planned\n * above a target strands every level between the two, and each must be\n * re-keyed under the one above before the target can be signed. The batch\n * carries them without waiting to be told: they are proper ancestors of a\n * granted container, so the server would name them, and a refusal per level\n * is a round trip each. Anything stale above the rotated ancestor is not this\n * batch's doing and is left alone. `carryLevel` holds the count to the cap.\n */\nexport function staleLevelsAbove(\n  projection: ContainerWriterProjectionResponse,\n  rotatedAncestorId: string,\n): string[] {\n  const keks = projection.containerKeks;\n  const ancestor = keks.findIndex(\n    (kek) => kek.containerId === rotatedAncestorId,\n  );\n  if (ancestor < 0) return [];\n  const between = keks.slice(ancestor, -1);\n  const firstStale = between.findIndex(\n    (kek, index) =>\n      index > 0 &&\n      kek.parentContainerKeyEpochId !== between[index - 1]?.containerKeyEpochId,\n  );\n  return firstStale < 0\n    ? []\n    : between.slice(firstStale).map((kek) => kek.containerId);\n}\n"]}

package/workflows/organizations/rematerialization/principalContainerRematerializationTargets.js

@@ -0,0 +1,79 @@
+import { MAX_ROTATION_CONTAINER_REKEYS } from "../../../internal/validators/util/index.js";
+import { isContainerNotFoundFailure } from "../../../data/containers/shared/mutationFailures.js";
+import { referencedPrincipalPolicyKey } from "../../../data/keyingProjectionVerification/principalPolicy/principalPolicyCache.js";
+/**
+ * Order a batch parent-first, by served depth. A group granted on a container
+ * and on one of its descendants rotates both, and the lower rotation must be
+ * signed against the epoch the upper one mints in this same batch, or it
+ * extends a head the batch itself retires. A carried rekey sits below the
+ * rotation it rides for the same reason. Ties keep id order for stability.
+ */
+export function orderRematerializationsParentFirst(batch) {
+    return [...batch].sort((left, right) => left.projection.path.length - right.projection.path.length ||
+        left.projection.containerId.localeCompare(right.projection.containerId));
+}
+/** The served projection of a container the batch will sign for. */
+export async function loadServedProjection(apiClient, containerId) {
+    const projection = await apiClient.getContainerWriterProjection(containerId);
+    if (!projection) {
+        throw new Error(`Container ${containerId} could not be prepared for principal rotation`);
+    }
+    if (projection.containerId !== containerId) {
+        throw new Error("Served projection describes another container");
+    }
+    return projection;
+}
+/**
+ * Fetch what the batch signs for, parent-first. A named descendant the batch
+ * already rematerializes is not fetched twice: its own rotation is re-planned
+ * under whatever the batch carries above it. Names are a hint from the server,
+ * never an authority; each is verified where it is planned.
+ */
+export async function loadRematerializationTargets(input) {
+    const grantByContainerId = new Map(input.grants.map((grant) => [grant.containerId, grant]));
+    const carried = [...new Set(input.carriedContainerIds)]
+        .filter((containerId) => !grantByContainerId.has(containerId))
+        .slice(0, MAX_ROTATION_CONTAINER_REKEYS);
+    const targets = [];
+    const retiredContainerIds = [];
+    for (const containerId of [...grantByContainerId.keys(), ...carried].sort((left, right) => left.localeCompare(right))) {
+        const grantRow = grantByContainerId.get(containerId) ?? null;
+        const result = await input.apiClient.getContainerWriterProjectionResult(containerId, { reportErrors: false });
+        if (!result.ok) {
+            // This is only a planning hint. Keep the signed grant intact; the API
+            // independently requires every live grant under the organization lock.
+            if (grantRow &&
+                result.kind === "http" &&
+                isContainerNotFoundFailure(result)) {
+                retiredContainerIds.push(containerId);
+                continue;
+            }
+            result.report();
+            throw new Error(`Container ${containerId} could not be prepared for principal rotation: ${result.message}`);
+        }
+        if (result.data.containerId !== containerId)
+            throw new Error("Served projection describes another container");
+        targets.push({ grantRow, projection: result.data });
+    }
+    return {
+        targets: orderRematerializationsParentFirst(targets),
+        retiredContainerIds,
+    };
+}
+/** An in-memory cache holding only the policy this batch is about to commit. */
+export function seededPrincipalPolicyCache(nextPolicy) {
+    return new Map([
+        [
+            referencedPrincipalPolicyKey({
+                keyEpoch: nextPolicy.keyEpoch,
+                keyFingerprint: nextPolicy.state.keyFingerprint,
+                principalId: nextPolicy.principalId,
+                principalType: nextPolicy.principalType,
+                stateHash: nextPolicy.stateHash,
+                version: nextPolicy.version,
+            }),
+            nextPolicy,
+        ],
+    ]);
+}
+//# sourceMappingURL=principalContainerRematerializationTargets.js.map

package/workflows/organizations/rematerialization/principalContainerRematerializationTargets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalContainerRematerializationTargets.js","sourceRoot":"","sources":["principalContainerRematerializationTargets.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ApiClient } from \"@tearleads/api-client\";\nimport type { PrincipalContainerGrant } from \"@tearleads/crypto\";\nimport type { ContainerWriterProjectionResponse } from \"@tearleads/validators/response\";\nimport { MAX_ROTATION_CONTAINER_REKEYS } from \"@tearleads/validators/util\";\nimport { isContainerNotFoundFailure } from \"../../../data/containers/shared/mutationFailures\";\nimport type {\n  MaterializedContainerRekeyPlan,\n  MaterializedContainerRevokePlan,\n  MaterializedContainerSharePlan,\n} from \"../../../data/containers/shared/types\";\nimport type { PrincipalPolicyCache } from \"../../../data/keyingProjectionVerification\";\nimport { referencedPrincipalPolicyKey } from \"../../../data/keyingProjectionVerification/principalPolicy/principalPolicyCache\";\nimport type { PrincipalPolicyCurrentEvidence } from \"../../../data/principals/principalPolicyEvidence\";\nimport type { SpeculativePath } from \"../../containers/child/rekey/carriedDescendantRekeys\";\n\nexport type MaterializedPrincipalContainerMutationPlan =\n  | MaterializedContainerRekeyPlan\n  | MaterializedContainerRevokePlan\n  | MaterializedContainerSharePlan;\n\n/** Authored paths for chaining plans; only rotated is null for a grant. */\nexport interface PlannedRematerialization {\n  /** The authored successor for either a grant or a rotation. */\n  readonly nextProjection?: ContainerWriterProjectionResponse | undefined;\n  /** A descendant rekey carried for a rotation above, not a rematerialization. */\n  readonly carried: boolean;\n  readonly planned: MaterializedPrincipalContainerMutationPlan;\n  readonly rotated: SpeculativePath | null;\n}\n\n/**\n * One container a batch signs for: a group grant it rematerializes, or a\n * descendant rekey it carries for a rotation above (`grantRow` null).\n */\nexport interface RematerializationTarget {\n  readonly grantRow: PrincipalContainerGrant | null;\n  readonly projection: ContainerWriterProjectionResponse;\n}\n\n/**\n * Order a batch parent-first, by served depth. A group granted on a container\n * and on one of its descendants rotates both, and the lower rotation must be\n * signed against the epoch the upper one mints in this same batch, or it\n * extends a head the batch itself retires. A carried rekey sits below the\n * rotation it rides for the same reason. Ties keep id order for stability.\n */\nexport function orderRematerializationsParentFirst<\n  T extends {\n    readonly projection: {\n      readonly containerId: string;\n      readonly path: readonly unknown[];\n    };\n  },\n>(batch: readonly T[]): T[] {\n  return [...batch].sort(\n    (left, right) =>\n      left.projection.path.length - right.projection.path.length ||\n      left.projection.containerId.localeCompare(right.projection.containerId),\n  );\n}\n\ninterface ProjectionApi {\n  getContainerWriterProjection(\n    containerId: string,\n  ): Promise<ContainerWriterProjectionResponse | null>;\n}\n\n/** The served projection of a container the batch will sign for. */\nexport async function loadServedProjection(\n  apiClient: ProjectionApi,\n  containerId: string,\n): Promise<ContainerWriterProjectionResponse> {\n  const projection = await apiClient.getContainerWriterProjection(containerId);\n  if (!projection) {\n    throw new Error(\n      `Container ${containerId} could not be prepared for principal rotation`,\n    );\n  }\n  if (projection.containerId !== containerId) {\n    throw new Error(\"Served projection describes another container\");\n  }\n  return projection;\n}\n\n/**\n * Fetch what the batch signs for, parent-first. A named descendant the batch\n * already rematerializes is not fetched twice: its own rotation is re-planned\n * under whatever the batch carries above it. Names are a hint from the server,\n * never an authority; each is verified where it is planned.\n */\nexport async function loadRematerializationTargets(input: {\n  readonly apiClient: Pick<ApiClient, \"getContainerWriterProjectionResult\">;\n  readonly carriedContainerIds: readonly string[];\n  readonly grants: readonly PrincipalContainerGrant[];\n}): Promise<{\n  targets: RematerializationTarget[];\n  retiredContainerIds: string[];\n}> {\n  const grantByContainerId = new Map(\n    input.grants.map((grant) => [grant.containerId, grant] as const),\n  );\n  const carried = [...new Set(input.carriedContainerIds)]\n    .filter((containerId) => !grantByContainerId.has(containerId))\n    .slice(0, MAX_ROTATION_CONTAINER_REKEYS);\n  const targets: RematerializationTarget[] = [];\n  const retiredContainerIds: string[] = [];\n  for (const containerId of [...grantByContainerId.keys(), ...carried].sort(\n    (left, right) => left.localeCompare(right),\n  )) {\n    const grantRow = grantByContainerId.get(containerId) ?? null;\n    const result = await input.apiClient.getContainerWriterProjectionResult(\n      containerId,\n      { reportErrors: false },\n    );\n    if (!result.ok) {\n      // This is only a planning hint. Keep the signed grant intact; the API\n      // independently requires every live grant under the organization lock.\n      if (\n        grantRow &&\n        result.kind === \"http\" &&\n        isContainerNotFoundFailure(result)\n      ) {\n        retiredContainerIds.push(containerId);\n        continue;\n      }\n      result.report();\n      throw new Error(\n        `Container ${containerId} could not be prepared for principal rotation: ${result.message}`,\n      );\n    }\n    if (result.data.containerId !== containerId)\n      throw new Error(\"Served projection describes another container\");\n    targets.push({ grantRow, projection: result.data });\n  }\n  return {\n    targets: orderRematerializationsParentFirst(targets),\n    retiredContainerIds,\n  };\n}\n\n/** An in-memory cache holding only the policy this batch is about to commit. */\nexport function seededPrincipalPolicyCache(\n  nextPolicy: PrincipalPolicyCurrentEvidence,\n): PrincipalPolicyCache {\n  return new Map([\n    [\n      referencedPrincipalPolicyKey({\n        keyEpoch: nextPolicy.keyEpoch,\n        keyFingerprint: nextPolicy.state.keyFingerprint,\n        principalId: nextPolicy.principalId,\n        principalType: nextPolicy.principalType,\n        stateHash: nextPolicy.stateHash,\n        version: nextPolicy.version,\n      }),\n      nextPolicy,\n    ],\n  ]);\n}\n"]}

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

@@ -0,0 +1,33 @@
+import { type VerifiedPrincipalPolicyCurrent } from "../../../internal/crypto/index.js";
+import type { PutPrincipalPolicyRequest } from "../../../internal/validators/request/index.js";
+import type { PrincipalPolicyMutationResponse } from "../../../internal/validators/response/index.js";
+import { type AcknowledgedPrincipalCurrentRetirement } from "../../../data/persistence/principalCurrentAcknowledgementPersistence.js";
+import type { ExecSql } from "../../../data/sqlite/sqlSchema.js";
+import type { RecoverPrincipalPolicyHistoryOptions } from "../historyRecovery/principalHistoryRecoveryTypes.js";
+import { type AcknowledgedPrincipalPredecessor } from "./acknowledgedPrincipalPredecessor.js";
+import type { PrincipalAcknowledgementChecks } from "./principalAcknowledgementChecks.js";
+export interface AcknowledgedPrincipalCurrentInput {
+    /** Capture before submitting the mutation; null only for a new group. */
+    readonly predecessor: AcknowledgedPrincipalPredecessor | null;
+    /** Only a newly authored group at version one; never skips a predecessor. */
+    readonly initialGroup?: boolean | undefined;
+    /** The same scoped protection and verification mode used to recover the predecessor. */
+    readonly recovery: Omit<RecoverPrincipalPolicyHistoryOptions, "execSql" | "organizationId" | "stillCurrent">;
+    readonly request: PutPrincipalPolicyRequest;
+    readonly response: PrincipalPolicyMutationResponse;
+}
+/** The acknowledged currents of one mutation, recorded together. */
+export interface AcknowledgedPrincipalCurrentBatch {
+    readonly execSql: ExecSql;
+    readonly organizationId: string;
+    readonly entries: readonly AcknowledgedPrincipalCurrentInput[];
+    readonly retirements?: readonly AcknowledgedPrincipalCurrentRetirement[] | undefined;
+    readonly stillCurrent: () => boolean;
+}
+/**
+ * Extend authenticated local progress and retain exact acknowledged artifacts
+ * atomically with pins, once `checks` accept each acknowledgement.
+ */
+export declare function recordAcknowledgedPrincipalCurrents(input: AcknowledgedPrincipalCurrentBatch & {
+    readonly checks: PrincipalAcknowledgementChecks;
+}): Promise<VerifiedPrincipalPolicyCurrent[]>;