@better-forge/auth 0.1.0 → 0.1.1

package/src/setupRoutes.ts

@@ -1,100 +1,100 @@
-import type { FastifyInstance, FastifyReply } from 'fastify'
-import bcrypt from 'bcryptjs'
-import { eq } from 'drizzle-orm'
-import type { SqliteDatabase } from '@better-forge/db'
-import { users } from './tables.js'
-
-export interface SetupRoutesOptions<Identity extends { sessionId?: string }> {
-  db: SqliteDatabase
-  /** Runs `work` so that all of it is written, or none of it. */
-  withTransaction: <T>(work: () => Promise<T>) => Promise<T>
-  isSetupComplete: () => boolean
-  /** Records that setup is done. Called as the last step inside the transaction: if it throws, the administrator is not kept. */
-  writeSetupComplete: () => void
-  /** Takes the record back, when the transaction fails to commit after it was written. */
-  removeSetupMarker: () => void
-  /** Opens the database and brings its tables up to date; called once the request has been checked. */
-  prepareDatabase: () => void
-  /** Signs the new administrator in. */
-  createSession: (app: FastifyInstance, reply: FastifyReply, user: typeof users.$inferSelect) => Promise<Identity>
-  /** Rate limit of `POST /complete` (the config the rate limit plugin understands). */
-  rateLimit: Record<string, unknown>
-  /** Writes whatever else the application needs on first run, inside the same transaction as the administrator. */
-  onSetup?: () => Promise<void>
-  /** Starts the work that runs only once the application is set up. */
-  startBackgroundServices?: () => void
-  /** Lets setup run although accounts already exist, for an installation that is filled with accounts before its first run. Checked on each request. */
-  allowExistingUsers?: () => boolean
-}
-
-/**
- * The first-run routes: whether the application still needs setup, and the one request that creates the administrator
- * and finishes it. Setup is refused once it is done, and only one attempt runs at a time.
- */
-export function createSetupRoutes<Identity extends { sessionId?: string }>(options: SetupRoutesOptions<Identity>) {
-  const { db } = options
-  let inProgress = false
-
-  return async function setupRoutes(app: FastifyInstance, overrides: { startBackgroundServices?: () => void } = {}) {
-    app.get('/status', async () => ({ needsSetup: !options.isSetupComplete() }))
-
-    app.post<{ Body: { email: string; password: string } }>('/complete', {
-      config: { rateLimit: options.rateLimit },
-    }, async (req, reply) => {
-      if (options.isSetupComplete()) {
-        return reply.code(409).send({ error: 'Setup already completed' })
-      }
-
-      const { email, password } = req.body ?? {}
-      if (typeof email !== 'string' || typeof password !== 'string' || !email || !password) {
-        return reply.code(400).send({ error: 'Email and password are required' })
-      }
-      if (email.length > 254 || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
-        return reply.code(400).send({ error: 'A valid email address is required' })
-      }
-      if (password.length < 8 || password.length > 128) {
-        return reply.code(400).send({ error: 'Password must be between 8 and 128 characters' })
-      }
-
-      if (inProgress) {
-        return reply.code(409).send({ error: 'Setup is already in progress' })
-      }
-
-      inProgress = true
-      try {
-        // Initialize DB and run migrations now that we have a confirmed DB type
-        options.prepareDatabase()
-
-        const hash = await bcrypt.hash(password, 10)
-        let setupMarkerWritten = false
-        const user = await options.withTransaction(async () => {
-          // The marker can be missing while the data is not (a lost volume, a restore). Accounts that already
-          // exist mean setup was done: never create or overwrite an administrator over them.
-          if (!options.allowExistingUsers?.() && (await db.select({ id: users.id }).from(users).limit(1)).length > 0) return null
-
-          await db.insert(users).values({ email, passwordHash: hash, role: 'admin', createdAt: Date.now() })
-
-          await options.onSetup?.()
-
-          const admin = (await db.select().from(users).where(eq(users.email, email)))[0]!
-          // Last step: if writing the marker fails the admin insert rolls back with it.
-          options.writeSetupComplete()
-          setupMarkerWritten = true
-          return admin
-        }).catch((error: unknown) => {
-          // COMMIT itself failed after the marker was written — undo it so setup can be retried.
-          if (setupMarkerWritten) options.removeSetupMarker()
-          throw error
-        })
-        if (!user) return reply.code(409).send({ error: 'Setup already completed' })
-        const startServices = overrides.startBackgroundServices ?? options.startBackgroundServices
-        startServices?.()
-        const identity = await options.createSession(app, reply, user)
-        const { sessionId: _sessionId, ...safeIdentity } = identity
-        return safeIdentity
-      } finally {
-        inProgress = false
-      }
-    })
-  }
-}
+import type { FastifyInstance, FastifyReply } from 'fastify'
+import bcrypt from 'bcryptjs'
+import { eq } from 'drizzle-orm'
+import type { SqliteDatabase } from '@better-forge/db'
+import { users } from './tables.js'
+
+export interface SetupRoutesOptions<Identity extends { sessionId?: string }> {
+  db: SqliteDatabase
+  /** Runs `work` so that all of it is written, or none of it. */
+  withTransaction: <T>(work: () => Promise<T>) => Promise<T>
+  isSetupComplete: () => boolean
+  /** Records that setup is done. Called as the last step inside the transaction: if it throws, the administrator is not kept. */
+  writeSetupComplete: () => void
+  /** Takes the record back, when the transaction fails to commit after it was written. */
+  removeSetupMarker: () => void
+  /** Opens the database and brings its tables up to date; called once the request has been checked. */
+  prepareDatabase: () => void
+  /** Signs the new administrator in. */
+  createSession: (app: FastifyInstance, reply: FastifyReply, user: typeof users.$inferSelect) => Promise<Identity>
+  /** Rate limit of `POST /complete` (the config the rate limit plugin understands). */
+  rateLimit: Record<string, unknown>
+  /** Writes whatever else the application needs on first run, inside the same transaction as the administrator. */
+  onSetup?: () => Promise<void>
+  /** Starts the work that runs only once the application is set up. */
+  startBackgroundServices?: () => void
+  /** Lets setup run although accounts already exist, for an installation that is filled with accounts before its first run. Checked on each request. */
+  allowExistingUsers?: () => boolean
+}
+
+/**
+ * The first-run routes: whether the application still needs setup, and the one request that creates the administrator
+ * and finishes it. Setup is refused once it is done, and only one attempt runs at a time.
+ */
+export function createSetupRoutes<Identity extends { sessionId?: string }>(options: SetupRoutesOptions<Identity>) {
+  const { db } = options
+  let inProgress = false
+
+  return async function setupRoutes(app: FastifyInstance, overrides: { startBackgroundServices?: () => void } = {}) {
+    app.get('/status', async () => ({ needsSetup: !options.isSetupComplete() }))
+
+    app.post<{ Body: { email: string; password: string } }>('/complete', {
+      config: { rateLimit: options.rateLimit },
+    }, async (req, reply) => {
+      if (options.isSetupComplete()) {
+        return reply.code(409).send({ error: 'Setup already completed' })
+      }
+
+      const { email, password } = req.body ?? {}
+      if (typeof email !== 'string' || typeof password !== 'string' || !email || !password) {
+        return reply.code(400).send({ error: 'Email and password are required' })
+      }
+      if (email.length > 254 || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+        return reply.code(400).send({ error: 'A valid email address is required' })
+      }
+      if (password.length < 8 || password.length > 128) {
+        return reply.code(400).send({ error: 'Password must be between 8 and 128 characters' })
+      }
+
+      if (inProgress) {
+        return reply.code(409).send({ error: 'Setup is already in progress' })
+      }
+
+      inProgress = true
+      try {
+        // Initialize DB and run migrations now that we have a confirmed DB type
+        options.prepareDatabase()
+
+        const hash = await bcrypt.hash(password, 10)
+        let setupMarkerWritten = false
+        const user = await options.withTransaction(async () => {
+          // The marker can be missing while the data is not (a lost volume, a restore). Accounts that already
+          // exist mean setup was done: never create or overwrite an administrator over them.
+          if (!options.allowExistingUsers?.() && (await db.select({ id: users.id }).from(users).limit(1)).length > 0) return null
+
+          await db.insert(users).values({ email, passwordHash: hash, role: 'admin', createdAt: Date.now() })
+
+          await options.onSetup?.()
+
+          const admin = (await db.select().from(users).where(eq(users.email, email)))[0]!
+          // Last step: if writing the marker fails the admin insert rolls back with it.
+          options.writeSetupComplete()
+          setupMarkerWritten = true
+          return admin
+        }).catch((error: unknown) => {
+          // COMMIT itself failed after the marker was written — undo it so setup can be retried.
+          if (setupMarkerWritten) options.removeSetupMarker()
+          throw error
+        })
+        if (!user) return reply.code(409).send({ error: 'Setup already completed' })
+        const startServices = overrides.startBackgroundServices ?? options.startBackgroundServices
+        startServices?.()
+        const identity = await options.createSession(app, reply, user)
+        const { sessionId: _sessionId, ...safeIdentity } = identity
+        return safeIdentity
+      } finally {
+        inProgress = false
+      }
+    })
+  }
+}

