@openlup/platform 0.15.0 → 0.17.0

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

package/src/identity/managedClient.ts

@@ -0,0 +1,58 @@
+import type { SupabaseCreateClient } from "../data/index.js";
+
+export interface ManagedIdentityUser {
+  id: string;
+  email?: string | null;
+  email_confirmed_at?: string | null;
+  user_metadata?: Record<string, unknown> | null;
+}
+export interface ManagedIdentityRow {
+  id: string;
+  email?: string | null;
+  auth_user_id?: string | null;
+  role?: string | null;
+  is_machine_actor?: boolean | null;
+  membership_state?: string;
+}
+export interface ManagedIdentityQuery extends PromiseLike<{ data: ManagedIdentityRow[] | null; error: unknown }> {
+  select(columns: string): ManagedIdentityQuery;
+  eq(column: string, value: string): ManagedIdentityQuery;
+  filter(column: string, operator: "imatch", value: string): ManagedIdentityQuery;
+  is(column: string, value: null): ManagedIdentityQuery;
+  order(column: string, options: { ascending: boolean }): ManagedIdentityQuery;
+  limit(count: number): ManagedIdentityQuery;
+  maybeSingle(): PromiseLike<{ data: ManagedIdentityRow | null; error: unknown }>;
+  single(): PromiseLike<{ data: ManagedIdentityRow | null; error: unknown }>;
+}
+export interface ManagedIdentityTable {
+  select(columns: string): ManagedIdentityQuery;
+  update(value: Record<string, unknown>): ManagedIdentityQuery;
+  insert(value: Record<string, unknown>): ManagedIdentityQuery;
+}
+/** Only the methods consumed by the identity adapters; the host owns the SDK. */
+export interface ManagedIdentityClient {
+  from(table: string): ManagedIdentityTable;
+  auth: {
+    getUser(token: string): PromiseLike<{ data: { user: ManagedIdentityUser | null }; error: unknown }>;
+    admin: {
+      listUsers(options: { page: number; perPage: number }): PromiseLike<{
+        data: { users: ManagedIdentityUser[]; nextPage?: number | null }; error: unknown;
+      }>;
+      getUserById(id: string): PromiseLike<{ data: { user: ManagedIdentityUser | null }; error: unknown }>;
+      createUser(input: { email: string; email_confirm: boolean }): PromiseLike<{ data: { user: ManagedIdentityUser | null }; error: unknown }>;
+    };
+  };
+}
+
+export function createManagedIdentityClients(createClient: SupabaseCreateClient) {
+  const actor = (env: { url: string; anonKey: string }, accessToken: string | null): ManagedIdentityClient =>
+    createClient(env.url, env.anonKey, {
+      auth: { persistSession: false, autoRefreshToken: false },
+      global: { headers: accessToken ? { Authorization: `Bearer ${accessToken}` } : {} },
+    }) as ManagedIdentityClient;
+  const service = (env: { url: string; serviceRoleKey: string }): ManagedIdentityClient =>
+    createClient(env.url, env.serviceRoleKey, {
+      auth: { persistSession: false, autoRefreshToken: false },
+    }) as ManagedIdentityClient;
+  return { actor, service };
+}

package/src/identity/managedClientAuthLink.ts

