@openlup/platform 0.15.0 → 0.17.0

package/src/identity/adminAuthorization.ts

@@ -0,0 +1,106 @@
+import type { HttpResponse, HttpRequest } from "../http/index.js";
+import type { ManagedIdentityClient } from "./managedClient.js";
+import { createIdentityResponder, type IdentityResponseOptions } from "./response.js";
+export type AdminRole = "admin" | "distributor";
+
+/** Authorization outcome: a resolved admin `userId`, or a typed denial. */
+export type AdminAuthorization =
+  | { ok: true; userId: string; role: AdminRole; isMachineActor: boolean }
+  | { ok: false; code: "UNAUTHORIZED" | "FORBIDDEN"; message: string; identityCode?: string };
+
+/** A request-bound thunk that resolves the calling admin (or a denial). */
+export type AuthorizeAdmin = () => Promise<AdminAuthorization>;
+
+export async function authorizeAdminWithUser(
+  rawClient: unknown,
+  accessToken: string | null,
+  options: { allowedRoles?: readonly AdminRole[] } = {},
+): Promise<AdminAuthorization> {
+  const client = rawClient as ManagedIdentityClient;
+  if (!accessToken) {
+    return { ok: false, code: "UNAUTHORIZED", message: "Admin session required" };
+  }
+
+  const { data: userData, error: userError } = await client.auth.getUser(accessToken);
+  if (userError || !userData.user) {
+    return { ok: false, code: "UNAUTHORIZED", message: "Admin session required" };
+  }
+
+  const { data, error } = await client
+    .from("admin_users")
+    .select("id, role, is_machine_actor")
+    .eq("id", userData.user.id)
+    .eq("membership_state", "active")
+    .maybeSingle();
+  if (error) throw error;
+  if (!data) {
+    return { ok: false, code: "FORBIDDEN", message: "Admin role required" };
+  }
+
+  const role = normalizeAdminRole(data.role);
+  if (role === null || (options.allowedRoles && !options.allowedRoles.includes(role))) {
+    return { ok: false, code: "FORBIDDEN", message: "Admin role required" };
+  }
+
+  // Fail closed: mirror the activate RPC's `COALESCE(is_machine_actor, true)` — only an
+  // explicit `false` is a human actor; anything else is treated as a machine. The DB row
+  // (`admin_users.is_machine_actor`, re-derived here and in every write RPC) is the single
+  // source of truth for actor kind — never trusted from the caller.
+  return {
+    ok: true,
+    userId: userData.user.id,
+    role,
+    isMachineActor: data.is_machine_actor !== false,
+  };
+}
+
+export function authorizeCommerceAdminWithUser(
+  client: unknown,
+  accessToken: string | null,
+): Promise<AdminAuthorization> {
+  return authorizeAdminWithUser(client, accessToken, { allowedRoles: ["admin"] });
+}
+
+export async function authorizeAdminBooleanWithUser(
+  client: unknown,
+  accessToken: string | null,
+  options: { allowedRoles?: readonly AdminRole[] } = {},
+): Promise<boolean> {
+  const authorization = await authorizeAdminWithUser(client, accessToken, options);
+  return authorization.ok;
+}
+
+/**
+ * Shared authz gate: returns the resolved admin (`userId` + DB-derived
+ * `isMachineActor`) or sends the error envelope and returns null.
+ */
+export async function resolveAdmin(
+  authorizeAdmin: AuthorizeAdmin,
+  res: HttpResponse,
+  options: IdentityResponseOptions = {},
+): Promise<{ userId: string; role: AdminRole; isMachineActor: boolean } | null> {
+  const { sendBffError } = createIdentityResponder(options);
+  let authz: AdminAuthorization;
+  try {
+    authz = await authorizeAdmin();
+  } catch {
+    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+    return null;
+  }
+  if (authz.ok === false) {
+    sendBffError(res, authz.code, authz.message);
+    return null;
+  }
+  return { userId: authz.userId, role: authz.role, isMachineActor: authz.isMachineActor };
+}
+
+function normalizeAdminRole(role: unknown): AdminRole | null {
+  return role === "admin" || role === "distributor" ? role : null;
+}
+export function readBearerToken(req: HttpRequest): string | null {
+  const raw = req.headers.authorization;
+  const value = Array.isArray(raw) ? raw[0] : raw;
+  const match = value?.match(/^Bearer\s+(.+)$/i);
+  return match?.[1]?.trim() || null;
+}
+

