0036 — Redirect an unknown OAuth client back to the server's own web app
Status: Accepted
Date: 2026-11-06
Amends: ADR-0025 (client storage no longer needs CHARTGEN_SCRIPTING=1)
Amended by: ADR-0044 (with sign-in on, a client’s liveness is limited per user, so the lockout costs accounts), ADR-0058 (an external client’s access token survives a restart, and a refresh token keeps its client from being evicted, for up to 30 days out of use)
Context and Problem Statement
Section titled “Context and Problem Statement”The web app keeps its client_id in localStorage. The server keeps clients
in memory unless CHARTGEN_SCRIPTING=1 persists them
(ADR-0025), and a deployment
without a volume forgets them on every redeploy.
After a redeploy a returning browser therefore navigates to /authorize with a
stale id and lands on a raw JSON page,
{"error":"invalid_client","error_description":"Unknown client_id"}. It is a
top-level navigation, so the app’s JavaScript never runs again and the user is
stuck until they clear localStorage by hand.
RFC 6749 section 4.1.2.1 says the authorization server must not automatically
redirect when the client is invalid: an unverified redirect_uri is what makes
an open redirector. Any recovery by redirect has to be a deliberate exception.
Decision Drivers
Section titled “Decision Drivers”- The app recovers with no user action, and share links survive it.
- The new redirect must add no open redirect.
/authorizealready follows anyredirect_uria registered client names, and registration is open and auto-approved, so this path must not reach anywhere that does not. - External MCP clients get no redirect, and keep their registration across a deploy.
- Script tools stay off unless
CHARTGEN_SCRIPTING=1. - Works whatever the persistence setup of the deployment is.
Considered Options
Section titled “Considered Options”Redirect to the server’s own origin only (chosen). The server tells the app through its own callback, under the conditions below.
Persist clients only. This removes the cause on a deployment with a volume, and we do it as well (below). Alone it does nothing for a deployment without a volume, and a browser can still hold an id the server has collected.
Client-side probe. fetch /authorize before navigating and re-register on
a 400. For a valid client this GET has a side effect: it issues an auth code
that is never used, on every sign-in.
Server-rendered error page. A page with a “Sign in again” link instead of
JSON. It needs the user to act and has to clear localStorage from a page that
is not the app, so it only makes the dead end look better.
Decision Outcome
Section titled “Decision Outcome”Chosen option: redirect to the server’s own origin only, because the target of the redirect is then fixed by server configuration and not by the requester, which is what the RFC’s rule protects against.
For an unknown client_id, GET /authorize answers 302 to redirect_uri with
error=invalid_client and the original state added to its query string when all
of these hold. In every other case it keeps the 400 JSON.
- The server serves the web app (
CHARTGEN_WEB_DIRis set). redirect_uriparses to exactly the origin (scheme, host, port) ofbase_url(). Origins are compared after parsing, never as string prefixes, sohttps://example.com.evil.comandhttps://example.com@evil.comfail.redirect_urihas no userinfo and no fragment.
base_url() is CHARTGEN_BASE_URL, falling back to http://localhost:<port>.
It never comes from the Host header or a forwarding header, so a client cannot
influence the origin it is compared with. The Location is the re-serialized
parsed URL, so a browser cannot read it differently from the check.
The web app acts on ?error=invalid_client only if state equals the pending
PKCE state in sessionStorage. It then clears the PKCE state, removes the
parameters from the URL and restarts the flow. A crafted link does not know the
state, so it cannot wipe the stored client: the app removes the parameters and
stops at Sign in again. It does not restart, because where sessionStorage
does not survive a navigation the state can never match and a restart would loop.
Tabs of one browser share localStorage but not sessionStorage, so the PKCE state
records the client_id that asked. The stored client is cleared only if it still
equals the rejected id, so a tab bounced late cannot remove the client another tab
has just registered. The code exchange uses the recorded id, because the stored one
may have changed since. Entries saved before this have no id and use the stored
client as before.
Registering and removing the stored client both take a Web Lock, re-checking the stored client inside it, so tabs that find it empty end up sharing one client instead of each registering. Without Web Locks, on an insecure origin or an old browser, tabs may each register. The last one stored wins and each tab keeps working as its own client, though with scripting on a script saved in a losing tab is not listed after a reload.
This counts as a failed redirect in the app’s existing one-retry guard. A second
failure in the tab stops at sign-in failed: <reason> with Sign in again,
which registers again because the client is already gone. Share parameters are
written to the stores before any redirect
(ADR-0029), so a share link
opened with a stale client still lands on its chart.
Persisting clients without scripting
Section titled “Persisting clients without scripting”External MCP clients cannot use the redirect, so they also need the cause
removed. In a build with the scripting cargo feature, the default, the HTTP
server now stores and restores registered clients in CHARTGEN_DB whether or not
CHARTGEN_SCRIPTING=1. ADR-0025 tied this to scripting because the client_id
owns scripts. A build without the feature has no store and keeps clients in
memory.
The env var still alone decides the script tools, in tools/list and in
dispatch, because turning it on just to keep clients would expose them. A separate
env var for client storage was rejected: it adds a switch with no use for off,
since a store that cannot be opened is already logged and not fatal.
Eviction at the client limit
Section titled “Eviction at the client limit”Persisting clients would make the 1000 client limit permanent: clients that
received a token are never collected, and sign-in is auto-approved. A restart used
to empty the table; now a full table would leave /register at 503 for good.
So when the table is full, /register evicts where it can, from memory and from
the store:
- A client with a live token is never evicted. A stranger must not be able to end a session in use.
- A client that owns stored scripts is never evicted, whether or not
CHARTGEN_SCRIPTING=1is set now, because theclient_idis the owner’s only identity. - Of the rest, clients that never received a token go first, oldest registration
first, then the client longest out of use. Last use is an in-memory field, set
when a token is issued and on each authenticated call, with no store write per
request. After a restart it starts from
last_token_at. - If nothing is left, or the owners cannot be read,
/registeranswers503and evicts nobody.
The owners are read from the store before taking the OAuth lock, because every authenticated call needs that lock and the store may be busy. A client’s first script can land after the read, but writing one takes a live token, so that client is not evictable anyway unless the token expires in that moment.
Eviction drops the client’s pending codes, so a code cannot mint a token for a client on no record. An evicted client recovers as after a restart without a volume: the web app through the redirect above, an MCP client by registering again.
Rejected:
- Evict by oldest token and revoke it. The first version did this. A client working daily on a 6-day-old token was first in line, and a stranger repeating register, authorize and token emptied the table of everyone else’s sessions: 1000 rounds took 1.7 s on a loopback peer.
- Always refuse with
503. Then every full table needs an operator, even one filled by ordinary use with idle clients. With eviction, only a deliberate lockout does. - Expiry by age alone. It would not stop the table filling quickly, and would drop idle clients even when there is room.
Consequences
Section titled “Consequences”- Good: redeploys no longer strand browsers, with or without a volume.
- Good: with a volume, external MCP clients keep their
client_idacross a deploy. They re-authorize, because tokens stay in memory. - Good: nobody can lose a session in use to a stranger. A client with a live token sees no change, however full the table gets.
- Good: registration keeps working at the limit while any client is evictable.
- Bad: anyone scripting the flow can push out every client with no live token. That
means clients idle past the 7-day token lifetime, and right after a restart every
client that has not signed in again, because tokens are memory-only. The rate limit
does not bound this in general: loopback peers are exempt, so a same-host reverse
proxy has no limit, and the limit is per address, so many addresses get around it.
Those clients must sign in again, and an MCP client gets a new
client_id. No scripts are lost, because their owners are spared. - Bad: this does not stop a deliberate lockout. Someone holding 1000 live tokens gets
503for all new registrations, and it lasts until an operator acts. Tokens expire after 7 days and a restart drops them, but the clients persist, and/authorizeand/tokenissue new tokens with no/registerand no rate limit: re-tokening 999 clients after a restart took 1.6 s on a loopback peer. Clients already registered keep working. New browsers, browsers recovering from a stale client and new MCP clients cannot sign in. Refusals are logged at most once a minute, and the recovery deletes every client that owns no scripts. While registration is open and auto-approved, the server cannot tell a stranger’s client from a user’s. Requiring approval or authentication at registration is the real alternative, and a separate project. - Bad: at the limit, a client that just registered is the first to go until it has a token, so a concurrent registration can evict it mid sign-in. It then recovers like any other evicted client. Registrations without a token can evict at most one other client this way, since each evicts the previous one.
- Bad: 1000 clients that own scripts still leave
/registerat503. Script tools are off by default, so this needs scripting turned on. - Neutral: every default
--servenow creates~/.chartgen/chartgen.db. - Good: external MCP clients with their own redirect URIs, and API-only servers,
still get the
400. - Bad: a deliberate deviation from RFC 6749 section 4.1.2.1. Anyone can make
/authorizeredirect to a path on the server’s own origin, with these two parameters added. No other origin can be reached this way, and the app does nothing with astateit did not issue beyond stopping at Sign in again. A crafted link can therefore show that screen to someone who follows it. - Bad: each recovery registers a client. Unused ones are collected after 24 hours and registration is rate-limited as before.
- Neutral: the recovery needs
CHARTGEN_BASE_URLto match the origin the app is served from. If it does not, sign-in is broken already, because the discovery document points elsewhere. The Vite dev server is such a case: its origin is not the server’s, so a stale client there still gets the400.