@bevel-software/platform-core-backend 0.21.0 → 0.23.0

package/src/modules/workspace/__tests__/workspace.routes.at-ref.test.ts

@@ -0,0 +1,305 @@
+import { get as httpGet, 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 { testKbContext } from '../../../__tests__/kb-context.js';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { VersionNotOnBranchError, VERSION_NOT_ON_BRANCH_MESSAGE } from '../../../shared/domain-errors.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+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 { createWorkspaceRoutes } from '../workspace.routes.js';
+import type { WorkspaceService } from '../workspace.service.js';
+
+/**
+ * `GET /workspace/:id/file/raw?ref=<sha>` — the bytes of a PAST save.
+ *
+ * What the suite is really pinning is that the ref changes WHICH bytes and
+ * nothing else about the route: the same read gate, the same `download:` verb,
+ * the same content type and svg sandbox, and — the one that would be worst to
+ * get wrong — that a request naming a ref can never come back with today's
+ * working-tree bytes. A silent fall back there looks exactly like a success.
+ */
+
+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 SHA = 'a1b2c3d4e5f60718293a4b5c6d7e8f9012345678';
+
+/** Bytes that are not valid UTF-8, so a decode step anywhere would be visible. */
+const PAST_BYTES = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x00, 0xff, 0xfe, 0x01]);
+const TREE_BYTES = Buffer.from('TODAY');
+
+const stubCreatorAccess: ICreatorAccess = {
+  planForCreate: async () => null,
+  grantInExtractedFile: async () => null,
+  noteAccessFileWritten: () => {},
+};
+
+interface Harness {
+  server: Server;
+  baseUrl: string;
+  fileBytesAtChange: ReturnType<typeof vi.fn>;
+  readFileBinary: ReturnType<typeof vi.fn>;
+  canRead: ReturnType<typeof vi.fn>;
+  canDownload: ReturnType<typeof vi.fn>;
+}
+
+async function makeHarness(
+  opts: {
+    canRead?: boolean;
+    canDownload?: boolean;
+    /** What the workflow service answers; default is the past bytes. */
+    atRef?: () => Promise<{ bytes: Uint8Array; blobId: string } | null>;
+  } = {},
+): Promise<Harness> {
+  const canRead = vi.fn(async () => opts.canRead !== false);
+  const canDownload = vi.fn(async () => opts.canDownload !== false);
+  const accessControl = {
+    canRead,
+    canDownload,
+    canReadBatch: vi.fn(async (_w: string, _e: string, paths: string[]) =>
+      new Map(paths.map((p) => [p, opts.canRead !== false])),
+    ),
+  } as unknown as IAccessControl;
+
+  const readFileBinary = vi.fn(async () => TREE_BYTES);
+  const workspaceService = { readFileBinary } as unknown as WorkspaceService;
+
+  const fileBytesAtChange = vi.fn(
+    opts.atRef ?? (async () => ({ bytes: PAST_BYTES, blobId: 'deadbeef'.repeat(5) })),
+  );
+  const workflowService = { fileBytesAtChange } as unknown as IWorkflowService;
+
+  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,
+      workflowService,
+      {} as unknown as WorkflowEventBus,
+      accessControl,
+      testKbContext({ kbDirName: 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}`,
+    fileBytesAtChange,
+    readFileBinary,
+    canRead,
+    canDownload,
+  };
+}
+
+function close(s: Server): Promise<void> {
+  return new Promise((resolve, reject) => s.close((e) => (e ? reject(e) : resolve())));
+}
+
+describe('GET /workspace/:id/file/raw?ref= — one file at a past save', () => {
+  let h: Harness | null = null;
+  afterEach(async () => {
+    if (h) await close(h.server);
+    h = null;
+  });
+
+  const raw = (query: string) => fetch(`${h!.baseUrl}/api/workspace/${WS}/file/raw?${query}`);
+  const png = (extra = '') =>
+    `path=${encodeURIComponent(`${KB}/Docs/logo.png`)}&ref=${SHA}${extra}`;
+
+  it('serves the save\'s exact bytes with the format\'s content type, and never the working tree', async () => {
+    h = await makeHarness();
+    const res = await raw(png());
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toBe('image/png');
+    expect(res.headers.get('x-content-type-options')).toBe('nosniff');
+    expect(res.headers.get('cache-control')).toBe('private, no-cache');
+    const body = Buffer.from(await res.arrayBuffer());
+    expect(body.equals(PAST_BYTES)).toBe(true);
+    // THE regression guard: a ref read must not reach the working tree at all.
+    expect(h.readFileBinary).not.toHaveBeenCalled();
+    expect(h.fileBytesAtChange).toHaveBeenCalledWith(WS, `${KB}/Docs/logo.png`, SHA, 'after');
+  });
+
+  it('reads the side just before the save when asked, for a save that deleted the file', async () => {
+    h = await makeHarness();
+    const res = await raw(png('&side=before'));
+    expect(res.status).toBe(200);
+    expect(h.fileBytesAtChange).toHaveBeenCalledWith(WS, `${KB}/Docs/logo.png`, SHA, 'before');
+  });
+
+  it('answers 400 for a malformed ref, and never falls back to today\'s bytes', async () => {
+    h = await makeHarness();
+    for (const bad of ['HEAD', 'main', 'zzz', `${SHA}${SHA}`, 'abc']) {
+      const res = await raw(`path=${encodeURIComponent(`${KB}/Docs/logo.png`)}&ref=${bad}`);
+      expect(res.status).toBe(400);
+    }
+    expect(h.readFileBinary).not.toHaveBeenCalled();
+    expect(h.fileBytesAtChange).not.toHaveBeenCalled();
+  });
+
+  it('answers 400 for a path carrying a line break, before any gate is asked', async () => {
+    // `cat-file --batch` reads one `<ref>:<path>` object name per LINE, so
+    // `Docs/secret.md%0Azzz` would be TWO specs: git answers about
+    // `Docs/secret.md` and serves its bytes, while the read gate, the
+    // download gate and the not-a-directory check were all asked about the
+    // whole string — a name that exists nowhere, whose own frontmatter rules
+    // therefore never ran. Refused at the normaliser, which is before the
+    // gates, so neither gate is even consulted.
+    h = await makeHarness();
+    for (const injected of [
+      `${KB}/Docs/secret.md\nzzz`,
+      `${KB}/Docs/secret.md\rzzz`,
+      `${KB}/Docs/secret.md\n${KB}/Docs/logo.png`,
+      `${KB}/Docs/secret.md\u0000zzz`,
+    ]) {
+      const withRef = await raw(`path=${encodeURIComponent(injected)}&ref=${SHA}`);
+      expect(withRef.status).toBe(400);
+      expect(((await withRef.json()) as { error: string }).error).toMatch(/control character/);
+      // The same refusal without a ref: the rule is the path's, not the
+      // history feature's, so today's working-tree read is closed too.
+      expect((await raw(`path=${encodeURIComponent(injected)}`)).status).toBe(400);
+    }
+    expect(h.canRead).not.toHaveBeenCalled();
+    expect(h.canDownload).not.toHaveBeenCalled();
+    expect(h.fileBytesAtChange).not.toHaveBeenCalled();
+    expect(h.readFileBinary).not.toHaveBeenCalled();
+  });
+
+  it('answers 400 for an unknown side, and for a side with no ref', async () => {
+    h = await makeHarness();
+    expect((await raw(png('&side=middle'))).status).toBe(400);
+    const orphan = await raw(`path=${encodeURIComponent(`${KB}/Docs/logo.png`)}&side=before`);
+    expect(orphan.status).toBe(400);
+    expect(h.readFileBinary).not.toHaveBeenCalled();
+  });
+
+  it('answers 404 with the history message for a save off this branch', async () => {
+    h = await makeHarness({
+      atRef: async () => {
+        throw new VersionNotOnBranchError();
+      },
+    });
+    const res = await raw(png());
+    expect(res.status).toBe(404);
+    expect(((await res.json()) as { error: string }).error).toBe(VERSION_NOT_ON_BRANCH_MESSAGE);
+  });
+
+  it('answers 404 when the file was not there on that side', async () => {
+    h = await makeHarness({ atRef: async () => null });
+    const res = await raw(png());
+    expect(res.status).toBe(404);
+    expect(((await res.json()) as { error: string }).error).toBe('File not found');
+  });
+
+  it('answers a failure of OUR making with a 500, not "File not found"', async () => {
+    // The ref read goes through the git runner: a blob over its output ceiling
+    // arrives here as a RangeError, a hung `cat-file` as a run error. Either
+    // one answered 404 would tell a reader the save they can SEE LISTED had
+    // vanished — and would retire the pane's "Try again" as pointless.
+    h = await makeHarness({
+      atRef: async () => {
+        throw new RangeError('git output exceeded 67108864 bytes');
+      },
+    });
+    const res = await raw(png());
+    expect(res.status).toBe(500);
+    expect(((await res.json()) as { error: string }).error).toBe(
+      'Could not read this version of the file',
+    );
+  });
+
+  it('refuses a reader who may not read the file today, before any read happens', async () => {
+    h = await makeHarness({ canRead: false });
+    const res = await raw(png());
+    expect(res.status).toBe(403);
+    expect(h.fileBytesAtChange).not.toHaveBeenCalled();
+  });
+
+  it('refuses a download without the download verb, and allows the inline read', async () => {
+    h = await makeHarness({ canDownload: false });
+    const dl = await raw(png('&download=1'));
+    expect(dl.status).toBe(403);
+    expect(((await dl.json()) as { error: string }).error).toBe('Download permission required');
+    expect(h.fileBytesAtChange).not.toHaveBeenCalled();
+
+    // The same reader still SEES the version — read and download are separate
+    // verbs at a ref exactly as they are in the working tree.
+    const inline = await raw(png());
+    expect(inline.status).toBe(200);
+  });
+
+  it('downloads the VERSION bytes, named in the attachment disposition', async () => {
+    h = await makeHarness();
+    const res = await raw(png('&download=1'));
+    expect(res.status).toBe(200);
+    // The bytes, not just the headers: a download that quietly fell back to
+    // the working tree would hand over today's file under a past save's name,
+    // and every header assertion would still pass.
+    expect(Buffer.from(await res.arrayBuffer()).equals(PAST_BYTES)).toBe(true);
+    expect(h.fileBytesAtChange).toHaveBeenCalledWith(WS, `${KB}/Docs/logo.png`, SHA, 'after');
+    expect(h.readFileBinary).not.toHaveBeenCalled();
+    expect(res.headers.get('content-disposition')).toContain(
+      `filename*=UTF-8''${encodeURIComponent('logo.png')}`,
+    );
+  });
+
+  it('keeps the svg rules at a ref: sandboxed inline, octet-stream on download', async () => {
+    h = await makeHarness();
+    const path = `path=${encodeURIComponent(`${KB}/Docs/chart.svg`)}&ref=${SHA}`;
+    const inline = await raw(path);
+    expect(inline.headers.get('content-type')).toBe('image/svg+xml');
+    expect(inline.headers.get('content-security-policy')).toBe('sandbox');
+    const dl = await raw(`${path}&download=1`);
+    expect(dl.headers.get('content-type')).toBe('application/octet-stream');
+  });
+
+  it('ETags the version by its blob id and answers a revalidation with 304', async () => {
+    h = await makeHarness();
+    const first = await raw(png());
+    const etag = first.headers.get('etag');
+    expect(etag).toBe(`"${'deadbeef'.repeat(5)}"`);
+
+    // `node:http` rather than fetch: undici adds `Cache-Control: no-cache` to
+    // a conditional request, which Express reads as "do not answer 304".
+    const status = await new Promise<number>((resolve, reject) => {
+      const req = httpGet(
+        `${h!.baseUrl}/api/workspace/${WS}/file/raw?${png()}`,
+        { headers: { 'If-None-Match': etag! } },
+        (res) => {
+          res.resume();
+          resolve(res.statusCode ?? 0);
+        },
+      );
+      req.on('error', reject);
+    });
+    expect(status).toBe(304);
+  });
+
+  it('is unchanged for a request with no ref: the working tree, as before', async () => {
+    h = await makeHarness();
+    const res = await raw(`path=${encodeURIComponent(`${KB}/Docs/logo.png`)}`);
+    expect(res.status).toBe(200);
+    expect(Buffer.from(await res.arrayBuffer()).equals(TREE_BYTES)).toBe(true);
+    expect(h.fileBytesAtChange).not.toHaveBeenCalled();
+  });
+});

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

@@ -109,6 +109,8 @@ async function makeHarness(opts: {
       return { userId: USER_ID, email: USER.email };
     }) as unknown as AuthService['verifyToken'],
   };
+  // A session is accepted only for an account that is on; this one is.
+  authServiceMock.resolveSession = vi.fn(async (token: string) => authServiceMock.verifyToken!(token));
   const authService = authServiceMock as AuthService;
 
   const workflowService = {} as unknown as IWorkflowService;

package/src/modules/workspace/__tests__/workspace.service.forget-clone-races.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { WorkspaceService } from '../workspace.service.js';
+import type { IGitRunner } from '../../../shared/git.contract.js';
+
+/**
+ * What happens to work ALREADY IN FLIGHT when the knowledge-base repository is
+ * replaced under a running server.
+ *
+ * `forgetClone` clearing the caches is not enough on its own: a bootstrap or a
+ * fetch started before the replacement finishes afterwards and writes its
+ * result back into those very caches — about a working copy that no longer
+ * exists. Both readers record how many times the copy has been taken away and
+ * check that before publishing anything.
+ */
+
+const BRANCH = 'main';
+const WORKSPACE_ID = encodeURIComponent(BRANCH);
+
+let root: string;
+let workspacesRoot: string;
+
+beforeEach(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-forget-races-'));
+  workspacesRoot = path.join(root, 'workspaces');
+  await fs.mkdir(workspacesRoot, { recursive: true });
+});
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await fs.rm(root, { recursive: true, force: true });
+});
+
+/** A git runner whose every call is a promise this test resolves by hand. */
+function heldRunner() {
+  const calls: Array<{ args: string[]; settle: () => void; fail: (err: Error) => void }> = [];
+  const runner = {
+    defaultTimeoutMs: 1000,
+    credentials: { token: () => null, username: () => null, fingerprint: () => 'none' },
+    run: vi.fn(
+      (_cwd: string, args: string[]) =>
+        new Promise((resolve, reject) => {
+          calls.push({
+            args,
+            settle: () => resolve({ stdout: '', stderr: '', exitCode: 0 }),
+            fail: (err: Error) => reject(err),
+          });
+        }),
+    ),
+  } as unknown as IGitRunner;
+  return { runner, calls };
+}
+
+function service(runner: IGitRunner) {
+  return new WorkspaceService(
+    workspacesRoot,
+    () => `${root}/configured.git`,
+    testKbContext({ branchModel: { defaultBranch: BRANCH, protectedBranches: [BRANCH] } }),
+    new NodeFs(),
+    runner,
+  );
+}
+
+/** A working copy on disk, as far as anything that only looks for `.git` cares. */
+async function cloneOnDisk(): Promise<string> {
+  const repoDir = path.join(workspacesRoot, WORKSPACE_ID, 'knowledge-base');
+  await fs.mkdir(path.join(repoDir, '.git'), { recursive: true });
+  return repoDir;
+}
+
+describe('a fetch in flight when the working copy is taken away', () => {
+  it('does not stamp its result onto the clone that replaced it', async () => {
+    const { runner, calls } = heldRunner();
+    const svc = service(runner);
+    const repoDir = await cloneOnDisk();
+
+    // A fetch of the working copy as it is now, held open.
+    const fetching = svc.ensureRemotesFetched(WORKSPACE_ID);
+    await vi.waitFor(() => expect(calls.length).toBe(1));
+
+    // The replacement lands mid-fetch: the copy is set aside, a fresh one is
+    // cloned to the same path, and this process is told to forget the old one.
+    svc.forgetClone(WORKSPACE_ID);
+    calls[0]!.settle();
+    await fetching;
+
+    // The next reader must actually refresh the NEW clone. Were the stale
+    // fetch's success stamped, it would be inside the TTL and skipped — the
+    // app would serve the refs of a working copy that is gone for 30 seconds.
+    const second = svc.ensureRemotesFetched(WORKSPACE_ID);
+    await vi.waitFor(() => expect(calls.length).toBe(2));
+    expect(calls[1]!.args).toEqual(calls[0]!.args);
+    expect(calls[1]!.args).toContain('fetch');
+    calls[1]!.settle();
+    await second;
+    expect(repoDir).toContain(WORKSPACE_ID);
+  });
+
+  it('does not leave a strict caller reading the old copy’s failure', async () => {
+    const { runner, calls } = heldRunner();
+    const svc = service(runner);
+    await cloneOnDisk();
+
+    const fetching = svc.ensureRemotesFetched(WORKSPACE_ID);
+    await vi.waitFor(() => expect(calls.length).toBe(1));
+    svc.forgetClone(WORKSPACE_ID);
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    calls[0]!.fail(new Error('repository not found'));
+    await fetching;
+
+    // The failure belonged to the working copy that was replaced. The fresh
+    // one gets its own answer, and a successful fetch of it is a success.
+    const strict = svc.ensureRemotesFetched(WORKSPACE_ID, { strict: true });
+    await vi.waitFor(() => expect(calls.length).toBe(2));
+    calls[1]!.settle();
+    await expect(strict).resolves.toBeUndefined();
+  });
+});
+
+describe('a bootstrap in flight when the working copy is taken away', () => {
+  it('is refused rather than cached as the path of a directory that is gone', async () => {
+    const { runner, calls } = heldRunner();
+    const svc = service(runner);
+    // Nothing on disk: this is a first clone, which is what takes seconds.
+    const opening = svc.getOrCreateForBranch(BRANCH);
+    await vi.waitFor(() => expect(calls.length).toBeGreaterThan(0));
+
+    // The replacement lands while the clone runs.
+    svc.forgetClone(WORKSPACE_ID);
+    // Let the clone — and every config call after it — finish.
+    for (let i = 0; i < 40 && calls.length > 0; i++) {
+      const pending = calls.splice(0, calls.length);
+      for (const call of pending) call.settle();
+      await Promise.resolve();
+      await new Promise((r) => setTimeout(r, 0));
+    }
+
+    // Told, rather than handed a cached path to a working copy of the
+    // repository that was replaced — which every later read would ENOENT on,
+    // with nothing left to re-clone it.
+    await expect(opening).rejects.toThrow(/replaced while the "main" working copy was being created/);
+  });
+});