38 KiB
Q175 design: the Console verifies SSO itself (Vikunja #412)
Author Sage, 2026-10-20, r3. Reviewer Filbert, and the review comes before any code. Line numbers are at
refactor 4ca8d6e94 unless a line says otherwise. This replaces Part B (row 178 proxy proof, #385 comments 345
and 353). #385 stays open until the Console stops trusting X-authentik-username.
Changes from r2 (Filbert's r2 review, CHANGES)
- C1: the
consolekey goes into the shared loader, scripts/mosaic-config.mjs, which today refuses any unknown top-level key (:113). Section 4 names the blast radius. Jason step 4 moves inside the phase 2 window, after the pin and before the Console starts. The phase 2 rollback removesconsolefirst. A test-config.sh case covers it (test 25). Mos confirms the sequence before phase 1 (section 5). - C2: under
--ssothe page treats a 401sign-in requiredas signed out and links to/auth/login?return=<path>(section 5 phase 1, test 24). - Notes: tests 7 and 15 are built so that only the record rule refuses; test 9a is an alg test; Q-B's two
classes are defined, and test 23 adds a 200 HTML page; the phase 2 scratch Console uses a scratch config,
a dummy slot, no
--sendand no--tester-port. - r3 fix (Filbert r3 approve): D1, the loader checks the slot reference's shape only, and the file checks
run in the Console's
--ssostart; D2, the slot resolves from the config dir, and the scratch Console has a scratch dataRoot and an unreachable issuer (section 5). - Q-E: settled as Filbert ruled. The
subject-unknownline keeps iss and sub, JSON-escaped and capped (section 1, tests 10 and 19).
Changes from r1 (Filbert's r1 review, CHANGES)
- B1: the provider config moves to
~/.config/mosaic-dev/config.json(section 4). Mos agreed (mos-0973). The Console prints provider ids, issuers and subject counts at start. The rehearse-strip follow-up is dropped. - B2: one return-path rule,
new URL(ret, publicOrigin).origin === publicOrigin(section 1 step 7), with tests for/\evil.exampleand/%09/evil.example. - B3: refusals log a fixed code and the provider id, never the error or its cause (section 1).
- B4: login records are capped at 32 (section 1 step 1), with a test.
- B5: test 9 splits into a forged payload under a real kid and a kid missing from the JWKS, and a try/catch mutant joins the list. Test 2 no longer claims the signature mutant (section 9).
- B6: the phase 2 forged-header check runs on a scratch Console, or Mos or Jason runs it on live (section 5).
- Rulings: Q-B start degraded (section 4), Q-C only the public Host on 7332 (section 3), Q-D keep 1 h idle but polls don't count as activity (section 3).
- Section 6:
startServerthrows ontester && sso, andhumanjoinstesteras a refused subject label. - The missing tests and nits N1-N5 are in sections 1, 3, 7 and 9.
- Section 8: the human-cli statement stays as written (mos-0972). The recommendation is now Mos's ruling.
The ruling this implements
Jason, DECISIONS Q175, verbatim: "Q1: yes. This should be a requirement for SSO usage. Whether we are using Pocket ID, Authentik, WorkOS, or another provider (we should support multiple), the system should use best practices for jwt or other methods of validation that do not rely on hacks to pass the auth." He added "Zero trust with verification" and confirmed five points (mos-0970):
- The stack verifies every SSO login itself. It never takes identity from a proxy header or a shared secret.
- The Console is an OIDC relying party: discovery from the issuer URL, authorization code with PKCE, the ID token checked against the provider JWKS (signature, iss, aud, exp, nonce), then its own session cookie.
- Several providers can be configured side by side.
- Only asymmetric signing counts. HS256 is refused.
- A proxy-forwarded token such as
X-authentik-jwtcounts only through the same checks. It is optional and never the only way in.
What exists today
The live Console runs from copies/490e2771d3d0 with --public-host mosaic.woltje.com --auth-header X-authentik-username --allow-user jason.woltje --send --tester-port 7333. Row 189 (#1687, P19 #413) adds
stack-release.sh activate --no-send, and Mos's ruling mos-0972 takes --send off the live Console until
phase 2.
previewOptions(packages/webui/src/serve.mjs:205) builds{ host, header, user }.- A request is
namedwhen its Host equals the public name (:493). A named request passes sign-in when it carries exactly one auth header value equal to the user (:517-521). That header value is the whole identity. - Requests with a loopback Host on 7332 get the unauthenticated read path (:509-512). Writes need
named(:526-546). proofOptions(:217) is the row 178 shared-secret header. Q175 point 1 rules it out, so it retires with the auth header.- The tester listener (
--tester-port, row 176) binds 127.0.0.1. Its writer is fixed as{ tester: true, user: 'tester' }(:522), it allows only the instance, route, name and chat writes (:523), and it refuses the auth and proof headers (:486-487). 7332 refusesx-mosaic-tester(:485). - The public path is Traefik, then the Authentik proxy outpost (provider mosaic-preview, HS256, empty JWKS),
then chisel
R:0.0.0.0:7332:127.0.0.1:7332, then the Console. Every public request reaches the Console from 127.0.0.1 with whatever Host the outpost forwards.
Design
1. The Console becomes an OIDC relying party
New module packages/webui/src/sso.mjs, used only by the human listener (7332). Routes:
| Route | Method | What it does |
|---|---|---|
/auth/login |
GET | One provider configured: start its flow. Several: a plain page listing them, each a link to /auth/login?provider=ID. A provider whose discovery hasn't succeeded gets 503 (section 4). |
/auth/callback |
GET | Finish the flow, create the session, 303 to the saved return path. |
/auth/logout |
POST | Same-origin checks, delete the session, 303 to the provider's end_session_endpoint. |
/auth/signed-out |
GET | Static "signed out" page with a sign-in link. |
Every URL the Console hands a provider is built from the configured publicOrigin: redirect_uri is
publicOrigin + '/auth/callback' and post_logout_redirect_uri is publicOrigin + '/auth/signed-out'. No
code path reads the request's Host to build them (N2).
The flow per provider:
- Start. Generate a state, a nonce and a PKCE verifier (
generateRandomState,generateRandomNonce,generateRandomCodeVerifier), and a challenge withcalculatePKCECodeChallenge(S256 only). Put them, the provider id, the return path and an expiry 10 minutes out in a server-side login record keyed by a random id. The store holds at most 32 login records; a new one evicts the oldest (B4). Set__Host-mosaic_loginto that id. 303 toauthorization_endpointwithresponse_type=code,scope=openid profile email,code_challenge_method=S256,redirect_uri,stateandnonce. - Callback. Read exactly one
__Host-mosaic_logincookie, then take and delete its record (single use, so a replayed callback finds nothing). Expire the cookie in the response. The provider comes from the record, never from the query, which stops a mix-up between providers. Two tabs signing in at once each set the cookie, so the later one wins and the earlier tab's callback finds no record and gets the 403 page with a sign-in link (N5). That costs one retry and keeps one cookie per browser. validateAuthResponse(as, client, url, record.state)checks state, refuses an error response, and checks theissparameter when the provider advertises RFC 9207.authorizationCodeGrantRequest(as, client, clientAuth, params, redirectUri, record.verifier)returns aResponse. Keep that object.processAuthorizationCodeResponse(as, client, response, { expectedNonce: record.nonce, requireIdToken: true })checks iss, aud (and azp when aud has several values), exp, iat and nonce, and checksalgagainstclient.id_token_signed_response_alg. That field gets the provider's wholealgsarray, which the library'scheckSigningAlgorithmaccepts, so a provider listing RS256 and ES256 takes either and nothing else (N1). Test 16 pins this.- Signature. oauth4webapi does not verify the signature of an ID token that came straight from the token
endpoint over TLS (OIDC Core 3.1.3.7 allows that, and the library docs for
validateApplicationLevelSignaturesay so). Point 2 asks for the JWKS check, so the callback always callsvalidateApplicationLevelSignature(as, response)with the sameResponseobject from step 4. It fetches the JWKS from the discoveredjwks_uri, picks the key bykty,kid,alganduse, and refuses HS* outright. On akidit doesn't have, it refetches the JWKS once if the cache is at least 60 s old, which covers key rotation (test 18). The call is not wrapped in a catch that continues; its throw ends the callback. - Our own checks on top of the library:
header.algis in the provider'salgs, the token'sissequals the configured issuer as a raw string compare, with no URL normalising (N3; the library's discovery check compares normalised hrefs, so this one is stricter), and(iss, sub)is in the provider'ssubjectslist. - Create the session (section 3), then 303 to the return path. The rule (B2): resolve
u = new URL(ret, publicOrigin), and useu.pathname + u.searchonly whenu.origin === publicOrigin; otherwise use/. A missing or unparsableretgives/.
Every refusal in steps 2-6 ends at a 403 page saying sign-in failed, with a link back to /auth/login. No
step falls back to a header.
Logging (B3). A refusal logs one line: a fixed code from a closed list (login-record-missing,
state-mismatch, auth-error-response, grant-failed, id-token-invalid, signature-invalid,
alg-refused, issuer-mismatch, subject-unknown, discovery-failed, jwks-failed) and the provider id.
It never logs the exception, its message or its cause. oauth4webapi's errors carry token bodies and claims
in cause, so even a message can leak. The one extra field is on subject-unknown: it logs iss and sub,
because Jason step 3 reads his sub from that line (Q-E, Filbert's ruling). Authentik's default subject mode
is a hashed user id that its admin view doesn't show, so the line is the practical source. Neither value is a
credential. Three conditions hold:
- Only a token that passed steps 3-6 up to the subject check reaches this line. Every earlier refusal logs its own code and the provider id only.
- Both values are written with
JSON.stringifyand each is cut to 255 characters first. Any account at the provider can get a signed token, so asubmay hold a newline, and an unescaped one would let a sign-in forge a log line. - Test 10 uses a
subholding\nand a fakerefused sign-insuffix and asserts one escaped line.
Test 19 asserts that no log line holds a token, code, state, nonce, verifier, client secret or session id.
It exempts only the iss and sub fields of the subject-unknown line.
2. Library: oauth4webapi 3.8.8, pinned exactly
Mos's steer (mos-0971) was to prefer oauth4webapi over hand-rolled verification on node:crypto unless I
could name a defect or a dependency cost that outweighs it. I found neither.
- MIT, no dependencies, one ESM file (build/index.js, 99,856 bytes). Tarball sha256
bac088aecc7c..., integritysha512-8N28E+a/oxfXW...(the full values go in package-lock.json). supported()covers PS/ES/RS 256/384/512, Ed25519/EdDSA and ML-DSA. No HS*. RSA keys under 2048 bits are refused.- It does discovery with an issuer equality check (
processDiscoveryResponse(expectedIssuer, ...)), PKCE, state, the RFC 9207issparameter, nonce, and JWKS caching. - The one gap is the default skip of the token-endpoint signature check (section 1 step 5). Calling one exported function closes it, so it isn't a reason to hand-roll.
Hand-rolling would mean writing JOSE parsing, JWK import, key selection by kid, the claim checks and the
discovery checks ourselves, with the same tests and more places to get it wrong.
Pin: "oauth4webapi": "3.8.8" in the root package.json dependencies, next to the pi pin, with the lockfile
entry. Root is right because scripts/stack-copy.sh:23-31 copies only the root package.json and lock and runs
npm ci there (:55-56). packages/webui/src resolves the import from the copy's root node_modules. This is the
webui's first runtime dependency. The root dependency rule (exact pins, never unversioned) applies to it.
Upgrades are reviewed commits.
3. Sessions, cookies, Host and logout
- Session id: 32 random bytes, base64url. The store keys on its sha256 and holds no raw id, so a heap dump doesn't hold usable ids. Test 20 checks that the store's keys and values never contain the cookie value.
- Cookie, exactly:
__Host-mosaic_session=<id>; Path=/; Secure; HttpOnly; SameSite=Lax, no Domain, no Max-Age (a browser-session cookie). The__Host-prefix makes the browser refuse it unless it was set over https on this exact host. Test 21 asserts the whole Set-Cookie value, and a mutant dropsHttpOnly. - Login cookie
__Host-mosaic_login, the same attributes plusMax-Age=600. The login record also expires at 10 minutes server-side. - Lax, not Strict, because the callback is a top-level navigation from the provider's site, and a Strict
cookie set there would be missing on the redirect to
/. Lax still keeps the session off cross-site POSTs. The write routes keep their exactOriginandSec-Fetch-Site: same-originchecks (:171, :250, :297, :340, :387, :425), so cross-site writes are refused twice. - Lifetime: 8 h absolute, 1 h idle, both server-side (Q-D, Filbert's ruling). The store is in memory with a cap of 64 sessions (oldest goes first), so a Console restart signs everyone out. That's acceptable for one human and keeps sessions off disk.
- Activity (Q-D). Only a page load (a GET outside
/api/) or a write (a POST) refreshesseen. The page's background reads don't:refreshre-reads the board every 10 s (packages/webui/src/public/app.js:346) and the 5 s timer at :301 redraws the age label. Without this rule an open tab would never go idle. Test 13 covers it. - The session holds
{ provider, iss, sub, name, idToken, created, seen }.nameis the subject entry's label. It goes wherepreview.usergoes today (send logs, settings, seat routes), so the downstream writer shape stays as it is.idTokenis kept only as the logout hint and never leaves the server. - Host (Q-C, Filbert's ruling). Under
--sso, 7332 serves only requests whose Host is the public host. Any other Host, loopback included, gets 403public Host required, exceptGET /healthz. The loopback read path at :509-512 is gone under--sso. Today's readers of 127.0.0.1:7332 and where they go:scripts/webui-service.sh status(:406), the stack-release gate (scripts/stack-release.sh:484) and the rehearse gate (:1369) read only/healthz, which stays open on loopback.- The webui README (:83) describes the loopback path. It changes in phase 1.
- Agent reads of the board go to the tester listener on 7333, which already serves reads. I found no other
code that reads 7332 on loopback. A person opening http://127.0.0.1:7332 in a local browser gets the 403
and uses the public URL instead.
Test 22 covers a loopback Host on
/,/api/boardand a write, and/healthzpassing.
- Every request on 7332 except
/healthzand/auth/*needs a valid session. Without one,/api/*gets 401 JSON and other GETs get a 303 to/auth/login?return=<path>. - Logout:
POST /auth/logoutwith the same-origin checks. It deletes the session, expires the cookie, and 303s toend_session_endpoint?id_token_hint=...&post_logout_redirect_uri=<publicOrigin>/auth/signed-out&client_id=.... If the provider has noend_session_endpoint, it goes straight to/auth/signed-out. - Limit: signing out at the provider does not end a Console session until idle or absolute expiry. Back-channel logout is a follow-up, not phase 1.
4. Provider config: shape and location
Location (B1, Filbert's ruling, Mos agreed in mos-0973): a console.sso key in
~/.config/mosaic-dev/config.json. The reason is who can write it. The business file is writable by agents
through organizationWriter (the tester verbs and the chief's organization.set), so a provider entry there
could be changed by the agents the Console is meant to keep out. config.json is user-authored and never
auto-written: scripts/bootstrap.sh creates it and nothing overwrites it. Adding the key is a Jason step
(section 10).
The loader (C1). Every tool reads config.json through one loader, scripts/mosaic-config.mjs. Its validate
refuses any top-level key other than configVersion, environment, dataRoot and execution with
unsupported configuration key (:113). The business, seat, cli, discord, bootstrap, land-work, stack-copy and
conductor-apply code all use it. So phase 1 changes the shared loader, not a Console-only reader:
- mosaic-config.mjs accepts an optional
consolekey, and the strictconsole.ssoshape validator (the config checks below, except the slot file checks) runs inside the loader. The fail-closed canon holds for every reader. The loader checks shape only and never touches a slot file:clientSecretmust be{ slot: <name> }with the name matching[a-z0-9-]{1,64}. The file checks and the read run only in the Console's--ssostart (D1), so a missing slot or a 0640 slot stops the Console, not the stack. - The blast radius is the whole stack. A typo in
console.ssomakes every tool refuse the config, not just the Console. That's the price of one loader, and the reason step 4 writes the key inside a window with a backup first. - The other direction breaks too. A copy older than phase 1 refuses a config that has the key. If the key
went in before the phase 2 pin, the live copy (
490e2771d3or later) would refuse its own config on the next read, and the bus, seats and host would stop. After phase 2, a rollback to a pre-phase-1 copy fails the same way until the key is removed. This is the same trap as the plug-in kind before a rollback. - Files without the key still load, on old and new copies.
Test 25 in scripts/test-config.sh: a config with a valid console.sso loads, a malformed one fails with
the bad key path named, and a config without console loads.
No secret value goes in this file. The client secret is a slot reference.
"console": {
"sso": {
"publicOrigin": "https://mosaic.woltje.com",
"providers": [
{
"id": "authentik",
"issuer": "https://auth.diversecanvas.com/application/o/mosaic-stack/",
"clientId": "<from Jason>",
"clientSecret": { "slot": "console-sso-authentik" },
"algs": ["RS256"],
"subjects": [ { "sub": "<from Jason>", "name": "jason.woltje" } ]
}
]
}
}
At start, --sso prints one line per provider: its id, its issuer and the number of subjects. No client id
value beyond that, no secret, no sub.
The slot is <configDir>/secrets/mosaic-stack/<slot>, where configDir is the directory of the config file
the loader read (MOSAIC_CONFIG, default ~/.config/mosaic-dev), so a scratch config gets a scratch slot
(D2). The Console's --sso start reads it. The Console refuses to start if
the file is a symlink, isn't a regular file, isn't owned by the Console's uid, has any group or other mode
bits (0640 refuses as well as 0644), or resolves under the repo or a stack copy. The value is never logged or
put in a refusal message.
stack-release.sh rehearse starts its Console with serve --port N --business B and no --sso, so a
rehearsed Console never reads console.sso and never uses the live redirect URI. No rehearse change is
needed; r1's follow-up is dropped.
Config checks, run at start without the network. Any failure refuses the start, and the message names the provider and the check:
publicOriginis an https origin with no path, query or fragment.- Provider ids are unique and
[a-z0-9-]{1,32}. issueris https with no query or fragment.algsis non-empty and holds only asymmetric algs from the library's list.HS256, anyHS*andnonerefuse.subjectsis non-empty, eachsubis 1..255 visible characters, and nonameistesterorhuman.clientSecretis{ slot: <name> }with the name matching[a-z0-9-]{1,64}(shape only, in the loader).- In the Console's
--ssostart only, the slot file passes the file checks above.
Discovery checks, run per provider when its discovery succeeds:
- Discovery returns
issuerexactly. id_token_signing_alg_values_supportedshares at least one alg withalgs. mosaic-preview advertises HS256 only, so it fails here.code_challenge_methods_supportedincludesS256.jwks_urireturns at least one key usable for one ofalgs. The empty mosaic-preview JWKS fails here too.
Unreachable provider (Q-B, Filbert's ruling). Config errors still refuse the start. Each fetch of the discovery document or the JWKS lands in one of two classes:
- Unreachable: a network error, a timeout, a status other than 200, or a body that doesn't parse as JSON. An Authentik maintenance page served as 200 HTML is unreachable, not refused, so it can't block a restart.
- Refused: a JSON document that fails the issuer, alg, S256 or JWKS check.
An unreachable provider doesn't stop the Console. It starts, that provider's /auth/login gets 503
sign-in unavailable, and a retry runs with backoff (5 s, doubling, capped at 5 minutes). /healthz stays
200 and adds sso: { <id>: "ready" | "unreachable" | "refused" }, so the gates still pass and an operator
can see the state. A refused provider at start refuses the start, because it's a configuration problem. On a
later retry it stays disabled with the discovery-failed code until a restart. Sessions already made keep
working while a provider is unreachable, since a session check needs no network. Test 23 covers the degraded
start, a 200 HTML page, and the recovery.
Several providers: Pocket ID, WorkOS and other compliant OPs use the same entry shape. The login page lists them. Each entry has its own issuer, client, algs and subjects, and a session records which provider made it.
5. Retiring --auth-header, --allow-user and the proof header
-
Phase 1 (code row). Add
--ssotocli.mjs serveandwebui-service.sh. It readsconsole.ssofrom config.json.--ssocannot be combined with--auth-header,--allow-useror--proof-*. Under--sso,namedmeans "has a session", andwritercomes from the session.--sendneeds--ssoor the old preview set. Phase 1 also carries the loader change and its test-config.sh case (section 4, test 25). Nothing live changes until the re-pin.The page (C2). Today app.js signs out only on
res.type === 'opaqueredirect'(packages/webui/src/public/ app.js:111 and :305), which is the outpost's redirect. Under--ssothe Console answers an/api/*request without a session with 401sign-in required, so the page would show an error on every 10 s refresh and never offer a way back. Phase 1 makes both fetch paths treat a 401 whose body haserror: 'sign-in required'as signed out, and the signed-out notice links to/auth/login?return=<current path and query>. Other 401s stay errors. The opaqueredirect branch stays until phase 3, because the preview flags still run behind the outpost until then. Test 24 covers it.Before phase 1 starts, Mos confirms the config.json sequence in phase 2 (C1).
-
Phase 2 (Jason-gated window). Re-pin to the phase 1 commit with
--sso --send --tester-port 7333instead of the preview flags, after Jason steps 1 to 3. Backup first, STATE after (Q173). The order inside the window:- Back up the store, the pointer, the unit and config.json.
- Pin the phase 1 copy with the Console stopped. The copy's loader accepts a config with or without
console, so the bus and seats keep reading the old config. - Straggler check (Mos's C1 condition, mos-0977): list every running process, unit and timer that still runs from the old copy and reads config.json. Each one is restarted on the new copy or shown not to re-read config. The old loader refuses the key, so a straggler would fail on its next read. Step 4 waits until the list is clean.
- Jason step 4: the
console.ssokey goes into config.json, written by Jason or by an agent on his go for that one key. The new loader reads it back (scripts/mosaic-config.mjsvalidate) before anything starts. - Start the Console with
--sso --send --tester-port 7333. Acceptance: Jason signs in through the Console flow, sends one message and signs out. The forged-header check (a request withX-authentik-usernameand no cookie gets 401) runs either on a scratch Console or on live by Mos or Jason (B6). No agent sends the auth header to the live 7332 (section 8). The scratch Console runs from the same copy asserve --sso --port <scratch port>, withMOSAIC_CONFIGpointing at a scratch config in a scratch dir. That config has a scratchdataRoot, and any business it serves comes from the scratch config dir; neither points at live. Its dummy client secret sits in the scratch slot (<scratch configDir>/secrets/mosaic-stack/<slot>). Its issuer is an unreachable loopback host, not Authentik, so the scratch Console sends nothing outbound (D2, mos-0971). It comes up in the degraded state (Q-B), and the 401 check needs no sign-in. It has no--sendand no--tester-port.
Rollback for phase 2: remove the
consolekey from config.json first (restore the step 1 backup), then roll the pointer back. An older copy's loader refuses a config holding the key (section 4), so the other order stops the bus and seats. The window plan lists that order, and the STATE check after a rollback reads config.json for the key's absence. -
Phase 3 (code row). Remove
previewOptions,proofOptionsand their tests.cli.mjsandwebui-service.shrefuse the old flags with--auth-header was retired by Q175; use --sso. Close #385 with the phase 2 STATE and the phase 3 commit.
The Authentik proxy outpost can stay in front. It still sends X-authentik-* headers, and the Console never
reads them. A test proves that a request carrying them gets nothing without a session cookie.
6. The tester port and the N3 tester identity
The tester listener exists so agents can test as the tester and never as Jason (mos-0870 N3). Under SSO:
- It never mounts
/auth/*(404), never reads a cookie, and refuses any request carryingAuthorizationor a__Host-mosaic_session/__Host-mosaic_logincookie (403tester listener takes no sign-in). The same goes forX-authentik-jwtand the old auth and proof header names. startServerthrows when its options hold bothtesterandsso, so the SSO module can't be mounted on the tester listener by a wiring mistake. A unit test calls it with both.- Its writer stays the fixed
{ tester: true, user: 'tester' }, and it allows only the row 175 writes, as today. No session or header can change it. - Its bus calls stay on
TESTER_CLI. The bus checks the tester proof and refuses human verbs from it, and the broker refuses a business whose human istesterand any role namedtester. So nothing that reaches 7333 can become the human. - 7332 keeps refusing
x-mosaic-testerfor every Host (:485). subjectsvalidation refuses anameoftesterorhuman.
7. Point 5, the proxy-forwarded token
Not in phase 1. Point 5 makes it optional and the code flow covers the ruling. If it's built later:
- Verify with jose (MIT, exact pin), against the JWKS from the configured issuer's own discovery. Never use
the
X-authentik-meta-jwksheader, because it arrives with the request and the forger controls it. - Use the same alg allow list, iss, exp and subject list.
audis the proxy provider's client id, and the config check refuses it if it equals any code-flowclientId, so an ID token issued to the Console can't be replayed as a proxy token or the other way round (N4). - The mosaic-preview provider signs with HS256 and has an empty JWKS, so its
X-authentik-jwtfails every check until Jason gives it an RSA or EC key (Jason step 1).
8. Interim exposure until phase 2
Today, with --send live, any same-uid process on dragon-lin can connect to 127.0.0.1:7332 with
Host: mosaic.woltje.com, X-authentik-username: jason.woltje, the matching Origin and
Sec-Fetch-Site: same-origin, and send as Jason. That includes agent seats. Through the tunnel, the outpost
strips client copies of the header, so a remote forger needs local code execution first. Users on other uids
can reach the loopback port too (P19 333).
Mos ruled (mos-0972) that the Console runs without --send until phase 2. Reads stay up, the header path
stops carrying writes, and Jason sends piece 1 with mosaic talk pm instead. Row 189 (stack-release.sh activate --no-send, #1687) makes that change through the pointer so the unit and stack-active.json stay in
step; the restart follows its landing. Until phase 2, no agent sends a request with the auth header to 7332.
The tests use fixture servers.
To be clear about the limit: SSO protects Console ingress. It doesn't protect the bus's human boundary. The
human proof is path-bound (#225), so a same-uid process can already run the tree's human-cli.mjs and act
as the human without touching the Console. Q175 doesn't change that. P19 333 owns it.
9. Tests
All tests run against a fake OP in packages/webui/tests/helpers/fake-oidc.mjs. It's a loopback https
server with a self-signed cert. Each test passes the library a customFetch that trusts only that cert, so
production code needs no insecure-request flag. The fake OP has discovery, a JWKS, and authorization, token
and end-session endpoints, with keys made by node:crypto (RSA 2048, P-256, and an HMAC secret for the
forgeries). It can serve two issuers at once and rotate its keys. No test reaches a real provider. Each
refusal test asserts the status, that no __Host-mosaic_session was set, and that the bus send stub was
never called. Each test also passes once unmutated, as the control.
Refusals Mos named:
- Forged header.
X-authentik-username: jason.woltjewithHost: mosaic.woltje.com, the right Origin and Fetch Metadata, and no cookie: 401 on/api/bus/message,/api/settingsand/api/config, and a 303 to login on/. - HS256 ID token. The fake OP signs the ID token with HS256, using the client secret as the key (the classic
confusion) and
kidset to a real RSA kid: refused at the callback. The library's alg check refuses it before any signature check, so this test proves the alg rule, not the signature check. Test 9 covers that. - Wrong aud. A correctly signed RS256 token with
audset to another client id: refused. Also anaudarray holding our client id and another, with noazp: refused. - Expired token. A correctly signed token with
exp10 minutes ago (beyond the library's 30 s clock tolerance): refused.
More refusals:
- Wrong
iss, both a different issuer and a trailing-slash variant. - Nonce mismatch or missing nonce.
- State mismatch, a missing login cookie, a replayed callback (record already taken), an expired login record, and two login cookies. For the replay, the fake OP is set to accept the same code twice, so the second callback reaches the record lookup and only the take-and-delete rule refuses it.
- A provider that demands no PKCE. The token request must carry
code_verifier, and the fake OP refuses a wrong one. - The signature check (B5), three cases: (a)
alg: none; (b) an RS256 token whose header names a real kid in the JWKS, with a changed payload and the original signature; (c) an RS256 token signed by a key whose kid isn't in the JWKS, even after the refetch. (a) is refused by the alg check in step 4, so it's an alg test like test 2. Only (b) and (c) reach step 5, and (b) is the case only the signature check catches. - A valid token for a
subnot insubjects: 403 and onesubject-unknownlog line with the provider id, iss and sub only. - Start refusals:
algsholdingHS256ornone, HS-only discovery (the mosaic-preview shape), an empty JWKS, no S256, an issuer mismatch, a subject namedtesterorhuman,--ssotogether with--auth-header, and slot files that are a symlink, mode 0644, mode 0640, or under the repo. The owner check has no test: making a file owned by another uid needs root, which the suite doesn't have. The review reads that branch instead. - Tester port: a valid session cookie (taken from a 7332 sign-in),
Authorization: Bearer <valid id token>, andX-authentik-jwteach get 403./auth/loginon 7333 gets 404.startServerwithtesterandssothrows. - Session: idle expiry, absolute expiry, a logout followed by reuse of the old cookie, and logout without
same-origin (refused, session kept). Background
/api/GETs every 10 s for over an hour don't keep the session alive; a page load does. - Open redirect:
return=//evil.example,return=https://evil.example,return=/\evil.exampleandreturn=/%09/evil.exampleall land on/, andreturn=/board?x=1lands there. - Provider mix-up. Two providers, A and B. A login started for A whose callback carries B's
issand a code from B is refused, and aprovider=query on the callback is ignored. B's code is issued against A-record's PKCE challenge, so the verifier matches and only the record rule (the callback belongs to A) refuses it. - Several algs: a provider with
algs: ["RS256", "ES256"]takes a token signed with either, and refuses PS256 even when the JWKS holds a usable PS256 key. - Login record cap: 33 started logins leave 32 records, and the first login's callback finds no record.
- JWKS rotation: the fake OP rotates to a new key with a new kid. A sign-in after the rotation succeeds through the one refetch, and a token under the removed kid is refused.
- Logs: across every test in this file, captured log lines hold none of the tokens, codes, states, nonces, verifiers, the client secret or a session id that the test produced.
- The session store holds no raw session id (keys are sha256 values, and no value holds the cookie).
- Set-Cookie: the exact session and login cookie strings, including the expiry of the login cookie at callback.
- Host: under
--sso, a loopback Host on/,/api/boardand a write each get 403;/healthzon loopback gets 200. - Degraded start: the fake OP is down at start; the Console starts,
/auth/loginis 503,/healthzreportsunreachable; the OP comes up and the next retry makes sign-in work. A discovery URL that answers 200 with an HTML page also counts asunreachableand the Console starts. A provider that answers with HS-only discovery at start refuses the start. - Signed-out page (C2). A page test in the board-held.test.mjs style stubs fetch to answer 401
{ error: 'sign-in required' }: the page shows the signed-out notice, its link is/auth/login?return=<current path and query>, and the refresh stops. A 401 with another error stays an error. The existing opaqueredirect case still signs out. - Loader (C1), in scripts/test-config.sh: a config with a valid
console.ssoloads; a malformed one (an HS alg, a missingslotfield, a slot name outside the pattern, an unknown key underconsole) fails and names the bad key path, and no case reads a slot file (the file cases stay in test 11); a config withoutconsoleloads.
Positive paths: an RS256 and an ES256 provider each complete sign-in and one send, and two providers configured together each work with their own subjects.
Mutants for the gate, each killed by the named test:
- drop the
validateApplicationLevelSignaturecall (9b); - wrap that call in a try/catch that continues (9b);
- drop the
subjectscheck (10); - accept HS* in
algs(11); - take the provider from the query (15);
- let the tester listener read cookies (12);
- skip the login record delete (7);
- drop
HttpOnlyfrom the session cookie (21); - refresh
seenon every request (13); - build
redirect_urifrom the request Host (a test with a different Host on/auth/loginchecks theredirect_urisent to the fake OP); - serve the loopback read path under
--sso(22).
10. Jason-gated steps
- Authentik mosaic-preview: give it an RSA or EC signing key or retire it, and confirm by an admin read that
client_id
GEQ84kBbt2RG6fhYQGgZl2J9jgjw6wRJ3oSWxqZQbelongs to it. (Ask B matched it only on scopes and redirect_uri.) - Authentik mosaic-stack provider: register redirect URI
https://mosaic.woltje.com/auth/callbackand post-logout URIhttps://mosaic.woltje.com/auth/signed-out, keep RS256, and give the client id. Put the client secret into slotconsole-sso-authentik(or say an agent may create the slot file from a value he puts in place, per the Q173 secrets rule). Agents never see the value. - His
subfor that provider, or a go to read it from the Console's onesubject-unknownlog line on his first sign-in attempt. - The
console.ssoentry in~/.config/mosaic-dev/config.json, inside the phase 2 window, after the pin and before the Console starts (section 5). He writes it, or he gives an agent the go to write that one key from the values in steps 2 and 3, with a backup of the file first. config.json is user-authored, so this isn't covered by Q173. Writing it earlier stops every tool on the live copy, whose loader refuses the key. - Any Traefik or outpost change. None is needed while the outpost stays in front. Dropping the outpost later, so the Console is the only gate, changes who can reach the Console from outside and is his call.
- The phase 2 re-pin window go.
Questions for review
Q-A to Q-E are settled (Filbert r1 and r2, Mos mos-0973). One open point, for Mos:
- The config.json sequence (C1): the key goes in only inside the phase 2 window, after the pin and before the Console starts, with a backup first, and a rollback removes it before the pointer moves (section 5). Mos confirms this before phase 1 starts.