Skip to content

fix(api): name an interposed proxy's auth challenge instead of failing silently - #9898

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
rnoack1:fix/recover-from-edge-auth-challenge
Sep 26, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
rnoack1:fix/recover-from-edge-auth-challenge

Conversation

@rnoack1

@rnoack1 rnoack1 commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

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 /api polls too, which is where the failure becomes invisible.

Measured against a real proxy:

HTTP/2 403
content-type: text/html; charset=UTF-8

<!DOCTYPE html>…<h1>Access Required</h1><p>… <a href="…?redirect=…">Sign in</a> …

There is no Location to follow, and no gateway header travels on the response because the request never reached the gateway. So checkSessionExpired, which keys on the gateway's own X-Auth-Required header in api/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.ts recognises 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 own X-Auth-Required header is present, because that header proves the request reached the gateway and so nothing interposed answered it.

Two outcomes, not three. ChallengeOutcome is 'challenged' | 'framed'. framed is 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/jane as a sign-in link, /oauth2/start as not one, a form-rendered gate as a block, and a geo-block page's visible Location = US text 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 authRequired and a narrower edgeChallenge flag on the ApiError, and retryPolicy keys the stop on the narrower one. The gateway's own X-Auth-Required 403 is deliberately excluded: there attemptSilentRefresh plus the one retry is what recovers a slept-laptop cookie invisibly, and a successful refresh invalidates only ['auth-me'] while staleTime is Infinity.

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.tsx additionally renders it as a target="_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 sets 13px with overflowWrap: 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: addressNamedByMessage answers 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-*.mjs pattern.

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, and target/rel are 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-built ApiError.
  • node scripts/capture-error-card-proxy-challenge.mjs exits 0 and asserts every episode it captures, in both themes.

Frames

Produced by node scripts/capture-error-card-proxy-challenge.mjs, which exits 0 and
asserts 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 added
by 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, target and rel, and is
readable as a diff. captureTranscriptParity.test.ts holds it to what the shipped
capture 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:

error card, proxy challenge, light theme

Dark:

error card, proxy challenge, dark theme

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: safeHttpUrl answers is this URL safe to open and was used to answer is this a
way to sign in
; lower[j] === '=' answers is there an equals sign here and was used
to 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.

@rnoack1
rnoack1 requested review from a team and smeyffret September 10, 2026 11:36
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 10, 2026
@github-actions

github-actions Bot commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — 🟡 CONCERNS

Design-level review of 70213769d9ea70d8be884f5459a666f509ec68f6 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

Description claims captureTranscriptParity.test.ts guards the committed transcript, but that test exists nowhere — the parity guarantee is phantom.

Watch

  • The description's Frames section says "captureTranscriptParity.test.ts holds it to what the shipped capture 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" — no such file is in the diff, and it does not exist in the base tree. A reviewer trusting the committed temp-screenshots/...md transcript relies on a pin that isn't there, so the transcript can drift from what capture-error-card-proxy-challenge.mjs actually emits (or from the shipped catalog strings) with nothing going red.
    Clears when: the test is added to the PR, or the claim is removed from the description and the transcript is treated as run output only.

Suggestions

  • The description quotes the unframed message as "check its logs" while the shipped string (and the test that pins it) says "check the proxy's logs" — update the description so it quotes what ships.

[DESIGN-REVIEWED] 7021376

@github-actions

github-actions Bot commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — 🟡 CONCERNS

Premise-level review of 70213769d9ea70d8be884f5459a666f509ec68f6 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

  • Item 6 — symptom-level: the root cause is app modules hand-rolling error factories that fall back to message = text || …; the diff fixes md-notebook ("Recognition is delegated rather than re-spelled") but grep for that fallback counts 2 unfixed siblings, website/src/apps/crew-companion/api.ts:30 and website/src/apps/project-scaffolder/api.ts:95, where the same challenge renders as <!DOCTYPE html>… — the pre-fix: stop rendering an HTML error page as the error message #9484 defect.
    Subtraction: replace those two factories' raw-text fallback with the existing shared toApiError / noteEdgeAuthChallenge path this change already built.
    Clears when: both factories route the refusal through the shared detection, or the (truncated) description names them as counted, deferred siblings.

What this change ships

Inventory (8 items) — 6 justified