package/src/identity/adminContracts.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+z.config({ jitless: true });
+export const adminUserRoleSchema = z.enum(["admin", "distributor"]);
+
+export const adminPlatformMeRequestSchema = z.object({}).strict();
+
+export const adminPlatformMeResponseSchema = z.object({
+  isAdmin: z.boolean(),
+  role: adminUserRoleSchema.nullable(),
+});
+
+export const adminUserRoleUpdateRequestSchema = z.object({
+  userId: z.string().min(1),
+  role: adminUserRoleSchema,
+});
+
+export const adminUserRoleUpdateResponseSchema = z.object({
+  userId: z.string().min(1),
+  role: adminUserRoleSchema,
+  saved: z.literal(true),
+});
+
+export const adminUserInviteRequestSchema = z.object({
+  email: z.string().trim().email().toLowerCase(),
+  role: adminUserRoleSchema,
+});
+
+export const adminUserInviteResponseSchema = z.discriminatedUnion("membershipState", [z.object({
+  principalId: z.string().min(1),
+  invitationId: z.string().min(1),
+  membershipState: z.literal("invited"),
+  role: adminUserRoleSchema,
+  invitedAt: z.iso.datetime(),
+  expiresAt: z.iso.datetime(),
+  code: z.enum(["INVITATION_CREATED", "ALREADY_INVITED", "INVITATION_REISSUED"]),
+  message: z.string().optional(),
+}), z.object({
+  principalId: z.string().min(1),
+  membershipState: z.literal("active"),
+  role: adminUserRoleSchema,
+  code: z.enum(["MEMBERSHIP_CREATED", "ALREADY_ACTIVE"]),
+  message: z.string().optional(),
+})]);
+
+export const adminUserRemoveRequestSchema = z.object({
+  userId: z.string().min(1),
+});
+
+export const adminUserRemoveResponseSchema = z.object({
+  revoked: z.literal(true),
+});
+

package/src/identity/adminMagicLinkHandler.ts

