@openlup/platform 0.15.0 → 0.16.0

package/src/identity/identityPersonalDataContributor.ts

@@ -0,0 +1,48 @@
+import type { PersonalDataObligation, PrivacyJson } from "./contracts/privacy.js";
+import { PrivacyRefusal, type PersonalDataContributor, type PrivacyStore } from "./privacyPorts.js";
+
+export interface IdentityPrivacyPolicy {
+  /** Explicit dispositions for populated opaque contact fields; absence refuses erasure. */
+  retainedContactFields: Readonly<Record<string, PersonalDataObligation>>;
+}
+const owned = new Set(["id", "email", "first_name", "last_name", "phone", "country", "principal_id", "created_at", "updated_at"]);
+const populated = (value: PrivacyJson) => value !== null && value !== "" && !(typeof value === "object" && Object.keys(value).length === 0);
+export function createIdentityPersonalDataContributor<C>(store: PrivacyStore<C>, policy: IdentityPrivacyPolicy, randomId: () => string): PersonalDataContributor<C> {
+  function obligations(identity: { [key: string]: PrivacyJson }): PersonalDataObligation[] {
+    const contact = identity.contact;
+    const result: PersonalDataObligation[] = [{ owner: "identity", resource: "identity.audit-and-receipt", disposition: "retain", reasonCode: "PSEUDONYMOUS_AUDIT", remote: false }];
+    if (contact && typeof contact === "object" && !Array.isArray(contact)) {
+      for (const [key, value] of Object.entries(contact)) {
+        if (owned.has(key) || !populated(value)) continue;
+        const declaration = policy.retainedContactFields[key];
+        result.push(declaration?.disposition === "retain" && declaration.resource === `clients.${key}` ? declaration : { owner: "unassigned", resource: `clients.${key}`, disposition: "unresolved", reasonCode: "PRIVACY_OWNERSHIP_UNDECLARED", remote: false });
+      }
+    }
+    return result;
+  }
+  return {
+    id: "identity", version: "identity.personal-data.v1",
+    ownedResources: ["identity.contact-profile", "identity.principal", "identity.membership", "identity.invitations", "identity.audit-and-receipt"],
+    async prepareErasure() {},
+    async export(_context, subject) {
+      const unavailable = Array.isArray(subject.identity.unavailable) ? subject.identity.unavailable.map(String) : [];
+      const data = { ...subject.identity };
+      const contact = data.contact;
+      if (contact && typeof contact === "object" && !Array.isArray(contact)) {
+        data.contact = Object.fromEntries(Object.entries(contact).filter(([key]) => owned.has(key) || key === "auth_user_id"));
+        for (const key of Object.keys(contact)) if (!owned.has(key) && key !== "auth_user_id") unavailable.push(`contact.${key}`);
+      }
+      return { contributorId: "identity", version: "identity.personal-data.v1", data,
+        coverage: { complete: unavailable.length === 0, included: Object.keys(subject.identity).filter(k => k !== "unavailable"), unavailable }, obligations: obligations(subject.identity) };
+    },
+    async assessErasure(_context, subject) {
+      const declared = obligations(subject.identity);
+      if (declared.some(o => o.disposition === "unresolved")) throw new PrivacyRefusal("PRIVACY_OWNERSHIP_UNDECLARED");
+      return { obligations: declared };
+    },
+    async eraseOrRetain(context, subject, assessment, actor) {
+      await store.eraseIdentity(context, subject, actor, `erased+${randomId()}@identity.invalid`);
+      return { contributorId: "identity", version: "identity.personal-data.v1", obligations: assessment.obligations };
+    },
+  };
+}

package/src/identity/identityReadiness.ts

