@tearleads/client-sdk 0.0.0-stage → 0.1.13

package/workflows/organizations/groupPolicyMutationAcknowledgement.js

@@ -0,0 +1,239 @@
+import { computePrincipalContainerGrantRoot, computePrincipalMemberEnvelopesRoot, computePrincipalMembershipRoot, computePrincipalProjectionRoot, computePrincipalStatePayloadCiphertextHash, makeVerifiedPrincipalPolicy, normalizePrincipalContainerGrants, normalizePrincipalProjectionMembers, } from "../../internal/crypto/index.js";
+import { canonicalKeyingJsonString } from "../../data/keyingCanonicalJson.js";
+function sortedCanonicalValues(values, label) {
+    return [...values].sort((left, right) => canonicalKeyingJsonString(left, label).localeCompare(canonicalKeyingJsonString(right, label)));
+}
+export function assertGroupPolicyEnvelopesMatchAcknowledgement(expected, observed) {
+    const normalized = (value) => ({
+        ...value,
+        envelopes: sortedCanonicalValues(value.envelopes, "principal member envelope"),
+    });
+    if (canonicalKeyingJsonString(normalized(expected), "acknowledged group member envelopes") !==
+        canonicalKeyingJsonString(normalized(observed), "observed group member envelopes")) {
+        throw new Error("Group member envelopes changed after acknowledgement");
+    }
+}
+function assertContainerMutationAcknowledgements(input) {
+    if (!input.responses || input.responses.length !== input.requests.length) {
+        throw new Error("Group policy container acknowledgement batch is incomplete");
+    }
+    for (const [index, request] of input.requests.entries()) {
+        const response = input.responses[index];
+        if (!response) {
+            throw new Error("Group policy container acknowledgement batch is incomplete");
+        }
+        const expected = {
+            body: request.body,
+            event: request.event,
+            keyEpoch: request.keyEpoch,
+            manifest: request.manifest,
+            wraps: sortedCanonicalValues(request.wraps, "authored container wrap"),
+        };
+        const observed = {
+            body: response.accessManifest.event.body,
+            event: response.accessManifest.event.event,
+            keyEpoch: response.containerKek.keyEpoch,
+            manifest: response.accessManifest.manifest,
+            wraps: sortedCanonicalValues(response.containerKek.wraps, "stored container wrap"),
+        };
+        if (canonicalKeyingJsonString(observed, "stored group policy container mutation") !==
+            canonicalKeyingJsonString(expected, "authored group policy container mutation")) {
+            throw new Error("Group policy container acknowledgement mismatch");
+        }
+    }
+}
+function historyWithCurrent(bundle) {
+    return [
+        ...bundle.previousStates,
+        {
+            state: bundle.currentState,
+            projection: bundle.currentProjection,
+            grants: bundle.currentGrants,
+        },
+    ];
+}
+function isAuthoredSuccessorConsistent(state, expectedHead, previous) {
+    return (state.principalType === expectedHead.principalType &&
+        state.principalId === expectedHead.principalId &&
+        state.version === expectedHead.version &&
+        state.keyEpoch === expectedHead.keyEpoch &&
+        state.keyFingerprint === expectedHead.keyFingerprint &&
+        state.principalType === previous.principalType &&
+        state.principalId === previous.principalId &&
+        state.version === previous.version + 1 &&
+        state.prevStateHash === previous.stateHash);
+}
+export function buildAcknowledgedGroupPolicyBundle(input) {
+    assertContainerMutationAcknowledgements({
+        requests: input.request.containerMutations ?? [],
+        responses: input.response.containerMutations,
+    });
+    const { createdAt: _payloadCreatedAt, ...observedPayload } = input.response.currentPayload;
+    const expectedPayload = {
+        principalType: input.request.state.principalType,
+        principalId: input.request.state.principalId,
+        stateHash: input.expectedHead.stateHash,
+        ...input.request.encryptedPayload,
+    };
+    if (canonicalKeyingJsonString(observedPayload, "stored group policy payload") !==
+        canonicalKeyingJsonString(expectedPayload, "authored group policy payload") ||
+        canonicalKeyingJsonString(normalizePrincipalProjectionMembers(input.response.currentProjection), "stored group policy projection") !==
+            canonicalKeyingJsonString(normalizePrincipalProjectionMembers(input.request.projection), "authored group policy projection") ||
+        canonicalKeyingJsonString(normalizePrincipalContainerGrants(input.response.currentGrants), "stored group policy grants") !==
+            canonicalKeyingJsonString(normalizePrincipalContainerGrants(input.request.grants), "authored group policy grants")) {
+        throw new Error("Group policy bundle acknowledgement mismatch");
+    }
+    assertGroupPolicyEnvelopesMatchAcknowledgement({
+        principalType: input.request.state.principalType,
+        principalId: input.request.state.principalId,
+        stateHash: input.expectedHead.stateHash,
+        epoch: input.request.state.keyEpoch,
+        envelopes: input.request.memberEnvelopes,
+    }, input.response.currentMemberEnvelopes);
+    return {
+        ...input.response,
+        previousStates: historyWithCurrent(input.currentPolicy),
+    };
+}
+async function assertPolicyRequestCommitments(request) {
+    const projection = normalizePrincipalProjectionMembers(request.projection);
+    const members = projection.map((member) => ({ userId: member.userId }));
+    const [membershipRoot, memberEnvelopesRoot, projectionRoot, payloadCiphertextHash, grantRoot,] = await Promise.all([
+        computePrincipalMembershipRoot(members),
+        computePrincipalMemberEnvelopesRoot(request.memberEnvelopes),
+        computePrincipalProjectionRoot(projection),
+        computePrincipalStatePayloadCiphertextHash(request.encryptedPayload.ciphertext),
+        computePrincipalContainerGrantRoot(request.grants),
+    ]);
+    if (request.state.membershipRoot !== membershipRoot ||
+        request.state.memberEnvelopesRoot !== memberEnvelopesRoot ||
+        request.state.projectionRoot !== projectionRoot ||
+        request.state.memberCount !== projection.length ||
+        request.state.grantRoot !== grantRoot ||
+        request.state.grantCount !== request.grants.length ||
+        request.encryptedPayload.ciphertextHash !== payloadCiphertextHash ||
+        request.state.payloadCiphertextHash !== payloadCiphertextHash) {
+        throw new Error("Authored group policy commitments are invalid");
+    }
+}
+function verifiedPolicy(input) {
+    const previousStates = input.currentPolicy
+        ? historyWithCurrent(input.currentPolicy)
+        : [];
+    return makeVerifiedPrincipalPolicy({
+        checkpoint: {
+            principalId: input.state.principalId,
+            principalType: input.state.principalType,
+            stateHash: input.state.stateHash,
+            version: input.state.version,
+        },
+        history: [
+            ...previousStates,
+            {
+                state: input.state,
+                projection: input.projection,
+                grants: input.grants,
+            },
+        ],
+        keyEpoch: input.state.keyEpoch,
+        principalId: input.state.principalId,
+        principalType: input.state.principalType,
+        projection: input.projection,
+        grants: input.grants,
+        state: input.state,
+        stateHash: input.state.stateHash,
+        version: input.state.version,
+    });
+}
+export async function acknowledgeGroupPolicyState(input) {
+    await assertPolicyRequestCommitments(input.request);
+    const { createdAt: _createdAt, stateHash, ...responseState } = input.response;
+    const previous = input.currentPolicy.currentState;
+    if (stateHash !== input.expectedHead.stateHash ||
+        !isAuthoredSuccessorConsistent(input.response, input.expectedHead, previous) ||
+        canonicalKeyingJsonString(responseState, "stored group policy state") !==
+            canonicalKeyingJsonString(input.request.state, "authored group policy state")) {
+        throw new Error("Group policy state acknowledgement mismatch");
+    }
+    return verifiedPolicy({
+        currentPolicy: input.currentPolicy,
+        projection: input.request.projection,
+        grants: input.request.grants,
+        state: input.response,
+    });
+}
+/**
+ * Materialize the locally signed successor before submission so dependent
+ * container mutations can wrap to the exact head that will commit with it.
+ * The server still performs the authoritative signature, transition, and
+ * authorization checks inside the combined transaction.
+ */
+export async function prepareAuthoredGroupPolicy(input) {
+    await assertPolicyRequestCommitments(input.request);
+    const previous = input.currentPolicy.currentState;
+    const state = input.request.state;
+    if (!isAuthoredSuccessorConsistent(state, input.expectedHead, previous)) {
+        throw new Error("Authored group policy successor is inconsistent");
+    }
+    return verifiedPolicy({
+        currentPolicy: input.currentPolicy,
+        projection: input.request.projection,
+        grants: input.request.grants,
+        state: {
+            ...state,
+            stateHash: input.expectedHead.stateHash,
+            createdAt: state.signedAt,
+        },
+    });
+}
+export async function acknowledgeInitialGroupPolicy(input) {
+    await assertPolicyRequestCommitments(input.request.initialGroupPolicy);
+    const state = input.request.initialGroupPolicy.state;
+    if (input.response.groupId !== input.request.groupId ||
+        input.response.organizationId !== input.organizationId ||
+        input.response.isBuiltin ||
+        input.response.currentState?.stateHash !== input.stateHash ||
+        input.response.currentState.version !== state.version ||
+        input.response.currentState.keyEpoch !== state.keyEpoch ||
+        input.response.currentState.memberCount !== state.memberCount ||
+        state.principalType !== "group" ||
+        state.principalId !== input.request.groupId ||
+        state.version !== 1 ||
+        state.prevStateHash !== null) {
+        throw new Error("Created group policy acknowledgement mismatch");
+    }
+    const storedState = {
+        ...state,
+        createdAt: input.response.createdAt,
+        stateHash: input.stateHash,
+    };
+    const bundle = {
+        currentMemberEnvelopes: {
+            envelopes: input.request.initialGroupPolicy.memberEnvelopes,
+            epoch: state.keyEpoch,
+            principalId: state.principalId,
+            principalType: state.principalType,
+            stateHash: input.stateHash,
+        },
+        currentPayload: {
+            principalId: state.principalId,
+            principalType: state.principalType,
+            stateHash: input.stateHash,
+            ...input.request.initialGroupPolicy.encryptedPayload,
+            createdAt: input.response.createdAt,
+        },
+        currentProjection: input.request.initialGroupPolicy.projection,
+        currentGrants: input.request.initialGroupPolicy.grants,
+        currentState: storedState,
+        previousStates: [],
+    };
+    return {
+        bundle,
+        policy: verifiedPolicy({
+            projection: input.request.initialGroupPolicy.projection,
+            grants: input.request.initialGroupPolicy.grants,
+            state: storedState,
+        }),
+    };
+}
+//# sourceMappingURL=groupPolicyMutationAcknowledgement.js.map