@@ -0,0 +1,120 @@
+import type { EmailTrustPolicy } from "./emailTrustPolicy.js";
+import type { ManagedIdentityClient, ManagedIdentityRow, ManagedIdentityUser } from "./managedClient.js";
+import type { ClientAuthLinkStore } from "./ports.js";
+export function createSupabaseClientAuthLinkStore(rawClient: unknown, emailTrustPolicy: EmailTrustPolicy): ClientAuthLinkStore {
+  const client = rawClient as ManagedIdentityClient;
+  return {
+    emailTrustPolicy,
+    async findClientByEmail(email) {
+      const rows = await findManagedContactsByEmail(client, email, true);
+      const row = rows[0];
+      if (!row) return null;
+      return { id: row.id, authUserId: row.auth_user_id ?? null };
+    },
+
+    async findAuthUserIdByEmail(email) {
+      const perPage = 1000;
+      const maxUsers = 5000;
+      let page = 1;
+      let scanned = 0;
+
+      while (scanned < maxUsers) {
+        const { data, error } = await client.auth.admin.listUsers({ page, perPage });
+        if (error) throw error;
+        const users: ManagedIdentityUser[] = data.users;
+        const match = users.find(
+          (u) => (u.email ?? "").trim().toLowerCase() === email,
+        );
+        if (match) return match.id;
+        scanned += users.length;
+        const nextPage = "nextPage" in data ? data.nextPage : null;
+        if (!nextPage) return null;
+        page = nextPage;
+      }
+
+      throw new Error("auth_user_lookup_cap_exceeded");
+    },
+
+    async findAuthUserEmailById(authUserId) {
+      const { data, error } = await client.auth.admin.getUserById(authUserId);
+      if (error) throw error;
+      return data.user?.email ?? null;
+    },
+
+    async createAuthUser(email) {
+      const { data, error } = await client.auth.admin.createUser({
+        email,
+        email_confirm: false,
+      });
+      if (error && isAlreadyRegistered(error)) return null;
+      if (error) throw error;
+      if (!data.user) throw new Error("createUser returned no user");
+      return data.user.id;
+    },
+
+    async findAdminIdentity(authUserId) {
+      const { data, error } = await client
+        .from("admin_users")
+        .select("id, is_machine_actor")
+        .eq("id", authUserId)
+        .maybeSingle();
+      if (error) throw error;
+      if (!data) return null;
+      return { isMachineActor: data.is_machine_actor !== false };
+    },
+
+    async setClientAuthUserId(clientId, authUserId) {
+      const { data, error } = await client
+        .from("clients")
+        .update({ auth_user_id: authUserId })
+        .eq("id", clientId)
+        .is("auth_user_id", null)
+        .select("auth_user_id")
+        .maybeSingle();
+      if (error) throw error;
+      if (data?.auth_user_id === authUserId) {
+        return { ok: true, alreadyLinked: false };
+      }
+
+      const { data: current, error: currentError } = await client
+        .from("clients")
+        .select("auth_user_id")
+        .eq("id", clientId)
+        .maybeSingle();
+      if (currentError) throw currentError;
+      if (current?.auth_user_id === authUserId) {
+        return { ok: true, alreadyLinked: true };
+      }
+      return {
+        ok: false,
+        code: "CLIENT_AUTH_LINK_CONFLICT",
+        existingAuthUserId: current?.auth_user_id ?? null,
+      };
+    },
+  };
+}
+
+
+function isAlreadyRegistered(error: unknown): boolean {
+  const failure = (error ?? {}) as { code?: unknown; status?: unknown; message?: unknown };
+  if (failure.code === "email_exists" || failure.code === "user_already_exists") return true;
+  return failure.status === 422 && typeof failure.message === "string"
+    && /already (been )?registered/i.test(failure.message);
+}
+
+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/managedCustomerMe.ts

@@ -0,0 +1,52 @@
+import type { ManagedIdentityClient } from "./managedClient.js";
+import type { CustomerMeResponse } from "./customerContracts.js";
+import type { CustomerMePort } from "./customerPorts.js";
+
+type ManagedCustomerClient = ManagedIdentityClient;
+type LinkedCustomerRow = {
+  id: string;
+  email: string;
+  first_name: string | null;
+  last_name: string | null;
+  phone: string | null;
+  lifecycle_stage: CustomerMeResponse["lifecycleStage"];
+};
+
+export async function readLinkedCustomer(
+  rawClient: unknown,
+  userId: string,
+  includePhone = false,
+): Promise<LinkedCustomerRow | null> {
+  const client = rawClient as ManagedCustomerClient;
+  const { data, error } = await client
+    .from("clients")
+    .select(includePhone
+      ? "id, email, first_name, last_name, phone, lifecycle_stage"
+      : "id, email, first_name, last_name, lifecycle_stage")
+    .eq("auth_user_id", userId)
+    .maybeSingle();
+  if (error) throw error;
+  return data as unknown as LinkedCustomerRow | null;
+}
+
+
+export function createSupabaseCustomerMePort(
+  rawClient: unknown,
+): CustomerMePort {
+  const client = rawClient as ManagedCustomerClient;
+  return {
+    async getCustomerMe(userId): Promise<CustomerMeResponse | null> {
+      const data = await readLinkedCustomer(client, userId);
+      if (!data) return null;
+
+      return {
+        clientId: data.id,
+        email: data.email,
+        firstName: data.first_name,
+        lastName: data.last_name,
+        lifecycleStage:
+          data.lifecycle_stage as CustomerMeResponse["lifecycleStage"],
+      };
+    },
+  };
+}

