M4: ALPN lock, WebSocket detection, HAR export

[kalil0321]

Stacked on top of #74.

This is a focused M4 — original plan was full HTTP/2 + WebSocket, but a full H2 MITM and a WS frame relay are each large enough to deserve their own milestone. For v0.1 the practical win is to make the proxy honest about what it supports.

What's in

• ALPN locked to http/1.1 on both TLSContextFactory (server side) and UpstreamPump (client side). Clients capable of h2 negotiate down cleanly instead of failing the handshake or producing malformed frames against our HTTP/1 codec.
• WebSocket detection — ProxyHandler now inspects Upgrade: websocket before dispatching upstream and replies 502 Bad Gateway with a captured error message in the UI. Better than a silent stall.
• HAR 1.2 export — HARExporter produces Chrome/Firefox-compatible HAR with query string parsing, content-type detection, base64 fallback for binary bodies, and _error field for failed flows. Plumbed into the toolbar with an NSSavePanel-driven Export HAR button.

Out of scope (deliberate)

• Full HTTP/2 MITM (parse, route, re-encode h2 frames). Possible later if we want pinned-app or h2-only-API parity.
• WebSocket transparent tunnel relay. Same — needs its own pipeline mode.

---

Generated by Claude Code

---

Summary by cubic

Locks ALPN to HTTP/1.1, blocks WebSocket upgrades with a visible 502 in the UI, and adds HAR 1.2 export from the toolbar. Also stores the CA private key on disk to avoid Keychain prompts.

• New Features

  • HAR 1.2 export for captured flows: better query parsing (decodes + as space, strips fragments), omits postData when bodyless, base64 for binary bodies, adds _error, and uses a shared ISO8601 formatter.
  • “Export HAR” toolbar action with NSSavePanel, timestamped filename, off-main-thread serialize/write, keyboard shortcuts (export/clear/capture), and error alerts.

• Bug Fixes

  • Force ALPN http/1.1 on the proxy server and upstream client so h2-capable clients downgrade cleanly.
  • Detect Upgrade: websocket and return 502; handles comma-separated values, case differences, and multiple headers, and surfaces the error in the UI.
  • Store the CA private key on disk with 0600 perms (directory 0700) to avoid Keychain prompts; regenerate when the certificate exists without the key file.

^{Written for commit b5461ec. Summary will update on new commits.}

Greptile Summary

This PR delivers three focused improvements: ALPN is locked to http/1.1 on both the server-side TLSContextFactory and the upstream client so h2-capable clients negotiate down cleanly, WebSocket upgrade requests are intercepted early and returned as 502 so they surface in the UI rather than silently stalling, and a new HARExporter produces Chrome/Firefox-compatible HAR 1.2 output plumbed into the toolbar via an NSSavePanel.

• ALPN lock — forces http/1.1 negotiation on both sides, preventing handshake failures against the HTTP/1 codec when h2-capable clients connect.
• WebSocket detection — ProxyHandler.isWebSocketUpgrade scans comma-separated and multi-line Upgrade headers case-insensitively, emits a captured error flow to the bus, and responds 502; seven new unit tests cover the detection matrix.
• HAR 1.2 export — HARExporter handles +-as-space form encoding, fragment stripping, conditional postData, base64 for binary bodies, and _error for failed flows; the toolbar write is dispatched off the main actor via Task.detached.

Confidence Score: 5/5

The changes are self-contained and well-tested; the export path runs off the main actor and cannot block the UI.

All three feature areas are covered by new unit tests, the previously identified correctness issues have been addressed in this diff, and no new defects were found in the changed code paths.

No files require special attention.

Important Files Changed

Filename	Overview
macos/Sources/ReverseAPIProxy/Export/HARExporter.swift	New HAR 1.2 exporter with correct query-string parsing (+ as space, percent-decode), conditional postData, base64 fallback for binary bodies, and _error for failed flows. One minor allocation inefficiency: ISO8601DateFormatter is created per entry.
macos/Sources/ReverseAPIProxy/Proxy/ProxyHandler.swift	Adds WebSocket upgrade detection with 502 response and flow emission; static method exposed for testability via internal wrapper. Logic is correct and well-covered by the new test suite.
macos/Sources/ReverseAPI/UI/CaptureToolbar.swift	Adds Export HAR button with NSSavePanel, timestamped filename, Task.detached serialisation/write off the main actor, and NSAlert error handling. Keyboard shortcuts added for export, clear, and capture.
macos/Tests/ReverseAPIProxyTests/HARExporterTests.swift	Comprehensive tests for queryString parsing, decodeFormComponent, entry shape (postData omission, base64 encoding, _error field), and full HAR structure validation.
macos/Tests/ReverseAPIProxyTests/WebSocketDetectionTests.swift	Covers case-insensitive single-header, comma-separated, multi-header, and absent-header variants — good coverage of the detection logic.

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
macos/Sources/ReverseAPIProxy/Export/HARExporter.swift:16-19
A new `ISO8601DateFormatter` is created for every flow that gets serialised. `ISO8601DateFormatter` has non-trivial initialisation overhead; for a capture with hundreds of flows the repeated allocations add up noticeably during export. Hoisting it to a `static let` on the enum lets all calls share the same instance.

```suggestion
    private static let iso8601Formatter: ISO8601DateFormatter = {
        let f = ISO8601DateFormatter()
        f.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
        return f
    }()

    static func entry(for flow: CapturedFlow) -> [String: Any] {
        let formatter = Self.iso8601Formatter
        let started = formatter.string(from: flow.startedAt)
```

_{Reviews (3): Last reviewed commit: "M4 review fixes + tests" | Re-trigger Greptile}

[cubic-dev-ai]

2 issues found across 5 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[kind-agent]

⚠️ Error — The test run failed unexpectedly.

Grok 4 Fast is deprecated. xAI recommends switching to Grok 4.3 (https://openrouter.ai/x-ai/grok-4.3)

This is likely a transient issue. You can re-trigger a run from the dashboard.

[kalil0321]

@greptile review

---

Generated by Claude Code

[kalil0321]

@greptile review

---

Generated by Claude Code

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="macos/Sources/ReverseAPIProxy/CA/CAStore.swift">

<violation number="1" location="macos/Sources/ReverseAPIProxy/CA/CAStore.swift:81">
P1: `exists()` now ignores previously keychain-stored CA keys, so upgrades can silently rotate the root CA instead of loading the existing one.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: exists() now ignores previously keychain-stored CA keys, so upgrades can silently rotate the root CA instead of loading the existing one.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At macos/Sources/ReverseAPIProxy/CA/CAStore.swift, line 81:

<comment>`exists()` now ignores previously keychain-stored CA keys, so upgrades can silently rotate the root CA instead of loading the existing one.</comment>

<file context>
@@ -69,86 +67,33 @@ public final class CAStore: @unchecked Sendable {
     public func exists() -> Bool {
         guard FileManager.default.fileExists(atPath: certificateURL.path) else { return false }
-        return privateKeyExists()
+        return FileManager.default.fileExists(atPath: privateKeyURL.path)
     }
 
</file context>

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.