package/workflows/organizations/groupPolicyMutationAcknowledgement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"groupPolicyMutationAcknowledgement.js","sourceRoot":"","sources":["groupPolicyMutationAcknowledgement.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  computePrincipalContainerGrantRoot,\n  computePrincipalMemberEnvelopesRoot,\n  computePrincipalMembershipRoot,\n  computePrincipalProjectionRoot,\n  computePrincipalStatePayloadCiphertextHash,\n  makeVerifiedPrincipalPolicy,\n  normalizePrincipalContainerGrants,\n  normalizePrincipalProjectionMembers,\n  type ReferencedPrincipalHead,\n  type VerifiedPrincipalPolicy,\n} from \"@tearleads/crypto\";\nimport type {\n  CreateOrganizationGroupRequest,\n  PutPrincipalPolicyRequest,\n} from \"@tearleads/validators/request\";\nimport type {\n  ContainerMutationResponse,\n  CurrentPrincipalMemberEnvelopesResponse,\n  OrganizationGroupSummaryResponse,\n  PrincipalPolicyBundleResponse,\n  PrincipalPolicyMutationResponse,\n  PrincipalStateResponse,\n} from \"@tearleads/validators/response\";\nimport { canonicalKeyingJsonString } from \"../../data/keyingCanonicalJson\";\n\nfunction sortedCanonicalValues<T>(values: readonly T[], label: string): T[] {\n  return [...values].sort((left, right) =>\n    canonicalKeyingJsonString(left, label).localeCompare(\n      canonicalKeyingJsonString(right, label),\n    ),\n  );\n}\n\nexport function assertGroupPolicyEnvelopesMatchAcknowledgement(\n  expected: CurrentPrincipalMemberEnvelopesResponse,\n  observed: CurrentPrincipalMemberEnvelopesResponse,\n): void {\n  const normalized = (value: CurrentPrincipalMemberEnvelopesResponse) => ({\n    ...value,\n    envelopes: sortedCanonicalValues(\n      value.envelopes,\n      \"principal member envelope\",\n    ),\n  });\n  if (\n    canonicalKeyingJsonString(\n      normalized(expected),\n      \"acknowledged group member envelopes\",\n    ) !==\n    canonicalKeyingJsonString(\n      normalized(observed),\n      \"observed group member envelopes\",\n    )\n  ) {\n    throw new Error(\"Group member envelopes changed after acknowledgement\");\n  }\n}\n\nfunction assertContainerMutationAcknowledgements(input: {\n  readonly requests: readonly NonNullable<\n    PutPrincipalPolicyRequest[\"containerMutations\"]\n  >[number][];\n  readonly responses: readonly ContainerMutationResponse[] | undefined;\n}): void {\n  if (!input.responses || input.responses.length !== input.requests.length) {\n    throw new Error(\n      \"Group policy container acknowledgement batch is incomplete\",\n    );\n  }\n  for (const [index, request] of input.requests.entries()) {\n    const response = input.responses[index];\n    if (!response) {\n      throw new Error(\n        \"Group policy container acknowledgement batch is incomplete\",\n      );\n    }\n    const expected = {\n      body: request.body,\n      event: request.event,\n      keyEpoch: request.keyEpoch,\n      manifest: request.manifest,\n      wraps: sortedCanonicalValues(request.wraps, \"authored container wrap\"),\n    };\n    const observed = {\n      body: response.accessManifest.event.body,\n      event: response.accessManifest.event.event,\n      keyEpoch: response.containerKek.keyEpoch,\n      manifest: response.accessManifest.manifest,\n      wraps: sortedCanonicalValues(\n        response.containerKek.wraps,\n        \"stored container wrap\",\n      ),\n    };\n    if (\n      canonicalKeyingJsonString(\n        observed,\n        \"stored group policy container mutation\",\n      ) !==\n      canonicalKeyingJsonString(\n        expected,\n        \"authored group policy container mutation\",\n      )\n    ) {\n      throw new Error(\"Group policy container acknowledgement mismatch\");\n    }\n  }\n}\n\nfunction historyWithCurrent(\n  bundle: PrincipalPolicyBundleResponse,\n): PrincipalPolicyBundleResponse[\"previousStates\"] {\n  return [\n    ...bundle.previousStates,\n    {\n      state: bundle.currentState,\n      projection: bundle.currentProjection,\n      grants: bundle.currentGrants,\n    },\n  ];\n}\n\nfunction isAuthoredSuccessorConsistent(\n  state: Pick<\n    PrincipalStateResponse,\n    | \"keyEpoch\"\n    | \"keyFingerprint\"\n    | \"prevStateHash\"\n    | \"principalId\"\n    | \"principalType\"\n    | \"version\"\n  >,\n  expectedHead: ReferencedPrincipalHead,\n  previous: PrincipalStateResponse,\n): boolean {\n  return (\n    state.principalType === expectedHead.principalType &&\n    state.principalId === expectedHead.principalId &&\n    state.version === expectedHead.version &&\n    state.keyEpoch === expectedHead.keyEpoch &&\n    state.keyFingerprint === expectedHead.keyFingerprint &&\n    state.principalType === previous.principalType &&\n    state.principalId === previous.principalId &&\n    state.version === previous.version + 1 &&\n    state.prevStateHash === previous.stateHash\n  );\n}\n\nexport function buildAcknowledgedGroupPolicyBundle(input: {\n  readonly currentPolicy: PrincipalPolicyBundleResponse;\n  readonly expectedHead: ReferencedPrincipalHead;\n  readonly request: PutPrincipalPolicyRequest;\n  readonly response: PrincipalPolicyMutationResponse;\n}): PrincipalPolicyBundleResponse & PrincipalPolicyMutationResponse {\n  assertContainerMutationAcknowledgements({\n    requests: input.request.containerMutations ?? [],\n    responses: input.response.containerMutations,\n  });\n  const { createdAt: _payloadCreatedAt, ...observedPayload } =\n    input.response.currentPayload;\n  const expectedPayload = {\n    principalType: input.request.state.principalType,\n    principalId: input.request.state.principalId,\n    stateHash: input.expectedHead.stateHash,\n    ...input.request.encryptedPayload,\n  };\n\n  if (\n    canonicalKeyingJsonString(\n      observedPayload,\n      \"stored group policy payload\",\n    ) !==\n      canonicalKeyingJsonString(\n        expectedPayload,\n        \"authored group policy payload\",\n      ) ||\n    canonicalKeyingJsonString(\n      normalizePrincipalProjectionMembers(input.response.currentProjection),\n      \"stored group policy projection\",\n    ) !==\n      canonicalKeyingJsonString(\n        normalizePrincipalProjectionMembers(input.request.projection),\n        \"authored group policy projection\",\n      ) ||\n    canonicalKeyingJsonString(\n      normalizePrincipalContainerGrants(input.response.currentGrants),\n      \"stored group policy grants\",\n    ) !==\n      canonicalKeyingJsonString(\n        normalizePrincipalContainerGrants(input.request.grants),\n        \"authored group policy grants\",\n      )\n  ) {\n    throw new Error(\"Group policy bundle acknowledgement mismatch\");\n  }\n\n  assertGroupPolicyEnvelopesMatchAcknowledgement(\n    {\n      principalType: input.request.state.principalType,\n      principalId: input.request.state.principalId,\n      stateHash: input.expectedHead.stateHash,\n      epoch: input.request.state.keyEpoch,\n      envelopes: input.request.memberEnvelopes,\n    },\n    input.response.currentMemberEnvelopes,\n  );\n  return {\n    ...input.response,\n    previousStates: historyWithCurrent(input.currentPolicy),\n  };\n}\n\nasync function assertPolicyRequestCommitments(\n  request: PutPrincipalPolicyRequest,\n): Promise<void> {\n  const projection = normalizePrincipalProjectionMembers(request.projection);\n  const members = projection.map((member) => ({ userId: member.userId }));\n  const [\n    membershipRoot,\n    memberEnvelopesRoot,\n    projectionRoot,\n    payloadCiphertextHash,\n    grantRoot,\n  ] = await Promise.all([\n    computePrincipalMembershipRoot(members),\n    computePrincipalMemberEnvelopesRoot(request.memberEnvelopes),\n    computePrincipalProjectionRoot(projection),\n    computePrincipalStatePayloadCiphertextHash(\n      request.encryptedPayload.ciphertext,\n    ),\n    computePrincipalContainerGrantRoot(request.grants),\n  ]);\n  if (\n    request.state.membershipRoot !== membershipRoot ||\n    request.state.memberEnvelopesRoot !== memberEnvelopesRoot ||\n    request.state.projectionRoot !== projectionRoot ||\n    request.state.memberCount !== projection.length ||\n    request.state.grantRoot !== grantRoot ||\n    request.state.grantCount !== request.grants.length ||\n    request.encryptedPayload.ciphertextHash !== payloadCiphertextHash ||\n    request.state.payloadCiphertextHash !== payloadCiphertextHash\n  ) {\n    throw new Error(\"Authored group policy commitments are invalid\");\n  }\n}\n\nfunction verifiedPolicy(input: {\n  currentPolicy?: PrincipalPolicyBundleResponse | undefined;\n  projection: PutPrincipalPolicyRequest[\"projection\"];\n  grants: PutPrincipalPolicyRequest[\"grants\"];\n  state: PrincipalStateResponse;\n}): VerifiedPrincipalPolicy {\n  const previousStates = input.currentPolicy\n    ? historyWithCurrent(input.currentPolicy)\n    : [];\n  return makeVerifiedPrincipalPolicy({\n    checkpoint: {\n      principalId: input.state.principalId,\n      principalType: input.state.principalType,\n      stateHash: input.state.stateHash,\n      version: input.state.version,\n    },\n    history: [\n      ...previousStates,\n      {\n        state: input.state,\n        projection: input.projection,\n        grants: input.grants,\n      },\n    ],\n    keyEpoch: input.state.keyEpoch,\n    principalId: input.state.principalId,\n    principalType: input.state.principalType,\n    projection: input.projection,\n    grants: input.grants,\n    state: input.state,\n    stateHash: input.state.stateHash,\n    version: input.state.version,\n  });\n}\n\nexport async function acknowledgeGroupPolicyState(input: {\n  readonly currentPolicy: PrincipalPolicyBundleResponse;\n  readonly expectedHead: ReferencedPrincipalHead;\n  readonly request: PutPrincipalPolicyRequest;\n  readonly response: PrincipalStateResponse;\n}): Promise<VerifiedPrincipalPolicy> {\n  await assertPolicyRequestCommitments(input.request);\n  const { createdAt: _createdAt, stateHash, ...responseState } = input.response;\n  const previous = input.currentPolicy.currentState;\n  if (\n    stateHash !== input.expectedHead.stateHash ||\n    !isAuthoredSuccessorConsistent(\n      input.response,\n      input.expectedHead,\n      previous,\n    ) ||\n    canonicalKeyingJsonString(responseState, \"stored group policy state\") !==\n      canonicalKeyingJsonString(\n        input.request.state,\n        \"authored group policy state\",\n      )\n  ) {\n    throw new Error(\"Group policy state acknowledgement mismatch\");\n  }\n  return verifiedPolicy({\n    currentPolicy: input.currentPolicy,\n    projection: input.request.projection,\n    grants: input.request.grants,\n    state: input.response,\n  });\n}\n\n/**\n * Materialize the locally signed successor before submission so dependent\n * container mutations can wrap to the exact head that will commit with it.\n * The server still performs the authoritative signature, transition, and\n * authorization checks inside the combined transaction.\n */\nexport async function prepareAuthoredGroupPolicy(input: {\n  readonly currentPolicy: PrincipalPolicyBundleResponse;\n  readonly expectedHead: ReferencedPrincipalHead;\n  readonly request: PutPrincipalPolicyRequest;\n}): Promise<VerifiedPrincipalPolicy> {\n  await assertPolicyRequestCommitments(input.request);\n  const previous = input.currentPolicy.currentState;\n  const state = input.request.state;\n  if (!isAuthoredSuccessorConsistent(state, input.expectedHead, previous)) {\n    throw new Error(\"Authored group policy successor is inconsistent\");\n  }\n  return verifiedPolicy({\n    currentPolicy: input.currentPolicy,\n    projection: input.request.projection,\n    grants: input.request.grants,\n    state: {\n      ...state,\n      stateHash: input.expectedHead.stateHash,\n      createdAt: state.signedAt,\n    },\n  });\n}\n\nexport async function acknowledgeInitialGroupPolicy(input: {\n  readonly organizationId: string;\n  readonly request: CreateOrganizationGroupRequest;\n  readonly response: OrganizationGroupSummaryResponse;\n  readonly stateHash: string;\n}): Promise<{\n  readonly bundle: PrincipalPolicyBundleResponse;\n  readonly policy: VerifiedPrincipalPolicy;\n}> {\n  await assertPolicyRequestCommitments(input.request.initialGroupPolicy);\n  const state = input.request.initialGroupPolicy.state;\n  if (\n    input.response.groupId !== input.request.groupId ||\n    input.response.organizationId !== input.organizationId ||\n    input.response.isBuiltin ||\n    input.response.currentState?.stateHash !== input.stateHash ||\n    input.response.currentState.version !== state.version ||\n    input.response.currentState.keyEpoch !== state.keyEpoch ||\n    input.response.currentState.memberCount !== state.memberCount ||\n    state.principalType !== \"group\" ||\n    state.principalId !== input.request.groupId ||\n    state.version !== 1 ||\n    state.prevStateHash !== null\n  ) {\n    throw new Error(\"Created group policy acknowledgement mismatch\");\n  }\n  const storedState = {\n    ...state,\n    createdAt: input.response.createdAt,\n    stateHash: input.stateHash,\n  };\n  const bundle: PrincipalPolicyBundleResponse = {\n    currentMemberEnvelopes: {\n      envelopes: input.request.initialGroupPolicy.memberEnvelopes,\n      epoch: state.keyEpoch,\n      principalId: state.principalId,\n      principalType: state.principalType,\n      stateHash: input.stateHash,\n    },\n    currentPayload: {\n      principalId: state.principalId,\n      principalType: state.principalType,\n      stateHash: input.stateHash,\n      ...input.request.initialGroupPolicy.encryptedPayload,\n      createdAt: input.response.createdAt,\n    },\n    currentProjection: input.request.initialGroupPolicy.projection,\n    currentGrants: input.request.initialGroupPolicy.grants,\n    currentState: storedState,\n    previousStates: [],\n  };\n  return {\n    bundle,\n    policy: verifiedPolicy({\n      projection: input.request.initialGroupPolicy.projection,\n      grants: input.request.initialGroupPolicy.grants,\n      state: storedState,\n    }),\n  };\n}\n"]}

