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

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

@@ -1,5 +1,8 @@
 import { createHash, randomBytes } from 'node:crypto';
-import { and, desc, eq, isNotNull, isNull } from 'drizzle-orm';
+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 type { AuthUser } from '@bevel-software/platform-shared';
 import type { Database } from '../database/connection.js';
 import { externalApiKeys, users } from '../database/schema.js';
@@ -10,9 +13,12 @@ import {
 } from './external-api-key.errors.js';
 import {
   DEFAULT_KEY_KIND,
+  type AdminExternalApiKeySummary,
   type ExternalApiKeySummary,
   type IExternalApiKeyService,
+  type KeyKindSpec,
   type MintOptions,
+  type RevokedBy,
   type MintedExternalApiKey,
 } from './external-api-key.interface.js';
 
@@ -21,6 +27,9 @@ import {
 // brute force, cheap to copy. The prefix lets the auth middleware route
 // key-vs-JWT requests without parsing both shapes.
 const TOKEN_BYTES = 32;
+// A GitHub-shaped token: 20 random bytes as 40 hex digits — alphanumeric,
+// as GitHub's own are, and 160 bits, which a hash lookup never exhausts.
+const GITHUB_TOKEN_BYTES = 20;
 
 const MAX_LABEL_LEN = 200;
 
@@ -31,19 +40,19 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
    * @param keyPrefix Tenant-derived plaintext prefix (e.g. `bevel_`) — injected
    *   from {@link AppConfig.externalApiKeyPrefix} so a deploy can brand its keys.
    *   Every key of the default kind is minted with it.
-   * @param kinds Other kinds a key may be minted as, each with the plaintext
-   *   prefix that kind is spelled with — a Claude link's `gho_`, the shape
-   *   claude.ai expects from a GitHub host. Same key, same table, same
+   * @param kinds Other kinds a key may be minted as, each with the spelling
+   *   that kind has — a Claude link's `gho_` and GitHub's alphabet, the
+   *   shape claude.ai expects from a GitHub host. Same key, same table, same
    *   revocation; the KIND is stored on the row and is what tells such keys
-   *   apart (a label is the person's to edit), the prefix is only what the
+   *   apart (a label is the person's to edit), the spelling is only what the
    *   outside world sees and what routes the bearer back here.
    */
   constructor(
     private readonly db: Database,
     private readonly keyPrefix: string,
-    private readonly kinds: Readonly<Record<string, string>> = {},
+    private readonly kinds: Readonly<Record<string, KeyKindSpec>> = {},
   ) {
-    this.prefixes = [keyPrefix, ...Object.values(kinds)];
+    this.prefixes = [keyPrefix, ...Object.values(kinds).map((k) => k.prefix)];
   }
 
   /** True if a bearer string carries one of this service's key prefixes. */
@@ -53,8 +62,8 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
 
   async mint(userId: string, label: string, options: MintOptions = {}): Promise<MintedExternalApiKey> {
     const kind = options.kind ?? DEFAULT_KEY_KIND;
-    const prefix = kind === DEFAULT_KEY_KIND ? this.keyPrefix : this.kinds[kind];
-    if (!prefix) throw new Error(`Unknown key kind "${kind}"`);
+    const spec: KeyKindSpec | undefined = kind === DEFAULT_KEY_KIND ? { prefix: this.keyPrefix } : this.kinds[kind];
+    if (!spec) throw new Error(`Unknown key kind "${kind}"`);
     const trimmed = (label ?? '').trim();
     if (trimmed.length === 0) {
       throw new InvalidTokenLabelError('Label cannot be empty');
@@ -65,7 +74,11 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
       );
     }
 
-    const plaintext = prefix + randomBytes(TOKEN_BYTES).toString('base64url');
+    const random =
+      spec.shape === 'github-token'
+        ? randomBytes(GITHUB_TOKEN_BYTES).toString('hex')
+        : randomBytes(TOKEN_BYTES).toString('base64url');
+    const plaintext = spec.prefix + random;
     const tokenHash = hashToken(plaintext);
 
     const [row] = await this.db
@@ -116,7 +129,7 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
     // the worst case is a slightly stale `last_used_at`, which is fine for
     // a "when was this key last used" audit view.
     this.touchLastUsed(row.tokenId).catch((err) => {
-      console.warn('[external-api-key] touchLastUsed failed:', err);
+      log.warn('touchLastUsed failed:', { err });
     });
 
     return {
@@ -139,31 +152,65 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
     return rows.map(toSummary);
   }
 
+  async listForDeployment(): Promise<AdminExternalApiKeySummary[]> {
+    // 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).
+    const rows = await this.db
+      .select({
+        key: externalApiKeys,
+        userId: users.id,
+        email: users.email,
+        name: users.name,
+      })
+      .from(externalApiKeys)
+      .innerJoin(users, eq(externalApiKeys.userId, users.id))
+      .orderBy(asc(users.email), desc(externalApiKeys.createdAt));
+    return rows.map((row) => ({
+      ...toSummary(row.key),
+      user: { id: row.userId, email: row.email, name: row.name },
+    }));
+  }
+
   async revoke(id: string, userId: string): Promise<void> {
-    // Scope the WHERE by userId so a user can never revoke another user's
-    // token even if they learn the id. Idempotent on already-revoked rows
-    // because we only set `revokedAt` when it's currently null — re-revoking
-    // returns 0 rows changed but no error.
+    // Scope by userId so a user can never revoke another user's token even
+    // if they learn the id.
+    await this.markRevoked(
+      and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId))!,
+      'owner',
+    );
+  }
+
+  async revokeAny(id: string): Promise<void> {
+    // No owner scope: the caller is an admin acting across the deployment.
+    // The route that exposes this is admin-gated; nothing user-facing may
+    // reach it. Recorded as such so the owner is told it was taken, not
+    // that they disconnected it.
+    await this.markRevoked(eq(externalApiKeys.id, id), 'admin');
+  }
+
+  /**
+   * Set `revokedAt` (and who did it) on the rows matching `scope`. Idempotent
+   * on already-revoked rows because we only write when `revokedAt` is
+   * currently null — re-revoking returns 0 rows changed but no error, and
+   * never rewrites who ended it first. Throws TokenNotFoundError when `scope`
+   * matches nothing at all.
+   */
+  private async markRevoked(scope: SQL, by: RevokedBy): Promise<void> {
     const result = await this.db
       .update(externalApiKeys)
-      .set({ revokedAt: new Date() })
-      .where(
-        and(
-          eq(externalApiKeys.id, id),
-          eq(externalApiKeys.userId, userId),
-          isNull(externalApiKeys.revokedAt),
-        ),
-      )
+      .set({ revokedAt: new Date(), revokedBy: by })
+      .where(and(scope, isNull(externalApiKeys.revokedAt)))
       .returning({ id: externalApiKeys.id });
 
     if (result.length === 0) {
-      // Distinguish "doesn't exist / not yours" from "already revoked".
+      // Distinguish "doesn't exist / out of scope" from "already revoked".
       // The latter must stay idempotent (return success); only the former
       // throws.
       const [existing] = await this.db
         .select({ id: externalApiKeys.id })
         .from(externalApiKeys)
-        .where(and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId)))
+        .where(scope)
         .limit(1);
       if (!existing) {
         throw new TokenNotFoundError();
@@ -223,5 +270,6 @@ function toSummary(row: typeof externalApiKeys.$inferSelect): ExternalApiKeySumm
     createdAt: row.createdAt.getTime(),
     lastUsedAt: row.lastUsedAt ? row.lastUsedAt.getTime() : null,
     revokedAt: row.revokedAt ? row.revokedAt.getTime() : null,
+    revokedBy: (row.revokedBy as RevokedBy | null) ?? null,
   };
 }

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

