pipework 0.252.0 → 0.253.0

package/src/auth/auth/index.ts

@@ -0,0 +1,18 @@
+export type { AuthStrategy, AuthRequest, AuthContext, BaseAuth } from './types.js'
+export { runAuthChain } from './chain.js'
+export type { AuthEnricher, TenantResolver, AuthChainConfig, AuthChainResult } from './chain.js'
+export { createSessions } from './sessions.js'
+export type { SessionAuth, SessionStrategyOptions } from './sessions.js'
+export type { Sessions, SessionConfig, TokenPair, TokenPayload, HttpTokenResult, HttpRequest, HttpResponse } from './sessions.js'
+export type { CookieConfig, ResolvedCookieConfig } from './cookie.js'
+export { resolveCookieConfig, buildSetCookieHeader, buildClearCookieHeader, parseCookieHeader } from './cookie.js'
+export { createMultiOrgSessions } from './multi-org.js'
+export type { MultiOrgConfig, MultiOrgSessions, ResolveLoginResult, AuthenticatedResult, OrgSelectResult, OrgMembership, OrgInfo, OrgMembershipDetail } from './multi-org.js'
+export { createPasswords } from './passwords.js'
+export type { Passwords, PasswordsConfig, ScryptParams, VerifyResult } from './passwords.js'
+export { createSignIn } from './sign-in.js'
+export type { SignIn, SignInConfig, SignInAttempt, SignInResult } from './sign-in.js'
+export { createGuard } from './guard.js'
+export type { Guard, GuardConfig, GuardKeys, GuardTake, GuardStatus } from './guard.js'
+export { createEmailLinks } from './email-links.js'
+export type { EmailLinks, EmailLinksConfig, EmailLinkPurpose, EmailLinkPurposeConfig, EmailLinkState, EmailLinkCheck, EmailLinkRefusal, RequestLimit } from './email-links.js'

package/src/auth/auth/multi-org.ts

