Document request.authorized and request.peerCertificate

[kriszyp]

⊙ Problem

The HTTP Request reference mentioned request.authorized only in prose and never mentioned request.peerCertificate. A handler doing mTLS could not tell what either returns, or that results differ behind Harper Fabric's proxy and on Bun and uWebSockets.

🤔 Is this requirement warranted?

As specified, yes. Both getters ship in Request.ts, and the proxy path from harper#1858 (v5.2.0) changes who verifies the client and what the certificate object holds. Without the rows, a reader can assume the wrong trust root. No in-flight PR covers this.

💡 Solution

• The Request properties table gains authorized and peerCertificate, with their results on direct TLS, behind the Fabric proxy, on a plain connection, and on Bun and uWebSockets.
• The rows show where the TLS paths differ (trusted CAs, certificate fields) and that issuerCertificate can be missing.
• The mTLS paragraph links both rows and says authorized ignores revocation, which Harper's mTLS authentication checks separately.
• The mTLS setup and http.mtls pages now name authority certificate records as a CA source.

🤔 Is request.authorized the right gate to recommend?

The proxy path verifies against Symphony's CA, not Harper's, so the same true can rest on different trust roots. The alternative is to point apps at Harper's mTLS authentication (request.user), which also applies revocation. I kept authorized because it works in any middleware, and added the caveats. Reversing it later means re-teaching readers.

🤔 Keep both TLS paths inside the table cells?

The peerCertificate cell is now long, and a short "Client certificates" subsection the table links to would scan better. I kept the cells so each row stands alone. Links from the mTLS paragraph land at the table top, not on the row, because no table in reference/ uses per-row anchors. Easy to restructure later.

✅ Verification

• npm run build passes with no broken links or anchors, and npm run format:check is clean. Prettier re-widened the table, so every row in it shows as changed.
• Checked every runtime claim against harper origin/main: the Node, Bun and uWebSockets getters in server/serverHelpers/Request.ts, and the proxy path in server/serverHelpers/proxyProtocol.ts (applyProxyHeader, synthesizePeerCertificate). The revocation caveat matches the gate in security/auth.ts.
• git tag --contains places the proxy path (harper#1858) in v5.2.0, which the v5.2.0 badges on the new rows reflect. The related harper#1985 added connectionInfo.

_{🤖 Generated by Anthropic Claude Sonnet 5.5; posted via @kriszyp.}

🤖 Generated with Claude Code

https://claude.ai/code/session_01UrvaPnSVqfCTL7KPatikPN

Related PRs: none found
Complexity: medium

Deferred findings

• 839360062b78ca53 nit documentation — reference/http/api.md — #properties links land at table top, not the new rows — NOT FILED

_{Review-Coverage: authored=claude; ran=gemini,cursor-muse,codex; adjudicated=domain; blocked=muse(failed); declined=cursor-grok,cursor-composer,cursor-kimi; rounds=7; full=1 @ d8b1e49}

_{Review-Attention: skim ~2m (decisions: mirror-semantics-in-table-cells, authorized-as-recommended-gate) @ d8b1e49}

[gemini-code-assist]

Code Review

This pull request updates the documentation for Harper's HTTP API, configuration, and mTLS authentication, specifically detailing the new authorized and peerCertificate request properties and clarifying CA verification behavior. The review feedback recommends enhancing the clarity and conciseness of the security warnings in the mTLS section by removing filler phrases like 'Note that' and splitting complex sentences into distinct, readable points.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-735

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-735

This preview will update automatically when you push new commits.