@tearleads/client-sdk 0.0.0-stage → 0.1.13

package/workflows/containers/child/moveWraps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moveWraps.js","sourceRoot":"","sources":["moveWraps.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,uBAAuB,EAAE,MAAM,mDAAmD,CAAC;AAC5F,OAAO,EAAE,kBAAkB,EAAE,MAAM,4CAA4C,CAAC;AAChF,OAAO,EAAE,6BAA6B,EAAE,MAAM,qDAAqD,CAAC;AACpG,OAAO,EACL,iDAAiD,GAGlD,MAAM,4CAA4C,CAAC;AAGpD,OAAO,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AAE9D,MAAM,CAAC,KAAK,UAAU,qCAAqC,CAAC,KAO3D;IACC,MAAM,CAAC,cAAc,EAAE,yBAAyB,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACpE,iDAAiD,CAAC;YAChD,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,UAAU,EAAE,KAAK,CAAC,kBAAkB;YACpC,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,+BAA+B,EAAE,KAAK,CAAC,+BAA+B;SACvE,CAAC;QACF,iDAAiD,CAAC;YAChD,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,UAAU,EAAE,KAAK,CAAC,2BAA2B;YAC7C,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,+BAA+B,EAAE,KAAK,CAAC,+BAA+B;SACvE,CAAC;KACH,CAAC,CAAC;IACH,OAAO,uBAAuB,CAAC;QAC7B,GAAG,cAAc;QACjB,GAAG,yBAAyB;KAC7B,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,KAa7C;IACC,6BAA6B,CAC3B,KAAK,CAAC,2BAA2B,CAAC,aAAa,CAChD,CAAC;IACF,MAAM,iBAAiB,GAAG,KAAK,CAAC,iBAAiB,CAAC;IAClD,MAAM,cAAc,GAAG,KAAK,CAAC,2BAA2B,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACrE,IAAI,CAAC,cAAc;QACjB,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,OAAO;QACL,iBAAiB;QACjB,GAAG,CAAC,MAAM,2BAA2B,CAAC;YACpC,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,mBAAmB,EAAE,KAAK,CAAC,mBAAmB;YAC9C,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,cAAc,EAAE,gBAAgB;YAChC,SAAS,EAAE,KAAK,CAAC,oBAAoB;YACrC,eAAe,EAAE,kBAAkB,CAAC,cAAc,CAAC,CAAC,qBAAqB;YACzE,iBAAiB;YACjB,cAAc,EAAE,KAAK,CAAC,wBAAwB;YAC9C,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC","sourcesContent":["import type { ContainerAccessManifestState } from \"@tearleads/crypto\";\nimport type {\n  ContainerKekResponse,\n  ContainerWriterProjectionResponse,\n} from \"@tearleads/validators/response\";\nimport { uniquePrincipalPolicies } from \"../../../data/containers/shared/principalPolicies\";\nimport { readContainerState } from \"../../../data/containers/shared/projection\";\nimport { assertContainerKekPathCurrent } from \"../../../data/documents/shared/containerKekCurrency\";\nimport {\n  collectContainerWriterProjectionPrincipalPolicies,\n  type ProjectionUserKeyResolver,\n  type ReferencedPrincipalPolicyWarmer,\n} from \"../../../data/keyingProjectionVerification\";\nimport type { PrincipalPolicyCurrentEvidence } from \"../../../data/principals/principalPolicyEvidence\";\nimport type { ExecSql } from \"../../../data/sqlite/sqlSchema\";\nimport { buildContainerRotationWraps } from \"./rotationWraps\";\n\nexport async function collectContainerMovePrincipalPolicies(input: {\n  destinationParentProjection: ContainerWriterProjectionResponse;\n  execSql: ExecSql;\n  previousProjection: ContainerWriterProjectionResponse;\n  resolveUserKey: ProjectionUserKeyResolver;\n  stillCurrent?: (() => boolean) | undefined;\n  warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;\n}): Promise<PrincipalPolicyCurrentEvidence[]> {\n  const [sourcePolicies, destinationParentPolicies] = await Promise.all([\n    collectContainerWriterProjectionPrincipalPolicies({\n      execSql: input.execSql,\n      projection: input.previousProjection,\n      resolveUserKey: input.resolveUserKey,\n      stillCurrent: input.stillCurrent,\n      warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,\n    }),\n    collectContainerWriterProjectionPrincipalPolicies({\n      execSql: input.execSql,\n      projection: input.destinationParentProjection,\n      resolveUserKey: input.resolveUserKey,\n      stillCurrent: input.stillCurrent,\n      warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,\n    }),\n  ]);\n  return uniquePrincipalPolicies([\n    ...sourcePolicies,\n    ...destinationParentPolicies,\n  ]);\n}\n\nexport async function buildContainerMoveWraps(input: {\n  principalPolicies: readonly PrincipalPolicyCurrentEvidence[];\n  containerKey: Uint8Array;\n  containerKeyEpochId: string;\n  destinationParentKek: ContainerKekResponse;\n  destinationParentProjection: ContainerWriterProjectionResponse;\n  execSql: ExecSql;\n  manifestHash: string;\n  previousProjection: ContainerWriterProjectionResponse;\n  resolveProjectionUserKey: ProjectionUserKeyResolver;\n  state: ContainerAccessManifestState;\n  stillCurrent?: (() => boolean) | undefined;\n  warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;\n}) {\n  assertContainerKekPathCurrent(\n    input.destinationParentProjection.containerKeks,\n  );\n  const principalPolicies = input.principalPolicies;\n  const parentManifest = input.destinationParentProjection.path.at(-1);\n  if (!parentManifest)\n    throw new Error(\"Container move destination parent is missing\");\n  return {\n    principalPolicies,\n    ...(await buildContainerRotationWraps({\n      containerKey: input.containerKey,\n      containerKeyEpochId: input.containerKeyEpochId,\n      manifestHash: input.manifestHash,\n      operationLabel: \"Container move\",\n      parentKek: input.destinationParentKek,\n      parentPublicKey: readContainerState(parentManifest).containerKeyPublicKey,\n      principalPolicies,\n      resolveUserKey: input.resolveProjectionUserKey,\n      state: input.state,\n    })),\n  };\n}\n"]}

package/workflows/containers/child/mutationRequestCore.js

@@ -0,0 +1,39 @@
+import { principalPolicyRequestRecord } from "../../../data/containers/shared/principalPolicies.js";
+import { asContainerManifestBundle } from "../../../data/containers/shared/projection.js";
+import { readCanonicalRecord, readCanonicalRecords, } from "../../../data/keyingCanonicalJson.js";
+export function readCanonicalRecordOrNull(value, label) {
+    return value === null || value === undefined
+        ? null
+        : readCanonicalRecord(value, label);
+}
+/**
+ * The previous-manifest identity every non-create mutation
+ * (share/rekey/revoke/move) sends alongside the core request fields.
+ */
+export function previousPathRequestFields(previousManifest, previousProjection) {
+    return {
+        previousManifest,
+        previousContainerPath: previousProjection.path.map(asContainerManifestBundle),
+    };
+}
+/**
+ * The eight ContainerMutationRequest fields every child-container mutation
+ * (create/share/rekey/revoke/move) assembles identically, labeled by
+ * operation. The identity fields — previous manifest/path, manifest history,
+ * predecessor bridge, keyring, and the parent KEK — genuinely differ per
+ * operation and stay with each builder.
+ */
+export function containerMutationRequestCore(operation, input) {
+    const label = `Container ${operation}`;
+    return {
+        event: readCanonicalRecord(input.event, `${label} event`),
+        body: readCanonicalRecord(input.body, `${label} body`),
+        expectedManifestHash: input.manifestHash,
+        manifest: readCanonicalRecord(input.manifest, `${label} manifest`),
+        principalPolicies: readCanonicalRecords(input.principalPolicies.map((policy) => principalPolicyRequestRecord(policy)), `${label} principal policies`),
+        keyEpoch: readCanonicalRecord(input.keyEpoch, `${label} key epoch`),
+        wraps: readCanonicalRecords(input.wraps, `${label} wraps`),
+        userRecipientKeys: readCanonicalRecords(input.userRecipientKeys, `${label} user recipient keys`),
+    };
+}
+//# sourceMappingURL=mutationRequestCore.js.map