@@ -99,8 +99,11 @@ export class InternalTokenService {
     return this.ttlMs;
   }
 
-  /** @param ttlMs Override the default lifetime — e.g. the MCP proxy mints
-   *   session-loopback tokens that must outlive its 4h session idle TTL. */
+  /** @param ttlMs Override the default lifetime — for a caller whose token
+   *   must live a different span than the default: the MCP proxy's loopback
+   *   bearer (`MCP_LOOPBACK_TOKEN_TTL_MS`, longer, so a long tool call is not
+   *   cut off mid-way) and the external-proxy token minted for a grant, whose
+   *   life is bounded by the grant's remaining time (`mcp.routes.ts`). */
   mint(claim: InternalTokenClaim, ttlMs?: number): string {
     const payload: SignedPayload = { ...claim, exp: this.now() + (ttlMs ?? this.ttlMs) };
     const body = b64url(Buffer.from(JSON.stringify(payload), 'utf8'));

package/src/modules/tool-auth/key-or-session.middleware.ts

@@ -0,0 +1,45 @@
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+
+/**
+ * One gate for an endpoint that serves the app AND agents: a bearer that
+ * looks like a tool credential (a `bevel_…` connection key, an internal
+ * token) goes through the tool-auth middleware; anything else — the
+ * browser's session JWT, its cookie — goes through the session middleware.
+ * Whichever admitted the caller, `req.userId` names them afterwards, so a
+ * handler written for sessions (`resolveUser` → `req.userId`) serves both.
+ *
+ * Composition, not a third verifier: each credential is still checked by
+ * the code that owns it. Deliberately NOT the read-only-manuals gate
+ * (`createManualAuthMiddleware`), which is documented as the one place a
+ * session may stand in for a tool credential; here it is the other way
+ * round — a tool credential is admitted to an app endpoint — and only for
+ * endpoints a tool definition describes.
+ */
+export function keyOrSessionAuth(deps: {
+  sessionAuth: RequestHandler;
+  toolAuth: RequestHandler;
+  /** Whether a bearer value is a tool credential rather than a session token. */
+  isToolCredential(token: string): boolean;
+}): RequestHandler {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const header = req.headers.authorization;
+    const token =
+      header && header.toLowerCase().startsWith('bearer ') ? header.slice(header.indexOf(' ') + 1).trim() : '';
+    if (!token || !deps.isToolCredential(token)) {
+      deps.sessionAuth(req, res, next);
+      return;
+    }
+    deps.toolAuth(req, res, (err?: unknown) => {
+      if (err) {
+        next(err);
+        return;
+      }
+      // The tool gate names the caller on `req.toolAuth`; the endpoint reads
+      // `req.userId`, as it does for a session. Assigned unconditionally: the
+      // credential this gate accepted is who the caller is, whatever an
+      // earlier middleware may have written there.
+      if (req.toolAuth) req.userId = req.toolAuth.userId;
+      next();
+    });
+  };
+}

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

