@everystack/auth 0.2.5 → 0.3.0

package/src/postgres.ts

@@ -13,11 +13,12 @@
  */
 
 import { and, eq } from 'drizzle-orm';
+import { getTableConfig } from 'drizzle-orm/pg-core';
 import { createJwt } from './jwt';
 import { hmacNode } from './jwt/hmac-node';
 import type { RefreshTokenOptions } from './refresh';
 import type { AuthHandlers, AuthOptions, TokenPayload } from './index';
-import { getPasswordHash, withPassword } from './index';
+import { withPassword } from './index';
 import type { OAuthProvider } from './oauth';
 import { getRefreshFromCookies } from './cookies';
 import { authResponse, signoutResponse } from './response';
@@ -26,12 +27,27 @@ import { validateCsrfOrigin } from './csrf';
 
 const TOKEN_EXPIRY_SECONDS = 3600; // 1 hour
 
-/**
- * Dummy bcrypt hash for timing-safe user enumeration protection.
- * When a user is not found, we still run bcrypt against this hash
- * so response time is constant regardless of whether the email exists.
- */
-const DUMMY_BCRYPT_HASH = '$2a$10$abcdefghijklmnopqrstuuABCDEFGHIJKLMNOPQRSTUVWXYZ012345';
+// Postgres identifier rule — the only role name ever interpolated into SET LOCAL ROLE.
+const ROLE_NAME = /^[a-z_][a-z0-9_]*$/;
+
+/** Quote a Drizzle-derived SQL identifier (table/column) for safe interpolation. */
+function quoteIdent(name: string): string {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+    throw new Error(`Unsafe SQL identifier: ${name}`);
+  }
+  return `"${name}"`;
+}
+
+/** Schema-qualified, quoted table name from a Drizzle table (e.g. "auth"."users"). */
+function qualifiedTable(table: any): string {
+  const { schema, name } = getTableConfig(table);
+  return schema ? `${quoteIdent(schema)}.${quoteIdent(name)}` : quoteIdent(name);
+}
+
+/** postgres.js returns jsonb as an object or a string depending on the column path. */
+function parseJsonb(value: unknown): any {
+  return typeof value === 'string' ? JSON.parse(value) : value;
+}
 
 /**
  * Extract client IP and user agent from a request for refresh token metadata.
@@ -73,6 +89,88 @@ export function createPostgresAuthHandlers(
   const refreshTable = schema.refreshTokens;
   const jwtSecretString = new TextDecoder().decode(jwtSecret);
 
+  /**
+   * Run `fn` inside a transaction as `role`, with request.jwt.claims set for RLS.
+   * The single access primitive for the least-privilege path: SET LOCAL ROLE and
+   * set_config are transaction-scoped, so they reset when the transaction ends.
+   * `role` is validated (never user input) before interpolation.
+   */
+  async function withRole<T>(
+    role: string,
+    claims: Record<string, unknown> | null,
+    fn: (sql: any) => Promise<T>,
+  ): Promise<T> {
+    if (!ROLE_NAME.test(role)) {
+      throw new Error(`Invalid role name: ${role}`);
+    }
+    const claimsJson = JSON.stringify(claims ?? { role });
+    return pgSql.begin(async (sql: any) => {
+      await sql.unsafe(`SET LOCAL ROLE ${role}`);
+      await sql`SELECT set_config('request.jwt.claims', ${claimsJson}, true)`;
+      return fn(sql);
+    });
+  }
+
+  /**
+   * Read the public profile under the caller's role, using the column names from
+   * the app's own Drizzle schema so the handler stays schema-agnostic.
+   */
+  async function fetchProfileAsAnon(
+    sql: any,
+    id: string,
+  ): Promise<{ username?: string; displayName?: string } | undefined> {
+    const idCol = quoteIdent(profiles.id.name);
+    const usernameCol = quoteIdent(profiles.username.name);
+    const displayNameCol = quoteIdent(profiles.displayName.name);
+    const rows = await sql.unsafe(
+      `SELECT ${usernameCol} AS username, ${displayNameCol} AS "displayName" `
+        + `FROM ${qualifiedTable(profiles)} WHERE ${idCol} = $1 LIMIT 1`,
+      [id],
+    );
+    return rows[0];
+  }
+
+  /**
+   * Create the caller's own profile as the authenticated user — a plain INSERT,
+   * SECURITY INVOKER, gated by an RLS self-insert policy (WITH CHECK id = auth.uid()).
+   * No SECDEF, no trigger: profile creation is ordinary data access. Column names come
+   * from the app's own Drizzle schema so the handler stays schema-agnostic.
+   */
+  async function insertProfileSelf(
+    sql: any,
+    id: string,
+    data: { username: string; displayName: string },
+  ): Promise<void> {
+    const idCol = quoteIdent(profiles.id.name);
+    const usernameCol = quoteIdent(profiles.username.name);
+    const displayNameCol = quoteIdent(profiles.displayName.name);
+    await sql.unsafe(
+      `INSERT INTO ${qualifiedTable(profiles)} (${idCol}, ${usernameCol}, ${displayNameCol}) `
+        + `VALUES ($1, $2, $3)`,
+      [id, data.username, data.displayName],
+    );
+  }
+
+  /**
+   * Read the caller's own auth.users row (id, email, role) as the authenticated
+   * user — SECURITY INVOKER under RLS self-visibility (id = auth.uid()). No SECDEF:
+   * the caller has already proven they are `id`, and RLS gates the read.
+   */
+  async function fetchAuthUserSelf(
+    sql: any,
+    id: string,
+  ): Promise<{ id: string; email: string; role?: string } | undefined> {
+    const idCol = quoteIdent(users.id.name);
+    const emailCol = quoteIdent(users.email.name);
+    const roleCol = quoteIdent(users.role.name);
+    const rows = await sql.unsafe(
+      `SELECT ${idCol} AS id, ${emailCol} AS email, ${roleCol} AS role `
+        + `FROM ${qualifiedTable(users)} WHERE ${idCol} = $1 LIMIT 1`,
+      [id],
+    );
+    return rows[0];
+  }
+
   /**
    * Sign JWT via PostgreSQL pgcrypto hmac().
    * Requires GUC app.jwt_secret — uses pgSql.begin() for transaction-local setting.
@@ -100,22 +198,6 @@ export function createPostgresAuthHandlers(
     return rows[0].sign_jwt;
   }
 
-  /**
-   * Hash password via PostgreSQL pgcrypto crypt()/gen_salt('bf').
-   */
-  async function hashPasswordPg(password: string): Promise<string> {
-    const rows = await pgSql`SELECT auth.hash_password(${password}) as hash_password`;
-    return rows[0].hash_password;
-  }
-
-  /**
-   * Verify password via PostgreSQL pgcrypto crypt().
-   */
-  async function verifyPasswordPg(password: string, hash: string): Promise<boolean> {
-    const rows = await pgSql`SELECT auth.verify_password(${password}, ${hash}) as verify_password`;
-    return rows[0].verify_password;
-  }
-
   /**
    * Issue refresh token via PostgreSQL SECURITY DEFINER function.
    * Handles family ceiling, SHA-256 hashing, and token generation atomically.
@@ -140,33 +222,6 @@ export function createPostgresAuthHandlers(
     return { token: result.token, familyId: result.familyId };
   }
 
-  /**
-   * Validate and rotate refresh token via PostgreSQL.
-   * The SQL function handles SELECT FOR UPDATE, reuse detection, user state check.
-   */
-  async function validateRefreshTokenPg(
-    token: string,
-    deviceId?: string,
-    ipAddress?: string,
-    userAgent?: string,
-  ): Promise<{ userId: string; token: string; familyId: string }> {
-    const rows = await pgSql`SELECT auth.validate_refresh_token(
-      ${token},
-      ${deviceId ?? null}::uuid,
-      ${ipAddress ?? null},
-      ${userAgent ?? null}
-    ) as result`;
-    const result = typeof rows[0].result === 'string' ? JSON.parse(rows[0].result) : rows[0].result;
-    // token_reused returns as JSONB { error: 'token_reused' } instead of RAISE
-    // because PostgreSQL rolls back DELETEs when exceptions propagate.
-    if (result.error === 'token_reused') {
-      const err: any = new Error('token_reused');
-      err.code = 'P0002';
-      throw err;
-    }
-    return { userId: result.userId, token: result.token, familyId: result.familyId };
-  }
-
   /**
    * Revoke all refresh tokens for a user, optionally scoped by repository.
    */
