tlc-claude-code 2.0.1 → 2.2.0

package/server/lib/capture-bridge.test.js

@@ -0,0 +1,363 @@
+/**
+ * Capture Bridge Tests - Phase 82 Tasks 1+2
+ *
+ * Tests for the Node.js bridge that connects Claude Code Stop hooks
+ * to the TLC memory capture pipeline.
+ *
+ * RED: capture-bridge.js does not exist yet.
+ */
+
+import { describe, it, beforeEach, afterEach, expect, vi } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+import {
+  parseStopHookInput,
+  extractLastUserMessage,
+  captureExchange,
+  drainSpool,
+  SPOOL_FILENAME,
+} from './capture-bridge.js';
+
+describe('capture-bridge', () => {
+  let testDir;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-capture-bridge-'));
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  // ── parseStopHookInput ───────────────────────────────────────────
+
+  describe('parseStopHookInput', () => {
+    it('extracts last_assistant_message from valid JSON', () => {
+      const input = JSON.stringify({
+        session_id: 'sess-123',
+        last_assistant_message: 'We should use PostgreSQL for JSONB support',
+        transcript_path: '/tmp/transcript.jsonl',
+        cwd: '/projects/myapp',
+      });
+
+      const result = parseStopHookInput(input);
+
+      expect(result).not.toBeNull();
+      expect(result.sessionId).toBe('sess-123');
+      expect(result.assistantMessage).toBe('We should use PostgreSQL for JSONB support');
+      expect(result.transcriptPath).toBe('/tmp/transcript.jsonl');
+      expect(result.cwd).toBe('/projects/myapp');
+    });
+
+    it('handles missing fields gracefully', () => {
+      const input = JSON.stringify({ session_id: 'sess-456' });
+
+      const result = parseStopHookInput(input);
+
+      expect(result).not.toBeNull();
+      expect(result.sessionId).toBe('sess-456');
+      expect(result.assistantMessage).toBeNull();
+      expect(result.transcriptPath).toBeNull();
+    });
+
+    it('returns null for invalid JSON', () => {
+      const result = parseStopHookInput('not json at all {{{');
+
+      expect(result).toBeNull();
+    });
+
+    it('returns null for empty input', () => {
+      expect(parseStopHookInput('')).toBeNull();
+      expect(parseStopHookInput(null)).toBeNull();
+      expect(parseStopHookInput(undefined)).toBeNull();
+    });
+  });
+
+  // ── extractLastUserMessage ───────────────────────────────────────
+
+  describe('extractLastUserMessage', () => {
+    it('reads last user turn from transcript JSONL', () => {
+      const transcriptPath = path.join(testDir, 'transcript.jsonl');
+      const lines = [
+        JSON.stringify({ role: 'user', content: 'first question' }),
+        JSON.stringify({ role: 'assistant', content: 'first answer' }),
+        JSON.stringify({ role: 'user', content: 'second question' }),
+        JSON.stringify({ role: 'assistant', content: 'second answer' }),
+      ];
+      fs.writeFileSync(transcriptPath, lines.join('\n') + '\n');
+
+      const result = extractLastUserMessage(transcriptPath);
+
+      expect(result).toBe('second question');
+    });
+
+    it('returns null for empty transcript', () => {
+      const transcriptPath = path.join(testDir, 'empty.jsonl');
+      fs.writeFileSync(transcriptPath, '');
+
+      const result = extractLastUserMessage(transcriptPath);
+
+      expect(result).toBeNull();
+    });
+
+    it('returns null for missing file', () => {
+      const result = extractLastUserMessage('/nonexistent/transcript.jsonl');
+
+      expect(result).toBeNull();
+    });
+
+    it('handles transcript with only assistant messages', () => {
+      const transcriptPath = path.join(testDir, 'no-user.jsonl');
+      const lines = [
+        JSON.stringify({ role: 'assistant', content: 'hello' }),
+      ];
+      fs.writeFileSync(transcriptPath, lines.join('\n') + '\n');
+
+      const result = extractLastUserMessage(transcriptPath);
+
+      expect(result).toBeNull();
+    });
+  });
+
+  // ── captureExchange ──────────────────────────────────────────────
+
+  describe('captureExchange', () => {
+    it('POSTs to capture endpoint with correct payload', async () => {
+      const mockFetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ captured: 1 }),
+      });
+
+      // Create .tlc.json so projectId can be detected
+      fs.writeFileSync(
+        path.join(testDir, '.tlc.json'),
+        JSON.stringify({ project: 'my-app' })
+      );
+
+      await captureExchange({
+        cwd: testDir,
+        assistantMessage: 'Use JWT tokens for auth',
+        userMessage: 'How should we handle auth?',
+        sessionId: 'sess-1',
+      }, { fetch: mockFetch });
+
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+
+      const [url, options] = mockFetch.mock.calls[0];
+      expect(url).toContain('/api/projects/my-app/memory/capture');
+      expect(options.method).toBe('POST');
+
+      const body = JSON.parse(options.body);
+      expect(body.exchanges).toHaveLength(1);
+      expect(body.exchanges[0].assistant).toBe('Use JWT tokens for auth');
+      expect(body.exchanges[0].user).toBe('How should we handle auth?');
+    });
+
+    it('spools on POST failure', async () => {
+      const mockFetch = vi.fn().mockRejectedValue(new Error('ECONNREFUSED'));
+
+      fs.writeFileSync(
+        path.join(testDir, '.tlc.json'),
+        JSON.stringify({ project: 'my-app' })
+      );
+
+      // Ensure spool directory exists
+      const spoolDir = path.join(testDir, '.tlc', 'memory');
+      fs.mkdirSync(spoolDir, { recursive: true });
+
+      await captureExchange({
+        cwd: testDir,
+        assistantMessage: 'Use Redis for caching',
+        userMessage: 'What cache should we use?',
+        sessionId: 'sess-2',
+      }, { fetch: mockFetch, spoolDir });
+
+      // Should have written to spool file
+      const spoolPath = path.join(spoolDir, SPOOL_FILENAME);
+      expect(fs.existsSync(spoolPath)).toBe(true);
+
+      const spoolContent = fs.readFileSync(spoolPath, 'utf-8').trim();
+      const spooled = JSON.parse(spoolContent);
+      expect(spooled.exchanges[0].assistant).toBe('Use Redis for caching');
+    });
+
+    it('truncates messages over 10KB', async () => {
+      const mockFetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ captured: 1 }),
+      });
+
+      fs.writeFileSync(
+        path.join(testDir, '.tlc.json'),
+        JSON.stringify({ project: 'my-app' })
+      );
+
+      const longMessage = 'x'.repeat(15000); // 15KB
+
+      await captureExchange({
+        cwd: testDir,
+        assistantMessage: longMessage,
+        userMessage: 'short question',
+        sessionId: 'sess-3',
+      }, { fetch: mockFetch });
+
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(body.exchanges[0].assistant.length).toBeLessThanOrEqual(10240 + 20); // 10KB + truncation marker
+    });
+
+    it('never throws on any error', async () => {
+      // No .tlc.json, no spool dir, fetch fails — still should not throw
+      const mockFetch = vi.fn().mockRejectedValue(new Error('total failure'));
+
+      await expect(
+        captureExchange({
+          cwd: '/nonexistent/path',
+          assistantMessage: 'test',
+          userMessage: null,
+          sessionId: 'sess-4',
+        }, { fetch: mockFetch })
+      ).resolves.not.toThrow();
+    });
+
+    it('detects projectId from .tlc.json', async () => {
+      const mockFetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ captured: 1 }),
+      });
+
+      fs.writeFileSync(
+        path.join(testDir, '.tlc.json'),
+        JSON.stringify({ project: 'special-project' })
+      );
+
+      await captureExchange({
+        cwd: testDir,
+        assistantMessage: 'test',
+        userMessage: 'test',
+        sessionId: 'sess-5',
+      }, { fetch: mockFetch });
+
+      const url = mockFetch.mock.calls[0][0];
+      expect(url).toContain('/projects/special-project/');
+    });
+
+    it('falls back to directory name when no .tlc.json', async () => {
+      const mockFetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ captured: 1 }),
+      });
+
+      // No .tlc.json in testDir
+
+      await captureExchange({
+        cwd: testDir,
+        assistantMessage: 'test',
+        userMessage: 'test',
+        sessionId: 'sess-6',
+      }, { fetch: mockFetch });
+
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+      const url = mockFetch.mock.calls[0][0];
+      // Should contain the directory basename as projectId
+      expect(url).toContain('/projects/');
+    });
+
+    it('skips capture when assistantMessage is empty', async () => {
+      const mockFetch = vi.fn();
+
+      await captureExchange({
+        cwd: testDir,
+        assistantMessage: '',
+        userMessage: 'test',
+        sessionId: 'sess-7',
+      }, { fetch: mockFetch });
+
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+  });
+
+  // ── drainSpool ───────────────────────────────────────────────────
+
+  describe('drainSpool', () => {
+    it('posts spooled entries and removes them on success', async () => {
+      const mockFetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ captured: 1 }),
+      });
+
+      const spoolDir = path.join(testDir, '.tlc', 'memory');
+      fs.mkdirSync(spoolDir, { recursive: true });
+
+      const spoolPath = path.join(spoolDir, SPOOL_FILENAME);
+      const entry1 = JSON.stringify({
+        projectId: 'my-app',
+        exchanges: [{ user: 'q1', assistant: 'a1', timestamp: Date.now() }],
+      });
+      const entry2 = JSON.stringify({
+        projectId: 'my-app',
+        exchanges: [{ user: 'q2', assistant: 'a2', timestamp: Date.now() }],
+      });
+      fs.writeFileSync(spoolPath, entry1 + '\n' + entry2 + '\n');
+
+      await drainSpool(spoolDir, { fetch: mockFetch });
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+
+      // Spool file should be empty or removed
+      if (fs.existsSync(spoolPath)) {
+        expect(fs.readFileSync(spoolPath, 'utf-8').trim()).toBe('');
+      }
+    });
+
+    it('handles empty spool file without error', async () => {
+      const mockFetch = vi.fn();
+
+      const spoolDir = path.join(testDir, '.tlc', 'memory');
+      fs.mkdirSync(spoolDir, { recursive: true });
+      fs.writeFileSync(path.join(spoolDir, SPOOL_FILENAME), '');
+
+      await expect(drainSpool(spoolDir, { fetch: mockFetch })).resolves.not.toThrow();
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    it('handles missing spool file without error', async () => {
+      const mockFetch = vi.fn();
+
+      await expect(drainSpool(testDir, { fetch: mockFetch })).resolves.not.toThrow();
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    it('preserves failed entries in spool', async () => {
+      // First call succeeds, second fails
+      const mockFetch = vi.fn()
+        .mockResolvedValueOnce({ ok: true, json: async () => ({ captured: 1 }) })
+        .mockRejectedValueOnce(new Error('ECONNREFUSED'));
+
+      const spoolDir = path.join(testDir, '.tlc', 'memory');
+      fs.mkdirSync(spoolDir, { recursive: true });
+
+      const spoolPath = path.join(spoolDir, SPOOL_FILENAME);
+      const entry1 = JSON.stringify({
+        projectId: 'my-app',
+        exchanges: [{ user: 'q1', assistant: 'a1', timestamp: 1 }],
+      });
+      const entry2 = JSON.stringify({
+        projectId: 'my-app',
+        exchanges: [{ user: 'q2', assistant: 'a2', timestamp: 2 }],
+      });
+      fs.writeFileSync(spoolPath, entry1 + '\n' + entry2 + '\n');
+
+      await drainSpool(spoolDir, { fetch: mockFetch });
+
+      // Failed entry should remain in spool
+      const remaining = fs.readFileSync(spoolPath, 'utf-8').trim();
+      expect(remaining).not.toBe('');
+      const parsed = JSON.parse(remaining);
+      expect(parsed.exchanges[0].assistant).toBe('a2');
+    });
+  });
+});

