Repository navigation
Invite users by email, email every type change, and report the latest change on /v2/me - #4297
Merged
Merged
Conversation
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 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
…me 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 <noreply@anthropic.com>
Keeps both sides' route dependency imports, and regenerates the migration contracts from the merged registry. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## master #4297 +/- ##
==========================================
+ Coverage 93.48% 93.60% +0.11%
==========================================
Files 369 387 +18
Lines 21478 22380 +902
Branches 3401 3543 +142
==========================================
+ Hits 20079 20948 +869
- Misses 816 843 +27
- Partials 583 589 +6
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
3 tasks
Keeps both sides in the user-type service, the service protocols, the testing skill's module list, the route list test and the type script's tests, where master's new import check sits next to the branch's email tests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings in admins' account deletion (#4272) and budget-window reports (#4290). Keeps both sides in the user-type service's and validators' docstrings, the account service protocol (dismissal and admin deletion), the Stage 12A doc's account of the user-type change lock, and the runtime role's persistence tests, whose module now holds both sides' tests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Master gained the withheld area codes revision 1e1e3f079f2c (#4305) on 0c136a278f29, this branch's revision's parent, so f519a77ba122's down_revision moves to 1e1e3f079f2c, as 0c136a278f29's did; generating it again from 1e1e3f079f2c gives the same operations. The head constant, the revision-chain and revision tests, the invitations revision's integration tests and the Alembic skill doc follow it, keeping both sides' sections and tests. Two counts that both sides had raised by the same amount, and Git merged silently, now combine: 49 v2 tables, and 101 migration contract requests (the contracts are regenerated). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…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 6191dde) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Master gained the shared reports revision 94dc43079186 (#4303) on 1e1e3f079f2c, this branch's revision's parent, so f519a77ba122's down_revision moves to 94dc43079186; generating it again from 94dc43079186 gives the same operations. The head constant, the revision-chain and revision tests, the invitations revision's integration tests, and the rollback order in the Alembic skill doc and the Stage 9 and Stage 12A runbooks follow it, keeping both sides' sections and tests. Both sides had raised the v2 table count from 48 to 49, which Git merged silently; with both tables it is 50. With both sides' revision tests, tests/unit/v2/test_alembic_v2.py reached 1,504 lines, over the 1,500-line limit for test code. The revision order test and each revision's contents test, with the constants and helpers they use, move unchanged to tests/unit/v2/test_alembic_v2_revisions.py; the Alembic environment's tests stay. The v2 Alembic lifecycle script, its workflow test and the testing guide's commands name the new module. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tion 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 <noreply@anthropic.com>
anth-volk
marked this pull request as ready for review
November 16, 2026 17:58
anth-volk
added a commit
that referenced
this pull request
Nov 16, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
anth-volk
added a commit
that referenced
this pull request
Nov 16, 2026
…branch Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This branch was previously deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #4292
Summary
Admins invite an email address to become an author or admin, and the signed-in invitee accepts once Auth0 reports their verified email matching the address. Every committed type change emails the user through Postmark, and
GET /v2/mereports the latest change until the user dismisses it. The Public API stores no user's email and adds none to access tokens: the invitee's and each user's email are read from Auth0's Management API through the existing read-only profile reader (build_auth0_user_profile_reader). Acceptance reads the invitee with a newread_user_profile,GET /api/v2/users/{id}, which Auth0 answers at once, rather than the user search, which may not yet see someone who signed up or verified their email moments ago. The settings code of the Auth0 management module moves unchanged toauth0_management_settings, which it re-exports, to keep it under 800 lines.Schema
f519a77ba122on1e1e3f079f2c, no post-generation changes. It was generated on0c136a278f29; whenmastergained the withheld area codes revision (Record the UK area codes disclosure control withholds from a report run #4305) on the same parent, itsdown_revisionmoved to1e1e3f079f2c, and generating it again from that revision gives identical operations. It addsuser_invitationsanduser_type_changes.dismissed_at, and renames the source check tock_user_type_changes_source_allowed, which also allowsinvitation(Alembic compares checks by name only). Deleting the inviting admin keeps an invitation (SET NULL); deleting the user who accepted it deletes it (CASCADE), since its address was theirs.TABLE_ACCESS: the runtime role reads, inserts and updatesuser_invitations(never deletes), and updates onlyuser_type_changes.dismissed_at.admin_routeorscript, so there an admin's read of the type history of a user who accepted an invitation answers 500. The downgrade dropsuser_invitationsanddismissed_atand fails while any change's source isinvitation.Routes
POST /v2/admin/invitations{email, user_type}(201),GET /v2/admin/invitations?offset=&limit=,POST /v2/admin/invitations/{invitation_id}/resend,DELETE /v2/admin/invitations/{invitation_id}(204): admins only, every write under the user-type change lock. Inviting an address again revokes its open invitation; resending replaces the token and the 7-day expiry. A failed send leaves the invitation open withlast_send_error.POST /v2/me/invitations/accept?country_id={token}: reads the caller's Auth0 profile first (503auth0_unavailable), then in one transaction under the lock checks the token (410invitation_not_found,invitation_revoked,invitation_accepted,invitation_expired), the inviting admin (409inviter_not_admin), verification (409email_not_verified) and the address, whole and ignoring case (403email_mismatch). It never lowers a type, and records a change with sourceinvitationand the inviting admin. Refusals carry acodenext tostatusandmessage.GET /v2/me:result.latest_type_change(id,previous_user_type,user_type,changed_at) until dismissed;POST /v2/me/type-changes/{type_change_id}/dismiss?country_id=(204).Emails
scripts/set_v2_user_type.py) the user is emailed at their first verified Auth0 email; an acceptance reuses the address it read. The script says whether it emailed the user, and why not. Postmark'sPOST /email/withTemplate, template aliasesuser-invitationanduser-type-changed,outboundstream; a timeout, connection error, 429 or 5xx is retried, three attempts in all, after 0.5 s and 1 s.user_type_change_email_not_sent(v2 user ID and cause only) oruser_invitation_email_not_sent(invitation ID and cause). Without Postmark settings nothing is sent.Docs and contracts
Stage 12A doc (routes, emails, settings, Postmark operator steps, rollback), the Alembic and testing skills, OpenAPI descriptions, the regenerated migration contracts (
GET /v2/megains the stable fieldresult.latest_type_change; the accept and dismiss routes are added), and a changelog fragment.Settings and their wiring
The Postmark setup (C3 · 14) created the values in both GitHub environments: production on 2026-11-13, staging on 2026-11-16. Each setting is optional and all-or-none; with none set the Public API sends nothing and records a WARNING, and partial or invalid values fail readiness and the deploy validation.
POSTMARK_SERVER_TOKEN_SECRET_RESOURCEstagingandproductionenvironments, naming a Secret Manager version:projects/policyengine-api/secrets/policyengine-api-staging-postmark-server-token/versions/latestand…-prod-postmark-server-token/versions/latest. The token itself is in Secret Manager (projectpolicyengine-api, automatic replication).push.ymljobsdeploy-cloud-run-staging(environment: staging) anddeploy-cloud-run-candidate(environment: production), job-levelenv:→ the "Deploy tagged Cloud Run … candidate" step inherits it →deploy_cloud_run_candidate.shrunsvalidate_cloud_run_deploy_env.shand passes it in--set-env-vars→ the revision's environment →load_postmark_settings→ read from Secret Manager when an email is sent, as the revision's runtime service accountroles/secretmanager.secretAccessorfor its environment's runtime account:policyengine-api-cr-staging@for staging,policyengine-api-cr-runtime@for production, the accounts the current Cloud Run services run as. Unverified: Cloud Run's own read of the secret, until this PR deploys.POSTMARK_SENDER_ADDRESSstagingandproductionPolicyEngine <hello@policyengine.org>POLICYENGINE_APP_URLstagingandproductionhttps://app.policyengine.org. Staging: the Vercel preview of PolicyEngine/policyengine-app-v2#1562, the app's half of this work, since there is no staging app address; it needs a new value once #1562 merges.POSTMARK_SERVER_TOKENload_postmark_settings; no workflow or deploy script passes itAcceptance and type-change emails also use the existing
AUTH0_USER_PROFILES_*settings andPUBLIC_API_AUTH_ISSUER; this PR changes nothing in how they reach the revision.release-testsreceives none of the new settings.Postmark, as set up in C3 · 14: each server has the templates
user-invitationanduser-type-changedon theoutboundstream, and one test email per template per server, sent with the token read from Secret Manager, was delivered. Two limits remain:@policyengine.orgaddresses and refuses others with error code 412. The Public API records such a refusal aspostmark_412and doesn't retry it.Inline suppressions added
# noqa: S105on the two constants that name the Postmark token's environment variables: ruff reads a constant named…TOKEN…as a hard-coded secret; it is a variable name, as for the Auth0 constants. The two Auth0 constants' existing# noqa: S105moved, unchanged, with the settings code toauth0_management_settings.# noqa: BLE001four times in the email service module: the sender factory, the send, the profile source factory and the Auth0 profile read. A committed type change or invitation must not fail because its email can't be sent, whatever the error; each failure is recorded by cause instead.# noqa: BLE001in one integration test, which keeps the waiting acceptance's error for the assertion, as the neighbouring lock tests do.# type: ignore[assignment]in one unit test, which sets the stand-in sender to None to play "no Postmark settings".Testing
masteris merged in, most recently atd7042b226(Serve household reports through /v2/reports #4293, Answer 400 for a household calculation whose policy can't be read #4279, Log refused economy requests at WARNING instead of ERROR #4220, Run reports again and list their runs in /v2/reports #4298 and Record the UK area codes disclosure control withholds from a report run #4305). Record the UK area codes disclosure control withholds from a report run #4305's revision shares this PR's parent, so this PR's revision moved onto it (see Schema). Two counts that both sides had raised by the same amount, and Git merged silently, now add up: 49 v2 tables in the import side-effects test, and 101 requests in the migration contracts, regenerated from the merged registry.master's), and the oversized-body test, which now fills in{type_change_id}too; the dismiss and resend routes apply the 256 KiB request limit like every other write./v2/meroute contracts, the account service's latest change and dismissal, the user-type service's and the script's emails, the models, privileges, revision chain, readiness, the deploy validation and deploy script,push.yml, the app workflow contracts; and on disposable PostgreSQL 17 the revision's upgrade from1e1e3f079f2cand refused downgrade, and as the runtime role the whole invitation flow, dismissal, the deletion of an accepted invitation with its account, and an acceptance that waits on the user-type change lock while its admin is demoted.ruff check,ruff format --check,mypy(configured scope),lint-imports,python -m scripts.rules validate,python scripts/run_quality_guards.py,python scripts/export_migration_contracts.py(committed output), the changelog fragment check, andalembic checkagainst the upgraded database (no differences).mypynow also checkspolicyengine_api/libs/auth0_management_settings.pyandpolicyengine_api/libs/postmark_email.py, so theapi.quality.mypy-v2rule inrules/registry.tomlnames them (the rendered rules docs are regenerated).mypyon the changedpolicyengine_api/data/v2model module reports onlycall-overloadforsa_type=sa.DateTime(timezone=True), the convention every v2 timestamp column uses (49 such errors indata/v2/modelson master, 54 with the five new columns); the typecheck job skips that package.🤖 Generated with Claude Code