Developer portal auth pages

Purpose

Five static pages through which a developer gets into the portal without a password: request a sign-in link, land on the mailed link, and, for a new account, request a confirmation link, land on it, and read the first API key once. The invariant that makes them trustworthy is that the browser never learns what the server refuses to say: the two request pages render the same "if this address can be ... a link is on its way" panel whether or not the address exists, the verify page cannot tell an expired token from a used or forged one and its copy names all three, and a full key exists in exactly one DOM node on one page load and nowhere in storage, the URL or a log.

It makes three backend modules visible: B14 (POST /api/prima/v1/accounts and /accounts/verify, the two-step signup whose second step this surface owns), B5 (POST /api/auth/request-magic-link and /verify-magic-link with surface: prima_dev), and B4 (the prima_dev surface: the 403 copy on both request and verify, and /me.surfaces on the page that follows).

When to use

Trigger phrases: "magic link page", "the sign-in card", "why does the portal say the link is on its way when I typed a wrong address", "the key shown once", "the confirmation link 404s", "nicht konfiguriert", "where does the mailed link land". Surface: portal, a static Astro site (astro 4.16.19, prima-developer/package-lock.json at c594dfc) on its own origin with no server of its own, every call a cross-origin fetch to the Labs API whose base is baked at build (src/lib/auth.ts lines 79 to 91). It is static because ADR-0020 gives every Prima surface its own compile-time surface constant and its own build (astro.config.mjs lines 3 to 9); the sibling pages on prima.li share the shape and differ in SURFACE and in the two-step registration (auth.ts header, lines 10 to 16).

Do not use it for the Labs SPA's login (identity-auth/ui/auth-screens, F1: React, password and passkey, cookie mode), for the chat client's sign-in (identity-auth/ui/chat-signin-and-workspace-picker, F6: a server holds the session), or for the page after sign-in (identity-auth/ui/developer-portal-keys-page, F8: the guard, the shell, the keys). The primacode desktop hand-over that branches off /auth/magic-link (src/pages/auth/desktop.astro, 750 lines at c594dfc) is a primacode row, not this one; this recipe records only the one conditional that sends a token there.

Stack assumptions

S1 as the token vocabulary in the demo only: the portal's own global.css declares a house palette copied from prima.li's marketing site (src/styles/global.css lines 1 to 5 and 32 to 68: --purple, --sand, --sand-deep, --ink, --ink-60, --ink-30, --line, --line-strong, --swiss, --ok, --ok-bg, --r-*, --s-*, --shadow-*, --font, --font-display, --mono), not prima.li's tokens.css aliases, and the auth pages read those (auth.css, 224 lines, "Tokens only"). The demo maps them onto @prima-modules/prima-tokens (Frontend). S3 (_shared/astro-site-skeleton) for the site shape; no S2, nothing here is React.

Component library: none. The pages are hand-written markup with one stylesheet (auth.css) and one <script> each; Code.astro on the confirm page is the docs' code block with its copy button (src/components/Code.astro lines 1 to 22). Data-fetch style: auth.ts post() with credentials: "omit", Content-Type and Accept JSON, no cookie ever read or relied on (lines 161 to 173); results are an AuthResult<T> discriminated union, never a thrown error (lines 126 to 143). Copy: de-CH, Sie-Form, no ß.

Environment baked at build (astro.config.mjs lines 26 to 96, apiBaseGuard): PUBLIC_PRIMA_API_BASE unset means a loud warning and every auth page built in its "nicht konfiguriert" branch with no form; unset with PRIMA_REQUIRE_API_BASE=1 fails the build; malformed, a non-https non-local host, or a query or fragment fails the build always. There is no fallback host anywhere in the repo, on purpose (lines 11 to 25). CONTACT is one constant used by every "this is broken" branch (auth.ts line 108).

Data model

Client state, per page, held in the DOM and in module-scope variables of the page script, never in a store:

Types the pages consume (src/lib/auth.ts):

type AuthErrorCode = 'not_configured' | 'network' | 'rate_limited' | 'invalid_email' | 'missing_token'
  | 'link_invalid' | 'email_taken' | 'surface_denied' | 'server' | 'unknown';              // lines 114 to 124
