[Testing 06] test: unit tests for access control, storage, user API keys and chat doc resolution

backend/package.json

@@ -5,7 +5,9 @@
   "scripts": {
     "dev": "tsx watch src/index.ts",
     "build": "tsc",
-    "start": "node dist/index.js"
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.90.0",
@@ -36,9 +38,11 @@
     "@types/express": "^4.17.21",
     "@types/multer": "^1.4.12",
     "@types/node": "^22.14.1",
+    "@vitest/coverage-v8": "^4.1.9",
     "prettier": "^3.8.1",
     "tsx": "^4.19.3",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.9"
   },
   "license": "AGPL-3.0-only"
 }

backend/src/lib/__tests__/access.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it } from "vitest";
+import {
+    checkProjectAccess,
+    ensureDocAccess,
+    ensureReviewAccess,
+    filterAccessibleDocumentIds,
+    listAccessibleProjectIds,
+} from "../access";
+
+type Row = Record<string, unknown>;
+
+function makeDb(tables: Record<string, Row[]>) {
+    return {
+        from(table: string) {
+            let rows = [...(tables[table] ?? [])];
+            const query = {
+                select: () => query,
+                eq: (column: string, value: unknown) => {
+                    rows = rows.filter((row) => row[column] === value);
+                    return query;
+                },
+                neq: (column: string, value: unknown) => {
+                    rows = rows.filter((row) => row[column] !== value);
+                    return query;
+                },
+                in: (column: string, values: unknown[]) => {
+                    rows = rows.filter((row) => values.includes(row[column]));
+                    return query;
+                },
+                filter: (column: string, operator: string, value: string) => {
+                    if (operator !== "cs") return query;
+                    const expected = (JSON.parse(value) as string[]).map((item) =>
+                        item.toLowerCase(),
+                    );
+                    rows = rows.filter((row) => {
+                        const actual = row[column];
+                        const normalizedActual = Array.isArray(actual)
+                            ? actual.map((item) => String(item).toLowerCase())
+                            : [];
+                        return (
+                            Array.isArray(actual) &&
+                            expected.every((item) => normalizedActual.includes(item))
+                        );
+                    });
+                    return query;
+                },
+                single: async () => ({ data: rows[0] ?? null, error: null }),
+                then: (
+                    resolve: (value: { data: Row[]; error: null }) => unknown,
+                    reject?: (reason: unknown) => unknown,
+                ) => Promise.resolve({ data: rows, error: null }).then(resolve, reject),
+            };
+            return query;
+        },
+    } as any;
+}
+
+describe("access helpers", () => {
+    const db = makeDb({
+        projects: [
+            { id: "own-project", user_id: "owner", shared_with: [] },
+            {
+                id: "shared-project",
+                user_id: "other-owner",
+                shared_with: ["Reviewer@Example.com"],
+            },
+            { id: "private-project", user_id: "other-owner", shared_with: [] },
+        ],
+        documents: [
+            { id: "own-doc", user_id: "owner", project_id: null },
+            {
+                id: "shared-doc",
+                user_id: "other-owner",
+                project_id: "shared-project",
+            },
+            {
+                id: "private-doc",
+                user_id: "other-owner",
+                project_id: "private-project",
+            },
+        ],
+    });
+
+    it("allows project owners", async () => {
+        await expect(
+            checkProjectAccess("own-project", "owner", "owner@example.com", db),
+        ).resolves.toMatchObject({ ok: true, isOwner: true });
+    });
+
+    it("allows shared project access case-insensitively", async () => {
+        await expect(
+            checkProjectAccess(
+                "shared-project",
+                "reviewer",
+                "reviewer@example.com",
+                db,
+            ),
+        ).resolves.toMatchObject({ ok: true, isOwner: false });
+    });
+
+    it("denies private project access", async () => {
+        await expect(
+            checkProjectAccess(
+                "private-project",
+                "reviewer",
+                "reviewer@example.com",
+                db,
+            ),
+        ).resolves.toEqual({ ok: false });
+    });
+
+    it("allows document owners and shared-project readers", async () => {
+        await expect(
+            ensureDocAccess(
+                { user_id: "owner", project_id: null },
+                "owner",
+                "owner@example.com",
+                db,
+            ),
+        ).resolves.toMatchObject({ ok: true, isOwner: true });
+
+        await expect(
+            ensureDocAccess(
+                { user_id: "other-owner", project_id: "shared-project" },
+                "reviewer",
+                "reviewer@example.com",
+                db,
+            ),
+        ).resolves.toMatchObject({ ok: true, isOwner: false });
+    });
+
+    it("filters user-supplied document IDs to accessible documents only", async () => {
+        await expect(
+            filterAccessibleDocumentIds(
+                ["own-doc", "shared-doc", "private-doc", "missing-doc"],
+                "reviewer",
+                "reviewer@example.com",
+                db,
+            ),
+        ).resolves.toEqual(["shared-doc"]);
+    });
+
+    it("lists own and directly shared projects", async () => {
+        await expect(
+            listAccessibleProjectIds("owner", "reviewer@example.com", db),
+        ).resolves.toEqual(expect.arrayContaining(["own-project", "shared-project"]));
+    });
+
+    it("allows direct review sharing without project access", async () => {
+        await expect(
+            ensureReviewAccess(
+                {
+                    user_id: "other-owner",
+                    project_id: null,
+                    shared_with: ["Reviewer@Example.com"],
+                },
+                "reviewer",
+                "reviewer@example.com",
+                db,
+            ),
+        ).resolves.toMatchObject({ ok: true, isOwner: false });
+    });
+});

