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

.github/scripts/deploy_cloud_run_candidate.sh

@@ -44,8 +44,21 @@ env_vars=(
   "V2_SUPABASE_PROJECT_REF=${V2_SUPABASE_PROJECT_REF}"
   "V2_SUPABASE_ENVIRONMENT=${V2_SUPABASE_ENVIRONMENT}"
   "V2_RUNTIME_DATABASE_URL_SECRET_RESOURCE=${V2_RUNTIME_DATABASE_URL_SECRET_RESOURCE}"
+  "PUBLIC_API_AUTH_REQUIRED=${PUBLIC_API_AUTH_REQUIRED}"
+  "PUBLIC_API_AUTH_ISSUER=${PUBLIC_API_AUTH_ISSUER:-}"
+  "PUBLIC_API_AUTH_AUDIENCE=${PUBLIC_API_AUTH_AUDIENCE:-}"
 )
 
+# Optional: account deletion removes the Auth0 user only when the Management
+# API client is configured. Validation requires all three values or none.
+if [[ -n "${AUTH0_MANAGEMENT_DOMAIN:-}" ]]; then
+  env_vars+=(
+    "AUTH0_MANAGEMENT_DOMAIN=${AUTH0_MANAGEMENT_DOMAIN}"
+    "AUTH0_MANAGEMENT_CLIENT_ID=${AUTH0_MANAGEMENT_CLIENT_ID}"
+    "AUTH0_MANAGEMENT_CLIENT_SECRET_RESOURCE=${AUTH0_MANAGEMENT_CLIENT_SECRET_RESOURCE}"
+  )
+fi
+
 if [[ -n "${OLD_SIMULATION_GATEWAY_URL:-}" ]]; then
   env_vars+=("OLD_SIMULATION_GATEWAY_URL=${OLD_SIMULATION_GATEWAY_URL}")
 fi

.github/scripts/validate_cloud_run_deploy_env.sh

@@ -56,7 +56,8 @@ cloud_run_require_env \
   GATEWAY_AUTH_ISSUER \
   GATEWAY_AUTH_AUDIENCE \
   GATEWAY_AUTH_CLIENT_ID \
-  GATEWAY_AUTH_CLIENT_SECRET_RESOURCE
+  GATEWAY_AUTH_CLIENT_SECRET_RESOURCE \
+  PUBLIC_API_AUTH_REQUIRED
 
 for selector in \
   ROUTE_IMPL_HEALTH \
@@ -110,6 +111,51 @@ case "${DB_WRITE_HOUSEHOLD}" in
     ;;
 esac
 
