Stage 12A: Sign in to app v3 and save work to the account

[anth-volk]

Fixes #1253

Summary

Stage 12A of the unified API migration, app side. App v3 (the flagship workspace, US and UK) gets a standard sign-in flow using Auth0 social sign-on, and every v3 reform and report is saved through the Public API: signed in to the account, signed out to this browser's unauthenticated user.

Only app v3 gets accounts. The legacy calculator is unchanged from main and stays browser-only. Canada, Nigeria and Israel stay browser-only too, and so does v3 with accounts off. Everything sits behind NEXT_PUBLIC_AUTH_ENABLED, which is off by default.

• Two states: signed in and signed out.
  • The state comes only from the Auth0 session. The auth provider is mounted only in the v3 workspace, and shows a loading state while Auth0 restores the session, so nothing below it sees an in-between state.
  • Tokens are held in memory, refresh tokens rotate, and the callback route only returns to same-origin paths.
  • The menu identity comes from the ID token. If a token can't be renewed, the user is signed out locally and the menu asks them to sign in again; their unsaved draft stays for them. Any other token failure (timeout, network) leaves the session signed in and reports that sign-in could not be reached.
  • The draft is kept with the account that had it signed in, by a fingerprint of its subject. A page that loads signed out drops a draft left by a session that expired between visits, a different account signing in drops the previous one's, and signing out clears it.
  • The callback drops ?code&state once handled, so a reload does not replay a used code.
• Signed in:
  • v3 reforms are /v2/user-policies rows with provenance, each pointing at a v1 policy.
  • v3 reports are /v2/user-reports rows with the v3 fields (title, source note, provisions with their growth settings, validation, the reform it was run from, the saved reform it was compared with, budget-window years), each pointing at a v1 report. The report page rebuilds its header, budget window and comparison from the row, so they survive a reload and open on any device; the comparison's name is the linked saved reform's, looked up by the Public API, so no name is stored on the report.
  • The server stamps the owner, so the app never sends a user_id.
  • Failures are ordinary per-request errors; nothing falls back to browser storage. The API stores accept only API IDs (a browser-only ID is refused before any v1 policy is created for it).
• Signed out (accounts on, US and UK): the same Public API routes and stores, as this browser's unauthenticated user.
  • On the first visit the browser gets a random UUID, kept in localStorage (pe-browser-user-id) with no expiry and sent as PolicyEngine-Unauthenticated-User. The Public API keeps the work under an unauthenticated user with that ID, created on its first write. The UUID is the credential for that work, so it never goes in a URL or a log.
  • Nothing saved lives only in the browser, and nothing is copied anywhere at sign-in.
