@better-forge/auth 0.0.0-stage → 0.1.0

package/src/context.ts

@@ -0,0 +1,85 @@
+import type { DatabaseSync } from 'node:sqlite'
+// Loaded for the request and reply properties they add (`cookies`, `jwt`, `user`, route `rateLimit` config).
+import type {} from '@fastify/cookie'
+import type {} from '@fastify/jwt'
+import type {} from '@fastify/rate-limit'
+import type { Audit } from '@better-forge/audit'
+import type { SqliteDatabase } from '@better-forge/db'
+import type { RoleRegistry } from './roles.js'
+import type { TokenCatalogue } from './tokenCatalogue.js'
+
+/** Which sessions were ended, so the application can close what they had open (for example live connections). */
+export type SessionsRevoked =
+  | { sessionId: string }
+  | { userId: number; exceptSessionId?: string | undefined }
+
+export interface UnknownSsoUser {
+  email: string
+  subject: string
+  issuer: string
+}
+
+export type SignInOutcome = { role: string } | { error: string } | 'two-factor'
+
+export interface AuthHooks {
+  /** Called after sessions were deleted, whatever the reason (sign-out, password reset, role change, ...). */
+  onSessionsRevoked?: (match: SessionsRevoked) => void
+  /**
+   * An SSO sign-in succeeded at the provider but no account matches. Return the role of an account to create for
+   * this person, or null to refuse. Only called when the provider's identity is verified; without this hook nobody
+   * is created.
+   */
+  resolveUnknownSsoUser?: (user: UnknownSsoUser) => Promise<{ role: string } | null>
+  /**
+   * Where a sign-in goes next, for one that started with a `returnTo` target the application listed in
+   * `returnTargets`, or for a role that belongs somewhere else than `urls.home`. Return undefined for the default.
+   */
+  signInRedirect?: (flow: { returnTo?: string | undefined }, outcome: SignInOutcome) => string | undefined
+}
+
+/** A `@fastify/rate-limit` route configuration. Passed through untouched, so a group id can be shared with other routes. */
+export interface RateLimitConfig {
+  groupId?: string
+  max: number
+  timeWindow: string | number
+}
+
+/**
+ * Everything the auth module needs from the application. All of it is passed in: the module reads no globals, so
+ * two applications (or two tests) can each have their own.
+ */
+export interface AuthOptions {
+  /** Database handle and the raw connection (for transactions). Both are used lazily, so they may be opened after this is created. */
+  db: SqliteDatabase
+  sqlite: DatabaseSync
+  audit: Pick<Audit, 'write' | 'actor' | 'diffObjects' | 'snapshot'>
+  roles: RoleRegistry
+  tokens: TokenCatalogue
+  /** Encrypts and decrypts secrets the module stores (the SSO client secret, authenticator secrets). */
+  secretBox: { encrypt(plain: string): string; decrypt(stored: string): string }
+  cookies: { session: string; csrf: string; oidcFlow: string; twoFactorChallenge: string }
+  /** Prefix that tells an API token from a session token in a Bearer header. */
+  apiTokenPrefix: string
+  /** Name an authenticator app shows next to the account. */
+  totpIssuer: string
+  /** Where the sign-in routes are mounted. The cookie paths and the SSO callback derive from it. */
+  basePath: string
+  urls: {
+    /** Where a failed sign-in sends the browser, e.g. `/admin/login`. */
+    signIn: string
+    /** Where a finished sign-in goes by default. */
+    home: string
+    /** The page that closes the SSO confirmation popup. */
+    ssoConfirm: string
+    /** The page that shows the result of an SSO test. */
+    ssoTest: string
+  }
+  /** The address the application is reached at, from the environment; '' when unknown. */
+  publicUrl: (env: NodeJS.ProcessEnv) => string
+  /** Whether cookies are marked Secure. Evaluated on every response. */
+  secureCookies: () => boolean
+  rateLimits: { signIn: RateLimitConfig; sensitiveAction: RateLimitConfig }
+  /** `returnTo` values a sign-in may start with; the application's `signInRedirect` hook turns them into a destination. */
+  returnTargets?: readonly string[]
+  hooks?: AuthHooks
+}