+# Signed-in user routes fail closed without Auth0 settings. When required,
+# the issuer and audience must be present; otherwise they are set together
+# or not at all.
+case "${PUBLIC_API_AUTH_REQUIRED}" in
+  0|1) ;;
+  *)
+    printf '%s=%s is invalid; expected 0 or 1\n' \
+      "PUBLIC_API_AUTH_REQUIRED" "${PUBLIC_API_AUTH_REQUIRED}" >&2
+    exit 1
+    ;;
+esac
+if [[ "${PUBLIC_API_AUTH_REQUIRED}" == "1" ]]; then
+  cloud_run_require_env PUBLIC_API_AUTH_ISSUER PUBLIC_API_AUTH_AUDIENCE
+fi
+if [[ -n "${PUBLIC_API_AUTH_ISSUER:-}" && -z "${PUBLIC_API_AUTH_AUDIENCE:-}" ]] \
+  || [[ -z "${PUBLIC_API_AUTH_ISSUER:-}" && -n "${PUBLIC_API_AUTH_AUDIENCE:-}" ]]; then
+  echo "Set both PUBLIC_API_AUTH_ISSUER and PUBLIC_API_AUTH_AUDIENCE, or neither" >&2
+  exit 1
+fi
+if [[ -n "${PUBLIC_API_AUTH_ISSUER:-}" && "${PUBLIC_API_AUTH_ISSUER}" != https://* ]]; then
+  echo "PUBLIC_API_AUTH_ISSUER must be an absolute HTTPS URL" >&2
+  exit 1
+fi
+
+auth0_management_count=0
+for name in \
+  AUTH0_MANAGEMENT_DOMAIN \
+  AUTH0_MANAGEMENT_CLIENT_ID \
+  AUTH0_MANAGEMENT_CLIENT_SECRET_RESOURCE; do
+  if [[ -n "${!name:-}" ]]; then
+    auth0_management_count=$((auth0_management_count + 1))
+  fi
+done
+if (( auth0_management_count != 0 && auth0_management_count != 3 )); then
+  echo "Set AUTH0_MANAGEMENT_DOMAIN, AUTH0_MANAGEMENT_CLIENT_ID, and AUTH0_MANAGEMENT_CLIENT_SECRET_RESOURCE together, or none" >&2
+  exit 1
+fi
+# The staging live test deletes its own account through DELETE /v2/me. With
+# Management API deletion configured, that would delete the CI user from
+# Auth0, so only production may configure it.
+if (( auth0_management_count != 0 )) && [[ "${DEPLOYMENT_ENVIRONMENT}" != "production" ]]; then
+  echo "AUTH0_MANAGEMENT_* settings are production-only; unset them for ${DEPLOYMENT_ENVIRONMENT}" >&2
+  exit 1
+fi
+
 selected_url_env="$(
   simulation_entrypoint_url_env_name "${SIM_ENTRYPOINT}"
 )"

.github/workflows/push.yml

@@ -207,6 +207,9 @@ jobs:
       DB_WRITE_POLICY: ${{ vars.DB_WRITE_POLICY }}
       DB_READ_HOUSEHOLD: ${{ vars.DB_READ_HOUSEHOLD }}
       DB_WRITE_HOUSEHOLD: ${{ vars.DB_WRITE_HOUSEHOLD }}
+      PUBLIC_API_AUTH_REQUIRED: ${{ vars.PUBLIC_API_AUTH_REQUIRED }}
+      PUBLIC_API_AUTH_ISSUER: ${{ vars.PUBLIC_API_AUTH_ISSUER }}
+      PUBLIC_API_AUTH_AUDIENCE: ${{ vars.PUBLIC_API_AUTH_AUDIENCE }}
       CLOUD_RUN_SERVICE: policyengine-api-staging
       CLOUD_RUN_RUNTIME_CACHE_ENVIRONMENT: staging
       CLOUD_RUN_RUNTIME_CACHE_URL_SECRET: policyengine-api-staging-runtime-cache-url:latest
@@ -251,7 +254,7 @@ jobs:
         run: >-
           env -u DEPLOYMENT_ENVIRONMENT -u ROUTE_IMPL_HEALTH -u ROUTE_IMPL_SPECIFICATION -u ROUTE_IMPL_METADATA -u ROUTE_IMPL_POLICY -u ROUTE_IMPL_HOUSEHOLD -u DB_READ_POLICY -u DB_WRITE_POLICY -u DB_READ_HOUSEHOLD -u DB_WRITE_HOUSEHOLD
           -u CLOUD_RUN_SERVICE -u CLOUD_RUN_RUNTIME_CACHE_ENVIRONMENT -u CLOUD_RUN_RUNTIME_CACHE_URL_SECRET -u CLOUD_RUN_RUNTIME_CACHE_CA_CERT_SECRET -u CLOUD_RUN_POLICYENGINE_DB_PASSWORD_SECRET -u CLOUD_RUN_MIN_INSTANCES -u CLOUD_RUN_SERVICE_MIN_INSTANCES -u CLOUD_RUN_MAX_INSTANCES
-          -u V2_SUPABASE_PROJECT_REF -u V2_SUPABASE_ENVIRONMENT -u V2_RUNTIME_DATABASE_URL_SECRET_RESOURCE -u PRODUCTION_V2_SUPABASE_PROJECT_REF -u PRODUCTION_V2_RUNTIME_DATABASE_URL_SECRET_RESOURCE -u PRODUCTION_POLICYENGINE_DB_INSTANCE_CONNECTION_NAME make test
+          -u V2_SUPABASE_PROJECT_REF -u V2_SUPABASE_ENVIRONMENT -u V2_RUNTIME_DATABASE_URL_SECRET_RESOURCE -u PRODUCTION_V2_SUPABASE_PROJECT_REF -u PRODUCTION_V2_RUNTIME_DATABASE_URL_SECRET_RESOURCE -u PRODUCTION_POLICYENGINE_DB_INSTANCE_CONNECTION_NAME -u PUBLIC_API_AUTH_REQUIRED -u PUBLIC_API_AUTH_ISSUER -u PUBLIC_API_AUTH_AUDIENCE make test
         env:
           RUNTIME_CACHE_MODE: local
           RUNTIME_CACHE_URL: redis://127.0.0.1:6379/0
@@ -326,6 +329,14 @@ jobs:
           API_BASE_URL: ${{ steps.candidate.outputs.url }}
           STAGING_API_TEST_PROBE_ID: cloud-run-${{ steps.cloud_run.outputs.revision_tag }}
           V2_MIGRATION_DATABASE_URL: ${{ secrets.V2_MIGRATION_DATABASE_URL }}
+          # Staging-only Auth0 CI application (password grant) and test user.
+          STAGING_AUTH0_TEST_DOMAIN: ${{ vars.STAGING_AUTH0_TEST_DOMAIN }}
+          STAGING_AUTH0_TEST_AUDIENCE: ${{ vars.STAGING_AUTH0_TEST_AUDIENCE }}
+          STAGING_AUTH0_TEST_CLIENT_ID: ${{ secrets.STAGING_AUTH0_TEST_CLIENT_ID }}
+          STAGING_AUTH0_TEST_CLIENT_SECRET: ${{ secrets.STAGING_AUTH0_TEST_CLIENT_SECRET }}
+          STAGING_AUTH0_TEST_USERNAME: ${{ secrets.STAGING_AUTH0_TEST_USERNAME }}
+          STAGING_AUTH0_TEST_PASSWORD: ${{ secrets.STAGING_AUTH0_TEST_PASSWORD }}
+          STAGING_AUTH0_TEST_REALM: ${{ vars.STAGING_AUTH0_TEST_REALM }}
 
   parallel-live-simulation-tests-staging-cloud-run:
     name: Run live simulations against the staging candidate
@@ -491,6 +502,12 @@ jobs:
       DB_WRITE_POLICY: ${{ vars.DB_WRITE_POLICY }}
       DB_READ_HOUSEHOLD: ${{ vars.DB_READ_HOUSEHOLD }}
       DB_WRITE_HOUSEHOLD: ${{ vars.DB_WRITE_HOUSEHOLD }}
+      PUBLIC_API_AUTH_REQUIRED: ${{ vars.PUBLIC_API_AUTH_REQUIRED }}
+      PUBLIC_API_AUTH_ISSUER: ${{ vars.PUBLIC_API_AUTH_ISSUER }}
+      PUBLIC_API_AUTH_AUDIENCE: ${{ vars.PUBLIC_API_AUTH_AUDIENCE }}
+      AUTH0_MANAGEMENT_DOMAIN: ${{ vars.AUTH0_MANAGEMENT_DOMAIN }}
+      AUTH0_MANAGEMENT_CLIENT_ID: ${{ vars.AUTH0_MANAGEMENT_CLIENT_ID }}
+      AUTH0_MANAGEMENT_CLIENT_SECRET_RESOURCE: ${{ secrets.AUTH0_MANAGEMENT_CLIENT_SECRET_RESOURCE }}
       CLOUD_RUN_SERVICE: policyengine-api
       CLOUD_RUN_RUNTIME_CACHE_ENVIRONMENT: production
       CLOUD_RUN_RUNTIME_CACHE_URL_SECRET: policyengine-api-prod-runtime-cache-url:latest

.github/workflows/seed-v2-database.yml

@@ -46,6 +46,10 @@ jobs:
         run: uv run python scripts/qualify_v2_household_migration.py
         env:
           V2_MIGRATION_DATABASE_URL: ${{ secrets.V2_MIGRATION_DATABASE_URL }}
+      - name: Qualify the pending user-association reshape
+        run: uv run python scripts/qualify_v2_user_association_migration.py
+        env:
+          V2_MIGRATION_DATABASE_URL: ${{ secrets.V2_MIGRATION_DATABASE_URL }}
       - name: Upgrade and verify the v2 schema
         run: bash .github/scripts/migrate_v2_metadata_schema.sh
         env:

.github/workflows/v2-integration-check.yml

@@ -75,6 +75,8 @@ jobs:
         run: uv run coverage run -a --branch -m pytest -q tests/integration/test_v2_catalog_publication.py tests/integration/test_v2_metadata_routes.py
       - name: Test v2 policy persistence and immediate v1 mirroring
         run: uv run coverage run -a --branch -m pytest -q tests/integration/test_v2_policy_persistence.py tests/integration/test_v1_policy_dual_write.py tests/integration/test_mysql_policy_dual_write.py tests/integration/test_v2_user_policy_mirroring.py tests/integration/test_v1_user_policy_dual_write.py
+      - name: Test signed-in identity provisioning and user associations
+        run: uv run coverage run -a --branch -m pytest -q tests/integration/test_v2_user_identity_persistence.py
       - name: Test v2 household persistence and immediate v1 copying
         run: uv run coverage run -a --branch -m pytest -q tests/integration/test_v2_household_persistence.py tests/integration/test_v1_household_dual_write.py tests/integration/test_mysql_household_spm_dual_write.py
       - name: Qualify production-scale v2 metadata publication

AGENTS.md

@@ -79,6 +79,7 @@ To add or change a rule, read `docs/engineering/skills/rules-registry.md`.
 - `api.v2.routes-no-sessions-or-sql`: v2 route modules never open database sessions or construct SQL; they call one service method and map typed failures to HTTP. (doc-only, not checked: follow it yourself)
 - `api.v2.services-no-sql`: v2 services sequence work but never construct SQL expressions, call Session.exec, or define HTTP response models. (doc-only, not checked: follow it yourself)
 - `api.v2.session-modules-no-queries`: v2 database_session modules own session lifetime only and never build select, insert, update, delete or exec calls. (blocking: pytest `tests/unit/v2/test_data_crud_boundaries.py`)
+- `api.v2.user-services-no-sql`: v2 user services (identity, accounts, legacy references and user associations) never build or run SQL themselves or import SQLAlchemy; their connectors do. (blocking: pytest `tests/unit/v2/test_data_crud_boundaries.py`)
 - `api.v2.validators-transformations-no-db`: v2 validators and transformations never import SQLAlchemy or SQLModel query or session APIs. (blocking: pytest `tests/unit/v2/test_data_crud_boundaries.py`)
 
 ### Runtime persistence and route boundaries
@@ -120,7 +121,7 @@ To add or change a rule, read `docs/engineering/skills/rules-registry.md`.
 
 - `api.quality.alembic-revisions-unused-imports`: Alembic revision files are exempt from unused-import checks (F401), because autogenerated revisions import types they may not use. (advisory: ruff per-file ignore of F401 for `migrations/*/versions/*.py`, not blocking)
 - `api.quality.environment-variables-load`: Required environment variables and credentials load in a deployed-like environment. (blocking: CI job `test_env_vars`)
-- `api.quality.mypy-v2`: Shared query models, FastAPI dependencies, and v2 routes and services pass mypy with untyped definitions disallowed. (blocking: mypy)
+- `api.quality.mypy-v2`: Shared query models, FastAPI dependencies, v2 routes and services, and the user sign-in and account-deletion libraries pass mypy with untyped definitions disallowed. (blocking: mypy)
 - `api.quality.ruff-format`: All Python files are formatted with ruff format. (blocking: ruff format)
 - `api.quality.ruff-lint`: Changed Python files pass ruff check with the rules selected in pyproject.toml (ruff's defaults, made explicit); agents run it before committing, but CI does not yet. (advisory: ruff check (E4, E7, E9, F), not blocking)
 - `api.quality.tests-pass`: The unit, contract and to-refactor test suites pass. (blocking: CI job `test`)

changelog.d/feat-stage-12a-user-login-associations.added.md

@@ -0,0 +1 @@
+Add Auth0 user login and signed-out saving for app v3: /v2/me (provisioning, profile, export, upgrade of a browser's unauthenticated user at sign-in, account deletion), standard and unauthenticated user types identified by a bearer token or the PolicyEngine-Unauthenticated-User header, owner-scoped v1-anchored user associations for policies, households, simulations, and reports, and the user_identities schema.