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

package/src/modules/tool-auth/external-api-key.service.ts

@@ -2,7 +2,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('external-api-key');
-import { and, asc, desc, eq, isNotNull, isNull, type SQL } from 'drizzle-orm';
+import { and, desc, eq, isNotNull, isNull, type SQL } from 'drizzle-orm';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import type { Database } from '../database/connection.js';
 import { externalApiKeys, users } from '../database/schema.js';
@@ -108,7 +108,9 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
     // Join users so a single round-trip resolves both "token is valid" and
     // "load the user it belongs to". The unique index on token_hash makes
     // this a point-lookup. `isNull(revokedAt)` is what enforces revocation
-    // — the row remains for audit.
+    // — the row remains for audit — and `isNull(deactivatedAt)` is what
+    // stops a switched-off account's keys without revoking them, so
+    // switching it back on restores them.
     const [row] = await this.db
       .select({
         tokenId: externalApiKeys.id,
@@ -119,7 +121,7 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
       })
       .from(externalApiKeys)
       .innerJoin(users, eq(externalApiKeys.userId, users.id))
-      .where(and(eq(externalApiKeys.tokenHash, tokenHash), isNull(externalApiKeys.revokedAt)))
+      .where(and(eq(externalApiKeys.tokenHash, tokenHash), isNull(externalApiKeys.revokedAt), isNull(users.deactivatedAt)))
       .limit(1);
 
     if (!row) return null;
@@ -167,6 +169,11 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
     // Owner joined in so the admin overview is one round-trip; ordered by
     // owner email so per-account grouping is a linear pass, newest key
     // first within an account (same order the owner sees on their own page).
+    // The email half of that order is applied in-process: the column is
+    // ciphertext in the database, where ORDER BY would sort by IV noise. The
+    // sort is stable, so the database's newest-first survives within an owner.
+    // By code unit, not by locale: a collation can call two different
+    // addresses equal, and equal here means "the same owner's group".
     const rows = await this.db
       .select({
         key: externalApiKeys,
@@ -176,7 +183,8 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
       })
       .from(externalApiKeys)
       .innerJoin(users, eq(externalApiKeys.userId, users.id))