type AuthResult<T> = { ok: true; data: T } | { ok: false; code: AuthErrorCode; message: string; retryAfter?: number };  // 126 to 135
interface MagicLinkRequested { email: string }                                             // 243 to 246: the typed address echoed back
interface SessionUser { id: string; email: string; name: string | null }                   // 300 to 304
interface PrimaSession { accessToken: string; expiresAt: number; surface: string; user: SessionUser; sid: string; issuedAt?: number }  // 306 to 326
interface SignUpRequested { email: string; expiresInMinutes: number | null }               // 400 to 404
interface SignUpConfirmed { key: string | null; keyPrefix: string | null; email: string | null }  // 462 to 472

Browser storage written by these pages, all under the prima.dev.* namespace so a prima_web session stays distinguishable once a shared .prima.li cookie replaces it (auth.ts 567 to 571):

What the browser never holds: a password (there is no password field and the header comment forbids adding one, auth.ts 18 to 22), a refresh token, a raw API key after the confirm page unloads, the magic-link token after the page read it (scrubUrl, verify.astro 117 to 123).

API surface

Four contracts, all POST with a JSON body, no credential, surface sent where the client can (auth.ts 29 to 33; the backend side is B5 and B14):

Error bodies: the Labs handler emits {error, code, request_id, timestamp} and plain FastAPI validation emits detail; detailOf reads both so a server-worded refusal is not flattened into the generic sentence (auth.ts 35 to 42, 229 to 237; S7). Retry-After is not CORS-safelisted and Labs exposes only X-Total-Count and X-Request-ID (alchemy_labs/backend/app_fastapi.py line 452 at fd8558f), so retryAfter is undefined cross-origin and the 429 copy is the wording without a countdown (auth.ts 175 to 181).

No WebSocket, no postMessage. The mailed links: {surface.origin}/auth/magic-link?token= for a magic link (alchemy_labs/backend/api/routers/auth_router.py lines 1090 and 1119, and services/email_service.py line 522, fd8558f) and {PRIMA_DEV origin}/signup/confirm?token= for a signup confirmation (primaapi_router.py 678 to 679), which is why /auth/magic-link and /signup/confirm on this origin are not optional.

Application logic

Sign-in, /anmelden (anmelden.astro):

1. The page renders the card with the form, the hidden sent panel and the empty status region (33 to 99); the script binds only when IS_CONFIGURED and both nodes exist (118).
2. Submit: preventDefault, trim, clear aria-invalid, disable the button and relabel it "Wird gesendet …", status busy (137 to 146).
3. requestMagicLink(email): the loose client check first (looksLikeEmail, 290 to 294; a typo saved from a rate-limited round trip), then the POST.
4. Failure: the button restored; invalid_email also sets aria-invalid and focuses the input; the message in the status region as error (153 to 160).
5. Success: status cleared, form hidden, the typed address written into the sent panel, panel shown and focused with tabindex=-1 so keyboard and screen-reader users land on the new content (162 to 169). "Andere Adresse verwenden" reverses it and clears the field (172 to 178).

Landing, /auth/magic-link then /anmelden/verify:

6. The mailer's route reads token from #token= first, then ?token= (magic-link.astro 72 to 79). No token: replace('/anmelden/'). Otherwise it forwards with replace to /anmelden/verify#token=..., or to /auth/desktop/#token=... when readDesktopAuth() returns a fresh record (81 to 94): the fragment never reaches a server or a Referer, and replace keeps the mailed URL out of history.
7. /anmelden/verify reads the token the same way, then scrubUrl (history.replaceState to the bare path) before any await (133 to 134). No token: heading "Kein Anmeldecode gefunden", the error explains that mail programs shorten long addresses, and the "Neuen Link anfordern" action appears (136 to 147).
8. Status busy; verifyMagicLink(token). Failure: heading "Anmeldung fehlgeschlagen", the message, and for every code but rate_limited the sentence that links are single-use and short-lived; the action appears (153 to 163).
9. Success: saveSession(result.data) (166), then mintGatewayKeyAtSignIn() best-effort so the next page has a balance without a second round trip; a failed mint must not undo a sign-in that succeeded (168 to 172). Heading "Angemeldet", status ok with a manual link, then location.replace('/schluessel/') so the back button cannot return to a spent token (174 to 184).