package/src/identity/managedEmailTrustPolicy.ts

@@ -0,0 +1,90 @@
+import type { EmailTrustAssessment, EmailTrustPolicy } from "./emailTrustPolicy.js";
+
+const unavailable: EmailTrustAssessment = { trusted: false, code: "EMAIL_TRUST_SETTINGS_UNAVAILABLE" };
+const refused: EmailTrustAssessment = { trusted: false, code: "EMAIL_TRUST_ENVELOPE_REFUSED" };
+const providerId = /^[a-z][a-z0-9_-]*$/;
+/** Server-side assertion by the adopter, never a provider certification. */
+export function parseEmailVerifyingProviders(value: string): readonly string[] {
+  if (!value.trim()) return [];
+  const entries = value.split(",").map(entry => entry.trim().toLowerCase());
+  if (entries.some(entry => !providerId.test(entry))) throw new Error("Invalid email-verifying provider declaration");
+  return [...new Set(entries)].sort();
+}
+
+/** One immutable origin/key/allowlist binding; import and construction perform no I/O. */
+export function createManagedEmailTrustPolicy(options: {
+  authBaseUrl: string;
+  publicKey: string;
+  emailVerifyingProviders?: readonly string[];
+  fetch?: typeof globalThis.fetch;
+  now?: () => number;
+}): EmailTrustPolicy {
+  const origin = new URL(options.authBaseUrl);
+  if (!["http:", "https:"].includes(origin.protocol) || origin.username || origin.password
+    || origin.pathname !== "/" || origin.search || origin.hash || !options.publicKey.trim()) {
+    throw new Error("Invalid identity email-trust configuration");
+  }
+  const url = new URL("/auth/v1/settings", origin);
+  const publicKey = options.publicKey;
+  const allowed = new Set(parseEmailVerifyingProviders((options.emailVerifyingProviders ?? []).join(",")));
+  const fetchSettings = options.fetch ?? globalThis.fetch;
+  const now = options.now ?? Date.now;
+  let cached: { result: EmailTrustAssessment; expires: number } | undefined;
+  let inFlight: Promise<EmailTrustAssessment> | undefined;
+
+  function decode(value: unknown): EmailTrustAssessment {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return unavailable;
+    const { mailer_autoconfirm: automatic, external } = value as Record<string, unknown>;
+    if (typeof automatic !== "boolean" || !external || typeof external !== "object" || Array.isArray(external)) return unavailable;
+    const entries = Object.entries(external);
+    if (entries.some(([key, enabled]) => !providerId.test(key) || typeof enabled !== "boolean")) return unavailable;
+    if (automatic || entries.some(([key, enabled]) => enabled && key !== "email" && !allowed.has(key))) return refused;
+    return { trusted: true };
+  }
+
+  async function load(): Promise<EmailTrustAssessment> {
+    const controller = new AbortController();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const deadline = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => { controller.abort(); reject(new Error("Identity settings deadline")); }, 3000);
+    });
+    async function read(): Promise<EmailTrustAssessment> {
+      const response = await fetchSettings(url, {
+        headers: { apikey: publicKey }, redirect: "error", signal: controller.signal,
+      });
+      if (!response.ok || response.redirected || !response.body) return unavailable;
+      const reader = response.body.getReader();
+      let bytes = 0;
+      const chunks: Uint8Array[] = [];
+      try {
+        while (true) {
+          const chunk = await reader.read();
+          if (chunk.done) break;
+          bytes += chunk.value.byteLength;
+          if (bytes > 65536) { controller.abort(); void reader.cancel().catch(() => {}); return unavailable; }
+          chunks.push(chunk.value);
+        }
+      } finally { reader.releaseLock(); }
+      const body = new Uint8Array(bytes);
+      let offset = 0;
+      for (const chunk of chunks) { body.set(chunk, offset); offset += chunk.byteLength; }
+      return decode(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(body)));
+    }
+    try { return await Promise.race([read(), deadline]); }
+    catch { return unavailable; }
+    finally { controller.abort(); clearTimeout(timer); }
+  }
+  return {
+    async assess() {
+      if (cached && now() < cached.expires) return cached.result;
+      if (!inFlight) {
+        inFlight = load().then(result => {
+          const ttl = !result.trusted && result.code === "EMAIL_TRUST_SETTINGS_UNAVAILABLE" ? 5000 : 60000;
+          cached = { result, expires: now() + ttl };
+          return result;
+        }).finally(() => { inFlight = undefined; });
+      }
+      return inFlight;
+    },
+  };
+}

package/src/identity/managedIdentityVerifier.ts

@@ -0,0 +1,20 @@
+import type { ManagedIdentityClient } from "./managedClient.js";
+import type { IdentityVerifierPort, VerifiedPrincipal } from "./ports.js";
+
+
+export function createSupabaseIdentityVerifier(rawClient: unknown): IdentityVerifierPort {
+  const client = rawClient as ManagedIdentityClient;
+  return {
+    async verifyAccessToken(accessToken: string): Promise<VerifiedPrincipal | null> {
+      const { data, error } = await client.auth.getUser(accessToken);
+      if (error || !data.user) return null;
+
+      const user = data.user;
+      return {
+        principalId: user.id,
+        email: user.email ?? null,
+        emailVerified: Boolean(user.email_confirmed_at),
+      };
+    },
+  };
+}

package/src/identity/managedPrivacy.ts

@@ -0,0 +1,37 @@
+import type { ManagedIdentityClient } from "./managedClient.js";
+import { PrivacyRefusal, type PrivacyStore } from "./privacyPorts.js";
+import type { PrivacyJson } from "./contracts/privacy.js";
+
+/** Reads only committed service projections. No managed write or provider delete is composed. */
+export function createManagedPrivacyStore(): PrivacyStore<ManagedIdentityClient> {
+  const refuse = async (): Promise<never> => { throw new PrivacyRefusal("MANAGED_PRIVACY_ERASURE_UNAVAILABLE"); };
+  return {
+    erasureSupported: false, prepareErasure: refuse, authorizeErasure: refuse, eraseIdentity: refuse, saveReceipt: refuse,
+    async findReceipt() { return null; },
+    async resolve(client, ref) {
+      const query = client.from("clients").select("id, email, auth_user_id, first_name, last_name, phone");
+      const { data: contact, error } = await query.eq(ref.kind === "contact" ? "id" : "auth_user_id", ref.kind === "contact" ? ref.contactId : ref.principalId).maybeSingle();
+      if (error) throw new PrivacyRefusal("PRIVACY_ASSESSMENT_UNAVAILABLE");
+      const principalId = ref.kind === "principal" ? ref.principalId : contact?.auth_user_id ?? null;
+      let principal: PrivacyJson = null;
+      let membership: PrivacyJson = null;
+      if (principalId) {
+        const result = await client.auth.admin.getUserById(principalId);
+        if (result.error) {
+          const failure = result.error as { status?: unknown; code?: unknown };
+          if (!contact && (failure.status === 404 || failure.code === "user_not_found")) return null;
+          throw new PrivacyRefusal("PRIVACY_ASSESSMENT_UNAVAILABLE");
+        }
+        if (result.data.user) principal = { principal_id: result.data.user.id, email: result.data.user.email ?? null, email_confirmed_at: result.data.user.email_confirmed_at ?? null };
+        const read = await client.from("admin_users").select("id, membership_state, role, is_machine_actor").eq("id", principalId).maybeSingle();
+        if (read.error) throw new PrivacyRefusal("PRIVACY_ASSESSMENT_UNAVAILABLE");
+        membership = read.data ? JSON.parse(JSON.stringify(read.data)) as PrivacyJson : null;
+      }
+      if (!contact && !principal) return null;
+      return { contactId: contact?.id ?? null, principalId, identity: {
+        contact: contact ? JSON.parse(JSON.stringify(contact)) as PrivacyJson : null, principal, membership,
+        unavailable: ["contact.country", "identity.audit-history", "identity.invitation-history", "identity.erasure-receipts"],
+      } };
+    },
+  };
+}

