Document how to attribute a private-api 401#59
Conversation
These handlers pipe upstream responses through unchanged, so a 401 from a backend is indistinguishable from one this service produced unless you look at the body length. Records that tell, plus two checks that separate a token problem from a misconfigured gate downstream.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Greptile SummaryThis PR adds private-api 401 troubleshooting notes to
Confidence Score: 5/5The documentation change looks mergeable after tightening two troubleshooting examples.
CLAUDE.md Important Files Changed
Reviews (1): Last reviewed commit: "docs: how to attribute a private-api 401" | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| answers `SendText(401, "Unauthorized")`, a 12-byte body. A longer body almost | ||
| always means the 401 was piped from further upstream. | ||
|
|
There was a problem hiding this comment.
When the backend returns a 401 body of Unauthorized, the proxy path forwards that body unchanged and it is also 12 bytes. The body-length check only proves upstream when the body is longer, so the current wording can make an upstream 401 look like a local auth failure.
There was a problem hiding this comment.
Confirmed and fixed in 496fc52. You are right that the inference only runs one way: an upstream that also answers Unauthorized is piped through at exactly 12 bytes, so a short body is inconclusive. Reworded to state that a longer body means upstream while a 12-byte body proves nothing.
| notifications succeed while one endpoint 401s for the same session, the code | ||
| validated fine and the failure is downstream of this service. Route-specific | ||
| auth on the backend, not the caller's token, is then the thing to look at. | ||
| - **Check the failure rate.** A token or session problem affects a subset of |
There was a problem hiding this comment.
notifications is a risky sibling example because that handler can continue with a body-supplied user after ValidateCode fails. A request with a bad signed code can therefore succeed there and fail on another private-api route, making the docs incorrectly rule out a token or session problem.
There was a problem hiding this comment.
Confirmed in the source and fixed in 496fc52. Notifications falls back to body.Field("user") when ValidateCode returns nothing, and the following if (JsJson.IsTruthy(user)) overrides even a validated username with that field. So it can answer for a request whose code was rejected, which makes it actively misleading as a validation canary. Swapped the example to notifications/unread and notifications/mark, which 401 unconditionally, and documented the notifications behaviour as a trap rather than dropping it.
The body length only proves upstream in one direction: an upstream answering Unauthorized forwards through at the same 12 bytes, so a short body is inconclusive rather than evidence the 401 was raised here. notifications was the wrong sibling to suggest comparing against. It falls back to a body-supplied user when validation fails and overrides even a validated username with that field, so it can answer for a request whose code was rejected. Points at notifications/unread and notifications/mark instead, which 401 unconditionally, and records the notifications behaviour as a trap.
1 participant
A 401 on a private-API route is easy to misattribute to this service, because the handlers pipe upstream responses through unchanged: a 401 from the backend arrives looking identical to one produced here.
Records the tell and two cheap checks:
SendText(401, "Unauthorized"), 12 bytes. A longer body means it was piped from upstream.ValidateCode. If one endpoint 401s while another succeeds for the same session, the code validated fine and the cause is downstream.Also notes that
RequireAuthedUsernameand a directValidateCodecall validate identically, so the choice between them never explains one route failing while another passes.Written without infrastructure specifics, per this repo being public. Documentation only.