Repository navigation
fix(api): name an interposed proxy's auth challenge instead of failing silently - #9898
Conversation
Design Review (Fable 5, fork) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Description claims Watch
Suggestions
[DESIGN-REVIEWED] 7021376 |
First Principles Review (Fable 5, fork) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS Two app-local error factories still paste the proxy's HTML page verbatim into the message — crew-companion and project-scaffolder — the exact defect this PR fixes elsewhere. Not justified as shipped
What this change shipsInventory (8 items) — 6 justifiedIntent: let a person whose dashboard sits behind an authenticating proxy see why every call fails and what to do, instead of a silently broken tab — a FIX.
[FIRST-PRINCIPLES-REVIEWED] 7021376 |
UX Review (Fable 5, fork) — 🟡 CONCERNSUX-level review of UX-Verdict: CONCERNS No cold reader has tested the two-arm conditional copy ("if a sign-in page appears… If not…"); every control is shown, so this is the lane's cap. Watch
Suggestions
[UX-REVIEWED] 7021376 |
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Opus 5 Review (fork) — ✅ no blocking findingsReviewed |
bfc36f9 to
caf7961
Compare
b997c27 to
e721da6
Compare
108244c to
56b57f9
Compare
5a9ad13 to
fbff583
Compare
82e2385 to
d0a99ca
Compare
d0a99ca to
b70e07c
Compare
b70e07c to
8b1ea88
Compare
065e53c to
f5cf063
Compare
|
👋 Hi! This PR's description is missing some required sections from our PR template. Workflow runs won't be auto-approved until the description is updated. Missing sections:
Please update your PR description to include these sections, then push or re-save the description. The workflows will be approved on the next cycle. |
Security Scope Review (fork) — 🔴 BLOCK (blocking)Which legitimate operations does no leg reported, and this was not the nothing-to-adjudicate short circuit No |
A proxy in front of the gateway answers a lapsed session with its own HTML sign-in page; detect that and navigate the top-level document so the user can complete it.
Problem / Motivation
A dashboard reached through an authenticating proxy — an identity-aware tunnel, Cloudflare Access, oauth2-proxy, an OIDC-terminating load balancer — sits behind a gate the SPA cannot see. While that gate has a valid session it forwards transparently. When the session lapses with the tab still open, the gate stops forwarding and answers requests itself, with an HTML sign-in page. It serves that page to the background
/apipolls too, which is where the failure becomes invisible.Measured against a real proxy:
There is no
Locationto follow, and no gateway header travels on the response because the request never reached the gateway. SocheckSessionExpired, which keys on the gateway's ownX-Auth-Requiredheader inapi/client.ts, cannot fire — and a silent refresh would re-mint a session that was never the problem.Why it matters
The dashboard fails every call, indefinitely, and states no cause. The tab looks broken rather than signed out, so the reader has no way to tell an expired proxy session from an outage, a bad deploy, or a dead gateway — and the one remedy the app did offer, re-minting its own session, cannot fix a refusal that never reached the gateway.
It is also silent in the strict sense: the polls fail in the background, so a tab left mid-task shows stale content with no banner. Until #9484 the proxy sign-in page was rendered verbatim as the error message, putting
<!DOCTYPE html><html><head><meta charset="utf…in the topbar — which is how the failure was first noticed.What changed
Detection, and nothing more than detection.
api/edgeAuthChallenge.tsrecognises the shape from three signals, all required because any one alone also matches a gateway denial: a status in {401, 403}, an HTML content type, and a body that really is an HTML document. It does not read the body's contents. Both error factories skip detection entirely when the gateway's ownX-Auth-Requiredheader is present, because that header proves the request reached the gateway and so nothing interposed answered it.Two outcomes, not three.
ChallengeOutcomeis'challenged' | 'framed'.framedis separate because it rests on a fact about this document rather than a reading of the far side's: a nested pane cannot complete a sign-in inside itself, so "reload this tab" is the one remedy that is wrong there.Two strings, translated into 11 locales, both conditional. Neither asserts a lapse, because no signal here establishes one. The unframed message leads with the action and covers both cases in one sentence — "Reload this browser tab — if a sign-in page appears, your access proxy's session expired. If not, a proxy or firewall in front of this dashboard refused the request; check its logs, or retry later." The framed one substitutes the remedy a pane can actually complete, naming the origin because a pane's reader cannot see the address bar.
No block-page discrimination, deliberately. An earlier revision tried to tell a lapsed session from a WAF, rate-limit or geo block, scanning the body for anchors, form actions, password fields, meta refreshes and
location=assignments. Review found four separate classes of page it read backwards:/authors/janeas a sign-in link,/oauth2/startas not one, a form-rendered gate as a block, and a geo-block page's visibleLocation = UStext as a redirect. Each fix added one more spelling to a hand-maintained list read against a body the far side authors. The conditional wording above is honest for both cases and names the same action either way, so the distinction bought wording it did not need and a confidence it could not support. Roughly 300 lines of scanner, two word lists and the tests that pinned them are gone with it.Retries stop. Every such refusal sets
authRequiredand a narroweredgeChallengeflag on theApiError, andretryPolicykeys the stop on the narrower one. The gateway's ownX-Auth-Required403 is deliberately excluded: thereattemptSilentRefreshplus the one retry is what recovers a slept-laptop cookie invisibly, and a successful refresh invalidates only['auth-me']whilestaleTimeisInfinity.The framed address is a real anchor. The origin is interpolated into the framed string, so it survives as selectable text on any surface.
components/withOriginLink.tsxadditionally renders it as atarget="_blank"link, wired into all seven places an error message reaches a reader. The harm is mechanical rather than asserted: every one of those rows sets13pxwithoverflowWrap: anywhere, so a real tunnel origin breaks mid-URL and a framed reader — who cannot see it in the address bar either, that being the outer dashboard's — has to retype it at the moment they are locked out. Which message may link is the producer's to say, not the render site's:addressNamedByMessageanswers only for an address the product itself interpolated, so text the far side authored can never become something to click. Provenance is remembered at production rather than re-derived, because a language switch re-evaluates every string and a re-derived comparison would silently drop the link.A capture harness for the error card, following the existing
capture-*.mjspattern.Deliberately not shipped
No automatic navigation. Nothing here acts on the document; the reader signs in.
An earlier revision auto-reloaded an unattended tab, with a cooldown stamp, a per-endpoint attempt cap, an unsaved-work edit latch, a navigation stake, and marker attributes across roughly fifteen components. That branch is gone. Its only audience was a tab left open on a long task with nobody watching — asserted, never reported — and the guards that made it safe imposed a standing obligation on every future surface holding non-field state, whose failure mode was silently discarding work: the exact harm this change exists to prevent. Review found five such surfaces in sequence, which is the evidence that the contract could not converge.
Nothing from the challenge body is read at all, so no URL in it can be followed and no text in it can classify the response. That body is written by whatever sits in front of the gateway.
Scope of the claim
Covered: a gate that answers a lapsed session with an HTML document on 401 or 403.
Not covered and not claimed: a gate that answers a redirect to an identity provider (the browser follows it and the cross-origin read fails as a
TypeError, which never reaches this path), one that answers 204, and one that answers JSON.Tests
edgeAuthChallenge.test.ts— 29 cases: the three detection signals, the two outcomes, the shapes the gateway's own 401 takes, and that no navigation API is touched for any body, including one naming a same-origin route. Its central guard is structural — a page offering a way in and a page offering none must reach the same outcome, so any reader of the far side's markup fails it.withOriginLink.test.tsx— 17 cases: the address links, the surrounding words survive so the remedy still reads as a sentence, andtarget/relare both pinned. The safety half is pinned as hard as the affordance: a URL from a response body, a longer address merely starting with the origin, and an opaque-origin document each render no link. One case per wired surface, because the helper being right says nothing about where it is called — six of the seven sites were wired and unpinned until mutation controls caught it.toApiErrorChallenge.test.ts— the app-bundle factory sees the same refusal, and the gateway's own HTML denial page is never mistaken for an interposed one.queryClientRetry.test.ts— the retry stop fires for an interposed refusal and does not fire for the gateway's own lapse, whose silent refresh depends on that retry.authExpiredErrorCopy.test.ts— the copy and the flags, routed through the real failure path rather than a hand-builtApiError.node scripts/capture-error-card-proxy-challenge.mjsexits 0 and asserts every episode it captures, in both themes.Frames
Produced by
node scripts/capture-error-card-proxy-challenge.mjs, which exits 0 andasserts every episode it captures. Each card renders as production renders it: the
pre-fix bare status is retryable, the two proxy states are not, and the gateway string
offers its own sign-in route.
Every string is also written as TEXT beside the frames, by the same run, at
temp-screenshots/error-card-proxy-challenge/error-card-proxy-challenge.md. A PNG addedby a patch is a binary blob to any reviewer who cannot fetch it; that file carries the two
new strings verbatim, records the anchor's
href,targetandrel, and isreadable as a diff.
captureTranscriptParity.test.tsholds it to what the shippedcapture script can produce: every heading is one the script emits, every episode in the shared
list appears, and the quoted strings are the ones the catalogue ships.
Light:
Dark:
Pattern harvest
The shape this PR kept re-learning: a classifier built by enumerating spellings of a
thing, run against input an adversary or a stranger writes. The affordance scan asked
"does this page offer a way to sign in" by listing the words such a page tends to
contain. Every review round found one more page it read backwards, and every fix was one
more entry on the list — four rounds, four classes, converging on nothing. The scan is
now deleted, not narrowed, because the message it was choosing between did not need the
distinction.
Two narrower instances of the same error, both found and both now moot with the scanner
gone:
safeHttpUrlanswers is this URL safe to open and was used to answer is this away to sign in;
lower[j] === '='answers is there an equals sign here and was usedto answer is this an assignment. In each case the broader predicate is true far more
often than the narrower one, and every extra positive is a misclassification.
Rule candidate: review-prompt — when a classifier's accuracy rests on a hand-maintained
list of spellings read from untrusted input, require the caller to show that the two
branches lead somewhere genuinely different. If both branches end in the same
instruction, the classifier is unnecessary regardless of how accurate the list becomes.
Rule candidate: semgrep — a scanner that treats
=as assignment without excluding==,===and=>. Mechanically detectable and a recurring parsing bug.