package/workflows/organizations/groupPolicyMutationContext.d.ts

@@ -0,0 +1,95 @@
+import type { RequestFailureKind } from "../../internal/api-client/index.js";
+import type { PrincipalPolicyCheckpoint, PrincipalPolicyExternalAuthority, PrincipalPolicySignerPublicKey, ReferencedPrincipalHead, SigningKeyPair } from "../../internal/crypto/index.js";
+import type { CommitOrganizationGroupPolicyRequest, ContainerMutationRequest, CreateOrganizationGroupWithPolicyRequest, PutPrincipalPolicyRequest } from "../../internal/validators/request/index.js";
+import { type CommitOrganizationGroupPolicyResponse, type CreateOrganizationGroupResponse, type CurrentPrincipalMemberEnvelopesResponse, type PrincipalPolicyBundleResponse, type PrincipalPolicyMutationResponse } from "../../internal/validators/response/index.js";
+import type { ExecSql } from "../../data/sqlite/sqlSchema.js";
+import type { TrustedUserIdentityResolver } from "../../data/trustedUserIdentity/index.js";
+import { type VerifiedExternalAdminPolicy } from "../principals/externalAdminPolicy.js";
+export interface PrincipalPolicyReadApi {
+    getCurrentPrincipalPolicy: (principalType: "group" | "organization", principalId: string) => Promise<PrincipalPolicyBundleResponse | null>;
+}
+export interface PrincipalPolicyReadWriteApi extends PrincipalPolicyReadApi {
+    commitOrganizationGroupPolicy: (organizationId: string, groupId: string, input: CommitOrganizationGroupPolicyRequest) => Promise<CommitOrganizationGroupPolicyResponse | null>;
+    /**
+     * Optional status-bearing variant. A rematerialized rotation the server
+     * refuses for stranding a granted path names the descendant rekeys the batch
+     * must carry; without this the refusal is a plain failure.
+     */
+    commitOrganizationGroupPolicyResult?: (organizationId: string, groupId: string, input: CommitOrganizationGroupPolicyRequest, options?: {
+        readonly reportErrors?: boolean | undefined;
+    }) => Promise<{
+        readonly ok: true;
+        readonly data: CommitOrganizationGroupPolicyResponse;
+    } | {
+        readonly ok: false;
+        readonly kind?: RequestFailureKind | undefined;
+        readonly message?: string | undefined;
+        readonly code?: string | undefined;
+        readonly report?: (() => void) | undefined;
+        readonly requiredContainerIds?: readonly string[] | undefined;
+        readonly status: number | null;
+    }>;
+}
+export interface OrganizationPrincipalPolicyApi extends PrincipalPolicyReadApi {
+    createOrganizationGroup: (organizationId: string, input: CreateOrganizationGroupWithPolicyRequest) => Promise<CreateOrganizationGroupResponse | null>;
+}
+export interface BuildGroupMembershipMutationInput {
+    readonly currentPolicy: PrincipalPolicyBundleResponse;
+    readonly currentPolicySignerPublicKeys: readonly PrincipalPolicySignerPublicKey[];
+    readonly currentOrgAdminUserIds?: readonly string[] | undefined;
+    readonly externalAuthority?: PrincipalPolicyExternalAuthority | undefined;
+    readonly isOrganizationAdminsGroup?: boolean | undefined;
+    readonly localPolicyCheckpoint?: PrincipalPolicyCheckpoint | null;
+    readonly signerUserId: string;
+    readonly signingFingerprint: string;
+    readonly signingKeyPair: SigningKeyPair;
+}
+interface LoadedGroupPolicyMutationContext extends BuildGroupMembershipMutationInput {
+    readonly adminGroupId: string;
+    readonly adminPolicyBundle: PrincipalPolicyBundleResponse;
+    readonly currentOrgAdminUserIds: readonly string[];
+    readonly organizationDescriptor: VerifiedExternalAdminPolicy["descriptor"];
+    readonly organizationPolicyBundle: PrincipalPolicyBundleResponse;
+    readonly memberGroupId: string;
+}
+export declare function cacheGroupPolicy(input: {
+    readonly acknowledgedMemberEnvelopes?: CurrentPrincipalMemberEnvelopesResponse | undefined;
+    readonly apiClient: PrincipalPolicyReadApi;
+    readonly externalAuthority?: PrincipalPolicyExternalAuthority | undefined;
+    readonly execSql: ExecSql;
+    readonly expectedCurrentHead?: ReferencedPrincipalHead | undefined;
+    readonly groupId: string;
+    readonly localPolicyCheckpoint?: PrincipalPolicyCheckpoint | null;
+    readonly organizationId: string;
+    readonly resolveTrustedUserIdentity: TrustedUserIdentityResolver;
+    readonly stillCurrent?: (() => boolean) | undefined;
+}): Promise<PrincipalPolicyBundleResponse>;
+export declare function loadGroupPolicyMutationContext(input: {
+    readonly apiClient: PrincipalPolicyReadApi;
+    readonly execSql: ExecSql;
+    readonly groupId: string;
+    readonly organizationId: string;
+    readonly resolveTrustedUserIdentity: TrustedUserIdentityResolver;
+    readonly signerUserId: string;
+    readonly signingFingerprint: string;
+    readonly signingKeyPair: SigningKeyPair;
+}): Promise<LoadedGroupPolicyMutationContext>;
+export declare function commitGroupPolicyMutation(input: {
+    readonly retiredContainerIds?: (() => readonly string[]) | undefined;
+    readonly apiClient: PrincipalPolicyReadWriteApi;
+    readonly currentPolicy: PrincipalPolicyBundleResponse;
+    readonly execSql: ExecSql;
+    readonly expectedHead: ReferencedPrincipalHead;
+    readonly groupId: string;
+    readonly organizationId: string;
+    readonly organizationPolicy: PrincipalPolicyBundleResponse;
+    readonly organizationRequest: PutPrincipalPolicyRequest;
+    /**
+     * Re-sign the batch with the descendant rekeys a refusal named woven in; the
+     * result replaces `containerMutations` and the commit is retried once.
+     */
+    readonly carryDescendantRekeys?: ((requiredContainerIds: readonly string[]) => Promise<readonly ContainerMutationRequest[]>) | undefined;
+    readonly request: PutPrincipalPolicyRequest;
+    readonly stillCurrent?: (() => boolean) | undefined;
+}): Promise<PrincipalPolicyBundleResponse & PrincipalPolicyMutationResponse>;
+export {};

