@openlup/platform 0.15.0 → 0.17.0

package/src/identity/directOperatorInvitationStore.ts

@@ -0,0 +1,178 @@
+import { createPostgresRoleFreeTransactionLane, type PgQueryExecutor, type PostgresDataGatewayEnv, type PostgresDataGatewayOptions } from "../data/index.js";
+import type { OperatorInvitationStore } from "./operatorInvitationPorts.js";
+import type { OperatorInvitationResult, OperatorRole } from "./contracts/operatorInvitations.js";
+import { assertOperatorInvitationTtl, invitationFailure } from "./operatorInvitationLifecycle.js";
+
+type Row = Record<string, unknown>;
+const iso = (value: unknown): string => value instanceof Date ? value.toISOString() : new Date(String(value)).toISOString();
+const role = (value: unknown): OperatorRole => value === "distributor" ? "distributor" : "admin";
+const snapshot = (row: Row) => ({ principalId: String(row.principal_id), role: role(row.role) });
+function result(row: Row, code: OperatorInvitationResult["code"]): OperatorInvitationResult {
+  return { ...snapshot(row), code, membershipState: "invited", invitationId: String(row.invitation_id), invitedAt: iso(row.invited_at), expiresAt: iso(row.expires_at) };
+}
+async function event(db: PgQueryExecutor, action: string, before: Row | null, after: Row, actor: string | null): Promise<void> {
+  await db.query(`INSERT INTO public.identity_operator_invitation_events
+    (event_id, invitation_id, principal_id, action, actor_kind, actor_principal_id, old_value, new_value, occurred_at)
+    VALUES (gen_random_uuid(), $1, $2, $3, $4, $5, $6::jsonb, $7::jsonb, clock_timestamp())`,
+  [after.invitation_id, after.principal_id, action, actor ? "human" : "system", actor, JSON.stringify(before ?? {}), JSON.stringify(after)]);
+}
+async function lock(db: PgQueryExecutor, id: string): Promise<Row | null> {
+  const principal = (await db.query("SELECT principal_id, email FROM public.platform_human_principals WHERE principal_id = $1", [id])).rows[0];
+  if (!principal) return null;
+  await db.query("SELECT pg_advisory_xact_lock(hashtext($1)::bigint)", [`operator_invitation:${String(principal.email).trim().toLowerCase()}`]);
+  return principal;
+}
+async function membership(db: PgQueryExecutor, id: string): Promise<Row | null> {
+  return (await db.query("SELECT * FROM public.platform_human_memberships WHERE principal_id = $1 FOR UPDATE", [id])).rows[0] ?? null;
+}
+async function machine(db: PgQueryExecutor, id: string): Promise<boolean> {
+  return (await db.query("SELECT EXISTS (SELECT 1 FROM public.platform_control_operators WHERE principal_id = $1) AS present", [id])).rows[0]?.present === true;
+}
+async function lockCommandMemberships(db: PgQueryExecutor, actor: string, target: string): Promise<void> {
+  // Lock both rows in the same order before taking either actor or target locks.
+  await db.query("SELECT principal_id FROM public.platform_human_memberships WHERE principal_id = ANY($1::uuid[]) ORDER BY principal_id FOR UPDATE", [[actor, target]]);
+}
+async function administrator(db: PgQueryExecutor, id: string): Promise<void> {
+  const row = (await db.query("SELECT role, membership_state FROM public.platform_human_memberships WHERE principal_id = $1 FOR SHARE", [id])).rows[0];
+  if (row?.role !== "admin" || row.membership_state !== "active" || await machine(db, id)) throw invitationFailure("HUMAN_ADMIN_REQUIRED", "FORBIDDEN");
+}
+async function invitation(db: PgQueryExecutor, id: string): Promise<Row | null> {
+  const row = (await db.query("SELECT * FROM public.identity_operator_invitations WHERE principal_id = $1 FOR UPDATE", [id])).rows[0];
+  if (!row) return null;
+  // Capture the database clock after serialization; equality is already expired.
+  const expiredNow = (await db.query("SELECT clock_timestamp() >= $1::timestamptz AS expired", [row.expires_at])).rows[0]!.expired;
+  if (row.phase === "invited" && expiredNow === true) {
+    const expired = (await db.query("UPDATE public.identity_operator_invitations SET phase = 'expired', closed_at = expires_at WHERE principal_id = $1 RETURNING *", [id])).rows[0]!;
+    await event(db, "expire", row, expired, null);
+    return expired;
+  }
+  return row;
+}
+
+/** Owner-authority lane, never the actor gateway. One transaction per command. */
+export function createDirectOperatorInvitationStore(env: PostgresDataGatewayEnv, options: PostgresDataGatewayOptions = {}): OperatorInvitationStore & { close(): Promise<void> } {
+  const lane = createPostgresRoleFreeTransactionLane(env, options);
+  const run = <T>(work: (db: PgQueryExecutor) => Promise<T>) => lane.run((db) => work(db as PgQueryExecutor));
+  return {
+    issue(input) {
+      assertOperatorInvitationTtl(input.ttlSeconds);
+      return run(async (db) => {
+        // Serialize same-target commands, then lock both memberships in order.
+        const principal = await lock(db, input.targetPrincipalId);
+        await lockCommandMemberships(db, input.actorPrincipalId, input.targetPrincipalId);
+        await administrator(db, input.actorPrincipalId);
+        if ((await db.query("SELECT 1 FROM public.identity_privacy_erasures WHERE principal_id = $1", [input.targetPrincipalId])).rows.length) return { code: "IDENTITY_CONFLICT" };
+        const email = input.email.trim().toLowerCase();
+        if (!principal || String(principal.email).trim().toLowerCase() !== email || await machine(db, input.targetPrincipalId)) return { code: "IDENTITY_CONFLICT" };
+        const member = await membership(db, input.targetPrincipalId);
+        if (member?.membership_state === "active") return { code: "MEMBERSHIP_ALREADY_ACTIVE" };
+        const previous = await invitation(db, input.targetPrincipalId);
+        if (previous?.phase === "invited") return previous.role === input.role ? result(previous, "ALREADY_INVITED") : { code: "INVITATION_ROLE_CONFLICT" };
+        const collision = (await db.query("SELECT principal_id FROM public.identity_operator_invitations WHERE email_key = $1", [email])).rows[0];
+        if (collision && collision.principal_id !== input.targetPrincipalId) return { code: "IDENTITY_CONFLICT" };
+        const row = (await db.query(`WITH stamp AS (SELECT clock_timestamp() AS at)
+          INSERT INTO public.identity_operator_invitations
+          (principal_id, invitation_id, email_key, role, phase, invited_by, invited_at, expires_at)
+          SELECT $1, gen_random_uuid(), $2, $3, 'invited', $4, stamp.at, stamp.at + $5 * interval '1 second' FROM stamp WHERE true
+          ON CONFLICT (principal_id) DO UPDATE SET invitation_id = EXCLUDED.invitation_id, email_key = EXCLUDED.email_key,
+          role = EXCLUDED.role, phase = 'invited', invited_by = EXCLUDED.invited_by, invited_at = EXCLUDED.invited_at,
+          expires_at = EXCLUDED.expires_at, accepted_at = NULL, closed_at = NULL RETURNING *`,
+        [input.targetPrincipalId, email, input.role, input.actorPrincipalId, input.ttlSeconds])).rows[0]!;
+        await event(db, previous || member ? "reissue" : "issue", previous, row, input.actorPrincipalId);
+        return result(row, previous || member ? "INVITATION_REISSUED" : "INVITATION_CREATED");
+      });
+    },
+    read(id) {
+      return run(async (db) => {
+        if (!await lock(db, id)) return null;
+        const member = await membership(db, id);
+        if (member?.membership_state === "active") return { ...snapshot(member), membershipState: "active" };
+        const pending = await invitation(db, id);
+        if (pending && pending.phase !== "accepted") return { ...snapshot(pending), membershipState: pending.phase === "invited" ? "invited" : pending.phase === "expired" ? "expired" : "revoked" };
+        return member ? { ...snapshot(member), membershipState: "revoked" } : null;
+      });
+    },
+    acceptOperatorInvitation(id) {
+      return run((db) => acceptDirectOperatorInvitationInTransaction(db, id));
+    },
+    remove(input) {
+      return run(async (db) => {
+        const principal = await lock(db, input.targetPrincipalId);
+        await lockCommandMemberships(db, input.actorPrincipalId, input.targetPrincipalId);
+        await administrator(db, input.actorPrincipalId);
+        if (input.actorPrincipalId === input.targetPrincipalId) throw invitationFailure("SELF_REVOKE_FORBIDDEN", "FORBIDDEN");
+        if (!principal || await machine(db, input.targetPrincipalId)) throw invitationFailure("IDENTITY_CONFLICT");
+        const member = await membership(db, input.targetPrincipalId);
+        const pending = await invitation(db, input.targetPrincipalId);
+        if (pending?.phase === "invited") {
+          const cancelled = (await db.query("UPDATE public.identity_operator_invitations SET phase = 'cancelled', closed_at = clock_timestamp() WHERE principal_id = $1 RETURNING *", [input.targetPrincipalId])).rows[0]!;
+          await event(db, "cancel", pending, cancelled, input.actorPrincipalId);
+        }
+        if (member?.membership_state === "active") await db.query("SELECT public.platform_revoke_human_membership($1, $2, $3)", [input.actorPrincipalId, input.targetPrincipalId, input.reason ?? null]);
+        if (!member && !pending) throw invitationFailure("ADMIN_NOT_FOUND", "BAD_REQUEST");
+        return { revoked: true };
+      });
+    },
+    close: lane.close,
+  };
+}
+
+/** Principal creation commits independently; an invitation failure leaves it reusable. */
+export function createDirectOperatorIdentityDirectory(env: PostgresDataGatewayEnv, options: PostgresDataGatewayOptions = {}) {
+  const lane = createPostgresRoleFreeTransactionLane(env, options);
+  return {
+    ensurePrincipal(input: { email: string; redirectTo: string }): Promise<{ principalId: string; created: boolean }> {
+      const email = input.email.trim().toLowerCase();
+      return lane.run(async (executor) => {
+        const db = executor as PgQueryExecutor;
+        await db.query("SELECT pg_advisory_xact_lock(hashtext($1)::bigint)", [`operator_invitation:${email}`]);
+        const matches = (await db.query("SELECT principal_id FROM public.platform_human_principals WHERE lower(btrim(email)) = $1", [email])).rows;
+        if (matches.length > 1) throw invitationFailure("IDENTITY_CONFLICT");
+        if (matches[0]) {
+          const principalId = String(matches[0].principal_id);
+          if (await machine(db, principalId)) throw invitationFailure("IDENTITY_CONFLICT");
+          return { principalId, created: false };
+        }
+        const row = (await db.query("INSERT INTO public.platform_human_principals (principal_id, email) VALUES (gen_random_uuid(), $1) RETURNING principal_id", [email])).rows[0]!;
+        return { principalId: String(row.principal_id), created: true };
+      });
+    },
+    close: lane.close,
+  };
+}
+
+/** Trusted authentication only; caller owns the transaction, including challenge consumption. */
+export async function acceptDirectOperatorInvitationInTransaction(db: PgQueryExecutor, id: string): Promise<import("./contracts/operatorInvitations.js").OperatorInvitationAcceptance> {
+  if (!await lock(db, id) || await machine(db, id)) return { code: "NO_INVITATION" };
+  if ((await db.query("SELECT 1 FROM public.identity_privacy_erasures WHERE principal_id = $1", [id])).rows.length) return { code: "INVITATION_REVOKED" };
+  const member = await membership(db, id);
+  if (member?.membership_state === "active") {
+    if (member.role !== "admin" && member.role !== "distributor") return { code: "NO_INVITATION" };
+    return { code: "ALREADY_ACTIVE", role: member.role };
+  }
+  const pending = await invitation(db, id);
+  if (!pending) return { code: "NO_INVITATION" };
+  if (pending.phase === "expired") return { code: "INVITATION_EXPIRED" };
+  if (pending.phase !== "invited" || (pending.role !== "admin" && pending.role !== "distributor")) return { code: "INVITATION_REVOKED" };
+  const clock = (await db.query("WITH stamp AS (SELECT clock_timestamp() AS at) SELECT at, at >= $1::timestamptz AS expired FROM stamp", [pending.expires_at])).rows[0]!;
+  const at = clock.at;
+  if (clock.expired === true) {
+    const expired = (await db.query("UPDATE public.identity_operator_invitations SET phase = 'expired', closed_at = expires_at WHERE principal_id = $1 RETURNING *", [id])).rows[0]!;
+    await event(db, "expire", pending, expired, null);
+    return { code: "INVITATION_EXPIRED" };
+  }
+  if (member) {
+    const setting = (await db.query("SELECT current_setting('app.platform_human_membership_revoke', true) AS previous")).rows[0]?.previous;
+    await db.query("SELECT set_config('app.platform_human_membership_revoke', 'true', true)");
+    await db.query(`UPDATE public.platform_human_memberships SET membership_state = 'active', membership_provenance = 'invitation',
+      membership_accepted_at = $2, membership_revoked_at = NULL, membership_revoked_by = NULL, membership_revocation_reason = NULL WHERE principal_id = $1`, [id, at]);
+    await db.query("UPDATE public.platform_human_memberships SET role = $2 WHERE principal_id = $1", [id, pending.role]);
+    await db.query("SELECT set_config('app.platform_human_membership_revoke', $1, true)", [setting ?? ""]);
+  } else {
+    await db.query(`INSERT INTO public.platform_human_memberships (principal_id, role, membership_state, membership_provenance, membership_accepted_at)
+      VALUES ($1, $2, 'active', 'invitation', $3)`, [id, pending.role, at]);
+  }
+  const accepted = (await db.query("UPDATE public.identity_operator_invitations SET phase = 'accepted', accepted_at = $2, closed_at = $2 WHERE principal_id = $1 RETURNING *", [id, at])).rows[0]!;
+  await event(db, "accept", pending, accepted, id);
+  return { code: "ACTIVATED", role: role(pending.role) };
+}

package/src/identity/emailTrustPolicy.ts

@@ -0,0 +1,16 @@
+import type { EmailTrustFailureCode } from "./contracts/emailTrust.js";
+export type EmailTrustAssessment = { trusted: true } | { trusted: false; code: EmailTrustFailureCode };
+export interface EmailTrustPolicy { assess(): Promise<EmailTrustAssessment> }
+/** Explicitly retain verifier-only admission. This does not bypass mailbox verification. */
+export function createVerifierResultOnlyEmailTrustPolicy(): EmailTrustPolicy {
+  return { async assess() { return { trusted: true }; } };
+}
+/** Invalid, absent or throwing JavaScript bindings fail closed, including invalid results. */
+export async function assessEmailTrust(policy: EmailTrustPolicy): Promise<EmailTrustAssessment> {
+  try {
+    const result = await policy.assess();
+    if (result?.trusted === true) return { trusted: true };
+    if (result?.trusted === false && result.code === "EMAIL_TRUST_ENVELOPE_REFUSED") return result;
+  } catch { /* Do not expose policy or transport details. */ }
+  return { trusted: false, code: "EMAIL_TRUST_SETTINGS_UNAVAILABLE" };
+}

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