Harden path safety with safePath(), add CodeQL config, add tests

- Replace join() with safePath() at all 25 path construction sites where
  user-controlled or readdir-sourced data flows into filesystem operations
  (sessions.ts, message-store.ts, agent-context.ts, privacy.ts)
- Add validatePathSegment() to readdir loops in deleteUserData() and
  runRetentionCleanup() for consistency with exportUserData()
- Add .github/codeql/codeql-config.yml excluding js/missing-rate-limiting
  (false positive: Fastify plugin-based rate limiting not recognized)
- Add .github/workflows/codeql.yml for advanced CodeQL setup with config
- Add src/path-safety.test.ts with 27 tests covering all validators
- Test suite now at 110 tests, all passing

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Chris Shellenbarger

.github/codeql/codeql-config.yml

@@ -0,0 +1,9 @@
+name: "CodeQL config for mastersof-ai/harness"
+
+# Exclude queries that produce false positives for Fastify's architecture.
+# Fastify uses plugin-based global rate limiting (@fastify/rate-limit),
+# not per-route middleware. CodeQL's js/missing-rate-limiting rule is
+# Express-centric and doesn't recognize this pattern.
+query-filters:
+  - exclude:
+      id: js/missing-rate-limiting

.github/workflows/codeql.yml

@@ -0,0 +1,26 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+  schedule:
+    - cron: "0 6 * * 1" # Weekly Monday 6am UTC
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: github/codeql-action/init@v3
+        with:
+          languages: javascript-typescript
+          config-file: .github/codeql/codeql-config.yml
+
+      - uses: github/codeql-action/analyze@v3

package.json