package/workflows/organizations/groupPolicyMutationContext.js

@@ -0,0 +1,228 @@
+import { CONTAINER_MUTATION_ERROR_CODES, } from "../../internal/validators/response/index.js";
+import { persistVerifiedPrincipalPolicyBundlesAtomically } from "../../data/persistence/keyingCheckpointAdvancePersistence.js";
+import { retainLocallyAcknowledgedPrincipalPolicyBundles } from "../../data/persistence/locallyAcknowledgedCheckpointPersistence.js";
+import { requireOrganizationGroupHead } from "../../data/principals/organizationAuthorityDescriptor.js";
+import { externalAdminPolicyPersistenceEntries, loadOrganizationExternalAdminPolicy, } from "../principals/externalAdminPolicy.js";
+import { assertGroupMetadataBinding } from "./groupMetadataBinding.js";
+import { requireSignerCanManageGroup } from "./groupMutationAuthorization.js";
+import { acknowledgeGroupPolicyState, assertGroupPolicyEnvelopesMatchAcknowledgement, buildAcknowledgedGroupPolicyBundle, } from "./groupPolicyMutationAcknowledgement.js";
+import { assertPrincipalPolicyCurrentStateMatchesHead, groupPolicyMutationHead, } from "./groupPolicyMutationHead.js";
+import { collectGroupPolicySignerPublicKeys, prepareGroupPolicyVerification, verifyGroupPolicy, verifyGroupPolicyWithExternalOrganizationAdmins, } from "./groupPolicyVerification.js";
+export async function cacheGroupPolicy(input) {
+    const bundle = await input.apiClient.getCurrentPrincipalPolicy("group", input.groupId);
+    if (!bundle) {
+        throw new Error("Updated group policy could not be loaded");
+    }
+    const signerPublicKeys = await collectGroupPolicySignerPublicKeys({
+        bundle,
+        resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,
+    });
+    const verified = await verifyGroupPolicy({
+        currentPolicy: bundle,
+        ...(input.externalAuthority
+            ? { externalAuthority: input.externalAuthority }
+            : {}),
+        localPolicyCheckpoint: input.localPolicyCheckpoint ?? null,
+        signerPublicKeys,
+    });
+    if (input.expectedCurrentHead) {
+        assertPrincipalPolicyCurrentStateMatchesHead(bundle.currentState, input.expectedCurrentHead);
+    }
+    if (input.acknowledgedMemberEnvelopes) {
+        assertGroupPolicyEnvelopesMatchAcknowledgement(input.acknowledgedMemberEnvelopes, bundle.currentMemberEnvelopes);
+    }
+    await persistVerifiedPrincipalPolicyBundlesAtomically({
+        entries: [{ bundle, policy: verified }],
+        execSql: input.execSql,
+        organizationId: input.organizationId,
+        stillCurrent: input.stillCurrent,
+        updatedAt: new Date().toISOString(),
+    });
+    return bundle;
+}
+export async function loadGroupPolicyMutationContext(input) {
+    const adminPolicy = await loadOrganizationExternalAdminPolicy({
+        execSql: input.execSql,
+        getCurrentPrincipalPolicy: (principalType, principalId) => input.apiClient.getCurrentPrincipalPolicy(principalType, principalId),
+        organizationId: input.organizationId,
+        resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,
+    });
+    if (!adminPolicy) {
+        throw new Error("Organization admin authority could not be verified");
+    }
+    const expectedGroupHead = requireOrganizationGroupHead(adminPolicy.descriptor, input.groupId);
+    const currentPolicy = input.groupId === adminPolicy.adminGroupId
+        ? adminPolicy.adminBundle
+        : await input.apiClient.getCurrentPrincipalPolicy("group", input.groupId);
+    if (!currentPolicy) {
+        throw new Error("Group policy could not be loaded");
+    }
+    assertPrincipalPolicyCurrentStateMatchesHead(currentPolicy.currentState, expectedGroupHead);
+    const verification = await prepareGroupPolicyVerification({
+        currentPolicy,
+        execSql: input.execSql,
+        resolveTrustedUserIdentity: input.resolveTrustedUserIdentity,
+    });
+    const isOrganizationAdminsGroup = adminPolicy.adminGroupId === input.groupId;
+    const currentOrgAdminUserIds = adminPolicy.signerUserIds;
+    const externalAuthority = adminPolicy.externalAuthority;
+    if (!currentOrgAdminUserIds.includes(input.signerUserId)) {
+        throw new Error("Organization admin authority is required");
+    }
+    const verified = isOrganizationAdminsGroup
+        ? await verifyGroupPolicy({
+            currentPolicy,
+            localPolicyCheckpoint: verification.localPolicyCheckpoint,
+            signerPublicKeys: verification.currentPolicySignerPublicKeys,
+        })
+        : await verifyGroupPolicyWithExternalOrganizationAdmins({
+            currentPolicy,
+            loadExternalAuthority: async () => externalAuthority,
+            localPolicyCheckpoint: verification.localPolicyCheckpoint,
+            signerPublicKeys: verification.currentPolicySignerPublicKeys,
+        });
+    assertGroupMetadataBinding(currentPolicy, adminPolicy.descriptor);
+    requireSignerCanManageGroup(currentPolicy, currentOrgAdminUserIds, input.signerUserId);
+    await persistVerifiedPrincipalPolicyBundlesAtomically({
+        entries: [
+            ...externalAdminPolicyPersistenceEntries(adminPolicy).filter((entry) => entry.policy.principalType !== verified.principalType ||
+                entry.policy.principalId !== verified.principalId),
+            { bundle: currentPolicy, policy: verified },
+        ],
+        execSql: input.execSql,
+        organizationId: input.organizationId,
+        updatedAt: new Date().toISOString(),
+    });
+    return {
+        adminGroupId: adminPolicy.adminGroupId,
+        adminPolicyBundle: adminPolicy.adminBundle,
+        currentPolicy,
+        currentOrgAdminUserIds,
+        externalAuthority,
+        isOrganizationAdminsGroup,
+        memberGroupId: adminPolicy.memberGroupId,
+        organizationDescriptor: adminPolicy.descriptor,
+        organizationPolicyBundle: adminPolicy.bundle,
+        ...verification,
+        localPolicyCheckpoint: verified.checkpoint,
+        signerUserId: input.signerUserId,
+        signingFingerprint: input.signingFingerprint,
+        signingKeyPair: input.signingKeyPair,
+    };
+}
+/**
+ * Commit, answering one refusal: a rematerialized rekey or revoke that would
+ * strand a level above a directly granted container is refused with the
+ * descendant rekeys it must carry. The refused attempt rolled back whole, so
+ * the served heads still stand; the batch is signed again with the named
+ * levels woven in, replaces the container mutations, and the commit is retried
+ * once. A second refusal means the tree moved underneath, and the caller's own
+ * retry starts from a fresh policy.
+ */
+async function submitGroupPolicyCommit(input) {
+    const body = () => ({
+        groupPolicy: input.request,
+        organizationPolicy: input.organizationRequest,
+    });
+    const { commitOrganizationGroupPolicyResult } = input.apiClient;
+    if (!commitOrganizationGroupPolicyResult) {
+        return input.apiClient.commitOrganizationGroupPolicy(input.organizationId, input.groupId, body());
+    }
+    const first = await commitOrganizationGroupPolicyResult.call(input.apiClient, input.organizationId, input.groupId, body(), { reportErrors: false });
+    if (first.ok)
+        return first.data;
+    if (first.kind === "cancelled")
+        return null;
+    if (first.kind === "outcome-unknown")
+        throw new Error(first.message ??
+            "Policy request may have committed; refresh before retrying");
+    if (!input.carryDescendantRekeys ||
+        first.code !== CONTAINER_MUTATION_ERROR_CODES.descendantRekeysRequired ||
+        !first.requiredContainerIds?.length) {
+        first.report?.();
+        return null;
+    }
+    let carried;
+    try {
+        carried = await input.carryDescendantRekeys(first.requiredContainerIds);
+    }
+    catch (error) {
+        // The refusal was answerable, and the answer failed: surface both. Once
+        // the generation that owned the attempt is gone, only the failure is
+        // surfaced; a superseded refusal is not an error.
+        if (input.stillCurrent?.() !== false)
+            first.report?.();
+        throw error;
+    }
+    if (input.stillCurrent?.() === false)
+        return null;
+    // Nothing signed means the same refusal again; report the one already had.
+    if (carried.length === 0) {
+        first.report?.();
+        return null;
+    }
+    input.request.containerMutations = [...carried];
+    const second = await commitOrganizationGroupPolicyResult.call(input.apiClient, input.organizationId, input.groupId, body(), { reportErrors: false });
+    if (!second.ok) {
+        if (second.kind === "cancelled")
+            return null;
+        if (second.kind === "outcome-unknown")
+            throw new Error(second.message ??
+                "Policy request may have committed; refresh before retrying");
+        second.report?.();
+        return null;
+    }
+    return second.data;
+}
+export async function commitGroupPolicyMutation(input) {
+    const stored = await submitGroupPolicyCommit(input);
+    if (!stored) {
+        throw new Error("Group policy update failed");
+    }
+    const storedPolicy = stored.groupPolicy;
+    const acknowledgedPolicy = await acknowledgeGroupPolicyState({
+        currentPolicy: input.currentPolicy,
+        expectedHead: input.expectedHead,
+        request: input.request,
+        response: storedPolicy.currentState,
+    });
+    const groupBundle = buildAcknowledgedGroupPolicyBundle({
+        currentPolicy: input.currentPolicy,
+        expectedHead: input.expectedHead,
+        request: input.request,
+        response: storedPolicy,
+    });
+    const organizationHead = await groupPolicyMutationHead(input.organizationRequest);
+    const acknowledgedOrganization = await acknowledgeGroupPolicyState({
+        currentPolicy: input.organizationPolicy,
+        expectedHead: organizationHead,
+        request: input.organizationRequest,
+        response: stored.organizationPolicy.currentState,
+    });
+    const organizationBundle = buildAcknowledgedGroupPolicyBundle({
+        currentPolicy: input.organizationPolicy,
+        expectedHead: organizationHead,
+        request: input.organizationRequest,
+        response: stored.organizationPolicy,
+    });
+    await retainLocallyAcknowledgedPrincipalPolicyBundles({
+        retiredContainers: {
+            containerIds: input.retiredContainerIds?.() ?? [],
+            organizationId: input.organizationId,
+            policy: acknowledgedPolicy,
+        },
+        entries: [
+            { bundle: groupBundle, policy: acknowledgedPolicy },
+            {
+                bundle: organizationBundle,
+                policy: acknowledgedOrganization,
+            },
+        ],
+        execSql: input.execSql,
+        organizationId: input.organizationId,
+        stillCurrent: input.stillCurrent,
+        updatedAt: new Date().toISOString(),
+    });
+    return groupBundle;
+}
+//# sourceMappingURL=groupPolicyMutationContext.js.map