chapterhouse 0.9.1 → 0.10.0

package/README.md

@@ -18,7 +18,7 @@ See [CHANGELOG.md](CHANGELOG.md) for recent changes and feature history.
 
 ## Installation
 
-**Requires Node.js 24 or later** (npm ≥ 11.5.1 for Trusted Publishing support).
+**Requires Node.js 22.5 or later**.
 
 Install globally via npm:
 

package/agents/korg.agent.md

@@ -14,6 +14,26 @@ You are **Korg**, the Personal Knowledge Base (PKB) synthesizer for Chapterhouse
 
 Your mission: ingest external sources, extract structured knowledge, maintain compiled truth pages, and manage research sessions — so the user's wiki becomes a reliable, growing knowledge asset.
 
+## Character
+
+You are a careful analyst and archivist. You take the long view: a knowledge base is only as good as its structure, its provenance, and the accuracy of what's been distilled. You treat every source as evidence, every page as a living document, and every synthesis as a claim that must be earned.
+
+**Personality:**
+
+- You think before you write. When ingesting a new source, you form a view on what it actually says before deciding how it changes existing compiled truth.
+- You surface uncertainty explicitly. If evidence is thin or conflicting, say so — don't smooth it over with confident prose.
+- You explain your reasoning when it matters. A user asking why you organized something a certain way deserves a real answer, not a deflection.
+- You push back on low-quality sources. If something looks like noise or marketing, name it.
+- You take provenance seriously. Where something came from is part of what it means.
+
+**Communication:**
+
+- Write like a thoughtful analyst, not a bullet-point generator. Prose when the idea warrants it.
+- Be precise but not pedantic. Define terms when the distinction matters; skip it when it doesn't.
+- When you surface a synthesis or conclusion, make it clear what the evidence is and where it came from.
+- Don't perform enthusiasm. "This is a rich source" means nothing. Tell the user what's actually in it.
+- End cleanly. No trailing "Let me know if you'd like me to dig deeper!" when the work speaks for itself.
+
 ## Your Toolkit
 
 - `wiki_ingest_source(source, type?, topic?, session_id?, session_name?)` — ingest a URL, PDF, repo, or text into the PKB

package/dist/api/auth.js

@@ -1,3 +1,4 @@
+import { timingSafeEqual } from "crypto";
 import jwt from "jsonwebtoken";
 import jwksClient from "jwks-rsa";
 import { childLogger } from "../util/logger.js";
@@ -39,6 +40,15 @@ function buildAuthenticatedUser(claims, teamLeadId) {
 function unauthorized(res, message) {
     res.status(401).json({ error: message });
 }
+export function timingSafeTokenEqual(provided, expected) {
+    if (!provided || !expected)
+        return false;
+    const a = Buffer.from(provided);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
 // Module-level cache of JWKS clients keyed by tenant ID.
 // Creating a new client per request discards the in-process key cache; keeping
 // one client per tenant lets jwks-rsa honour its cacheMaxAge and avoids an
@@ -124,7 +134,7 @@ export function createAuthMiddleware(options) {
         }
         if (!options.config.entraAuthEnabled) {
             const token = getBearerToken(req);
-            if (!options.apiToken || token !== options.apiToken) {
+            if (!timingSafeTokenEqual(token, options.apiToken)) {
                 unauthorized(res, "Unauthorized");
                 return;
             }

package/dist/api/auth.test.js

@@ -448,4 +448,33 @@ test("JWKS client is reused across calls for the same tenant (module-level cache
     assert.doesNotMatch(String(err2.message), /ENTRA_TENANT_ID or ENTRA_CLIENT_ID is missing/, "second error must come from JWT processing — client reused from module cache");
     auth._resetJwksClientCache();
 });
+// ---------------------------------------------------------------------------
+// timingSafeTokenEqual unit tests
+// ---------------------------------------------------------------------------
+test("timingSafeTokenEqual returns true for matching tokens", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    assert.equal(typeof auth.timingSafeTokenEqual, "function", "timingSafeTokenEqual should be exported");
+    assert.equal(auth.timingSafeTokenEqual("secret-token", "secret-token"), true);
+});
+test("timingSafeTokenEqual returns false for wrong token", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    assert.equal(auth.timingSafeTokenEqual("wrong-token", "secret-token"), false);
+});
+test("timingSafeTokenEqual returns false when provided token is null", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    assert.equal(auth.timingSafeTokenEqual(null, "secret-token"), false);
+});
+test("timingSafeTokenEqual returns false when expected token is null", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    assert.equal(auth.timingSafeTokenEqual("secret-token", null), false);
+});
+test("timingSafeTokenEqual returns false for different-length tokens", async () => {
+    const auth = await loadAuthModule();
+    assert.ok(auth, "auth module should exist");
+    assert.equal(auth.timingSafeTokenEqual("short", "much-longer-token"), false);
+});
 //# sourceMappingURL=auth.test.js.map

package/dist/api/errors.js

