Phase 1: Local MITM proxy with CA lifecycle and trace capture

AGENTS.md

@@ -1,6 +1,6 @@
 # AgentTap - Development Guide
 
-> **IMPORTANT**: Do NOT update this file unless the user explicitly says to.
+> **IMPORTANT**: Update this file with key learnings as they are discovered during development. Keep entries brief and actionable.
 
 ## Project Overview
 
@@ -86,4 +86,43 @@ groq: api.groq.com
 - All proxy operations must handle TLS errors gracefully
 - Traces must be queryable by provider, model, timestamp, and source app
 
+## Rollback & Restore
+
+**Kill proxy:** `pkill -f AgentTap` or `lsof -ti:8443 | xargs kill -9`
+**Remove CA:** `rm -rf ~/Library/Application\ Support/AgentTap/ca/`
+**Remove CA from system keychain:** `security delete-certificate -c "AgentTap CA" /Library/Keychains/System.keychain`
+**Remove pf rules:** `sudo pfctl -f /etc/pf.conf` (restores defaults)
+**Verify no lingering listeners:** `lsof -i :8443 -i :18443`
+**Uninstall app:** `rm -rf ~/Library/Application\ Support/AgentTap/`
+
+## Key Learnings
+
+### Bun TLS Limitations (CRITICAL)
+
+Bun's `node:tls` has significant limitations for MITM proxy use cases:
+
+- **`tls.TLSSocket` wrapping with `isServer: true`**: data events never fire on the wrapped socket
+- **`pipe()` between TLS sockets**: drops the TLS ClientHello — data never arrives
+- **`SNICallback` on `tls.createServer`**: handshake completes but cleartext data events don't fire on piped connections
+
+**Working pattern**: Per-domain `tls.createServer` with **static certs** (no SNICallback) + manual ClientHello capture via `once("data")` after sending CONNECT 200 + `net.connect` to loopback TLS server with explicit `write()` forwarding (not pipe). See `proxy-server.ts`.
+
+### HTTP Response Completion
+
+HTTP/1.1 keep-alive means upstream connections don't close after sending a response. Never rely on `end`/`close` events for response completion. Instead detect completion by:
+- **Content-Length**: track body bytes received vs header value
+- **Chunked**: scan for `0\r\n\r\n` terminator
+- **SSE**: finalize only on connection close (server closes when stream ends)
+
+### Dependencies
+
+- `@peculiar/x509` requires `reflect-metadata` polyfill (`import "reflect-metadata"` at top of cert-generator.ts) — tsyringe dependency
+- Use `globalThis.crypto` (Bun built-in WebCrypto), NOT `@peculiar/webcrypto`
+- `bun-types` has known `Buffer`/`ArrayBufferLike` type mismatches with strict TS — safe to ignore, works at runtime
+
+### ElectroBun
+
+- Tray click handlers are sync — use `.then()/.catch()` for async operations, not `await`
+- `exitOnLastWindowClosed: false` required for tray-only apps
+
 *Generated by [LynxPrompt](https://lynxprompt.com) CLI*

electrobun.config.ts

@@ -31,6 +31,8 @@ export default {
       "src/views/mainview/index.css": "views/mainview/index.css",
       "src/views/mainview/assets/tray-icon-template.png":
         "views/assets/tray-icon-template.png",
+      "src/views/mainview/assets/tray-icon-template@2x.png":
+        "views/assets/tray-icon-template@2x.png",
     },
 
     useAsar: false,

package.json

@@ -18,5 +18,9 @@
   "devDependencies": {
     "electrobun": "^1.16.0",
     "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "@peculiar/x509": "^2.0.0",
+    "reflect-metadata": "^0.2.2"
   }
 }

src/bun/ca/ca-manager.ts