@@ -0,0 +1,132 @@
+import { createMagicLinkOriginResolver } from "./authVerifyUrl.js";
+import { createIdentityResponder, type IdentityResponseOptions } from "./response.js";
+import type { z } from "zod";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { MagicLinkAuthClient, MagicLinkRateLimitClient, MagicLinkDecision } from "./magicLinkPorts.js";
+export interface AdminMagicLinkHandlerOptions extends IdentityResponseOptions {
+  requestSchema: z.ZodType<{ email: string }>;
+  responseSchema: z.ZodType<{ accepted: true }>;
+  readEnvironment: () => { url: string; anonKey: string; serviceRoleKey: string } | null;
+  createRuntime: (env: { url: string; anonKey: string; serviceRoleKey: string }) => {
+    authClient: MagicLinkAuthClient;
+    rateLimitClient: MagicLinkRateLimitClient;
+    platformPort: { checkAdminMagicLinkEligibility(email: string): Promise<string> };
+  };
+  checkAttempt: (input: { client: MagicLinkRateLimitClient; ip: string; email: string }) => Promise<MagicLinkDecision>;
+  extractClientIp: (headers: HttpRequest["headers"]) => string;
+  padResponseTime: (startedAt: number, floor: number) => Promise<void>;
+  redirectOrigins?: readonly string[];
+  resolveOrigin?: (req: HttpRequest) => string | null;
+  callbackPath: string;
+}
+const ADMIN_MAGIC_LINK_RESPONSE_FLOOR_MS = 400;
+export function createAdminMagicLinkHandler(options: AdminMagicLinkHandlerOptions) {
+const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createIdentityResponder(options);
+const readRequestOrigin = options.resolveOrigin ?? createMagicLinkOriginResolver(options.redirectOrigins ?? []);
+const { requestSchema: adminMagicLinkRequestSchema, responseSchema: adminMagicLinkResponseSchema, readEnvironment: readSupabaseAdminServiceEnv, createRuntime: createAdminMagicLinkRuntime, checkAttempt: checkAndRecordAdminMagicLinkAttempt, extractClientIp, padResponseTime } = options;
+return async (req: HttpRequest, res: HttpResponse): Promise<void> => {
+  if (req.method !== "POST") {
+    sendMethodNotAllowed(res, ["POST"]);
+    return;
+  }
+
+  const request = adminMagicLinkRequestSchema.safeParse(req.body);
+  if (!request.success) {
+    sendBffError(res, "BAD_REQUEST", "Invalid admin magic-link request", {
+      details: request.error.flatten(),
+    });
+    return;
+  }
+
+  const startedAt = Date.now();
+  const origin = readRequestOrigin(req);
+  if (!origin) {
+    await padResponseTime(startedAt, ADMIN_MAGIC_LINK_RESPONSE_FLOOR_MS);
+    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Magic link origin is not configured", {
+      details: { reason: "magic_link_origin_not_configured" },
+    });
+    return;
+  }
+
+  const env = readSupabaseAdminServiceEnv();
+  if (!env) {
+    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin auth is not configured", {
+      details: { feature: "admin_auth", requiredEnv: "SUPABASE_SERVICE_ROLE_KEY" },
+    });
+    return;
+  }
+
+  const runtime = createAdminMagicLinkRuntime(env);
+
+  const decision = await checkAndRecordAdminMagicLinkAttempt({
+    client: runtime.rateLimitClient,
+    ip: extractClientIp(req.headers),
+    email: request.data.email,
+  });
+
+  if (!decision.allowed && decision.reason === "rpc_error") {
+    console.warn("admin_magic_link_rate_limit_unavailable", JSON.stringify({ reason: decision.reason }));
+    await padResponseTime(startedAt, ADMIN_MAGIC_LINK_RESPONSE_FLOOR_MS);
+    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Magic link service temporarily unavailable");
+    return;
+  }
+
+  if (decision.allowed) {
+    let eligibility: Awaited<ReturnType<typeof runtime.platformPort.checkAdminMagicLinkEligibility>>;
+    try {
+      eligibility = await runtime.platformPort.checkAdminMagicLinkEligibility(request.data.email);
+    } catch {
+      console.warn("admin_magic_link_lookup_failed", JSON.stringify({ outcome: "lookup_error" }));
+      await padResponseTime(startedAt, ADMIN_MAGIC_LINK_RESPONSE_FLOOR_MS);
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Magic link service temporarily unavailable");
+      return;
+    }
+
+    if (eligibility === "eligible") {
+      const outcome = await sendMagicLink(runtime.authClient, request.data.email, origin);
+      console.info(
+        "admin_magic_link_outcome",
+        JSON.stringify({ outcome: outcome.status, code: outcome.code ?? null }),
+      );
+    } else {
+      console.warn("admin_magic_link_outcome", JSON.stringify({ outcome: eligibility }));
+    }
+  } else {
+    console.warn(
+      "admin_magic_link_outcome",
+      JSON.stringify({ outcome: "rate_limited", reason: decision.reason ?? "unknown" }),
+    );
+  }
+
+  await padResponseTime(startedAt, ADMIN_MAGIC_LINK_RESPONSE_FLOOR_MS);
+  sendBffSuccess(res, adminMagicLinkResponseSchema.parse({ accepted: true }));
+};
+
+async function sendMagicLink(
+  client: MagicLinkAuthClient,
+  email: string,
+  origin: string,
+): Promise<{ status: "sent" | "auth_error" | "threw"; code?: string }> {
+  try {
+    const { error } = await client.auth.signInWithOtp({
+      email,
+      options: {
+        shouldCreateUser: false,
+        emailRedirectTo: `${origin}${options.callbackPath}`,
+      },
+    });
+
+    if (error) {
+      console.warn("admin_magic_link_send_failed", JSON.stringify({ code: error.name ?? "AuthError" }));
+      return { status: "auth_error", code: error.name ?? "AuthError" };
+    }
+    return { status: "sent" };
+  } catch (error) {
+    const code = error instanceof Error ? error.name : "unknown";
+    console.warn("admin_magic_link_send_threw", JSON.stringify({ error: code }));
+    return { status: "threw", code };
+  }
+}
+
+
+}

package/src/identity/adminMeHandler.ts

