@bevel-software/platform-core-backend 0.21.0 → 0.23.0

package/src/modules/auth/account.routes.ts

@@ -6,7 +6,7 @@ import { printable } from '../../shared/printable.js';
 const log = logger('accounts');
 import type { AuthUser } from '@bevel-software/platform-shared';
 import type { AuthService } from './auth.service.js';
-import { AccountAdmissionRefusedError } from './account-admission.js';
+import { AccountAdmissionRefusedError, AccountChangeRefusedError } from './account-admission.js';
 import { erasedAccountId, type IAccountErasureService } from './account-erasure.service.js';
 import type { IAdminAccessService } from '../admin/admin.interface.js';
 import type { UserAccessRemovalService } from '../access/user-access-removal.service.js';
@@ -26,7 +26,7 @@ import './auth.middleware.js'; // Express Request augmentation
  * bootstrap admin (always-admin, see AdminAccessService).
  */
 export function createAccountRoutes(
-  authService: Pick<AuthService, 'listAccounts' | 'createAccount' | 'getUserById'>,
+  authService: Pick<AuthService, 'listAccounts' | 'createAccount' | 'getUserById' | 'deactivate' | 'reactivate'>,
   adminAccess: IAdminAccessService,
   accountErasure: Pick<IAccountErasureService, 'eraseUser'>,
   accessRemoval?: Pick<UserAccessRemovalService, 'report' | 'assertRemovable' | 'remove' | 'filesNaming'>,
@@ -47,17 +47,23 @@ export function createAccountRoutes(
     res.json({ accounts: await authService.listAccounts() });
   });
 
-  // POST /api/admin/accounts { email, name?, password } — create an account
+  // POST /api/admin/accounts { email, name?, password? } — create an account
   // (or reset the password of an existing one; upsert-by-email is deliberate,