@@ -35,8 +35,8 @@
   "scripts": {
     "start": "tsx src/index.tsx",
     "dev": "tsx watch src/index.tsx",
-    "test": "tsx --test src/manifest.test.ts src/agent-context.test.ts src/tools/index.test.ts src/prompt.test.ts src/types/ask-user.test.ts src/integration.test.ts",
-    "test:unit": "tsx --test src/manifest.test.ts src/agent-context.test.ts src/tools/index.test.ts src/prompt.test.ts src/types/ask-user.test.ts",
+    "test": "tsx --test src/manifest.test.ts src/agent-context.test.ts src/path-safety.test.ts src/tools/index.test.ts src/prompt.test.ts src/types/ask-user.test.ts src/integration.test.ts",
+    "test:unit": "tsx --test src/manifest.test.ts src/agent-context.test.ts src/path-safety.test.ts src/tools/index.test.ts src/prompt.test.ts src/types/ask-user.test.ts",
     "test:integration": "tsx --test src/integration.test.ts",
     "lint": "biome check",
     "lint:fix": "biome check --write",

src/agent-context.ts

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { getHomeDir } from "./config.js";
 import { type AgentManifest, loadAgentManifest } from "./manifest.js";
-import { validateName } from "./path-safety.js";
+import { safePath, validateName } from "./path-safety.js";
 
 export interface AgentContext {
   name: string;
@@ -36,7 +36,8 @@ export function getAgentsDir(): string {
 
 export function resolveAgent(name: string): AgentContext {
   validateName(name, "agent name");
-  const agentDir = join(getAgentsDir(), name);
+  const agentsDir = getAgentsDir();
+  const agentDir = safePath(agentsDir, name);
   const identityPath = join(agentDir, "IDENTITY.md");
 
   if (!existsSync(agentDir)) {
@@ -46,7 +47,7 @@ export function resolveAgent(name: string): AgentContext {
     throw new AgentNotFoundError(name, `IDENTITY.md not found: ${identityPath}`);
   }
 
-  const stateDir = join(getHomeDir(), "state", name);
+  const stateDir = safePath(getHomeDir(), "state", name);
   const workspaceDir = join(agentDir, "workspace");
   mkdirSync(workspaceDir, { recursive: true });
 
@@ -77,7 +78,8 @@ export function resolveRemoteAgent(name: string, userId: string): AgentContext {
   validateName(name, "agent name");
   validateName(userId, "user ID");
 
-  const agentDir = join(getAgentsDir(), name);
+  const agentsDir = getAgentsDir();
+  const agentDir = safePath(agentsDir, name);
   const identityPath = join(agentDir, "IDENTITY.md");
 
   if (!existsSync(agentDir)) {
@@ -87,9 +89,9 @@ export function resolveRemoteAgent(name: string, userId: string): AgentContext {
     throw new AgentNotFoundError(name, `IDENTITY.md not found: ${identityPath}`);
   }
 
-  const stateDir = join(getHomeDir(), "state", name);
-  const userWorkspaceDir = join(agentDir, "workspace", userId);
-  const userMemoryDir = join(agentDir, "memory", userId);
+  const stateDir = safePath(getHomeDir(), "state", name);
+  const userWorkspaceDir = safePath(agentDir, "workspace", userId);
+  const userMemoryDir = safePath(agentDir, "memory", userId);
 
   mkdirSync(userWorkspaceDir, { recursive: true, mode: 0o700 });
   mkdirSync(userMemoryDir, { recursive: true, mode: 0o700 });
@@ -123,8 +125,8 @@ export async function listAgents(): Promise<AgentManifest[]> {
   }
 
   const agentDirs = entries
-    .filter((e) => e.isDirectory() && existsSync(join(agentsDir, e.name, "IDENTITY.md")))
-    .map((e) => join(agentsDir, e.name));
+    .filter((e) => e.isDirectory() && existsSync(safePath(agentsDir, e.name, "IDENTITY.md")))
+    .map((e) => safePath(agentsDir, e.name));
 
   const results = await Promise.all(
     agentDirs.map(async (dir) => {

src/message-store.ts

@@ -1,6 +1,5 @@
 import { appendFile, mkdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
-import { validateSessionId } from "./path-safety.js";
+import { safePath, validateSessionId } from "./path-safety.js";
 import type { SessionDirs } from "./sessions.js";
 
 export interface PersistedMessage {
@@ -12,12 +11,12 @@ export interface PersistedMessage {
 
 function messagesPath(dirs: SessionDirs, sessionId: string): string {
   validateSessionId(sessionId);
-  return join(dirs.sessionsDir, sessionId, "messages.jsonl");
+  return safePath(dirs.sessionsDir, sessionId, "messages.jsonl");
 }
 
 export async function appendMessage(dirs: SessionDirs, sessionId: string, message: PersistedMessage): Promise<void> {
   const filePath = messagesPath(dirs, sessionId);
-  await mkdir(join(dirs.sessionsDir, sessionId), { recursive: true });
+  await mkdir(safePath(dirs.sessionsDir, sessionId), { recursive: true });
   await appendFile(filePath, `${JSON.stringify(message)}\n`, "utf-8");
 }
 

src/path-safety.test.ts

@@ -0,0 +1,138 @@
+import assert from "node:assert";
+import { resolve } from "node:path";
+import { describe, it } from "node:test";
+import { safePath, validateName, validatePathSegment, validateSessionId } from "./path-safety.js";
+
+describe("validatePathSegment", () => {
+  it("accepts normal strings", () => {
+    assert.strictEqual(validatePathSegment("hello", "test"), "hello");
+    assert.strictEqual(validatePathSegment("my-file", "test"), "my-file");
+    assert.strictEqual(validatePathSegment("abc123", "test"), "abc123");
+  });
+
+  it("returns the segment on success", () => {
+    const result = validatePathSegment("valid-segment", "label");
+    assert.strictEqual(result, "valid-segment");
+  });
+
+  it("rejects empty string", () => {
+    assert.throws(() => validatePathSegment("", "test"), /Invalid test/);
+  });
+
+  it("rejects strings containing '..'", () => {
+    assert.throws(() => validatePathSegment("..", "test"), /Invalid test/);
+    assert.throws(() => validatePathSegment("foo/../bar", "test"), /Invalid test/);
+  });
+
+  it("rejects strings containing '/'", () => {
+    assert.throws(() => validatePathSegment("foo/bar", "test"), /Invalid test/);
+    assert.throws(() => validatePathSegment("/absolute", "test"), /Invalid test/);
+  });
+
+  it("rejects strings containing '\\'", () => {
+    assert.throws(() => validatePathSegment("foo\\bar", "test"), /Invalid test/);
+  });
+
+  it("rejects strings containing null byte", () => {
+    assert.throws(() => validatePathSegment("foo\0bar", "test"), /Invalid test/);
+  });
+});
+
+describe("validateSessionId", () => {
+  it("accepts valid UUID v4", () => {
+    const uuid = "550e8400-e29b-41d4-a716-446655440000";
+    assert.strictEqual(validateSessionId(uuid), uuid);
+  });
+
+  it("accepts uppercase UUID", () => {
+    const uuid = "550E8400-E29B-41D4-A716-446655440000";
+    assert.strictEqual(validateSessionId(uuid), uuid);
+  });
+
+  it("returns the id on success", () => {
+    const uuid = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
+    assert.strictEqual(validateSessionId(uuid), uuid);
+  });
+
+  it("rejects empty string", () => {
+    assert.throws(() => validateSessionId(""), /Invalid session ID/);
+  });
+
+  it("rejects non-UUID strings", () => {
+    assert.throws(() => validateSessionId("not-a-uuid"), /Invalid session ID/);
+    assert.throws(() => validateSessionId("hello"), /Invalid session ID/);
+    assert.throws(() => validateSessionId("../etc"), /Invalid session ID/);
+  });
+
+  it("rejects partial UUIDs", () => {
+    assert.throws(() => validateSessionId("550e8400-e29b-41d4"), /Invalid session ID/);
+    assert.throws(() => validateSessionId("550e8400"), /Invalid session ID/);
+  });
+});
+
+describe("validateName", () => {
+  it("accepts valid names", () => {
+    assert.strictEqual(validateName("cofounder", "agent"), "cofounder");
+    assert.strictEqual(validateName("my-agent", "agent"), "my-agent");
+    assert.strictEqual(validateName("agent_1", "agent"), "agent_1");
+    assert.strictEqual(validateName("ab", "agent"), "ab");
+  });
+
+  it("returns the name on success", () => {
+    assert.strictEqual(validateName("researcher", "agent"), "researcher");
+  });
+
+  it("rejects single character", () => {
+    assert.throws(() => validateName("a", "agent"), /Invalid agent/);
+  });
+
+  it("rejects names with dots", () => {
+    assert.throws(() => validateName("my.agent", "agent"), /Invalid agent/);
+  });
+
+  it("rejects names with slashes", () => {
+    assert.throws(() => validateName("my/agent", "agent"), /Invalid agent/);
+  });
+
+  it("rejects names starting with hyphen", () => {
+    assert.throws(() => validateName("-agent", "agent"), /Invalid agent/);
+  });
+
+  it("rejects names longer than 64 characters", () => {
+    const longName = "a".repeat(65);
+    assert.throws(() => validateName(longName, "agent"), /Invalid agent/);
+  });
+
+  it("rejects empty string", () => {
+    assert.throws(() => validateName("", "agent"), /Invalid agent/);
+  });
+
+  it("rejects path traversal", () => {
+    assert.throws(() => validateName("../etc", "agent"), /Invalid agent/);
+  });
+});
+
+describe("safePath", () => {
+  it("returns resolved path for valid segments", () => {
+    const result = safePath("/tmp/base", "sub", "file.txt");
+    assert.strictEqual(result, resolve("/tmp/base", "sub", "file.txt"));
+  });
+
+  it("throws on traversal attempt", () => {
+    assert.throws(() => safePath("/tmp/base", "..", "etc", "passwd"), /Path traversal detected/);
+  });
+
+  it("throws on absolute path injection", () => {
+    assert.throws(() => safePath("/tmp/base", "/etc/passwd"), /Path traversal detected/);
+  });
+
+  it("accepts base directory itself (no segments)", () => {
+    const result = safePath("/tmp/base");
+    assert.strictEqual(result, resolve("/tmp/base"));
+  });
+
+  it("works with nested valid segments", () => {
+    const result = safePath("/tmp/base", "level1", "level2", "level3");
+    assert.strictEqual(result, resolve("/tmp/base", "level1", "level2", "level3"));
+  });
+});