@bevel-software/platform-core-backend 0.20.0 → 0.22.0

package/src/modules/agent-instructions/__tests__/read-preamble.test.ts

@@ -6,6 +6,7 @@ import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { readAgentPreamble, type PreambleWorkspace } from '../read-preamble.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /** The one disk, as production wires it. */
 const disk = new NodeFs();
@@ -42,7 +43,7 @@ describe('readAgentPreamble', () => {
   it('reads the default branch copy at <kbDirName>/mcp-description.md, creating the workspace first', async () => {
     await fs.writeFile(path.join(wsDir, KB, 'mcp-description.md'), 'Acme.\n', 'utf8');
     const ws = workspace();
-    expect(await readAgentPreamble(ws, KB, disk)).toBe('Acme.\n');
+    expect(await readAgentPreamble(ws, testKbContext({ kbDirName: KB }), disk)).toBe('Acme.\n');
     expect(ws.getOrCreateForBranch).toHaveBeenCalledWith(DEFAULT_BRANCH);
     expect(ws.getWorkspacePath).toHaveBeenCalledWith(workspaceIdForBranch(DEFAULT_BRANCH));
   });
@@ -50,19 +51,19 @@ describe('readAgentPreamble', () => {
   it("spells the path with the deployment's own KB dir name", async () => {
     await fs.mkdir(path.join(wsDir, 'kb'), { recursive: true });
     await fs.writeFile(path.join(wsDir, 'kb', 'mcp-description.md'), 'Renamed root.', 'utf8');
-    expect(await readAgentPreamble(workspace(), 'kb', disk)).toBe('Renamed root.');
-    expect(await readAgentPreamble(workspace(), KB, disk)).toBeNull(); // the default-named root has none
+    expect(await readAgentPreamble(workspace(), testKbContext({ kbDirName: 'kb' }), disk)).toBe('Renamed root.');
+    expect(await readAgentPreamble(workspace(), testKbContext({ kbDirName: KB }), disk)).toBeNull(); // the default-named root has none
   });
 
   it('a file that is not there is an absence, not a fault', async () => {
-    expect(await readAgentPreamble(workspace(), KB, disk)).toBeNull();
+    expect(await readAgentPreamble(workspace(), testKbContext({ kbDirName: KB }), disk)).toBeNull();
   });
 
   it('refuses a symlink: the secret it points at is never read, and it is not an absence either', async () => {
     const secret = path.join(root, 'secret.txt');
     await fs.writeFile(secret, 'DATABASE_URL=postgres://…', 'utf8');
     await fs.symlink(secret, path.join(wsDir, KB, 'mcp-description.md'));
-    await expect(readAgentPreamble(workspace(), KB, disk)).rejects.toThrow(/symlink, not a regular file/);
+    await expect(readAgentPreamble(workspace(), testKbContext({ kbDirName: KB }), disk)).rejects.toThrow(/symlink, not a regular file/);
   });
 
   it('refuses a repository folder reached through a link — the whole path must be its own, not only the file', async () => {
@@ -72,7 +73,7 @@ describe('readAgentPreamble', () => {
     await fs.writeFile(path.join(elsewhere, 'mcp-description.md'), 'Not the repository.', 'utf8');
     await fs.rm(path.join(wsDir, KB), { recursive: true });
     await fs.symlink(elsewhere, path.join(wsDir, KB), process.platform === 'win32' ? 'junction' : 'dir');
-    await expect(readAgentPreamble(workspace(), KB, disk)).rejects.toThrow(/through a symlink/);
+    await expect(readAgentPreamble(workspace(), testKbContext({ kbDirName: KB }), disk)).rejects.toThrow(/through a symlink/);
   });
 
   it('reads through a link ABOVE the workspace — a mounted volume is the operator\'s, not the repository\'s', async () => {
@@ -81,12 +82,12 @@ describe('readAgentPreamble', () => {
     await fs.symlink(wsDir, mount, process.platform === 'win32' ? 'junction' : 'dir');
     const ws = workspace();
     ws.getWorkspacePath.mockImplementation(async () => mount);
-    expect(await readAgentPreamble(ws, KB, disk)).toBe('Acme.\n');
+    expect(await readAgentPreamble(ws, testKbContext({ kbDirName: KB }), disk)).toBe('Acme.\n');
   });
 
   it('refuses a directory squatting the name', async () => {
     await fs.mkdir(path.join(wsDir, KB, 'mcp-description.md'));
-    await expect(readAgentPreamble(workspace(), KB, disk)).rejects.toThrow(/directory, not a regular file/);
+    await expect(readAgentPreamble(workspace(), testKbContext({ kbDirName: KB }), disk)).rejects.toThrow(/directory, not a regular file/);
   });
 
   it('a KB directory that is a regular file is an ABSENT preamble, the shared rule for "nothing can be there"', async () => {
@@ -96,7 +97,7 @@ describe('readAgentPreamble', () => {
     // squatted this way is the startup phase's to refuse, loudly, once.
     await fs.rm(path.join(wsDir, KB), { recursive: true });
     await fs.writeFile(path.join(wsDir, KB), 'not a directory', 'utf8');
-    expect(await readAgentPreamble(workspace(), KB, disk)).toBeNull();
+    expect(await readAgentPreamble(workspace(), testKbContext({ kbDirName: KB }), disk)).toBeNull();
   });
 
   it('an lstat that fails for any reason but absence throws, never an empty preamble', async () => {
@@ -110,7 +111,7 @@ describe('readAgentPreamble', () => {
         ? Promise.reject(Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' }))
         : (real as (p: string) => Promise<unknown>).call(fs, p)) as never);
     try {
-      await expect(readAgentPreamble(workspace(), KB, disk)).rejects.toMatchObject({ code: 'EACCES' });
+      await expect(readAgentPreamble(workspace(), testKbContext({ kbDirName: KB }), disk)).rejects.toMatchObject({ code: 'EACCES' });
     } finally {
       spy.mockRestore();
     }
@@ -121,7 +122,7 @@ describe('readAgentPreamble', () => {
     const file = path.join(wsDir, KB, 'mcp-description.md');
     await fs.writeFile(file, 'Acme.', 'utf8');
     await fs.chmod(file, 0o000); // the lstat still passes; the open is what fails
-    await expect(readAgentPreamble(workspace(), KB, disk)).rejects.toMatchObject({ code: 'EACCES' });
+    await expect(readAgentPreamble(workspace(), testKbContext({ kbDirName: KB }), disk)).rejects.toMatchObject({ code: 'EACCES' });
   });
 
   it('a workspace that cannot be located throws too', async () => {
@@ -130,6 +131,6 @@ describe('readAgentPreamble', () => {
     ws.getWorkspacePath.mockImplementation(async () => {
       throw eio;
     });
-    await expect(readAgentPreamble(ws, KB, disk)).rejects.toBe(eio);
+    await expect(readAgentPreamble(ws, testKbContext({ kbDirName: KB }), disk)).rejects.toBe(eio);
   });
 });

package/src/modules/agent-instructions/read-preamble.ts

@@ -1,7 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
-import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import { isAbsence, type IFsProbe } from '../../shared/fs.contract.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { PREAMBLE_FILE } from './compose.js';
@@ -43,11 +42,17 @@ export type PreambleWorkspace = Pick<WorkspaceService, 'getOrCreateForBranch' |
  */
 export async function readAgentPreamble(
   workspace: PreambleWorkspace,
-  kbDirName: string,
+  kb: Pick<KbContext, 'kbDirName' | 'defaultBranch' | 'defaultWorkspaceId'>,
   disk: IFsProbe,
 ): Promise<string | null> {
-  await workspace.getOrCreateForBranch(DEFAULT_BRANCH);
-  const wsDir = await workspace.getWorkspacePath(workspaceIdForBranch(DEFAULT_BRANCH));
+  const { kbDirName, defaultBranch } = kb;
+  const notRegular = (kind: string): Error =>
+    new Error(
+      `${PREAMBLE_FILE} on branch "${defaultBranch}" is a ${kind}, not a regular file at its own place; ` +
+        'refusing to read it. Replace it with a plain markdown file in the repository folder.',
+    );
+  await workspace.getOrCreateForBranch(defaultBranch);
+  const wsDir = await workspace.getWorkspacePath(kb.defaultWorkspaceId());
   const abs = path.join(wsDir, kbDirName, PREAMBLE_FILE);
 
   const found = await disk.lstatOrNull(abs);
@@ -79,10 +84,3 @@ export async function readAgentPreamble(
     await handle.close();
   }
 }
-
-function notRegular(kind: string): Error {
-  return new Error(
-    `${PREAMBLE_FILE} on branch "${DEFAULT_BRANCH}" is a ${kind}, not a regular file at its own place; ` +
-      'refusing to read it. Replace it with a plain markdown file in the repository folder.',
-  );
-}

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';
 
 /**
@@ -573,6 +574,44 @@ describe('AuthService — the SSO domain allow-list', () => {
     ).rejects.toThrow(/domain is not allowed/i);
   });
 
+  /**
+   * One rule per sign-in. A provider that decided for itself who may enter
+   * (an invitation, a claimed domain) is not overruled by a list the admin
+   * set for the deployment's own provider; the plan still has its say.
+   */
+  it('is not laid on top of a provider that decided admission itself', async () => {
+    const { db } = makeFakeDb([[{ ...ROW, email: 'invited@gmail.com', name: 'Invited' }]]);
+    const out = await new AuthService(db, config).loginWithSso('invited@gmail.com', 'Invited', {
+      admittedByProvider: true,
+    });
+    expect(out.user.email).toBe('invited@gmail.com');
+  });
+
+  it('still asks the plan about someone the provider admitted', async () => {
+    const asked: Array<[string, string]> = [];
+    const plan: IAccountAdmission = {
+      canProvision: async (email, reason) => {
+        asked.push([email, reason]);
+        return { ok: false, message: 'No seat left on this plan' };
+      },
+    };
+    const { db } = makeFakeDb([[]]);
+    await expect(
+      new AuthService(db, config, plan).loginWithSso('invited@gmail.com', 'Invited', { admittedByProvider: true }),
+    ).rejects.toBeInstanceOf(AccountAdmissionRefusedError);
+    expect(asked).toEqual([['invited@gmail.com', 'sso']]);
+    expect(vi.mocked(db.insert)).not.toHaveBeenCalled();
+  });
+
+  it('governs a provider that says nothing, or says it did not decide', async () => {
+    for (const opts of [undefined, {}, { admittedByProvider: false }]) {
+      const { db } = makeFakeDb([[]]);
+      await expect(new AuthService(db, config).loginWithSso('someone@gmail.com', 'Someone', opts)).rejects.toThrow(
+        /domain is not allowed/i,
+      );
+    }
+  });
+
   it('admits a subdomain of an allowed domain', async () => {
     const { db } = makeFakeDb([[{ ...ROW, email: 'eu@eu.bevel.software', name: 'EU' }]]);
     const out = await new AuthService(db, config).loginWithSso('eu@eu.bevel.software', 'EU');
@@ -605,3 +644,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 });
     }
   });
 

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

@@ -1,10 +1,15 @@
 import jwt from 'jsonwebtoken';
 import { eq } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
-import type { CoreConfig } from '../../core-config.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,
+  admitEveryone,
+  type AccountProvisionReason,
+  type IAccountAdmission,
+} from './account-admission.js';
 import {
   hashPassword,
   verifyPassword,
@@ -80,12 +85,53 @@ 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,
     private readonly config: AuthConfig,
+    /**
+     * Whether a new account may be provisioned — see `account-admission.ts`.
+     * Core admits everyone; a host that sells seats answers from its plan.
+     */
+    private readonly admission: IAccountAdmission = admitEveryone,
   ) {}
 
+  /**
+   * Ask the admission port before an account is CREATED: an address that
+   * already has a row is never asked about, so a refusal cannot lock an
+   * existing user out. The default port is not asked at all, which also
+   * spares the lookup.
+   */
+  private async assertAdmitted(normalizedEmail: string, reason: AccountProvisionReason): Promise<void> {
+    if (this.admission === admitEveryone) return;
+    const [existing] = await this.db
+      .select({ id: users.id })
+      .from(users)
+      .where(eq(users.email, normalizedEmail))
+      .limit(1);
+    if (existing) return;
+    const verdict = await this.admission.canProvision(normalizedEmail, reason);
+    if (!verdict.ok) throw new AccountAdmissionRefusedError(verdict.message);
+  }
+
   /**
    * Password login. Two credential sources, in order:
    *
@@ -155,6 +201,7 @@ export class AuthService {
         throw new Error('Invalid credentials');
       }
       const defaultName = normalizedEmail.split('@')[0] || normalizedEmail;
+      await this.assertAdmitted(normalizedEmail, 'bootstrap');
       const admin = await this.upsertUserByEmail(normalizedEmail, defaultName);
       return { token: this.signToken(admin.id, admin.email), user: this.toClientUser(admin) };
     }
@@ -177,16 +224,26 @@ 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);
     return { token: this.signToken(user.id, user.email), user: this.toClientUser(user) };
@@ -221,6 +278,7 @@ export class AuthService {
       throw new Error(ENV_ADMIN_PASSWORD_REFUSAL);
     }
     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);
@@ -382,6 +440,7 @@ export class AuthService {
   ): Promise<{ id: string; email: string; name: string } | null> {
     const normalizedEmail = canonicalEmail(email ?? '');
     if (!EMAIL_REGEX.test(normalizedEmail)) return null;
+    await this.assertAdmitted(normalizedEmail, 'embed');
     const displayName = (name ?? '').trim() || normalizedEmail.split('@')[0] || normalizedEmail;
     const user = await this.upsertUserByEmail(normalizedEmail, displayName);
     return { id: user.id, email: user.email, name: user.name };

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

@@ -7,6 +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 { normalizeIssuerUrl } from '../settings/oidc-check.js';
 
 // Short-lived CSRF state + PKCE verifier for the OAuth round-trip: set before
@@ -319,6 +320,14 @@ export class OidcAuthProvider implements AuthProviderPlugin {
         });
         res.redirect(`${publicFrontendUrl}/auth/oidc/callback#token=${encodeURIComponent(token)}`);
       } catch (error) {
+        // A refused provisioning is not a failed sign-in: the identity was
+        // verified, the deployment has no seat for it. Named so the login
+        // 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');
+          return;
+        }
         log.error('OIDC callback error:', { err: error });
         fail('auth');
       }

package/src/modules/connection-probe/connection-probe.service.ts

@@ -399,6 +399,12 @@ export class ConnectionProbeService implements IConnectionProbeService {
   constructor(
     private readonly toolManualService: IToolManualService,
     private readonly secretsVault: ISecretsVaultService,
+    /**
+     * The scope this knowledge base's vault was registered under with the
+     * UTCP variable loader, so a probe's client resolves the caller's secrets
+     * from it — see `secrets-variable-loader.ts`. Default: the single one.
+     */
+    private readonly secretsScope?: string,
   ) {}
 
   async probe(userId: string, userEmail: string, slug: string): Promise<ProbeVerdict | null> {
@@ -556,7 +562,7 @@ export class ConnectionProbeService implements IConnectionProbeService {
       // loader, which is exactly the credential under test.
       const config = new UtcpClientConfigSerializer().validateDict({
         variables: {},
-        load_variables_from: [bevelSecretsLoaderConfig(userId)],
+        load_variables_from: [bevelSecretsLoaderConfig(userId, this.secretsScope)],
       });
       // No late-settle owner: a client that arrives after the deadline has no
       // manual registered and therefore no session, and neither

package/src/modules/database/__tests__/advisory-lock.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { AdvisoryLock, withAdvisoryLock } from '../advisory-lock.js';
+import { AdvisoryLock, advisoryLockKey, withAdvisoryLock } from '../advisory-lock.js';
 import type { Database } from '../connection.js';
 
 /**
@@ -145,3 +145,25 @@ describe('withAdvisoryLock', () => {
     expect(clients[0].releasedWith).toBeInstanceOf(Error);
   });
 });
+
+describe('advisoryLockKey', () => {
+  it('keeps the ids a single-tenant deployment always used when no tenant is named', () => {
+    expect(advisoryLockKey(AdvisoryLock.Migrations)).toBe(AdvisoryLock.Migrations);
+    expect(advisoryLockKey(AdvisoryLock.CommitWorker, '')).toBe(AdvisoryLock.CommitWorker);
+  });
+
+  it('gives each tenant its own key for each lock, stable across calls and inside int4', () => {
+    const a = advisoryLockKey(AdvisoryLock.CommitWorker, 't_acme');
+    const b = advisoryLockKey(AdvisoryLock.CommitWorker, 't_globex');
+    expect(a).toBe(advisoryLockKey(AdvisoryLock.CommitWorker, 't_acme'));
+    expect(a).not.toBe(b);
+    expect(a).not.toBe(AdvisoryLock.CommitWorker);
+    // The two locks of one tenant stay two locks.
+    expect(advisoryLockKey(AdvisoryLock.Migrations, 't_acme')).not.toBe(a);
+    for (const key of [a, b]) {
+      expect(Number.isInteger(key)).toBe(true);
+      expect(key).toBeGreaterThanOrEqual(-(2 ** 31));
+      expect(key).toBeLessThanOrEqual(2 ** 31 - 1);
+    }
+  });
+});

package/src/modules/database/__tests__/connection.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import {
+  DEFAULT_DB_SCHEMA,
+  assertSchemaName,
+  assertSearchPath,
+  closeDb,
+  createDb,
+  dbSchemaOf,
+  getDb,
+  type Database,
+} from '../connection.js';
+
+/**
+ * Pools here are never connected: `pg.Pool` opens nothing until a query is
+ * asked of it, so what a handle was built with — the schema its connections
+ * will search, whether two asks share one pool — is observable without a
+ * database, and that is what these cases pin.
+ */
+const URL = 'postgresql://u:p@127.0.0.1:1/never';
+
+const searchPath = (db: Database): string | undefined =>
+  (db.$client.options as { options?: string }).options;
+
+const opened: Database[] = [];
+afterEach(async () => {
+  await Promise.all(opened.splice(0).map((db) => closeDb(db)));
+});
+
+describe('schema per knowledge base', () => {
+  it('searches the schema it was built for, and leaves the default schema to the server', () => {
+    const acme = createDb(URL, { schema: 'acme' });
+    const plain = createDb(URL);
+    opened.push(acme, plain);
+    expect(searchPath(acme)).toBe('-c search_path=acme');
+    expect(dbSchemaOf(acme)).toBe('acme');
+    // Nothing set: an operator's own `search_path` stays in force.
+    expect(searchPath(plain)).toBeUndefined();
+    expect(dbSchemaOf(plain)).toBe(DEFAULT_DB_SCHEMA);
+  });
+
+  it('refuses a schema name that is not a plain lowercase identifier', () => {
+    for (const bad of ['Acme', 'a-b', 'a b', '1abc', 'public; drop schema x', '', 'a'.repeat(64)]) {
+      expect(() => assertSchemaName(bad), bad).toThrow(/schema name/);
+      expect(() => createDb(URL, { schema: bad }), bad).toThrow(/schema name/);
+    }
+    expect(assertSchemaName('t_acme_2')).toBe('t_acme_2');
+  });
+
+  it('refuses the names Postgres and drizzle already own', () => {
+    for (const reserved of ['pg_catalog', 'pg_toast', 'pg_x', 'information_schema', 'drizzle']) {
+      expect(() => assertSchemaName(reserved), reserved).toThrow(/reserved/);
+    }
+    // The default schema is a valid name here: a single-tenant deployment
+    // lives on it. A tenant source refuses it for a tenant, not this guard.
+    expect(assertSchemaName(DEFAULT_DB_SCHEMA)).toBe(DEFAULT_DB_SCHEMA);
+  });
+});
+
+describe('assertSearchPath', () => {
+  const answering = (schema: string | null) => ({
+    execute: async () => ({ rows: [{ schema }] }) as never,
+  });
+
+  it('passes when the server searches the configured schema first', async () => {
+    await expect(assertSearchPath(answering('t_acme'), 't_acme')).resolves.toBeUndefined();
+  });
+
+  it('refuses a connection whose schema a pooler dropped, naming both schemas and the cause', async () => {
+    // What a transaction-mode pooler leaves behind: the startup parameter
+    // never reached the server, so `public` is searched first.
+    await expect(assertSearchPath(answering('public'), 't_acme')).rejects.toThrow(
+      /search "public" first, not the configured schema "t_acme".*transaction-mode pooler/,
+    );
+    await expect(assertSearchPath(answering(null), 't_acme')).rejects.toThrow(/\(none\)/);
+  });
+});
+
+describe('getDb', () => {
+  it('shares one pool per (url, schema) and keeps different schemas apart', () => {
+    const a1 = getDb(URL, { schema: 'acme' });
+    const a2 = getDb(URL, { schema: 'acme' });
+    const b = getDb(URL, { schema: 'globex' });
+    const plain = getDb(URL);
+    opened.push(a1, b, plain);
+    expect(a2).toBe(a1);
+    expect(b).not.toBe(a1);
+    expect(plain).not.toBe(a1);
+    expect(getDb(URL, { schema: DEFAULT_DB_SCHEMA })).toBe(plain);
+  });
+
+  it('opens a fresh pool after the cached one was closed', async () => {
+    const first = getDb(URL, { schema: 'closing' });
+    await closeDb(first);
+    const second = getDb(URL, { schema: 'closing' });
+    opened.push(second);
+    expect(second).not.toBe(first);
+  });
+});