@better-forge/auth 0.0.0-stage → 0.1.0

package/src/oidc.ts

@@ -0,0 +1,291 @@
+import { randomBytes, randomUUID } from 'node:crypto'
+import bcrypt from 'bcryptjs'
+import * as client from 'openid-client'
+import { and, eq, sql } from 'drizzle-orm'
+import { users } from './tables.js'
+import type { AuthOptions } from './context.js'
+import { ADMIN_ROLE } from './roles.js'
+import type { OidcConfig } from './oidcConfig.js'
+import type { SignInAudit } from './signInAudit.js'
+
+type User = typeof users.$inferSelect
+
+export interface OidcFlowState {
+  state: string
+  nonce: string
+  codeVerifier: string
+}
+
+/** An SSO confirmation must come from a sign-in at the provider no older than this (the ID token's auth_time). */
+export const OIDC_CONFIRMATION_MAX_AGE_SECONDS = 5 * 60
+
+/** Why an SSO sign-in was refused. The user only sees a generic message; the audit log gets the code and detail. */
+export type OidcDenialCode =
+  | 'discovery_failed'
+  | 'flow_expired'
+  | 'idp_error'
+  | 'token_exchange_failed'
+  | 'no_email_claim'
+  | 'email_not_verified'
+  | 'no_matching_account'
+  | 'subject_mismatch'
+  | 'confirmation_mismatch'
+
+export interface OidcDenial {
+  code: OidcDenialCode
+  reason: string
+  email?: string
+}
+
+/** An account an SSO sign-in may create, bound to this identity. The application decides who qualifies and the role (see `resolveUnknownSsoUser`). */
+export interface SsoProvisioning {
+  email: string
+  subject: string
+  role: string
+}
+
+/**
+ * The outcome for a set of validated ID token claims. `link` means the user was matched by email and the
+ * identity (issuer + subject) should now be bound to them, so later sign-ins no longer depend on the email.
+ * A denial for an unknown email carries `provision` when a sign-in may create an account instead.
+ */
+export type OidcDecision =
+  | { user: User; link: boolean; subject: string; denial?: undefined; provision?: undefined }
+  | { user: null; denial: OidcDenial; provision?: SsoProvisioning | undefined }
+
+// Some providers send booleans as strings ("true").
+const isTrue = (value: unknown) => value === true || value === 'true'
+
+const isFalse = (value: unknown) => value === false || value === 'false'
+
+/**
+ * Whether the email claim may be trusted. `email_verified` is the standard claim; Microsoft Entra ID never
+ * sends it but offers the optional `xms_edov` claim (email domain owner verified) instead. An explicit
+ * `false` from either claim is never overridden by `allowUnverifiedEmail`.
+ */
+export function checkEmailVerified(claims: Record<string, unknown>, allowUnverifiedEmail: boolean): string | null {
+  const standard = claims['email_verified']
+  const entra = claims['xms_edov']
+  if (isTrue(standard) || isTrue(entra)) return null
+  if (isFalse(standard)) return 'The identity provider reports the email as unverified (email_verified is false).'
+  if (isFalse(entra)) return 'Microsoft Entra ID reports that the email domain is not verified (xms_edov is false).'
+  if (allowUnverifiedEmail && standard === undefined && entra === undefined) return null
+  return 'The ID token has neither an email_verified nor an xms_edov claim. For Microsoft Entra ID, add the xms_edov optional claim to the ID token. '
+    + 'For other providers, enable "Accept identity providers that omit email_verified" only if their email claim is trustworthy.'
+}
+
+// ── Test sign-in ────────────────────────────────────────────────────────────
+// An administrator runs the real flow to see the claims and what would happen, without signing anyone in.
+
+export interface OidcTestResult {
+  issuer: string
+  testedAt: number
+  claims: Record<string, unknown> | null
+  /** `provision`: the sign-in would create an account. */
+  outcome: 'sign_in' | 'link' | 'provision' | 'deny'
+  user: string | null
+  denial: OidcDenial | null
+}
+
+const TEST_RESULT_TTL_MS = 10 * 60 * 1000
+
+export function createOidc(ctx: AuthOptions, signInAudit: SignInAudit) {
+  const { db, audit } = ctx
+  const hooks = ctx.hooks ?? {}
+  const { auditSignInDenial } = signInAudit
+
+  let cached: { key: string; config: Promise<client.Configuration> } | null = null
+
+  function runDiscovery(cfg: OidcConfig): Promise<client.Configuration> {
+    const issuer = new URL(cfg.issuer)
+    // The client library refuses plain http; allow it only for issuers configured that way (e.g. a local Keycloak).
+    const options = issuer.protocol === 'http:' ? { execute: [client.allowInsecureRequests] } : undefined
+    return client.discovery(issuer, cfg.clientId, cfg.clientSecret || undefined, undefined, options)
+  }
+
+  function discover(cfg: OidcConfig): Promise<client.Configuration> {
+    const key = `${cfg.issuer}|${cfg.clientId}|${cfg.clientSecret}`
+    if (cached?.key !== key) {
+      const config = runDiscovery(cfg)
+      config.catch(() => { if (cached?.key === key) cached = null })
+      cached = { key, config }
+    }
+    return cached.config
+  }
+
+  /**
+   * Builds the provider redirect. `confirm` asks the provider to authenticate the user again (`prompt=login`)
+   * and to report when it did (`max_age`), so the callback can require a fresh `auth_time`.
+   */
+  async function beginOidcLogin(cfg: OidcConfig, options: { confirm?: boolean } = {}): Promise<{ url: string; flow: OidcFlowState }> {
+    const config = await discover(cfg)
+    const flow: OidcFlowState = {
+      state: client.randomState(),
+      nonce: client.randomNonce(),
+      codeVerifier: client.randomPKCECodeVerifier(),
+    }
+    const url = client.buildAuthorizationUrl(config, {
+      redirect_uri: cfg.redirectUri,
+      scope: cfg.scopes,
+      state: flow.state,
+      nonce: flow.nonce,
+      code_challenge: await client.calculatePKCECodeChallenge(flow.codeVerifier),
+      code_challenge_method: 'S256',
+      ...(options.confirm ? { prompt: 'login', max_age: String(OIDC_CONFIRMATION_MAX_AGE_SECONDS) } : {}),
+    })
+    return { url: url.href, flow }
+  }
+
+  /**
+   * Completes the code exchange and returns the validated ID token claims, or why that failed. With `maxAge`
+   * the ID token must carry an `auth_time` no older than that many seconds.
+   */
+  async function exchangeOidcCode(
+    cfg: OidcConfig, callbackUrl: URL, flow: OidcFlowState, maxAge?: number,
+  ): Promise<{ claims: Record<string, unknown>; denial?: undefined } | { claims?: undefined; denial: OidcDenial }> {
+    const config = await discover(cfg)
+    try {
+      const tokens = await client.authorizationCodeGrant(config, callbackUrl, {
+        pkceCodeVerifier: flow.codeVerifier,
+        expectedState: flow.state,
+        expectedNonce: flow.nonce,
+        idTokenExpected: true,
+        ...(maxAge !== undefined ? { maxAge } : {}),
+      })
+      return { claims: tokens.claims() ?? {} }
+    } catch (error) {
+      return { denial: describeExchangeError(error) }
+    }
+  }
+
+  /**
+   * Finds the local user for validated claims without changing anything. An identity already bound to a
+   * user wins; otherwise the verified email is matched, but never onto a user bound to another identity at
+   * the same provider, so an email address given to someone else cannot take over the account.
+   */
+  async function evaluateOidcClaims(cfg: OidcConfig, claims: Record<string, unknown>): Promise<OidcDecision> {
+    const subject = typeof claims['sub'] === 'string' ? claims['sub'] : ''
+    if (subject) {
+      const bound = (await db.select().from(users)
+        .where(and(eq(users.oidcIssuer, cfg.issuer), eq(users.oidcSubject, subject))))[0]
+      if (bound) return { user: bound, link: false, subject }
+    }
+
+    const email = typeof claims['email'] === 'string' ? claims['email'].trim().toLowerCase() : ''
+    if (!email) {
+      return {
+        user: null,
+        denial: {
+          code: 'no_email_claim',
+          reason: `The ID token has no email claim. Request the "email" scope and, for Microsoft Entra ID, add the email optional claim. Claims received: ${Object.keys(claims).join(', ') || 'none'}.`,
+        },
+      }
+    }
+    const unverified = checkEmailVerified(claims, cfg.allowUnverifiedEmail)
+    if (unverified) return { user: null, denial: { code: 'email_not_verified', reason: unverified, email } }
+    const user = (await db.select().from(users).where(sql`lower(${users.email}) = ${email}`))[0]
+    if (!user) {
+      const resolved = subject ? await hooks.resolveUnknownSsoUser?.({ email, subject, issuer: cfg.issuer }) : null
+      // A role the application did not register, or admin, is never handed out by a sign-in: no account is created.
+      const provision = subject && resolved && ctx.roles.isValid(resolved.role) && resolved.role !== ADMIN_ROLE ? { email, subject, role: resolved.role } : undefined
+      return { user: null, denial: { code: 'no_matching_account', reason: `No user has the email ${email}. Create the user first.`, email }, provision }
+    }
+    if (user.oidcSubject && user.oidcIssuer === cfg.issuer) {
+      return {
+        user: null,
+        denial: {
+          code: 'subject_mismatch',
+          reason: `${user.email} is linked to another identity at this provider (subject ${user.oidcSubject}; this sign-in: ${subject || 'none'}). `
+            + 'The email address may have been given to someone else.',
+          email,
+        },
+      }
+    }
+    return { user, link: true, subject }
+  }
+
+  /** Binds the provider identity to the user and records it; a binding to a previous issuer is replaced. */
+  async function linkOidcIdentity(cfg: OidcConfig, user: User, subject: string): Promise<void> {
+    await db.update(users).set({ oidcIssuer: cfg.issuer, oidcSubject: subject }).where(eq(users.id, user.id))
+    await audit.write(
+      { userId: user.id, userEmail: user.email },
+      'update', 'user-security', user.id, user.email,
+      { ssoLinked: { from: user.oidcIssuer, to: cfg.issuer }, subject },
+    )
+  }
+
+  /**
+   * Creates the account of a first SSO sign-in, already bound to the identity.
+   * Its password is random and never handed out: the account signs in through SSO only.
+   */
+  async function provisionSsoUser(cfg: OidcConfig, provision: SsoProvisioning): Promise<User> {
+    const passwordHash = await bcrypt.hash(randomBytes(32).toString('base64url'), 10)
+    const [user] = await db.insert(users).values({
+      email: provision.email,
+      passwordHash,
+      role: provision.role,
+      createdAt: Date.now(),
+      oidcIssuer: cfg.issuer,
+      oidcSubject: provision.subject,
+    }).returning()
+    await audit.write(
+      { userId: user!.id, userEmail: user!.email },
+      'create', 'user', user!.id, user!.email,
+      { email: user!.email, role: provision.role, createdBy: 'sso', issuer: cfg.issuer },
+    )
+    return user!
+  }
+
+  /** Records a refused SSO sign-in or confirmation as a 'sign_in' denial, with the issuer. */
+  async function auditOidcDenial(cfg: OidcConfig, denial: OidcDenial): Promise<void> {
+    await auditSignInDenial('sso', denial, { issuer: cfg.issuer })
+  }
+
+  function describeExchangeError(error: unknown): OidcDenial {
+    if (error instanceof client.AuthorizationResponseError) {
+      const description = error.error_description ? `: ${error.error_description}` : ''
+      return { code: 'idp_error', reason: `The identity provider returned ${error.error}${description}`.slice(0, 1000) }
+    }
+    const message = error instanceof Error ? error.message : String(error)
+    return { code: 'token_exchange_failed', reason: `Code exchange or ID token validation failed: ${message}`.slice(0, 1000) }
+  }
+
+  /** Runs OIDC discovery against the issuer without caching, to validate settings before saving them. */
+  async function testOidcDiscovery(cfg: OidcConfig): Promise<{ issuer: string; authorizationEndpoint: string | null }> {
+    const config = await runDiscovery(cfg)
+    const meta = config.serverMetadata()
+    return { issuer: meta.issuer, authorizationEndpoint: meta.authorization_endpoint ?? null }
+  }
+
+  const testResults = new Map<string, { adminUserId: number; expiresAt: number; result: OidcTestResult }>()
+
+  function storeOidcTestResult(adminUserId: number, result: OidcTestResult): string {
+    const now = Date.now()
+    for (const [id, entry] of testResults) if (entry.expiresAt <= now) testResults.delete(id)
+    const id = randomUUID()
+    testResults.set(id, { adminUserId, expiresAt: now + TEST_RESULT_TTL_MS, result })
+    return id
+  }
+
+  /** Only the administrator who started the test can read its result. */
+  function readOidcTestResult(id: string, adminUserId: number): OidcTestResult | null {
+    const entry = testResults.get(id)
+    if (!entry || entry.expiresAt <= Date.now() || entry.adminUserId !== adminUserId) return null
+    return entry.result
+  }
+
+  async function runOidcTest(cfg: OidcConfig, callbackUrl: URL, flow: OidcFlowState): Promise<OidcTestResult> {
+    const base = { issuer: cfg.issuer, testedAt: Date.now() }
+    const exchanged = await exchangeOidcCode(cfg, callbackUrl, flow)
+      .catch((error: unknown) => ({ claims: undefined, denial: describeExchangeError(error) }))
+    if (exchanged.denial) return { ...base, claims: null, outcome: 'deny', user: null, denial: exchanged.denial }
+    const decision = await evaluateOidcClaims(cfg, exchanged.claims)
+    if (decision.provision) return { ...base, claims: exchanged.claims, outcome: 'provision', user: decision.provision.email, denial: null }
+    if (decision.denial) return { ...base, claims: exchanged.claims, outcome: 'deny', user: null, denial: decision.denial }
+    return { ...base, claims: exchanged.claims, outcome: decision.link ? 'link' : 'sign_in', user: decision.user.email, denial: null }
+  }
+
+  return { beginOidcLogin, exchangeOidcCode, evaluateOidcClaims, linkOidcIdentity, provisionSsoUser, auditOidcDenial, testOidcDiscovery, storeOidcTestResult, readOidcTestResult, runOidcTest }
+}
+
+export type Oidc = ReturnType<typeof createOidc>