@@ -0,0 +1,26 @@
+import type { ReadinessIssue } from "@openlup/core/readiness";
+import { assessEmailTrust, type EmailTrustPolicy } from "./emailTrustPolicy.js";
+
+/** The module field stays structural so older core readiness types still compile; no new core code is needed. */
+export async function identityEmailTrustReadiness(policy: EmailTrustPolicy): Promise<readonly (ReadinessIssue & { module: "identity" })[]> {
+  const result = await assessEmailTrust(policy);
+  if (result.trusted) return [];
+  return [{
+    code: "OPENLUP_E_PORT_MISSING", package: "@openlup/platform", module: "identity",
+    subject: "emailTrustPolicy", observation: result.code,
+    fix: result.code === "EMAIL_TRUST_ENVELOPE_REFUSED"
+      ? "Disable automatic confirmation and declare only providers that verify email."
+      : "Restore access to valid public identity settings or bind an explicit email-trust policy.",
+  }];
+}
+
+/** Discovery and fresh key availability are independent readiness observations. */
+export async function identityOidcReadiness(verifier: import("./oidcIdentityVerifier.js").OidcIdentityVerifier): Promise<readonly (ReadinessIssue & { module: "identity" })[]> {
+  const report = await verifier.readiness();
+  if (report.state === "ready") return [];
+  return [
+    ...(!report.discovery.valid ? ["oidcDiscovery"] : []),
+    ...(!report.jwks.loaded ? ["oidcJwks"] : []),
+  ].map(subject => ({ code: "OPENLUP_E_PORT_MISSING", package: "@openlup/platform", module: "identity", subject,
+    observation: report.code ?? "OIDC_JWKS_INVALID", fix: "Restore valid issuer discovery and fresh same-origin signing keys." }));
+}

package/src/identity/index.ts

@@ -0,0 +1,69 @@
+export * from "./adminMagicLinkHandler.js";
+export * from "./reconcileAccountForPrincipal.js";
+export * from "./customerVerifyOtpHandler.js";
+export * from "./authVerifyUrl.js";
+export * from "./customerIdentityVerifier.js";
+export * from "./operatorTokenAdminAuth.js";
+export * from "./managedIdentityVerifier.js";
+export * from "./managedAdminAuthVerifier.js";
+export * from "./managedCustomerMe.js";
+export * from "./sql.js";
+export * from "./customerMeHandler.js";
+export * from "./messages.js";
+export * from "./managedAccountLinkStore.js";
+export * from "./customerIdentityBinding.js";
+export * from "./adminUserActionPorts.js";
+export * from "./contribution.js";
+export * from "./customerContracts.js";
+export * from "./machineActorWriteFence.js";
+export * from "./managedClient.js";
+export * from "./customerAuthorization.js";
+export * from "./customerSessionIssuer.js";
+export * from "./managedClientAuthLink.js";
+export * from "./customerAuth.js";
+export * from "./reconcileAccountHandler.js";
+export * from "./postgresCustomerMe.js";
+export * from "./ports.js";
+export * from "./postgresCustomerRecovery.js";
+export * from "./customerMagicLinkHandler.js";
+export * from "./customerSessionBinding.js";
+export * from "./adminUserHandlers.js";
+export * from "./adminPreflight.js";
+export * from "./adminAuthBinding.js";
+export * from "./customerPorts.js";
+export * from "./magicLinkPorts.js";
+export * from "./inviteAdminUserUseCase.js";
+export * from "./adminAuthorization.js";
+export * from "./removeAdminUserUseCase.js";
+export * from "./adminMeHandler.js";
+export * from "./managedAdminUserGateways.js";
+export * from "./jwtLibrary.js";
+export * from "./platformAdminAuth.js";
+export * from "./adminContracts.js";
+export * from "./contracts/emailTrust.js";
+export { createVerifierResultOnlyEmailTrustPolicy } from "./emailTrustPolicy.js";
+export type { EmailTrustAssessment, EmailTrustPolicy } from "./emailTrustPolicy.js";
+export * from "./managedEmailTrustPolicy.js";
+export * from "./identityReadiness.js";
+
+export * from "./operatorInvitationPorts.js";
+export * from "./operatorInvitationLifecycle.js";
+export * from "./directOperatorInvitationStore.js";
+export * from "./operatorPorts.js";
+export * from "./operatorSession.js";
+export * from "./operatorIdentityVerifier.js";
+export * from "./operatorAdminAuth.js";
+export * from "./operatorAuthHandlers.js";
+export * from "./postgresOperatorIdentity.js";
+export * from "./privacyPorts.js";
+export * from "./personalDataRegistry.js";
+export * from "./privacyUseCases.js";
+export * from "./identityPersonalDataContributor.js";
+export * from "./postgresPrivacy.js";
+export * from "./managedPrivacy.js";
+export * from "./privacyHandlers.js";
+
+export * from "./oidcIdentityVerifier.js";
+export * from "./oidcPrincipal.js";
+export * from "./postgresAccountLinkStore.js";
+export * from "./contracts/oidc.js";