@@ -46,6 +46,19 @@ function isBodyParserSyntaxError(error) {
 function formatZodError(error) {
     return error.issues[0]?.message ?? "Invalid request";
 }
+function getStatusCodeError(error) {
+    if (!(error instanceof Error))
+        return undefined;
+    const candidate = error;
+    if (typeof candidate.statusCode !== "number" || candidate.statusCode < 400 || candidate.statusCode > 599) {
+        return undefined;
+    }
+    return {
+        statusCode: candidate.statusCode,
+        message: error.message,
+        expose: candidate.expose === true || candidate.statusCode < 500,
+    };
+}
 export function parseRequest(schema, input) {
     const parsed = schema.safeParse(input);
     if (!parsed.success) {
@@ -90,6 +103,16 @@ export function createApiErrorHandler() {
             res.status(error.statusCode).json({ error: error.expose ? error.message : "Internal server error" });
             return;
         }
+        const statusCodeError = getStatusCodeError(error);
+        if (statusCodeError) {
+            if (statusCodeError.statusCode >= 500) {
+                log.error({ method: req.method, url: req.originalUrl, err: statusCodeError.message }, "API request failed");
+            }
+            res
+                .status(statusCodeError.statusCode)
+                .json({ error: statusCodeError.expose ? statusCodeError.message : "Internal server error" });
+            return;
+        }
         log.error({ method: req.method, url: req.originalUrl, err: error instanceof Error ? error.message : error }, "API request failed (unhandled)");
         res.status(500).json({ error: "Internal server error" });
     };

package/dist/api/route-coverage.test.js

@@ -17,13 +17,14 @@
 // ──────────────────────────────────────────────────────────────────────────────
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const ROOT = join(__dirname, "..", "..");
 const FRONTEND_API_PATH = join(ROOT, "web", "src", "api.ts");
 const SERVER_TS_PATH = join(ROOT, "src", "api", "server.ts");
+const ROUTES_DIR = join(ROOT, "src", "api", "routes");
 const WEB_SCHEMAS_PATH = join(ROOT, "src", "shared", "api-schemas.ts");
 /**
  * Normalise a URL path for comparison:
@@ -59,20 +60,42 @@ function extractFrontendPaths(src) {
     return paths;
 }
 /**
- * Extract all unique normalised API paths registered via app.METHOD() in
- * server.ts. Only /api/ prefixed paths are considered.
+ * Read server.ts plus extracted route modules so static route coverage stays
+ * effective after handlers move behind Express Router instances.
  */
-function extractServerPaths(src) {
-    const re = /app\.(get|post|put|delete|patch)\(["'`](\/api\/[^"'`?]+)/g;
+function readServerRouteSources() {
+    const sources = [readFileSync(SERVER_TS_PATH, "utf8")];
+    if (!existsSync(ROUTES_DIR)) {
+        return sources;
+    }
+    const routeFiles = readdirSync(ROUTES_DIR)
+        .filter((name) => name.endsWith(".ts") && !name.endsWith(".test.ts"))
+        .sort();
+    for (const file of routeFiles) {
+        sources.push(readFileSync(join(ROUTES_DIR, file), "utf8"));
+    }
+    return sources;
+}
+/**
+ * Extract all unique normalised API paths registered via app.METHOD() or
+ * router.METHOD(). Only /api/ prefixed paths are considered.
+ */
+function extractServerPaths(sources) {
+    const re = /\b(?:app|router)\.(get|post|put|delete|patch)\(["'`](\/api\/[^"'`?]+)/g;
     const paths = new Set();
-    for (const m of src.matchAll(re)) {
-        const normalised = normalizePath(m[2]);
-        if (normalised) {
-            paths.add(normalised);
+    for (const src of sources) {
+        for (const m of src.matchAll(re)) {
+            const normalised = normalizePath(m[2]);
+            if (normalised) {
+                paths.add(normalised);
+            }
         }
     }
     return paths;
 }
+function readCombinedServerRouteSource() {
+    return readServerRouteSources().join("\n");
+}
 /**
  * Extract SSE type literals emitted inline via formatSseData({ type: "X", ... })
  * in server.ts. Pass-through calls like formatSseData(event) are not detected.
@@ -128,9 +151,9 @@ function extractStreamEventSchemaTypes(src) {
 describe("route coverage — static analysis", () => {
     test("all frontend authedFetch paths have a matching server route registration", () => {
         const frontendSrc = readFileSync(FRONTEND_API_PATH, "utf8");
-        const serverSrc = readFileSync(SERVER_TS_PATH, "utf8");
+        const serverSources = readServerRouteSources();
         const frontendPaths = extractFrontendPaths(frontendSrc);
-        const serverPaths = extractServerPaths(serverSrc);
+        const serverPaths = extractServerPaths(serverSources);
         const missing = [];
         for (const fp of [...frontendPaths].sort()) {
             if (!serverPaths.has(fp)) {
@@ -139,20 +162,37 @@ describe("route coverage — static analysis", () => {
         }
         assert.ok(missing.length === 0, `Frontend calls ${missing.length} route(s) with no matching server registration:\n` +
             missing.map((p) => `  MISSING: ${p}`).join("\n") +
-            "\n\nAdd the missing route(s) to src/api/server.ts");
+            "\n\nAdd the missing route(s) to src/api/server.ts or src/api/routes/*.ts");
+    });
+    test("server route coverage scans extracted route modules", () => {
+        assert.ok(existsSync(ROUTES_DIR), "Expected src/api/routes/ to exist so route coverage scans extracted routers.");
+        const routeFiles = readdirSync(ROUTES_DIR)
+            .filter((name) => name.endsWith(".ts") && !name.endsWith(".test.ts"))
+            .sort();
+        assert.deepEqual(routeFiles, ["agents.ts", "memory.ts", "projects.ts", "sessions.ts", "system.ts", "wiki.ts"]);
     });
     test("server routes cover every unique normalised path (no obvious duplicates leaked)", () => {
-        const serverSrc = readFileSync(SERVER_TS_PATH, "utf8");
-        const serverPaths = extractServerPaths(serverSrc);
+        const serverPaths = extractServerPaths(readServerRouteSources());
         // Sanity: the server must expose at least 30 /api/ routes.
         assert.ok(serverPaths.size >= 30, `Expected ≥30 server routes, found ${serverPaths.size}. Check extractServerPaths regex.`);
     });
 });
-describe("wiki write route safeguards — static analysis", () => {
-    test("wiki update and pin routes declare authMiddleware explicitly", () => {
-        const serverSrc = readFileSync(SERVER_TS_PATH, "utf8");
-        assert.match(serverSrc, /app\.post\("\/api\/wiki\/update",\s*authMiddleware,\s*async \(req: Request, res: Response\) => \{/);
-        assert.match(serverSrc, /app\.post\("\/api\/wiki\/page\/pin",\s*authMiddleware,\s*async \(req: Request, res: Response\) => \{/);
+describe("shared API schema enforcement — static analysis", () => {
+    test("server route success responses go through sendJson schema validation", () => {
+        const serverSrc = readCombinedServerRouteSource();
+        assert.doesNotMatch(serverSrc, /\bres\.json\(/, "Do not send successful route responses with res.json() directly; use sendJson(res, SharedSchema, payload).");
+    });
+});
+describe("explicit auth route safeguards — static analysis", () => {
+    test("sensitive wiki and memory routes declare authMiddleware explicitly", () => {
+        const serverSrc = readCombinedServerRouteSource();
+        assert.match(serverSrc, /\b(?:app|router)\.post\("\/api\/wiki\/update",\s*authMiddleware,\s*async \(req: Request, res: Response\) => \{/);
+        assert.match(serverSrc, /\b(?:app|router)\.post\("\/api\/wiki\/page\/pin",\s*authMiddleware,\s*async \(req: Request, res: Response\) => \{/);
+        assert.match(serverSrc, /\b(?:app|router)\.get\("\/api\/wiki\/korg\/sessions",\s*authMiddleware,/);
+        assert.match(serverSrc, /\b(?:app|router)\.post\("\/api\/wiki\/ingest",\s*authMiddleware,\s*async \(req: Request, res: Response\) => \{/);
+        assert.match(serverSrc, /\b(?:app|router)\.get\("\/api\/wiki\/search",\s*authMiddleware,\s*async \(req: Request, res: Response\) => \{/);
+        assert.match(serverSrc, /\b(?:app|router)\.post\("\/api\/memory\/hooks\/git-commit",\s*authMiddleware,/);
+        assert.match(serverSrc, /\b(?:app|router)\.post\("\/api\/memory\/hooks\/pr-merge",\s*authMiddleware,/);
     });
 });
 describe("SSE exhaustiveness — static analysis", () => {
@@ -169,7 +209,7 @@ describe("SSE exhaustiveness — static analysis", () => {
     // type in StreamEventSchema, this test FAILS, preventing the regression.
     // ───────────────────────────────────────────────────────────────────────────
     test("formatSseEvent is not used with names that belong in the StreamEventSchema data channel", () => {
-        const serverSrc = readFileSync(SERVER_TS_PATH, "utf8");
+        const serverSrc = readCombinedServerRouteSource();
         const schemaSrc = readFileSync(WEB_SCHEMAS_PATH, "utf8");
         const namedEventNames = extractSseEventNames(serverSrc);
         const schemaTypes = extractStreamEventSchemaTypes(schemaSrc);
@@ -184,7 +224,7 @@ describe("SSE exhaustiveness — static analysis", () => {
             "\n\nNamed SSE events are silently dropped by the frontend's default 'message' handler (issues #367/#368).");
     });
     test("all inline formatSseData type literals are known StreamEventSchema types or agent-stream-only types", () => {
-        const serverSrc = readFileSync(SERVER_TS_PATH, "utf8");
+        const serverSrc = readCombinedServerRouteSource();
         const schemaSrc = readFileSync(WEB_SCHEMAS_PATH, "utf8");
         const emittedTypes = extractSseDataTypes(serverSrc);
         const schemaTypes = extractStreamEventSchemaTypes(schemaSrc);