@better-forge/auth 0.1.0 → 0.1.1

package/src/oidcConfig.ts

@@ -1,96 +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)
-}
+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

@@ -1,60 +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>
+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

@@ -1,165 +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 }
-}
+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 }
+}