[anth-volk]

Fixes #4282

Summary

• Adds an optional, read-only settings group for Auth0 user profiles: AUTH0_USER_PROFILES_DOMAIN, AUTH0_USER_PROFILES_CLIENT_ID, and AUTH0_USER_PROFILES_CLIENT_SECRET_RESOURCE or AUTH0_USER_PROFILES_CLIENT_SECRET.
  • It is validated like the account-deletion settings and also needs PUBLIC_API_AUTH_ISSUER.
  • It shares the Management API client's code and token cache with the deletion settings.
  • build_auth0_user_profile_reader returns a read-only UserProfileReader, with no deletion.
  • The AUTH0_MANAGEMENT_* deletion settings are unchanged and stay production-only: staging's live tests delete their own account through DELETE /v2/me.
• Adds two profile reads to the client:
  • read_user_profiles: one GET /api/v2/users search per 50 user IDs (q=user_id:("…" OR "…"), search_engine=v3, sort=user_id:1, only the profile fields), with quotes and backslashes escaped.
  • search_user_ids_by_email: escapes every Lucene special character and whitespace, and uses email:*text* (or email:text* below three characters). It reads sorted pages of 50, counting each user once, and stops once more than the match limit match. A full last page counts as more than the limit.
  • Each operation sends all its requests, including the token request, through one HTTP client.
  • A 429 is retried once after the wait Auth0 gives (Retry-After first, else X-RateLimit-Reset minus now), when that wait fits in what's left of a RateLimitWaitBudget (policyengine_api.libs.rate_limit_wait_budget). Each admin request starts one 2-second budget, shared by all its Auth0 calls. A call given no budget gets its own, and a negative or non-finite wait is never taken.
  • Every failure becomes one "profiles unavailable" error that names a cause without personal data: http_<status>, timeout, connection_error, unreadable_answer, token_http_<status>, token_unreadable_answer or secret_unavailable.
• The admin user routes take email, first_name and last_name (and the history's changed_by_email) from Auth0, for identities from the users' issuer. The most recently seen identity comes first, a verified email is preferred, and stored values fill any gaps. Nothing read from Auth0 is stored.
• An email search lists users found through Auth0 together with users whose stored email matches, newest first, with the same offset, limit and has_more. It answers 422 for:
  • text with < or >, before the profile settings are read or Auth0 is called;
  • text that more than MAXIMUM_EMAIL_SEARCH_MATCHES (200) Auth0 users match ("More than 200 users match that email text; enter more of it"). Exactly 200 are served.
  • Without the profile settings, the search reads stored emails as before.
• When Auth0 can't answer, the routes return stored values and record admin_user_profiles_unavailable, with the operation, the error type and a safe cause (unknown unless it is a short identifier). A type change still commits, and an email search answers 503.
• Readiness, validate_cloud_run_deploy_env.sh, deploy_cloud_run_candidate.sh, and both deploy jobs in push.yml carry the new settings: variables for the domain and client ID, a secret for the secret resource. The Stage 12A design doc, the OpenAPI descriptions (whose limit comes from the constant), the testing skill and a changelog fragment are updated.
• The new wait-budget module is added to mypy's files and to rule api.quality.mypy-v2's paths in rules/registry.toml, with docs/generated/rules.md re-rendered. This change to the rule machinery needs approval from a core developer other than the author.
• Response shapes are unchanged. No migration contract changes, and no Flask routes are affected.

Operator steps, not in this PR:

• Create a client with only read:users in each environment's users' tenant (policyengine.uk.auth0.com for production, policyengine-dev.uk.auth0.com for staging), on the canonical *.auth0.com domain.
• Set AUTH0_USER_PROFILES_DOMAIN and AUTH0_USER_PROFILES_CLIENT_ID as GitHub environment variables, and AUTH0_USER_PROFILES_CLIENT_SECRET_RESOURCE as a GitHub environment secret, in staging and production.
• Store each client secret in Secret Manager, and grant that environment's Cloud Run runtime service account roles/secretmanager.secretAccessor on it.

Until then, admins see stored values as today. Unverified until then: the GitHub variables and secret, the Secret Manager secrets and their access grants, and each client's read:users grant.

Shares files with #4269 and #4272 (the admin routes, the user-type service and, for #4272, the Auth0 Management module); whichever merges later resolves the conflicts.

Testing

• Unit tests for the Auth0 client, using httpx.MockTransport and a recorded wait instead of sleeping; no network calls (tests/unit/libs/test_auth0_management.py). They cover:
  • the settings and the issuer requirement;
  • 50-ID groups, escaping, sorting, paging and deduplication;
  • the match limit: exactly the limit, duplicates reaching it, and a full last page;
  • < and >;
  • the 429 retry: header precedence, non-finite waits, the refreshed token, a shared budget, and a budget of its own for each call made without one;
  • one HTTP client per operation, and each failure's cause.
• Unit tests for the wait budget (tests/unit/libs/test_rate_limit_wait_budget.py): its module loads no other application module, the admin service loads it but not the Auth0 module, it spends waits that fit, and it refuses negative and non-finite ones.
• Service tests with a stand-in for Auth0 (tests/unit/v2/test_admin_user_profile_service.py). They cover:
  • filling, verified-email order, and other issuers in the list and the history;
  • stored values and the recorded cause when Auth0 or the settings fail (list, single read, PATCH and history), and unsafe causes;
  • the 422 refusals and their order, the 503, and the default profile source;
  • one wait budget per admin request, for the list, the single read, the type change and the history.
• Route tests for the 422, the 503 and the OpenAPI descriptions (tests/unit/v2/test_admin_user_routes.py). Readiness, deploy validation, candidate deploy and push workflow tests cover the new settings.
• A PostgreSQL test runs the email search as the runtime role (tests/integration/test_v2_user_type_persistence.py::test_the_runtime_role_finds_users_by_their_auth0_email).
• The Management API calls these reads make (GET /api/v2/users/{id}, a search by several user IDs joined with OR, prefix, suffix and text-anywhere email searches, and sort=user_id:1) were tried by hand, read-only, on the production users' tenant.
• Ran lint-imports, python -m scripts.rules validate, python scripts/run_quality_guards.py, ruff check, ruff format --check, mypy, scripts/export_migration_contracts.py (no diff) and the changelog fragment check.
• Reviewed in three adversarial rounds. Round 1 found two bugs (rate-limited broad searches answering 503, and </> turning a short search into a range query), fixed test-first; rounds 2 and 3 found none, and their quality findings are fixed.

Inline suppressions added: none.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 97.99499% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.82%. Comparing base (cd513da) to head (bb52245).

Files with missing lines	Patch %	Lines
policyengine_api/libs/auth0_management.py	97.69%	5 Missing ⚠️
policyengine_api/fastapi_routes/dependencies.py	87.50%	1 Missing ⚠️
...olicyengine_api/services/v2/user_types/services.py	98.83%	0 Missing and 1 partial ⚠️
...gine_api/services/v2/user_types/transformations.py	97.50%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4283      +/-   ##
==========================================
+ Coverage   92.69%   92.82%   +0.13%     
==========================================
  Files         329      330       +1     
  Lines       18783    19154     +371     
  Branches     3114     3096      -18     
==========================================
+ Hits        17410    17780     +370     
- Misses        818      821       +3     
+ Partials      555      553       -2     

Flag	Coverage Δ
integration	53.92% <47.86%> (+0.15%)	⬆️
unit	90.62% <97.49%> (+0.16%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.