package/workflows/containers/child/mutationRequestCore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutationRequestCore.js","sourceRoot":"","sources":["mutationRequestCore.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,4BAA4B,EAAE,MAAM,mDAAmD,CAAC;AACjG,OAAO,EAAE,yBAAyB,EAAE,MAAM,4CAA4C,CAAC;AACvF,OAAO,EACL,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,mCAAmC,CAAC;AAG3C,MAAM,UAAU,yBAAyB,CACvC,KAAc,EACd,KAAa;IAEb,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAC1C,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,mBAAmB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,gBAA0C,EAC1C,kBAAqD;IAKrD,OAAO;QACL,gBAAgB;QAChB,qBAAqB,EAAE,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAChD,yBAAyB,CAC1B;KACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,4BAA4B,CAC1C,SAAiB,EACjB,KASC;IAYD,MAAM,KAAK,GAAG,aAAa,SAAS,EAAE,CAAC;IACvC,OAAO;QACL,KAAK,EAAE,mBAAmB,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,KAAK,QAAQ,CAAC;QACzD,IAAI,EAAE,mBAAmB,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC;QACtD,oBAAoB,EAAE,KAAK,CAAC,YAAY;QACxC,QAAQ,EAAE,mBAAmB,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,KAAK,WAAW,CAAC;QAClE,iBAAiB,EAAE,oBAAoB,CACrC,KAAK,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CACrC,4BAA4B,CAAC,MAAM,CAAC,CACrC,EACD,GAAG,KAAK,qBAAqB,CAC9B;QACD,QAAQ,EAAE,mBAAmB,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,KAAK,YAAY,CAAC;QACnE,KAAK,EAAE,oBAAoB,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,KAAK,QAAQ,CAAC;QAC1D,iBAAiB,EAAE,oBAAoB,CACrC,KAAK,CAAC,iBAAiB,EACvB,GAAG,KAAK,sBAAsB,CAC/B;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type {\n  AccessEvent,\n  AccessManifest,\n  ContainerKeyEpoch,\n  ContainerKeyWrap,\n  ContainerUserRecipientKey,\n} from \"@tearleads/crypto\";\nimport type {\n  AccessManifestBundleWire,\n  ContainerMutationRequest,\n} from \"@tearleads/validators/request\";\nimport type { ContainerWriterProjectionResponse } from \"@tearleads/validators/response\";\nimport { principalPolicyRequestRecord } from \"../../../data/containers/shared/principalPolicies\";\nimport { asContainerManifestBundle } from \"../../../data/containers/shared/projection\";\nimport {\n  readCanonicalRecord,\n  readCanonicalRecords,\n} from \"../../../data/keyingCanonicalJson\";\nimport type { PrincipalPolicyCurrentEvidence } from \"../../../data/principals/principalPolicyEvidence\";\n\nexport function readCanonicalRecordOrNull(\n  value: unknown,\n  label: string,\n): Record<string, unknown> | null {\n  return value === null || value === undefined\n    ? null\n    : readCanonicalRecord(value, label);\n}\n\n/**\n * The previous-manifest identity every non-create mutation\n * (share/rekey/revoke/move) sends alongside the core request fields.\n */\nexport function previousPathRequestFields(\n  previousManifest: AccessManifestBundleWire,\n  previousProjection: ContainerWriterProjectionResponse,\n): Pick<\n  ContainerMutationRequest,\n  \"previousManifest\" | \"previousContainerPath\"\n> {\n  return {\n    previousManifest,\n    previousContainerPath: previousProjection.path.map(\n      asContainerManifestBundle,\n    ),\n  };\n}\n\n/**\n * The eight ContainerMutationRequest fields every child-container mutation\n * (create/share/rekey/revoke/move) assembles identically, labeled by\n * operation. The identity fields — previous manifest/path, manifest history,\n * predecessor bridge, keyring, and the parent KEK — genuinely differ per\n * operation and stay with each builder.\n */\nexport function containerMutationRequestCore(\n  operation: string,\n  input: {\n    body: unknown;\n    event: AccessEvent;\n    keyEpoch: ContainerKeyEpoch;\n    manifest: AccessManifest;\n    manifestHash: string;\n    principalPolicies: readonly PrincipalPolicyCurrentEvidence[];\n    userRecipientKeys: readonly ContainerUserRecipientKey[];\n    wraps: readonly ContainerKeyWrap[];\n  },\n): Pick<\n  ContainerMutationRequest,\n  | \"event\"\n  | \"body\"\n  | \"expectedManifestHash\"\n  | \"manifest\"\n  | \"principalPolicies\"\n  | \"keyEpoch\"\n  | \"wraps\"\n  | \"userRecipientKeys\"\n> {\n  const label = `Container ${operation}`;\n  return {\n    event: readCanonicalRecord(input.event, `${label} event`),\n    body: readCanonicalRecord(input.body, `${label} body`),\n    expectedManifestHash: input.manifestHash,\n    manifest: readCanonicalRecord(input.manifest, `${label} manifest`),\n    principalPolicies: readCanonicalRecords(\n      input.principalPolicies.map((policy) =>\n        principalPolicyRequestRecord(policy),\n      ),\n      `${label} principal policies`,\n    ),\n    keyEpoch: readCanonicalRecord(input.keyEpoch, `${label} key epoch`),\n    wraps: readCanonicalRecords(input.wraps, `${label} wraps`),\n    userRecipientKeys: readCanonicalRecords(\n      input.userRecipientKeys,\n      `${label} user recipient keys`,\n    ),\n  };\n}\n"]}

package/workflows/containers/child/mutationSubmit.js