package/src/identity/inviteAdminUserUseCase.ts

@@ -0,0 +1,134 @@
+import type { ManagedOperatorMembershipResult, OperatorInvitationConflict } from "./contracts/operatorInvitations.js";
+import type { OperatorInvitationStore } from "./operatorInvitationPorts.js";
+import { assertOperatorInvitationTtl } from "./operatorInvitationLifecycle.js";
+import { identityMessages, type IdentityMessages } from "./messages.js";
+export type AdminUserInviteRole = "admin" | "distributor";
+export const ADMIN_ROLE_NOTIFICATION_LOCALE = "en" as const;
+export type AdminRoleNotificationSkipReason = "admin_disabled" | "egress_suppressed";
+
+export type InviteAdminUserResponse = {
+  [key: string]: unknown;
+  success?: boolean;
+  message?: string;
+  error?: string;
+  code?: string;
+  deliveryReference?: string | null;
+  deliveryReferencePresent?: boolean;
+};
+
+export interface InviteAdminUserGateway {
+  getUser: (accessToken: string) => Promise<{
+    user: { id: string } | null;
+    error: unknown;
+  }>;
+  findAdminUser: (userId: string) => Promise<{ id: string; role: string; membership_state: string; is_machine_actor: boolean } | null>;
+  findAdminUserByEmail: (email: string) => Promise<{ id: string } | null>;
+  findAuthUserByEmail: (email: string) => Promise<{ id: string; email?: string | null } | null>;
+  inviteAuthUser: (input: {
+    email: string;
+    redirectTo: string;
+    role: AdminUserInviteRole;
+  }) => Promise<{
+    user: { id: string } | null;
+    error: { message: string } | null;
+  }>;
+}
+
+export interface AdminRoleNotificationPort {
+  sendRoleGranted: (input: {
+    email: string;
+    authUserId: string;
+    role: AdminUserInviteRole;
+    locale: "pl" | "en";
+    invitationId?: string;
+    expiresAt?: string;
+  }) => Promise<{
+    ok: boolean;
+    providerMessageId: string | null;
+    providerError: string | null;
+    skipped: boolean;
+    skipReason: AdminRoleNotificationSkipReason | null;
+  }>;
+}
+
+export async function runInviteAdminUserUseCase(
+  request: { accessToken: string | null; email: string; role: string },
+  deps: {
+    gateway: InviteAdminUserGateway;
+    roleNotificationPort: AdminRoleNotificationPort;
+    siteUrl: string;
+
+    messages?: IdentityMessages;
+    notificationLocale?: "pl" | "en";
+  } & (
+    | { invitationStore: OperatorInvitationStore; ttlSeconds: number }
+    | { activateMembership: (input: { principalId: string; email: string; role: AdminUserInviteRole }) => Promise<ManagedOperatorMembershipResult | { code: OperatorInvitationConflict }> }
+  ),
+): Promise<{ status: number; body: InviteAdminUserResponse }> {
+  const messages = deps.messages ?? identityMessages.en;
+  try {
+    if ("invitationStore" in deps) assertOperatorInvitationTtl(deps.ttlSeconds);
+    if (!request.accessToken) {
+      return { status: 401, body: { code: "UNAUTHORIZED", error: messages.unauthorized } };
+    }
+
+    const { user, error: authError } = await deps.gateway.getUser(request.accessToken);
+    if (authError || !user) {
+      return { status: 401, body: { code: "INVALID_TOKEN", error: messages.invalidToken } };
+    }
+
+    const callerAdmin = await deps.gateway.findAdminUser(user.id);
+    if (!callerAdmin || callerAdmin.role !== "admin" || callerAdmin.membership_state !== "active" || callerAdmin.is_machine_actor !== false) {
+      return { status: 403, body: { code: "INVITE_FORBIDDEN", error: messages.inviteForbidden } };
+    }
+
+    if (!request.email) {
+      return { status: 400, body: { code: "EMAIL_REQUIRED", error: messages.emailRequired } };
+    }
+
+    if (!isInviteRole(request.role)) {
+      return { status: 400, body: { code: "INVALID_ROLE", error: messages.invalidRole } };
+    }
+    const role = request.role;
+
+    const email = request.email.trim().toLowerCase();
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) return { status: 400, body: { code: "INVALID_EMAIL", error: "Invalid email" } };
+    const existingMembership = await deps.gateway.findAdminUserByEmail(email);
+    let principal = await deps.gateway.findAuthUserByEmail(email);
+    if (existingMembership && existingMembership.id !== principal?.id) return { status: 409, body: { code: "IDENTITY_CONFLICT", error: "IDENTITY_CONFLICT" } };
+    if (!principal) {
+      const invite = await deps.gateway.inviteAuthUser({ email, role, redirectTo: new URL("/admin/auth/callback", deps.siteUrl).toString() });
+      if (invite.error || !invite.user) {
+        // A provider duplicate race reuses the durable identity. Never delete it.
+        principal = await deps.gateway.findAuthUserByEmail(email);
+        if (!principal) throw new Error("operator_identity_creation_failed");
+      } else principal = invite.user;
+    }
+    const issued = "invitationStore" in deps
+      ? await deps.invitationStore.issue({ actorPrincipalId: user.id, targetPrincipalId: principal.id, email, role, ttlSeconds: deps.ttlSeconds })
+      : await deps.activateMembership({ principalId: principal.id, email, role });
+    if (!("membershipState" in issued)) return { status: 409, body: { code: issued.code, error: issued.code } };
+    let delivery: Pick<InviteAdminUserResponse, "deliveryReference" | "deliveryReferencePresent"> = {};
+    if (issued.code !== "ALREADY_INVITED" && issued.code !== "ALREADY_ACTIVE") {
+      try {
+        const notification = await deps.roleNotificationPort.sendRoleGranted({ email, authUserId: principal.id, role, locale: deps.notificationLocale ?? ADMIN_ROLE_NOTIFICATION_LOCALE, ...(issued.membershipState === "invited" ? { invitationId: issued.invitationId, expiresAt: issued.expiresAt } : {}) });
+        if (!notification.ok) throw new Error("operator_invitation_notification_failed");
+        delivery = { deliveryReference: notification.skipped ? null : notification.providerMessageId, deliveryReferencePresent: !notification.skipped && Boolean(notification.providerMessageId) };
+      } catch {
+        return { status: 503, body: issued.membershipState === "invited"
+          ? { code: "INVITATION_NOTIFICATION_FAILED", error: "Invitation persisted; notification unavailable", invitationId: issued.invitationId }
+          : { ...issued, code: "INVITATION_NOTIFICATION_FAILED", error: "Membership active; notification unavailable" } };
+      }
+    }
+    return { status: 200, body: { success: true, ...issued, ...delivery, message: issued.membershipState === "invited" ? `Invitation pending until ${issued.expiresAt}` : "Operator membership active" } };
+
+  } catch (err) {
+    const failure = err as { identityCode?: string; bffCode?: string };
+    if (failure.identityCode) return { status: failure.bffCode === "FORBIDDEN" ? 403 : 409, body: { code: failure.identityCode, error: failure.identityCode } };
+    return { status: 503, body: { code: "IDENTITY_ACTION_FAILED", error: String(err) } };
+  }
+}
+
+function isInviteRole(value: string): value is AdminUserInviteRole {
+  return value === "admin" || value === "distributor";
+}

