@opengeni/db 3.4.0-canary.2 → 3.6.0

package/src/organization-recovery-schema.ts

@@ -0,0 +1,277 @@
+import {
+  bigint,
+  boolean,
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  primaryKey,
+  text,
+  timestamp,
+  unique,
+  uniqueIndex,
+  uuid,
+} from "drizzle-orm/pg-core";
+import { sql } from "drizzle-orm";
+
+export const organizationRecoveryPolicies = pgTable(
+  "organization_recovery_policies",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    revision: bigint("revision", { mode: "number" }).notNull(),
+    configuredByMembershipId: uuid("configured_by_membership_id").notNull(),
+    configuredByIdentityId: uuid("configured_by_identity_id").notNull(),
+    configuredAt: timestamp("configured_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    idAccount: unique("organization_recovery_policies_id_account_unique").on(
+      table.id,
+      table.accountId,
+    ),
+    accountRevision: unique("organization_recovery_policies_account_revision_unique").on(
+      table.accountId,
+      table.revision,
+    ),
+  }),
+);
+
+export const organizationRecoveryPolicyHeads = pgTable("organization_recovery_policy_heads", {
+  accountId: uuid("account_id").primaryKey(),
+  currentPolicyId: uuid("current_policy_id").notNull().unique(),
+  revision: bigint("revision", { mode: "number" }).notNull(),
+  enabled: boolean("enabled").notNull().default(true),
+  activatedAt: timestamp("activated_at", { withTimezone: true }),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+});
+
+export const organizationRecoveryCustodians = pgTable(
+  "organization_recovery_custodians",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    policyId: uuid("policy_id").notNull(),
+    ordinal: integer("ordinal").notNull(),
+    membershipId: uuid("membership_id").notNull(),
+    canonicalIdentityId: uuid("canonical_identity_id").notNull(),
+    enrolledAt: timestamp("enrolled_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    policyOrdinal: unique("organization_recovery_custodians_policy_ordinal_unique").on(
+      table.policyId,
+      table.ordinal,
+    ),
+    policyMembership: unique("organization_recovery_custodians_policy_membership_unique").on(
+      table.policyId,
+      table.membershipId,
+    ),
+    policyIdentity: unique("organization_recovery_custodians_policy_identity_unique").on(
+      table.policyId,
+      table.canonicalIdentityId,
+    ),
+    accountPolicy: index("organization_recovery_custodians_account_policy_idx").on(
+      table.accountId,
+      table.policyId,
+      table.ordinal,
+    ),
+  }),
+);
+
+export const organizationRecoveryCustodianAcceptances = pgTable(
+  "organization_recovery_custodian_acceptances",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    policyId: uuid("policy_id").notNull(),
+    custodianId: uuid("custodian_id").notNull(),
+    membershipId: uuid("membership_id").notNull(),
+    canonicalIdentityId: uuid("canonical_identity_id").notNull(),
+    authUserId: text("auth_user_id").notNull(),
+    loginBindingId: uuid("login_binding_id").notNull(),
+    membershipAuthorizationRevision: bigint("membership_authorization_revision", {
+      mode: "number",
+    }).notNull(),
+    identityRevision: bigint("identity_revision", { mode: "number" }).notNull(),
+    authRevision: bigint("auth_revision", { mode: "number" }).notNull(),
+    subjectRevision: bigint("subject_revision", { mode: "number" }).notNull(),
+    loginBindingRevision: bigint("login_binding_revision", { mode: "number" }).notNull(),
+    reauthOperationId: uuid("reauth_operation_id").notNull(),
+    acceptedAt: timestamp("accepted_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    current: index("organization_recovery_acceptances_current_idx").on(
+      table.policyId,
+      table.canonicalIdentityId,
+      table.acceptedAt,
+      table.id,
+    ),
+  }),
+);
+
+export const organizationRecoveryOperations = pgTable(
+  "organization_recovery_operations",
+  {
+    id: uuid("id").primaryKey(),
+    accountId: uuid("account_id").notNull(),
+    policyId: uuid("policy_id").notNull(),
+    policyRevision: bigint("policy_revision", { mode: "number" }).notNull(),
+    revision: bigint("revision", { mode: "number" }).notNull().default(1),
+    state: text("state").notNull().default("collecting"),
+    targetMembershipId: uuid("target_membership_id").notNull(),
+    targetIdentityId: uuid("target_identity_id").notNull(),
+    targetAuthUserId: text("target_auth_user_id").notNull(),
+    targetMembershipAuthorizationRevision: bigint("target_membership_authorization_revision", {
+      mode: "number",
+    }).notNull(),
+    targetIdentityRevision: bigint("target_identity_revision", { mode: "number" }).notNull(),
+    targetAuthRevision: bigint("target_auth_revision", { mode: "number" }).notNull(),
+    targetSubjectRevision: bigint("target_subject_revision", { mode: "number" }).notNull(),
+    startedByCustodianId: uuid("started_by_custodian_id").notNull(),
+    startedByIdentityId: uuid("started_by_identity_id").notNull(),
+    quorumAt: timestamp("quorum_at", { withTimezone: true }),
+    executableAt: timestamp("executable_at", { withTimezone: true }),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    notificationBatchId: uuid("notification_batch_id"),
+    notificationCount: integer("notification_count"),
+    notificationDigest: text("notification_digest"),
+    executedAt: timestamp("executed_at", { withTimezone: true }),
+    cancelledAt: timestamp("cancelled_at", { withTimezone: true }),
+    supersededAt: timestamp("superseded_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    oneLive: uniqueIndex("organization_recovery_operations_one_live_idx")
+      .on(table.accountId)
+      .where(sql`${table.state} in ('collecting', 'cooling')`),
+    accountCreated: index("organization_recovery_operations_account_created_idx").on(
+      table.accountId,
+      table.createdAt,
+      table.id,
+    ),
+  }),
+);
+
+export const organizationRecoveryApprovals = pgTable(
+  "organization_recovery_approvals",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    operationId: uuid("operation_id").notNull(),
+    operationRevision: bigint("operation_revision", { mode: "number" }).notNull(),
+    policyId: uuid("policy_id").notNull(),
+    custodianId: uuid("custodian_id").notNull(),
+    membershipId: uuid("membership_id").notNull(),
+    canonicalIdentityId: uuid("canonical_identity_id").notNull(),
+    authUserId: text("auth_user_id").notNull(),
+    loginBindingId: uuid("login_binding_id").notNull(),
+    membershipAuthorizationRevision: bigint("membership_authorization_revision", {
+      mode: "number",
+    }).notNull(),
+    identityRevision: bigint("identity_revision", { mode: "number" }).notNull(),
+    authRevision: bigint("auth_revision", { mode: "number" }).notNull(),
+    subjectRevision: bigint("subject_revision", { mode: "number" }).notNull(),
+    loginBindingRevision: bigint("login_binding_revision", { mode: "number" }).notNull(),
+    custodianAcceptanceId: uuid("custodian_acceptance_id").notNull(),
+    reauthOperationId: uuid("reauth_operation_id").notNull(),
+    approvedAt: timestamp("approved_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    current: index("organization_recovery_approvals_current_idx").on(
+      table.operationId,
+      table.canonicalIdentityId,
+      table.approvedAt,
+      table.id,
+    ),
+  }),
+);
+
+export const organizationRecoveryCommandReceipts = pgTable(
+  "organization_recovery_command_receipts",
+  {
+    accountId: uuid("account_id").notNull(),
+    operationId: uuid("operation_id").notNull(),
+    action: text("action").notNull(),
+    actorMembershipId: uuid("actor_membership_id").notNull(),
+    actorIdentityId: uuid("actor_identity_id").notNull(),
+    inputHash: text("input_hash").notNull(),
+    result: jsonb("result").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    primaryKey: primaryKey({ columns: [table.accountId, table.operationId] }),
+  }),
+);
+
+export const organizationRecoveryEvents = pgTable(
+  "organization_recovery_events",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    policyId: uuid("policy_id"),
+    operationId: uuid("operation_id"),
+    commandOperationId: uuid("command_operation_id"),
+    eventType: text("event_type").notNull(),
+    actorMembershipId: uuid("actor_membership_id"),
+    actorIdentityId: uuid("actor_identity_id"),
+    eventRevision: bigint("event_revision", { mode: "number" }).notNull(),
+    evidence: jsonb("evidence").notNull().default({}),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    commandType: uniqueIndex("organization_recovery_events_command_type_unique")
+      .on(table.accountId, table.commandOperationId, table.eventType)
+      .where(sql`${table.commandOperationId} is not null`),
+  }),
+);
+
+export const organizationRecoveryNotificationOutbox = pgTable(
+  "organization_recovery_notification_outbox",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    policyId: uuid("policy_id").notNull(),
+    operationId: uuid("operation_id").notNull(),
+    batchId: uuid("batch_id").notNull(),
+    recipientMembershipId: uuid("recipient_membership_id").notNull(),
+    recipientIdentityId: uuid("recipient_identity_id").notNull(),
+    audience: text("audience").notNull(),
+    notificationType: text("notification_type").notNull(),
+    idempotencyKey: text("idempotency_key").notNull().unique(),
+    payloadDigest: text("payload_digest").notNull(),
+    payload: jsonb("payload").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    batch: index("organization_recovery_outbox_batch_idx").on(
+      table.operationId,
+      table.batchId,
+      table.id,
+    ),
+  }),
+);
+
+export const organizationRecoveryNotificationAttempts = pgTable(
+  "organization_recovery_notification_attempts",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    outboxId: uuid("outbox_id").notNull(),
+    deliveryId: uuid("delivery_id").notNull(),
+    provider: text("provider").notNull(),
+    claimOwner: text("claim_owner").notNull(),
+    attemptNumber: integer("attempt_number").notNull(),
+    leaseExpiresAt: timestamp("lease_expires_at", { withTimezone: true }).notNull(),
+    phase: text("phase").notNull(),
+    providerMessageId: text("provider_message_id"),
+    errorClass: text("error_class"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    deliveryPhase: unique("organization_recovery_attempts_delivery_phase_unique").on(
+      table.outboxId,
+      table.deliveryId,
+      table.phase,
+    ),
+  }),
+);

