@bevel-software/platform-core-backend 0.1.0

package/src/modules/workspace/__tests__/workspace.routes.download.test.ts

@@ -0,0 +1,303 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { AuthService } from '../../auth/auth.service.js';
+import { AccessConfigError } from '../../access/access-errors.js';
+import { createWorkspaceRoutes } from '../workspace.routes.js';
+import type { ICreatorAccess } from '../../access/creator-access.js';
+import { FolderTooLargeError, type WorkspaceService } from '../workspace.service.js';
+
+const stubCreatorAccess: ICreatorAccess = {
+  planForCreate: async () => null,
+  grantInExtractedFile: async () => null,
+  noteAccessFileWritten: () => {},
+};
+
+/**
+ * Contract test for the `?download=1` flavours of the workspace routes:
+ *
+ *   - GET /workspace/:id/file/raw?download=1  (single-file save)
+ *   - GET /workspace/:id/folder/zip?download=1  (folder → zip save)
+ *
+ * Both are gated on the dedicated `Download` role in roles.yaml. Admin
+ * status is fully orthogonal — being in the `Admin` role does NOT
+ * implicitly grant Download; users must be listed under the `Download`
+ * role to receive bytes. The inline branch of /file/raw (no flag) stays
+ * open to every authenticated user so the PdfRenderer and image renderers
+ * keep working for everyone.
+ */
+
+const USER_ID = 'user-1';
+const USER = { id: USER_ID, email: 'alice@example.com', name: 'Alice' };
+const WORKSPACE_ID = 'target-company-state';
+const FILE_BYTES = Buffer.from('hello world');
+const ZIP_BYTES = Buffer.from('PK\x03\x04 fake-zip-bytes');
+
+interface Harness {
+  server: Server;
+  baseUrl: string;
+  canDownload: ReturnType<typeof vi.fn>;
+  canWrite: ReturnType<typeof vi.fn>;
+  createFolderZip: ReturnType<typeof vi.fn>;
+}
+
+async function makeHarness(opts: {
+  canDownload: boolean;
+  folderZip?: () => Promise<Buffer> | Buffer;
+  /** When set, canDownload rejects with this error instead of returning a bool. */
+  canDownloadError?: Error;
+}): Promise<Harness> {
+  const canDownload = vi.fn(async () => {
+    if (opts.canDownloadError) throw opts.canDownloadError;
+    return opts.canDownload;
+  });
+  const canWrite = vi.fn();
+  const accessControl: IAccessControl = {
+    canWrite,
+    canWriteBatch: vi.fn(),
+    // The /file/raw route now read-gates before the download gate; these tests
+    // exercise the download verb, so reads pass.
+    canRead: vi.fn(async () => true),
+    canReadBatch: vi.fn(async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, true]))),
+    canDownload,
+    eligibleWriters: vi.fn(),
+    eligibleWriterEmails: vi.fn(),
+    invalidate: vi.fn(),
+    findEmailByHash: vi.fn(),
+    canWriteAtRef: vi.fn(),
+    canWriteBatchAtRef: vi.fn(),
+    eligibleWritersAtRef: vi.fn(),
+    eligibleWritersForPathsAtRef: vi.fn(),
+  } as unknown as IAccessControl;
+
+  const createFolderZip = vi.fn(async () => {
+    if (opts.folderZip) return opts.folderZip();
+    return ZIP_BYTES;
+  });
+
+  // Partial<WorkspaceService> + final cast keeps the contract typed at the
+  // call site (createWorkspaceRoutes wants a full WorkspaceService) while
+  // letting us stub only the two methods these tests exercise.
+  const workspaceServiceMock: Partial<WorkspaceService> = {
+    readFileBinary: vi.fn(async () => FILE_BYTES),
+    createFolderZip,
+  };
+  const workspaceService = workspaceServiceMock as WorkspaceService;
+
+  const authServiceMock: Partial<AuthService> = {
+    getUserById: vi.fn(async () => USER),
+  };
+  const authService = authServiceMock as AuthService;
+
+  const workflowService = {} as unknown as IWorkflowService;
+  const eventBus = {} as unknown as WorkflowEventBus;
+
+  const app = express();
+  app.use(express.json());
+  app.use('/api', (req, _res, next) => {
+    (req as any).userId = USER_ID;
+    next();
+  });
+  app.use('/api', createWorkspaceRoutes(
+    workspaceService,
+    authService,
+    workflowService,
+    eventBus,
+    accessControl,
+    'knowledge-base',
+    stubCreatorAccess,
+  ));
+
+  const server = await new Promise<Server>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  // `server.address()` returns `AddressInfo | string | null`. The string
+  // branch is for Unix-domain sockets and the null branch for an
+  // unbound listener — neither can happen here (we awaited `listen(0,
+  // ...)` on a TCP port), so a narrow + throw is sufficient and avoids
+  // the `as any` lint.
+  const addr = server.address();
+  if (addr === null || typeof addr === 'string') {
+    throw new Error(`Unexpected server.address() shape: ${JSON.stringify(addr)}`);
+  }
+  const port = (addr as AddressInfo).port;
+  return { server, baseUrl: `http://127.0.0.1:${port}`, canDownload, canWrite, createFolderZip };
+}
+
+async function closeServer(server: Server): Promise<void> {
+  await new Promise<void>((resolve, reject) =>
+    server.close((err) => (err ? reject(err) : resolve())),
+  );
+}
+
+describe('GET /workspace/:id/file/raw — ?download=1 gated on Download role', () => {
+  let h: Harness | null = null;
+  afterEach(async () => { if (h) await closeServer(h.server); h = null; });
+
+  it('user with Download role gets 200 + attachment disposition + bytes', async () => {
+    h = await makeHarness({ canDownload: true });
+    const res = await fetch(
+      `${h.baseUrl}/api/workspace/${WORKSPACE_ID}/file/raw?path=${encodeURIComponent('Knowledge/Foo.md')}&download=1`,
+    );
+    expect(res.status).toBe(200);
+    const dispo = res.headers.get('content-disposition');
+    expect(dispo).toBeTruthy();
+    expect(dispo).toContain('attachment');
+    expect(dispo).toContain(`filename*=UTF-8''${encodeURIComponent('Foo.md')}`);
+    expect(res.headers.get('x-content-type-options')).toBe('nosniff');
+    const buf = Buffer.from(await res.arrayBuffer());
+    expect(buf.equals(FILE_BYTES)).toBe(true);
+    // canDownload is path-scoped now; the route strips the kbDirName prefix
+    // before consulting the access service (mirrors useFileAccess on the
+    // frontend), so the resolver sees the repo-relative path.
+    expect(h.canDownload).toHaveBeenCalledWith(WORKSPACE_ID, USER.email, 'Knowledge/Foo.md');
+    // canWrite must NOT be consulted by the download gate — the two verbs
+    // are independent.
+    expect(h.canWrite).not.toHaveBeenCalled();
+  });
+
+  it('user without Download role gets 403 with no body bytes', async () => {
+    h = await makeHarness({ canDownload: false });
+    const res = await fetch(
+      `${h.baseUrl}/api/workspace/${WORKSPACE_ID}/file/raw?path=${encodeURIComponent('Knowledge/Foo.md')}&download=1`,
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe('Download permission required');
+    expect(res.headers.get('content-disposition')).toBeNull();
+  });
+
+  it('inline view (no ?download flag) returns 200 for any authed user without consulting access-control', async () => {
+    // Even a user with no download permission must be able to view PDFs /
+    // images inline — that's the PdfRenderer happy path. The route must not
+    // call canDownload at all on this branch.
+    h = await makeHarness({ canDownload: false });
+    const res = await fetch(
+      `${h.baseUrl}/api/workspace/${WORKSPACE_ID}/file/raw?path=${encodeURIComponent('Knowledge/Foo.md')}`,
+    );
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-disposition')).toBeNull();
+    expect(h.canDownload).not.toHaveBeenCalled();
+  });
+
+  it('returns 500 with AccessConfigError payload when roles.yaml / access.md fails to load', async () => {
+    // Regression guard: if `canDownload` throws inside requireDownloadPermission
+    // (e.g. roles.yaml is missing or the access tree is unrecoverably
+    // malformed) and we don't catch it, the async rejection bubbles past
+    // Express and the request hangs (or 500s without the helpful
+    // config-error payload). The route should surface the
+    // WorkflowDomainError shape — same JSON the per-path /access endpoint
+    // returns when it hits the same exception — so the operator can see
+    // which access.md file is broken.
+    const configErr = new AccessConfigError([
+      "Knowledge/Sales/access.md: unknown role 'Product Manager'",
+    ]);
+    h = await makeHarness({ canDownload: true, canDownloadError: configErr });
+    const res = await fetch(
+      `${h.baseUrl}/api/workspace/${WORKSPACE_ID}/file/raw?path=${encodeURIComponent('Knowledge/Foo.md')}&download=1`,
+    );
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: string; accessConfigErrors?: string[] };
+    expect(body.error).toContain('Access-control config is invalid');
+    expect(body.accessConfigErrors?.[0]).toContain("unknown role 'Product Manager'");
+  });
+
+  it('forces SVG to octet-stream when downloading (anti-XSS), preserves image/svg+xml inline', async () => {
+    h = await makeHarness({ canDownload: true });
+    const dl = await fetch(
+      `${h.baseUrl}/api/workspace/${WORKSPACE_ID}/file/raw?path=${encodeURIComponent('icon.svg')}&download=1`,
+    );
+    expect(dl.headers.get('content-type')).toBe('application/octet-stream');
+
+    await closeServer(h.server);
+    h = await makeHarness({ canDownload: false });
+    const inline = await fetch(
+      `${h.baseUrl}/api/workspace/${WORKSPACE_ID}/file/raw?path=${encodeURIComponent('icon.svg')}`,
+    );
+    expect(inline.headers.get('content-type')).toBe('image/svg+xml');
+  });
+});
+
+describe('GET /workspace/:id/folder/zip — gated on Download role', () => {
+  let h: Harness | null = null;
+  afterEach(async () => { if (h) await closeServer(h.server); h = null; });
+
+  it('user with Download role gets a 200 zip with attachment disposition', async () => {
+    h = await makeHarness({ canDownload: true });
+    const res = await fetch(
+      `${h.baseUrl}/api/workspace/${WORKSPACE_ID}/folder/zip?path=${encodeURIComponent('Knowledge/Sales')}&download=1`,
+    );
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toBe('application/zip');
+    expect(res.headers.get('x-content-type-options')).toBe('nosniff');
+    const dispo = res.headers.get('content-disposition');
+    expect(dispo).toBeTruthy();
+    expect(dispo).toContain('attachment');
+    expect(dispo).toContain(`filename*=UTF-8''${encodeURIComponent('Sales.zip')}`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    expect(buf.equals(ZIP_BYTES)).toBe(true);
+    expect(h.canDownload).toHaveBeenCalledWith(WORKSPACE_ID, USER.email, 'Knowledge/Sales');
+    expect(h.createFolderZip).toHaveBeenCalledWith(WORKSPACE_ID, 'Knowledge/Sales');
+  });
+
+  it('user without Download role gets 403 and no zip is built', async () => {
+    h = await makeHarness({ canDownload: false });
+    const res = await fetch(
+      `${h.baseUrl}/api/workspace/${WORKSPACE_ID}/folder/zip?path=${encodeURIComponent('Knowledge/Sales')}&download=1`,
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe('Download permission required');
+    expect(h.createFolderZip).not.toHaveBeenCalled();
+  });
+
+  it('requires ?download=1 — a stray inline call is rejected with 400', async () => {
+    // Folder zip is download-only; refuse the inline shape so the URL contract
+    // matches the file route and there's no ambiguity about what should happen.
+    h = await makeHarness({ canDownload: true });
+    const res = await fetch(
+      `${h.baseUrl}/api/workspace/${WORKSPACE_ID}/folder/zip?path=${encodeURIComponent('Knowledge/Sales')}`,
+    );
+    expect(res.status).toBe(400);
+    expect(h.createFolderZip).not.toHaveBeenCalled();
+  });
+
+  it('maps FolderTooLargeError to 413 with the limit-bearing message', async () => {
+    h = await makeHarness({
+      canDownload: true,
+      folderZip: async () => { throw new FolderTooLargeError(500 * 1024 * 1024); },
+    });
+    const res = await fetch(
+      `${h.baseUrl}/api/workspace/${WORKSPACE_ID}/folder/zip?path=${encodeURIComponent('Big')}&download=1`,
+    );
+    expect(res.status).toBe(413);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toContain('524288000');
+  });
+
+  it('maps Path traversal detected to 403', async () => {
+    h = await makeHarness({
+      canDownload: true,
+      folderZip: async () => { throw new Error('Path traversal detected'); },
+    });
+    const res = await fetch(
+      `${h.baseUrl}/api/workspace/${WORKSPACE_ID}/folder/zip?path=${encodeURIComponent('../escape')}&download=1`,
+    );
+    expect(res.status).toBe(403);
+  });
+
+  it('maps Not a directory to 400 (user pointed at a file)', async () => {
+    h = await makeHarness({
+      canDownload: true,
+      folderZip: async () => { throw new Error('Not a directory'); },
+    });
+    const res = await fetch(
+      `${h.baseUrl}/api/workspace/${WORKSPACE_ID}/folder/zip?path=${encodeURIComponent('Knowledge/Foo.md')}&download=1`,
+    );
+    expect(res.status).toBe(400);
+  });
+});

package/src/modules/workspace/__tests__/workspace.routes.read-gate.test.ts

@@ -0,0 +1,276 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { ICreatorAccess } from '../../access/creator-access.js';
+import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { AuthService } from '../../auth/auth.service.js';
+import { createWorkspaceRoutes } from '../workspace.routes.js';
+import type { WorkspaceService, ReadTreeFilter } from '../workspace.service.js';
+
+/**
+ * Contract test for the read-permission gates on the human read routes:
+ *   GET /file, /file/raw (inline), /resolve-id, /kb-files, /files.
+ * `allow(path)` decides each verdict; by convention any path containing
+ * "Secret" is denied. The harness wires the real route layer over mocked
+ * access + workspace services. (The /graph + /resolve-id routes live in the
+ * enterprise kb-graph module; their gate tests moved with them.)
+ */
+
+const USER_ID = 'user-1';
+const USER = { id: USER_ID, email: 'alice@example.com', name: 'Alice' };
+const WS = 'target-company-state';
+const KB = 'knowledge-base';
+
+const allow = (p: string) => !p.includes('Secret');
+
+const stubCreatorAccess: ICreatorAccess = {
+  planForCreate: async () => null,
+  grantInExtractedFile: async () => null,
+  noteAccessFileWritten: () => {},
+};
+
+
+interface Harness {
+  server: Server;
+  baseUrl: string;
+  canRead: ReturnType<typeof vi.fn>;
+  canReadBatchFull: ReturnType<typeof vi.fn>;
+  listFilesFilter: () => ReadTreeFilter | undefined;
+}
+
+async function makeHarness(opts: {
+  kbFiles?: Record<string, string>;
+  allowFn?: (p: string) => boolean;
+} = {}): Promise<Harness> {
+  const allowP = opts.allowFn ?? allow;
+  const canRead = vi.fn(async (_w: string, _e: string, p: string) => allowP(p));
+  const batch = async (_w: string, _e: string, paths: string[]) =>
+    new Map(paths.map((p) => [p, allowP(p)]));
+  const canReadBatchFull = vi.fn(batch);
+  const accessControl = {
+    canRead,
+    canReadBatch: canReadBatchFull,
+  } as unknown as IAccessControl;
+
+  let captured: ReadTreeFilter | undefined;
+  const workspaceService = {
+    getOrCreateForBranch: vi.fn(async (branch: string) => ({
+      id: branch,
+      name: branch,
+      absolutePath: `/tmp/${branch}`,
+      createdAt: new Date(0).toISOString(),
+      kbDirName: KB,
+    })),
+    readFile: vi.fn(async () => 'CONTENT'),
+    readFileBinary: vi.fn(async () => Buffer.from('BYTES')),
+    readAllKbFiles: vi.fn(async () => opts.kbFiles ?? {}),
+    listFiles: vi.fn(async (_id: string, filter?: ReadTreeFilter) => {
+      captured = filter;
+      return { name: 'root', relativePath: '.', type: 'directory', children: [] };
+    }),
+  } as unknown as WorkspaceService;
+
+  const authService = { getUserById: vi.fn(async () => USER) } as unknown as AuthService;
+
+  const app = express();
+  app.use(express.json());
+  app.use('/api', (req, _res, next) => {
+    (req as unknown as { userId: string }).userId = USER_ID;
+    next();
+  });
+  app.use(
+    '/api',
+    createWorkspaceRoutes(
+      workspaceService,
+      authService,
+      {} as unknown as IWorkflowService,
+      {} as unknown as WorkflowEventBus,
+      accessControl,
+      KB,
+      stubCreatorAccess,
+    ),
+  );
+  const server = await new Promise<Server>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  const addr = server.address() as AddressInfo;
+  return {
+    server,
+    baseUrl: `http://127.0.0.1:${addr.port}`,
+    canRead,
+    canReadBatchFull,
+    listFilesFilter: () => captured,
+  };
+}
+
+function close(s: Server): Promise<void> {
+  return new Promise((resolve, reject) => s.close((e) => (e ? reject(e) : resolve())));
+}
+
+describe('read-permission gates on human read routes', () => {
+  let h: Harness | null = null;
+  afterEach(async () => { if (h) await close(h.server); h = null; });
+
+  const get = (path: string) => fetch(`${h!.baseUrl}/api/workspace/${WS}${path}`);
+
+  it('GET /file: readable → 200, denied → 403', async () => {
+    h = await makeHarness();
+    // Paths are workspace-relative (kbDir-prefixed), as the file tree produces
+    // and `readFile` resolves them.
+    const ok = await get(`/file?path=${encodeURIComponent(`${KB}/Knowledge/Open/a.md`)}`);
+    expect(ok.status).toBe(200);
+    expect((await ok.json()).content).toBe('CONTENT');
+
+    const denied = await get(`/file?path=${encodeURIComponent(`${KB}/Knowledge/Secret/x.md`)}`);
+    expect(denied.status).toBe(403);
+    // canRead consulted with the KB-repo-relative path (kbDir prefix stripped).
+    expect(h.canRead).toHaveBeenCalledWith(WS, USER.email, 'Knowledge/Secret/x.md');
+  });
+
+  it('GET /file: a non-KB path (reserved workspace file) is not read-gated', async () => {
+    h = await makeHarness();
+    // Outside `kbDirName` → carries no read rules → served without a canRead
+    // check (matches the agent tools and diff routes). Previously this 403'd
+    // because the full path was passed to default-deny canRead.
+    const res = await get(`/file?path=${encodeURIComponent('reserved-config.json')}`);
+    expect(res.status).toBe(200);
+    expect(h.canRead).not.toHaveBeenCalled();
+  });
+
+  it('GET /file/raw (inline, no download) is read-gated', async () => {
+    h = await makeHarness();
+    const denied = await get(`/file/raw?path=${encodeURIComponent(`${KB}/Secret/x.png`)}`);
+    expect(denied.status).toBe(403);
+    const ok = await get(`/file/raw?path=${encodeURIComponent(`${KB}/Open/a.png`)}`);
+    expect(ok.status).toBe(200);
+  });
+
+  // NOTE (core split): the `GET /resolve-id` and `GET /graph` read-gate tests
+  // moved with the kb-graph module (enterprise) — those routes are not part of
+  // the core workspace surface.
+
+  it('GET /kb-files drops unreadable nodes from the graph payload', async () => {
+    h = await makeHarness({ kbFiles: { 'Knowledge/Open/a.md': 'A', 'Knowledge/Secret/x.md': 'S' } });
+    const res = await get('/kb-files');
+    expect(res.status).toBe(200);
+    const { files } = await res.json();
+    expect(files['Knowledge/Open/a.md']).toBe('A');
+    expect(files['Knowledge/Secret/x.md']).toBeUndefined();
+  });
+
+  it('GET /files passes a working shallow read filter to listFiles', async () => {
+    h = await makeHarness();
+    expect((await get('/files')).status).toBe(200);
+    const filter = h.listFilesFilter();
+    expect(typeof filter).toBe('function');
+    // The filter maps workspace-relative paths (kbDir-prefixed) → verdicts,
+    // stripping the kbDir and consulting the full canReadBatch.
+    const verdict = await filter!([
+      `${KB}/Knowledge/Open/a.md`,
+      `${KB}/Knowledge/Secret/x.md`,
+    ]);
+    expect(verdict.get(`${KB}/Knowledge/Open/a.md`)).toBe(true);
+    expect(verdict.get(`${KB}/Knowledge/Secret/x.md`)).toBe(false);
+  });
+
+  it('keeps the structural root folders visible even when nothing is readable', async () => {
+    // A user with no read grants: the access batch denies everything. The
+    // structural top-level folders (KnowledgeBase, Data, Agents, Pipelines,
+    // Skills, Tools) must still resolve readable (so the explorer renders its
+    // section view), while their contents stay gated.
+    h = await makeHarness({ allowFn: () => false });
+    expect((await get('/files')).status).toBe(200);
+    const filter = h.listFilesFilter();
+    const verdict = await filter!([
+      `${KB}/KnowledgeBase`,
+      `${KB}/Data`,
+      `${KB}/Agents`,
+      `${KB}/Pipelines`,
+      `${KB}/Skills`,
+      `${KB}/Tools`,
+      `${KB}/KnowledgeBase/Open/a.md`,
+      `${KB}/Data/Ops/Knowledge/item.md`,
+      `${KB}/Skills/rfi/SKILL.md`,
+    ]);
+    // Folders themselves: forced visible.
+    expect(verdict.get(`${KB}/KnowledgeBase`)).toBe(true);
+    expect(verdict.get(`${KB}/Data`)).toBe(true);
+    expect(verdict.get(`${KB}/Agents`)).toBe(true);
+    expect(verdict.get(`${KB}/Pipelines`)).toBe(true);
+    expect(verdict.get(`${KB}/Skills`)).toBe(true);
+    expect(verdict.get(`${KB}/Tools`)).toBe(true);
+    // Their contents: still gated (the override matches only the exact folder).
+    expect(verdict.get(`${KB}/KnowledgeBase/Open/a.md`)).toBe(false);
+    expect(verdict.get(`${KB}/Data/Ops/Knowledge/item.md`)).toBe(false);
+    expect(verdict.get(`${KB}/Skills/rfi/SKILL.md`)).toBe(false);
+  });
+
+  it('resolves every entry with the FULL read batch (frontmatter grants AND denies honoured)', async () => {
+    // The tree filter consults the full canReadBatch for ALL paths in one
+    // call — a per-file frontmatter grant (e.g. the creator read grant a
+    // loose root-level .md gets on creation) makes the file visible, and a
+    // frontmatter deny hides it, exactly matching what the content route
+    // will enforce on open.
+    h = await makeHarness({ allowFn: () => false });
+    const full = h.canReadBatchFull;
+    full.mockImplementation(async (_w: string, _e: string, paths: string[]) =>
+      new Map(paths.map((p) => [p, p === 'KnowledgeBase/mine.md'])));
+    expect((await get('/files')).status).toBe(200);
+    const filter = h.listFilesFilter();
+    const verdict = await filter!([
+      `${KB}/KnowledgeBase/mine.md`, // frontmatter grant → visible
+      `${KB}/KnowledgeBase/other.md`, // no grant → hidden
+      `${KB}/KnowledgeBase/Secret/deep.md`, // no grant → hidden
+    ]);
+    expect(verdict.get(`${KB}/KnowledgeBase/mine.md`)).toBe(true);
+    expect(verdict.get(`${KB}/KnowledgeBase/other.md`)).toBe(false);
+    expect(verdict.get(`${KB}/KnowledgeBase/Secret/deep.md`)).toBe(false);
+    // ONE batched call covers every path — no per-file fan-out.
+    expect(full).toHaveBeenCalledTimes(1);
+    expect(full.mock.calls[0][2]).toEqual([
+      'KnowledgeBase/mine.md',
+      'KnowledgeBase/other.md',
+      'KnowledgeBase/Secret/deep.md',
+    ]);
+  });
+
+  it('legacy layout: root-level Knowledge/ is forced visible and its loose files get the full check', async () => {
+    // Clones that predate the KnowledgeBase/Skills split keep their knowledge
+    // root at `Knowledge/` (repo root). It must get the same structural-root
+    // treatment: the folder itself stays visible, and a loose file directly
+    // under it (whose creator grant lives in frontmatter) is re-checked with
+    // the FULL batch.
+    h = await makeHarness({ allowFn: () => false });
+    h.canReadBatchFull.mockImplementation(async (_w: string, _e: string, paths: string[]) =>
+      new Map(paths.map((p) => [p, p === 'Knowledge/mine.md'])));
+    expect((await get('/files')).status).toBe(200);
+    const filter = h.listFilesFilter();
+    const verdict = await filter!([
+      `${KB}/Knowledge`,
+      `${KB}/Knowledge/mine.md`,
+      `${KB}/Knowledge/other.md`,
+      `${KB}/Knowledge/Secret/deep.md`,
+    ]);
+    expect(verdict.get(`${KB}/Knowledge`)).toBe(true);
+    expect(verdict.get(`${KB}/Knowledge/mine.md`)).toBe(true);
+    expect(verdict.get(`${KB}/Knowledge/other.md`)).toBe(false);
+    expect(verdict.get(`${KB}/Knowledge/Secret/deep.md`)).toBe(false);
+  });
+
+  it('GET /workspace bootstrap also returns a read-filtered file tree', async () => {
+    h = await makeHarness();
+    const res = await fetch(`${h.baseUrl}/api/workspace?branch=${encodeURIComponent(WS)}`);
+    expect(res.status).toBe(200);
+    const filter = h.listFilesFilter();
+    expect(typeof filter).toBe('function');
+    const verdict = await filter!([
+      `${KB}/Knowledge/Open/a.md`,
+      `${KB}/Knowledge/Secret/x.md`,
+    ]);
+    expect(verdict.get(`${KB}/Knowledge/Open/a.md`)).toBe(true);
+    expect(verdict.get(`${KB}/Knowledge/Secret/x.md`)).toBe(false);
+  });
+});