docs: gardening Apr 2026 - #40
Conversation
Greptile SummaryDocumentation gardening pass updating Confidence Score: 5/5Safe to merge — docs-only PR, no runtime code changed, only P2 findings remain All remaining findings are P2 style suggestions (CLAUDE.md stale module map). No P0/P1 issues exist. Both prior review thread concerns (Principle 1/12 conflict, missing Principle 12 version annotation) have been addressed in this PR. docs/architecture.md — CLAUDE.md should also be updated to list X402.Utils and X402.Header
|
| Filename | Overview |
|---|---|
| docs/architecture.md | Updated last-modified date, added Utils/Header to module tree, added Recent Changes section for v0.3.2→v0.3.3; CLAUDE.md Module Map not updated to match |
| docs/golden-principles.md | Principle 1 updated to require HTTPS, Principles 11–12 added with v0.3.2 annotations; prior Principle 1/12 conflict fully resolved |
| docs/quality.md | Test grade A-→A (≥90% coverage confirmed), Security grade B+→A- (TLS+HTTPS enforcement, 8KB size caps, atomic ETS claim) |
Sequence Diagram
sequenceDiagram
participant Client
participant PaymentGate as X402.Plug.PaymentGate
participant Facilitator as X402.Facilitator
participant HTTP as Facilitator.HTTP (HTTPS+TLS)
participant App
Client->>PaymentGate: HTTP request (no PAYMENT-SIGNATURE)
PaymentGate-->>Client: 402 + PAYMENT-REQUIRED header
Client->>PaymentGate: HTTP request + PAYMENT-SIGNATURE
PaymentGate->>PaymentGate: Decode + validate header (≤8KB)
PaymentGate->>Facilitator: verify/2
Facilitator->>HTTP: POST /verify (HTTPS-only, TLS verified)
HTTP-->>Facilitator: {:ok, result}
Facilitator-->>PaymentGate: :ok
PaymentGate->>Facilitator: settle/2
Facilitator->>HTTP: POST /settle (HTTPS-only, TLS verified)
HTTP-->>Facilitator: {:ok, result}
Facilitator-->>PaymentGate: :ok
PaymentGate->>App: pass conn
App-->>Client: 200 + PAYMENT-RESPONSE header
Reviews (6): Last reviewed commit: "docs: fix module tree and golden-princip..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| ## 12. Enforce HTTPS on Facilitator URL | ||
| The facilitator `base_url` must start with `https://`. This is validated at `Facilitator.start_link/1` time, not at call time. | ||
|
|
||
| **Violation:** Accepting an `http://` facilitator URL at startup without raising. |
There was a problem hiding this comment.
Principle 1 explicitly states: "Any facilitator URL is accepted" as part of its Zero Lock-In guarantee. Principle 12 now contradicts this by restricting accepted URLs to https:// only. A contributor reading Principle 1 would be misled.
Consider either:
- Updating Principle 1's wording to note the HTTPS constraint (e.g., "Any HTTPS facilitator URL is accepted"), or
- Adding a clarifying note to Principle 12 that it is a deliberate, security-motivated refinement of Principle 1.
|
|
||
| **Violation:** Passing `[transport_opts: [verify: :verify_none]]` to `Finch.start_link`. | ||
|
|
||
| ## 12. Enforce HTTPS on Facilitator URL |
There was a problem hiding this comment.
Principle 11 carries a (added v0.3.2) annotation in its heading for traceability, but Principle 12 — added in the same release — does not. For consistency:
| ## 12. Enforce HTTPS on Facilitator URL | |
| ## 12. Enforce HTTPS on Facilitator URL (added v0.3.2) |
- Add X402.Utils and X402.Header to module structure tree - Add (added v0.3.2) annotation to Principle 12 - Fix Principle 1 wording: 'Any facilitator URL' → 'Any HTTPS facilitator URL' to remove conflict with Principle 12
|
@greptile review |
4 similar comments
|
@greptile review |
|
@greptile review |
|
@greptile review |
|
@greptile review |
1 participant
Weekly doc gardening pass.
Changes
docs/architecture.md— timestamped to Apr 1, added v0.3.2→v0.3.3 changes:X402.Utilsnew module, TLS enforcement, 8KB header caps, HTTPS-only facilitator URL, SIWX ETS fixesdocs/quality.md— Tests upgraded A- → A (coverage confirmed ≥90%), Security upgraded B+ → A-docs/golden-principles.md— added principles 11 (TLS must be verified) and 12 (HTTPS on facilitator URL), reflecting new enforcement added in v0.3.2/v0.3.3Note
Low Risk
Docs-only changes updating architecture/quality notes and documenting HTTPS/TLS requirements; no runtime code or behavior is modified.
Overview
Updates documentation to reflect recent v0.3.3 work:
docs/architecture.mdaddsX402.Utils/X402.Headerto the module map and includes a new “Recent Changes” section covering TLS peer verification, HTTPS-only facilitator URLs, header/ETS size caps, and related SIWX fixes.Refreshes
docs/golden-principles.mdto require HTTPS facilitator URLs and verified TLS (new principles 11–12), and updatesdocs/quality.mdtimestamps/grades to note ≥90% coverage and the improved security posture.Written by Cursor Bugbot for commit 1b1acb5. This will update automatically on new commits. Configure here.