package/src/identity/jwtLibrary.ts

@@ -0,0 +1,24 @@
+export interface IdentityJwk {
+  [key: string]: unknown;
+  kty?: string; alg?: string; crv?: string; kid?: string; use?: string; x?: string; y?: string; d?: string;
+}
+type Key = CryptoKey | Uint8Array;
+interface Signer {
+  setProtectedHeader(header: { alg: string; kid: string; typ: string }): Signer;
+  setSubject(value: string): Signer; setIssuer(value: string): Signer;
+  setAudience(value: string): Signer; setIssuedAt(value: number): Signer;
+  setExpirationTime(value: number): Signer; sign(key: Key): Promise<string>;
+}
+/** The host loads its selected JWT implementation only for the selected adapter. */
+export interface IdentityJwtLibrary {
+  importJWK(jwk: IdentityJwk, alg: string): Promise<Key>;
+  jwtVerify(token: string, key: (header: { alg?: string; kid?: string }) => Promise<Key>, options: { algorithms: string[]; audience: string; issuer: string; currentDate?: Date; clockTolerance?: number }): Promise<{ payload: IdentityJwtClaims }>;
+  SignJWT: new (payload: Record<string, unknown>) => Signer;
+}
+export type IdentityJwtLibraryLoader = () => Promise<IdentityJwtLibrary>;
+
+/** Claims returned only after signature verification by the host library. */
+export interface IdentityJwtClaims {
+  [claim: string]: unknown;
+  sub?: string; iss?: string; aud?: string | string[]; exp?: number; iat?: number; nbf?: number;
+}