backend/src/lib/__tests__/chatTypes.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from "vitest";
+import {
+    resolveDoc,
+    resolveDocLabel,
+    type DocIndex,
+    type DocStore,
+} from "../chat/types";
+
+// ---------------------------------------------------------------------------
+// resolveDoc
+// ---------------------------------------------------------------------------
+
+describe("resolveDoc", () => {
+    const index: DocIndex = {
+        "doc-1": { document_id: "uuid-aaa", filename: "contract.pdf" },
+        "doc-2": { document_id: "uuid-bbb", filename: "nda.pdf" },
+    };
+
+    it("returns the doc entry for a known label", () => {
+        expect(resolveDoc("doc-1", index)).toEqual({
+            document_id: "uuid-aaa",
+            filename: "contract.pdf",
+        });
+    });
+
+    it("returns undefined for an unknown label", () => {
+        expect(resolveDoc("doc-99", index)).toBeUndefined();
+    });
+
+    it("returns undefined for an empty string", () => {
+        expect(resolveDoc("", index)).toBeUndefined();
+    });
+});
+
+// ---------------------------------------------------------------------------
+// resolveDocLabel
+// ---------------------------------------------------------------------------
+
+describe("resolveDocLabel", () => {
+    const store: DocStore = new Map([
+        ["doc-1", { storage_path: "path/a", file_type: "pdf", filename: "contract.pdf" }],
+        ["doc-2", { storage_path: "path/b", file_type: "pdf", filename: "nda.pdf" }],
+    ]);
+
+    const index: DocIndex = {
+        "doc-1": { document_id: "uuid-aaa", filename: "contract.pdf" },
+        "doc-2": { document_id: "uuid-bbb", filename: "nda.pdf" },
+    };
+
+    it("resolves by label when the label is in the store", () => {
+        expect(resolveDocLabel("doc-1", store, index)).toBe("doc-1");
+    });
+
+    it("resolves by filename when the filename matches a store entry", () => {
+        expect(resolveDocLabel("contract.pdf", store, index)).toBe("doc-1");
+    });
+
+    it("resolves by document UUID via the docIndex", () => {
+        expect(resolveDocLabel("uuid-bbb", store, index)).toBe("doc-2");
+    });
+
+    it("returns null when nothing matches", () => {
+        expect(resolveDocLabel("unknown-id", store, index)).toBeNull();
+    });
+
+    it("returns null when docIndex is omitted and only UUID matches", () => {
+        // Without the index there is no fallback for raw UUIDs.
+        expect(resolveDocLabel("uuid-aaa", store)).toBeNull();
+    });
+
+    it("prioritises exact label match over filename match", () => {
+        // If a label happens to equal a filename of a different doc,
+        // the label match wins.
+        const storeWithCrossMatch: DocStore = new Map([
+            ["nda.pdf", { storage_path: "path/c", file_type: "pdf", filename: "contract.pdf" }],
+        ]);
+        // "nda.pdf" is a label here, and it IS in the store, so it should
+        // be returned directly without the filename-fallback loop.
+        expect(resolveDocLabel("nda.pdf", storeWithCrossMatch)).toBe("nda.pdf");
+    });
+});