package/src/signInAudit.ts

@@ -1,43 +1,43 @@
-import type { AuthOptions } from './context.js'
-
-/** How the user tried to sign in, as recorded in `diff.method` of 'sign_in' audit entries. */
-export type SignInMethod = 'password' | 'sso'
-
-/** Why a password, or the authentication-code step of any sign-in, was refused. SSO refusals use the OIDC codes. */
-export type CredentialDenialCode =
-  | 'password_login_disabled'
-  | 'no_matching_account'
-  | 'wrong_password'
-  | 'two_factor_expired'
-  | 'invalid_two_factor_code'
-
-export interface SignInDenial {
-  code: string
-  reason: string
-  email?: string | undefined
-}
-
-export function createSignInAudit(ctx: AuthOptions) {
-  const { audit } = ctx
-
-  /** Records a successful sign-in; `twoFactor` says whether an authentication code was part of it. */
-  async function auditSignIn(user: { id: number; email: string }, method: SignInMethod, twoFactor: boolean): Promise<void> {
-    await audit.write({ userId: user.id, userEmail: user.email }, 'allow', 'sign_in', user.id, user.email, { method, twoFactor })
-  }
-
-  /**
-   * Records a refused sign-in. Nobody is signed in, so the actor is user 0 with the email that was entered or that
-   * the provider asserted, when there was one. The user only ever sees a generic message; this holds the reason.
-   */
-  async function auditSignInDenial(method: SignInMethod, denial: SignInDenial, extra: Record<string, unknown> = {}): Promise<void> {
-    await audit.write(
-      { userId: 0, userEmail: denial.email ?? `unknown (${method === 'sso' ? 'SSO' : 'password'})` },
-      'deny', 'sign_in', null, denial.email ?? (method === 'sso' ? 'SSO sign-in' : 'Password sign-in'),
-      { method, code: denial.code, reason: denial.reason, ...extra },
-    )
-  }
-
-  return { auditSignIn, auditSignInDenial }
-}
-
-export type SignInAudit = ReturnType<typeof createSignInAudit>
+import type { AuthOptions } from './context.js'
+
+/** How the user tried to sign in, as recorded in `diff.method` of 'sign_in' audit entries. */
+export type SignInMethod = 'password' | 'sso'
+
+/** Why a password, or the authentication-code step of any sign-in, was refused. SSO refusals use the OIDC codes. */
+export type CredentialDenialCode =
+  | 'password_login_disabled'
+  | 'no_matching_account'
+  | 'wrong_password'
+  | 'two_factor_expired'
+  | 'invalid_two_factor_code'
+
+export interface SignInDenial {
+  code: string
+  reason: string
+  email?: string | undefined
+}
+
+export function createSignInAudit(ctx: AuthOptions) {
+  const { audit } = ctx
+
+  /** Records a successful sign-in; `twoFactor` says whether an authentication code was part of it. */
+  async function auditSignIn(user: { id: number; email: string }, method: SignInMethod, twoFactor: boolean): Promise<void> {
+    await audit.write({ userId: user.id, userEmail: user.email }, 'allow', 'sign_in', user.id, user.email, { method, twoFactor })
+  }
+
+  /**
+   * Records a refused sign-in. Nobody is signed in, so the actor is user 0 with the email that was entered or that
+   * the provider asserted, when there was one. The user only ever sees a generic message; this holds the reason.
+   */
+  async function auditSignInDenial(method: SignInMethod, denial: SignInDenial, extra: Record<string, unknown> = {}): Promise<void> {
+    await audit.write(
+      { userId: 0, userEmail: denial.email ?? `unknown (${method === 'sso' ? 'SSO' : 'password'})` },
+      'deny', 'sign_in', null, denial.email ?? (method === 'sso' ? 'SSO sign-in' : 'Password sign-in'),
+      { method, code: denial.code, reason: denial.reason, ...extra },
+    )
+  }
+
+  return { auditSignIn, auditSignInDenial }
+}
+
+export type SignInAudit = ReturnType<typeof createSignInAudit>

