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

package/src/modules/audit/audit.routes.ts

@@ -0,0 +1,168 @@
+import express from 'express';
+import { logger } from '../../shared/logging.js';
+import type { IAdminAccessService } from '../admin/admin.interface.js';
+import { TokenNotFoundError } from '../tool-auth/external-api-key.errors.js';
+import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
+import {
+  AuditPrincipalNotFoundError,
+  InvalidCursorError,
+  isUuid,
+  type AuditPrincipalRef,
+  type IAgentAuditService,
+} from './audit.contract.js';
+import { MAX_EVENT_PAGE } from './agent-audit.service.js';
+import '../auth/auth.middleware.js'; // Express Request augmentation (req.userId / req.userEmail)
+
+const log = logger('audit');
+
+const DEFAULT_EVENT_PAGE = 50;
+
+/**
+ * The Audit log's routes, JWT-only (mounted behind the session middleware):
+ *
+ *   GET    /api/audit/principals?scope=me|all           — agents + keys, with owners and event counts
+ *   GET    /api/audit/principals/:kind/:id/events        — one principal's events, newest first, cursor-paged
+ *   DELETE /api/audit/agents/:id                         — revoke an agent (owner or admin)
+ *   DELETE /api/audit/keys/:id                           — revoke a key (owner or admin)
+ *
+ * Everyone may read and revoke their OWN rows; `scope=all` and anyone else's
+ * rows are admins' (per request, through {@link IAdminAccessService}). Both
+ * revokes are recorded as the owner's or an admin's doing, so the owner's
+ * page can say which. Keys keep their existing per-user and admin routes;
+ * the one here exists so the page has a single client for both kinds.
+ */
+export function createAuditRoutes(
+  audit: IAgentAuditService,
+  keys: Pick<IExternalApiKeyService, 'revoke' | 'revokeAny'>,
+  adminAccess: IAdminAccessService,
+): express.Router {
+  const router = express.Router();
+
+  const isAdmin = (req: express.Request) => adminAccess.isAdmin(req.userEmail);
+
+  /** The principal named by the URL, or null when it names none (a malformed id is a not-found, not a 500). */
+  const principalOf = (req: express.Request): AuditPrincipalRef | null => {
+    const kind = String(req.params.kind);
+    const id = String(req.params.id);
+    if ((kind !== 'key' && kind !== 'agent') || !isUuid(id)) return null;
+    return { kind, id };
+  };
+
+  /** Whether the caller may read or revoke `principal`: its owner, or an admin. Null when there is no such principal. */
+  const mayAct = async (req: express.Request, principal: AuditPrincipalRef): Promise<boolean | null> => {
+    const owner = await audit.ownerOf(principal);
+    if (owner === null) return null;
+    if (owner === req.userId) return true;
+    return isAdmin(req);
+  };
+
+  router.get('/audit/principals', async (req, res) => {
+    try {
+      const all = req.query.scope === 'all';
+      if (all && !(await isAdmin(req))) {
+        res.status(403).json({ error: 'Admins only' });
+        return;
+      }
+      const principals = await audit.listPrincipals(all ? 'all' : { userId: req.userId! });
+      res.json({ principals });
+    } catch (err) {
+      log.error('list principals failed:', { err });
+      res.status(500).json({ error: 'Failed to load the audit log' });
+    }
+  });
+
+  router.get('/audit/principals/:kind/:id/events', async (req, res) => {
+    const principal = principalOf(req);
+    if (!principal) {
+      res.status(404).json({ error: 'No such agent or key' });
+      return;
+    }
+    try {
+      const allowed = await mayAct(req, principal);
+      if (allowed === null) {
+        res.status(404).json({ error: 'No such agent or key' });
+        return;
+      }
+      if (!allowed) {
+        res.status(403).json({ error: 'Not yours' });
+        return;
+      }
+      const rawLimit = Number(req.query.limit);
+      const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(rawLimit, MAX_EVENT_PAGE) : DEFAULT_EVENT_PAGE;
+      const before = typeof req.query.before === 'string' && req.query.before ? req.query.before : undefined;
+      res.json(await audit.listEvents(principal, { before, limit }));
+    } catch (err) {
+      if (err instanceof InvalidCursorError) {
+        res.status(400).json({ error: 'Invalid cursor — reload the events from the start' });
+        return;
+      }
+      log.error('list events failed:', { err });
+      res.status(500).json({ error: 'Failed to load events' });
+    }
+  });
+
+  router.delete('/audit/agents/:id', async (req, res) => {
+    const id = String(req.params.id);
+    if (!isUuid(id)) {
+      res.status(404).json({ error: 'No such agent' });
+      return;
+    }
+    try {
+      // Own connection: the owner's revoke, recorded as theirs — an admin
+      // cutting off their OWN agent disconnected it, and the row must not
+      // tell them an admin took it. Anyone else's: only an admin may, and it
+      // is recorded as an admin's so the owner is told. Same order as keys.
+      const owner = await audit.ownerOf({ kind: 'agent', id });
+      if (owner === req.userId) {
+        await audit.revokeConnection(id, 'owner', req.userId!);
+      } else if (await isAdmin(req)) {
+        await audit.revokeConnection(id, 'admin');
+        log.info('revoke audit:', { action: 'admin-revoke-agent', actorUserId: req.userId, connectionId: id });
+      } else {
+        res.status(owner === null ? 404 : 403).json({ error: owner === null ? 'No such agent' : 'Not yours' });
+        return;
+      }
+      res.json({ status: 'revoked' });
+    } catch (err) {
+      if (err instanceof AuditPrincipalNotFoundError) {
+        res.status(404).json({ error: err.message });
+        return;
+      }
+      log.error('revoke agent failed:', { err });
+      res.status(500).json({ error: 'Failed to revoke this agent' });
+    }
+  });
+
+  router.delete('/audit/keys/:id', async (req, res) => {
+    const id = String(req.params.id);
+    if (!isUuid(id)) {
+      res.status(404).json({ error: 'Token not found' });
+      return;
+    }
+    try {
+      const admin = await isAdmin(req);
+      // Own key: the owner's revoke (recorded as theirs). Anyone else's: only
+      // an admin may, and it is recorded as an admin's so the owner is told.
+      const owner = await audit.ownerOf({ kind: 'key', id });
+      if (owner === req.userId) {
+        await keys.revoke(id, req.userId!);
+      } else if (admin) {
+        await keys.revokeAny(id);
+        log.info('revoke audit:', { action: 'admin-revoke-key', actorUserId: req.userId, tokenId: id });
+      } else {
+        res.status(owner === null ? 404 : 403).json({ error: owner === null ? 'Token not found' : 'Not yours' });
+        return;
+      }
+      res.json({ status: 'revoked' });
+    } catch (err) {
+      if (err instanceof TokenNotFoundError) {
+        res.status(404).json({ error: err.message });
+        return;
+      }
+      log.error('revoke key failed:', { err });
+      res.status(500).json({ error: 'Failed to revoke this key' });
+    }
+  });
+
+  return router;
+}

