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

package/src/modules/workspace/__tests__/workspace.routes.create-grant.test.ts

@@ -2,9 +2,12 @@ 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 { NodeFs } from '../../kb-fs/node-fs.js';
 import type { IWorkflowService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { ICreatorAccess } from '../../access-model/creator.js';
+import type { ChangeReadVerdict, IChangeReadGate } from '../../access-model/change-gate.js';
+import { AccessDeniedError } from '../../access-model/access-errors.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
@@ -13,11 +16,12 @@ import type { WorkspaceService } from '../workspace.service.js';
 
 /**
  * Contract test for the creator read-grant hooks on the creation routes:
- * PUT /file (frontmatter transform + subtree seed), POST /directory (subtree
- * seed before the .gitkeep cycle), POST /unzip (in-place grant per extracted
- * file). The planner itself is unit-tested in creator-access.test.ts — here
- * it's mocked to return canned plans and the assertion is on what the route
- * writes, locks, and invalidates.
+ * PUT /file and POST /upload (a new root folder's seed before the file),
+ * POST /directory (the seed before the .gitkeep cycle), POST /unzip (the
+ * read gate on the destination before extraction). The planner itself is
+ * unit-tested in creator-access.test.ts — here it's mocked to return canned
+ * plans and the assertion is on what the route writes, locks, and
+ * invalidates.
  */
 
 const USER_ID = 'user-1';
@@ -29,29 +33,38 @@ interface Harness {
   server: Server;
   baseUrl: string;
   writes: Array<{ path: string; content: string }>;
+  /** The exact bytes each binary write (POST /upload) handed the service. */
+  binaryWrites: Array<{ path: string; bytes: Buffer }>;
   lockedPaths: string[];
   writeFileMock: ReturnType<typeof vi.fn>;
   creatorAccess: {
     planForCreate: ReturnType<typeof vi.fn>;
-    grantInExtractedFile: ReturnType<typeof vi.fn>;
     noteAccessFileWritten: ReturnType<typeof vi.fn>;
   };
+  unzipFileMock: ReturnType<typeof vi.fn>;
 }
 
-async function makeHarness(opts: { extracted?: string[] } = {}): Promise<Harness> {
+async function makeHarness(opts: { extracted?: string[]; changeGate?: IChangeReadGate } = {}): Promise<Harness> {
   const writes: Array<{ path: string; content: string }> = [];
   const lockedPaths: string[] = [];
+  const binaryWrites: Array<{ path: string; bytes: Buffer }> = [];
 
   const writeFileMock = vi.fn(async (_id: string, p: string, content: string) => {
     writes.push({ path: p, content });
   });
+  const unzipFileMock = vi.fn(async () => ({ extracted: opts.extracted ?? [] }));
   const workspaceService = {
     writeFile: writeFileMock,
     writeFileBinary: vi.fn(async (_id: string, p: string, data: Uint8Array) => {
       writes.push({ path: p, content: Buffer.from(data).toString('utf8') });
+      binaryWrites.push({ path: p, bytes: Buffer.from(data) });
     }),
     createDirectory: vi.fn(async () => undefined),
-    unzipFile: vi.fn(async () => ({ extracted: opts.extracted ?? [] })),
+    unzipFile: unzipFileMock,
+    // `PUT /file` runs its precondition, plan and write inside one turn for
+    // the target path. Straight through here: what this file asserts is the
+    // ORDER of the plan's writes and locks, which the real turn preserves.
+    withPathTurn: vi.fn(async (_id: string, _p: string, op: () => Promise<unknown>) => op()),
   } as unknown as WorkspaceService;
 
   const workflowService = {
@@ -66,7 +79,6 @@ async function makeHarness(opts: { extracted?: string[] } = {}): Promise<Harness
 
   const creatorAccess = {
     planForCreate: vi.fn(async () => null),
-    grantInExtractedFile: vi.fn(async () => null),
     noteAccessFileWritten: vi.fn(),
   };
 
@@ -91,6 +103,9 @@ async function makeHarness(opts: { extracted?: string[] } = {}): Promise<Harness
         creatorAccess as unknown as ICreatorAccess,
       // Not exercised here — only `.bevelignore`'s tree visibility consults it.
       { isAdmin: async () => false } as unknown as IAdminAccessService,
+      new NodeFs(),
+      undefined,
+      opts.changeGate,
     ),
   );
   const server = await new Promise<Server>((resolve) => {
@@ -101,9 +116,11 @@ async function makeHarness(opts: { extracted?: string[] } = {}): Promise<Harness
     server,
     baseUrl: `http://127.0.0.1:${addr.port}`,
     writes,
+    binaryWrites,
     lockedPaths,
     writeFileMock,
     creatorAccess,
+    unzipFileMock,
   };
 }
 
@@ -118,12 +135,8 @@ describe('creator read-grant hooks on the creation routes', () => {
     h = null;
   });
 
-  it('PUT /file with a frontmatter plan writes the transformed content in ONE write', async () => {
+  it('PUT /file asks the planner about the new file and writes the content as given', async () => {
     h = await makeHarness();
-    h.creatorAccess.planForCreate.mockResolvedValue({
-      kind: 'frontmatter',
-      apply: (c: string) => `---\nread: Alice <alice@example.com>\n---\n${c}`,
-    });
     const res = await fetch(
       `${h.baseUrl}/api/workspace/${WS}/file?path=${encodeURIComponent(`${KB}/KnowledgeBase/new.md`)}`,
       { method: 'PUT', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ content: '# New\n' }) },
@@ -132,9 +145,9 @@ describe('creator read-grant hooks on the creation routes', () => {
     expect(h.creatorAccess.planForCreate).toHaveBeenCalledWith(
       WS, USER, `${KB}/KnowledgeBase/new.md`, 'file',
     );
-    expect(h.writes).toEqual([
-      { path: `${KB}/KnowledgeBase/new.md`, content: '---\nread: Alice <alice@example.com>\n---\n# New\n' },
-    ]);
+    // No plan rewrites file content: the one grant that exists is seeded into
+    // a new root folder's access.md, never into the file.
+    expect(h.writes).toEqual([{ path: `${KB}/KnowledgeBase/new.md`, content: '# New\n' }]);
   });
 
   it('PUT /file with a seed plan writes the access.md under its own lock BEFORE the file', async () => {
@@ -158,14 +171,14 @@ describe('creator read-grant hooks on the creation routes', () => {
     expect(h.creatorAccess.noteAccessFileWritten).toHaveBeenCalledWith(WS);
   });
 
-  it('a failing seed never fails the creation itself', async () => {
+  it('a failing seed fails the creation before anything lands — a root folder must not appear invisible to its creator', async () => {
     h = await makeHarness();
     h.creatorAccess.planForCreate.mockResolvedValue({
       kind: 'seed-access-md',
       wsRelPath: `${KB}/KnowledgeBase/Mine/access.md`,
       apply: () => 'seed',
     });
-    // Only the seed write blows up; the file write succeeds.
+    // The seed write blows up; the file write must then never be attempted.
     h.writeFileMock.mockImplementation(async (_id: string, p: string, content: string) => {
       if (p.endsWith('/access.md')) throw new Error('boom');
       h!.writes.push({ path: p, content });
@@ -174,8 +187,27 @@ describe('creator read-grant hooks on the creation routes', () => {
       `${h.baseUrl}/api/workspace/${WS}/file?path=${encodeURIComponent(`${KB}/KnowledgeBase/Mine/doc.md`)}`,
       { method: 'PUT', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ content: 'body' }) },
     );
-    expect(res.status).toBe(200);
-    expect(h.writes).toEqual([{ path: `${KB}/KnowledgeBase/Mine/doc.md`, content: 'body' }]);
+    expect(res.status).toBe(500);
+    expect(h.writes).toEqual([]);
+  });
+
+  it('an unzip whose destination seed fails extracts nothing', async () => {
+    h = await makeHarness({ extracted: [`${KB}/KnowledgeBase/Fresh/a.md`] });
+    h.creatorAccess.planForCreate.mockResolvedValue({
+      kind: 'seed-access-md',
+      wsRelPath: `${KB}/KnowledgeBase/Fresh/access.md`,
+      apply: () => 'seed',
+    });
+    h.writeFileMock.mockImplementation(async () => {
+      throw new Error('boom');
+    });
+    const res = await fetch(`${h.baseUrl}/api/workspace/${WS}/unzip`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ path: `${KB}/KnowledgeBase/drop.zip`, destination: `${KB}/KnowledgeBase/Fresh` }),
+    });
+    expect(res.status).toBe(500);
+    expect(h.unzipFileMock).not.toHaveBeenCalled();
   });
 
   it('POST /directory seeds the new folder access.md before the .gitkeep cycle', async () => {
@@ -201,36 +233,156 @@ describe('creator read-grant hooks on the creation routes', () => {
     expect(h.lockedPaths[1]).toBe(`${KB}/KnowledgeBase/Projects/.gitkeep`);
   });
 
-  it('POST /unzip splices the creator grant into extracted files that need one', async () => {
-    const extracted = [`${KB}/KnowledgeBase/a.md`, `${KB}/KnowledgeBase/b.md`];
+  it('POST /unzip locks each extracted file for its commit and rewrites none of them', async () => {
+    const extracted = [`${KB}/KnowledgeBase/a.md`, `${KB}/KnowledgeBase/b.pdf`];
     h = await makeHarness({ extracted });
-    h.creatorAccess.grantInExtractedFile.mockImplementation(
-      async (_w: string, _u: unknown, p: string) =>
-        p.endsWith('a.md') ? 'GRANTED CONTENT' : null,
-    );
     const res = await fetch(`${h.baseUrl}/api/workspace/${WS}/unzip`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ path: `${KB}/KnowledgeBase/drop.zip` }),
     });
     expect(res.status).toBe(200);
-    // a.md got rewritten with the granted content; b.md untouched.
-    expect(h.writes).toEqual([{ path: `${KB}/KnowledgeBase/a.md`, content: 'GRANTED CONTENT' }]);
+    expect(h.lockedPaths).toEqual(extracted);
+    expect(h.writes).toEqual([]);
   });
 
-  it('POST /upload transforms an uploaded .md through the frontmatter plan', async () => {
+  it('POST /upload lands an uploaded .md as given, with no grant folded in', async () => {
     h = await makeHarness();
-    h.creatorAccess.planForCreate.mockResolvedValue({
-      kind: 'frontmatter',
-      apply: (c: string) => `---\nread: Alice <alice@example.com>\n---\n${c}`,
-    });
     const res = await fetch(
       `${h.baseUrl}/api/workspace/${WS}/upload?path=${encodeURIComponent(`${KB}/KnowledgeBase/up.md`)}`,
       { method: 'POST', headers: { 'content-type': 'application/octet-stream' }, body: '# Uploaded\n' },
     );
     expect(res.status).toBe(200);
-    expect(h.writes).toEqual([
-      { path: `${KB}/KnowledgeBase/up.md`, content: '---\nread: Alice <alice@example.com>\n---\n# Uploaded\n' },
-    ]);
+    expect(h.writes).toEqual([{ path: `${KB}/KnowledgeBase/up.md`, content: '# Uploaded\n' }]);
+  });
+});
+
+/**
+ * Archive extraction is the one route whose bytes land on disk BEFORE the
+ * lock, so the lock's read gate would meet files already there. The route
+ * asks the same gate about the destination first, and extracts nothing when
+ * it refuses.
+ */
+describe('POST /unzip asks the read-before-write gate about its destination first', () => {
+  let h: Harness | null = null;
+  afterEach(async () => {
+    if (h) await close(h.server);
+    h = null;
+  });
+
+  function gateThat(verdict: ChangeReadVerdict) {
+    const judge = vi.fn(async () => verdict);
+    const gate: IChangeReadGate = {
+      judge,
+      assertMayChange: async (...args) => {
+        const v = await judge(...args);
+        if (v.allowed) return;
+        throw new AccessDeniedError({ path: args[2], eligibleRoles: [], eligibleUsers: [], unreadable: v.unreadable });
+      },
+    };
+    return { gate, judge };
+  }
+
+  it('a destination the caller cannot read is refused whole — nothing is extracted or locked', async () => {
+    const { gate, judge } = gateThat({ allowed: false, unreadable: 'KnowledgeBase/Sealed' });
+    h = await makeHarness({ extracted: [`${KB}/KnowledgeBase/Sealed/a.md`], changeGate: gate });
+    const res = await fetch(`${h.baseUrl}/api/workspace/${WS}/unzip`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ path: `${KB}/KnowledgeBase/drop.zip`, destination: `${KB}/KnowledgeBase/Sealed` }),
+    });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toContain('You don\'t have read access to "KnowledgeBase/Sealed"');
+    // Asked about the DESTINATION as a folder, and nothing happened after the refusal.
+    expect(judge).toHaveBeenCalledWith(WS, USER.email, `${KB}/KnowledgeBase/Sealed`, 'dir');
+    expect(h.unzipFileMock).not.toHaveBeenCalled();
+    expect(h.lockedPaths).toEqual([]);
+  });
+
+  it('without a destination the archive\'s own folder is what is asked about', async () => {
+    const { gate, judge } = gateThat({ allowed: true, via: 'readable' });
+    h = await makeHarness({ extracted: [`${KB}/KnowledgeBase/Open/a.md`], changeGate: gate });
+    const res = await fetch(`${h.baseUrl}/api/workspace/${WS}/unzip`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ path: `${KB}/KnowledgeBase/Open/drop.zip` }),
+    });
+    expect(res.status).toBe(200);
+    expect(judge).toHaveBeenCalledWith(WS, USER.email, `${KB}/KnowledgeBase/Open`, 'dir');
+    expect(h.unzipFileMock).toHaveBeenCalledOnce();
+    expect(h.lockedPaths).toEqual([`${KB}/KnowledgeBase/Open/a.md`]);
+  });
+
+  it('a new root folder as destination is seeded with the creator grant BEFORE the gate and the extraction', async () => {
+    const { gate, judge } = gateThat({ allowed: true, via: 'readable' });
+    h = await makeHarness({ extracted: [`${KB}/KnowledgeBase/Fresh/a.md`], changeGate: gate });
+    const seedPath = `${KB}/KnowledgeBase/Fresh/access.md`;
+    h.creatorAccess.planForCreate.mockResolvedValue({
+      kind: 'seed-access-md',
+      wsRelPath: seedPath,
+      apply: () => '---\nread:\n  - Alice <alice@example.com>\n---\n',
+    });
+    const res = await fetch(`${h.baseUrl}/api/workspace/${WS}/unzip`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ path: `${KB}/KnowledgeBase/drop.zip`, destination: `${KB}/KnowledgeBase/Fresh` }),
+    });
+    expect(res.status).toBe(200);
+    // Planned as a FOLDER, seeded under its own lock, then the gate, then the archive.
+    expect(h.creatorAccess.planForCreate).toHaveBeenCalledWith(WS, USER, `${KB}/KnowledgeBase/Fresh`, 'dir');
+    expect(h.writes.map((w) => w.path)).toEqual([seedPath]);
+    expect(h.lockedPaths).toEqual([seedPath, `${KB}/KnowledgeBase/Fresh/a.md`]);
+    const seedOrder = h.creatorAccess.planForCreate.mock.invocationCallOrder[0]!;
+    expect(judge.mock.invocationCallOrder[0]!).toBeGreaterThan(seedOrder);
+    expect(h.unzipFileMock.mock.invocationCallOrder[0]!).toBeGreaterThan(judge.mock.invocationCallOrder[0]!);
+  });
+
+  it('hands the extraction a per-entry guard that asks the gate about each entry as a file', async () => {
+    const { gate, judge } = gateThat({ allowed: true, via: 'readable' });
+    h = await makeHarness({ extracted: [], changeGate: gate });
+    const res = await fetch(`${h.baseUrl}/api/workspace/${WS}/unzip`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ path: `${KB}/KnowledgeBase/Open/drop.zip` }),
+    });
+    expect(res.status).toBe(200);
+    const guard = h.unzipFileMock.mock.calls[0]![3] as (p: string) => Promise<void>;
+    expect(typeof guard).toBe('function');
+    await guard(`${KB}/KnowledgeBase/Open/Nested/deep.md`);
+    expect(judge).toHaveBeenCalledWith(WS, USER.email, `${KB}/KnowledgeBase/Open/Nested/deep.md`, 'file');
+  });
+});
+
+describe('POST /upload is where new bytes of any kind arrive', () => {
+  let h: Harness | null = null;
+  afterEach(async () => {
+    if (h) await close(h.server);
+    h = null;
+  });
+
+  it('lands a text file, a document, an image and a zip byte-for-byte', async () => {
+    h = await makeHarness();
+    const files = [
+      { name: 'notes.md', bytes: Buffer.from('# Notes\n') },
+      // A zip container with a NUL and a high byte: what a .pptx looks like on the wire.
+      { name: 'deck.pptx', bytes: Buffer.from([0x50, 0x4b, 0x03, 0x04, 0x00, 0xff, 0x10]) },
+      { name: 'logo.png', bytes: Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0xfe]) },
+      { name: 'bundle.zip', bytes: Buffer.from([0x50, 0x4b, 0x05, 0x06, 0x00, 0x00, 0xc3, 0x28]) },
+    ];
+    for (const f of files) {
+      const path = `${KB}/KnowledgeBase/${f.name}`;
+      const res = await fetch(`${h.baseUrl}/api/workspace/${WS}/upload?path=${encodeURIComponent(path)}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/octet-stream' },
+        body: f.bytes,
+      });
+      expect(res.status, f.name).toBe(200);
+    }
+    expect(h.binaryWrites.map((w) => w.path)).toEqual(files.map((f) => `${KB}/KnowledgeBase/${f.name}`));
+    for (const [i, f] of files.entries()) {
+      // Never decoded as text on the way: invalid UTF-8 would not survive a round trip.
+      expect(h.binaryWrites[i].bytes.equals(f.bytes), f.name).toBe(true);
+    }
   });
 });

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

@@ -5,6 +5,7 @@ import path from 'node:path';
 import os from 'node:os';
 import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
 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';
@@ -34,11 +35,16 @@ const stubCreatorAccess: ICreatorAccess = {
 const USER_ID = 'user-1';
 const USER = { id: USER_ID, email: 'alice@example.com', name: 'Alice' };
 const WORKSPACE_ID = 'feature-branch';
+const KB = 'knowledge-base';
 
 interface Harness {
   server: Server;
   baseUrl: string;
   workspaceDir: string;
+  /** The checkout inside it — where every path the route accepts resolves. */
+  repoDir: string;
+  /** Exposed so a test can assert the PATH the route handed the service. */
+  deleteFileMock: ReturnType<typeof vi.fn>;
 }
 
 async function makeHarness(): Promise<Harness> {
@@ -63,6 +69,7 @@ async function makeHarness(): Promise<Harness> {
   // recursive-cleanup logic under test reacts to.
   const workspaceServiceMock: Partial<WorkspaceService> = {
     getWorkspacePath: vi.fn(async () => workspaceDir),
+    withFolderTurn: async <T>(_id: string, _dir: string, op: () => Promise<T>) => op(),
     deleteFile: vi.fn(async (_id: string, relPath: string) => {
       await fs.rm(path.resolve(workspaceDir, relPath));
     }),
@@ -96,10 +103,11 @@ async function makeHarness(): Promise<Harness> {
     workflowService,
     eventBus,
     accessControl,
-    'knowledge-base',
+    KB,
     stubCreatorAccess,
     // Not exercised here — only `.bevelignore`'s tree visibility consults it.
     { isAdmin: async () => false } as unknown as IAdminAccessService,
+    new NodeFs(),
   ));
 
   const server = await new Promise<Server>((resolve) => {
@@ -110,7 +118,13 @@ async function makeHarness(): Promise<Harness> {
     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}`, workspaceDir };
+  return {
+    server,
+    baseUrl: `http://127.0.0.1:${port}`,
+    workspaceDir,
+    repoDir: path.join(workspaceDir, KB),
+    deleteFileMock: workspaceServiceMock.deleteFile as unknown as ReturnType<typeof vi.fn>,
+  };
 }
 
 async function closeServer(server: Server): Promise<void> {
@@ -144,11 +158,11 @@ describe('DELETE /workspace/:id/file — recursive folder delete (BEVA-132)', ()
     //   sub/a.md
     //   sub/deep/b.md
     //   other/c.md
-    await fs.mkdir(path.join(h.workspaceDir, 'parent/sub/deep'), { recursive: true });
-    await fs.mkdir(path.join(h.workspaceDir, 'parent/other'), { recursive: true });
-    await fs.writeFile(path.join(h.workspaceDir, 'parent/sub/a.md'), 'a');
-    await fs.writeFile(path.join(h.workspaceDir, 'parent/sub/deep/b.md'), 'b');
-    await fs.writeFile(path.join(h.workspaceDir, 'parent/other/c.md'), 'c');
+    await fs.mkdir(path.join(h.repoDir, 'parent/sub/deep'), { recursive: true });
+    await fs.mkdir(path.join(h.repoDir, 'parent/other'), { recursive: true });
+    await fs.writeFile(path.join(h.repoDir, 'parent/sub/a.md'), 'a');
+    await fs.writeFile(path.join(h.repoDir, 'parent/sub/deep/b.md'), 'b');
+    await fs.writeFile(path.join(h.repoDir, 'parent/other/c.md'), 'c');
 
     const res = await fetch(
       `${h.baseUrl}/api/workspace/${WORKSPACE_ID}/file?path=${encodeURIComponent('parent')}`,
@@ -159,13 +173,13 @@ describe('DELETE /workspace/:id/file — recursive folder delete (BEVA-132)', ()
     expect(body.status).toBe('deleted');
     expect(body.count).toBe(3);
     // The whole subtree — including the empty sub-folder shells — is gone.
-    expect(await exists(path.join(h.workspaceDir, 'parent'))).toBe(false);
+    expect(await exists(path.join(h.repoDir, 'parent'))).toBe(false);
   });
 
   it('removes a folder that contains only empty sub-folders (no tracked files)', async () => {
     h = await makeHarness();
-    await fs.mkdir(path.join(h.workspaceDir, 'parent/emptyA/nested'), { recursive: true });
-    await fs.mkdir(path.join(h.workspaceDir, 'parent/emptyB'), { recursive: true });
+    await fs.mkdir(path.join(h.repoDir, 'parent/emptyA/nested'), { recursive: true });
+    await fs.mkdir(path.join(h.repoDir, 'parent/emptyB'), { recursive: true });
 
     const res = await fetch(
       `${h.baseUrl}/api/workspace/${WORKSPACE_ID}/file?path=${encodeURIComponent('parent')}`,
@@ -174,6 +188,32 @@ describe('DELETE /workspace/:id/file — recursive folder delete (BEVA-132)', ()
     expect(res.status).toBe(200);
     const body = (await res.json()) as { status: string; count: number };
     expect(body.count).toBe(0);
-    expect(await exists(path.join(h.workspaceDir, 'parent'))).toBe(false);
+    expect(await exists(path.join(h.repoDir, 'parent'))).toBe(false);
+  });
+});
+
+describe('DELETE /workspace/:id/file — one file identity', () => {
+  it('deletes the canonical path, whichever accepted spelling was sent', async () => {
+    // The workflow lock row is keyed by this path, so a delete spelled
+    // `.//note.md` must not coordinate separately from a save on `note.md`.
+    const h = await makeHarness();
+    try {
+      await fs.mkdir(h.repoDir, { recursive: true });
+      await fs.writeFile(path.join(h.repoDir, 'note.md'), 'bye', 'utf-8');
+
+      const res = await fetch(
+        `${h.baseUrl}/api/workspace/${WORKSPACE_ID}/file?path=${encodeURIComponent('.//note.md')}`,
+        { method: 'DELETE' },
+      );
+
+      expect(res.status).toBe(200);
+      // One identity, and it is the REPOSITORY path: the spelling is collapsed
+      // and the checkout folder added, so the lock row a delete takes is the one
+      // a save on the same file takes.
+      expect(h.deleteFileMock).toHaveBeenCalledWith(WORKSPACE_ID, `${KB}/note.md`);
+    } finally {
+      await closeServer(h.server);
+      await fs.rm(h.workspaceDir, { recursive: true, force: true });
+    }
   });
 });

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

@@ -0,0 +1,161 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import express from 'express';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { ICreatorAccess } from '../../access-model/creator.js';
+import type { IAdminAccessService } from '../../admin/admin.interface.js';
+import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { AuthService } from '../../auth/auth.service.js';
+import { AccessControlService } from '../../access/access-control.service.js';
+import { createWorkspaceRoutes } from '../workspace.routes.js';
+import type { WorkspaceService } from '../workspace.service.js';
+
+/**
+ * The raw-file route over the REAL resolver, on a path whose only rule is a
+ * `download:` grant.
+ *
+ * This is the combination the ticket was filed for: the route read-gates
+ * before it download-gates, so before `download` folded into `read` a
+ * download-only grantee was refused at the FIRST gate and could neither open
+ * the file nor save it. Every other route test stubs the access service, so
+ * only a test wired to the real one can show the two gates agreeing.
+ */
+
+const KB = 'knowledge-base';
+const WORKSPACE_ID = 'target-company-state';
+const FILE = `${KB}/Knowledge/Deal.md`;
+const BYTES = 'hello world';
+
+const stubCreatorAccess: ICreatorAccess = {
+  planForCreate: async () => null,
+  grantInExtractedFile: async () => null,
+  noteAccessFileWritten: () => {},
+};
+
+/** Who the stubbed auth layer says the caller is — set per test before the request. */
+let caller = { id: 'user-1', email: 'ana@x.io', name: 'Ana' };
+
+const ROLES_YAML = `roles:
+  Admin:
+    - admin@x.io
+`;
+
+interface Harness {
+  server: Server;
+  baseUrl: string;
+}
+
+describe('GET /file/raw on a download-only path (real resolver)', () => {
+  let root: string;
+  let h: Harness | null = null;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-dl-read-route-'));
+    caller = { id: 'user-1', email: 'ana@x.io', name: 'Ana' };
+  });
+
+  afterEach(async () => {
+    if (h) {
+      await new Promise<void>((resolve, reject) => h!.server.close((e) => (e ? reject(e) : resolve())));
+      h = null;
+    }
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  async function makeHarness(files: Record<string, string>): Promise<Harness> {
+    const workspaceDir = path.join(root, WORKSPACE_ID);
+    const repo = path.join(workspaceDir, KB);
+    for (const [rel, contents] of Object.entries({ 'roles.yaml': ROLES_YAML, ...files })) {
+      const abs = path.join(repo, rel);
+      await fs.mkdir(path.dirname(abs), { recursive: true });
+      await fs.writeFile(abs, contents);
+    }
+
+    const workspaceService = {
+      getWorkspacePath: async (id: string) => {
+        if (id !== WORKSPACE_ID) throw new Error(`unexpected workspace ${id}`);
+        return workspaceDir;
+      },
+      ensureRemotesFetched: async () => undefined,
+      readFileBinary: async () => Buffer.from(BYTES),
+    } as unknown as WorkspaceService;
+
+    const accessControl = new AccessControlService(workspaceService, KB, new NodeFs());
+    const authService = { getUserById: async () => caller } as unknown as AuthService;
+
+    const app = express();
+    app.use(express.json());
+    app.use('/api', (req, _res, next) => {
+      (req as unknown as { userId: string }).userId = caller.id;
+      next();
+    });
+    app.use(
+      '/api',
+      createWorkspaceRoutes(
+        workspaceService,
+        authService,
+        {} as unknown as IWorkflowService,
+        {} as unknown as WorkflowEventBus,
+        accessControl,
+        KB,
+        stubCreatorAccess,
+        { isAdmin: async () => false } as unknown as IAdminAccessService,
+        new NodeFs(),
+      ),
+    );
+    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}` };
+  }
+
+  const raw = (base: string, download: boolean) =>
+    fetch(
+      `${base}/api/workspace/${WORKSPACE_ID}/file/raw?path=${encodeURIComponent(FILE)}` +
+        (download ? '&download=1' : ''),
+    );
+
+  it('serves the bytes inline AND as a download to a download-only grantee', async () => {
+    h = await makeHarness({
+      'Knowledge/access.md': '---\n---\ndownload:\n  - Ana <ana@x.io>\n',
+    });
+
+    const inline = await raw(h.baseUrl, false);
+    expect(inline.status).toBe(200);
+    expect(await inline.text()).toBe(BYTES);
+
+    const saved = await raw(h.baseUrl, true);
+    expect(saved.status).toBe(200);
+    expect(saved.headers.get('content-disposition')).toContain('attachment');
+    expect(await saved.text()).toBe(BYTES);
+  });
+
+  it('still refuses both to someone with no grant at all', async () => {
+    h = await makeHarness({
+      'Knowledge/access.md': '---\n---\ndownload:\n  - Ana <ana@x.io>\n',
+    });
+    caller = { id: 'user-2', email: 'mallory@x.io', name: 'Mallory' };
+
+    expect((await raw(h.baseUrl, false)).status).toBe(403);
+    expect((await raw(h.baseUrl, true)).status).toBe(403);
+  });
+
+  it('a `deny download` beside an inherited read leaves the file open but unsavable', async () => {
+    h = await makeHarness({
+      'access.md': '---\n---\nread:\n  - Ana <ana@x.io>\n',
+      'Knowledge/access.md': '---\n---\ndownload:\n  - deny Ana <ana@x.io>\n',
+    });
+
+    expect((await raw(h.baseUrl, false)).status).toBe(200);
+    const saved = await raw(h.baseUrl, true);
+    expect(saved.status).toBe(403);
+    expect((await saved.json()).error).toMatch(/download permission required/i);
+  });
+});