package/src/tables.ts

@@ -1,59 +1,59 @@
-import { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core'
-
-export const users = sqliteTable('users', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  email: text('email').notNull().unique(),
-  passwordHash: text('password_hash').notNull(),
-  role: text('role').notNull().default('admin'),
-  createdAt: integer('created_at').notNull(),
-  // Additive columns (added via ALTER TABLE, must stay at end for sqlite-proxy position mapping)
-  mustChangePassword: integer('must_change_password').notNull().default(0),
-  totpSecret: text('totp_secret'),
-  totpEnabled: integer('totp_enabled').notNull().default(0),
-  totpRecoveryCodes: text('totp_recovery_codes'),
-  // SSO identity bound on the first OIDC sign-in; later sign-ins match on it instead of the email.
-  oidcIssuer: text('oidc_issuer'),
-  oidcSubject: text('oidc_subject'),
-})
-
-export const authSessions = sqliteTable('auth_sessions', {
-  id: text('id').primaryKey(),
-  userId: integer('user_id').notNull(),
-  csrfTokenHash: text('csrf_token_hash').notNull(),
-  createdAt: integer('created_at').notNull(),
-  lastSeenAt: integer('last_seen_at').notNull(),
-  expiresAt: integer('expires_at').notNull(),
-  // 'password' or 'oidc'. An SSO session never asks for the temporary password to be changed.
-  authMethod: text('auth_method').notNull().default('password'),
-  // When the user last proved who they are in this session: the sign-in, or a later SSO confirmation.
-  verifiedAt: integer('verified_at'),
-})
-
-/** Long-lived bearer credentials for scripts and CI. Only the SHA-256 of the token is stored; revoking deletes the row. */
-export const apiTokens = sqliteTable('api_tokens', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  name: text('name').notNull(),
-  tokenHash: text('token_hash').notNull().unique(),
-  /** Leading characters of the token, so it can be recognised in the list. */
-  prefix: text('prefix').notNull(),
-  createdAt: integer('created_at').notNull(),
-  expiresAt: integer('expires_at'),
-  lastUsedAt: integer('last_used_at'),
-  /** JSON list of what the token may do, e.g. `["notes:write","tags:read"]` (the permissions are defined by the application). */
-  scopes: text('scopes').notNull(),
-})
-
-export const oidcSettings = sqliteTable('oidc_settings', {
-  id: integer('id').primaryKey(),
-  enabled: integer('enabled').notNull().default(0),
-  issuer: text('issuer').notNull().default(''),
-  clientId: text('client_id').notNull().default(''),
-  /** Stored encrypted by the application's secret box; empty when no secret is set. */
-  clientSecret: text('client_secret').notNull().default(''),
-  scopes: text('scopes').notNull().default(''),
-  redirectUri: text('redirect_uri').notNull().default(''),
-  buttonLabel: text('button_label').notNull().default(''),
-  allowUnverifiedEmail: integer('allow_unverified_email').notNull().default(0),
-  disablePasswordLogin: integer('disable_password_login').notNull().default(0),
-  updatedAt: integer('updated_at').notNull(),
-})
+import { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core'
+
+export const users = sqliteTable('users', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  email: text('email').notNull().unique(),
+  passwordHash: text('password_hash').notNull(),
+  role: text('role').notNull().default('admin'),
+  createdAt: integer('created_at').notNull(),
+  // Additive columns (added via ALTER TABLE, must stay at end for sqlite-proxy position mapping)
+  mustChangePassword: integer('must_change_password').notNull().default(0),
+  totpSecret: text('totp_secret'),
+  totpEnabled: integer('totp_enabled').notNull().default(0),
+  totpRecoveryCodes: text('totp_recovery_codes'),
+  // SSO identity bound on the first OIDC sign-in; later sign-ins match on it instead of the email.
+  oidcIssuer: text('oidc_issuer'),
+  oidcSubject: text('oidc_subject'),
+})
+
+export const authSessions = sqliteTable('auth_sessions', {
+  id: text('id').primaryKey(),
+  userId: integer('user_id').notNull(),
+  csrfTokenHash: text('csrf_token_hash').notNull(),
+  createdAt: integer('created_at').notNull(),
+  lastSeenAt: integer('last_seen_at').notNull(),
+  expiresAt: integer('expires_at').notNull(),
+  // 'password' or 'oidc'. An SSO session never asks for the temporary password to be changed.
+  authMethod: text('auth_method').notNull().default('password'),
+  // When the user last proved who they are in this session: the sign-in, or a later SSO confirmation.
+  verifiedAt: integer('verified_at'),
+})
+
+/** Long-lived bearer credentials for scripts and CI. Only the SHA-256 of the token is stored; revoking deletes the row. */
+export const apiTokens = sqliteTable('api_tokens', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  name: text('name').notNull(),
+  tokenHash: text('token_hash').notNull().unique(),
+  /** Leading characters of the token, so it can be recognised in the list. */
+  prefix: text('prefix').notNull(),
+  createdAt: integer('created_at').notNull(),
+  expiresAt: integer('expires_at'),
+  lastUsedAt: integer('last_used_at'),
+  /** JSON list of what the token may do, e.g. `["notes:write","tags:read"]` (the permissions are defined by the application). */
+  scopes: text('scopes').notNull(),
+})
+
+export const oidcSettings = sqliteTable('oidc_settings', {
+  id: integer('id').primaryKey(),
+  enabled: integer('enabled').notNull().default(0),
+  issuer: text('issuer').notNull().default(''),
+  clientId: text('client_id').notNull().default(''),
+  /** Stored encrypted by the application's secret box; empty when no secret is set. */
+  clientSecret: text('client_secret').notNull().default(''),
+  scopes: text('scopes').notNull().default(''),
+  redirectUri: text('redirect_uri').notNull().default(''),
+  buttonLabel: text('button_label').notNull().default(''),
+  allowUnverifiedEmail: integer('allow_unverified_email').notNull().default(0),
+  disablePasswordLogin: integer('disable_password_login').notNull().default(0),
+  updatedAt: integer('updated_at').notNull(),
+})

