@pramen/auth 0.0.37 → 0.0.39

package/dist/index.d.ts

@@ -33,12 +33,22 @@ export declare const authSchema: {
     }, Record<string, never>>;
 };
 export declare function hashPassword(password: string): Promise<string>;
+/** Verify `password` against a foreign hash `payload` (the stored value with its
+ * `<scheme>$` prefix already stripped). May be sync or async; throwing counts as a
+ * failed verification, never a 500. */
+export type PasswordVerifier = (password: string, payload: string) => boolean | Promise<boolean>;
+/** Register a verifier for an imported hash scheme. Call once at module scope, before
+ * any login can run. `pbkdf2` is built in and cannot be overridden. */
+export declare function registerPasswordVerifier(scheme: string, verify: PasswordVerifier): void;
+/** True if `stored` is a foreign (non-PBKDF2) hash, i.e. one that login should upgrade
+ * after a successful verify. Also true for an unparseable value, which never verifies. */
+export declare function isForeignHash(stored: string): boolean;
 export declare function verifyPassword(password: string, stored: string): Promise<boolean>;
 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;
@@ -63,6 +73,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<{
@@ -180,8 +197,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;
@@ -230,8 +250,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;

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) => ({
@@ -84,7 +84,38 @@ function parseStoredHash(stored) {
     const hash = algSeg === "sha512" ? "SHA-512" : "SHA-256";
     return { iterations, hash, saltB64, hashB64 };
 }
+const foreignVerifiers = new Map();
+/** Register a verifier for an imported hash scheme. Call once at module scope, before
+ * any login can run. `pbkdf2` is built in and cannot be overridden. */
+export function registerPasswordVerifier(scheme, verify) {
+    if (!scheme || scheme.includes("$"))
+        throw new Error(`invalid hash scheme '${scheme}' (must be non-empty and contain no '$')`);
+    if (scheme === "pbkdf2")
+        throw new Error("'pbkdf2' is built in and cannot be overridden");
+    foreignVerifiers.set(scheme, verify);
+}
+/** True if `stored` is a foreign (non-PBKDF2) hash, i.e. one that login should upgrade
+ * after a successful verify. Also true for an unparseable value, which never verifies. */
+export function isForeignHash(stored) {
+    return stored.split("$")[0] !== "pbkdf2";
+}
 export async function verifyPassword(password, stored) {
+    const scheme = stored.split("$")[0];
+    if (scheme !== "pbkdf2") {
+        const verify = foreignVerifiers.get(scheme);
+        // Unknown scheme (including the empty passwordHash of a passwordless user) never
+        // verifies — same as before this feature existed.
+        if (!verify)
+            return false;
+        try {
+            return await verify(password, stored.slice(scheme.length + 1));
+        }
+        catch {
+            // A broken/garbage payload must fail closed, not surface as a 500 that
+            // distinguishes it from a wrong password.
+            return false;
+        }
+    }
     const parsed = parseStoredHash(stored);
     if (!parsed)
         return false;
@@ -146,8 +177,35 @@ function parseCreds(raw) {
     }
     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
@@ -198,11 +256,28 @@ export const authHandlers = {
         // deactivated user gets no new token. Existing tokens expire within the TTL.
         if (!isActive(u.active))
             throw new Unauthorized("account is deactivated");
+        // Upgrade an imported foreign hash (see registerPasswordVerifier). This is the one
+        // moment the plaintext is in hand for a user whose hash predates pramen, so rehash
+        // to PBKDF2 and drop the old scheme. Deliberately AFTER the active check, so a
+        // deactivated account is never rewritten. Best-effort: a failed upgrade must not
+        // fail an otherwise valid login — the row simply upgrades on a later attempt.
+        if (isForeignHash(String(u.passwordHash))) {
+            try {
+                await ctx.db.exec("UPDATE auth_users SET passwordHash = ? WHERE username = ?", await hashPassword(input.password), String(u.username));
+            }
+            catch {
+                /* keep the legacy hash; the next login retries */
+            }
+        }
         const roles = JSON.parse(String(u.roles));
         const token = await signToken({ sub: String(u.username), roles }, secretOf(ctx), { ttlSeconds: sessionTtlOf(ctx) });
         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 ---------------------------------------
 //
@@ -291,6 +366,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).
@@ -381,12 +460,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;
@@ -435,8 +521,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");
@@ -448,6 +537,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
@@ -460,6 +554,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/auth",
-  "version": "0.0.37",
+  "version": "0.0.39",
   "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.37"
+    "@pramen/server": "0.0.39"
   }
 }

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 ---
@@ -94,7 +94,64 @@ function parseStoredHash(stored: string): { iterations: number; hash: string; sa
   return { iterations, hash, saltB64, hashB64 };
 }
 
+// --- foreign hash schemes (opt-in, for migrating in from another system) -----
+//
+// Importing users from an existing app means importing hashes that are NOT PBKDF2 —
+// bcrypt from Contember/Rails, `pbkdf2_sha256$` from Django, and so on. Those cannot be
+// converted (that needs the plaintext), so the only alternative would be forcing every
+// user to reset their password.
+//
+// Instead: store the foreign hash under its own scheme prefix (`bcrypt$<payload>`),
+// register a verifier for that scheme, and let login UPGRADE it. On the one successful
+// login where the plaintext is briefly in hand, the row is rehashed to PBKDF2. The
+// scheme deletes itself as users return; nothing has to be migrated ahead of time.
+//
+// pramen deliberately does NOT bundle an implementation. bcrypt needs a pure-JS library
+// (WebCrypto has none) which is real bundle weight, and it is useless to the apps that
+// never import anything — so the app supplies it:
+//
+//   import bcrypt from "bcryptjs";
+//   registerPasswordVerifier("bcrypt", (password, payload) => bcrypt.compare(password, payload));
+//
+// then import rows with `passwordHash = "bcrypt$" + row.password_hash` (a bcrypt hash is
+// itself `$2b$10$...`, so the stored value reads `bcrypt$$2b$10$...`).
+
+/** Verify `password` against a foreign hash `payload` (the stored value with its
+ * `<scheme>$` prefix already stripped). May be sync or async; throwing counts as a
+ * failed verification, never a 500. */
+export type PasswordVerifier = (password: string, payload: string) => boolean | Promise<boolean>;
+
+const foreignVerifiers = new Map<string, PasswordVerifier>();
+
+/** Register a verifier for an imported hash scheme. Call once at module scope, before
+ * any login can run. `pbkdf2` is built in and cannot be overridden. */
+export function registerPasswordVerifier(scheme: string, verify: PasswordVerifier): void {
+  if (!scheme || scheme.includes("$")) throw new Error(`invalid hash scheme '${scheme}' (must be non-empty and contain no '$')`);
+  if (scheme === "pbkdf2") throw new Error("'pbkdf2' is built in and cannot be overridden");
+  foreignVerifiers.set(scheme, verify);
+}
+
+/** True if `stored` is a foreign (non-PBKDF2) hash, i.e. one that login should upgrade
+ * after a successful verify. Also true for an unparseable value, which never verifies. */
+export function isForeignHash(stored: string): boolean {
+  return stored.split("$")[0] !== "pbkdf2";
+}
+
 export async function verifyPassword(password: string, stored: string): Promise<boolean> {
+  const scheme = stored.split("$")[0];
+  if (scheme !== "pbkdf2") {
+    const verify = foreignVerifiers.get(scheme);
+    // Unknown scheme (including the empty passwordHash of a passwordless user) never
+    // verifies — same as before this feature existed.
+    if (!verify) return false;
+    try {
+      return await verify(password, stored.slice(scheme.length + 1));
+    } catch {
+      // A broken/garbage payload must fail closed, not surface as a 500 that
+      // distinguishes it from a wrong password.
+      return false;
+    }
+  }
   const parsed = parseStoredHash(stored);
   if (!parsed) return false;
   const key = await crypto.subtle.importKey("raw", enc(password), "PBKDF2", false, ["deriveBits"]);
@@ -169,8 +226,38 @@ function parseCreds(raw: unknown): { username: string; password: string; email?:
   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
@@ -234,6 +321,22 @@ export const authHandlers = {
       // Only after the password verifies (so this can't enumerate accounts): a
       // deactivated user gets no new token. Existing tokens expire within the TTL.
       if (!isActive(u.active)) throw new Unauthorized("account is deactivated");
+      // Upgrade an imported foreign hash (see registerPasswordVerifier). This is the one
+      // moment the plaintext is in hand for a user whose hash predates pramen, so rehash
+      // to PBKDF2 and drop the old scheme. Deliberately AFTER the active check, so a
+      // deactivated account is never rewritten. Best-effort: a failed upgrade must not
+      // fail an otherwise valid login — the row simply upgrades on a later attempt.
+      if (isForeignHash(String(u.passwordHash))) {
+        try {
+          await ctx.db.exec(
+            "UPDATE auth_users SET passwordHash = ? WHERE username = ?",
+            await hashPassword(input.password),
+            String(u.username),
+          );
+        } catch {
+          /* keep the legacy hash; the next login retries */
+        }
+      }
       const roles = JSON.parse(String(u.roles)) as string[];
       const token = await signToken({ sub: String(u.username), roles }, secretOf(ctx), { ttlSeconds: sessionTtlOf(ctx) });
       return { token, user: { username: String(u.username), roles } };
@@ -242,6 +345,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 ---------------------------------------
@@ -357,6 +465,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).
@@ -489,12 +602,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 {
@@ -553,8 +673,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");
@@ -563,6 +686,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;
     }),
 
@@ -573,6 +699,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 };
     }),