@better-forge/auth 0.1.0 → 0.1.1

package/src/context.ts

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

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

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

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