package/src/identity/machineActorWriteFence.ts

@@ -0,0 +1,19 @@
+import type { HttpResponse } from "../http/index.js";
+import { createIdentityResponder, type IdentityResponseOptions } from "./response.js";
+
+export function refusesMachineActorRequest(
+  route: string,
+  method: string | undefined,
+  isMachineActor: boolean | undefined,
+  writeRoutes: readonly string[] = [],
+): boolean {
+  if (isMachineActor === false) return false;
+  const verb = (method ?? "").toUpperCase();
+  return verb !== "GET" && verb !== "HEAD" && !writeRoutes.includes(route);
+}
+export function sendMachineActorWriteRefused(res: HttpResponse, options: IdentityResponseOptions = {}): void {
+  const { sendBffError } = createIdentityResponder(options);
+  sendBffError(res, "FORBIDDEN", "Human operator required", {
+    details: { reason: "machine_actor_write_refused" },
+  });
+}

package/src/identity/magicLinkPorts.ts

@@ -0,0 +1,7 @@
+export interface MagicLinkAuthClient {
+  auth: { signInWithOtp(input: { email: string; options: { shouldCreateUser: false; emailRedirectTo: string } }): Promise<{ error: { name?: string; message?: string } | null }> };
+}
+export interface MagicLinkRateLimitClient {
+  rpc(fn: string, args: Record<string, unknown>): Promise<{ data: unknown; error: { message?: string } | null }>;
+}
+export interface MagicLinkDecision { allowed: boolean; reason?: string }

package/src/identity/managedAccountLinkStore.ts

