@everystack/auth 0.4.9 → 0.4.10

package/CHANGELOG.md

@@ -4,17 +4,26 @@ All notable changes to `@everystack/auth` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
-## [0.4.9] - 2026-10-14
+## [0.4.10] - 2026-10-30
+
+### Added
+
+- accountTrigger ends an account's sessions in its soft-delete transaction
 
 ### Fixed
 
-- break the model and auth import cycles; gate new ones
+- accountTrigger keeps an admin's earlier disable
+- review nits: cap accountTrigger's column at 39 characters; docs state the column the trigger trusts
 
-### Changed
+### Documentation
 
-- share refresh token extraction
+- accountTrigger in the lifecycle guide, the auth README, upgrading and the MCP resource
+
+## [0.4.9] - 2026-10-14
 
-## [Unreleased]
+### Fixed
+
+- break the model and auth import cycles; gate new ones
 
 ### Changed
 

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.9",
+  "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.21"
+    "@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.35",
-    "@everystack/api": "0.4.3"
+    "@everystack/api": "0.4.13",
+    "@everystack/server": "0.4.40"
   },
   "scripts": {
     "test": "jest",

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/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';