package/src/organization-recovery.ts

@@ -0,0 +1,424 @@
+import { sql } from "drizzle-orm";
+import type { Database } from "./database";
+import { rawRows, setSubjectRlsContext, withRlsContext } from "./database";
+import { nestedPostgresSqlState } from "./persistence-errors";
+
+export type OrganizationRecoveryPolicyState =
+  | "pending_acceptance"
+  | "active"
+  | "degraded"
+  | "superseded"
+  | "disabled";
+
+export type OrganizationRecoveryOperationState =
+  | "collecting"
+  | "cooling"
+  | "executed"
+  | "cancelled"
+  | "expired"
+  | "superseded";
+
+export type OrganizationRecoveryActorEvidence = {
+  authorityHash: string;
+  actorEpoch: string;
+};
+
+export type OrganizationRecoveryActorFence = OrganizationRecoveryActorEvidence & {
+  requestId: string;
+};
+
+export type OrganizationRecoveryCapabilities = {
+  configure: boolean;
+  accept: boolean;
+  disable: boolean;
+  start: boolean;
+  approve: boolean;
+  cancel: boolean;
+  execute: boolean;
+};
+
+export type OrganizationRecoveryMemberSummary = {
+  membershipId: string;
+  name: string | null;
+  email: string | null;
+};
+
+export type OrganizationRecoveryOverview = {
+  organizationId: string;
+  availability: "available" | "recovery_unavailable";
+  unavailableReason:
+    | "no_policy"
+    | "pending_acceptance"
+    | "degraded"
+    | "disabled"
+    | "identity_unavailable"
+    | null;
+  recentReauthenticationAt: string | null;
+  eligibleMembers: OrganizationRecoveryMemberSummary[];
+  policy: null | {
+    id: string;
+    organizationId: string;
+    revision: number;
+    state: OrganizationRecoveryPolicyState;
+    createdAt: string;
+    updatedAt: string;
+    custodians: Array<{
+      ordinal: number;
+      membershipId: string;
+      name: string | null;
+      email: string | null;
+      enrollmentState: "pending_acceptance" | "accepted" | "ineligible";
+      acceptedAt: string | null;
+    }>;
+  };
+  operation: null | {
+    id: string;
+    organizationId: string;
+    policyId: string;
+    policyRevision: number;
+    revision: number;
+    state: OrganizationRecoveryOperationState;
+    target: OrganizationRecoveryMemberSummary;
+    approvalCount: number;
+    approvals: Array<{
+      membershipId: string;
+      name: string | null;
+      email: string | null;
+      approvedAt: string;
+    }>;
+    quorumAt: string | null;
+    executableAt: string | null;
+    expiresAt: string;
+    notificationJournaled: boolean;
+    executedAt: string | null;
+    cancelledAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+  };
+  capabilities: OrganizationRecoveryCapabilities;
+};
+
+export type OrganizationRecoveryMutationResult = {
+  replay: boolean;
+  overview: OrganizationRecoveryOverview;
+};
+
+export class OrganizationRecoveryDeniedError extends Error {
+  readonly name = "OrganizationRecoveryDeniedError";
+  readonly code = "organization_recovery_denied";
+}
+
+export class OrganizationRecoveryUnavailableError extends Error {
+  readonly name = "OrganizationRecoveryUnavailableError";
+  readonly code = "recovery_unavailable";
+}
+
+export class OrganizationRecoveryRevisionConflictError extends Error {
+  readonly name = "OrganizationRecoveryRevisionConflictError";
+  readonly code = "organization_recovery_revision_conflict";
+}
+
+export class OrganizationRecoveryOperationReuseError extends Error {
+  readonly name = "OrganizationRecoveryOperationReuseError";
+  readonly code = "organization_recovery_operation_reuse";
+}
+
+function mapOrganizationRecoverySqlError(error: unknown): never {
+  const state = nestedPostgresSqlState(error);
+  if (state === "40001") throw new OrganizationRecoveryRevisionConflictError();
+  if (state === "23505") throw new OrganizationRecoveryOperationReuseError();
+  if (state === "55000") {
+    throw new OrganizationRecoveryUnavailableError(
+      error instanceof Error ? error.message : "Organization recovery is unavailable",
+    );
+  }
+  if (state === "42501" || state === "P0002") {
+    throw new OrganizationRecoveryDeniedError(
+      error instanceof Error ? error.message : "Organization recovery authority denied",
+    );
+  }
+  throw error;
+}
+
+function asOverview(value: unknown): OrganizationRecoveryOverview {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Organization recovery returned an invalid overview");
+  }
+  return value as OrganizationRecoveryOverview;
+}
+
+function asMutationResult(value: unknown): OrganizationRecoveryMutationResult {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Organization recovery returned an invalid mutation result");
+  }
+  const candidate = value as { replay?: unknown; overview?: unknown };
+  if (typeof candidate.replay !== "boolean") {
+    throw new Error("Organization recovery returned an invalid replay result");
+  }
+  return { replay: candidate.replay, overview: asOverview(candidate.overview) };
+}
+
+async function scopedRecoveryJson(
+  db: Database,
+  organizationId: string,
+  actorSubjectId: string,
+  query: (scopedDb: Database) => Promise<unknown>,
+): Promise<OrganizationRecoveryOverview> {
+  try {
+    return await withRlsContext(
+      db,
+      { accountId: organizationId, workspaceId: null },
+      async (scopedDb) => {
+        await setSubjectRlsContext(scopedDb, actorSubjectId);
+        return asOverview(await query(scopedDb));
+      },
+    );
+  } catch (error) {
+    mapOrganizationRecoverySqlError(error);
+  }
+}
+
+async function runRecoveryCommand(
+  db: Database,
+  command: Record<string, unknown> & {
+    organizationId: string;
+    actorSubjectId: string;
+  },
+): Promise<OrganizationRecoveryMutationResult> {
+  try {
+    return await withRlsContext(
+      db,
+      { accountId: command.organizationId, workspaceId: null },
+      async (scopedDb) => {
+        await setSubjectRlsContext(scopedDb, command.actorSubjectId);
+        const [row] = await rawRows<{ result: unknown }>(
+          scopedDb,
+          sql`select organization_recovery_command(${JSON.stringify(command)}::jsonb) as result`,
+        );
+        return asMutationResult(row?.result);
+      },
+    );
+  } catch (error) {
+    mapOrganizationRecoverySqlError(error);
+  }
+}
+
+export async function getOrganizationRecoveryOverview(
+  db: Database,
+  input: {
+    organizationId: string;
+    actorSubjectId: string;
+    actorAuthUserId: string;
+    actorAuthSessionId: string;
+    actorFence: OrganizationRecoveryActorEvidence | null;
+  },
+): Promise<OrganizationRecoveryOverview> {
+  return await scopedRecoveryJson(
+    db,
+    input.organizationId,
+    input.actorSubjectId,
+    async (scopedDb) => {
+      const [row] = await rawRows<{ result: unknown }>(
+        scopedDb,
+        sql`select get_organization_recovery_overview(
+          ${input.organizationId}::uuid, ${input.actorSubjectId},
+          ${input.actorFence ? JSON.stringify(input.actorFence) : null}::jsonb,
+          ${input.actorAuthSessionId}, ${input.actorAuthUserId}
+        ) as result`,
+      );
+      return row?.result;
+    },
+  );
+}
+
+type RecoveryMutationBase = {
+  organizationId: string;
+  actorSubjectId: string;
+  actorAuthUserId: string;
+  actorAuthSessionId: string;
+  operationId: string;
+  actorFence: OrganizationRecoveryActorFence;
+};
+
+export type OrganizationRecoveryNotificationClaim = {
+  attemptId: string;
+  outboxId: string;
+  deliveryId: string;
+  provider: string;
+  claimOwner: string;
+  attemptNumber: number;
+  leaseExpiresAt: string;
+  idempotencyKey: string;
+  recipientCanonicalIdentityId: string;
+  notificationType: "recovery_quorum_started";
+  payloadDigest: string;
+  payload: Record<string, unknown>;
+};
+
+export type OrganizationRecoveryNotificationSettlement = {
+  outboxId: string;
+  deliveryId: string;
+  claimOwner: string;
+  attemptNumber: number;
+  phase: "sent" | "failed" | "outcome_unknown";
+  providerMessageId: string | null;
+  errorClass: string | null;
+  settledAt: string;
+  replay: boolean;
+};
+
+export type OrganizationRecoveryNotificationReconciliation = {
+  outboxId: string;
+  deliveryId: string;
+  reconciliationOwner: string;
+  attemptNumber: number;
+  resolution: "sent" | "retry";
+  providerMessageId: string | null;
+  reconciledAt: string;
+  replay: boolean;
+};
+
+function asObject<T>(value: unknown, label: string): T {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Organization recovery returned invalid ${label}`);
+  }
+  return value as T;
+}
+
+export async function prepareOrganizationRecoveryNotifications(
+  db: Database,
+  input: {
+    provider: string;
+    claimOwner: string;
+    limit: number;
+    leaseSeconds: number;
+  },
+): Promise<OrganizationRecoveryNotificationClaim[]> {
+  const [row] = await rawRows<{ result: unknown }>(
+    db,
+    sql`select prepare_organization_recovery_notifications(
+      ${input.provider}, ${input.claimOwner}, ${input.limit}::integer,
+      ${input.leaseSeconds}::integer
+    ) as result`,
+  );
+  if (!Array.isArray(row?.result)) {
+    throw new Error("Organization recovery returned invalid notification claims");
+  }
+  return row.result as OrganizationRecoveryNotificationClaim[];
+}
+
+export const claimOrganizationRecoveryNotifications = prepareOrganizationRecoveryNotifications;
+
+export async function settleOrganizationRecoveryNotification(
+  db: Database,
+  input: {
+    outboxId: string;
+    deliveryId: string;
+    claimOwner: string;
+    phase: "sent" | "failed" | "outcome_unknown";
+    providerMessageId?: string | null;
+    errorClass?: string | null;
+  },
+): Promise<OrganizationRecoveryNotificationSettlement> {
+  const [row] = await rawRows<{ result: unknown }>(
+    db,
+    sql`select settle_organization_recovery_notification(
+      ${input.outboxId}::uuid, ${input.deliveryId}::uuid, ${input.claimOwner},
+      ${input.phase}, ${input.providerMessageId ?? null}, ${input.errorClass ?? null}
+    ) as result`,
+  );
+  return asObject<OrganizationRecoveryNotificationSettlement>(
+    row?.result,
+    "notification settlement",
+  );
+}
+
+export async function reconcileOrganizationRecoveryNotification(
+  db: Database,
+  input: {
+    outboxId: string;
+    deliveryId: string;
+    reconciliationOwner: string;
+    resolution: "sent" | "retry";
+    providerMessageId?: string | null;
+  },
+): Promise<OrganizationRecoveryNotificationReconciliation> {
+  const [row] = await rawRows<{ result: unknown }>(
+    db,
+    sql`select reconcile_organization_recovery_notification(
+      ${input.outboxId}::uuid, ${input.deliveryId}::uuid,
+      ${input.reconciliationOwner}, ${input.resolution},
+      ${input.providerMessageId ?? null}
+    ) as result`,
+  );
+  return asObject<OrganizationRecoveryNotificationReconciliation>(
+    row?.result,
+    "notification reconciliation",
+  );
+}
+
+export async function configureOrganizationRecoveryPolicy(
+  db: Database,
+  input: RecoveryMutationBase & {
+    expectedPolicyRevision: number;
+    custodianMembershipIds: [string, string, string];
+  },
+): Promise<OrganizationRecoveryMutationResult> {
+  return await runRecoveryCommand(db, { action: "configure_policy", ...input });
+}
+
+export async function acceptOrganizationRecoveryCustody(
+  db: Database,
+  input: RecoveryMutationBase & { expectedPolicyRevision: number },
+): Promise<OrganizationRecoveryMutationResult> {
+  return await runRecoveryCommand(db, { action: "accept_custody", ...input });
+}
+
+export async function disableOrganizationRecoveryPolicy(
+  db: Database,
+  input: RecoveryMutationBase & { expectedPolicyRevision: number },
+): Promise<OrganizationRecoveryMutationResult> {
+  return await runRecoveryCommand(db, { action: "disable_policy", ...input });
+}
+
+export async function startOrganizationRecoveryOperation(
+  db: Database,
+  input: RecoveryMutationBase & {
+    expectedPolicyRevision: number;
+    targetMembershipId: string;
+  },
+): Promise<OrganizationRecoveryMutationResult> {
+  return await runRecoveryCommand(db, { action: "start_operation", ...input });
+}
+
+type RecoveryOperationMutation = RecoveryMutationBase & {
+  recoveryOperationId: string;
+  expectedOperationRevision: number;
+};
+
+export async function approveOrganizationRecoveryOperation(
+  db: Database,
+  input: RecoveryOperationMutation,
+): Promise<OrganizationRecoveryMutationResult> {
+  return await runRecoveryCommand(db, {
+    action: "approve_operation",
+    ...input,
+  });
+}
+
+export async function cancelOrganizationRecoveryOperation(
+  db: Database,
+  input: RecoveryOperationMutation,
+): Promise<OrganizationRecoveryMutationResult> {
+  return await runRecoveryCommand(db, { action: "cancel_operation", ...input });
+}
+
+export async function executeOrganizationRecoveryOperation(
+  db: Database,
+  input: RecoveryOperationMutation,
+): Promise<OrganizationRecoveryMutationResult> {
+  return await runRecoveryCommand(db, {
+    action: "execute_operation",
+    ...input,
+  });
+}