Registration, /registrieren then /signup/confirm:

10. Same shape as sign-in with a second, optional company field (registrieren.astro 39 to 75); signUp(email, company) sends null for an empty company (auth.ts 426 to 434). The sent panel says a link is on its way "falls für ... ein Konto angelegt werden kann", states the expiry only from expiresInMinutes, and says in bold that account and key exist only once the link is opened (77 to 97, 187 to 189).
11. /signup/confirm reads the token, scrubs the URL, latches redeemed and calls verifySignup(token) once per page load (confirm.astro 178 to 210). There is deliberately no retry button: the token is burnt server-side in the transaction that creates the account, so a retry after a transient blip would turn into "your account exists and your key is gone" (36 to 43).
12. Failure: heading "Bestätigung fehlgeschlagen" and the message; for email_taken the action is rebuilt as "Zur Anmeldung" because sign-in is the useful next step (212 to 229).
13. Success: heading "Konto bestätigt", lede with the address. With a key: status ok "Willkommen bei PrimaAPI.", the key written into #reveal-key with textContent, the reveal shown, the key node focused (237 to 244). Without a key: an error status saying the account exists but no key came back and to mint one under "Schlüssel" (245 to 253). In both cases the "first call" block appears with the curl that reads $PRIMA_API_KEY from the environment rather than interpolating the key (19 to 24, 254).
14. Copy button: navigator.clipboard.writeText, label "Kopiert" on success, an honest "Nicht möglich, bitte markieren und kopieren" on refusal (257 to 268). beforeunload warns while the reveal is visible (272 to 278).

Invariants

• No page says an e-mail was sent. Both request pages say a link is on its way if the address can be signed in or registered; the 202 is the same for an unknown or taken address on the server (B5, B14) and the client cannot detect either (auth.ts 44 to 51, 406 to 413).
• The verify copy names three causes at once (expired, used, invalid) because the server answers them alike (auth.ts 49 to 51, 353 to 358).
• A raw key is rendered into exactly one node by textContent, never with innerHTML, never stored, never in the URL; hideReveal on the keys page clears the node and this page has no such button, so the key lives until unload and the browser warns before that (confirm.astro 34 to 43, 240 to 244, 272 to 278; prima-api.ts INVARIANT B, 29 to 35).
• The magic-link token is read from the fragment before the query, and the address bar is scrubbed before the first await (verify.astro 102 to 123).
• verifySignup runs at most once per page load (confirm.astro 181, 189 to 190).
• There is no <input type="password"> in the repository (auth.ts 18 to 22; Acceptance check 2).
• Every status message is escaped before innerHTML (escapeHtml, anmelden.astro 181 to 186 and the same in the other three scripts); the sent-panel address is written with textContent.
• The unconfigured build renders no form: an address typed into a form with nothing to post to would be discarded silently (anmelden.astro 6 to 10).

Frontend