@@ -0,0 +1,122 @@
+import { CONTAINER_MUTATION_ERROR_CODES, } from "../../../internal/validators/response/index.js";
+import { ContainerPathTooDeepError } from "../../../data/containers/shared/containerPathLimits.js";
+import { rememberVerifiedContainerHeads } from "../../../data/containers/shared/heldContainerHeads.js";
+import { acknowledgeContainerMutation, acknowledgeContainerMutationBatch, } from "../../../data/containers/shared/mutationAcknowledgement.js";
+import { isContainerPathTooDeepFailure } from "../../../data/containers/shared/mutationFailures.js";
+import { planCarriedDescendantRekeys, } from "./carriedDescendantRekeys.js";
+import { scheduleHeldDescendantRecitations } from "./recite.js";
+/** A mutation with no status-bearing variant: a share mints nothing to carry. */
+export async function submitPlainContainerMutation(plain) {
+    const data = await plain();
+    return data ? { data, ok: true } : { ok: false, status: null };
+}
+/**
+ * Adapt a rotation endpoint pair to one status-bearing call. An adapter with
+ * only the plain method still rotates; it just cannot learn what to carry, so a
+ * rotation that needs descendants fails as any other refusal does.
+ */
+export async function submitContainerRotation(input) {
+    return input.result
+        ? input.result()
+        : submitPlainContainerMutation(input.plain);
+}
+/**
+ * Submit a rotation; if the server refuses it for stranding a level above a
+ * directly granted container, sign the descendant rekeys it names and resubmit
+ * once with them carried. The refused attempt rolled back whole, so the signed
+ * rotation still extends the current head and only the descendants need
+ * signing. A second refusal means the tree moved underneath, and the caller's
+ * own retry starts from a fresh projection.
+ */
+export async function submitRotationCarryingDescendants(input) {
+    const result = await input.submit([]);
+    if (result.ok ||
+        result.code !== CONTAINER_MUTATION_ERROR_CODES.descendantRekeysRequired ||
+        !result.requiredContainerIds?.length ||
+        !input.carriedRekeys) {
+        return { carriedPlans: [], result: reportTerminalRefusal(result) };
+    }
+    // Answerable, so not an error: callers submit with `reportErrors: false` and
+    // only the refusal that ends the attempt is surfaced.
+    const carriedPlans = await planCarriedDescendantRekeys({
+        ...input.carriedRekeys.planning,
+        requiredContainerIds: result.requiredContainerIds,
+        rotated: [await input.carriedRekeys.rotated()],
+    });
+    // Superseded mid-flight: hand back the refusal unreported, since the caller
+    // discards it and the generation that owned this attempt is gone.
+    if (input.stillCurrent?.() === false)
+        return { carriedPlans: [], result };
+    return {
+        carriedPlans,
+        result: reportTerminalRefusal(await input.submit(carriedPlans.map(({ plan }) => plan.request))),
+    };
+}
+function reportTerminalRefusal(result) {
+    if (!result.ok)
+        result.report?.();
+    return result;
+}
+/**
+ * Submit and acknowledge remote share/rekey/revoke/move plans before scheduling
+ * opportunistic descendant re-citations. Create separately handles its lost
+ * response conflict; group share caches the rotated policy after this tail.
+ */
+export async function submitAcknowledgedContainerMutation(input) {
+    if (input.stillCurrent?.() === false)
+        return null;
+    const submitted = await submitRotationCarryingDescendants(input);
+    if (!submitted.result.ok) {
+        // Final, unlike the other refusals: a queued move must not retry it.
+        if (isContainerPathTooDeepFailure(submitted.result))
+            throw new ContainerPathTooDeepError();
+        return null;
+    }
+    const { carriedPlans } = submitted;
+    const response = submitted.result.data;
+    const acknowledged = carriedPlans.length === 0
+        ? await acknowledgeContainerMutation({
+            execSql: input.execSql,
+            plan: input.plan,
+            response,
+            stillCurrent: input.stillCurrent,
+        })
+        : // The rotation and what it carried committed together, so their pins
+            // advance together: a missing acknowledgement refuses the whole batch.
+            await acknowledgeContainerMutationBatch({
+                execSql: input.execSql,
+                plans: [input.plan, ...carriedPlans.map(({ plan }) => plan)],
+                responses: [response, ...(response.containerRekeys ?? [])],
+                stillCurrent: input.stillCurrent,
+            });
+    if (!acknowledged || input.stillCurrent?.() === false)
+        return null;
+    try {
+        rememberVerifiedContainerHeads({
+            execSql: input.execSql,
+            organizationId: input.author.organizationId,
+            heads: [],
+            policies: input.recitationPolicies,
+        });
+        scheduleHeldDescendantRecitations({
+            apiClient: input.apiClient,
+            author: input.author,
+            execSql: input.execSql,
+            // `plans` are the containers whose descendants get re-cited; they are
+            // never re-cited themselves. A carried rekey already cites the current
+            // path, so listing it here spares its recitation budget.
+            plans: [input.plan, ...carriedPlans.map(({ plan }) => plan)],
+            reportSecurityIncident: input.reportSecurityIncident,
+            stillCurrent: input.stillCurrent,
+        });
+    }
+    catch {
+        // Optional cache population cannot change an acknowledged mutation result.
+    }
+    return {
+        containerKey: input.containerKey,
+        plan: input.plan,
+        response,
+    };
+}
+//# sourceMappingURL=mutationSubmit.js.map