@@ -0,0 +1,337 @@
+import { SignJWT, jwtVerify } from 'jose'
+import { parseExpiry } from './parse-expiry.js'
+import { sql } from '../../data/db/sql.js'
+import type { DB } from '../../data/db/index.js'
+import { ForbiddenError, UnauthorizedError, ConflictError, NotFoundError } from '../../core/errors/index.js'
+import { assertValidIdentifier } from '../../data/db/identifiers.js'
+import { assertUuid } from './uuid.js'
+import { checkSigningKeys, importSigningKey } from './signing-keys.js'
+import type { Sessions, HttpResponse, HttpRequest, HttpTokenResult } from './sessions.js'
+import { refuseScopedHandle } from '../tenant/scoped-db.js'
+
+/** Configuration for multi-org sessions — base sessions, signing keys, org-select token TTL. */
+export interface MultiOrgConfig {
+  readonly sessions: Sessions
+  readonly signing: { algorithm: 'ES256'; privateKey: string; publicKey: string }
+  readonly issuer: string
+  readonly audience: string
+  readonly orgSelectToken?: { readonly expiresIn?: string }
+  /**
+   * Membership table name. Default `pipework_user_orgs`, whose definition ships with the `orgs: {}`
+   * blueprint flag. A custom name means the app owns that table's DDL (org_id uuid, same columns).
+   */
+  readonly table?: string
+  readonly resolveOrgNames?: (db: DB, orgIds: string[]) => Promise<Map<string, string>>
+}
+
+/** A user's membership in an organization — userId, orgId, role. */
+export interface OrgMembership {
+  readonly id: string
+  readonly orgId: string
+  readonly role: string | null
+  readonly joinedAt: Date
+}
+
+/** Basic organization info — id and display name. */
+export interface OrgInfo {
+  readonly id: string
+  readonly name: string
+}
+
+/** Organization membership with display name — extends OrgMembership with org info. */
+export interface OrgMembershipDetail {
+  readonly id: string
+  readonly name: string
+  readonly role: string | null
+}
+
+/** Result when user has exactly one org — direct authentication, no org selection needed. */
+export interface AuthenticatedResult {
+  readonly type: 'authenticated'
+  readonly accessToken: string
+  readonly expiresIn: number
+}
+
+/** Result when user has multiple orgs — returns a session token for org selection. */
+export interface OrgSelectResult {
+  readonly type: 'org_select'
+  readonly sessionToken: string
+  readonly orgs: readonly OrgInfo[]
+}
+
+/** Union result from resolveLogin() — either AuthenticatedResult or OrgSelectResult. */
+export type ResolveLoginResult = AuthenticatedResult | OrgSelectResult
+
+/** Multi-org session manager — login resolution, org selection, switching, membership CRUD. */
+export interface MultiOrgSessions {
+  resolveLogin(
+    response: HttpResponse,
+    db: DB,
+    user: { id: string },
+  ): Promise<ResolveLoginResult>
+
+  selectOrg(
+    response: HttpResponse,
+    db: DB,
+    sessionToken: string,
+    orgId: string,
+  ): Promise<HttpTokenResult>
+
+  switchOrg(
+    response: HttpResponse,
+    db: DB,
+    request: Pick<HttpRequest, 'headers'> & { readonly method?: string },
+    orgId: string,
+    userId: string,
+  ): Promise<HttpTokenResult>
+
+  listOrgs(
+    db: DB,
+    userId: string,
+  ): Promise<{ orgs: readonly OrgMembershipDetail[] }>
+
+  addMember(
+    db: DB,
+    params: { userId: string; orgId: string; role?: string; addedBy?: string },
+  ): Promise<{ id: string }>
+
+  removeMember(
+    db: DB,
+    params: { userId: string; orgId: string },
+  ): Promise<void>
+
+  checkMembership(
+    db: DB,
+    userId: string,
+    orgId: string,
+  ): Promise<OrgMembership | null>
+}
+
+/**
+ * Creates a multi-org session manager with org selection flow and membership management.
+ * The default table comes from blueprint `orgs: {}`; org ids must be uuids.
+ */
+export function createMultiOrgSessions(config: MultiOrgConfig): MultiOrgSessions {
+  const tableName = config.table ?? 'pipework_user_orgs'
+  assertValidIdentifier(tableName, 'multi-org membership table')
+  const t = sql.raw(`"${tableName}"`)
+
+  checkSigningKeys(config.signing, 'createMultiOrgSessions')
+
+  const orgSelectAudience = `${config.audience}:org-select`
+  const orgSelectExpiresIn = config.orgSelectToken?.expiresIn ?? '10m'
+
+  let cachedPrivateKey: CryptoKey | null = null
+  let cachedPublicKey: CryptoKey | null = null
+
+  async function getPrivateKey(): Promise<CryptoKey> {
+    if (cachedPrivateKey === null) {
+      cachedPrivateKey = await importSigningKey('private', config.signing, 'createMultiOrgSessions')
+    }
+    return cachedPrivateKey
+  }
+
+  async function getPublicKey(): Promise<CryptoKey> {
+    if (cachedPublicKey === null) {
+      cachedPublicKey = await importSigningKey('public', config.signing, 'createMultiOrgSessions')
+    }
+    return cachedPublicKey
+  }
+
+
+  async function signOrgSelectToken(userId: string): Promise<string> {
+    const key = await getPrivateKey()
+    const expiresInSeconds = parseExpiry(orgSelectExpiresIn)
+    return new SignJWT({ purpose: 'org_select' })
+      .setProtectedHeader({ alg: config.signing.algorithm })
+      .setSubject(userId)
+      .setIssuer(config.issuer)
+      .setAudience(orgSelectAudience)
+      .setIssuedAt()
+      .setExpirationTime(`${expiresInSeconds}s`)
+      .sign(key)
+  }
+
+  async function verifyOrgSelectToken(token: string): Promise<string> {
+    const key = await getPublicKey()
+    try {
+      const { payload } = await jwtVerify(token, key, {
+        algorithms: [config.signing.algorithm],
+        issuer: config.issuer,
+        audience: orgSelectAudience,
+      })
+      if (payload['purpose'] !== 'org_select') {
+        throw new Error('wrong purpose')
+      }
+      return payload.sub!
+    } catch {
+      throw new UnauthorizedError(
+        'Invalid or expired organization selection token. Please log in again.',
+      )
+    }
+  }
+
+  async function requireMembership(db: DB, userId: string, orgId: string): Promise<void> {
+    assertUuid(orgId, 'orgId')
+    const rows = await db.execute(
+      sql`SELECT 1 FROM ${t} WHERE user_id = ${userId} AND org_id = ${orgId}`,
+    )
+    if (rows.length === 0) {
+      throw new ForbiddenError('You are not a member of this organization.')
+    }
+  }
+
+  async function resolveLogin(
+    response: HttpResponse,
+    db: DB,
+    user: { id: string },
+  ): Promise<ResolveLoginResult> {
+    const rows = await db.execute(
+      sql`SELECT org_id, role FROM ${t} WHERE user_id = ${user.id} ORDER BY joined_at`,
+    )
+
+    if (rows.length === 0) {
+      throw new ForbiddenError(
+        'User has no organization memberships. Contact your administrator to be added to an organization.',
+      )
+    }
+
+    if (rows.length === 1) {
+      const orgId = rows[0]!['org_id'] as string
+      const result = await config.sessions.issueTokensHttp(response, db, { id: user.id, tenantId: orgId })
+      return { type: 'authenticated', accessToken: result.accessToken, expiresIn: result.expiresIn }
+    }
+
+    const orgIds = rows.map(r => r['org_id'] as string)
+    let orgNames: Map<string, string> | null = null
+    if (config.resolveOrgNames !== undefined) {
+      orgNames = await config.resolveOrgNames(db, orgIds)
+    }
+
+    const orgs: OrgInfo[] = orgIds.map(id => ({
+      id,
+      name: orgNames?.get(id) ?? id,
+    }))
+
+    const sessionToken = await signOrgSelectToken(user.id)
+    return { type: 'org_select', sessionToken, orgs }
+  }
+
+  async function selectOrg(
+    response: HttpResponse,
+    db: DB,
+    sessionToken: string,
+    orgId: string,
+  ): Promise<HttpTokenResult> {
+    const userId = await verifyOrgSelectToken(sessionToken)
+    await requireMembership(db, userId, orgId)
+    return config.sessions.issueTokensHttp(response, db, { id: userId, tenantId: orgId })
+  }
+
+  async function switchOrg(
+    response: HttpResponse,
+    db: DB,
+    request: Pick<HttpRequest, 'headers'> & { readonly method?: string },
+    orgId: string,
+    userId: string,
+  ): Promise<HttpTokenResult> {
+    config.sessions.assertSameSiteCookie(request)
+    await requireMembership(db, userId, orgId)
+    await config.sessions.revokeRefreshCookie(db, request)
+    return config.sessions.issueTokensHttp(response, db, { id: userId, tenantId: orgId })
+  }
+
+  async function listOrgs(
+    db: DB,
+    userId: string,
+  ): Promise<{ orgs: readonly OrgMembershipDetail[] }> {
+    const rows = await db.execute(
+      sql`SELECT org_id, role FROM ${t} WHERE user_id = ${userId} ORDER BY joined_at`,
+    )
+
+    const orgIds = rows.map(r => r['org_id'] as string)
+    let orgNames: Map<string, string> | null = null
+    if (config.resolveOrgNames !== undefined && orgIds.length > 0) {
+      orgNames = await config.resolveOrgNames(db, orgIds)
+    }
+
+    const orgs: OrgMembershipDetail[] = rows.map(r => {
+      const orgId = r['org_id'] as string
+      return {
+        id: orgId,
+        name: orgNames?.get(orgId) ?? orgId,
+        role: (r['role'] as string | null) ?? null,
+      }
+    })
+
+    return { orgs }
+  }
+
+  async function addMember(
+    db: DB,
+    params: { userId: string; orgId: string; role?: string; addedBy?: string },
+  ): Promise<{ id: string }> {
+    assertUuid(params.orgId, 'orgId')
+    const role = params.role ?? null
+    const addedBy = params.addedBy ?? null
+    const rows = await db.execute(
+      sql`INSERT INTO ${t} (user_id, org_id, role, added_by)
+          VALUES (${params.userId}, ${params.orgId}, ${role}, ${addedBy})
+          ON CONFLICT (user_id, org_id) DO NOTHING
+          RETURNING id`,
+    )
+
+    if (rows.length === 0) {
+      throw new ConflictError('User is already a member of this organization.')
+    }
+
+    return { id: rows[0]!['id'] as string }
+  }
+
+  async function removeMember(
+    db: DB,
+    params: { userId: string; orgId: string },
+  ): Promise<void> {
+    assertUuid(params.orgId, 'orgId')
+    const rows = await db.execute(
+      sql`DELETE FROM ${t} WHERE user_id = ${params.userId} AND org_id = ${params.orgId} RETURNING id`,
+    )
+
+    if (rows.length === 0) {
+      throw new NotFoundError('Membership')
+    }
+
+    await config.sessions.bumpVersion(db, params.userId)
+  }
+
+  async function checkMembershipFn(
+    db: DB,
+    userId: string,
+    orgId: string,
+  ): Promise<OrgMembership | null> {
+    assertUuid(orgId, 'orgId')
+    const rows = await db.execute(
+      sql`SELECT id, org_id, role, joined_at FROM ${t} WHERE user_id = ${userId} AND org_id = ${orgId}`,
+    )
+
+    if (rows.length === 0) return null
+
+    const row = rows[0]!
+    return {
+      id: row['id'] as string,
+      orgId: row['org_id'] as string,
+      role: (row['role'] as string | null) ?? null,
+      joinedAt: new Date(row['joined_at'] as string),
+    }
+  }
+
+  return refuseScopedHandle({
+    resolveLogin,
+    selectOrg,
+    switchOrg,
+    listOrgs,
+    addMember,
+    removeMember,
+    checkMembership: checkMembershipFn,
+  }, 'multiOrg', 'a user\'s memberships span tenants')
+}