package/src/createAuth.ts

@@ -0,0 +1,58 @@
+import type { AuthOptions } from './context.js'
+import { createApiTokenRoutes } from './apiTokenRoutes.js'
+import { createApiTokens } from './apiTokens.js'
+import { createIdentityConfirmation } from './identityConfirmation.js'
+import { createMiddleware } from './middleware.js'
+import { createOidc } from './oidc.js'
+import { createOidcConfigResolver } from './oidcConfig.js'
+import { createOidcSettings } from './oidcSettings.js'
+import { createOidcSettingsRoutes } from './oidcSettingsRoutes.js'
+import { createSessions } from './sessions.js'
+import { createSignInAudit } from './signInAudit.js'
+import { createSignInRoutes } from './authRoutes.js'
+import { createTwoFactor } from './twoFactor.js'
+import { createUserRoutes } from './userRoutes.js'
+
+/**
+ * Accounts, sessions, two-factor sign-in, single sign-on, API tokens and the routes that manage them. Everything is
+ * built from `options` and kept in the returned closures; nothing is shared between two calls.
+ */
+export function createAuth(options: AuthOptions) {
+  options.roles.freeze()
+
+  const apiTokens = createApiTokens(options)
+  const sessions = createSessions(options, apiTokens)
+  const middleware = createMiddleware(sessions, apiTokens)
+  const identityConfirmation = createIdentityConfirmation(options)
+  const twoFactor = createTwoFactor(options)
+  const signInAudit = createSignInAudit(options)
+  const oidcConfig = createOidcConfigResolver({ publicUrl: options.publicUrl, callbackPath: `${options.basePath}/oidc/callback` })
+  const oidcSettings = createOidcSettings(options, oidcConfig)
+  const oidc = createOidc(options, signInAudit)
+
+  const signIn = createSignInRoutes(options, { sessions, middleware, twoFactor, identityConfirmation, signInAudit, oidcSettings, oidc })
+  const users = createUserRoutes(options, { sessions, twoFactor, identityConfirmation })
+  const oidcSettingsRoutes = createOidcSettingsRoutes(options, { identityConfirmation, oidc, oidcSettings, resolver: oidcConfig, startOidcFlow: signIn.startOidcFlow })
+  const tokenRoutes = createApiTokenRoutes(options, apiTokens, identityConfirmation)
+
+  return {
+    sessions,
+    middleware,
+    identityConfirmation,
+    twoFactor,
+    signInAudit,
+    oidcConfig,
+    oidcSettings,
+    oidc,
+    apiTokens,
+    /** Plain plugins (not wrapped for encapsulation), so the hooks of the scope they are registered in apply to them. */
+    routes: {
+      signIn: signIn.authRoutes,
+      users: users.userRoutes,
+      oidcSettings: oidcSettingsRoutes.oidcSettingsRoutes,
+      apiTokens: tokenRoutes.apiTokenRoutes,
+    },
+  }
+}
+
+export type Auth = ReturnType<typeof createAuth>

package/src/identityConfirmation.ts

