@openlup/platform 0.15.0 → 0.16.0

package/sql/20260901143000_admin_membership_authority_foundation.sql

@@ -0,0 +1,234 @@
+-- Dormant direct human membership authority.
+--
+-- This forward introduces a provider-neutral human principal and its separate
+-- current-panel membership for the direct bundle. It mirrors the managed role,
+-- active/revoked state, provenance, acceptance, revocation, retained identity,
+-- last-human-administrator refusal, and one-row revoke audit semantics. It does
+-- not verify a login, grant browser access, seed a person, or link to the
+-- existing platform_control_operators machine authority. The direct host owns
+-- activation of a future human-login adapter; until then these relations are
+-- deliberately dormant and default-deny for the actor roles.
+
+CREATE TABLE public.platform_human_principals (
+  principal_id uuid PRIMARY KEY,
+  email text NOT NULL UNIQUE,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE public.platform_human_memberships (
+  principal_id uuid PRIMARY KEY REFERENCES public.platform_human_principals(principal_id) ON DELETE RESTRICT,
+  role text NOT NULL CHECK (role IN ('admin', 'distributor')),
+  membership_state text NOT NULL CHECK (membership_state IN ('active', 'revoked')),
+  membership_provenance text NOT NULL CHECK (membership_provenance IN ('legacy', 'invitation')),
+  membership_accepted_at timestamptz NOT NULL,
+  membership_revoked_at timestamptz,
+  membership_revoked_by uuid REFERENCES public.platform_human_principals(principal_id) ON DELETE RESTRICT,
+  membership_revocation_reason text,
+  CONSTRAINT platform_human_memberships_lifecycle_check CHECK (
+    (membership_state = 'active'
+      AND membership_revoked_at IS NULL
+      AND membership_revoked_by IS NULL
+      AND membership_revocation_reason IS NULL)
+    OR
+    (membership_state = 'revoked'
+      AND membership_revoked_at IS NOT NULL
+      AND membership_revoked_by IS NOT NULL)
+  ),
+  CONSTRAINT platform_human_memberships_distinct_revoker_check
+    CHECK (membership_revoked_by IS NULL OR membership_revoked_by <> principal_id),
+  CONSTRAINT platform_human_memberships_reason_length_check
+    CHECK (membership_revocation_reason IS NULL OR char_length(membership_revocation_reason) <= 1000)
+);
+
+CREATE TABLE public.platform_human_membership_audit_events (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  actor_principal_id uuid NOT NULL REFERENCES public.platform_human_principals(principal_id) ON DELETE RESTRICT,
+  target_principal_id uuid NOT NULL REFERENCES public.platform_human_principals(principal_id) ON DELETE RESTRICT,
+  action text NOT NULL CHECK (action = 'revoke'),
+  old_value jsonb NOT NULL,
+  new_value jsonb NOT NULL,
+  reason text,
+  occurred_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX platform_human_membership_audit_target_idx
+  ON public.platform_human_membership_audit_events(target_principal_id, occurred_at DESC);
+
+REVOKE ALL ON TABLE
+  public.platform_human_principals,
+  public.platform_human_memberships,
+  public.platform_human_membership_audit_events
+FROM PUBLIC, anon, authenticated;
+
+CREATE FUNCTION public.platform_human_membership_is_active(p_principal_id uuid)
+RETURNS boolean
+LANGUAGE sql
+STABLE
+SET search_path = pg_catalog
+AS $$
+  SELECT EXISTS (
+    SELECT 1
+    FROM public.platform_human_memberships AS membership_row
+    WHERE membership_row.principal_id = p_principal_id
+      AND membership_row.membership_state = 'active'
+  );
+$$;
+
+CREATE FUNCTION public.platform_human_membership_is_administrator(p_principal_id uuid)
+RETURNS boolean
+LANGUAGE sql
+STABLE
+SET search_path = pg_catalog
+AS $$
+  SELECT EXISTS (
+    SELECT 1
+    FROM public.platform_human_memberships AS membership_row
+    WHERE membership_row.principal_id = p_principal_id
+      AND membership_row.membership_state = 'active'
+      AND membership_row.role = 'admin'
+  );
+$$;
+
+CREATE FUNCTION public.platform_human_memberships_guard()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = pg_catalog, public
+AS $$
+DECLARE
+  v_removes_active_human_admin boolean := false;
+  v_other_active_human_admins integer;
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    v_removes_active_human_admin := OLD.membership_state = 'active' AND OLD.role = 'admin';
+  ELSE
+    IF (OLD.membership_state, OLD.membership_provenance, OLD.membership_accepted_at,
+        OLD.membership_revoked_at, OLD.membership_revoked_by,
+        OLD.membership_revocation_reason)
+       IS DISTINCT FROM
+       (NEW.membership_state, NEW.membership_provenance, NEW.membership_accepted_at,
+        NEW.membership_revoked_at, NEW.membership_revoked_by,
+        NEW.membership_revocation_reason)
+      AND current_setting('app.platform_human_membership_revoke', true) IS DISTINCT FROM 'true' THEN
+      RAISE EXCEPTION 'platform_human_membership_lifecycle_update_forbidden' USING ERRCODE = '42501';
+    END IF;
+
+    IF OLD.membership_state <> 'active' AND NEW.role IS DISTINCT FROM OLD.role THEN
+      RAISE EXCEPTION 'platform_human_target_membership_inactive' USING ERRCODE = 'P0001';
+    END IF;
+
+    v_removes_active_human_admin := OLD.membership_state = 'active'
+      AND OLD.role = 'admin'
+      AND (NEW.membership_state <> 'active' OR NEW.role <> 'admin');
+  END IF;
+
+  IF v_removes_active_human_admin THEN
+    PERFORM pg_advisory_xact_lock(hashtext('platform_human_memberships_active_admin')::bigint);
+    SELECT count(*)
+      INTO v_other_active_human_admins
+    FROM public.platform_human_memberships
+    WHERE principal_id <> OLD.principal_id
+      AND membership_state = 'active'
+      AND role = 'admin';
+
+    IF v_other_active_human_admins < 1 THEN
+      RAISE EXCEPTION 'platform_human_last_admin_lockout' USING ERRCODE = 'P0001';
+    END IF;
+  END IF;
+
+  IF TG_OP = 'DELETE' THEN
+    RAISE EXCEPTION 'platform_human_membership_delete_forbidden' USING ERRCODE = '42501';
+  END IF;
+
+  RETURN NEW;
+END;
+$$;
+
+CREATE TRIGGER trg_platform_human_memberships_guard
+  BEFORE UPDATE OR DELETE ON public.platform_human_memberships
+  FOR EACH ROW EXECUTE FUNCTION public.platform_human_memberships_guard();
+
+CREATE FUNCTION public.platform_revoke_human_membership(
+  p_actor_principal_id uuid,
+  p_target_principal_id uuid,
+  p_reason text DEFAULT NULL
+)
+RETURNS public.platform_human_memberships
+LANGUAGE plpgsql
+SET search_path = pg_catalog, public
+AS $$
+DECLARE
+  v_target public.platform_human_memberships;
+  v_reason text := NULLIF(btrim(p_reason), '');
+  v_revoked_at timestamptz := clock_timestamp();
+BEGIN
+  IF NOT public.platform_human_membership_is_administrator(p_actor_principal_id) THEN
+    RAISE EXCEPTION 'platform_human_revoke_forbidden' USING ERRCODE = '42501';
+  END IF;
+
+  IF p_target_principal_id IS NULL THEN
+    RAISE EXCEPTION 'platform_human_target_required' USING ERRCODE = '22023';
+  END IF;
+
+  IF p_target_principal_id = p_actor_principal_id THEN
+    RAISE EXCEPTION 'platform_human_self_revoke_forbidden' USING ERRCODE = 'P0001';
+  END IF;
+
+  IF v_reason IS NOT NULL AND char_length(v_reason) > 1000 THEN
+    RAISE EXCEPTION 'platform_human_revocation_reason_too_long' USING ERRCODE = '22023';
+  END IF;
+
+  SELECT * INTO v_target
+  FROM public.platform_human_memberships
+  WHERE principal_id = p_target_principal_id
+  FOR UPDATE;
+
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'platform_human_target_not_found' USING ERRCODE = 'P0002';
+  END IF;
+
+  IF v_target.membership_state = 'revoked' THEN
+    RETURN v_target;
+  END IF;
+
+  PERFORM set_config('app.platform_human_membership_revoke', 'true', true);
+
+  UPDATE public.platform_human_memberships
+  SET membership_state = 'revoked',
+      membership_revoked_at = v_revoked_at,
+      membership_revoked_by = p_actor_principal_id,
+      membership_revocation_reason = v_reason
+  WHERE principal_id = p_target_principal_id
+  RETURNING * INTO v_target;
+
+  INSERT INTO public.platform_human_membership_audit_events
+    (actor_principal_id, target_principal_id, action, old_value, new_value, reason, occurred_at)
+  VALUES (
+    p_actor_principal_id,
+    p_target_principal_id,
+    'revoke',
+    jsonb_build_object('membershipState', 'active', 'role', v_target.role),
+    jsonb_build_object(
+      'membershipState', 'revoked',
+      'revokedAt', v_revoked_at,
+      'revokedBy', p_actor_principal_id,
+      'revocationReason', v_reason
+    ),
+    v_reason,
+    v_revoked_at
+  );
+
+  RETURN v_target;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.platform_human_membership_is_active(uuid)
+  FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.platform_human_membership_is_administrator(uuid)
+  FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.platform_human_memberships_guard()
+  FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.platform_revoke_human_membership(uuid, uuid, text)
+  FROM PUBLIC, anon, authenticated;
+
+COMMENT ON FUNCTION public.platform_revoke_human_membership(uuid, uuid, text) IS
+  'Dormant direct-bundle revoke command. Requires an active human administrator, retains the target principal/membership, refuses self and last-admin removal, and records one atomic revoke event.';

package/sql/20261018120000_identity_operator_invitations.sql

@@ -0,0 +1,42 @@
+-- Pending direct operator invitations. Lifecycle commands use the trusted
+-- server transaction lane; this forward adds no function or actor privilege.
+CREATE TABLE public.identity_operator_invitations (
+  principal_id uuid PRIMARY KEY REFERENCES public.platform_human_principals(principal_id),
+  invitation_id uuid NOT NULL UNIQUE,
+  email_key text NOT NULL UNIQUE,
+  role text NOT NULL CHECK (role IN ('admin', 'distributor')),
+  phase text NOT NULL CHECK (phase IN ('invited', 'accepted', 'expired', 'cancelled')),
+  invited_by uuid NOT NULL REFERENCES public.platform_human_principals(principal_id),
+  invited_at timestamptz NOT NULL,
+  expires_at timestamptz NOT NULL,
+  accepted_at timestamptz,
+  closed_at timestamptz,
+  CHECK (email_key = lower(btrim(email_key)) AND NOT email_key = ''),
+  CHECK (expires_at BETWEEN invited_at + interval '60 seconds' AND invited_at + interval '30 days'),
+  CHECK (
+    (phase = 'invited' AND accepted_at IS NULL AND closed_at IS NULL)
+    OR (phase = 'accepted' AND accepted_at IS NOT NULL
+      AND accepted_at BETWEEN invited_at AND expires_at
+      AND NOT accepted_at = expires_at AND closed_at = accepted_at)
+    OR (phase = 'expired' AND accepted_at IS NULL AND closed_at = expires_at)
+    OR (phase = 'cancelled' AND accepted_at IS NULL AND closed_at IS NOT NULL)
+  )
+);
+
+CREATE TABLE public.identity_operator_invitation_events (
+  event_id uuid PRIMARY KEY,
+  invitation_id uuid NOT NULL,
+  principal_id uuid NOT NULL REFERENCES public.platform_human_principals(principal_id),
+  action text NOT NULL CHECK (action IN ('issue', 'reissue', 'accept', 'expire', 'cancel')),
+  actor_kind text NOT NULL CHECK (actor_kind IN ('human', 'system')),
+  actor_principal_id uuid REFERENCES public.platform_human_principals(principal_id),
+  old_value jsonb NOT NULL,
+  new_value jsonb NOT NULL,
+  occurred_at timestamptz NOT NULL,
+  UNIQUE (invitation_id, action),
+  CHECK ((actor_kind = 'human' AND actor_principal_id IS NOT NULL)
+    OR (actor_kind = 'system' AND actor_principal_id IS NULL))
+);
+
+CREATE INDEX identity_operator_invitation_events_target_idx
+  ON public.identity_operator_invitation_events(principal_id, occurred_at DESC);

package/sql/20261018180000_identity_operator_challenges.sql

@@ -0,0 +1,56 @@
+CREATE UNIQUE INDEX platform_human_principals_normalized_email_key
+  ON public.platform_human_principals (lower(btrim(email)));
+
+CREATE TABLE public.operator_identity_challenges (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  principal_id uuid NOT NULL
+    REFERENCES public.platform_human_principals(principal_id),
+  email_fingerprint text NOT NULL,
+  token_hash text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  expires_at timestamptz NOT NULL,
+  used_at timestamptz,
+
+  CONSTRAINT operator_identity_challenges_email_fingerprint_check
+    CHECK (
+      length(email_fingerprint) = 64
+      AND translate(
+        email_fingerprint,
+        '0123456789abcdef',
+        ''
+      ) = ''
+    ),
+
+  CONSTRAINT operator_identity_challenges_token_hash_check
+    CHECK (
+      length(token_hash) = 64
+      AND translate(
+        token_hash,
+        '0123456789abcdef',
+        ''
+      ) = ''
+    ),
+
+  CONSTRAINT operator_identity_challenges_token_hash_key
+    UNIQUE (token_hash),
+
+  CONSTRAINT operator_identity_challenges_expiry_check
+    CHECK (
+      expires_at BETWEEN
+        created_at + INTERVAL '1 second'
+        AND created_at + INTERVAL '10 minutes'
+    ),
+
+  CONSTRAINT operator_identity_challenges_used_at_check
+    CHECK (
+      used_at IS NULL
+      OR used_at BETWEEN created_at AND expires_at
+    )
+);
+
+CREATE INDEX operator_identity_challenges_principal_created_idx
+  ON public.operator_identity_challenges
+    (principal_id, created_at DESC);
+
+CREATE INDEX operator_identity_challenges_expiry_idx
+  ON public.operator_identity_challenges (expires_at, id);

package/sql/20261018190000_identity_privacy_erasures.sql

@@ -0,0 +1,15 @@
+-- Direct identity erasure receipts. Audit and idempotency share one retained
+-- pseudonymous record; no personal export snapshot or actor grants are stored.
+CREATE TABLE public.identity_privacy_erasures (
+  erasure_id uuid PRIMARY KEY,
+  idempotency_key uuid NOT NULL UNIQUE,
+  client_id uuid UNIQUE REFERENCES public.clients(id),
+  principal_id uuid UNIQUE,
+  actor_principal_id uuid NOT NULL REFERENCES public.platform_human_principals(principal_id),
+  contract_version text NOT NULL CHECK (contract_version = 'identity.erasure.v1'),
+  contributor_versions jsonb NOT NULL,
+  dispositions jsonb NOT NULL,
+  retained_obligations jsonb NOT NULL,
+  completed_at timestamptz NOT NULL,
+  CHECK (client_id IS NOT NULL OR principal_id IS NOT NULL)
+);

package/src/identity/adminAuthBinding.ts

@@ -0,0 +1,76 @@
+import { createOperatorTokenAdminAuth, resolvePlatformOperatorAuthConfig } from "./operatorTokenAdminAuth.js";
+import { resolveBundleId } from "../kernel/index.js";
+import type { AdminAuthPort } from "./ports.js";
+import type { AdminAuthBinding } from "./adminPreflight.js";
+type Env = Record<string, string | undefined>;
+export interface PlatformOperatorChecker { isOperatorAllowed(principalId: string): Promise<boolean>; close(): Promise<void> }
+export type PlatformOperatorCheckerFactory = (env: Env) => PlatformOperatorChecker | Promise<PlatformOperatorChecker>;
+export type AdminAuthBindingResolution =
+  | { readonly binding: AdminAuthBinding; readonly error?: undefined }
+  | { readonly binding?: undefined; readonly error: "managed_admin_auth_env_required" | "direct_admin_auth_config_invalid" };
+export interface AdminAuthBindingOptions {
+  humanAuthFactory?: (env: Env) => AdminAuthPort & { close(): Promise<void> };
+  checkerFactory?: PlatformOperatorCheckerFactory;
+  managedAuthFactory?: (env: { url: string; anonKey: string }, accessToken: string | null) => AdminAuthPort;
+}
+function managedAuthEnv(env: Env): { url: string; anonKey: string } | null {
+  const url = env.SUPABASE_URL ?? env.VITE_SUPABASE_URL;
+  const anonKey = env.VITE_SUPABASE_PUBLISHABLE_KEY ?? env.VITE_SUPABASE_ANON_KEY ?? env.SUPABASE_ANON_KEY;
+  return url && anonKey ? { url, anonKey } : null;
+}
+
+/** Bind the admin authorizer selected by PLATFORM_BUNDLE. */
+export function createAdminAuthBindingResolver(defaults: Required<Pick<AdminAuthBindingOptions, "checkerFactory" | "managedAuthFactory">> & Pick<AdminAuthBindingOptions, "humanAuthFactory">) {
+return function resolveAdminAuthBinding(
+  env: Env,
+  options: AdminAuthBindingOptions = {},
+): AdminAuthBindingResolution {
+  const bundleId = resolveBundleId(env);
+  if (bundleId === "node-postgres") {
+    const config = resolvePlatformOperatorAuthConfig(env);
+    const humanFactory = options.humanAuthFactory ?? defaults.humanAuthFactory;
+    const humanEnabled = !!env.OPERATOR_IDENTITY_AUDIENCE && !!humanFactory;
+    if (!config.config && !humanEnabled) return { error: "direct_admin_auth_config_invalid" };
+    const checkerFactory = options.checkerFactory ?? defaults.checkerFactory;
+    return {
+      binding: {
+        identity: bundleId,
+        async run(accessToken, work) {
+          const scope: { checker?: PlatformOperatorChecker } = {};
+          const machine = config.config ? createOperatorTokenAdminAuth(config.config, async (principalId) => {
+            scope.checker ??= await checkerFactory(env);
+            return scope.checker.isOperatorAllowed(principalId);
+          }) : null;
+          let human: (AdminAuthPort & { close(): Promise<void> }) | undefined;
+          const auth: AdminAuthPort = { async authorize(token, restrictions) {
+            // Only a credential mismatch may select human verification; machine
+            // revocation and database errors retain their existing result.
+            const result = machine ? await machine.authorize(token, restrictions) : null;
+            if (result && (result.ok || result.code !== "UNAUTHORIZED")) return result;
+            if (!humanEnabled || !token) return result ?? { ok: false, code: "UNAUTHORIZED", message: "Operator authentication required" };
+            human ??= humanFactory!(env);
+            return human.authorize(token, restrictions);
+          } };
+          try {
+            return await work(auth);
+          } finally {
+            try { await scope.checker?.close(); } finally { await human?.close(); }
+          }
+        },
+      },
+    };
+  }
+
+  const authEnv = managedAuthEnv(env);
+  if (!authEnv) return { error: "managed_admin_auth_env_required" };
+  const managedAuthFactory = options.managedAuthFactory ?? defaults.managedAuthFactory;
+  return {
+    binding: {
+      identity: bundleId,
+      run: (accessToken, work) => work(managedAuthFactory(authEnv, accessToken)),
+    },
+  };
+}
+
+
+}

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),
+});
+