package/workflows/containers/child/mutationSubmit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutationSubmit.js","sourceRoot":"","sources":["mutationSubmit.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AnyVerifiedPrincipalPolicy } from \"@tearleads/crypto\";\nimport type { ContainerMutationRequest } from \"@tearleads/validators/request\";\nimport {\n  CONTAINER_MUTATION_ERROR_CODES,\n  type ContainerRotationResponse,\n} from \"@tearleads/validators/response\";\nimport { ContainerPathTooDeepError } from \"../../../data/containers/shared/containerPathLimits\";\nimport { rememberVerifiedContainerHeads } from \"../../../data/containers/shared/heldContainerHeads\";\nimport {\n  acknowledgeContainerMutation,\n  acknowledgeContainerMutationBatch,\n} from \"../../../data/containers/shared/mutationAcknowledgement\";\nimport { isContainerPathTooDeepFailure } from \"../../../data/containers/shared/mutationFailures\";\nimport type { ContainerReciteApi } from \"../../../data/containers/shared/reciteApi\";\nimport type {\n  ContainerMutationAuthor,\n  ContainerRotationResult,\n  MaterializedContainerRekeyPlan,\n} from \"../../../data/containers/shared/types\";\nimport type { SecurityIncidentReporter } from \"../../../data/securityIncidents\";\nimport type { ExecSql } from \"../../../data/sqlite/sqlSchema\";\nimport {\n  type CarriedRekeyPlanningInput,\n  planCarriedDescendantRekeys,\n  type SpeculativePath,\n} from \"./carriedDescendantRekeys\";\nimport { scheduleHeldDescendantRecitations } from \"./recite\";\n\n/**\n * Supplied by mutations that mint a new key epoch (rekey, revoke, move). The\n * server refuses one that would strand a level above a directly granted\n * container, and names the descendant rekeys it must carry instead (#2340).\n */\nexport interface CarriedRekeys {\n  readonly planning: CarriedRekeyPlanningInput;\n  /** The rotated container's own path once the rotation is accepted. */\n  readonly rotated: () => Promise<SpeculativePath>;\n}\n\n/** A mutation with no status-bearing variant: a share mints nothing to carry. */\nexport async function submitPlainContainerMutation(\n  plain: () => Promise<ContainerRotationResponse | null>,\n): Promise<ContainerRotationResult> {\n  const data = await plain();\n  return data ? { data, ok: true } : { ok: false, status: null };\n}\n\n/**\n * Adapt a rotation endpoint pair to one status-bearing call. An adapter with\n * only the plain method still rotates; it just cannot learn what to carry, so a\n * rotation that needs descendants fails as any other refusal does.\n */\nexport async function submitContainerRotation(input: {\n  plain: () => Promise<ContainerRotationResponse | null>;\n  result: (() => Promise<ContainerRotationResult>) | undefined;\n}): Promise<ContainerRotationResult> {\n  return input.result\n    ? input.result()\n    : submitPlainContainerMutation(input.plain);\n}\n\n/**\n * Submit a rotation; if the server refuses it for stranding a level above a\n * directly granted container, sign the descendant rekeys it names and resubmit\n * once with them carried. The refused attempt rolled back whole, so the signed\n * rotation still extends the current head and only the descendants need\n * signing. A second refusal means the tree moved underneath, and the caller's\n * own retry starts from a fresh projection.\n */\nexport async function submitRotationCarryingDescendants(input: {\n  carriedRekeys?: CarriedRekeys | undefined;\n  stillCurrent?: (() => boolean) | undefined;\n  submit: (\n    carried: readonly ContainerMutationRequest[],\n  ) => Promise<ContainerRotationResult>;\n}): Promise<{\n  carriedPlans: MaterializedContainerRekeyPlan[];\n  result: ContainerRotationResult;\n}> {\n  const result = await input.submit([]);\n  if (\n    result.ok ||\n    result.code !== CONTAINER_MUTATION_ERROR_CODES.descendantRekeysRequired ||\n    !result.requiredContainerIds?.length ||\n    !input.carriedRekeys\n  ) {\n    return { carriedPlans: [], result: reportTerminalRefusal(result) };\n  }\n  // Answerable, so not an error: callers submit with `reportErrors: false` and\n  // only the refusal that ends the attempt is surfaced.\n  const carriedPlans = await planCarriedDescendantRekeys({\n    ...input.carriedRekeys.planning,\n    requiredContainerIds: result.requiredContainerIds,\n    rotated: [await input.carriedRekeys.rotated()],\n  });\n  // Superseded mid-flight: hand back the refusal unreported, since the caller\n  // discards it and the generation that owned this attempt is gone.\n  if (input.stillCurrent?.() === false) return { carriedPlans: [], result };\n  return {\n    carriedPlans,\n    result: reportTerminalRefusal(\n      await input.submit(carriedPlans.map(({ plan }) => plan.request)),\n    ),\n  };\n}\n\nfunction reportTerminalRefusal(\n  result: ContainerRotationResult,\n): ContainerRotationResult {\n  if (!result.ok) result.report?.();\n  return result;\n}\n\n/**\n * Submit and acknowledge remote share/rekey/revoke/move plans before scheduling\n * opportunistic descendant re-citations. Create separately handles its lost\n * response conflict; group share caches the rotated policy after this tail.\n */\nexport async function submitAcknowledgedContainerMutation<\n  TPlan extends Parameters<typeof acknowledgeContainerMutation>[0][\"plan\"],\n>(input: {\n  apiClient: ContainerReciteApi;\n  author: ContainerMutationAuthor;\n  /** Present exactly when the plan minted a new key epoch. */\n  carriedRekeys?: CarriedRekeys | undefined;\n  containerKey: Uint8Array;\n  execSql: ExecSql;\n  plan: TPlan;\n  recitationPolicies: readonly AnyVerifiedPrincipalPolicy[];\n  reportSecurityIncident: SecurityIncidentReporter;\n  stillCurrent?: (() => boolean) | undefined;\n  submit: (\n    carried: readonly ContainerMutationRequest[],\n  ) => Promise<ContainerRotationResult>;\n}): Promise<{\n  containerKey: Uint8Array;\n  plan: TPlan;\n  response: ContainerRotationResponse;\n} | null> {\n  if (input.stillCurrent?.() === false) return null;\n  const submitted = await submitRotationCarryingDescendants(input);\n  if (!submitted.result.ok) {\n    // Final, unlike the other refusals: a queued move must not retry it.\n    if (isContainerPathTooDeepFailure(submitted.result))\n      throw new ContainerPathTooDeepError();\n    return null;\n  }\n  const { carriedPlans } = submitted;\n  const response = submitted.result.data;\n\n  const acknowledged =\n    carriedPlans.length === 0\n      ? await acknowledgeContainerMutation({\n          execSql: input.execSql,\n          plan: input.plan,\n          response,\n          stillCurrent: input.stillCurrent,\n        })\n      : // The rotation and what it carried committed together, so their pins\n        // advance together: a missing acknowledgement refuses the whole batch.\n        await acknowledgeContainerMutationBatch({\n          execSql: input.execSql,\n          plans: [input.plan, ...carriedPlans.map(({ plan }) => plan)],\n          responses: [response, ...(response.containerRekeys ?? [])],\n          stillCurrent: input.stillCurrent,\n        });\n  if (!acknowledged || input.stillCurrent?.() === false) return null;\n\n  try {\n    rememberVerifiedContainerHeads({\n      execSql: input.execSql,\n      organizationId: input.author.organizationId,\n      heads: [],\n      policies: input.recitationPolicies,\n    });\n    scheduleHeldDescendantRecitations({\n      apiClient: input.apiClient,\n      author: input.author,\n      execSql: input.execSql,\n      // `plans` are the containers whose descendants get re-cited; they are\n      // never re-cited themselves. A carried rekey already cites the current\n      // path, so listing it here spares its recitation budget.\n      plans: [input.plan, ...carriedPlans.map(({ plan }) => plan)],\n      reportSecurityIncident: input.reportSecurityIncident,\n      stillCurrent: input.stillCurrent,\n    });\n  } catch {\n    // Optional cache population cannot change an acknowledged mutation result.\n  }\n  return {\n    containerKey: input.containerKey,\n    plan: input.plan,\n    response,\n  };\n}\n"]}

package/workflows/containers/child/policyRepair.js

@@ -0,0 +1,23 @@
+import { cachePrincipalPolicyBundles } from "../../principals/policyCache.js";
+export async function cacheRemoteContainerCreatePolicyRepair(input) {
+    const bundles = input.failure.stalePrincipalPolicies;
+    if (!input.execSql ||
+        !bundles ||
+        bundles.length === 0 ||
+        input.stillCurrent?.() === false) {
+        return false;
+    }
+    // The server supplied fresh signed policy bundles with the 409. Verify and
+    // cache them locally before rebuilding the signed create request.
+    await cachePrincipalPolicyBundles({
+        bundles,
+        execSql: input.execSql,
+        getCurrentPrincipalPolicy: input.apiClient.getCurrentPrincipalPolicy.bind(input.apiClient),
+        organizationId: input.organizationId,
+        reportSecurityIncident: input.reportSecurityIncident,
+        resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,
+        stillCurrent: input.stillCurrent,
+    });
+    return input.stillCurrent?.() !== false;
+}
+//# sourceMappingURL=policyRepair.js.map

package/workflows/containers/child/policyRepair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policyRepair.js","sourceRoot":"","sources":["policyRepair.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AAE3E,MAAM,CAAC,KAAK,UAAU,sCAAsC,CAAC,KAQ5D;IACC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,sBAAsB,CAAC;IACrD,IACE,CAAC,KAAK,CAAC,OAAO;QACd,CAAC,OAAO;QACR,OAAO,CAAC,MAAM,KAAK,CAAC;QACpB,KAAK,CAAC,YAAY,EAAE,EAAE,KAAK,KAAK,EAChC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,2EAA2E;IAC3E,kEAAkE;IAClE,MAAM,2BAA2B,CAAC;QAChC,OAAO;QACP,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,yBAAyB,EAAE,KAAK,CAAC,SAAS,CAAC,yBAAyB,CAAC,IAAI,CACvE,KAAK,CAAC,SAAS,CAChB;QACD,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,sBAAsB,EAAE,KAAK,CAAC,sBAAsB;QACpD,0BAA0B,EAAE,KAAK,CAAC,0BAA0B;QAC5D,YAAY,EAAE,KAAK,CAAC,YAAY;KACjC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC,YAAY,EAAE,EAAE,KAAK,KAAK,CAAC;AAC1C,CAAC","sourcesContent":["import type {\n  ContainerCreateApi,\n  ContainerMutationSubmitFailure,\n} from \"../../../data/containers/shared/types\";\nimport type { SecurityIncidentReporter } from \"../../../data/securityIncidents\";\nimport type { ExecSql } from \"../../../data/sqlite/sqlSchema\";\nimport type { TrustedUserIdentityResolver } from \"../../../data/trustedUserIdentity\";\nimport { cachePrincipalPolicyBundles } from \"../../principals/policyCache\";\n\nexport async function cacheRemoteContainerCreatePolicyRepair(input: {\n  readonly apiClient: ContainerCreateApi;\n  readonly execSql: ExecSql | undefined;\n  readonly failure: ContainerMutationSubmitFailure;\n  readonly organizationId: string;\n  readonly reportSecurityIncident: SecurityIncidentReporter;\n  readonly resolveTrustedUserIdentity: TrustedUserIdentityResolver;\n  readonly stillCurrent?: (() => boolean) | undefined;\n}): Promise<boolean> {\n  const bundles = input.failure.stalePrincipalPolicies;\n  if (\n    !input.execSql ||\n    !bundles ||\n    bundles.length === 0 ||\n    input.stillCurrent?.() === false\n  ) {\n    return false;\n  }\n\n  // The server supplied fresh signed policy bundles with the 409. Verify and\n  // cache them locally before rebuilding the signed create request.\n  await cachePrincipalPolicyBundles({\n    bundles,\n    execSql: input.execSql,\n    getCurrentPrincipalPolicy: input.apiClient.getCurrentPrincipalPolicy.bind(\n      input.apiClient,\n    ),\n    organizationId: input.organizationId,\n    reportSecurityIncident: input.reportSecurityIncident,\n    resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,\n    stillCurrent: input.stillCurrent,\n  });\n  return input.stillCurrent?.() !== false;\n}\n"]}