package/server/lib/capture-guard.js

@@ -0,0 +1,140 @@
+/**
+ * Capture Guard - Endpoint hardening for the memory capture API.
+ *
+ * Provides payload size validation, exchange validation, content deduplication,
+ * and per-project rate limiting.
+ *
+ * @module capture-guard
+ */
+
+const crypto = require('crypto');
+
+/** Maximum payload size in bytes (100KB) */
+const MAX_PAYLOAD_SIZE = 100 * 1024;
+
+/** Deduplication window in milliseconds (60 seconds) */
+const DEDUP_WINDOW_MS = 60 * 1000;
+
+/** Maximum captures per minute per project */
+const RATE_LIMIT_PER_MINUTE = 100;
+
+/** Rate limit window in milliseconds (60 seconds) */
+const RATE_LIMIT_WINDOW_MS = 60 * 1000;
+
+/**
+ * Create a capture guard instance with internal state for dedup and rate limiting.
+ *
+ * @returns {{ validate: Function, deduplicate: Function, checkRateLimit: Function }}
+ */
+function createCaptureGuard() {
+  /** Map of content hash → timestamp for deduplication */
+  const dedupCache = new Map();
+
+  /** Map of projectId → { count, windowStart } for rate limiting */
+  const rateLimits = new Map();
+
+  /**
+   * Hash exchange content for deduplication.
+   * @param {object} exchange
+   * @returns {string}
+   */
+  function hashExchange(exchange) {
+    const content = (exchange.user || '') + '|' + (exchange.assistant || '');
+    return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
+  }
+
+  /**
+   * Clean expired entries from dedup cache.
+   */
+  function cleanDedupCache() {
+    const now = Date.now();
+    for (const [hash, timestamp] of dedupCache) {
+      if (now - timestamp > DEDUP_WINDOW_MS) {
+        dedupCache.delete(hash);
+      }
+    }
+  }
+
+  /**
+   * Validate the capture payload for size and structure.
+   *
+   * @param {object} payload - The request body
+   * @param {string} projectId - Project identifier
+   * @returns {{ ok: boolean, status?: number, error?: string }}
+   */
+  function validate(payload, projectId) {
+    // Size check
+    const payloadSize = JSON.stringify(payload).length;
+    if (payloadSize > MAX_PAYLOAD_SIZE) {
+      return { ok: false, status: 413, error: `Payload too large: ${payloadSize} bytes (max ${MAX_PAYLOAD_SIZE})` };
+    }
+
+    // Exchange validation
+    if (!payload.exchanges || !Array.isArray(payload.exchanges)) {
+      return { ok: false, status: 400, error: 'exchanges array is required' };
+    }
+
+    for (const exchange of payload.exchanges) {
+      const hasUser = exchange.user && typeof exchange.user === 'string' && exchange.user.trim().length > 0;
+      const hasAssistant = exchange.assistant && typeof exchange.assistant === 'string' && exchange.assistant.trim().length > 0;
+      if (!hasUser && !hasAssistant) {
+        return { ok: false, status: 400, error: 'Each exchange must have at least one of user or assistant as a non-empty string' };
+      }
+    }
+
+    return { ok: true };
+  }
+
+  /**
+   * Filter out duplicate exchanges within the dedup window.
+   *
+   * @param {Array} exchanges - Array of exchange objects
+   * @param {string} projectId - Project identifier
+   * @returns {Array} Deduplicated exchanges
+   */
+  function deduplicate(exchanges, projectId) {
+    cleanDedupCache();
+    const now = Date.now();
+    const unique = [];
+
+    for (const exchange of exchanges) {
+      const hash = projectId + ':' + hashExchange(exchange);
+      const lastSeen = dedupCache.get(hash);
+
+      if (!lastSeen || (now - lastSeen) > DEDUP_WINDOW_MS) {
+        dedupCache.set(hash, now);
+        unique.push(exchange);
+      }
+    }
+
+    return unique;
+  }
+
+  /**
+   * Check if a project has exceeded its rate limit.
+   *
+   * @param {string} projectId - Project identifier
+   * @returns {{ ok: boolean, status?: number, error?: string }}
+   */
+  function checkRateLimit(projectId) {
+    const now = Date.now();
+    let entry = rateLimits.get(projectId);
+
+    if (!entry || (now - entry.windowStart) > RATE_LIMIT_WINDOW_MS) {
+      entry = { count: 0, windowStart: now };
+      rateLimits.set(projectId, entry);
+    }
+
+    entry.count++;
+
+    if (entry.count > RATE_LIMIT_PER_MINUTE) {
+      return { ok: false, status: 429, error: `Rate limit exceeded: ${RATE_LIMIT_PER_MINUTE} captures/minute` };
+    }
+
+    return { ok: true };
+  }
+
+  return { validate, deduplicate, checkRateLimit };
+}
+
+module.exports = { createCaptureGuard };

