Stage 12A: Check Auth0 permissions on Simulation Entrypoint routes

[anth-volk]

Fixes #759

Same-Repository Draft PR Check

• This PR is a draft.
• This PR is from a branch in PolicyEngine/policyengine-sim-api, not a personal fork.

Summary

• Handlers now receive the caller's identity. Protected routes get the validated CallerIdentity, which used to be parsed and discarded.
• Auth0 permissions per route:
  • simulation:submit: POST /simulate/economy/comparison and POST /simulate/economy/budget-window.
  • simulation:read: GET /jobs/{job_id} and GET /budget-window-jobs/{batch_job_id}.
  • stage12:operate: both /internal/stage12/* routes.
• How a permission is matched: exact matches only, from the RBAC permissions claim on any token. The space-delimited scope claim also counts, but only on client-credentials (machine) tokens, identified by gty (a string or a list) or an @clients subject; a gty of any other shape is ignored rather than rejecting the token. Claims are read only by their registered JWT names, so a grant_types or subject claim cannot stand in for gty or sub. Without RBAC, Auth0 copies requested API scopes into a user token's scope, so a user token's scope is ignored. Public routes are unchanged.
• SIMULATION_ENTRYPOINT_ENFORCE_PERMISSIONS, strictly 0 or 1, defaulting to 0:
  • 0 (log-only): emits simulation_entry_permission_missing with the permission and azp client ID, never tokens, and lets the request through.
  • 1: answers 403.
  • Disabled auth, which is non-production only, is always allowed.
• Deploy wiring: the deploy script and reusable workflow pass the flag from the GitHub variable SIMULATION_ENTRYPOINT_ENFORCE_PERMISSIONS; unset means 0. The deployed auth tests receive it too.
• Deployed check: a new authenticated test runs only when enforcement is 1. It confirms the deployed test client, which must not hold stage12:operate, gets 403 from a Stage 12 route.
• Docs: the README and DEPLOYMENT docs cover the permission table, the modes, the Auth0 prerequisites, and rollout and rollback. Beta never promotes its candidate, so missing API v1 grants can only be seen in prod's log-only events; the rollout steps say so.

Before setting enforcement to 1: on the shared entrypoint API in Auth0, enable RBAC and "Add Permissions in the Access Token". Then grant:

• simulation:submit and simulation:read to the API v1 client and to the deployed test client (but not stage12:operate to the test client);
• stage12:operate to the Stage 12 operator client.

Wait one access-token lifetime with no log-only events before flipping, because cached tokens don't carry new grants. The API v1 client uses a single GATEWAY_AUTH_AUDIENCE for both the old gateway and the entrypoint.

Testing

• uv run pytest tests/ (entry project): 233 passed. Before this change there were 158. The new tests cover:
  • the per-route permission matrix;
  • permissions vs scope claims, including near misses, and scope being ignored on user tokens, including signed user tokens with string, list and malformed gty, and tokens whose grant_types or subject claims try to stand in for gty or sub;
  • log-only vs enforced;
  • disabled auth;
  • public routes staying public;
  • telemetry failure not changing the response.
• ruff format --check src tests authenticated_tests is clean.
• ruff check src was already failing on main with 4 findings and now has 11. The 7 new ones are all B008, the same Depends(...)-as-default pattern as the existing Depends(_bearer).
• Pyright shows only the 2 errors already on main.
• Deployed tests were not run.

Related:

• Public API: Stage 12A: Sign-in identity and v1-anchored user associations policyengine-api#3891
• app v3: Stage 12A: Sign in to app v3 and save work to the account policyengine-app-v2#1252

🤖 Generated with Claude Code