package/workflows/containers/child/recite.js

@@ -0,0 +1,175 @@
+import { KeyingVerificationError } from "../../../internal/crypto/index.js";
+import { heldContainerPath, heldContainerSnapshot, rememberAcknowledgedContainerHead, } from "../../../data/containers/shared/heldContainerHeads.js";
+import { loadAccessManifestCheckpoint, loadPrincipalPolicyCheckpoint, } from "../../../data/persistence/keyingCheckpointPersistence.js";
+import { advanceLocallyAcknowledgedAccessManifestHeadsAtomically, locallyAuthoredAccessManifestHead, } from "../../../data/persistence/locallyAcknowledgedCheckpointPersistence.js";
+import { resolveCanonicalExecSql, } from "../../../data/sqlite/sqlSchema.js";
+import { assertContainerReciteAcknowledgement, buildContainerRecitePlan, referencedRecitationPolicies, } from "./recitePlan.js";
+const MAX_RECITES_PER_PASS = 8;
+const RECITE_SPACING_MS = 250;
+async function pathIsPinned(execSql, path) {
+    for (const head of path) {
+        const checkpoint = await loadAccessManifestCheckpoint(execSql, "container", head.state.organizationId, head.state.containerId);
+        if (checkpoint?.manifestHash !== head.bundle.manifestHash)
+            return false;
+    }
+    return true;
+}
+async function recitePinnedPath(input, path, policies) {
+    const usedPolicies = referencedRecitationPolicies(path, policies);
+    if (!(await policiesArePinned(input.execSql, usedPolicies)))
+        return null;
+    const plan = await buildContainerRecitePlan({
+        author: input.author,
+        path,
+        policies: usedPolicies,
+    });
+    if (!(await policiesArePinned(input.execSql, usedPolicies)))
+        return null;
+    if (!(await pathIsPinned(input.execSql, path)))
+        return null;
+    if (input.stillCurrent?.() === false)
+        return null;
+    const id = plan.state.containerId;
+    const response = await input.apiClient.reciteContainer(id, plan.request, {
+        reportErrors: false,
+    });
+    if (!response || input.stillCurrent?.() === false)
+        return null;
+    try {
+        assertContainerReciteAcknowledgement(plan, response);
+    }
+    catch (error) {
+        const failure = error instanceof KeyingVerificationError
+            ? error
+            : new KeyingVerificationError("invalid_shape", "Malformed re-citation acknowledgement");
+        await input.reportSecurityIncident(failure, {
+            operation: "container.recite.acknowledge",
+            objectKind: "container",
+            objectId: id,
+            organizationId: input.author.organizationId,
+            evidenceHashes: { plannedManifestHash: plan.manifestHash },
+        });
+        return null;
+    }
+    let acknowledged;
+    try {
+        acknowledged =
+            await advanceLocallyAcknowledgedAccessManifestHeadsAtomically({
+                execSql: input.execSql,
+                heads: [locallyAuthoredAccessManifestHead(plan)],
+                expectedAccessManifestCheckpoints: path.map((head) => ({
+                    objectKind: "container",
+                    objectId: head.state.containerId,
+                    organizationId: head.state.organizationId,
+                    epoch: head.state.epoch,
+                    manifestHash: head.bundle.manifestHash,
+                })),
+                expectedPrincipalPolicyCheckpoints: usedPolicies.map((policy) => policy.checkpoint),
+                stillCurrent: input.stillCurrent,
+            });
+    }
+    catch (error) {
+        if (!(error instanceof KeyingVerificationError))
+            throw error;
+        // Another local operation can advance the durable pin while the request
+        // is in flight. Refuse the write, but do not label that local race as a
+        // contradictory server response: the exact signed acknowledgement above
+        // already passed. Normal projection verification reconciles newer heads.
+        return null;
+    }
+    if (!acknowledged || input.stillCurrent?.() === false)
+        return null;
+    return rememberAcknowledgedContainerHead(input.execSql, plan);
+}
+async function policiesArePinned(execSql, policies) {
+    for (const policy of policies) {
+        const checkpoint = await loadPrincipalPolicyCheckpoint(execSql, policy.principalType, policy.principalId);
+        if (checkpoint?.version !== policy.version ||
+            checkpoint.stateHash !== policy.stateHash)
+            return false;
+    }
+    return true;
+}
+async function waitForPinnedPath(input, path, attempts) {
+    if (!(await pathIsPinned(input.execSql, path)))
+        return false;
+    if (attempts > 0) {
+        await new Promise((resolve) => setTimeout(resolve, RECITE_SPACING_MS));
+        if (!(await pathIsPinned(input.execSql, path)))
+            return false;
+    }
+    return input.stillCurrent?.() !== false;
+}
+/**
+ * Best effort only: never fetches a subtree or policy, never retries conflicts,
+ * and never turns an unavailable/missing descendant into an ancestor refusal.
+ * The API checks admin authority and exact current paths again at commit time.
+ */
+export async function reciteHeldDescendants(input) {
+    const snapshot = heldContainerSnapshot(input.execSql, input.author.organizationId);
+    const ancestors = new Set(input.ancestorIds);
+    const candidates = [...snapshot.heads.keys()]
+        .map((id) => ({ id, path: heldContainerPath(snapshot.heads, id) }))
+        .filter(({ id, path }) => !ancestors.has(id) &&
+        path?.some((head) => ancestors.has(head.state.containerId)))
+        .sort((a, b) => (a.path?.length ?? 0) - (b.path?.length ?? 0));
+    let attempts = 0;
+    for (const { id } of candidates) {
+        if (attempts >= MAX_RECITES_PER_PASS)
+            return;
+        if (input.stillCurrent?.() === false)
+            return;
+        try {
+            const path = heldContainerPath(snapshot.heads, id);
+            if (!path)
+                continue;
+            // Every held head must still equal its durable pin. A failed projection,
+            // concurrent mutation, or verify-without-persist result cannot become an
+            // implicit checkpoint advance through this opportunistic path.
+            if (!(await waitForPinnedPath(input, path, attempts)))
+                continue;
+            attempts += 1;
+            const updated = await recitePinnedPath(input, path, snapshot.policies);
+            if (updated)
+                snapshot.heads.set(id, updated);
+        }
+        catch {
+            // A later reconciliation can observe any committed response we lost.
+            // Do not retry here or change the result of the acknowledged ancestor.
+        }
+    }
+}
+const running = new WeakSet();
+/** Called only after exact acknowledgement of the original mutation. */
+export function scheduleHeldDescendantRecitations(input) {
+    if (input.stillCurrent?.() === false)
+        return;
+    try {
+        for (const plan of input.plans) {
+            rememberAcknowledgedContainerHead(input.execSql, plan);
+        }
+    }
+    catch {
+        return;
+    }
+    const canonical = resolveCanonicalExecSql(input.execSql);
+    if (running.has(canonical))
+        return;
+    running.add(canonical);
+    void Promise.resolve()
+        .then(() => reciteHeldDescendants({
+        apiClient: input.apiClient,
+        author: input.author,
+        // Background work outlives the caller's lock scope. Use the canonical
+        // executor so its checkpoint write acquires a new mutation lock.
+        execSql: canonical,
+        reportSecurityIncident: input.reportSecurityIncident,
+        stillCurrent: input.stillCurrent,
+        ancestorIds: input.plans.map((plan) => plan.containerId),
+    }))
+        .catch(() => {
+        // Failure is deliberately independent of the user's completed mutation.
+    })
+        .finally(() => running.delete(canonical));
+}
+//# sourceMappingURL=recite.js.map