package/server/lib/capture-guard.test.js

@@ -0,0 +1,182 @@
+/**
+ * Capture Guard Tests - Phase 82 Task 4
+ *
+ * Tests for endpoint hardening: size limits, dedup, rate limiting.
+ *
+ * RED: capture-guard.js does not exist yet.
+ */
+
+import { describe, it, beforeEach, afterEach, expect, vi } from 'vitest';
+
+import { createCaptureGuard } from './capture-guard.js';
+
+describe('capture-guard', () => {
+  let guard;
+
+  beforeEach(() => {
+    guard = createCaptureGuard();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('payload size validation', () => {
+    it('rejects payload over 100KB', () => {
+      const hugePayload = {
+        exchanges: [{
+          user: 'x'.repeat(50000),
+          assistant: 'y'.repeat(60000),
+          timestamp: Date.now(),
+        }],
+      };
+
+      const result = guard.validate(hugePayload, 'test-project');
+
+      expect(result.ok).toBe(false);
+      expect(result.status).toBe(413);
+      expect(result.error).toMatch(/payload.*too.*large/i);
+    });
+
+    it('accepts payload under 100KB', () => {
+      const normalPayload = {
+        exchanges: [{
+          user: 'How should we handle auth?',
+          assistant: 'Use JWT tokens',
+          timestamp: Date.now(),
+        }],
+      };
+
+      const result = guard.validate(normalPayload, 'test-project');
+
+      expect(result.ok).toBe(true);
+    });
+  });
+
+  describe('exchange validation', () => {
+    it('rejects exchange without user or assistant', () => {
+      const payload = {
+        exchanges: [{ timestamp: Date.now() }],
+      };
+
+      const result = guard.validate(payload, 'test-project');
+
+      expect(result.ok).toBe(false);
+      expect(result.status).toBe(400);
+    });
+
+    it('accepts exchange with only assistant message', () => {
+      const payload = {
+        exchanges: [{ assistant: 'some response', timestamp: Date.now() }],
+      };
+
+      const result = guard.validate(payload, 'test-project');
+
+      expect(result.ok).toBe(true);
+    });
+
+    it('accepts exchange with only user message', () => {
+      const payload = {
+        exchanges: [{ user: 'some question', timestamp: Date.now() }],
+      };
+
+      const result = guard.validate(payload, 'test-project');
+
+      expect(result.ok).toBe(true);
+    });
+  });
+
+  describe('deduplication', () => {
+    it('deduplicates identical exchanges within 60s window', () => {
+      const exchange = {
+        user: 'What cache?',
+        assistant: 'Use Redis',
+        timestamp: Date.now(),
+      };
+
+      const first = guard.deduplicate([exchange], 'proj-1');
+      expect(first).toHaveLength(1);
+
+      // Same exchange again immediately
+      const second = guard.deduplicate([exchange], 'proj-1');
+      expect(second).toHaveLength(0);
+    });
+
+    it('allows same exchange after 60s window expires', () => {
+      const exchange = {
+        user: 'What cache?',
+        assistant: 'Use Redis',
+        timestamp: Date.now(),
+      };
+
+      const first = guard.deduplicate([exchange], 'proj-1');
+      expect(first).toHaveLength(1);
+
+      // Advance 61 seconds
+      vi.advanceTimersByTime(61000);
+
+      const second = guard.deduplicate([exchange], 'proj-1');
+      expect(second).toHaveLength(1);
+    });
+
+    it('deduplicates per-project (same exchange in different projects is allowed)', () => {
+      const exchange = {
+        user: 'What cache?',
+        assistant: 'Use Redis',
+        timestamp: Date.now(),
+      };
+
+      const proj1 = guard.deduplicate([exchange], 'proj-1');
+      expect(proj1).toHaveLength(1);
+
+      const proj2 = guard.deduplicate([exchange], 'proj-2');
+      expect(proj2).toHaveLength(1);
+    });
+  });
+
+  describe('rate limiting', () => {
+    it('allows requests under rate limit', () => {
+      for (let i = 0; i < 50; i++) {
+        const result = guard.checkRateLimit('proj-1');
+        expect(result.ok).toBe(true);
+      }
+    });
+
+    it('rate limits at 100 captures per minute', () => {
+      // Burn through 100 requests
+      for (let i = 0; i < 100; i++) {
+        guard.checkRateLimit('proj-1');
+      }
+
+      const result = guard.checkRateLimit('proj-1');
+
+      expect(result.ok).toBe(false);
+      expect(result.status).toBe(429);
+    });
+
+    it('resets rate limit after 60 seconds', () => {
+      // Hit the limit
+      for (let i = 0; i < 100; i++) {
+        guard.checkRateLimit('proj-1');
+      }
+      expect(guard.checkRateLimit('proj-1').ok).toBe(false);
+
+      // Advance 61 seconds
+      vi.advanceTimersByTime(61000);
+
+      expect(guard.checkRateLimit('proj-1').ok).toBe(true);
+    });
+
+    it('rate limits per-project', () => {
+      // Hit limit on proj-1
+      for (let i = 0; i < 100; i++) {
+        guard.checkRateLimit('proj-1');
+      }
+      expect(guard.checkRateLimit('proj-1').ok).toBe(false);
+
+      // proj-2 should still be allowed
+      expect(guard.checkRateLimit('proj-2').ok).toBe(true);
+    });
+  });
+});