@@ -0,0 +1,105 @@
+import type { ManagedIdentityClient, ManagedIdentityRow } from "./managedClient.js";
+import type {
+  AccountLinkStore,
+  CreateAccountInput,
+  CustomerAccount,
+  LinkPrincipalResult,
+} from "./ports.js";
+
+
+export function createSupabaseAccountLinkStore(rawClient: unknown): AccountLinkStore {
+  const client = rawClient as ManagedIdentityClient;
+  return {
+    async findAccountByPrincipalId(principalId: string): Promise<CustomerAccount | null> {
+      const { data, error } = await client
+        .from("clients")
+        .select("id, email, auth_user_id")
+        .eq("auth_user_id", principalId)
+        .maybeSingle();
+      if (error) throw error;
+      if (!data) return null;
+      return { id: data.id, email: data.email ?? null, principalId: data.auth_user_id ?? null };
+    },
+
+    async findAccountByEmail(email: string): Promise<CustomerAccount | null> {
+      const rows = await findManagedContactsByEmail(client, email, false);
+      if (rows.length > 1) {
+        throw Object.assign(new Error("multiple rows returned"), { code: "PGRST116" });
+      }
+      const data = rows[0];
+      if (!data) return null;
+      return { id: data.id, email: data.email ?? null, principalId: data.auth_user_id ?? null };
+    },
+
+    async isReservedPrincipal(principalId: string): Promise<boolean> {
+      const { data, error } = await client
+        .from("admin_users")
+        .select("id, is_machine_actor")
+        .eq("id", principalId)
+        .maybeSingle();
+      if (error) throw error;
+      if (!data) return false;
+      return data.is_machine_actor !== false;
+    },
+
+    async linkPrincipalToAccount(
+      accountId: string,
+      principalId: string,
+    ): Promise<LinkPrincipalResult> {
+      const { data, error } = await client
+        .from("clients")
+        .update({ auth_user_id: principalId })
+        .eq("id", accountId)
+        .is("auth_user_id", null)
+        .select("auth_user_id")
+        .maybeSingle();
+      if (error) throw error;
+      if (data?.auth_user_id === principalId) {
+        return { ok: true, alreadyLinked: false };
+      }
+
+      const { data: current, error: currentError } = await client
+        .from("clients")
+        .select("auth_user_id")
+        .eq("id", accountId)
+        .maybeSingle();
+      if (currentError) throw currentError;
+      if (current?.auth_user_id === principalId) {
+        return { ok: true, alreadyLinked: true };
+      }
+      return { ok: false, existingPrincipalId: current?.auth_user_id ?? null };
+    },
+
+    async createAccount(input: CreateAccountInput): Promise<{ id: string }> {
+      const { data, error } = await client
+        .from("clients")
+        .insert({
+          email: input.email,
+          auth_user_id: input.principalId,
+          acquisition_source: input.acquisitionSource,
+          lifecycle_stage: input.lifecycleStage,
+        })
+        .select("id")
+        .single();
+      if (error) throw error;
+      return { id: data!.id };
+    },
+  };
+}
+
+async function findManagedContactsByEmail(
+  client: ManagedIdentityClient,
+  email: string,
+  oldestFirst: boolean,
+): Promise<ManagedIdentityRow[]> {
+  const normalized = email.trim().toLowerCase();
+  // Escaping bounds the database prefilter; Unicode regex folding can still
+  // widen it, so only exact normalized addresses may cross this boundary.
+  let query = client.from("clients")
+    .select("id, email, auth_user_id")
+    .filter("email", "imatch", `^${normalized.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&")}$`);
+  if (oldestFirst) query = query.order("created_at", { ascending: true });
+  const { data, error } = await query.limit(10);
+  if (error) throw error;
+  return (data ?? []).filter((row) => row.email?.trim().toLowerCase() === normalized);
+}

package/src/identity/managedAdminAuthVerifier.ts

@@ -0,0 +1,40 @@
+import type { SupabaseCreateClient } from "../data/index.js";
+import type { ManagedIdentityClient } from "./managedClient.js";
+import type { AdminAuthPort, AdminAuthorizationResult, AdminPrincipalRole } from "./ports.js";
+import { authorizeAdminWithUser, type AdminAuthorization } from "./adminAuthorization.js";
+
+export function createSupabaseAdminAuth(rawClient: unknown): AdminAuthPort {
+  const client = rawClient as ManagedIdentityClient;
+  return {
+    async authorize(
+      accessToken: string | null,
+      options?: { allowedRoles?: readonly AdminPrincipalRole[] },
+    ): Promise<AdminAuthorizationResult> {
+      const authz: AdminAuthorization = await authorizeAdminWithUser(client, accessToken, options);
+      if (authz.ok === false) {
+        return { ok: false, code: authz.code, message: authz.message };
+      }
+      return {
+        ok: true,
+        principalId: authz.userId,
+        role: authz.role,
+        isMachineActor: authz.isMachineActor,
+      };
+    },
+  };
+}
+
+
+export function createSupabaseAdminAuthFromEnv(
+  env: { url: string; anonKey: string },
+  accessToken: string | null,
+  createClient: SupabaseCreateClient,
+): AdminAuthPort {
+  const client = createClient(env.url, env.anonKey, {
+    auth: { persistSession: false, autoRefreshToken: false },
+    global: {
+      headers: accessToken ? { Authorization: `Bearer ${accessToken}` } : {},
+    },
+  });
+  return createSupabaseAdminAuth(client as ManagedIdentityClient);
+}