package/workflows/containers/child/recite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recite.js","sourceRoot":"","sources":["recite.ts"],"names":[],"mappings":"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","sourcesContent":["import { KeyingVerificationError } from \"@tearleads/crypto\";\nimport {\n  type HeldContainerHead,\n  heldContainerPath,\n  heldContainerSnapshot,\n  rememberAcknowledgedContainerHead,\n} from \"../../../data/containers/shared/heldContainerHeads\";\nimport type { AuthoredContainerMutationHead } from \"../../../data/containers/shared/mutationAcknowledgement\";\nimport type { ContainerReciteApi } from \"../../../data/containers/shared/reciteApi\";\nimport type { ContainerMutationAuthor } from \"../../../data/containers/shared/types\";\nimport {\n  loadAccessManifestCheckpoint,\n  loadPrincipalPolicyCheckpoint,\n} from \"../../../data/persistence/keyingCheckpointPersistence\";\nimport {\n  advanceLocallyAcknowledgedAccessManifestHeadsAtomically,\n  locallyAuthoredAccessManifestHead,\n} from \"../../../data/persistence/locallyAcknowledgedCheckpointPersistence\";\nimport type { SecurityIncidentReporter } from \"../../../data/securityIncidents\";\nimport {\n  type ExecSql,\n  resolveCanonicalExecSql,\n} from \"../../../data/sqlite/sqlSchema\";\nimport {\n  assertContainerReciteAcknowledgement,\n  buildContainerRecitePlan,\n  referencedRecitationPolicies,\n} from \"./recitePlan\";\n\nconst MAX_RECITES_PER_PASS = 8;\nconst RECITE_SPACING_MS = 250;\n\ninterface ReciteHeldDescendantsInput {\n  readonly apiClient: ContainerReciteApi;\n  readonly author: ContainerMutationAuthor;\n  readonly ancestorIds: readonly string[];\n  readonly execSql: ExecSql;\n  readonly reportSecurityIncident: SecurityIncidentReporter;\n  readonly stillCurrent?: (() => boolean) | undefined;\n}\n\nasync function pathIsPinned(\n  execSql: ExecSql,\n  path: readonly HeldContainerHead[],\n): Promise<boolean> {\n  for (const head of path) {\n    const checkpoint = await loadAccessManifestCheckpoint(\n      execSql,\n      \"container\",\n      head.state.organizationId,\n      head.state.containerId,\n    );\n    if (checkpoint?.manifestHash !== head.bundle.manifestHash) return false;\n  }\n  return true;\n}\n\nasync function recitePinnedPath(\n  input: ReciteHeldDescendantsInput,\n  path: readonly HeldContainerHead[],\n  policies: ReturnType<typeof heldContainerSnapshot>[\"policies\"],\n): Promise<HeldContainerHead | null> {\n  const usedPolicies = referencedRecitationPolicies(path, policies);\n  if (!(await policiesArePinned(input.execSql, usedPolicies))) return null;\n  const plan = await buildContainerRecitePlan({\n    author: input.author,\n    path,\n    policies: usedPolicies,\n  });\n  if (!(await policiesArePinned(input.execSql, usedPolicies))) return null;\n  if (!(await pathIsPinned(input.execSql, path))) return null;\n  if (input.stillCurrent?.() === false) return null;\n  const id = plan.state.containerId;\n  const response = await input.apiClient.reciteContainer(id, plan.request, {\n    reportErrors: false,\n  });\n  if (!response || input.stillCurrent?.() === false) return null;\n  try {\n    assertContainerReciteAcknowledgement(plan, response);\n  } catch (error) {\n    const failure =\n      error instanceof KeyingVerificationError\n        ? error\n        : new KeyingVerificationError(\n            \"invalid_shape\",\n            \"Malformed re-citation acknowledgement\",\n          );\n    await input.reportSecurityIncident(failure, {\n      operation: \"container.recite.acknowledge\",\n      objectKind: \"container\",\n      objectId: id,\n      organizationId: input.author.organizationId,\n      evidenceHashes: { plannedManifestHash: plan.manifestHash },\n    });\n    return null;\n  }\n  let acknowledged: boolean;\n  try {\n    acknowledged =\n      await advanceLocallyAcknowledgedAccessManifestHeadsAtomically({\n        execSql: input.execSql,\n        heads: [locallyAuthoredAccessManifestHead(plan)],\n        expectedAccessManifestCheckpoints: path.map((head) => ({\n          objectKind: \"container\",\n          objectId: head.state.containerId,\n          organizationId: head.state.organizationId,\n          epoch: head.state.epoch,\n          manifestHash: head.bundle.manifestHash,\n        })),\n        expectedPrincipalPolicyCheckpoints: usedPolicies.map(\n          (policy) => policy.checkpoint,\n        ),\n        stillCurrent: input.stillCurrent,\n      });\n  } catch (error) {\n    if (!(error instanceof KeyingVerificationError)) throw error;\n    // Another local operation can advance the durable pin while the request\n    // is in flight. Refuse the write, but do not label that local race as a\n    // contradictory server response: the exact signed acknowledgement above\n    // already passed. Normal projection verification reconciles newer heads.\n    return null;\n  }\n  if (!acknowledged || input.stillCurrent?.() === false) return null;\n  return rememberAcknowledgedContainerHead(input.execSql, plan);\n}\n\nasync function policiesArePinned(\n  execSql: ExecSql,\n  policies: ReturnType<typeof referencedRecitationPolicies>,\n): Promise<boolean> {\n  for (const policy of policies) {\n    const checkpoint = await loadPrincipalPolicyCheckpoint(\n      execSql,\n      policy.principalType,\n      policy.principalId,\n    );\n    if (\n      checkpoint?.version !== policy.version ||\n      checkpoint.stateHash !== policy.stateHash\n    )\n      return false;\n  }\n  return true;\n}\n\nasync function waitForPinnedPath(\n  input: ReciteHeldDescendantsInput,\n  path: readonly HeldContainerHead[],\n  attempts: number,\n): Promise<boolean> {\n  if (!(await pathIsPinned(input.execSql, path))) return false;\n  if (attempts > 0) {\n    await new Promise((resolve) => setTimeout(resolve, RECITE_SPACING_MS));\n    if (!(await pathIsPinned(input.execSql, path))) return false;\n  }\n  return input.stillCurrent?.() !== false;\n}\n\n/**\n * Best effort only: never fetches a subtree or policy, never retries conflicts,\n * and never turns an unavailable/missing descendant into an ancestor refusal.\n * The API checks admin authority and exact current paths again at commit time.\n */\nexport async function reciteHeldDescendants(\n  input: ReciteHeldDescendantsInput,\n): Promise<void> {\n  const snapshot = heldContainerSnapshot(\n    input.execSql,\n    input.author.organizationId,\n  );\n  const ancestors = new Set(input.ancestorIds);\n  const candidates = [...snapshot.heads.keys()]\n    .map((id) => ({ id, path: heldContainerPath(snapshot.heads, id) }))\n    .filter(\n      ({ id, path }) =>\n        !ancestors.has(id) &&\n        path?.some((head) => ancestors.has(head.state.containerId)),\n    )\n    .sort((a, b) => (a.path?.length ?? 0) - (b.path?.length ?? 0));\n  let attempts = 0;\n  for (const { id } of candidates) {\n    if (attempts >= MAX_RECITES_PER_PASS) return;\n    if (input.stillCurrent?.() === false) return;\n    try {\n      const path = heldContainerPath(snapshot.heads, id);\n      if (!path) continue;\n      // Every held head must still equal its durable pin. A failed projection,\n      // concurrent mutation, or verify-without-persist result cannot become an\n      // implicit checkpoint advance through this opportunistic path.\n      if (!(await waitForPinnedPath(input, path, attempts))) continue;\n      attempts += 1;\n      const updated = await recitePinnedPath(input, path, snapshot.policies);\n      if (updated) snapshot.heads.set(id, updated);\n    } catch {\n      // A later reconciliation can observe any committed response we lost.\n      // Do not retry here or change the result of the acknowledged ancestor.\n    }\n  }\n}\n\nconst running = new WeakSet<ExecSql>();\n\n/** Called only after exact acknowledgement of the original mutation. */\nexport function scheduleHeldDescendantRecitations(\n  input: Omit<ReciteHeldDescendantsInput, \"ancestorIds\"> & {\n    readonly plans: readonly AuthoredContainerMutationHead[];\n  },\n): void {\n  if (input.stillCurrent?.() === false) return;\n  try {\n    for (const plan of input.plans) {\n      rememberAcknowledgedContainerHead(input.execSql, plan);\n    }\n  } catch {\n    return;\n  }\n  const canonical = resolveCanonicalExecSql(input.execSql);\n  if (running.has(canonical)) return;\n  running.add(canonical);\n  void Promise.resolve()\n    .then(() =>\n      reciteHeldDescendants({\n        apiClient: input.apiClient,\n        author: input.author,\n        // Background work outlives the caller's lock scope. Use the canonical\n        // executor so its checkpoint write acquires a new mutation lock.\n        execSql: canonical,\n        reportSecurityIncident: input.reportSecurityIncident,\n        stillCurrent: input.stillCurrent,\n        ancestorIds: input.plans.map((plan) => plan.containerId),\n      }),\n    )\n    .catch(() => {\n      // Failure is deliberately independent of the user's completed mutation.\n    })\n    .finally(() => running.delete(canonical));\n}\n"]}