@@ -0,0 +1,50 @@
+import bcrypt from 'bcryptjs'
+import { and, eq, gt } from 'drizzle-orm'
+import type { FastifyReply } from 'fastify'
+import { authSessions, users } from './tables.js'
+import type { AuthOptions } from './context.js'
+import type { AuthIdentity } from './sessions.js'
+
+/** Error code telling the admin UI to confirm the user through the identity provider, then retry. */
+export const SSO_CONFIRMATION_REQUIRED = 'SSO_CONFIRMATION_REQUIRED'
+
+/** How long an SSO sign-in or SSO confirmation covers sensitive actions in that session. */
+export const SSO_CONFIRMATION_WINDOW_MS = 10 * 60 * 1000
+
+export function createIdentityConfirmation(ctx: AuthOptions) {
+  const { db } = ctx
+
+  /**
+   * Sensitive actions are confirmed the way the session signed in: a password session with the current
+   * password, an SSO session with a recent sign-in at the identity provider (the sign-in itself, or a
+   * confirmation popup started from the UI). Returns true, or sends the refusal and returns false.
+   */
+  async function confirmIdentity(identity: AuthIdentity, currentPassword: unknown, reply: FastifyReply): Promise<boolean> {
+    if (identity.authMethod === 'oidc') {
+      const session = (await db.select().from(authSessions).where(eq(authSessions.id, identity.sessionId)))[0]
+      const verifiedAt = session?.verifiedAt ?? session?.createdAt ?? 0
+      if (Date.now() - verifiedAt <= SSO_CONFIRMATION_WINDOW_MS) return true
+      await reply.code(403).send({ error: 'Confirm your identity with single sign-on to continue', code: SSO_CONFIRMATION_REQUIRED })
+      return false
+    }
+    const user = (await db.select().from(users).where(eq(users.id, identity.userId)))[0]
+    if (user && typeof currentPassword === 'string' && currentPassword && await bcrypt.compare(currentPassword, user.passwordHash)) return true
+    await reply.code(400).send({ error: 'Current password is incorrect' })
+    return false
+  }
+
+  /** Records a successful SSO confirmation on a live SSO session of that user. False when there is no such session. */
+  async function markSessionVerified(sessionId: string, userId: number): Promise<boolean> {
+    const updated = await db.update(authSessions).set({ verifiedAt: Date.now() }).where(and(
+      eq(authSessions.id, sessionId),
+      eq(authSessions.userId, userId),
+      eq(authSessions.authMethod, 'oidc'),
+      gt(authSessions.expiresAt, Date.now()),
+    )).returning({ id: authSessions.id })
+    return updated.length > 0
+  }
+
+  return { confirmIdentity, markSessionVerified }
+}
+
+export type IdentityConfirmation = ReturnType<typeof createIdentityConfirmation>

package/src/index.ts

@@ -0,0 +1,17 @@
+export { createAuth, type Auth } from './createAuth.js'
+export { authDbModule } from './module.js'
+export { apiTokens, authSessions, oidcSettings, users } from './tables.js'
+export { acceptApiTokens, belongsTo, registerAdminApi, type AdminRouteGroup } from './routeScope.js'
+export { createSetupRoutes, type SetupRoutesOptions } from './setupRoutes.js'
+export { ADMIN_ROLE, createRoleRegistry, type RoleRegistry } from './roles.js'
+export { createTokenCatalogue, type TokenCatalogue } from './tokenCatalogue.js'
+export type { AuthHooks, AuthOptions, RateLimitConfig, SessionsRevoked, SignInOutcome, UnknownSsoUser } from './context.js'
+export { ALLOW_PENDING_PASSWORD_CHANGE, PASSWORD_CHANGE_REQUIRED, requestIdentity } from './middleware.js'
+export { API_TOKEN_NOT_ACCEPTED, type AuthenticateOptions, type AuthIdentity, type AuthMethod } from './sessions.js'
+export { SSO_CONFIRMATION_REQUIRED, SSO_CONFIRMATION_WINDOW_MS } from './identityConfirmation.js'
+export { checkEmailVerified, OIDC_CONFIRMATION_MAX_AGE_SECONDS } from './oidc.js'
+export type { OidcDecision, OidcDenial, OidcDenialCode, OidcFlowState, OidcTestResult, SsoProvisioning } from './oidc.js'
+export type { OidcSettingsRow } from './oidcSettings.js'
+export { createOidcConfigResolver, DEFAULT_OIDC_BUTTON_LABEL, DEFAULT_OIDC_SCOPES, isHttpUrl, passwordLoginEnabled, type OidcConfig, type OidcSettingsInput } from './oidcConfig.js'
+export { consumeRecoveryCode, generateRecoveryCodes, generateTotpCode, generateTotpSecret, hashRecoveryCode, totpUri, verifyTotp } from './totp.js'
+export type { CredentialDenialCode, SignInDenial, SignInMethod } from './signInAudit.js'