@@ -1,7 +1,11 @@
 import type { Request, Response, NextFunction, RequestHandler } from 'express';
+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 { InternalTokenService } from './internal-token.service.js';
+import { INVALID_CONNECTION_KEY_CHALLENGE, INVALID_CONNECTION_KEY_MESSAGE } from './connection-key-rejection.js';
 
 /**
  * What the `toolAuth` middleware resolves a bearer to, before the per-call
@@ -88,10 +92,15 @@ export const requireExternalSource: RequestHandler = (req, res, next) => {
   next();
 };
 
-/** Outcome of verifying a bearer token — either a normalized identity or a status+message to surface. */
+/**
+ * Outcome of verifying a bearer token — either a normalized identity or a
+ * status+message to surface. `challenge` overrides the default
+ * `WWW-Authenticate` value on a 401 (a rejected connection key answers with
+ * its own plain `invalid_token` challenge).
+ */
 export type VerifyResult =
   | { ok: true; auth: ToolAuth }
-  | { ok: false; status: number; message: string };
+  | { ok: false; status: number; message: string; challenge?: string };
 
 /**
  * The framework-agnostic verify core: bearer token (the value AFTER `Bearer `) →
@@ -129,7 +138,7 @@ export function createTokenVerifier(
       const resolved = await externalApiKeyService.verifyAndLoadToken(token);
       return resolved
         ? { ok: true, auth: { source: 'external', userId: resolved.user.id, tokenId: resolved.tokenId, scope: 'write' } }
-        : { ok: false, status: 401, message: 'Invalid or revoked connection key' };
+        : { ok: false, status: 401, message: INVALID_CONNECTION_KEY_MESSAGE, challenge: INVALID_CONNECTION_KEY_CHALLENGE };
     }
 
     return missing;
@@ -158,14 +167,14 @@ export function createToolAuthMiddleware(
     try {
       const result = await verify(token);
       if (!result.ok) {
-        if (result.status === 401) res.setHeader('WWW-Authenticate', WWW_AUTH);
+        if (result.status === 401) res.setHeader('WWW-Authenticate', result.challenge ?? WWW_AUTH);
         res.status(result.status).json({ error: result.message });
         return;
       }
       req.toolAuth = result.auth;
       next();
     } catch (err) {
-      console.error('[tools] connection-key verification failed:', err);
+      log.error('connection-key verification failed:', { err });
       res.status(500).json({ error: 'Authentication backend unavailable' });
     }
   };
@@ -202,14 +211,14 @@ export function createManualAuthMiddleware(
       try {
         const result = await verify(token);
         if (!result.ok) {
-          if (result.status === 401) res.setHeader('WWW-Authenticate', WWW_AUTH);
+          if (result.status === 401) res.setHeader('WWW-Authenticate', result.challenge ?? WWW_AUTH);
           res.status(result.status).json({ error: result.message });
           return;
         }
         req.toolAuth = result.auth;
         next();
       } catch (err) {
-        console.error('[tools] connection-key verification failed:', err);
+        log.error('connection-key verification failed:', { err });
         res.status(500).json({ error: 'Authentication backend unavailable' });
       }
       return;

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

@@ -0,0 +1,228 @@
+import type { Server as HttpServer } from 'node:http';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import express from 'express';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
+import { createToolAuthMiddleware } from '../../tool-auth/tool-auth.middleware.js';
+import { createToolContextResolver } from '../tool-context.js';
+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 { 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';
+import { loadActiveGroups } from '../../access/access-control.service.js';
+
+/**
+ * The agent's file tools over the production context resolver and a real
+ * workspace on disk: a roles.yaml write that creates a role is refused with a
+ * 422 whose message the agent can relay verbatim, and nothing is written; a
+ * write that only changes membership lands as before.
+ */
+
+const KB = 'knowledge-base';
+const WS = 'target-company-state';
+const ROLES = `${KB}/roles.yaml`;
+const DRAFT = `${KB}/KnowledgeBase/draft-roles.yaml`;
+const CURRENT = 'roles:\n  Admin:\n    - admin@x.io\n  Sales:\n    - felix@x.io\n';
+const WITH_NEW_ROLE = `${CURRENT}  Project Phoenix:\n    - p@x.io\n`;
+
+let root = '';
+let docCache = '';
+let httpServer: HttpServer | undefined;
+const internalToken = new InternalTokenService({ secret: 's' });
+
+async function start(): Promise<string> {
+  const authService = { getUserById: async (id: string) => ({ id, email: 'admin@x.io', name: 'Admin' }) } as never;
+  const workspaceService = {
+    getOrCreateForUser: async () => ({ id: WS }),
+    getWorkspacePath: async () => root,
+  } as never;
+  const workflowService = {
+    acquireLock: async () => ({ acquired: true, lock: { holderUserId: 'user-A', holderName: 'Admin' } }),
+    releaseLock: async () => null,
+    releaseLockNoCommit: async () => undefined,
+    commitChanges: async () => ({}),
+  } as never;
+  const resolve = createToolContextResolver({
+    authService,
+    workspaceService,
+    workflowService,
+    events: {} as never,
+    kbDirName: KB,
+    creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} },
+    loadActiveGroups,
+  });
+  const registry = new ToolRegistry();
+  const toolAuth = createToolAuthMiddleware({ verifyAndLoadToken: async () => null } as never, internalToken);
+  const router = express.Router();
+  const allowAll = {
+    canRead: async () => true,
+    canWrite: async () => true,
+    canDownload: async () => true,
+    canOwner: async () => true,
+    canWriteBatchAtRef: async () => null,
+    canReadBatch: async (_w: string, _u: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+  } as never;
+  registerWorkspaceTools(registry, router, toolAuth, createToolHandlerFactory(resolve), new SpillStore(path.join(os.tmpdir(), 'bevel-test-spills')), new DocExtractService(docCache), allowAll, KB, {
+    service: {} as never,
+    enabled: false, // ontology boundary not under test here
+    kbDirName: KB,
+    recoveryBotEmail: 'recovery-bot@bevel.local',
+    hooks: new WorkflowHooks(),
+  }, new RoutineWritePolicyService(), {} as never);
+  const app = express();
+  app.use(express.json());
+  app.use('/api', router);
+  httpServer = await new Promise<HttpServer>((r) => {
+    const s = app.listen(0, () => r(s));
+  });
+  return `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
+}
+
+const call = (base: string, tool: string, body: Record<string, unknown>) =>
+  fetch(`${base}/api/agent/tools/${tool}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${internalToken.mint({ userId: 'user-A' })}` },
+    body: JSON.stringify({ branch: 'main', ...body }),
+  });
+
+const rolesOnDisk = () => fs.readFile(path.join(root, ROLES), 'utf-8');
+
+async function expectNewRoleRefused(res: Response, roleName: string): Promise<void> {
+  expect(res.status).toBe(422);
+  const { error } = (await res.json()) as { error: string };
+  expect(error).toContain(`'${roleName}'`);
+  expect(error).toContain(NEW_ROLE_GUIDANCE);
+  expect(await rolesOnDisk()).toBe(CURRENT);
+}
+
+beforeEach(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-roles-'));
+  docCache = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-roles-doc-'));
+  await fs.mkdir(path.join(root, KB, 'KnowledgeBase'), { recursive: true });
+  await fs.writeFile(path.join(root, ROLES), CURRENT);
+  await fs.writeFile(path.join(root, DRAFT), WITH_NEW_ROLE);
+});
+
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+  await fs.rm(root, { recursive: true, force: true });
+  await fs.rm(docCache, { recursive: true, force: true });
+});
+
+describe('agent writes to roles.yaml never create a role', () => {
+  it('write_file with a new role → 422 naming it, with the group redirect; nothing written', async () => {
+    const base = await start();
+    await expectNewRoleRefused(await call(base, 'write_file', { path: ROLES, content: WITH_NEW_ROLE, mode: 'overwrite' }), 'Project Phoenix');
+  });
+
+  it('edit_file renaming a role → 422 for the created name', async () => {
+    const base = await start();
+    const res = await call(base, 'edit_file', { path: ROLES, old_string: '  Sales:', new_string: '  Marketing:' });
+    await expectNewRoleRefused(res, 'Marketing');
+  });
+
+  it('write_files carrying a new role → 422, and the batch lands nothing', async () => {
+    const base = await start();
+    const res = await call(base, 'write_files', {
+      // roles.yaml exists, so the batch says it means to replace it — what the
+      // guard refuses is the new role in the content, not the overwrite.
+      mode: 'overwrite',
+      files: [
+        { path: `${KB}/KnowledgeBase/note.md`, content: 'hello' },
+        { path: ROLES, content: WITH_NEW_ROLE },
+      ],
+    });
+    await expectNewRoleRefused(res, 'Project Phoenix');
+    await expect(fs.access(path.join(root, KB, 'KnowledgeBase/note.md'))).rejects.toBeDefined();
+  });
+
+  it('copy_file onto the existing roles.yaml is refused for the name; with none there, the bytes are judged', async () => {
+    const base = await start();
+    // A copy never overwrites, so the file that decides admin membership is
+    // not replaced — the clash is the answer, before any byte is read.
+    const onto = await call(base, 'copy_file', { src: DRAFT, dest: ROLES });
+    expect(onto.status).toBe(409);
+    expect(((await onto.json()) as { error: string }).error).toBe(
+      `A file named roles.yaml already exists in ${KB}.`,
+    );
+    expect(await rolesOnDisk()).toBe(CURRENT);
+
+    // With nothing at that path the copy is free to land, and then it is the
+    // validator that judges the bytes it would write: a file declaring roles
+    // no current one does is still refused, and nothing is created.
+    await fs.rm(path.join(root, ROLES));
+    const created = await call(base, 'copy_file', { src: DRAFT, dest: ROLES });
+    expect(created.status).toBe(422);
+    const { error } = (await created.json()) as { error: string };
+    expect(error).toContain("'Project Phoenix'");
+    expect(error).toContain(NEW_ROLE_GUIDANCE);
+    await expect(fs.access(path.join(root, ROLES))).rejects.toBeDefined();
+    expect(await fs.readFile(path.join(root, DRAFT), 'utf-8')).toBe(WITH_NEW_ROLE);
+  });
+
+  it('move_file onto the existing roles.yaml is refused before any byte moves: a move never overwrites', async () => {
+    const base = await start();
+    const res = await call(base, 'move_file', { src: DRAFT, dest: ROLES });
+    expect(res.status).toBe(409);
+    expect(((await res.json()) as { error: string }).error).toContain('already exists');
+    expect(await rolesOnDisk()).toBe(CURRENT);
+    expect(await fs.readFile(path.join(root, DRAFT), 'utf-8')).toBe(WITH_NEW_ROLE);
+  });
+
+  it('a members-only edit_file succeeds exactly as before', async () => {
+    const base = await start();
+    const res = await call(base, 'edit_file', {
+      path: ROLES,
+      old_string: '    - felix@x.io\n',
+      new_string: '    - felix@x.io\n    - dana@x.io\n',
+    });
+    expect(res.status).toBe(200);
+    expect(await rolesOnDisk()).toBe(`${CURRENT}    - dana@x.io\n`);
+  });
+});
+
+describe('agent writes to roles.yaml check `- group:<Name>` entries against the active group source', () => {
+  beforeEach(async () => {
+    await fs.writeFile(path.join(root, KB, 'groups.yaml'), 'groups:\n  Platform Team:\n    - p@x.io\n');
+  });
+
+  it('an entry naming a known group lands, matched case- and whitespace-insensitively', async () => {
+    const base = await start();
+    const res = await call(base, 'edit_file', {
+      path: ROLES,
+      old_string: '    - felix@x.io\n',
+      new_string: '    - felix@x.io\n    - group:platform  team\n',
+    });
+    expect(res.status).toBe(200);
+    expect(await rolesOnDisk()).toBe(`${CURRENT}    - group:platform  team\n`);
+  });
+
+  it('an unknown group → 422 naming the entry and its role; nothing written', async () => {
+    const base = await start();
+    const res = await call(base, 'write_file', { path: ROLES, content: `${CURRENT}    - group:Platfrom Team\n`, mode: 'overwrite' });
+    expect(res.status).toBe(422);
+    const { error } = (await res.json()) as { error: string };
+    expect(error).toContain("'- group:Platfrom Team' under role 'Sales'");
+    expect(error).toContain('groups.yaml');
+    expect(await rolesOnDisk()).toBe(CURRENT);
+  });
+
+  it('in IdP mode the synced file is the source, and groups.yaml no longer counts', async () => {
+    await fs.writeFile(path.join(root, KB, 'synced-groups.yaml'), 'groups:\n  Directory Team:\n    - d@x.io\n');
+    const base = await start();
+    const refused = await call(base, 'write_file', { path: ROLES, content: `${CURRENT}    - group:Platform Team\n`, mode: 'overwrite' });
+    expect(refused.status).toBe(422);
+    expect(((await refused.json()) as { error: string }).error).toContain('synced-groups.yaml');
+    expect(await rolesOnDisk()).toBe(CURRENT);
+    const landed = await call(base, 'write_file', { path: ROLES, content: `${CURRENT}    - group:Directory Team\n`, mode: 'overwrite' });
+    expect(landed.status).toBe(200);
+    expect(await rolesOnDisk()).toBe(`${CURRENT}    - group:Directory Team\n`);
+  });
+});

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

@@ -15,15 +15,29 @@ import { DocExtractService } from '../../workspace/file-readers/doc-extract.serv
 
 const WS = 'target-company-state';
 let recorded: unknown[][] = [];
+/** Workspace-relative targets the stub archive holds; each is offered to the tool's write guard. */
+let archiveEntries: string[] = [];
 
 const externalApiKeyService = { verifyAndLoadToken: async () => null } as never;
 const authService = { getUserById: async (id: string) => ({ id, email: 'e@x', name: 'N' }) } as never;
 const workspaceService = {
   getOrCreateForUser: async () => ({ id: WS }),
   getWorkspacePath: async () => '/tmp/ws',
-  unzipFile: async (ws: string, p: string, d?: string) => {
+  unzipFile: async (ws: string, p: string, d?: string, guardWrite?: (target: string) => Promise<void>) => {
     recorded.push(['unzip', ws, p, d]);
-    return { extracted: [p], skipped: [] };
+    if (archiveEntries.length === 0) return { extracted: [p], skipped: [] };
+    // Mirrors the real extraction: a guard refusal skips that entry with its message.
+    const extracted: string[] = [];
+    const skipped: { path: string; reason: string }[] = [];
+    for (const target of archiveEntries) {
+      try {
+        await guardWrite?.(target);
+        extracted.push(target);
+      } catch (err) {
+        skipped.push({ path: target, reason: (err as Error).message });
+      }
+    }
+    return { extracted, skipped };
   },
   readFile: async () => {
     throw new Error('no such file');
@@ -73,6 +87,7 @@ const post = (url: string, body: unknown = {}) =>
 
 beforeEach(() => {
   recorded = [];
+  archiveEntries = [];
 });
 afterEach(async () => {
   if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
@@ -80,11 +95,25 @@ afterEach(async () => {
 });
 
 describe('Phase 4 tools (core subset)', () => {
-  it('unzip calls workspaceService.unzipFile with the context workspace', async () => {
+  it('unzip calls workspaceService.unzipFile with the context workspace, on the repository path', async () => {
     const base = await start();
     const res = await post(`${base}/api/agent/tools/unzip`, { path: 'a.zip', branch: WS });
     expect(res.status).toBe(200);
-    expect(recorded).toContainEqual(['unzip', WS, 'a.zip', undefined]);
+    // The archive is named without the clone-folder prefix; the normaliser
+    // places it inside the checkout, and THAT is the path the service is given.
+    expect(recorded).toContainEqual(['unzip', WS, 'knowledge-base/a.zip', undefined]);
+  });
+
+  it('unzip never extracts a roles.yaml — extraction bypasses the filesystem gate that checks it', async () => {
+    archiveEntries = ['knowledge-base/KnowledgeBase/notes.md', 'knowledge-base/roles.yaml'];
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/unzip`, { path: 'knowledge-base/a.zip', branch: WS });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { extracted: string[]; skipped: { path: string; reason: string }[] };
+    expect(body.extracted).toEqual(['knowledge-base/KnowledgeBase/notes.md']);
+    expect(body.skipped).toEqual([
+      { path: 'knowledge-base/roles.yaml', reason: expect.stringContaining('roles.yaml is never extracted') },
+    ]);
   });
 
   it('the registered core tool appears in the internal manual', async () => {