package/workflows/containers/child/recitePlan.js

@@ -0,0 +1,80 @@
+import { computeAccessManifestHash, deriveContainerAccessManifest, KeyingVerificationError, MAX_CONTAINER_RECITATION_EPOCH, resolveContainerStatePathUserAccessLevel, } from "../../../internal/crypto/index.js";
+import { signContainerMutationEvent } from "../../../data/containers/shared/events.js";
+import { principalPolicyRequestRecord } from "../../../data/containers/shared/principalPolicies.js";
+import { canonicalKeyingJsonString, readCanonicalRecord, } from "../../../data/keyingCanonicalJson.js";
+export function referencedRecitationPolicies(path, policies) {
+    const referencedIds = new Set(path.flatMap((head) => head.state.referencedPrincipalHeads.map((ref) => `${ref.principalType}:${ref.principalId}`)));
+    return policies.filter((policy) => referencedIds.has(`${policy.principalType}:${policy.principalId}`));
+}
+export async function buildContainerRecitePlan(input) {
+    const previous = input.path.at(-1);
+    if (!previous)
+        throw new Error("Recitation requires a held container path");
+    if (previous.state.epoch >= MAX_CONTAINER_RECITATION_EPOCH) {
+        throw new Error("Container re-citation history budget is exhausted");
+    }
+    if (input.path.some((head) => head.state.organizationId !== input.author.organizationId)) {
+        throw new Error("Recitation cannot cross organizations");
+    }
+    if (resolveContainerStatePathUserAccessLevel({
+        states: input.path.map((head) => head.state),
+        principalPolicies: input.policies,
+        userId: input.author.signerUserId,
+    }) !== "admin") {
+        throw new KeyingVerificationError("unauthorized", "Container re-citation signer lacks admin access on the held path");
+    }
+    const body = {
+        eventType: "container.recite",
+        containerKeyEpochId: previous.state.containerKeyEpochId,
+        containerKeyPublicKey: previous.state.containerKeyPublicKey,
+    };
+    const { event, eventHash } = await signContainerMutationEvent({
+        author: input.author,
+        body,
+        containerId: previous.state.containerId,
+        dependencyManifestHashes: input.path.map((head) => head.bundle.manifestHash),
+        eventId: crypto.randomUUID(),
+        previousManifestHash: previous.bundle.manifestHash,
+        signedAt: new Date().toISOString(),
+    });
+    const state = {
+        ...previous.state,
+        epoch: previous.state.epoch + 1,
+        eventHash,
+        previousManifestHash: previous.bundle.manifestHash,
+    };
+    const manifest = await deriveContainerAccessManifest(state);
+    const manifestHash = await computeAccessManifestHash(manifest);
+    const request = {
+        body,
+        event: readCanonicalRecord(event, "Recitation event"),
+        manifest: readCanonicalRecord(manifest, "Recitation manifest"),
+        expectedManifestHash: manifestHash,
+        previousManifest: previous.bundle,
+        previousContainerPath: input.path.map((head) => head.bundle),
+        principalPolicies: referencedRecitationPolicies(input.path, input.policies).map((policy) => principalPolicyRequestRecord(policy)),
+    };
+    return { body, event, eventHash, manifest, manifestHash, state, request };
+}
+export function assertContainerReciteAcknowledgement(plan, response) {
+    const bundle = response.accessManifest;
+    const signedFieldsMatch = [
+        [bundle.event.event, plan.event],
+        [bundle.event.body, plan.body],
+        [bundle.manifest, plan.manifest],
+        [bundle.state, plan.state],
+    ].every(([actual, expected]) => canonicalKeyingJsonString(actual, "Recitation response") ===
+        canonicalKeyingJsonString(expected, "Recitation plan"));
+    if (response.containerId !== plan.state.containerId ||
+        response.organizationId !== plan.state.organizationId ||
+        response.parentId !== plan.state.parentContainerId ||
+        response.manifestHead.epoch !== plan.state.epoch ||
+        response.manifestHead.manifestHash !== plan.manifestHash ||
+        bundle.manifestHash !== plan.manifestHash ||
+        bundle.event.eventHash !== plan.eventHash ||
+        !signedFieldsMatch ||
+        canonicalKeyingJsonString(response.referencedPrincipalHeads, "Recitation references") !==
+            canonicalKeyingJsonString(plan.manifest.referencedPrincipalHeads, "Recitation planned references"))
+        throw new KeyingVerificationError("object_mismatch", "Container recitation response does not match the signed plan");
+}
+//# sourceMappingURL=recitePlan.js.map

