Stage 12A: Sign-in identity and v1-anchored user associations #3892

Goal

Stage 12A of the unified API migration. Users sign in to app v3 with social sign-on (Auth0). The Public API verifies their identity and saves their work as user associations that point at v1 artifacts (v1 policy, household, simulation and report IDs).

Problem

• The Public API does not authenticate inbound requests.
• /v2/user-policies and /v2/user-households are live with a caller-supplied user_id and no ownership check.
• v2 users has no link to an identity provider.
• user_simulation_associations and user_report_associations exist but are dormant. They have hard foreign keys to v2 simulations / reports, which nothing populates.

Scope

• Token validation: Auth0 RS256 bearer validation, or a signed-out browser's PolicyEngine-Unauthenticated-User UUID, plus a fail-closed require_user on /v2/me* and /v2/user-*.
• Identity:
  • user_identities, mapping (issuer, subject) to users.id;
  • users.user_type: standard or unauthenticated (a browser's signed-out user);
  • just-in-time, race-safe provisioning, with one strategy per user type;
  • GET/PATCH/DELETE /v2/me, GET /v2/me/export and POST /v2/me/upgrade (converts or merges the browser's unauthenticated user at sign-in).
• Ownership and references:
  • The owner comes from the token on all user association routes; user_id is removed from requests, and another user's row returns 404.
  • v1 references (legacy_*_id) are validated against Cloud SQL.
  • New /v2/user-simulations and /v2/user-reports.
• Persistence: one autogenerated v2 Alembic revision, all through SQLAlchemy and Alembic, with no v1 schema changes.
• Operations: a read-only qualification command, deploy and readiness settings, and a staging live test that uses an Auth0 test user.

Acceptance

• /v2/me* and /v2/user-* return 401 without a token or unauthenticated header, and 403 for machine clients. Another user's rows return 404, and the header never acts on a standard user.
• Concurrent first sign-ins create exactly one user.
• A missing v1 reference returns 422.
• The upgrade converts or merges exactly once under concurrency.
• alembic check is clean, and upgrade/downgrade both pass.
• The staging live test passes with the Auth0 test user.

Prerequisites

• GitHub variables PUBLIC_API_AUTH_REQUIRED, PUBLIC_API_AUTH_ISSUER and PUBLIC_API_AUTH_AUDIENCE.
• Staging Auth0 test secrets.
• Auth0 resource server and staging CI application.

Related

• Advances Add authentication/authorization to the API #2063 for the v2 user-owned routes. v1 /user-profile authorization is not in scope.
• PRs: Stage 12A: Sign-in identity and v1-anchored user associations #3891, Stage 12A: Check Auth0 permissions on Simulation Entrypoint routes policyengine-sim-api#758, Stage 12A: Sign in to app v3 and save work to the account policyengine-app-v2#1252