@everystack/auth 0.4.8 → 0.4.10

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.10] - 2026-10-30
+
+### Added
+
+- accountTrigger ends an account's sessions in its soft-delete transaction
+
+### Fixed
+
+- accountTrigger keeps an admin's earlier disable
+- review nits: cap accountTrigger's column at 39 characters; docs state the column the trigger trusts
+
+### Documentation
+
+- accountTrigger in the lifecycle guide, the auth README, upgrading and the MCP resource
+
+## [0.4.9] - 2026-10-14
+
+### Fixed
+
+- break the model and auth import cycles; gate new ones
+
+### Changed
+
+- share refresh token extraction
+
 ## [0.4.8] - 2026-09-26
 
 ### Fixed

package/README.md

@@ -185,6 +185,16 @@ Edge verification trusts the signature; it cannot consult a revocation list with
 - Keep **refresh tokens long-lived in DB** with revocation
 - Sign-out / password change → revoke refresh tokens, access tokens expire on their own
 
+## Account deletion
+
+When an app deletes an account by soft-deleting a lifecycle row (a profile whose `id` is the
+`auth.users` id), put `accountTrigger({ userId: 'id' })` in that model's `triggers`. In the same
+transaction it marks the `auth.users` row deleted and removes the user's refresh and one-time tokens,
+so sign-in and refresh stop at once. An access token already issued lives out its TTL (default 3600s).
+Restoring the row clears the mark only: the user signs in again, and no old session comes back.
+Identities and MFA factors are kept. It replaces an app's own token `DELETE` in its delete-account
+code. See [docs/lifecycle.md](../../docs/lifecycle.md), "When the deleted row is an account".
+
 ## SQL Twin
 
 `@everystack/auth/jwt/sql` ships pgcrypto-based functions that produce byte-identical tokens to the JS path:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/auth",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "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.20"