package/workflows/containers/child/recitePlan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recitePlan.js","sourceRoot":"","sources":["recitePlan.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  computeAccessManifestHash,\n  deriveContainerAccessManifest,\n  KeyingVerificationError,\n  MAX_CONTAINER_RECITATION_EPOCH,\n  resolveContainerStatePathUserAccessLevel,\n} from \"@tearleads/crypto\";\nimport type { ContainerReciteRequest } from \"@tearleads/validators/request\";\nimport type { ContainerReciteResponse } from \"@tearleads/validators/response\";\nimport { signContainerMutationEvent } from \"../../../data/containers/shared/events\";\nimport type { HeldContainerHead } from \"../../../data/containers/shared/heldContainerHeads\";\nimport { principalPolicyRequestRecord } from \"../../../data/containers/shared/principalPolicies\";\nimport type { ContainerMutationAuthor } from \"../../../data/containers/shared/types\";\nimport {\n  canonicalKeyingJsonString,\n  readCanonicalRecord,\n} from \"../../../data/keyingCanonicalJson\";\nimport type { PrincipalPolicyCheckpointEvidence } from \"../../../data/principals/principalPolicyEvidence\";\n\nexport function referencedRecitationPolicies(\n  path: readonly HeldContainerHead[],\n  policies: readonly PrincipalPolicyCheckpointEvidence[],\n): readonly PrincipalPolicyCheckpointEvidence[] {\n  const referencedIds = new Set(\n    path.flatMap((head) =>\n      head.state.referencedPrincipalHeads.map(\n        (ref) => `${ref.principalType}:${ref.principalId}`,\n      ),\n    ),\n  );\n  return policies.filter((policy) =>\n    referencedIds.has(`${policy.principalType}:${policy.principalId}`),\n  );\n}\n\nexport async function buildContainerRecitePlan(input: {\n  readonly author: ContainerMutationAuthor;\n  readonly path: readonly HeldContainerHead[];\n  readonly policies: readonly PrincipalPolicyCheckpointEvidence[];\n}) {\n  const previous = input.path.at(-1);\n  if (!previous) throw new Error(\"Recitation requires a held container path\");\n  if (previous.state.epoch >= MAX_CONTAINER_RECITATION_EPOCH) {\n    throw new Error(\"Container re-citation history budget is exhausted\");\n  }\n  if (\n    input.path.some(\n      (head) => head.state.organizationId !== input.author.organizationId,\n    )\n  ) {\n    throw new Error(\"Recitation cannot cross organizations\");\n  }\n  if (\n    resolveContainerStatePathUserAccessLevel({\n      states: input.path.map((head) => head.state),\n      principalPolicies: input.policies,\n      userId: input.author.signerUserId,\n    }) !== \"admin\"\n  ) {\n    throw new KeyingVerificationError(\n      \"unauthorized\",\n      \"Container re-citation signer lacks admin access on the held path\",\n    );\n  }\n  const body = {\n    eventType: \"container.recite\" as const,\n    containerKeyEpochId: previous.state.containerKeyEpochId,\n    containerKeyPublicKey: previous.state.containerKeyPublicKey,\n  };\n  const { event, eventHash } = await signContainerMutationEvent({\n    author: input.author,\n    body,\n    containerId: previous.state.containerId,\n    dependencyManifestHashes: input.path.map(\n      (head) => head.bundle.manifestHash,\n    ),\n    eventId: crypto.randomUUID(),\n    previousManifestHash: previous.bundle.manifestHash,\n    signedAt: new Date().toISOString(),\n  });\n  const state = {\n    ...previous.state,\n    epoch: previous.state.epoch + 1,\n    eventHash,\n    previousManifestHash: previous.bundle.manifestHash,\n  };\n  const manifest = await deriveContainerAccessManifest(state);\n  const manifestHash = await computeAccessManifestHash(manifest);\n  const request: ContainerReciteRequest = {\n    body,\n    event: readCanonicalRecord(event, \"Recitation event\"),\n    manifest: readCanonicalRecord(manifest, \"Recitation manifest\"),\n    expectedManifestHash: manifestHash,\n    previousManifest: previous.bundle,\n    previousContainerPath: input.path.map((head) => head.bundle),\n    principalPolicies: referencedRecitationPolicies(\n      input.path,\n      input.policies,\n    ).map((policy) => principalPolicyRequestRecord(policy)),\n  };\n  return { body, event, eventHash, manifest, manifestHash, state, request };\n}\n\nexport function assertContainerReciteAcknowledgement(\n  plan: Awaited<ReturnType<typeof buildContainerRecitePlan>>,\n  response: ContainerReciteResponse,\n): void {\n  const bundle = response.accessManifest;\n  const signedFieldsMatch = [\n    [bundle.event.event, plan.event],\n    [bundle.event.body, plan.body],\n    [bundle.manifest, plan.manifest],\n    [bundle.state, plan.state],\n  ].every(\n    ([actual, expected]) =>\n      canonicalKeyingJsonString(actual, \"Recitation response\") ===\n      canonicalKeyingJsonString(expected, \"Recitation plan\"),\n  );\n  if (\n    response.containerId !== plan.state.containerId ||\n    response.organizationId !== plan.state.organizationId ||\n    response.parentId !== plan.state.parentContainerId ||\n    response.manifestHead.epoch !== plan.state.epoch ||\n    response.manifestHead.manifestHash !== plan.manifestHash ||\n    bundle.manifestHash !== plan.manifestHash ||\n    bundle.event.eventHash !== plan.eventHash ||\n    !signedFieldsMatch ||\n    canonicalKeyingJsonString(\n      response.referencedPrincipalHeads,\n      \"Recitation references\",\n    ) !==\n      canonicalKeyingJsonString(\n        plan.manifest.referencedPrincipalHeads,\n        \"Recitation planned references\",\n      )\n  )\n    throw new KeyingVerificationError(\n      \"object_mismatch\",\n      \"Container recitation response does not match the signed plan\",\n    );\n}\n"]}

package/workflows/containers/child/rekey.d.ts

@@ -0,0 +1,32 @@
+import type { ContainerKekKeyringEntry } from "../../../internal/crypto/index.js";
+import type { ContainerWriterProjectionResponse } from "../../../internal/validators/response/index.js";
+import type { ContainerMutationAuthor, MaterializedContainerRekeyPlan } from "../../../data/containers/shared/types.js";
+import { type PrincipalPolicyCache, type ProjectionUserKeyResolver, type ReferencedPrincipalPolicyWarmer } from "../../../data/keyingProjectionVerification.js";
+import type { PrincipalPolicyCurrentEvidence } from "../../../data/principals/principalPolicyEvidence.js";
+import type { ExecSql } from "../../../data/sqlite/sqlSchema.js";
+/**
+ * An explicit container KEK rotation with no membership change. Doubles as
+ * the repair operation: passing `keyringEntriesOverride` seals a keyring
+ * rebuilt from the bridge log instead of re-opening the served one, so a
+ * poisoned snapshot is replaced by ground truth.
+ */
+interface RekeyPlanInput {
+    author: ContainerMutationAuthor;
+    eventId?: string | undefined;
+    execSql: ExecSql;
+    keyringEntriesOverride?: readonly ContainerKekKeyringEntry[] | undefined;
+    /** Keys a batch minted above this container and has yet to commit. */
+    knownContainerKeks?: ReadonlyMap<string, Uint8Array> | undefined;
+    persistVerificationCheckpoints?: boolean | undefined;
+    previousProjection: ContainerWriterProjectionResponse;
+    /** Verified policies the path may cite before they are stored locally. */
+    principalPolicyCache?: PrincipalPolicyCache | undefined;
+    replacementPrincipalPolicy?: PrincipalPolicyCurrentEvidence | undefined;
+    resolveProjectionUserKey: ProjectionUserKeyResolver;
+    signedAt?: string | undefined;
+    stillCurrent?: (() => boolean) | undefined;
+    targetSecretKey: Uint8Array;
+    warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;
+}
+export declare function buildMaterializedContainerRekeyPlan(input: RekeyPlanInput): Promise<MaterializedContainerRekeyPlan>;
+export {};