@better-forge/auth 0.1.0 → 0.1.1

package/src/roles.ts

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

package/src/routeScope.ts

@@ -1,50 +1,50 @@
-import type { FastifyInstance } from 'fastify'
-
-/**
- * Marks every route registered in `scope` as belonging to a part of the API, which is what an API token is checked
- * against (`<part>:read` for GET, `<part>:write` otherwise). A route without a part is refused to every token.
- */
-export function belongsTo(scope: FastifyInstance, part: string): void {
-  scope.addHook('onRoute', (route) => { route.config = { ...route.config, tokenScope: part } })
-}
-
-/** Lets (or, with `false`, stops) the routes registered in `scope` accept an API token. Routes accept none by default. */
-export function acceptApiTokens(scope: FastifyInstance, accept = true): void {
-  scope.addHook('onRoute', (route) => { route.config = { ...route.config, allowApiToken: accept } })
-}
-
-type RoutePlugin = (scope: FastifyInstance) => Promise<void> | void
-type Guard = (...args: never[]) => unknown
-
-/** A group of routes that share a guard and, usually, a part of the API tokens are checked against. */
-export interface AdminRouteGroup {
-  /** The part of the API the routes belong to. Omit it for a group whose routes no token reaches. */
-  part?: string
-  /** The group refuses API tokens even though the rest of the API accepts them. */
-  noTokens?: boolean
-  /** Runs before every route of the group (the role the group needs). */
-  guard: Guard
-  /** The route plugins of the group with the prefix each is mounted at. */
-  routes: ReadonlyArray<readonly [plugin: RoutePlugin, options: { prefix: string }]>
-}
-
-/**
- * Registers the admin API: the scope accepts API tokens and needs a signed-in caller (`authenticate`), then every group
- * gets its own scope with its part, its guard and its routes. A token is checked against the part of the group a route
- * is in; a group with `noTokens` is for what a leaked token must never reach.
- */
-export async function registerAdminApi(
-  adminApp: FastifyInstance,
-  options: { authenticate: Guard; groups: readonly AdminRouteGroup[] },
-): Promise<void> {
-  acceptApiTokens(adminApp)
-  adminApp.addHook('preHandler', options.authenticate as never)
-  for (const group of options.groups) {
-    await adminApp.register(async (scope) => {
-      if (group.noTokens) acceptApiTokens(scope, false)
-      if (group.part !== undefined) belongsTo(scope, group.part)
-      scope.addHook('preHandler', group.guard as never)
-      for (const [plugin, routeOptions] of group.routes) await scope.register(plugin, routeOptions)
-    })
-  }
-}
+import type { FastifyInstance } from 'fastify'
+
+/**
+ * Marks every route registered in `scope` as belonging to a part of the API, which is what an API token is checked
+ * against (`<part>:read` for GET, `<part>:write` otherwise). A route without a part is refused to every token.
+ */
+export function belongsTo(scope: FastifyInstance, part: string): void {
+  scope.addHook('onRoute', (route) => { route.config = { ...route.config, tokenScope: part } })
+}
+
+/** Lets (or, with `false`, stops) the routes registered in `scope` accept an API token. Routes accept none by default. */
+export function acceptApiTokens(scope: FastifyInstance, accept = true): void {
+  scope.addHook('onRoute', (route) => { route.config = { ...route.config, allowApiToken: accept } })
+}
+
+type RoutePlugin = (scope: FastifyInstance) => Promise<void> | void
+type Guard = (...args: never[]) => unknown
+
+/** A group of routes that share a guard and, usually, a part of the API tokens are checked against. */
+export interface AdminRouteGroup {
+  /** The part of the API the routes belong to. Omit it for a group whose routes no token reaches. */
+  part?: string
+  /** The group refuses API tokens even though the rest of the API accepts them. */
+  noTokens?: boolean
+  /** Runs before every route of the group (the role the group needs). */
+  guard: Guard
+  /** The route plugins of the group with the prefix each is mounted at. */
+  routes: ReadonlyArray<readonly [plugin: RoutePlugin, options: { prefix: string }]>
+}
+
+/**
+ * Registers the admin API: the scope accepts API tokens and needs a signed-in caller (`authenticate`), then every group
+ * gets its own scope with its part, its guard and its routes. A token is checked against the part of the group a route
+ * is in; a group with `noTokens` is for what a leaked token must never reach.
+ */
+export async function registerAdminApi(
+  adminApp: FastifyInstance,
+  options: { authenticate: Guard; groups: readonly AdminRouteGroup[] },
+): Promise<void> {
+  acceptApiTokens(adminApp)
+  adminApp.addHook('preHandler', options.authenticate as never)
+  for (const group of options.groups) {
+    await adminApp.register(async (scope) => {
+      if (group.noTokens) acceptApiTokens(scope, false)
+      if (group.part !== undefined) belongsTo(scope, group.part)
+      scope.addHook('preHandler', group.guard as never)
+      for (const [plugin, routeOptions] of group.routes) await scope.register(plugin, routeOptions)
+    })
+  }
+}