package/src/identity/managedAdminUserGateways.ts

@@ -0,0 +1,164 @@
+import type { AdminUserInviteRole } from "./inviteAdminUserUseCase.js";
+import type { ManagedOperatorMembershipResult, OperatorInvitationConflict } from "./contracts/operatorInvitations.js";
+import type { ManagedIdentityClient } from "./managedClient.js";
+import type { InviteAdminUserGateway } from "./inviteAdminUserUseCase.js";
+import type { RemoveAdminUserGateway } from "./removeAdminUserUseCase.js";
+interface InviteAdminUserQuery {
+  insert(row: { id: string; email: string; role: AdminUserInviteRole; membership_state: "active"; membership_provenance: "invitation"; membership_accepted_at: string }): PromiseLike<{ error: { code?: string; message?: string } | null }>;
+  select(columns: string): { eq(column: string, value: string): {
+    maybeSingle(): PromiseLike<{ data: { id: string; role?: string; membership_state?: string; is_machine_actor?: boolean | null } | null; error?: unknown }>;
+  } };
+}
+export interface InviteAdminUserClient {
+  auth: {
+    getUser(token: string): PromiseLike<{ data: { user: { id: string } | null }; error: unknown }>;
+    admin: {
+      listUsers(options: { page: number; perPage: number }): PromiseLike<{ data: { users: Array<{ id: string; email?: string | null }>; nextPage?: number | null } | null; error: unknown }>;
+      inviteUserByEmail(email: string, options: { redirectTo: string }): PromiseLike<{
+        data: { user: { id: string } | null }; error: { message: string } | null;
+      }>;
+    };
+  };
+  from(table: "admin_users"): InviteAdminUserQuery;
+}
+
+interface RemoveAdminUserQuery {
+  select(columns: string): {
+    eq(column: string, value: string): RemoveAdminUserQueryResult;
+  };
+}
+
+interface RemoveAdminUserQueryResult {
+  eq(column: string, value: string): RemoveAdminUserQueryResult;
+  maybeSingle(): PromiseLike<{ data: { id: string; role: string } | null; error: { message: string } | null }>;
+}
+
+export interface RemoveAdminUserClient {
+  auth: {
+    getUser(token: string): PromiseLike<{ data: { user: { id: string } | null }; error: unknown }>;
+  };
+  from(table: "admin_users"): RemoveAdminUserQuery;
+  rpc(
+    fn: "admin_revoke_admin_user",
+    args: { p_target: string; p_reason: string | null },
+  ): PromiseLike<{ error: { message: string } | null }>;
+}
+
+export function createInviteAdminUserGateway(clientFactory: () => InviteAdminUserClient): InviteAdminUserGateway & {
+  activateMembership(input: { principalId: string; email: string; role: AdminUserInviteRole }): Promise<ManagedOperatorMembershipResult | { code: OperatorInvitationConflict }>;
+} {
+  let client: InviteAdminUserClient | null = null;
+  const getClient = (): InviteAdminUserClient => client ??= clientFactory();
+
+  async function membership(principalId: string) {
+    const { data, error } = await getClient().from("admin_users").select("id, role, membership_state, is_machine_actor").eq("id", principalId).maybeSingle();
+    if (error) throw error;
+    return data;
+  }
+  function existing(row: NonNullable<Awaited<ReturnType<typeof membership>>>, role: AdminUserInviteRole): ManagedOperatorMembershipResult | { code: OperatorInvitationConflict } {
+    if (row.is_machine_actor !== false) return { code: "IDENTITY_CONFLICT" };
+    if (row.membership_state === "revoked") return { code: "MANAGED_REINVITE_UNSUPPORTED" };
+    if (row.membership_state !== "active") return { code: "IDENTITY_CONFLICT" };
+    if (row.role !== role) return { code: "INVITATION_ROLE_CONFLICT" };
+    return { principalId: row.id, role, membershipState: "active", code: "ALREADY_ACTIVE" };
+  }
+  return {
+    async activateMembership(input) {
+      const before = await membership(input.principalId);
+      if (before) return existing(before, input.role);
+      const { error } = await getClient().from("admin_users").insert({ id: input.principalId, email: input.email, role: input.role,
+        membership_state: "active", membership_provenance: "invitation", membership_accepted_at: new Date().toISOString() });
+      if (error) {
+        if (error.code !== "23505") throw error;
+        const raced = await membership(input.principalId);
+        if (!raced) throw error;
+        return existing(raced, input.role);
+      }
+      return { principalId: input.principalId, role: input.role, membershipState: "active", code: "MEMBERSHIP_CREATED" };
+    },
+    async getUser(accessToken) {
+      const { data, error } = await getClient().auth.getUser(accessToken);
+      return { user: data?.user ?? null, error };
+    },
+    async findAdminUser(userId) {
+      const { data, error } = await getClient()
+        .from("admin_users")
+        .select("id, role, membership_state, is_machine_actor")
+        .eq("id", userId)
+        .maybeSingle();
+      if (error) throw error;
+      return data && typeof data.role === "string" && typeof data.membership_state === "string" ? { id: data.id, role: data.role, membership_state: data.membership_state, is_machine_actor: data.is_machine_actor !== false } : null;
+    },
+    async findAdminUserByEmail(email) {
+      const { data, error } = await getClient()
+        .from("admin_users")
+        .select("id")
+        .eq("email", email)
+        .maybeSingle();
+      if (error) throw error;
+      return data ? { id: data.id } : null;
+    },
+    async findAuthUserByEmail(email) {
+      const normalizedEmail = email.trim().toLowerCase();
+      const perPage = 1000;
+      const maxUsers = 5000;
+      let page = 1;
+      let scanned = 0;
+      while (scanned < maxUsers) {
+        const { data, error } = await getClient().auth.admin.listUsers({ page, perPage });
+        if (error) throw error;
+        const users = data?.users ?? [];
+        const match = users.find((user) => (user.email ?? "").trim().toLowerCase() === normalizedEmail);
+        if (match) return { id: match.id, email: match.email };
+        scanned += users.length;
+        if (!data?.nextPage) return null;
+        page = data.nextPage;
+      }
+      throw new Error("auth_user_lookup_cap_exceeded");
+    },
+    async inviteAuthUser(input) {
+      const { data, error } = await getClient().auth.admin.inviteUserByEmail(input.email, {
+        redirectTo: input.redirectTo,
+      });
+      return { user: data.user, error };
+    },
+  };
+}
+
+export function createRemoveAdminUserGateway(clientFactory: () => RemoveAdminUserClient): RemoveAdminUserGateway {
+  let client: RemoveAdminUserClient | null = null;
+  const getClient = (): RemoveAdminUserClient => client ??= clientFactory();
+
+  return {
+    async getUser(accessToken) {
+      const { data, error } = await getClient().auth.getUser(accessToken);
+      return { user: data?.user ?? null, error };
+    },
+    async findAdminUser(userId) {
+      const { data, error } = await getClient()
+        .from("admin_users")
+        .select("id, role")
+        .eq("id", userId)
+        .eq("membership_state", "active")
+        .maybeSingle();
+      if (error) throw error;
+      return data;
+    },
+    async revokeAdminUser(userId) {
+      return await getClient().rpc("admin_revoke_admin_user", {
+        p_target: userId,
+        p_reason: null,
+      });
+    },
+  };
+}
+
+
+/** Managed eligibility depends only on active native membership and known roles. */
+export async function managedOperatorMagicLinkEligibility(rawClient: unknown, email: string): Promise<"eligible" | "not_allowlisted" | "role_not_allowed"> {
+  const client = rawClient as ManagedIdentityClient;
+  const { data, error } = await client.from("admin_users").select("id, role").eq("email", email.trim().toLowerCase()).eq("membership_state", "active").maybeSingle();
+  if (error) throw error;
+  if (!data) return "not_allowlisted";
+  return data.role === "admin" || data.role === "distributor" ? "eligible" : "role_not_allowed";
+}