The rendering is the live rebuild developer-portal-auth-pages/demo.astro, rendered by the docs host as one frame per state (RENDERING.md, section 3). One Astro component takes state and renders the card the real page would show after its script has run: every branch that the real script toggles with hidden and a class is here a server-rendered state, so all seventeen are on the page at once and none touches the network. The real page is a static shell (the visible branch is the script's decision after the fetch, and the HTML carries no account data); that is a property of the page, not a mount mode, so the frontmatter's hydrate stays at the default visible: the docs host renders an Astro demo server-side with no directive and reads the key for React demos only (prima.li/src/index-site/DemoIsland.astro at 86fe9d1, lines 131 to 136).

States, in order: signin (the form, nothing typed), signin-busy (button disabled and relabelled, the live region busy), signin-invalid (the client check refused the address: aria-invalid, the error status), signin-sent (the 202 panel with its enumeration-safe copy and "Andere Adresse verwenden"), signin-denied (403), signin-throttled (429 without a countdown), verify-busy, verify-failed (the three-cause sentence, the "Neuen Link anfordern" action), verify-ok (status ok, the manual link), magic-link-forward (the mailer's route: the card with the lede and a one-line note of where the token goes; the real page shows the lede alone for the instant before replace), signup (e-mail and the optional company), signup-sent (the panel with the server-stated 30 minutes and the bold "erst, wenn Sie den Link öffnen"), confirm-busy, confirm-key (201: the reveal with an obviously fake key in one node, the first curl block, the two buttons; the card widens to 620 px as confirm.astro line 53 does), confirm-taken (409 with "Zur Anmeldung"), confirm-no-key (201 without a key: the error status and the first-call block, no empty box), unconfigured (/anmelden built without PUBLIC_PRIMA_API_BASE: no form, the red panel naming the variable and the sign-in footer; the other four pages carry their own unconfigured copy, registrieren.astro 100 to 111, verify.astro 47 to 59, confirm.astro 112 to 125, and the verify and confirm scripts also rewrite the heading; those variants are not states).

Design system prima (D1b): the demo draws auth.css with @prima-modules/prima-tokens aliases. The mapping, portal variable to token: --sand-deep (the ground) to --bg-surface; the white card to --bg-page; --line to --border-default; --line-strong to --border-strong; --purple to --fg-accent; --purple-dark to --c-violet-600; --ink to --fg-default; --ink-60 to --fg-muted; --ink-30 to a color-mix of --fg-default into the page; --r-xl (card) to --radius, --r-md and --r-sm to --radius-sm; --s-3 to --s-9 to --space-sm through --space-4xl (the same pixel values at 16 px root); --shadow-lg to --shadow-soft; --font-display to --font-body at weight 500 (prima.li's display face is a serif italic accent, not a heading face); --mono to --work-mono. The once-only reveal (app.css 608 to 658) and the code block (docs.css 137 to 189) bring four more: --r-lg (16 px, the reveal's corner) to --radius-sm (8 px; the token layer has no 16 px step and --radius is 20 px), --purple-50 (the reveal's ground) to a 6% color-mix of --fg-accent into the page, the two violet text colours #43307E (reveal__warn) and #5B4A94 (reveal__note) both to --c-violet-600, and the code block's --slate to --bg-dark at the docs' 13 px on --s-5 padding. Two colours the token layer does not carry, the refusal red #c4362f (--swiss) and the confirmation green #2f7d5b with its tint (--ok, --ok-bg), are declared once on the demo root and named in Gotchas as a gap in prima-tokens.

The frames flow at the column's width with no viewport: the card is max-width: 460px centred on its ground, the screen is the card, and the site header and footer around it (Layout.astro lines 51 to 131) are not rendered because the auth pages sit outside the signed-in sub-navigation; F8 renders that shell. Text and headings inside the demo are div and h3, and inline code is span.mono, because the docs host's shell rules reach p, h1, h2 and code inside a frame at a specificity an Astro scoped rule cannot beat (prima.li/src/index-site/demo-frame.css at 86fe9d1, the header comment and lines 147 to 169); the real pages use h1, p and code.

Responsive: the card is max-width: 460px (620 px on confirm) and shrinks with the column down to about 400 px of viewport; the inputs stay 16 px so iOS does not zoom on focus (auth.css line 69). Below that the unbreakable tokens set the floor, on the reference and in the demo alike: PUBLIC_PRIMA_API_BASE in the unconfigured chip (auth.css 210 to 216, no wrapping), the sample address in the confirm lede and developer.prima.li in the denied status. Measured on the built docs page on 2026-09-12: at a 400 px viewport the unconfigured card is 294 px in a 254 px ground and the two confirm cards 261 px; at 360 px eight of the seventeen cards pass their ground and the unconfigured stage scrolls sideways (Gotchas). The real site's header collapses its links below 900 px and keeps "Anmelden" at every width (Layout.astro 164 to 175). Loading is the busy status plus the disabled button; empty is the untouched form; error is the error status, and on the landing pages also the swapped heading and the action link.

What the demo deliberately does not render: the header and footer, the noscript blocks (the verify and confirm pages carry one explaining that a static site needs JavaScript to redeem a link, verify.astro 61 to 71, confirm.astro 127 to 137; magic-link.astro 58 to 63 carries the "Neuen Link anfordern" line inside its noscript and nothing under the lede otherwise, so the magic-link-forward card ends with the lede and the route note), the beforeunload guard, the redirect after verify-ok, the focus moves, and the desktop branch of /auth/magic-link (its target page is a primacode row). Two docs-only differences in the markup, named in the demo's header: the forms carry method="dialog", which the HTML form submission algorithm turns into a no-op outside a <dialog>, so a click or Enter on the docs page neither reloads it nor puts the typed address into its query string (the real forms have no method and their script calls preventDefault); and the aria-live region is written without whitespace children in the states that have no status, so .auth__status:empty matches as it does on the real page (Gotchas). The /auth/magic-link card has no status region, as magic-link.astro 53 to 65 has none. The copy is the pages' own with the em dashes the source uses replaced by a colon or a full stop (house rule); the support address and the sample address are placeholders.

Security & tenancy

What the browser may hold: the access token in sessionStorage (dies with the tab; the interim answer until a backend on a *.prima.li origin can set an HttpOnly cookie scoped to .prima.li, which ADR-0020 reserves and which does not exist yet, auth.ts 548 to 571), the per-session ai key beside it (F8), and the parked row ids. Never a key beyond that page load, never a refresh token, never a password, never the magic-link token after it was read.

Origin and CSRF: every call is credentials: "omit", so no ambient credential is sent and the API's Set-Cookie is ignored (161 to 166); the Labs CORS list is built from the surface registry, so https://developer.prima.li is an explicit allowed origin and never a wildcard (alchemy_labs/backend/app_fastapi.py 400 to 411 and core/surfaces.py 152 to 157 at fd8558f). The surface travels as surface: "prima_dev" in the request bodies and as X-Prima-Surface on the signed-in calls (prima-api.ts 415); the backend is the enforcement point and the constant is the claim (auth.ts 24 to 27).

Surface gating: a 403 on request or verify renders the surface_denied copy and stays on the page; /me.surfaces is read on the next page (F8), where prima_dev missing is a 403 state that does not bounce to sign-in, because signing in again cannot add a grant (prima-api.ts 492 to 500). Nothing on these pages is hidden by CSS as a security measure: the unconfigured branch is a build-time decision (the form is not in the HTML), and the sent panel hides the form after a 202 for focus, not for access.

Attacker-controlled inputs rendered: the typed address (written with textContent), server error strings (escaped before innerHTML), the key (textContent). The status region is role=status aria-live=polite from first paint so late insertions are announced (anmelden.astro 90 to 99).

Tests

• prima-developer has no test for these pages at c594dfc: npm test is node --test --experimental-strip-types "src/**/*.test.ts" and runs the pure helpers only (gateway-key.test.ts, billing.test.ts, desktop-auth.test.ts: 173 tests, 30 suites, all passing on 2026-09-12). auth.ts itself has no test.
• What a new app adds, as node --test on pure functions: looksLikeEmail accepts [email protected] and refuses a@b; detailOf reads error before detail and the first msg of a list; a table of (status, body) to AuthErrorCode for each of the four calls, with 409 only on accounts/verify and 403 only on the two magic-link calls; readSession returns null and clears the entry when expiresAt has passed.
• Playwright, against dist/ served statically with the API mocked at the route level: (a) submit /anmelden with a malformed address and assert aria-invalid and the error status without a network call; (b) mock a 202 and assert the sent panel names the typed address and the form is hidden; (c) open /auth/magic-link?token=x and assert the navigation lands on /anmelden/verify with the token in the fragment and no token in the query; (d) mock verify-magic-link 200 and assert sessionStorage['prima.dev.session.v1'] exists and the page leaves for /schluessel/; (e) mock accounts/verify 201 with a key and assert exactly one element contains it and sessionStorage does not.
• The kit's gate: npm run check prints no line for this recipe; the render smoke (node tooling/verify/render-smoke.mjs) covers React demos only and reports nothing for an Astro demo; the docs build is the render check for it (Acceptance check 6).

Deploy & ops

Build target: Astro static (astro build, output default), dist/ served as verbatim bytes. Env baked at build: PUBLIC_PRIMA_API_BASE (the only host the pages talk to) and PRIMA_REQUIRE_API_BASE=1 on a release build so an unconfigured build cannot ship (astro.config.mjs 26 to 96). The deploy path is S13's static portal: the ship script builds with both variables set, refuses an empty dist/index.html or any localhost, 127.0.0.1 or staging host left in dist/, backs up the served directory and rsyncs the new one in (S13 Application logic steps 20 to 21); rollback is the printed rsync from the backup. The comment at the top of astro.config.mjs (lines 3 to 4) still says "deployed to Cloudflare Pages"; S13 measured the rsync path on 2026-09-11.

CORS: nothing to add on the portal; the API side lists the surface origin (Security & tenancy). CSP: the portal sets none of its own at c594dfc (no <meta http-equiv> in Layout.astro, no headers file in public/). Argus: none for these pages; a broken confirmation route has no symptom but people who never arrive (confirm.astro 30 to 32), so the check that matters is the ingress one in B14 (the /accounts* routes matched to Labs before the Prima catch-all).

Gotchas

• 2026-09-12 (rendering trap, fixed in the demo the same day): Astro emits the template whitespace around a falsy {cond && ...} expression as a text node, so a region written as <div class="auth__status">{v.status && ...}</div> across several lines serialised as <div class="auth__status"> </div>, :empty never matched and six states (signin, signin-sent, magic-link-forward, signup, signup-sent, unconfigured) painted a 34 px empty bordered box under the form that the real page never shows (anmelden.astro 93 to 99 is <div ...></div>, hidden by auth.css 102 to 104). The fix is two branches, the empty one written as <div ...></div> with nothing between the tags; the built docs page now computes display: none and height 0 for all six (Playwright against prima.li at 86fe9d1, 2026-09-12).
• 2026-09-12 (rendering trap, fixed in the demo the same day): a <form> with no action and no script performs a native GET on submit, so a click or Enter in a docs-page frame reloaded the recipe page with ?email= in the query, the one request an Astro demo could still cause (RENDERING.md section 2, nothing reaches the network). method="dialog" on the demo's forms makes the submission a no-op outside a <dialog>; the click and the Enter key both leave the URL unchanged on the built page.
• 2026-09-12 (measured at c594dfc, auth.css 210 to 216 and the built docs page): the reference card is not fluid below about 400 px. .auth__unconfigured code has no overflow-wrap, and neither the lede nor the status region breaks a long token, so PUBLIC_PRIMA_API_BASE, the address in the confirm lede and developer.prima.li in the denied copy push the card past its ground (294 px in 254 px at a 400 px viewport on the unconfigured page; eight of seventeen states at 360 px). The demo keeps the rules so the frame is faithful. The fix it needs is overflow-wrap: anywhere on .auth__unconfigured code, .auth__lede and .auth__status in auth.css; no code is changed in this wave (D8).
• 2026-09-12 (measured at c594dfc, verify.astro lines 8 to 15): the page's header comment says the mailer builds its URL from FRONTEND_URL rather than the surface registry. At fd8558f it does not: auth_router.py line 1090 sets base_url = surface.origin and only the labs surface in development falls back to FRONTEND_URL (1091 to 1092). The trap the W6 route closed was the path, /auth/magic-link (email_service.py 522), not the host; magic-link.astro lines 7 to 26 record it correctly. A stale comment, no behaviour to fix; the fix it needs is deleting lines 8 to 15.
• 2026-09-12 (measured at c594dfc, auth.ts 440 to 450, and B14 API surface): POST /api/prima/v1/accounts answers 403 with "Self-service signup is disabled on this deployment ..." or "Signup for this email domain is not permitted ..."; signUp has no 403 branch, so both land in unknown and render "Unerwartete Antwort vom Anmeldedienst." with the server's sentence dropped. verifySignup (508 to 524) has the same gap for the re-check at redemption. Fix it needs: a surface_denied-style branch for 403 on both that renders detailOf(res.body).
• 2026-09-12 (measured at fd8558f, app_fastapi.py 452; c594dfc, auth.ts 175 to 181): Retry-After is not in expose_headers, so the 429 copy never carries the countdown the client is written to render. The fix is one entry on the Labs side (expose_headers=[..., "Retry-After"]), then no change here.
• 2026-09-12 (measured at c594dfc, confirm.astro 181 and 280): the redeemed latch guards run(), which is called exactly once and has no caller that could run it again; the latch is a belt for a retry button that was deliberately not built. Harmless.
• 2026-09-12 (measured at c594dfc, confirm.astro 19 to 24 and docs.ts 25 to 28): the first-call block on an unconfigured build prints https://<PUBLIC_PRIMA_API_BASE>/api/prima/v1, which is the placeholder the demo shows too; on a configured build it is the baked host plus /api/prima/v1.
• 2026-09-12 (rendering trap): the real script decides the visible branch after the fetch, so a screenshot of the page shows the form and nothing else; the demo renders each branch as its own state. A verifier comparison against /anmelden matches signin only, and verify.route says so.
• 2026-09-12 (rendering trap, demo-frame.css at 86fe9d1): p, h1, h2 and code inside a frame inherit the frame's reset, so the demo uses div, h3 and span.mono; a rebuild that keeps the source's elements renders its lede and title unstyled on the docs host.
• 2026-09-12 (@prima-modules/prima-tokens at its 03f4205 pin): prima.li's tokens.css has no state colours (no danger, no success); the demo declares the portal's two values locally (--dpa-danger, --dpa-ok, --dpa-ok-bg). When the token layer gains them, the demo reads them and drops its own.
• 2026-09-12 (measured at c594dfc, auth.ts 376 to 377): a 200 without expires_in gives the local session 1800 seconds; B5's 200 carries expires_in, so the default is a fallback and not the lifetime.
• 2026-08-25 (wiki platform/primaapi.md, recorded in magic-link.astro 7 to 18): every mailed prima_dev link landed on a 404 because the site did not serve /auth/magic-link; the workaround was to request the link as prima_chat from the Labs host. Serving the path (W6) closed it; the workaround stays valid.
• 2026-08-03 (prima-api.ts 549 to 555, measured then): POST /api/auth/logout answered 404 through the API host's ingress allow-list, so sign-out is local until the path is allowed; the request stays in place because it is correct.

Reference implementation

Branch: prima-developer w6-konto at c594dfc (2026-09-12), one commit past the d5f9aa8 the inventory row names (the desktop hand-over, which touches magic-link.astro 35 to 44 and 87 to 93). Paths relative to the repo root:

• src/pages/anmelden.astro (187 lines): guard comment 6 to 13, card 22 to 109 (form 33 to 55, sent panel 57 to 72, unconfigured 75 to 87, status region 93 to 99, alt and fine print 101 to 107), script 112 to 187 (setStatus 125 to 133, submit 137 to 170, again 172 to 178, escapeHtml 181 to 186).
• src/pages/anmelden/verify.astro (188 lines): header 6 to 20, card 29 to 77, script 80 to 188 (REDIRECT_TO 91, extractToken 103 to 110, scrubUrl 117 to 123, run 125 to 185).
• src/pages/auth/magic-link.astro (95 lines): why it exists 5 to 44, script 68 to 95.
• src/pages/registrieren.astro (211 lines): what the page can promise 6 to 19, form 39 to 75, sent panel 77 to 97, script 133 to 211 (expiry sentence 186 to 189).
• src/pages/signup/confirm.astro (281 lines): firstCall 19 to 24, the page every signup mail points at 26 to 43, reveal 69 to 85, next 87 to 104, script 142 to 281 (redeemed 181, run 183 to 255, copy 257 to 268, beforeunload 272 to 278).
• src/lib/auth.ts (951 lines): header 1 to 52, SURFACE 77, API_BASE and IS_CONFIGURED 86 to 91, CONTACT 108, result type 114 to 143, post 167 to 196, detailOf 229 to 237, requestMagicLink 248 to 288, looksLikeEmail 290 to 294, verifyMagicLink 328 to 394, signUp 415 to 460, verifySignup 487 to 542, session storage 548 to 659, gateway key storage 662 to 866, desktop record 869 to 951.
• src/lib/prima-api.ts (1442 lines): SIGNIN_PATH 201, redirectToSignIn 476 to 481, requireSession 507 to 546, signOut 557 to 578, mintGatewayKeyAtSignIn 746.
• src/layouts/Layout.astro (207 lines): header 51 to 77, footer 83 to 131, nav styles 135 to 175. src/components/AppNav.astro (26 lines) is the signed-in sub-navigation and is not on these pages.
• src/styles/auth.css (224 lines): .auth 5, .auth__card 13, form 49 to 99, status 102 to 138, sent 141 to 174, footer of the card 177 to 193, unconfigured 196 to 224.

Deviations of the reference from this recipe, dated 2026-09-12: the stale mailer comment in verify.astro; no 403 branch on the two signup calls; no test of auth.ts; the astro.config.mjs comment naming Cloudflare Pages where S13 measured rsync; the card overflowing its ground below about 400 px on the pages that carry an unbreakable token (Gotchas).

Acceptance checks

From prima-developer at c594dfc, or a new portal built to this recipe:

1. grep -c 'surface: SURFACE' src/lib/auth.ts prints 3 (request, verify, signup); grep -n '"prima_dev"' src/lib/auth.ts prints line 77 and nothing else.
2. grep -rn 'type="password"' src/pages src/components src/layouts prints nothing, and grep -rn 'type="password"' src/ prints exactly one line, the forbidding comment at src/lib/auth.ts line 21 (verified 2026-09-12 at c594dfc).
3. grep -n 'credentials: "omit"' src/lib/auth.ts src/lib/prima-api.ts prints at least three lines (the auth post, the data client's send, the logout fetch).
4. PUBLIC_PRIMA_API_BASE= npx astro build warns PUBLIC_PRIMA_API_BASE is not set and grep -c 'Nicht konfiguriert' dist/anmelden/index.html prints 1 with no <form in the file; PRIMA_REQUIRE_API_BASE=1 PUBLIC_PRIMA_API_BASE= npx astro build exits non-zero; PUBLIC_PRIMA_API_BASE=http://api.example.com npx astro build exits non-zero (non-local http).
5. Browser walk-through against dist/ served statically (tooling/verify/astro-static.sh <site> /anmelden --serve) with the API mocked: (a) /anmelden: type a@b, submit, observe the red outline and "Bitte geben Sie eine gültige E-Mail-Adresse ein." with no request sent; (b) type any address, mock 202, observe "Prüfen Sie Ihren Posteingang", the address in bold, the form gone, focus on the panel; click "Andere Adresse verwenden", observe the empty form back; (c) mock 403, observe the surface_denied sentence and the form still present; (d) open /auth/magic-link?token=abc, observe the address bar /anmelden/verify with no token in the query and then, after the mocked 200, sessionStorage holding prima.dev.session.v1 and the page leaving for /schluessel/; (e) /anmelden/verify#token=abc with a mocked 400, observe "Anmeldung fehlgeschlagen", the three-cause sentence and "Neuen Link anfordern"; (f) /registrieren, mock 202 with expires_in_minutes: 30, observe "läuft nach 30 Minuten ab"; mock 202 without it, observe "nur für kurze Zeit"; (g) /signup/confirm#token=abc with a mocked 201 carrying api_key, observe "Einmalig", the key in exactly one element (document.body.innerText.split(key).length === 2), sessionStorage without it, the curl block reading $PRIMA_API_KEY; reload, observe the key gone and "Bestätigung fehlgeschlagen" for the now-spent mock; (h) mocked 409, observe "Zur Anmeldung".
6. Demo gate: npm run check prints no line for this recipe; in the prima.li checkout, PRIMA_MODULES_DIR=<this repo> npm run build:index writes dist/docs/modules/identity-auth/ui/developer-portal-auth-pages/index.html, and opened in Playwright the page has seventeen figure[data-demo-state] elements each with a .dpa child, pageerror count 0, .auth__status in the signin frame matching :empty with computed display: none, no .auth__status in the magic-link-forward frame, and the page URL unchanged after a click on the signin frame's submit button (verified 2026-09-12 against prima.li at 86fe9d1).
7. Verifier: node tooling/verify/compare.mjs identity-auth/ui/developer-portal-auth-pages --state signin --docs http://127.0.0.1:4321 --app http://127.0.0.1:4320 --app-repo <prima-developer> with the portal served by astro-static.sh and built with a configured base; the report's page_errors is empty on both sides and mismatch_ratio is read for the card only, excluding by name the site header and footer (not in the demo), the font (the portal self-hosts Helvetica Now, the docs host renders the token stack) and the purple (#6844C4 on the portal, #6642C1 in prima-tokens; RENDERING.md section 7).