backend/src/lib/__tests__/downloadTokens.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { signDownload, verifyDownload, buildDownloadUrl } from "../downloadTokens";
+
+const SECRET = "test-secret-32-bytes-long-enough!!";
+
+beforeAll(() => {
+    process.env.DOWNLOAD_SIGNING_SECRET = SECRET;
+});
+
+afterAll(() => {
+    delete process.env.DOWNLOAD_SIGNING_SECRET;
+});
+
+describe("signDownload", () => {
+    it("returns a two-part dot-separated token", () => {
+        const token = signDownload("documents/user/doc.pdf", "contract.pdf");
+        const parts = token.split(".");
+        expect(parts).toHaveLength(2);
+        expect(parts[0].length).toBeGreaterThan(0);
+        expect(parts[1].length).toBeGreaterThan(0);
+    });
+
+    it("produces different tokens for different paths", () => {
+        const t1 = signDownload("documents/a/file.pdf", "a.pdf");
+        const t2 = signDownload("documents/b/file.pdf", "b.pdf");
+        expect(t1).not.toBe(t2);
+    });
+
+    it("uses base64url characters only (no +, /, =)", () => {
+        const token = signDownload("documents/user/file.pdf", "file.pdf");
+        expect(token).not.toMatch(/[+/=]/);
+    });
+});
+
+describe("verifyDownload", () => {
+    it("round-trips a valid token", () => {
+        const path = "documents/user123/doc456/source.pdf";
+        const filename = "Contract Final v2.pdf";
+        const token = signDownload(path, filename);
+        const result = verifyDownload(token);
+        expect(result).not.toBeNull();
+        expect(result!.path).toBe(path);
+        expect(result!.filename).toBe(filename);
+    });
+
+    it("returns null for a tampered payload", () => {
+        const token = signDownload("documents/user/file.pdf", "file.pdf");
+        const [, sig] = token.split(".");
+        const fakePayload = Buffer.from(
+            JSON.stringify({ p: "documents/attacker/file.pdf", f: "file.pdf" }),
+        )
+            .toString("base64")
+            .replace(/\+/g, "-")
+            .replace(/\//g, "_")
+            .replace(/=+$/g, "");
+        expect(verifyDownload(`${fakePayload}.${sig}`)).toBeNull();
+    });
+
+    it("returns null for a tampered signature", () => {
+        const token = signDownload("documents/user/file.pdf", "file.pdf");
+        const [enc] = token.split(".");
+        const fakeSig = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
+        expect(verifyDownload(`${enc}.${fakeSig}`)).toBeNull();
+    });
+
+    it("returns null for a token with too many parts", () => {
+        expect(verifyDownload("a.b.c")).toBeNull();
+    });
+
+    it("returns null for a token with too few parts", () => {
+        expect(verifyDownload("onlyonepart")).toBeNull();
+    });
+
+    it("returns null when payload JSON is missing required fields", () => {
+        const bad = Buffer.from(JSON.stringify({ x: 1 }))
+            .toString("base64")
+            .replace(/\+/g, "-")
+            .replace(/\//g, "_")
+            .replace(/=+$/g, "");
+        const sig = Buffer.alloc(32).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+        expect(verifyDownload(`${bad}.${sig}`)).toBeNull();
+    });
+
+    it("returns null when signed with a different secret", () => {
+        const token = signDownload("documents/user/file.pdf", "file.pdf");
+        process.env.DOWNLOAD_SIGNING_SECRET = "different-secret-value-!!";
+        const result = verifyDownload(token);
+        process.env.DOWNLOAD_SIGNING_SECRET = SECRET;
+        expect(result).toBeNull();
+    });
+});
+
+describe("buildDownloadUrl", () => {
+    it("returns a path starting with /download/", () => {
+        const url = buildDownloadUrl("documents/user/file.pdf", "file.pdf");
+        expect(url).toMatch(/^\/download\//);
+    });
+
+    it("embeds a verifiable token in the URL", () => {
+        const path = "documents/user/file.pdf";
+        const filename = "file.pdf";
+        const url = buildDownloadUrl(path, filename);
+        const token = url.replace("/download/", "");
+        const result = verifyDownload(token);
+        expect(result).not.toBeNull();
+        expect(result!.path).toBe(path);
+        expect(result!.filename).toBe(filename);
+    });
+});