@better-forge/auth 0.1.0 → 0.1.1

package/src/middleware.ts

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

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

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