From 2efc1560def806a0d1be3037e7180b8f6b85f43c Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:08:38 +0400 Subject: [PATCH 1/6] Invite users by email and announce type changes Admins invite an email address to become an author or admin; a signed-in user whose verified Auth0 email matches the address accepts the invitation with the token from its link. Every committed type change, through an invitation, the admin routes or the type script, emails the user through Postmark's template API, and GET /v2/me reports the latest change until the user dismisses it. - user_invitations, user_type_changes.dismissed_at and the invitation source, in autogenerated v2 revision bb09a374231f, with the runtime role's privileges. - Admin routes to create, list, resend and revoke invitations, and POST /v2/me/invitations/accept, whose refusals name a code. - POST /v2/me/type-changes/{type_change_id}/dismiss. - POSTMARK_SERVER_TOKEN_SECRET_RESOURCE, POSTMARK_SENDER_ADDRESS and POLICYENGINE_APP_URL in readiness, the deploy validation, the deploy script and both deploy jobs. Co-Authored-By: Claude Opus 5.5 --- .github/scripts/deploy_cloud_run_candidate.sh | 10 + .../scripts/validate_cloud_run_deploy_env.sh | 25 + .github/workflows/push.yml | 9 + changelog.d/user-invitations.added.md | 1 + docs/engineering/migration-contracts.md | 8 +- docs/engineering/skills/alembic-migrations.md | 39 +- docs/engineering/skills/testing.md | 4 + docs/generated/migration_contracts.json | 34 +- docs/migration/stage-12a-user-login.md | 175 ++++- ...f_invite_users_and_dismiss_type_changes.py | 139 ++++ policyengine_api/data/v2/migration_target.py | 2 +- policyengine_api/data/v2/models/__init__.py | 4 + policyengine_api/data/v2/models/users.py | 80 ++- policyengine_api/data/v2/privileges.py | 12 +- .../fastapi_routes/dependencies.py | 45 ++ .../resource_service_protocols.py | 59 ++ .../v2/admin_invitations/__init__.py | 1 + .../v2/admin_invitations/request_models.py | 22 + .../v2/admin_invitations/response_models.py | 105 +++ .../v2/admin_invitations/routes.py | 234 +++++++ .../fastapi_routes/v2/errors_support.py | 26 + .../fastapi_routes/v2/me/account_support.py | 50 ++ .../fastapi_routes/v2/me/request_models.py | 11 + .../fastapi_routes/v2/me/response_models.py | 88 +++ .../fastapi_routes/v2/me/routes.py | 58 +- .../fastapi_routes/v2/me/user_type_routes.py | 174 +++++ policyengine_api/fastapi_routes/v2/routes.py | 8 + .../v2/user_resources_support.py | 28 + policyengine_api/libs/postmark_email.py | 311 +++++++++ policyengine_api/query_parameters.py | 4 + policyengine_api/readiness.py | 6 +- .../database_connectors/reads.py | 25 +- .../database_connectors/updates.py | 13 +- .../services/v2/user_accounts/services.py | 40 +- .../v2/user_accounts/transformations.py | 26 +- .../services/v2/user_accounts/types.py | 14 + .../services/v2/user_accounts/validators.py | 14 +- .../services/v2/user_emails/__init__.py | 1 + .../services/v2/user_emails/services.py | 201 ++++++ .../v2/user_emails/transformations.py | 87 +++ .../services/v2/user_emails/types.py | 68 ++ .../services/v2/user_invitations/__init__.py | 1 + .../database_connectors/__init__.py | 1 + .../database_connectors/creates.py | 27 + .../database_connectors/reads.py | 81 +++ .../database_connectors/updates.py | 73 ++ .../v2/user_invitations/database_session.py | 32 + .../services/v2/user_invitations/services.py | 407 +++++++++++ .../v2/user_invitations/transformations.py | 47 ++ .../services/v2/user_invitations/types.py | 95 +++ .../v2/user_invitations/validators.py | 155 +++++ .../services/v2/user_types/services.py | 64 +- .../services/v2/user_types/validators.py | 8 +- pyproject.toml | 8 +- scripts/set_v2_user_type.py | 17 +- tests/contract/registry.py | 23 + .../test_app_v2_workflow_contracts.py | 19 + .../integration/test_alembic_v2_user_types.py | 122 +++- .../test_v2_user_type_persistence.py | 185 ++++- tests/unit/libs/test_postmark_email.py | 285 ++++++++ tests/unit/test_cloud_run_candidate_deploy.py | 43 ++ .../unit/test_cloud_run_deploy_environment.py | 63 ++ tests/unit/test_cloud_run_push_workflow.py | 23 + tests/unit/test_readiness.py | 54 ++ tests/unit/test_set_v2_user_type_script.py | 47 ++ tests/unit/v2/test_admin_invitation_routes.py | 283 ++++++++ tests/unit/v2/test_alembic_v2.py | 61 +- tests/unit/v2/test_me_routes.py | 213 +++++- tests/unit/v2/test_models.py | 72 +- tests/unit/v2/test_privilege_manifest.py | 17 +- tests/unit/v2/test_user_account_service.py | 114 +++ tests/unit/v2/test_user_email_service.py | 262 +++++++ tests/unit/v2/test_user_invitation_service.py | 651 ++++++++++++++++++ tests/unit/v2/test_user_type_service.py | 118 ++++ tests/unit/v2/user_email_support.py | 136 ++++ 75 files changed, 5952 insertions(+), 116 deletions(-) create mode 100644 changelog.d/user-invitations.added.md create mode 100644 migrations/v2/versions/bb09a374231f_invite_users_and_dismiss_type_changes.py create mode 100644 policyengine_api/fastapi_routes/v2/admin_invitations/__init__.py create mode 100644 policyengine_api/fastapi_routes/v2/admin_invitations/request_models.py create mode 100644 policyengine_api/fastapi_routes/v2/admin_invitations/response_models.py create mode 100644 policyengine_api/fastapi_routes/v2/admin_invitations/routes.py create mode 100644 policyengine_api/fastapi_routes/v2/me/account_support.py create mode 100644 policyengine_api/fastapi_routes/v2/me/user_type_routes.py create mode 100644 policyengine_api/libs/postmark_email.py create mode 100644 policyengine_api/services/v2/user_emails/__init__.py create mode 100644 policyengine_api/services/v2/user_emails/services.py create mode 100644 policyengine_api/services/v2/user_emails/transformations.py create mode 100644 policyengine_api/services/v2/user_emails/types.py create mode 100644 policyengine_api/services/v2/user_invitations/__init__.py create mode 100644 policyengine_api/services/v2/user_invitations/database_connectors/__init__.py create mode 100644 policyengine_api/services/v2/user_invitations/database_connectors/creates.py create mode 100644 policyengine_api/services/v2/user_invitations/database_connectors/reads.py create mode 100644 policyengine_api/services/v2/user_invitations/database_connectors/updates.py create mode 100644 policyengine_api/services/v2/user_invitations/database_session.py create mode 100644 policyengine_api/services/v2/user_invitations/services.py create mode 100644 policyengine_api/services/v2/user_invitations/transformations.py create mode 100644 policyengine_api/services/v2/user_invitations/types.py create mode 100644 policyengine_api/services/v2/user_invitations/validators.py create mode 100644 tests/unit/libs/test_postmark_email.py create mode 100644 tests/unit/v2/test_admin_invitation_routes.py create mode 100644 tests/unit/v2/test_user_email_service.py create mode 100644 tests/unit/v2/test_user_invitation_service.py create mode 100644 tests/unit/v2/user_email_support.py diff --git a/.github/scripts/deploy_cloud_run_candidate.sh b/.github/scripts/deploy_cloud_run_candidate.sh index b5125450c..4d16bd438 100755 --- a/.github/scripts/deploy_cloud_run_candidate.sh +++ b/.github/scripts/deploy_cloud_run_candidate.sh @@ -83,6 +83,16 @@ if [[ -n "${AUTH0_USER_PROFILES_DOMAIN:-}" ]]; then ) fi +# Optional: invitation and type-change emails go through Postmark only when +# its settings are set. Validation requires all three values or none. +if [[ -n "${POSTMARK_SERVER_TOKEN_SECRET_RESOURCE:-}" ]]; then + env_vars+=( + "POSTMARK_SERVER_TOKEN_SECRET_RESOURCE=${POSTMARK_SERVER_TOKEN_SECRET_RESOURCE}" + "POSTMARK_SENDER_ADDRESS=${POSTMARK_SENDER_ADDRESS}" + "POLICYENGINE_APP_URL=${POLICYENGINE_APP_URL}" + ) +fi + if [[ -n "${OLD_SIMULATION_GATEWAY_URL:-}" ]]; then env_vars+=("OLD_SIMULATION_GATEWAY_URL=${OLD_SIMULATION_GATEWAY_URL}") fi diff --git a/.github/scripts/validate_cloud_run_deploy_env.sh b/.github/scripts/validate_cloud_run_deploy_env.sh index c46f9436d..9dd331bd6 100755 --- a/.github/scripts/validate_cloud_run_deploy_env.sh +++ b/.github/scripts/validate_cloud_run_deploy_env.sh @@ -233,6 +233,31 @@ if (( auth0_user_profiles_count != 0 )) && [[ -z "${PUBLIC_API_AUTH_ISSUER:-}" ] exit 1 fi +# Optional: invitation and type-change emails go through Postmark only when +# its server token's Secret Manager version, the sender address and the app's +# address the emails link to are all set. Staging and production may both +# configure it, each with its own Postmark server. +postmark_count=0 +for name in \ + POSTMARK_SERVER_TOKEN_SECRET_RESOURCE \ + POSTMARK_SENDER_ADDRESS \ + POLICYENGINE_APP_URL; do + if [[ -n "${!name:-}" ]]; then + postmark_count=$((postmark_count + 1)) + fi +done +if (( postmark_count != 0 && postmark_count != 3 )); then + echo "Set POSTMARK_SERVER_TOKEN_SECRET_RESOURCE, POSTMARK_SENDER_ADDRESS, and POLICYENGINE_APP_URL together, or none" >&2 + exit 1 +fi +# The emails' links open the app, so its address is HTTPS, and has no query +# or fragment for the links' paths to follow. +app_url_pattern='^https://[^/?#[:space:]]+(/[^?#[:space:]]*)?$' +if [[ -n "${POLICYENGINE_APP_URL:-}" && ! "${POLICYENGINE_APP_URL}" =~ ${app_url_pattern} ]]; then + echo "POLICYENGINE_APP_URL must be an https address with no query or fragment" >&2 + exit 1 +fi + selected_url_env="$( simulation_entrypoint_url_env_name "${SIM_ENTRYPOINT}" )" diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml index a753f9269..1fee9f41d 100644 --- a/.github/workflows/push.yml +++ b/.github/workflows/push.yml @@ -524,6 +524,12 @@ jobs: AUTH0_USER_PROFILES_DOMAIN: ${{ vars.AUTH0_USER_PROFILES_DOMAIN }} AUTH0_USER_PROFILES_CLIENT_ID: ${{ vars.AUTH0_USER_PROFILES_CLIENT_ID }} AUTH0_USER_PROFILES_CLIENT_SECRET_RESOURCE: ${{ secrets.AUTH0_USER_PROFILES_CLIENT_SECRET_RESOURCE }} + # Invitation and type-change emails through the environment's Postmark + # server: its token's Secret Manager version, the sender address, and + # the app's address the emails link to. All three, or none. + POSTMARK_SERVER_TOKEN_SECRET_RESOURCE: ${{ secrets.POSTMARK_SERVER_TOKEN_SECRET_RESOURCE }} + POSTMARK_SENDER_ADDRESS: ${{ vars.POSTMARK_SENDER_ADDRESS }} + POLICYENGINE_APP_URL: ${{ vars.POLICYENGINE_APP_URL }} 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 @@ -868,6 +874,9 @@ jobs: AUTH0_USER_PROFILES_DOMAIN: ${{ vars.AUTH0_USER_PROFILES_DOMAIN }} AUTH0_USER_PROFILES_CLIENT_ID: ${{ vars.AUTH0_USER_PROFILES_CLIENT_ID }} AUTH0_USER_PROFILES_CLIENT_SECRET_RESOURCE: ${{ secrets.AUTH0_USER_PROFILES_CLIENT_SECRET_RESOURCE }} + POSTMARK_SERVER_TOKEN_SECRET_RESOURCE: ${{ secrets.POSTMARK_SERVER_TOKEN_SECRET_RESOURCE }} + POSTMARK_SENDER_ADDRESS: ${{ vars.POSTMARK_SENDER_ADDRESS }} + POLICYENGINE_APP_URL: ${{ vars.POLICYENGINE_APP_URL }} CLOUD_RUN_SERVICE: policyengine-api CLOUD_RUN_RUNTIME_CACHE_ENVIRONMENT: production CLOUD_RUN_RUNTIME_CACHE_URL_SECRET: policyengine-api-prod-runtime-cache-url:latest diff --git a/changelog.d/user-invitations.added.md b/changelog.d/user-invitations.added.md new file mode 100644 index 000000000..7f3190105 --- /dev/null +++ b/changelog.d/user-invitations.added.md @@ -0,0 +1 @@ +Admins invite an email address to become an author or admin, and a signed-in user with that verified Auth0 email accepts the invitation; every type change emails the user through Postmark, and `GET /v2/me` reports the latest type change until the user dismisses it. diff --git a/docs/engineering/migration-contracts.md b/docs/engineering/migration-contracts.md index 1529b4d14..f4cf57653 100644 --- a/docs/engineering/migration-contracts.md +++ b/docs/engineering/migration-contracts.md @@ -8,7 +8,7 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi | --- | ---: | | route group count | 9 | | workflow count | 17 | -| request count | 92 | +| request count | 94 | | db entity count | 6 | | sim flow count | 3 | @@ -160,12 +160,14 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi | Method | Path | Status | Route group | Required headers | Stable response fields | | --- | --- | ---: | --- | --- | --- | -| `GET` | `/v2/me?country_id=us` | 200 | `user_profile` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.user_type`, `result.item.primary_country`, `result.item.first_name`, `result.item.last_name`, `result.item.email`, `result.item.created_at` | -| `GET` | `/v2/me?country_id=us` | 200 | `user_profile` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.user_type`, `result.item.primary_country`, `result.item.first_name`, `result.item.last_name`, `result.item.email`, `result.item.created_at` | +| `GET` | `/v2/me?country_id=us` | 200 | `user_profile` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.user_type`, `result.item.primary_country`, `result.item.first_name`, `result.item.last_name`, `result.item.email`, `result.item.created_at`, `result.latest_type_change` | +| `GET` | `/v2/me?country_id=us` | 200 | `user_profile` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.user_type`, `result.item.primary_country`, `result.item.first_name`, `result.item.last_name`, `result.item.email`, `result.item.created_at`, `result.latest_type_change` | | `PATCH` | `/v2/me?country_id=us` | 200 | `user_profile` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.primary_country`, `result.item.first_name`, `result.item.last_name` | | `GET` | `/v2/me/export?country_id=us` | 200 | `user_profile` | `Authorization` | `status`, `message`, `result.user`, `result.policies`, `result.households`, `result.simulations`, `result.reports` | | `GET` | `/v2/me/export?country_id=us` | 200 | `user_profile` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.user`, `result.policies`, `result.households`, `result.simulations`, `result.reports` | | `POST` | `/v2/me/upgrade?country_id=us` | 200 | `user_profile` | `Authorization`, `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.user_type`, `result.item.primary_country`, `result.outcome` | +| `POST` | `/v2/me/invitations/accept?country_id=us` | 200 | `user_profile` | `Authorization` | `status`, `message`, `result.item.user_type`, `result.item.previous_user_type`, `result.item.type_changed` | +| `POST` | `/v2/me/type-changes/{type_change_id}/dismiss?country_id=us` | 204 | `user_profile` | `Authorization` | | | `DELETE` | `/v2/me?country_id=us` | 204 | `user_profile` | `Authorization` | | | `DELETE` | `/v2/me?country_id=us` | 204 | `user_profile` | `PolicyEngine-Unauthenticated-User` | | diff --git a/docs/engineering/skills/alembic-migrations.md b/docs/engineering/skills/alembic-migrations.md index f5abccd2c..458727b2b 100644 --- a/docs/engineering/skills/alembic-migrations.md +++ b/docs/engineering/skills/alembic-migrations.md @@ -792,9 +792,9 @@ script), the previous and new types (each `standard`, `author` or `admin`, and different), and the `source`, `admin_route` or `script`. An index on `(user_id, created_at)` serves a user's history, and one on `changed_by_user_id` the `SET NULL` that every user deletion runs. The runtime role may read and -insert its rows, never update or delete them; a user's deletion removes them -through the foreign key, which PostgreSQL runs with the table owner's -privileges. +insert its rows, and since the user invitations revision update only their +`dismissed_at`, never delete them; a user's deletion removes them through +the foreign key, which PostgreSQL runs with the table owner's privileges. The previous Public API revision never uses the table. The downgrade drops it with every recorded change. `test_user_type_changes_revision_adds_only_its_table` @@ -825,3 +825,36 @@ The revision writes no data, and the previous Public API revision, which doesn't map the column, keeps working at it. The downgrade drops the column with its values, which the next publication run of each PolicyEngine.py version records again. + +### API v2 user invitations + +Revision `bb09a374231f` (parent `0c136a278f29`) was autogenerated, with no +post-generation corrections, after the `UserInvitation` model was added, +`UserTypeChange` gained `dismissed_at`, and `UserTypeChangeSource` gained +`invitation`. It adds `user_invitations`, one row per admin's invitation for +an email address to become an author or admin: the address, the type +(`author` or `admin`), the SHA-256 digest of its token in hexadecimal +(unique; the token itself is never stored), the inviting admin, its expiry, +its last send's time or failure, and when it was accepted, and by whom, or +revoked (never both). Deleting the inviting or accepting user keeps the +invitation and sets that column to NULL; an index on each serves that +`SET NULL`. It adds the nullable `user_type_changes.dismissed_at`, and +replaces the source check: Alembic compares checks by name only, so the +check that also allows `invitation` is named +`ck_user_type_changes_source_allowed`, and autogenerate drops +`ck_user_type_changes_source` and adds it, as for the user types revision. +The runtime role reads, inserts and updates invitations, never deletes them, +and updates only `dismissed_at` of `user_type_changes` +(`update_columns("dismissed_at")`). + +The previous Public API revision never uses `user_invitations` and doesn't +map `dismissed_at`, but it reads every recorded change's source as +`admin_route` or `script`: there, an admin's read of the type history of a +user who accepted an invitation fails with 500. The downgrade drops +`user_invitations` and `dismissed_at` with their values, and restores the +check that allows only `admin_route` and `script`, so it fails while any +change's source is `invitation`. +`test_user_invitations_revision_adds_invitations_and_dismissals_only` and +`test_user_invitations_revision_records_invitation_changes_until_downgraded` +in `tests/integration/test_alembic_v2_user_types.py` check both. + diff --git a/docs/engineering/skills/testing.md b/docs/engineering/skills/testing.md index 817cc83ab..a170ae350 100644 --- a/docs/engineering/skills/testing.md +++ b/docs/engineering/skills/testing.md @@ -613,6 +613,7 @@ uv run --frozen --extra dev mypy uv run --frozen pytest \ tests/unit/libs/test_user_auth.py \ tests/unit/libs/test_auth0_management.py \ + tests/unit/libs/test_postmark_email.py \ tests/unit/libs/test_rate_limit_wait_budget.py \ tests/unit/v2/test_user_route_auth.py \ tests/unit/v2/test_me_routes.py \ @@ -620,6 +621,9 @@ uv run --frozen pytest \ tests/unit/v2/test_user_type_service.py \ tests/unit/v2/test_admin_user_routes.py \ tests/unit/v2/test_admin_user_profile_service.py \ + tests/unit/v2/test_admin_invitation_routes.py \ + tests/unit/v2/test_user_invitation_service.py \ + tests/unit/v2/test_user_email_service.py \ tests/unit/test_set_v2_user_type_script.py \ tests/unit/v2/test_user_policy_routes.py \ tests/unit/v2/test_user_household_routes.py \ diff --git a/docs/generated/migration_contracts.json b/docs/generated/migration_contracts.json index 15e622f8d..7cfaa0853 100644 --- a/docs/generated/migration_contracts.json +++ b/docs/generated/migration_contracts.json @@ -1,7 +1,7 @@ { "metadata": { "db_entity_count": 6, - "request_count": 92, + "request_count": 94, "route_group_count": 9, "sim_flow_count": 3, "workflow_count": 17 @@ -1179,7 +1179,8 @@ "result.item.first_name", "result.item.last_name", "result.item.email", - "result.item.created_at" + "result.item.created_at", + "result.latest_type_change" ] }, { @@ -1199,7 +1200,8 @@ "result.item.first_name", "result.item.last_name", "result.item.email", - "result.item.created_at" + "result.item.created_at", + "result.latest_type_change" ] }, { @@ -1273,6 +1275,32 @@ "result.outcome" ] }, + { + "expected_status": 200, + "headers": [ + "Authorization" + ], + "method": "POST", + "path": "/v2/me/invitations/accept?country_id=us", + "route_group": "user_profile", + "stable_response_fields": [ + "status", + "message", + "result.item.user_type", + "result.item.previous_user_type", + "result.item.type_changed" + ] + }, + { + "expected_status": 204, + "headers": [ + "Authorization" + ], + "method": "POST", + "path": "/v2/me/type-changes/{type_change_id}/dismiss?country_id=us", + "route_group": "user_profile", + "stable_response_fields": [] + }, { "expected_status": 204, "headers": [ diff --git a/docs/migration/stage-12a-user-login.md b/docs/migration/stage-12a-user-login.md index 00102d271..5bf3a8999 100644 --- a/docs/migration/stage-12a-user-login.md +++ b/docs/migration/stage-12a-user-login.md @@ -208,18 +208,21 @@ The response shapes are unchanged; the routes' OpenAPI descriptions say where the emails and names come from. Each change is a row of `user_type_changes`: the user, the previous and new -types, the admin (`changed_by_user_id`) and the `source`, `admin_route` or -`script`. Deleting the user deletes its changes; deleting the admin keeps them -with no admin. +types, the admin (`changed_by_user_id`), the `source`, `admin_route`, +`invitation` or `script`, and `dismissed_at`, when the user dismissed the +app's notice of it. Deleting the user deletes its changes; deleting the admin +keeps them with no admin. A change that would leave no admin is refused with 409, and so is the last -admin's `DELETE /v2/me`. Every change, the script's included, and every +admin's `DELETE /v2/me`. Every change, the script's and an invitation's +included, every invitation an admin creates, resends or revokes, and every signed-in account deletion first takes one transaction-scoped advisory lock (`pg_advisory_xact_lock(8629020026100001)`), then reads the admins in a -statement of its own and checks the caller, or the deleted user, against -them. Because of that lock, concurrent changes and deletions run one at a -time, and each reads the admins the ones before it committed; an admin -demoted by an earlier change is then refused with 403. An admin's change to +statement of its own and checks the caller, the invitation's admin, or the +deleted user, against them. Because of that lock, concurrent changes, +invitations and deletions run one at a time, and each reads the admins the +ones before it committed; an admin demoted by an earlier change is then +refused with 403. An admin's change to another type then also compares the user's locked row with `expected_user_type`, as the route table says; the script's changes don't. Locking the admins' rows instead would miss a user promoted while the lock was awaited, since a waiting query rechecks @@ -233,7 +236,109 @@ settings (`V2_RUNTIME_DATABASE_URL` or `V2_RUNTIME_DATABASE_URL_SECRET_RESOURCE`, `V2_SUPABASE_PROJECT_REF`, `V2_SUPABASE_ENVIRONMENT`), and refuses an address with no signed-in user, or several, and the last admin's demotion. A person's user exists only after -their first signed-in request to the detailed-save routes. +their first signed-in request to the detailed-save routes. Like an admin's +change, the script's change emails the user (below) when it has the +`AUTH0_USER_PROFILES_*` and `POSTMARK_*` settings. + +### Email invitations + +An admin invites an email address to become an author or admin; the person +signs in, or signs up, through Auth0 and the app accepts the invitation for +them. No email address of a user is stored: the invitee's is read from Auth0 +when they accept. + +| Route | What it does | +| --- | --- | +| `POST /v2/admin/invitations` `{"email": …, "user_type": "author" or "admin"}` | Creates the invitation (201), then emails its link. `email` is stripped and must be one address (an `@` with text on both sides, no whitespace, `<` or `>`, at most 320 characters). An open invitation to the same address, compared ignoring case, is revoked first. | +| `GET /v2/admin/invitations?offset=&limit=` | Open invitations (neither accepted nor revoked), newest first, expired ones included. | +| `POST /v2/admin/invitations/{invitation_id}/resend` | A new link and a new 7-day expiry, the caller as its inviting admin, and the email again; 404 unless the invitation is open. An expired one can be resent. | +| `DELETE /v2/admin/invitations/{invitation_id}` | Revokes it (204); 404 unless it is open. | +| `POST /v2/me/invitations/accept?country_id=` `{"token": …}` | Signed-in users only (401 for the unauthenticated-user header). Accepts it; see below. | + +An invitation item is `{id, email, user_type, invited_by_user_id, created_at, +expires_at, expired, last_sent_at, last_send_error}`. `last_sent_at` is when +Postmark accepted the email with the current link; `last_send_error` names +why the last send failed, as `not_configured`, `timeout`, +`connection_error`, `http_`, `postmark_` (`postmark_406` +for an address Postmark suppresses) or `secret_unavailable`. A failed send +still answers 201 or 200, and the invitation stays open for a resend. + +Each invitation's token is 32 random bytes from `secrets`, URL-safe base64, +sent only in the email's link, `/invitations/accept#token=`: +in the fragment, which browsers never send to a server. `user_invitations` +stores only its SHA-256 digest, in hexadecimal. A resend replaces it, so the +earlier link finds no invitation. + +Acceptance first reads the signed-in identity's profile from the users' +Auth0 tenant by its Auth0 user ID, through the `AUTH0_USER_PROFILES_*` +client (503 `auth0_unavailable` without those settings or when Auth0 can't +answer; the app tries again). An identity from another issuer, or one Auth0 +doesn't know, has no verified email. Then, in one transaction, the caller's +user is provisioned as on any first signed-in request, the user-type change +lock is taken, and these are checked in order, each refusal naming its +`code` next to `status` and `message`: + +| Status | `code` | When | +| --- | --- | --- | +| 410 | `invitation_not_found` | No invitation has the token's digest. | +| 410 | `invitation_revoked` | It was revoked, or replaced by a newer invitation to the address. | +| 410 | `invitation_accepted` | It was accepted already. | +| 410 | `invitation_expired` | Its 7 days have passed. | +| 409 | `inviter_not_admin` | Its inviting admin is no longer among the admins read after the lock. | +| 409 | `email_not_verified` | Auth0 has no verified email for the user; it may after they open Auth0's verification email. | +| 403 | `email_mismatch` | The verified email isn't the invited address, compared whole and ignoring case. The invitation stays open. | + +Otherwise the invitation is marked accepted by the user, and the user gets +its type unless they already have it or a higher one: an invitation never +lowers a type, so the last-admin rule can't apply. A change is recorded with +`source = invitation` and the inviting admin as `changed_by_user_id`. The +response is `{user_type, previous_user_type, type_changed}`. Nothing changes +when any check refuses. + +### Type-change emails and the notice + +After a type change commits, through an admin's `PATCH`, an invitation or +the script, the user, and only the user, is emailed. The address is the +first verified Auth0 email among the user's identities from the users' +issuer, most recently seen first, read then and never stored; an +acceptance uses the address it already read. When there are no `POSTMARK_*` +settings, no user profile settings, no verified email, Auth0 can't answer, +or the send fails, nothing is sent and the WARNING +`user_type_change_email_not_sent` names only the v2 user ID and a cause +(`not_configured`, `no_user_profiles`, `no_verified_email`, +`profiles_unavailable`, or the sender's cause); an unsent invitation is the +WARNING `user_invitation_email_not_sent` with the invitation's ID. A failed +email never undoes or fails the change, and there is no queue: an admin +resends an invitation instead. + +`GET /v2/me` answers `result.latest_type_change`, `{id, previous_user_type, +user_type, changed_at}`, for the user's most recent change until +`POST /v2/me/type-changes/{type_change_id}/dismiss?country_id=` (204; +signed-in users only; 404 for a change that isn't the caller's) sets its +`dismissed_at`. It is null when the user's type never changed, once the most +recent change is dismissed (an older one doesn't come back), and for a +signed-out browser. `PATCH /v2/me` answers only `result.item`. + +### Sending through Postmark + +`policyengine_api/libs/postmark_email.py` sends each email with Postmark's +`POST https://api.postmarkapp.com/email/withTemplate`, on the `outbound` +transactional message stream, from `POSTMARK_SENDER_ADDRESS`, with the +template alias and its data: + +| Template alias | To | Template data | +| --- | --- | --- | +| `user-invitation` | The invited address | `user_type`, `accept_url`, `expires_at` (for example `19 November 2026, 14:05 UTC`), `app_url` | +| `user-type-changed` | The user's verified Auth0 email | `previous_user_type`, `user_type`, `promoted` (the new type has more permissions), `app_url` | + +A timeout, a connection error, 429 or a 5xx is tried again, three attempts in +all, after waits of 0.5 and 1 second, within the request; a retried timeout +may send an email twice. Any other answer, such as 422 with Postmark's own +error code, is final. Postmark keeps the templates and their layout, delivers +to the recipient's mail server, signs with DKIM, suppresses addresses that +bounced or complained, and logs each message, so the Public API does none of +that. The templates are created on each environment's Postmark server +(C3 · 14). ## Provisioning strategies @@ -553,9 +658,11 @@ admin; `scripts/set_v2_user_type.py` makes another admin afterwards. `users.primary_country`, so it fails while legacy-only rows, any simulation or report associations, or any unauthenticated user exist. Removing them first deletes users' saved work. From the head, the later revisions' - downgrades run first: the user type changes revision (`970be5d29283`) drops - every recorded change, the user types revision (`617f531f1506`) needs no - author or admin, and the simulation runs revision (`1356f658347d`) needs + downgrades run first: the user invitations revision (`bb09a374231f`) drops + every invitation and dismissal and needs no change with source + `invitation`, the user type changes revision (`970be5d29283`) drops every + recorded change, the user types revision (`617f531f1506`) needs no author + or admin, and the simulation runs revision (`1356f658347d`) needs `simulations` empty. ### Schema compatibility @@ -613,6 +720,9 @@ requests keep their 401/503 behavior, and signed-out requests still work. | `AUTH0_USER_PROFILES_DOMAIN` | GitHub variable (optional, `staging` and `production`) | The users' tenant's canonical domain, for reading users' emails and names for the admin routes; the group needs `PUBLIC_API_AUTH_ISSUER` | | `AUTH0_USER_PROFILES_CLIENT_ID` | GitHub variable (optional, `staging` and `production`) | Read-only M2M client with `read:users` | | `AUTH0_USER_PROFILES_CLIENT_SECRET_RESOURCE` | GitHub secret (optional, `staging` and `production`) | Secret Manager version holding that client's secret | +| `POSTMARK_SERVER_TOKEN_SECRET_RESOURCE` | GitHub secret (optional, `staging` and `production`) | Secret Manager version holding the environment's Postmark server token, read when an email is sent (`POSTMARK_SERVER_TOKEN`, the token itself, is for local use) | +| `POSTMARK_SENDER_ADDRESS` | GitHub variable (optional, `staging` and `production`) | The emails' From address, on a sender signature or domain the Postmark server has verified; may carry a display name | +| `POLICYENGINE_APP_URL` | GitHub variable (optional, `staging` and `production`) | The app's HTTPS address the emails link to, with no query or fragment; the accept page is its `/invitations/accept` | > **Set the final issuer before the first sign-in.** `user_identities` is > keyed by `(issuer, subject)`, so `PUBLIC_API_AUTH_ISSUER` must hold its @@ -630,10 +740,16 @@ each all-or-none: a domain, a client ID and exactly one client-secret source the same client code and token cache; they are separate so that staging can read users without being able to delete them. +The email settings, `POSTMARK_SENDER_ADDRESS`, `POLICYENGINE_APP_URL` and +exactly one server-token source, are all-or-none too. Without them no email +is sent, each unsent one is a WARNING, and invitations stay open with +`last_send_error` `not_configured`. Invitations can be accepted only with the +`AUTH0_USER_PROFILES_*` settings, and type-change emails need both groups. + `readiness.validate_policy_runtime_configuration` validates the `PUBLIC_API_AUTH_*`, `PUBLIC_API_SERVER_AUTH_ISSUER`, -`PUBLIC_API_SERVER_CLIENT_IDS`, `AUTH0_MANAGEMENT_*` and -`AUTH0_USER_PROFILES_*` settings. Inconsistent values fail +`PUBLIC_API_SERVER_CLIENT_IDS`, `AUTH0_MANAGEMENT_*`, +`AUTH0_USER_PROFILES_*` and email settings. Inconsistent values fail readiness, which the deploy waits on. Request handling reads the `PUBLIC_API_AUTH_*` settings only for a bearer token, so nothing in them blocks a signed-out request. `validate_cloud_run_deploy_env.sh` requires @@ -641,11 +757,13 @@ blocks a signed-out request. `validate_cloud_run_deploy_env.sh` requires all-or-none Management and user profile settings, and it rejects Management settings outside production, user profile settings without `PUBLIC_API_AUTH_ISSUER` and a malformed `PUBLIC_API_SERVER_CLIENT_IDS`. -It allows the user profile settings in staging and production. -`deploy_cloud_run_candidate.sh` writes them to the revision. The release test -step unsets the `PUBLIC_API_AUTH_*` and `PUBLIC_API_SERVER_*` settings; the -`release-tests` job never receives the `AUTH0_MANAGEMENT_*` or -`AUTH0_USER_PROFILES_*` settings. +It allows the user profile settings in staging and production, and the +email settings there too, all three or none, with an HTTPS +`POLICYENGINE_APP_URL`. `deploy_cloud_run_candidate.sh` writes them to the +revision from each deploy job's `env:` in `push.yml`. The release test step +unsets the `PUBLIC_API_AUTH_*` and `PUBLIC_API_SERVER_*` settings; the +`release-tests` job never receives the `AUTH0_MANAGEMENT_*`, +`AUTH0_USER_PROFILES_*` or email settings. Every request's `Authorization` header is checked before route matching (`policyengine_api.request_caller`), so a bearer token sent to any route, not @@ -781,6 +899,25 @@ Configure staging first, then production: command above. Without the grant, or without `read:users`, admins see stored values and an email search answers 503. +## Postmark prerequisites (operator) + +For each environment, staging first (C3 · 14): + +1. **A Postmark server** with a verified sender signature or domain for the + sender address (DKIM and Return-Path records in the sending domain's DNS). + Postmark may review a new account before it sends to outside addresses. +2. **Two templates**, with the aliases `user-invitation` and + `user-type-changed`, filled from the template data under "Sending through + Postmark"; create them on the staging server and copy them to the + production server with Postmark's template copying. +3. **The server token** in Secret Manager, its version's resource name in + the environment's `POSTMARK_SERVER_TOKEN_SECRET_RESOURCE` GitHub secret, + and `roles/secretmanager.secretAccessor` on that secret for the + environment's Cloud Run runtime service account, with the command above. + Without the grant every email fails with `secret_unavailable`. +4. **`POSTMARK_SENDER_ADDRESS` and `POLICYENGINE_APP_URL`**, GitHub variables + of the environment. They take effect at the next deploy. + ## Rollout 1. Create the GitHub variables and secrets above. Every deploy now requires diff --git a/migrations/v2/versions/bb09a374231f_invite_users_and_dismiss_type_changes.py b/migrations/v2/versions/bb09a374231f_invite_users_and_dismiss_type_changes.py new file mode 100644 index 000000000..4535d76dd --- /dev/null +++ b/migrations/v2/versions/bb09a374231f_invite_users_and_dismiss_type_changes.py @@ -0,0 +1,139 @@ +"""invite users and dismiss type changes + +Revision ID: bb09a374231f +Revises: 0c136a278f29 +Create Date: 2026-11-12 23:37:15.642213 +Generation: uv run alembic -c alembic-v2.ini revision --autogenerate + +Adds user_invitations, one row per admin's invitation for an email address to +become an author or admin: the address, the type, the SHA-256 digest of its +token (the token itself is never stored), the inviting admin, its expiry, its +last send, and when it was accepted (and by whom) or revoked. Deleting the +inviting or accepting user keeps the invitation without them; an index on +each serves the SET NULL that every user deletion runs. user_type_changes +gains dismissed_at, when the user dismissed the app's notice of the change, +and its source check, renamed ck_user_type_changes_source_allowed because +Alembic compares checks by name only, also allows invitation. The operations +are exactly as generated. + +The previous Public API revision never uses user_invitations and doesn't map +dismissed_at, but it reads every recorded change's source as admin_route or +script: an admin's read of the type history of a user who accepted an +invitation fails with 500 there. The downgrade drops user_invitations and +dismissed_at with their values, and fails while any change's source is +invitation. +""" + +from typing import Sequence, Union + +from alembic import op +import sqlalchemy as sa +import sqlmodel + + +revision: str = "bb09a374231f" +down_revision: Union[str, None] = "0c136a278f29" +branch_labels: Union[str, Sequence[str], None] = None +depends_on: Union[str, Sequence[str], None] = None + + +def upgrade() -> None: + # ### commands auto generated by Alembic - please adjust! ### + op.create_table( + "user_invitations", + sa.Column("id", sa.Uuid(), nullable=False), + sa.Column( + "created_at", + sa.DateTime(timezone=True), + server_default=sa.text("now()"), + nullable=False, + ), + sa.Column( + "email", sqlmodel.sql.sqltypes.AutoString(length=320), nullable=False + ), + sa.Column( + "user_type", sqlmodel.sql.sqltypes.AutoString(length=16), nullable=False + ), + sa.Column( + "token_hash", sqlmodel.sql.sqltypes.AutoString(length=64), nullable=False + ), + sa.Column("invited_by_user_id", sa.Uuid(), nullable=True), + sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False), + sa.Column("last_sent_at", sa.DateTime(timezone=True), nullable=True), + sa.Column( + "last_send_error", + sqlmodel.sql.sqltypes.AutoString(length=64), + nullable=True, + ), + sa.Column("accepted_at", sa.DateTime(timezone=True), nullable=True), + sa.Column("accepted_by_user_id", sa.Uuid(), nullable=True), + sa.Column("revoked_at", sa.DateTime(timezone=True), nullable=True), + sa.CheckConstraint( + "user_type IN ('author', 'admin')", + name=op.f("ck_user_invitations_user_type"), + ), + sa.CheckConstraint( + "accepted_at IS NULL OR revoked_at IS NULL", + name=op.f("ck_user_invitations_accepted_or_revoked"), + ), + sa.ForeignKeyConstraint( + ["accepted_by_user_id"], + ["users.id"], + name=op.f("fk_user_invitations_accepted_by_user_id_users"), + ondelete="SET NULL", + ), + sa.ForeignKeyConstraint( + ["invited_by_user_id"], + ["users.id"], + name=op.f("fk_user_invitations_invited_by_user_id_users"), + ondelete="SET NULL", + ), + sa.PrimaryKeyConstraint("id", name=op.f("pk_user_invitations")), + sa.UniqueConstraint("token_hash", name="uq_user_invitations_token_hash"), + ) + op.create_index( + "ix_user_invitations_accepted_by_user_id", + "user_invitations", + ["accepted_by_user_id"], + unique=False, + ) + op.create_index( + "ix_user_invitations_invited_by_user_id", + "user_invitations", + ["invited_by_user_id"], + unique=False, + ) + op.add_column( + "user_type_changes", + sa.Column("dismissed_at", sa.DateTime(timezone=True), nullable=True), + ) + op.drop_constraint( + op.f("ck_user_type_changes_source"), "user_type_changes", type_="check" + ) + op.create_check_constraint( + op.f("ck_user_type_changes_source_allowed"), + "user_type_changes", + "source IN ('admin_route', 'script', 'invitation')", + ) + # ### end Alembic commands ### + + +def downgrade() -> None: + # ### commands auto generated by Alembic - please adjust! ### + op.drop_constraint( + op.f("ck_user_type_changes_source_allowed"), "user_type_changes", type_="check" + ) + op.create_check_constraint( + op.f("ck_user_type_changes_source"), + "user_type_changes", + "source::text = ANY (ARRAY['admin_route'::character varying, 'script'::character varying]::text[])", + ) + op.drop_column("user_type_changes", "dismissed_at") + op.drop_index( + "ix_user_invitations_invited_by_user_id", table_name="user_invitations" + ) + op.drop_index( + "ix_user_invitations_accepted_by_user_id", table_name="user_invitations" + ) + op.drop_table("user_invitations") + # ### end Alembic commands ### diff --git a/policyengine_api/data/v2/migration_target.py b/policyengine_api/data/v2/migration_target.py index f52dc5987..b363f38ce 100644 --- a/policyengine_api/data/v2/migration_target.py +++ b/policyengine_api/data/v2/migration_target.py @@ -24,7 +24,7 @@ from collections.abc import Mapping V2_ALEMBIC_DISPOSABLE_TEST = "V2_ALEMBIC_DISPOSABLE_TEST" -V2_ALEMBIC_HEAD_REVISION = "0c136a278f29" +V2_ALEMBIC_HEAD_REVISION = "bb09a374231f" DISPOSABLE_DATABASE_NAME = "policyengine_v2_alembic_test" DISPOSABLE_HOSTS = frozenset({"localhost", "127.0.0.1", "::1", "postgres"}) MIGRATION_ROLE = "policyengine_v2_migrator" diff --git a/policyengine_api/data/v2/models/__init__.py b/policyengine_api/data/v2/models/__init__.py index 0eeafa5a5..2451452b0 100644 --- a/policyengine_api/data/v2/models/__init__.py +++ b/policyengine_api/data/v2/models/__init__.py @@ -97,9 +97,11 @@ SimulationType, ) from policyengine_api.data.v2.models.users import ( # noqa: E402 + INVITATION_USER_TYPES, SIGNED_IN_USER_TYPES, User, UserIdentity, + UserInvitation, UserType, UserTypeChange, UserTypeChangeSource, @@ -109,6 +111,7 @@ validate_v2_metadata_table_names(V2_METADATA.tables) __all__ = [ + "INVITATION_USER_TYPES", "SIGNED_IN_USER_TYPES", "V2_METADATA", "AggregateOutput", @@ -168,6 +171,7 @@ "User", "UserHouseholdAssociation", "UserIdentity", + "UserInvitation", "UserPolicy", "UserReportAssociation", "UserSimulationAssociation", diff --git a/policyengine_api/data/v2/models/users.py b/policyengine_api/data/v2/models/users.py index 8d956bebc..80f9f5fe8 100644 --- a/policyengine_api/data/v2/models/users.py +++ b/policyengine_api/data/v2/models/users.py @@ -1,10 +1,12 @@ -"""Canonical SQLModel tables for v2 users and their sign-in identities. +"""Canonical SQLModel tables for v2 users, their sign-in identities and types. A user is ``unauthenticated``, or a signed-in user of type ``standard``, ``author`` or ``admin``, backed by one or more verified sign-in identities (every Stage 10 legacy-mapping user is standard). An unauthenticated user's ``id`` is the random UUID a signed-out browser generates and sends as its -credential; every other user column stays NULL. +credential; every other user column stays NULL. Each change of a signed-in +user's type is recorded, and admins invite email addresses to become authors +or admins. """ from datetime import datetime @@ -57,8 +59,15 @@ class UserTypeChangeSource(StrEnum): ADMIN_ROUTE = "admin_route" # An operator, through scripts/set_v2_user_type.py. SCRIPT = "script" + # The user, by accepting an admin's email invitation. + INVITATION = "invitation" +# The types an admin's email invitation can grant. +INVITATION_USER_TYPES = (UserType.AUTHOR, UserType.ADMIN) +_INVITATION_USER_TYPES_SQL = ", ".join( + f"'{user_type.value}'" for user_type in INVITATION_USER_TYPES +) _USER_TYPE_CHANGE_SOURCES_SQL = ", ".join( f"'{source.value}'" for source in UserTypeChangeSource ) @@ -161,9 +170,11 @@ class UserTypeChange(IdentifiedModel, table=True): """One change of a signed-in user's type; together, the user's type history. ``created_at`` is when the type changed. ``changed_by_user_id`` names the - admin who changed it through the admin routes. It is empty for a change the - type script made, and becomes empty if that admin's account is deleted. - Deleting the user deletes its history. + admin who changed it through the admin routes, or who sent the invitation + the user accepted. It is empty for a change the type script made, and + becomes empty if that admin's account is deleted. ``dismissed_at`` is when + the user dismissed the app's notice of the change. Deleting the user + deletes its history. """ __tablename__ = "user_type_changes" @@ -180,9 +191,11 @@ class UserTypeChange(IdentifiedModel, table=True): "previous_user_type <> new_user_type", name="ck_user_type_changes_changed_type", ), + # Alembic compares checks by name only, so this one was renamed from + # ck_user_type_changes_source when invitation was allowed. sa.CheckConstraint( f"source IN ({_USER_TYPE_CHANGE_SOURCES_SQL})", - name="ck_user_type_changes_source", + name="ck_user_type_changes_source_allowed", ), sa.Index("ix_user_type_changes_user_id_created_at", "user_id", "created_at"), # Deleting any user sets its changes' admin to NULL, which searches here. @@ -196,3 +209,58 @@ class UserTypeChange(IdentifiedModel, table=True): previous_user_type: str = Field(max_length=16) new_user_type: str = Field(max_length=16) source: str = Field(max_length=16) + dismissed_at: datetime | None = Field( + default=None, sa_type=sa.DateTime(timezone=True) + ) + + +class UserInvitation(IdentifiedModel, table=True): + """An admin's invitation for an email address to become an author or admin. + + The invitation's token is sent only in its email; only the token's SHA-256 + digest, in hexadecimal, is stored. An invitation is open until it is + accepted or revoked, and can be accepted only before ``expires_at``. + Resending gives it a new token and expiry. ``last_sent_at`` is when the + email with the current token was sent, and ``last_send_error`` names why + the last send failed. ``invited_by_user_id`` is the admin who created or + last resent it, and ``accepted_by_user_id`` the user who accepted it; each + becomes empty if that user's account is deleted. + """ + + __tablename__ = "user_invitations" + __table_args__ = ( + sa.CheckConstraint( + f"user_type IN ({_INVITATION_USER_TYPES_SQL})", + name="ck_user_invitations_user_type", + ), + sa.CheckConstraint( + "accepted_at IS NULL OR revoked_at IS NULL", + name="ck_user_invitations_accepted_or_revoked", + ), + sa.UniqueConstraint("token_hash", name="uq_user_invitations_token_hash"), + # Deleting any user sets its invitations' users to NULL, which + # searches here. + sa.Index("ix_user_invitations_invited_by_user_id", "invited_by_user_id"), + sa.Index("ix_user_invitations_accepted_by_user_id", "accepted_by_user_id"), + ) + + email: str = Field(max_length=320) + user_type: str = Field(max_length=16) + token_hash: str = Field(max_length=64) + invited_by_user_id: UUID | None = Field( + default=None, foreign_key="users.id", ondelete="SET NULL" + ) + expires_at: datetime = Field(sa_type=sa.DateTime(timezone=True)) + last_sent_at: datetime | None = Field( + default=None, sa_type=sa.DateTime(timezone=True) + ) + last_send_error: str | None = Field(default=None, max_length=64) + accepted_at: datetime | None = Field( + default=None, sa_type=sa.DateTime(timezone=True) + ) + accepted_by_user_id: UUID | None = Field( + default=None, foreign_key="users.id", ondelete="SET NULL" + ) + revoked_at: datetime | None = Field( + default=None, sa_type=sa.DateTime(timezone=True) + ) diff --git a/policyengine_api/data/v2/privileges.py b/policyengine_api/data/v2/privileges.py index a0bfb27f5..4820524fd 100644 --- a/policyengine_api/data/v2/privileges.py +++ b/policyengine_api/data/v2/privileges.py @@ -284,9 +284,15 @@ def _run_table( "user_report_associations": _access(runtime=READ_WRITE), "user_simulation_associations": _access(runtime=READ_WRITE), "users": _access(runtime=READ_WRITE), - # Each change of a signed-in user's type, recorded by the admin routes and - # the type script and never changed afterwards. - "user_type_changes": _access(runtime=READ_INSERT), + # Each change of a signed-in user's type, recorded by the admin routes, + # invitations and the type script. Afterwards only the time the user + # dismissed its notice is set. + "user_type_changes": _access( + runtime=READ_INSERT | {update_columns("dismissed_at")} + ), + # Admins' email invitations: revoking or accepting one updates it, and none + # is deleted. + "user_invitations": _access(runtime=READ_INSERT_UPDATE), # Temporary Stage 12 comparison-run tables. "stage12_evaluation_reports": _access(runtime=READ_WRITE, stage12=READ_WRITE), "stage12_evaluation_simulations": _access(runtime=READ_WRITE, stage12=READ_WRITE), diff --git a/policyengine_api/fastapi_routes/dependencies.py b/policyengine_api/fastapi_routes/dependencies.py index da87826aa..e7b59697a 100644 --- a/policyengine_api/fastapi_routes/dependencies.py +++ b/policyengine_api/fastapi_routes/dependencies.py @@ -21,6 +21,7 @@ V2HouseholdResourceService, V2PolicyResourceService, V2UserHouseholdResourceService, + V2UserInvitationResourceService, V2UserPolicyResourceService, V2UserReportResourceService, V2UserSimulationResourceService, @@ -55,6 +56,7 @@ from policyengine_api.services.v2.identity.types import ( AccountPrincipal, ) + from policyengine_api.services.v2.user_emails.services import V2UserEmailService __all__ = [ "MetadataReader", @@ -67,6 +69,7 @@ "V2MetadataResourceReader", "V2PolicyResourceService", "V2UserHouseholdResourceService", + "V2UserInvitationResourceService", "V2UserPolicyResourceService", "V2UserReportResourceService", "V2UserSimulationResourceService", @@ -369,6 +372,23 @@ def _default_user_profile_source() -> UserProfileSource | None: return UserProfileSource(issuer=load_user_auth_settings().issuer, reader=reader) +def _default_user_email_service() -> V2UserEmailService: + """Return the email service: Postmark, and the users' Auth0 tenant. + + Without the POSTMARK_* settings it sends nothing and records a WARNING + for each email; settings are read when an email is sent. + """ + from policyengine_api.libs.postmark_email import build_postmark_email_sender + from policyengine_api.services.v2.user_emails.services import ( + V2UserEmailService, + ) + + return V2UserEmailService( + email_sender_factory=build_postmark_email_sender, + user_profile_source_factory=_default_user_profile_source, + ) + + def _default_v2_user_type_service_factory() -> V2UserTypeResourceService: from policyengine_api.data.v2.database import ( get_v2_session_factory, @@ -381,6 +401,25 @@ def _default_v2_user_type_service_factory() -> V2UserTypeResourceService: return V2UserTypeService( UserTypeDatabaseSession(get_v2_session_factory()), user_profile_source_factory=_default_user_profile_source, + user_email_service=_default_user_email_service(), + ) + + +def _default_v2_user_invitation_service_factory() -> V2UserInvitationResourceService: + from policyengine_api.data.v2.database import ( + get_v2_session_factory, + ) + from policyengine_api.services.v2.user_invitations.database_session import ( + UserInvitationDatabaseSession, + ) + from policyengine_api.services.v2.user_invitations.services import ( + V2UserInvitationService, + ) + + return V2UserInvitationService( + UserInvitationDatabaseSession(get_v2_session_factory()), + user_email_service=_default_user_email_service(), + user_profile_source_factory=_default_user_profile_source, ) @@ -412,6 +451,9 @@ class NativeRouteDependencies: ) v2_account_service_factory: Callable[[], V2AccountResourceService] | None = None v2_user_type_service_factory: Callable[[], V2UserTypeResourceService] | None = None + v2_user_invitation_service_factory: ( + Callable[[], V2UserInvitationResourceService] | None + ) = None # Whole catalog-version responses (/v2/model-catalog and its variables) are # kept here once built; None reads them on every request. v2_metadata_response_cache: MetadataResponseCache | None = None @@ -446,5 +488,8 @@ def defaults(cls) -> NativeRouteDependencies: v2_user_report_service_factory=_default_v2_user_report_service_factory, v2_account_service_factory=_default_v2_account_service_factory, v2_user_type_service_factory=_default_v2_user_type_service_factory, + v2_user_invitation_service_factory=( + _default_v2_user_invitation_service_factory + ), require_user=_default_require_user, ) diff --git a/policyengine_api/fastapi_routes/resource_service_protocols.py b/policyengine_api/fastapi_routes/resource_service_protocols.py index 9c9e116c3..8ef603121 100644 --- a/policyengine_api/fastapi_routes/resource_service_protocols.py +++ b/policyengine_api/fastapi_routes/resource_service_protocols.py @@ -44,6 +44,12 @@ UserHouseholdRead, UserHouseholdUpdateInput, ) + from policyengine_api.services.v2.user_invitations.types import ( + AdminInvitationPage, + AdminInvitationRead, + AdminInvitationSearch, + InvitationAcceptance, + ) from policyengine_api.services.v2.user_policies.types import ( UserPolicyCreateFields, UserPolicyFilter, @@ -485,6 +491,15 @@ def delete_account(self, *, principal: AccountPrincipal) -> AccountDeletion: """ ... + def dismiss_type_change( + self, *, principal: UserPrincipal, type_change_id: UUID + ) -> None: + """Record that the signed-in user dismissed the notice of a type change. + + Raise ``TypeChangeNotFoundError`` unless the user has this change. + """ + ... + class V2UserTypeResourceService(Protocol): """Route-independent minimum user types and admins' changes to users' types.""" @@ -530,3 +545,47 @@ def list_user_type_changes( ) -> tuple[UserTypeChangeRead, ...]: """Return a signed-in user's recorded type changes, newest first.""" ... + + +class V2UserInvitationResourceService(Protocol): + """Route-independent email invitations and their acceptance.""" + + def create_invitation( + self, *, principal: AccountPrincipal, email: str, user_type: UserType + ) -> AdminInvitationRead: + """Invite an address to become an author or admin, then email it.""" + ... + + def list_invitations( + self, *, principal: AccountPrincipal, search: AdminInvitationSearch + ) -> AdminInvitationPage: + """Return one page of open invitations, newest first, to an admin.""" + ... + + def resend_invitation( + self, *, principal: AccountPrincipal, invitation_id: UUID + ) -> AdminInvitationRead: + """Give an open invitation a new link and expiry, and email it again. + + Raise ``InvitationNotFoundError`` unless an open invitation has the ID. + """ + ... + + def revoke_invitation( + self, *, principal: AccountPrincipal, invitation_id: UUID + ) -> None: + """Revoke an open invitation. + + Raise ``InvitationNotFoundError`` unless an open invitation has the ID. + """ + ... + + def accept_invitation( + self, *, principal: UserPrincipal, token: str, country_id: str + ) -> InvitationAcceptance: + """Accept an invitation for the signed-in user, giving its type. + + Raise one of the invitation acceptance errors, each with its ``code``, + when it can't be accepted. + """ + ... diff --git a/policyengine_api/fastapi_routes/v2/admin_invitations/__init__.py b/policyengine_api/fastapi_routes/v2/admin_invitations/__init__.py new file mode 100644 index 000000000..d8a208102 --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/admin_invitations/__init__.py @@ -0,0 +1 @@ +"""Admins' email invitation routes.""" diff --git a/policyengine_api/fastapi_routes/v2/admin_invitations/request_models.py b/policyengine_api/fastapi_routes/v2/admin_invitations/request_models.py new file mode 100644 index 000000000..c117f8c45 --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/admin_invitations/request_models.py @@ -0,0 +1,22 @@ +"""Strict HTTP request models for admins' email invitation routes.""" + +from typing import Literal + +from pydantic import BaseModel, ConfigDict + +from policyengine_api.services.v2.user_invitations.types import ( + InvitationEmailAddress, +) + + +class InvitationCreateRequest(BaseModel): + """The address an admin invites, and the type the invitation grants. + + ``email`` is stripped of surrounding whitespace and must be one address: + an @ with text on both sides and no whitespace, < or >. + """ + + model_config = ConfigDict(extra="forbid") + + email: InvitationEmailAddress + user_type: Literal["author", "admin"] diff --git a/policyengine_api/fastapi_routes/v2/admin_invitations/response_models.py b/policyengine_api/fastapi_routes/v2/admin_invitations/response_models.py new file mode 100644 index 000000000..adb5b098d --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/admin_invitations/response_models.py @@ -0,0 +1,105 @@ +"""Strict HTTP response models for admins' email invitation routes.""" + +from __future__ import annotations + +from datetime import datetime +from typing import TYPE_CHECKING, Generic, Literal, TypeVar +from uuid import UUID + +from pydantic import BaseModel, ConfigDict + +if TYPE_CHECKING: + from policyengine_api.services.v2.user_invitations.types import ( + AdminInvitationPage, + AdminInvitationRead, + ) + + +class StrictInvitationAPIModel(BaseModel): + """Base for invitation responses; rejects unknown fields.""" + + model_config = ConfigDict(extra="forbid") + + +class AdminInvitationItem(StrictInvitationAPIModel): + """An invitation as admins see it. + + ``invited_by_user_id`` is the admin who created or last resent it, null + once that account is deleted. ``expired`` says ``expires_at`` has passed: + it can't be accepted, but it can be resent. ``last_sent_at`` is when + Postmark accepted the email with the current link, null when the last + send failed or wasn't tried; ``last_send_error`` then names why, as a + short identifier such as ``not_configured``, ``timeout``, ``http_500`` + or ``postmark_406`` (an address Postmark suppresses). + """ + + id: UUID + email: str + user_type: Literal["author", "admin"] + invited_by_user_id: UUID | None + created_at: datetime + expires_at: datetime + expired: bool + last_sent_at: datetime | None + last_send_error: str | None + + @classmethod + def from_read(cls, invitation: AdminInvitationRead) -> AdminInvitationItem: + """Convert the service's read model; the type is validated as a literal.""" + return cls.model_validate( + { + "id": invitation.id, + "email": invitation.email, + "user_type": invitation.user_type.value, + "invited_by_user_id": invitation.invited_by_user_id, + "created_at": invitation.created_at, + "expires_at": invitation.expires_at, + "expired": invitation.expired, + "last_sent_at": invitation.last_sent_at, + "last_send_error": invitation.last_send_error, + } + ) + + +class AdminInvitationResult(StrictInvitationAPIModel): + """Result holding one invitation in ``item``.""" + + item: AdminInvitationItem + + +class AdminInvitationPageResult(StrictInvitationAPIModel): + """One page of open invitations, newest first.""" + + items: list[AdminInvitationItem] + offset: int + limit: int + has_more: bool + + @classmethod + def from_page(cls, page: AdminInvitationPage) -> AdminInvitationPageResult: + """Convert the service's page.""" + return cls( + items=[AdminInvitationItem.from_read(item) for item in page.items], + offset=page.offset, + limit=page.limit, + has_more=page.has_more, + ) + + +ResultT = TypeVar("ResultT") + + +class InvitationSuccessResponse(StrictInvitationAPIModel, Generic[ResultT]): + """Success envelope: ``status`` "ok", a null ``message`` and the ``result``.""" + + status: Literal["ok"] = "ok" + message: None = None + result: ResultT + + +class AdminInvitationResponse(InvitationSuccessResponse[AdminInvitationResult]): + """Success response holding one invitation.""" + + +class AdminInvitationPageResponse(InvitationSuccessResponse[AdminInvitationPageResult]): + """Success response holding one page of open invitations.""" diff --git a/policyengine_api/fastapi_routes/v2/admin_invitations/routes.py b/policyengine_api/fastapi_routes/v2/admin_invitations/routes.py new file mode 100644 index 000000000..bc8289f0a --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/admin_invitations/routes.py @@ -0,0 +1,234 @@ +"""Native FastAPI routes for admins' email invitations. + +Every route requires an admin: the router checks the caller's stored type +before any route runs (403 below admin), and each service operation checks it +again inside its own transaction. An invitation's email is sent after the +invitation commits, through Postmark; a failed send leaves it open with the +failure in ``last_send_error``, so the admin can resend it. +""" + +from collections.abc import Callable +from typing import Annotated, Any +from uuid import UUID + +from fastapi import APIRouter, Depends +from starlette.responses import JSONResponse, Response + +from policyengine_api.data.v2.models import UserType +from policyengine_api.fastapi_routes.dependencies import ( + NativeRouteDependencies, + V2UserInvitationResourceService, + V2UserTypeResourceService, + _default_v2_user_invitation_service_factory, + _default_v2_user_type_service_factory, +) +from policyengine_api.fastapi_routes.query_parameters import query_dependency +from policyengine_api.fastapi_routes.v2.admin_invitations.request_models import ( + InvitationCreateRequest, +) +from policyengine_api.fastapi_routes.v2.admin_invitations.response_models import ( + AdminInvitationItem, + AdminInvitationPageResponse, + AdminInvitationPageResult, + AdminInvitationResponse, + AdminInvitationResult, +) +from policyengine_api.fastapi_routes.v2.errors_support import V2ErrorResponse +from policyengine_api.fastapi_routes.v2.user_resources_support import ( + enforce_user_write_request_size, + user_resource_operation, +) +from policyengine_api.fastapi_routes.v2.user_type_support import ( + minimum_user_type_dependency, +) +from policyengine_api.query_parameters import AdminInvitationCollectionQuery +from policyengine_api.services.v2.identity.types import AccountPrincipal +from policyengine_api.services.v2.user_invitations.types import AdminInvitationSearch + +AdminInvitationCollectionQueryDependency = Annotated[ + AdminInvitationCollectionQuery, + Depends(query_dependency(AdminInvitationCollectionQuery)), +] + +ADMIN_INVITATION_ERROR_RESPONSES: dict[int | str, dict[str, Any]] = { + 401: { + "model": V2ErrorResponse, + "description": ( + "A valid bearer access token is required. The response carries " + "WWW-Authenticate: Bearer." + ), + }, + 403: { + "model": V2ErrorResponse, + "description": "Only admins may use these routes.", + }, + 413: { + "model": V2ErrorResponse, + "description": "The request body exceeds 256 KiB.", + }, + 422: { + "model": V2ErrorResponse, + "description": "The request does not match the schema.", + }, + 500: { + "model": V2ErrorResponse, + "description": "The operation could not be completed.", + }, + 503: { + "model": V2ErrorResponse, + "description": "User authentication or persistence is unavailable.", + }, +} +NOT_OPEN_RESPONSE: dict[int | str, dict[str, Any]] = { + 404: { + "model": V2ErrorResponse, + "description": ( + "No open invitation has this ID: it is unknown, accepted or revoked." + ), + }, +} +SEND_DESCRIPTION = ( + "The email is sent through Postmark after the invitation commits, and " + "retried a few times; when every attempt fails, or Postmark isn't " + "configured, the invitation stays open with last_sent_at null and " + "last_send_error naming why. The link is valid for 7 days." +) + + +def _invitation_service_factory( + dependencies: NativeRouteDependencies, +) -> Callable[[], V2UserInvitationResourceService]: + if dependencies.v2_user_invitation_service_factory is not None: + return dependencies.v2_user_invitation_service_factory + return _default_v2_user_invitation_service_factory + + +def _user_type_service_factory( + dependencies: NativeRouteDependencies, +) -> Callable[[], V2UserTypeResourceService]: + if dependencies.v2_user_type_service_factory is not None: + return dependencies.v2_user_type_service_factory + return _default_v2_user_type_service_factory + + +def build_v2_admin_invitation_router( + dependencies: NativeRouteDependencies, +) -> APIRouter: + """Build admins' invitation routes without opening a connection.""" + require_user = dependencies.require_user + service_factory = _invitation_service_factory(dependencies) + require_admin = minimum_user_type_dependency( + require_user, _user_type_service_factory(dependencies), UserType.ADMIN + ) + router = APIRouter( + prefix="/v2/admin", + responses=ADMIN_INVITATION_ERROR_RESPONSES, + dependencies=[Depends(require_user), Depends(require_admin)], + ) + + @router.post( + "/invitations", + response_model=AdminInvitationResponse, + status_code=201, + summary="Invite an email address to become an author or admin", + description=( + "Admins only. Creates the invitation and emails its link to the " + "address; an open invitation to the same address, compared " + "ignoring case, is revoked first, so its link stops working. " + + SEND_DESCRIPTION + + " The response is 201 even when the send failed." + ), + ) + def create_invitation( + body: InvitationCreateRequest, + principal: Annotated[AccountPrincipal, Depends(require_user)], + _size: Annotated[None, Depends(enforce_user_write_request_size)], + ) -> AdminInvitationResponse | JSONResponse: + def create() -> AdminInvitationResponse: + invitation = service_factory().create_invitation( + principal=principal, + email=body.email, + user_type=UserType(body.user_type), + ) + return AdminInvitationResponse( + result=AdminInvitationResult( + item=AdminInvitationItem.from_read(invitation) + ) + ) + + return user_resource_operation(create) + + @router.get( + "/invitations", + response_model=AdminInvitationPageResponse, + summary="List open invitations, newest first", + description=( + "Admins only. Lists the invitations that are neither accepted nor " + "revoked, expired ones included (expired is true)." + ), + ) + def list_invitations( + query: AdminInvitationCollectionQueryDependency, + principal: Annotated[AccountPrincipal, Depends(require_user)], + ) -> AdminInvitationPageResponse | JSONResponse: + def read() -> AdminInvitationPageResponse: + page = service_factory().list_invitations( + principal=principal, + search=AdminInvitationSearch(offset=query.offset, limit=query.limit), + ) + return AdminInvitationPageResponse( + result=AdminInvitationPageResult.from_page(page) + ) + + return user_resource_operation(read) + + @router.post( + "/invitations/{invitation_id}/resend", + response_model=AdminInvitationResponse, + responses=NOT_OPEN_RESPONSE, + summary="Email an open invitation again with a new link", + description=( + "Admins only. Gives the invitation a new link, so the earlier one " + "stops working, and a new 7-day expiry, makes the caller its " + "inviting admin, and emails it again. An expired invitation can be " + "resent. " + SEND_DESCRIPTION + ), + ) + def resend_invitation( + invitation_id: UUID, + principal: Annotated[AccountPrincipal, Depends(require_user)], + ) -> AdminInvitationResponse | JSONResponse: + def resend() -> AdminInvitationResponse: + invitation = service_factory().resend_invitation( + principal=principal, invitation_id=invitation_id + ) + return AdminInvitationResponse( + result=AdminInvitationResult( + item=AdminInvitationItem.from_read(invitation) + ) + ) + + return user_resource_operation(resend) + + @router.delete( + "/invitations/{invitation_id}", + response_model=None, + status_code=204, + response_class=Response, + responses=NOT_OPEN_RESPONSE, + summary="Revoke an open invitation", + description="Admins only. The invitation's link stops working.", + ) + def revoke_invitation( + invitation_id: UUID, + principal: Annotated[AccountPrincipal, Depends(require_user)], + ) -> Response | JSONResponse: + def revoke() -> Response: + service_factory().revoke_invitation( + principal=principal, invitation_id=invitation_id + ) + return Response(status_code=204) + + return user_resource_operation(revoke) + + return router diff --git a/policyengine_api/fastapi_routes/v2/errors_support.py b/policyengine_api/fastapi_routes/v2/errors_support.py index f922c46f2..632442309 100644 --- a/policyengine_api/fastapi_routes/v2/errors_support.py +++ b/policyengine_api/fastapi_routes/v2/errors_support.py @@ -46,6 +46,16 @@ class V2ErrorResponse(BaseModel): message: Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)] +class V2CodedErrorResponse(V2ErrorResponse): + """An error that also names its reason with a stable ``code``. + + Clients choose what to do from ``code``, not from ``message``, which is + for people and may change. + """ + + code: Annotated[str, StringConstraints(min_length=1, max_length=64)] + + class V2MissingParametersErrorResponse(V2ErrorResponse): """A refused calculation whose policy sets parameters the catalog lacks. @@ -73,6 +83,22 @@ def v2_error_response( ) +def v2_coded_error_response( + status_code: int, + message: str, + code: str, + *, + headers: Mapping[str, str] | None = None, +) -> JSONResponse: + """Serialize one API v2 error that names its reason with ``code``.""" + error = V2CodedErrorResponse(message=message, code=code) + return JSONResponse( + status_code=status_code, + content=error.model_dump(mode="json"), + headers=dict(headers) if headers is not None else None, + ) + + def v2_missing_parameters_response( message: str, missing_parameters: Sequence[str] ) -> JSONResponse: diff --git a/policyengine_api/fastapi_routes/v2/me/account_support.py b/policyengine_api/fastapi_routes/v2/me/account_support.py new file mode 100644 index 000000000..53d0824ba --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/me/account_support.py @@ -0,0 +1,50 @@ +"""HTTP support the account routes (/v2/me) share.""" + +# FastAPI evaluates the dependencies' annotations when routes are registered, +# against this module's globals, so they are not postponed and their types are +# imported at runtime. +from collections.abc import Callable +from typing import Annotated + +from fastapi import Depends + +from policyengine_api.fastapi_routes.dependencies import ( + NativeRouteDependencies, + V2AccountResourceService, + _default_v2_account_service_factory, +) +from policyengine_api.fastapi_routes.query_parameters import query_dependency +from policyengine_api.fastapi_routes.v2.user_auth_support import ( + require_signed_in_principal, +) +from policyengine_api.query_parameters import CountryQuery +from policyengine_api.services.v2.identity.types import ( + AccountPrincipal, + UserPrincipal, +) + +CountryQueryDependency = Annotated[ + CountryQuery, Depends(query_dependency(CountryQuery)) +] + + +def account_service_factory( + dependencies: NativeRouteDependencies, +) -> Callable[[], V2AccountResourceService]: + """Return the account service factory, or the default one.""" + if dependencies.v2_account_service_factory is not None: + return dependencies.v2_account_service_factory + return _default_v2_account_service_factory + + +def signed_in_user_dependency( + require_user: Callable[..., AccountPrincipal], +) -> Callable[..., UserPrincipal]: + """Build a dependency that admits only a signed-in principal of ``require_user``.""" + + def require_signed_in_user( + principal: Annotated[AccountPrincipal, Depends(require_user)], + ) -> UserPrincipal: + return require_signed_in_principal(principal) + + return require_signed_in_user diff --git a/policyengine_api/fastapi_routes/v2/me/request_models.py b/policyengine_api/fastapi_routes/v2/me/request_models.py index b0f9bf15d..268b8cb48 100644 --- a/policyengine_api/fastapi_routes/v2/me/request_models.py +++ b/policyengine_api/fastapi_routes/v2/me/request_models.py @@ -1,7 +1,18 @@ """Strict HTTP request models for the account resource.""" +from pydantic import BaseModel, ConfigDict + from policyengine_api.services.v2.user_accounts.types import AccountUpdateInput +from policyengine_api.services.v2.user_invitations.types import InvitationToken class AccountPatchRequest(AccountUpdateInput): """Explicitly supplied account presentation fields.""" + + +class InvitationAcceptRequest(BaseModel): + """The token from an invitation's link, from its ``#token=`` fragment.""" + + model_config = ConfigDict(extra="forbid") + + token: InvitationToken diff --git a/policyengine_api/fastapi_routes/v2/me/response_models.py b/policyengine_api/fastapi_routes/v2/me/response_models.py index f11e01f67..f5983941c 100644 --- a/policyengine_api/fastapi_routes/v2/me/response_models.py +++ b/policyengine_api/fastapi_routes/v2/me/response_models.py @@ -27,7 +27,13 @@ AccountExport, AccountRead, AccountUpgrade, + LatestTypeChangeRead, ) + from policyengine_api.services.v2.user_invitations.types import ( + InvitationAcceptance, + ) + +SignedInUserType = Literal["standard", "author", "admin"] class StrictAccountAPIModel(BaseModel): @@ -67,6 +73,80 @@ class MeDetailResult(StrictAccountAPIModel): item: MeItem +class LatestTypeChangeItem(StrictAccountAPIModel): + """The user's most recent type change, from ``previous_user_type``.""" + + id: UUID + previous_user_type: SignedInUserType + user_type: SignedInUserType + changed_at: datetime + + @classmethod + def from_read(cls, change: LatestTypeChangeRead) -> LatestTypeChangeItem: + """Convert the service's read model; the types are validated as literals.""" + return cls.model_validate( + { + "id": change.id, + "previous_user_type": change.previous_user_type.value, + "user_type": change.user_type.value, + "changed_at": change.changed_at, + } + ) + + +class MeReadResult(StrictAccountAPIModel): + """The current user, and their most recent type change until it is dismissed. + + ``latest_type_change`` is null when the user's type never changed, when + its most recent change was dismissed, and for an unauthenticated user. + """ + + item: MeItem + latest_type_change: LatestTypeChangeItem | None + + @classmethod + def from_read(cls, account: AccountRead) -> MeReadResult: + """Build the result from the service's account read.""" + change = account.latest_type_change + return cls( + item=MeItem.from_read(account), + latest_type_change=( + None if change is None else LatestTypeChangeItem.from_read(change) + ), + ) + + +class InvitationAcceptanceItem(StrictAccountAPIModel): + """The user's type after accepting an invitation, and before. + + ``type_changed`` is false when the user already had the invited type or a + higher one: an invitation never lowers a type. + """ + + user_type: SignedInUserType + previous_user_type: SignedInUserType + type_changed: bool + + @classmethod + def from_acceptance( + cls, acceptance: InvitationAcceptance + ) -> InvitationAcceptanceItem: + """Convert the service's acceptance; the types are validated as literals.""" + return cls.model_validate( + { + "user_type": acceptance.user_type.value, + "previous_user_type": acceptance.previous_user_type.value, + "type_changed": acceptance.type_changed, + } + ) + + +class InvitationAcceptanceResult(StrictAccountAPIModel): + """Result holding the accepted invitation's outcome in ``item``.""" + + item: InvitationAcceptanceItem + + class MeExportResult(StrictAccountAPIModel): """The current user and every policy, household, simulation and report it saved. @@ -131,6 +211,14 @@ class MeDetailResponse(AccountSuccessResponse[MeDetailResult]): """Success response holding the current user.""" +class MeReadResponse(AccountSuccessResponse[MeReadResult]): + """Success response holding the current user and their latest type change.""" + + +class InvitationAcceptanceResponse(AccountSuccessResponse[InvitationAcceptanceResult]): + """Success response holding an accepted invitation's outcome.""" + + class MeExportResponse(AccountSuccessResponse[MeExportResult]): """Success response holding the current user's export.""" diff --git a/policyengine_api/fastapi_routes/v2/me/routes.py b/policyengine_api/fastapi_routes/v2/me/routes.py index f07e5be99..8385ed60a 100644 --- a/policyengine_api/fastapi_routes/v2/me/routes.py +++ b/policyengine_api/fastapi_routes/v2/me/routes.py @@ -5,6 +5,9 @@ unauthenticated user exists only after its first saved record, so reading an absent one returns 404 and exporting it returns nothing. Every route requires a credential; authentication is a router-level dependency. + +Reading the account also reports the user's latest type change until it is +dismissed; ``user_type_routes`` accepts invitations and dismisses changes. """ from collections.abc import Callable @@ -17,10 +20,13 @@ from policyengine_api.fastapi_routes.dependencies import ( NativeRouteDependencies, V2AccountResourceService, - _default_v2_account_service_factory, ) -from policyengine_api.fastapi_routes.query_parameters import query_dependency from policyengine_api.fastapi_routes.v2.errors_support import V2ErrorResponse +from policyengine_api.fastapi_routes.v2.me.account_support import ( + CountryQueryDependency, + account_service_factory, + signed_in_user_dependency, +) from policyengine_api.fastapi_routes.v2.me.request_models import ( AccountPatchRequest, ) @@ -30,12 +36,11 @@ MeExportResponse, MeExportResult, MeItem, + MeReadResponse, + MeReadResult, MeUpgradeResponse, MeUpgradeResult, ) -from policyengine_api.fastapi_routes.v2.user_auth_support import ( - require_signed_in_principal, -) from policyengine_api.fastapi_routes.v2.user_resources_support import ( USER_RESOURCE_ERROR_RESPONSES, enforce_user_write_request_size, @@ -45,37 +50,11 @@ CANONICAL_UUID_PATTERN, UNAUTHENTICATED_USER_HEADER, ) -from policyengine_api.query_parameters import CountryQuery from policyengine_api.services.v2.identity.types import ( AccountPrincipal, UserPrincipal, ) -CountryQueryDependency = Annotated[ - CountryQuery, Depends(query_dependency(CountryQuery)) -] - - -def _service_factory( - dependencies: NativeRouteDependencies, -) -> Callable[[], V2AccountResourceService]: - if dependencies.v2_account_service_factory is not None: - return dependencies.v2_account_service_factory - return _default_v2_account_service_factory - - -def _signed_in_user_dependency( - require_user: Callable[..., AccountPrincipal], -) -> Callable[..., UserPrincipal]: - """Build a dependency that admits only a signed-in principal of ``require_user``.""" - - def require_signed_in_user( - principal: Annotated[AccountPrincipal, Depends(require_user)], - ) -> UserPrincipal: - return require_signed_in_principal(principal) - - return require_signed_in_user - def _upgrade_account( service_factory: Callable[[], V2AccountResourceService], @@ -104,31 +83,32 @@ def build_v2_me_router(dependencies: NativeRouteDependencies) -> APIRouter: responses=USER_RESOURCE_ERROR_RESPONSES, dependencies=[Depends(require_user)], ) - service_factory = _service_factory(dependencies) - require_signed_in_user = _signed_in_user_dependency(require_user) + service_factory = account_service_factory(dependencies) + require_signed_in_user = signed_in_user_dependency(require_user) @router.get( "/me", - response_model=MeDetailResponse, + response_model=MeReadResponse, summary="Read the current user", description=( "For a bearer access token, returns the PolicyEngine user, creating " "it on the first call with primary_country set from country_id. For " "the PolicyEngine-Unauthenticated-User header, returns the " "browser's unauthenticated user, or 404 before its first saved " - "record; reading never creates one." + "record; reading never creates one. latest_type_change is the " + "user's most recent type change until it is dismissed, else null." ), ) def get_me( query: CountryQueryDependency, principal: Annotated[AccountPrincipal, Depends(require_user)], - ) -> MeDetailResponse | JSONResponse: - def read() -> MeDetailResponse: - item = service_factory().get_account( + ) -> MeReadResponse | JSONResponse: + def read() -> MeReadResponse: + account = service_factory().get_account( principal=principal, country_id=query.country_id, ) - return MeDetailResponse(result=MeDetailResult(item=MeItem.from_read(item))) + return MeReadResponse(result=MeReadResult.from_read(account)) return user_resource_operation(read) diff --git a/policyengine_api/fastapi_routes/v2/me/user_type_routes.py b/policyengine_api/fastapi_routes/v2/me/user_type_routes.py new file mode 100644 index 000000000..f969d0e14 --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/me/user_type_routes.py @@ -0,0 +1,174 @@ +"""Native FastAPI routes for the signed-in user's type, under /v2/me. + +A signed-in user accepts an admin's email invitation with the token from its +link, and dismisses the notice of their latest type change, which +``GET /v2/me`` reports until then. Both need a bearer access token: the +unauthenticated-user header alone is refused with 401. +""" + +from collections.abc import Callable +from typing import Annotated, Any +from uuid import UUID + +from fastapi import APIRouter, Depends +from starlette.responses import JSONResponse, Response + +from policyengine_api.fastapi_routes.dependencies import ( + NativeRouteDependencies, + V2UserInvitationResourceService, + _default_v2_user_invitation_service_factory, +) +from policyengine_api.fastapi_routes.v2.errors_support import ( + V2CodedErrorResponse, + V2ErrorResponse, +) +from policyengine_api.fastapi_routes.v2.me.account_support import ( + CountryQueryDependency, + account_service_factory, + signed_in_user_dependency, +) +from policyengine_api.fastapi_routes.v2.me.request_models import ( + InvitationAcceptRequest, +) +from policyengine_api.fastapi_routes.v2.me.response_models import ( + InvitationAcceptanceItem, + InvitationAcceptanceResponse, + InvitationAcceptanceResult, +) +from policyengine_api.fastapi_routes.v2.user_resources_support import ( + USER_RESOURCE_ERROR_RESPONSES, + enforce_user_write_request_size, + user_resource_operation, +) +from policyengine_api.services.v2.identity.types import UserPrincipal + + +def _invitation_service_factory( + dependencies: NativeRouteDependencies, +) -> Callable[[], V2UserInvitationResourceService]: + if dependencies.v2_user_invitation_service_factory is not None: + return dependencies.v2_user_invitation_service_factory + return _default_v2_user_invitation_service_factory + + +ACCEPTANCE_ERROR_RESPONSES: dict[int | str, dict[str, Any]] = { + 401: { + "model": V2ErrorResponse, + "description": ( + "A valid bearer access token is required; the unauthenticated-user " + "header alone can't accept an invitation." + ), + }, + 403: { + "model": V2CodedErrorResponse, + "description": ( + "code email_mismatch: the signed-in user's verified email isn't the " + "invited address, compared whole and ignoring case. The invitation " + "stays open." + ), + }, + 409: { + "model": V2CodedErrorResponse, + "description": ( + "code inviter_not_admin: the admin who sent the invitation is no " + "longer an admin. code email_not_verified: Auth0 has no verified " + "email for the signed-in user yet; try again once it is verified." + ), + }, + 410: { + "model": V2CodedErrorResponse, + "description": ( + "The token can't be accepted. code invitation_not_found: no " + "invitation has it, including a link replaced by a resend; " + "invitation_revoked: it was revoked or replaced by a newer " + "invitation; invitation_expired; invitation_accepted." + ), + }, + 503: { + "model": V2CodedErrorResponse, + "description": ( + "code auth0_unavailable: the signed-in user's email couldn't be " + "read from Auth0; try again shortly. Persistence being unavailable " + "is also 503, without a code." + ), + }, +} + + +def build_v2_me_user_type_router(dependencies: NativeRouteDependencies) -> APIRouter: + """Build the invitation acceptance and type-change dismissal routes.""" + require_user = dependencies.require_user + router = APIRouter( + prefix="/v2", + responses=USER_RESOURCE_ERROR_RESPONSES, + dependencies=[Depends(require_user)], + ) + service_factory = account_service_factory(dependencies) + invitation_service_factory = _invitation_service_factory(dependencies) + require_signed_in_user = signed_in_user_dependency(require_user) + + @router.post( + "/me/invitations/accept", + response_model=InvitationAcceptanceResponse, + responses=ACCEPTANCE_ERROR_RESPONSES, + summary="Accept an admin's email invitation with its token", + description=( + "Signed-in users only. A user with no account yet gets one, with " + "primary_country from country_id. The signed-in user's email is " + "read from Auth0 first and never stored; then the token, the " + "inviting admin, the email's verification and its match with the " + "invited address are checked, in that order, and each refusal " + "names its code. On success the user gets the invited type, unless " + "they already have it or a higher one, the invitation is marked " + "accepted, and a type change is recorded and emailed to the user." + ), + ) + def accept_invitation( + body: InvitationAcceptRequest, + query: CountryQueryDependency, + principal: Annotated[UserPrincipal, Depends(require_signed_in_user)], + _size: Annotated[None, Depends(enforce_user_write_request_size)], + ) -> InvitationAcceptanceResponse | JSONResponse: + def accept() -> InvitationAcceptanceResponse: + acceptance = invitation_service_factory().accept_invitation( + principal=principal, token=body.token, country_id=query.country_id + ) + return InvitationAcceptanceResponse( + result=InvitationAcceptanceResult( + item=InvitationAcceptanceItem.from_acceptance(acceptance) + ) + ) + + return user_resource_operation(accept) + + @router.post( + "/me/type-changes/{type_change_id}/dismiss", + response_model=None, + status_code=204, + response_class=Response, + responses={ + 404: { + "model": V2ErrorResponse, + "description": "The signed-in user has no type change with this ID.", + }, + }, + summary="Dismiss the notice of a type change", + description=( + "Signed-in users only. GET /v2/me then stops reporting the change " + "as latest_type_change. Dismissing it again changes nothing." + ), + ) + def dismiss_type_change( + type_change_id: UUID, + _query: CountryQueryDependency, + principal: Annotated[UserPrincipal, Depends(require_signed_in_user)], + ) -> Response | JSONResponse: + def dismiss() -> Response: + service_factory().dismiss_type_change( + principal=principal, type_change_id=type_change_id + ) + return Response(status_code=204) + + return user_resource_operation(dismiss) + + return router diff --git a/policyengine_api/fastapi_routes/v2/routes.py b/policyengine_api/fastapi_routes/v2/routes.py index 1153588af..26f13beb3 100644 --- a/policyengine_api/fastapi_routes/v2/routes.py +++ b/policyengine_api/fastapi_routes/v2/routes.py @@ -7,6 +7,9 @@ from fastapi import APIRouter, Request from starlette.responses import JSONResponse +from policyengine_api.fastapi_routes.v2.admin_invitations.routes import ( + build_v2_admin_invitation_router, +) from policyengine_api.fastapi_routes.v2.admin_users.routes import ( build_v2_admin_user_router, ) @@ -21,6 +24,9 @@ build_v2_household_router, ) from policyengine_api.fastapi_routes.v2.me.routes import build_v2_me_router +from policyengine_api.fastapi_routes.v2.me.user_type_routes import ( + build_v2_me_user_type_router, +) from policyengine_api.fastapi_routes.v2.metadata.catalog_routes import ( build_v2_model_catalog_router, ) @@ -58,7 +64,9 @@ def build_v2_router( """Build isolated resource routes without loading v2 configuration.""" router = APIRouter() router.include_router(build_v2_me_router(dependencies)) + router.include_router(build_v2_me_user_type_router(dependencies)) router.include_router(build_v2_admin_user_router(dependencies)) + router.include_router(build_v2_admin_invitation_router(dependencies)) router.include_router(build_v2_user_report_router(dependencies)) router.include_router(build_v2_shared_report_router(dependencies)) router.include_router(build_v2_user_simulation_router(dependencies)) diff --git a/policyengine_api/fastapi_routes/v2/user_resources_support.py b/policyengine_api/fastapi_routes/v2/user_resources_support.py index c862ed405..176a1ca37 100644 --- a/policyengine_api/fastapi_routes/v2/user_resources_support.py +++ b/policyengine_api/fastapi_routes/v2/user_resources_support.py @@ -17,6 +17,7 @@ BEARER_CHALLENGE, V2ErrorResponse, V2RequestTooLargeError, + v2_coded_error_response, v2_error_response, ) from policyengine_api.services.v2.associations.validators import ( @@ -36,10 +37,19 @@ AccountEditRequiresSignInError, AccountIdentityDeletionError, AccountNotFoundError, + TypeChangeNotFoundError, ) from policyengine_api.services.v2.user_households.validators import ( AssociationHouseholdNotFoundError, ) +from policyengine_api.services.v2.user_invitations.validators import ( + InvitationEmailMismatchError, + InvitationEmailNotVerifiedError, + InvitationEmailUnavailableError, + InvitationNotFoundError, + InvitationUnavailableError, + InviterNotAdminError, +) from policyengine_api.services.v2.user_policies.validators import ( AssociationPolicyNotFoundError, ) @@ -181,6 +191,7 @@ class UserResourceFailure(NamedTuple): Without a ``message``, the response carries the error's own message. A ``logged_event`` records the failure, without its message, under that name. + With ``coded``, the response also carries the error's ``code`` attribute. """ error_types: tuple[type[Exception], ...] @@ -188,6 +199,7 @@ class UserResourceFailure(NamedTuple): message: str | None = None headers: Mapping[str, str] | None = None logged_event: str | None = None + coded: bool = False # Checked in order, so a subclass is listed before any base it shares a status @@ -200,6 +212,13 @@ class UserResourceFailure(NamedTuple): ), UserResourceFailure((AccountEditRequiresSignInError,), 403), UserResourceFailure((UserTypeBelowMinimumError,), 403), + # A refused invitation acceptance names its reason with a code. + UserResourceFailure((InvitationEmailMismatchError,), 403, coded=True), + UserResourceFailure( + (InviterNotAdminError, InvitationEmailNotVerifiedError), 409, coded=True + ), + UserResourceFailure((InvitationUnavailableError,), 410, coded=True), + UserResourceFailure((InvitationEmailUnavailableError,), 503, coded=True), UserResourceFailure((AssociationReferenceConflictError,), 400), UserResourceFailure( ( @@ -216,6 +235,8 @@ class UserResourceFailure(NamedTuple): AssociationHouseholdNotFoundError, AccountNotFoundError, SignedInUserNotFoundError, + InvitationNotFoundError, + TypeChangeNotFoundError, ), 404, ), @@ -252,6 +273,13 @@ def _user_failure_response(error: Exception) -> JSONResponse: if failure.logged_event is not None: _log_failure(failure.logged_event, error) message = str(error) if failure.message is None else failure.message + if failure.coded: + return v2_coded_error_response( + failure.status_code, + message, + str(getattr(error, "code", "")), + headers=failure.headers, + ) return v2_error_response( failure.status_code, message, headers=failure.headers ) diff --git a/policyengine_api/libs/postmark_email.py b/policyengine_api/libs/postmark_email.py new file mode 100644 index 000000000..c3a76125b --- /dev/null +++ b/policyengine_api/libs/postmark_email.py @@ -0,0 +1,311 @@ +"""Optional email through Postmark's HTTP API, for invitations and type changes. + +The Public API sends only template emails: ``POST /email/withTemplate`` with a +template alias and the data the template fills in, on the default +transactional message stream. Postmark keeps the templates, their layout and +HTML, delivery to the recipient's mail server, DKIM signing, suppression of +addresses that bounced or complained, and the activity log, so none of that +is done here. + +One settings group configures it, all or none: + +- the server token, from exactly one source: ``POSTMARK_SERVER_TOKEN``, the + token itself, for local use, or ``POSTMARK_SERVER_TOKEN_SECRET_RESOURCE``, + the Secret Manager version that holds it, as deployments set it; +- ``POSTMARK_SENDER_ADDRESS``, the From address, which may carry a display + name (``PolicyEngine ``); +- ``POLICYENGINE_APP_URL``, the app's address the emails link to. + +Without them nothing is sent, and callers record that. This module never +logs, or puts in an error message, an email address, the token or a template +model. +""" + +from __future__ import annotations + +import os +import re +import time +from dataclasses import dataclass, field +from functools import cache +from http import HTTPStatus +from typing import TYPE_CHECKING +from urllib.parse import urlsplit + +import httpx + +if TYPE_CHECKING: + from collections.abc import Callable, Mapping + +POSTMARK_SERVER_TOKEN_ENV = "POSTMARK_SERVER_TOKEN" # noqa: S105 # an environment variable name, not a secret +POSTMARK_SERVER_TOKEN_SECRET_RESOURCE_ENV = "POSTMARK_SERVER_TOKEN_SECRET_RESOURCE" # noqa: S105 # an environment variable name, not a secret +POSTMARK_SENDER_ADDRESS_ENV = "POSTMARK_SENDER_ADDRESS" +POLICYENGINE_APP_URL_ENV = "POLICYENGINE_APP_URL" +POSTMARK_ENV_VARS = ( + POSTMARK_SERVER_TOKEN_ENV, + POSTMARK_SERVER_TOKEN_SECRET_RESOURCE_ENV, + POSTMARK_SENDER_ADDRESS_ENV, + POLICYENGINE_APP_URL_ENV, +) +POSTMARK_TEMPLATE_URL = "https://api.postmarkapp.com/email/withTemplate" +# The statuses whose answer names Postmark's own error code for the email. +POSTMARK_REFUSAL_STATUSES = frozenset({HTTPStatus.OK, HTTPStatus.UNPROCESSABLE_ENTITY}) +# Postmark's default transactional message stream. +MESSAGE_STREAM = "outbound" +HTTP_TIMEOUT_SECONDS = 5.0 +# A failed request is tried this many times in all, waiting before each retry. +SEND_ATTEMPTS = 3 +RETRY_WAIT_SECONDS = (0.5, 1.0) +SECRET_RESOURCE_PATTERN = re.compile(r"^projects/[^/]+/secrets/[^/]+/versions/[^/]+$") +MAXIMUM_SENDER_LENGTH = 320 +# One address, optionally after a display name, with no line breaks: Postmark +# reads the From field as one header value. +SENDER_PATTERN = re.compile(r"^[^\r\n]*?@]+@[^\s<>@]+\.[^\s<>@]+>?$") +LOCAL_APP_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"}) + + +class PostmarkConfigurationError(RuntimeError): + """Raised when the optional Postmark settings are incomplete or invalid.""" + + +class EmailSendError(RuntimeError): + """Raised when Postmark did not accept an email after every attempt. + + ``cause`` says why, with no personal data: ``http_``, + ``postmark_`` for an email Postmark refused with its own + error code (406 is a suppressed address), ``timeout``, + ``connection_error`` or ``secret_unavailable``. + """ + + def __init__(self, cause: str) -> None: + """Keep ``cause``, which also forms the message.""" + super().__init__(f"Postmark did not accept the email: {cause}") + self.cause = cause + + +@dataclass(frozen=True) +class PostmarkSettings: + """Validated Postmark settings. + + Exactly one of ``server_token`` and ``server_token_resource`` (a Secret + Manager version name) is set; the token is kept out of ``repr``. + ``app_url`` has no trailing slash. + """ + + sender_address: str + app_url: str + server_token: str = field(default="", repr=False) + server_token_resource: str = "" + + +def _app_url(value: str) -> str: + """Return the app's address without a trailing slash, or raise.""" + parts = urlsplit(value) + local = parts.scheme == "http" and parts.hostname in LOCAL_APP_HOSTS + if not parts.netloc or not (parts.scheme == "https" or local): + msg = ( + f"{POLICYENGINE_APP_URL_ENV} must be an https address (http only " + "for localhost)" + ) + raise PostmarkConfigurationError(msg) + if parts.query or parts.fragment or value.endswith(("?", "#")): + msg = f"{POLICYENGINE_APP_URL_ENV} must have no query or fragment" + raise PostmarkConfigurationError(msg) + return value.rstrip("/") + + +def load_postmark_settings( + environ: Mapping[str, str] | None = None, +) -> PostmarkSettings | None: + """Return complete Postmark settings, or ``None`` when none are set.""" + values = os.environ if environ is None else environ + token = values.get(POSTMARK_SERVER_TOKEN_ENV, "").strip() + token_resource = values.get(POSTMARK_SERVER_TOKEN_SECRET_RESOURCE_ENV, "").strip() + sender = values.get(POSTMARK_SENDER_ADDRESS_ENV, "").strip() + app_url = values.get(POLICYENGINE_APP_URL_ENV, "").strip() + if not any((token, token_resource, sender, app_url)): + return None + if token and token_resource: + msg = ( + f"Set exactly one of {POSTMARK_SERVER_TOKEN_ENV} or " + f"{POSTMARK_SERVER_TOKEN_SECRET_RESOURCE_ENV}" + ) + raise PostmarkConfigurationError(msg) + if not (token or token_resource) or not sender or not app_url: + msg = ( + "Postmark email is partially configured: set " + f"{POSTMARK_SENDER_ADDRESS_ENV}, {POLICYENGINE_APP_URL_ENV}, and " + "exactly one server-token source" + ) + raise PostmarkConfigurationError(msg) + if token_resource and SECRET_RESOURCE_PATTERN.fullmatch(token_resource) is None: + msg = f"{POSTMARK_SERVER_TOKEN_SECRET_RESOURCE_ENV} is invalid" + raise PostmarkConfigurationError(msg) + if len(sender) > MAXIMUM_SENDER_LENGTH or SENDER_PATTERN.fullmatch(sender) is None: + msg = f"{POSTMARK_SENDER_ADDRESS_ENV} must be an email address" + raise PostmarkConfigurationError(msg) + return PostmarkSettings( + sender_address=sender, + app_url=_app_url(app_url), + server_token=token, + server_token_resource=token_resource, + ) + + +@cache +def _load_secret_from_secret_manager(resource_name: str) -> str: + from google.cloud import secretmanager + + client = secretmanager.SecretManagerServiceClient() + response = client.access_secret_version(request={"name": resource_name}) + return response.payload.data.decode("utf-8") + + +def _postmark_error_code(response: httpx.Response) -> int | None: + """Return the answer's Postmark ``ErrorCode``, or None when it has none.""" + try: + answer = response.json() + except ValueError: + return None + if not isinstance(answer, dict): + return None + error_code = answer.get("ErrorCode") + if isinstance(error_code, bool) or not isinstance(error_code, int): + return None + return error_code + + +def _retryable(response: httpx.Response) -> bool: + """Say whether Postmark may accept the same request later.""" + return ( + response.status_code == HTTPStatus.TOO_MANY_REQUESTS + or response.status_code >= HTTPStatus.INTERNAL_SERVER_ERROR + ) + + +class PostmarkEmailSender: + """Send template emails through Postmark, retrying a failed request.""" + + def __init__( + self, + settings: PostmarkSettings, + *, + http_client: httpx.Client | None = None, + secret_loader: Callable[[str], str] = _load_secret_from_secret_manager, + sleep: Callable[[float], None] = time.sleep, + ) -> None: + """Use ``settings``; tests pass a mock ``http_client`` and ``sleep``. + + ``secret_loader`` reads ``server_token_resource`` when no token is + set directly. + """ + self._settings = settings + self._http_client = http_client + self._secret_loader = secret_loader + self._sleep = sleep + + @property + def app_url(self) -> str: + """Return the app's address that emails link to, without a trailing slash.""" + return self._settings.app_url + + def _server_token(self) -> str: + if self._settings.server_token: + return self._settings.server_token + cause = "secret_unavailable" + try: + token = self._secret_loader(self._settings.server_token_resource).strip() + except Exception as error: + raise EmailSendError(cause) from error + if not token: + raise EmailSendError(cause) + return token + + def _post(self, http_client: httpx.Client, request: httpx.Request) -> str | None: + """Send one attempt; return None when accepted, else its failure cause. + + Raise EmailSendError for an answer that a retry wouldn't change. + """ + try: + response = http_client.send(request) + except httpx.TimeoutException: + return "timeout" + except httpx.HTTPError: + return "connection_error" + error_code = _postmark_error_code(response) + if response.status_code == HTTPStatus.OK and not error_code: + return None + if _retryable(response): + return f"http_{response.status_code}" + # Postmark refuses an email it can't send, such as one to a + # suppressed address, with 422 and its own error code. + if error_code and response.status_code in POSTMARK_REFUSAL_STATUSES: + cause = f"postmark_{error_code}" + else: + cause = f"http_{response.status_code}" + raise EmailSendError(cause) + + def send_template( + self, + *, + to: str, + template_alias: str, + template_model: Mapping[str, object], + ) -> None: + """Send the template ``template_alias`` filled with ``template_model``. + + A timeout, a connection error, HTTP 429 or a server error is tried + again, up to three attempts in all, after waits of 0.5 and 1 second; + a retried timeout may send the email twice. Raise EmailSendError, + with its cause, when Postmark refuses the email or every attempt + fails. + """ + request_body = { + "From": self._settings.sender_address, + "To": to, + "TemplateAlias": template_alias, + "TemplateModel": dict(template_model), + "MessageStream": MESSAGE_STREAM, + } + headers = { + "Accept": "application/json", + "X-Postmark-Server-Token": self._server_token(), + } + if self._http_client is not None: + self._send_with_retries(self._http_client, request_body, headers) + return + with httpx.Client(timeout=HTTP_TIMEOUT_SECONDS) as http_client: + self._send_with_retries(http_client, request_body, headers) + + def _send_with_retries( + self, + http_client: httpx.Client, + request_body: Mapping[str, object], + headers: Mapping[str, str], + ) -> None: + cause = "unknown" + for attempt in range(SEND_ATTEMPTS): + if attempt: + self._sleep(RETRY_WAIT_SECONDS[attempt - 1]) + request = http_client.build_request( + "POST", POSTMARK_TEMPLATE_URL, json=request_body, headers=headers + ) + failure = self._post(http_client, request) + if failure is None: + return + cause = failure + raise EmailSendError(cause) + + +def build_postmark_email_sender( + environ: Mapping[str, str] | None = None, +) -> PostmarkEmailSender | None: + """Return a sender for the configured Postmark server, or ``None``. + + Settings are read on each call; invalid ones raise + PostmarkConfigurationError. + """ + settings = load_postmark_settings(environ) + if settings is None: + return None + return PostmarkEmailSender(settings) diff --git a/policyengine_api/query_parameters.py b/policyengine_api/query_parameters.py index 8d8aad15e..92c2df8f8 100644 --- a/policyengine_api/query_parameters.py +++ b/policyengine_api/query_parameters.py @@ -374,6 +374,10 @@ class AdminUserCollectionQuery(PaginationQuery): email: EmailSearch | None = None +class AdminInvitationCollectionQuery(PaginationQuery): + """Query contract for admins' list of open email invitations.""" + + class HouseholdCreateQuery(CountryQuery): """Query contract for native immutable household creation.""" diff --git a/policyengine_api/readiness.py b/policyengine_api/readiness.py index 9fecc0e88..6200cb447 100644 --- a/policyengine_api/readiness.py +++ b/policyengine_api/readiness.py @@ -16,7 +16,7 @@ def validate_policy_runtime_configuration() -> None: - """Validate source selectors, v2 persistence, auth, Auth0 and measurement.""" + """Validate source selectors, v2 persistence, auth, Auth0, email and measurement.""" from policyengine_api.data.v2.settings import ( # noqa: PLC0415 # keeps importing readiness cheap; only validation needs configuration load_v2_runtime_database_settings, ) @@ -24,6 +24,7 @@ def validate_policy_runtime_configuration() -> None: load_auth0_management_settings, load_auth0_user_profile_settings, ) + from policyengine_api.libs.postmark_email import load_postmark_settings from policyengine_api.libs.server_credentials import ( # noqa: PLC0415 # keeps importing readiness cheap; only validation needs configuration load_server_credential_requirement, load_server_credential_settings, @@ -60,6 +61,9 @@ def validate_policy_runtime_configuration() -> None: # Unusable profile settings would leave admins without emails and make # every email search answer 503. load_auth0_user_profile_settings() + # Unusable email settings would leave every invitation unsent and every + # type change unannounced; absent ones only send nothing. + load_postmark_settings() # A bundle whose measurement configuration this build cannot serve would # reject every country request. Report it here, where the deployment is # gated, instead of only on the requests themselves. diff --git a/policyengine_api/services/v2/user_accounts/database_connectors/reads.py b/policyengine_api/services/v2/user_accounts/database_connectors/reads.py index dbff75726..eea2d3849 100644 --- a/policyengine_api/services/v2/user_accounts/database_connectors/reads.py +++ b/policyengine_api/services/v2/user_accounts/database_connectors/reads.py @@ -6,7 +6,7 @@ from sqlmodel import Session, col, select -from policyengine_api.data.v2.models import User, UserIdentity +from policyengine_api.data.v2.models import User, UserIdentity, UserTypeChange if TYPE_CHECKING: from uuid import UUID @@ -31,3 +31,26 @@ def read_identity_subjects( .order_by(col(UserIdentity.created_at), col(UserIdentity.id)) ).all() ) + + +def read_latest_user_type_change( + session: Session, user_id: UUID +) -> UserTypeChange | None: + """Return the user's most recent recorded type change, or None.""" + return session.exec( + select(UserTypeChange) + .where(UserTypeChange.user_id == user_id) + .order_by(col(UserTypeChange.created_at).desc(), col(UserTypeChange.id).desc()) + .limit(1) + ).first() + + +def read_user_type_change( + session: Session, type_change_id: UUID, *, user_id: UUID +) -> UserTypeChange | None: + """Return this user's recorded type change with this ID, or None.""" + return session.exec( + select(UserTypeChange).where( + UserTypeChange.id == type_change_id, UserTypeChange.user_id == user_id + ) + ).one_or_none() diff --git a/policyengine_api/services/v2/user_accounts/database_connectors/updates.py b/policyengine_api/services/v2/user_accounts/database_connectors/updates.py index cd6a0c99f..3ed8e488d 100644 --- a/policyengine_api/services/v2/user_accounts/database_connectors/updates.py +++ b/policyengine_api/services/v2/user_accounts/database_connectors/updates.py @@ -6,10 +6,11 @@ if TYPE_CHECKING: from collections.abc import Mapping + from datetime import datetime from sqlmodel import Session - from policyengine_api.data.v2.models import User + from policyengine_api.data.v2.models import User, UserTypeChange def update_account_user( @@ -24,3 +25,13 @@ def update_account_user( session.flush() session.refresh(user) return user + + +def dismiss_user_type_change( + session: Session, change: UserTypeChange, *, dismissed_at: datetime +) -> UserTypeChange: + """Record when the user dismissed the app's notice of a type change.""" + change.dismissed_at = dismissed_at + session.add(change) + session.flush() + return change diff --git a/policyengine_api/services/v2/user_accounts/services.py b/policyengine_api/services/v2/user_accounts/services.py index 0831e8ac0..16aae4232 100644 --- a/policyengine_api/services/v2/user_accounts/services.py +++ b/policyengine_api/services/v2/user_accounts/services.py @@ -22,6 +22,7 @@ from typing import TYPE_CHECKING from policyengine_api.data.v2.models import UserType +from policyengine_api.data.v2.models.base import utc_now from policyengine_api.services.v2.identity.database_connectors.deletes import ( delete_unauthenticated_user, ) @@ -43,13 +44,17 @@ from policyengine_api.services.v2.user_accounts.database_connectors.reads import ( read_account_user, read_identity_subjects, + read_latest_user_type_change, + read_user_type_change, ) from policyengine_api.services.v2.user_accounts.database_connectors.updates import ( + dismiss_user_type_change, update_account_user, ) from policyengine_api.services.v2.user_accounts.transformations import ( account_read, account_update_values, + latest_type_change_read, ) from policyengine_api.services.v2.user_accounts.types import ( AccountDeletion, @@ -62,9 +67,11 @@ from policyengine_api.services.v2.user_accounts.validators import ( AccountDeletionUnavailableError, AccountIdentityDeletionError, + TypeChangeNotFoundError, require_account, require_editable_account, require_resolved_account, + require_type_change, ) if TYPE_CHECKING: @@ -121,8 +128,9 @@ def get_account( ) -> AccountRead: """Return the caller's account, provisioning a signed-in caller's user. - Raise AccountNotFoundError for a signed-out browser that has not saved - anything yet. + The account carries the user's most recent type change unless it was + dismissed. Raise AccountNotFoundError for a signed-out browser that + has not saved anything yet. """ with self._database_session.transaction() as session: owner = require_resolved_account( @@ -131,7 +139,33 @@ def get_account( ) ) user = require_account(read_account_user(session, owner.user_id)) - return account_read(user, email=owner.email) + return account_read( + user, + email=owner.email, + latest_type_change=latest_type_change_read( + read_latest_user_type_change(session, owner.user_id) + ), + ) + + def dismiss_type_change( + self, *, principal: UserPrincipal, type_change_id: UUID + ) -> None: + """Record that the signed-in user dismissed the notice of a type change. + + Dismissing one already dismissed changes nothing. Raise + TypeChangeNotFoundError unless the caller's user has this change; a + caller with no user yet gets none. + """ + with self._database_session.transaction() as session: + owner = find_principal_user_in_session(session, principal) + if owner is None: + msg = "You have no type change with this ID" + raise TypeChangeNotFoundError(msg) + change = require_type_change( + read_user_type_change(session, type_change_id, user_id=owner.user_id) + ) + if change.dismissed_at is None: + dismiss_user_type_change(session, change, dismissed_at=utc_now()) def update_account( self, diff --git a/policyengine_api/services/v2/user_accounts/transformations.py b/policyengine_api/services/v2/user_accounts/transformations.py index 11134208f..13572667b 100644 --- a/policyengine_api/services/v2/user_accounts/transformations.py +++ b/policyengine_api/services/v2/user_accounts/transformations.py @@ -4,16 +4,23 @@ from typing import TYPE_CHECKING, Any +from policyengine_api.data.v2.models import UserType from policyengine_api.services.v2.user_accounts.types import ( AccountRead, AccountUpdateInput, + LatestTypeChangeRead, ) if TYPE_CHECKING: - from policyengine_api.data.v2.models import User + from policyengine_api.data.v2.models import User, UserTypeChange -def account_read(user: User, *, email: str | None) -> AccountRead: +def account_read( + user: User, + *, + email: str | None, + latest_type_change: LatestTypeChangeRead | None = None, +) -> AccountRead: """Convert a user row to the account read model, preferring the identity's email.""" return AccountRead( id=user.id, @@ -23,6 +30,21 @@ def account_read(user: User, *, email: str | None) -> AccountRead: last_name=user.last_name, email=email if email is not None else user.email, created_at=user.created_at, + latest_type_change=latest_type_change, + ) + + +def latest_type_change_read( + change: UserTypeChange | None, +) -> LatestTypeChangeRead | None: + """Describe a user's most recent type change, or None once it is dismissed.""" + if change is None or change.dismissed_at is not None: + return None + return LatestTypeChangeRead( + id=change.id, + previous_user_type=UserType(change.previous_user_type), + user_type=UserType(change.new_user_type), + changed_at=change.created_at, ) diff --git a/policyengine_api/services/v2/user_accounts/types.py b/policyengine_api/services/v2/user_accounts/types.py index ff9d4f8fc..ad0e15bcb 100644 --- a/policyengine_api/services/v2/user_accounts/types.py +++ b/policyengine_api/services/v2/user_accounts/types.py @@ -13,6 +13,7 @@ from datetime import datetime from uuid import UUID + from policyengine_api.data.v2.models import UserType from policyengine_api.services.v2.identity.types import AccountConversionOutcome from policyengine_api.services.v2.user_households.types import UserHouseholdRead from policyengine_api.services.v2.user_policies.types import UserPolicyRead @@ -53,6 +54,16 @@ def require_valid_supplied_field(self) -> AccountUpdateInput: return self +@dataclass(frozen=True) +class LatestTypeChangeRead: + """A user's most recent type change, which the app shows until dismissed.""" + + id: UUID + previous_user_type: UserType + user_type: UserType + changed_at: datetime + + @dataclass(frozen=True) class AccountRead: """A user's account as the service returns it to routes.""" @@ -65,6 +76,9 @@ class AccountRead: last_name: str | None email: str | None created_at: datetime + # Only reading the account fills it: the user's most recent type change, + # unless it was dismissed. Every other operation leaves it None. + latest_type_change: LatestTypeChangeRead | None = None @dataclass(frozen=True) diff --git a/policyengine_api/services/v2/user_accounts/validators.py b/policyengine_api/services/v2/user_accounts/validators.py index c1ce3d2be..dc4ef3d54 100644 --- a/policyengine_api/services/v2/user_accounts/validators.py +++ b/policyengine_api/services/v2/user_accounts/validators.py @@ -11,7 +11,7 @@ ) if TYPE_CHECKING: - from policyengine_api.data.v2.models import User + from policyengine_api.data.v2.models import User, UserTypeChange class AccountNotFoundError(LookupError): @@ -30,6 +30,10 @@ class AccountDeletionUnavailableError(RuntimeError): """Raised before any data is deleted when Auth0 deletion cannot run.""" +class TypeChangeNotFoundError(LookupError): + """Raised when the caller has no recorded type change with an ID (404).""" + + def require_resolved_account(owner: ResolvedUser | None) -> ResolvedUser: """Return the resolved user, or raise AccountNotFoundError if there is none. @@ -55,3 +59,11 @@ def require_editable_account(principal: AccountPrincipal) -> UserPrincipal: msg = "Sign in to edit your account details." raise AccountEditRequiresSignInError(msg) return principal + + +def require_type_change(change: UserTypeChange | None) -> UserTypeChange: + """Return the caller's recorded type change, or raise TypeChangeNotFoundError.""" + if change is None: + msg = "You have no type change with this ID" + raise TypeChangeNotFoundError(msg) + return change diff --git a/policyengine_api/services/v2/user_emails/__init__.py b/policyengine_api/services/v2/user_emails/__init__.py new file mode 100644 index 000000000..5aba13837 --- /dev/null +++ b/policyengine_api/services/v2/user_emails/__init__.py @@ -0,0 +1 @@ +"""The emails the Public API sends to users: invitations and type changes.""" diff --git a/policyengine_api/services/v2/user_emails/services.py b/policyengine_api/services/v2/user_emails/services.py new file mode 100644 index 000000000..3143f8974 --- /dev/null +++ b/policyengine_api/services/v2/user_emails/services.py @@ -0,0 +1,201 @@ +"""Send the invitation and type-change emails through a template email sender. + +An email goes out only after the change it reports has committed, and a +failure to send never undoes or fails that change: each unsent email is +recorded as a WARNING naming the invitation or the user by ID and the cause, +never an email address. A type-change email goes to the user's verified +email as Auth0 has it, read when the email is sent and never stored. +""" + +from __future__ import annotations + +import logging +import re +from typing import TYPE_CHECKING + +from policyengine_api.libs.rate_limit_wait_budget import RateLimitWaitBudget +from policyengine_api.services.v2.user_emails.transformations import ( + first_verified_email, + invitation_template_model, + subjects_from_issuer, + type_change_template_model, +) +from policyengine_api.services.v2.user_emails.types import ( + USER_INVITATION_TEMPLATE_ALIAS, + USER_TYPE_CHANGED_TEMPLATE_ALIAS, +) + +if TYPE_CHECKING: + from collections.abc import Callable, Mapping + + from policyengine_api.services.v2.user_emails.types import ( + InvitationEmail, + TemplateEmailSender, + UserTypeChangeEmail, + ) + from policyengine_api.services.v2.user_types.types import UserProfileSource + +logger = logging.getLogger(__name__) + +INVITATION_EMAIL_NOT_SENT_EVENT = "user_invitation_email_not_sent" +TYPE_CHANGE_EMAIL_NOT_SENT_EVENT = "user_type_change_email_not_sent" +# Failure causes besides an EmailSendError's own. +NOT_CONFIGURED = "not_configured" +INVALID_SETTINGS = "invalid_settings" +NO_USER_PROFILES = "no_user_profiles" +PROFILES_UNAVAILABLE = "profiles_unavailable" +NO_VERIFIED_EMAIL = "no_verified_email" +UNEXPECTED_ERROR = "unexpected_error" +# A sender's failure cause is a short identifier such as http_500 or +# postmark_406, so no email address can pass as one. +SAFE_CAUSE_PATTERN = re.compile(r"[a-z][a-z0-9_]{0,39}") + + +def _send_failure_cause(error: Exception) -> str: + """Return the cause a sender's error names, else ``unexpected_error``. + + Postmark's EmailSendError carries a ``cause``; any other failure is + unexpected. + """ + cause = getattr(error, "cause", None) + if isinstance(cause, str) and SAFE_CAUSE_PATTERN.fullmatch(cause): + return cause + return UNEXPECTED_ERROR + + +def _record_unsent(event: str, attributes: Mapping[str, str]) -> None: + logger.warning(event, extra={"policyengine_attributes": dict(attributes)}) + + +class V2UserEmailService: + """Fill and send the invitation and type-change emails.""" + + def __init__( + self, + *, + email_sender_factory: Callable[[], TemplateEmailSender | None], + user_profile_source_factory: Callable[[], UserProfileSource | None], + ) -> None: + """Build the sender and the Auth0 profile source only when sending. + + Either factory returns None when it isn't configured; then no email, + or no type-change email, is sent. + """ + self._email_sender_factory = email_sender_factory + self._user_profile_source_factory = user_profile_source_factory + + def _sender(self) -> tuple[TemplateEmailSender | None, str]: + """Return the sender, or None and why there is none.""" + try: + sender = self._email_sender_factory() + except Exception: # noqa: BLE001 # unusable settings send nothing + return None, INVALID_SETTINGS + return sender, NOT_CONFIGURED + + def _send( + self, + sender: TemplateEmailSender, + *, + to: str, + template_alias: str, + template_model: Mapping[str, object], + ) -> str | None: + """Send one email; return None, or the cause it wasn't sent.""" + try: + sender.send_template( + to=to, template_alias=template_alias, template_model=template_model + ) + except Exception as error: # noqa: BLE001 # a committed change must not fail on its email + return _send_failure_cause(error) + return None + + def send_invitation(self, invitation: InvitationEmail) -> str | None: + """Email an invitation's link to its address. + + Return None when Postmark accepted it, else the cause it wasn't sent: + ``not_configured``, or the sender's cause, such as ``timeout`` or + ``postmark_406``. + """ + sender, missing_cause = self._sender() + if sender is None: + _record_unsent( + INVITATION_EMAIL_NOT_SENT_EVENT, + { + "invitation_id": str(invitation.invitation_id), + "cause": missing_cause, + }, + ) + return NOT_CONFIGURED + cause = self._send( + sender, + to=invitation.email, + template_alias=USER_INVITATION_TEMPLATE_ALIAS, + template_model=invitation_template_model(invitation, sender.app_url), + ) + if cause is not None: + _record_unsent( + INVITATION_EMAIL_NOT_SENT_EVENT, + {"invitation_id": str(invitation.invitation_id), "cause": cause}, + ) + return cause + + def _verified_email(self, change: UserTypeChangeEmail) -> tuple[str | None, str]: + """Read the user's first verified Auth0 email, or say why there is none.""" + try: + source = self._user_profile_source_factory() + except Exception: # noqa: BLE001 # unusable settings read nothing + return None, NO_USER_PROFILES + if source is None: + return None, NO_USER_PROFILES + subjects = subjects_from_issuer(change.identities, source.issuer) + if not subjects: + return None, NO_VERIFIED_EMAIL + try: + profiles = source.reader.read_user_profiles( + subjects, wait_budget=RateLimitWaitBudget() + ) + except Exception: # noqa: BLE001 # Auth0's failure leaves the change committed + return None, PROFILES_UNAVAILABLE + email = first_verified_email(subjects, profiles) + return email, NO_VERIFIED_EMAIL + + def send_type_change( + self, change: UserTypeChangeEmail, *, verified_email: str | None = None + ) -> str | None: + """Email a user about a committed change of their type. + + The email goes to ``verified_email`` when the caller already read it + from Auth0, else to the first verified Auth0 email of the user's + identities from the users' issuer, most recently seen first. Return + None when Postmark accepted it, else the cause it wasn't sent: + ``not_configured``, ``no_user_profiles``, ``profiles_unavailable``, + ``no_verified_email``, or the sender's cause. + """ + sender, missing_sender_cause = self._sender() + if sender is None: + self._record_unsent_type_change(change, missing_sender_cause) + return NOT_CONFIGURED + email, missing_email_cause = ( + (verified_email, NO_VERIFIED_EMAIL) + if verified_email is not None + else self._verified_email(change) + ) + if email is None: + self._record_unsent_type_change(change, missing_email_cause) + return missing_email_cause + cause = self._send( + sender, + to=email, + template_alias=USER_TYPE_CHANGED_TEMPLATE_ALIAS, + template_model=type_change_template_model(change, sender.app_url), + ) + if cause is not None: + self._record_unsent_type_change(change, cause) + return cause + + @staticmethod + def _record_unsent_type_change(change: UserTypeChangeEmail, cause: str) -> None: + _record_unsent( + TYPE_CHANGE_EMAIL_NOT_SENT_EVENT, + {"user_id": str(change.user_id), "cause": cause}, + ) diff --git a/policyengine_api/services/v2/user_emails/transformations.py b/policyengine_api/services/v2/user_emails/transformations.py new file mode 100644 index 000000000..88e0ca7db --- /dev/null +++ b/policyengine_api/services/v2/user_emails/transformations.py @@ -0,0 +1,87 @@ +"""Pure conversions that fill the invitation and type-change email templates.""" + +from __future__ import annotations + +from datetime import UTC +from typing import TYPE_CHECKING +from urllib.parse import quote + +from policyengine_api.data.v2.models import UserType + +if TYPE_CHECKING: + from collections.abc import Iterable, Mapping + from datetime import datetime + + from policyengine_api.libs.auth0_management import Auth0UserProfile + from policyengine_api.services.v2.user_emails.types import ( + InvitationEmail, + SignInIdentity, + UserTypeChangeEmail, + ) + +# The app's page that accepts an invitation; the token travels in the URL +# fragment, which browsers never send to a server. +INVITATION_ACCEPT_PATH = "/invitations/accept" +USER_TYPE_ORDER = tuple(UserType) + + +def invitation_accept_url(app_url: str, token: str) -> str: + """Return the link to the app's accept page, carrying ``token``.""" + return f"{app_url}{INVITATION_ACCEPT_PATH}#token={quote(token, safe='-_')}" + + +def expiry_text(moment: datetime) -> str: + """Write a time as people read it in an email, in UTC, to the minute.""" + utc = moment.astimezone(UTC) + return f"{utc.day} {utc:%B %Y, %H:%M} UTC" + + +def invitation_template_model( + invitation: InvitationEmail, app_url: str +) -> dict[str, object]: + """Return the data the ``user-invitation`` template fills in.""" + return { + "user_type": invitation.user_type.value, + "accept_url": invitation_accept_url(app_url, invitation.token), + "expires_at": expiry_text(invitation.expires_at), + "app_url": app_url, + } + + +def type_change_template_model( + change: UserTypeChangeEmail, app_url: str +) -> dict[str, object]: + """Return the data the ``user-type-changed`` template fills in. + + ``promoted`` is true when the new type has more permissions than the + previous one. + """ + return { + "previous_user_type": change.previous_user_type.value, + "user_type": change.user_type.value, + "promoted": USER_TYPE_ORDER.index(change.user_type) + > USER_TYPE_ORDER.index(change.previous_user_type), + "app_url": app_url, + } + + +def subjects_from_issuer( + identities: Iterable[SignInIdentity], issuer: str +) -> tuple[str, ...]: + """Return the subjects of the identities from ``issuer``, in order, once each.""" + return tuple( + dict.fromkeys( + identity.subject for identity in identities if identity.issuer == issuer + ) + ) + + +def first_verified_email( + subjects: Iterable[str], profiles: Mapping[str, Auth0UserProfile] +) -> str | None: + """Return the first verified Auth0 email of these subjects, in their order.""" + for subject in subjects: + profile = profiles.get(subject) + if profile is not None and profile.email_verified and profile.email: + return profile.email + return None diff --git a/policyengine_api/services/v2/user_emails/types.py b/policyengine_api/services/v2/user_emails/types.py new file mode 100644 index 000000000..70c118c04 --- /dev/null +++ b/policyengine_api/services/v2/user_emails/types.py @@ -0,0 +1,68 @@ +"""Framework-independent data for the invitation and type-change emails.""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import TYPE_CHECKING, Protocol + +if TYPE_CHECKING: + from collections.abc import Mapping + from datetime import datetime + from uuid import UUID + + from policyengine_api.data.v2.models import UserType + +# The aliases of the Postmark templates each email fills in. +USER_INVITATION_TEMPLATE_ALIAS = "user-invitation" +USER_TYPE_CHANGED_TEMPLATE_ALIAS = "user-type-changed" + + +class TemplateEmailSender(Protocol): + """Sends template emails: Postmark, or a stand-in in tests.""" + + @property + def app_url(self) -> str: + """Return the app's address that emails link to, without a trailing slash.""" + ... + + def send_template( + self, + *, + to: str, + template_alias: str, + template_model: Mapping[str, object], + ) -> None: + """Send one template email; raise when it isn't accepted.""" + ... + + +@dataclass(frozen=True) +class SignInIdentity: + """One of a user's sign-in identities: its token issuer and subject.""" + + issuer: str + subject: str + + +@dataclass(frozen=True) +class UserTypeChangeEmail: + """A committed change of a user's type, to email the user about.""" + + user_id: UUID + previous_user_type: UserType + user_type: UserType + # The user's sign-in identities, most recently seen first; the email goes + # to the first verified Auth0 email among those from the users' issuer. + identities: tuple[SignInIdentity, ...] + + +@dataclass(frozen=True) +class InvitationEmail: + """A committed invitation, to email to its address with its token.""" + + invitation_id: UUID + email: str + user_type: UserType + expires_at: datetime + # Sent only in the email: kept out of repr, and never logged or stored. + token: str = field(repr=False) diff --git a/policyengine_api/services/v2/user_invitations/__init__.py b/policyengine_api/services/v2/user_invitations/__init__.py new file mode 100644 index 000000000..ea2a645f3 --- /dev/null +++ b/policyengine_api/services/v2/user_invitations/__init__.py @@ -0,0 +1 @@ +"""Admins' email invitations to become an author or admin, and their acceptance.""" diff --git a/policyengine_api/services/v2/user_invitations/database_connectors/__init__.py b/policyengine_api/services/v2/user_invitations/database_connectors/__init__.py new file mode 100644 index 000000000..e6e32972d --- /dev/null +++ b/policyengine_api/services/v2/user_invitations/database_connectors/__init__.py @@ -0,0 +1 @@ +"""Database access for admins' email invitations.""" diff --git a/policyengine_api/services/v2/user_invitations/database_connectors/creates.py b/policyengine_api/services/v2/user_invitations/database_connectors/creates.py new file mode 100644 index 000000000..4741e22c6 --- /dev/null +++ b/policyengine_api/services/v2/user_invitations/database_connectors/creates.py @@ -0,0 +1,27 @@ +"""Database inserts of admins' email invitations.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from policyengine_api.data.v2.models import UserInvitation + +if TYPE_CHECKING: + from sqlmodel import Session + + from policyengine_api.services.v2.user_invitations.types import NewInvitation + + +def create_user_invitation(session: Session, new: NewInvitation) -> UserInvitation: + """Store one invitation, with its token's hash.""" + invitation = UserInvitation( + email=new.email, + user_type=new.user_type.value, + token_hash=new.token_hash, + invited_by_user_id=new.invited_by_user_id, + created_at=new.created_at, + expires_at=new.expires_at, + ) + session.add(invitation) + session.flush() + return invitation diff --git a/policyengine_api/services/v2/user_invitations/database_connectors/reads.py b/policyengine_api/services/v2/user_invitations/database_connectors/reads.py new file mode 100644 index 000000000..fb2adc9b6 --- /dev/null +++ b/policyengine_api/services/v2/user_invitations/database_connectors/reads.py @@ -0,0 +1,81 @@ +"""Database reads of admins' email invitations.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from sqlalchemy import func +from sqlmodel import Session, col, select + +from policyengine_api.data.v2.models import UserInvitation + +if TYPE_CHECKING: + from uuid import UUID + + from sqlalchemy import ColumnElement + + +def _open() -> tuple[ColumnElement[bool], ColumnElement[bool]]: + """Return the conditions of an invitation neither accepted nor revoked.""" + return ( + col(UserInvitation.accepted_at).is_(None), + col(UserInvitation.revoked_at).is_(None), + ) + + +def read_open_invitations( + session: Session, *, offset: int, limit: int +) -> list[UserInvitation]: + """Return a page of invitations neither accepted nor revoked, newest first.""" + return list( + session.exec( + select(UserInvitation) + .where(*_open()) + .order_by(col(UserInvitation.created_at).desc(), col(UserInvitation.id)) + .offset(offset) + .limit(limit) + ).all() + ) + + +def read_open_invitations_to(session: Session, email: str) -> list[UserInvitation]: + """Return the open invitations to ``email``, compared whole ignoring case. + + Each row is locked (``FOR UPDATE``) until the transaction ends. + """ + return list( + session.exec( + select(UserInvitation) + .where(func.lower(col(UserInvitation.email)) == email.lower(), *_open()) + .order_by(col(UserInvitation.id)) + .with_for_update() + .execution_options(populate_existing=True) + ).all() + ) + + +def read_invitation( + session: Session, invitation_id: UUID, *, for_update: bool = False +) -> UserInvitation | None: + """Return the invitation with this ID, or None. + + ``for_update`` locks the row (``FOR UPDATE``) until the transaction ends. + """ + statement = select(UserInvitation).where(UserInvitation.id == invitation_id) + if for_update: + statement = statement.with_for_update() + return session.exec( + statement.execution_options(populate_existing=True) + ).one_or_none() + + +def read_invitation_by_token_hash( + session: Session, token_hash: str +) -> UserInvitation | None: + """Return the invitation whose token has this hash, locked until the end.""" + return session.exec( + select(UserInvitation) + .where(UserInvitation.token_hash == token_hash) + .with_for_update() + .execution_options(populate_existing=True) + ).one_or_none() diff --git a/policyengine_api/services/v2/user_invitations/database_connectors/updates.py b/policyengine_api/services/v2/user_invitations/database_connectors/updates.py new file mode 100644 index 000000000..9c98f887e --- /dev/null +++ b/policyengine_api/services/v2/user_invitations/database_connectors/updates.py @@ -0,0 +1,73 @@ +"""Database updates of admins' email invitations.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from datetime import datetime + from uuid import UUID + + from sqlmodel import Session + + from policyengine_api.data.v2.models import UserInvitation + + +def _store(session: Session, invitation: UserInvitation) -> UserInvitation: + session.add(invitation) + session.flush() + return invitation + + +def revoke_invitation( + session: Session, invitation: UserInvitation, *, revoked_at: datetime +) -> UserInvitation: + """Mark an open invitation revoked, so its link stops working.""" + invitation.revoked_at = revoked_at + return _store(session, invitation) + + +def renew_invitation( + session: Session, + invitation: UserInvitation, + *, + token_hash: str, + expires_at: datetime, + invited_by_user_id: UUID, +) -> UserInvitation: + """Give an open invitation a new token, expiry and inviting admin. + + Its last send is cleared, since it was for the earlier token. + """ + invitation.token_hash = token_hash + invitation.expires_at = expires_at + invitation.invited_by_user_id = invited_by_user_id + invitation.last_sent_at = None + invitation.last_send_error = None + return _store(session, invitation) + + +def record_invitation_send( + session: Session, + invitation: UserInvitation, + *, + sent_at: datetime | None, + send_error: str | None, +) -> UserInvitation: + """Record the last send of an invitation's email: its time, or its failure.""" + invitation.last_sent_at = sent_at + invitation.last_send_error = send_error + return _store(session, invitation) + + +def accept_invitation( + session: Session, + invitation: UserInvitation, + *, + accepted_at: datetime, + accepted_by_user_id: UUID, +) -> UserInvitation: + """Mark an invitation accepted by a user.""" + invitation.accepted_at = accepted_at + invitation.accepted_by_user_id = accepted_by_user_id + return _store(session, invitation) diff --git a/policyengine_api/services/v2/user_invitations/database_session.py b/policyengine_api/services/v2/user_invitations/database_session.py new file mode 100644 index 000000000..de1c70727 --- /dev/null +++ b/policyengine_api/services/v2/user_invitations/database_session.py @@ -0,0 +1,32 @@ +"""Database session lifetime management for admins' email invitations.""" + +from __future__ import annotations + +from contextlib import contextmanager +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from collections.abc import Iterator + + from sqlalchemy.orm import sessionmaker + from sqlmodel import Session + + +class UserInvitationDatabaseSession: + """Session lifetimes for invitation services: reads and transactions.""" + + def __init__(self, session_factory: sessionmaker[Session]) -> None: + """Use ``session_factory`` to open every session.""" + self._session_factory = session_factory + + @contextmanager + def read(self) -> Iterator[Session]: + """Yield a session for reads; nothing is committed.""" + with self._session_factory() as session: + yield session + + @contextmanager + def transaction(self) -> Iterator[Session]: + """Yield a session whose transaction commits on exit and rolls back on error.""" + with self._session_factory.begin() as session: + yield session diff --git a/policyengine_api/services/v2/user_invitations/services.py b/policyengine_api/services/v2/user_invitations/services.py new file mode 100644 index 000000000..c4e0493b0 --- /dev/null +++ b/policyengine_api/services/v2/user_invitations/services.py @@ -0,0 +1,407 @@ +"""Admins' email invitations to become an author or admin, and their acceptance. + +An admin invites an email address; the invitation's token is sent only in +its email, after the invitation commits, and only the token's SHA-256 hash is +stored. Inviting an address again revokes its open invitation, and resending +one gives it a new token and expiry, so an earlier link stops working. A send +that fails leaves the invitation open with the failure recorded. + +A signed-in user accepts with the token. Their email is first read from +Auth0 by their Auth0 user ID, and never stored. Then, in one transaction +under the user-type change lock, the token's invitation must be open and +unexpired (410), its inviting admin still an admin (409), the user's Auth0 +email verified (409) and equal to the invited address ignoring case (403). +The user then gets the invited type, unless they already have it or a higher +one: an invitation never lowers a type. A change is recorded with the +inviting admin named, and the user is emailed about it after the commit. + +Every invitation write takes the user-type change lock, which type changes +and account deletions take too, and checks the caller against the admins +read after it. +""" + +from __future__ import annotations + +import logging +import secrets +from typing import TYPE_CHECKING + +from policyengine_api.data.v2.models import UserType, UserTypeChangeSource +from policyengine_api.data.v2.models.base import utc_now +from policyengine_api.libs.rate_limit_wait_budget import RateLimitWaitBudget +from policyengine_api.services.v2.identity.services import ( + find_principal_user_in_session, + resolve_principal_user_in_session, +) +from policyengine_api.services.v2.user_emails.types import ( + InvitationEmail, + SignInIdentity, + UserTypeChangeEmail, +) +from policyengine_api.services.v2.user_invitations.database_connectors.creates import ( + create_user_invitation, +) +from policyengine_api.services.v2.user_invitations.database_connectors.reads import ( + read_invitation, + read_invitation_by_token_hash, + read_open_invitations, + read_open_invitations_to, +) +from policyengine_api.services.v2.user_invitations.database_connectors.updates import ( + accept_invitation, + record_invitation_send, + renew_invitation, + revoke_invitation, +) +from policyengine_api.services.v2.user_invitations.transformations import ( + admin_invitation_read, + invitation_token_hash, +) +from policyengine_api.services.v2.user_invitations.types import ( + INVITATION_LIFETIME, + INVITATION_TOKEN_BYTES, + AdminInvitationPage, + AdminInvitationRead, + InvitationAcceptance, + NewInvitation, +) +from policyengine_api.services.v2.user_invitations.validators import ( + InvitationEmailUnavailableError, + InvitationNotFoundError, + grants_new_type, + require_acceptable_invitation, + require_invitation_user_type, + require_invited_email, + require_inviter_admin, + require_open_invitation, + require_verified_email, +) +from policyengine_api.services.v2.user_types.database_connectors.creates import ( + create_user_type_change, +) +from policyengine_api.services.v2.user_types.database_connectors.reads import ( + acquire_user_type_change_lock, + read_admin_user_ids, + read_identities_newest_first, + read_signed_in_user, +) +from policyengine_api.services.v2.user_types.database_connectors.updates import ( + update_user_type, +) +from policyengine_api.services.v2.user_types.transformations import caller_user_type +from policyengine_api.services.v2.user_types.types import UserTypeChangeOrigin +from policyengine_api.services.v2.user_types.validators import ( + require_minimum_user_type, + require_signed_in_user, +) + +if TYPE_CHECKING: + from collections.abc import Callable + from datetime import datetime + from uuid import UUID + + from sqlmodel import Session + + from policyengine_api.data.v2.models import UserInvitation + from policyengine_api.libs.auth0_management import Auth0UserProfile + from policyengine_api.services.v2.identity.types import ( + AccountPrincipal, + UserPrincipal, + ) + from policyengine_api.services.v2.user_emails.services import V2UserEmailService + from policyengine_api.services.v2.user_invitations.database_session import ( + UserInvitationDatabaseSession, + ) + from policyengine_api.services.v2.user_invitations.types import ( + AdminInvitationSearch, + ) + from policyengine_api.services.v2.user_types.types import UserProfileSource + +logger = logging.getLogger(__name__) + +INVITEE_EMAIL_UNAVAILABLE_EVENT = "invitee_email_unavailable" +INVITEE_EMAIL_UNAVAILABLE_MESSAGE = ( + "Your email address can't be checked right now; try again shortly" +) + + +def _new_token() -> str: + """Return a new invitation token: 32 random bytes, URL-safe base64.""" + return secrets.token_urlsafe(INVITATION_TOKEN_BYTES) + + +def _lock_and_require_admin(session: Session, principal: AccountPrincipal) -> UUID: + """Take the user-type change lock; return the caller's ID if an admin.""" + from policyengine_api.services.v2.user_types.services import ( + lock_and_require_admin_in_session, + ) + + return lock_and_require_admin_in_session(session, principal) + + +def _invitation_email(invitation: UserInvitation, token: str) -> InvitationEmail: + return InvitationEmail( + invitation_id=invitation.id, + email=invitation.email, + user_type=UserType(invitation.user_type), + expires_at=invitation.expires_at, + token=token, + ) + + +class V2UserInvitationService: + """Sequence invitations and their acceptance through explicit sessions.""" + + def __init__( + self, + database_session: UserInvitationDatabaseSession, + *, + user_email_service: V2UserEmailService, + user_profile_source_factory: Callable[[], UserProfileSource | None], + clock: Callable[[], datetime] = utc_now, + token_factory: Callable[[], str] = _new_token, + ) -> None: + """Open every session through ``database_session``. + + ``user_email_service`` sends the invitation and type-change emails. + ``user_profile_source_factory`` gives the users' Auth0 tenant, from + which an invitee's verified email is read; with none, no invitation + can be accepted. ``clock`` and ``token_factory`` are replaced in tests. + """ + self._database_session = database_session + self._emails = user_email_service + self._user_profile_source_factory = user_profile_source_factory + self._clock = clock + self._token_factory = token_factory + + def create_invitation( + self, *, principal: AccountPrincipal, email: str, user_type: UserType + ) -> AdminInvitationRead: + """Invite ``email`` to become ``user_type``, then email the link. + + The address's open invitation, if any, is revoked first. The + returned invitation says whether the email was sent. + """ + require_invitation_user_type(user_type) + token = self._token_factory() + now = self._clock() + with self._database_session.transaction() as session: + caller_user_id = _lock_and_require_admin(session, principal) + for earlier in read_open_invitations_to(session, email): + revoke_invitation(session, earlier, revoked_at=now) + invitation = create_user_invitation( + session, + NewInvitation( + email=email, + user_type=user_type, + token_hash=invitation_token_hash(token), + invited_by_user_id=caller_user_id, + created_at=now, + expires_at=now + INVITATION_LIFETIME, + ), + ) + sending = _invitation_email(invitation, token) + return self._send_invitation(sending) + + def list_invitations( + self, *, principal: AccountPrincipal, search: AdminInvitationSearch + ) -> AdminInvitationPage: + """Return one page of open invitations, newest first, expired ones too.""" + now = self._clock() + with self._database_session.read() as session: + require_minimum_user_type( + caller_user_type( + principal, find_principal_user_in_session(session, principal) + ), + UserType.ADMIN, + ) + invitations = read_open_invitations( + session, offset=search.offset, limit=search.limit + 1 + ) + items = tuple( + admin_invitation_read(invitation, now=now) + for invitation in invitations[: search.limit] + ) + return AdminInvitationPage( + items=items, + offset=search.offset, + limit=search.limit, + has_more=len(invitations) > search.limit, + ) + + def resend_invitation( + self, *, principal: AccountPrincipal, invitation_id: UUID + ) -> AdminInvitationRead: + """Give an open invitation a new link and expiry, and email it again. + + The caller becomes its inviting admin. Raise InvitationNotFoundError + unless an open invitation has this ID. + """ + token = self._token_factory() + now = self._clock() + with self._database_session.transaction() as session: + caller_user_id = _lock_and_require_admin(session, principal) + invitation = renew_invitation( + session, + require_open_invitation( + read_invitation(session, invitation_id, for_update=True) + ), + token_hash=invitation_token_hash(token), + expires_at=now + INVITATION_LIFETIME, + invited_by_user_id=caller_user_id, + ) + sending = _invitation_email(invitation, token) + return self._send_invitation(sending) + + def revoke_invitation( + self, *, principal: AccountPrincipal, invitation_id: UUID + ) -> None: + """Revoke an open invitation, so its link stops working. + + Raise InvitationNotFoundError unless an open invitation has this ID. + """ + now = self._clock() + with self._database_session.transaction() as session: + _lock_and_require_admin(session, principal) + revoke_invitation( + session, + require_open_invitation( + read_invitation(session, invitation_id, for_update=True) + ), + revoked_at=now, + ) + + def _send_invitation(self, sending: InvitationEmail) -> AdminInvitationRead: + """Email a committed invitation, then record how the send went. + + The record is skipped when the invitation's token changed meanwhile, + since a later resend then owns it. + """ + failure = self._emails.send_invitation(sending) + now = self._clock() + with self._database_session.transaction() as session: + invitation = read_invitation( + session, sending.invitation_id, for_update=True + ) + if invitation is None: + msg = "No pending invitation has this ID" + raise InvitationNotFoundError(msg) + if invitation.token_hash == invitation_token_hash(sending.token): + record_invitation_send( + session, + invitation, + sent_at=now if failure is None else None, + send_error=failure, + ) + return admin_invitation_read(invitation, now=now) + + def _invitee_profile(self, principal: UserPrincipal) -> Auth0UserProfile | None: + """Read the signed-in invitee's Auth0 profile by their Auth0 user ID. + + Return None when the identity isn't from the users' Auth0 tenant or + Auth0 doesn't know it. Raise InvitationEmailUnavailableError when + there are no profile settings or Auth0 can't answer. + """ + try: + source = self._user_profile_source_factory() + except Exception as error: + self._record_unavailable("invalid_settings") + raise InvitationEmailUnavailableError( + INVITEE_EMAIL_UNAVAILABLE_MESSAGE + ) from error + if source is None: + self._record_unavailable("no_user_profiles") + raise InvitationEmailUnavailableError(INVITEE_EMAIL_UNAVAILABLE_MESSAGE) + if principal.issuer != source.issuer: + return None + try: + profiles = source.reader.read_user_profiles( + (principal.subject,), wait_budget=RateLimitWaitBudget() + ) + except Exception as error: + cause = getattr(error, "cause", None) + self._record_unavailable(cause if isinstance(cause, str) else "unknown") + raise InvitationEmailUnavailableError( + INVITEE_EMAIL_UNAVAILABLE_MESSAGE + ) from error + return profiles.get(principal.subject) + + @staticmethod + def _record_unavailable(cause: str) -> None: + """Record why an invitee's email couldn't be read, by cause only.""" + logger.warning( + INVITEE_EMAIL_UNAVAILABLE_EVENT, + extra={"policyengine_attributes": {"cause": cause[:40]}}, + ) + + def accept_invitation( + self, *, principal: UserPrincipal, token: str, country_id: str + ) -> InvitationAcceptance: + """Accept an invitation for the signed-in user, giving its type. + + A user with no account yet gets one, with ``country_id`` as its + primary country, as on any first signed-in request. Raise, in this + order: InvitationEmailUnavailableError (Auth0 can't answer), an + InvitationUnavailableError for a token that is unknown, revoked, + accepted or expired, InviterNotAdminError, + InvitationEmailNotVerifiedError, then InvitationEmailMismatchError. + Nothing changes when any is raised. + """ + profile = self._invitee_profile(principal) + token_hash = invitation_token_hash(token) + now = self._clock() + with self._database_session.transaction() as session: + owner = resolve_principal_user_in_session( + session, principal, country_id=country_id + ) + acquire_user_type_change_lock(session) + invitation = require_acceptable_invitation( + read_invitation_by_token_hash(session, token_hash), now=now + ) + require_inviter_admin( + invitation.invited_by_user_id, read_admin_user_ids(session) + ) + verified_email = require_verified_email(profile) + require_invited_email(invitation.email, verified_email) + user = require_signed_in_user( + read_signed_in_user(session, owner.user_id, for_update=True) + ) + previous_user_type = UserType(user.user_type) + invited_user_type = UserType(invitation.user_type) + type_changed = grants_new_type(previous_user_type, invited_user_type) + if type_changed: + update_user_type(session, user, user_type=invited_user_type) + create_user_type_change( + session, + user_id=user.id, + previous_user_type=previous_user_type, + new_user_type=invited_user_type, + origin=UserTypeChangeOrigin( + changed_by_user_id=invitation.invited_by_user_id, + source=UserTypeChangeSource.INVITATION, + ), + ) + user_id = user.id + accept_invitation( + session, invitation, accepted_at=now, accepted_by_user_id=user_id + ) + identities = tuple( + SignInIdentity(issuer=identity.issuer, subject=identity.subject) + for identity in read_identities_newest_first(session, [user_id]) + ) + acceptance = InvitationAcceptance( + user_type=UserType(user.user_type), + previous_user_type=previous_user_type, + type_changed=type_changed, + ) + if type_changed: + self._emails.send_type_change( + UserTypeChangeEmail( + user_id=user_id, + previous_user_type=previous_user_type, + user_type=invited_user_type, + identities=identities, + ), + verified_email=verified_email, + ) + return acceptance diff --git a/policyengine_api/services/v2/user_invitations/transformations.py b/policyengine_api/services/v2/user_invitations/transformations.py new file mode 100644 index 000000000..cbc4808df --- /dev/null +++ b/policyengine_api/services/v2/user_invitations/transformations.py @@ -0,0 +1,47 @@ +"""Pure conversions for admins' email invitations.""" + +from __future__ import annotations + +import hashlib +from datetime import UTC +from typing import TYPE_CHECKING + +from policyengine_api.data.v2.models import UserType +from policyengine_api.services.v2.user_invitations.types import AdminInvitationRead + +if TYPE_CHECKING: + from datetime import datetime + + from policyengine_api.data.v2.models import UserInvitation + + +def invitation_token_hash(token: str) -> str: + """Return the SHA-256 digest of a token in hexadecimal, as it is stored.""" + return hashlib.sha256(token.encode("utf-8")).hexdigest() + + +def as_utc(moment: datetime) -> datetime: + """Return an aware UTC time; a naive one (from SQLite) is read as UTC.""" + if moment.tzinfo is None: + return moment.replace(tzinfo=UTC) + return moment.astimezone(UTC) + + +def admin_invitation_read( + invitation: UserInvitation, *, now: datetime +) -> AdminInvitationRead: + """Describe a stored invitation for admins, as of ``now``.""" + expires_at = as_utc(invitation.expires_at) + return AdminInvitationRead( + id=invitation.id, + email=invitation.email, + user_type=UserType(invitation.user_type), + invited_by_user_id=invitation.invited_by_user_id, + created_at=as_utc(invitation.created_at), + expires_at=expires_at, + expired=expires_at <= now, + last_sent_at=( + None if invitation.last_sent_at is None else as_utc(invitation.last_sent_at) + ), + last_send_error=invitation.last_send_error, + ) diff --git a/policyengine_api/services/v2/user_invitations/types.py b/policyengine_api/services/v2/user_invitations/types.py new file mode 100644 index 000000000..e7ae822c1 --- /dev/null +++ b/policyengine_api/services/v2/user_invitations/types.py @@ -0,0 +1,95 @@ +"""Framework-independent data for admins' email invitations and their acceptance.""" + +from __future__ import annotations + +from dataclasses import dataclass +from datetime import timedelta +from typing import TYPE_CHECKING, Annotated + +from pydantic import BaseModel, ConfigDict, Field, StringConstraints + +from policyengine_api.query_parameters import DEFAULT_QUERY_LIMIT, MAXIMUM_QUERY_LIMIT + +if TYPE_CHECKING: + from datetime import datetime + from uuid import UUID + + from policyengine_api.data.v2.models import UserType + +# How long an invitation's link works after it was created or last resent. +INVITATION_LIFETIME = timedelta(days=7) +# The random bytes in each invitation's token; it is sent URL-safe base64. +INVITATION_TOKEN_BYTES = 32 + +# One email address: an @ with text on both sides, and no whitespace, < or >. +InvitationEmailAddress = Annotated[ + str, + StringConstraints( + strip_whitespace=True, + min_length=3, + max_length=320, + pattern=r"^[^@\s<>]+@[^@\s<>]+$", + ), +] +# The token from an invitation's link, as the app sends it back. +InvitationToken = Annotated[str, StringConstraints(min_length=1, max_length=256)] + + +class AdminInvitationSearch(BaseModel): + """Which page of open invitations an admin lists.""" + + model_config = ConfigDict(extra="forbid", frozen=True) + + offset: int = Field(default=0, ge=0) + limit: int = Field(default=DEFAULT_QUERY_LIMIT, ge=1, le=MAXIMUM_QUERY_LIMIT) + + +@dataclass(frozen=True) +class NewInvitation: + """An invitation to store: only its token's hash, never the token.""" + + email: str + user_type: UserType + token_hash: str + invited_by_user_id: UUID + created_at: datetime + expires_at: datetime + + +@dataclass(frozen=True) +class AdminInvitationRead: + """An invitation as admins see it.""" + + id: UUID + email: str + user_type: UserType + # The admin who created or last resent it; None once that account is gone. + invited_by_user_id: UUID | None + created_at: datetime + expires_at: datetime + # Whether expires_at has passed: it can't be accepted, but can be resent. + expired: bool + # When the email with the current link was sent; None when it wasn't. + last_sent_at: datetime | None + # Why the last send failed, as a short identifier; None after a success. + last_send_error: str | None + + +@dataclass(frozen=True) +class AdminInvitationPage: + """One page of open invitations, newest first.""" + + items: tuple[AdminInvitationRead, ...] + offset: int + limit: int + has_more: bool + + +@dataclass(frozen=True) +class InvitationAcceptance: + """The invitee's type after accepting, and before.""" + + user_type: UserType + previous_user_type: UserType + # False when the user already had the invited type or a higher one. + type_changed: bool diff --git a/policyengine_api/services/v2/user_invitations/validators.py b/policyengine_api/services/v2/user_invitations/validators.py new file mode 100644 index 000000000..00b752107 --- /dev/null +++ b/policyengine_api/services/v2/user_invitations/validators.py @@ -0,0 +1,155 @@ +"""Database-independent checks for admins' email invitations and their acceptance.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from policyengine_api.data.v2.models import INVITATION_USER_TYPES, UserType +from policyengine_api.services.v2.user_invitations.transformations import as_utc + +if TYPE_CHECKING: + from collections.abc import Collection + from datetime import datetime + from uuid import UUID + + from policyengine_api.data.v2.models import UserInvitation + from policyengine_api.libs.auth0_management import Auth0UserProfile + + +class InvitationNotFoundError(LookupError): + """Raised when no open invitation has an admin's requested ID (404).""" + + +class InvitationUnavailableError(Exception): + """Raised when an invitation's token can't be accepted (410). + + Each subclass names one reason with its ``code``. + """ + + code = "invitation_unavailable" + + +class InvitationTokenNotFoundError(InvitationUnavailableError): + """No invitation has the token, including a link replaced by a resend.""" + + code = "invitation_not_found" + + +class InvitationRevokedError(InvitationUnavailableError): + """The invitation was revoked, or replaced by a newer one to its address.""" + + code = "invitation_revoked" + + +class InvitationExpiredError(InvitationUnavailableError): + """The invitation's link expired.""" + + code = "invitation_expired" + + +class InvitationAcceptedError(InvitationUnavailableError): + """The invitation was already accepted.""" + + code = "invitation_accepted" + + +class InviterNotAdminError(ValueError): + """Raised when the admin who sent an invitation is no longer an admin (409).""" + + code = "inviter_not_admin" + + +class InvitationEmailNotVerifiedError(ValueError): + """Raised when Auth0 has no verified email for the invitee (409).""" + + code = "email_not_verified" + + +class InvitationEmailMismatchError(PermissionError): + """Raised when the invitee's verified email isn't the invited address (403).""" + + code = "email_mismatch" + + +class InvitationEmailUnavailableError(RuntimeError): + """Raised when the invitee's email can't be read from Auth0 (503).""" + + code = "auth0_unavailable" + + +def require_invitation_user_type(user_type: UserType) -> UserType: + """Return a type an invitation can grant, author or admin; raise otherwise.""" + if user_type not in INVITATION_USER_TYPES: + msg = "An invitation grants the author or admin type" + raise ValueError(msg) + return user_type + + +def require_open_invitation(invitation: UserInvitation | None) -> UserInvitation: + """Return an invitation that is neither accepted nor revoked.""" + if ( + invitation is None + or invitation.accepted_at is not None + or invitation.revoked_at is not None + ): + msg = "No pending invitation has this ID" + raise InvitationNotFoundError(msg) + return invitation + + +def require_acceptable_invitation( + invitation: UserInvitation | None, *, now: datetime +) -> UserInvitation: + """Return the token's invitation if it is open and unexpired; raise otherwise.""" + if invitation is None: + msg = "This invitation link is not valid; ask for a new invitation" + raise InvitationTokenNotFoundError(msg) + if invitation.revoked_at is not None: + msg = "This invitation was withdrawn; ask for a new invitation" + raise InvitationRevokedError(msg) + if invitation.accepted_at is not None: + msg = "This invitation was already accepted" + raise InvitationAcceptedError(msg) + if as_utc(invitation.expires_at) <= now: + msg = "This invitation expired; ask for a new invitation" + raise InvitationExpiredError(msg) + return invitation + + +def require_inviter_admin( + invited_by_user_id: UUID | None, admin_user_ids: Collection[UUID] +) -> None: + """Refuse an invitation whose inviting admin is no longer among the admins.""" + if invited_by_user_id is None or invited_by_user_id not in admin_user_ids: + msg = ( + "The admin who sent this invitation is no longer an admin; ask for " + "a new invitation" + ) + raise InviterNotAdminError(msg) + + +def require_verified_email(profile: Auth0UserProfile | None) -> str: + """Return the invitee's verified Auth0 email, or refuse until it is verified.""" + if profile is None or not profile.email_verified or not profile.email: + msg = ( + "Your email address isn't verified yet: open the verification " + "email from PolicyEngine's sign-in service, then try again" + ) + raise InvitationEmailNotVerifiedError(msg) + return profile.email + + +def require_invited_email(invited_email: str, verified_email: str) -> None: + """Refuse a verified email that isn't the invited address, ignoring case.""" + if invited_email.lower() != verified_email.lower(): + msg = ( + "This invitation was sent to another email address; sign in with " + "the address it was sent to" + ) + raise InvitationEmailMismatchError(msg) + + +def grants_new_type(current_user_type: UserType, invited_user_type: UserType) -> bool: + """Say whether accepting raises the type: an invitation never lowers one.""" + order = tuple(UserType) + return order.index(invited_user_type) > order.index(current_user_type) diff --git a/policyengine_api/services/v2/user_types/services.py b/policyengine_api/services/v2/user_types/services.py index 8e78a6512..063a5fd05 100644 --- a/policyengine_api/services/v2/user_types/services.py +++ b/policyengine_api/services/v2/user_types/services.py @@ -14,10 +14,11 @@ the previous and new type, who made it and how. A change that would leave no admin is refused. -Every change, and every signed-in account deletion, first takes one -transaction-scoped advisory lock, then reads the admins and checks the caller -or the deleted user against them, so they run one at a time and none can leave -no admin. +Every change, every invitation write and every signed-in account deletion +first takes one transaction-scoped advisory lock, then reads the admins and +checks the caller or the deleted user against them, so they run one at a time +and none can leave no admin. After a change commits, the user is emailed about +it when an email service is configured. With a user profile source, admins see each user's email and names as Auth0 has them, read after the database work and never stored: only identities @@ -40,6 +41,10 @@ from policyengine_api.services.v2.identity.services import ( find_principal_user_in_session, ) +from policyengine_api.services.v2.user_emails.types import ( + SignInIdentity, + UserTypeChangeEmail, +) from policyengine_api.services.v2.user_types.database_connectors.creates import ( create_user_type_change, ) @@ -101,6 +106,7 @@ from policyengine_api.data.v2.models import User, UserIdentity, UserTypeChange from policyengine_api.libs.auth0_management import Auth0UserProfile from policyengine_api.services.v2.identity.types import AccountPrincipal + from policyengine_api.services.v2.user_emails.services import V2UserEmailService from policyengine_api.services.v2.user_types.database_session import ( UserTypeDatabaseSession, ) @@ -161,15 +167,24 @@ def __init__( user_profile_source_factory: ( Callable[[], UserProfileSource | None] | None ) = None, + user_email_service: V2UserEmailService | None = None, ) -> None: """Open every session through ``database_session``. ``user_profile_source_factory`` is called once by each admin read or change; without it, or when it returns None, admins see stored emails and names only, and an email search reads only stored emails. + ``user_email_service`` emails each user whose type changed, after the + commit; without it nobody is emailed. """ self._database_session = database_session self._user_profile_source_factory = user_profile_source_factory + self._user_email_service = user_email_service + + def _email_type_change(self, change: UserTypeChangeEmail | None) -> None: + """Email the user about a committed change; never raises for a failure.""" + if change is not None and self._user_email_service is not None: + self._user_email_service.send_type_change(change) def _profile_source(self) -> UserProfileSource | None: """Return the configured profile source, or None when there is none. @@ -373,7 +388,7 @@ def change_user_type( user = require_signed_in_user( read_signed_in_user(session, user_id, for_update=True) ) - _change_type_in_session( + change = _change_type_in_session( session, user, requested=RequestedUserType( @@ -386,6 +401,7 @@ def change_user_type( ), ) stored = _stored_admin_users(session, [user], issuer) + self._email_type_change(change) (read,) = self._with_profiles(source, stored, RateLimitWaitBudget()) return read @@ -461,7 +477,7 @@ def set_user_type_by_email( read_signed_in_user(session, matched.id, for_update=True) ) previous_user_type = UserType(user.user_type) - _change_type_in_session( + change = _change_type_in_session( session, user, requested=RequestedUserType( @@ -473,9 +489,23 @@ def set_user_type_by_email( ), ) (read,) = _admin_user_reads(session, [user]) - return ScriptedUserTypeChange( - user=read, previous_user_type=previous_user_type - ) + self._email_type_change(change) + return ScriptedUserTypeChange(user=read, previous_user_type=previous_user_type) + + +def lock_and_require_admin_in_session( + session: Session, principal: AccountPrincipal +) -> UUID: + """Take the user-type change lock, then return the caller's ID if an admin. + + The caller is checked against the admins read after the lock, as a type + change checks it. Raise UserTypeBelowMinimumError otherwise. + """ + caller = find_principal_user_in_session(session, principal) + acquire_user_type_change_lock(session) + return require_listed_admin( + None if caller is None else caller.user_id, read_admin_user_ids(session) + ) def require_admin_remains_after_deletion_in_session( @@ -528,16 +558,17 @@ def _change_type_in_session( requested: RequestedUserType, admin_user_ids: list[UUID], origin: UserTypeChangeOrigin, -) -> None: +) -> UserTypeChangeEmail | None: """Change the type, unless the user already has it, and record the change. When ``requested`` names the type its requester last read, the user's - stored type must still be that one. + stored type must still be that one. Return the email to send the user + once the change commits, or None when nothing changed. """ previous_user_type = UserType(user.user_type) user_type = requested.user_type if previous_user_type is user_type: - return + return None if requested.expected_user_type is not None: require_expected_user_type( current_user_type=previous_user_type, @@ -556,3 +587,12 @@ def _change_type_in_session( new_user_type=user_type, origin=origin, ) + return UserTypeChangeEmail( + user_id=user.id, + previous_user_type=previous_user_type, + user_type=user_type, + identities=tuple( + SignInIdentity(issuer=identity.issuer, subject=identity.subject) + for identity in read_identities_newest_first(session, [user.id]) + ), + ) diff --git a/policyengine_api/services/v2/user_types/validators.py b/policyengine_api/services/v2/user_types/validators.py index 7b6793b37..5150beb07 100644 --- a/policyengine_api/services/v2/user_types/validators.py +++ b/policyengine_api/services/v2/user_types/validators.py @@ -81,10 +81,14 @@ def require_minimum_user_type(user_type: UserType, minimum: UserType) -> UserTyp def require_listed_admin( caller_user_id: UUID | None, admin_user_ids: Collection[UUID] -) -> None: - """Refuse a caller who isn't among the admins read in this transaction.""" +) -> UUID: + """Return the caller's ID if it is among the admins read in this transaction. + + Refuse any other caller. + """ if caller_user_id is None or caller_user_id not in admin_user_ids: raise UserTypeBelowMinimumError(BELOW_MINIMUM_MESSAGES[UserType.ADMIN]) + return caller_user_id def require_signed_in_user(user: User | None) -> User: diff --git a/pyproject.toml b/pyproject.toml index 2831f1d0c..fedab7f05 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -386,8 +386,8 @@ showcontent = true # registers an exit hook at import, the v2 database sessions and services load # persistence only when a default factory runs, the household calculation # client of the simulation service loads only when a calculation is submitted, -# and Auth0 Management and the Google Secret Manager client load only when a -# secret is read. Ruff's PLC0415 +# Auth0 Management and the Google Secret Manager client load only when a +# secret is read, and Postmark only when an email is sent. Ruff's PLC0415 # accepts in-function imports of these without a suppression. A module belongs # here only if no application module imports it at module level. banned-module-level-imports = [ @@ -395,6 +395,7 @@ banned-module-level-imports = [ "policyengine", "policyengine_api.data.v2.database", "policyengine_api.libs.auth0_management", + "policyengine_api.libs.postmark_email", "policyengine_api.libs.simulation_household_calculations", "policyengine_api.services.v2.countries.database_session", "policyengine_api.services.v2.countries.services", @@ -410,8 +411,11 @@ banned-module-level-imports = [ "policyengine_api.services.v2.policies.services", "policyengine_api.services.v2.user_accounts.database_session", "policyengine_api.services.v2.user_accounts.services", + "policyengine_api.services.v2.user_emails.services", "policyengine_api.services.v2.user_households.database_session", "policyengine_api.services.v2.user_households.services", + "policyengine_api.services.v2.user_invitations.database_session", + "policyengine_api.services.v2.user_invitations.services", "policyengine_api.services.v2.user_policies.database_session", "policyengine_api.services.v2.user_policies.services", "policyengine_api.services.v2.user_reports.database_session", diff --git a/scripts/set_v2_user_type.py b/scripts/set_v2_user_type.py index db9fa69ff..10f9cb399 100755 --- a/scripts/set_v2_user_type.py +++ b/scripts/set_v2_user_type.py @@ -8,7 +8,10 @@ The email is compared whole, ignoring case, with the user's own email and its sign-in identities' emails; exactly one signed-in user must match. The change is recorded in the user's type history with no admin named. Demoting the last -admin is refused, as it is through the admin routes. +admin is refused, as it is through the admin routes. After the change, the +user is emailed at their verified Auth0 email, as for an admin's change, when +the ``AUTH0_USER_PROFILES_*`` and ``POSTMARK_*`` settings are set; otherwise a +WARNING record says no email was sent. It connects as the Public API's runtime role, configured as the deployed Public API is: ``V2_RUNTIME_DATABASE_URL`` (or @@ -24,6 +27,9 @@ from typing import TYPE_CHECKING, Protocol from policyengine_api.data.v2.models import SIGNED_IN_USER_TYPES, UserType + +# The route dependencies build the email service the admin routes use. +from policyengine_api.fastapi_routes.dependencies import _default_user_email_service from policyengine_api.services.v2.user_types.validators import ( LastAdminDemotionError, UserEmailMatchError, @@ -51,9 +57,7 @@ def _runtime_user_type_service() -> UserTypeSetter: """Build the user-type service on the runtime role's database connection.""" # These modules are imported only when the command runs, as they read the # database settings or need the connection. - from policyengine_api.data.v2.database import ( - get_v2_session_factory, - ) + from policyengine_api.data.v2 import database from policyengine_api.services.v2.user_types.database_session import ( UserTypeDatabaseSession, ) @@ -61,7 +65,10 @@ def _runtime_user_type_service() -> UserTypeSetter: V2UserTypeService, ) - return V2UserTypeService(UserTypeDatabaseSession(get_v2_session_factory())) + return V2UserTypeService( + UserTypeDatabaseSession(database.get_v2_session_factory()), + user_email_service=_default_user_email_service(), + ) def _parser() -> argparse.ArgumentParser: diff --git a/tests/contract/registry.py b/tests/contract/registry.py index 5c2df6b72..017e9037b 100644 --- a/tests/contract/registry.py +++ b/tests/contract/registry.py @@ -474,6 +474,7 @@ class WorkflowContract: "result.item.last_name", "result.item.email", "result.item.created_at", + "result.latest_type_change", ), route_group="user_profile", headers=headers, @@ -529,6 +530,28 @@ class WorkflowContract: route_group="user_profile", headers=(AUTHORIZATION_HEADER, UNAUTHENTICATED_USER_HEADER), ), + ContractRequest( + method="POST", + path="/v2/me/invitations/accept?country_id=us", + expected_status=200, + stable_response_fields=( + "status", + "message", + "result.item.user_type", + "result.item.previous_user_type", + "result.item.type_changed", + ), + route_group="user_profile", + headers=USER_AUTH_HEADERS, + ), + ContractRequest( + method="POST", + path="/v2/me/type-changes/{type_change_id}/dismiss?country_id=us", + expected_status=204, + stable_response_fields=(), + route_group="user_profile", + headers=USER_AUTH_HEADERS, + ), *( ContractRequest( method="DELETE", diff --git a/tests/contract/test_app_v2_workflow_contracts.py b/tests/contract/test_app_v2_workflow_contracts.py index 20c6733d3..b8430d595 100644 --- a/tests/contract/test_app_v2_workflow_contracts.py +++ b/tests/contract/test_app_v2_workflow_contracts.py @@ -114,6 +114,25 @@ def test_user_routes_record_signed_in_and_signed_out_contracts() -> None: assert not any( "/v2/me/imports" in path for _method, path, _headers in user_requests ) + # Only a signed-in user accepts an invitation or dismisses a type change. + for method, path in ( + ("POST", "/v2/me/invitations/accept"), + ("POST", "/v2/me/type-changes/{type_change_id}/dismiss"), + ): + assert (method, path, ("Authorization",)) in user_requests + assert (method, path) not in signed_out + + +def test_reading_the_account_reports_the_latest_type_change() -> None: + reads = [ + request + for request in APP_V2_ROUTE_CONTRACTS + if request.method == "GET" and request.path.split("?", 1)[0] == "/v2/me" + ] + + assert reads + for request in reads: + assert "result.latest_type_change" in request.stable_response_fields def test_shared_reports_are_read_without_a_credential() -> None: diff --git a/tests/integration/test_alembic_v2_user_types.py b/tests/integration/test_alembic_v2_user_types.py index 9e95bf1aa..60e0efc32 100644 --- a/tests/integration/test_alembic_v2_user_types.py +++ b/tests/integration/test_alembic_v2_user_types.py @@ -4,7 +4,10 @@ author and admin, and changes nothing else; its downgrade restores the check that allows only unauthenticated and standard, so it fails while any user is an author or an admin. Revision 970be5d29283, on it, adds user_type_changes and -changes nothing else. +changes nothing else. Revision bb09a374231f, on the SPM availability revision, +adds user_invitations and user_type_changes.dismissed_at, and lets a change's +source be invitation; its downgrade fails while any change's source is +invitation. """ import re @@ -27,6 +30,9 @@ USER_TYPES_REVISION = "617f531f1506" # The user type changes revision, on the user types revision. USER_TYPE_CHANGES_REVISION = "970be5d29283" +# The SPM availability revision, and the user invitations revision on it. +SPM_AVAILABILITY_REVISION = "0c136a278f29" +USER_INVITATIONS_REVISION = "bb09a374231f" def _check_names(engine: Engine, table_name: str) -> set[str]: @@ -195,3 +201,117 @@ def test_user_type_changes_revision_adds_only_its_table() -> None: finally: command.upgrade(config, "head") engine.dispose() + + +def test_user_invitations_revision_adds_invitations_and_dismissals_only() -> None: + """The revision adds user_invitations, dismissed_at and a wider source check.""" + database_url = disposable_v2_url() + config = alembic_v2_config() + engine = create_engine(database_url) + + try: + command.downgrade(config, SPM_AVAILABILITY_REVISION) + parent = _schema_shape(engine) + command.upgrade(config, USER_INVITATIONS_REVISION) + revision = _schema_shape(engine) + + assert set(revision) - set(parent) == {"user_invitations"} + changed_tables = sorted( + table_name + for table_name in parent + if revision[table_name] != parent[table_name] + ) + assert changed_tables == ["user_type_changes"] + parent_changes = dict(parent["user_type_changes"]) + revision_changes = dict(revision["user_type_changes"]) + parent_columns = parent_changes.pop("columns") + revision_columns = revision_changes.pop("columns") + assert revision_columns == [ + *parent_columns, + ("dismissed_at", "TIMESTAMP", True, None), + ] + parent_checks = dict(parent_changes.pop("checks")) + revision_checks = dict(revision_changes.pop("checks")) + assert revision_changes == parent_changes + assert re.findall( + r"'(\w+)'", parent_checks.pop("ck_user_type_changes_source") + ) == ["admin_route", "script"] + assert re.findall( + r"'(\w+)'", revision_checks.pop("ck_user_type_changes_source_allowed") + ) == ["admin_route", "script", "invitation"] + assert revision_checks == parent_checks + + invitations = revision["user_invitations"] + assert sorted(invitations["foreign_keys"]) == [ + ( + "fk_user_invitations_accepted_by_user_id_users", + ["accepted_by_user_id"], + "users", + ), + ( + "fk_user_invitations_invited_by_user_id_users", + ["invited_by_user_id"], + "users", + ), + ] + assert invitations["unique_constraints"] == [ + ("uq_user_invitations_token_hash", ["token_hash"]) + ] + assert set(invitations["checks"]) == { + "ck_user_invitations_user_type", + "ck_user_invitations_accepted_or_revoked", + } + finally: + command.upgrade(config, "head") + engine.dispose() + + +def test_user_invitations_revision_records_invitation_changes_until_downgraded() -> ( + None +): + """A change from an invitation is stored, and keeps the downgrade from running.""" + database_url = disposable_v2_url() + config = alembic_v2_config() + engine = create_engine(database_url) + user_id = uuid4() + + def insert_change() -> None: + with engine.begin() as connection: + connection.execute( + text( + "INSERT INTO user_type_changes (id, user_id, " + "previous_user_type, new_user_type, source) VALUES " + "(:change_id, :user_id, 'standard', 'author', 'invitation')" + ), + {"change_id": uuid4(), "user_id": user_id}, + ) + + try: + command.downgrade(config, SPM_AVAILABILITY_REVISION) + with engine.begin() as connection: + connection.execute( + text( + "INSERT INTO users (id, user_type, primary_country) " + "VALUES (:user_id, 'author', 'us')" + ), + {"user_id": user_id}, + ) + with pytest.raises(sa.exc.IntegrityError): + insert_change() + + command.upgrade(config, USER_INVITATIONS_REVISION) + insert_change() + with pytest.raises(sa.exc.IntegrityError): + command.downgrade(config, SPM_AVAILABILITY_REVISION) + with engine.connect() as connection: + context = MigrationContext.configure(connection) + assert context.get_current_revision() == USER_INVITATIONS_REVISION + assert "user_invitations" in inspect(engine).get_table_names() + finally: + with engine.begin() as connection: + connection.execute( + text("DELETE FROM users WHERE id = :user_id"), {"user_id": user_id} + ) + command.downgrade(config, SPM_AVAILABILITY_REVISION) + command.upgrade(config, "head") + engine.dispose() diff --git a/tests/integration/test_v2_user_type_persistence.py b/tests/integration/test_v2_user_type_persistence.py index f208cfc9e..adf984fe5 100644 --- a/tests/integration/test_v2_user_type_persistence.py +++ b/tests/integration/test_v2_user_type_persistence.py @@ -1,9 +1,11 @@ """PostgreSQL tests for admins' changes to users' types, as the runtime role. These prove what SQLite cannot: the runtime role's declared privileges cover -the changes and their history, the user-type change lock makes concurrent -changes and deletions run one at a time so the last admin is never demoted or -deleted and a change from a type changed meanwhile is refused, and account +the changes and their history, email invitations and their acceptance, and +dismissing a change's notice; the user-type change lock makes concurrent +changes, acceptances and deletions run one at a time so the last admin is +never demoted or deleted, a change from a type changed meanwhile is refused, +and an invitation whose admin was demoted meanwhile is refused; and account deletion cascades through the history or keeps a change without its admin. """ @@ -15,7 +17,7 @@ from uuid import UUID, uuid4 import pytest -from sqlalchemy import create_engine, delete, select, update +from sqlalchemy import create_engine, delete, or_, select, update from sqlalchemy.orm import sessionmaker from sqlmodel import Session @@ -27,6 +29,7 @@ LegacyUserMapping, User, UserIdentity, + UserInvitation, UserType, UserTypeChange, ) @@ -41,6 +44,17 @@ AccountDatabaseSession, ) from policyengine_api.services.v2.user_accounts.services import V2AccountService +from policyengine_api.services.v2.user_emails.services import V2UserEmailService +from policyengine_api.services.v2.user_invitations.database_session import ( + UserInvitationDatabaseSession, +) +from policyengine_api.services.v2.user_invitations.services import ( + V2UserInvitationService, +) +from policyengine_api.services.v2.user_invitations.types import AdminInvitationSearch +from policyengine_api.services.v2.user_invitations.validators import ( + InviterNotAdminError, +) from policyengine_api.services.v2.user_types.database_connectors.reads import ( acquire_user_type_change_lock, read_admin_user_ids, @@ -119,6 +133,14 @@ def sessions(managed_v2_roles, v2_engine_as_role) -> Iterator[sessionmaker[Sessi owned = select(UserIdentity.user_id).where(UserIdentity.issuer == issuer) user_ids = list(connection.execute(owned).scalars()) if user_ids: + connection.execute( + delete(UserInvitation).where( + or_( + UserInvitation.invited_by_user_id.in_(user_ids), + UserInvitation.accepted_by_user_id.in_(user_ids), + ) + ) + ) connection.execute( delete(LegacyUserMapping).where( LegacyUserMapping.user_id.in_(user_ids) @@ -511,3 +533,158 @@ def carol_promotes_bob() -> None: assert isinstance(outcomes.get("error"), UserTypeChangedError) assert _stored_types(sessions, [bob_id]) == ["author"] assert _history(sessions, bob_id) == [] + + +class RecordingPostmark: + """Record each template email, as Postmark would accept it.""" + + app_url = "https://app.example.test" + + def __init__(self) -> None: + self.sent: list[dict] = [] + + def send_template(self, *, to, template_alias, template_model) -> None: + self.sent.append( + {"to": to, "template_alias": template_alias, "model": dict(template_model)} + ) + + +def _invitations( + sessions, postmark: RecordingPostmark, auth0: StandInAuth0 +) -> V2UserInvitationService: + def source() -> UserProfileSource: + return UserProfileSource(issuer=sessions.kw["info"]["issuer"], reader=auth0) + + return V2UserInvitationService( + UserInvitationDatabaseSession(sessions), + user_email_service=V2UserEmailService( + email_sender_factory=lambda: postmark, user_profile_source_factory=source + ), + user_profile_source_factory=source, + ) + + +def _sent_token(postmark: RecordingPostmark) -> str: + return postmark.sent[-1]["model"]["accept_url"].split("#token=", 1)[1] + + +def test_the_runtime_role_invites_accepts_and_dismisses(sessions) -> None: + alice = _principal(sessions, "alice") + bob = _principal(sessions, "bob") + accounts = _accounts(sessions) + alice_id = accounts.get_account(principal=alice, country_id="us").id + bob_id = accounts.get_account(principal=bob, country_id="us").id + _store_type_as_superuser(alice_id, UserType.ADMIN) + postmark = RecordingPostmark() + auth0 = StandInAuth0( + Auth0UserProfile( + user_id=bob.subject, + email="Bob@Invited.example.test", + email_verified=True, + given_name=None, + family_name=None, + name=None, + ) + ) + invitations = _invitations(sessions, postmark, auth0) + + withdrawn = invitations.create_invitation( + principal=alice, email="other@invited.example.test", user_type=UserType.ADMIN + ) + invitations.revoke_invitation(principal=alice, invitation_id=withdrawn.id) + invited = invitations.create_invitation( + principal=alice, email="bob@invited.example.test", user_type=UserType.AUTHOR + ) + resent = invitations.resend_invitation(principal=alice, invitation_id=invited.id) + listed = invitations.list_invitations( + principal=alice, search=AdminInvitationSearch() + ) + acceptance = invitations.accept_invitation( + principal=bob, token=_sent_token(postmark), country_id="us" + ) + latest = accounts.get_account(principal=bob, country_id="us").latest_type_change + assert latest is not None + accounts.dismiss_type_change(principal=bob, type_change_id=latest.id) + after_dismissal = accounts.get_account(principal=bob, country_id="us") + + assert resent.last_sent_at is not None + assert invited.id in {item.id for item in listed.items} + assert withdrawn.id not in {item.id for item in listed.items} + assert acceptance.type_changed is True + assert _stored_types(sessions, [bob_id]) == ["author"] + (change,) = _history(sessions, bob_id) + assert (change.source, change.changed_by_user_id) == ("invitation", alice_id) + assert (latest.previous_user_type, latest.user_type) == ( + UserType.STANDARD, + UserType.AUTHOR, + ) + assert after_dismissal.latest_type_change is None + assert [email["template_alias"] for email in postmark.sent] == [ + "user-invitation", + "user-invitation", + "user-invitation", + "user-type-changed", + ] + assert postmark.sent[-1]["to"] == "Bob@Invited.example.test" + + +def test_an_acceptance_waits_for_its_inviters_demotion_and_is_refused( + sessions, +) -> None: + """Carol demotes Alice while Bob's acceptance of Alice's invitation waits.""" + alice = _principal(sessions, "alice") + bob = _principal(sessions, "bob") + carol = _principal(sessions, "carol") + accounts = _accounts(sessions) + alice_id = accounts.get_account(principal=alice, country_id="us").id + bob_id = accounts.get_account(principal=bob, country_id="us").id + carol_id = accounts.get_account(principal=carol, country_id="us").id + for user_id in (alice_id, carol_id): + _store_type_as_superuser(user_id, UserType.ADMIN) + postmark = RecordingPostmark() + auth0 = StandInAuth0( + Auth0UserProfile( + user_id=bob.subject, + email="bob@invited.example.test", + email_verified=True, + given_name=None, + family_name=None, + name=None, + ) + ) + _invitations(sessions, postmark, auth0).create_invitation( + principal=alice, email="bob@invited.example.test", user_type=UserType.ADMIN + ) + token = _sent_token(postmark) + outcomes: dict[str, object] = {} + finished = threading.Event() + + def bob_accepts() -> None: + try: + outcomes["result"] = _invitations( + sessions, postmark, auth0 + ).accept_invitation(principal=bob, token=token, country_id="us") + except Exception as error: # noqa: BLE001 # the test inspects the failure + outcomes["error"] = error + finally: + finished.set() + + held = sessions() + try: + held.begin() + # Carol's change holds the user-type change lock, as the service's does. + assert sorted(_lock_and_read_admins(held)) == sorted([alice_id, carol_id]) + waiting_acceptance = threading.Thread(target=bob_accepts) + waiting_acceptance.start() + assert not finished.wait(LOCK_WAIT_SECONDS) + alice_row = read_signed_in_user(held, alice_id, for_update=True) + assert alice_row is not None + update_user_type(held, alice_row, user_type=UserType.AUTHOR) + held.commit() + finally: + held.close() + waiting_acceptance.join(timeout=10) + + # Alice is no longer an admin once Bob's turn comes, so it is refused. + assert isinstance(outcomes.get("error"), InviterNotAdminError) + assert _stored_types(sessions, [bob_id]) == ["standard"] diff --git a/tests/unit/libs/test_postmark_email.py b/tests/unit/libs/test_postmark_email.py new file mode 100644 index 000000000..4582625d1 --- /dev/null +++ b/tests/unit/libs/test_postmark_email.py @@ -0,0 +1,285 @@ +"""Unit tests for :mod:`policyengine_api.libs.postmark_email`.""" + +from __future__ import annotations + +import json + +import httpx +import pytest + +from policyengine_api.libs.postmark_email import ( + POSTMARK_TEMPLATE_URL, + SEND_ATTEMPTS, + EmailSendError, + PostmarkConfigurationError, + PostmarkEmailSender, + PostmarkSettings, + build_postmark_email_sender, + load_postmark_settings, +) + +SECRET_RESOURCE = "projects/p/secrets/postmark-server-token/versions/latest" +SENDER = "PolicyEngine " +APP_URL = "https://app.policyengine.org" +COMPLETE_SETTINGS = { + "POSTMARK_SERVER_TOKEN_SECRET_RESOURCE": SECRET_RESOURCE, + "POSTMARK_SENDER_ADDRESS": SENDER, + "POLICYENGINE_APP_URL": APP_URL, +} + + +def _sender( + responses: list[httpx.Response | Exception], + **settings: str, +) -> tuple[PostmarkEmailSender, list[httpx.Request], list[float]]: + """Build a sender whose requests get ``responses`` in order.""" + requests: list[httpx.Request] = [] + waits: list[float] = [] + + def answer(request: httpx.Request) -> httpx.Response: + requests.append(request) + response = responses.pop(0) + if isinstance(response, Exception): + raise response + return response + + values = { + "sender_address": SENDER, + "app_url": APP_URL, + "server_token": "server-token", + } + values.update(settings) + return ( + PostmarkEmailSender( + PostmarkSettings(**values), + http_client=httpx.Client(transport=httpx.MockTransport(answer)), + secret_loader=lambda _resource: "loaded-token\n", + sleep=waits.append, + ), + requests, + waits, + ) + + +def _send(sender: PostmarkEmailSender) -> None: + sender.send_template( + to="ada@example.org", + template_alias="user-type-changed", + template_model={"user_type": "author"}, + ) + + +def test_settings_are_optional_and_all_or_none() -> None: + assert load_postmark_settings({}) is None + assert build_postmark_email_sender({}) is None + for left_out in COMPLETE_SETTINGS: + partial = { + name: value for name, value in COMPLETE_SETTINGS.items() if name != left_out + } + with pytest.raises(PostmarkConfigurationError, match="partially configured"): + load_postmark_settings(partial) + with pytest.raises(PostmarkConfigurationError, match="exactly one"): + load_postmark_settings( + COMPLETE_SETTINGS | {"POSTMARK_SERVER_TOKEN": "server-token"} + ) + + +def test_complete_settings_keep_the_token_out_of_their_repr() -> None: + settings = load_postmark_settings( + { + "POSTMARK_SERVER_TOKEN": " server-token ", + "POSTMARK_SENDER_ADDRESS": f" {SENDER} ", + "POLICYENGINE_APP_URL": f"{APP_URL}/", + } + ) + + assert settings == PostmarkSettings( + sender_address=SENDER, app_url=APP_URL, server_token="server-token" + ) + assert "server-token" not in repr(settings) + assert load_postmark_settings(COMPLETE_SETTINGS) == PostmarkSettings( + sender_address=SENDER, + app_url=APP_URL, + server_token_resource=SECRET_RESOURCE, + ) + + +@pytest.mark.parametrize( + ("name", "value", "message"), + [ + ("POSTMARK_SERVER_TOKEN_SECRET_RESOURCE", "postmark-token", "is invalid"), + ("POSTMARK_SENDER_ADDRESS", "no-reply", "an email address"), + ("POSTMARK_SENDER_ADDRESS", "a@b.org\nBcc: c@d.org", "an email address"), + ("POLICYENGINE_APP_URL", "app.policyengine.org", "https"), + ("POLICYENGINE_APP_URL", "http://app.policyengine.org", "https"), + ("POLICYENGINE_APP_URL", f"{APP_URL}/?next=1", "query or fragment"), + ("POLICYENGINE_APP_URL", f"{APP_URL}/#top", "query or fragment"), + ], +) +def test_invalid_settings_are_refused_without_their_values( + name: str, value: str, message: str +) -> None: + with pytest.raises(PostmarkConfigurationError, match=message) as refused: + load_postmark_settings(COMPLETE_SETTINGS | {name: value}) + + assert value not in str(refused.value) + + +def test_a_local_app_url_may_use_http() -> None: + settings = load_postmark_settings( + COMPLETE_SETTINGS | {"POLICYENGINE_APP_URL": "http://localhost:5173"} + ) + + assert settings is not None + assert settings.app_url == "http://localhost:5173" + + +def test_a_template_email_is_posted_once_on_the_transactional_stream() -> None: + sender, requests, waits = _sender( + [httpx.Response(200, json={"ErrorCode": 0, "Message": "OK"})] + ) + + _send(sender) + + (request,) = requests + assert str(request.url) == POSTMARK_TEMPLATE_URL + assert request.method == "POST" + assert request.headers["X-Postmark-Server-Token"] == "server-token" + assert request.headers["Accept"] == "application/json" + assert json.loads(request.content) == { + "From": SENDER, + "To": "ada@example.org", + "TemplateAlias": "user-type-changed", + "TemplateModel": {"user_type": "author"}, + "MessageStream": "outbound", + } + assert waits == [] + assert sender.app_url == APP_URL + + +def test_the_token_is_read_from_its_secret_manager_resource() -> None: + sender, requests, _waits = _sender( + [httpx.Response(200, json={"ErrorCode": 0})], + server_token="", + server_token_resource=SECRET_RESOURCE, + ) + + _send(sender) + + assert requests[0].headers["X-Postmark-Server-Token"] == "loaded-token" + + +def test_an_unreadable_token_fails_without_a_request() -> None: + def refuse(_resource: str) -> str: + msg = "permission denied" + raise RuntimeError(msg) + + requests: list[httpx.Request] = [] + sender = PostmarkEmailSender( + PostmarkSettings( + sender_address=SENDER, + app_url=APP_URL, + server_token_resource=SECRET_RESOURCE, + ), + http_client=httpx.Client( + transport=httpx.MockTransport( + lambda request: requests.append(request) or httpx.Response(200) + ) + ), + secret_loader=refuse, + sleep=lambda _seconds: None, + ) + + with pytest.raises(EmailSendError) as failed: + _send(sender) + + assert failed.value.cause == "secret_unavailable" + assert requests == [] + + +@pytest.mark.parametrize( + "failure", + [ + httpx.Response(500), + httpx.Response(503), + httpx.Response(429), + httpx.ConnectTimeout("slow"), + httpx.ConnectError("refused"), + ], +) +def test_a_retryable_failure_is_retried_after_short_waits( + failure: httpx.Response | Exception, +) -> None: + sender, requests, waits = _sender( + [failure, failure, httpx.Response(200, json={"ErrorCode": 0})] + ) + + _send(sender) + + assert len(requests) == SEND_ATTEMPTS + assert waits == [0.5, 1.0] + + +@pytest.mark.parametrize( + ("failure", "cause"), + [ + (httpx.Response(500), "http_500"), + (httpx.ReadTimeout("slow"), "timeout"), + (httpx.ConnectError("refused"), "connection_error"), + ], +) +def test_a_send_failing_every_attempt_names_its_last_cause( + failure: httpx.Response | Exception, cause: str +) -> None: + sender, requests, waits = _sender([failure] * SEND_ATTEMPTS) + + with pytest.raises(EmailSendError) as failed: + _send(sender) + + assert failed.value.cause == cause + assert str(failed.value) == f"Postmark did not accept the email: {cause}" + assert len(requests) == SEND_ATTEMPTS + assert waits == [0.5, 1.0] + + +@pytest.mark.parametrize( + ("response", "cause"), + [ + ( + httpx.Response(401, json={"ErrorCode": 10, "Message": "Bad token"}), + "http_401", + ), + # Postmark answers 422 with its own error code, such as 406 for an + # address it suppresses after a bounce or spam complaint. + ( + httpx.Response( + 422, json={"ErrorCode": 406, "Message": "ada@example.org inactive"} + ), + "postmark_406", + ), + (httpx.Response(422, text="not json"), "http_422"), + ( + httpx.Response(200, json={"ErrorCode": 300, "Message": "Invalid"}), + "postmark_300", + ), + ], +) +def test_a_refused_email_is_not_retried_and_names_no_address( + response: httpx.Response, cause: str +) -> None: + sender, requests, waits = _sender([response]) + + with pytest.raises(EmailSendError) as failed: + _send(sender) + + assert failed.value.cause == cause + assert "ada@example.org" not in str(failed.value) + assert len(requests) == 1 + assert waits == [] + + +def test_build_returns_a_sender_for_complete_settings() -> None: + sender = build_postmark_email_sender(COMPLETE_SETTINGS) + + assert isinstance(sender, PostmarkEmailSender) + assert sender.app_url == APP_URL diff --git a/tests/unit/test_cloud_run_candidate_deploy.py b/tests/unit/test_cloud_run_candidate_deploy.py index 4634ca1c3..f2b401694 100644 --- a/tests/unit/test_cloud_run_candidate_deploy.py +++ b/tests/unit/test_cloud_run_candidate_deploy.py @@ -504,3 +504,46 @@ def test_deploy_cloud_run_candidate_passes_enforcement_when_it_is_switched_on(): assert result.returncode == 0, result.stderr assert r"\|PUBLIC_API_SERVER_CREDENTIAL_REQUIRED=1\|" in result.stdout + + +def test_deploy_cloud_run_candidate_passes_postmark_settings_when_set(): + postmark_resource = ( + "projects/policyengine-api/secrets/postmark-server-token/versions/latest" + ) + without_postmark = _run_script( + ".github/scripts/deploy_cloud_run_candidate.sh", + _script_env( + **_required_runtime_env(), + CLOUD_RUN_IMAGE_URI="us-central1-docker.pkg.dev/project/repo/api:sha", + CLOUD_RUN_TAG="stage3-test", + POSTMARK_SERVER_TOKEN_SECRET_RESOURCE="", + POSTMARK_SENDER_ADDRESS="", + POLICYENGINE_APP_URL="", + ), + ) + with_postmark = _run_script( + ".github/scripts/deploy_cloud_run_candidate.sh", + _script_env( + **_required_runtime_env(), + CLOUD_RUN_IMAGE_URI="us-central1-docker.pkg.dev/project/repo/api:sha", + CLOUD_RUN_TAG="stage3-test", + POSTMARK_SERVER_TOKEN_SECRET_RESOURCE=postmark_resource, + POSTMARK_SENDER_ADDRESS="no-reply@policyengine.org", + POLICYENGINE_APP_URL="https://app.policyengine.org", + ), + ) + + assert without_postmark.returncode == 0, without_postmark.stderr + assert "POSTMARK" not in without_postmark.stdout + assert "POLICYENGINE_APP_URL" not in without_postmark.stdout + assert with_postmark.returncode == 0, with_postmark.stderr + # The command trace escapes the list's separators. + for setting in ( + f"POSTMARK_SERVER_TOKEN_SECRET_RESOURCE={postmark_resource}", + "POSTMARK_SENDER_ADDRESS=no-reply@policyengine.org", + "POLICYENGINE_APP_URL=https://app.policyengine.org", + ): + assert rf"\|{setting}" in with_postmark.stdout + # The resource names the token's version; the token itself never reaches + # the deploy. + assert "POSTMARK_SERVER_TOKEN=" not in with_postmark.stdout diff --git a/tests/unit/test_cloud_run_deploy_environment.py b/tests/unit/test_cloud_run_deploy_environment.py index af12bb300..07fdf8d79 100644 --- a/tests/unit/test_cloud_run_deploy_environment.py +++ b/tests/unit/test_cloud_run_deploy_environment.py @@ -532,3 +532,66 @@ def test_validate_cloud_run_deploy_env_accepts_the_enforcement_setting( result = _run_script(".github/scripts/validate_cloud_run_deploy_env.sh", env) assert result.returncode == 0, result.stderr + + +POSTMARK_SETTINGS = { + "POSTMARK_SERVER_TOKEN_SECRET_RESOURCE": ( + "projects/policyengine-api/secrets/postmark-server-token/versions/latest" + ), + "POSTMARK_SENDER_ADDRESS": "PolicyEngine ", + "POLICYENGINE_APP_URL": "https://app.policyengine.org", +} + + +@pytest.mark.parametrize("left_out", list(POSTMARK_SETTINGS)) +def test_validate_cloud_run_deploy_env_requires_every_postmark_setting_or_none( + left_out: str, +): + partial = { + name: value for name, value in POSTMARK_SETTINGS.items() if name != left_out + } + + result = _run_script( + ".github/scripts/validate_cloud_run_deploy_env.sh", + _script_env(**_required_runtime_env(), **partial), + ) + + assert result.returncode == 1 + assert ( + "Set POSTMARK_SERVER_TOKEN_SECRET_RESOURCE, POSTMARK_SENDER_ADDRESS, and " + "POLICYENGINE_APP_URL together, or none" + ) in result.stderr + + +def test_validate_cloud_run_deploy_env_allows_postmark_in_staging_and_production(): + results = [ + _run_script( + ".github/scripts/validate_cloud_run_deploy_env.sh", + _script_env(**environment, **POSTMARK_SETTINGS), + ) + for environment in (_staging_runtime_env(), _required_runtime_env()) + ] + + for result in results: + assert result.returncode == 0, result.stderr + + +@pytest.mark.parametrize( + "app_url", + [ + "http://app.policyengine.org", + "app.policyengine.org", + "https://app.policyengine.org/?next=1", + ], +) +def test_validate_cloud_run_deploy_env_requires_an_https_app_url(app_url: str): + result = _run_script( + ".github/scripts/validate_cloud_run_deploy_env.sh", + _script_env( + **_required_runtime_env(), + **(POSTMARK_SETTINGS | {"POLICYENGINE_APP_URL": app_url}), + ), + ) + + assert result.returncode == 1 + assert "POLICYENGINE_APP_URL must be an https address" in result.stderr diff --git a/tests/unit/test_cloud_run_push_workflow.py b/tests/unit/test_cloud_run_push_workflow.py index 60bb9bf9a..bcf04476c 100644 --- a/tests/unit/test_cloud_run_push_workflow.py +++ b/tests/unit/test_cloud_run_push_workflow.py @@ -564,3 +564,26 @@ def test_push_workflow_wires_auth0_user_profile_settings_to_both_deploys(): assert line in job # The release tests never see them. assert "AUTH0_USER_PROFILES" not in _workflow_job_block(workflow, RELEASE_TESTS_JOB) + + +def test_push_workflow_wires_postmark_settings_to_both_deploys(): + """Each deploy job gets its environment's Postmark server and app address.""" + workflow = _push_workflow() + staging = _workflow_job_block(workflow, "deploy-cloud-run-staging") + production = _workflow_job_block(workflow, "deploy-cloud-run-candidate") + + for job, environment in ((staging, "staging"), (production, "production")): + assert f" environment: {environment}\n" in job + for line in ( + "POSTMARK_SERVER_TOKEN_SECRET_RESOURCE: " + "${{ secrets.POSTMARK_SERVER_TOKEN_SECRET_RESOURCE }}", + "POSTMARK_SENDER_ADDRESS: ${{ vars.POSTMARK_SENDER_ADDRESS }}", + "POLICYENGINE_APP_URL: ${{ vars.POLICYENGINE_APP_URL }}", + ): + assert line in job + # The deploy names the token's Secret Manager version, never the token. + assert "POSTMARK_SERVER_TOKEN:" not in job + # The release tests never see them. + release_tests = _workflow_job_block(workflow, RELEASE_TESTS_JOB) + assert "POSTMARK" not in release_tests + assert "POLICYENGINE_APP_URL" not in release_tests diff --git a/tests/unit/test_readiness.py b/tests/unit/test_readiness.py index 478d2b053..ccc796c36 100644 --- a/tests/unit/test_readiness.py +++ b/tests/unit/test_readiness.py @@ -291,3 +291,57 @@ def test_enforcement_with_allowed_server_clients_passes_readiness( ): readiness.mark_ready() assert readiness.is_ready() is True + + +POSTMARK_SETTING_NAMES = ( + "POSTMARK_SERVER_TOKEN", + "POSTMARK_SERVER_TOKEN_SECRET_RESOURCE", + "POSTMARK_SENDER_ADDRESS", + "POLICYENGINE_APP_URL", +) +COMPLETE_POSTMARK_SETTINGS = { + "POSTMARK_SERVER_TOKEN_SECRET_RESOURCE": ( + "projects/p/secrets/postmark-server-token/versions/latest" + ), + "POSTMARK_SENDER_ADDRESS": "PolicyEngine ", + "POLICYENGINE_APP_URL": "https://app.policyengine.org", +} + + +def _ready_with_postmark(monkeypatch, environment: dict[str, str]) -> bool: + for name in POSTMARK_SETTING_NAMES: + monkeypatch.delenv(name, raising=False) + for name, value in environment.items(): + monkeypatch.setenv(name, value) + with patch( + "policyengine_api.data.v2.settings.load_v2_runtime_database_settings", + return_value=object(), + ): + readiness.mark_ready() + return readiness.is_ready() + + +@pytest.mark.parametrize( + "environment", + [ + # All or none, so a half-configured deploy never runs without email. + {"POSTMARK_SENDER_ADDRESS": "no-reply@policyengine.org"}, + { + name: value + for name, value in COMPLETE_POSTMARK_SETTINGS.items() + if name != "POLICYENGINE_APP_URL" + }, + # The emails' links must be https. + COMPLETE_POSTMARK_SETTINGS + | {"POLICYENGINE_APP_URL": "http://app.policyengine.org"}, + ], +) +def test_unusable_postmark_settings_fail_readiness(monkeypatch, environment) -> None: + assert _ready_with_postmark(monkeypatch, environment) is False + + +@pytest.mark.parametrize("environment", [{}, COMPLETE_POSTMARK_SETTINGS]) +def test_absent_or_complete_postmark_settings_pass_readiness( + monkeypatch, environment +) -> None: + assert _ready_with_postmark(monkeypatch, environment) is True diff --git a/tests/unit/test_set_v2_user_type_script.py b/tests/unit/test_set_v2_user_type_script.py index ee2dd0a39..5c14d844e 100644 --- a/tests/unit/test_set_v2_user_type_script.py +++ b/tests/unit/test_set_v2_user_type_script.py @@ -121,3 +121,50 @@ def test_the_command_refuses_missing_or_unknown_arguments(arguments) -> None: assert exit_info.value.code == 2 assert user_types.calls == [] + + +def test_the_command_emails_the_user_whose_type_it_changed(monkeypatch) -> None: + """The command's own service emails the user, as the admin routes do.""" + from policyengine_api.data.v2 import database + from policyengine_api.fastapi_routes import dependencies + from policyengine_api.services.v2.identity.types import UserPrincipal + from policyengine_api.services.v2.user_accounts.database_session import ( + AccountDatabaseSession, + ) + from policyengine_api.services.v2.user_accounts.services import V2AccountService + from tests.unit.v2.user_email_support import ( + RecordingEmailSender, + StandInProfileReader, + auth0_profile, + profile_source, + ) + from tests.unit.v2.user_service_support import ISSUER, v2_store + + ada = UserPrincipal( + issuer=ISSUER, subject="google-oauth2|ada", email="ada@example.org" + ) + sender = RecordingEmailSender() + reader = StandInProfileReader([auth0_profile(ada.subject, "ada@auth0.test")]) + with v2_store() as store: + V2AccountService(AccountDatabaseSession(store.sessions)).get_account( + principal=ada, country_id="us" + ) + monkeypatch.setattr(database, "get_v2_session_factory", lambda: store.sessions) + monkeypatch.setattr( + "policyengine_api.libs.postmark_email.build_postmark_email_sender", + lambda: sender, + ) + monkeypatch.setattr( + dependencies, + "_default_user_profile_source", + lambda: profile_source(ISSUER, reader), + ) + + exit_code = set_v2_user_type.main( + ["--email", "ada@example.org", "--user-type", "author"] + ) + + assert exit_code == 0 + assert [(email["to"], email["template_alias"]) for email in sender.sent] == [ + ("ada@auth0.test", "user-type-changed") + ] diff --git a/tests/unit/v2/test_admin_invitation_routes.py b/tests/unit/v2/test_admin_invitation_routes.py new file mode 100644 index 000000000..41b006942 --- /dev/null +++ b/tests/unit/v2/test_admin_invitation_routes.py @@ -0,0 +1,283 @@ +"""Native FastAPI contract tests for admins' email invitation routes.""" + +from __future__ import annotations + +from datetime import UTC, datetime +from uuid import UUID + +import pytest + +from policyengine_api.data.v2.models import UserType +from policyengine_api.services.v2.user_invitations.types import ( + AdminInvitationPage, + AdminInvitationRead, + AdminInvitationSearch, +) +from policyengine_api.services.v2.user_invitations.validators import ( + InvitationNotFoundError, +) +from policyengine_api.services.v2.user_types.validators import ( + UserTypeBelowMinimumError, +) +from tests.unit.v2.user_route_support import ( + CREATED_AT, + OWNER_ID, + PRINCIPAL, + RecordingService, + signed_out_browser, + user_route_client, +) + +INVITATION_ID = UUID("00000000-0000-0000-0000-000000000091") +EXPIRES_AT = datetime(2026, 1, 8, tzinfo=UTC) + + +def _invitation(**changes) -> AdminInvitationRead: + values = { + "id": INVITATION_ID, + "email": "Ada@Example.org", + "user_type": UserType.AUTHOR, + "invited_by_user_id": OWNER_ID, + "created_at": CREATED_AT, + "expires_at": EXPIRES_AT, + "expired": False, + "last_sent_at": None, + "last_send_error": "postmark_406", + } + values.update(changes) + return AdminInvitationRead(**values) + + +EXPECTED_INVITATION = { + "id": str(INVITATION_ID), + "email": "Ada@Example.org", + "user_type": "author", + "invited_by_user_id": str(OWNER_ID), + "created_at": "2026-01-01T00:00:00Z", + "expires_at": "2026-01-08T00:00:00Z", + "expired": False, + "last_sent_at": None, + "last_send_error": "postmark_406", +} + + +def _result(name: str, kwargs: dict): + if name == "list_invitations": + search = kwargs["search"] + return AdminInvitationPage( + items=(_invitation(),), + offset=search.offset, + limit=search.limit, + has_more=False, + ) + if name == "revoke_invitation": + return None + return _invitation() + + +def _client( + invitations: RecordingService | None = None, + user_types: RecordingService | None = None, + **client_options, +): + invitations = invitations or RecordingService(_result) + user_types = user_types or RecordingService(UserType.ADMIN) + client, _flask_calls = user_route_client( + v2_user_invitation_service_factory=lambda: invitations, + v2_user_type_service_factory=lambda: user_types, + **client_options, + ) + return client, invitations, user_types + + +def test_admins_invite_an_address_to_become_an_author_or_admin() -> None: + client, invitations, user_types = _client() + + response = client.post( + "/v2/admin/invitations", + json={"email": " Ada@Example.org ", "user_type": "author"}, + ) + + assert response.status_code == 201 + assert response.json() == { + "status": "ok", + "message": None, + "result": {"item": EXPECTED_INVITATION}, + } + assert user_types.calls == [ + ( + "require_minimum_user_type", + {"principal": PRINCIPAL, "minimum": UserType.ADMIN}, + ) + ] + assert invitations.calls == [ + ( + "create_invitation", + { + "principal": PRINCIPAL, + "email": "Ada@Example.org", + "user_type": UserType.AUTHOR, + }, + ) + ] + + +@pytest.mark.parametrize( + "body", + [ + {}, + {"email": "ada@example.org"}, + {"email": "ada@example.org", "user_type": "standard"}, + {"email": "ada@example.org", "user_type": "unauthenticated"}, + {"email": "ada", "user_type": "author"}, + {"email": "ada@@example.org", "user_type": "author"}, + {"email": "ada smith@example.org", "user_type": "author"}, + {"email": "", "user_type": "author"}, + {"email": "a@" + "b" * 319, "user_type": "author"}, + {"email": "ada@example.org", "user_type": "author", "note": "hi"}, + ], +) +def test_an_invitation_needs_one_address_and_an_author_or_admin_type( + body: dict, +) -> None: + client, invitations, _user_types = _client() + + response = client.post("/v2/admin/invitations", json=body) + + assert response.status_code == 422 + assert invitations.calls == [] + + +def test_admins_list_open_invitations_a_page_at_a_time() -> None: + client, invitations, _user_types = _client() + + response = client.get("/v2/admin/invitations?offset=2&limit=5") + default = client.get("/v2/admin/invitations") + + assert response.status_code == 200 + assert response.json()["result"] == { + "items": [EXPECTED_INVITATION], + "offset": 2, + "limit": 5, + "has_more": False, + } + assert default.status_code == 200 + assert [kwargs for name, kwargs in invitations.calls] == [ + {"principal": PRINCIPAL, "search": AdminInvitationSearch(offset=2, limit=5)}, + {"principal": PRINCIPAL, "search": AdminInvitationSearch(offset=0, limit=100)}, + ] + + +@pytest.mark.parametrize( + "query", ["limit=0", "limit=501", "offset=-1", "unknown=1", "limit=1&limit=2"] +) +def test_the_invitation_list_refuses_invalid_queries(query: str) -> None: + client, invitations, _user_types = _client() + + response = client.get(f"/v2/admin/invitations?{query}") + + assert response.status_code == 422 + assert invitations.calls == [] + + +def test_admins_resend_and_revoke_an_invitation() -> None: + client, invitations, _user_types = _client() + + resent = client.post(f"/v2/admin/invitations/{INVITATION_ID}/resend") + revoked = client.delete(f"/v2/admin/invitations/{INVITATION_ID}") + + assert resent.status_code == 200 + assert resent.json()["result"] == {"item": EXPECTED_INVITATION} + assert revoked.status_code == 204 + assert revoked.content == b"" + assert invitations.calls == [ + ("resend_invitation", {"principal": PRINCIPAL, "invitation_id": INVITATION_ID}), + ("revoke_invitation", {"principal": PRINCIPAL, "invitation_id": INVITATION_ID}), + ] + + +def test_an_invitation_that_isnt_open_is_not_found() -> None: + invitations = RecordingService(_result) + invitations.error = InvitationNotFoundError("No pending invitation has this ID") + client, _invitations, _user_types = _client(invitations) + + responses = [ + client.post(f"/v2/admin/invitations/{INVITATION_ID}/resend"), + client.delete(f"/v2/admin/invitations/{INVITATION_ID}"), + ] + + assert [response.status_code for response in responses] == [404, 404] + assert responses[0].json() == { + "status": "error", + "message": "No pending invitation has this ID", + } + + +def test_callers_below_admin_reach_no_invitation_route() -> None: + user_types = RecordingService() + user_types.error = UserTypeBelowMinimumError("Only admins may do this") + client, invitations, _user_types = _client(user_types=user_types) + + responses = [ + client.post( + "/v2/admin/invitations", + json={"email": "ada@example.org", "user_type": "admin"}, + ), + client.get("/v2/admin/invitations"), + client.post(f"/v2/admin/invitations/{INVITATION_ID}/resend"), + client.delete(f"/v2/admin/invitations/{INVITATION_ID}"), + ] + + assert [response.status_code for response in responses] == [403] * 4 + assert invitations.calls == [] + + +def test_a_service_refusal_inside_the_transaction_is_403() -> None: + invitations = RecordingService(_result) + invitations.error = UserTypeBelowMinimumError("Only admins may do this") + client, _invitations, _user_types = _client(invitations) + + response = client.get("/v2/admin/invitations") + + assert response.status_code == 403 + + +def test_signed_out_browsers_reach_no_invitation_route() -> None: + user_types = RecordingService() + user_types.error = UserTypeBelowMinimumError("Only admins may do this") + client, invitations, _user_types = _client( + user_types=user_types, require_user=signed_out_browser + ) + + response = client.get("/v2/admin/invitations") + + assert response.status_code == 403 + assert invitations.calls == [] + + +def test_invitation_routes_need_a_credential() -> None: + client, invitations, _user_types = _client(require_user=None) + + response = client.get("/v2/admin/invitations") + + assert response.status_code == 401 + assert invitations.calls == [] + + +def test_the_openapi_document_describes_the_invitation_routes() -> None: + client, _invitations, _user_types = _client() + + paths = client.get("/v2/openapi.json").json()["paths"] + + create = paths["/v2/admin/invitations"]["post"] + assert set(create["responses"]) >= {"201", "401", "403", "413", "422", "503"} + assert set( + paths["/v2/admin/invitations/{invitation_id}"]["delete"]["responses"] + ) >= { + "204", + "404", + } + assert ( + "404" + in paths["/v2/admin/invitations/{invitation_id}/resend"]["post"]["responses"] + ) diff --git a/tests/unit/v2/test_alembic_v2.py b/tests/unit/v2/test_alembic_v2.py index 1c27b6f0d..3ea47c221 100644 --- a/tests/unit/v2/test_alembic_v2.py +++ b/tests/unit/v2/test_alembic_v2.py @@ -54,6 +54,7 @@ "stage12_evaluation_reports", "stage12_evaluation_simulations", "user_identities", + "user_invitations", "user_type_changes", } ) @@ -79,6 +80,8 @@ # The user type changes revision, on the user types revision, and parent of # the SPM availability revision. USER_TYPE_CHANGES_REVISION = "970be5d29283" +# The SPM availability revision, parent of the user invitations revision. +SPM_AVAILABILITY_REVISION = "0c136a278f29" DISPOSABLE_URL = ( "postgresql+psycopg://postgres:test-password@127.0.0.1:5432/" f"{DISPOSABLE_DATABASE_NAME}" @@ -260,6 +263,7 @@ def test_v2_revision_chain_has_generated_policy_and_user_identity_changes() -> N assert script.get_heads() == [V2_ALEMBIC_HEAD_REVISION] assert [revision.revision for revision in script.walk_revisions()] == [ V2_ALEMBIC_HEAD_REVISION, + SPM_AVAILABILITY_REVISION, USER_TYPE_CHANGES_REVISION, USER_TYPES_REVISION, SAVED_ITEM_KEYS_REVISION, @@ -1298,7 +1302,7 @@ def test_spm_availability_revision_adds_only_one_nullable_column() -> None: if revision.down_revision == USER_TYPE_CHANGES_REVISION ] assert len(children) == 1 - assert children[0].revision == V2_ALEMBIC_HEAD_REVISION + assert children[0].revision == SPM_AVAILABILITY_REVISION revision = Path(children[0].path).read_text(encoding="utf-8") upgrade = revision[ revision.index("def upgrade()") : revision.index("def downgrade()") @@ -1328,3 +1332,58 @@ def test_spm_availability_revision_adds_only_one_nullable_column() -> None: assert "op.bulk_insert(" not in body assert "op.create_table(" not in body assert "op.drop_table(" not in body + + +def test_user_invitations_revision_adds_its_table_and_the_dismissal_column() -> None: + """The revision after SPM availability adds invitations and dismissals. + + It is generated with no corrections: it adds ``user_invitations`` with + its two indexes, adds ``user_type_changes.dismissed_at``, and replaces + the source check with one that also allows ``invitation``, under a new + name because Alembic compares checks by name only. The downgrade undoes + each, and neither writes data. + """ + (path,) = (REPO / "migrations/v2/versions").glob(f"{V2_ALEMBIC_HEAD_REVISION}_*.py") + revision = path.read_text(encoding="utf-8") + upgrade = revision[ + revision.index("def upgrade()") : revision.index("def downgrade()") + ] + downgrade = revision[revision.index("def downgrade()") :] + + assert ( + "Generation: uv run alembic -c alembic-v2.ini revision --autogenerate" + in revision + ) + assert ( + f'down_revision: Union[str, None] = "{SPM_AVAILABILITY_REVISION}"' in revision + ) + assert "correction" not in revision.lower() + assert sorted(re.findall(r"op\.\w+", upgrade)) == [ + "op.add_column", + "op.create_check_constraint", + "op.create_index", + "op.create_index", + "op.create_table", + "op.drop_constraint", + # Five constraint names in create_table, and the two checks'. + *["op.f"] * 7, + ] + assert sorted(re.findall(r"op\.\w+", downgrade)) == [ + "op.create_check_constraint", + "op.drop_column", + "op.drop_constraint", + "op.drop_index", + "op.drop_index", + "op.drop_table", + "op.f", + "op.f", + ] + assert re.search(r"op\.create_table\(\s*\"user_invitations\"", upgrade) + assert re.search( + r"op\.add_column\(\s*\"user_type_changes\",\s*" + r"sa\.Column\(\"dismissed_at\", sa\.DateTime\(timezone=True\), " + r"nullable=True\)", + upgrade, + ) + assert "ck_user_type_changes_source_allowed" in upgrade + assert "source IN ('admin_route', 'script', 'invitation')" in upgrade diff --git a/tests/unit/v2/test_me_routes.py b/tests/unit/v2/test_me_routes.py index 4e86e86ff..bd2937ada 100644 --- a/tests/unit/v2/test_me_routes.py +++ b/tests/unit/v2/test_me_routes.py @@ -2,10 +2,12 @@ from __future__ import annotations +from datetime import UTC, datetime from uuid import UUID import pytest +from policyengine_api.data.v2.models import UserType from policyengine_api.services.v2.identity.types import AccountConversionOutcome from policyengine_api.services.v2.identity.validators import ( StandardUserRequiresSignInError, @@ -15,12 +17,25 @@ AccountExport, AccountRead, AccountUpgrade, + LatestTypeChangeRead, ) from policyengine_api.services.v2.user_accounts.validators import ( AccountDeletionUnavailableError, AccountEditRequiresSignInError, AccountIdentityDeletionError, AccountNotFoundError, + TypeChangeNotFoundError, +) +from policyengine_api.services.v2.user_invitations.types import InvitationAcceptance +from policyengine_api.services.v2.user_invitations.validators import ( + InvitationAcceptedError, + InvitationEmailMismatchError, + InvitationEmailNotVerifiedError, + InvitationEmailUnavailableError, + InvitationExpiredError, + InvitationRevokedError, + InvitationTokenNotFoundError, + InviterNotAdminError, ) from policyengine_api.services.v2.user_policies.types import UserPolicyRead from policyengine_api.services.v2.user_reports.types import UserReportRead @@ -102,7 +117,8 @@ def test_get_me_provisions_with_the_query_country() -> None: "last_name": None, "email": None, "created_at": "2026-01-01T00:00:00Z", - } + }, + "latest_type_change": None, }, } assert service.calls == [ @@ -493,3 +509,198 @@ def test_import_route_is_removed() -> None: assert response.status_code == 405 assert service.calls == [] + + +TYPE_CHANGE_ID = UUID("00000000-0000-0000-0000-000000000066") +TYPE_CHANGED_AT = datetime(2026, 11, 1, tzinfo=UTC) + + +def test_get_me_carries_the_latest_type_change_until_it_is_dismissed() -> None: + def result(_name: str, _kwargs: dict): + return _account( + user_type="author", + latest_type_change=LatestTypeChangeRead( + id=TYPE_CHANGE_ID, + previous_user_type=UserType.STANDARD, + user_type=UserType.AUTHOR, + changed_at=TYPE_CHANGED_AT, + ), + ) + + client, _service = _client(RecordingService(result)) + + read = client.get("/v2/me?country_id=us") + patched = client.patch("/v2/me?country_id=us", json={"first_name": "Ada"}) + + assert read.status_code == 200 + assert read.json()["result"]["latest_type_change"] == { + "id": str(TYPE_CHANGE_ID), + "previous_user_type": "standard", + "user_type": "author", + "changed_at": "2026-11-01T00:00:00Z", + } + # Only reading the account reports the change. + assert set(patched.json()["result"]) == {"item"} + + +def _accepting_client(invitations: RecordingService, **client_options): + client, _flask_calls = user_route_client( + v2_user_invitation_service_factory=lambda: invitations, **client_options + ) + return client + + +def test_a_signed_in_user_accepts_an_invitation_with_its_token() -> None: + invitations = RecordingService( + InvitationAcceptance( + user_type=UserType.ADMIN, + previous_user_type=UserType.STANDARD, + type_changed=True, + ) + ) + client = _accepting_client(invitations) + + response = client.post( + "/v2/me/invitations/accept?country_id=UK", json={"token": "a-token"} + ) + + assert response.status_code == 200 + assert response.json() == { + "status": "ok", + "message": None, + "result": { + "item": { + "user_type": "admin", + "previous_user_type": "standard", + "type_changed": True, + } + }, + } + assert invitations.calls == [ + ( + "accept_invitation", + {"principal": PRINCIPAL, "token": "a-token", "country_id": "uk"}, + ) + ] + + +@pytest.mark.parametrize( + ("error", "status_code", "code"), + [ + ( + InvitationEmailUnavailableError("try again shortly"), + 503, + "auth0_unavailable", + ), + (InvitationTokenNotFoundError("not valid"), 410, "invitation_not_found"), + (InvitationRevokedError("withdrawn"), 410, "invitation_revoked"), + (InvitationExpiredError("expired"), 410, "invitation_expired"), + (InvitationAcceptedError("already accepted"), 410, "invitation_accepted"), + (InviterNotAdminError("no longer an admin"), 409, "inviter_not_admin"), + (InvitationEmailNotVerifiedError("not verified"), 409, "email_not_verified"), + (InvitationEmailMismatchError("another address"), 403, "email_mismatch"), + ], +) +def test_each_refused_acceptance_names_its_reason( + error: Exception, status_code: int, code: str +) -> None: + invitations = RecordingService() + invitations.error = error + client = _accepting_client(invitations) + + response = client.post( + "/v2/me/invitations/accept?country_id=us", json={"token": "a-token"} + ) + + assert response.status_code == status_code + assert response.json() == { + "status": "error", + "message": str(error), + "code": code, + } + + +@pytest.mark.parametrize( + ("path", "body"), + [ + ("/v2/me/invitations/accept", {"token": "a-token"}), + ("/v2/me/invitations/accept?country_id=us", {}), + ("/v2/me/invitations/accept?country_id=us", {"token": ""}), + ("/v2/me/invitations/accept?country_id=us", {"token": "t" * 257}), + ("/v2/me/invitations/accept?country_id=us", {"token": "t", "email": "x"}), + ], +) +def test_an_acceptance_needs_a_country_and_only_a_token(path: str, body: dict) -> None: + invitations = RecordingService() + client = _accepting_client(invitations) + + response = client.post(path, json=body) + + assert response.status_code == 422 + assert invitations.calls == [] + + +def test_only_a_signed_in_user_accepts_an_invitation() -> None: + invitations = RecordingService() + client = _accepting_client(invitations, require_user=signed_out_browser) + + response = client.post( + "/v2/me/invitations/accept?country_id=us", + json={"token": "a-token"}, + headers=UNAUTHENTICATED_HEADERS, + ) + + assert response.status_code == 401 + assert invitations.calls == [] + + +def test_a_signed_in_user_dismisses_a_type_change() -> None: + client, service = _client(RecordingService()) + + response = client.post( + f"/v2/me/type-changes/{TYPE_CHANGE_ID}/dismiss?country_id=us" + ) + + assert response.status_code == 204 + assert response.content == b"" + assert service.calls == [ + ( + "dismiss_type_change", + {"principal": PRINCIPAL, "type_change_id": TYPE_CHANGE_ID}, + ) + ] + + +def test_dismissing_a_type_change_the_user_doesnt_have_is_not_found() -> None: + service = RecordingService() + service.error = TypeChangeNotFoundError("You have no type change with this ID") + client, _service = _client(service) + + response = client.post( + f"/v2/me/type-changes/{TYPE_CHANGE_ID}/dismiss?country_id=us" + ) + + assert response.status_code == 404 + + +def test_only_a_signed_in_user_dismisses_a_type_change() -> None: + client, service = _client(RecordingService(), require_user=signed_out_browser) + + response = client.post( + f"/v2/me/type-changes/{TYPE_CHANGE_ID}/dismiss?country_id=us", + headers=UNAUTHENTICATED_HEADERS, + ) + + assert response.status_code == 401 + assert service.calls == [] + + +def test_the_openapi_document_names_each_refused_acceptance_code() -> None: + client = _accepting_client(RecordingService()) + + document = client.get("/v2/openapi.json").json() + accept = document["paths"]["/v2/me/invitations/accept"]["post"] + + assert {"200", "401", "403", "409", "410", "422", "503"} <= set(accept["responses"]) + for status in ("403", "409", "410", "503"): + assert "code" in str(accept["responses"][status]) diff --git a/tests/unit/v2/test_models.py b/tests/unit/v2/test_models.py index ebedf109f..9e88e395d 100644 --- a/tests/unit/v2/test_models.py +++ b/tests/unit/v2/test_models.py @@ -1022,9 +1022,14 @@ def test_user_type_changes_record_each_change_of_a_signed_in_users_type() -> Non "previous_user_type", "new_user_type", "source", + "dismissed_at", } assert not changes.c.user_id.nullable assert changes.c.changed_by_user_id.nullable + # Set when the user dismisses the app's notice of the change. + assert changes.c.dismissed_at.nullable + assert isinstance(changes.c.dismissed_at.type, sa.DateTime) + assert changes.c.dismissed_at.type.timezone is True foreign_keys = { key.parent.name: (key.column.table.name, key.ondelete) for key in changes.foreign_keys @@ -1046,9 +1051,74 @@ def test_user_type_changes_record_each_change_of_a_signed_in_users_type() -> Non ), "ck_user_type_changes_new_user_type": f"new_user_type IN {signed_in_types}", "ck_user_type_changes_changed_type": "previous_user_type <> new_user_type", - "ck_user_type_changes_source": "source IN ('admin_route', 'script')", + # Renamed when invitation was allowed: Alembic compares checks by + # name only, so a new name makes autogenerate replace the check. + "ck_user_type_changes_source_allowed": ( + "source IN ('admin_route', 'script', 'invitation')" + ), } # The admin's index serves the SET NULL that each user deletion runs. assert { tuple(column.name for column in index.columns) for index in changes.indexes } == {("user_id", "created_at"), ("changed_by_user_id",)} + + +def test_user_invitations_hold_each_invitation_and_only_its_token_hash() -> None: + invitations = V2_METADATA.tables["user_invitations"] + + assert {column.name for column in invitations.columns} == { + "id", + "created_at", + "email", + "user_type", + "token_hash", + "invited_by_user_id", + "expires_at", + "last_sent_at", + "last_send_error", + "accepted_at", + "accepted_by_user_id", + "revoked_at", + } + required = {"id", "created_at", "email", "user_type", "token_hash", "expires_at"} + assert { + column.name for column in invitations.columns if not column.nullable + } == required + for name in ("expires_at", "last_sent_at", "accepted_at", "revoked_at"): + column_type = invitations.c[name].type + assert isinstance(column_type, sa.DateTime), name + assert column_type.timezone is True, name + assert invitations.c.email.type.length == 320 + # A SHA-256 digest in hexadecimal; the token itself is never stored. + assert invitations.c.token_hash.type.length == 64 + assert invitations.c.last_send_error.type.length == 64 + foreign_keys = { + key.parent.name: (key.column.table.name, key.ondelete) + for key in invitations.foreign_keys + } + # Deleting the inviting or accepting user keeps the invitation. + assert foreign_keys == { + "invited_by_user_id": ("users", "SET NULL"), + "accepted_by_user_id": ("users", "SET NULL"), + } + checks = { + constraint.name: str(constraint.sqltext) + for constraint in invitations.constraints + if isinstance(constraint, sa.CheckConstraint) + } + assert checks == { + "ck_user_invitations_user_type": "user_type IN ('author', 'admin')", + "ck_user_invitations_accepted_or_revoked": ( + "accepted_at IS NULL OR revoked_at IS NULL" + ), + } + unique = { + tuple(column.name for column in constraint.columns) + for constraint in invitations.constraints + if isinstance(constraint, sa.UniqueConstraint) + } + assert unique == {("token_hash",)} + # The users' indexes serve the SET NULL that each user deletion runs. + assert { + tuple(column.name for column in index.columns) for index in invitations.indexes + } == {("invited_by_user_id",), ("accepted_by_user_id",)} diff --git a/tests/unit/v2/test_privilege_manifest.py b/tests/unit/v2/test_privilege_manifest.py index dbce4159e..39bef215c 100644 --- a/tests/unit/v2/test_privilege_manifest.py +++ b/tests/unit/v2/test_privilege_manifest.py @@ -22,6 +22,7 @@ NO_ACCESS, READ, READ_INSERT, + READ_INSERT_UPDATE, READ_WRITE, ROLES_AWAITING_PROVISIONING, RUNTIME_ROLE, @@ -392,7 +393,21 @@ def test_the_catalog_writer_deletes_only_the_rows_catalog_pruning_removes() -> N def test_the_public_api_records_user_type_changes_but_never_rewrites_them() -> None: declared = declared_privileges(TEST_ENVIRONMENT) - assert declared[RUNTIME_ROLE]["user_type_changes"] == READ_INSERT + # It updates only when the user dismissed the change's notice. + assert declared[RUNTIME_ROLE]["user_type_changes"] == READ_INSERT | { + update_columns("dismissed_at") + } for role, tables in declared.items(): if role != RUNTIME_ROLE: assert tables["user_type_changes"] == NO_ACCESS, role + + +def test_the_public_api_revokes_and_accepts_invitations_but_never_deletes_them() -> ( + None +): + declared = declared_privileges(TEST_ENVIRONMENT) + + assert declared[RUNTIME_ROLE]["user_invitations"] == READ_INSERT_UPDATE + for role, tables in declared.items(): + if role != RUNTIME_ROLE: + assert tables["user_invitations"] == NO_ACCESS, role diff --git a/tests/unit/v2/test_user_account_service.py b/tests/unit/v2/test_user_account_service.py index 63777b421..3e5dfd034 100644 --- a/tests/unit/v2/test_user_account_service.py +++ b/tests/unit/v2/test_user_account_service.py @@ -3,6 +3,7 @@ from __future__ import annotations from datetime import UTC, datetime, timedelta +from uuid import uuid4 import pytest from sqlmodel import select @@ -13,6 +14,8 @@ UserIdentity, UserPolicy, UserSimulationAssociation, + UserType, + UserTypeChange, ) from policyengine_api.services.v2.associations.validators import ( AssociationLinkNotFoundError, @@ -33,6 +36,7 @@ from policyengine_api.services.v2.user_accounts.validators import ( AccountDeletionUnavailableError, AccountIdentityDeletionError, + TypeChangeNotFoundError, ) from policyengine_api.services.v2.user_policies.database_session import ( UserPolicyDatabaseSession, @@ -565,3 +569,113 @@ def unexpected_build(): account_input=AccountUpdateInput(first_name="Ada"), ) accounts.export_account(principal=ALICE, country_id="us") + + +TYPE_CHANGED_AT = datetime(2026, 11, 1, tzinfo=UTC) + + +def _record_type_change( + store, + user_id, + previous_user_type: UserType, + new_user_type: UserType, + *, + changed_at: datetime, +): + with store.sessions.begin() as session: + change = UserTypeChange( + user_id=user_id, + previous_user_type=previous_user_type.value, + new_user_type=new_user_type.value, + source="admin_route", + created_at=changed_at, + ) + session.add(change) + session.flush() + return change.id + + +def test_the_account_carries_its_latest_type_change_until_it_is_dismissed( + store, +) -> None: + accounts, *_ = _services(store) + user_id = accounts.get_account(principal=ALICE, country_id="us").id + assert ( + accounts.get_account(principal=ALICE, country_id="us").latest_type_change + is None + ) + _record_type_change( + store, user_id, UserType.STANDARD, UserType.AUTHOR, changed_at=TYPE_CHANGED_AT + ) + latest_id = _record_type_change( + store, + user_id, + UserType.AUTHOR, + UserType.ADMIN, + changed_at=TYPE_CHANGED_AT + timedelta(days=1), + ) + + latest = accounts.get_account(principal=ALICE, country_id="us").latest_type_change + accounts.dismiss_type_change(principal=ALICE, type_change_id=latest_id) + after_dismissal = accounts.get_account(principal=ALICE, country_id="us") + # Dismissing again changes nothing. + accounts.dismiss_type_change(principal=ALICE, type_change_id=latest_id) + + assert latest is not None + assert (latest.id, latest.previous_user_type, latest.user_type) == ( + latest_id, + UserType.AUTHOR, + UserType.ADMIN, + ) + assert latest.changed_at.replace(tzinfo=UTC) == TYPE_CHANGED_AT + timedelta(days=1) + # An older change that wasn't dismissed doesn't come back. + assert after_dismissal.latest_type_change is None + with store.sessions() as session: + stored = session.get(UserTypeChange, latest_id) + assert stored is not None + assert stored.dismissed_at is not None + + +def test_only_the_users_own_type_change_is_dismissed(store) -> None: + accounts, *_ = _services(store) + accounts.get_account(principal=ALICE, country_id="us") + bob_id = accounts.get_account(principal=BOB, country_id="us").id + bobs_change = _record_type_change( + store, bob_id, UserType.STANDARD, UserType.AUTHOR, changed_at=TYPE_CHANGED_AT + ) + newcomer = UserPrincipal(issuer=ISSUER, subject="google-oauth2|newcomer") + + with pytest.raises(TypeChangeNotFoundError): + accounts.dismiss_type_change(principal=ALICE, type_change_id=bobs_change) + with pytest.raises(TypeChangeNotFoundError): + accounts.dismiss_type_change(principal=newcomer, type_change_id=bobs_change) + with pytest.raises(TypeChangeNotFoundError): + accounts.dismiss_type_change(principal=BOB, type_change_id=uuid4()) + + bob = accounts.get_account(principal=BOB, country_id="us") + assert bob.latest_type_change is not None + assert bob.latest_type_change.id == bobs_change + with store.sessions() as session: + # Dismissing never creates the caller's account. + assert ( + session.exec( + select(UserIdentity).where(UserIdentity.subject == newcomer.subject) + ).all() + == [] + ) + + +def test_other_account_reads_carry_no_type_change(store) -> None: + accounts, *_ = _services(store) + user_id = accounts.get_account(principal=ALICE, country_id="us").id + _record_type_change( + store, user_id, UserType.STANDARD, UserType.AUTHOR, changed_at=TYPE_CHANGED_AT + ) + + updated = accounts.update_account( + principal=ALICE, + country_id="us", + account_input=AccountUpdateInput(first_name="Alice"), + ) + + assert updated.latest_type_change is None diff --git a/tests/unit/v2/test_user_email_service.py b/tests/unit/v2/test_user_email_service.py new file mode 100644 index 000000000..7029b0547 --- /dev/null +++ b/tests/unit/v2/test_user_email_service.py @@ -0,0 +1,262 @@ +"""Tests for the invitation and type-change emails the Public API sends. + +The service fills Postmark's templates and records a WARNING, naming no +email address, whenever an email isn't sent. A stand-in sender plays +Postmark and a stand-in reader plays Auth0; the Postmark client itself is +tested in ``tests/unit/libs/test_postmark_email.py``. +""" + +from __future__ import annotations + +from datetime import UTC, datetime +from uuid import UUID + +import pytest + +from policyengine_api.data.v2.models import UserType +from policyengine_api.libs.auth0_management import Auth0UserProfilesUnavailableError +from policyengine_api.libs.postmark_email import EmailSendError +from policyengine_api.services.v2.user_emails import services as email_services +from policyengine_api.services.v2.user_emails.services import V2UserEmailService +from policyengine_api.services.v2.user_emails.types import ( + InvitationEmail, + SignInIdentity, + UserTypeChangeEmail, +) +from tests.unit.v2.user_email_support import ( + APP_URL, + RecordingEmailSender, + StandInProfileReader, + auth0_profile, + profile_source, + recorded_logs, + warnings_named, +) + +ISSUER = "https://auth.example.test/" +OTHER_ISSUER = "https://other.example.test/" +USER_ID = UUID("00000000-0000-0000-0000-0000000000a1") +INVITATION_ID = UUID("00000000-0000-0000-0000-0000000000b1") +TOKEN = "x" * 43 +INVITATION = InvitationEmail( + invitation_id=INVITATION_ID, + email="Ada@Example.org", + user_type=UserType.AUTHOR, + expires_at=datetime(2026, 11, 19, 14, 5, 59, tzinfo=UTC), + token=TOKEN, +) +PROMOTION = UserTypeChangeEmail( + user_id=USER_ID, + previous_user_type=UserType.STANDARD, + user_type=UserType.ADMIN, + identities=( + SignInIdentity(issuer=OTHER_ISSUER, subject="other|ada"), + SignInIdentity(issuer=ISSUER, subject="auth0|ada-new"), + SignInIdentity(issuer=ISSUER, subject="google-oauth2|ada"), + ), +) + + +def _service( + sender: RecordingEmailSender | None, + reader: StandInProfileReader | None = None, +) -> V2UserEmailService: + return V2UserEmailService( + email_sender_factory=lambda: sender, + user_profile_source_factory=( + (lambda: None) + if reader is None + else (lambda: profile_source(ISSUER, reader)) + ), + ) + + +def test_an_invitation_email_links_to_the_accept_page_with_its_token() -> None: + sender = RecordingEmailSender() + + failure = _service(sender).send_invitation(INVITATION) + + assert failure is None + assert sender.sent == [ + { + "to": "Ada@Example.org", + "template_alias": "user-invitation", + "template_model": { + "user_type": "author", + "accept_url": f"{APP_URL}/invitations/accept#token={TOKEN}", + "expires_at": "19 November 2026, 14:05 UTC", + "app_url": APP_URL, + }, + } + ] + assert TOKEN not in repr(INVITATION) + + +@pytest.mark.parametrize( + ("sender", "failure"), + [ + (None, "not_configured"), + (RecordingEmailSender(EmailSendError("postmark_406")), "postmark_406"), + (RecordingEmailSender(RuntimeError("Ada@Example.org")), "unexpected_error"), + ], +) +def test_an_unsent_invitation_names_its_failure_and_records_a_warning( + sender: RecordingEmailSender | None, failure: str +) -> None: + with recorded_logs(email_services.logger) as records: + named_failure = _service(sender).send_invitation(INVITATION) + + assert named_failure == failure + assert warnings_named(records, "user_invitation_email_not_sent") == [ + {"invitation_id": str(INVITATION_ID), "cause": failure} + ] + assert all("Ada@Example.org" not in record.getMessage() for record in records) + + +def test_an_unusable_sender_setting_counts_as_not_configured() -> None: + def refuse() -> RecordingEmailSender: + msg = "POSTMARK_SENDER_ADDRESS must be an email address" + raise ValueError(msg) + + service = V2UserEmailService( + email_sender_factory=refuse, user_profile_source_factory=lambda: None + ) + + with recorded_logs(email_services.logger) as records: + assert service.send_invitation(INVITATION) == "not_configured" + + assert warnings_named(records, "user_invitation_email_not_sent") == [ + {"invitation_id": str(INVITATION_ID), "cause": "invalid_settings"} + ] + + +def test_a_type_change_email_goes_to_the_first_verified_auth0_email() -> None: + sender = RecordingEmailSender() + reader = StandInProfileReader( + [ + auth0_profile("auth0|ada-new", "new@example.org", verified=False), + auth0_profile("google-oauth2|ada", "ada@example.org"), + ] + ) + + failure = _service(sender, reader).send_type_change(PROMOTION) + + assert failure is None + # Only identities from the users' issuer are Auth0 users, read together. + assert reader.profile_reads == [("auth0|ada-new", "google-oauth2|ada")] + assert sender.sent == [ + { + "to": "ada@example.org", + "template_alias": "user-type-changed", + "template_model": { + "previous_user_type": "standard", + "user_type": "admin", + "promoted": True, + "app_url": APP_URL, + }, + } + ] + + +def test_a_demotion_email_says_it_is_not_a_promotion() -> None: + sender = RecordingEmailSender() + demotion = UserTypeChangeEmail( + user_id=USER_ID, + previous_user_type=UserType.ADMIN, + user_type=UserType.AUTHOR, + identities=(), + ) + + failure = _service(sender).send_type_change( + demotion, verified_email="ada@example.org" + ) + + assert failure is None + assert sender.sent[0]["template_model"] == { + "previous_user_type": "admin", + "user_type": "author", + "promoted": False, + "app_url": APP_URL, + } + + +def test_a_known_verified_email_needs_no_auth0_read() -> None: + sender = RecordingEmailSender() + reader = StandInProfileReader() + + _service(sender, reader).send_type_change( + PROMOTION, verified_email="ada@example.org" + ) + + assert reader.profile_reads == [] + assert sender.sent[0]["to"] == "ada@example.org" + + +@pytest.mark.parametrize( + ("sender", "reader", "failure"), + [ + (None, StandInProfileReader(), "not_configured"), + (RecordingEmailSender(), None, "no_user_profiles"), + ( + RecordingEmailSender(), + StandInProfileReader( + failure=Auth0UserProfilesUnavailableError("timeout", cause="timeout") + ), + "profiles_unavailable", + ), + ( + RecordingEmailSender(), + StandInProfileReader( + [auth0_profile("google-oauth2|ada", "ada@example.org", verified=False)] + ), + "no_verified_email", + ), + (RecordingEmailSender(), StandInProfileReader(), "no_verified_email"), + ( + RecordingEmailSender(EmailSendError("timeout")), + StandInProfileReader( + [auth0_profile("google-oauth2|ada", "ada@example.org")] + ), + "timeout", + ), + ], +) +def test_an_unsent_type_change_email_records_a_warning_with_the_user_id_only( + sender: RecordingEmailSender | None, + reader: StandInProfileReader | None, + failure: str, +) -> None: + with recorded_logs(email_services.logger) as records: + named_failure = _service(sender, reader).send_type_change(PROMOTION) + + assert named_failure == failure + assert warnings_named(records, "user_type_change_email_not_sent") == [ + {"user_id": str(USER_ID), "cause": failure} + ] + if sender is not None: + assert sender.sent == [] + + +def test_nothing_is_read_from_auth0_when_no_email_can_be_sent() -> None: + reader = StandInProfileReader( + [auth0_profile("google-oauth2|ada", "ada@example.org")] + ) + + assert _service(None, reader).send_type_change(PROMOTION) == "not_configured" + + assert reader.profile_reads == [] + + +def test_a_user_with_no_identity_from_the_users_issuer_reads_nothing() -> None: + reader = StandInProfileReader() + change = UserTypeChangeEmail( + user_id=USER_ID, + previous_user_type=UserType.STANDARD, + user_type=UserType.AUTHOR, + identities=(SignInIdentity(issuer=OTHER_ISSUER, subject="other|ada"),), + ) + + failure = _service(RecordingEmailSender(), reader).send_type_change(change) + + assert failure == "no_verified_email" + assert reader.profile_reads == [] diff --git a/tests/unit/v2/test_user_invitation_service.py b/tests/unit/v2/test_user_invitation_service.py new file mode 100644 index 000000000..5fc58a44e --- /dev/null +++ b/tests/unit/v2/test_user_invitation_service.py @@ -0,0 +1,651 @@ +"""Service tests for admins' email invitations and their acceptance. + +An admin invites an email address to become an author or admin; the signed-in +invitee accepts with the token from the email once Auth0 reports their +verified email matching the address. Stand-ins play Postmark and Auth0. +""" + +from __future__ import annotations + +import hashlib +from datetime import UTC, datetime, timedelta +from typing import TYPE_CHECKING + +import pytest +from sqlmodel import select + +from policyengine_api.data.v2.models import ( + User, + UserInvitation, + UserType, + UserTypeChange, +) +from policyengine_api.libs.auth0_management import Auth0UserProfilesUnavailableError +from policyengine_api.libs.postmark_email import EmailSendError +from policyengine_api.services.v2.identity.types import UserPrincipal +from policyengine_api.services.v2.user_accounts.database_session import ( + AccountDatabaseSession, +) +from policyengine_api.services.v2.user_accounts.services import V2AccountService +from policyengine_api.services.v2.user_emails.services import V2UserEmailService +from policyengine_api.services.v2.user_invitations.database_session import ( + UserInvitationDatabaseSession, +) +from policyengine_api.services.v2.user_invitations.services import ( + V2UserInvitationService, +) +from policyengine_api.services.v2.user_invitations.types import ( + AdminInvitationSearch, + InvitationAcceptance, +) +from policyengine_api.services.v2.user_invitations.validators import ( + InvitationAcceptedError, + InvitationEmailMismatchError, + InvitationEmailNotVerifiedError, + InvitationEmailUnavailableError, + InvitationExpiredError, + InvitationNotFoundError, + InvitationRevokedError, + InvitationTokenNotFoundError, + InviterNotAdminError, +) +from policyengine_api.services.v2.user_types.validators import ( + UserTypeBelowMinimumError, +) +from tests.unit.v2.user_email_support import ( + APP_URL, + RecordingEmailSender, + StandInProfileReader, + auth0_profile, + profile_source, +) +from tests.unit.v2.user_service_support import ALICE, BOB, ISSUER, V2Store, v2_store + +if TYPE_CHECKING: + from collections.abc import Iterator + from uuid import UUID + +NOW = datetime(2026, 11, 12, 14, 5, tzinfo=UTC) +CAROL = UserPrincipal(issuer=ISSUER, subject="google-oauth2|carol") +BOB_EMAIL = "bob@example.test" + + +def _never_build_the_auth0_deleter(): + msg = "these tests delete no account" + raise AssertionError(msg) + + +def _hash(token: str) -> str: + return hashlib.sha256(token.encode()).hexdigest() + + +class Invitations: + """A store, the invitation service on it, and the stand-ins it uses.""" + + def __init__(self, store: V2Store) -> None: + self.store = store + self.sender = RecordingEmailSender() + self.reader = StandInProfileReader( + [auth0_profile(BOB.subject, BOB_EMAIL), auth0_profile(CAROL.subject, None)] + ) + self.profiles_configured = True + self.now = NOW + self._token_number = 0 + + def _token(self) -> str: + self._token_number += 1 + return f"token-{self._token_number:02d}-" + "x" * 34 + + def service(self) -> V2UserInvitationService: + def source(): + if not self.profiles_configured: + return None + return profile_source(ISSUER, self.reader) + + return V2UserInvitationService( + UserInvitationDatabaseSession(self.store.sessions), + user_email_service=V2UserEmailService( + email_sender_factory=lambda: self.sender, + user_profile_source_factory=source, + ), + user_profile_source_factory=source, + clock=lambda: self.now, + token_factory=self._token, + ) + + def sign_in(self, principal: UserPrincipal, user_type: UserType) -> UUID: + accounts = V2AccountService( + AccountDatabaseSession(self.store.sessions), + auth0_user_deleter_factory=_never_build_the_auth0_deleter, + ) + user_id = accounts.get_account(principal=principal, country_id="us").id + with self.store.sessions.begin() as session: + user = session.get(User, user_id) + assert user is not None + user.user_type = user_type.value + return user_id + + def stored_type(self, user_id: UUID) -> UserType: + with self.store.sessions() as session: + user = session.get(User, user_id) + assert user is not None + return UserType(user.user_type) + + def invitations(self) -> list[UserInvitation]: + with self.store.sessions() as session: + return list(session.exec(select(UserInvitation)).all()) + + def changes(self) -> list[UserTypeChange]: + with self.store.sessions() as session: + return list(session.exec(select(UserTypeChange)).all()) + + def sent_tokens(self) -> list[str]: + return [ + email["template_model"]["accept_url"].split("#token=", 1)[1] + for email in self.sender.sent + if email["template_alias"] == "user-invitation" + ] + + +@pytest.fixture +def invitations() -> Iterator[Invitations]: + with v2_store() as store: + yield Invitations(store) + + +def _invite( + invitations: Invitations, + email: str = BOB_EMAIL, + user_type: UserType = UserType.AUTHOR, +): + return invitations.service().create_invitation( + principal=ALICE, email=email, user_type=user_type + ) + + +def _accept(invitations: Invitations, token: str, principal: UserPrincipal = BOB): + return invitations.service().accept_invitation( + principal=principal, token=token, country_id="uk" + ) + + +def test_an_admin_invites_an_address_and_only_the_tokens_hash_is_stored( + invitations: Invitations, +) -> None: + admin_id = invitations.sign_in(ALICE, UserType.ADMIN) + + read = _invite(invitations, email="Bob@Example.test", user_type=UserType.ADMIN) + + (stored,) = invitations.invitations() + (token,) = invitations.sent_tokens() + assert stored.token_hash == _hash(token) + assert token not in repr(stored.model_dump()) + assert read.id == stored.id + assert read.email == "Bob@Example.test" + assert read.user_type is UserType.ADMIN + assert read.invited_by_user_id == admin_id + assert read.expires_at == NOW + timedelta(days=7) + assert read.expired is False + assert read.last_sent_at == NOW + assert read.last_send_error is None + assert invitations.sender.sent == [ + { + "to": "Bob@Example.test", + "template_alias": "user-invitation", + "template_model": { + "user_type": "admin", + "accept_url": f"{APP_URL}/invitations/accept#token={token}", + "expires_at": "19 November 2026, 14:05 UTC", + "app_url": APP_URL, + }, + } + ] + + +@pytest.mark.parametrize("caller_type", [UserType.STANDARD, UserType.AUTHOR]) +def test_only_admins_invite(invitations: Invitations, caller_type: UserType) -> None: + invitations.sign_in(ALICE, caller_type) + + with pytest.raises(UserTypeBelowMinimumError): + _invite(invitations) + + assert invitations.invitations() == [] + assert invitations.sender.sent == [] + + +def test_inviting_an_address_again_revokes_its_open_invitation( + invitations: Invitations, +) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + invitations.sign_in(BOB, UserType.STANDARD) + first = _invite(invitations, email="BOB@example.test") + invitations.now = NOW + timedelta(hours=1) + + second = _invite(invitations, user_type=UserType.ADMIN) + + stored = {invitation.id: invitation for invitation in invitations.invitations()} + assert stored[first.id].revoked_at is not None + assert stored[second.id].revoked_at is None + first_token, _second_token = invitations.sent_tokens() + with pytest.raises(InvitationRevokedError): + _accept(invitations, first_token) + + +def test_a_failed_send_keeps_the_invitation_with_its_failure( + invitations: Invitations, +) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + invitations.sender.failure = EmailSendError("postmark_406") + + read = _invite(invitations) + + assert read.last_sent_at is None + assert read.last_send_error == "postmark_406" + (stored,) = invitations.invitations() + assert stored.last_send_error == "postmark_406" + assert stored.revoked_at is None + + +def test_without_postmark_the_invitation_is_kept_as_not_sent( + invitations: Invitations, +) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + invitations.sender = None # type: ignore[assignment] # no Postmark settings + + read = _invite(invitations) + + assert read.last_send_error == "not_configured" + assert read.last_sent_at is None + + +def test_admins_list_open_invitations_newest_first_with_expired_ones( + invitations: Invitations, +) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + oldest = _invite(invitations, email="old@example.test") + invitations.now = NOW + timedelta(days=1) + revoked = _invite(invitations, email="revoked@example.test") + invitations.service().revoke_invitation(principal=ALICE, invitation_id=revoked.id) + invitations.now = NOW + timedelta(days=2) + newest = _invite(invitations, email="new@example.test") + invitations.now = NOW + timedelta(days=7, seconds=1) + + first_page = invitations.service().list_invitations( + principal=ALICE, search=AdminInvitationSearch(offset=0, limit=1) + ) + second_page = invitations.service().list_invitations( + principal=ALICE, search=AdminInvitationSearch(offset=1, limit=1) + ) + + assert [item.id for item in first_page.items] == [newest.id] + assert first_page.has_more is True + assert first_page.items[0].expired is False + assert [item.id for item in second_page.items] == [oldest.id] + assert second_page.has_more is False + assert second_page.items[0].expired is True + + +def test_accepted_invitations_are_not_listed(invitations: Invitations) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + _invite(invitations) + (token,) = invitations.sent_tokens() + _accept(invitations, token) + + page = invitations.service().list_invitations( + principal=ALICE, search=AdminInvitationSearch() + ) + + assert page.items == () + + +def test_only_admins_list_resend_or_revoke(invitations: Invitations) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + invitations.sign_in(BOB, UserType.AUTHOR) + invitation = _invite(invitations) + service = invitations.service() + + with pytest.raises(UserTypeBelowMinimumError): + service.list_invitations(principal=BOB, search=AdminInvitationSearch()) + with pytest.raises(UserTypeBelowMinimumError): + service.resend_invitation(principal=BOB, invitation_id=invitation.id) + with pytest.raises(UserTypeBelowMinimumError): + service.revoke_invitation(principal=BOB, invitation_id=invitation.id) + + (stored,) = invitations.invitations() + assert stored.revoked_at is None + assert len(invitations.sender.sent) == 1 + + +def test_resending_replaces_the_token_and_expiry_and_names_the_resender( + invitations: Invitations, +) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + carol_id = invitations.sign_in(CAROL, UserType.ADMIN) + invitations.sign_in(BOB, UserType.STANDARD) + invitations.sender.failure = EmailSendError("timeout") + invitation = _invite(invitations) + invitations.sender.failure = None + invitations.now = NOW + timedelta(days=8) + + resent = invitations.service().resend_invitation( + principal=CAROL, invitation_id=invitation.id + ) + + assert resent.id == invitation.id + assert resent.invited_by_user_id == carol_id + assert resent.expires_at == NOW + timedelta(days=15) + assert resent.expired is False + assert resent.last_sent_at == NOW + timedelta(days=8) + assert resent.last_send_error is None + (token,) = invitations.sent_tokens() + (stored,) = invitations.invitations() + assert stored.token_hash == _hash(token) + assert _accept(invitations, token).type_changed is True + + +def test_a_resent_invitations_earlier_link_no_longer_works( + invitations: Invitations, +) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + invitations.sign_in(BOB, UserType.STANDARD) + invitation = _invite(invitations) + invitations.service().resend_invitation( + principal=ALICE, invitation_id=invitation.id + ) + earlier_token, _later_token = invitations.sent_tokens() + + with pytest.raises(InvitationTokenNotFoundError): + _accept(invitations, earlier_token) + + +def test_revoking_closes_the_invitation_and_its_link(invitations: Invitations) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + invitations.sign_in(BOB, UserType.STANDARD) + invitation = _invite(invitations) + service = invitations.service() + + service.revoke_invitation(principal=ALICE, invitation_id=invitation.id) + + (stored,) = invitations.invitations() + assert stored.revoked_at is not None + (token,) = invitations.sent_tokens() + with pytest.raises(InvitationRevokedError): + _accept(invitations, token) + with pytest.raises(InvitationNotFoundError): + service.revoke_invitation(principal=ALICE, invitation_id=invitation.id) + with pytest.raises(InvitationNotFoundError): + service.resend_invitation(principal=ALICE, invitation_id=invitation.id) + + +def test_an_accepted_invitation_is_neither_resent_nor_revoked( + invitations: Invitations, +) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + invitation = _invite(invitations) + (token,) = invitations.sent_tokens() + _accept(invitations, token) + service = invitations.service() + + with pytest.raises(InvitationNotFoundError): + service.resend_invitation(principal=ALICE, invitation_id=invitation.id) + with pytest.raises(InvitationNotFoundError): + service.revoke_invitation(principal=ALICE, invitation_id=invitation.id) + + +def test_accepting_gives_the_invited_type_and_emails_the_user( + invitations: Invitations, +) -> None: + admin_id = invitations.sign_in(ALICE, UserType.ADMIN) + bob_id = invitations.sign_in(BOB, UserType.STANDARD) + invitation = _invite(invitations, email="BOB@EXAMPLE.TEST") + (token,) = invitations.sent_tokens() + invitations.now = NOW + timedelta(days=1) + + acceptance = _accept(invitations, token) + + assert acceptance == InvitationAcceptance( + user_type=UserType.AUTHOR, + previous_user_type=UserType.STANDARD, + type_changed=True, + ) + assert invitations.stored_type(bob_id) is UserType.AUTHOR + (stored,) = invitations.invitations() + assert stored.id == invitation.id + assert stored.accepted_by_user_id == bob_id + assert stored.accepted_at is not None + (change,) = invitations.changes() + assert change.user_id == bob_id + assert change.changed_by_user_id == admin_id + assert (change.previous_user_type, change.new_user_type, change.source) == ( + "standard", + "author", + "invitation", + ) + # Auth0's verified email was read once, before the change, and the + # type-change email goes there after the commit. + assert invitations.reader.profile_reads == [(BOB.subject,)] + assert invitations.sender.sent[-1] == { + "to": BOB_EMAIL, + "template_alias": "user-type-changed", + "template_model": { + "previous_user_type": "standard", + "user_type": "author", + "promoted": True, + "app_url": APP_URL, + }, + } + + +def test_accepting_creates_a_new_users_account_first(invitations: Invitations) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + _invite(invitations, user_type=UserType.ADMIN) + (token,) = invitations.sent_tokens() + + acceptance = _accept(invitations, token) + + assert acceptance.type_changed is True + assert acceptance.user_type is UserType.ADMIN + with invitations.store.sessions() as session: + (bob,) = [ + user + for user in session.exec(select(User)).all() + if user.user_type == "admin" and user.primary_country == "uk" + ] + assert bob is not None + + +@pytest.mark.parametrize("stored_type", [UserType.AUTHOR, UserType.ADMIN]) +def test_an_invitation_never_lowers_or_repeats_a_type( + invitations: Invitations, stored_type: UserType +) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + bob_id = invitations.sign_in(BOB, stored_type) + _invite(invitations, user_type=UserType.AUTHOR) + (token,) = invitations.sent_tokens() + + acceptance = _accept(invitations, token) + + assert acceptance == InvitationAcceptance( + user_type=stored_type, previous_user_type=stored_type, type_changed=False + ) + assert invitations.stored_type(bob_id) is stored_type + (stored,) = invitations.invitations() + assert stored.accepted_by_user_id == bob_id + assert invitations.changes() == [] + assert [email["template_alias"] for email in invitations.sender.sent] == [ + "user-invitation" + ] + + +def _assert_still_open(invitations: Invitations, bob_id: UUID) -> None: + (stored,) = invitations.invitations() + assert stored.accepted_at is None + assert stored.revoked_at is None + assert invitations.stored_type(bob_id) is UserType.STANDARD + assert invitations.changes() == [] + + +def test_auth0_is_read_before_the_token_is_checked(invitations: Invitations) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + bob_id = invitations.sign_in(BOB, UserType.STANDARD) + _invite(invitations) + invitations.reader.failure = Auth0UserProfilesUnavailableError( + "unavailable", cause="http_503" + ) + + with pytest.raises(InvitationEmailUnavailableError): + _accept(invitations, "not-a-token") + + _assert_still_open(invitations, bob_id) + + +def test_without_auth0_profile_settings_no_invitation_is_accepted( + invitations: Invitations, +) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + bob_id = invitations.sign_in(BOB, UserType.STANDARD) + _invite(invitations) + (token,) = invitations.sent_tokens() + invitations.profiles_configured = False + + with pytest.raises(InvitationEmailUnavailableError): + _accept(invitations, token) + + _assert_still_open(invitations, bob_id) + + +def test_an_unknown_token_is_not_found(invitations: Invitations) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + bob_id = invitations.sign_in(BOB, UserType.STANDARD) + _invite(invitations) + + with pytest.raises(InvitationTokenNotFoundError): + _accept(invitations, "token-99-" + "x" * 34) + + _assert_still_open(invitations, bob_id) + + +def test_an_expired_invitation_is_refused(invitations: Invitations) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + bob_id = invitations.sign_in(BOB, UserType.STANDARD) + _invite(invitations) + (token,) = invitations.sent_tokens() + invitations.now = NOW + timedelta(days=7) + + with pytest.raises(InvitationExpiredError): + _accept(invitations, token) + + _assert_still_open(invitations, bob_id) + + +def test_an_accepted_invitation_is_refused_the_second_time( + invitations: Invitations, +) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + invitations.sign_in(BOB, UserType.STANDARD) + _invite(invitations) + (token,) = invitations.sent_tokens() + _accept(invitations, token) + + with pytest.raises(InvitationAcceptedError): + _accept(invitations, token) + + assert len(invitations.changes()) == 1 + + +def test_an_invitation_from_a_former_admin_is_refused(invitations: Invitations) -> None: + alice_id = invitations.sign_in(ALICE, UserType.ADMIN) + invitations.sign_in(CAROL, UserType.ADMIN) + bob_id = invitations.sign_in(BOB, UserType.STANDARD) + _invite(invitations) + (token,) = invitations.sent_tokens() + with invitations.store.sessions.begin() as session: + alice = session.get(User, alice_id) + assert alice is not None + alice.user_type = UserType.AUTHOR.value + + with pytest.raises(InviterNotAdminError): + _accept(invitations, token) + + _assert_still_open(invitations, bob_id) + + +def test_an_unverified_email_is_refused_until_auth0_verifies_it( + invitations: Invitations, +) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + bob_id = invitations.sign_in(BOB, UserType.STANDARD) + _invite(invitations) + (token,) = invitations.sent_tokens() + invitations.reader.profiles[BOB.subject] = auth0_profile( + BOB.subject, BOB_EMAIL, verified=False + ) + + with pytest.raises(InvitationEmailNotVerifiedError): + _accept(invitations, token) + + _assert_still_open(invitations, bob_id) + invitations.reader.profiles[BOB.subject] = auth0_profile(BOB.subject, BOB_EMAIL) + assert _accept(invitations, token).type_changed is True + + +def test_a_user_auth0_doesnt_know_has_no_verified_email( + invitations: Invitations, +) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + bob_id = invitations.sign_in(BOB, UserType.STANDARD) + _invite(invitations) + (token,) = invitations.sent_tokens() + del invitations.reader.profiles[BOB.subject] + + with pytest.raises(InvitationEmailNotVerifiedError): + _accept(invitations, token) + + _assert_still_open(invitations, bob_id) + + +def test_another_verified_email_is_refused_and_the_invitation_stays_open( + invitations: Invitations, +) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + bob_id = invitations.sign_in(BOB, UserType.STANDARD) + _invite(invitations, email="bobby@example.test") + (token,) = invitations.sent_tokens() + + with pytest.raises(InvitationEmailMismatchError): + _accept(invitations, token) + + _assert_still_open(invitations, bob_id) + + +def test_the_token_is_checked_before_the_inviter_and_the_email( + invitations: Invitations, +) -> None: + alice_id = invitations.sign_in(ALICE, UserType.ADMIN) + invitations.sign_in(CAROL, UserType.ADMIN) + invitations.sign_in(BOB, UserType.STANDARD) + _invite(invitations, email="bobby@example.test") + (token,) = invitations.sent_tokens() + invitations.reader.profiles[BOB.subject] = auth0_profile( + BOB.subject, BOB_EMAIL, verified=False + ) + with invitations.store.sessions.begin() as session: + alice = session.get(User, alice_id) + assert alice is not None + alice.user_type = UserType.STANDARD.value + invitations.now = NOW + timedelta(days=8) + + with pytest.raises(InvitationExpiredError): + _accept(invitations, token) + invitations.now = NOW + with pytest.raises(InviterNotAdminError): + _accept(invitations, token) + with invitations.store.sessions.begin() as session: + alice = session.get(User, alice_id) + assert alice is not None + alice.user_type = UserType.ADMIN.value + with pytest.raises(InvitationEmailNotVerifiedError): + _accept(invitations, token) + invitations.reader.profiles[BOB.subject] = auth0_profile(BOB.subject, BOB_EMAIL) + with pytest.raises(InvitationEmailMismatchError): + _accept(invitations, token) diff --git a/tests/unit/v2/test_user_type_service.py b/tests/unit/v2/test_user_type_service.py index 76ddb983b..e0c0e449f 100644 --- a/tests/unit/v2/test_user_type_service.py +++ b/tests/unit/v2/test_user_type_service.py @@ -15,11 +15,13 @@ UserTypeChange, UserTypeChangeSource, ) +from policyengine_api.libs.postmark_email import EmailSendError from policyengine_api.services.v2.identity.types import UserPrincipal from policyengine_api.services.v2.user_accounts.database_session import ( AccountDatabaseSession, ) from policyengine_api.services.v2.user_accounts.services import V2AccountService +from policyengine_api.services.v2.user_emails.services import V2UserEmailService from policyengine_api.services.v2.user_policies.database_session import ( UserPolicyDatabaseSession, ) @@ -38,6 +40,13 @@ UserTypeBelowMinimumError, UserTypeChangedError, ) +from tests.unit.v2.user_email_support import ( + APP_URL, + RecordingEmailSender, + StandInProfileReader, + auth0_profile, + profile_source, +) from tests.unit.v2.user_service_support import ( ALICE, BOB, @@ -504,3 +513,112 @@ def test_a_change_is_refused_once_the_type_differs_from_the_expected_one( (change.changed_by_user_id, change.new_user_type) for change in _history_rows(store) ] == [(alice_id, "author")] + + +def _emailing_user_types( + store: V2Store, sender: RecordingEmailSender, reader: StandInProfileReader +) -> V2UserTypeService: + return V2UserTypeService( + UserTypeDatabaseSession(store.sessions), + user_email_service=V2UserEmailService( + email_sender_factory=lambda: sender, + user_profile_source_factory=lambda: profile_source(ISSUER, reader), + ), + ) + + +def test_an_admins_change_emails_the_user_at_their_auth0_email( + store: V2Store, +) -> None: + _signed_in_admin(store, ALICE) + bob_id = _sign_in(store, BOB) + sender = RecordingEmailSender() + reader = StandInProfileReader([auth0_profile(BOB.subject, "bob@auth0.test")]) + user_types = _emailing_user_types(store, sender, reader) + + user_types.change_user_type( + principal=ALICE, + user_id=bob_id, + user_type=UserType.AUTHOR, + expected_user_type=UserType.STANDARD, + ) + user_types.change_user_type( + principal=ALICE, + user_id=bob_id, + user_type=UserType.AUTHOR, + expected_user_type=UserType.AUTHOR, + ) + + # Setting the type the user already has emails nobody. + assert sender.sent == [ + { + "to": "bob@auth0.test", + "template_alias": "user-type-changed", + "template_model": { + "previous_user_type": "standard", + "user_type": "author", + "promoted": True, + "app_url": APP_URL, + }, + } + ] + + +def test_a_refused_change_emails_nobody(store: V2Store) -> None: + alice_id = _signed_in_admin(store, ALICE) + sender = RecordingEmailSender() + reader = StandInProfileReader([auth0_profile(ALICE.subject, "alice@auth0.test")]) + user_types = _emailing_user_types(store, sender, reader) + + with pytest.raises(LastAdminDemotionError): + user_types.change_user_type( + principal=ALICE, + user_id=alice_id, + user_type=UserType.AUTHOR, + expected_user_type=UserType.ADMIN, + ) + + assert sender.sent == [] + + +def test_the_scripts_change_emails_the_user(store: V2Store) -> None: + _signed_in_admin(store, ALICE) + _sign_in(store, BOB_WITH_EMAIL) + sender = RecordingEmailSender() + reader = StandInProfileReader([auth0_profile(BOB.subject, "bob@auth0.test")]) + user_types = _emailing_user_types(store, sender, reader) + + user_types.set_user_type_by_email( + email="bob@example.test", user_type=UserType.ADMIN + ) + + assert [(email["to"], email["template_model"]) for email in sender.sent] == [ + ( + "bob@auth0.test", + { + "previous_user_type": "standard", + "user_type": "admin", + "promoted": True, + "app_url": APP_URL, + }, + ) + ] + + +def test_an_unsent_type_change_email_leaves_the_change_committed( + store: V2Store, +) -> None: + _signed_in_admin(store, ALICE) + bob_id = _sign_in(store, BOB) + sender = RecordingEmailSender(EmailSendError("http_500")) + reader = StandInProfileReader([auth0_profile(BOB.subject, "bob@auth0.test")]) + + changed = _emailing_user_types(store, sender, reader).change_user_type( + principal=ALICE, + user_id=bob_id, + user_type=UserType.AUTHOR, + expected_user_type=UserType.STANDARD, + ) + + assert changed.user_type is UserType.AUTHOR + assert _stored_type(store, bob_id) == "author" diff --git a/tests/unit/v2/user_email_support.py b/tests/unit/v2/user_email_support.py new file mode 100644 index 000000000..c1213c274 --- /dev/null +++ b/tests/unit/v2/user_email_support.py @@ -0,0 +1,136 @@ +"""Stand-ins for Postmark and Auth0 in invitation and type-change email tests.""" + +from __future__ import annotations + +import logging +from contextlib import contextmanager +from typing import TYPE_CHECKING, Any + +from policyengine_api.libs.auth0_management import Auth0UserProfile + +if TYPE_CHECKING: + from collections.abc import Iterable, Iterator, Mapping + + from policyengine_api.libs.rate_limit_wait_budget import RateLimitWaitBudget + from policyengine_api.services.v2.user_types.types import UserProfileSource + +APP_URL = "https://app.example.test" + + +class RecordingEmailSender: + """Record each template email; raise ``failure`` instead when it is set.""" + + app_url = APP_URL + + def __init__(self, failure: Exception | None = None) -> None: + self.failure = failure + self.sent: list[dict[str, Any]] = [] + + def send_template( + self, + *, + to: str, + template_alias: str, + template_model: Mapping[str, object], + ) -> None: + if self.failure is not None: + raise self.failure + self.sent.append( + { + "to": to, + "template_alias": template_alias, + "template_model": dict(template_model), + } + ) + + +class StandInProfileReader: + """Answer Auth0 profile reads from ``profiles``, or raise ``failure``.""" + + def __init__( + self, + profiles: Iterable[Auth0UserProfile] = (), + *, + failure: Exception | None = None, + ) -> None: + self.profiles = {profile.user_id: profile for profile in profiles} + self.failure = failure + self.profile_reads: list[tuple[str, ...]] = [] + + def read_user_profiles( + self, + user_ids: Iterable[str], + *, + wait_budget: RateLimitWaitBudget | None = None, + ) -> dict[str, Auth0UserProfile]: + del wait_budget + requested = tuple(user_ids) + self.profile_reads.append(requested) + if self.failure is not None: + raise self.failure + return { + user_id: self.profiles[user_id] + for user_id in requested + if user_id in self.profiles + } + + def search_user_ids_by_email(self, *_args: object, **_kwargs: object) -> object: + msg = "invitations and type-change emails never search by email" + raise AssertionError(msg) + + +def auth0_profile( + subject: str, email: str | None, *, verified: bool = True +) -> Auth0UserProfile: + """Build the Auth0 profile of ``subject`` with ``email``.""" + return Auth0UserProfile( + user_id=subject, + email=email, + email_verified=verified, + given_name=None, + family_name=None, + name=None, + ) + + +def profile_source(issuer: str, reader: StandInProfileReader) -> UserProfileSource: + """Return the users' Auth0 tenant as ``reader`` plays it.""" + from policyengine_api.services.v2.user_types.types import UserProfileSource + + return UserProfileSource(issuer=issuer, reader=reader) + + +def warnings_named(records: Iterable[Any], event: str) -> list[dict[str, Any]]: + """Return the attributes of each WARNING record named ``event``.""" + return [ + record.policyengine_attributes + for record in records + if record.getMessage() == event and record.levelname == "WARNING" + ] + + +@contextmanager +def recorded_logs(logger: logging.Logger) -> Iterator[list[logging.LogRecord]]: + """Record ``logger``'s records, even after a test disabled it. + + Alembic's tests configure logging from a file, which disables loggers + that already exist, so the logger is enabled here and records are taken + from it directly. + """ + records: list[logging.LogRecord] = [] + + class RecordingHandler(logging.Handler): + def emit(self, record: logging.LogRecord) -> None: + records.append(record) + + handler = RecordingHandler(level=logging.INFO) + previous_disabled, previous_level = logger.disabled, logger.level + logger.disabled = False + logger.setLevel(logging.INFO) + logger.addHandler(handler) + try: + yield records + finally: + logger.removeHandler(handler) + logger.disabled = previous_disabled + logger.setLevel(previous_level) From 5a9bdd9b6c84d56f17951894fac734211691ae7c Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:39:07 +0400 Subject: [PATCH 2/6] Read the invitee by Auth0 user ID and tidy review findings - Acceptance reads the invitee's Auth0 profile with GET /api/v2/users/{id}, which Auth0 answers at once, instead of the eventually consistent user search, so a user who signed up or verified their email moments ago is not refused as unverified. - The Auth0 settings code moves unchanged to auth0_management_settings, which auth0_management re-exports, keeping that module under 800 lines; mypy and its rule now also cover that module and the Postmark library. - Deleting an account deletes the invitations it accepted (CASCADE), whose address was the user's; the revision is regenerated as f519a77ba122. - The acceptance route documents both error shapes for 409 and 503. - The type script says whether it emailed the user, and why not. - Tests for a send whose invitation a resend replaced or that is gone, and docs and docstrings brought in line. Co-Authored-By: Claude Opus 5.5 --- docs/engineering/skills/alembic-migrations.md | 11 +- docs/generated/rules.md | 2 +- docs/migration/stage-12a-user-login.md | 13 +- docs/migration/stage-9-v2-metadata.md | 5 +- ..._invite_users_and_dismiss_type_changes.py} | 13 +- policyengine_api/data/v2/migration_target.py | 2 +- policyengine_api/data/v2/models/users.py | 11 +- .../v2/admin_users/response_models.py | 10 +- .../fastapi_routes/v2/me/user_type_routes.py | 9 +- policyengine_api/libs/auth0_management.py | 295 +++++++++--------- .../libs/auth0_management_settings.py | 160 ++++++++++ .../services/v2/user_invitations/services.py | 18 +- .../services/v2/user_types/services.py | 33 +- .../services/v2/user_types/types.py | 8 +- pyproject.toml | 2 + rules/registry.toml | 6 +- scripts/set_v2_user_type.py | 15 +- .../integration/test_alembic_v2_user_types.py | 4 +- .../test_v2_user_type_persistence.py | 6 + tests/unit/libs/test_auth0_management.py | 118 +++++++ tests/unit/test_set_v2_user_type_script.py | 23 +- tests/unit/v2/test_admin_user_routes.py | 29 ++ tests/unit/v2/test_me_routes.py | 20 +- tests/unit/v2/test_models.py | 7 +- tests/unit/v2/test_user_invitation_service.py | 93 +++++- tests/unit/v2/test_user_type_service.py | 20 +- tests/unit/v2/user_email_support.py | 11 + 27 files changed, 725 insertions(+), 219 deletions(-) rename migrations/v2/versions/{bb09a374231f_invite_users_and_dismiss_type_changes.py => f519a77ba122_invite_users_and_dismiss_type_changes.py} (93%) create mode 100644 policyengine_api/libs/auth0_management_settings.py diff --git a/docs/engineering/skills/alembic-migrations.md b/docs/engineering/skills/alembic-migrations.md index 458727b2b..62eb36447 100644 --- a/docs/engineering/skills/alembic-migrations.md +++ b/docs/engineering/skills/alembic-migrations.md @@ -446,6 +446,8 @@ it publishes that version, with nothing to restore it. Downgrading past the revision is therefore safe only while no version is pruned (no `tax_benefit_model_versions` row has `catalog_values_pruned_at` set). From the head, such a downgrade first runs the later revisions' downgrades: +`f519a77ba122`'s drops `user_invitations` and needs no recorded change with +source `invitation` (see "API v2 user invitations"), `970be5d29283`'s drops `user_type_changes` with every recorded change (see "API v2 user type changes"), `617f531f1506`'s needs no user to be an author or an admin (see "API v2 user types"), and `1356f658347d`'s needs @@ -828,7 +830,7 @@ version records again. ### API v2 user invitations -Revision `bb09a374231f` (parent `0c136a278f29`) was autogenerated, with no +Revision `f519a77ba122` (parent `0c136a278f29`) was autogenerated, with no post-generation corrections, after the `UserInvitation` model was added, `UserTypeChange` gained `dismissed_at`, and `UserTypeChangeSource` gained `invitation`. It adds `user_invitations`, one row per admin's invitation for @@ -836,9 +838,10 @@ an email address to become an author or admin: the address, the type (`author` or `admin`), the SHA-256 digest of its token in hexadecimal (unique; the token itself is never stored), the inviting admin, its expiry, its last send's time or failure, and when it was accepted, and by whom, or -revoked (never both). Deleting the inviting or accepting user keeps the -invitation and sets that column to NULL; an index on each serves that -`SET NULL`. It adds the nullable `user_type_changes.dismissed_at`, and +revoked (never both). Deleting the inviting admin keeps the invitation and +sets that column to NULL; deleting the user who accepted it deletes it, since +its address was theirs (`CASCADE`). An index on each serves what every user +deletion runs. It adds the nullable `user_type_changes.dismissed_at`, and replaces the source check: Alembic compares checks by name only, so the check that also allows `invitation` is named `ck_user_type_changes_source_allowed`, and autogenerate drops diff --git a/docs/generated/rules.md b/docs/generated/rules.md index 92266084c..79b3012d4 100644 --- a/docs/generated/rules.md +++ b/docs/generated/rules.md @@ -376,7 +376,7 @@ flowchart LR | `api.quality.environment-variables-load` | Required environment variables and credentials load in a deployed-like environment. | mechanical | enforced | yes | CI job `test_env_vars` | `pr.yml:test_env_vars` | — | | `api.quality.file-length` | A tracked Python file has at most 800 physical lines, or at most 1,500 if it is test code (a file under a tests or fixtures directory, or a conftest.py); a longer file is split by responsibility into modules, and keeps its public import path. | metric | enforced | yes | quality guard `file-length` | `pr.yml:quality-guards` | yes | | `api.quality.make-quality` | make quality is the command for the quality checks, locally and in CI: it applies ruff check --fix and ruff format, then runs make quality-check, which runs uv lock --check, ruff check, ruff format --check, Import Linter, mypy and the quality guards without changing files. Run with a stand-in uv, make quality runs each of them and fails whenever one fails, and make -n prints the same commands. pr.yml's quality-guards job runs make quality and then git diff --exit-code HEAD, with neither step skipped, allowed to fail, or run in another shell or directory, no MAKEFLAGS, GNUMAKEFLAGS or MAKEFILES set for them, and no earlier step writing to GITHUB_ENV or GITHUB_PATH; the Makefile uses no syntax the rules registry doesn't follow and nothing that hides a failing command; and no other pr.yml job's commands run ruff, mypy, lint-imports or the quality guards, directly or through a make target. | mechanical | enforced | yes | pytest `tests/unit/test_make_quality.py` | `pr.yml:test` | yes | -| `api.quality.mypy-v2` | Shared query models, FastAPI dependencies, v2 routes and services, the gzip negotiation, the user sign-in and Auth0 Management libraries with their rate-limit wait budget, the country list and its startup check pass mypy with untyped definitions disallowed. | mechanical | enforced | yes | mypy | `pr.yml:quality-guards` | — | +| `api.quality.mypy-v2` | Shared query models, FastAPI dependencies, v2 routes and services, the gzip negotiation, the user sign-in and Auth0 Management libraries with their settings and rate-limit wait budget, the Postmark email library, the country list and its startup check pass mypy with untyped definitions disallowed. | mechanical | enforced | yes | mypy | `pr.yml:quality-guards` | — | | `api.quality.pre-commit-hook` | make install turns on the git hooks in .githooks through core.hooksPath, a setting of the clone that every worktree shares and resolves against its own checkout, unless that would change an enclosing repository, replace another core.hooksPath, or stop the clone's own hooks (files or symbolic links), which .githooks/turn-on.sh says, always exiting 0. pre-commit runs make quality from the root of the working tree before git commit, and pre-merge-commit runs it before a merge commits without conflicts, with make's variables from the environment cleared. Because make quality checks the working tree, the hook stops the commit, naming the files or what to install, when the working tree holds unstaged changes to tracked files (case-only renames included), skip-worktree or assume-unchanged files, untracked files outside the ignore files, Python files or tool settings that only local or global excludes hide (outside virtual environments), or tracked Python files those excludes match; when make quality fails; when ruff's fixes changed a file; or when make, uv or the dev environment is missing. | mechanical | enforced | yes | pytest `tests/unit/test_pre_commit_hook.py` | `pr.yml:test` | yes | | `api.quality.ruff-format` | All Python files are formatted with ruff format. | mechanical | enforced | yes | ruff format | `pr.yml:quality-guards` | — | | `api.quality.ruff-lint` | All Python code passes ruff check with every ruff rule selected (ALL), with no ratchet, except the ignores in pyproject.toml: COM812 and ISC001, which conflict with ruff format, and D203 and D213, which conflict with the kept D211 and D212. | mechanical | enforced | yes | ruff check (ALL) | `pr.yml:quality-guards` | — | diff --git a/docs/migration/stage-12a-user-login.md b/docs/migration/stage-12a-user-login.md index 5bf3a8999..038c2db38 100644 --- a/docs/migration/stage-12a-user-login.md +++ b/docs/migration/stage-12a-user-login.md @@ -237,8 +237,10 @@ settings (`V2_RUNTIME_DATABASE_URL` or `V2_SUPABASE_ENVIRONMENT`), and refuses an address with no signed-in user, or several, and the last admin's demotion. A person's user exists only after their first signed-in request to the detailed-save routes. Like an admin's -change, the script's change emails the user (below) when it has the -`AUTH0_USER_PROFILES_*` and `POSTMARK_*` settings. +change, the script's change emails the user (below), and the script says +whether it did and, if not, why (for example `no_verified_email`). That needs +the `POSTMARK_*` settings, and the `AUTH0_USER_PROFILES_*` settings with +`PUBLIC_API_AUTH_ISSUER` and `PUBLIC_API_AUTH_AUDIENCE`. ### Email invitations @@ -293,7 +295,10 @@ its type unless they already have it or a higher one: an invitation never lowers a type, so the last-admin rule can't apply. A change is recorded with `source = invitation` and the inviting admin as `changed_by_user_id`. The response is `{user_type, previous_user_type, type_changed}`. Nothing changes -when any check refuses. +when any check refuses. Deleting an account deletes the invitations it +accepted, whose address was the user's own; the invitations an admin sent +are kept without the admin. An invitation that is never accepted keeps its +address until someone deletes it. ### Type-change emails and the notice @@ -658,7 +663,7 @@ admin; `scripts/set_v2_user_type.py` makes another admin afterwards. `users.primary_country`, so it fails while legacy-only rows, any simulation or report associations, or any unauthenticated user exist. Removing them first deletes users' saved work. From the head, the later revisions' - downgrades run first: the user invitations revision (`bb09a374231f`) drops + downgrades run first: the user invitations revision (`f519a77ba122`) drops every invitation and dismissal and needs no change with source `invitation`, the user type changes revision (`970be5d29283`) drops every recorded change, the user types revision (`617f531f1506`) needs no author diff --git a/docs/migration/stage-9-v2-metadata.md b/docs/migration/stage-9-v2-metadata.md index 48a07b84f..c6de37b99 100644 --- a/docs/migration/stage-9-v2-metadata.md +++ b/docs/migration/stage-9-v2-metadata.md @@ -799,8 +799,9 @@ pruning"). A schema downgrade past revision `334859ef4fec` drops `catalog_last_published_at` and `catalog_values_pruned_at`. From the head, -it first runs the later revisions' downgrades: `970be5d29283`'s drops -`user_type_changes` with every recorded change, `617f531f1506`'s needs no +it first runs the later revisions' downgrades: `f519a77ba122`'s drops +`user_invitations` and needs no recorded change with source `invitation`, +`970be5d29283`'s drops `user_type_changes` with every recorded change, `617f531f1506`'s needs no user to be an author or an admin, and `1356f658347d`'s needs `simulations` empty. A pruned version then looks complete, but holds diff --git a/migrations/v2/versions/bb09a374231f_invite_users_and_dismiss_type_changes.py b/migrations/v2/versions/f519a77ba122_invite_users_and_dismiss_type_changes.py similarity index 93% rename from migrations/v2/versions/bb09a374231f_invite_users_and_dismiss_type_changes.py rename to migrations/v2/versions/f519a77ba122_invite_users_and_dismiss_type_changes.py index 4535d76dd..27c497779 100644 --- a/migrations/v2/versions/bb09a374231f_invite_users_and_dismiss_type_changes.py +++ b/migrations/v2/versions/f519a77ba122_invite_users_and_dismiss_type_changes.py @@ -1,16 +1,17 @@ """invite users and dismiss type changes -Revision ID: bb09a374231f +Revision ID: f519a77ba122 Revises: 0c136a278f29 -Create Date: 2026-11-12 23:37:15.642213 +Create Date: 2026-11-13 00:29:54.681740 Generation: uv run alembic -c alembic-v2.ini revision --autogenerate Adds user_invitations, one row per admin's invitation for an email address to become an author or admin: the address, the type, the SHA-256 digest of its token (the token itself is never stored), the inviting admin, its expiry, its last send, and when it was accepted (and by whom) or revoked. Deleting the -inviting or accepting user keeps the invitation without them; an index on -each serves the SET NULL that every user deletion runs. user_type_changes +inviting admin keeps the invitation without them; deleting the user who +accepted it deletes it, since its address was theirs. An index on each of +those two columns serves what every user deletion runs. user_type_changes gains dismissed_at, when the user dismissed the app's notice of the change, and its source check, renamed ck_user_type_changes_source_allowed because Alembic compares checks by name only, also allows invitation. The operations @@ -31,7 +32,7 @@ import sqlmodel -revision: str = "bb09a374231f" +revision: str = "f519a77ba122" down_revision: Union[str, None] = "0c136a278f29" branch_labels: Union[str, Sequence[str], None] = None depends_on: Union[str, Sequence[str], None] = None @@ -80,7 +81,7 @@ def upgrade() -> None: ["accepted_by_user_id"], ["users.id"], name=op.f("fk_user_invitations_accepted_by_user_id_users"), - ondelete="SET NULL", + ondelete="CASCADE", ), sa.ForeignKeyConstraint( ["invited_by_user_id"], diff --git a/policyengine_api/data/v2/migration_target.py b/policyengine_api/data/v2/migration_target.py index b363f38ce..b51fd461c 100644 --- a/policyengine_api/data/v2/migration_target.py +++ b/policyengine_api/data/v2/migration_target.py @@ -24,7 +24,7 @@ from collections.abc import Mapping V2_ALEMBIC_DISPOSABLE_TEST = "V2_ALEMBIC_DISPOSABLE_TEST" -V2_ALEMBIC_HEAD_REVISION = "bb09a374231f" +V2_ALEMBIC_HEAD_REVISION = "f519a77ba122" DISPOSABLE_DATABASE_NAME = "policyengine_v2_alembic_test" DISPOSABLE_HOSTS = frozenset({"localhost", "127.0.0.1", "::1", "postgres"}) MIGRATION_ROLE = "policyengine_v2_migrator" diff --git a/policyengine_api/data/v2/models/users.py b/policyengine_api/data/v2/models/users.py index 80f9f5fe8..396f703ac 100644 --- a/policyengine_api/data/v2/models/users.py +++ b/policyengine_api/data/v2/models/users.py @@ -223,8 +223,9 @@ class UserInvitation(IdentifiedModel, table=True): Resending gives it a new token and expiry. ``last_sent_at`` is when the email with the current token was sent, and ``last_send_error`` names why the last send failed. ``invited_by_user_id`` is the admin who created or - last resent it, and ``accepted_by_user_id`` the user who accepted it; each - becomes empty if that user's account is deleted. + last resent it, and becomes empty if that admin's account is deleted. + ``accepted_by_user_id`` is the user who accepted it: deleting that user's + account deletes the invitation, whose address was the user's own. """ __tablename__ = "user_invitations" @@ -238,8 +239,8 @@ class UserInvitation(IdentifiedModel, table=True): name="ck_user_invitations_accepted_or_revoked", ), sa.UniqueConstraint("token_hash", name="uq_user_invitations_token_hash"), - # Deleting any user sets its invitations' users to NULL, which - # searches here. + # Deleting any user sets the invitations it sent to NULL and deletes + # those it accepted, which searches here. sa.Index("ix_user_invitations_invited_by_user_id", "invited_by_user_id"), sa.Index("ix_user_invitations_accepted_by_user_id", "accepted_by_user_id"), ) @@ -259,7 +260,7 @@ class UserInvitation(IdentifiedModel, table=True): default=None, sa_type=sa.DateTime(timezone=True) ) accepted_by_user_id: UUID | None = Field( - default=None, foreign_key="users.id", ondelete="SET NULL" + default=None, foreign_key="users.id", ondelete="CASCADE" ) revoked_at: datetime | None = Field( default=None, sa_type=sa.DateTime(timezone=True) diff --git a/policyengine_api/fastapi_routes/v2/admin_users/response_models.py b/policyengine_api/fastapi_routes/v2/admin_users/response_models.py index 0f03c1328..41d9fdb69 100644 --- a/policyengine_api/fastapi_routes/v2/admin_users/response_models.py +++ b/policyengine_api/fastapi_routes/v2/admin_users/response_models.py @@ -108,9 +108,11 @@ class UserTypeChangeItem(StrictAdminUserAPIModel): """One recorded change of a signed-in user's type. ``source`` is ``admin_route`` for a change an admin made through these - routes, named by ``changed_by_user_id`` and ``changed_by_email``, and - ``script`` for one the type script made, which names no admin. - ``changed_by_user_id`` is also null once that admin's account is deleted. + routes, named by ``changed_by_user_id`` and ``changed_by_email``, + ``invitation`` for one the user made by accepting an admin's email + invitation, which names that admin, and ``script`` for one the type + script made, which names no admin. ``changed_by_user_id`` is also null + once that admin's account is deleted. ``changed_by_email`` is read from Auth0 like an admin user item's email, else stored. """ @@ -121,7 +123,7 @@ class UserTypeChangeItem(StrictAdminUserAPIModel): new_user_type: Literal["standard", "author", "admin"] changed_by_user_id: UUID | None changed_by_email: str | None - source: Literal["admin_route", "script"] + source: Literal["admin_route", "invitation", "script"] created_at: datetime @classmethod diff --git a/policyengine_api/fastapi_routes/v2/me/user_type_routes.py b/policyengine_api/fastapi_routes/v2/me/user_type_routes.py index f969d0e14..6a460ae07 100644 --- a/policyengine_api/fastapi_routes/v2/me/user_type_routes.py +++ b/policyengine_api/fastapi_routes/v2/me/user_type_routes.py @@ -68,11 +68,13 @@ def _invitation_service_factory( ), }, 409: { - "model": V2CodedErrorResponse, + # A conflict with stored state answers without a code. + "model": V2CodedErrorResponse | V2ErrorResponse, "description": ( "code inviter_not_admin: the admin who sent the invitation is no " "longer an admin. code email_not_verified: Auth0 has no verified " - "email for the signed-in user yet; try again once it is verified." + "email for the signed-in user yet; try again once it is verified. " + "A conflict with stored state is also 409, without a code." ), }, 410: { @@ -85,7 +87,8 @@ def _invitation_service_factory( ), }, 503: { - "model": V2CodedErrorResponse, + # Unavailable persistence answers without a code. + "model": V2CodedErrorResponse | V2ErrorResponse, "description": ( "code auth0_unavailable: the signed-in user's email couldn't be " "read from Auth0; try again shortly. Persistence being unavailable " diff --git a/policyengine_api/libs/auth0_management.py b/policyengine_api/libs/auth0_management.py index 04620ecab..81751de1e 100644 --- a/policyengine_api/libs/auth0_management.py +++ b/policyengine_api/libs/auth0_management.py @@ -8,9 +8,10 @@ account deletion removes only Public API data and logs that the Auth0 deletion was skipped. Deployments allow it in production only. - ``AUTH0_USER_PROFILES_*``: the admin user routes read users' emails and - names from Auth0 only when a client with the ``read:users`` permission is - configured; nothing they read is stored. Deployments allow it in staging - and production. + names from Auth0, invitations are accepted against the invitee's verified + email, and type-change emails find the user's address, only when a client + with the ``read:users`` permission is configured; nothing they read is + stored. Deployments allow it in staging and production. Each group is all-or-none: a domain, a client ID, and exactly one client-secret source (a direct value or a Secret Manager resource, matching @@ -23,12 +24,10 @@ from __future__ import annotations import math -import os -import re import threading import time from contextlib import contextmanager -from dataclasses import dataclass, field +from dataclasses import dataclass from functools import cache from http import HTTPStatus from typing import TYPE_CHECKING, Protocol @@ -36,27 +35,55 @@ import httpx +from policyengine_api.libs.auth0_management_settings import ( + AUTH0_MANAGEMENT_CLIENT_ID_ENV, + AUTH0_MANAGEMENT_CLIENT_SECRET_ENV, + AUTH0_MANAGEMENT_CLIENT_SECRET_RESOURCE_ENV, + AUTH0_MANAGEMENT_DOMAIN_ENV, + AUTH0_MANAGEMENT_ENV_VARS, + AUTH0_MANAGEMENT_SETTING_NAMES, + AUTH0_USER_PROFILE_SETTING_NAMES, + DOMAIN_PATTERN, + SECRET_RESOURCE_PATTERN, + Auth0ClientSettingNames, + Auth0ManagementConfigurationError, + Auth0ManagementSettings, + load_auth0_management_settings, + load_auth0_user_profile_settings, +) from policyengine_api.libs.rate_limit_wait_budget import RateLimitWaitBudget -from policyengine_api.libs.user_auth import PUBLIC_API_AUTH_ISSUER_ENV if TYPE_CHECKING: from collections.abc import Callable, Iterable, Iterator, Mapping -AUTH0_MANAGEMENT_DOMAIN_ENV = "AUTH0_MANAGEMENT_DOMAIN" -AUTH0_MANAGEMENT_CLIENT_ID_ENV = "AUTH0_MANAGEMENT_CLIENT_ID" -AUTH0_MANAGEMENT_CLIENT_SECRET_ENV = "AUTH0_MANAGEMENT_CLIENT_SECRET" # noqa: S105 # an environment variable name, not a secret -AUTH0_MANAGEMENT_CLIENT_SECRET_RESOURCE_ENV = "AUTH0_MANAGEMENT_CLIENT_SECRET_RESOURCE" # noqa: S105 # an environment variable name, not a secret -AUTH0_MANAGEMENT_ENV_VARS = ( - AUTH0_MANAGEMENT_DOMAIN_ENV, - AUTH0_MANAGEMENT_CLIENT_ID_ENV, - AUTH0_MANAGEMENT_CLIENT_SECRET_ENV, - AUTH0_MANAGEMENT_CLIENT_SECRET_RESOURCE_ENV, -) -DOMAIN_PATTERN = re.compile( - r"^(?=.{1,253}$)[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?" - r"(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$" -) -SECRET_RESOURCE_PATTERN = re.compile(r"^projects/[^/]+/secrets/[^/]+/versions/[^/]+$") +# The settings moved to auth0_management_settings; they are still imported +# from here. +__all__ = [ + "AUTH0_MANAGEMENT_CLIENT_ID_ENV", + "AUTH0_MANAGEMENT_CLIENT_SECRET_ENV", + "AUTH0_MANAGEMENT_CLIENT_SECRET_RESOURCE_ENV", + "AUTH0_MANAGEMENT_DOMAIN_ENV", + "AUTH0_MANAGEMENT_ENV_VARS", + "AUTH0_MANAGEMENT_SETTING_NAMES", + "AUTH0_USER_PROFILE_SETTING_NAMES", + "DOMAIN_PATTERN", + "SECRET_RESOURCE_PATTERN", + "Auth0ClientSettingNames", + "Auth0ManagementClient", + "Auth0ManagementConfigurationError", + "Auth0ManagementError", + "Auth0ManagementSettings", + "Auth0UserIdSearch", + "Auth0UserProfile", + "Auth0UserProfilesUnavailableError", + "UserProfileReader", + "build_auth0_user_deleter", + "build_auth0_user_profile_reader", + "email_search_query", + "load_auth0_management_settings", + "load_auth0_user_profile_settings", +] + HTTP_TIMEOUT_SECONDS = 10.0 TOKEN_REFRESH_MARGIN_SECONDS = 60 # Every search page is sorted by user ID, so pages don't shift between requests. @@ -77,49 +104,6 @@ MAXIMUM_NAME_LENGTH = 255 -@dataclass(frozen=True) -class Auth0ClientSettingNames: - """The environment variables that configure one Management API client.""" - - prefix: str - # The configuration error's opening words when the group is incomplete. - incomplete_message: str - - @property - def domain(self) -> str: - """Name the variable that holds the tenant's canonical domain.""" - return f"{self.prefix}_DOMAIN" - - @property - def client_id(self) -> str: - """Name the variable that holds the machine-to-machine client's ID.""" - return f"{self.prefix}_CLIENT_ID" - - @property - def client_secret(self) -> str: - """Name the variable that holds the client secret itself, for local use.""" - return f"{self.prefix}_CLIENT_SECRET" - - @property - def client_secret_resource(self) -> str: - """Name the variable that holds the client secret's Secret Manager version.""" - return f"{self.prefix}_CLIENT_SECRET_RESOURCE" - - -AUTH0_MANAGEMENT_SETTING_NAMES = Auth0ClientSettingNames( - prefix="AUTH0_MANAGEMENT", - incomplete_message="Auth0 Management API deletion is partially configured", -) -AUTH0_USER_PROFILE_SETTING_NAMES = Auth0ClientSettingNames( - prefix="AUTH0_USER_PROFILES", - incomplete_message="Auth0 user profile reads are partially configured", -) - - -class Auth0ManagementConfigurationError(RuntimeError): - """Raised when the optional Management API settings are incomplete.""" - - class Auth0ManagementError(RuntimeError): """Raised when the Management API rejects or fails a request. @@ -164,21 +148,6 @@ def _seconds(value: str | None) -> float | None: return seconds if math.isfinite(seconds) else None -@dataclass(frozen=True) -class Auth0ManagementSettings: - """Validated Management API settings for one Auth0 tenant. - - Exactly one of ``client_secret`` and ``client_secret_resource`` (a Secret - Manager version name) is set. The secret is kept out of ``repr``, and equal - settings share one client, so its token is reused. - """ - - domain: str - client_id: str - client_secret: str = field(default="", repr=False) - client_secret_resource: str = "" - - @dataclass(frozen=True) class Auth0UserProfile: """What the admin routes read about one Auth0 user; never stored. @@ -243,70 +212,16 @@ def search_user_ids_by_email( """ ... + def read_user_profile( + self, user_id: str, *, wait_budget: RateLimitWaitBudget | None = None + ) -> Auth0UserProfile | None: + """Return one user's profile as Auth0 has it now, or None if unknown. -def _load_client_settings( - names: Auth0ClientSettingNames, environ: Mapping[str, str] | None -) -> Auth0ManagementSettings | None: - """Return one group's complete settings, or ``None`` when it is absent.""" - values = os.environ if environ is None else environ - domain = values.get(names.domain, "").strip() - client_id = values.get(names.client_id, "").strip() - client_secret = values.get(names.client_secret, "").strip() - secret_resource = values.get(names.client_secret_resource, "").strip() - if not any((domain, client_id, client_secret, secret_resource)): - return None - if client_secret and secret_resource: - msg = ( - f"Set exactly one of {names.client_secret} or " - f"{names.client_secret_resource}" - ) - raise Auth0ManagementConfigurationError(msg) - if not domain or not client_id or not (client_secret or secret_resource): - msg = ( - f"{names.incomplete_message}: set {names.domain}, " - f"{names.client_id}, and exactly one client-secret source" - ) - raise Auth0ManagementConfigurationError(msg) - if DOMAIN_PATTERN.fullmatch(domain) is None: - msg = f"{names.domain} must be a bare host name" - raise Auth0ManagementConfigurationError(msg) - if secret_resource and SECRET_RESOURCE_PATTERN.fullmatch(secret_resource) is None: - msg = f"{names.client_secret_resource} is invalid" - raise Auth0ManagementConfigurationError(msg) - return Auth0ManagementSettings( - domain=domain, - client_id=client_id, - client_secret=client_secret, - client_secret_resource=secret_resource, - ) - - -def load_auth0_management_settings( - environ: Mapping[str, str] | None = None, -) -> Auth0ManagementSettings | None: - """Return complete account-deletion settings, or ``None`` when absent.""" - return _load_client_settings(AUTH0_MANAGEMENT_SETTING_NAMES, environ) - - -def load_auth0_user_profile_settings( - environ: Mapping[str, str] | None = None, -) -> Auth0ManagementSettings | None: - """Return complete user-profile settings, or ``None`` when absent. - - Raise when they are set without ``PUBLIC_API_AUTH_ISSUER``: only - identities from the users' issuer are users of the tenant, so without it - profiles would be read for nobody. - """ - values = os.environ if environ is None else environ - settings = _load_client_settings(AUTH0_USER_PROFILE_SETTING_NAMES, values) - if settings is not None and not values.get(PUBLIC_API_AUTH_ISSUER_ENV, "").strip(): - msg = ( - f"{AUTH0_USER_PROFILE_SETTING_NAMES.prefix}_* settings need " - f"{PUBLIC_API_AUTH_ISSUER_ENV}: only identities from the users' " - "issuer are looked up" - ) - raise Auth0ManagementConfigurationError(msg) - return settings + Unlike the search the other reads use, it sees a user created or + changed moments ago. Rate-limit waits are spent from ``wait_budget``, + else from a budget of this call's own. + """ + ... def _quoted_user_id(user_id: str) -> str: @@ -584,6 +499,26 @@ def _rate_limit_wait(self, response: httpx.Response) -> float | None: return max(0.0, reset_at - self._clock()) return None + def _profile_read( + self, send: Callable[[], httpx.Response], wait_budget: RateLimitWaitBudget + ) -> httpx.Response: + """Send one profile read; raise Auth0UserProfilesUnavailableError on failure. + + A rate-limited read (429) is retried once, after the wait Auth0 gives, + when that wait fits in what is left of ``wait_budget``. + """ + try: + response = send() + if response.status_code == HTTPStatus.TOO_MANY_REQUESTS: + wait = self._rate_limit_wait(response) + if wait is not None and wait_budget.take(wait): + self._sleep(wait) + response = send() + except Auth0ManagementError as error: + msg = f"Auth0 user profiles are unavailable: {error.cause}" + raise Auth0UserProfilesUnavailableError(msg, cause=error.cause) from error + return response + def _search_users( self, http_client: httpx.Client, @@ -595,16 +530,9 @@ def _search_users( A rate-limited search (429) is retried once, after the wait Auth0 gives, when that wait fits in what is left of ``wait_budget``. """ - try: - response = self._authorized_search(http_client, parameters) - if response.status_code == HTTPStatus.TOO_MANY_REQUESTS: - wait = self._rate_limit_wait(response) - if wait is not None and wait_budget.take(wait): - self._sleep(wait) - response = self._authorized_search(http_client, parameters) - except Auth0ManagementError as error: - msg = f"Auth0 user profiles are unavailable: {error.cause}" - raise Auth0UserProfilesUnavailableError(msg, cause=error.cause) from error + response = self._profile_read( + lambda: self._authorized_search(http_client, parameters), wait_budget + ) if response.status_code != HTTPStatus.OK: msg = f"Auth0 user profiles are unavailable: HTTP {response.status_code}" raise Auth0UserProfilesUnavailableError( @@ -662,6 +590,67 @@ def read_user_profiles( profiles[profile.user_id] = profile return profiles + def _user_request( + self, http_client: httpx.Client, user_id: str, token: str + ) -> httpx.Response: + return self._send( + http_client, + http_client.build_request( + "GET", + f"{self._base_url}/api/v2/users/{quote(user_id, safe='')}", + params={"fields": USER_PROFILE_FIELDS, "include_fields": "true"}, + headers={"Authorization": f"Bearer {token}"}, + ), + ) + + def _authorized_user_request( + self, http_client: httpx.Client, user_id: str + ) -> httpx.Response: + """Read one user with the cached token; after a 401, with a new one.""" + token = self._access_token(http_client) + response = self._user_request(http_client, user_id, token) + if response.status_code == HTTPStatus.UNAUTHORIZED: + self._discard_token(token) + response = self._user_request( + http_client, user_id, self._access_token(http_client) + ) + return response + + def read_user_profile( + self, user_id: str, *, wait_budget: RateLimitWaitBudget | None = None + ) -> Auth0UserProfile | None: + """Return one user's profile, read by ID, or None when Auth0 has no such user. + + ``GET /api/v2/users/{id}`` is immediately consistent, so it sees a user + who signed up or verified their email moments ago, which the search + may not. A rate-limited read is retried once within ``wait_budget``, + else a budget of this call's own. Raise Auth0UserProfilesUnavailableError + when Auth0 can't answer, or answers with another user or no user. + """ + budget = RateLimitWaitBudget() if wait_budget is None else wait_budget + with self._operation_http_client() as http_client: + response = self._profile_read( + lambda: self._authorized_user_request(http_client, user_id), budget + ) + if response.status_code == HTTPStatus.NOT_FOUND: + return None + if response.status_code != HTTPStatus.OK: + msg = f"Auth0 user profiles are unavailable: HTTP {response.status_code}" + raise Auth0UserProfilesUnavailableError( + msg, cause=f"http_{response.status_code}" + ) + try: + profile = _user_profile(response.json()) + except ValueError as error: + msg = "Auth0 user profiles are unavailable: the answer is not JSON" + raise Auth0UserProfilesUnavailableError( + msg, cause="unreadable_answer" + ) from error + if profile is None or profile.user_id != user_id: + msg = "Auth0 user profiles are unavailable: the answer is not the user" + raise Auth0UserProfilesUnavailableError(msg, cause="unreadable_answer") + return profile + def search_user_ids_by_email( self, text: str, diff --git a/policyengine_api/libs/auth0_management_settings.py b/policyengine_api/libs/auth0_management_settings.py new file mode 100644 index 000000000..cec6e06ab --- /dev/null +++ b/policyengine_api/libs/auth0_management_settings.py @@ -0,0 +1,160 @@ +"""Settings for the optional Auth0 Management API clients. + +Two settings groups each configure one Management API machine-to-machine +client, ``AUTH0_MANAGEMENT_*`` for account deletion and +``AUTH0_USER_PROFILES_*`` for reading users' profiles; see +``policyengine_api.libs.auth0_management``, which uses them and re-exports +these names. Each group is all-or-none: a domain, a client ID, and exactly +one client-secret source (a direct value or a Secret Manager resource). +""" + +from __future__ import annotations + +import os +import re +from dataclasses import dataclass, field +from typing import TYPE_CHECKING + +from policyengine_api.libs.user_auth import PUBLIC_API_AUTH_ISSUER_ENV + +if TYPE_CHECKING: + from collections.abc import Mapping + +AUTH0_MANAGEMENT_DOMAIN_ENV = "AUTH0_MANAGEMENT_DOMAIN" +AUTH0_MANAGEMENT_CLIENT_ID_ENV = "AUTH0_MANAGEMENT_CLIENT_ID" +AUTH0_MANAGEMENT_CLIENT_SECRET_ENV = "AUTH0_MANAGEMENT_CLIENT_SECRET" # noqa: S105 # an environment variable name, not a secret +AUTH0_MANAGEMENT_CLIENT_SECRET_RESOURCE_ENV = "AUTH0_MANAGEMENT_CLIENT_SECRET_RESOURCE" # noqa: S105 # an environment variable name, not a secret +AUTH0_MANAGEMENT_ENV_VARS = ( + AUTH0_MANAGEMENT_DOMAIN_ENV, + AUTH0_MANAGEMENT_CLIENT_ID_ENV, + AUTH0_MANAGEMENT_CLIENT_SECRET_ENV, + AUTH0_MANAGEMENT_CLIENT_SECRET_RESOURCE_ENV, +) +DOMAIN_PATTERN = re.compile( + r"^(?=.{1,253}$)[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?" + r"(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$" +) +SECRET_RESOURCE_PATTERN = re.compile(r"^projects/[^/]+/secrets/[^/]+/versions/[^/]+$") + + +@dataclass(frozen=True) +class Auth0ClientSettingNames: + """The environment variables that configure one Management API client.""" + + prefix: str + # The configuration error's opening words when the group is incomplete. + incomplete_message: str + + @property + def domain(self) -> str: + """Name the variable that holds the tenant's canonical domain.""" + return f"{self.prefix}_DOMAIN" + + @property + def client_id(self) -> str: + """Name the variable that holds the machine-to-machine client's ID.""" + return f"{self.prefix}_CLIENT_ID" + + @property + def client_secret(self) -> str: + """Name the variable that holds the client secret itself, for local use.""" + return f"{self.prefix}_CLIENT_SECRET" + + @property + def client_secret_resource(self) -> str: + """Name the variable that holds the client secret's Secret Manager version.""" + return f"{self.prefix}_CLIENT_SECRET_RESOURCE" + + +AUTH0_MANAGEMENT_SETTING_NAMES = Auth0ClientSettingNames( + prefix="AUTH0_MANAGEMENT", + incomplete_message="Auth0 Management API deletion is partially configured", +) +AUTH0_USER_PROFILE_SETTING_NAMES = Auth0ClientSettingNames( + prefix="AUTH0_USER_PROFILES", + incomplete_message="Auth0 user profile reads are partially configured", +) + + +class Auth0ManagementConfigurationError(RuntimeError): + """Raised when the optional Management API settings are incomplete.""" + + +@dataclass(frozen=True) +class Auth0ManagementSettings: + """Validated Management API settings for one Auth0 tenant. + + Exactly one of ``client_secret`` and ``client_secret_resource`` (a Secret + Manager version name) is set. The secret is kept out of ``repr``, and equal + settings share one client, so its token is reused. + """ + + domain: str + client_id: str + client_secret: str = field(default="", repr=False) + client_secret_resource: str = "" + + +def _load_client_settings( + names: Auth0ClientSettingNames, environ: Mapping[str, str] | None +) -> Auth0ManagementSettings | None: + """Return one group's complete settings, or ``None`` when it is absent.""" + values = os.environ if environ is None else environ + domain = values.get(names.domain, "").strip() + client_id = values.get(names.client_id, "").strip() + client_secret = values.get(names.client_secret, "").strip() + secret_resource = values.get(names.client_secret_resource, "").strip() + if not any((domain, client_id, client_secret, secret_resource)): + return None + if client_secret and secret_resource: + msg = ( + f"Set exactly one of {names.client_secret} or " + f"{names.client_secret_resource}" + ) + raise Auth0ManagementConfigurationError(msg) + if not domain or not client_id or not (client_secret or secret_resource): + msg = ( + f"{names.incomplete_message}: set {names.domain}, " + f"{names.client_id}, and exactly one client-secret source" + ) + raise Auth0ManagementConfigurationError(msg) + if DOMAIN_PATTERN.fullmatch(domain) is None: + msg = f"{names.domain} must be a bare host name" + raise Auth0ManagementConfigurationError(msg) + if secret_resource and SECRET_RESOURCE_PATTERN.fullmatch(secret_resource) is None: + msg = f"{names.client_secret_resource} is invalid" + raise Auth0ManagementConfigurationError(msg) + return Auth0ManagementSettings( + domain=domain, + client_id=client_id, + client_secret=client_secret, + client_secret_resource=secret_resource, + ) + + +def load_auth0_management_settings( + environ: Mapping[str, str] | None = None, +) -> Auth0ManagementSettings | None: + """Return complete account-deletion settings, or ``None`` when absent.""" + return _load_client_settings(AUTH0_MANAGEMENT_SETTING_NAMES, environ) + + +def load_auth0_user_profile_settings( + environ: Mapping[str, str] | None = None, +) -> Auth0ManagementSettings | None: + """Return complete user-profile settings, or ``None`` when absent. + + Raise when they are set without ``PUBLIC_API_AUTH_ISSUER``: only + identities from the users' issuer are users of the tenant, so without it + profiles would be read for nobody. + """ + values = os.environ if environ is None else environ + settings = _load_client_settings(AUTH0_USER_PROFILE_SETTING_NAMES, values) + if settings is not None and not values.get(PUBLIC_API_AUTH_ISSUER_ENV, "").strip(): + msg = ( + f"{AUTH0_USER_PROFILE_SETTING_NAMES.prefix}_* settings need " + f"{PUBLIC_API_AUTH_ISSUER_ENV}: only identities from the users' " + "issuer are looked up" + ) + raise Auth0ManagementConfigurationError(msg) + return settings diff --git a/policyengine_api/services/v2/user_invitations/services.py b/policyengine_api/services/v2/user_invitations/services.py index c4e0493b0..db6156d53 100644 --- a/policyengine_api/services/v2/user_invitations/services.py +++ b/policyengine_api/services/v2/user_invitations/services.py @@ -15,9 +15,11 @@ one: an invitation never lowers a type. A change is recorded with the inviting admin named, and the user is emailed about it after the commit. -Every invitation write takes the user-type change lock, which type changes -and account deletions take too, and checks the caller against the admins -read after it. +Creating, resending, revoking and accepting an invitation each take the +user-type change lock, which type changes and account deletions take too, and +check the caller or the inviting admin against the admins read after it. +Recording how a send went takes only the invitation's row lock, and records +nothing when a resend replaced its token meanwhile. """ from __future__ import annotations @@ -298,6 +300,9 @@ def _send_invitation(self, sending: InvitationEmail) -> AdminInvitationRead: def _invitee_profile(self, principal: UserPrincipal) -> Auth0UserProfile | None: """Read the signed-in invitee's Auth0 profile by their Auth0 user ID. + It is read with ``GET /api/v2/users/{id}``, never the search, so a + just-created or just-verified user is seen. + Return None when the identity isn't from the users' Auth0 tenant or Auth0 doesn't know it. Raise InvitationEmailUnavailableError when there are no profile settings or Auth0 can't answer. @@ -315,8 +320,10 @@ def _invitee_profile(self, principal: UserPrincipal) -> Auth0UserProfile | None: if principal.issuer != source.issuer: return None try: - profiles = source.reader.read_user_profiles( - (principal.subject,), wait_budget=RateLimitWaitBudget() + # Read by ID, which Auth0 answers at once: its search may not yet + # see someone who signed up, or verified their email, moments ago. + return source.reader.read_user_profile( + principal.subject, wait_budget=RateLimitWaitBudget() ) except Exception as error: cause = getattr(error, "cause", None) @@ -324,7 +331,6 @@ def _invitee_profile(self, principal: UserPrincipal) -> Auth0UserProfile | None: raise InvitationEmailUnavailableError( INVITEE_EMAIL_UNAVAILABLE_MESSAGE ) from error - return profiles.get(principal.subject) @staticmethod def _record_unavailable(cause: str) -> None: diff --git a/policyengine_api/services/v2/user_types/services.py b/policyengine_api/services/v2/user_types/services.py index 063a5fd05..c7fe165e3 100644 --- a/policyengine_api/services/v2/user_types/services.py +++ b/policyengine_api/services/v2/user_types/services.py @@ -14,11 +14,11 @@ the previous and new type, who made it and how. A change that would leave no admin is refused. -Every change, every invitation write and every signed-in account deletion -first takes one transaction-scoped advisory lock, then reads the admins and -checks the caller or the deleted user against them, so they run one at a time -and none can leave no admin. After a change commits, the user is emailed about -it when an email service is configured. +Every change, every invitation created, resent, revoked or accepted, and +every signed-in account deletion first takes one transaction-scoped advisory +lock, then reads the admins and checks the caller or the deleted user against +them, so they run one at a time and none can leave no admin. After a change +commits, the user is emailed about it when an email service is configured. With a user profile source, admins see each user's email and names as Auth0 has them, read after the database work and never stored: only identities @@ -115,6 +115,8 @@ logger = logging.getLogger(__name__) PROFILES_UNAVAILABLE_EVENT = "admin_user_profiles_unavailable" +# Why a change's email wasn't sent when the service was built without emails. +NO_EMAIL_SERVICE = "not_configured" EMAIL_SEARCH_UNAVAILABLE_MESSAGE = ( "Users can't be searched by email now: their emails could not be read " "from Auth0. Try again shortly." @@ -181,10 +183,16 @@ def __init__( self._user_profile_source_factory = user_profile_source_factory self._user_email_service = user_email_service - def _email_type_change(self, change: UserTypeChangeEmail | None) -> None: - """Email the user about a committed change; never raises for a failure.""" - if change is not None and self._user_email_service is not None: - self._user_email_service.send_type_change(change) + def _email_type_change(self, change: UserTypeChangeEmail | None) -> str | None: + """Email the user about a committed change; never raise for a failure. + + Return why it wasn't sent, or None when it was or none was needed. + """ + if change is None: + return None + if self._user_email_service is None: + return NO_EMAIL_SERVICE + return self._user_email_service.send_type_change(change) def _profile_source(self) -> UserProfileSource | None: """Return the configured profile source, or None when there is none. @@ -489,8 +497,11 @@ def set_user_type_by_email( ), ) (read,) = _admin_user_reads(session, [user]) - self._email_type_change(change) - return ScriptedUserTypeChange(user=read, previous_user_type=previous_user_type) + return ScriptedUserTypeChange( + user=read, + previous_user_type=previous_user_type, + email_failure=self._email_type_change(change), + ) def lock_and_require_admin_in_session( diff --git a/policyengine_api/services/v2/user_types/types.py b/policyengine_api/services/v2/user_types/types.py index e838b5128..b338dee60 100644 --- a/policyengine_api/services/v2/user_types/types.py +++ b/policyengine_api/services/v2/user_types/types.py @@ -106,10 +106,16 @@ class UserTypeChangeOrigin: @dataclass(frozen=True) class ScriptedUserTypeChange: - """What the type script did: the user as it is now, and its type before.""" + """What the type script did: the user as it is now, and its type before. + + ``email_failure`` names why the user wasn't emailed about the change, + such as ``no_verified_email``; it is None when the email was sent, or + when nothing changed and none was needed. + """ user: AdminUserRead previous_user_type: UserType + email_failure: str | None = None @dataclass(frozen=True) diff --git a/pyproject.toml b/pyproject.toml index fedab7f05..46c2834f6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -197,6 +197,8 @@ files = [ "policyengine_api/content_encoding.py", "policyengine_api/libs/user_auth.py", "policyengine_api/libs/auth0_management.py", + "policyengine_api/libs/auth0_management_settings.py", + "policyengine_api/libs/postmark_email.py", "policyengine_api/libs/rate_limit_wait_budget.py", "policyengine_api/startup_country_check.py", "policyengine_api/supported_countries.py", diff --git a/rules/registry.toml b/rules/registry.toml index bd16a12e6..c31a7ab57 100644 --- a/rules/registry.toml +++ b/rules/registry.toml @@ -1457,9 +1457,9 @@ invocation = "ruff check ." [[rule]] id = "api.quality.mypy-v2" category = "quality" -statement = "Shared query models, FastAPI dependencies, v2 routes and services, the gzip negotiation, the user sign-in and Auth0 Management libraries with their rate-limit wait budget, the country list and its startup check pass mypy with untyped definitions disallowed." +statement = "Shared query models, FastAPI dependencies, v2 routes and services, the gzip negotiation, the user sign-in and Auth0 Management libraries with their settings and rate-limit wait budget, the Postmark email library, the country list and its startup check pass mypy with untyped definitions disallowed." rationale = "docs/engineering/skills/v2-code-organization.md" -scope = ["policyengine_api/fastapi_routes/v2/**/*.py", "policyengine_api/services/v2/**/*.py", "policyengine_api/content_encoding.py", "policyengine_api/libs/user_auth.py", "policyengine_api/libs/auth0_management.py", "policyengine_api/libs/rate_limit_wait_budget.py", "policyengine_api/startup_country_check.py", "policyengine_api/supported_countries.py"] +scope = ["policyengine_api/fastapi_routes/v2/**/*.py", "policyengine_api/services/v2/**/*.py", "policyengine_api/content_encoding.py", "policyengine_api/libs/user_auth.py", "policyengine_api/libs/auth0_management.py", "policyengine_api/libs/auth0_management_settings.py", "policyengine_api/libs/postmark_email.py", "policyengine_api/libs/rate_limit_wait_budget.py", "policyengine_api/startup_country_check.py", "policyengine_api/supported_countries.py"] tier = "mechanical" status = "enforced" autofix = false @@ -1476,6 +1476,8 @@ paths = [ "policyengine_api/content_encoding.py", "policyengine_api/libs/user_auth.py", "policyengine_api/libs/auth0_management.py", + "policyengine_api/libs/auth0_management_settings.py", + "policyengine_api/libs/postmark_email.py", "policyengine_api/libs/rate_limit_wait_budget.py", "policyengine_api/startup_country_check.py", "policyengine_api/supported_countries.py", diff --git a/scripts/set_v2_user_type.py b/scripts/set_v2_user_type.py index 10f9cb399..50812dc3d 100755 --- a/scripts/set_v2_user_type.py +++ b/scripts/set_v2_user_type.py @@ -9,9 +9,11 @@ sign-in identities' emails; exactly one signed-in user must match. The change is recorded in the user's type history with no admin named. Demoting the last admin is refused, as it is through the admin routes. After the change, the -user is emailed at their verified Auth0 email, as for an admin's change, when -the ``AUTH0_USER_PROFILES_*`` and ``POSTMARK_*`` settings are set; otherwise a -WARNING record says no email was sent. +user is emailed at their verified Auth0 email, as for an admin's change; the +command says whether it was, and why not. The email needs the +``POSTMARK_*`` settings, and the ``AUTH0_USER_PROFILES_*`` settings with +``PUBLIC_API_AUTH_ISSUER`` and ``PUBLIC_API_AUTH_AUDIENCE``, as the deployed +Public API has them. It connects as the Public API's runtime role, configured as the deployed Public API is: ``V2_RUNTIME_DATABASE_URL`` (or @@ -92,10 +94,13 @@ def _describe(change: ScriptedUserTypeChange, email: str) -> str: f"{email} (user {user.id}) is already {user.user_type.value}; " "nothing changed." ) - return ( + changed = ( f"Changed {email} (user {user.id}) from " - f"{change.previous_user_type.value} to {user.user_type.value}." + f"{change.previous_user_type.value} to {user.user_type.value}.\n" ) + if change.email_failure is None: + return changed + "Emailed the user about the change." + return changed + f"The user was not emailed: {change.email_failure}." def main( diff --git a/tests/integration/test_alembic_v2_user_types.py b/tests/integration/test_alembic_v2_user_types.py index 60e0efc32..ebc116d2b 100644 --- a/tests/integration/test_alembic_v2_user_types.py +++ b/tests/integration/test_alembic_v2_user_types.py @@ -4,7 +4,7 @@ author and admin, and changes nothing else; its downgrade restores the check that allows only unauthenticated and standard, so it fails while any user is an author or an admin. Revision 970be5d29283, on it, adds user_type_changes and -changes nothing else. Revision bb09a374231f, on the SPM availability revision, +changes nothing else. Revision f519a77ba122, on the SPM availability revision, adds user_invitations and user_type_changes.dismissed_at, and lets a change's source be invitation; its downgrade fails while any change's source is invitation. @@ -32,7 +32,7 @@ USER_TYPE_CHANGES_REVISION = "970be5d29283" # The SPM availability revision, and the user invitations revision on it. SPM_AVAILABILITY_REVISION = "0c136a278f29" -USER_INVITATIONS_REVISION = "bb09a374231f" +USER_INVITATIONS_REVISION = "f519a77ba122" def _check_names(engine: Engine, table_name: str) -> set[str]: diff --git a/tests/integration/test_v2_user_type_persistence.py b/tests/integration/test_v2_user_type_persistence.py index adf984fe5..84cba8969 100644 --- a/tests/integration/test_v2_user_type_persistence.py +++ b/tests/integration/test_v2_user_type_persistence.py @@ -266,6 +266,12 @@ def read_user_profiles( if user_id == self.profile.user_id } + def read_user_profile( + self, user_id: str, *, wait_budget: RateLimitWaitBudget | None = None + ) -> Auth0UserProfile | None: + assert isinstance(wait_budget, RateLimitWaitBudget) + return self.profile if user_id == self.profile.user_id else None + def test_the_runtime_role_finds_users_by_their_auth0_email(sessions) -> None: alice = _principal(sessions, "alice") diff --git a/tests/unit/libs/test_auth0_management.py b/tests/unit/libs/test_auth0_management.py index cd567f48d..a49caa4ae 100644 --- a/tests/unit/libs/test_auth0_management.py +++ b/tests/unit/libs/test_auth0_management.py @@ -1140,3 +1140,121 @@ def test_each_call_without_a_budget_gets_its_own_two_seconds(operation: str) -> assert waits == [1.5, 1.5] assert len(_searches(requests)) == 4 + + +def _token_then_user(answer_user): + """Issue a token, then answer each read of one user with ``answer_user``.""" + + def handler(request: httpx.Request) -> httpx.Response: + if request.url.path == "/oauth/token": + return httpx.Response( + 200, json={"access_token": "mgmt", "expires_in": 3600} + ) + return answer_user(request) + + return handler + + +def test_one_user_is_read_by_id_which_auth0_answers_at_once() -> None: + """The read by ID is immediately consistent, unlike the user search.""" + client, requests = _client( + _token_then_user( + lambda request: httpx.Response( + 200, + json=_profile_payload( + "google-oauth2|ada/1", + email=" ada@example.test ", + email_verified=True, + name="Ada", + ), + ) + ) + ) + + profile = client.read_user_profile("google-oauth2|ada/1") + + (read,) = [request for request in requests if request.url.path != "/oauth/token"] + assert read.method == "GET" + assert read.url.raw_path.startswith(b"/api/v2/users/google-oauth2%7Cada%2F1?") + assert read.url.params["fields"] == PROFILE_FIELDS + assert read.url.params["include_fields"] == "true" + assert read.headers["authorization"] == "Bearer mgmt" + assert profile == Auth0UserProfile( + user_id="google-oauth2|ada/1", + email="ada@example.test", + email_verified=True, + given_name=None, + family_name=None, + name="Ada", + ) + + +def test_a_user_auth0_doesnt_know_reads_as_none() -> None: + client, _requests = _client( + _token_then_user(lambda _request: httpx.Response(404, json={})) + ) + + assert client.read_user_profile("auth0|gone") is None + + +@pytest.mark.parametrize( + ("answer", "cause"), + [ + (httpx.Response(403, json={}), "http_403"), + (httpx.Response(500), "http_500"), + (httpx.Response(200, text="not json"), "unreadable_answer"), + (httpx.Response(200, json=[]), "unreadable_answer"), + (httpx.Response(200, json={"user_id": "auth0|other"}), "unreadable_answer"), + ], +) +def test_a_failed_read_of_one_user_says_why_without_naming_it( + answer: httpx.Response, cause: str +) -> None: + client, _requests = _client(_token_then_user(lambda _request: answer)) + + with pytest.raises(Auth0UserProfilesUnavailableError) as failed: + client.read_user_profile("auth0|ada") + + assert failed.value.cause == cause + assert "auth0|ada" not in str(failed.value) + + +def test_a_rate_limited_read_of_one_user_is_retried_once_within_the_budget() -> None: + client, requests, waits = _rate_limited_client( + [ + httpx.Response(429, headers={"Retry-After": "1"}), + httpx.Response(200, json=_profile_payload("auth0|1", email="a@b.test")), + ] + ) + budget = RateLimitWaitBudget() + + profile = client.read_user_profile("auth0|1", wait_budget=budget) + + assert profile is not None + assert waits == [1.0] + assert budget.remaining_seconds == 1.0 + assert [ + request.url.path + for request in requests + if request.url.path.startswith("/api/v2/users/") + ] == ["/api/v2/users/auth0|1"] * 2 + + +def test_a_rejected_token_is_replaced_once_for_a_read_of_one_user() -> None: + tokens = iter(["mgmt-1", "mgmt-2"]) + reads: list[str] = [] + + def handler(request: httpx.Request) -> httpx.Response: + if request.url.path == "/oauth/token": + return httpx.Response( + 200, json={"access_token": next(tokens), "expires_in": 3600} + ) + reads.append(request.headers["authorization"]) + if request.headers["authorization"] == "Bearer mgmt-1": + return httpx.Response(401) + return httpx.Response(200, json=_profile_payload("auth0|1")) + + client, _requests = _client(handler) + + assert client.read_user_profile("auth0|1") is not None + assert reads == ["Bearer mgmt-1", "Bearer mgmt-2"] diff --git a/tests/unit/test_set_v2_user_type_script.py b/tests/unit/test_set_v2_user_type_script.py index 5c14d844e..4523b3ed8 100644 --- a/tests/unit/test_set_v2_user_type_script.py +++ b/tests/unit/test_set_v2_user_type_script.py @@ -28,9 +28,11 @@ def __init__( self, previous_user_type: UserType = UserType.STANDARD, error: Exception | None = None, + email_failure: str | None = None, ) -> None: self.previous_user_type = previous_user_type self.error = error + self.email_failure = email_failure self.calls: list[dict] = [] def set_user_type_by_email( @@ -51,6 +53,7 @@ def set_user_type_by_email( last_seen_at=None, ), previous_user_type=self.previous_user_type, + email_failure=self.email_failure, ) @@ -68,6 +71,23 @@ def test_the_command_sets_a_type_and_says_what_changed(capsys) -> None: ] assert capsys.readouterr().out == ( f"Changed ada@example.test (user {USER_ID}) from standard to admin.\n" + "Emailed the user about the change.\n" + ) + + +def test_the_command_says_why_the_user_was_not_emailed(capsys) -> None: + user_types = FakeUserTypes(email_failure="no_verified_email") + + status = set_v2_user_type.main( + ["--email", "ada@example.test", "--user-type", "admin"], + user_type_service_factory=lambda: user_types, + ) + + # The change stands, so the command still succeeds. + assert status == 0 + assert capsys.readouterr().out == ( + f"Changed ada@example.test (user {USER_ID}) from standard to admin.\n" + "The user was not emailed: no_verified_email.\n" ) @@ -123,7 +143,7 @@ def test_the_command_refuses_missing_or_unknown_arguments(arguments) -> None: assert user_types.calls == [] -def test_the_command_emails_the_user_whose_type_it_changed(monkeypatch) -> None: +def test_the_command_emails_the_user_whose_type_it_changed(monkeypatch, capsys) -> None: """The command's own service emails the user, as the admin routes do.""" from policyengine_api.data.v2 import database from policyengine_api.fastapi_routes import dependencies @@ -168,3 +188,4 @@ def test_the_command_emails_the_user_whose_type_it_changed(monkeypatch) -> None: assert [(email["to"], email["template_alias"]) for email in sender.sent] == [ ("ada@auth0.test", "user-type-changed") ] + assert capsys.readouterr().out.endswith("Emailed the user about the change.\n") diff --git a/tests/unit/v2/test_admin_user_routes.py b/tests/unit/v2/test_admin_user_routes.py index b3f8536cc..26d699a19 100644 --- a/tests/unit/v2/test_admin_user_routes.py +++ b/tests/unit/v2/test_admin_user_routes.py @@ -401,3 +401,32 @@ def refuse(name: str, kwargs: dict): assert response.status_code == 422 assert response.json() == {"status": "error", "message": message} + + +def test_the_type_history_names_a_change_made_through_an_invitation() -> None: + def result(name: str, kwargs: dict): + if name == "list_user_type_changes": + return ( + UserTypeChangeRead( + id=CHANGE_ID, + user_id=TARGET_ID, + previous_user_type=UserType.STANDARD, + new_user_type=UserType.AUTHOR, + changed_by_user_id=OWNER_ID, + changed_by_email="alice@example.test", + source=UserTypeChangeSource.INVITATION, + created_at=LAST_SEEN_AT, + ), + ) + return _result(name, kwargs) + + client, _service = _client(RecordingService(result)) + + history = client.get(f"/v2/admin/users/{TARGET_ID}/user-type-changes") + + assert history.status_code == 200 + (item,) = history.json()["result"]["items"] + assert (item["source"], item["changed_by_user_id"]) == ( + "invitation", + str(OWNER_ID), + ) diff --git a/tests/unit/v2/test_me_routes.py b/tests/unit/v2/test_me_routes.py index bd2937ada..71e982bc3 100644 --- a/tests/unit/v2/test_me_routes.py +++ b/tests/unit/v2/test_me_routes.py @@ -702,5 +702,23 @@ def test_the_openapi_document_names_each_refused_acceptance_code() -> None: accept = document["paths"]["/v2/me/invitations/accept"]["post"] assert {"200", "401", "403", "409", "410", "422", "503"} <= set(accept["responses"]) + + def schemas(status: str) -> set[str]: + schema = accept["responses"][status]["content"]["application/json"]["schema"] + options = schema.get("anyOf", [schema]) + return {option["$ref"].rsplit("/", 1)[1] for option in options} + + # Only acceptance refusals answer 403 and 410, each with a code; 409 and + # 503 may also be a conflict with stored state or unavailable + # persistence, which carry none. + assert schemas("403") == schemas("410") == {"V2CodedErrorResponse"} + assert ( + schemas("409") + == schemas("503") + == { + "V2CodedErrorResponse", + "V2ErrorResponse", + } + ) for status in ("403", "409", "410", "503"): - assert "code" in str(accept["responses"][status]) + assert "code" in accept["responses"][status]["description"] diff --git a/tests/unit/v2/test_models.py b/tests/unit/v2/test_models.py index 9e88e395d..8d32cee5c 100644 --- a/tests/unit/v2/test_models.py +++ b/tests/unit/v2/test_models.py @@ -1096,10 +1096,11 @@ def test_user_invitations_hold_each_invitation_and_only_its_token_hash() -> None key.parent.name: (key.column.table.name, key.ondelete) for key in invitations.foreign_keys } - # Deleting the inviting or accepting user keeps the invitation. + # Deleting the inviting admin keeps the invitation; deleting the user who + # accepted it deletes it, so the address, theirs, goes with the account. assert foreign_keys == { "invited_by_user_id": ("users", "SET NULL"), - "accepted_by_user_id": ("users", "SET NULL"), + "accepted_by_user_id": ("users", "CASCADE"), } checks = { constraint.name: str(constraint.sqltext) @@ -1118,7 +1119,7 @@ def test_user_invitations_hold_each_invitation_and_only_its_token_hash() -> None if isinstance(constraint, sa.UniqueConstraint) } assert unique == {("token_hash",)} - # The users' indexes serve the SET NULL that each user deletion runs. + # The users' indexes serve what each user deletion runs on them. assert { tuple(column.name for column in index.columns) for index in invitations.indexes } == {("invited_by_user_id",), ("accepted_by_user_id",)} diff --git a/tests/unit/v2/test_user_invitation_service.py b/tests/unit/v2/test_user_invitation_service.py index 5fc58a44e..15d6b619c 100644 --- a/tests/unit/v2/test_user_invitation_service.py +++ b/tests/unit/v2/test_user_invitation_service.py @@ -421,9 +421,11 @@ def test_accepting_gives_the_invited_type_and_emails_the_user( "author", "invitation", ) - # Auth0's verified email was read once, before the change, and the - # type-change email goes there after the commit. - assert invitations.reader.profile_reads == [(BOB.subject,)] + # Auth0's verified email was read once by user ID, which Auth0 answers at + # once, unlike its search, before the change; the type-change email goes + # there after the commit. + assert invitations.reader.single_reads == [BOB.subject] + assert invitations.reader.profile_reads == [] assert invitations.sender.sent[-1] == { "to": BOB_EMAIL, "template_alias": "user-type-changed", @@ -649,3 +651,88 @@ def test_the_token_is_checked_before_the_inviter_and_the_email( invitations.reader.profiles[BOB.subject] = auth0_profile(BOB.subject, BOB_EMAIL) with pytest.raises(InvitationEmailMismatchError): _accept(invitations, token) + + +def test_deleting_an_account_deletes_the_invitations_it_accepted( + invitations: Invitations, +) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + invitations.sign_in(BOB, UserType.STANDARD) + _invite(invitations) + (token,) = invitations.sent_tokens() + _accept(invitations, token) + open_invitation = _invite(invitations, email="carol@example.test") + + V2AccountService( + AccountDatabaseSession(invitations.store.sessions), + auth0_user_deleter_factory=lambda: None, + ).delete_account(principal=BOB) + + # The accepted invitation held Bob's address; the open one is kept. + assert [invitation.id for invitation in invitations.invitations()] == [ + open_invitation.id + ] + + +class ResendingSender(RecordingEmailSender): + """Fail the first email after a resend has replaced its invitation's token.""" + + def __init__(self, invitations: Invitations) -> None: + super().__init__() + self.invitations = invitations + + def send_template(self, *, to, template_alias, template_model) -> None: + super().send_template( + to=to, template_alias=template_alias, template_model=template_model + ) + if len(self.sent) == 1: + (invitation,) = self.invitations.invitations() + self.invitations.service().resend_invitation( + principal=ALICE, invitation_id=invitation.id + ) + cause = "timeout" + raise EmailSendError(cause) + + +def test_a_send_isnt_recorded_over_a_resend_that_replaced_its_link( + invitations: Invitations, +) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + invitations.sender = ResendingSender(invitations) + + created = _invite(invitations) + + # The resend's successful send stands; the earlier link's failure is + # not recorded over it. + assert created.last_send_error is None + assert created.last_sent_at == NOW + (stored,) = invitations.invitations() + _earlier_token, later_token = invitations.sent_tokens() + assert stored.token_hash == _hash(later_token) + assert stored.last_send_error is None + + +class DeletingSender(RecordingEmailSender): + """Delete the invitation while its email is sent.""" + + def __init__(self, invitations: Invitations) -> None: + super().__init__() + self.invitations = invitations + + def send_template(self, *, to, template_alias, template_model) -> None: + super().send_template( + to=to, template_alias=template_alias, template_model=template_model + ) + with self.invitations.store.sessions.begin() as session: + for invitation in session.exec(select(UserInvitation)).all(): + session.delete(invitation) + + +def test_an_invitation_gone_before_its_send_is_recorded_is_not_found( + invitations: Invitations, +) -> None: + invitations.sign_in(ALICE, UserType.ADMIN) + invitations.sender = DeletingSender(invitations) + + with pytest.raises(InvitationNotFoundError): + _invite(invitations) diff --git a/tests/unit/v2/test_user_type_service.py b/tests/unit/v2/test_user_type_service.py index e0c0e449f..17c275e2f 100644 --- a/tests/unit/v2/test_user_type_service.py +++ b/tests/unit/v2/test_user_type_service.py @@ -588,7 +588,10 @@ def test_the_scripts_change_emails_the_user(store: V2Store) -> None: reader = StandInProfileReader([auth0_profile(BOB.subject, "bob@auth0.test")]) user_types = _emailing_user_types(store, sender, reader) - user_types.set_user_type_by_email( + scripted = user_types.set_user_type_by_email( + email="bob@example.test", user_type=UserType.ADMIN + ) + unchanged = user_types.set_user_type_by_email( email="bob@example.test", user_type=UserType.ADMIN ) @@ -603,6 +606,21 @@ def test_the_scripts_change_emails_the_user(store: V2Store) -> None: }, ) ] + assert scripted.email_failure is None + assert unchanged.email_failure is None + + +def test_the_script_learns_why_the_user_was_not_emailed(store: V2Store) -> None: + _signed_in_admin(store, ALICE) + _sign_in(store, BOB_WITH_EMAIL) + reader = StandInProfileReader() + + scripted = _emailing_user_types( + store, RecordingEmailSender(), reader + ).set_user_type_by_email(email="bob@example.test", user_type=UserType.AUTHOR) + + assert scripted.user.user_type is UserType.AUTHOR + assert scripted.email_failure == "no_verified_email" def test_an_unsent_type_change_email_leaves_the_change_committed( diff --git a/tests/unit/v2/user_email_support.py b/tests/unit/v2/user_email_support.py index c1213c274..dfe1f4dac 100644 --- a/tests/unit/v2/user_email_support.py +++ b/tests/unit/v2/user_email_support.py @@ -55,7 +55,9 @@ def __init__( ) -> None: self.profiles = {profile.user_id: profile for profile in profiles} self.failure = failure + # Reads of several users (Auth0's search) and of one user by ID. self.profile_reads: list[tuple[str, ...]] = [] + self.single_reads: list[str] = [] def read_user_profiles( self, @@ -74,6 +76,15 @@ def read_user_profiles( if user_id in self.profiles } + def read_user_profile( + self, user_id: str, *, wait_budget: RateLimitWaitBudget | None = None + ) -> Auth0UserProfile | None: + del wait_budget + self.single_reads.append(user_id) + if self.failure is not None: + raise self.failure + return self.profiles.get(user_id) + def search_user_ids_by_email(self, *_args: object, **_kwargs: object) -> object: msg = "invitations and type-change emails never search by email" raise AssertionError(msg) From f3f88bc562ec7595aee0ed5374fbfd536196781e Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:57:15 +0400 Subject: [PATCH 3/6] Document every 403 shape and test the invitation cascade as the runtime role - The acceptance route's 403 also documents a machine principal's refusal, which has no code. - A PostgreSQL test deletes, as the runtime role, an account that accepted an invitation, and the foreign key deletes that invitation. - Auth0 docstrings cover the read by ID, and the admin profile tests' stand-in reader has the protocol's new method. Co-Authored-By: Claude Opus 5.5 --- .../fastapi_routes/v2/me/user_type_routes.py | 6 ++- policyengine_api/libs/auth0_management.py | 11 ++--- .../test_v2_user_type_persistence.py | 43 +++++++++++++++++++ .../v2/test_admin_user_profile_service.py | 6 +++ tests/unit/v2/test_me_routes.py | 16 +++---- 5 files changed, 66 insertions(+), 16 deletions(-) diff --git a/policyengine_api/fastapi_routes/v2/me/user_type_routes.py b/policyengine_api/fastapi_routes/v2/me/user_type_routes.py index 6a460ae07..71c6e7286 100644 --- a/policyengine_api/fastapi_routes/v2/me/user_type_routes.py +++ b/policyengine_api/fastapi_routes/v2/me/user_type_routes.py @@ -60,11 +60,13 @@ def _invitation_service_factory( ), }, 403: { - "model": V2CodedErrorResponse, + # A machine (client-credentials) principal's refusal has no code. + "model": V2CodedErrorResponse | V2ErrorResponse, "description": ( "code email_mismatch: the signed-in user's verified email isn't the " "invited address, compared whole and ignoring case. The invitation " - "stays open." + "stays open. A machine (client-credentials) principal is also " + "refused with 403, without a code." ), }, 409: { diff --git a/policyengine_api/libs/auth0_management.py b/policyengine_api/libs/auth0_management.py index 81751de1e..5dc392c3f 100644 --- a/policyengine_api/libs/auth0_management.py +++ b/policyengine_api/libs/auth0_management.py @@ -125,8 +125,9 @@ class Auth0UserProfilesUnavailableError(Auth0ManagementError): Timeouts, connection errors, a refused or failed token request, a missing ``read:users`` permission (``http_403``), rate limiting (``http_429``, after at most one short wait), server errors (``http_500`` and so on) - and an answer that isn't a list of users all raise it, each with its - ``cause``. The message names at most that cause. + and an answer that isn't a list of users, or for a read by ID isn't that + user, all raise it, each with its ``cause``. The message names at most + that cause. """ @@ -150,7 +151,7 @@ def _seconds(value: str | None) -> float | None: @dataclass(frozen=True) class Auth0UserProfile: - """What the admin routes read about one Auth0 user; never stored. + """What the Public API reads about one Auth0 user; never stored. Each text is stripped, and absent when Auth0 sent none, sent an empty one or sent something other than text. ``email_verified`` is true only when @@ -268,7 +269,7 @@ def _profile_text(value: object, maximum_length: int) -> str | None: def _user_profile(payload: object) -> Auth0UserProfile | None: - """Read one user of a search answer, or ``None`` when it has no user ID.""" + """Read one user of an answer, or ``None`` when it has no user ID.""" if not isinstance(payload, dict): return None user_id = payload.get("user_id") @@ -310,7 +311,7 @@ def __init__( ``http_client`` replaces the per-request and per-operation clients (tests pass a mock transport), and ``secret_loader`` reads ``client_secret_resource`` when no direct secret is set. ``sleep`` - waits before a rate-limited search's retry, and ``clock`` gives the + waits before a rate-limited read's retry, and ``clock`` gives the current Unix time for Auth0's rate-limit reset. """ self._settings = settings diff --git a/tests/integration/test_v2_user_type_persistence.py b/tests/integration/test_v2_user_type_persistence.py index 84cba8969..59ca8e08b 100644 --- a/tests/integration/test_v2_user_type_persistence.py +++ b/tests/integration/test_v2_user_type_persistence.py @@ -694,3 +694,46 @@ def bob_accepts() -> None: # Alice is no longer an admin once Bob's turn comes, so it is refused. assert isinstance(outcomes.get("error"), InviterNotAdminError) assert _stored_types(sessions, [bob_id]) == ["standard"] + + +def test_deleting_an_account_deletes_the_invitations_it_accepted(sessions) -> None: + """The runtime role holds no DELETE on invitations; the foreign key cascades.""" + alice = _principal(sessions, "alice") + bob = _principal(sessions, "bob") + accounts = _accounts(sessions) + alice_id = accounts.get_account(principal=alice, country_id="us").id + accounts.get_account(principal=bob, country_id="us") + _store_type_as_superuser(alice_id, UserType.ADMIN) + postmark = RecordingPostmark() + auth0 = StandInAuth0( + Auth0UserProfile( + user_id=bob.subject, + email="bob@invited.example.test", + email_verified=True, + given_name=None, + family_name=None, + name=None, + ) + ) + invitations = _invitations(sessions, postmark, auth0) + accepted = invitations.create_invitation( + principal=alice, email="bob@invited.example.test", user_type=UserType.AUTHOR + ) + invitations.accept_invitation( + principal=bob, token=_sent_token(postmark), country_id="us" + ) + still_open = invitations.create_invitation( + principal=alice, email="other@invited.example.test", user_type=UserType.ADMIN + ) + + accounts.delete_account(principal=bob) + + with sessions() as session: + kept = set( + session.execute( + select(UserInvitation.id).where( + UserInvitation.id.in_([accepted.id, still_open.id]) + ) + ).scalars() + ) + assert kept == {still_open.id} diff --git a/tests/unit/v2/test_admin_user_profile_service.py b/tests/unit/v2/test_admin_user_profile_service.py index 083b1d1da..1abd13534 100644 --- a/tests/unit/v2/test_admin_user_profile_service.py +++ b/tests/unit/v2/test_admin_user_profile_service.py @@ -99,6 +99,12 @@ def read_user_profiles( if user_id in self.profiles } + def read_user_profile( + self, user_id: str, *, wait_budget: RateLimitWaitBudget | None = None + ) -> Auth0UserProfile | None: + msg = "admins' reads read users through the search, never one by ID" + raise AssertionError(msg) + def search_user_ids_by_email( self, text: str, diff --git a/tests/unit/v2/test_me_routes.py b/tests/unit/v2/test_me_routes.py index 71e982bc3..79559a17d 100644 --- a/tests/unit/v2/test_me_routes.py +++ b/tests/unit/v2/test_me_routes.py @@ -708,17 +708,15 @@ def schemas(status: str) -> set[str]: options = schema.get("anyOf", [schema]) return {option["$ref"].rsplit("/", 1)[1] for option in options} - # Only acceptance refusals answer 403 and 410, each with a code; 409 and - # 503 may also be a conflict with stored state or unavailable - # persistence, which carry none. - assert schemas("403") == schemas("410") == {"V2CodedErrorResponse"} + # Only acceptance refusals answer 410, each with a code; 403, 409 and 503 + # may also be a machine principal's refusal, a conflict with stored + # state or unavailable persistence, which carry none. + assert schemas("410") == {"V2CodedErrorResponse"} assert ( - schemas("409") + schemas("403") + == schemas("409") == schemas("503") - == { - "V2CodedErrorResponse", - "V2ErrorResponse", - } + == {"V2CodedErrorResponse", "V2ErrorResponse"} ) for status in ("403", "409", "410", "503"): assert "code" in accept["responses"][status]["description"] From be00e997eb099afd7694781c00c451bc5a94fd6c Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Fri, 13 Nov 2026 01:46:06 +0400 Subject: [PATCH 4/6] Apply the request size limit to every new write and update route tests - The dismiss and resend routes refuse bodies over 256 KiB with 413, like every other user write, before the service runs. - Existing tests that list routes and counts include the new routes: the v2 OpenAPI paths, the migration contract request counts, the v2 table count, and the oversized-body test, which now fills in {type_change_id}. Co-Authored-By: Claude Opus 5.5 --- .../v2/admin_invitations/routes.py | 1 + .../fastapi_routes/v2/me/user_type_routes.py | 1 + .../unit/test_migration_contract_artifacts.py | 4 ++-- tests/unit/v2/test_admin_invitation_routes.py | 21 +++++++++++++++++++ tests/unit/v2/test_import_side_effects.py | 2 +- tests/unit/v2/test_metadata_routes.py | 5 +++++ tests/unit/v2/test_user_write_limits.py | 7 ++++++- 7 files changed, 37 insertions(+), 4 deletions(-) diff --git a/policyengine_api/fastapi_routes/v2/admin_invitations/routes.py b/policyengine_api/fastapi_routes/v2/admin_invitations/routes.py index bc8289f0a..efe966c4a 100644 --- a/policyengine_api/fastapi_routes/v2/admin_invitations/routes.py +++ b/policyengine_api/fastapi_routes/v2/admin_invitations/routes.py @@ -197,6 +197,7 @@ def read() -> AdminInvitationPageResponse: def resend_invitation( invitation_id: UUID, principal: Annotated[AccountPrincipal, Depends(require_user)], + _size: Annotated[None, Depends(enforce_user_write_request_size)], ) -> AdminInvitationResponse | JSONResponse: def resend() -> AdminInvitationResponse: invitation = service_factory().resend_invitation( diff --git a/policyengine_api/fastapi_routes/v2/me/user_type_routes.py b/policyengine_api/fastapi_routes/v2/me/user_type_routes.py index 71c6e7286..0e5386194 100644 --- a/policyengine_api/fastapi_routes/v2/me/user_type_routes.py +++ b/policyengine_api/fastapi_routes/v2/me/user_type_routes.py @@ -167,6 +167,7 @@ def dismiss_type_change( type_change_id: UUID, _query: CountryQueryDependency, principal: Annotated[UserPrincipal, Depends(require_signed_in_user)], + _size: Annotated[None, Depends(enforce_user_write_request_size)], ) -> Response | JSONResponse: def dismiss() -> Response: service_factory().dismiss_type_change( diff --git a/tests/unit/test_migration_contract_artifacts.py b/tests/unit/test_migration_contract_artifacts.py index e8f5bcc1a..8d3359390 100644 --- a/tests/unit/test_migration_contract_artifacts.py +++ b/tests/unit/test_migration_contract_artifacts.py @@ -14,7 +14,7 @@ def test_migration_contract_payload_summarizes_route_contracts(): assert payload["metadata"] == { "route_group_count": 9, "workflow_count": 18, - "request_count": 97, + "request_count": 99, "db_entity_count": 6, "sim_flow_count": 3, } @@ -141,7 +141,7 @@ def test_user_contracts_require_a_signed_in_or_signed_out_credential(): headers_by_request = Counter(tuple(request["headers"]) for request in user_requests) assert headers_by_request == { - ("Authorization",): 24, + ("Authorization",): 26, ("PolicyEngine-Unauthenticated-User",): 23, ("Authorization", "PolicyEngine-Unauthenticated-User"): 1, } diff --git a/tests/unit/v2/test_admin_invitation_routes.py b/tests/unit/v2/test_admin_invitation_routes.py index 41b006942..3afa43189 100644 --- a/tests/unit/v2/test_admin_invitation_routes.py +++ b/tests/unit/v2/test_admin_invitation_routes.py @@ -2,6 +2,7 @@ from __future__ import annotations +import json from datetime import UTC, datetime from uuid import UUID @@ -281,3 +282,23 @@ def test_the_openapi_document_describes_the_invitation_routes() -> None: "404" in paths["/v2/admin/invitations/{invitation_id}/resend"]["post"]["responses"] ) + + +@pytest.mark.parametrize( + "path", + ["/v2/admin/invitations", f"/v2/admin/invitations/{INVITATION_ID}/resend"], +) +def test_invitation_writes_refuse_oversized_bodies_before_the_service( + path: str, +) -> None: + client, invitations, _user_types = _client() + body = json.dumps( + {"email": "ada@example.org", "user_type": "author", "pad": "x" * 262_144} + ) + + response = client.post( + path, content=body, headers={"Content-Type": "application/json"} + ) + + assert response.status_code == 413 + assert invitations.calls == [] diff --git a/tests/unit/v2/test_import_side_effects.py b/tests/unit/v2/test_import_side_effects.py index cbeae024e..88cb604b6 100644 --- a/tests/unit/v2/test_import_side_effects.py +++ b/tests/unit/v2/test_import_side_effects.py @@ -69,7 +69,7 @@ def reject_ddl(*args, **kwargs): import sys after = set(pathlib.Path.cwd().iterdir()) assert before == after -assert len(V2_METADATA.tables) == 47 +assert len(V2_METADATA.tables) == 48 assert "policyengine_api.data.v2.catalog.initialization" not in sys.modules assert "policyengine_api.data.v2.policy_migration_qualification" not in sys.modules assert "policyengine_api.data.v2.household_migration_qualification" not in sys.modules diff --git a/tests/unit/v2/test_metadata_routes.py b/tests/unit/v2/test_metadata_routes.py index ae8602905..d00e81aea 100644 --- a/tests/unit/v2/test_metadata_routes.py +++ b/tests/unit/v2/test_metadata_routes.py @@ -353,9 +353,14 @@ def test_openapi_references_explicit_resource_response_schemas() -> None: "/v2/me", "/v2/me/export", "/v2/me/upgrade", + "/v2/me/invitations/accept", + "/v2/me/type-changes/{type_change_id}/dismiss", "/v2/admin/users", "/v2/admin/users/{user_id}", "/v2/admin/users/{user_id}/user-type-changes", + "/v2/admin/invitations", + "/v2/admin/invitations/{invitation_id}", + "/v2/admin/invitations/{invitation_id}/resend", } assert set(schema["paths"]) == metadata_paths | native_paths assert "V2ErrorResponse" in schema["components"]["schemas"] diff --git a/tests/unit/v2/test_user_write_limits.py b/tests/unit/v2/test_user_write_limits.py index 85789a9b9..16c64c8cf 100644 --- a/tests/unit/v2/test_user_write_limits.py +++ b/tests/unit/v2/test_user_write_limits.py @@ -66,7 +66,12 @@ def _user_write_operations() -> list[tuple[str, str]]: client, _flask_calls = user_route_client(**factories) paths = client.get("/v2/openapi.json").json()["paths"] operations = [ - (method.upper(), path.replace("{association_id}", UUID_PATH_VALUE)) + ( + method.upper(), + path.replace("{association_id}", UUID_PATH_VALUE).replace( + "{type_change_id}", UUID_PATH_VALUE + ), + ) for path, methods in paths.items() if path.startswith(("/v2/me", "/v2/user-")) for method in methods From f48343bef1ae73bb12850b8b604ea72eea396d22 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:16:28 +0400 Subject: [PATCH 5/6] Check the bundle's default UK dataset in the Hugging Face credential test The required "Test environment variables" check failed on every pull request: the test asserted that the main branch of policyengine/populace-uk-private lists populace_uk_2023.h5, which it no longer does. The test now finds the installed bundle's default UK dataset, with the policyengine package's fallbacks and without importing that package, and lists the files at the revision the bundle pins. Applied unchanged from #4303, so both pull requests carry identical files. (cherry picked from commit 6191ddebf) Co-Authored-By: Claude Opus 5.5 --- .../uk-private-hugging-face-credential.md | 10 ++-- .../test_environment_variables.py | 60 +++++++++++++++---- 2 files changed, 56 insertions(+), 14 deletions(-) diff --git a/docs/engineering/uk-private-hugging-face-credential.md b/docs/engineering/uk-private-hugging-face-credential.md index 295be325c..d94b5c13b 100644 --- a/docs/engineering/uk-private-hugging-face-credential.md +++ b/docs/engineering/uk-private-hugging-face-credential.md @@ -46,10 +46,12 @@ Core reads that compatibility environment variable. `HUGGING_FACE_TOKEN` is not the name of the stored GitHub or Google Cloud credential. The pull-request environment check verifies the token identity, confirms that -it has no write permission, and checks both required private repositories. The -Cloud Run candidate resolver verifies that the exact deployed revision binds -`HUGGING_FACE_TOKEN` to `pe-uk-private-hf-read-token:latest`, without printing -the credential. +it has no write permission, and checks both required private repositories. For +the dataset repository it lists the files at the revision the installed bundle +pins for its default UK dataset and checks that the dataset's file is among +them, so the check follows bundle upgrades. The Cloud Run candidate resolver +verifies that the exact deployed revision binds `HUGGING_FACE_TOKEN` to +`pe-uk-private-hf-read-token:latest`, without printing the credential. The v2 catalog publication step of `.github/workflows/seed-v2-database.yml` also receives the organization secret as `HUGGING_FACE_TOKEN`, step-scoped. diff --git a/tests/env_variables/test_environment_variables.py b/tests/env_variables/test_environment_variables.py index e64a81578..4a11a451b 100644 --- a/tests/env_variables/test_environment_variables.py +++ b/tests/env_variables/test_environment_variables.py @@ -1,15 +1,17 @@ import os +from urllib.parse import quote import pytest import requests +from policyengine_api.constants import get_bundle_data_release + HUGGING_FACE_API_URL = "https://huggingface.co/api/whoami-v2" HUGGING_FACE_UK_DATA_MODEL_URL = ( "https://huggingface.co/api/models/policyengine/policyengine-uk-data-private" ) -HUGGING_FACE_UK_POPULATION_DATASET_URL = ( - "https://huggingface.co/api/datasets/policyengine/populace-uk-private" -) +HUGGING_FACE_REPOSITORY_API_URL = "https://huggingface.co/api" +HUGGING_FACE_REPOSITORY_TYPE_PATHS = {"model": "models", "dataset": "datasets"} EXPECTED_HUGGING_FACE_TOKEN_NAME = "pe-uk-private-hf-read-token" GITHUB_API_URL = "https://api.github.com/user" @@ -18,6 +20,33 @@ def do_not_run_in_debug(): return os.getenv("FLASK_DEBUG") == "1" +def uk_default_dataset_location() -> tuple[str, str, str, str]: + """Locate the bundle's default UK dataset: repository type and ID, path, revision. + + The default dataset is the national file UK simulations load when no + region-specific dataset applies. The location is resolved as the + ``policyengine`` package resolves it: a dataset entry without its own + repository, repository type or revision takes the data package's. The + bundled manifest is read without importing that package, whose import builds + both country models and contacts Hugging Face. + """ + release = get_bundle_data_release("uk") + default_dataset = release.get("default_dataset") + dataset_entry = release.get("datasets", {}).get(default_dataset) + assert dataset_entry is not None, ( + f"The bundle has no location for its default UK dataset {default_dataset}" + ) + data_package = release["data_package"] + return ( + dataset_entry.get("repo_type") or data_package.get("repo_type") or "model", + dataset_entry.get("repo_id") or data_package["repo_id"], + dataset_entry["path"], + dataset_entry.get("revision") + or data_package.get("release_manifest_revision") + or data_package["version"], + ) + + class TestEnvironmentVariables: """Tests for expiring environment variables.""" @@ -68,19 +97,30 @@ def test_hugging_face_token(self): } assert "local_authority_weights.h5" in uk_data_files - populace_response = requests.get( - HUGGING_FACE_UK_POPULATION_DATASET_URL, + # Hugging Face read permission covers a whole repository, so listing the + # files at the pinned revision checks the credential's access and that + # the pinned file exists at that revision. + repository_type, repository_id, dataset_path, dataset_revision = ( + uk_default_dataset_location() + ) + dataset_response = requests.get( + f"{HUGGING_FACE_REPOSITORY_API_URL}" + f"/{HUGGING_FACE_REPOSITORY_TYPE_PATHS[repository_type]}/{repository_id}" + f"/revision/{quote(dataset_revision, safe='')}", headers=headers, timeout=10, ) - assert populace_response.status_code == 200, ( + assert dataset_response.status_code == 200, ( "The shared API and simulation runtime token cannot read " - f"policyengine/populace-uk-private: {populace_response.text}" + f"{repository_type} repository {repository_id} " + f"at revision {dataset_revision}: {dataset_response.text}" ) - populace_files = { - sibling["rfilename"] for sibling in populace_response.json()["siblings"] + dataset_files = { + sibling["rfilename"] for sibling in dataset_response.json()["siblings"] } - assert "populace_uk_2023.h5" in populace_files + assert dataset_path in dataset_files, ( + f"{repository_id} at revision {dataset_revision} has no {dataset_path}" + ) @pytest.mark.skipif( do_not_run_in_debug(), From a4819771ae0179c10a8af8e7183f6b0d02937628 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:30:11 +0400 Subject: [PATCH 6/6] Name the invitations revision in its unit test, and note its regeneration The invitations revision's contents test found its file by the head revision's ID, so it would read the wrong file once another revision lands on it, as the shared reports test did in this merge. It now uses its own USER_INVITATIONS_REVISION constant. The revision's docstring also says that generating it again from 94dc43079186 gives the same operations, as the Alembic skill doc and the shared reports revision say of theirs. Co-Authored-By: Claude Opus 5.5 --- .../f519a77ba122_invite_users_and_dismiss_type_changes.py | 3 ++- tests/unit/v2/test_alembic_v2_revisions.py | 6 +++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/migrations/v2/versions/f519a77ba122_invite_users_and_dismiss_type_changes.py b/migrations/v2/versions/f519a77ba122_invite_users_and_dismiss_type_changes.py index aac36cd99..54e68cb31 100644 --- a/migrations/v2/versions/f519a77ba122_invite_users_and_dismiss_type_changes.py +++ b/migrations/v2/versions/f519a77ba122_invite_users_and_dismiss_type_changes.py @@ -7,7 +7,8 @@ Generated on 0c136a278f29; its down_revision moved to 1e1e3f079f2c when the withheld area codes revision reached master first, and to 94dc43079186 when -the shared reports revision did. +the shared reports revision did. Generating it again from 94dc43079186 gives +the same operations. Adds user_invitations, one row per admin's invitation for an email address to become an author or admin: the address, the type, the SHA-256 digest of its diff --git a/tests/unit/v2/test_alembic_v2_revisions.py b/tests/unit/v2/test_alembic_v2_revisions.py index 93240e165..2c484b86d 100644 --- a/tests/unit/v2/test_alembic_v2_revisions.py +++ b/tests/unit/v2/test_alembic_v2_revisions.py @@ -66,6 +66,8 @@ # The shared reports revision, on the withheld area codes revision, and parent # of the user invitations revision. SHARED_REPORTS_REVISION = "94dc43079186" +# The user invitations revision, on the shared reports revision. +USER_INVITATIONS_REVISION = "f519a77ba122" def test_v2_revision_chain_has_generated_policy_and_user_identity_changes() -> None: @@ -1086,7 +1088,9 @@ def test_user_invitations_revision_adds_its_table_and_the_dismissal_column() -> name because Alembic compares checks by name only. The downgrade undoes each, and neither writes data. """ - (path,) = (REPO / "migrations/v2/versions").glob(f"{V2_ALEMBIC_HEAD_REVISION}_*.py") + (path,) = (REPO / "migrations/v2/versions").glob( + f"{USER_INVITATIONS_REVISION}_*.py" + ) revision = path.read_text(encoding="utf-8") upgrade = revision[ revision.index("def upgrade()") : revision.index("def downgrade()")