@@ -0,0 +1,83 @@
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { generateRootCA, type KeyCertPair } from "./cert-generator";
+
+export type CAStatus =
+  | "not-generated"
+  | "generated"
+  | "installed"
+  | "expired";
+
+const CA_DIR = join(
+  process.env.HOME ?? "~",
+  "Library",
+  "Application Support",
+  "AgentTap",
+  "ca",
+);
+const CA_KEY_PATH = join(CA_DIR, "ca-key.pem");
+const CA_CERT_PATH = join(CA_DIR, "ca.pem");
+
+let loaded: KeyCertPair | null = null;
+
+export function getCAPaths() {
+  return { keyPath: CA_KEY_PATH, certPath: CA_CERT_PATH, dir: CA_DIR };
+}
+
+export async function ensureCA(): Promise<KeyCertPair> {
+  if (loaded) return loaded;
+
+  if (existsSync(CA_KEY_PATH) && existsSync(CA_CERT_PATH)) {
+    const key = await Bun.file(CA_KEY_PATH).text();
+    const cert = await Bun.file(CA_CERT_PATH).text();
+
+    if (isCertExpired(cert)) {
+      console.log("[CA] Certificate expired, regenerating...");
+      return regenerateCA();
+    }
+
+    loaded = { key, cert };
+    console.log("[CA] Loaded existing CA from", CA_DIR);
+    return loaded;
+  }
+
+  return regenerateCA();
+}
+
+export async function regenerateCA(): Promise<KeyCertPair> {
+  await mkdir(CA_DIR, { recursive: true });
+
+  console.log("[CA] Generating new root CA...");
+  const pair = await generateRootCA();
+
+  await Bun.write(CA_KEY_PATH, pair.key, { mode: 0o600 });
+  await Bun.write(CA_CERT_PATH, pair.cert);
+
+  loaded = pair;
+  console.log("[CA] Root CA written to", CA_DIR);
+  return loaded;
+}
+
+export function getCA(): KeyCertPair | null {
+  return loaded;
+}
+
+export function getCAStatus(): CAStatus {
+  if (!loaded) {
+    if (!existsSync(CA_CERT_PATH)) return "not-generated";
+  }
+  if (loaded && isCertExpired(loaded.cert)) return "expired";
+  if (loaded) return "generated";
+  return "not-generated";
+}
+
+function isCertExpired(pem: string): boolean {
+  try {
+    const crypto = require("node:crypto");
+    const cert = new crypto.X509Certificate(pem);
+    return new Date(cert.validTo) < new Date();
+  } catch {
+    return false;
+  }
+}

src/bun/ca/cert-cache.ts

@@ -0,0 +1,56 @@
+import type { KeyCertPair } from "./cert-generator";
+import { generateLeafCert } from "./cert-generator";
+
+const MAX_CACHE_SIZE = 100;
+
+interface CacheEntry {
+  pair: KeyCertPair;
+  expiresAt: number;
+  lastUsed: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+export async function getOrGenerateLeafCert(
+  domain: string,
+  caCert: string,
+  caKey: string,
+): Promise<KeyCertPair> {
+  const existing = cache.get(domain);
+  const now = Date.now();
+
+  if (existing && existing.expiresAt > now) {
+    existing.lastUsed = now;
+    return existing.pair;
+  }
+
+  const pair = await generateLeafCert(domain, caCert, caKey);
+
+  if (cache.size >= MAX_CACHE_SIZE) {
+    evictLRU();
+  }
+
+  cache.set(domain, {
+    pair,
+    expiresAt: now + 25 * 86400_000, // 25 days (leaf certs valid 30)
+    lastUsed: now,
+  });
+
+  return pair;
+}
+
+export function clearCache(): void {
+  cache.clear();
+}
+
+function evictLRU(): void {
+  let oldest: string | null = null;
+  let oldestTime = Infinity;
+  for (const [domain, entry] of cache) {
+    if (entry.lastUsed < oldestTime) {
+      oldestTime = entry.lastUsed;
+      oldest = domain;
+    }
+  }
+  if (oldest) cache.delete(oldest);
+}