@@ -0,0 +1,64 @@
+import type { OperatorInvitationStore } from "./operatorInvitationPorts.js";
+import { createIdentityResponder, type IdentityResponseOptions } from "./response.js";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import { adminPlatformMeRequestSchema, adminPlatformMeResponseSchema } from "./adminContracts.js";
+import type { PlatformUserAuthenticationResult } from "./platformAdminAuth.js";
+export interface AdminPlatformMeDeps extends IdentityResponseOptions {
+  invitationStore?: Pick<OperatorInvitationStore, "acceptOperatorInvitation">;
+  platformPort: { getAdminMe(userId: string): Promise<{ isAdmin: boolean; role: "admin" | "distributor" | null }> };
+  authenticateUser: (req: HttpRequest) => Promise<PlatformUserAuthenticationResult>;
+}
+
+export function createAdminPlatformMeHandler({
+  platformPort, invitationStore,
+  authenticateUser, responseRequestId,
+}: AdminPlatformMeDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createIdentityResponder({ responseRequestId });
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "GET") {
+      sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+
+    let authentication: PlatformUserAuthenticationResult;
+    try {
+      authentication = await authenticateUser(req);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Platform user authentication failed");
+      return;
+    }
+
+    if (authentication.ok === false) {
+      sendBffError(res, authentication.code, authentication.message);
+      return;
+    }
+
+    const request = adminPlatformMeRequestSchema.safeParse(req.query);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid platform me request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      if (invitationStore) {
+        const outcome = await invitationStore.acceptOperatorInvitation(authentication.userId);
+        if (outcome.code === "INVITATION_EXPIRED" || outcome.code === "INVITATION_REVOKED") {
+          sendBffError(res, "FORBIDDEN", outcome.code, { details: { identityCode: outcome.code } });
+          return;
+        }
+      }
+      const result = await platformPort.getAdminMe(authentication.userId);
+      const response = adminPlatformMeResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Platform me returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Platform me read failed");
+    }
+  };
+}

package/src/identity/adminPreflight.ts

@@ -0,0 +1,46 @@
+import { createIdentityResponder, type IdentityResponseOptions } from "./response.js";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { AdminAuthPort, AdminPrincipalRole } from "./ports.js";
+import { readBearerToken } from "./adminAuthorization.js";
+import { refusesMachineActorRequest, sendMachineActorWriteRefused } from "./machineActorWriteFence.js";
+
+export interface AdminAuthBinding {
+  readonly identity: string;
+  run<T>(accessToken: string | null, work: (auth: AdminAuthPort) => Promise<T>): Promise<T>;
+}
+export function createAdminBffPreflight(options: IdentityResponseOptions & {
+  allowedRoles: (route: string) => readonly AdminPrincipalRole[] | null;
+  resolveBinding: () => { binding?: AdminAuthBinding; error?: string };
+  machineWriteRoutes?: readonly string[];
+  managedEnvironmentMessage?: string;
+}) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createIdentityResponder(options);
+  return async (req: HttpRequest, res: HttpResponse, route: string): Promise<boolean> => {
+    const allowedRoles = options.allowedRoles(route);
+    if (!allowedRoles) return true;
+    const resolved = options.resolveBinding();
+    if (!resolved.binding) {
+      if (resolved.error === "managed_admin_auth_env_required") {
+        sendBffError(res, "INTERNAL", options.managedEnvironmentMessage ?? "Identity environment is not configured");
+      } else sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+      return false;
+    }
+    const accessToken = readBearerToken(req);
+    try {
+      const authz = await resolved.binding.run(accessToken, (auth) => auth.authorize(accessToken, { allowedRoles }));
+      if (authz.ok === false) {
+        sendBffError(res, authz.code, authz.message);
+        return false;
+      }
+      if (resolved.binding.identity !== "node-postgres"
+        && refusesMachineActorRequest(route, req.method, authz.isMachineActor, options.machineWriteRoutes)) {
+        sendMachineActorWriteRefused(res, options);
+        return false;
+      }
+      return true;
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+      return false;
+    }
+  };
+}

package/src/identity/adminUserActionPorts.ts