package/src/tokenCatalogue.ts

@@ -1,42 +1,42 @@
-import type { TokenPreset, TokenResource } from '@better-forge/contracts'
-import { VAULT_USE_SCOPE, normalizeScopes } from '@better-forge/contracts'
-
-export interface TokenCatalogue {
-  /** Every permission a token can hold, in the order they are listed: `<part>:read`, `<part>:write`, then the extra ones. */
-  readonly scopes: readonly string[]
-  readonly resources: readonly TokenResource[]
-  readonly presets: readonly TokenPreset[]
-  /** A clean list of known permissions (reading added wherever writing is granted), or null if one is unknown or none is given. */
-  normalize(input: unknown): string[] | null
-  /** The permissions stored with a token. Anything that is not a known permission is dropped. */
-  parse(stored: string): string[]
-}
-
-/**
- * The permissions an API token can be given. A part is a group of routes (`belongsTo(scope, part)` ties routes to
- * it); `extraScopes` are single permissions that belong to no part, such as the one to use vault secrets.
- */
-export function createTokenCatalogue(options: {
-  resources: readonly TokenResource[]
-  extraScopes?: readonly string[]
-  presets?: (scopes: readonly string[]) => readonly TokenPreset[]
-}): TokenCatalogue {
-  const scopes = [
-    ...options.resources.flatMap((resource) => resource.levels.map((level) => `${resource.key}:${level}`)),
-    ...(options.extraScopes ?? [VAULT_USE_SCOPE]),
-  ]
-  return {
-    scopes,
-    resources: options.resources,
-    presets: options.presets?.(scopes) ?? [],
-    normalize: (input) => normalizeScopes(input, scopes),
-    parse(stored) {
-      try {
-        const parsed: unknown = JSON.parse(stored)
-        return Array.isArray(parsed) ? parsed.filter((scope): scope is string => typeof scope === 'string' && scopes.includes(scope)) : []
-      } catch {
-        return []
-      }
-    },
-  }
-}
+import type { TokenPreset, TokenResource } from '@better-forge/contracts'
+import { VAULT_USE_SCOPE, normalizeScopes } from '@better-forge/contracts'
+
+export interface TokenCatalogue {
+  /** Every permission a token can hold, in the order they are listed: `<part>:read`, `<part>:write`, then the extra ones. */
+  readonly scopes: readonly string[]
+  readonly resources: readonly TokenResource[]
+  readonly presets: readonly TokenPreset[]
+  /** A clean list of known permissions (reading added wherever writing is granted), or null if one is unknown or none is given. */
+  normalize(input: unknown): string[] | null
+  /** The permissions stored with a token. Anything that is not a known permission is dropped. */
+  parse(stored: string): string[]
+}
+
+/**
+ * The permissions an API token can be given. A part is a group of routes (`belongsTo(scope, part)` ties routes to
+ * it); `extraScopes` are single permissions that belong to no part, such as the one to use vault secrets.
+ */
+export function createTokenCatalogue(options: {
+  resources: readonly TokenResource[]
+  extraScopes?: readonly string[]
+  presets?: (scopes: readonly string[]) => readonly TokenPreset[]
+}): TokenCatalogue {
+  const scopes = [
+    ...options.resources.flatMap((resource) => resource.levels.map((level) => `${resource.key}:${level}`)),
+    ...(options.extraScopes ?? [VAULT_USE_SCOPE]),
+  ]
+  return {
+    scopes,
+    resources: options.resources,
+    presets: options.presets?.(scopes) ?? [],
+    normalize: (input) => normalizeScopes(input, scopes),
+    parse(stored) {
+      try {
+        const parsed: unknown = JSON.parse(stored)
+        return Array.isArray(parsed) ? parsed.filter((scope): scope is string => typeof scope === 'string' && scopes.includes(scope)) : []
+      } catch {
+        return []
+      }
+    },
+  }
+}