@pramen/auth 0.0.36 → 0.0.38

package/dist/index.d.ts

@@ -19,6 +19,9 @@ export declare const authSchema: {
         } & {
             readonly unique: true;
         };
+        emailVerified: {
+            readonly type: "integer";
+        };
         active: {
             readonly type: "boolean";
         } & {
@@ -34,17 +37,19 @@ export declare function verifyPassword(password: string, stored: string): Promis
 export declare function signToken(claims: Record<string, unknown>, secret: string, opts?: {
     ttlSeconds?: number;
 }): Promise<string>;
-/** signup / login / me. Roles are assigned server-side (default `["user"]`) — the
- * client never picks its own roles. Spread into your handler map. */
+/** signup / login / me / refreshSession. Roles are assigned server-side (default `["user"]`)
+ * — the client never picks its own roles. Spread into your handler map. */
 export declare const authHandlers: {
     signup: import("@pramen/server").Handler<{
         username: string;
         password: string;
+        email?: string;
     }, {
         token: string;
         user: {
             username: string;
             roles: string[];
+            email: string | null;
         };
     }>;
     login: import("@pramen/server").Handler<{
@@ -58,6 +63,13 @@ export declare const authHandlers: {
         };
     }>;
     me: import("@pramen/server").Handler<unknown, import("@pramen/server").Identity | null>;
+    refreshSession: import("@pramen/server").Handler<unknown, {
+        token: string;
+        user: {
+            username: string;
+            roles: string[];
+        };
+    }>;
 };
 export declare const magicLinkSchema: {
     auth_magic_links: import("@pramen/server").EntityDef<{
@@ -80,6 +92,33 @@ export declare const magicLinkSchema: {
         };
     }, Record<string, never>>;
 };
+export declare const emailTokenSchema: {
+    auth_email_tokens: import("@pramen/server").EntityDef<{
+        tokenHash: {
+            readonly type: "text";
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        purpose: {
+            readonly type: "text";
+        };
+        username: {
+            readonly type: "text";
+        };
+        email: {
+            readonly type: "text";
+        };
+        expiresAt: {
+            readonly type: "integer";
+        };
+        consumedAt: {
+            readonly type: "integer";
+        };
+        createdAt: {
+            readonly type: "integer";
+        };
+    }, Record<string, never>>;
+};
 export interface MagicLinkOptions {
     /** Deliver the link to the recipient. Receives the handler ctx and the raw token —
      * build the URL however your app routes it, e.g. `${ctx.env.APP_URL}/auth?token=${token}`.
@@ -148,8 +187,11 @@ export declare function createUserHandlers(opts?: {
         username: string;
         roles: string[];
     }, Record<string, unknown>>;
-    /** Admin: activate / deactivate a user. Deactivating blocks future logins (and
-     * token refresh); existing tokens still expire naturally within the TTL. */
+    /** Admin: activate / deactivate a user. Deactivating blocks future logins AND
+     * refreshSession, AND revokes OUTSTANDING tokens immediately via the KV denylist (the
+     * Worker fails them closed) — so revocation no longer waits out the token TTL. The
+     * denylist entry self-expires at the session TTL. Reactivating LIFTS the entry (it is
+     * username-scoped, so a stale entry would otherwise lock out even a fresh login). */
     setUserActive: import("@pramen/server").Handler<{
         username: string;
         active: boolean;
@@ -166,7 +208,9 @@ export declare function createUserHandlers(opts?: {
      * so a clash is reported as a clean 400 rather than surfacing the DB constraint as a 500. */
     changeEmail: import("@pramen/server").Handler<{
         email: string;
-    }, Record<string, unknown>>;
+    }, {
+        emailVerified: null;
+    }>;
     /** Self-service: change the caller's password. A credential op — it reads the
      * caller's OWN hash (passwordHash is never ACL-readable) to verify the current
      * password, then writes the new one. Self-scoped by the verified identity, so it
@@ -196,8 +240,11 @@ export declare const userHandlers: {
         username: string;
         roles: string[];
     }, Record<string, unknown>>;
-    /** Admin: activate / deactivate a user. Deactivating blocks future logins (and
-     * token refresh); existing tokens still expire naturally within the TTL. */
+    /** Admin: activate / deactivate a user. Deactivating blocks future logins AND
+     * refreshSession, AND revokes OUTSTANDING tokens immediately via the KV denylist (the
+     * Worker fails them closed) — so revocation no longer waits out the token TTL. The
+     * denylist entry self-expires at the session TTL. Reactivating LIFTS the entry (it is
+     * username-scoped, so a stale entry would otherwise lock out even a fresh login). */
     setUserActive: import("@pramen/server").Handler<{
         username: string;
         active: boolean;
@@ -214,7 +261,9 @@ export declare const userHandlers: {
      * so a clash is reported as a clean 400 rather than surfacing the DB constraint as a 500. */
     changeEmail: import("@pramen/server").Handler<{
         email: string;
-    }, Record<string, unknown>>;
+    }, {
+        emailVerified: null;
+    }>;
     /** Self-service: change the caller's password. A credential op — it reads the
      * caller's OWN hash (passwordHash is never ACL-readable) to verify the current
      * password, then writes the new one. Self-scoped by the verified identity, so it
@@ -253,3 +302,53 @@ export declare function authPolicies(opts?: {
     admin: Policy[];
     self: Policy[];
 };
+export interface PasswordResetOptions {
+    /** Deliver the reset link. Receives the ctx + `{ email, token, username }` — build the
+     * URL your app routes to, e.g. `${ctx.env.APP_URL}/reset?token=${token}`. Called from the
+     * `sendPasswordResetEmail` TASK (after commit), like magic-link's sendEmail. */
+    sendEmail: (ctx: HandlerContext, args: {
+        email: string;
+        token: string;
+        username: string;
+    }) => void | Promise<void>;
+    /** The users table to reset against (must have `username` PK + `passwordHash`/`email`).
+     * Default `auth_users`; pass your own authSchema-shaped table (as with createUserHandlers). */
+    table?: string;
+    /** How long the reset link stays valid, in seconds. Default 3600 (1h). */
+    linkTtlSeconds?: number;
+}
+/** Build the `requestPasswordReset` / `resetPassword` handler pair + the
+ * `sendPasswordResetEmail` task. Both handlers are ANONYMOUS — the emailed token is the
+ * capability. `requestPasswordReset` is enumeration-safe (always `{ ok: true }`, sends only
+ * when an active account matches the email); `resetPassword` redeems the single-use token
+ * and sets the new password. Spread `emailTokenSchema` into your schema and `.tasks` into
+ * your task map. */
+export declare function createPasswordReset(opts: PasswordResetOptions): {
+    handlers: HandlerMap;
+    tasks: AppTaskMap;
+};
+export interface EmailVerificationOptions {
+    /** Deliver the verification link. Receives the ctx + `{ email, token, username }` — build
+     * the URL your app routes to, e.g. `${ctx.env.APP_URL}/verify?token=${token}`. Called from
+     * the `sendVerificationEmail` TASK (after commit). */
+    sendEmail: (ctx: HandlerContext, args: {
+        email: string;
+        token: string;
+        username: string;
+    }) => void | Promise<void>;
+    /** The users table (must have `username` PK + `email`/`emailVerified`). Default `auth_users`. */
+    table?: string;
+    /** How long the verification link stays valid, in seconds. Default 86400 (24h). */
+    linkTtlSeconds?: number;
+}
+/** Build the `requestEmailVerification` / `verifyEmail` handler pair + the
+ * `sendVerificationEmail` task. `requestEmailVerification` is AUTHENTICATED (a caller
+ * verifies their OWN current email — runs right after signup, when the client already holds
+ * the session token); `verifyEmail` is ANONYMOUS (the token is the capability) and stamps
+ * `auth_users.emailVerified`. A token is bound to the address current at request time, so a
+ * later `changeEmail` invalidates it (verifyEmail rejects a token whose address no longer
+ * matches). Spread `emailTokenSchema` into your schema and `.tasks` into your task map. */
+export declare function createEmailVerification(opts: EmailVerificationOptions): {
+    handlers: HandlerMap;
+    tasks: AppTaskMap;
+};

package/dist/index.js

@@ -15,7 +15,7 @@
 // Passwordless magic-link login is also available via createMagicLinkAuth (spread
 // magicLinkSchema too). It is transport-agnostic: you supply sendEmail; pramen owns
 // the token lifecycle. See createMagicLinkAuth below.
-import { Entity, mutation, query, defaultTo, unique, hidden, policy, allow, $identity, BadRequest, Unauthorized } from "@pramen/server";
+import { Entity, mutation, query, defaultTo, unique, hidden, policy, allow, $identity, BadRequest, Unauthorized, denySession, allowSession } from "@pramen/server";
 // --- schema fragment: spread into your defineSchema so the table is migrated ---
 export const authSchema = {
     auth_users: Entity((t) => ({
@@ -23,6 +23,7 @@ export const authSchema = {
         passwordHash: hidden(t.text()), // never readable via the ORM; empty for passwordless users
         roles: t.json(), // string[]
         email: unique(t.text()), // mutable contact email (nullable, unique); the magic-link key
+        emailVerified: t.int(), // epoch ms the current `email` was confirmed; NULL = unverified (additive)
         active: defaultTo(t.bool(), true), // deactivation flag — false blocks login (additive, backfills 1)
         createdAt: t.int(),
     })),
@@ -124,16 +125,56 @@ function sessionTtlOf(ctx) {
     const v = Number(ctx.env.AUTH_SESSION_TTL_SECONDS);
     return Number.isFinite(v) && v > 0 ? Math.trunc(v) : TOKEN_TTL_SECONDS;
 }
+/** A permissive email shape check (one `@`, a dot in the domain). The single source of
+ * truth for `parseEmail` and the optional email at signup. */
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
 function parseCreds(raw) {
     const o = (raw ?? {});
     if (typeof o.username !== "string" || o.username.length === 0)
         throw new Error("username is required");
     if (typeof o.password !== "string" || o.password.length < 8)
         throw new Error("password must be at least 8 characters");
-    return { username: o.username, password: o.password };
+    // Optional contact email at signup — validated + normalized when present, so password
+    // reset and email verification work without a separate changeEmail round-trip. Absent ⇒
+    // the row's email stays NULL (still allowed; the user can set it later).
+    let email;
+    if (o.email !== undefined && o.email !== null && o.email !== "") {
+        const e = String(o.email).trim().toLowerCase();
+        if (!EMAIL_RE.test(e))
+            throw new Error("a valid email is required");
+        email = e;
+    }
+    return { username: o.username, password: o.password, email };
 }
-/** signup / login / me. Roles are assigned server-side (default `["user"]`) — the
- * client never picks its own roles. Spread into your handler map. */
+/** Build the `refreshSession` handler: an AUTHENTICATED mutation that re-reads the caller's
+ * `roles` + `active` from the users table (keyed on `username` = the JWT `sub`) and reissues a
+ * fresh token with the configured session TTL — the same `{ token, user }` shape as `login`.
+ * Throws Unauthorized if the row is gone or the account is deactivated (the `isActive` helper).
+ *
+ * Why it exists: the core is stateless verify-only, so roles/active are baked into a token at
+ * login. refreshSession lets a client (1) silently refresh at ~half-TTL, so AUTH_SESSION_TTL_SECONDS
+ * can be kept SHORT (bounded revocation lag) without logging the user out; and (2) pick up a role
+ * GRANT immediately — e.g. right after a subscription checkout flips the role — with no re-login.
+ * Shared by password users (`authHandlers`) and magic-link users (`createMagicLinkAuth`): both
+ * store the row in the same authSchema-shaped table keyed on the immutable `username`. `ttlOf`
+ * supplies each factory's own configured TTL. */
+function buildRefreshSession(ttlOf, table = "auth_users") {
+    return mutation(async (ctx) => {
+        const userId = requireUserId(ctx);
+        const rows = await ctx.db.exec(`SELECT username, roles, active FROM ${table} WHERE username = ? LIMIT 1`, userId);
+        const u = rows[0];
+        // Gone or deactivated ⇒ no fresh token (mirrors login). The Worker denylist already
+        // fails a deactivated user's outstanding token closed; this ensures refresh can't
+        // launder a revoked session into a new, longer-lived one either.
+        if (!u || !isActive(u.active))
+            throw new Unauthorized("session is no longer valid");
+        const roles = JSON.parse(String(u.roles));
+        const token = await signToken({ sub: String(u.username), roles }, secretOf(ctx), { ttlSeconds: ttlOf(ctx) });
+        return { token, user: { username: String(u.username), roles } };
+    }, { auth: "authenticated" });
+}
+/** signup / login / me / refreshSession. Roles are assigned server-side (default `["user"]`)
+ * — the client never picks its own roles. Spread into your handler map. */
 export const authHandlers = {
     // NOTE on username enumeration: signup returns a distinct "username is taken" error,
     // which is an enumeration oracle. This is INHERENT to systems where the username is a
@@ -151,11 +192,21 @@ export const authHandlers = {
             await hashPassword(input.password);
             throw new BadRequest("username is taken");
         }
+        // A supplied email must be free (the column is unique). Same clean-400 shape as
+        // changeEmail rather than surfacing the DB constraint as a 500.
+        if (input.email) {
+            const emailTaken = await ctx.db.exec("SELECT 1 FROM auth_users WHERE email = ? LIMIT 1", input.email);
+            if (emailTaken.length > 0)
+                throw new BadRequest("email already in use");
+        }
         const roles = DEFAULT_ROLES;
         const passwordHash = await hashPassword(input.password);
-        await ctx.db.exec("INSERT INTO auth_users (username, passwordHash, roles, createdAt) VALUES (?, ?, ?, ?)", input.username, passwordHash, JSON.stringify(roles), Date.now());
+        // Signup stores the email UNVERIFIED (emailVerified NULL). The app confirms it via
+        // createEmailVerification (requestEmailVerification runs right after signup — the
+        // client already holds the returned session token).
+        await ctx.db.exec("INSERT INTO auth_users (username, passwordHash, roles, email, createdAt) VALUES (?, ?, ?, ?, ?)", input.username, passwordHash, JSON.stringify(roles), input.email ?? null, Date.now());
         const token = await signToken({ sub: input.username, roles }, secretOf(ctx), { ttlSeconds: sessionTtlOf(ctx) });
-        return { token, user: { username: input.username, roles } };
+        return { token, user: { username: input.username, roles, email: input.email ?? null } };
     }, { input: parseCreds }),
     login: mutation(async (ctx, input) => {
         const rows = await ctx.db.exec("SELECT username, passwordHash, roles, active FROM auth_users WHERE username = ? LIMIT 1", input.username);
@@ -179,6 +230,10 @@ export const authHandlers = {
         return { token, user: { username: String(u.username), roles } };
     }, { input: parseCreds }),
     me: query((ctx) => ctx.identity),
+    // Re-read roles/active for the caller and reissue a token at the env-configured session
+    // TTL (AUTH_SESSION_TTL_SECONDS). Lets a short TTL bound revocation lag without logging
+    // the user out, and picks up role grants without re-login. See buildRefreshSession.
+    refreshSession: buildRefreshSession(sessionTtlOf),
 };
 // --- magic link (passwordless) login ---------------------------------------
 //
@@ -206,6 +261,23 @@ export const magicLinkSchema = {
         createdAt: t.int(),
     })),
 };
+// One-time email-token table shared by password reset AND email verification (spread it
+// once if you use EITHER `createPasswordReset` or `createEmailVerification`). Rows are
+// discriminated by `purpose` ("reset" | "verify"); only a SHA-256 hash of the token is
+// stored, so a DB leak never exposes a live token. `username` binds the token to the
+// account it acts on; `email` pins the address it was minted for (verification rejects a
+// token whose address the user has since changed).
+export const emailTokenSchema = {
+    auth_email_tokens: Entity((t) => ({
+        tokenHash: t.textId(), // PK = sha256(token)
+        purpose: t.text(), // "reset" | "verify"
+        username: t.text(), // the account (JWT sub) the token acts on
+        email: t.text(), // the address at mint time
+        expiresAt: t.int(), // epoch ms
+        consumedAt: t.int(), // epoch ms; NULL until redeemed (single-use)
+        createdAt: t.int(),
+    })),
+};
 async function sha256Hex(s) {
     const digest = await crypto.subtle.digest("SHA-256", enc(s));
     return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
@@ -217,7 +289,7 @@ function mintToken() {
 function parseEmail(raw) {
     const o = (raw ?? {});
     const email = typeof o.email === "string" ? o.email.trim().toLowerCase() : "";
-    if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email))
+    if (!EMAIL_RE.test(email))
         throw new BadRequest("a valid email is required");
     return { email };
 }
@@ -250,6 +322,10 @@ export function createMagicLinkAuth(opts) {
     const sessionTtl = opts.sessionTtlSeconds ?? TOKEN_TTL_SECONDS;
     const defaultRoles = opts.defaultRoles ?? DEFAULT_ROLES;
     const handlers = {
+        // Silent token refresh for magic-link users (same table, keyed on username). Reissues
+        // at this factory's configured session TTL. Shared implementation with authHandlers —
+        // when both are spread into one app, either definition serves either user.
+        refreshSession: buildRefreshSession(() => sessionTtl),
         /** Admin-only: create a passwordless user with the given roles (defaults if omitted)
          * and email them a fresh magic link. Idempotent — inviting an existing user just
          * resends the link and leaves their roles alone (admin uses setUserRoles for changes).
@@ -340,12 +416,19 @@ export function createMagicLinkAuth(opts) {
 // roles (admin manages everyone; the authenticated user manages only itself). Because
 // the admin read policy restricts `fields`, `passwordHash` is never projected back.
 //
-// Role/active changes are baked into the JWT at login, so setUserRoles / setUserActive
-// take effect on the user's NEXT login — not instantly. That lag is the cost of the
-// stateless, verify-only core (no session store, by design). Tune the revocation window
-// with the AUTH_SESSION_TTL_SECONDS env var (default 3600); for immediate revocation an
-// app can keep a per-user denylist in ctx.kv and check it in a route/middleware —
-// deliberately left to the app rather than building a session store into the core.
+// Roles are baked into the JWT at login, so the core is stateless verify-only. Two
+// mechanisms close the gap that leaves, without a session store:
+//  - `refreshSession` (authHandlers / createMagicLinkAuth): an authenticated caller
+//    re-reads roles/active and gets a fresh token. A client refreshing at ~half-TTL lets
+//    AUTH_SESSION_TTL_SECONDS (default 3600) stay short — bounding how long a stale
+//    setUserRoles/setUserActive lingers — and picks up a role GRANT immediately (no re-login).
+//  - KV denylist (HARD revocation, independent of TTL): setUserActive(false) and deleteUser
+//    write an `authDenied:<username>` entry via `denySession(ctx.kv, …)`; the core Worker
+//    checks `isSessionDenied` right after resolving identity and fails a revoked token closed
+//    (401) — so a deactivate/delete takes effect on the NEXT request, not the next login. The
+//    entry self-expires at the session TTL (the list never grows); reactivation lifts it
+//    (`allowSession`). `denySession`/`allowSession`/`isSessionDenied` are exported from
+//    @pramen/server so an app can revoke on its own compromise signals too.
 /** SQLite has no bool: `active` is stored 0/1 (NULL on a pre-column row = active). */
 function isActive(v) {
     return v == null || Number(v) !== 0;
@@ -394,8 +477,11 @@ export function createUserHandlers(opts = {}) {
                 throw new BadRequest("user not found"); // (or out of the caller's update scope)
             return updated;
         }),
-        /** Admin: activate / deactivate a user. Deactivating blocks future logins (and
-         * token refresh); existing tokens still expire naturally within the TTL. */
+        /** Admin: activate / deactivate a user. Deactivating blocks future logins AND
+         * refreshSession, AND revokes OUTSTANDING tokens immediately via the KV denylist (the
+         * Worker fails them closed) — so revocation no longer waits out the token TTL. The
+         * denylist entry self-expires at the session TTL. Reactivating LIFTS the entry (it is
+         * username-scoped, so a stale entry would otherwise lock out even a fresh login). */
         setUserActive: mutation(async (ctx, input) => {
             if (typeof input?.username !== "string" || input.username.length === 0)
                 throw new BadRequest("username is required");
@@ -407,6 +493,11 @@ export function createUserHandlers(opts = {}) {
             const updated = await usersDb(ctx).update(table, input.username, { active: input.active });
             if (!updated)
                 throw new BadRequest("user not found");
+            // KV is not part of the mutation's transaction — do it after the update succeeds.
+            if (input.active === false)
+                await denySession(ctx.kv, input.username, sessionTtlOf(ctx));
+            else
+                await allowSession(ctx.kv, input.username);
             return updated;
         }),
         /** Admin: permanently delete a user. ACL-gated by the admin delete policy; a caller
@@ -419,6 +510,8 @@ export function createUserHandlers(opts = {}) {
             const deleted = await usersDb(ctx).delete(table, input.username);
             if (!deleted)
                 throw new BadRequest("user not found");
+            // Revoke any outstanding tokens for the now-deleted user (self-expires at the TTL).
+            await denySession(ctx.kv, input.username, sessionTtlOf(ctx));
             return { ok: true };
         }),
         /** Self-service: change the caller's contact email. The ACL self policy scopes the
@@ -433,7 +526,13 @@ export function createUserHandlers(opts = {}) {
             const updated = await usersDb(ctx).update(table, userId, { email });
             if (!updated)
                 throw new Unauthorized("authentication required");
-            return updated;
+            // The new address is UNVERIFIED — clear any prior verification so `emailVerified`
+            // never claims an unconfirmed address. Raw (ACL-bypassing) but self-scoped by the
+            // verified identity, and it only ever CLEARS the flag (routing it through the self
+            // update policy would instead let a user set their own verified state). Any pending
+            // verify token for the old address is now dead (verifyEmail's current-email guard).
+            await ctx.db.exec(`UPDATE ${table} SET emailVerified = NULL WHERE username = ?`, userId);
+            return { ...updated, emailVerified: null };
         }),
         /** Self-service: change the caller's password. A credential op — it reads the
          * caller's OWN hash (passwordHash is never ACL-readable) to verify the current
@@ -460,9 +559,9 @@ export function createUserHandlers(opts = {}) {
  * `createUserHandlers()`; spread alongside `authHandlers`. */
 export const userHandlers = createUserHandlers();
 // Fields a self-service caller may see of their own row (never passwordHash/roles).
-const SELF_READ_FIELDS = ["username", "email", "active", "createdAt"];
+const SELF_READ_FIELDS = ["username", "email", "emailVerified", "active", "createdAt"];
 // Fields an admin may see of any user (never passwordHash).
-const ADMIN_READ_FIELDS = ["username", "roles", "email", "active", "createdAt"];
+const ADMIN_READ_FIELDS = ["username", "roles", "email", "emailVerified", "active", "createdAt"];
 /** ACL policy fragments that turn on the user-management handlers. Spread `admin`
  * into your admin role and `self` into your authenticated-user role:
  *
@@ -497,3 +596,138 @@ export function authPolicies(opts = {}) {
         ],
     };
 }
+// --- password reset + email verification -------------------------------------
+//
+// Two one-time-email-token flows, built on the same machinery as magic-link: mint a
+// random token, persist only its SHA-256 HASH + an expiry (in the shared
+// `auth_email_tokens` table, spread `emailTokenSchema`), email the raw token from a TASK
+// (off the mutation's storage transaction — a slow send can't hold the store lock), and
+// redeem it once. Both are transport-agnostic: you supply `sendEmail`; pramen owns the
+// token lifecycle. Wire the returned `tasks` into your app's task map, or the token is
+// written but the email never sends.
+const PURPOSE_RESET = "reset";
+const PURPOSE_VERIFY = "verify";
+/** Mint a one-time token for `username`, invalidate any prior pending token of the same
+ * purpose for that user (only the latest works), and persist its hash + expiry. Returns
+ * the raw token (the caller enqueues the send task with it). */
+async function issueEmailToken(ctx, purpose, username, email, expiresAt) {
+    const token = mintToken();
+    const tokenHash = await sha256Hex(token);
+    await ctx.db.exec("DELETE FROM auth_email_tokens WHERE purpose = ? AND username = ?", purpose, username);
+    await ctx.db.exec("INSERT INTO auth_email_tokens (tokenHash, purpose, username, email, expiresAt, createdAt) VALUES (?, ?, ?, ?, ?, ?)", tokenHash, purpose, username, email, expiresAt, Date.now());
+    return token;
+}
+/** Validate a token (right purpose, unexpired, unconsumed) and CONSUME it (single-use).
+ * Returns the account + address it was minted for. Throws Unauthorized on any failure —
+ * the same opaque error for missing / wrong-purpose / expired / already-used, so a caller
+ * learns nothing beyond "this token won't work". */
+async function redeemEmailToken(ctx, purpose, token) {
+    const tokenHash = await sha256Hex(token);
+    const rows = await ctx.db.exec("SELECT username, email, expiresAt, consumedAt FROM auth_email_tokens WHERE tokenHash = ? AND purpose = ? LIMIT 1", tokenHash, purpose);
+    const row = rows[0];
+    if (!row || row.consumedAt != null || Number(row.expiresAt) < Date.now())
+        throw new Unauthorized("invalid or expired token");
+    await ctx.db.exec("UPDATE auth_email_tokens SET consumedAt = ? WHERE tokenHash = ?", Date.now(), tokenHash);
+    return { username: String(row.username), email: String(row.email) };
+}
+/** Parse `{ token, newPassword }` for `resetPassword`. */
+function parseResetInput(raw) {
+    const o = (raw ?? {});
+    if (typeof o.token !== "string" || o.token.length === 0)
+        throw new BadRequest("token is required");
+    if (typeof o.newPassword !== "string" || o.newPassword.length < 8)
+        throw new BadRequest("newPassword must be at least 8 characters");
+    return { token: o.token, newPassword: o.newPassword };
+}
+/** Build the `requestPasswordReset` / `resetPassword` handler pair + the
+ * `sendPasswordResetEmail` task. Both handlers are ANONYMOUS — the emailed token is the
+ * capability. `requestPasswordReset` is enumeration-safe (always `{ ok: true }`, sends only
+ * when an active account matches the email); `resetPassword` redeems the single-use token
+ * and sets the new password. Spread `emailTokenSchema` into your schema and `.tasks` into
+ * your task map. */
+export function createPasswordReset(opts) {
+    const table = assertIdentifier(opts.table ?? "auth_users");
+    const linkTtlMs = (opts.linkTtlSeconds ?? 3600) * 1000;
+    const handlers = {
+        /** Anonymous: request a reset link for `email`. Resolves the address to an ACTIVE
+         * account and, only then, mints a token + enqueues the send — but the response is the
+         * same `{ ok: true }` whether or not any account matched (no enumeration). */
+        requestPasswordReset: mutation(async (ctx, input) => {
+            const rows = await ctx.db.exec(`SELECT username, active FROM ${table} WHERE email = ? LIMIT 1`, input.email);
+            const u = rows[0];
+            if (u && isActive(u.active)) {
+                const token = await issueEmailToken(ctx, PURPOSE_RESET, String(u.username), input.email, Date.now() + linkTtlMs);
+                await ctx.tasks.enqueue({ kind: "sendPasswordResetEmail", payload: { email: input.email, token, username: String(u.username) } });
+            }
+            return { ok: true };
+        }, { input: parseEmail }),
+        /** Anonymous: redeem a reset token and set the new password. Single-use (the token is
+         * consumed first). The account must still exist + be active. Any other pending reset
+         * tokens for the user are dropped on success. */
+        resetPassword: mutation(async (ctx, input) => {
+            const { username } = await redeemEmailToken(ctx, PURPOSE_RESET, input.token);
+            const rows = await ctx.db.exec(`SELECT active FROM ${table} WHERE username = ? LIMIT 1`, username);
+            if (!rows[0])
+                throw new Unauthorized("invalid or expired token");
+            if (!isActive(rows[0].active))
+                throw new Unauthorized("account is deactivated");
+            await ctx.db.exec(`UPDATE ${table} SET passwordHash = ? WHERE username = ?`, await hashPassword(input.newPassword), username);
+            await ctx.db.exec("DELETE FROM auth_email_tokens WHERE purpose = ? AND username = ?", PURPOSE_RESET, username);
+            return { ok: true };
+        }, { input: parseResetInput }),
+    };
+    const tasks = {
+        sendPasswordResetEmail: async (ctx, payload) => {
+            const p = payload;
+            await opts.sendEmail(ctx, p);
+        },
+    };
+    return { handlers, tasks };
+}
+/** Build the `requestEmailVerification` / `verifyEmail` handler pair + the
+ * `sendVerificationEmail` task. `requestEmailVerification` is AUTHENTICATED (a caller
+ * verifies their OWN current email — runs right after signup, when the client already holds
+ * the session token); `verifyEmail` is ANONYMOUS (the token is the capability) and stamps
+ * `auth_users.emailVerified`. A token is bound to the address current at request time, so a
+ * later `changeEmail` invalidates it (verifyEmail rejects a token whose address no longer
+ * matches). Spread `emailTokenSchema` into your schema and `.tasks` into your task map. */
+export function createEmailVerification(opts) {
+    const table = assertIdentifier(opts.table ?? "auth_users");
+    const linkTtlMs = (opts.linkTtlSeconds ?? 86_400) * 1000;
+    const handlers = {
+        /** Authenticated: email the caller a verification link for their CURRENT address. A
+         * no-op `{ ok: true, alreadyVerified: true }` if already verified; 400 if no email is set. */
+        requestEmailVerification: mutation(async (ctx) => {
+            const userId = requireUserId(ctx);
+            const rows = await ctx.db.exec(`SELECT email, emailVerified FROM ${table} WHERE username = ? LIMIT 1`, userId);
+            const u = rows[0];
+            const email = u && typeof u.email === "string" ? u.email : "";
+            if (!email)
+                throw new BadRequest("no email on file — set one with changeEmail first");
+            if (u.emailVerified != null)
+                return { ok: true, alreadyVerified: true };
+            const token = await issueEmailToken(ctx, PURPOSE_VERIFY, userId, email, Date.now() + linkTtlMs);
+            await ctx.tasks.enqueue({ kind: "sendVerificationEmail", payload: { email, token, username: userId } });
+            return { ok: true };
+        }, { auth: "authenticated" }),
+        /** Anonymous: redeem a verification token and mark the address verified. Guards that the
+         * account's CURRENT email still equals the address the token was minted for — a stale
+         * token (email changed since request) is rejected, never verifying the new address. */
+        verifyEmail: mutation(async (ctx, input) => {
+            const { username, email } = await redeemEmailToken(ctx, PURPOSE_VERIFY, input.token);
+            const rows = await ctx.db.exec(`SELECT email FROM ${table} WHERE username = ? LIMIT 1`, username);
+            const current = rows[0] && typeof rows[0].email === "string" ? String(rows[0].email) : null;
+            if (current == null || current !== email)
+                throw new Unauthorized("invalid or expired token");
+            await ctx.db.exec(`UPDATE ${table} SET emailVerified = ? WHERE username = ?`, Date.now(), username);
+            return { ok: true, email };
+        }, { input: parseLinkToken }),
+    };
+    const tasks = {
+        sendVerificationEmail: async (ctx, payload) => {
+            const p = payload;
+            await opts.sendEmail(ctx, p);
+        },
+    };
+    return { handlers, tasks };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/auth",
-  "version": "0.0.36",
+  "version": "0.0.38",
   "description": "Optional credential→JWT login for pramen — signup/login/me + PBKDF2 hashing, issuing HS256 tokens the pramen verifier accepts.",
   "license": "MIT",
   "repository": {
@@ -34,6 +34,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@pramen/server": "0.0.36"
+    "@pramen/server": "0.0.38"
   }
 }

package/src/index.ts

@@ -16,7 +16,7 @@
 // magicLinkSchema too). It is transport-agnostic: you supply sendEmail; pramen owns
 // the token lifecycle. See createMagicLinkAuth below.
 
-import { Entity, mutation, query, defaultTo, unique, hidden, policy, allow, $identity, BadRequest, Unauthorized } from "@pramen/server";
+import { Entity, mutation, query, defaultTo, unique, hidden, policy, allow, $identity, BadRequest, Unauthorized, denySession, allowSession } from "@pramen/server";
 import type { AppTaskMap, HandlerContext, HandlerMap, Policy } from "@pramen/server";
 
 // --- schema fragment: spread into your defineSchema so the table is migrated ---
@@ -27,6 +27,7 @@ export const authSchema = {
     passwordHash: hidden(t.text()), // never readable via the ORM; empty for passwordless users
     roles: t.json(), // string[]
     email: unique(t.text()), // mutable contact email (nullable, unique); the magic-link key
+    emailVerified: t.int(), // epoch ms the current `email` was confirmed; NULL = unverified (additive)
     active: defaultTo(t.bool(), true), // deactivation flag — false blocks login (additive, backfills 1)
     createdAt: t.int(),
   })),
@@ -148,15 +149,58 @@ function sessionTtlOf(ctx: HandlerContext): number {
   return Number.isFinite(v) && v > 0 ? Math.trunc(v) : TOKEN_TTL_SECONDS;
 }
 
-function parseCreds(raw: unknown): { username: string; password: string } {
+/** A permissive email shape check (one `@`, a dot in the domain). The single source of
+ * truth for `parseEmail` and the optional email at signup. */
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+
+function parseCreds(raw: unknown): { username: string; password: string; email?: string } {
   const o = (raw ?? {}) as Record<string, unknown>;
   if (typeof o.username !== "string" || o.username.length === 0) throw new Error("username is required");
   if (typeof o.password !== "string" || o.password.length < 8) throw new Error("password must be at least 8 characters");
-  return { username: o.username, password: o.password };
+  // Optional contact email at signup — validated + normalized when present, so password
+  // reset and email verification work without a separate changeEmail round-trip. Absent ⇒
+  // the row's email stays NULL (still allowed; the user can set it later).
+  let email: string | undefined;
+  if (o.email !== undefined && o.email !== null && o.email !== "") {
+    const e = String(o.email).trim().toLowerCase();
+    if (!EMAIL_RE.test(e)) throw new Error("a valid email is required");
+    email = e;
+  }
+  return { username: o.username, password: o.password, email };
 }
 
-/** signup / login / me. Roles are assigned server-side (default `["user"]`) — the
- * client never picks its own roles. Spread into your handler map. */
+/** Build the `refreshSession` handler: an AUTHENTICATED mutation that re-reads the caller's
+ * `roles` + `active` from the users table (keyed on `username` = the JWT `sub`) and reissues a
+ * fresh token with the configured session TTL — the same `{ token, user }` shape as `login`.
+ * Throws Unauthorized if the row is gone or the account is deactivated (the `isActive` helper).
+ *
+ * Why it exists: the core is stateless verify-only, so roles/active are baked into a token at
+ * login. refreshSession lets a client (1) silently refresh at ~half-TTL, so AUTH_SESSION_TTL_SECONDS
+ * can be kept SHORT (bounded revocation lag) without logging the user out; and (2) pick up a role
+ * GRANT immediately — e.g. right after a subscription checkout flips the role — with no re-login.
+ * Shared by password users (`authHandlers`) and magic-link users (`createMagicLinkAuth`): both
+ * store the row in the same authSchema-shaped table keyed on the immutable `username`. `ttlOf`
+ * supplies each factory's own configured TTL. */
+function buildRefreshSession(ttlOf: (ctx: HandlerContext) => number, table = "auth_users") {
+  return mutation(
+    async (ctx) => {
+      const userId = requireUserId(ctx);
+      const rows = await ctx.db.exec(`SELECT username, roles, active FROM ${table} WHERE username = ? LIMIT 1`, userId);
+      const u = rows[0];
+      // Gone or deactivated ⇒ no fresh token (mirrors login). The Worker denylist already
+      // fails a deactivated user's outstanding token closed; this ensures refresh can't
+      // launder a revoked session into a new, longer-lived one either.
+      if (!u || !isActive(u.active)) throw new Unauthorized("session is no longer valid");
+      const roles = JSON.parse(String(u.roles)) as string[];
+      const token = await signToken({ sub: String(u.username), roles }, secretOf(ctx), { ttlSeconds: ttlOf(ctx) });
+      return { token, user: { username: String(u.username), roles } };
+    },
+    { auth: "authenticated" },
+  );
+}
+
+/** signup / login / me / refreshSession. Roles are assigned server-side (default `["user"]`)
+ * — the client never picks its own roles. Spread into your handler map. */
 export const authHandlers = {
   // NOTE on username enumeration: signup returns a distinct "username is taken" error,
   // which is an enumeration oracle. This is INHERENT to systems where the username is a
@@ -167,7 +211,7 @@ export const authHandlers = {
   // The enumeration-SAFE flow is the passwordless / magic-link path (createMagicLinkAuth),
   // which keys on the email and always returns the same `{ ok: true }`.
   signup: mutation(
-    async (ctx, input: { username: string; password: string }) => {
+    async (ctx, input: { username: string; password: string; email?: string }) => {
       const existing = await ctx.db.exec("SELECT 1 FROM auth_users WHERE username = ? LIMIT 1", input.username);
       if (existing.length > 0) {
         // Equalize timing with the available path (which hashes below) so the taken vs.
@@ -175,17 +219,27 @@ export const authHandlers = {
         await hashPassword(input.password);
         throw new BadRequest("username is taken");
       }
+      // A supplied email must be free (the column is unique). Same clean-400 shape as
+      // changeEmail rather than surfacing the DB constraint as a 500.
+      if (input.email) {
+        const emailTaken = await ctx.db.exec("SELECT 1 FROM auth_users WHERE email = ? LIMIT 1", input.email);
+        if (emailTaken.length > 0) throw new BadRequest("email already in use");
+      }
       const roles = DEFAULT_ROLES;
       const passwordHash = await hashPassword(input.password);
+      // Signup stores the email UNVERIFIED (emailVerified NULL). The app confirms it via
+      // createEmailVerification (requestEmailVerification runs right after signup — the
+      // client already holds the returned session token).
       await ctx.db.exec(
-        "INSERT INTO auth_users (username, passwordHash, roles, createdAt) VALUES (?, ?, ?, ?)",
+        "INSERT INTO auth_users (username, passwordHash, roles, email, createdAt) VALUES (?, ?, ?, ?, ?)",
         input.username,
         passwordHash,
         JSON.stringify(roles),
+        input.email ?? null,
         Date.now(),
       );
       const token = await signToken({ sub: input.username, roles }, secretOf(ctx), { ttlSeconds: sessionTtlOf(ctx) });
-      return { token, user: { username: input.username, roles } };
+      return { token, user: { username: input.username, roles, email: input.email ?? null } };
     },
     { input: parseCreds },
   ),
@@ -218,6 +272,11 @@ export const authHandlers = {
   ),
 
   me: query((ctx) => ctx.identity),
+
+  // Re-read roles/active for the caller and reissue a token at the env-configured session
+  // TTL (AUTH_SESSION_TTL_SECONDS). Lets a short TTL bound revocation lag without logging
+  // the user out, and picks up role grants without re-login. See buildRefreshSession.
+  refreshSession: buildRefreshSession(sessionTtlOf),
 };
 
 // --- magic link (passwordless) login ---------------------------------------
@@ -248,6 +307,24 @@ export const magicLinkSchema = {
   })),
 };
 
+// One-time email-token table shared by password reset AND email verification (spread it
+// once if you use EITHER `createPasswordReset` or `createEmailVerification`). Rows are
+// discriminated by `purpose` ("reset" | "verify"); only a SHA-256 hash of the token is
+// stored, so a DB leak never exposes a live token. `username` binds the token to the
+// account it acts on; `email` pins the address it was minted for (verification rejects a
+// token whose address the user has since changed).
+export const emailTokenSchema = {
+  auth_email_tokens: Entity((t) => ({
+    tokenHash: t.textId(), // PK = sha256(token)
+    purpose: t.text(), // "reset" | "verify"
+    username: t.text(), // the account (JWT sub) the token acts on
+    email: t.text(), // the address at mint time
+    expiresAt: t.int(), // epoch ms
+    consumedAt: t.int(), // epoch ms; NULL until redeemed (single-use)
+    createdAt: t.int(),
+  })),
+};
+
 async function sha256Hex(s: string): Promise<string> {
   const digest = await crypto.subtle.digest("SHA-256", enc(s));
   return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
@@ -261,7 +338,7 @@ function mintToken(): string {
 function parseEmail(raw: unknown): { email: string } {
   const o = (raw ?? {}) as Record<string, unknown>;
   const email = typeof o.email === "string" ? o.email.trim().toLowerCase() : "";
-  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) throw new BadRequest("a valid email is required");
+  if (!EMAIL_RE.test(email)) throw new BadRequest("a valid email is required");
   return { email };
 }
 
@@ -315,6 +392,11 @@ export function createMagicLinkAuth(opts: MagicLinkOptions): { handlers: Handler
   const defaultRoles = opts.defaultRoles ?? DEFAULT_ROLES;
 
   const handlers: HandlerMap = {
+    // Silent token refresh for magic-link users (same table, keyed on username). Reissues
+    // at this factory's configured session TTL. Shared implementation with authHandlers —
+    // when both are spread into one app, either definition serves either user.
+    refreshSession: buildRefreshSession(() => sessionTtl),
+
     /** Admin-only: create a passwordless user with the given roles (defaults if omitted)
      * and email them a fresh magic link. Idempotent — inviting an existing user just
      * resends the link and leaves their roles alone (admin uses setUserRoles for changes).
@@ -447,12 +529,19 @@ export function createMagicLinkAuth(opts: MagicLinkOptions): { handlers: Handler
 // roles (admin manages everyone; the authenticated user manages only itself). Because
 // the admin read policy restricts `fields`, `passwordHash` is never projected back.
 //
-// Role/active changes are baked into the JWT at login, so setUserRoles / setUserActive
-// take effect on the user's NEXT login — not instantly. That lag is the cost of the
-// stateless, verify-only core (no session store, by design). Tune the revocation window
-// with the AUTH_SESSION_TTL_SECONDS env var (default 3600); for immediate revocation an
-// app can keep a per-user denylist in ctx.kv and check it in a route/middleware —
-// deliberately left to the app rather than building a session store into the core.
+// Roles are baked into the JWT at login, so the core is stateless verify-only. Two
+// mechanisms close the gap that leaves, without a session store:
+//  - `refreshSession` (authHandlers / createMagicLinkAuth): an authenticated caller
+//    re-reads roles/active and gets a fresh token. A client refreshing at ~half-TTL lets
+//    AUTH_SESSION_TTL_SECONDS (default 3600) stay short — bounding how long a stale
+//    setUserRoles/setUserActive lingers — and picks up a role GRANT immediately (no re-login).
+//  - KV denylist (HARD revocation, independent of TTL): setUserActive(false) and deleteUser
+//    write an `authDenied:<username>` entry via `denySession(ctx.kv, …)`; the core Worker
+//    checks `isSessionDenied` right after resolving identity and fails a revoked token closed
+//    (401) — so a deactivate/delete takes effect on the NEXT request, not the next login. The
+//    entry self-expires at the session TTL (the list never grows); reactivation lifts it
+//    (`allowSession`). `denySession`/`allowSession`/`isSessionDenied` are exported from
+//    @pramen/server so an app can revoke on its own compromise signals too.
 
 /** SQLite has no bool: `active` is stored 0/1 (NULL on a pre-column row = active). */
 function isActive(v: unknown): boolean {
@@ -511,8 +600,11 @@ export function createUserHandlers(opts: { table?: string } = {}) {
       return updated;
     }),
 
-    /** Admin: activate / deactivate a user. Deactivating blocks future logins (and
-     * token refresh); existing tokens still expire naturally within the TTL. */
+    /** Admin: activate / deactivate a user. Deactivating blocks future logins AND
+     * refreshSession, AND revokes OUTSTANDING tokens immediately via the KV denylist (the
+     * Worker fails them closed) — so revocation no longer waits out the token TTL. The
+     * denylist entry self-expires at the session TTL. Reactivating LIFTS the entry (it is
+     * username-scoped, so a stale entry would otherwise lock out even a fresh login). */
     setUserActive: mutation(async (ctx, input: { username: string; active: boolean }) => {
       if (typeof input?.username !== "string" || input.username.length === 0) throw new BadRequest("username is required");
       if (typeof input?.active !== "boolean") throw new BadRequest("active must be a boolean");
@@ -521,6 +613,9 @@ export function createUserHandlers(opts: { table?: string } = {}) {
       }
       const updated = await usersDb(ctx).update(table, input.username, { active: input.active });
       if (!updated) throw new BadRequest("user not found");
+      // KV is not part of the mutation's transaction — do it after the update succeeds.
+      if (input.active === false) await denySession(ctx.kv, input.username, sessionTtlOf(ctx));
+      else await allowSession(ctx.kv, input.username);
       return updated;
     }),
 
@@ -531,6 +626,8 @@ export function createUserHandlers(opts: { table?: string } = {}) {
       if (input.username === ctx.identity?.userId) throw new BadRequest("cannot delete your own account");
       const deleted = await usersDb(ctx).delete(table, input.username);
       if (!deleted) throw new BadRequest("user not found");
+      // Revoke any outstanding tokens for the now-deleted user (self-expires at the TTL).
+      await denySession(ctx.kv, input.username, sessionTtlOf(ctx));
       return { ok: true };
     }),
 
@@ -544,7 +641,13 @@ export function createUserHandlers(opts: { table?: string } = {}) {
       if (taken.length > 0) throw new BadRequest("email already in use");
       const updated = await usersDb(ctx).update(table, userId, { email });
       if (!updated) throw new Unauthorized("authentication required");
-      return updated;
+      // The new address is UNVERIFIED — clear any prior verification so `emailVerified`
+      // never claims an unconfirmed address. Raw (ACL-bypassing) but self-scoped by the
+      // verified identity, and it only ever CLEARS the flag (routing it through the self
+      // update policy would instead let a user set their own verified state). Any pending
+      // verify token for the old address is now dead (verifyEmail's current-email guard).
+      await ctx.db.exec(`UPDATE ${table} SET emailVerified = NULL WHERE username = ?`, userId);
+      return { ...updated, emailVerified: null };
     }),
 
     /** Self-service: change the caller's password. A credential op — it reads the
@@ -573,9 +676,9 @@ export function createUserHandlers(opts: { table?: string } = {}) {
 export const userHandlers = createUserHandlers();
 
 // Fields a self-service caller may see of their own row (never passwordHash/roles).
-const SELF_READ_FIELDS = ["username", "email", "active", "createdAt"];
+const SELF_READ_FIELDS = ["username", "email", "emailVerified", "active", "createdAt"];
 // Fields an admin may see of any user (never passwordHash).
-const ADMIN_READ_FIELDS = ["username", "roles", "email", "active", "createdAt"];
+const ADMIN_READ_FIELDS = ["username", "roles", "email", "emailVerified", "active", "createdAt"];
 
 /** ACL policy fragments that turn on the user-management handlers. Spread `admin`
  * into your admin role and `self` into your authenticated-user role:
@@ -619,3 +722,192 @@ export function authPolicies(opts: {
     ],
   };
 }
+
+// --- password reset + email verification -------------------------------------
+//
+// Two one-time-email-token flows, built on the same machinery as magic-link: mint a
+// random token, persist only its SHA-256 HASH + an expiry (in the shared
+// `auth_email_tokens` table, spread `emailTokenSchema`), email the raw token from a TASK
+// (off the mutation's storage transaction — a slow send can't hold the store lock), and
+// redeem it once. Both are transport-agnostic: you supply `sendEmail`; pramen owns the
+// token lifecycle. Wire the returned `tasks` into your app's task map, or the token is
+// written but the email never sends.
+
+const PURPOSE_RESET = "reset";
+const PURPOSE_VERIFY = "verify";
+
+/** Mint a one-time token for `username`, invalidate any prior pending token of the same
+ * purpose for that user (only the latest works), and persist its hash + expiry. Returns
+ * the raw token (the caller enqueues the send task with it). */
+async function issueEmailToken(ctx: HandlerContext, purpose: string, username: string, email: string, expiresAt: number): Promise<string> {
+  const token = mintToken();
+  const tokenHash = await sha256Hex(token);
+  await ctx.db.exec("DELETE FROM auth_email_tokens WHERE purpose = ? AND username = ?", purpose, username);
+  await ctx.db.exec(
+    "INSERT INTO auth_email_tokens (tokenHash, purpose, username, email, expiresAt, createdAt) VALUES (?, ?, ?, ?, ?, ?)",
+    tokenHash,
+    purpose,
+    username,
+    email,
+    expiresAt,
+    Date.now(),
+  );
+  return token;
+}
+
+/** Validate a token (right purpose, unexpired, unconsumed) and CONSUME it (single-use).
+ * Returns the account + address it was minted for. Throws Unauthorized on any failure —
+ * the same opaque error for missing / wrong-purpose / expired / already-used, so a caller
+ * learns nothing beyond "this token won't work". */
+async function redeemEmailToken(ctx: HandlerContext, purpose: string, token: string): Promise<{ username: string; email: string }> {
+  const tokenHash = await sha256Hex(token);
+  const rows = await ctx.db.exec(
+    "SELECT username, email, expiresAt, consumedAt FROM auth_email_tokens WHERE tokenHash = ? AND purpose = ? LIMIT 1",
+    tokenHash,
+    purpose,
+  );
+  const row = rows[0];
+  if (!row || row.consumedAt != null || Number(row.expiresAt) < Date.now()) throw new Unauthorized("invalid or expired token");
+  await ctx.db.exec("UPDATE auth_email_tokens SET consumedAt = ? WHERE tokenHash = ?", Date.now(), tokenHash);
+  return { username: String(row.username), email: String(row.email) };
+}
+
+/** Parse `{ token, newPassword }` for `resetPassword`. */
+function parseResetInput(raw: unknown): { token: string; newPassword: string } {
+  const o = (raw ?? {}) as Record<string, unknown>;
+  if (typeof o.token !== "string" || o.token.length === 0) throw new BadRequest("token is required");
+  if (typeof o.newPassword !== "string" || o.newPassword.length < 8) throw new BadRequest("newPassword must be at least 8 characters");
+  return { token: o.token, newPassword: o.newPassword };
+}
+
+export interface PasswordResetOptions {
+  /** Deliver the reset link. Receives the ctx + `{ email, token, username }` — build the
+   * URL your app routes to, e.g. `${ctx.env.APP_URL}/reset?token=${token}`. Called from the
+   * `sendPasswordResetEmail` TASK (after commit), like magic-link's sendEmail. */
+  sendEmail: (ctx: HandlerContext, args: { email: string; token: string; username: string }) => void | Promise<void>;
+  /** The users table to reset against (must have `username` PK + `passwordHash`/`email`).
+   * Default `auth_users`; pass your own authSchema-shaped table (as with createUserHandlers). */
+  table?: string;
+  /** How long the reset link stays valid, in seconds. Default 3600 (1h). */
+  linkTtlSeconds?: number;
+}
+
+/** Build the `requestPasswordReset` / `resetPassword` handler pair + the
+ * `sendPasswordResetEmail` task. Both handlers are ANONYMOUS — the emailed token is the
+ * capability. `requestPasswordReset` is enumeration-safe (always `{ ok: true }`, sends only
+ * when an active account matches the email); `resetPassword` redeems the single-use token
+ * and sets the new password. Spread `emailTokenSchema` into your schema and `.tasks` into
+ * your task map. */
+export function createPasswordReset(opts: PasswordResetOptions): { handlers: HandlerMap; tasks: AppTaskMap } {
+  const table = assertIdentifier(opts.table ?? "auth_users");
+  const linkTtlMs = (opts.linkTtlSeconds ?? 3600) * 1000;
+
+  const handlers: HandlerMap = {
+    /** Anonymous: request a reset link for `email`. Resolves the address to an ACTIVE
+     * account and, only then, mints a token + enqueues the send — but the response is the
+     * same `{ ok: true }` whether or not any account matched (no enumeration). */
+    requestPasswordReset: mutation(
+      async (ctx, input: { email: string }) => {
+        const rows = await ctx.db.exec(`SELECT username, active FROM ${table} WHERE email = ? LIMIT 1`, input.email);
+        const u = rows[0];
+        if (u && isActive(u.active)) {
+          const token = await issueEmailToken(ctx, PURPOSE_RESET, String(u.username), input.email, Date.now() + linkTtlMs);
+          await ctx.tasks.enqueue({ kind: "sendPasswordResetEmail", payload: { email: input.email, token, username: String(u.username) } });
+        }
+        return { ok: true };
+      },
+      { input: parseEmail },
+    ),
+
+    /** Anonymous: redeem a reset token and set the new password. Single-use (the token is
+     * consumed first). The account must still exist + be active. Any other pending reset
+     * tokens for the user are dropped on success. */
+    resetPassword: mutation(
+      async (ctx, input: { token: string; newPassword: string }) => {
+        const { username } = await redeemEmailToken(ctx, PURPOSE_RESET, input.token);
+        const rows = await ctx.db.exec(`SELECT active FROM ${table} WHERE username = ? LIMIT 1`, username);
+        if (!rows[0]) throw new Unauthorized("invalid or expired token");
+        if (!isActive(rows[0].active)) throw new Unauthorized("account is deactivated");
+        await ctx.db.exec(`UPDATE ${table} SET passwordHash = ? WHERE username = ?`, await hashPassword(input.newPassword), username);
+        await ctx.db.exec("DELETE FROM auth_email_tokens WHERE purpose = ? AND username = ?", PURPOSE_RESET, username);
+        return { ok: true };
+      },
+      { input: parseResetInput },
+    ),
+  };
+
+  const tasks: AppTaskMap = {
+    sendPasswordResetEmail: async (ctx, payload) => {
+      const p = payload as { email: string; token: string; username: string };
+      await opts.sendEmail(ctx, p);
+    },
+  };
+
+  return { handlers, tasks };
+}
+
+export interface EmailVerificationOptions {
+  /** Deliver the verification link. Receives the ctx + `{ email, token, username }` — build
+   * the URL your app routes to, e.g. `${ctx.env.APP_URL}/verify?token=${token}`. Called from
+   * the `sendVerificationEmail` TASK (after commit). */
+  sendEmail: (ctx: HandlerContext, args: { email: string; token: string; username: string }) => void | Promise<void>;
+  /** The users table (must have `username` PK + `email`/`emailVerified`). Default `auth_users`. */
+  table?: string;
+  /** How long the verification link stays valid, in seconds. Default 86400 (24h). */
+  linkTtlSeconds?: number;
+}
+
+/** Build the `requestEmailVerification` / `verifyEmail` handler pair + the
+ * `sendVerificationEmail` task. `requestEmailVerification` is AUTHENTICATED (a caller
+ * verifies their OWN current email — runs right after signup, when the client already holds
+ * the session token); `verifyEmail` is ANONYMOUS (the token is the capability) and stamps
+ * `auth_users.emailVerified`. A token is bound to the address current at request time, so a
+ * later `changeEmail` invalidates it (verifyEmail rejects a token whose address no longer
+ * matches). Spread `emailTokenSchema` into your schema and `.tasks` into your task map. */
+export function createEmailVerification(opts: EmailVerificationOptions): { handlers: HandlerMap; tasks: AppTaskMap } {
+  const table = assertIdentifier(opts.table ?? "auth_users");
+  const linkTtlMs = (opts.linkTtlSeconds ?? 86_400) * 1000;
+
+  const handlers: HandlerMap = {
+    /** Authenticated: email the caller a verification link for their CURRENT address. A
+     * no-op `{ ok: true, alreadyVerified: true }` if already verified; 400 if no email is set. */
+    requestEmailVerification: mutation(
+      async (ctx) => {
+        const userId = requireUserId(ctx);
+        const rows = await ctx.db.exec(`SELECT email, emailVerified FROM ${table} WHERE username = ? LIMIT 1`, userId);
+        const u = rows[0];
+        const email = u && typeof u.email === "string" ? u.email : "";
+        if (!email) throw new BadRequest("no email on file — set one with changeEmail first");
+        if (u.emailVerified != null) return { ok: true, alreadyVerified: true };
+        const token = await issueEmailToken(ctx, PURPOSE_VERIFY, userId, email, Date.now() + linkTtlMs);
+        await ctx.tasks.enqueue({ kind: "sendVerificationEmail", payload: { email, token, username: userId } });
+        return { ok: true };
+      },
+      { auth: "authenticated" },
+    ),
+
+    /** Anonymous: redeem a verification token and mark the address verified. Guards that the
+     * account's CURRENT email still equals the address the token was minted for — a stale
+     * token (email changed since request) is rejected, never verifying the new address. */
+    verifyEmail: mutation(
+      async (ctx, input: { token: string }) => {
+        const { username, email } = await redeemEmailToken(ctx, PURPOSE_VERIFY, input.token);
+        const rows = await ctx.db.exec(`SELECT email FROM ${table} WHERE username = ? LIMIT 1`, username);
+        const current = rows[0] && typeof rows[0].email === "string" ? String(rows[0].email) : null;
+        if (current == null || current !== email) throw new Unauthorized("invalid or expired token");
+        await ctx.db.exec(`UPDATE ${table} SET emailVerified = ? WHERE username = ?`, Date.now(), username);
+        return { ok: true, email };
+      },
+      { input: parseLinkToken },
+    ),
+  };
+
+  const tasks: AppTaskMap = {
+    sendVerificationEmail: async (ctx, payload) => {
+      const p = payload as { email: string; token: string; username: string };
+      await opts.sendEmail(ctx, p);
+    },
+  };
+
+  return { handlers, tasks };
+}