Intent: 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.

  1. A proxy refusal now shows an actionable conditional message instead of a bare HTTP 403 (two strings, 13 locale files) — justified
  2. Background retries stop on that refusal; the gateway's own 403 keeps the retry its silent refresh rides on — justified
  3. The gateway sign-in banner/token flow is no longer offered for a proxy refusal — justified
  4. A theme-catalog failure behind a proxy surfaces a notice instead of silently replaying — justified
  5. Six sites that hand-built errors (exports, dev-fleet, artifact publish/act) now route through the shared factory — justified
  6. md-notebook throws the shared error so its retries stop too; crew-companion and project-scaffolder factories still paste the raw page — symptom-level (point patch, 2 counted siblings)
  7. The framed-pane message's origin renders as a clickable link on all seven error surfaces (withOriginLink + provenance map) — rides along (declared; harm named mechanically: 13px anywhere-wrap breaks the URL a locked-out framed reader must retype)
  8. Capture harness plus committed screenshots/transcript — rides along (matches the 631-script capture-*.mjs / committed temp-screenshots/ convention)

[FIRST-PRINCIPLES-REVIEWED] 7021376

@github-actions

github-actions Bot commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5, fork) — 🟡 CONCERNS

UX-level review of 70213769d9ea70d8be884f5459a666f509ec68f6 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

  • Comprehension of the conditional structure is unverified: both new strings ask the reader to run an experiment and self-diagnose from its result (proxy_challenge_reload, en.manual.json). A blind read on a same-repo branch would settle whether a first-time reader follows it; until then this is stochastic risk, hit on every proxy lapse.
  • Framed string ends "then reload this page" — a pane has no reload control of its own, so the referent (panel vs outer dashboard tab) is ambiguous at exactly the moment the reader is locked out; same ambiguity class the author already fixed for "open this page". Low frequency (embedded panes only), persistent.

Suggestions

  • The challenged card's leading instruction ("Reload this browser tab") could be a button, as the framed card's address is a link — a user-clicked location.reload() is not the auto-navigation the PR deliberately dropped. Component: ErrorCard when edgeChallenge.
  • Framed string: replace "then reload this page" with wording that names the surface, e.g. "then reload the dashboard" (api.client.proxy_challenge_framed).

[UX-REVIEWED] 7021376

@github-actions

github-actions Bot commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed 70213769d9ea70d8be884f5459a666f509ec68f6 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 7021376

@github-actions

github-actions Bot commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed 70213769d9ea70d8be884f5459a666f509ec68f6 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 7021376

@rnoack1
rnoack1 force-pushed the fix/recover-from-edge-auth-challenge branch 3 times, most recently from bfc36f9 to caf7961 Compare September 10, 2026 15:28
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 10, 2026
@rnoack1
rnoack1 force-pushed the fix/recover-from-edge-auth-challenge branch 2 times, most recently from b997c27 to e721da6 Compare September 10, 2026 18:30
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 10, 2026
@rnoack1
rnoack1 force-pushed the fix/recover-from-edge-auth-challenge branch 3 times, most recently from 108244c to 56b57f9 Compare September 11, 2026 00:46
@rnoack1
rnoack1 force-pushed the fix/recover-from-edge-auth-challenge branch from 5a9ad13 to fbff583 Compare September 11, 2026 11:41
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 11, 2026
@rnoack1
rnoack1 force-pushed the fix/recover-from-edge-auth-challenge branch 2 times, most recently from 82e2385 to d0a99ca Compare September 11, 2026 14:23
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 11, 2026
@rnoack1
rnoack1 force-pushed the fix/recover-from-edge-auth-challenge branch from d0a99ca to b70e07c Compare September 11, 2026 20:31
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Sep 11, 2026
@rnoack1
rnoack1 force-pushed the fix/recover-from-edge-auth-challenge branch from b70e07c to 8b1ea88 Compare September 11, 2026 23:04
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 11, 2026
@rnoack1
rnoack1 force-pushed the fix/recover-from-edge-auth-challenge branch 3 times, most recently from 065e53c to f5cf063 Compare September 12, 2026 04:35
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Sep 12, 2026
@dwu96

dwu96 commented Sep 12, 2026

Copy link
Copy Markdown
Contributor

👋 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:

  • ## Problem / Motivation
  • ## Why it matters
  • ## What changed
  • ## Tests

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.

@github-actions

Copy link
Copy Markdown
Contributor

Security Scope Review (fork) — 🔴 BLOCK (blocking)

Which legitimate operations does 53d327cf71d46a853732e374f947344405fe64fd newly refuse? Model proposes, scripts/deny_diff.py decides — updated in place on each push. A script-confirmed regression blocks PR readiness.

no leg reported, and this was not the nothing-to-adjudicate short circuit

No [SCOPE-REVIEWED] marker for this head was produced, so the model's text is withheld: it cannot be shown to describe this revision. See the job logs.

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants