@openlup/platform 0.15.0 → 0.16.0

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

package/src/identity/oidcIdentityVerifier.ts

@@ -0,0 +1,229 @@
+import type { IdentityJwtLibrary, IdentityJwtLibraryLoader, IdentityJwk } from "./jwtLibrary.js";
+import type { IdentityVerifierPort, VerifiedPrincipal } from "./ports.js";
+import type { OidcFailureCode } from "./contracts/oidc.js";
+import { deriveOidcPrincipalId } from "./oidcPrincipal.js";
+
+export interface OidcIdentityVerifierConfig {
+  issuer: string;
+  audience: string;
+  algorithms: readonly ("RS256" | "ES256")[];
+  maxTokenLifetimeSeconds: number;
+  requireSingleAudience?: boolean;
+  /** Conformance only: literal loopback addresses, never arbitrary HTTP hosts. */
+  allowLoopbackHttp?: boolean;
+}
+export type OidcVerificationResult = { ok: true; principal: VerifiedPrincipal; expiresAt: string }
+  | { ok: false; code: OidcFailureCode };
+export interface OidcReadinessReport {
+  state: "ready" | "unknown" | "unsatisfied";
+  discovery: { reachable: boolean; valid: boolean; checkedAt: string | null; expiresAt: string | null };
+  jwks: { loaded: boolean; checkedAt: string | null; expiresAt: string | null };
+  code?: OidcFailureCode;
+}
+export interface OidcIdentityVerifier extends IdentityVerifierPort {
+  verifyToken(token: string): Promise<OidcVerificationResult>;
+  readiness(): Promise<OidcReadinessReport>;
+}
+class Refusal extends Error {
+  constructor(readonly code: OidcFailureCode) { super(code); }
+}
+const refuse = (code: OidcFailureCode): never => { throw new Refusal(code); };
+const record = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+const bounded = (value: unknown, max: number): value is string => typeof value === "string" && value.length > 0 && Buffer.byteLength(value) <= max && !Array.from(value).some(character => character.charCodeAt(0) <= 0x20 || character.charCodeAt(0) === 0x7f);
+const stamp = (value: number | null) => value === null ? null : new Date(value).toISOString();
+const unavailable = (code: OidcFailureCode) => code.endsWith("_UNAVAILABLE") || code === "OIDC_JWKS_REFRESH_RATE_LIMITED";
+
+/** One binding per host/configuration. Imports and construction perform no I/O or JWT loading. */
+export function createOidcIdentityVerifier(config: OidcIdentityVerifierConfig, dependencies: {
+  loadJwt: IdentityJwtLibraryLoader; fetch?: typeof globalThis.fetch; now?: () => number;
+}): OidcIdentityVerifier {
+  const settings = { ...config, algorithms: [...config.algorithms] };
+  const now = dependencies.now ?? Date.now;
+  const transport = dependencies.fetch ?? globalThis.fetch;
+  function validUrl(value: string) {
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash || (url.protocol !== "https:"
+      && !(settings.allowLoopbackHttp && url.protocol === "http:" && ["127.0.0.1", "[::1]"].includes(url.hostname)))) throw new Error();
+    return url;
+  }
+  let origin = "", configurationValid = true;
+  try {
+    if (!bounded(settings.issuer, 2048) || !bounded(settings.audience, 256)
+      || !settings.algorithms.length || settings.algorithms.some(alg => alg !== "RS256" && alg !== "ES256")
+      || !Number.isInteger(settings.maxTokenLifetimeSeconds) || settings.maxTokenLifetimeSeconds < 1 || settings.maxTokenLifetimeSeconds > 3600) throw new Error();
+    origin = validUrl(settings.issuer).origin;
+  } catch { configurationValid = false; }
+  let library: Promise<IdentityJwtLibrary> | undefined;
+  const jwt = () => library ??= Promise.resolve().then(dependencies.loadJwt).catch(() => { library = undefined; return refuse("OIDC_JWT_LIBRARY_UNAVAILABLE"); });
+  let discovery: { jwksUrl: string; expires: number } | undefined;
+  let keys: { values: IdentityJwk[]; expires: number } | undefined;
+  let discoveryCheck: number | null = null, keyCheck: number | null = null, lastKeyAttempt = -Infinity;
+  let reachable = false, discoveryValid = false;
+  let discoveryFlight: Promise<NonNullable<typeof discovery>> | undefined;
+  let keyFlight: Promise<NonNullable<typeof keys>> | undefined;
+  let keyFailure: OidcFailureCode | undefined;
+
+  async function document(url: string, kind: "DISCOVERY" | "JWKS", maxAge: number) {
+    const controller = new AbortController();
+    let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const deadline = new Promise<never>((_, reject) => { timer = setTimeout(() => {
+      controller.abort(); void reader?.cancel().catch(() => {});
+      reject(new Refusal(`OIDC_${kind}_UNAVAILABLE`));
+    }, 3000); });
+    try {
+      return await Promise.race([deadline, (async () => {
+        const response = await transport(url, { redirect: "error", signal: controller.signal, headers: { accept: "application/json" } });
+        if (kind === "DISCOVERY") reachable = true;
+        if (!response.ok) return refuse(`OIDC_${kind}_UNAVAILABLE`);
+        if (response.redirected || (response.url && response.url !== url)) return refuse(`OIDC_${kind}_INVALID`);
+        const length = response.headers.get("content-length");
+        if (length && (!/^\d+$/.test(length) || Number(length) > 65536)) return refuse(`OIDC_${kind}_INVALID`);
+        if (!response.body) return refuse(`OIDC_${kind}_INVALID`);
+        reader = response.body.getReader();
+        const chunks: Uint8Array[] = []; let size = 0;
+        for (;;) {
+          const part = await reader.read(); if (part.done) break;
+          size += part.value.byteLength;
+          if (size > 65536) { void reader.cancel().catch(() => {}); return refuse(`OIDC_${kind}_INVALID`); }
+          chunks.push(part.value);
+        }
+        let value: unknown;
+        try { value = JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch { return refuse(`OIDC_${kind}_INVALID`); }
+        const control = response.headers.get("cache-control") ?? "";
+        const ages = [...control.matchAll(/(?:^|,)\s*max-age\s*=\s*"?(\d+)"?/gi)].map(match => Number(match[1]));
+        const age = Number(response.headers.get("age") ?? "0");
+        // Revalidate no-cache documents at the next permitted JWKS refresh.
+        const cacheBound = /(?:^|,)\s*no-cache(?:\s|,|$)/i.test(control) ? 30 : maxAge;
+        const seconds = /(?:^|,)\s*no-store(?:\s|,|$)/i.test(control) ? 0
+          : Math.max(0, Math.min(maxAge, cacheBound, ...ages) - (Number.isFinite(age) && age >= 0 ? age : maxAge));
+        return { value, expires: now() + seconds * 1000 };
+      })()]);
+    } catch (error) {
+      if (error instanceof Refusal) throw error;
+      return refuse(`OIDC_${kind}_UNAVAILABLE`);
+    } finally { clearTimeout(timer); controller.abort(); }
+  }
+  async function metadata() {
+    if (!configurationValid) return refuse("OIDC_CONFIGURATION_INVALID");
+    if (discovery && discovery.expires > now()) return discovery;
+    if (discoveryFlight) return discoveryFlight;
+    discoveryFlight = (async () => {
+      discoveryCheck = now(); reachable = false; discoveryValid = false;
+      const fetched = await document(`${settings.issuer.replace(/\/$/, "")}/.well-known/openid-configuration`, "DISCOVERY", 3600);
+      if (!record(fetched.value) || fetched.value.issuer !== settings.issuer || typeof fetched.value.jwks_uri !== "string") return refuse("OIDC_DISCOVERY_INVALID");
+      try { if (validUrl(fetched.value.jwks_uri).origin !== origin) throw new Error(); }
+      catch { return refuse("OIDC_DISCOVERY_INVALID"); }
+      if (discovery?.jwksUrl !== fetched.value.jwks_uri) keys = undefined;
+      discoveryValid = true;
+      return discovery = { jwksUrl: fetched.value.jwks_uri, expires: fetched.expires };
+    })();
+    try { return await discoveryFlight; } finally { discoveryFlight = undefined; }
+  }
+  async function keySet(force = false) {
+    const meta = await metadata();
+    if (!force && keys && keys.expires > now()) return keys;
+    if (keyFlight) return keyFlight;
+    if (now() - lastKeyAttempt < 30000) return refuse("OIDC_JWKS_REFRESH_RATE_LIMITED");
+    lastKeyAttempt = now(); keyCheck = now();
+    keyFlight = (async () => {
+      const fetched = await document(meta.jwksUrl, "JWKS", 300);
+      const value = fetched.value;
+      if (!record(value) || !Array.isArray(value.keys) || !value.keys.length || value.keys.length > 64) return refuse("OIDC_JWKS_INVALID");
+      const eligible: IdentityJwk[] = [];
+      for (const key of value.keys) {
+        if (!record(key) || ["d", "p", "q", "dp", "dq", "qi", "oth", "k"].some(field => field in key)) return refuse("OIDC_JWKS_INVALID");
+        if ((key.use !== undefined && key.use !== "sig") || (key.key_ops !== undefined && (!Array.isArray(key.key_ops) || !key.key_ops.length || !key.key_ops.every(operation => operation === "verify")))) continue;
+        const alg = key.alg === undefined ? (key.kty === "RSA" ? "RS256" : key.kty === "EC" && key.crv === "P-256" ? "ES256" : "") : key.alg;
+        if (!settings.algorithms.includes(alg as "RS256" | "ES256")
+          || (alg === "RS256" ? key.kty !== "RSA" : key.kty !== "EC" || key.crv !== "P-256")) continue;
+        if (!bounded(key.kid, 128) || (alg === "RS256" ? !bounded(key.n, 2048) || !bounded(key.e, 16)
+          : !bounded(key.x, 128) || !bounded(key.y, 128))) return refuse("OIDC_JWKS_INVALID");
+        eligible.push({ ...key, alg: String(alg) });
+      }
+      if (!eligible.length || new Set(eligible.map(key => key.kid)).size !== eligible.length) return refuse("OIDC_JWKS_INVALID");
+      const lib = await jwt();
+      try { await Promise.all(eligible.map(key => lib.importJWK(key, key.alg!))); }
+      catch { return refuse("OIDC_JWKS_INVALID"); }
+      keyFailure = undefined;
+      return keys = { values: eligible, expires: fetched.expires };
+    })();
+    try { return await keyFlight; }
+    catch (error) { keyFailure = error instanceof Refusal ? error.code : "OIDC_JWKS_UNAVAILABLE"; throw error; }
+    finally { keyFlight = undefined; }
+  }
+  async function verifyToken(token: string): Promise<OidcVerificationResult> {
+    try {
+      if (!configurationValid) return refuse("OIDC_CONFIGURATION_INVALID");
+      if (typeof token !== "string" || Buffer.byteLength(token) > 16384 || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(token)) return refuse("OIDC_TOKEN_INVALID");
+      let header: unknown, unverifiedPayload: unknown;
+      try {
+        const parts = token.split(".").map(part => {
+          const bytes = Buffer.from(part, "base64url");
+          if (bytes.toString("base64url") !== part) return refuse("OIDC_TOKEN_INVALID");
+          return bytes;
+        });
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        header = JSON.parse(decoder.decode(parts[0]!));
+        unverifiedPayload = JSON.parse(decoder.decode(parts[1]!));
+      } catch { return refuse("OIDC_TOKEN_INVALID"); }
+      if (!record(header) || !record(unverifiedPayload) || !bounded(header.kid, 128)
+        || !settings.algorithms.includes(header.alg as "RS256" | "ES256")) return refuse("OIDC_TOKEN_INVALID");
+      // Unverified claims may refuse before I/O; only verified claims can admit.
+      if (unverifiedPayload.iss !== settings.issuer) return refuse("OIDC_ISSUER_MISMATCH");
+      let set = await keySet();
+      const select = () => set.values.find(key => key.kid === header.kid && key.alg === header.alg);
+      if (!select()) { set = await keySet(true); if (!select()) return refuse("OIDC_KID_UNKNOWN"); }
+      const lib = await jwt();
+      const selected = select()!;
+      let payload;
+      try {
+        const key = await lib.importJWK(selected, String(header.alg));
+        ({ payload } = await lib.jwtVerify(token, async protectedHeader => {
+          if (protectedHeader.alg !== header.alg || protectedHeader.kid !== header.kid) return refuse("OIDC_TOKEN_INVALID");
+          return key;
+        }, { algorithms: settings.algorithms, audience: settings.audience, issuer: settings.issuer, currentDate: new Date(now()), clockTolerance: 0 }));
+      } catch (error) {
+        if (record(error)) {
+          if (error.code === "ERR_JWT_EXPIRED") return refuse("OIDC_TOKEN_EXPIRED");
+          if (error.code === "ERR_JWT_CLAIM_VALIDATION_FAILED") {
+            if (error.claim === "iss") return refuse("OIDC_ISSUER_MISMATCH");
+            if (error.claim === "aud") return refuse("OIDC_AUDIENCE_MISMATCH");
+            if (error.claim === "nbf") return refuse("OIDC_TOKEN_NOT_ACTIVE");
+          }
+        }
+        return refuse("OIDC_TOKEN_INVALID");
+      }
+      if (payload.iss !== settings.issuer) return refuse("OIDC_ISSUER_MISMATCH");
+      if (settings.requireSingleAudience ? payload.aud !== settings.audience
+        : !(payload.aud === settings.audience || (Array.isArray(payload.aud) && payload.aud.every(aud => typeof aud === "string") && payload.aud.includes(settings.audience)))) return refuse("OIDC_AUDIENCE_MISMATCH");
+      const seconds = now() / 1000;
+      if (!Number.isSafeInteger(payload.iat) || !Number.isSafeInteger(payload.exp) || payload.exp! <= payload.iat!
+        || payload.exp! - payload.iat! > settings.maxTokenLifetimeSeconds || payload.iat! > seconds) return refuse("OIDC_TOKEN_LIFETIME_INVALID");
+      if (payload.exp! <= seconds) return refuse("OIDC_TOKEN_EXPIRED");
+      if (payload.nbf !== undefined && (!Number.isSafeInteger(payload.nbf) || payload.nbf > seconds)) return refuse("OIDC_TOKEN_NOT_ACTIVE");
+      if (!bounded(payload.sub, 1024)) return refuse("OIDC_SUBJECT_INVALID");
+      if (!bounded(payload.email, 254) || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(payload.email)) return refuse("OIDC_EMAIL_INVALID");
+      if (payload.email_verified !== true) return refuse("OIDC_EMAIL_UNVERIFIED");
+      return { ok: true, principal: { principalId: deriveOidcPrincipalId(settings.issuer, payload.sub), email: payload.email.trim().toLowerCase(), emailVerified: true }, expiresAt: stamp(payload.exp! * 1000)! };
+    } catch (error) { return { ok: false, code: error instanceof Refusal ? error.code : "OIDC_TOKEN_INVALID" }; }
+  }
+  return {
+    verifyToken,
+    async verifyAccessToken(token) {
+      const result = await verifyToken(token);
+      if (result.ok) return result.principal;
+      if (unavailable(result.code)) throw new Error("OIDC identity verification unavailable");
+      return null;
+    },
+    async readiness() {
+      let code: OidcFailureCode | undefined;
+      try { await keySet(); } catch (error) { code = error instanceof Refusal ? error.code : "OIDC_JWKS_UNAVAILABLE"; }
+      if (code === "OIDC_JWKS_REFRESH_RATE_LIMITED" && keyFailure) code = keyFailure;
+      const fresh = !!keys && keys.expires > now();
+      return { state: code ? unavailable(code) ? "unknown" : "unsatisfied" : fresh ? "ready" : "unsatisfied",
+        discovery: { reachable, valid: discoveryValid && !!discovery && discovery.expires > now(), checkedAt: stamp(discoveryCheck), expiresAt: stamp(discovery?.expires ?? null) },
+        jwks: { loaded: fresh, checkedAt: stamp(keyCheck), expiresAt: stamp(keys?.expires ?? null) }, ...(code ? { code } : {}) };
+    },
+  };
+}