package/src/modules/audit/event-classifier.ts

@@ -0,0 +1,155 @@
+import type { AgentEventKind } from './audit.contract.js';
+
+/**
+ * Pure classification of one UTCP tool call into what the Audit log records:
+ * a hexis capability, a manual's tool, or a skill read. No I/O — the one
+ * catalog it may need (the skill folders) is handed in by the caller, which
+ * asks {@link skillReadPath} first whether that catalog is worth fetching.
+ */
+
+/** What a call is logged as: the kind, the manual (or skill folder), and the bare name. */
+export interface ClassifiedCall {
+  kind: AgentEventKind;
+  manual: string | null;
+  name: string;
+}
+
+/** A skill as the classifier needs it: its name and its repo-relative folder. */
+export interface SkillFolder {
+  name: string;
+  path: string;
+}
+
+export interface ClassifierContext {
+  /** The registered name of the platform's own manual (`KNOWLEDGE_BASE`). */
+  kbManualName: string;
+  /** Registered (rewritten) manual name → catalog name, for pooled MCP manuals. */
+  catalogNames: ReadonlyMap<string, string>;
+}
+
+/**
+ * The platform tools whose `path` argument may point INTO a skill folder — a
+ * read of `Plugins/Sales/rfi/SKILL.md` or of a file bundled beside it is the
+ * agent reading that skill, and is logged as such rather than as a file read.
+ */
+const SKILL_FOLDER_READ_TOOLS: ReadonlySet<string> = new Set(['read_file', 'grep', 'list_files']);
+
+/** The platform tool that loads a skill by name. */
+const GET_SKILL = 'get_skill';
+
+/** `<manual>.<tool>` → its two halves; a bare name has no manual. */
+export function splitUtcpName(utcpName: string): { manual: string; tool: string } {
+  const dot = utcpName.indexOf('.');
+  return dot < 0
+    ? { manual: '', tool: utcpName }
+    : { manual: utcpName.slice(0, dot), tool: utcpName.slice(dot + 1) };
+}
+
+/**
+ * The `path` a platform tool was called with, wherever the caller put it.
+ * Bevel-hosted http tools take their arguments inside a `body` envelope
+ * (`{ body: { path } }`); a caller that flattened it (`{ path }`) is read too.
+ */
+function pathArgument(args: Record<string, unknown>): string | null {
+  const body = args.body;
+  const inner = body && typeof body === 'object' ? (body as Record<string, unknown>).path : undefined;
+  const candidate = typeof inner === 'string' ? inner : args.path;
+  return typeof candidate === 'string' && candidate.length > 0 ? candidate : null;
+}
+
+/** The `name` a `get_skill` call asked for, from the envelope or flattened. */
+function skillNameArgument(args: Record<string, unknown>): string | null {
+  const body = args.body;
+  const inner = body && typeof body === 'object' ? (body as Record<string, unknown>).name : undefined;
+  const candidate = typeof inner === 'string' ? inner : args.name;
+  return typeof candidate === 'string' && candidate.length > 0 ? candidate : null;
+}
+
+/**
+ * When a platform read names a path, the path — the signal that the caller
+ * should fetch the skill catalog before classifying (a folder match turns
+ * the read into a skill event). Null for every other call, so the catalog is
+ * never fetched for a `notion.search` or a `write_file`.
+ */
+export function skillReadPath(utcpName: string, args: Record<string, unknown>, kbManualName: string): string | null {
+  const { manual, tool } = splitUtcpName(utcpName);
+  if (manual !== kbManualName) return null;
+  if (tool === GET_SKILL) return skillNameArgument(args) === null ? null : '';
+  if (!SKILL_FOLDER_READ_TOOLS.has(tool)) return null;
+  return pathArgument(args);
+}
+
+/**
+ * The path as segments, resolved: forward slashes, `.` dropped, `..` taken
+ * back a segment, no empty segments — so two spellings of one place compare
+ * equal, and a path that climbs OUT of a folder is never matched to it. A
+ * path that climbs above its own start has no place at all and resolves to
+ * the empty string, which matches nothing. (The file tools refuse `..`
+ * outright; the log must still not credit a refused read to a skill.)
+ */
+function normalizePath(p: string): string {
+  const out: string[] = [];
+  for (const segment of p.replace(/\\/g, '/').split('/')) {
+    if (segment === '' || segment === '.') continue;
+    if (segment === '..') {
+      if (out.length === 0) return '';
+      out.pop();
+      continue;
+    }
+    out.push(segment);
+  }
+  return out.join('/');
+}
+
+/**
+ * The skill whose folder contains `path`, if any. Matched on a segment
+ * boundary anywhere in the path — a caller may spell the path from the
+ * repository root (`Plugins/Sales/rfi/SKILL.md`) or from one level above it
+ * (`knowledge-base/Plugins/Sales/rfi/SKILL.md`), and both are that skill.
+ * The longest folder wins, so a skill nested under another's folder is not
+ * mistaken for its parent.
+ */
+export function skillContaining(path: string, skills: readonly SkillFolder[]): SkillFolder | null {
+  const normalized = normalizePath(path);
+  if (!normalized) return null;
+  const haystack = `/${normalized}/`;
+  let best: SkillFolder | null = null;
+  for (const skill of skills) {
+    const folder = normalizePath(skill.path);
+    if (!folder) continue;
+    if (haystack.includes(`/${folder}/`) && (!best || folder.length > normalizePath(best.path).length)) {
+      best = skill;
+    }
+  }
+  return best;
+}
+
+/**
+ * Classify one call. `skills` is the catalog when {@link skillReadPath} asked
+ * for it and the caller could fetch it; null otherwise (the read is then
+ * logged as the capability it is, which is the honest fallback).
+ */
+export function classifyToolCall(
+  utcpName: string,
+  args: Record<string, unknown>,
+  ctx: ClassifierContext,
+  skills: readonly SkillFolder[] | null,
+): ClassifiedCall {
+  const { manual, tool } = splitUtcpName(utcpName);
+  // A meta-tool (`call_tool_chain`, `list_tools`, …) has no manual: the platform's own.
+  if (manual === '' || manual === ctx.kbManualName) {
+    if (tool === GET_SKILL) {
+      const name = skillNameArgument(args);
+      if (name) {
+        const folder = skills?.find((s) => s.name === name)?.path ?? null;
+        return { kind: 'skill', manual: folder, name };
+      }
+    } else if (SKILL_FOLDER_READ_TOOLS.has(tool) && skills) {
+      const path = pathArgument(args);
+      const skill = path ? skillContaining(path, skills) : null;
+      if (skill) return { kind: 'skill', manual: skill.path, name: skill.name };
+    }
+    return { kind: 'capability', manual: null, name: tool };
+  }
+  return { kind: 'tool', manual: ctx.catalogNames.get(manual) ?? manual, name: tool };
+}