package/src/middleware.ts

@@ -0,0 +1,123 @@
+import type { FastifyReply, FastifyRequest } from 'fastify'
+import { requiredScope, tokenAllows } from '@better-forge/contracts'
+import { API_TOKEN_NOT_ACCEPTED, type AuthIdentity, type Sessions } from './sessions.js'
+import type { ApiTokens } from './apiTokens.js'
+
+declare module 'fastify' {
+  interface FastifyContextConfig {
+    allowPendingPasswordChange?: boolean
+    /** Routes that accept an API token. Everything else answers 403 to one, so tokens never reach account security. */
+    allowApiToken?: boolean
+    /**
+     * The part of the admin API a route belongs to (a key of TOKEN_RESOURCES, or `vault`). A token needs `<part>:read`
+     * for GET and `<part>:write` for anything else. `custom` means the handler checks the token itself. A route a
+     * token may reach but that names no part is refused: tokens fail closed.
+     */
+    tokenScope?: string
+  }
+}
+
+export const PASSWORD_CHANGE_REQUIRED = 'PASSWORD_CHANGE_REQUIRED'
+
+/**
+ * Route config for the few routes a user with a pending forced password change may still call
+ * (session lookup, change-password, logout). Every other authenticated route answers 403 until
+ * the password is changed, so the requirement is enforced server-side, not only by the admin UI.
+ */
+export const ALLOW_PENDING_PASSWORD_CHANGE = { allowPendingPasswordChange: true } as const
+
+function existingIdentity(req: FastifyRequest): AuthIdentity | null {
+  const value = req.user as Partial<AuthIdentity> | undefined
+  return value?.sessionId && typeof value.userId === 'number' ? value as AuthIdentity : null
+}
+
+/**
+ * The identity attached by requireAuth/requireRole. Only call from handlers behind one of them.
+ */
+export function requestIdentity(req: FastifyRequest): AuthIdentity {
+  const value = req.user as Partial<AuthIdentity> | undefined
+  if (typeof value?.userId !== 'number') throw new Error('requestIdentity called on an unauthenticated request')
+  return value as AuthIdentity
+}
+
+function passwordChangeBlocks(req: FastifyRequest, identity: AuthIdentity): boolean {
+  if (!identity.mustChangePassword) return false
+  return req.routeOptions.config?.allowPendingPasswordChange !== true
+}
+
+function sendPasswordChangeRequired(reply: FastifyReply) {
+  return reply.code(403).send({ error: 'Password change required', code: PASSWORD_CHANGE_REQUIRED })
+}
+
+export function createMiddleware(sessions: Sessions, apiTokens: ApiTokens) {
+  const { authenticateRequest, verifyCsrf } = sessions
+  const { consumeApiTokenBudget } = apiTokens
+
+  /**
+   * Authenticates the request and checks its CSRF token. Answers 401 (with `unauthorized` as the body) or 403
+   * itself and returns null when either fails, or when the user still has to replace a temporary password.
+   * A hook that gets null must return the reply.
+   */
+  async function authenticateOrReject(
+    req: FastifyRequest,
+    reply: FastifyReply,
+    unauthorized: Record<string, string> = { error: 'Unauthorized' },
+  ): Promise<AuthIdentity | null> {
+    const allowApiToken = req.routeOptions.config?.allowApiToken === true
+    const existing = existingIdentity(req)
+    let identity: AuthIdentity
+    try {
+      identity = existing ?? await authenticateRequest(req, { allowApiToken })
+      if (identity.apiToken && !allowApiToken) throw new Error(API_TOKEN_NOT_ACCEPTED)
+      await verifyCsrf(req, identity)
+    } catch (error) {
+      const message = error instanceof Error ? error.message : ''
+      if (message === 'Invalid CSRF token') reply.code(403).send({ error: 'Invalid CSRF token' })
+      else if (message === API_TOKEN_NOT_ACCEPTED) reply.code(403).send({ error: 'API tokens cannot call this endpoint' })
+      else reply.code(401).send(unauthorized)
+      return null
+    }
+    // Only a request that just authenticated spends budget; the later hooks of the same request reuse the identity.
+    if (identity.apiToken && !existing && !consumeApiTokenBudget(identity.apiToken.id)) {
+      reply.code(429).header('retry-after', '60').send({ error: 'Too many requests' })
+      return null
+    }
+    if (identity.apiToken) {
+      const resource = req.routeOptions.config?.tokenScope
+      if (resource !== 'custom') {
+        const required = resource ? requiredScope(resource, req.method) : null
+        if (!required || !tokenAllows(identity.apiToken.scopes, required)) {
+          reply.code(403).send({ error: required ? `This token does not have the "${required}" permission` : 'API tokens cannot call this endpoint' })
+          return null
+        }
+      }
+    }
+    if (passwordChangeBlocks(req, identity)) {
+      sendPasswordChangeRequired(reply)
+      return null
+    }
+    return identity
+  }
+
+  async function requireAuth(req: FastifyRequest, reply: FastifyReply) {
+    if (!await authenticateOrReject(req, reply)) return reply
+  }
+
+  function requireRole(...allowed: string[]) {
+    const hook = async (req: FastifyRequest, reply: FastifyReply) => {
+      const identity = await authenticateOrReject(req, reply)
+      if (!identity) return reply
+      const { role } = identity
+      if (role !== 'admin' && !allowed.includes(role)) {
+        return reply.code(403).send({ error: 'Forbidden' })
+      }
+    }
+    // Readable by the route-table snapshot test; the hook itself never looks at it.
+    return Object.assign(hook, { allowedRoles: allowed, requiresAuth: true })
+  }
+
+  // Readable by the route-table snapshot test, like `allowedRoles`; the hook itself never looks at it.
+  return { authenticateOrReject, requireAuth: Object.assign(requireAuth, { requiresAuth: true }), requireRole }
+}
+
+export type Middleware = ReturnType<typeof createMiddleware>

