@everystack/auth 0.4.6 → 0.4.8

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to `@everystack/auth` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.8] - 2026-09-26
+
+### Fixed
+
+- revoke sessions when users are blocked
+
+## [0.4.7] - 2026-09-26
+
+### Fixed
+
+- enforce bans on refresh and signin, check password before ban
+- make the access token lifetime configurable
+- signout revokes the presented refresh token
+- refuse banned users on OAuth sign-in; signout never fails on revoke
+
+### Documentation
+
+- document signout revocation, accessTokenTtlSec and ban enforcement
+
+## [0.4.6] - 2026-09-22
+
+### Fixed
+
+- refresh expired JWT instead of silently failing every request
+
 ## [0.4.5] - 2026-09-16
 
 ### Added

package/README.md

@@ -111,11 +111,14 @@ const auth = createAuthHandlers(
 | `signup` | POST | `{ email, password, username, displayName }` | `{ token, refreshToken, user }` |
 | `signin` | POST | `{ email, password }` | `{ token, refreshToken, user }` |
 | `refresh` | POST | `{ refreshToken }` | `{ token, refreshToken }` |
+| `signout` | POST | `{ refreshToken }` (or the refresh cookie) | revokes that session's refresh tokens, clears cookies |
 | `oauth` | POST | `{ provider, token }` | `{ token, refreshToken, user }` |
 | `verifyToken` | — | token string | `TokenPayload \| null` |
 | `revokeRefreshTokens` | — | `userId` | `void` |
 
-Defaults: HS256, access TTL 1h, refresh TTL 7d.
+Defaults: HS256, access TTL 1h, refresh TTL 7d. Set the access TTL with `accessTokenTtlSec` (seconds) in the options. If you install the SQL `_jwt` wrappers, pass the same value to `generateAuthSQL({ jwtWrappers: true, accessTokenTtlSec })`.
+
+Banned (`bannedUntil` in the future) and soft-deleted (`deletedAt`) users cannot sign in or refresh, in either mode. A banned user gets 403 only after the correct password; any wrong password gets the usual 401.
 
 ## OAuth (RS256 + JWKS)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/auth",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "JWT authentication handlers, password hashing, and React auth context",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -108,7 +108,7 @@
   },
   "dependencies": {
     "bcryptjs": "3.0.3",
-    "@everystack/model": "0.4.19"
+    "@everystack/model": "0.4.20"
   },
   "peerDependencies": {
     "@everystack/api": ">=0.1.0",
@@ -137,7 +137,7 @@
     "postgres": "3.4.9",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/server": "0.4.32",
+    "@everystack/server": "0.4.33",
     "@everystack/api": "0.4.2"
   },
   "scripts": {

package/src/cookies.ts

@@ -98,3 +98,17 @@ export function getRefreshFromCookies(cookieHeader: string | null): string | nul
   const cookies = parseCookies(cookieHeader);
   return cookies[COOKIE_NAMES.refresh] ?? null;
 }
+
+/**
+ * The refresh token a request presents: the JSON body's `refreshToken` (mobile), else the
+ * refresh cookie (web). Null when neither is present or the body is not JSON.
+ */
+export async function readPresentedRefreshToken(request: Request): Promise<string | null> {
+  try {
+    const body = await request.clone().json();
+    if (typeof body?.refreshToken === 'string' && body.refreshToken) return body.refreshToken;
+  } catch {
+    // No or non-JSON body: fall through to the cookie.
+  }
+  return getRefreshFromCookies(request.headers.get('cookie'));
+}

package/src/index.ts

@@ -30,6 +30,7 @@ import {
   createRefreshToken,
   rotateRefreshToken,
   revokeAllRefreshTokens,
+  revokeRefreshTokenFamilyByToken,
   TokenError,
 } from './refresh';
 import type { RefreshTokenOptions } from './refresh';
@@ -37,14 +38,14 @@ import type { OAuthProvider, OAuthUserInfo } from './oauth';
 export type { OAuthProvider, OAuthUserInfo } from './oauth';
 export { createAppleProvider, createGoogleProvider } from './oauth';
 import { createPostgresAuthHandlers } from './postgres';
-import { getRefreshFromCookies } from './cookies';
+import { getRefreshFromCookies, readPresentedRefreshToken } from './cookies';
 import { authResponse, signoutResponse } from './response';
 import type { CookieConfig } from './response';
 import type { EnrichClaimsFn } from './plugin';
 export type { EnrichClaimsFn } from './plugin';
 import { validateCsrfOrigin } from './csrf';
+import { resolveAccessTokenTtl } from './sql';
 
-const TOKEN_EXPIRY_SEC = 3600; // 1h
 const REFRESH_EXPIRY_SEC = 30 * 24 * 3600; // 30d
 
 /**
@@ -66,6 +67,35 @@ export function getPasswordHash(user: any): string | null {
  * Build insert values with the correct password column name.
  * Checks which column exists on the Drizzle table definition.
  */