@@ -0,0 +1,78 @@
+import { adminUserInviteResponseSchema } from "./adminContracts.js";
+import type { IdentityAdminActionsPort } from "./adminUserHandlers.js";
+import type { runInviteAdminUserUseCase } from "./inviteAdminUserUseCase.js";
+import type { runRemoveAdminUserUseCase } from "./removeAdminUserUseCase.js";
+export interface AdminUserInviteErrorDetails {
+  identityCode?: string;
+  invitationId?: string;
+  principalId?: string;
+  membershipState?: "active";
+  role?: "admin" | "distributor";
+}
+type AdminUserActionRuntimeEnv = Record<string, string | undefined>;
+type AdminUserInviteRunner = (request: { accessToken: string | null; email: string; role: "admin" | "distributor" }, env?: AdminUserActionRuntimeEnv) => ReturnType<typeof runInviteAdminUserUseCase>;
+type AdminUserRemoveRunner = (request: { accessToken: string | null; userId: string }, env?: AdminUserActionRuntimeEnv) => ReturnType<typeof runRemoveAdminUserUseCase>;
+export function createAdminUserInvitePort(options: {
+  accessToken: string | null;
+  env?: AdminUserActionRuntimeEnv;
+  runInviteAdminUser: AdminUserInviteRunner;
+}): Pick<IdentityAdminActionsPort, "inviteAdminUser"> {
+  const runInviteAdminUser = options.runInviteAdminUser;
+  return {
+    async inviteAdminUser(request) {
+      const result = await runInviteAdminUser({
+        accessToken: options.accessToken,
+        email: request.email,
+        role: request.role,
+      }, options.env);
+      if (result.status < 200 || result.status >= 300) {
+        const details: AdminUserInviteErrorDetails = {
+          identityCode: result.body.code,
+          ...(typeof result.body.invitationId === "string" ? { invitationId: result.body.invitationId } : {}),
+          ...(result.body.membershipState === "active" && typeof result.body.principalId === "string"
+            && (result.body.role === "admin" || result.body.role === "distributor")
+            ? { principalId: result.body.principalId, membershipState: "active", role: result.body.role } : {}),
+        };
+        throw Object.assign(new Error(String(result.body.error ?? `invite_admin_user_http_${result.status}`)), { bffCode: ({ 400: "BAD_REQUEST", 401: "UNAUTHORIZED", 403: "FORBIDDEN", 409: "CONFLICT" } as Record<number, string>)[result.status] ?? "UPSTREAM_UNAVAILABLE", inviteDetails: details });
+      }
+      if (result.body.error) throw new Error(result.body.error);
+
+      return adminUserInviteResponseSchema.parse(result.body);
+    },
+  };
+}
+
+export function createAdminUserRemovePort(options: {
+  accessToken: string | null;
+  env?: AdminUserActionRuntimeEnv;
+  runRemoveAdminUser: AdminUserRemoveRunner;
+}): Pick<IdentityAdminActionsPort, "removeAdminUser"> {
+  const runRemoveAdminUser = options.runRemoveAdminUser;
+  return {
+    async removeAdminUser(request) {
+      const result = await runRemoveAdminUser({
+        accessToken: options.accessToken,
+        userId: request.userId,
+      }, options.env);
+      if (result.status < 200 || result.status >= 300) {
+        throw removePortError(
+          result.status,
+          String(result.body.error ?? `remove_admin_user_http_${result.status}`),
+        );
+      }
+      if (result.body.error) throw new Error(result.body.error);
+
+      if (result.body.revoked !== true) {
+        throw new Error("admin_revoke_admin_user returned an invalid response");
+      }
+      return { revoked: true };
+    },
+  };
+}
+
+function removePortError(status: number, message: string): Error {
+  const bffCode = ({ 400: "BAD_REQUEST", 403: "FORBIDDEN", 409: "CONFLICT" } as const)[status]
+    ?? "UPSTREAM_UNAVAILABLE";
+  return Object.assign(new Error(message), { bffCode });
+}
+

package/src/identity/adminUserHandlers.ts