package/src/modules/audit/index.ts

@@ -0,0 +1,14 @@
+export * from './audit.contract.js';
+export { AgentAuditService, MAX_EVENT_PAGE, retentionDaysFrom } from './agent-audit.service.js';
+export { createAgentRestAuditMiddleware } from './agent-rest-audit.middleware.js';
+export { createAuditRoutes } from './audit.routes.js';
+export { RequestAudit } from './request-audit.js';
+export {
+  classifyToolCall,
+  skillContaining,
+  skillReadPath,
+  splitUtcpName,
+  type ClassifiedCall,
+  type ClassifierContext,
+  type SkillFolder,
+} from './event-classifier.js';

package/src/modules/audit/request-audit.ts

@@ -0,0 +1,141 @@
+import type { CodeModeUtcpClient } from '@utcp/code-mode';
+import { logger } from '../../shared/logging.js';
+import type { AgentEventOutcome, AuditPrincipalRef, IAgentEventRecorder } from './audit.contract.js';
+import {
+  classifyToolCall,
+  skillReadPath,
+  type ClassifiedCall,
+  type ClassifierContext,
+  type SkillFolder,
+} from './event-classifier.js';
+
+const log = logger('audit');
+
+/**
+ * The Audit log's view of ONE MCP request: who is calling (the user and the
+ * key or agent connection the request arrived through), and how to name what
+ * they call. The MCP proxy creates one per request that has a principal and
+ * routes every call through it; a request with none (a browser JWT, an
+ * internal token minted before connections existed) gets no instance and
+ * records nothing.
+ *
+ * Holds nothing that outlives the request. The skill catalog it may need to
+ * tell a skill read from a file read is fetched at most once, and only when
+ * a platform read names a path.
+ */
+export class RequestAudit {
+  private skills: Promise<readonly SkillFolder[] | null> | undefined;
+
+  constructor(
+    private readonly recorder: IAgentEventRecorder,
+    private readonly userId: string,
+    private readonly principal: AuditPrincipalRef,
+    private readonly ctx: {
+      kbManualName: string;
+      /** Read at classification time — the surface (and its catalog names) is built lazily. */
+      catalogNames: () => ReadonlyMap<string, string>;
+      /** The caller's skill catalog, for telling a skill read from a file read. */
+      loadSkills: () => Promise<readonly SkillFolder[]>;
+    },
+  ) {}
+
+  /** Record one already-classified call. Never throws. */
+  emit(call: ClassifiedCall, outcome: AgentEventOutcome, durationMs: number | null): void {
+    try {
+      this.recorder.record({
+        userId: this.userId,
+        principal: this.principal,
+        kind: call.kind,
+        manual: call.manual,
+        name: call.name,
+        outcome,
+        durationMs,
+      });
+    } catch (err) {
+      log.warn('recording an agent event failed:', { err });
+    }
+  }
+
+  /** What a UTCP call is logged as — fetching the skill catalog first when the call might be a skill read. */
+  async classify(utcpName: string, args: Record<string, unknown>): Promise<ClassifiedCall> {
+    const ctx: ClassifierContext = { kbManualName: this.ctx.kbManualName, catalogNames: this.ctx.catalogNames() };
+    const wantsSkills = skillReadPath(utcpName, args, ctx.kbManualName) !== null;
+    const skills = wantsSkills ? await this.skillCatalog() : null;
+    return classifyToolCall(utcpName, args, ctx, skills);
+  }
+
+  /**
+   * Run a UTCP call and record it: `error` when it throws or `isError` says
+   * the result is one, `ok` otherwise. The result (or the throw) reaches the
+   * caller unchanged — recording is a side effect, never a filter.
+   *
+   * The call starts FIRST and is classified alongside: naming a read may cost
+   * a loopback fetch of the skill catalog, and that is the log's business,
+   * not the tool's — a tool result never waits on its own bookkeeping.
+   */
+  async call<T>(
+    utcpName: string,
+    args: Record<string, unknown>,
+    run: () => Promise<T>,
+    isError: (result: T) => boolean,
+  ): Promise<T> {
+    const started = performance.now();
+    const classified = this.classify(utcpName, args);
+    try {
+      const result = await run();
+      const duration = elapsed(started);
+      this.emit(await classified, isError(result) ? 'error' : 'ok', duration);
+      return result;
+    } catch (err) {
+      const duration = elapsed(started);
+      this.emit(await classified, 'error', duration);
+      throw err;
+    }
+  }
+
+  /** A call refused before it ran, because the caller's sign-in for its manual is missing. */
+  async denied(utcpName: string, args: Record<string, unknown>): Promise<void> {
+    this.emit(await this.classify(utcpName, args), 'denied', null);
+  }
+
+  /**
+   * Record every tool call made from INSIDE `call_tool_chain`: the chain
+   * bridges each in-isolate tool function to `client.callTool`, so wrapping
+   * that one entry point catches them all. Installed after the downstream
+   * routing wrapper so the timing covers the pool lease and any retry too.
+   * The direct MCP path (`callToolStreaming`) is deliberately NOT wrapped —
+   * the proxy's tool handler records those itself, with the result's
+   * `isError` in hand.
+   */
+  instrumentChainCalls(client: CodeModeUtcpClient): void {
+    const callTool = client.callTool.bind(client);
+    client.callTool = (toolName: string, toolArgs: Record<string, unknown>) =>
+      this.call(toolName, toolArgs, () => callTool(toolName, toolArgs), isErrorShaped);
+  }
+
+  private skillCatalog(): Promise<readonly SkillFolder[] | null> {
+    // A failed fetch is remembered as "no catalog" for the rest of the
+    // request: the read is then logged as a capability, and one hiccup does
+    // not cost a loopback round-trip per subsequent call.
+    this.skills ??= this.ctx.loadSkills().catch((err) => {
+      log.warn('skill catalog unavailable for audit classification:', { err });
+      return null;
+    });
+    return this.skills;
+  }
+}
+
+function elapsed(started: number): number {
+  return Math.max(0, Math.round(performance.now() - started));
+}
+
+/**
+ * A chain-internal result that is the tool saying it failed. A downstream
+ * MCP server answers a failed call with `{ isError: true, content }` as a
+ * VALUE (the UTCP mcp protocol hands it through rather than throwing), and
+ * the direct path records that as an error — so must the chain path, or the
+ * same failure would read `ok` inside a chain and `error` outside one.
+ */
+function isErrorShaped(result: unknown): boolean {
+  return typeof result === 'object' && result !== null && (result as { isError?: unknown }).isError === true;
+}

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