+/**
+ * Why a user row may not hold a session, or null when it may. Reads row fields, not table
+ * columns, so an app schema without `bannedUntil`/`deletedAt` simply never trips it.
+ * Mirrors the SQL side: auth.sign_in filters deleted_at, auth.validate_refresh_token
+ * rejects deleted_at (P0004) and an unexpired banned_until (P0007).
+ */
+export function accountBlock(user: any): 'deleted' | 'banned' | null {
+  if (user.deletedAt) return 'deleted';
+  if (user.bannedUntil && new Date(user.bannedUntil).getTime() > Date.now()) return 'banned';
+  return null;
+}
+
+/** The refusal for a sign-in path that already proved identity (OAuth), or null to proceed.
+ *  A missing row is treated as a deleted account. */
+export function accountBlockedResponse(user: any): Response | null {
+  const block = user ? accountBlock(user) : 'deleted';
+  if (block === 'banned') return Response.json({ message: 'Account suspended' }, { status: 403 });
+  if (block === 'deleted') return Response.json({ message: 'Account disabled' }, { status: 401 });
+  return null;
+}
+
+/** Signout must always clear cookies. A failed server-side revoke is logged, never thrown:
+ *  only the error's code or message is logged, never the token. */
+export function warnRevokeFailed(err: unknown): void {
+  const e = err as { code?: string; message?: string } | undefined;
+  // eslint-disable-next-line no-console
+  console.warn('[everystack/auth] signout: refresh token revocation failed:', e?.code ?? e?.message ?? 'unknown error');
+}
+
 export function withPassword(users: any, values: Record<string, any>, hash: string | null): Record<string, any> {
   if ('encryptedPassword' in users) {
     return { ...values, encryptedPassword: hash };
@@ -136,6 +166,9 @@ export interface AuthOptions {
      *  Return true if valid, false to reject. */
     validateNonce?: (nonce: string, userInfo: OAuthUserInfo) => Promise<boolean>;
   };
+  /** Access-token (JWT) lifetime in seconds. Positive integer; default 3600. For the SQL
+   *  `_jwt` wrappers, pass the same value to `generateAuthSQL({ accessTokenTtlSec })`. */
+  accessTokenTtlSec?: number;
   /** When set, auth responses also set HttpOnly cookies. `true` uses defaults. */
   cookies?: CookieConfig;
   /** When true, signup returns the same 200 response whether the email exists or not.
@@ -433,6 +466,7 @@ export function createAuthHandlers(
   options?: AuthOptions
 ): AuthHandlers {
   assertSafeCookieConfig(options?.cookies);
+  const accessTokenTtlSec = resolveAccessTokenTtl(options?.accessTokenTtlSec);
 
   if (options?.mode === 'postgres') {
     const handlers = createPostgresAuthHandlers(db, schema, jwtSecret, options);
@@ -446,7 +480,7 @@ export function createAuthHandlers(
   const accessJwt = createJwt({
     secret: jwtSecret,
     hmac: hmacNode,
-    ttlSec: TOKEN_EXPIRY_SEC,
+    ttlSec: accessTokenTtlSec,
   });
   const refreshJwt = createJwt({
     secret: jwtSecret,
@@ -571,13 +605,19 @@ export function createAuthHandlers(
         );
       }
 
+      // Password first, account status second: every outcome pays for bcrypt, and only a
+      // caller who proved the password learns the account is suspended.
       const valid = await verifyPassword(password, getPasswordHash(user)!);
-      if (!valid) {
+      const block = accountBlock(user);
+      if (!valid || block === 'deleted') {
         return Response.json(
           { message: 'Invalid email or password' },
           { status: 401 }
         );
       }
+      if (block === 'banned') {
+        return Response.json({ message: 'Account suspended' }, { status: 403 });
+      }
 
       const [profile] = await db
         .select()
@@ -638,9 +678,15 @@ export function createAuthHandlers(
         // DB-backed rotation path
         try {
           const meta = extractRequestMeta(request, options?.repositoryId);
+          // checkUser runs before rotation: a banned/deleted account gets no new token, and
+          // rotateRefreshToken revokes every token it holds.
           const result = await rotateRefreshToken(db, refreshTable, refreshToken, {
             ipAddress: meta.ipAddress,
             userAgent: meta.userAgent,
+            checkUser: async (userId: string) => {
+              const [u] = await db.select().from(users).where(eq(users.id, userId)).limit(1);
+              return !!u && accountBlock(u) === null;
+            },
           });
 
           const [user] = await db
@@ -690,6 +736,9 @@ export function createAuthHandlers(
           if (!user) {
             return Response.json({ message: 'User not found' }, { status: 401 });
           }
+          if (accountBlock(user)) {
+            return Response.json({ message: 'Invalid or expired refresh token' }, { status: 401 });
+          }
 
           const token = await signToken({
             sub: user.id,
@@ -793,6 +842,8 @@ export function createAuthHandlers(
                 .from(users)
                 .where(eq(users.id, existing.userId))
                 .limit(1);
+              const blocked = accountBlockedResponse(existingUser);
+              if (blocked) return blocked;
 
               const [profile] = await db
                 .select()
@@ -879,6 +930,8 @@ export function createAuthHandlers(
               .from(users)
               .where(eq(users.id, existingAccount.userId))
               .limit(1);
+            const blocked = accountBlockedResponse(existingUser);
+            if (blocked) return blocked;
 
             const [profile] = await db
               .select()
@@ -989,6 +1042,17 @@ export function createAuthHandlers(
       const csrfError = csrfCheck(request, options?.cookies);
       if (csrfError) return csrfError;
 
+      // End the session server-side, not just in the browser: revoke the presented token's
+      // family. Stateless JWT refresh tokens have nothing to revoke.
+      const presented = await readPresentedRefreshToken(request);
+      if (refreshTable && presented) {
+        try {
+          await revokeRefreshTokenFamilyByToken(db, refreshTable, presented);
+        } catch (err) {
+          warnRevokeFailed(err);
+        }
+      }
+
       return signoutResponse(options?.cookies);
     },
 

package/src/models/functions.ts

@@ -39,7 +39,9 @@
  * hand-patch a body here.
  */
 
-import { defineFunction, arg, can, sql } from '@everystack/model';
+import { defineFunction, defineTrigger, arg, can, sql } from '@everystack/model';
+import { DEFAULT_ACCESS_TOKEN_TTL_SEC, resolveAccessTokenTtl } from '../sql';
+import { User } from './user';
 
 export const changePasswordFn = defineFunction('auth.change_password', {
   args: [arg('p_current_password', 'text'), arg('p_new_password', 'text')],
@@ -286,6 +288,10 @@ BEGIN
     IF NOT FOUND THEN
       RAISE EXCEPTION 'user_disabled' USING ERRCODE = 'P0004';
     END IF;
+    -- The provider proved identity; a ban still ends the road here.
+    IF v_user.banned_until IS NOT NULL AND v_user.banned_until > now() THEN
+      RAISE EXCEPTION 'user_banned' USING ERRCODE = 'P0006';
+    END IF;
 
     UPDATE auth.identities
     SET identity_data = p_identity_data, last_sign_in_at = now(), updated_at = now()
@@ -307,6 +313,11 @@ BEGIN
   WHERE email = lower(trim(p_email)) AND deleted_at IS NULL;
 
   IF FOUND THEN
+    -- Never link a provider to (or sign in) a banned account.
+    IF v_user.banned_until IS NOT NULL AND v_user.banned_until > now() THEN
+      RAISE EXCEPTION 'user_banned' USING ERRCODE = 'P0006';
+    END IF;
+
     -- Link the new provider to existing user
     v_providers := COALESCE(v_user.raw_app_meta_data->'providers', '[]'::jsonb);
     IF NOT v_providers ? p_provider THEN
@@ -357,7 +368,7 @@ END;
 `,
 });
 
-export const oauthSignInJwtFn = defineFunction('auth.oauth_sign_in_jwt', {
+const oauthSignInJwt = (ttl: number) => defineFunction('auth.oauth_sign_in_jwt', {
   args: [arg('p_provider', 'text'), arg('p_provider_id', 'text'), arg('p_email', 'text'), arg('p_identity_data', 'jsonb', { default: sql`'{}'::jsonb` })],
   returns: 'jsonb',
   language: 'plpgsql',
@@ -375,7 +386,7 @@ BEGIN
 
   v_claims := v_payload || jsonb_build_object(
     'iat', extract(epoch FROM now())::bigint,
-    'exp', (extract(epoch FROM now()) + 3600)::bigint
+    'exp', (extract(epoch FROM now()) + ${ttl})::bigint
   );
   v_token := auth.sign_jwt(v_claims);
 
@@ -481,16 +492,17 @@ BEGIN
     RAISE EXCEPTION 'invalid_credentials' USING ERRCODE = 'P0001';
   END IF;
 
-  -- Check banned
-  IF v_user.banned_until IS NOT NULL AND v_user.banned_until > now() THEN
-    RAISE EXCEPTION 'user_banned' USING ERRCODE = 'P0006';
-  END IF;
-
   v_valid := auth.verify_password(p_password, v_user.encrypted_password);
   IF NOT v_valid THEN
     RAISE EXCEPTION 'invalid_credentials' USING ERRCODE = 'P0001';
   END IF;
 
+  -- Check banned only AFTER the password is proven. Every path above pays for bcrypt and
+  -- answers invalid_credentials, so a ban is never visible to someone without the password.
+  IF v_user.banned_until IS NOT NULL AND v_user.banned_until > now() THEN
+    RAISE EXCEPTION 'user_banned' USING ERRCODE = 'P0006';
+  END IF;
+
   -- Update last sign in
   UPDATE auth.users SET last_sign_in_at = now(), updated_at = now()
   WHERE id = v_user.id;
@@ -504,7 +516,7 @@ END;
 `,
 });
 
-export const signInJwtFn = defineFunction('auth.sign_in_jwt', {
+const signInJwt = (ttl: number) => defineFunction('auth.sign_in_jwt', {
   args: [arg('p_email', 'text'), arg('p_password', 'text')],
   returns: 'jsonb',
   language: 'plpgsql',
@@ -522,7 +534,7 @@ BEGIN
 
   v_claims := v_payload || jsonb_build_object(
     'iat', extract(epoch FROM now())::bigint,
-    'exp', (extract(epoch FROM now()) + 3600)::bigint
+    'exp', (extract(epoch FROM now()) + ${ttl})::bigint
   );
   v_token := auth.sign_jwt(v_claims);
 
@@ -605,6 +617,37 @@ END;
 `,
 });
 
+export const signOutFn = defineFunction('auth.sign_out', {
+  args: [arg('p_token', 'text')],
+  returns: 'integer',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  abilities: [can('execute', { role: 'anon' })],
+  body: sql`
+DECLARE
+  v_family_id UUID;
+  v_count INTEGER;
+BEGIN
+  -- The presented refresh token is the credential: only its holder can end its session.
+  SELECT family_id INTO v_family_id
+  FROM auth.refresh_tokens
+  WHERE token_hash = encode(digest(p_token, 'sha256'), 'hex');
+
+  IF NOT FOUND THEN
+    RETURN 0;
+  END IF;
+
+  -- Revoke the whole family (every rotation of this session), leaving the user's other
+  -- sessions alone.
+  DELETE FROM auth.refresh_tokens WHERE family_id = v_family_id;
+
+  GET DIAGNOSTICS v_count = ROW_COUNT;
+  RETURN v_count;
+END;
+`,
+});
+
 export const signUpFn = defineFunction('auth.sign_up', {
   args: [arg('p_email', 'text'), arg('p_password', 'text'), arg('p_user_meta_data', 'jsonb', { default: sql`'{}'::jsonb` })],
   returns: 'jsonb',
@@ -650,7 +693,7 @@ END;
 `,
 });
 
-export const signUpJwtFn = defineFunction('auth.sign_up_jwt', {
+const signUpJwt = (ttl: number) => defineFunction('auth.sign_up_jwt', {
   args: [arg('p_email', 'text'), arg('p_password', 'text'), arg('p_user_meta_data', 'jsonb', { default: sql`'{}'::jsonb` })],
   returns: 'jsonb',
   language: 'plpgsql',
@@ -668,7 +711,7 @@ BEGIN
 
   v_claims := v_payload || jsonb_build_object(
     'iat', extract(epoch FROM now())::bigint,
-    'exp', (extract(epoch FROM now()) + 3600)::bigint
+    'exp', (extract(epoch FROM now()) + ${ttl})::bigint
   );
   v_token := auth.sign_jwt(v_claims);
 
@@ -731,6 +774,7 @@ DECLARE
   v_token_hash TEXT;
   v_row RECORD;
   v_user_deleted TIMESTAMPTZ;
+  v_user_banned_until TIMESTAMPTZ;
   v_new_token JSONB;
 BEGIN
   -- 1. Hash the input token
@@ -762,8 +806,8 @@ BEGIN
     RAISE EXCEPTION 'token_expired' USING ERRCODE = 'P0003';
   END IF;
 
-  -- 5. Check user is not deleted
-  SELECT deleted_at INTO v_user_deleted
+  -- 5. Check user is not deleted or banned
+  SELECT deleted_at, banned_until INTO v_user_deleted, v_user_banned_until
   FROM auth.users
   WHERE id = v_row.user_id;
 
@@ -772,6 +816,12 @@ BEGIN
     RAISE EXCEPTION 'user_disabled' USING ERRCODE = 'P0004';
   END IF;
 
+  -- A ban blocks rotation for as long as it holds. The RAISE rolls back this statement,
+  -- so the token row survives; it simply cannot rotate until banned_until has passed.
+  IF v_user_banned_until IS NOT NULL AND v_user_banned_until > now() THEN
+    RAISE EXCEPTION 'user_banned' USING ERRCODE = 'P0007';
+  END IF;
+
   -- 6. Device binding: if token was issued to a specific device, verify it
   IF v_row.device_id IS NOT NULL AND p_device_id IS NOT NULL
      AND v_row.device_id IS DISTINCT FROM p_device_id THEN
@@ -800,6 +850,36 @@ END;
 `,
 });
 
+/** Removes every session as soon as an account becomes unavailable. */
+export const revokeRefreshTokensOnUserBlockFn = defineFunction('auth.revoke_refresh_tokens_on_user_block', {
+  returns: 'trigger',
+  language: 'plpgsql',
+  security: 'definer',
+  searchPath: ['auth', 'public', 'pg_temp'],
+  body: sql`
+BEGIN
+  DELETE FROM auth.refresh_tokens WHERE user_id = NEW.id;
+  RETURN NEW;
+END;`,
+});
+
+/** The blocking transition is the durable revocation point; validation keeps its raise contract. */
+export const revokeRefreshTokensOnUserBlockTrigger = defineTrigger('users_revoke_refresh_tokens_on_block', {
+  on: User,
+  timing: 'after',
+  events: ['update'],
+  of: ['banned_until', 'deleted_at'],
+  forEach: 'row',
+  condition: sql`
+    (NEW.deleted_at IS NOT NULL AND OLD.deleted_at IS NULL)
+    OR (
+      NEW.banned_until > now()
+      AND (OLD.banned_until IS NULL OR OLD.banned_until <= now())
+    )
+  `,
+  execute: revokeRefreshTokensOnUserBlockFn,
+});
+
 export const verifyJwtFn = defineFunction('auth.verify_jwt', {
   args: [arg('p_token', 'text')],
   returns: 'jsonb',
@@ -929,7 +1009,8 @@ export const coreFunctions = [hashPasswordFn, verifyPasswordFn, signJwtFn, verif
 
 /** The refresh-token family (RFC 6819 rotation). Always on. */
 export const refreshTokenFunctions = [
-  issueRefreshTokenFn, validateRefreshTokenFn, revokeRefreshTokensFn, cleanupRefreshTokensFn,
+  issueRefreshTokenFn, validateRefreshTokenFn, revokeRefreshTokensFn, signOutFn, cleanupRefreshTokensFn,
+  revokeRefreshTokensOnUserBlockFn,
 ];
 
 /** `auth.uid()` / `auth.role()` / `auth.jwt()` — called FROM RLS policies, so granted to the
@@ -948,7 +1029,20 @@ export const sessionWrapperFunctions = [signInSessionFn, signUpSessionFn];
 /** The raw sign_in/sign_up/oauth minters. Default on; never granted to anon. */
 export const defaultAuthFunctions = [signUpFn, signInFn, oauthSignInFn];
 
-/** JWT convenience wrappers. Default OFF, matching `generateAuthSQL`. */
+/**
+ * JWT convenience wrappers for a given access-token lifetime (seconds), the descriptor twin of
+ * `generateJwtWrappersSQL({ accessTokenTtlSec })`. Default OFF in {@link authFunctions}.
+ */
+export function jwtWrapperFunctionsFor(accessTokenTtlSec?: number) {
+  const ttl = resolveAccessTokenTtl(accessTokenTtlSec);
+  return [signInJwt(ttl), signUpJwt(ttl), oauthSignInJwt(ttl)];
+}
+
+export const signInJwtFn = signInJwt(DEFAULT_ACCESS_TOKEN_TTL_SEC);
+export const signUpJwtFn = signUpJwt(DEFAULT_ACCESS_TOKEN_TTL_SEC);
+export const oauthSignInJwtFn = oauthSignInJwt(DEFAULT_ACCESS_TOKEN_TTL_SEC);
+
+/** JWT convenience wrappers at the default lifetime. Default OFF, matching `generateAuthSQL`. */
 export const jwtWrapperFunctions = [signInJwtFn, signUpJwtFn, oauthSignInJwtFn];
 
 /** Mirrors {@link AuthSQLOptions} in sql.ts — same defaults, same meanings. */
@@ -959,6 +1053,7 @@ export interface AuthFunctionOptions {
   sessionWrappers?: boolean;
   defaultAuthFunctions?: boolean;
   jwtWrappers?: boolean;
+  accessTokenTtlSec?: number;
 }
 
 /**
@@ -975,6 +1070,11 @@ export function authFunctions(opts: AuthFunctionOptions = {}) {
     ...(opts.tokenActions !== false ? tokenActionFunctions : []),
     ...(opts.sessionWrappers !== false ? sessionWrapperFunctions : []),
     ...(opts.defaultAuthFunctions !== false ? defaultAuthFunctions : []),
-    ...(opts.jwtWrappers === true ? jwtWrapperFunctions : []),
+    ...(opts.jwtWrappers === true ? jwtWrapperFunctionsFor(opts.accessTokenTtlSec) : []),
   ];
 }
+
+/** The auth module's complete derived layer: functions plus lifecycle bindings. */
+export function authDerived(opts: AuthFunctionOptions = {}) {
+  return [...authFunctions(opts), revokeRefreshTokensOnUserBlockTrigger];
+}

package/src/models/index.ts

@@ -25,7 +25,7 @@ import { Device } from './device';
 import { MfaFactor } from './mfa-factor';
 import { MfaChallenge } from './mfa-challenge';
 import { OneTimeToken } from './one-time-token';
-import { authFunctions, type AuthFunctionOptions } from './functions';
+import { authDerived, type AuthFunctionOptions } from './functions';
 
 export * from './functions';
 
@@ -51,7 +51,7 @@ export function defineAuthModule(opts: AuthFunctionOptions = {}): Module {
   return defineModule({
     models: authModels,
     extensions: ['pgcrypto'],
-    derived: authFunctions(opts),
+    derived: authDerived(opts),
   });
 }
 

package/src/postgres.ts

@@ -18,14 +18,13 @@ import { createJwt } from './jwt';
 import { hmacNode } from './jwt/hmac-node';
 import type { RefreshTokenOptions } from './refresh';
 import type { AuthHandlers, AuthOptions, TokenPayload } from './index';
-import { withPassword } from './index';
+import { accountBlock, accountBlockedResponse, warnRevokeFailed, withPassword } from './index';
 import type { OAuthProvider } from './oauth';
-import { getRefreshFromCookies } from './cookies';
+import { getRefreshFromCookies, readPresentedRefreshToken } from './cookies';
 import { authResponse, signoutResponse } from './response';
 import type { CookieConfig } from './response';
 import { validateCsrfOrigin } from './csrf';
-
-const TOKEN_EXPIRY_SECONDS = 3600; // 1 hour
+import { resolveAccessTokenTtl } from './sql';
 
 // Postgres identifier rule — the only role name ever interpolated into SET LOCAL ROLE.
 const ROLE_NAME = /^[a-z_][a-z0-9_]*$/;
@@ -85,6 +84,7 @@ export function createPostgresAuthHandlers(
     throw new Error("mode: 'postgres' requires options.sql (postgres.js client)");
   }
 
+  const accessTokenTtlSec = resolveAccessTokenTtl(options?.accessTokenTtlSec);
   const { users, profiles } = schema;
   const refreshTable = schema.refreshTokens;
   const jwtSecretString = new TextDecoder().decode(jwtSecret);
@@ -188,7 +188,7 @@ export function createPostgresAuthHandlers(
     const fullPayload = {
       ...claims,
       iat: now,
-      exp: now + TOKEN_EXPIRY_SECONDS,
+      exp: now + accessTokenTtlSec,
     };
     const payloadJson = JSON.stringify(fullPayload);
     const rows = await pgSql.begin(async (sql: any) => {
@@ -234,7 +234,7 @@ export function createPostgresAuthHandlers(
   const verifier = createJwt({
     secret: jwtSecret,
     hmac: hmacNode,
-    ttlSec: TOKEN_EXPIRY_SECONDS,
+    ttlSec: accessTokenTtlSec,
   });
 
   /**
@@ -506,8 +506,9 @@ export function createPostgresAuthHandlers(
         } catch (err: any) {
           // Map PG error codes to HTTP responses
           const pgCode = err?.code;
+          // P0004 user_disabled (deleted), P0007 user_banned — both revoke the tokens in SQL.
           if (pgCode === 'P0001' || pgCode === 'P0002' || pgCode === 'P0003'
-              || pgCode === 'P0004' || pgCode === 'P0005') {
+              || pgCode === 'P0004' || pgCode === 'P0005' || pgCode === 'P0007') {
             return Response.json(
               { message: 'Invalid or expired refresh token' },
               { status: 401 },
@@ -532,6 +533,9 @@ export function createPostgresAuthHandlers(
           if (!user) {
             return Response.json({ message: 'User not found' }, { status: 401 });
           }
+          if (accountBlock(user)) {
+            return Response.json({ message: 'Invalid or expired refresh token' }, { status: 401 });
+          }
 
           const token = await signJwtPg({
             sub: user.id,
@@ -661,6 +665,8 @@ export function createPostgresAuthHandlers(
                 .from(users)
                 .where(eq(users.id, existing.userId))
                 .limit(1);
+              const blocked = accountBlockedResponse(existingUser);
+              if (blocked) return blocked;
 
               const [profile] = await db
                 .select()
@@ -759,6 +765,8 @@ export function createPostgresAuthHandlers(
               .from(users)
               .where(eq(users.id, existingAccount.userId))
               .limit(1);
+            const blocked = accountBlockedResponse(existingUser);
+            if (blocked) return blocked;
 
             const [profile] = await db
               .select()
@@ -881,6 +889,18 @@ export function createPostgresAuthHandlers(
       const csrfError = csrfCheck(request, options?.cookies);
       if (csrfError) return csrfError;
 
+      // End the session server-side: revoke the presented token's family through the
+      // token-gated SECDEF auth.sign_out, as anon (the token is the credential). Covers
+      // tokens from signin and signup alike. Stateless JWT refresh tokens have nothing to revoke.
+      const presented = await readPresentedRefreshToken(request);
+      if (refreshTable && presented) {
+        try {
+          await withRole('anon', { role: 'anon' }, (sql: any) => sql`SELECT auth.sign_out(${presented})`);
+        } catch (err) {
+          warnRevokeFailed(err);
+        }
+      }
+
       return signoutResponse(options?.cookies);
     },
 

package/src/refresh.ts

@@ -240,6 +240,20 @@ export async function revokeTokenFamily(
   await db.delete(table).where(eq(table.familyId, familyId));
 }
 
+/**
+ * Revoke the family of a presented raw refresh token (signout). Unknown tokens are a no-op.
+ * Revokes every rotation of that session and leaves the user's other sessions alone.
+ */
+export async function revokeRefreshTokenFamilyByToken(
+  db: any,
+  table: any,
+  rawToken: string,
+): Promise<void> {
+  const tokenHash = await hashToken(rawToken);
+  const [row] = await db.select().from(table).where(eq(table.tokenHash, tokenHash)).limit(1);
+  if (row) await revokeTokenFamily(db, table, row.familyId);
+}
+
 /**
  * Delete all expired and stale consumed tokens.
  * Call periodically (e.g., daily cron via pg_cron).

package/src/sql.ts

@@ -25,6 +25,21 @@
  *   const sql = generateCoreSQL() + '\n' + generateAccessorSQL();
  */
 
+/** Access-token lifetime when none is configured. */
+export const DEFAULT_ACCESS_TOKEN_TTL_SEC = 3600;
+
+/**
+ * The configured access-token lifetime, or the default. This value is interpolated into
+ * generated SQL, so anything but a positive safe integer is refused rather than coerced.
+ */
+export function resolveAccessTokenTtl(ttl?: number): number {
+  if (ttl === undefined) return DEFAULT_ACCESS_TOKEN_TTL_SEC;
+  if (!Number.isSafeInteger(ttl) || ttl <= 0) {
+    throw new Error(`accessTokenTtlSec must be a positive integer number of seconds, got ${String(ttl)}`);
+  }
+  return ttl;
+}
+
 const PGCRYPTO = `CREATE EXTENSION IF NOT EXISTS pgcrypto;`;
 
 const HASH_PASSWORD = `\
@@ -266,6 +281,7 @@ DECLARE
   v_token_hash TEXT;
   v_row RECORD;
   v_user_deleted TIMESTAMPTZ;
+  v_user_banned_until TIMESTAMPTZ;
   v_new_token JSONB;
 BEGIN
   -- 1. Hash the input token
@@ -297,8 +313,8 @@ BEGIN
     RAISE EXCEPTION 'token_expired' USING ERRCODE = 'P0003';
   END IF;
 
-  -- 5. Check user is not deleted
-  SELECT deleted_at INTO v_user_deleted
+  -- 5. Check user is not deleted or banned
+  SELECT deleted_at, banned_until INTO v_user_deleted, v_user_banned_until
   FROM auth.users
   WHERE id = v_row.user_id;
 
@@ -307,6 +323,12 @@ BEGIN
     RAISE EXCEPTION 'user_disabled' USING ERRCODE = 'P0004';
   END IF;
 
+  -- A ban blocks rotation for as long as it holds. The RAISE rolls back this statement,
+  -- so the token row survives; it simply cannot rotate until banned_until has passed.
+  IF v_user_banned_until IS NOT NULL AND v_user_banned_until > now() THEN
+    RAISE EXCEPTION 'user_banned' USING ERRCODE = 'P0007';
+  END IF;
+
   -- 6. Device binding: if token was issued to a specific device, verify it
   IF v_row.device_id IS NOT NULL AND p_device_id IS NOT NULL
      AND v_row.device_id IS DISTINCT FROM p_device_id THEN
@@ -336,6 +358,33 @@ $$;
 
 REVOKE EXECUTE ON FUNCTION auth.validate_refresh_token FROM PUBLIC;`;
 
+const REVOKE_REFRESH_TOKENS_ON_USER_BLOCK = `\
+CREATE OR REPLACE FUNCTION auth.revoke_refresh_tokens_on_user_block()
+RETURNS TRIGGER
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = auth, public, pg_temp
+AS $$
+BEGIN
+  DELETE FROM auth.refresh_tokens WHERE user_id = NEW.id;
+  RETURN NEW;
+END;
+$$;
+
+REVOKE EXECUTE ON FUNCTION auth.revoke_refresh_tokens_on_user_block FROM PUBLIC;
+
+CREATE TRIGGER users_revoke_refresh_tokens_on_block
+AFTER UPDATE OF banned_until, deleted_at ON auth.users
+FOR EACH ROW
+WHEN (
+  (NEW.deleted_at IS NOT NULL AND OLD.deleted_at IS NULL)
+  OR (
+    NEW.banned_until > now()
+    AND (OLD.banned_until IS NULL OR OLD.banned_until <= now())
+  )
+)
+EXECUTE FUNCTION auth.revoke_refresh_tokens_on_user_block();`;
+
 const REVOKE_REFRESH_TOKENS = `\
 CREATE OR REPLACE FUNCTION auth.revoke_refresh_tokens(
   p_user_id UUID,
@@ -368,6 +417,40 @@ $$;
 
 REVOKE EXECUTE ON FUNCTION auth.revoke_refresh_tokens FROM PUBLIC;`;
 
+// auth.sign_out — the anon-safe signout. Token-gated like validate_refresh_token: the caller
+// proves possession of a refresh token and may revoke only that token's family. The by-user
+// revoke (auth.revoke_refresh_tokens) stays owner-only.
+const SIGN_OUT = `\
+CREATE OR REPLACE FUNCTION auth.sign_out(p_token TEXT)
+RETURNS INTEGER
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = auth, public, pg_temp
+AS $$
+DECLARE
+  v_family_id UUID;
+  v_count INTEGER;
+BEGIN
+  -- The presented refresh token is the credential: only its holder can end its session.
+  SELECT family_id INTO v_family_id
+  FROM auth.refresh_tokens
+  WHERE token_hash = encode(digest(p_token, 'sha256'), 'hex');
+
+  IF NOT FOUND THEN
+    RETURN 0;
+  END IF;
+
+  -- Revoke the whole family (every rotation of this session), leaving the user's other
+  -- sessions alone.
+  DELETE FROM auth.refresh_tokens WHERE family_id = v_family_id;
+
+  GET DIAGNOSTICS v_count = ROW_COUNT;
+  RETURN v_count;
+END;
+$$;
+
+REVOKE EXECUTE ON FUNCTION auth.sign_out FROM PUBLIC;`;
+
 const CLEANUP_REFRESH_TOKENS = `\
 CREATE OR REPLACE FUNCTION auth.cleanup_refresh_tokens(
   p_consumed_retention INTERVAL DEFAULT '7 days'
@@ -707,16 +790,17 @@ BEGIN
     RAISE EXCEPTION 'invalid_credentials' USING ERRCODE = 'P0001';
   END IF;
 
-  -- Check banned
-  IF v_user.banned_until IS NOT NULL AND v_user.banned_until > now() THEN
-    RAISE EXCEPTION 'user_banned' USING ERRCODE = 'P0006';
-  END IF;
-
   v_valid := auth.verify_password(p_password, v_user.encrypted_password);
   IF NOT v_valid THEN
     RAISE EXCEPTION 'invalid_credentials' USING ERRCODE = 'P0001';
   END IF;
 
+  -- Check banned only AFTER the password is proven. Every path above pays for bcrypt and
+  -- answers invalid_credentials, so a ban is never visible to someone without the password.
+  IF v_user.banned_until IS NOT NULL AND v_user.banned_until > now() THEN
+    RAISE EXCEPTION 'user_banned' USING ERRCODE = 'P0006';
+  END IF;
+
   -- Update last sign in
   UPDATE auth.users SET last_sign_in_at = now(), updated_at = now()
   WHERE id = v_user.id;
@@ -758,6 +842,10 @@ BEGIN
     IF NOT FOUND THEN
       RAISE EXCEPTION 'user_disabled' USING ERRCODE = 'P0004';
     END IF;
+    -- The provider proved identity; a ban still ends the road here.
+    IF v_user.banned_until IS NOT NULL AND v_user.banned_until > now() THEN
+      RAISE EXCEPTION 'user_banned' USING ERRCODE = 'P0006';
+    END IF;
 
     UPDATE auth.identities
     SET identity_data = p_identity_data, last_sign_in_at = now(), updated_at = now()
@@ -779,6 +867,11 @@ BEGIN
   WHERE email = lower(trim(p_email)) AND deleted_at IS NULL;
 
   IF FOUND THEN
+    -- Never link a provider to (or sign in) a banned account.
+    IF v_user.banned_until IS NOT NULL AND v_user.banned_until > now() THEN
+      RAISE EXCEPTION 'user_banned' USING ERRCODE = 'P0006';
+    END IF;
+
     -- Link the new provider to existing user
     v_providers := COALESCE(v_user.raw_app_meta_data->'providers', '[]'::jsonb);
     IF NOT v_providers ? p_provider THEN
@@ -834,7 +927,7 @@ REVOKE EXECUTE ON FUNCTION auth.oauth_sign_in FROM PUBLIC;`;
 // JWT CONVENIENCE WRAPPERS
 // =============================================================================
 
-const SIGN_IN_JWT = `\
+const SIGN_IN_JWT = (ttl: number): string => `\
 CREATE OR REPLACE FUNCTION auth.sign_in_jwt(p_email TEXT, p_password TEXT)
 RETURNS JSONB
 LANGUAGE plpgsql
@@ -851,7 +944,7 @@ BEGIN
 
   v_claims := v_payload || jsonb_build_object(
     'iat', extract(epoch FROM now())::bigint,
-    'exp', (extract(epoch FROM now()) + 3600)::bigint
+    'exp', (extract(epoch FROM now()) + ${ttl})::bigint
   );
   v_token := auth.sign_jwt(v_claims);
 
@@ -867,7 +960,7 @@ $$;
 
 REVOKE EXECUTE ON FUNCTION auth.sign_in_jwt FROM PUBLIC;`;
 
-const SIGN_UP_JWT = `\
+const SIGN_UP_JWT = (ttl: number): string => `\
 CREATE OR REPLACE FUNCTION auth.sign_up_jwt(
   p_email TEXT,
   p_password TEXT,
@@ -888,7 +981,7 @@ BEGIN
 
   v_claims := v_payload || jsonb_build_object(
     'iat', extract(epoch FROM now())::bigint,
-    'exp', (extract(epoch FROM now()) + 3600)::bigint
+    'exp', (extract(epoch FROM now()) + ${ttl})::bigint
   );
   v_token := auth.sign_jwt(v_claims);
 
@@ -904,7 +997,7 @@ $$;
 
 REVOKE EXECUTE ON FUNCTION auth.sign_up_jwt FROM PUBLIC;`;
 
-const OAUTH_SIGN_IN_JWT = `\
+const OAUTH_SIGN_IN_JWT = (ttl: number): string => `\
 CREATE OR REPLACE FUNCTION auth.oauth_sign_in_jwt(
   p_provider TEXT,
   p_provider_id TEXT,
@@ -926,7 +1019,7 @@ BEGIN
 
   v_claims := v_payload || jsonb_build_object(
     'iat', extract(epoch FROM now())::bigint,
-    'exp', (extract(epoch FROM now()) + 3600)::bigint
+    'exp', (extract(epoch FROM now()) + ${ttl})::bigint
   );
   v_token := auth.sign_jwt(v_claims);
 
@@ -1023,9 +1116,12 @@ export function generateCoreSQL(): string {
     .trimEnd() + '\n';
 }
 
-/** issue + validate + revoke + cleanup refresh tokens (RFC 6819) */
+/** issue + validate + revoke + sign_out + cleanup refresh tokens (RFC 6819) */
 export function generateRefreshTokenSQL(): string {
-  return [ISSUE_REFRESH_TOKEN, '', VALIDATE_REFRESH_TOKEN, '', REVOKE_REFRESH_TOKENS, '', CLEANUP_REFRESH_TOKENS]
+  return [
+    ISSUE_REFRESH_TOKEN, '', VALIDATE_REFRESH_TOKEN, '', REVOKE_REFRESH_TOKENS_ON_USER_BLOCK, '',
+    REVOKE_REFRESH_TOKENS, '', SIGN_OUT, '', CLEANUP_REFRESH_TOKENS,
+  ]
     .join('\n')
     .trimEnd() + '\n';
 }
@@ -1062,9 +1158,13 @@ export function generateDefaultAuthSQL(): string {
     .trimEnd() + '\n';
 }
 
-/** auth.sign_in_jwt, auth.sign_up_jwt, auth.oauth_sign_in_jwt */
-export function generateJwtWrappersSQL(): string {
-  return [SIGN_IN_JWT, '', SIGN_UP_JWT, '', OAUTH_SIGN_IN_JWT]
+/**
+ * auth.sign_in_jwt, auth.sign_up_jwt, auth.oauth_sign_in_jwt. `accessTokenTtlSec` (default
+ * 3600) is baked into the generated bodies as the access token's `exp` offset.
+ */
+export function generateJwtWrappersSQL(opts: { accessTokenTtlSec?: number } = {}): string {
+  const ttl = resolveAccessTokenTtl(opts.accessTokenTtlSec);
+  return [SIGN_IN_JWT(ttl), '', SIGN_UP_JWT(ttl), '', OAUTH_SIGN_IN_JWT(ttl)]
     .join('\n')
     .trimEnd() + '\n';
 }
@@ -1096,6 +1196,8 @@ export function generateAuthGrantsSQL(opts: AuthSQLOptions = {}): string {
   const lines = ['GRANT USAGE ON SCHEMA auth TO anon, authenticated, admin;'];
   // validate_refresh_token is always generated (the refresh path) and anon-callable.
   lines.push('GRANT EXECUTE ON FUNCTION auth.validate_refresh_token(text, uuid, text, text, interval) TO anon;');
+  // sign_out is generated with the refresh functions and is token-gated the same way.
+  lines.push('GRANT EXECUTE ON FUNCTION auth.sign_out(text) TO anon;');
   if (opts.tokenActions !== false) {
     lines.push('GRANT EXECUTE ON FUNCTION auth.confirm_email(text) TO anon;');
     lines.push('GRANT EXECUTE ON FUNCTION auth.reset_password(text, text) TO anon;');
@@ -1125,6 +1227,8 @@ export interface AuthSQLOptions {
   defaultAuthFunctions?: boolean;
   /** Include JWT convenience wrappers (default: false) */
   jwtWrappers?: boolean;
+  /** Access-token lifetime baked into the JWT wrappers, in seconds (default: 3600) */
+  accessTokenTtlSec?: number;
 }
 
 /**
@@ -1157,7 +1261,7 @@ export function generateAuthSQL(options?: AuthSQLOptions): string {
     parts.push('', generateDefaultAuthSQL());
   }
   if (options?.jwtWrappers) {
-    parts.push('', generateJwtWrappersSQL());
+    parts.push('', generateJwtWrappersSQL({ accessTokenTtlSec: options.accessTokenTtlSec }));
   }
 
   // The role grants come LAST — every GRANT EXECUTE target now exists. This is what makes the