package/src/sessions.ts

@@ -1,209 +1,209 @@
-import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto'
-import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
-import { and, eq, lt, ne } from 'drizzle-orm'
-import { authSessions, users } from './tables.js'
-import type { AuthOptions } from './context.js'
-import type { ApiTokens } from './apiTokens.js'
-
-const SESSION_SECONDS = 12 * 60 * 60
-
-export type AuthMethod = 'password' | 'oidc'
-
-export interface AuthIdentity {
-  userId: number
-  email: string
-  role: string
-  sessionId: string
-  mustChangePassword: boolean
-  twoFactorEnabled: boolean
-  authMethod: AuthMethod
-  /**
-   * Set when the request is authenticated by an API token instead of a session. A token belongs to no user: `userId`
-   * is 0, `email` is `token: <name>` (it names the token in the audit log) and `sessionId` is a synthetic
-   * `api-token:<id>`. A token has no role: `role` is a placeholder
-   * that lets it through the role checks, and what it may do is decided by `scopes`, checked for every request in
-   * authenticateOrReject.
-   */
-  apiToken?: { id: number; name: string; scopes: string[] }
-}
-
-export interface AuthenticateOptions {
-  /** API tokens are only accepted on routes that opt in; everywhere else they are refused. */
-  allowApiToken?: boolean
-}
-
-export const API_TOKEN_NOT_ACCEPTED = 'API token not accepted here'
-
-interface SessionClaims {
-  userId: number
-  email: string
-  role: string
-  sessionId: string
-}
-
-export function createSessions(ctx: AuthOptions, apiTokens: ApiTokens) {
-  const { db, roles } = ctx
-  const hooks = ctx.hooks ?? {}
-  const SESSION_COOKIE = ctx.cookies.session
-  const CSRF_COOKIE = ctx.cookies.csrf
-  const { findUsableApiToken, isApiToken, parseScopes } = apiTokens
-
-  function cookieOptions(httpOnly: boolean) {
-    return {
-      path: '/',
-      httpOnly,
-      secure: ctx.secureCookies(),
-      sameSite: 'strict' as const,
-      maxAge: SESSION_SECONDS,
-    }
-  }
-
-  function hash(value: string): string {
-    return createHash('sha256').update(value).digest('hex')
-  }
-
-  function equalHash(left: string, right: string): boolean {
-    const a = Buffer.from(left)
-    const b = Buffer.from(right)
-    return a.length === b.length && timingSafeEqual(a, b)
-  }
-
-  async function createAuthSession(
-    app: FastifyInstance,
-    reply: FastifyReply,
-    user: { id: number; email: string; role: string; mustChangePassword: number; totpEnabled: number },
-    authMethod: AuthMethod = 'password',
-  ): Promise<AuthIdentity> {
-    const now = Date.now()
-    const sessionId = randomUUID()
-    const csrfToken = randomBytes(32).toString('base64url')
-    const expiresAt = now + SESSION_SECONDS * 1000
-    await db.delete(authSessions).where(lt(authSessions.expiresAt, now))
-    await db.insert(authSessions).values({
-      id: sessionId,
-      userId: user.id,
-      csrfTokenHash: hash(csrfToken),
-      createdAt: now,
-      lastSeenAt: now,
-      expiresAt,
-      authMethod,
-      verifiedAt: now,
-    })
-
-    const role = roles.normalize(user.role)
-    const token = app.jwt.sign({ userId: user.id, email: user.email, role, sessionId })
-    reply.setCookie(SESSION_COOKIE, token, cookieOptions(true))
-    reply.setCookie(CSRF_COOKIE, csrfToken, cookieOptions(false))
-    return {
-      userId: user.id,
-      email: user.email,
-      role,
-      sessionId,
-      mustChangePassword: mustChangePassword(user, authMethod),
-      twoFactorEnabled: !!user.totpEnabled,
-      authMethod,
-    }
-  }
-
-  /**
-   * A password session must replace a pending temporary password, so the one the administrator handed out stops
-   * working. An SSO session never has to: the SSO sign-in makes the temporary password unusable instead.
-   */
-  function mustChangePassword(user: { mustChangePassword: number }, authMethod: string): boolean {
-    return !!user.mustChangePassword && authMethod !== 'oidc'
-  }
-
-  function clearAuthCookies(reply: FastifyReply): void {
-    const base = { path: '/', secure: ctx.secureCookies(), sameSite: 'strict' as const }
-    reply.clearCookie(SESSION_COOKIE, { ...base, httpOnly: true })
-    reply.clearCookie(CSRF_COOKIE, { ...base, httpOnly: false })
-  }
-
-  function requestToken(req: FastifyRequest): string | null {
-    const authorization = req.headers.authorization
-    if (authorization?.startsWith('Bearer ')) return authorization.slice(7)
-    return req.cookies[SESSION_COOKIE] ?? null
-  }
-
-  async function authenticateApiToken(req: FastifyRequest, token: string): Promise<AuthIdentity> {
-    const found = await findUsableApiToken(token)
-    if (!found) throw new Error('Invalid API token')
-    const identity: AuthIdentity = {
-      userId: 0,
-      email: `token: ${found.name}`,
-      role: 'admin',
-      sessionId: `api-token:${found.id}`,
-      mustChangePassword: false,
-      twoFactorEnabled: false,
-      authMethod: 'password',
-      apiToken: { id: found.id, name: found.name, scopes: parseScopes(found.scopes) },
-    }
-    req.user = identity
-    return identity
-  }
-
-  async function authenticateRequest(req: FastifyRequest, options: AuthenticateOptions = {}): Promise<AuthIdentity> {
-    const token = requestToken(req)
-    if (!token) throw new Error('Missing session')
-    if (isApiToken(token)) {
-      if (!options.allowApiToken) throw new Error(API_TOKEN_NOT_ACCEPTED)
-      return authenticateApiToken(req, token)
-    }
-    const claims = req.server.jwt.verify<SessionClaims>(token)
-    if (!claims.sessionId || !Number.isInteger(claims.userId)) throw new Error('Invalid session')
-
-    const now = Date.now()
-    const session = (await db.select().from(authSessions).where(eq(authSessions.id, claims.sessionId)))[0]
-    if (!session || session.userId !== claims.userId || session.expiresAt <= now) {
-      if (session) await db.delete(authSessions).where(eq(authSessions.id, session.id))
-      throw new Error('Expired session')
-    }
-    const user = (await db.select().from(users).where(eq(users.id, claims.userId)))[0]
-    if (!user) throw new Error('Unknown user')
-
-    if (now - session.lastSeenAt >= 60_000) {
-      await db.update(authSessions).set({ lastSeenAt: now }).where(eq(authSessions.id, session.id))
-    }
-    const identity: AuthIdentity = {
-      userId: user.id,
-      email: user.email,
-      role: roles.normalize(user.role),
-      sessionId: session.id,
-      mustChangePassword: mustChangePassword(user, session.authMethod),
-      twoFactorEnabled: !!user.totpEnabled,
-      authMethod: session.authMethod === 'oidc' ? 'oidc' : 'password',
-    }
-    req.user = identity
-    return identity
-  }
-
-  async function verifyCsrf(req: FastifyRequest, identity: AuthIdentity): Promise<void> {
-    if (req.headers.authorization?.startsWith('Bearer ')) return
-    if (['GET', 'HEAD', 'OPTIONS'].includes(req.method)) return
-    const cookie = req.cookies[CSRF_COOKIE]
-    const header = req.headers['x-csrf-token']
-    if (!cookie || typeof header !== 'string' || !equalHash(hash(cookie), hash(header))) {
-      throw new Error('Invalid CSRF token')
-    }
-    const session = (await db.select({ csrfTokenHash: authSessions.csrfTokenHash })
-      .from(authSessions).where(eq(authSessions.id, identity.sessionId)))[0]
-    if (!session || !equalHash(session.csrfTokenHash, hash(header))) throw new Error('Invalid CSRF token')
-  }
-
-  async function revokeSession(sessionId: string): Promise<void> {
-    await db.delete(authSessions).where(eq(authSessions.id, sessionId))
-    hooks.onSessionsRevoked?.({ sessionId })
-  }
-
-  async function revokeUserSessions(userId: number, exceptSessionId?: string): Promise<void> {
-    const condition = exceptSessionId
-      ? and(eq(authSessions.userId, userId), ne(authSessions.id, exceptSessionId))
-      : eq(authSessions.userId, userId)
-    await db.delete(authSessions).where(condition)
-    hooks.onSessionsRevoked?.({ userId, exceptSessionId })
-  }
-
-  return { createAuthSession, clearAuthCookies, authenticateRequest, verifyCsrf, revokeSession, revokeUserSessions }
-}
-
-export type Sessions = ReturnType<typeof createSessions>
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto'
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
+import { and, eq, lt, ne } from 'drizzle-orm'
+import { authSessions, users } from './tables.js'
+import type { AuthOptions } from './context.js'
+import type { ApiTokens } from './apiTokens.js'
+
+const SESSION_SECONDS = 12 * 60 * 60
+
+export type AuthMethod = 'password' | 'oidc'
+
+export interface AuthIdentity {
+  userId: number
+  email: string
+  role: string
+  sessionId: string
+  mustChangePassword: boolean
+  twoFactorEnabled: boolean
+  authMethod: AuthMethod
+  /**
+   * Set when the request is authenticated by an API token instead of a session. A token belongs to no user: `userId`
+   * is 0, `email` is `token: <name>` (it names the token in the audit log) and `sessionId` is a synthetic
+   * `api-token:<id>`. A token has no role: `role` is a placeholder
+   * that lets it through the role checks, and what it may do is decided by `scopes`, checked for every request in
+   * authenticateOrReject.
+   */
+  apiToken?: { id: number; name: string; scopes: string[] }
+}
+
+export interface AuthenticateOptions {
+  /** API tokens are only accepted on routes that opt in; everywhere else they are refused. */
+  allowApiToken?: boolean
+}
+
+export const API_TOKEN_NOT_ACCEPTED = 'API token not accepted here'
+
+interface SessionClaims {
+  userId: number
+  email: string
+  role: string
+  sessionId: string
+}
+
+export function createSessions(ctx: AuthOptions, apiTokens: ApiTokens) {
+  const { db, roles } = ctx
+  const hooks = ctx.hooks ?? {}
+  const SESSION_COOKIE = ctx.cookies.session
+  const CSRF_COOKIE = ctx.cookies.csrf
+  const { findUsableApiToken, isApiToken, parseScopes } = apiTokens
+
+  function cookieOptions(httpOnly: boolean) {
+    return {
+      path: '/',
+      httpOnly,
+      secure: ctx.secureCookies(),
+      sameSite: 'strict' as const,
+      maxAge: SESSION_SECONDS,
+    }
+  }
+
+  function hash(value: string): string {
+    return createHash('sha256').update(value).digest('hex')
+  }
+
+  function equalHash(left: string, right: string): boolean {
+    const a = Buffer.from(left)
+    const b = Buffer.from(right)
+    return a.length === b.length && timingSafeEqual(a, b)
+  }
+
+  async function createAuthSession(
+    app: FastifyInstance,
+    reply: FastifyReply,
+    user: { id: number; email: string; role: string; mustChangePassword: number; totpEnabled: number },
+    authMethod: AuthMethod = 'password',
+  ): Promise<AuthIdentity> {
+    const now = Date.now()
+    const sessionId = randomUUID()
+    const csrfToken = randomBytes(32).toString('base64url')
+    const expiresAt = now + SESSION_SECONDS * 1000
+    await db.delete(authSessions).where(lt(authSessions.expiresAt, now))
+    await db.insert(authSessions).values({
+      id: sessionId,
+      userId: user.id,
+      csrfTokenHash: hash(csrfToken),
+      createdAt: now,
+      lastSeenAt: now,
+      expiresAt,
+      authMethod,
+      verifiedAt: now,
+    })
+
+    const role = roles.normalize(user.role)
+    const token = app.jwt.sign({ userId: user.id, email: user.email, role, sessionId })
+    reply.setCookie(SESSION_COOKIE, token, cookieOptions(true))
+    reply.setCookie(CSRF_COOKIE, csrfToken, cookieOptions(false))
+    return {
+      userId: user.id,
+      email: user.email,
+      role,
+      sessionId,
+      mustChangePassword: mustChangePassword(user, authMethod),
+      twoFactorEnabled: !!user.totpEnabled,
+      authMethod,
+    }
+  }
+
+  /**
+   * A password session must replace a pending temporary password, so the one the administrator handed out stops
+   * working. An SSO session never has to: the SSO sign-in makes the temporary password unusable instead.
+   */
+  function mustChangePassword(user: { mustChangePassword: number }, authMethod: string): boolean {
+    return !!user.mustChangePassword && authMethod !== 'oidc'
+  }
+
+  function clearAuthCookies(reply: FastifyReply): void {
+    const base = { path: '/', secure: ctx.secureCookies(), sameSite: 'strict' as const }
+    reply.clearCookie(SESSION_COOKIE, { ...base, httpOnly: true })
+    reply.clearCookie(CSRF_COOKIE, { ...base, httpOnly: false })
+  }
+
+  function requestToken(req: FastifyRequest): string | null {
+    const authorization = req.headers.authorization
+    if (authorization?.startsWith('Bearer ')) return authorization.slice(7)
+    return req.cookies[SESSION_COOKIE] ?? null
+  }
+
+  async function authenticateApiToken(req: FastifyRequest, token: string): Promise<AuthIdentity> {
+    const found = await findUsableApiToken(token)
+    if (!found) throw new Error('Invalid API token')
+    const identity: AuthIdentity = {
+      userId: 0,
+      email: `token: ${found.name}`,
+      role: 'admin',
+      sessionId: `api-token:${found.id}`,
+      mustChangePassword: false,
+      twoFactorEnabled: false,
+      authMethod: 'password',
+      apiToken: { id: found.id, name: found.name, scopes: parseScopes(found.scopes) },
+    }
+    req.user = identity
+    return identity
+  }
+
+  async function authenticateRequest(req: FastifyRequest, options: AuthenticateOptions = {}): Promise<AuthIdentity> {
+    const token = requestToken(req)
+    if (!token) throw new Error('Missing session')
+    if (isApiToken(token)) {
+      if (!options.allowApiToken) throw new Error(API_TOKEN_NOT_ACCEPTED)
+      return authenticateApiToken(req, token)
+    }
+    const claims = req.server.jwt.verify<SessionClaims>(token)
+    if (!claims.sessionId || !Number.isInteger(claims.userId)) throw new Error('Invalid session')
+
+    const now = Date.now()
+    const session = (await db.select().from(authSessions).where(eq(authSessions.id, claims.sessionId)))[0]
+    if (!session || session.userId !== claims.userId || session.expiresAt <= now) {
+      if (session) await db.delete(authSessions).where(eq(authSessions.id, session.id))
+      throw new Error('Expired session')
+    }
+    const user = (await db.select().from(users).where(eq(users.id, claims.userId)))[0]
+    if (!user) throw new Error('Unknown user')
+
+    if (now - session.lastSeenAt >= 60_000) {
+      await db.update(authSessions).set({ lastSeenAt: now }).where(eq(authSessions.id, session.id))
+    }
+    const identity: AuthIdentity = {
+      userId: user.id,
+      email: user.email,
+      role: roles.normalize(user.role),
+      sessionId: session.id,
+      mustChangePassword: mustChangePassword(user, session.authMethod),
+      twoFactorEnabled: !!user.totpEnabled,
+      authMethod: session.authMethod === 'oidc' ? 'oidc' : 'password',
+    }
+    req.user = identity
+    return identity
+  }
+
+  async function verifyCsrf(req: FastifyRequest, identity: AuthIdentity): Promise<void> {
+    if (req.headers.authorization?.startsWith('Bearer ')) return
+    if (['GET', 'HEAD', 'OPTIONS'].includes(req.method)) return
+    const cookie = req.cookies[CSRF_COOKIE]
+    const header = req.headers['x-csrf-token']
+    if (!cookie || typeof header !== 'string' || !equalHash(hash(cookie), hash(header))) {
+      throw new Error('Invalid CSRF token')
+    }
+    const session = (await db.select({ csrfTokenHash: authSessions.csrfTokenHash })
+      .from(authSessions).where(eq(authSessions.id, identity.sessionId)))[0]
+    if (!session || !equalHash(session.csrfTokenHash, hash(header))) throw new Error('Invalid CSRF token')
+  }
+
+  async function revokeSession(sessionId: string): Promise<void> {
+    await db.delete(authSessions).where(eq(authSessions.id, sessionId))
+    hooks.onSessionsRevoked?.({ sessionId })
+  }
+
+  async function revokeUserSessions(userId: number, exceptSessionId?: string): Promise<void> {
+    const condition = exceptSessionId
+      ? and(eq(authSessions.userId, userId), ne(authSessions.id, exceptSessionId))
+      : eq(authSessions.userId, userId)
+    await db.delete(authSessions).where(condition)
+    hooks.onSessionsRevoked?.({ userId, exceptSessionId })
+  }
+
+  return { createAuthSession, clearAuthCookies, authenticateRequest, verifyCsrf, revokeSession, revokeUserSessions }
+}
+
+export type Sessions = ReturnType<typeof createSessions>