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

README.md

@@ -52,6 +52,43 @@ Format code:
 make format
 ```
 
+## Sign-in and saved work (v3 workspace)
+
+The v3 workspace (the flagship shell: Ask, Build, Reforms, reports and the
+account page) can sign users in with social sign-on (Auth0) and save their
+reforms and reports to their PolicyEngine account through the PolicyEngine
+API (`/v2/me` and `/v2/user-*`). It is off unless all of these are set at
+build time (see `calculator-app/.env.example`), alongside
+`NEXT_PUBLIC_FLAGSHIP_SHELL=true`:
+
+| Variable | Purpose |
+| --- | --- |
+| `NEXT_PUBLIC_AUTH_ENABLED` | `true` turns sign-in on |
+| `NEXT_PUBLIC_AUTH0_DOMAIN` | Auth0 (custom) domain |
+| `NEXT_PUBLIC_AUTH0_CLIENT_ID` | SPA application for the environment |
+| `NEXT_PUBLIC_AUTH0_AUDIENCE` | PolicyEngine API resource server identifier |
+| `NEXT_PUBLIC_API_URL` | PolicyEngine API origin (default `https://api.policyengine.org`); set to the staging API on staging |
+
+- On the US and UK workspace, saved reforms and reports always go to the
+  PolicyEngine API. Signed in, they belong to the account. Signed out, they
+  belong to this browser's unauthenticated user: a random UUID made on the
+  first visit, kept in localStorage (`pe-browser-user-id`) with no expiry,
+  and sent as the `PolicyEngine-Unauthenticated-User` header. It is the
+  credential for that work, so it never goes in a URL or a log.
+- A saved reform is a pointer to its PolicyEngine API policy (with its
+  name, baseline and origin); its changes are read back from the policy.
+  Running a report creates its policy, simulations and report in the API.
+- Signing in upgrades the browser's unauthenticated user
+  (`POST /v2/me/upgrade`): on a first sign-in it becomes the account, so
+  everything saved stays; for an existing account its work moves into that
+  account. The browser then starts over with a new UUID. A failed upgrade
+  keeps the UUID, so the next sign-in tries again.
+- With sign-in off, and outside the US and UK, saved work stays in this
+  browser, in v3's own keys.
+- The legacy calculator (policies, households, simulations and reports
+  built outside the workspace) has no sign-in and keeps its saved work in
+  localStorage, as before. v3 never reads or writes that storage.
+
 ## Project structure
 
 ```

app/package.json

@@ -35,7 +35,7 @@
     "chromatic": "VITE_APP_MODE=website chromatic --only-changed --build-script-name='storybook:build'"
   },
   "dependencies": {
-    "policyengine-household-wizard": "^0.1.0",
+    "@auth0/auth0-react": "2.27.0",
     "@policyengine/ui-kit": "^0.4.0",
     "@reduxjs/toolkit": "^2.8.2",
     "@tabler/icons-react": "^3.34.0",
@@ -53,6 +53,7 @@
     "html-to-image": "^1.11.13",
     "jsonp": "^0.2.1",
     "lucide-react": "^0.575.0",
+    "policyengine-household-wizard": "^0.1.0",
     "radix-ui": "^1.4.3",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",