-  // see AuthService.createAccount).
+  // see AuthService.createAccount). Without a password the account is for
+  // single sign-on: the person finds it waiting when they first sign in.
   router.post('/admin/accounts', requireAdmin, async (req, res) => {
     const { email, name, password } = req.body as {
       email?: string;
       name?: string;
-      password?: string;
+      password?: unknown;
     };
-    if (!email || !password) {
-      res.status(400).json({ error: 'email and password are required' });
+    if (!email) {
+      res.status(400).json({ error: 'email is required' });
+      return;
+    }
+    // Absent means single sign-on; anything else that is not text is a mistake, not that.
+    if (password !== undefined && typeof password !== 'string') {
+      res.status(400).json({ error: 'password must be a string' });
       return;
     }
     try {
@@ -71,6 +77,56 @@ export function createAccountRoutes(
     }
   });
 
+  // POST /api/admin/accounts/:userId/deactivate — switch an account off. It
+  // keeps its row, history and place in roles and groups; nothing it holds
+  // signs in any more (see AuthService.isActive). An admin's own account is
+  // refused, so whoever does this is still an admin who is on afterwards —
+  // the deployment is never left with no admin able to sign in.
+  router.post('/admin/accounts/:userId/deactivate', requireAdmin, async (req, res) => {
+    const userId = String(req.params.userId);
+    if (userId === req.userId) {
+      res.status(400).json({ error: 'You cannot switch off your own account. Ask another admin.' });
+      return;
+    }
+    try {
+      if (!(await authService.deactivate(userId))) {
+        res.status(404).json({ error: 'No such user' });
+        return;
+      }
+      log.info('account audit:', { action: 'deactivate', actorUserId: req.userId, targetUserId: userId });
+      res.status(204).end();
+    } catch (error) {
+      if (error instanceof AccountChangeRefusedError) {
+        res.status(400).json({ error: error.message });
+        return;
+      }
+      log.error('switching an account off failed:', { err: error });
+      res.status(500).json({ error: 'Could not switch this account off' });
+    }
+  });
+
+  // POST /api/admin/accounts/:userId/reactivate — switch it back on, if the
+  // deployment has room: the admission port is asked, as for a new account
+  // (a host that sells seats answers from its plan; 403 with its words).
+  router.post('/admin/accounts/:userId/reactivate', requireAdmin, async (req, res) => {
+    const userId = String(req.params.userId);
+    try {
+      if (!(await authService.reactivate(userId))) {
+        res.status(404).json({ error: 'No such user' });
+        return;
+      }
+      log.info('account audit:', { action: 'reactivate', actorUserId: req.userId, targetUserId: userId });
+      res.status(204).end();
+    } catch (error) {
+      if (error instanceof AccountAdmissionRefusedError) {
+        res.status(403).json({ error: error.message });
+        return;
+      }
+      log.error('switching an account on failed:', { err: error });
+      res.status(500).json({ error: 'Could not switch this account on' });
+    }
+  });
+
   // GET /api/admin/accounts/:userId/references — how many places in the
   // knowledge base name this account's address (roles, groups, access rules,
   // file grants) and whether removing them is allowed. Feeds the delete

package/src/modules/auth/auth.middleware.ts

@@ -1,5 +1,6 @@
 import type { Request, Response, NextFunction } from 'express';
 import type { AuthService } from './auth.service.js';
+import { AccountDeactivatedError, AuthBackendError } from './account-admission.js';
 
 // Augment Express Request so userId/userEmail are available after auth middleware
 declare global {
@@ -46,8 +47,8 @@ function readAuthCookie(req: Request): string | null {
   return null;
 }
 
-export function createAuthMiddleware(authService: AuthService) {
-  return (req: Request, res: Response, next: NextFunction) => {
+export function createAuthMiddleware(authService: Pick<AuthService, 'resolveSession'>) {
+  return async (req: Request, res: Response, next: NextFunction) => {
     // Bearer is the primary path — every JSON API call in the frontend
     // attaches it via `authFetch`. Cookie is the fallback for transports
     // that can't carry headers (EventSource, image tags), set at login by
@@ -66,13 +67,23 @@ export function createAuthMiddleware(authService: AuthService) {
       return;
     }
 
+    let session: { userId: string; email: string };
     try {
-      const { userId, email } = authService.verifyToken(token);
-      req.userId = userId;
-      req.userEmail = email;
-      next();
-    } catch {
-      res.status(401).json({ error: 'Invalid or expired token' });
+      session = await authService.resolveSession(token);
+    } catch (err) {
+      // The account could not be looked up: not the caller's doing, and a
+      // 401 here would sign every valid session out during an outage.
+      if (err instanceof AuthBackendError) {
+        res.status(500).json({ error: 'Authentication backend unavailable' });
+        return;
+      }
+      // A 401 otherwise, so the app drops the session and shows the login
+      // page; a switched-off account is told why there.
+      res.status(401).json({ error: err instanceof AccountDeactivatedError ? err.message : 'Invalid or expired token' });
+      return;
     }
+    req.userId = session.userId;
+    req.userEmail = session.email;
+    next();
   };
 }

package/src/modules/auth/auth.routes.ts

@@ -5,6 +5,7 @@ const log = logger('auth');
 import type { AuthService } from './auth.service.js';
 import { AUTH_COOKIE_NAME } from './auth.middleware.js'; // also imports Express Request augmentation
 import { FixedWindowRateLimiter } from './rate-limit.js';
+import { AccountDeactivatedError } from './account-admission.js';
 import { canonicalEmail } from '../../shared/email-identity.js';
 
 /**
@@ -113,6 +114,13 @@ export function createAuthRoutes(
       });
       res.json(result);
     } catch (error) {
+      // The password was right and an admin switched the account off: said
+      // as such (only ever after the password is proven, see
+      // `loginWithPassword`), so the person knows whom to ask.
+      if (error instanceof AccountDeactivatedError) {
+        res.status(403).json({ error: error.message });
+        return;
+      }
       const msg = error instanceof Error ? error.message : 'Unknown error';
       log.error('Login error:', { detail: msg });
       res.status(401).json({ error: 'Authentication failed' });

package/src/modules/auth/auth.service.ts

@@ -1,11 +1,14 @@
 import jwt from 'jsonwebtoken';
-import { eq } from 'drizzle-orm';
+import { and, eq, isNotNull, isNull } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
 import { users } from '../database/schema.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import { canonicalEmail, hashEmail } from '../../shared/email-identity.js';
 import {
   AccountAdmissionRefusedError,
+  AccountChangeRefusedError,
+  AccountDeactivatedError,
+  AuthBackendError,
   admitEveryone,
   type AccountProvisionReason,
   type IAccountAdmission,
@@ -16,9 +19,22 @@ import {
   timingSafeStringEqual,
   MIN_PASSWORD_LENGTH,
 } from './password-hash.js';
+import { RECOVERY_BOT_EMAIL } from '../workflow/recovery-bot.js';
+import { DIRECTORY_SYNC_BOT_EMAIL } from '../access/directory-sync-bot.js';
 
 const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
+/**
+ * How long {@link AuthService.isActive} trusts what it last read. Every
+ * request carrying a credential asks, so the answer is kept briefly rather
+ * than read each time; switching an account off or on in THIS process
+ * forgets it at once, and another replica sees the change within this long.
+ */
+const ACTIVE_CACHE_MS = 30_000;
+
+/** The accounts core runs its own work as. Nobody signs in with them, and nobody switches them off. */
+const SYSTEM_ACCOUNT_EMAILS: readonly string[] = [RECOVERY_BOT_EMAIL, DIRECTORY_SYNC_BOT_EMAIL];
+
 /**
  * What every caller is told when it tries to give the deployment admin a
  * stored password — the Account page's own change and an admin's "Set
@@ -85,6 +101,24 @@ export interface AuthConfig {
   loginPasswordEnabled?: boolean;
 }
 
+/** What a sign-in provider tells {@link AuthService.loginWithSso} about the sign-in it hands over. */
+export interface SsoLoginOptions {
+  /**
+   * The provider has itself decided that this person may enter: they were
+   * invited, their address is on a domain the deployment claimed, whatever
+   * its rule is. The domain allow-list (`ALLOWED_EMAIL_DOMAINS`) is then
+   * not applied.
+   *
+   * The allow-list exists for a provider that decides nothing: it is what
+   * stands between "the issuer knows this person" and "this person has an
+   * account here". Applied on top of a provider's own decision it is a
+   * second rule the admin set somewhere else, and the person it refuses was
+   * let in by the first. Default false, so every provider that does not say
+   * otherwise is governed by the allow-list as before.
+   */
+  admittedByProvider?: boolean;
+}
+
 export class AuthService {
   constructor(
     private readonly db: Database,
@@ -111,7 +145,19 @@ export class AuthService {
       .limit(1);
     if (existing) return;
     const verdict = await this.admission.canProvision(normalizedEmail, reason);
-    if (!verdict.ok) throw new AccountAdmissionRefusedError(verdict.message);
+    if (verdict.ok) return;
+    // A first sign-in the port would rather keep than turn away: the person
+    // is put on file, switched off, for an admin to switch on — and is still
+    // refused now, with the port's words. Only for single sign-on, the one
+    // provisioning nobody asked for (see `AccountAdmissionVerdict`).
+    if (verdict.waitForAdmin && reason === 'sso') {
+      await this.db
+        .insert(users)
+        .values({ email: normalizedEmail, name: normalizedEmail.split('@')[0] || normalizedEmail, deactivatedAt: new Date() })
+        .onConflictDoNothing({ target: users.email });
+      throw new AccountAdmissionRefusedError(verdict.message, { waitingForAdmin: true });
+    }
+    throw new AccountAdmissionRefusedError(verdict.message);
   }
 
   /**
@@ -182,6 +228,9 @@ export class AuthService {
         await verifyPassword(provided, await decoyHash());
         throw new Error('Invalid credentials');
       }
+      // Never refused for being switched off: the environment password is
+      // the deployment's way back in, and {@link deactivate} refuses this
+      // account for that reason.
       const defaultName = normalizedEmail.split('@')[0] || normalizedEmail;
       await this.assertAdmitted(normalizedEmail, 'bootstrap');
       const admin = await this.upsertUserByEmail(normalizedEmail, defaultName);
@@ -197,6 +246,9 @@ export class AuthService {
     if (!user?.passwordHash || !matches) {
       throw new Error('Invalid credentials');
     }
+    // Only now, with the password proven: telling a stranger that an address
+    // is switched off would tell them it has an account.
+    if (user.deactivatedAt) throw new AccountDeactivatedError();
     return { token: this.signToken(user.id, user.email), user: this.toClientUser(user) };
   }
 
@@ -206,19 +258,29 @@ export class AuthService {
    * verified. Same upsert-by-email + JWT path as password login. Email is the
    * idempotency key, so a user who first used password login and later signs
    * in via SSO (same email) keeps the same account/id.
+   *
+   * WHO MAY ENTER is decided once per sign-in, by whoever is in a position
+   * to decide it. For the deployment's own provider that is the domain
+   * allow-list: the provider signs in whoever its issuer knows, and nobody
+   * has approved the person. A provider that HAS decided (see
+   * {@link SsoLoginOptions.admittedByProvider}) is governed by its own rule
+   * alone; the allow-list is not laid on top of it. The admission port is
+   * asked either way: that is the plan's answer, not a sign-in rule.
    */
   async loginWithSso(
     email: string,
     name: string,
+    opts: SsoLoginOptions = {},
   ): Promise<{ token: string; user: AuthUser }> {
     const normalizedEmail = canonicalEmail(email ?? '');
     if (!EMAIL_REGEX.test(normalizedEmail)) {
       throw new Error('Sign-in returned an invalid email');
     }
-    this.assertAllowedDomain(normalizedEmail);
+    if (!opts.admittedByProvider) this.assertAllowedDomain(normalizedEmail);
     await this.assertAdmitted(normalizedEmail, 'sso');
     const displayName = (name ?? '').trim() || normalizedEmail.split('@')[0] || normalizedEmail;
     const user = await this.upsertUserByEmail(normalizedEmail, displayName);
+    if (user.deactivatedAt) throw new AccountDeactivatedError();
     return { token: this.signToken(user.id, user.email), user: this.toClientUser(user) };
   }
 
@@ -228,7 +290,13 @@ export class AuthService {
    * account (e.g. one that first arrived via SSO, or a reset for a locked-out
    * user) is deliberate admin behavior, not an error.
    *
-   * The deployment admin is the one target this refuses, for the reason
+   * WITHOUT a password the account is made for single sign-on: the person
+   * signs in through the deployment's provider and finds their account
+   * waiting, already holding its place (a seat, on a host that sells them).
+   * Password sign-in refuses it until a password is set. For an address that
+   * already has an account it changes nothing but an explicitly given name.
+   *
+   * WITH a password, the deployment admin is the one target this refuses, for the reason
    * {@link changePassword} refuses it: that account's password is the
    * environment's, so a stored hash would not replace it but ADD a second
    * credential — one that keeps signing in after `ADMIN_PASSWORD` is rotated,
@@ -239,12 +307,26 @@ export class AuthService {
   async createAccount(
     email: string,
     name: string | undefined,
-    password: string,
+    password?: string,
   ): Promise<AuthUser> {
     const normalizedEmail = canonicalEmail(email ?? '');
     if (!EMAIL_REGEX.test(normalizedEmail)) {
       throw new Error('Invalid email');
     }
+    const suppliedName = (name ?? '').trim();
+    const displayName = suppliedName || normalizedEmail.split('@')[0] || normalizedEmail;
+    if (!password) {
+      await this.assertAdmitted(normalizedEmail, 'admin-create');
+      const [created] = await this.db
+        .insert(users)
+        .values({ email: normalizedEmail, name: displayName })
+        .onConflictDoUpdate({
+          target: users.email,
+          set: suppliedName ? { name: suppliedName, updatedAt: new Date() } : { updatedAt: new Date() },
+        })
+        .returning();
+      return this.toClientUser(created);
+    }
     // Before the policy check, so the refusal names the real reason rather
     // than sending the admin off to pick a longer password first.
     if (this.isEnvAdminEmail(normalizedEmail)) {
@@ -252,8 +334,6 @@ export class AuthService {
     }
     this.assertPasswordPolicy(password);
     await this.assertAdmitted(normalizedEmail, 'admin-create');
-    const suppliedName = (name ?? '').trim();
-    const displayName = suppliedName || normalizedEmail.split('@')[0] || normalizedEmail;
     const passwordHash = await hashPassword(password);
     // One atomic upsert. On conflict (re-provisioning an existing account) an
     // EXPLICITLY supplied name is persisted too; a blank name keeps the
@@ -375,6 +455,10 @@ export class AuthService {
       name: string;
       hasPassword: boolean;
       isEnvAdmin: boolean;
+      /** When an admin switched the account off; null while it is on. */
+      deactivatedAt: Date | null;
+      /** One of the accounts the platform runs its own work as: never switched off, nobody signs in with it. */
+      isSystem: boolean;
       createdAt: Date;
     }>
   > {
@@ -385,6 +469,8 @@ export class AuthService {
       name: row.name,
       hasPassword: row.passwordHash != null,
       isEnvAdmin: this.reportsAsEnvAdmin(row.email),
+      deactivatedAt: row.deactivatedAt,
+      isSystem: SYSTEM_ACCOUNT_EMAILS.includes(row.email),
       createdAt: row.createdAt,
     }));
   }
@@ -416,6 +502,7 @@ export class AuthService {
     await this.assertAdmitted(normalizedEmail, 'embed');
     const displayName = (name ?? '').trim() || normalizedEmail.split('@')[0] || normalizedEmail;
     const user = await this.upsertUserByEmail(normalizedEmail, displayName);
+    if (user.deactivatedAt) throw new AccountDeactivatedError();
     return { id: user.id, email: user.email, name: user.name };
   }
 
@@ -428,6 +515,11 @@ export class AuthService {
     return user;
   }
 
+  /**
+   * The signature and expiry of a session token, and nothing else — whether
+   * its account is still on is {@link resolveSession}'s question. Every
+   * place a session is ACCEPTED goes through that one.
+   */
   verifyToken(token: string): { userId: string; email: string } {
     const decoded = jwt.verify(token, this.config.jwtSecret) as {
       userId: string;
@@ -436,6 +528,114 @@ export class AuthService {
     return { userId: decoded.userId, email: decoded.email };
   }
 
+  /**
+   * A session token that may still be used: signed by us, not expired, and
+   * its account still on. A token outlives a deactivation by up to seven
+   * days, so the signature alone no longer says the bearer may enter.
+   * Throws for an invalid token, {@link AccountDeactivatedError} for one
+   * whose account was switched off.
+   */
+  async resolveSession(token: string): Promise<{ userId: string; email: string }> {
+    const claim = this.verifyToken(token);
+    let active: boolean;
+    try {
+      active = await this.isActive(claim.userId);
+    } catch (err) {
+      // The token is fine; the database is not. Said apart from a refusal, so
+      // an outage is a 500 and not a sign-out (see `AuthBackendError`).
+      throw new AuthBackendError(err);
+    }
+    if (!active) throw new AccountDeactivatedError();
+    return claim;
+  }
+
+  private readonly activeCache = new Map<string, { active: boolean; at: number }>();
+
+  /**
+   * Whether the account behind a credential is on: it exists and no admin
+   * switched it off. Asked for every credential presented that does not
+   * already read the account (a session token, an internal token), so it is
+   * cached for {@link ACTIVE_CACHE_MS}; switching an account off or on in
+   * this process forgets its entry at once.
+   *
+   * A missing row is not on either — an erased account's tokens die with it.
+   *
+   * The deployment admin's account is always on, whatever its row says: its
+   * environment password signs it in regardless (see `loginWithPassword`),
+   * and a session that sign-in mints must then be usable too, or the way
+   * back into a deployment would lead nowhere. {@link deactivate} refuses
+   * the account, but a host may write the column itself.
+   */
+  async isActive(userId: string): Promise<boolean> {
+    const now = Date.now();
+    const hit = this.activeCache.get(userId);
+    if (hit && now - hit.at < ACTIVE_CACHE_MS) return hit.active;
+    const [row] = await this.db
+      .select({ email: users.email, deactivatedAt: users.deactivatedAt })
+      .from(users)
+      .where(eq(users.id, userId))
+      .limit(1);
+    const active = row !== undefined && (!row.deactivatedAt || this.isEnvAdminEmail(row.email ?? ''));
+    this.activeCache.set(userId, { active, at: now });
+    return active;
+  }
+
+  /**
+   * Switch an account off. Its row, history and place in roles and groups
+   * stay; every credential it holds stops being honoured (see
+   * {@link isActive}). Idempotent: an account already off keeps the moment
+   * it was first switched off.
+   *
+   * The deployment admin is refused: the environment password is the way
+   * back into a deployment whose every other admin is gone, and switching
+   * it off would close that door from inside. So are the machine accounts
+   * core runs its own work as. Refusing an admin's own account is the
+   * route's concern, since it knows who is asking.
+   *
+   * Returns false when there is no such account.
+   */
+  async deactivate(userId: string): Promise<boolean> {
+    const [row] = await this.db.select().from(users).where(eq(users.id, userId)).limit(1);
+    if (!row) return false;
+    if (this.isEnvAdminEmail(row.email)) {
+      throw new AccountChangeRefusedError('The deployment admin cannot be switched off: its password in the environment is the way back in.');
+    }
+    if (SYSTEM_ACCOUNT_EMAILS.includes(row.email)) {
+      throw new AccountChangeRefusedError('This account belongs to the platform itself and cannot be switched off.');
+    }
+    await this.db
+      .update(users)
+      .set({ deactivatedAt: new Date(), updatedAt: new Date() })
+      .where(and(eq(users.id, userId), isNull(users.deactivatedAt)));
+    this.activeCache.delete(userId);
+    return true;
+  }
+
+  /**
+   * Switch a deactivated account back on, if the deployment has room for it:
+   * the admission port is asked, as for a new account, because an account
+   * that is on takes the same place. A refusal throws
+   * {@link AccountAdmissionRefusedError} with the port's words. An account
+   * already on is not asked about.
+   *
+   * Returns false when there is no such account.
+   */
+  async reactivate(userId: string): Promise<boolean> {
+    const [row] = await this.db.select().from(users).where(eq(users.id, userId)).limit(1);
+    if (!row) return false;
+    if (!row.deactivatedAt) return true;
+    if (this.admission !== admitEveryone) {
+      const verdict = await this.admission.canProvision(row.email, 'reactivate');
+      if (!verdict.ok) throw new AccountAdmissionRefusedError(verdict.message);
+    }
+    await this.db
+      .update(users)
+      .set({ deactivatedAt: null, updatedAt: new Date() })
+      .where(and(eq(users.id, userId), isNotNull(users.deactivatedAt)));
+    this.activeCache.delete(userId);
+    return true;
+  }
+
   /**
    * Resolve a set of `authorId` hashes back to the app users that produced
    * them. Used by the PR list to display the human who triggered each PR

package/src/modules/auth/oidc-auth-provider.ts

@@ -7,7 +7,7 @@ import type { AuthProviderPlugin } from './auth.routes.js';
 import { AUTH_COOKIE_MAX_AGE_S } from './auth.routes.js';
 import { AUTH_COOKIE_NAME } from './auth.middleware.js';
 import type { AuthService } from './auth.service.js';
-import { AccountAdmissionRefusedError } from './account-admission.js';
+import { AccountAdmissionRefusedError, AccountDeactivatedError } from './account-admission.js';
 import { normalizeIssuerUrl } from '../settings/oidc-check.js';
 
 // Short-lived CSRF state + PKCE verifier for the OAuth round-trip: set before
@@ -325,7 +325,12 @@ export class OidcAuthProvider implements AuthProviderPlugin {
         // screen can say so instead of "try again".
         if (error instanceof AccountAdmissionRefusedError) {
           log.warn('OIDC sign-in refused by the account admission port:', { detail: error.message });
-          fail('admission');
+          fail(error.waitingForAdmin ? 'waiting' : 'admission');
+          return;
+        }
+        if (error instanceof AccountDeactivatedError) {
+          log.warn('OIDC sign-in refused: the account is switched off');
+          fail('deactivated');
           return;
         }
         log.error('OIDC callback error:', { err: error });

package/src/modules/database/core-schema.ts

@@ -1,8 +1,8 @@
 /**
  * CORE platform tables — the git-backed workspace/workflow, auth, access,
- * change requests, locks, the pending-commits queue, the ontology-session
- * touched-set, connection keys, MCP OAuth, and the Secrets Vault. A core-only
- * deployment migrates and runs on exactly these tables.
+ * change requests, locks, the pending-commits queue, connection keys, MCP
+ * OAuth, and the Secrets Vault. A core-only deployment migrates and runs on
+ * exactly these tables.
  *
  * Enterprise-only tables (chat, routines, watchlist, connectors, LLM config,
  * SharePoint/Atlassian links, feedback, upload, kb-revalidation) live in
@@ -37,6 +37,19 @@ export const users = pgTable('users', {
    * backfill would need, and being shown the setup once costs a click.
    */
   onboardingDone: boolean('onboarding_done').default(false).notNull(),
+  /**
+   * When an admin switched this account off; NULL while it is on. A
+   * deactivated account keeps its row, its history and its place in roles
+   * and groups, but nothing it holds is honoured: it cannot sign in, and its
+   * session, connection keys, agent tokens and internal tokens are refused
+   * the next time they are presented (see `AuthService.isActive`). Turning it
+   * back on restores all of them as they were.
+   *
+   * The off switch a host that sells seats needs — a seat is an account that
+   * is on — and the one an admin uses for someone who left without erasing
+   * what they did.
+   */
+  deactivatedAt: timestamp('deactivated_at'),
   createdAt: timestamp('created_at').defaultNow().notNull(),
   updatedAt: timestamp('updated_at').defaultNow().notNull(),
 });
@@ -160,6 +173,18 @@ export const changeRequests = pgTable('change_requests', {
   createdAt: timestamp('created_at').defaultNow().notNull(),
   updatedAt: timestamp('updated_at'),
   closedAt: timestamp('closed_at'),
+  /**
+   * Why a closed request was closed, when something other than a person
+   * closed it. Today the one value is 'repository-replaced': the admin
+   * pointed the deployment at a different knowledge-base repository and chose
+   * to close the requests rather than keep them. Null for every request
+   * closed the ordinary way — by its author, or by the deleted-branch sweep —
+   * so the column reads as "nobody recorded a reason", not as a default.
+   *
+   * The row is never deleted: a replaced repository loses the branches, not
+   * the record of what people asked for.
+   */
+  closedReason: text('closed_reason'),
 }, (t) => ({
   numberUnq: uniqueIndex('change_requests_number_unq').on(t.number),
   // Enforce the "A→B blocks A→B while open" uniqueness rule at the DB level —
@@ -382,30 +407,6 @@ export const secrets = pgTable('secrets', {
   sharedKeyUnq: uniqueIndex('secrets_shared_key_unq').on(t.key).where(sql`${t.userId} is null`),
 }));
 
-/**
- * Ontology-session boundary — the per-session log of which named ontologies a
- * run has TOUCHED (one row per `(session_id, ontology)`). Each agent operation
- * that resolves to a named ontology records a row here (idempotent on the PK).
- *
- * The rule the gate enforces from this set:
- *   - READS are always allowed; they just record the ontology they touched.
- *   - WRITES are allowed only while the session's touched set is a SINGLE named
- *     ontology equal to the write target. Once a session has touched two or
- *     more ontologies (e.g. by reading across them), every write is blocked —
- *     "read across ontologies → you can't write anymore at all."
- *
- * Postgres is the durable source of truth so the boundary holds across a
- * backend restart (an in-memory set would reset and silently un-poison a run).
- * A write-through in-process cache fronts this table for the chatty read path;
- * a cache miss falls back here.
- *
- *   - PK is `(session_id, ontology)` — a set, idempotent on repeat touches.
- *   - `ontology` is the resolved ontology id (e.g. `KnowledgeBase/Product`).
- *     Neutral touches don't record, so they never write a row.
- *   - `touched_at` drives the abandoned-run `sweepOlderThan` backstop; the
- *     primary reclamation is an explicit delete of all of a session's rows at
- *     run end.
- */
 /**
  * OAuth clients dynamically registered by MCP clients (RFC 7591 DCR). When an
  * MCP client (claude.ai, Claude Code) connects to `/api/mcp` without a
@@ -575,6 +576,13 @@ export const agentEvents = pgTable('agent_events', {
   ),
 }));
 
+/**
+ * UNUSED IN THIS RELEASE. It backed the per-session boundary that a deployment
+ * now owns for itself, behind the agent read/write hooks; nothing in this
+ * package reads or writes it any more. The definition stays for ONE release so
+ * that no deployment runs a version in which neither side has the table, and
+ * the NEXT release drops it (see `TODOS.md`). Do not build on it.
+ */
 export const sessionOntologyTouches = pgTable('session_ontology_touches', {
   sessionId: text('session_id').notNull(),
   ontology: text('ontology').notNull(),