package/src/auth/auth/namespace.ts

@@ -0,0 +1,34 @@
+import { createSessions } from './sessions.js'
+import { createMultiOrgSessions } from './multi-org.js'
+import { createPasswords } from './passwords.js'
+import { createSignIn } from './sign-in.js'
+import { createGuard } from './guard.js'
+import { createEmailLinks } from './email-links.js'
+import { runAuthChain } from './chain.js'
+import { resolveCookieConfig, parseCookieHeader, buildSetCookieHeader, buildClearCookieHeader } from './cookie.js'
+
+/** Authentication namespace — session management, multi-org support, auth chain resolution. */
+export const auth = {
+  /** Creates a Sessions manager with JWT access/refresh tokens, rotation, and reuse detection. */
+  createSessions,
+  /** Creates multi-org session management — org selection, switching, membership CRUD. */
+  createMultiOrg: createMultiOrgSessions,
+  /** Hashes and verifies passwords with scrypt; reports when a stored hash needs rehashing. */
+  passwords: createPasswords,
+  /** Guarded password sign-in that slows, then refuses, repeated failures per account and per client. */
+  signIn: createSignIn,
+  /** Guards wrong guesses at a secret the app checks itself: counted per key set before the check, reset on a right answer, refused with retryAfterSeconds. */
+  guard: createGuard,
+  /** Emailed single-use links that prove control of an address: password reset and address verification; the token is never stored. */
+  emailLinks: createEmailLinks,
+  /** Executes an auth chain (strategy pipeline) to resolve auth + tenant from a request. */
+  runChain: runAuthChain,
+  /** Resolves CookieConfig with defaults for secure cookie-based token delivery. */
+  resolveCookie: resolveCookieConfig,
+  /** Parses a Cookie header string into key-value pairs. */
+  parseCookie: parseCookieHeader,
+  /** Builds a Set-Cookie header string from name, value, and CookieConfig. */
+  buildSetCookie: buildSetCookieHeader,
+  /** Builds a Set-Cookie header that clears (expires) a cookie. */
+  buildClearCookie: buildClearCookieHeader,
+}