package/src/migrations.ts

@@ -0,0 +1,77 @@
+import { randomBytes } from 'node:crypto'
+import bcrypt from 'bcryptjs'
+import type { MigrationStep } from '@better-forge/db'
+
+/** Users, sign-in sessions, SSO settings and API tokens. Steps run in this order. */
+export const authMigrations: readonly MigrationStep[] = [
+  { kind: 'exec', sql: `
+CREATE TABLE IF NOT EXISTS users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  email TEXT NOT NULL UNIQUE,
+  password_hash TEXT NOT NULL,
+  role TEXT NOT NULL DEFAULT 'admin',
+  created_at INTEGER NOT NULL
+);
+` },
+  { kind: 'exec', sql: `
+CREATE TABLE IF NOT EXISTS oidc_settings (
+  id INTEGER PRIMARY KEY,
+  enabled INTEGER NOT NULL DEFAULT 0,
+  issuer TEXT NOT NULL DEFAULT '',
+  client_id TEXT NOT NULL DEFAULT '',
+  client_secret TEXT NOT NULL DEFAULT '',
+  scopes TEXT NOT NULL DEFAULT '',
+  redirect_uri TEXT NOT NULL DEFAULT '',
+  button_label TEXT NOT NULL DEFAULT '',
+  allow_unverified_email INTEGER NOT NULL DEFAULT 0,
+  disable_password_login INTEGER NOT NULL DEFAULT 0,
+  updated_at INTEGER NOT NULL
+);
+` },
+  { kind: 'exec', sql: `
+CREATE TABLE IF NOT EXISTS auth_sessions (
+  id TEXT PRIMARY KEY,
+  user_id INTEGER NOT NULL,
+  csrf_token_hash TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  last_seen_at INTEGER NOT NULL,
+  expires_at INTEGER NOT NULL,
+  auth_method TEXT NOT NULL DEFAULT 'password',
+  verified_at INTEGER,
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_auth_sessions_user ON auth_sessions(user_id);
+CREATE INDEX IF NOT EXISTS idx_auth_sessions_expires ON auth_sessions(expires_at);
+` },
+  { kind: 'exec', sql: `
+CREATE TABLE IF NOT EXISTS api_tokens (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL,
+  token_hash TEXT NOT NULL UNIQUE,
+  prefix TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  expires_at INTEGER,
+  last_used_at INTEGER,
+  scopes TEXT NOT NULL
+);
+` },
+  { kind: 'column', sql: `ALTER TABLE users ADD COLUMN must_change_password INTEGER NOT NULL DEFAULT 0`, desc: 'users.must_change_password' },
+  { kind: 'column', sql: `ALTER TABLE users ADD COLUMN totp_secret TEXT`, desc: 'users.totp_secret' },
+  { kind: 'column', sql: `ALTER TABLE users ADD COLUMN totp_enabled INTEGER NOT NULL DEFAULT 0`, desc: 'users.totp_enabled' },
+  { kind: 'column', sql: `ALTER TABLE users ADD COLUMN totp_recovery_codes TEXT`, desc: 'users.totp_recovery_codes' },
+  { kind: 'column', sql: `ALTER TABLE auth_sessions ADD COLUMN auth_method TEXT NOT NULL DEFAULT 'password'`, desc: 'auth_sessions.auth_method' },
+  { kind: 'column', sql: `ALTER TABLE users ADD COLUMN oidc_issuer TEXT`, desc: 'users.oidc_issuer' },
+  { kind: 'column', sql: `ALTER TABLE users ADD COLUMN oidc_subject TEXT`, desc: 'users.oidc_subject' },
+  { kind: 'column', sql: `ALTER TABLE auth_sessions ADD COLUMN verified_at INTEGER`, desc: 'auth_sessions.verified_at' },
+  // One IdP identity can be bound to one user only. Needs the columns added above.
+  { kind: 'exec', sql: `CREATE UNIQUE INDEX IF NOT EXISTS idx_users_oidc_identity ON users(oidc_issuer, oidc_subject)` },
+  /**
+   * Accounts linked to SSO before a sign-in started revoking the temporary password may still have a working one
+   * that their administrator knows. Linking only happens on an SSO sign-in, so revoke it the same way.
+   */
+  { kind: 'data', name: 'sso-users-temporary-password-revoked-v1', run(sqlite) {
+    const pending = sqlite.prepare('SELECT id FROM users WHERE must_change_password = 1 AND oidc_subject IS NOT NULL').all() as Array<{ id: number }>
+    const revoke = sqlite.prepare('UPDATE users SET password_hash = ?, must_change_password = 0 WHERE id = ?')
+    for (const { id } of pending) revoke.run(bcrypt.hashSync(randomBytes(32).toString('base64url'), 10), id)
+  } },
+]

package/src/module.ts

@@ -0,0 +1,6 @@
+import type { DbModule } from '@better-forge/db'
+import * as tables from './tables.js'
+import { authMigrations } from './migrations.js'
+
+/** The tables of accounts, sessions, API tokens and SSO settings, with their migrations, for the application's list of database modules. */
+export const authDbModule = { id: 'auth', tables, migrations: authMigrations } satisfies DbModule