• Upgrade at sign-in: the callback calls POST /v2/me/upgrade with the session and the browser's user. A first sign-in converts that user into the account (same user, so every saved reform and report stays); an existing account takes over its work. The browser then starts over with a new UUID, so the next person signed out here starts empty. A failed upgrade keeps the UUID (so the next sign-in tries again) and offers "Try again".
• Accounts off, and outside the US and UK: v3 uses only its own localStorage keys (reforms, pe-flagship-reports, pe-flagship-report-meta), as on main; saving a reform creates its v1 policy first and keeps the policy ID. Nothing from that storage is copied into the Public API.
• No labels on base records: the v1 policies v3 creates (report runs, saved reforms, the bill page's calculation) carry only their changes; names and titles live only on the user's records. The v1 policy route deduplicates on country, changes and label, so identical changes now share one policy, one pair of simulations and one report per year. Simulations and reports never carried labels.
• Everywhere: v3 no longer reads or writes the legacy calculator's keys, and no longer opens old sur- links, which only ever resolved in the browser that created them.
• Report links are shareable:
  • With accounts (US and UK, signed in or out), a report's URL is its /v2/user-reports row ID. Whoever opens it (signed in, signed out, or another user) reads the row through the Public API's credential-free /v2/shared-reports/{id} and sees the owner's title, source note, provisions, budget window, comparison and validation pin over the v1 report the row points at.
  • Only the session that ran the report links "Edit the reform" to its saved reform and pins the validation; anyone else editing it saves a new reform of their own.
  • Identical changes share one v1 report, so its number never named one run. Where accounts exist, a link carrying a v1 report's number is an old one and no longer opens.
  • Without accounts (sign-in off, or Canada, Nigeria and Israel) nothing is shared, so the link stays the v1 report's number, and others see the results with the provisions rebuilt from the policy, without the title.
• UI: sign-in or the user menu appears in the v3 top bar, US and UK only. The account page (/[country]/account, in the v3 shell) offers "Download my data" and "Delete my account"; on ca, ng and il it points to the US and UK calculators instead of offering sign-in. The sign-in upgrade notice is a v3 panel under the top bar, and the top bar's "More" menu sits with Build and Reforms.
• Every reform report is linked to a saved reform:
  • Build's run button is now "Save and run {year} report". It saves the draft first, exactly as Save does (changing the reform the draft came from, or saving a new one), then runs the report linked to that reform. A failed save runs nothing, and it waits while a Save is pending.
  • If the reform the draft edits is gone from this session's store (deleted, or belonging to another user), saving saves the draft as a new reform.
  • "Edit the reform" on a report that failed to calculate keeps the saved reform it was run from, so saving the edit changes that reform.
  • "View full impact report" on a saved reform links the report to it, and runs the reform as Build does: dated changes go with it (it used to send only each parameter's first value), and parameters left at current law stay out.
  • A reform whose values all match current law can't be run from the Reforms page, and the report page's Recompute waits until a value differs from current law; both say why, as Build already did.
  • Bill reports from the "In Congress" tab are unchanged and unlinked: an enacted bill is compared with the law before it.
• Reforms list: each reform's v1 policy loads separately and is cached for the session, so one failure shows "Changes could not be loaded" on that reform instead of breaking the list.
• BASE_URL reads NEXT_PUBLIC_API_URL / VITE_API_URL, defaulting to production, so staging builds talk to the staging API.
• Removed: the Next.js Drizzle / Neon database path (api/{reforms,reports}, calculator-app/src/db, DATABASE_URL, PGlite tests), including the edit-token ownership that landed on main on 13–14 October (libs/flagship/ownedItems, migration 0003_anonymous-ownership). v3 storage is the Public API (or the browser with accounts off), so that path is not merged.
• Merged from main a third time (15 October): the v3 audit (App v3: fix where the feature PRs overlap #1273, Validation: baseline comparisons for the programs the reform changes #1274, Reforms: tracker bill stages stay the same on every load #1277, Bill feed: complete stages, matching run settings and named fiscal notes #1278, Fix v3 bill budget label, reform delete, chart labels and accessibility #1280, Fix v3 report content: shared-link dates, NaN labels, people wording, downloads, phone names, district decimals #1281, Report: run and report lifecycle fixes from the v3 audit #1283, Build: fixes from the v3 audit #1284, v3 run bar: hold the time estimate inside the API's reported stage #1285), run progress from the API, a complete report opening from its stored output and a failed run recorded on its v1 report, the wait for the reform policy, the report year switcher and All years view (Report: switch a budget window report between its years #1292), dated edits in the adjust panel (Report: adjust each period of a multi-year reform; keep the window #1294), each country's own draft, and Your reforms' read-only reform detail with its parameters table, "View results", "Re-run" and delete prompt (Reforms: view or re-run a saved report; parameters as a table #1288). A report opened by its link loads the v1 report the saved report names (legacy_report_id) and gets the same stored output and run lifecycle as a link without accounts. Adapted to this PR:
  • "View results", "Open" and "View full impact report" go to the report's link (reportLink), never the v1 report's number.
  • Re-run keeps an account report's year (read from its v1 report), budget window (the row's budgetWindowYears) and comparison (the row's baselineReformId: the baseline policy the report ran, named from the saved reform), and links the new run to the same saved reform. A report kept in this browser still reads its run details by the v1 report's number, which is its link. When the comparison's policy can't be found, nothing runs rather than compare with current law. "View full impact report" reopens an account report of the same values the same way.
  • Build's run stays "Save and run" (a failed save runs nothing); it now saves only the values that differ from current law and leaves a reused reform, and its name, as it is. The reform detail keeps this PR's guards (changes that did not load, or a reform that changes nothing, cannot run).
  • Signing out, a signed-out load after an expired session, and another account signing in now clear every country's draft, not only the one in hand. The budget-window years asked for on a saved report's link stay in memory for the page session, not in browser storage, since the link opens the report for anyone.
  • A failed run and the stored output are written only to the v1 report (as stored output already was), never to the user's report row; the validation pin stays the only write to the row, and only from the session that ran it.
• Merged from main again (15 October): comparing a reform with a saved reform (Build's baseline picker, the run, the report's labels and adjust panel), growth settings on provisions, the versioned report schema for stored records and run details (and the "details can't be read" state), report load errors with not-found and retry, phone layouts, the bill filters and the chart fixes. Account rows are read through the same report schema as browser records. The baseline picker lists this session's saved reforms (the account's or this browser's). Neither the reform nor the baseline policy carries a label. The calculator-app report routes, their tests, and the schema helpers that only served them stay removed.
• Merged from main (14 October): the run bar (year and budget window, population with states and congressional districts), indexing in a pop-up, the editable title; "a run keeps its reform" (reuse a saved reform with the same values), reports listed under each saved reform, in-place edits that keep dated values, a saved reform's report run in the reform's own year; the report page's renaming, population and "Edit in Build" in the adjust panel, progress bar, budget window and no-change notice. Store methods follow main's names (findMine(countryId), findByApiReportId(apiReportId)), and names sent to the Public API are clamped to its 255-character limit (notes to 10,000) so a long bill title can't fail a save.
• Dependencies: the Auth0 SDK dependencies are pinned to releases more than two weeks old (@auth0/auth0-spa-js 2.27.0, @auth0/auth0-auth-js 1.15.0).

Environment

Auth0 (policyengine.uk.auth0.com, custom domain auth.policyengine.org pending DNS) has two v3 single-page apps, each with Google, Microsoft and GitHub sign-in and no password sign-up:

• "PolicyEngine v3 staging" (aHhxCvUHwCwCNZekW4yRX6hiGCF9kFYS) for this branch's preview alias (policyengine-calculator-next-git-feat-v3-u-70c7ce-policy-engine.vercel.app) and http://localhost:3001;
• "PolicyEngine v3 production" (LZBiZVIVG3sLzX66neu2RsE7rUDBDHjX) for https://app.policyengine.org.

Both allow <origin>/us/callback and <origin>/uk/callback, log out to <origin>/us and <origin>/uk, and rotate refresh tokens (30 days absolute, 7 days idle). The audience is https://api.policyengine.org/, now with offline access.

Vercel (policyengine-calculator-next):

• Set: NEXT_PUBLIC_AUTH0_DOMAIN=auth.policyengine.org, NEXT_PUBLIC_AUTH0_CLIENT_ID and NEXT_PUBLIC_AUTH0_AUDIENCE=https://api.policyengine.org/, in Production and in Preview for this branch only. They do nothing while sign-in is off. There is no fixed staging alias (the one custom environment, app-preview, serves another review), so this branch's preview is the staging app.
• After the Public API PR is on staging and the custom domain is verified: set NEXT_PUBLIC_AUTH_ENABLED=true and NEXT_PUBLIC_API_URL=https://policyengine-api-staging-43j3ckhyaa-uc.a.run.app in Preview for this branch, and redeploy it. Until then the preview stays browser-only, so reviewers can use it.
• Production: sign-in stays off until rollout. (NEXT_PUBLIC_FLAGSHIP_SHELL is not set in Production either.)
• Clean-up: none; the project has no DATABASE_URL.

Known limitations

• On a shared browser, whoever signs in next takes over the work saved there while signed out.
• Clearing the browser's storage loses the UUID, and with it access to that browser's signed-out work (which stays in the database, unreachable).
• Work saved in browser storage before accounts are turned on (US and UK) is not copied into the Public API and no longer shows.
• A tab still open signed out after another tab signs in gets 401s until it reloads: its UUID now belongs to the account.
• If the upgrade succeeds on the server but its response is lost, the browser keeps the converted UUID; signed out it then gets 401s until the next sign-in, whose upgrade returns none and starts the browser over.
• A report run fails if its record can't be saved, signed in or out.
• Anyone holding a report's link can read its title, source note and provisions. A link can't be made private, and deleting the report (or the account) breaks it.

Testing

• bun install --frozen-lockfile passes with bun 1.2.21.
• app: lint (eslint and stylelint) and typecheck pass; prettier passes on every file this PR touches. vitest: 4870 passed, 10 skipped, after the second merge of main. One test was updated for main's new adjust-panel labels.
• calculator-app: typecheck and next build pass, including the /[countryId]/account and /[countryId]/callback routes.
• After the shareable links (bun 1.4.2): app lint, typecheck and prettier pass, vitest has 4889 passed, 10 skipped, and calculator-app typecheck passes. next build was not rerun.
• After the third merge of main (bun 1.4.2): app lint and typecheck pass, prettier passes on every file the merge touched, and vitest has 5160 passed, 10 skipped. calculator-app typecheck and next build pass.
• New tests cover:
  • re-runs and reopening after the third merge: an account report's re-run keeps its year (from the v1 report), window and comparison (the policy it ran, named from the saved reform) and links the same reform; a browser report's re-run reads its run details by the v1 report's number; a comparison whose policy can't be read falls back to the saved reform's policy, or runs nothing; "View results" and "View full impact report" open the row's link; the compared reform is named after a reload; set-aside drafts are cleared with the session and a saved report's requested years stay out of browser storage;
  • shareable links: a saved report's link opens for someone who didn't run it (sign-in off, or signed out) with the owner's title, sending no credential; a deleted report is not found; a v1 report link where accounts exist and an old sur- link no longer open, while a v1 report link with sign-in off still does; a signed-in run opens at its row's link; "Open" in Your reforms follows the row ID (or the v1 report without accounts); someone else's report shows the owner's validation pin and pins nothing; the session's own row is read by link and another user's is not;
  • the provider's restore gate, the two states, the session-ended path (draft kept), an unreachable sign-in service, the draft dropped after a session that expired between visits or when another account signs in, and the used code leaving the address bar;
  • store choice: the account when signed in, the browser's unauthenticated user when signed out (with the header and no bearer), the browser with accounts off or outside the US and UK;
  • the browser's user ID (made once, kept, replaced after an upgrade, and page-only when storage is blocked);
  • the upgrade at sign-in: converted or merged (notice, new browser ID), nothing to upgrade (no notice), and a failure (browser ID kept, "Try again" upgrades it);
  • a signed-out save creating the v1 policy and keeping its ID, a rename keeping it, a parameter change replacing it, and a failed policy creation storing nothing;
  • a browser-mode run writing only v3 keys, and v3 reading no legacy key;
  • the sur- not-found message and the browser-ID message;
  • per-reform load failures;
  • save-then-run from Build (save before run, the report linked to the saved reform, an edited saved reform changed rather than copied, a failed save running nothing, no second save while one is pending, a missing reform saved as new), and a saved reform's run linked and keeping its dated changes;
  • no report run for a reform or adjustment that changes nothing, and the account page on ca, ng and il;
  • the legacy headers having no sign-in UI;
  • the v2 client, the API stores and the mappers, including the Authorization and unauthenticated-user headers and body shapes;
  • the budget window on the report row: sent for a window of two or more years, omitted for one, and read back into the report's run details from the report's year;
  • the compared reform: linked on the row only when it is an account reform, recorded by a run, never sent by name, and carried into the rebuilt run details;
  • growth settings round-tripping through the wire mapping, and account rows read through the report schema (an unreadable row left out of a list, and a typed error when opened).
• No end-to-end run against Auth0 or the staging API yet. That depends on the API PR and the Auth0 setup.

Related

• Public API (required first, including /v2/shared-reports): Stage 12A: Sign-in identity and v1-anchored user associations policyengine-api#3891
• Simulation Entrypoint permissions: Stage 12A: Check Auth0 permissions on Simulation Entrypoint routes policyengine-sim-api#758

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
policyengine-calculator-next	Ready	Preview	Oct 15, 2026 8:43pm UTC
policyengine-website	Ready	Preview	Oct 15, 2026 8:43pm UTC