@@ -182,7 +237,23 @@ export function createPostgresAuthHandlers(
     ttlSec: TOKEN_EXPIRY_SECONDS,
   });
 
-  return {
+  /**
+   * Mint the access JWT in JS (HS256), preserving app-level enrichClaims. Used by
+   * the least-privilege paths where the SQL minter auth.sign_jwt stays owner-only
+   * and the API runs as anon — so it can't call auth.sign_jwt.
+   */
+  async function signJwtJs(payload: Record<string, unknown>, request?: Request): Promise<string> {
+    let claims = payload;
+    if (options?.enrichClaims && request) {
+      const extra = await options.enrichClaims(claims, request);
+      if (extra && Object.keys(extra).length > 0) {
+        claims = { ...claims, ...extra };
+      }
+    }
+    return verifier.sign(claims);
+  }
+
+  const handlers: AuthHandlers = {
     verifyToken: async (token: string): Promise<TokenPayload | null> => {
       const claims = await verifier.verify(token);
       return (claims as TokenPayload | null) ?? null;
@@ -202,59 +273,79 @@ export function createPostgresAuthHandlers(
         );
       }
 
-      const existing = await db
-        .select()
-        .from(users)
-        .where(eq(users.email, email))
-        .limit(1);
-      if (existing.length > 0) {
-        if (options?.uniformSignupResponse) {
+      const meta = extractRequestMeta(request, options?.repositoryId);
+
+      // Least-privilege signup, in ONE transaction across two role contexts so the
+      // whole thing is atomic (a failed profile insert rolls back the new user — no
+      // orphaned auth.users row):
+      //   1. As `anon`, call the credential-gated SECDEF wrapper auth.sign_up_session —
+      //      the irreducible privileged step: it hashes the password, inserts auth.users
+      //      (raising email_exists on a duplicate), and issues the refresh token, all as
+      //      the definer. anon holds EXECUTE; the raw minters stay owner-only.
+      //   2. As the `authenticated` user it just created, INSERT the public profile —
+      //      a plain invoker write gated by RLS self-insert (WITH CHECK id = auth.uid()).
+      // The access JWT is minted in JS so enrichClaims is preserved.
+      const userMetaData = { username, displayName };
+      let session: { sub: string; email: string; role?: string; refresh_token: string };
+      try {
+        session = await pgSql.begin(async (sql: any) => {
+          await sql.unsafe('SET LOCAL ROLE anon');
+          await sql`SELECT set_config('request.jwt.claims', ${JSON.stringify({ role: 'anon' })}, true)`;
+          const rows = await sql`SELECT auth.sign_up_session(
+            ${email},
+            ${password},
+            ${JSON.stringify(userMetaData)}::jsonb,
+            ${meta.ipAddress ?? null},
+            ${meta.userAgent ?? null},
+            ${null}::uuid
+          ) as result`;
+          const s = parseJsonb(rows[0].result);
+
+          await sql.unsafe('SET LOCAL ROLE authenticated');
+          await sql`SELECT set_config('request.jwt.claims', ${JSON.stringify({ sub: s.sub, role: 'authenticated' })}, true)`;
+          await insertProfileSelf(sql, s.sub, { username, displayName });
+          return s;
+        });
+      } catch (err: any) {
+        if (err?.code === 'P0001') {
+          // email_exists — uniform response avoids leaking which emails are registered
+          if (options?.uniformSignupResponse) {
+            return Response.json(
+              { message: 'Check your email to continue.' },
+              { status: 200 },
+            );
+          }
           return Response.json(
-            { message: 'Check your email to continue.' },
-            { status: 200 },
+            { message: 'Email already registered' },
+            { status: 409 },
           );
         }
-        return Response.json(
-          { message: 'Email already registered' },
-          { status: 409 },
-        );
+        if (err?.code === '23505') {
+          // unique_violation — username already taken (the whole signup rolled back)
+          return Response.json(
+            { message: 'Username already taken' },
+            { status: 409 },
+          );
+        }
+        throw err;
       }
 
-      const hash = await hashPasswordPg(password);
-      const { user, profile } = await db.transaction(async (tx: any) => {
-        const [u] = await tx.insert(users).values(withPassword(users, { email }, hash)).returning();
-        const [p] = await tx.insert(profiles).values({ id: u.id, username, displayName }).returning();
-        return { user: u, profile: p };
-      });
-
-      const token = await signJwtPg({
-        sub: user.id,
-        email: user.email,
-        role: user.role ?? 'authenticated',
+      const token = await signJwtJs({
+        sub: session.sub,
+        email: session.email,
+        role: session.role ?? 'authenticated',
       }, enrichRequest);
 
-      const meta = extractRequestMeta(request, options?.repositoryId);
-      let refreshToken: string;
-      if (refreshTable) {
-        // Prefer PG function path when sql client is available
-        const result = await issueRefreshTokenPg(
-          user.id, meta.repositoryId, meta.ipAddress, meta.userAgent,
-        );
-        refreshToken = result.token;
-      } else {
-        refreshToken = await signJwtPg({ sub: user.id });
-      }
-
       return authResponse(
         {
           token,
-          refreshToken,
+          refreshToken: session.refresh_token,
           user: {
-            id: user.id,
-            email: user.email,
-            username: profile.username,
-            displayName: profile.displayName,
-            role: user.role ?? 'authenticated',
+            id: session.sub,
+            email: session.email,
+            username,
+            displayName,
+            role: session.role ?? 'authenticated',
           },
         },
         201,
@@ -276,63 +367,64 @@ export function createPostgresAuthHandlers(
         );
       }
 
-      const [user] = await db
-        .select()
-        .from(users)
-        .where(eq(users.email, email))
-        .limit(1);
-
-      if (!user) {
-        // Timing-safe: run bcrypt even when user doesn't exist
-        // so response time is constant regardless of email existence
-        await verifyPasswordPg(password, DUMMY_BCRYPT_HASH);
-        return Response.json(
-          { message: 'Invalid email or password' },
-          { status: 401 },
-        );
-      }
+      const meta = extractRequestMeta(request, options?.repositoryId);
 
-      const valid = await verifyPasswordPg(password, getPasswordHash(user)!);
-      if (!valid) {
-        return Response.json(
-          { message: 'Invalid email or password' },
-          { status: 401 },
-        );
+      // Least-privilege login: everything runs as `anon` over RLS. The credential-gated
+      // SECURITY DEFINER wrapper verifies the password (timing-safe — it runs bcrypt
+      // against a dummy hash for an unknown email) and issues the refresh token
+      // internally, so the raw minters (auth.sign_jwt, auth.issue_refresh_token) stay
+      // owner-only and never need a grant to anon. We read the public profile as anon and
+      // mint the access JWT here so app-level enrichClaims is preserved. The handler never
+      // touches auth.users directly.
+      let session: { sub: string; email: string; role?: string; refresh_token: string };
+      let profile: { username?: string; displayName?: string } | undefined;
+      try {
+        const out = await withRole('anon', { role: 'anon' }, async (sql: any) => {
+          const rows = await sql`SELECT auth.sign_in_session(
+            ${email},
+            ${password},
+            ${meta.ipAddress ?? null},
+            ${meta.userAgent ?? null},
+            ${null}::uuid
+          ) as result`;
+          const s = parseJsonb(rows[0].result);
+          const p = await fetchProfileAsAnon(sql, s.sub);
+          return { s, p };
+        });
+        session = out.s;
+        profile = out.p;
+      } catch (err: any) {
+        const code = err?.code;
+        if (code === 'P0001') {
+          // invalid_credentials — raised timing-safe inside auth.sign_in
+          return Response.json(
+            { message: 'Invalid email or password' },
+            { status: 401 },
+          );
+        }
+        if (code === 'P0006') {
+          // user_banned
+          return Response.json({ message: 'Account suspended' }, { status: 403 });
+        }
+        throw err;
       }
 
-      const [profile] = await db
-        .select()
-        .from(profiles)
-        .where(eq(profiles.id, user.id))
-        .limit(1);
-
-      const token = await signJwtPg({
-        sub: user.id,
-        email: user.email,
-        role: user.role ?? 'authenticated',
+      const token = await signJwtJs({
+        sub: session.sub,
+        email: session.email,
+        role: session.role ?? 'authenticated',
       }, enrichRequest);
 
-      const meta = extractRequestMeta(request, options?.repositoryId);
-      let refreshToken: string;
-      if (refreshTable) {
-        const result = await issueRefreshTokenPg(
-          user.id, meta.repositoryId, meta.ipAddress, meta.userAgent,
-        );
-        refreshToken = result.token;
-      } else {
-        refreshToken = await signJwtPg({ sub: user.id });
-      }
-
       return authResponse(
         {
           token,
-          refreshToken,
+          refreshToken: session.refresh_token,
           user: {
-            id: user.id,
-            email: user.email,
+            id: session.sub,
+            email: session.email,
             username: profile?.username,
             displayName: profile?.displayName,
-            role: user.role ?? 'authenticated',
+            role: session.role ?? 'authenticated',
           },
         },
         200,
@@ -363,31 +455,51 @@ export function createPostgresAuthHandlers(
       }
 
       if (refreshTable) {
-        // DB-backed rotation via PG SECURITY DEFINER functions (preferred)
+        // Least-privilege rotation. Two role contexts, no new SECDEF:
+        //  1. As `anon`, call auth.validate_refresh_token — the one legitimately
+        //     privileged step (SELECT FOR UPDATE + reuse detection + family revoke).
+        //     It is SECURITY DEFINER, EXECUTE-granted to anon; the refresh token is
+        //     the credential. token_reused comes back as JSONB (the family delete must
+        //     commit), not a RAISE.
+        //  2. As the `authenticated` user it just identified, read their OWN auth.users
+        //     row for email/role — SECURITY INVOKER, gated by RLS self-visibility
+        //     (id = auth.uid()). A row hidden by RLS (deleted/banned) yields no result.
         try {
           const meta = extractRequestMeta(request, options?.repositoryId);
-          const result = await validateRefreshTokenPg(
-            refreshToken, undefined, meta.ipAddress, meta.userAgent,
-          );
 
-          const [user] = await db
-            .select()
-            .from(users)
-            .where(eq(users.id, result.userId))
-            .limit(1);
+          const rotated = await withRole('anon', { role: 'anon' }, async (sql: any) => {
+            const rows = await sql`SELECT auth.validate_refresh_token(
+              ${refreshToken},
+              ${null}::uuid,
+              ${meta.ipAddress ?? null},
+              ${meta.userAgent ?? null}
+            ) as result`;
+            return parseJsonb(rows[0].result);
+          });
+          if (rotated?.error === 'token_reused') {
+            return Response.json(
+              { message: 'Invalid or expired refresh token' },
+              { status: 401 },
+            );
+          }
+
+          const user = await withRole(
+            'authenticated',
+            { sub: rotated.userId, role: 'authenticated' },
+            (sql: any) => fetchAuthUserSelf(sql, rotated.userId),
+          );
           if (!user) {
-            await revokeRefreshTokensPg(result.userId, options?.repositoryId);
             return Response.json({ message: 'User not found' }, { status: 401 });
           }
 
-          const token = await signJwtPg({
+          const token = await signJwtJs({
             sub: user.id,
             email: user.email,
             role: user.role ?? 'authenticated',
           }, request);
 
           return authResponse(
-            { token, refreshToken: result.token },
+            { token, refreshToken: rotated.token },
             200,
             options?.cookies,
           );
@@ -442,6 +554,32 @@ export function createPostgresAuthHandlers(
       }
     },
 
+    // ⚠️ NOT YET LEAST-PRIVILEGE — owner-connection path, deferred (see below).
+    //
+    // Unlike signin/signup/refresh, this handler still does its user lookups and
+    // creation directly on the Drizzle `db` connection (db.select / db.transaction)
+    // and mints tokens via signJwtPg / issueRefreshTokenPg. After the credential-split
+    // cutover (API runs as `authenticator`, no ambient table privileges) THIS WILL BREAK:
+    // those db reads/writes run with no SET ROLE and will be denied by RLS/grants.
+    //
+    // To convert it to the same model as signin/signup, it needs:
+    //   1. A new credential-gated SECDEF wrapper `auth.oauth_sign_in_session(provider,
+    //      provider_id, email, identity_data, ip, ua, device)` that wraps the existing
+    //      auth.oauth_sign_in (find/link/create user) + issues the refresh token
+    //      internally, returns { sub, email, role, isNewUser, refresh_token }, and is
+    //      GRANT EXECUTE'd to anon. (The OAuth token verified by provider.verify() is
+    //      the credential gate.)
+    //   2. Handler rewrite: provider.verify() in JS -> withRole('anon') over the wrapper
+    //      -> for isNewUser, INSERT the profile as withRole('authenticated', {sub})
+    //      (invoker, like signup) -> mint the access JWT in JS.
+    //   3. The app-custom `oauthCallbacks` path (findByProvider/createFromOAuth) and the
+    //      legacy identities/credentials path both run arbitrary JS on the owner
+    //      connection — they must either move behind the SECDEF wrapper or be documented
+    //      as requiring a privileged context. This is the main reason this is deferred:
+    //      it's not a clean single-wrapper swap.
+    // Deferred because the example app does not configure oauth, so this can't be
+    // verified end-to-end here; convert it with its own integration test. See memory
+    // secure-by-default-db.md "REMAINING" item 1.
     oauth: options?.oauth?.providers.length
       ? async (request: Request): Promise<Response> => {
           const csrfError = csrfCheck(request, options?.cookies);
@@ -752,4 +890,173 @@ export function createPostgresAuthHandlers(
       }
     },
   };
+
+  // Token-gated flows: run the SECDEF wrappers as `anon` over RLS. The one-time token
+  // is the credential; the token MINTING (auth.create_one_time_token) stays owner-only on
+  // the worker (see forgot-password / send-confirmation). These wrappers touch only
+  // auth.users. Always provided in postgres mode (the wrappers are part of the default auth
+  // schema); they take precedence over the generic owner-connection versions
+  // (addEmailPasswordFlows uses `??=`). Apps choose whether to route to them.
+  {
+    handlers.confirmEmail = async (request: Request): Promise<Response> => {
+      const csrfError = csrfCheck(request, options?.cookies);
+      if (csrfError) return csrfError;
+
+      let body: any;
+      try {
+        body = await request.json();
+      } catch {
+        return Response.json({ message: 'Invalid request body' }, { status: 400 });
+      }
+      if (!body?.token) {
+        return Response.json({ message: 'token is required' }, { status: 400 });
+      }
+
+      let result: any;
+      try {
+        result = await withRole('anon', { role: 'anon' }, async (sql: any) => {
+          const rows = await sql`SELECT auth.confirm_email(${body.token}) as result`;
+          return parseJsonb(rows[0].result);
+        });
+      } catch {
+        // Invalid/expired/consumed token — the wrapper raises (fails closed).
+        return Response.json({ message: 'Invalid or expired token' }, { status: 401 });
+      }
+
+      if (options.onEmailConfirmed && result?.userId) {
+        await options.onEmailConfirmed(result.userId);
+      }
+      return Response.json({ confirmed: true });
+    };
+
+    handlers.resetPassword = async (request: Request): Promise<Response> => {
+      const csrfError = csrfCheck(request, options?.cookies);
+      if (csrfError) return csrfError;
+
+      let body: any;
+      try {
+        body = await request.json();
+      } catch {
+        return Response.json({ message: 'Invalid request body' }, { status: 400 });
+      }
+      const { token, password } = body ?? {};
+      if (!token || !password) {
+        return Response.json(
+          { message: 'token and password are required' },
+          { status: 400 },
+        );
+      }
+
+      try {
+        // The wrapper verifies the recovery token, sets the new password, and revokes
+        // every refresh token for the user — all as the definer, in one statement.
+        await withRole('anon', { role: 'anon' }, async (sql: any) => {
+          await sql`SELECT auth.reset_password(${token}, ${password}) as result`;
+        });
+      } catch {
+        return Response.json({ message: 'Invalid or expired token' }, { status: 401 });
+      }
+
+      return Response.json({ reset: true });
+    };
+  }
+
+  // changePassword: authenticated self-service. Runs auth.change_password as the
+  // authenticated user (claims from the verified access token); the wrapper verifies the
+  // current password (reading the hash as the definer — authenticated may never) before
+  // setting the new one and revoking every session. No owner-connection access.
+  handlers.changePassword = async (request: Request): Promise<Response> => {
+    const csrfError = csrfCheck(request, options?.cookies);
+    if (csrfError) return csrfError;
+
+    const authHeader = request.headers.get('authorization');
+    if (!authHeader?.startsWith('Bearer ')) {
+      return Response.json({ message: 'Authentication required' }, { status: 401 });
+    }
+    const claims = await verifier.verify(authHeader.slice(7)) as TokenPayload | null;
+    if (!claims?.sub) {
+      return Response.json({ message: 'Invalid token' }, { status: 401 });
+    }
+
+    let body: any;
+    try {
+      body = await request.json();
+    } catch {
+      return Response.json({ message: 'Invalid request body' }, { status: 400 });
+    }
+    const { currentPassword, newPassword } = body ?? {};
+    if (!currentPassword || !newPassword) {
+      return Response.json(
+        { message: 'currentPassword and newPassword are required' },
+        { status: 400 },
+      );
+    }
+
+    try {
+      await withRole(
+        'authenticated',
+        { sub: claims.sub, role: (claims as any).role ?? 'authenticated' },
+        async (sql: any) => {
+          await sql`SELECT auth.change_password(${currentPassword}, ${newPassword}) as result`;
+        },
+      );
+    } catch (err: any) {
+      if (err?.code === 'P0001') {
+        // invalid_credentials / not_authenticated — current password wrong
+        return Response.json({ message: 'Current password is incorrect' }, { status: 401 });
+      }
+      throw err;
+    }
+
+    return Response.json({ changed: true });
+  };
+
+  // Least-privilege forgot-password: the API never reads the user table or mints a token
+  // (both owner-only). It enqueues; the privileged worker looks up the user, mints the
+  // recovery token, and sends the email. Always responds {sent:true} (no enumeration).
+  if (options?.onRecoveryRequested) {
+    handlers.forgotPassword = async (request: Request): Promise<Response> => {
+      const csrfError = csrfCheck(request, options?.cookies);
+      if (csrfError) return csrfError;
+
+      let body: any;
+      try {
+        body = await request.json();
+      } catch {
+        return Response.json({ message: 'Invalid request body' }, { status: 400 });
+      }
+      if (!body?.email) {
+        return Response.json({ message: 'email is required' }, { status: 400 });
+      }
+
+      try {
+        await options.onRecoveryRequested!(body.email);
+      } catch {
+        // Never reveal whether the email exists or the enqueue failed.
+      }
+      return Response.json({ sent: true });
+    };
+  }
+
+  // Least-privilege signup confirmation: on success, enqueue a confirmation job — the
+  // privileged worker mints the one-time token and sends the email. The API never mints.
+  if (options?.onConfirmationRequested) {
+    const baseSignup = handlers.signup;
+    handlers.signup = async (request: Request): Promise<Response> => {
+      const response = await baseSignup(request);
+      if (response.status === 201) {
+        try {
+          const body = await response.clone().json();
+          if (body?.user?.id && body?.user?.email) {
+            await options.onConfirmationRequested!({ id: body.user.id, email: body.user.email });
+          }
+        } catch {
+          // Don't fail signup if the confirmation enqueue fails.
+        }
+      }
+      return response;
+    };
+  }
+
+  return handlers;
 }