@@ -0,0 +1,174 @@
+import type { AdminUserInviteErrorDetails } from "./adminUserActionPorts.js";
+import { createIdentityResponder, type IdentityResponseOptions } from "./response.js";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import { adminUserRoleUpdateRequestSchema, adminUserRoleUpdateResponseSchema, adminUserInviteRequestSchema, adminUserInviteResponseSchema, adminUserRemoveRequestSchema, adminUserRemoveResponseSchema } from "./adminContracts.js";
+import type { PlatformAdminAuthorizationResult } from "./platformAdminAuth.js";
+import type { OperatorInviteResult } from "./contracts/operatorInvitations.js";
+export interface IdentityAdminActionsPort {
+  inviteAdminUser(request: { email: string; role: "admin" | "distributor" }): Promise<OperatorInviteResult>;
+  removeAdminUser(request: { userId: string }): Promise<{ revoked: true }>;
+  updateAdminUserRole(request: { userId: string; role: "admin" | "distributor" }): Promise<{ userId: string; role: "admin" | "distributor"; saved: true }>;
+}
+export interface AdminUserRoleUpdateDeps extends IdentityResponseOptions { settingsPort: Pick<IdentityAdminActionsPort, "updateAdminUserRole">; authorizeAdmin: (req: HttpRequest) => Promise<PlatformAdminAuthorizationResult> }
+export interface AdminUserInviteDeps extends IdentityResponseOptions { settingsPort: Pick<IdentityAdminActionsPort, "inviteAdminUser">; authorizeAdmin: (req: HttpRequest) => Promise<PlatformAdminAuthorizationResult> }
+export interface AdminUserRemoveDeps extends IdentityResponseOptions { settingsPort: Pick<IdentityAdminActionsPort, "removeAdminUser">; authorizeAdmin: (req: HttpRequest) => Promise<PlatformAdminAuthorizationResult> }
+export function createAdminUserRoleUpdateHandler({
+  settingsPort,
+  authorizeAdmin, responseRequestId,
+}: AdminUserRoleUpdateDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createIdentityResponder({ responseRequestId });
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res, ["POST"]);
+      return;
+    }
+
+    let authorization: PlatformAdminAuthorizationResult;
+    try {
+      authorization = await authorizeAdmin(req);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+      return;
+    }
+
+    if (authorization.ok === false) {
+      sendBffError(res, authorization.code, authorization.message);
+      return;
+    }
+
+    const request = adminUserRoleUpdateRequestSchema.safeParse(req.body);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin user role update request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await settingsPort.updateAdminUserRole(request.data);
+      const response = adminUserRoleUpdateResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Admin user role update returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch (error) {
+      const bffCode = (error as { bffCode?: string })?.bffCode;
+      if (bffCode) {
+        sendBffError(res, bffCode as Parameters<typeof sendBffError>[1], (error as Error).message);
+        return;
+      }
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin user role update failed");
+    }
+  };
+}
+
+export function createAdminUserInviteHandler({
+  settingsPort,
+  authorizeAdmin, responseRequestId,
+}: AdminUserInviteDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createIdentityResponder({ responseRequestId });
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res, ["POST"]);
+      return;
+    }
+
+    let authorization: PlatformAdminAuthorizationResult;
+    try {
+      authorization = await authorizeAdmin(req);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+      return;
+    }
+
+    if (authorization.ok === false) {
+      sendBffError(res, authorization.code, authorization.message);
+      return;
+    }
+
+    const request = adminUserInviteRequestSchema.safeParse(req.body);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin user invite request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await settingsPort.inviteAdminUser(request.data);
+      const response = adminUserInviteResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Admin user invite returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch (error) {
+      const failure = error as { bffCode?: string; inviteDetails?: AdminUserInviteErrorDetails };
+      sendBffError(res, (failure.bffCode ?? "UPSTREAM_UNAVAILABLE") as Parameters<typeof sendBffError>[1], errorMessage(error, "Admin user invite failed"), failure.inviteDetails ? { details: failure.inviteDetails } : {});
+    }
+  };
+}
+
+export function createAdminUserRemoveHandler({
+  settingsPort,
+  authorizeAdmin, responseRequestId,
+}: AdminUserRemoveDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createIdentityResponder({ responseRequestId });
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res, ["POST"]);
+      return;
+    }
+
+    let authorization: PlatformAdminAuthorizationResult;
+    try {
+      authorization = await authorizeAdmin(req);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+      return;
+    }
+
+    if (authorization.ok === false) {
+      sendBffError(res, authorization.code, authorization.message);
+      return;
+    }
+
+    const request = adminUserRemoveRequestSchema.safeParse(req.body);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin user remove request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await settingsPort.removeAdminUser(request.data);
+      const response = adminUserRemoveResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Admin user remove returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch (error) {
+      sendMutationError(res, error, "Admin user revoke failed", responseRequestId);
+    }
+  };
+}
+
+function errorMessage(error: unknown, fallback: string): string {
+  return error instanceof Error && error.message ? error.message : fallback;
+}
+
+function sendMutationError(res: HttpResponse, error: unknown, fallback: string, responseRequestId: IdentityResponseOptions["responseRequestId"]): void {
+  const { sendBffError } = createIdentityResponder({ responseRequestId });
+  const bffCode = (error as { bffCode?: string })?.bffCode;
+  if (bffCode) {
+    sendBffError(res, bffCode as Parameters<typeof sendBffError>[1], errorMessage(error, fallback));
+    return;
+  }
+  sendBffError(res, "UPSTREAM_UNAVAILABLE", errorMessage(error, fallback));
+}