package/src/oidcConfig.ts

@@ -0,0 +1,96 @@
+export const DEFAULT_OIDC_SCOPES = 'openid email profile'
+export const DEFAULT_OIDC_BUTTON_LABEL = 'Sign in with SSO'
+
+export interface OidcConfig {
+  issuer: string
+  clientId: string
+  clientSecret: string
+  scopes: string
+  redirectUri: string
+  buttonLabel: string
+  allowUnverifiedEmail: boolean
+  disablePasswordLogin: boolean
+}
+
+/** Raw, unvalidated OIDC settings from either source (environment or the database). */
+export interface OidcSettingsInput {
+  issuer?: string | undefined
+  clientId?: string | undefined
+  clientSecret?: string | undefined
+  scopes?: string | undefined
+  redirectUri?: string | undefined
+  buttonLabel?: string | undefined
+  allowUnverifiedEmail?: boolean | undefined
+  disablePasswordLogin?: boolean | undefined
+}
+
+function flag(value: string | undefined): boolean {
+  return ['1', 'true', 'yes'].includes((value ?? '').trim().toLowerCase())
+}
+
+export function isHttpUrl(value: string): boolean {
+  try {
+    const url = new URL(value)
+    return url.protocol === 'https:' || url.protocol === 'http:'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Settings validation and the environment variables, for an application whose public address is `publicUrl(env)` and
+ * whose provider redirects back to `callbackPath`.
+ */
+export function createOidcConfigResolver(options: { publicUrl: (env: NodeJS.ProcessEnv) => string; callbackPath: string }) {
+  /** Callback URL derived from the public URL, or '' when that is not set. */
+  function defaultOidcRedirectUri(env: NodeJS.ProcessEnv = process.env): string {
+    const publicUrl = options.publicUrl(env)
+    return publicUrl ? `${publicUrl}${options.callbackPath}` : ''
+  }
+
+  /** Validates raw settings and fills defaults. Returns null when they do not describe a usable setup. */
+  function buildOidcConfig(input: OidcSettingsInput, env: NodeJS.ProcessEnv = process.env): OidcConfig | null {
+    const issuer = (input.issuer ?? '').trim()
+    const clientId = (input.clientId ?? '').trim()
+    if (!issuer || !clientId || !isHttpUrl(issuer)) return null
+    const redirectUri = (input.redirectUri ?? '').trim() || defaultOidcRedirectUri(env)
+    if (!redirectUri || !isHttpUrl(redirectUri)) return null
+    return {
+      issuer,
+      clientId,
+      clientSecret: (input.clientSecret ?? '').trim(),
+      scopes: (input.scopes ?? '').trim() || DEFAULT_OIDC_SCOPES,
+      redirectUri,
+      buttonLabel: (input.buttonLabel ?? '').trim() || DEFAULT_OIDC_BUTTON_LABEL,
+      allowUnverifiedEmail: input.allowUnverifiedEmail === true,
+      disablePasswordLogin: input.disablePasswordLogin === true,
+    }
+  }
+
+  /**
+   * OIDC settings from environment variables, which override anything saved in the admin UI
+   * (for IaC deployments). Returns null when OIDC_ISSUER / OIDC_CLIENT_ID are not both set.
+   */
+  function resolveOidcConfigFromEnv(env: NodeJS.ProcessEnv = process.env): OidcConfig | null {
+    if (!(env['OIDC_ISSUER'] ?? '').trim() || !(env['OIDC_CLIENT_ID'] ?? '').trim()) return null
+    const config = buildOidcConfig({
+      issuer: env['OIDC_ISSUER'],
+      clientId: env['OIDC_CLIENT_ID'],
+      clientSecret: env['OIDC_CLIENT_SECRET'],
+      scopes: env['OIDC_SCOPES'],
+      redirectUri: env['OIDC_REDIRECT_URI'],
+      buttonLabel: env['OIDC_BUTTON_LABEL'],
+      allowUnverifiedEmail: flag(env['OIDC_ALLOW_UNVERIFIED_EMAIL']),
+      disablePasswordLogin: flag(env['OIDC_DISABLE_PASSWORD_LOGIN']),
+    }, env)
+    if (!config) console.warn('OIDC_* environment variables are set but incomplete or invalid (issuer, client id and a redirect URI or PUBLIC_URL are required) — OIDC sign-in is disabled')
+    return config
+  }
+
+  return { defaultOidcRedirectUri, buildOidcConfig, resolveOidcConfigFromEnv }
+}
+
+/** Password sign-in can only be turned off while OIDC is usable, so nobody is locked out by a typo. */
+export function passwordLoginEnabled(config: OidcConfig | null): boolean {
+  return !(config && config.disablePasswordLogin)
+}

package/src/oidcSettings.ts

@@ -0,0 +1,60 @@
+import { eq } from 'drizzle-orm'
+import { oidcSettings } from './tables.js'
+import type { AuthOptions } from './context.js'
+import type { OidcConfig, createOidcConfigResolver } from './oidcConfig.js'
+
+export type OidcSettingsRow = typeof oidcSettings.$inferSelect
+
+export function createOidcSettings(ctx: AuthOptions, resolver: ReturnType<typeof createOidcConfigResolver>) {
+  const { db, secretBox } = ctx
+  const { buildOidcConfig, resolveOidcConfigFromEnv } = resolver
+
+  async function getOidcSettingsRow(): Promise<OidcSettingsRow | null> {
+    return (await db.select().from(oidcSettings).where(eq(oidcSettings.id, 1)))[0] ?? null
+  }
+
+  function oidcConfigFromRow(row: OidcSettingsRow): OidcConfig | null {
+    return buildOidcConfig({
+      issuer: row.issuer,
+      clientId: row.clientId,
+      clientSecret: row.clientSecret ? secretBox.decrypt(row.clientSecret) : '',
+      scopes: row.scopes,
+      redirectUri: row.redirectUri,
+      buttonLabel: row.buttonLabel,
+      allowUnverifiedEmail: !!row.allowUnverifiedEmail,
+      disablePasswordLogin: !!row.disablePasswordLogin,
+    })
+  }
+
+  /** OIDC_FORCE_PASSWORD_LOGIN=true is the break-glass switch when the IdP is down and password sign-in was disabled. */
+  function withPasswordOverride(config: OidcConfig): OidcConfig {
+    return ['1', 'true', 'yes'].includes((process.env['OIDC_FORCE_PASSWORD_LOGIN'] ?? '').trim().toLowerCase())
+      ? { ...config, disablePasswordLogin: false }
+      : config
+  }
+
+  /**
+   * The OIDC configuration in effect: environment variables win (deployment-managed), otherwise the
+   * settings saved in the admin UI when enabled. Read per request, so saving takes effect without a restart.
+   */
+  async function getOidcConfig(): Promise<{ config: OidcConfig | null; source: 'env' | 'database' | 'none' }> {
+    const fromEnv = resolveOidcConfigFromEnv()
+    if (fromEnv) return { config: withPasswordOverride(fromEnv), source: 'env' }
+    const row = await getOidcSettingsRow()
+    if (!row?.enabled) return { config: null, source: 'none' }
+    const config = oidcConfigFromRow(row)
+    return { config: config && withPasswordOverride(config), source: config ? 'database' : 'none' }
+  }
+
+  /** Settings a test sign-in runs against: the environment, or the saved settings even while SSO is switched off. */
+  async function getOidcTestConfig(): Promise<OidcConfig | null> {
+    const fromEnv = resolveOidcConfigFromEnv()
+    if (fromEnv) return fromEnv
+    const row = await getOidcSettingsRow()
+    return row ? oidcConfigFromRow(row) : null
+  }
+
+  return { getOidcSettingsRow, oidcConfigFromRow, getOidcConfig, getOidcTestConfig }
+}
+
+export type OidcSettings = ReturnType<typeof createOidcSettings>

package/src/oidcSettingsRoutes.ts

@@ -0,0 +1,165 @@
+import type { FastifyInstance, FastifyReply } from 'fastify'
+import { oidcSettings } from './tables.js'
+import { requestIdentity } from './middleware.js'
+import type { AuthOptions } from './context.js'
+import type { IdentityConfirmation } from './identityConfirmation.js'
+import type { Oidc } from './oidc.js'
+import type { OidcSettings, OidcSettingsRow } from './oidcSettings.js'
+import type { OidcConfig, createOidcConfigResolver } from './oidcConfig.js'
+
+interface SettingsBody {
+  enabled?: boolean
+  issuer?: string
+  clientId?: string
+  /** Non-empty replaces the stored secret; omitted or empty keeps it, unless the issuer or client ID changed. */
+  clientSecret?: string
+  scopes?: string
+  redirectUri?: string
+  buttonLabel?: string
+  allowUnverifiedEmail?: boolean
+  disablePasswordLogin?: boolean
+  currentPassword?: string
+}
+
+export function createOidcSettingsRoutes(ctx: AuthOptions, parts: {
+  identityConfirmation: IdentityConfirmation
+  oidc: Oidc
+  oidcSettings: OidcSettings
+  resolver: ReturnType<typeof createOidcConfigResolver>
+  startOidcFlow: (app: FastifyInstance, reply: FastifyReply, cfg: OidcConfig, extra: { purpose?: 'oidc-flow' | 'oidc-test' | 'oidc-confirm'; adminUserId?: number }) => Promise<unknown>
+}) {
+  const { db, audit, secretBox } = ctx
+  const { confirmIdentity } = parts.identityConfirmation
+  const { readOidcTestResult, storeOidcTestResult, testOidcDiscovery } = parts.oidc
+  const { getOidcConfig, getOidcSettingsRow, getOidcTestConfig, oidcConfigFromRow } = parts.oidcSettings
+  const { buildOidcConfig, defaultOidcRedirectUri } = parts.resolver
+  const { startOidcFlow } = parts
+
+  function publicView(row: OidcSettingsRow | null) {
+    return {
+      enabled: !!row?.enabled,
+      issuer: row?.issuer ?? '',
+      clientId: row?.clientId ?? '',
+      hasClientSecret: !!row?.clientSecret,
+      scopes: row?.scopes ?? '',
+      redirectUri: row?.redirectUri ?? '',
+      buttonLabel: row?.buttonLabel ?? '',
+      allowUnverifiedEmail: !!row?.allowUnverifiedEmail,
+      disablePasswordLogin: !!row?.disablePasswordLogin,
+    }
+  }
+
+  /** Fields that appear in the audit diff; the secret is only recorded as changed, never its value. */
+  function auditView(row: OidcSettingsRow | null, secretChanged = false) {
+    const { hasClientSecret: _has, ...rest } = publicView(row)
+    return { ...rest, clientSecretChanged: secretChanged }
+  }
+
+  async function discoveryError(config: OidcConfig): Promise<string | null> {
+    try {
+      await testOidcDiscovery(config)
+      return null
+    } catch (error) {
+      return error instanceof Error ? error.message : 'Discovery failed'
+    }
+  }
+
+  async function oidcSettingsRoutes(app: FastifyInstance) {
+    app.get('/', async () => {
+      const [row, active] = await Promise.all([getOidcSettingsRow(), getOidcConfig()])
+      return {
+        source: active.source,
+        envManaged: active.source === 'env',
+        defaultRedirectUri: defaultOidcRedirectUri(),
+        settings: publicView(row),
+      }
+    })
+
+    app.put<{ Body: SettingsBody }>('/', { config: { rateLimit: ctx.rateLimits.sensitiveAction } }, async (req, reply) => {
+      if ((await getOidcConfig()).source === 'env') {
+        return reply.code(409).send({ error: 'OIDC is configured through environment variables and cannot be changed here' })
+      }
+      const body = req.body ?? {}
+      const identity = requestIdentity(req)
+      if (!await confirmIdentity(identity, body.currentPassword, reply)) return reply
+
+      const previous = await getOidcSettingsRow()
+      const secretChanged = !!body.clientSecret?.trim()
+      // The stored secret is sent to the issuer's token endpoint, so it must not follow a changed target.
+      if (previous?.clientSecret && !secretChanged && (
+        (body.issuer ?? '').trim() !== previous.issuer || (body.clientId ?? '').trim() !== previous.clientId
+      )) {
+        return reply.code(400).send({ error: 'Re-enter the client secret when changing the issuer URL or client ID' })
+      }
+      const clientSecret = secretChanged ? secretBox.encrypt(body.clientSecret!.trim()) : previous?.clientSecret ?? ''
+      const next: OidcSettingsRow = {
+        id: 1,
+        enabled: body.enabled ? 1 : 0,
+        issuer: (body.issuer ?? '').trim(),
+        clientId: (body.clientId ?? '').trim(),
+        clientSecret,
+        scopes: (body.scopes ?? '').trim(),
+        redirectUri: (body.redirectUri ?? '').trim(),
+        buttonLabel: (body.buttonLabel ?? '').trim(),
+        allowUnverifiedEmail: body.allowUnverifiedEmail ? 1 : 0,
+        disablePasswordLogin: body.disablePasswordLogin ? 1 : 0,
+        updatedAt: Date.now(),
+      }
+
+      if (next.enabled) {
+        const config = oidcConfigFromRow(next)
+        if (!config) {
+          return reply.code(400).send({ error: 'Issuer URL, client ID and a redirect URI (or PUBLIC_URL) are required and must be valid http(s) URLs' })
+        }
+        // Never persist a setup that could lock everyone out: with password login off, the IdP must be reachable.
+        if (config.disablePasswordLogin) {
+          const failure = await discoveryError(config)
+          if (failure) return reply.code(400).send({ error: `Password sign-in can only be disabled after OIDC discovery succeeds: ${failure}` })
+        }
+      } else {
+        next.disablePasswordLogin = 0
+      }
+
+      await db.insert(oidcSettings).values(next).onConflictDoUpdate({ target: oidcSettings.id, set: { ...next } })
+      await audit.write(audit.actor(identity), previous ? 'update' : 'create', 'oidc_settings', 1, 'OIDC sign-in',
+        audit.diffObjects(auditView(previous), auditView(next, secretChanged)))
+      return publicView(next)
+    })
+
+    // Opened in a new tab: runs the real sign-in with the saved settings and shows the outcome instead of signing in.
+    app.get('/test-sign-in', { config: { rateLimit: ctx.rateLimits.sensitiveAction } }, async (req, reply) => {
+      const cfg = await getOidcTestConfig()
+      if (!cfg) return reply.code(400).send({ error: 'Save a valid issuer URL, client ID and redirect URI first' })
+      try {
+        return await startOidcFlow(app, reply, cfg, { purpose: 'oidc-test', adminUserId: requestIdentity(req).userId })
+      } catch (error) {
+        const result = {
+          issuer: cfg.issuer, testedAt: Date.now(), claims: null, outcome: 'deny' as const, user: null,
+          denial: { code: 'discovery_failed' as const, reason: `OIDC discovery against the issuer failed: ${error instanceof Error ? error.message : String(error)}` },
+        }
+        return reply.redirect(`${ctx.urls.ssoTest}?result=${storeOidcTestResult(requestIdentity(req).userId, result)}`)
+      }
+    })
+
+    app.get<{ Params: { id: string } }>('/test-sign-in/:id', async (req, reply) => {
+      const result = readOidcTestResult(req.params.id, requestIdentity(req).userId)
+      if (!result) return reply.code(404).send({ error: 'The test result has expired. Run the test sign-in again.' })
+      return result
+    })
+
+    app.post<{ Body: SettingsBody }>('/test', { config: { rateLimit: ctx.rateLimits.sensitiveAction } }, async (req, reply) => {
+      const body = req.body ?? {}
+      const config = buildOidcConfig({
+        issuer: body.issuer,
+        clientId: body.clientId,
+        redirectUri: body.redirectUri,
+      })
+      if (!config) return reply.code(400).send({ error: 'Enter a valid issuer URL, client ID and a redirect URI (or set PUBLIC_URL)' })
+      const failure = await discoveryError(config)
+      if (failure) return reply.code(400).send({ error: `Discovery failed: ${failure}` })
+      return { ok: true, ...(await testOidcDiscovery(config)) }
+    })
+  }
+
+  return { oidcSettingsRoutes }
+}

package/src/roles.ts

@@ -0,0 +1,60 @@
+/** The role that may do everything; it exists in every application. */
+export const ADMIN_ROLE = 'admin'
+
+export interface RoleRegistry {
+  /**
+   * Adds the application's roles to `admin`. `fallback` is what a stored value that is not a role normalises to,
+   * and `defaultForNewUsers` is the role an account gets when none is asked for.
+   */
+  register(roles: readonly string[], options: { fallback: string; defaultForNewUsers: string }): void
+  /** Normalizes a stored role value, including the legacy JSON-array format. */
+  normalize(raw: string): string
+  isValid(role: string): boolean
+  /** Every role, `admin` first, in the order they were registered. */
+  list(): readonly string[]
+  readonly defaultForNewUsers: string
+  /**
+   * Called by createAuth: after this, registering throws, so the set of roles cannot change under a running app.
+   * It also throws when the application never registered its roles, because the fallback would then be `admin`.
+   */
+  freeze(): void
+}
+
+export function createRoleRegistry(): RoleRegistry {
+  const roles: string[] = [ADMIN_ROLE]
+  let fallback: string = ADMIN_ROLE
+  let defaultForNewUsers: string = ADMIN_ROLE
+  let frozen = false
+  let registered = false
+
+  const isValid = (role: string) => roles.includes(role)
+
+  return {
+    register(added, options) {
+      if (frozen) throw new Error('Roles cannot be registered after the auth module was created')
+      for (const role of added) if (!roles.includes(role)) roles.push(role)
+      if (!roles.includes(options.fallback) || !roles.includes(options.defaultForNewUsers)) {
+        throw new Error('The fallback and the default role for new users must be registered roles')
+      }
+      fallback = options.fallback
+      defaultForNewUsers = options.defaultForNewUsers
+      registered = true
+    },
+    normalize(raw) {
+      try {
+        const parsed: unknown = JSON.parse(raw)
+        const role = Array.isArray(parsed) ? parsed[0] : raw
+        return typeof role === 'string' && isValid(role) ? role : fallback
+      } catch {
+        return isValid(raw) ? raw : fallback
+      }
+    },
+    isValid,
+    list: () => roles,
+    get defaultForNewUsers() { return defaultForNewUsers },
+    freeze() {
+      if (!registered) throw new Error('Register the application roles before creating the auth module: without them every unknown role would be an administrator')
+      frozen = true
+    },
+  }
+}