docs(http): document request.connectionInfo (forwarded PROXY v2 TLS facts) - #614
docs(http): document request.connectionInfo (forwarded PROXY v2 TLS facts)#614kriszyp wants to merge 2 commits into
Conversation
…acts) Companion to harper#1985 — documents the new request.connectionInfo accessor (ALPN, SNI authority, TLS version/cipher, JA3/JA4 fingerprint, verified mTLS client cert chain, forwarded over PROXY protocol v2 by a TLS-terminating proxy) on the Request reference, plus the clarified request.protocol behavior behind such a proxy. Includes the ConnectionInfo shape, a JA4 usage example, and the trust/mTLS-verified caveat. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the HTTP API documentation in reference/http/api.md to document the new connectionInfo property on the Request object (introduced in v5.2.0) and explains how it exposes TLS facts forwarded over PROXY protocol v2. The feedback suggests defining the get method as static in the code example for consistency with Harper Resource documentation guidelines, and using a <VersionBadge type="changed" version="v5.2.0" /> badge to denote the updated behavior of the protocol property.
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-614 This preview will update automatically when you push new commits. |
Ethan-Arrowood
left a comment
Ethan-Arrowood
left a comment
There was a problem hiding this comment.
Traced every field, type, and presence condition against harper#1985 (which I approved earlier today) — the content is accurate, including the tls.verified-without-clientCertChain caveat. One real problem plus a few polish items, all with suggestions inline.
The one that matters: the request.peerCertificate link points at certificate-verification.md, which is about CRL/OCSP revocation checking and never mentions peerCertificate — in fact nothing in this repo documents it. Anyone following the mTLS-gating advice lands on a page that can't help them.
Merge-ordering: this should land after harper#1985, since it documents an accessor that doesn't exist on main yet. A connectionInfo entry in release-notes/v5-lincoln/5.2.md is also still missing — fine as a follow-up when #1985 lands.
On the Gemini bot's other suggestion (make the example's get static): I'd leave it as-is — it matches this page's existing instance-method examples, and I found no such rule in AGENTS.md or CONTRIBUTING.md.
One question: the core PR's own field doc recommends request.authorized as the standard verified-mTLS gate, while these docs recommend peerCertificate + the authenticated user. Intentional, or worth mentioning request.authorized too?
sent with Claude Opus 5
- Add <VersionBadge type="changed" version="v5.2.0" /> to the protocol row, matching the file's convention for documenting behavior changes to existing surface (Gemini + Ethan Arrowood, PR #614). - Fix the peerCertificate link: certificate-verification.md is about CRL/OCSP revocation and never mentions peerCertificate or the authenticated-user flow (Ethan Arrowood). - Tighten the connectionInfo undefined/runtime caveat: it's undefined whenever no TLS-bearing TLV decoded (not just "no v2 header"), and it's Node-runtime only — Bun and uWebSockets never populate it (Ethan Arrowood). - Flag alpn/authority/ja3/ja4 as string-decoded from raw, unvalidated TLV payloads with no grammar/length validation, matching the harper source docblock (server/serverHelpers/proxyProtocol.ts) that introduces these fields, and warn against placing them unsanitized in headers, logs, or cache keys. Switch the JA4 example's denial from a generic `throw new Error` (reads as a 500) to the repo's established `new Response(..., { status: 403 })` policy-denial convention (see reference/resources/resource-api.md). - Correct the verified-mTLS gating guidance: point at `request.authorized` (the chain-gated boolean the proxy layer populates with TLSSocket semantics — proxyProtocol.ts's own comment: "For the standard 'verified mTLS client' gate use request.authorized") instead of `request.peerCertificate` + "the authenticated user". Note it's Node-runtime only, same as connectionInfo. - Fix a real accuracy bug surfaced by independent review: `clientCertChain` was documented as "verified," but proxyProtocol.ts attaches the chain whenever the client presented a certificate, independent of the proxy's verify result — `tls.verified` and `clientCertChain` presence are two different signals, and treating chain presence as proof of verification accepts unverified clients. Corrected the property table, the ConnectionInfo interface comment, and the trust paragraph to say so explicitly. - Narrow the `protocol` row to Node-runtime SSL-TLV behavior; Bun and uWebSockets derive the scheme from X-Forwarded-Proto/the listener's secure flag instead. - Scope PROXY v2 decoding to Harper Fabric's proxy-protocol UDS mirrors specifically, not ordinary http.port/securePort listeners. The static-vs-instance-method suggestion on the get() example was deliberately left as-is: the file's other Resource example (line 148) also uses an instance method, and Ethan confirmed no such rule exists in AGENTS.md/CONTRIBUTING.md. Refs #614 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
Re: your Rewrote the trust paragraph to lead with Neither sent with Claude Sonnet 5 |
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-614 This preview will update automatically when you push new commits. |
2 participants
Companion docs for harper#1985 (closes harper#1983).
What
Documents the new
request.connectionInfoaccessor on the HTTPRequestreference (reference/http/api.md): the TLS facts a fronting TLS-terminating proxy (Harper Fabric's Symphony) forwards over PROXY protocol v2 — negotiated ALPN, SNI authority, TLS version/cipher, the client's JA3/JA4 fingerprint, and the verified mTLS client certificate chain. Adds:RequestProperties table (with<VersionBadge version="v5.2.0" />),ConnectionInfoTypeScript shape, a JA4 usage example, and the trust /tls.verified-vs-mTLS caveat,protocolrow: it reflects the client's original scheme (https) behind a v2-forwarding proxy even though the proxy→Harper hop is plaintext.Notes for review
v5.2.0badge — the feature ships in core 5.2 (currently5.2.0-beta.2), per the versioning convention.connectionInfo.tls.verifiedreflects the proxy's verify bit and can betruewith noclientCertChain(proxy verified but omitted an oversized chain), so the docs steer mTLS gating torequest.peerCertificate+ the authenticated user, matching the core PR's field doc.npm run format:checkclean;npm run buildsucceeds with no broken links/anchors on this page (the one broken-anchor warning is a pre-existing/release-notes/v5-lincoln/5.1issue, untouched here).Generated by an LLM (Claude Opus 4.8) pairing with Kris.