-      .orderBy(asc(users.email), desc(externalApiKeys.createdAt));
+      .orderBy(desc(externalApiKeys.createdAt));
+    rows.sort((a, b) => (a.email < b.email ? -1 : a.email > b.email ? 1 : 0));
     return rows.map((row) => ({
       ...toSummary(row.key),
       user: { id: row.userId, email: row.email, name: row.name },

package/src/modules/tool-auth/internal-token.service.ts

@@ -12,9 +12,9 @@ export interface InternalTokenClaim {
   /**
    * The agent run / conversation id (the Mastra thread id) this token is scoped
    * to, when minted per-run. Surfaced as `ToolContext.sessionId` so the
-   * ontology-session boundary can scope to one run for the in-process agent
-   * (the external/MCP path carries `sessionId` on the tool body instead).
-   * Absent for identity-only tokens.
+   * agent-access hooks can tell the in-process agent's run apart (the
+   * external/MCP path carries `sessionId` on the tool body instead). Absent
+   * for identity-only tokens.
    */
   sessionId?: string;
   /**

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

@@ -4,6 +4,7 @@ import { logger } from '../../shared/logging.js';
 const log = logger('tools');
 import type { IExternalApiKeyService } from './external-api-key.interface.js';
 import type { AuthService } from '../auth/auth.service.js';
+import { ACCOUNT_DEACTIVATED_MESSAGE, AuthBackendError } from '../auth/account-admission.js';
 import { InternalTokenService } from './internal-token.service.js';
 import { INVALID_CONNECTION_KEY_CHALLENGE, INVALID_CONNECTION_KEY_MESSAGE } from './connection-key-rejection.js';
 
@@ -79,10 +80,10 @@ export const requireInternalSource: RequestHandler = (req, res, next) => {
 
 /**
  * Mirror of `requireInternalSource` for surfaces that must admit ONLY external
- * callers. `start_session` mints a fresh chat thread as the caller's
- * ontology-session id; an internal (in-process agent) token already carries
- * its run's `sessionId`, so letting it mint a new thread mid-run would
- * silently reset the one-ontology-per-conversation boundary.
+ * callers. `start_session` mints a fresh chat thread as the caller's session
+ * id; an internal (in-process agent) token already carries its run's
+ * `sessionId`, so letting it mint a new thread mid-run would silently split
+ * one conversation in two.
  *
  * "External" is decided by the VERIFIER, not by which credential shape
  * authenticated: a `bevel_…` connection key resolves external, and so does an
@@ -122,6 +123,15 @@ export type VerifyResult =
 export function createTokenVerifier(
   externalApiKeyService: IExternalApiKeyService,
   internalTokenService: InternalTokenService,
+  /**
+   * Whether the account an internal token was minted for is still on. An
+   * internal token carries only a user id and lives up to an hour (longer
+   * for the MCP loopback), so without this a switched-off account's running
+   * agent would keep working until it expired. Connection keys need no
+   * second look: their lookup reads the account. Every deployment passes
+   * it; absent, internal tokens are judged on their signature alone.
+   */
+  accounts?: Pick<AuthService, 'isActive'>,
 ): (token: string | undefined) => Promise<VerifyResult> {
   const missing = { ok: false as const, status: 401, message: 'A connection key or internal token is required' };
   return async (token) => {
@@ -136,6 +146,9 @@ export function createTokenVerifier(
     if (internalTokenService.looksLikeInternalToken(token)) {
       const claim = internalTokenService.verify(token);
       if (!claim) return { ok: false, status: 401, message: 'Invalid or expired internal token' };
+      if (accounts && !(await accounts.isActive(claim.userId))) {
+        return { ok: false, status: 401, message: ACCOUNT_DEACTIVATED_MESSAGE };
+      }
       return claim.externalProxy
         ? {
             ok: true,
@@ -170,8 +183,9 @@ export function createTokenVerifier(
 export function createToolAuthMiddleware(
   externalApiKeyService: IExternalApiKeyService,
   internalTokenService: InternalTokenService,
+  accounts?: Pick<AuthService, 'isActive'>,
 ): RequestHandler {
-  const verify = createTokenVerifier(externalApiKeyService, internalTokenService);
+  const verify = createTokenVerifier(externalApiKeyService, internalTokenService, accounts);
   return async (req: Request, res: Response, next: NextFunction) => {
     const header = req.headers.authorization;
     if (!header || !header.toLowerCase().startsWith('bearer ')) {
@@ -210,9 +224,9 @@ export function createToolAuthMiddleware(
 export function createManualAuthMiddleware(
   externalApiKeyService: IExternalApiKeyService,
   internalTokenService: InternalTokenService,
-  authService: AuthService,
+  authService: Pick<AuthService, 'isActive' | 'resolveSession'>,
 ): RequestHandler {
-  const verify = createTokenVerifier(externalApiKeyService, internalTokenService);
+  const verify = createTokenVerifier(externalApiKeyService, internalTokenService, authService);
   return async (req: Request, res: Response, next: NextFunction) => {
     const header = req.headers.authorization;
     if (!header || !header.toLowerCase().startsWith('bearer ')) {
@@ -241,13 +255,22 @@ export function createManualAuthMiddleware(
     }
 
     // Otherwise treat the bearer as a browser session JWT.
+    let userId: string;
     try {
-      const { userId } = authService.verifyToken(token);
-      req.toolAuth = { source: 'session', userId, scope: 'write' };
-      next();
-    } catch {
+      ({ userId } = await authService.resolveSession(token));
+    } catch (err) {
+      // The account could not be looked up: an outage, not a verdict on the
+      // session, and a 401 would sign a valid caller out over it.
+      if (err instanceof AuthBackendError) {
+        log.error('session account lookup failed:', { err: err.cause });
+        res.status(500).json({ error: 'Authentication backend unavailable' });
+        return;
+      }
       res.setHeader('WWW-Authenticate', WWW_AUTH);
       res.status(401).json({ error: 'Invalid or expired token' });
+      return;
     }
+    req.toolAuth = { source: 'session', userId, scope: 'write' };
+    next();
   };
 }

package/src/modules/tool-helpers/__tests__/agent-roles-write.test.ts

@@ -12,6 +12,7 @@ import { createToolHandlerFactory } from '../tool-handler.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
 import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { SpillStore } from '../../workspace/spill-store.js';
 import { DocExtractService } from '../../workspace/file-readers/doc-extract.service.js';
 import { NEW_ROLE_GUIDANCE } from '../../access-model/roles-yaml-guard.js';
@@ -68,13 +69,14 @@ async function start(): Promise<string> {
     canOwner: async () => true,
     canWriteBatchAtRef: async () => null,
     canReadBatch: async (_w: string, _u: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+    // The `after` half of a move's or copy's preview — allowing everything, like the gates above.
+    previewAccessAfterRelocation: async () => ({ read: true, write: true, download: true, owner: true }),
   } as never;
   registerWorkspaceTools(registry, router, toolAuth, createToolHandlerFactory(resolve), new SpillStore(path.join(os.tmpdir(), 'bevel-test-spills')), new DocExtractService(docCache), allowAll, testKbContext({ kbDirName: KB }), {
-    service: {} as never,
-    enabled: false, // ontology boundary not under test here
-    kb: testKbContext({ kbDirName: KB }),
+    // No hook registered: the agent-access gate refuses nothing here.
     recoveryBotEmail: 'recovery-bot@bevel.local',
     hooks: new WorkflowHooks(),
+    notes: new ToolDescriptionNotes(),
   }, new RoutineWritePolicyService(), {} as never);
   const app = express();
   app.use(express.json());

package/src/modules/tool-helpers/__tests__/phase4-tools.test.ts

@@ -10,6 +10,7 @@ import { createManualRoutes } from '../../tool-registry/manual.routes.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
 import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { SpillStore } from '../../workspace/spill-store.js';
 import { DocExtractService } from '../../workspace/file-readers/doc-extract.service.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
@@ -65,11 +66,10 @@ async function start(): Promise<string> {
   // and their web_search / submit_feedback / cite_kb_node cases — moved to
   // the enterprise repo with their modules; core registers only core tools.
   registerWorkspaceTools(registry, router, toolAuth, th, new SpillStore('/tmp/bevel-test-spills'), new DocExtractService('/tmp/bevel-test-doc-extract'), accessControl, testKbContext(), {
-    service: {} as never,
-    enabled: false, // ontology boundary not under test here
-    kb: testKbContext(),
+    // No hook registered: the agent-access gate refuses nothing here.
     recoveryBotEmail: 'recovery-bot@bevel.local',
     hooks: new WorkflowHooks(),
+    notes: new ToolDescriptionNotes(),
   }, new RoutineWritePolicyService(), {} as never /* sessionSink — start_session not exercised here */);
   router.use(createManualRoutes(registry, toolAuth));
 

package/src/modules/tool-helpers/__tests__/validate-token.test.ts

@@ -18,7 +18,11 @@ const externalApiKeyService = {
   verifyAndLoadToken: async (t: string) =>
     t === 'bevel_ok' ? { user: { id: 'u-ext', email: 'e@x', name: 'Ext' }, tokenId: 'tk-1' } : null,
 } as never;
-const authService = { getUserById: async (id: string) => ({ id, email: 'e@x', name: 'N' }) } as never;
+// Every account is on except `u-off`, which an admin switched off.
+const authService = {
+  getUserById: async (id: string) => ({ id, email: 'e@x', name: 'N' }),
+  isActive: async (id: string) => id !== 'u-off',
+} as never;
 
 let tempDir = '';
 const workspaceService = {
@@ -66,6 +70,12 @@ describe('validateToken (tool-author SDK entry)', () => {
     expect((await fs.readFile('a.md')).toString()).toBe('hi');
   });
 
+  it('throws a 401 ToolError for a valid internal token whose account was switched off', async () => {
+    const err = await validateToken(internalToken.mint({ userId: 'u-off' })).catch((e) => e);
+    expect(hasHttpStatus(err) && err.status).toBe(401);
+    expect((err as Error).message).toContain('switched off');
+  });
+
   it('throws a 401 ToolError on a bad token and an empty token', async () => {
     for (const bad of ['garbage', 'bevel_nope', '', undefined]) {
       const err = await validateToken(bad as string).catch((e) => e);

package/src/modules/tool-helpers/tool-handler.ts

@@ -6,6 +6,7 @@ import { hasHttpStatus, ToolError, type ToolHandler } from './tool.contract.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import type { ResolveToolContext } from './tool-context.js';
+import { alwaysWritable, READ_ONLY_CODE, refuseWriteTool, type IWriteAccess } from '../write-access/write-access.js';
 import '../tool-auth/tool-auth.middleware.js'; // Express Request.toolAuth augmentation
 
 function isAsyncIterable(v: unknown): v is AsyncIterable<unknown> {
@@ -29,7 +30,7 @@ export interface ToolHandlerOptions {
  * The handler receives `req.body` as the flat args (UTCP's `body_field` already
  * delivered the inner body as the request body).
  */
-export function createToolHandlerFactory(resolve: ResolveToolContext) {
+export function createToolHandlerFactory(resolve: ResolveToolContext, writeAccess: IWriteAccess = alwaysWritable) {
   return function toolHandler(handler: ToolHandler, opts: ToolHandlerOptions = {}) {
     return async (req: Request, res: Response): Promise<void> => {
       const auth = req.toolAuth;
@@ -41,10 +42,29 @@ export function createToolHandlerFactory(resolve: ResolveToolContext) {
         res.status(403).json({ error: 'This tool requires write access.' });
         return;
       }
+      // Before anything is awaited: a client that goes away during the
+      // write-access check below must still abort the call.
+      //
+      // Asked of the RESPONSE. The request closes as soon as its body has
+      // been read, with the client still there and waiting, so its `close`
+      // says nothing about the client; the response closes when it has been
+      // sent or the connection is gone, and `writableEnded` tells the two
+      // apart.
       const abort = new AbortController();
-      req.on('close', () => {
+      res.on('close', () => {
         if (!res.writableEnded) abort.abort();
       });
+      // The tool layer's half of the read-only gate: the HTTP gate lets every
+      // tool call through, since only here is a write tool told from a read.
+      if (opts.write) {
+        const refusal = await refuseWriteTool(writeAccess);
+        if (refusal !== null) {
+          res.status(403).json({ error: refusal, code: READ_ONLY_CODE });
+          return;
+        }
+        // The client left while the verdict was awaited: nobody to answer.
+        if (abort.signal.aborted) return;
+      }
       const body: unknown = req.body;
       if (body !== undefined && body !== null && (typeof body !== 'object' || Array.isArray(body))) {
         res.status(400).json({ error: 'Request body must be a JSON object.' });
@@ -53,8 +73,8 @@ export function createToolHandlerFactory(resolve: ResolveToolContext) {
       const args = (body ?? {}) as Record<string, unknown>;
       // `sessionId` rides the tool body like `branch` does: the external MCP
       // proxy injects it (ask-tool continuity convention) and the in-process
-      // agent passes its thread id. Surfaced on the context so the ontology
-      // gate can scope to one run without each handler re-reading args.
+      // agent passes its thread id. Surfaced on the context so the
+      // agent-access gate can name the run without each handler re-reading args.
       const sessionId = typeof args.sessionId === 'string' && args.sessionId.length > 0
         ? args.sessionId
         : undefined;

package/src/modules/tool-helpers/tool.contract.ts

@@ -34,8 +34,9 @@ export interface ToolContext {
    * The agent run / conversation id this call belongs to (the agent thread id).
    * Supplied as a `sessionId` field on the tool's input body — the external MCP
    * proxy injects it via the `ask`-tool continuity convention, and the
-   * in-process agent passes its thread id. Used to scope the ontology-session
-   * boundary to one run. Absent for non-agent or unthreaded calls.
+   * in-process agent passes its thread id. Handed to the agent-access hooks,
+   * which is how a deployment scopes a rule to one conversation. Absent for
+   * non-agent or unthreaded calls.
    */
   sessionId?: string;
   /**

package/src/modules/tool-helpers/validate-token.ts

@@ -35,7 +35,7 @@ export type ValidateToken = (
 ) => Promise<ToolContext>;
 
 export function createToolValidator(deps: ToolValidatorDeps): ValidateToken {
-  const verify = createTokenVerifier(deps.externalApiKeyService, deps.internalTokenService);
+  const verify = createTokenVerifier(deps.externalApiKeyService, deps.internalTokenService, deps.authService);
   const resolve = createToolContextResolver(deps);
   return async (token, signal) => {
     let result;

package/src/modules/tool-manuals/tool-manuals.tools.ts

@@ -65,32 +65,24 @@ export function registerToolManualsTools(
 
   const listSetupDef = toolDef({
     name: 'list_tool_setup',
+    // What each FIELD means is documented on the field, in `outputs` below:
+    // `setup.kind`, `variables` and `invalid` each carried a paragraph here,
+    // which made this description two thousand characters and so the first
+    // thing a client cut. The description says what the tool answers and the
+    // three things an agent cannot read off a field.
     description:
-      'Configuration status of every `.tool` the current user can access: what each tool needs set up and ' +
-      'what is already configured. Results are scoped to the caller — a `.tool` the caller cannot READ is ' +
-      'absent entirely, and all status flags reflect the caller\'s own state. Per tool: `setup` describes ' +
-      'an MCP server\'s sign-in requirement (`open` = none; `oauth-auto` = sign-in was configured ' +
-      'automatically; `oauth-manual` = the sign-in needs an OAuth app the owner registers with the provider: ' +
-      'a writer declares its client id on a `user`-scoped variable with an `oauth` block — in the plugin.json ' +
-      'extensions entry for an mcp.json server (endpoints are discovered from the server; PKCE is on by ' +
-      'default), or in the `.tool` file with explicit URLs — and pastes the client secret on the tool\'s page. ' +
-      '`setup.reason` is present only while something still blocks the sign-in and says what). ' +
-      'Per variable: whether the shared (admin) value is set, whether the CURRENT user has ' +
-      'set/authorized their own, and whether it is an OAuth sign-in (users authorize those on the /connect ' +
-      'page, never by typing a value). `canWrite` = the caller may write THAT `.tool` FILE (per-file access ' +
-      'from its frontmatter `write:`/`owner:` verbs and the access.md chain — NOT a platform role), which ' +
-      'is exactly what gates setting its shared secrets: the people who manage the file configure the tool. ' +
-      'Secret VALUES are never returned and can never be set through a tool — an admin enters them in the ' +
-      'tool editor; users sign in on /connect. ' +
-      '`invalid` names any `.tool` file the scan REFUSED, with the reason and its location: those files ' +
-      'are the only ones missing — every other tool is listed and callable, and a refused file is listed ' +
-      'again as a normal tool on the next call once it is fixed (or removed), with nothing to restart or ' +
-      'reconnect. ' +
-      'The listing is the RELEASED catalog, built from the default branch only: a server or `.tool` you ' +
-      'declared on a draft is not listed, not callable and not signed-in-able until that draft is merged. ' +
-      'Pass `branch` (the draft you wrote the declaration on) and `onBranchOnly` names every tool declared ' +
-      'there that the default branch does not serve yet — open a change request, then ask the user to ' +
-      'review and merge it in the app to activate it.',
+      'Configuration status of every `.tool` the current user can access: what each tool needs set up and what is ' +
+      'already configured, as `{ tools, invalid, onBranchOnly, note? }`. Scoped to the CALLER — a `.tool` it cannot ' +
+      'READ is absent entirely, and every flag is the caller\'s own state. ' +
+      'Secret VALUES are never returned and can never be set through a tool: an admin enters them in the tool editor, ' +
+      'and users sign in on /connect rather than typing a value. ' +
+      'What gates setting a tool\'s shared secrets is `canWrite` on the `.tool` FILE — per-file access from its ' +
+      'frontmatter `write:`/`owner:` verbs and the access.md chain, NOT a platform role: the people who manage the ' +
+      'file configure the tool. ' +
+      'The listing is the RELEASED catalog, built from the default branch only: a server or `.tool` you declared on a ' +
+      'draft is not listed, not callable and not signed-in-able until that draft is merged. Pass `branch` (the draft ' +
+      'you wrote the declaration on) and `onBranchOnly` names every tool declared there that the default branch does ' +
+      'not serve yet — open a change request, then ask the user to review and merge it in the app to activate it.',
     path: '/api/agent/tools/list_tool_setup',
     inputs: {
       type: 'object',
@@ -119,12 +111,32 @@ export function registerToolManualsTools(
               type: { type: 'string' },
               setup: {
                 type: ['object', 'null'],
-                description: 'MCP auto-discovery setup requirement; null for non-mcp tools.',
-                properties: { kind: { type: 'string' }, reason: { type: 'string' } },
+                description: "An MCP server's sign-in requirement; null for non-mcp tools.",
+                properties: {
+                  kind: {
+                    type: 'string',
+                    description:
+                      '`open` = no sign-in; `oauth-auto` = sign-in was configured automatically; `oauth-manual` = the ' +
+                      'sign-in needs an OAuth app the owner registers with the provider: a writer declares its client ' +
+                      'id on a `user`-scoped variable with an `oauth` block — in the plugin.json extensions entry for ' +
+                      'an mcp.json server (endpoints are discovered from the server; PKCE is on by default), or in the ' +
+                      '`.tool` file with explicit URLs — and pastes the client secret on the tool\'s page.',
+                  },
+                  reason: {
+                    type: 'string',
+                    description: 'Present only while something still blocks the sign-in, and says what.',
+                  },
+                },
+              },
+              canWrite: {
+                type: 'boolean',
+                description: 'You may write this `.tool` FILE, which is what gates setting its shared secrets.',
               },
-              canWrite: { type: 'boolean' },
               variables: {
                 type: 'array',
+                description:
+                  'What this tool needs configured, and by whom: per variable, whether the shared (admin) value is ' +
+                  'set and whether the CURRENT user has set or authorized their own.',
                 items: {
                   type: 'object',
                   properties: {
@@ -150,9 +162,10 @@ export function registerToolManualsTools(
         invalid: {
           type: 'array',
           description:
-            '`.tool` files the scan refused — the ONLY tools missing from `tools`. Each names the file and ' +
-            'why it was refused, with the line/column or field where the validation failed. Fix the file (or ' +
-            'delete it) and the next call lists it as a normal tool. Never contains a secret value.',
+            '`.tool` files the scan refused — the ONLY tools missing from `tools`; every other tool is listed and ' +
+            'callable. Each names the file and why it was refused, with the line/column or field where the validation ' +
+            'failed. Fix the file (or delete it) and the next call lists it as a normal tool, with nothing to restart ' +
+            'or reconnect. Never contains a secret value.',
           items: {
             type: 'object',
             properties: {