package/src/auth/auth/parse-expiry.ts

@@ -0,0 +1,13 @@
+export function parseExpiry(exp: string): number {
+  const match = exp.match(/^(\d+)([smhd])$/)
+  if (!match) throw new Error(`Invalid expiry format: ${exp}`)
+  const value = parseInt(match[1]!, 10)
+  const unit = match[2]
+  switch (unit) {
+    case 's': return value
+    case 'm': return value * 60
+    case 'h': return value * 3600
+    case 'd': return value * 86400
+    default: return value
+  }
+}

package/src/auth/auth/passwords.ts

@@ -0,0 +1,110 @@
+import { scrypt, randomBytes, timingSafeEqual } from 'node:crypto'
+import { ValidationError } from '../../core/errors/index.js'
+import { getBaseLogger } from '../../core/logging/index.js'
+
+export interface ScryptParams {
+  /** log2 of the CPU/memory cost N. Default 15. */
+  readonly ln: number
+  /** Block size. Default 8. */
+  readonly r: number
+  /** Parallelism. Default 3. */
+  readonly p: number
+}
+
+export interface PasswordsConfig {
+  readonly scrypt?: Partial<ScryptParams>
+}
+
+export interface VerifyResult {
+  readonly ok: boolean
+  /** True when the password matched but the stored hash used other parameters than the configured ones. */
+  readonly needsRehash: boolean
+}
+
+export interface Passwords {
+  /** Returns a PHC string `$scrypt$ln=15,r=8,p=3$<salt>$<hash>` for the password. */
+  hash(password: string): Promise<string>
+  /** Checks a password against a stored hash in constant time. A malformed stored hash is `ok: false`. */
+  verify(stored: string, password: string): Promise<VerifyResult>
+  /** Spends the cost of a verify against a fixed dummy hash, for an account that does not exist. */
+  verifyNone(password: string): Promise<{ ok: false }>
+}
+
+const DEFAULTS: ScryptParams = { ln: 15, r: 8, p: 3 }
+const KEY_LENGTH = 32
+const SALT_LENGTH = 16
+const MAX_PASSWORD_BYTES = 4096
+const STORED_RE = /^\$scrypt\$ln=(\d+),r=(\d+),p=(\d+)\$([A-Za-z0-9+/]+)\$([A-Za-z0-9+/]+)$/
+
+function derive(password: string, salt: Buffer, params: ScryptParams, length: number): Promise<Buffer> {
+  const N = 2 ** params.ln
+  return new Promise((resolve, reject) => {
+    scrypt(password, salt, length, { N, r: params.r, p: params.p, maxmem: 256 * N * params.r + (1 << 20) }, (err, key) => {
+      if (err !== null) reject(err)
+      else resolve(key)
+    })
+  })
+}
+
+function normalize(password: string): string {
+  const normalized = password.normalize('NFC')
+  if (Buffer.byteLength(normalized, 'utf8') > MAX_PASSWORD_BYTES) {
+    throw new ValidationError({ password: [`must be at most ${MAX_PASSWORD_BYTES} bytes`] }, 'Password is too long.')
+  }
+  return normalized
+}
+
+function validParams(p: ScryptParams): boolean {
+  return Number.isInteger(p.ln) && p.ln >= 1 && p.ln <= 22
+    && Number.isInteger(p.r) && p.r >= 1 && p.r <= 32
+    && Number.isInteger(p.p) && p.p >= 1 && p.p <= 16
+}
+
+/**
+ * Creates the password hasher. Passwords are NFC-normalized and hashed with
+ * Node's scrypt (no dependency); there are no composition rules, and anything up
+ * to 4096 bytes of UTF-8 is accepted, so long passphrases and pasted passwords
+ * work. The hash records its own parameters, so raising `scrypt` later leaves old
+ * hashes verifiable and `verify` reports `needsRehash` for them.
+ *
+ * `verify` never throws on a bad stored string (it returns `ok: false` and logs),
+ * and `verifyNone` costs the same as a wrong password, so an unknown account is
+ * not distinguishable by timing.
+ */
+export function createPasswords(config: PasswordsConfig = {}): Passwords {
+  const params: ScryptParams = { ...DEFAULTS, ...config.scrypt }
+  if (!validParams(params)) {
+    throw new ValidationError('auth.passwords scrypt params must satisfy 1<=ln<=22, 1<=r<=32, 1<=p<=16.')
+  }
+  const encode = (b: Buffer): string => b.toString('base64').replace(/=+$/, '')
+  let dummy: Promise<string> | undefined
+
+  async function hash(password: string): Promise<string> {
+    const salt = randomBytes(SALT_LENGTH)
+    const key = await derive(normalize(password), salt, params, KEY_LENGTH)
+    return `$scrypt$ln=${params.ln},r=${params.r},p=${params.p}$${encode(salt)}$${encode(key)}`
+  }
+
+  async function verify(stored: string, password: string): Promise<VerifyResult> {
+    const m = STORED_RE.exec(stored)
+    const storedParams = m === null ? null : { ln: Number(m[1]), r: Number(m[2]), p: Number(m[3]) }
+    if (m === null || storedParams === null || !validParams(storedParams)) {
+      getBaseLogger().error({ event: 'password hash malformed' }, 'stored password hash is malformed')
+      return { ok: false, needsRehash: false }
+    }
+    const salt = Buffer.from(m[4]!, 'base64')
+    const expected = Buffer.from(m[5]!, 'base64')
+    const key = await derive(normalize(password), salt, storedParams, expected.length)
+    const ok = key.length === expected.length && timingSafeEqual(key, expected)
+    const needsRehash = ok && (storedParams.ln !== params.ln || storedParams.r !== params.r || storedParams.p !== params.p)
+    return { ok, needsRehash }
+  }
+
+  async function verifyNone(password: string): Promise<{ ok: false }> {
+    dummy ??= hash(randomBytes(16).toString('hex'))
+    await verify(await dummy, password)
+    return { ok: false }
+  }
+
+  return { hash, verify, verifyNone }
+}