package/src/identity/messages.ts

@@ -0,0 +1,41 @@
+type Role = "admin" | "distributor";
+const roleName = (role: Role) => role === "admin" ? "Admin" : "Dystrybutor";
+const en = {
+  unauthorized: "Unauthorized", invalidToken: "Invalid token",
+  inviteForbidden: "Only admins may invite users", emailRequired: "Email required",
+  invalidRole: "Invalid role", alreadyAdded: "This user is already added",
+  addFailed: (detail: string) => `Adding user failed: ${detail}`,
+  notificationFailed: (detail: string) => `Role added, but notification failed: ${detail}`,
+  roleAddedDisabled: (email: string, role: Role) => `User ${email} already had an account; added role ${role}, but notification was disabled and not sent.`,
+  roleAddedSuppressed: (email: string, role: Role) => `User ${email} already had an account; added role ${role}, but notification was suppressed and not sent.`,
+  roleAdded: (email: string, role: Role) => `User ${email} already had an account; added role ${role} and sent a notification.`,
+  inviteFailed: (detail: string) => `Invitation failed: ${detail}`,
+  roleInsertFailed: (detail: string) => `Account created, but adding role failed: ${detail}`,
+  invited: (email: string, role: Role) => `Invitation with role ${role} sent to ${email}`,
+  removeForbidden: "Only admins may revoke user access", userIdRequired: "User ID required",
+  selfRemoveForbidden: "You cannot revoke your own access",
+  lastAdmin: "At least one active human admin must remain.",
+  selfRevoke: "You cannot revoke your own access.",
+  machineRevoke: "Machine actors cannot be revoked through this route.",
+  adminNotFound: "Admin user not found.", adminRequired: "Admin role required.",
+  revokeFailed: (detail: string) => `Admin access revoke failed: ${detail}`,
+};
+export type IdentityMessages = typeof en;
+export const identityMessages: Readonly<Record<"en" | "pl", IdentityMessages>> = {
+  en,
+  pl: {
+    ...en,
+    inviteForbidden: "Tylko admini mogą zapraszać użytkowników", emailRequired: "Brak emaila",
+    invalidRole: "Nieprawidłowa rola", alreadyAdded: "Ten użytkownik jest już dodany",
+    addFailed: (detail) => `Błąd dodawania: ${detail}`,
+    notificationFailed: (detail) => `Rola dodana, ale nie udało się wysłać powiadomienia: ${detail}`,
+    roleAddedDisabled: (email, role) => `Użytkownik ${email} już miał konto — dodano rolę ${roleName(role)}, ale powiadomienie było wyłączone i nie zostało wysłane.`,
+    roleAddedSuppressed: (email, role) => `Użytkownik ${email} już miał konto — dodano rolę ${roleName(role)}, ale wysłanie powiadomienia zostało zablokowane i nie zostało wysłane.`,
+    roleAdded: (email, role) => `Użytkownik ${email} już miał konto — dodano rolę ${roleName(role)} i wysłano powiadomienie.`,
+    inviteFailed: (detail) => `Błąd zaproszenia: ${detail}`,
+    roleInsertFailed: (detail) => `Konto utworzone, ale błąd dodawania roli: ${detail}`,
+    invited: (email, role) => `Zaproszenie z rolą ${roleName(role)} wysłane na ${email}`,
+    removeForbidden: "Tylko administratorzy mogą odbierać dostęp użytkownikom",
+    userIdRequired: "Brak ID użytkownika", selfRemoveForbidden: "Nie możesz odebrać sobie dostępu",
+  },
+};