+    "@everystack/model": "0.4.25"
   },
   "peerDependencies": {
     "@everystack/api": ">=0.1.0",
@@ -137,8 +137,8 @@
     "postgres": "3.4.9",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/server": "0.4.33",
-    "@everystack/api": "0.4.2"
+    "@everystack/api": "0.4.13",
+    "@everystack/server": "0.4.40"
   },
   "scripts": {
     "test": "jest",

package/src/account.ts

@@ -0,0 +1,44 @@
+/**
+ * Account-state and password-column helpers shared by index.ts and postgres.ts.
+ * A leaf module: index.ts imports postgres.ts, so these cannot live in index.ts.
+ */
+
+/**
+ * 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');
+}
+
+/**
+ * Build insert values with the correct password column name.
+ * Checks which column exists on the Drizzle table definition.
+ */
+export function withPassword(users: any, values: Record<string, any>, hash: string | null): Record<string, any> {
+  if ('encryptedPassword' in users) {
+    return { ...values, encryptedPassword: hash };
+  }
+  return { ...values, passwordHash: hash };
+}

package/src/index.ts

@@ -38,7 +38,9 @@ import type { OAuthProvider, OAuthUserInfo } from './oauth';
 export type { OAuthProvider, OAuthUserInfo } from './oauth';
 export { createAppleProvider, createGoogleProvider } from './oauth';
 import { createPostgresAuthHandlers } from './postgres';
-import { getRefreshFromCookies, readPresentedRefreshToken } from './cookies';
+import { accountBlock, accountBlockedResponse, warnRevokeFailed, withPassword } from './account';
+export { accountBlock, accountBlockedResponse, warnRevokeFailed, withPassword } from './account';
+import { readPresentedRefreshToken } from './cookies';
 import { authResponse, signoutResponse } from './response';
 import type { CookieConfig } from './response';
 import type { EnrichClaimsFn } from './plugin';
@@ -63,45 +65,6 @@ export function getPasswordHash(user: any): string | null {
   return user.encryptedPassword ?? user.passwordHash ?? 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 };
-  }
-  return { ...values, passwordHash: hash };
-}
 
 export interface TokenPayload {
   sub: string;
@@ -656,17 +619,7 @@ export function createAuthHandlers(
       const csrfError = csrfCheck(request, options?.cookies);
       if (csrfError) return csrfError;
 
-      // Read refresh token from JSON body (mobile) or cookie (web SSR)
-      let refreshToken: string | undefined;
-      try {
-        const body = await request.clone().json();
-        refreshToken = body?.refreshToken;
-      } catch {
-        // Empty body is fine — fall through to cookie
-      }
-      if (!refreshToken) {
-        refreshToken = getRefreshFromCookies(request.headers.get('cookie')) ?? undefined;
-      }
+      const refreshToken = await readPresentedRefreshToken(request);
       if (!refreshToken) {
         return Response.json(
           { message: 'refreshToken is required' },

package/src/models/functions.ts

@@ -39,7 +39,8 @@
  * hand-patch a body here.
  */
 
-import { defineFunction, defineTrigger, arg, can, sql } from '@everystack/model';
+import { defineFunction, defineTrigger, trigger, arg, can, sql } from '@everystack/model';
+import type { FunctionDescriptor, RawSql, TriggerSpec } from '@everystack/model';
 import { DEFAULT_ACCESS_TOKEN_TTL_SEC, resolveAccessTokenTtl } from '../sql';
 import { User } from './user';
 
@@ -880,6 +881,94 @@ export const revokeRefreshTokensOnUserBlockTrigger = defineTrigger('users_revoke
   execute: revokeRefreshTokensOnUserBlockFn,
 });
 
+/** A column name the account trigger may read: lower snake case, at most 39 characters, so
+ *  `end_account_sessions_by_<col>` stays within PostgreSQL's 63-character identifier limit. */
+const ACCOUNT_USER_ID = /^[a-z_][a-z0-9_]{0,38}$/;
+
+/** The function name for one user-id column. `id` keeps the plain name; the auth module declares it. */
+function accountSessionsName(userId: string): string {
+  return userId === 'id' ? 'auth.end_account_sessions' : `auth.end_account_sessions_by_${userId}`;
+}
+
+function accountSessionsBody(userId: string): RawSql {
+  // The column is baked into the body: TriggerSpec carries no trigger arguments. It is validated
+  // as a lower snake case identifier before it gets here, so it needs no quoting.
+  return sql`
+DECLARE
+  v_user_id pg_catalog.uuid;
+BEGIN
+  IF TG_OP <> 'UPDATE' OR TG_WHEN <> 'AFTER' OR TG_LEVEL <> 'ROW' THEN
+    RAISE EXCEPTION 'end_account_sessions runs only as an AFTER UPDATE row trigger' USING ERRCODE = '42501';
+  END IF;
+  v_user_id := NEW.${userId}::pg_catalog.uuid;
+  IF OLD.deleted_at IS NULL AND NEW.deleted_at IS NOT NULL THEN
+    UPDATE auth.users SET deleted_at = NEW.deleted_at WHERE id = v_user_id AND deleted_at IS NULL;
+    PERFORM auth.revoke_refresh_tokens(v_user_id);
+    DELETE FROM auth.one_time_tokens WHERE user_id = v_user_id;
+  ELSIF OLD.deleted_at IS NOT NULL AND NEW.deleted_at IS NULL THEN
+    -- A restore brings the account back, never its sessions: the user signs in again.
+    -- It clears only the stamp this account set; an earlier disable stays.
+    UPDATE auth.users SET deleted_at = NULL WHERE id = v_user_id AND deleted_at = OLD.deleted_at;
+  END IF;
+  RETURN NULL;
+END`;
+}
+
+const accountSessionsFunctions = new Map<string, FunctionDescriptor>();
+
+/**
+ * The trigger function that carries an account's soft delete to auth.users, for an account table
+ * whose `userId` column holds the auth.users id. Deleting the account soft-deletes the user and
+ * removes its refresh and one-time tokens in the same transaction; restoring it clears the user's
+ * deleted_at and nothing else. Any other update writes nothing.
+ * It stamps only a live user and clears only its own stamp, so an earlier admin disable survives both.
+ *
+ * It runs inside the lifecycle functions' pinned search_path, so it pins `pg_catalog, pg_temp` and
+ * qualifies every name. No role but its owner may EXECUTE it (the compiler revokes PUBLIC).
+ *
+ * The auth module declares the `id` one. Declare any other in your own module's `derived`.
+ */
+export function accountSessionsFunction(userId: string): FunctionDescriptor {
+  if (!ACCOUNT_USER_ID.test(userId)) {
+    throw new Error(
+      `accountTrigger: userId '${userId}' is not a column name — pass the account table's column ` +
+      '(lower snake case, at most 39 characters), for example { userId: \'id\' } or { userId: \'user_id\' }.',
+    );
+  }
+  let fn = accountSessionsFunctions.get(userId);
+  if (!fn) {
+    fn = defineFunction(accountSessionsName(userId), {
+      returns: 'trigger',
+      language: 'plpgsql',
+      security: 'definer',
+      searchPath: ['pg_catalog', 'pg_temp'],
+      body: accountSessionsBody(userId),
+    });
+    accountSessionsFunctions.set(userId, fn);
+  }
+  return fn;
+}
+
+/** The `id` account function, which the auth module declares. */
+export const endAccountSessionsFn = accountSessionsFunction('id');
+
+/**
+ * Ends an account's sessions when the account is soft-deleted. Add it to the lifecycle model that
+ * IS the account (`lifecycle: true`), whose `userId` column holds the auth.users id:
+ * `triggers: [accountTrigger({ userId: 'id' })]`.
+ *
+ * AFTER UPDATE OF deleted_at, so it fires on a direct delete, a cascaded one and a restore alike.
+ */
+export function accountTrigger(opts: { userId: string }): TriggerSpec {
+  return trigger('end_account_sessions', {
+    timing: 'after',
+    events: ['update'],
+    of: ['deleted_at'],
+    forEach: 'row',
+    execute: accountSessionsFunction(opts.userId),
+  });
+}
+
 export const verifyJwtFn = defineFunction('auth.verify_jwt', {
   args: [arg('p_token', 'text')],
   returns: 'jsonb',
@@ -1010,7 +1099,7 @@ export const coreFunctions = [hashPasswordFn, verifyPasswordFn, signJwtFn, verif
 /** The refresh-token family (RFC 6819 rotation). Always on. */
 export const refreshTokenFunctions = [
   issueRefreshTokenFn, validateRefreshTokenFn, revokeRefreshTokensFn, signOutFn, cleanupRefreshTokensFn,
-  revokeRefreshTokensOnUserBlockFn,
+  revokeRefreshTokensOnUserBlockFn, endAccountSessionsFn,
 ];
 
 /** `auth.uid()` / `auth.role()` / `auth.jwt()` — called FROM RLS policies, so granted to the

package/src/postgres.ts

@@ -18,9 +18,9 @@ import { createJwt } from './jwt';
 import { hmacNode } from './jwt/hmac-node';
 import type { RefreshTokenOptions } from './refresh';
 import type { AuthHandlers, AuthOptions, TokenPayload } from './index';
-import { accountBlock, accountBlockedResponse, warnRevokeFailed, withPassword } from './index';
+import { accountBlock, accountBlockedResponse, warnRevokeFailed, withPassword } from './account';
 import type { OAuthProvider } from './oauth';
-import { getRefreshFromCookies, readPresentedRefreshToken } from './cookies';
+import { readPresentedRefreshToken } from './cookies';
 import { authResponse, signoutResponse } from './response';
 import type { CookieConfig } from './response';
 import { validateCsrfOrigin } from './csrf';
@@ -436,17 +436,7 @@ export function createPostgresAuthHandlers(
       const csrfError = csrfCheck(request, options?.cookies);
       if (csrfError) return csrfError;
 
-      // Read refresh token from JSON body (mobile) or cookie (web SSR)
-      let refreshToken: string | undefined;
-      try {
-        const body = await request.clone().json();
-        refreshToken = body?.refreshToken;
-      } catch {
-        // Empty body is fine — fall through to cookie
-      }
-      if (!refreshToken) {
-        refreshToken = getRefreshFromCookies(request.headers.get('cookie')) ?? undefined;
-      }
+      const refreshToken = await readPresentedRefreshToken(request);
       if (!refreshToken) {
         return Response.json(
           { message: 'refreshToken is required' },

package/src/sql.ts

@@ -385,6 +385,35 @@ WHEN (
 )
 EXECUTE FUNCTION auth.revoke_refresh_tokens_on_user_block();`;
 
+const END_ACCOUNT_SESSIONS = `\
+CREATE OR REPLACE FUNCTION auth.end_account_sessions()
+RETURNS TRIGGER
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = pg_catalog, pg_temp
+AS $$
+DECLARE
+  v_user_id pg_catalog.uuid;
+BEGIN
+  IF TG_OP <> 'UPDATE' OR TG_WHEN <> 'AFTER' OR TG_LEVEL <> 'ROW' THEN
+    RAISE EXCEPTION 'end_account_sessions runs only as an AFTER UPDATE row trigger' USING ERRCODE = '42501';
+  END IF;
+  v_user_id := NEW.id::pg_catalog.uuid;
+  IF OLD.deleted_at IS NULL AND NEW.deleted_at IS NOT NULL THEN
+    UPDATE auth.users SET deleted_at = NEW.deleted_at WHERE id = v_user_id AND deleted_at IS NULL;
+    PERFORM auth.revoke_refresh_tokens(v_user_id);
+    DELETE FROM auth.one_time_tokens WHERE user_id = v_user_id;
+  ELSIF OLD.deleted_at IS NOT NULL AND NEW.deleted_at IS NULL THEN
+    -- A restore brings the account back, never its sessions: the user signs in again.
+    -- It clears only the stamp this account set; an earlier disable stays.
+    UPDATE auth.users SET deleted_at = NULL WHERE id = v_user_id AND deleted_at = OLD.deleted_at;
+  END IF;
+  RETURN NULL;
+END
+$$;
+
+REVOKE EXECUTE ON FUNCTION auth.end_account_sessions FROM PUBLIC;`;
+
 const REVOKE_REFRESH_TOKENS = `\
 CREATE OR REPLACE FUNCTION auth.revoke_refresh_tokens(
   p_user_id UUID,
@@ -1120,7 +1149,7 @@ export function generateCoreSQL(): string {
 export function generateRefreshTokenSQL(): string {
   return [
     ISSUE_REFRESH_TOKEN, '', VALIDATE_REFRESH_TOKEN, '', REVOKE_REFRESH_TOKENS_ON_USER_BLOCK, '',
-    REVOKE_REFRESH_TOKENS, '', SIGN_OUT, '', CLEANUP_REFRESH_TOKENS,
+    REVOKE_REFRESH_TOKENS, '', SIGN_OUT, '', CLEANUP_REFRESH_TOKENS, '', END_ACCOUNT_SESSIONS,
   ]
     .join('\n')
     .trimEnd() + '\n';