package/src/auth/auth/schema.ts

@@ -0,0 +1,110 @@
+// Definitions for the tables behind `auth.createSessions` and
+// `auth.createMultiOrg`. Enabled with `sessions: {}` / `orgs: {}` in the
+// blueprint; `pipework generate` then emits them into the default database's
+// migrations. Emitted as IF NOT EXISTS so apps that created these tables by
+// hand from the former .sql files migrate cleanly.
+//
+// `user_id` is text everywhere: its format is the app's. `tenant_id` and
+// `org_id` are uuid so they can be the tenant id, but deliberately NOT
+// `.tenant()`: a refresh token is looked up by its hash before any tenant is
+// known, and a user's org list is read across orgs at sign-in, so tenant RLS on
+// either table would hide the rows the lookup needs.
+//
+// A custom `createMultiOrg({ table })` name is outside these definitions: the
+// app owns that table's DDL.
+
+import { define } from '../../data/domain/index.js'
+import { field } from '../../data/domain/field.js'
+import { sql } from '../../data/db/sql.js'
+import { index, unique } from '../../data/db/idx/index.js'
+
+export const AUTH_TABLE_NAMES: ReadonlySet<string> = new Set([
+  'pipework_refresh_tokens', 'pipework_auth_versions', 'pipework_user_orgs', 'pipework_signin_attempts', 'pipework_guard_attempts',
+  'pipework_email_links', 'pipework_email_link_requests',
+])
+
+export const refreshTokens = define('pipework_refresh_tokens', {
+  id: field.uuid().defaultRandom().primaryKey(),
+  userId: field.text(),
+  tenantId: field.uuid(),
+  tokenHash: field.text(),
+  familyId: field.uuid(),
+  revokedAt: field.timestamp().nullable(),
+  createdAt: field.timestamp().default('now'),
+  expiresAt: field.timestamp(),
+}, {
+  indexes: (t) => ({
+    byHash: index('idx_pipework_refresh_tokens_hash').on(t['tokenHash']),
+    byUser: index('idx_pipework_refresh_tokens_user').on(t['userId']).where(sql`revoked_at IS NULL`),
+    byFamily: index('idx_pipework_refresh_tokens_family').on(t['familyId']),
+  }),
+})
+
+export const authVersions = define('pipework_auth_versions', {
+  userId: field.text().primaryKey(),
+  version: field.integer().default(1),
+  updatedAt: field.timestamp().default('now'),
+})
+
+export const userOrgs = define('pipework_user_orgs', {
+  id: field.uuid().defaultRandom().primaryKey(),
+  userId: field.text(),
+  orgId: field.uuid(),
+  role: field.text().nullable(),
+  joinedAt: field.timestamp().default('now'),
+  addedBy: field.text().nullable(),
+}, {
+  indexes: (t) => ({
+    membership: unique('pipework_user_orgs_user_id_org_id_key').on(t['userId'], t['orgId']),
+    byUser: index('idx_pipework_user_orgs_user').on(t['userId']),
+    byOrg: index('idx_pipework_user_orgs_org').on(t['orgId']),
+  }),
+})
+
+// Behind `auth.signIn`. Not tenant-scoped: a sign-in happens before any tenant
+// is known. `key` is 'account:<sha256 of the account>' or 'client:<address>'.
+export const signinAttempts = define('pipework_signin_attempts', {
+  key: field.text().primaryKey(),
+  failures: field.integer().default(0),
+  firstFailureAt: field.timestamp().nullable(),
+  lastFailureAt: field.timestamp().nullable(),
+  lockedUntil: field.timestamp().nullable(),
+})
+
+// Behind `auth.guard`. Same shape as signinAttempts; `key` is
+// '<guard name>:<sha256 of the sorted key entries>'. Not tenant-scoped.
+export const guardAttempts = define('pipework_guard_attempts', {
+  key: field.text().primaryKey(),
+  failures: field.integer().default(0),
+  firstFailureAt: field.timestamp().nullable(),
+  lastFailureAt: field.timestamp().nullable(),
+  lockedUntil: field.timestamp().nullable(),
+})
+
+// Behind `auth.emailLinks`. Not tenant-scoped: a reset is asked for before any
+// tenant is known. The link's token is never stored: `token_hash` is its sha256,
+// and the token itself is an HMAC (keyed by the app's secret) of `id` and `nonce`.
+export const emailLinks = define('pipework_email_links', {
+  id: field.uuid().primaryKey(),
+  purpose: field.text(),
+  userId: field.text(),
+  address: field.text(),
+  tokenHash: field.text(),
+  nonce: field.text(),
+  createdAt: field.timestamp().default('now'),
+  expiresAt: field.timestamp(),
+  usedAt: field.timestamp().nullable(),
+  endedAt: field.timestamp().nullable(),
+}, {
+  indexes: (t) => ({
+    byHash: unique('pipework_email_links_token_hash_key').on(t['tokenHash']),
+    byUser: index('idx_pipework_email_links_user').on(t['userId'], t['purpose']),
+  }),
+})
+
+// Request counts behind `auth.emailLinks`; `key` is 'address:<sha256 of the address>' or 'client:<address>'.
+export const emailLinkRequests = define('pipework_email_link_requests', {
+  key: field.text().primaryKey(),
+  count: field.integer().default(0),
+  windowStart: field.timestamp().default('now'),
+})