@@ -3,6 +3,7 @@ import express from 'express';
 import type { Server } from 'node:http';
 import { createAccountRoutes } from '../account.routes.js';
 import { AuthService } from '../auth.service.js';
+import { AccountAdmissionRefusedError } from '../account-admission.js';
 import { hashPassword } from '../password-hash.js';
 import type { Database } from '../../database/connection.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
@@ -145,6 +146,20 @@ describe('account routes — admin gate', () => {
     expect(accountErasure.eraseUser).toHaveBeenLastCalledWith('u2');
   });
 
+  it('an account the admission port refuses → 403 carrying the port\'s own words', async () => {
+    const base = await listen(makeApp({ admin: true }));
+    vi.mocked(authService.createAccount).mockRejectedValueOnce(
+      new AccountAdmissionRefusedError('No seat left on this plan'),
+    );
+    const refused = await fetch(`${base}/api/admin/accounts`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email: 'b@example.com', password: 'long-enough-pw' }),
+    });
+    expect(refused.status).toBe(403);
+    expect(((await refused.json()) as { error: string }).error).toBe('No seat left on this plan');
+  });
+
   it('erasure failure → 500 with a generic body (no internal error text)', async () => {
     const base = await listen(makeApp({ admin: true }));
     vi.mocked(accountErasure.eraseUser).mockRejectedValueOnce(

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

@@ -2,6 +2,7 @@ import { describe, expect, it, vi } from 'vitest';
 import type { Database } from '../../database/connection.js';
 import type { CoreConfig } from '../../../core-config.js';
 import { AuthService } from '../auth.service.js';
+import { AccountAdmissionRefusedError, type IAccountAdmission } from '../account-admission.js';
 import { hashPassword, verifyPassword } from '../password-hash.js';
 
 /**
@@ -605,3 +606,62 @@ describe('AuthService — the SSO domain allow-list', () => {
     expect(out.user.email).toBe('root@gmail.com');
   });
 });
+
+describe('AuthService — the account admission port', () => {
+  const refusing: IAccountAdmission = {
+    canProvision: async () => ({ ok: false, message: 'No seat left on this plan' }),
+  };
+  const asked: Array<[string, string]> = [];
+  const recording: IAccountAdmission = {
+    canProvision: async (email, reason) => {
+      asked.push([email, reason]);
+      return { ok: true };
+    },
+  };
+
+  it('refuses a first SSO sign-in the port turns down, and inserts nothing', async () => {
+    // The lookup for an existing row answers empty: this is a new address (once per attempt).
+    const { db } = makeFakeDb([[], []]);
+    const svc = new AuthService(db, makeConfig(), refusing);
+    await expect(svc.loginWithSso('new@example.com', 'New')).rejects.toBeInstanceOf(AccountAdmissionRefusedError);
+    await expect(svc.loginWithSso('new@example.com', 'New')).rejects.toThrow('No seat left on this plan');
+    expect(vi.mocked(db.insert)).not.toHaveBeenCalled();
+  });
+
+  it('refuses an admin creating an account the port turns down, before any hash is stored', async () => {
+    const { db } = makeFakeDb([[]]);
+    const svc = new AuthService(db, makeConfig(), refusing);
+    await expect(svc.createAccount('new@example.com', 'New', 'a-long-enough-password')).rejects.toThrow(
+      'No seat left on this plan',
+    );
+    expect(vi.mocked(db.insert)).not.toHaveBeenCalled();
+  });
+
+  it('never asks about an address that already has an account, so a refusal cannot lock anyone out', async () => {
+    asked.length = 0;
+    const { db } = makeFakeDb([[{ id: ROW.id }], [ROW]]);
+    const svc = new AuthService(db, makeConfig(), refusing);
+    const { user } = await svc.loginWithSso('alice@example.com', 'Alice');
+    expect(user.email).toBe('alice@example.com');
+  });
+
+  it('names the path a new account arrives by, and admits when the port says so', async () => {
+    asked.length = 0;
+    const { db } = makeFakeDb([[], [ROW], [], [ROW]]);
+    const svc = new AuthService(db, makeConfig(), recording);
+    await svc.loginWithSso('alice@example.com', 'Alice');
+    await svc.createAccount('alice@example.com', 'Alice', 'a-long-enough-password');
+    expect(asked).toEqual([
+      ['alice@example.com', 'sso'],
+      ['alice@example.com', 'admin-create'],
+    ]);
+  });
+
+  it('admits everyone by default, without a lookup', async () => {
+    const { db } = makeFakeDb([[ROW]]);
+    const svc = new AuthService(db, makeConfig());
+    const { user } = await svc.loginWithSso('alice@example.com', 'Alice');
+    expect(user.email).toBe('alice@example.com');
+    expect(vi.mocked(db.select)).not.toHaveBeenCalled();
+  });
+});

package/src/modules/auth/account-admission.ts

@@ -0,0 +1,44 @@
+/**
+ * Whether a NEW account may be provisioned on this deployment, asked before
+ * the row is inserted. The one seam a host that sells seats needs: core
+ * admits everyone, and a cloud overlay answers from its plan without
+ * forking any sign-in path.
+ *
+ * Asked only for an address with no account yet. An existing user's sign-in
+ * is never a provisioning, so a refusal can never lock out someone who is
+ * already in.
+ */
+export type AccountProvisionReason =
+  /** A first sign-in through single sign-on, which provisions on its own. */
+  | 'sso'
+  /** An admin creating an account from the app. */
+  | 'admin-create'
+  /** The deployment owner's first password sign-in, which creates their row. */
+  | 'bootstrap'
+  /** A verified identity from an embedding surface that needs a row without a session. */
+  | 'embed';
+
+export type AccountAdmissionVerdict = { ok: true } | { ok: false; message: string };
+
+export interface IAccountAdmission {
+  canProvision(email: string, reason: AccountProvisionReason): Promise<AccountAdmissionVerdict>;
+}
+
+/** Core's default: every account is admitted. */
+export const admitEveryone: IAccountAdmission = {
+  canProvision: async () => ({ ok: true }),
+};
+
+/**
+ * The port said no. Carries the port's own words, which the routes surface
+ * to the person or admin who asked, and a 403: the identity was fine, the
+ * deployment has no place for it.
+ */
+export class AccountAdmissionRefusedError extends Error {
+  readonly status = 403;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'AccountAdmissionRefusedError';
+  }
+}

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

@@ -6,6 +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 { 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';
@@ -64,7 +65,9 @@ export function createAccountRoutes(
       res.status(201).json(user);
     } catch (error) {
       const msg = error instanceof Error ? error.message : 'Unknown error';
-      res.status(400).json({ error: msg });
+      // The deployment has no place for the account (a seat limit, say): the
+      // port's own words, as a refusal rather than a malformed request.
+      res.status(error instanceof AccountAdmissionRefusedError ? 403 : 400).json({ error: msg });
     }
   });