Merge feature/v0.18.0-email-webhook-hygiene

v0.18.0 — email + webhook hygiene per the proposal at
~/git/ohm-infra/RFC-APP-EMAIL-HYGIENE-PROPOSAL.md. All five
slices ship; 295 tests passing.

CHANGELOG.md

@@ -23,6 +23,733 @@ skip versions are the composition of each intervening adjacent
 release's steps in order — no A-to-B path is pre-computed beyond
 that.
 
+## 0.18.0 — 2026-05-28
+
+**Minor — schema migration required; one env var now mandatory; no
+new secrets.** This release lands the framework-side half of OHM
+roadmap items #18 (Secure the SMTP relay + Gitea webhook) and #20
+(Email deliverability). It is the framework counterpart to the
+operator-side SMTP / DNS hardening covered in the
+`EMAIL-AND-WEBHOOK-HARDENING-RUNBOOK.md` companion doc.
+
+The release is shipped in five atomic slices per the v0.18.0 proposal:
+
+1. **`build_envelope` shared helper.** A single place where every
+   outbound `EmailMessage` is constructed. Lands the
+   deliverability-critical headers (`Date`, `Message-ID`,
+   `Auto-Submitted`) uniformly across OTC, invite, watcher
+   notification, bundle, and digest paths; exposes per-kind
+   unsubscribe semantics (none for OTC, mailto: for invites, full
+   one-click for bulk-adjacent paths) as explicit kwargs.
+2. **Migrated send paths.** `email_otc.py`, `email_invite.py`,
+   `email._deliver`, `email._send_bundle`, and `digest.py` now
+   build their envelopes through the helper. Per-RFC invite
+   (v0.16.0) rides through `email_invite.py`'s helper and picks
+   up the change for free. The shared `_SENT` test buffer also
+   carries the constructed `EmailMessage` under `envelope["message"]`
+   so tests can assert on the header surface directly.
+3. **Webhook handler tightening.** `GITEA_WEBHOOK_SECRET` is now
+   mandatory at startup — the framework refuses to load_config()
+   if it's empty, unless the operator explicitly opts into the
+   dev-bypass with `RFC_APP_INSECURE_WEBHOOKS=1`. The
+   `/api/webhooks/gitea` receiver carries defense-in-depth checks
+   that surface the misconfiguration loudly at the request layer
+   too. Mis-targeted webhooks (a hook on a fork or a stale Gitea
+   binding) now log at INFO instead of silently 200-OK'ing.
+4. **`outbound_emails` audit table + admin endpoint.** Every send
+   helper writes one row to `outbound_emails` before returning,
+   capturing the send attempt regardless of outcome
+   (status='sent' / 'failed' / 'deferred'). The new admin endpoint
+   `GET /api/admin/outbound-emails` (filterable by kind / status /
+   to_address) lets the operator answer "did this person ever get
+   their invite?" without grepping VM logs. No admin UI ships
+   with v0.18.0; operator queries via curl + jq for now.
+5. **Bounce correlation.** The `POST /api/webhooks/email-bounce`
+   body accepts a new optional `message_id` field; when supplied,
+   the handler stamps status='bounced' on the matching
+   `outbound_emails` row and returns the row id as
+   `correlated_id`. The pre-existing hard-bounce ->
+   `email_opt_out_all = 1` flow still fires.
+
+The `POST /api/email/unsubscribe` endpoint also lands in Slice 2
+as the matching receiver for the new `List-Unsubscribe-Post:
+List-Unsubscribe=One-Click` header (Gmail and Yahoo POST that
+payload on the user's one-click action per RFC 8058 — the GET
+endpoint alone is no longer sufficient for senders at OHM's tier).
+
+### Added
+
+- **`backend/app/email_envelope.py`** — the `build_envelope` helper.
+  Single source of truth for every outbound `EmailMessage`'s
+  headers + body shape. Standalone module so tests can exercise it
+  without booting the FastAPI app.
+- **`backend/migrations/020_outbound_emails.sql`** — the audit
+  table. Single new table with three indexes (to_address, sent_at,
+  message_id); no changes to existing tables.
+- **`email.record_outbound(...)`** — best-effort write helper every
+  send path calls. Catches `RuntimeError` (so pure-helper unit
+  tests where `db.init()` was never called don't break) and any
+  other exception (so the audit write never breaks a send).
+- **`GET /api/admin/outbound-emails`** in `api_admin.py` —
+  admin-only listing of `outbound_emails`. Newest-first, filterable
+  by kind, status, and to_address (case-insensitive). Returns
+  `{items: [...], has_more}` per the rest of the admin endpoints'
+  shape.
+- **`POST /api/email/unsubscribe`** in `api_notifications.py` —
+  RFC 8058 one-click receiver. Accepts the same `?t=` token as the
+  GET handler; idempotent; returns 200 + `{ok, category}` on
+  success.
+- **`all` synthetic category** for unsubscribe URLs. Used by the
+  bundle + digest paths (which can't honor per-category opt-outs
+  because they span multiple categories); flips
+  `email_opt_out_all = 1` rather than a per-category column.
+
+### Changed
+
+- **`backend/app/email.py`** — `EmailConfig` gains
+  `unsubscribe_mailto` (env: `EMAIL_UNSUBSCRIBE_MAILTO`, default
+  falls back to `EMAIL_FROM`). `_deliver` and `_send_bundle`
+  build envelopes through `build_envelope` and thread `kind` +
+  `notification_id` into the audit write.
+- **`backend/app/email_otc.py`** + **`email_invite.py`** — both
+  call `build_envelope` and `record_outbound`. OTC carries no
+  `List-Unsubscribe` (recipient explicitly requested the code);
+  invite carries `List-Unsubscribe: <mailto:…>` only (no signed
+  URL — the invitee isn't a user yet, no per-user opt-out row
+  exists).
+- **`backend/app/digest.py`** — calls `_deliver` with `kind='digest'`
+  + the new `all`-category one-click unsubscribe.
+- **`backend/app/webhooks.py`** — refuses 500 at request time if
+  the secret is empty + bypass isn't set; logs a loud warning
+  per-request when running under the bypass; logs INFO when a
+  hook targets a repo not in `cached_rfcs`.
+- **`backend/app/config.py`** — `load_config()` raises
+  RuntimeError if `GITEA_WEBHOOK_SECRET` is empty unless
+  `RFC_APP_INSECURE_WEBHOOKS=1`.
+- **`backend/app/api_notifications.py`** — GET unsubscribe handler
+  accepts the `all` category (sets `email_opt_out_all = 1`).
+  Bounce webhook body adds optional `message_id` field; response
+  shape adds `correlated_id` field. (Tests that read the exact
+  response shape — currently just
+  `test_bounce_webhook_refuses_unsigned_when_secret_configured`
+  in test_e2e_smoke.py — updated to assert on the new shape.)
+- **`backend/tests/test_propose_vertical.py`** — the shared
+  `tmp_env` fixture binds a fake `GITEA_WEBHOOK_SECRET` so all
+  252 pre-v0.18.0 tests boot cleanly under the new mandatory
+  secret. Tests that want to exercise the dev-bypass path
+  monkeypatch `RFC_APP_INSECURE_WEBHOOKS=1` explicitly.
+
+### Tests
+
+- 15 new unit tests in `test_email_envelope.py` for the helper.
+- 10 new integration tests across `test_otc_vertical`,
+  `test_admin_create_user_invite_vertical`, and
+  `test_notifications_vertical` covering: OTC has no
+  List-Unsubscribe; invite has mailto: only; notification has
+  full one-click; POST one-click flips per-category; `all` flips
+  global; respects `EMAIL_UNSUBSCRIBE_MAILTO` override.
+- 7 new integration tests in `test_webhooks_vertical.py` covering
+  the startup-time mandatory-secret check, the dev-bypass, and
+  the request-time signature verification including the unknown-
+  repo log line.
+- 11 new integration tests in `test_outbound_emails_vertical.py`
+  covering the audit table write path (OTC / invite / notification),
+  the admin endpoint (list, filter by kind, filter by to_address,
+  non-admin refusal), and the bounce correlation (matched
+  message_id stamps status='bounced'; unknown message_id is
+  logged; absent message_id falls back to legacy behavior; bounced
+  rows surface in admin endpoint with `?status=bounced`).
+- One test updated for intentional response-shape change:
+  `test_e2e_smoke.test_bounce_webhook_refuses_unsigned_when_secret_configured`.
+
+Full suite: 295 passed (was 252 pre-v0.18.0).
+
+### Migration
+
+- **`backend/migrations/020_outbound_emails.sql`** — auto-applied
+  on next backend start. Single new table with three indexes; no
+  changes to existing tables.
+
+### Upgrade steps (from 0.17.0)
+
+- Operators **MUST** ensure `GITEA_WEBHOOK_SECRET` is set in the
+  deployment's env. The framework now refuses to start if it's
+  empty. (For OHM-flotilla deployments,
+  `flotilla secret list <deployment>` confirms the binding; OHM
+  has carried this binding since v0.14.0, so the upgrade is
+  gesture-free for OHM specifically.)
+- Operators **MAY** set `RFC_APP_INSECURE_WEBHOOKS=1` to bypass
+  the requirement in local-dev environments. Production
+  deployments **MUST NOT** set this; if they do, every webhook
+  POST logs a loud warning line per request.
+- Operators **MAY** set `EMAIL_UNSUBSCRIBE_MAILTO` to route
+  `List-Unsubscribe: <mailto:…>` opt-out courtesy mail to a
+  humans-monitored mailbox distinct from the no-reply
+  `EMAIL_FROM` sender. Default falls back to `EMAIL_FROM`.
+- You **MUST** apply schema migration
+  `020_outbound_emails.sql`. The migration creates a single new
+  table with three indexes; the framework runs migrations
+  automatically at process start, so no manual step is required
+  beyond restarting the backend so the migration runner picks
+  the file up. Existing deployments pick it up on first start
+  after upgrade with no operator action required.
+- You **MUST** rebuild the frontend and restart the backend
+  after upgrading. `frontend/package.json#version` and `VERSION`
+  both move to `0.18.0`. No new secrets (the `outbound_emails`
+  table writes synchronously to the same SQLite file as every
+  other write).
+- Operators **SHOULD** run a `mail-tester.com` probe against the
+  upgraded deployment to confirm the new envelope headers
+  (`Date`, `Message-ID`, `Auto-Submitted`, `List-Unsubscribe`,
+  `List-Unsubscribe-Post`) land cleanly with the upstream SMTP
+  relay's DKIM signing. The expected delta from pre-v0.18.0 is
+  +2-3 points on the spam-score axis (typical 5-6/10 baseline
+  → 9+/10 post-upgrade).
+
+
+## 0.17.0 — 2026-05-28
+
+**Minor — schema migration required; no new env vars; no new secrets.**
+This release lands admin-create user with role assignment + invite
+email (roadmap item #16, §6.1). From the v0.9.0 `/admin/users` surface,
+an admin can now type first name, last name, email, role, and an
+optional custom message; the framework provisions the `users` row with
+the chosen role and `permission_state='granted'` (the admin's hand is
+the grant) and sends an invite email carrying a single-use claim link.
+The invitee clicks through to `/invites/claim?token=…`, the token is
+verified and consumed, the session is established, and the user is
+routed to the passcode-set screen (per v0.10.0) on first sign-in.
+
+Distinct from #12 (which ships in parallel in this wave): #12 is
+per-RFC contribution/discussion membership and uses
+`rfc_invitations` (slot 018). v0.17.0 is platform-level access
+provisioning by an admin and uses `user_invite_tokens` (slot 019).
+Both can coexist; both surface in the same SMTP relay but with
+distinct email templates.
+
+Design decisions documented inline (see `backend/app/invites.py`'s
+module docstring + the migration's header comment):
+
+  * **Token shape: opaque DB token, not JWT.** 256 bits of CSPRNG
+    entropy (`secrets.token_urlsafe(32)`), bcrypt-hashed at rest.
+    Opaque chosen over JWT because revocation is then a single SQL
+    UPDATE — admin-issued invites are exactly the kind of thing an
+    admin should be able to yank back without rotating a signing
+    key. The raw token only ever lives in the outbound email link
+    and the inbound claim body.
+  * **TTL: 7 days, hard-coded constant** (`INVITE_TOKEN_TTL_DAYS`
+    in `backend/app/invites.py`). Env-var configurability is a
+    §19.2 candidate; the constant is exposed as a single point of
+    edit if a deployment wants to override.
+  * **Immediate send, no admin-review-then-send queue.** Matches
+    how the v0.9.0 beta-request admin notification works (single
+    SMTP path). Admin-preview-before-send is a future enhancement.
+  * **Bulk-invite (CSV paste) deferred.** v0.17.0 is one-at-a-time;
+    a follow-up release can layer bulk on top of the same
+    `POST /api/admin/users` body shape with minimal disruption.
+  * **OTC skipped on first sign-in.** Per the roadmap: clicking the
+    unique token in the email is itself proof of email control, so
+    the claim flow signs the invitee in directly. Subsequent
+    sign-ins go through the standard OTC / passcode paths.
+  * **No `users` table changes.** The brief floated
+    `first_sign_in_at` / `last_seen_at IS NULL` as the
+    "(pending invite)" discriminator, but the existing
+    `users.last_seen_at` column is NOT NULL with a `datetime('now')`
+    default (migrations/001) and no `first_sign_in_at` column
+    exists. Rather than land a schema migration to introduce one,
+    the discriminator is the existence of an active (not-claimed,
+    not-expired) row in `user_invite_tokens` joined on
+    `invited_user_id`. The admin user-listing carries a
+    `pending_invite` field populated via that join; on claim, the
+    badge clears naturally as the invite row's `claimed_at`
+    populates.
+  * **Admin-create vs. self-flip refusals.** Self-invite is refused
+    422 (use the role-change channel for self-edits). Duplicate
+    email is refused 409 (use the existing role / grant gestures on
+    the existing user). Owner-grant by a non-owner admin is refused
+    422 (§6.1's owner-zero is the only owner bootstrap path; the
+    sitting owner must issue the invite).
+
+### Added
+
+- **`POST /api/admin/users`** (`backend/app/api_admin.py`) — admin-only.
+  Body: `{ email, first_name?, last_name?, role, custom_message? }`.
+  Provisions the `users` row with the chosen role and writes the
+  `user_invite_tokens` row + dispatches the invite email + writes a
+  `permission_events` row with `event_kind='user_invited'`. Returns
+  `{ ok, invite_id, invited_user_id, email, role }` on success;
+  surfaces the four refusals (403/422/409/422) per their distinct
+  paths.
+- **`GET  /api/admin/users/invites`** — admin-only. Lists active
+  (not claimed, not expired) invites with the admin who created them
+  joined through for display. Powers the "I sent these but they
+  haven't been claimed yet" admin view.
+- **`POST /api/invites/claim`** (`backend/app/main.py` — alongside
+  `/auth/otc/verify` and `/auth/device-trust/start` since it shares
+  the device-trust cookie helpers). Anonymous-reachable. Body:
+  `{ token, trust_device? }`. Validates the token, consumes the
+  invite row, signs the user in, optionally mints a device-trust
+  cookie, and returns `{ ok, user, needs_passcode }`. The
+  `needs_passcode` hint drives the frontend's route-to-passcode-set
+  vs. route-to-home decision. Maps token-failure modes to distinct
+  HTTP statuses: expired/claimed → 410, unknown/invalid → 400.
+- **`backend/app/invites.py`** — the create + claim + list module.
+  Mirrors the `device_trust.py` shape: opaque-token issuance with
+  bcrypt-at-rest, candidate-set walk on lookup, dataclass-bracketed
+  outcomes (`CreateOutcome` / `ClaimOutcome` / `PendingInviteRow`).
+  Carries the `INVITE_TOKEN_TTL_DAYS = 7` constant and the
+  `CUSTOM_MESSAGE_MAX_LENGTH = 500` mirror of the API-side bound.
+- **`backend/app/email_invite.py`** — sibling of `email_otc.py`. Reuses
+  `EmailConfig.from_env()` for the SMTP plumbing + From identity;
+  composes a separate template (subject "You're invited to <app> by
+  <admin>"; body names the inviter, embeds the optional custom
+  message in a clearly-delimited indented block if present, and
+  carries the claim URL). Dev / no-SMTP path logs the envelope to
+  the shared `_SENT` buffer so backend tests can assert on the
+  outbound shape.
+- **Schema migration `019_user_invite_tokens.sql`** — new
+  `user_invite_tokens` table (id, email, role, first_name, last_name,
+  custom_message, token_hash, expires_at, created_at,
+  created_by_admin_id, claimed_at, claimed_by_user_id,
+  invited_user_id). Three indexes: unique on `token_hash`
+  (documents the no-collision invariant); `(email, claimed_at)` for
+  the "is this email already invited?" pre-check; and
+  `(created_by_admin_id, created_at DESC)` for the per-admin
+  invites listing. Slot 018 is reserved for the parallel #12
+  release shipping in the same wave; slot 016 stays
+  reserved-and-skipped per Session K's v0.9.0 integration.
+- **`frontend/src/components/InviteClaim.jsx`** — the
+  `/invites/claim?token=…` landing page. Reads the token from the
+  URL, renders a "Claim my account" CTA with an optional
+  "trust this device for 30 days" checkbox, calls
+  `POST /api/invites/claim` on submit, and routes onward
+  (`/settings/notifications#sign-in` if `needs_passcode`, else `/`)
+  on success. Anonymous-reachable.
+- **"Create user + invite" affordance** on `/admin/users`
+  (`frontend/src/components/Admin.jsx`). A header button opens a
+  modal with email / first / last / role / custom-message inputs
+  (the textarea shows a "chars left" counter against the 500-char
+  ceiling). On submit, the modal calls
+  `POST /api/admin/users` and refreshes the user listing.
+- **Amplitude wiring** (per `ohm-rfc/ROADMAP.md` #21 Part C, shipped
+  inline with v0.17.0): `USER_INVITED` event fires from
+  `CreateUserInviteModal` on successful invite-send with
+  `{ target_user_id, initial_role, custom_message_chars }` — the
+  OHM `invited_user_id` returned by `POST /api/admin/users`
+  becomes the dashboard's binding for the future Amplitude user
+  record; `custom_message_chars` is a coarse signal of admin
+  effort (0 = template-only, 1+ = personalized) and carries no
+  PII. `INVITE_CLAIMED` event fires from `InviteClaim.jsx` on
+  successful claim with `{ invited_by_admin_id, initial_role,
+  needs_passcode, trust_device }` — BUT the claim handler first
+  calls `identify({ user_id, properties: { claim_method:
+  'admin-invite', invited_at (setOnce), invited_by_admin_id
+  (setOnce), initial_role (setOnce) } })` so the Amplitude user
+  record is created with the OHM user_id from the very first
+  event the invitee fires, never as an anonymous device that
+  retroactively links. setOnce semantics preserve the original
+  invite context even if the invitee later changes roles.
+- **"(pending invite)" badge** inline on the user-listing's
+  per-row handle (rendered when the row's `pending_invite` field
+  is populated by the backend's join through `user_invite_tokens`).
+  Clears automatically on claim as the invite row's `claimed_at`
+  populates.
+
+### Changed
+
+- **`backend/app/api_admin.py`** — imports `invites` + `email_invite`
+  + `EmailConfig`; adds the two new endpoints alongside the existing
+  `set_role` / `set_permission` neighbors; extends `list_users` to
+  join through `user_invite_tokens` and emit the `pending_invite`
+  field on each row. The new `CreateUserInviteBody` pydantic model
+  carries the body bounds (320-char email, 120-char first/last,
+  regex-pinned role, 500-char custom_message) so malformed input
+  fails at the body bound (422) instead of at the SQL layer.
+- **`backend/app/main.py`** — imports `invites as invites_mod`;
+  adds the `InviteClaimBody` pydantic model alongside
+  `PasscodeVerifyBody`; mounts the `POST /api/invites/claim`
+  endpoint in the OAuth router so it can reuse the
+  `_set_device_trust_cookie` helper.
+- **`frontend/src/api.js`** — exports `createUserInvite()`,
+  `listUserInvites()`, `claimInvite()`. Same fetch shape as the
+  rest of the v0.9.0 / v0.10.0 admin neighborhood.
+- **`frontend/src/App.jsx`** — imports `InviteClaim`; registers the
+  `/invites/claim` route alongside `/beta-pending` (both are
+  anonymous-reachable auth-shape landings).
+
+### Migration
+
+- **`backend/migrations/019_user_invite_tokens.sql`** — auto-applied
+  on next backend start. Single new table with three indexes; no
+  changes to existing tables.
+
+### Upgrade steps (from 0.14.0)
+
+- You **MUST** apply schema migration `019_user_invite_tokens.sql`.
+  The migration creates a single new table with three indexes; the
+  framework runs migrations automatically at process start, so no
+  manual step is required beyond restarting the backend so the
+  migration runner picks the file up.
+- You **MUST** rebuild the frontend and restart the backend after
+  upgrading. `frontend/package.json#version` and `VERSION` both
+  move to `0.17.0`. No new env vars; no new secrets (the invite
+  email rides the existing SMTP relay configured for v0.7.0's OTC
+  mail).
+- You **MAY** announce the new admin-create gesture to existing
+  admins. Existing user rows are unaffected — the
+  `user_invite_tokens` table is empty post-migration, and the
+  user-listing's new `pending_invite` field is null on every
+  existing row. The bootstrap shape for the very first admin
+  account stays the v0.9.0 path (DB-level role flip on an OTC-
+  provisioned row); the v0.17.0 admin-create gesture works
+  end-to-end once at least one admin exists.
+
+
+## 0.16.0 — 2026-05-28
+
+**Minor — schema migration auto-applied; no operator action.** This
+release lands the owner-only invite for per-RFC PR or PR-less
+discussion (roadmap item #12). The RFC's owner can now invite
+specific users by email to one of two per-RFC roles —
+`contributor` (open PRs against the RFC AND join its discussion) or
+`discussant` (join the discussion only). Non-invited users keep
+the v0.6.0 anonymous-read contract: they can read but cannot
+write/discuss that RFC. Invitations are token-encoded in a
+transactional email; acceptance lands a per-RFC collaborator row
+and surfaces in the admin user-management page (additive on the
+existing `/api/admin/users` shape) so the platform-grant decision
+has the per-RFC context to inform it. The platform-level grant
+remains the admin's call — this release adds a per-RFC membership
+layer beneath it, not a new platform-grant path.
+
+The per-RFC write gate is layered on top of the existing
+`require_contributor` (v0.8.0) gate, not in place of it: a user
+must be platform-granted AND hold an accepted per-RFC role (or
+be the RFC owner / a platform admin/owner) to write. A super-
+draft with no frontmatter owners yet (pre-§13.1 claim) falls
+through to the platform-granted contract — there's no owner to
+issue invitations, so the gate is open until one exists. This
+preserves the v0.6.0 / v0.7.0 / v0.8.0 contracts inside their
+domains and confines item #12's change to "an RFC has owners →
+those owners decide who writes."
+
+### Added
+
+- **`backend/migrations/018_rfc_invitations.sql`** — two tables.
+  `rfc_invitations` carries the lifecycle row (issued, accepted,
+  revoked, expired) with the opaque token the email link encodes,
+  the inviter, the invitee email, the role-in-RFC, and the 30-day
+  expiry. `rfc_collaborators` is the accepted-invitation
+  substrate — the compact (rfc, user, role) shape the write gate
+  consults. Both tables are FK-cascaded against `cached_rfcs` and
+  `users` per §5's cascade rules. Indexed for the owner's listing,
+  the accept-by-token lookup, and the per-user read.
+- **`backend/app/api_invitations.py`** — the §17 surface. Five
+  endpoints: `POST /api/rfcs/{slug}/invitations` (create + email),
+  `GET /api/rfcs/{slug}/invitations` (owner's listing),
+  `POST /api/rfcs/{slug}/invitations/{id}/revoke`,
+  `GET /api/invitations/accept?token=…` (preview), and
+  `POST /api/invitations/accept` (redeem). The email reuses
+  `EmailConfig.from_env()` and the `_SENT` buffer the OTC and
+  notification mailers share — transactional, no preferences
+  honored, no unsubscribe footer. A failure to send does NOT
+  roll back the row; the owner has the token on the listing
+  surface for an out-of-band share.
+- **`backend/app/auth.py`** — four helpers. `is_rfc_owner`
+  reads the frontmatter `owners_json`. `is_rfc_collaborator`
+  reads the v0.16.0 `rfc_collaborators` table. `can_discuss_rfc`
+  and `can_contribute_to_rfc` are the composite predicates the
+  write endpoints consult (platform admin/owner OR no-owners-yet
+  fall-through OR RFC owner OR per-RFC collaborator at the right
+  role). `can_invite_to_rfc` is the issue-side predicate (RFC
+  owner or platform admin/owner only — collaborators don't get
+  invite power).
+- **`frontend/src/components/InvitationsModal.jsx`** — the RFC
+  owner's surface: an email input + role picker for sending,
+  and a status table for listing/revoking. Visible only to the
+  RFC's owner or a platform admin/owner (the backend gates the
+  endpoints regardless).
+- **`frontend/src/components/AcceptInvitation.jsx`** — the
+  `/invitations/accept?token=…` landing page. Previews what the
+  invitation grants, refuses on email mismatch / revoked /
+  expired with a single sentence each, redirects to the RFC's
+  view on accept.
+- **API client (`frontend/src/api.js`)** — five new helpers:
+  `listRFCInvitations`, `createRFCInvitation`,
+  `revokeRFCInvitation`, `previewInvitation`, `acceptInvitation`.
+- **Amplitude wiring** (per `ohm-rfc/ROADMAP.md` #21 Part C, shipped
+  inline with v0.16.0): `INVITATION_SENT` event fires from
+  `InvitationsModal.jsx` on successful send with `{ rfc_slug,
+  role_in_rfc }`; `INVITATION_ACCEPTED` event fires from
+  `AcceptInvitation.jsx` on successful accept with the same shape —
+  but the accept path first calls `identify({ user_id, properties:
+  { invited_at (setOnce), last_invited_to_rfc,
+  last_invite_role_in_rfc, claim_method: 'rfc-invite' } })` so the
+  Amplitude user record carries the invite context from the moment
+  of acceptance. No invitee email or other PII enters the event
+  body — only the slug, role, and the inviter's identity (through
+  the standard signed-in identify on the inviter's session).
+
+### Changed
+
+- **`backend/app/api.py`** — registers
+  `api_invitations.make_router()` alongside the existing routers.
+- **`backend/app/api_discussion.py`** — `POST .../discussion/threads`
+  and `POST .../discussion/threads/{thread_id}/messages` now compose
+  the new `auth.can_discuss_rfc` predicate after the existing
+  `require_contributor` check. A platform-granted user without a
+  per-RFC discussion role on an RFC with owners gets 403 with
+  "This RFC's owner has not invited you to its discussion."
+- **`backend/app/api_branches.py`** — `POST .../promote-to-branch`
+  and `POST .../start-edit-branch` now compose
+  `auth.can_contribute_to_rfc`. Same shape: platform-granted but
+  uninvited → 403.
+- **`backend/app/api_prs.py`** — `POST .../open-pr` also composes
+  `auth.can_contribute_to_rfc` so a user whose per-RFC role was
+  revoked between branch-cut and PR-open is refused at the
+  ship line.
+- **`backend/app/api_admin.py`** — `GET /api/admin/users` carries
+  a new `rfc_invitations` array per user (empty if none), naming
+  each accepted per-RFC collaboration with the RFC slug/title,
+  the role, the inviter, and the timestamp. Additive — the
+  existing v0.9.0 columns are unchanged; consumers that don't
+  read the new field see the legacy shape.
+- **`frontend/src/App.jsx`** — registers the
+  `/invitations/accept` route (visible to anonymous + signed-in
+  viewers; signed-out viewers see a sign-in prompt).
+- **`frontend/src/components/RFCView.jsx`** — additive
+  "Invitations" button in the RFC header strip, visible to RFC
+  owners and platform admins/owners on both super-drafts and
+  active RFCs. Mounts the new modal on click.
+- **`backend/tests/test_propose_vertical.py`** — adds the
+  `grant_rfc_collaborator` test helper so v0.5.0/v0.6.0/v0.8.0-era
+  tests that exercise non-owner contribution can opt into the new
+  invitation contract without rewriting their setup.
+- **`backend/tests/test_pr_flow_vertical.py`,
+  `backend/tests/test_graduation_vertical.py`,
+  `backend/tests/test_e2e_smoke.py`** — three tests that signed in
+  as non-owner contributors now seed an accepted per-RFC
+  collaborator row first (mirroring the production invite→accept
+  dance). The test intent is unchanged; the precondition is now
+  explicit.
+
+### Migration
+
+- **`018_rfc_invitations.sql`** — auto-applied on backend start by
+  the existing `db.run_migrations()` sweep. The two new tables
+  are empty at upgrade time; no existing data is touched. No
+  operator gesture needed.
+
+### Upgrade steps (from 0.15.0, or 0.14.0 if 0.15.0 is skipped)
+
+- You **MUST** rebuild the frontend and restart the backend after
+  upgrading so the new endpoints, the migration, the gate
+  composition in `api_discussion`/`api_branches`/`api_prs`, and the
+  new frontend routes/components are picked up. `frontend/package.json#version`
+  and `VERSION` both move to `0.16.0`.
+- You **MUST NOT** set any new env var — there are no new secrets
+  and no new overlay keys. The email path reuses the existing
+  `SMTP_HOST` / `SMTP_PORT` / `SMTP_USER` / `SMTP_PASSWORD` /
+  `EMAIL_FROM` / `EMAIL_FROM_NAME` / `APP_URL` / `EMAIL_ENABLED`
+  variables that the v0.7.0 OTC and v0.5.0 notification paths
+  already require. Deployments that have those wired need no
+  configuration change.
+- You **MUST NOT** apply the migration manually — the backend's
+  migration runner picks up `018_rfc_invitations.sql` on next
+  start. (If you've configured an external migration tool, run it
+  before starting the backend; the framework's own runner is
+  idempotent against already-applied migrations.)
+- You **SHOULD** inform existing RFC owners that they can now
+  invite collaborators from the RFC view's header strip. RFCs
+  with frontmatter owners that pre-date this release see no
+  behavioral change for the owner; the change is visible to
+  non-owner contributors who previously could write on any RFC
+  and now must be invited first.
+- You **MAY** seed `rfc_collaborators` rows directly via SQL for
+  pre-existing per-RFC working relationships you want to
+  grandfather past the v0.16.0 cutover. The `invitation_id`
+  column is nullable for exactly this purpose. Production
+  deployments without that history can ignore this option.
+## 0.15.0 — 2026-05-28
+
+**Minor — no schema migration; one new build-time env var bound via
+`flotilla overlay set`.** This release ships Amplitude Analytics +
+Session Replay instrumentation (roadmap item #13). The frontend
+gains a small wrapper around `@amplitude/unified` that gates SDK
+initialization on the v0.13.0 cookie/privacy consent — the SDK is
+never loaded for visitors who have not granted analytics consent,
+no session is recorded, no network request fires; a later consent
+flip to `denied` calls `setOptOut(true)` so events and session
+replay stop immediately. The wrapper exposes a stable taxonomy of
+nine events (Page Viewed, RFC Viewed, User Signed In / Signed Out,
+RFC Proposed, PR Opened, Comment Posted, Beta Access Requested, Admin
+Permission Decision) wired into the existing routes, the Login flow,
+the propose / open-PR / discussion / PR-review surfaces, and the
+admin grant/revoke action. Event bodies carry only ids and enums; no
+free-text fields (titles, comment bodies, names, emails) are ever
+sent. **Session replay** records sessions at `sampleRate: 1` (100%)
+— vendor-recommended default; gated by the same v0.13.0 analytics
+consent. The Amplitude API key is read from `VITE_AMPLITUDE_API_KEY`
+at build time; when unset, the wrapper logs one console warning and
+no-ops so dev environments without analytics keep working. No backend
+events ship in this release — Amplitude SaaS holds the events,
+nothing lands in our DB, no migration.
+
+### Added
+
+- **Analytics wrapper** (`frontend/src/lib/analytics.js`). Public
+  surface: `track(name, props)`, `identify({ user_id, properties? })`,
+  `setUserProperties(properties)`, `anonymize()`, the `EVENTS`
+  taxonomy constant, and a `__resetForTests` helper. Internally
+  lazy-imports `@amplitude/unified` and calls
+  `amplitude.initAll(API_KEY, { analytics: { autocapture: true },
+  sessionReplay: { sampleRate: 1 } })` only after consent is
+  granted; queues pre-init calls and drains them on init resolve;
+  flips `setOptOut(true)` on a granted→denied consent change (stops
+  both analytics events and session replay). The wrapper subscribes
+  to `onConsentChange()` so a freshly-banner-clicked "analytics on"
+  flips the SDK live without a page reload.
+- **User identity lifecycle** (per `ohm-rfc/ROADMAP.md` #21 Part C —
+  shipped inline with v0.15.0 instead of waiting for a follow-up).
+  `identify({ user_id, properties })` accepts a property bag that
+  applies as an Amplitude `Identify` event with `.set()` semantics
+  by default; values wrapped as `['__setOnce__', value]` apply with
+  `.setOnce()` semantics (immutable after first write — for
+  account-history markers like `first_sign_in_at`). The new
+  `setUserProperties(properties)` exposes the same property-apply
+  path for mid-session state changes (role grant/revoke, passcode
+  set, device trusted) so the Amplitude record stays current without
+  waiting for the next sign-in. `anonymize()` now clears both the
+  user_id binding AND the pending-property cache so a subsequent
+  sign-in as a different user starts with a fully fresh slate.
+- **Event taxonomy** wired into the app:
+  - `Page Viewed` — fires from `App.jsx` on every route change with
+    `path` (`location.pathname`); the location hook owns the firing
+    and dedupes by path.
+  - `RFC Viewed` — fires from `RFCView.jsx` once per slug load with
+    `rfc_slug` and `rfc_id`.
+  - `User Signed In` — fires from `Login.jsx` with
+    `method ∈ { 'otc', 'passcode', 'trust-device' }` matching the
+    three sign-in paths from v0.7.0 / v0.10.0 / v0.11.0.
+  - `User Signed Out` — fires from `App.jsx`'s "Sign out" click,
+    followed by `anonymize()` to clear the SDK's user binding before
+    the hard nav to `/auth/logout`.
+  - `RFC Proposed` — fires from `ProposeModal.jsx` on submit success
+    with `rfc_slug`.
+  - `PR Opened` — fires from `PRModal.jsx` on submit success with
+    `rfc_slug` and `pr_number`.
+  - `Comment Posted` — fires from `RFCDiscussionPanel.jsx`
+    (`surface: 'discussion'`) and from `PRView.jsx`
+    (`surface: 'pr'`, with `pr_number`) on each post-success.
+  - `Beta Access Requested` — fires from `Login.jsx` capture-profile
+    submit success. No PII in the event.
+  - `Admin Permission Decision` — fires from `Admin.jsx`'s grant /
+    revoke action with `action ∈ { 'grant', 'revoke' }` and
+    `target_user_id` (string).
+- **User binding + properties** (`App.jsx`): when `me.authenticated`
+  lands and a user id is available, the wrapper's
+  `identify({ user_id, properties })` is called with
+  `String(viewer.id)` AND a durable property bag — `role`,
+  `permission_state`, `passcode_set`, `device_trusted` (mutable;
+  refresh each sign-in), plus `first_sign_in_at` and
+  `account_created_at` (setOnce — immutable user-history markers).
+  The sign-out gesture calls `anonymize()` before the nav. No email,
+  display name, gitea_login, or other PII is passed through the SDK —
+  Amplitude only sees opaque ids, enums, timestamps, booleans.
+- **`@amplitude/unified`** dependency added to
+  `frontend/package.json` (analytics + session replay in one
+  install). Lockfile updated.
+- **`VITE_AMPLITUDE_API_KEY`** documented in `frontend/.env.example`
+  with the secret-vs-overlay binding caveat (see below).
+
+### Changed
+
+- **`frontend/src/App.jsx`** — adds `useLocation` for the route-change
+  Page Viewed firing, a `lastUserIdRef` memo to call
+  `identify` once per signed-in viewer, and an `onClick` handler on
+  the "Sign out" link that fires `User Signed Out` + `anonymize()`
+  before the hard nav.
+- **`frontend/src/components/Login.jsx`** — fires `User Signed In`
+  with the appropriate `method` at each of the three sign-in points
+  (trust-device cookie path, passcode verify success, OTC verify
+  success), and fires `Beta Access Requested` on capture-profile
+  submit success.
+- **`frontend/src/components/ProposeModal.jsx`** — fires `RFC Proposed`
+  with `rfc_slug` on submit success.
+- **`frontend/src/components/RFCView.jsx`** — fires `RFC Viewed`
+  inside the `getRFC` resolution so the event is keyed on the slug
+  param and includes the loaded `rfc_id`.
+- **`frontend/src/components/PRModal.jsx`** — fires `PR Opened` with
+  `rfc_slug` and `pr_number` on submit success.
+- **`frontend/src/components/RFCDiscussionPanel.jsx`** — fires
+  `Comment Posted` with `surface: 'discussion'` on send-success.
+- **`frontend/src/components/PRView.jsx`** — fires `Comment Posted`
+  with `surface: 'pr'` and `pr_number` on review-comment success.
+- **`frontend/src/components/Admin.jsx`** — fires
+  `Admin Permission Decision` on grant/revoke success.
+
+### Migration
+
+- **No schema migration.** Amplitude SaaS holds the events; the
+  framework's DB is unchanged. Migration slot **015** is unused by
+  this release and remains available for the next minor that needs a
+  schema bump.
+
+### Caveat — overlay binding for `VITE_AMPLITUDE_API_KEY`
+
+Amplitude browser API keys are embedded in the frontend bundle at
+build time and visible to anyone with browser dev tools. They are
+public by design — same nature as the v0.12.0
+`VITE_TURNSTILE_SITE_KEY` (also public, also bundle-embedded,
+explicitly contrasted with `CLOUDFLARE_TURNSTILE_SECRET` which is
+the real secret-half of that pair). The Amplitude installation
+guidance from the vendor shows the key inline as a literal string
+argument to `initAll(…)`, confirming the public framing. This
+release accordingly binds the value via `flotilla overlay set`,
+not `flotilla secret set` — the env-var name is `VITE_AMPLITUDE_API_KEY`
+(Vite-prefix convention, so the build picks it up directly without
+an alias step).
+
+(Roadmap row #13 originally said "new secret: AMPLITUDE_API_KEY";
+that wording predated vendor consultation. Mid-Session-L the
+operator provisioned the Amplitude project, surfaced the vendor's
+recommended init prompt, and the binding settled as overlay. The
+roadmap row will be updated to match when #13 ships.)
+
+### Caveat — session replay scope and consent
+
+This release enables Amplitude Session Replay at `sampleRate: 1`
+(100% of sessions recorded for full-DOM playback). The vendor's
+installation wizard recommends this default for new deployments —
+maximum learning during the early phase. The v0.13.0 single
+"analytics" consent toggle gates session replay together with
+events, so no recording happens without explicit opt-in. A future
+release **MAY** split this into a separate consent category for
+session replay specifically (recording has a meaningfully larger
+privacy footprint than event counters); §19.2 candidate.
+
+### Upgrade steps (from 0.14.0)
+
+- You **MUST** install the new frontend dependency before building:
+  `cd frontend && npm install` picks up `@amplitude/unified` from
+  the updated `frontend/package.json` and the refreshed
+  `package-lock.json`. The lockfile change is committed.
+- You **MUST** rebuild the frontend after upgrading so the analytics
+  wrapper and its consent gate ship to viewers. `frontend/package.json#version`
+  and `VERSION` both move to `0.15.0`. No schema migration; the
+  backend is unchanged for this release.
+- **MUST**: before deploying, the operator runs `/Users/benstull/projects/wiggleverse/ohm-rfc-app-flotilla/.venv/bin/ohm-rfc-app-flotilla overlay set ohm-rfc-app VITE_AMPLITUDE_API_KEY=<key>` to bind the Amplitude project's public API key. (Receiving the value in the conversation is fine — it's bundle-embedded by design, same as `VITE_TURNSTILE_SITE_KEY`.) The deploy **SHOULD NOT** proceed before this binding exists; if the binding is absent, the frontend's analytics wrapper no-ops with a console warning and the rest of the app continues to function — but no events or session replays are sent.
+- You **MAY** leave `VITE_AMPLITUDE_API_KEY` unset in dev environments
+  — the wrapper detects the empty value and no-ops with a single
+  console warning. The app, the consent banner, and every other
+  surface keep working unchanged.
+- You **SHOULD** verify after deploy that the Amplitude dashboard
+  receives events and a session replay when a consenting browser
+  exercises one of the taxonomy events (the easiest probe: open the
+  deployed site in an Incognito window, accept analytics on the
+  consent banner, navigate to an RFC, and watch the project's live
+  event stream + replay panel).
+
 ## 0.14.0 — 2026-05-28
 
 **Minor — no operator action required; new optional env var.** This
@@ -197,6 +924,264 @@ consent infrastructure is wired so item #13 (v0.15.0) can read from
   (because their `cookie_consent` row does not yet exist); their
   current sessions remain valid.
 
+## 0.12.0 — 2026-05-28
+
+**Minor — operator action required (new secret + new overlay).**
+CloudFlare Turnstile gates the email-entry step of the OTC sign-in
+flow against automated abuse (roadmap item #10, SPEC §6.2 / §19.2-
+settled). Since v0.7.0 made `/auth/otc/request` the primary human-
+auth path and v0.8.0 opened the request endpoint to any valid email,
+the OTC dispatch became the natural target for distributed scrapers
+fanning out to harvest "this email is admitted vs. this email is
+not" timing/bounce signals. The per-email cooldown stops the trivial
+back-to-back loop; the Turnstile challenge stops the distributed one
+by costing the attacker a browser-side proof-of-humanness on every
+request. The challenge runs before the bcrypt hash + SMTP send so a
+failed verify spends no rate budget and produces no envelope.
+
+Scope: the widget renders on the email-entry step of `/login` only.
+The OTC verify step (where the user pastes the six-digit code) is
+already bottlenecked on email delivery and protected by the
+five-minute TTL + single-use consume on the row; a second challenge
+there would double the rate budget against the same abuse path
+without measurably more protection. If bots adapt to defeat the
+email-entry challenge specifically — pushing the abuse vector onto
+the verify step — a future release adds the second widget. The
+widget also renders on the passcode step's "Use a code instead"
+fallback dispatch since that route also calls `/auth/otc/request`.
+
+Default policy: `TURNSTILE_REQUIRED=false`. The gate stays open when
+the secret is absent — the dev / test path, and the pre-rollout
+path while the operator is wiring the secret. Once the secret is in
+GCP Secret Manager and the site key is in the overlay, the operator
+**MAY** flip `TURNSTILE_REQUIRED=true` so a future config drift on
+the secret fails loudly (HTTP 500 "auth misconfigured") instead of
+silently disabling abuse defense.
+
+No schema migration — Turnstile siteverify is stateless.
+
+### Added
+
+- **`backend/app/turnstile.py`** — the siteverify caller. POSTs
+  `secret` + `response` (+ optional `remoteip`) to
+  `https://challenges.cloudflare.com/turnstile/v0/siteverify` and
+  returns a `VerifyOutcome` (`ok` boolean + `reason` enum:
+  `ok` / `skipped` / `misconfigured` / `missing-token` / `failed` /
+  `network`). Tunables read from env at call time so tests
+  monkeypatch cleanly: `CLOUDFLARE_TURNSTILE_SECRET`,
+  `TURNSTILE_REQUIRED`, and (test-only) `TURNSTILE_SITEVERIFY_URL`.
+- **`frontend/src/components/TurnstileWidget.jsx`** — the React
+  wrapper around the official CloudFlare Turnstile JS API. Reads the
+  site key from `import.meta.env.VITE_TURNSTILE_SITE_KEY`; renders
+  nothing when the var is unset (the form still submits and the
+  backend's `TURNSTILE_REQUIRED` policy decides admission). Loads
+  the CloudFlare script once per page on first widget mount. Cleans
+  up the widget instance on unmount via `turnstile.remove()` so a
+  remount produces a fresh challenge rather than reusing a stale,
+  already-consumed token.
+- **Backend tests** (`backend/tests/test_turnstile_vertical.py`) —
+  five vertical scenarios: happy path (secret + valid token →
+  admit), siteverify rejects → 400 + no envelope, missing-token →
+  400 + no envelope, missing-secret-soft (default) → admit, and
+  missing-secret-hard (`TURNSTILE_REQUIRED=true`) → 500
+  "misconfigured". All five mock the siteverify HTTP call via
+  `monkeypatch.setattr(turnstile.httpx, "post", …)`; no real
+  CloudFlare keys are ever embedded.
+- **SPEC `§6.2`** — names the Turnstile gate on the OTC dispatch as
+  the v0.12.0 settled shape; the §19.2 candidate from v0.7.0 closes.
+
+### Changed
+
+- **`backend/app/main.py`** — `OtcRequestBody` grows an optional
+  `turnstile_token` field. The `/auth/otc/request` handler calls
+  `turnstile.verify_token` first, before `otc.request_code`, so a
+  failed challenge spends no rate budget and produces no envelope.
+  The handler maps `misconfigured` → HTTP 500, all other failures
+  (`missing-token`, `failed`, `network`) → uniform HTTP 400 so the
+  response does not enumerate which leg of the challenge broke.
+- **`frontend/src/api.js`** — `requestOtc` accepts a second arg
+  `{ turnstileToken }` and threads it into the request body. The
+  positional signature stays backwards-compatible so calls that pass
+  only an email still type-check.
+- **`frontend/src/components/Login.jsx`** — the email step and the
+  passcode step both render `<TurnstileWidget>`. The submit button
+  on the email step is disabled until the widget produces a token
+  (when the widget is enabled at build time); the "Use a code
+  instead" link on the passcode step has the same gate. A 400 from
+  `/auth/otc/request` clears the token and surfaces a "couldn't
+  verify you're human, please retry" status. The fallback-from-
+  passcode path bounces back to the email step on 400 so the user
+  gets a fresh challenge in the natural place.
+- **`backend/.env.example`** — documents `CLOUDFLARE_TURNSTILE_SECRET`
+  and `TURNSTILE_REQUIRED` alongside the existing OTC tunables.
+- **`frontend/.env.example`** — documents `VITE_TURNSTILE_SITE_KEY`
+  with the operator wire-up procedure (dash.cloudflare.com →
+  Turnstile → Add site).
+
+### Upgrade steps (from 0.10.0)
+
+The operator **MUST** create a CloudFlare Turnstile site
+(dash.cloudflare.com → Turnstile → Add site, choose "Managed" widget
+mode), obtain the site key (public) and secret key (private), and:
+
+- You **MUST** `flotilla secret set ohm-rfc-app CLOUDFLARE_TURNSTILE_SECRET`
+  (paste the secret key when prompted) before the v0.12.0 deploy.
+  The framework reads the secret at request time; deploying v0.12.0
+  without the secret leaves the gate in its default soft-fail state
+  (every request admitted regardless of token), which means abuse
+  defense is silently off.
+- You **MUST** `flotilla overlay set ohm-rfc-app VITE_TURNSTILE_SITE_KEY <site-key>`
+  so the frontend build embeds the site key and the widget renders
+  on `/login`. The site key is public — it travels in the bundle and
+  appears in every browser — so this is the overlay (non-secret)
+  layer per the §3 invariant 1 split. Skipping this step leaves
+  `/login` with no widget; even after the operator sets the secret,
+  the backend would refuse every request as `missing-token` once
+  `TURNSTILE_REQUIRED=true` flips.
+- You **MUST** rebuild the frontend and restart the backend after
+  upgrading. `frontend/package.json#version` and `VERSION` both move
+  to `0.12.0`. No schema migration; Turnstile siteverify is
+  stateless. The site-key embed is build-time, so the rebuild after
+  the `flotilla overlay set` is what actually wires the widget into
+  the bundle the deploy serves.
+- You **MAY** `flotilla overlay set ohm-rfc-app TURNSTILE_REQUIRED true`
+  once you've confirmed a real sign-in works end-to-end with the
+  widget. The default (`false`) keeps the gate in soft-fail mode so
+  a missing-secret regression admits requests rather than 500ing
+  every sign-in attempt; flipping to `true` makes a future config
+  drift on the secret fail loudly with HTTP 500 instead of silently
+  disabling abuse defense. The framework's tested path is the
+  flipped-to-true production shape; the default `false` exists for
+  the dev / pre-rollout window only.
+- You **MAY** customize the Turnstile widget mode (Managed /
+  Non-interactive / Invisible) from the dashboard at any time
+  without redeploying — the site key stays the same, and the widget
+  picks up the mode change on the next page load. The framework's
+  tested path is "Managed" because it gives the operator a visible
+  challenge surface to debug against.
+
+If either of the two **MUST** secret/overlay steps is skipped, the
+deploy still boots and `/login` still serves; the failure mode is
+that abuse defense is off (default `TURNSTILE_REQUIRED=false`) or
+every sign-in attempt 500s (`TURNSTILE_REQUIRED=true` flipped while
+the secret is unset). The driver pauses the wave at the secret/
+overlay gesture so the operator confirms both are in place before
+the framework version pin moves.
+
+## 0.11.0 — 2026-05-28
+
+**Minor — schema migration required; no new env vars.** This release
+ships the "trust this device for 30 days" gesture (roadmap item #9,
+SPEC §6.2). After a successful OTC or passcode sign-in, the user
+can check a single checkbox to mint a server-issued opaque
+device-trust token; the token rides as a long-lived HttpOnly +
+Secure + SameSite=Lax cookie, and the matching row's hash lives in a
+new `device_trust` table. On a subsequent visit, the cookie is
+presented at `POST /auth/device-trust/start` — if a non-expired,
+non-revoked row matches, the session is re-established without
+another OTC / passcode roundtrip. A new `/settings/notifications`
+"Trusted devices" section lists active rows (created-at, last-seen,
+expiry, rough UA label) with per-row "Revoke" and a "Revoke all
+devices" button. The cookie is "essential" per the v0.13.0 cookie-
+consent contract — it is part of authentication, not analytics — and
+is set regardless of the user's analytics / other-cookies choice.
+
+The session model gains a cookie, not a session-store change: the
+existing `rfc_session` cookie still carries the in-flight session
+state; the new `rfc_device_trust` cookie is consulted only by
+`/auth/device-trust/start` to bootstrap a fresh session on a return
+visit. The raw token only ever lives in the outbound `Set-Cookie`
+header and the inbound `Cookie` header; server-side storage is the
+bcrypt hash; constant-time comparison via `bcrypt.checkpw` on the
+candidate walk. The raw token is never logged.
+
+### Added
+
+- **`device_trust` table** (`backend/migrations/017_device_trust.sql`).
+  Per-row id, `user_id` (FK with cascade), `device_token_hash`
+  (bcrypt at rest, unique index documents the no-collision
+  invariant), `created_at`, `expires_at` (`created_at + 30 days`),
+  `user_agent` (verbatim, app-layer-truncated to 1024 chars),
+  `last_seen_at` (refreshed on every successful lookup), `revoked_at`
+  (NULL means active). Secondary index on `(user_id, revoked_at)` so
+  the /settings list query is a covering walk.
+- **`backend/app/device_trust.py`** — sibling of `otc.py` and
+  `passcode.py`. Carries `issue(user_id, user_agent)`,
+  `lookup(raw_token)`, `list_for_user(user_id)`, `revoke(user_id,
+  row_id)`, and `revoke_all(user_id)`. The 30-day window and the
+  cookie name (`rfc_device_trust`) live as module-level constants;
+  env-ifying them is a §19.2 candidate.
+- **`§17` endpoints**
+  - `POST /auth/device-trust/start` — anonymous-reachable. Reads the
+    `rfc_device_trust` cookie; on a hit, signs the user in. On a
+    miss (expired, revoked, or unknown), clears the stale cookie and
+    returns 401.
+  - `GET  /api/auth/me/devices` — list active trusted devices for
+    the signed-in user.
+  - `DELETE /api/auth/me/devices/{id}` — revoke a single row.
+    User-id scope enforced in SQL so a hostile client cannot
+    revoke another user's row by guessing ids.
+  - `DELETE /api/auth/me/devices` — revoke every active row.
+- **OTC and passcode verify bodies** gain an optional
+  `trust_device: bool` field (default false). When true and verify
+  succeeds, the endpoint mints a fresh device-trust row and sets
+  the cookie on the response. Pre-v0.11.0 clients that omit the
+  field continue to behave as before.
+- **Login.jsx** gains a "Trust this device for 30 days" checkbox
+  on both the OTC and passcode verify steps, plus a silent on-mount
+  call to `POST /auth/device-trust/start` so a returning user with
+  a valid cookie skips the email step entirely. A failure is
+  intentionally invisible — the user proceeds to the normal email
+  step.
+- **`/settings/notifications` "Trusted devices" section** — lists
+  active rows with per-row "Revoke" + a "Revoke all devices" button
+  (with a `confirm()` prompt because the gesture is broad). The
+  surface intentionally does not single out the row whose cookie
+  the current request carries so a user can revoke "this device"
+  alongside any other from one place.
+
+### Changed
+
+- **`backend/app/main.py`** — the OTC and passcode verify endpoints
+  now also accept the `trust_device` flag and accept an injected
+  `Response` so they can attach the cookie. Two helpers
+  (`_set_device_trust_cookie`, `_clear_device_trust_cookie`) carry
+  the cookie attribute set in one place so the contract is
+  consistent across endpoints. The `Response` import is added
+  alongside the existing FastAPI re-exports.
+- **`backend/app/api.py`** — imports `device_trust as device_trust_mod`
+  alongside `auth`/`db`; mounts the three `/api/auth/me/devices*`
+  endpoints immediately after `/api/auth/me/beta-request` so the
+  auth-shaped neighborhood stays clustered.
+- **`frontend/src/api.js`** — exports `startDeviceTrust()`,
+  `listMyDevices()`, `revokeMyDevice(id)`, `revokeAllMyDevices()`.
+  `verifyOtc` and `verifyPasscode` accept an optional
+  `{ trustDevice }` argument that rides on the POST body.
+
+### Upgrade steps (from 0.10.0)
+
+- You **MUST** apply schema migration `017_device_trust.sql`. The
+  migration creates a single new table with one secondary index;
+  the framework runs migrations automatically at process start, so
+  no manual step is required beyond restarting the backend so the
+  migration runner picks the file up.
+- You **MUST** rebuild the frontend and restart the backend after
+  upgrading. `frontend/package.json#version` and `VERSION` both
+  move to `0.11.0` and the new `Set-Cookie` shape requires the
+  backend to be on the matching version.
+- You **MUST** serve the deployment over HTTPS. The
+  `rfc_device_trust` cookie is set with `Secure=True` — a
+  cleartext deployment will never receive the cookie back from
+  the browser, so the trust gesture will appear to silently fail.
+  Production OHM deployments already serve over HTTPS; local
+  development against `http://localhost` is unaffected (no cookie
+  is set, the OTC/passcode paths continue to work).
+- You **MAY** announce the new feature to your users. Existing
+  signed-in sessions are unaffected — the device-trust cookie is
+  opt-in on the next sign-in, and a user who never checks the box
+  keeps the v0.10.0 behavior verbatim.
+
+
 ## 0.10.0 — 2026-05-28
 
 **Minor — schema migration required; new auth path is additive.**

SPEC.md

@@ -339,6 +339,16 @@ and exact columns are illustrative; the implementing session can adjust.
   on first write and updated on every change. Absence of a row means
   "no choice yet" — the banner shows. Anonymous viewers persist their
   choice in `localStorage` only, with no corresponding row here.
+- `device_trust` — per-row record of the §6.2 device-trust gesture
+  (v0.11.0, roadmap item #9). One row per `(user, trusted device)`
+  pair; a user with three trusted devices has three rows. Columns:
+  `id`, `user_id` (FK users, ON DELETE CASCADE), `device_token_hash`
+  (bcrypt at rest, with a unique index documenting the no-collision
+  invariant of the 256-bit CSPRNG token space), `created_at`,
+  `expires_at` (`created_at + 30 days`), `user_agent` (verbatim,
+  application-layer-truncated to 1024 chars), `last_seen_at`
+  (refreshed on every successful lookup), `revoked_at` (NULL means
+  active). The raw token never lives in this table — only the hash.
 
 **Super-draft scoping.** For rows in `threads` and `changes` where the
 entry referenced by `rfc_slug` is in state `super-draft`, `branch_name`
@@ -374,7 +384,24 @@ them:
    separate "forgot passcode" flow. The user can remove the passcode
    at any time from the §6.2 sign-in settings tab, returning to
    OTC-only.
-3. **Gitea OAuth fallback (migration only).** The v0.1 OAuth
+3. **Device trust (cookie-only, 30 days).** Added in v0.11.0
+   (roadmap item #9). After a successful OTC or passcode sign-in,
+   the visitor may check "trust this device for 30 days." The
+   framework then mints a server-issued opaque token, hashes it
+   (bcrypt) into the `device_trust` table, and sets a long-lived
+   HttpOnly + Secure + SameSite=Lax cookie carrying the raw token.
+   On a subsequent visit, `POST /auth/device-trust/start` resolves
+   the cookie and re-establishes the session without an OTC /
+   passcode roundtrip. The user can list and revoke their trusted
+   devices from the `/settings/notifications` "Trusted devices"
+   section; a revoked or expired cookie is cleared on the next
+   request. The cookie is "essential" per §14.5 — it is part of
+   authentication, not analytics, and is set regardless of the
+   user's analytics / other-cookies choice. The raw token only
+   ever lives in the outbound `Set-Cookie` header and the inbound
+   `Cookie` header; server-side storage is the hash, with
+   constant-time comparison on lookup.
+4. **Gitea OAuth fallback (migration only).** The v0.1 OAuth
    callback remains functional during the v0.7.0 window, with a
    small "Sign in with Gitea (fallback)" link on `/login` so users
    with active OAuth sessions or older invite paths still have a
@@ -2761,9 +2788,19 @@ The follow-up session will refine this. A minimal starting set:
   silently if the email wasn't on the `allowed_emails` list (the
   v0.3.0 admission gate); v0.8.0 (item #6) removed that check —
   admission moved to `permission_state` on the freshly-provisioned
-  `users` row, asserted at the contributor gate. Per §19.2's
-  expected next session, this endpoint is the lead-up to the
-  Cloudflare-Turnstile abuse-mitigation overlay.
+  `users` row, asserted at the contributor gate. v0.12.0 (item #10)
+  gates this endpoint behind a CloudFlare Turnstile siteverify call:
+  the body carries an optional `turnstile_token` field, the server
+  POSTs `secret` + `response` to `challenges.cloudflare.com/turnstile/
+  v0/siteverify` before the bcrypt hash + SMTP send, and a failed
+  challenge refuses with HTTP 400 spending no rate budget. Two env
+  vars drive the policy: `CLOUDFLARE_TURNSTILE_SECRET` (Secret
+  Manager) and `TURNSTILE_REQUIRED` (overlay, default `false`). When
+  the secret is unset and `TURNSTILE_REQUIRED=false`, the gate is
+  open (the dev / pre-rollout path); when the secret is unset and
+  `TURNSTILE_REQUIRED=true`, the endpoint refuses with HTTP 500
+  "auth misconfigured" so a future config drift fails loudly
+  instead of silently disabling abuse defense.
 - `POST /auth/otc/verify` — unauthenticated. Body carries `email` and
   `code`. Validates the bcrypt hash against the most-recent unconsumed
   non-expired row for the email, marks the row consumed, provisions
@@ -2823,6 +2860,28 @@ The follow-up session will refine this. A minimal starting set:
   return HTTP 400 with a generic message; the no-passcode-set
   failure also collapses to 400 so the response does not enumerate
   account state. v0.10.0.
+- `POST /auth/device-trust/start` — unauthenticated. Reads the
+  `rfc_device_trust` cookie (set previously by an OTC or passcode
+  verify with `trust_device: true`). On a non-expired, non-revoked
+  match, re-establishes the session and returns HTTP 200 with the
+  minimal user payload. On a miss (no cookie, expired, revoked, or
+  unknown), returns HTTP 401 and clears the stale cookie via the
+  response's `Set-Cookie` header. The failure modes collapse to
+  one shape so a probing client cannot enumerate "your row was
+  revoked" vs. "this token never existed". v0.11.0.
+- `GET /api/auth/me/devices` — authenticated. Returns the active
+  (`revoked_at IS NULL` AND `expires_at > now`) device-trust rows
+  for the signed-in user: `id`, `created_at`, `expires_at`,
+  `last_seen_at`, `user_agent`. The bcrypt hash is structurally
+  private and is never surfaced. v0.11.0.
+- `DELETE /api/auth/me/devices/{id}` — authenticated. Stamps
+  `revoked_at` on the row with id `{id}` belonging to the
+  signed-in user. The user-id scope is enforced in SQL so a
+  hostile client cannot revoke another user's row by guessing
+  ids; a row that does not match returns HTTP 404. v0.11.0.
+- `DELETE /api/auth/me/devices` — authenticated. Revokes every
+  active row for the signed-in user; returns the count revoked.
+  v0.11.0.
 - `GET /api/rfcs` — list entries with state, id, title, slug, repo,
   owners, last_active_at, has_open_prs, starred-by-me. Supports
   search, sort, filter chips, and the `unclaimed` predicate.
@@ -3903,37 +3962,77 @@ Candidates surfaced during v0.8.0 (open beta-access request flow,
   message), and whether the `/auth/login` and `/auth/callback`
   routes get a tombstone redirect to `/login` or just 404. Earns
   its session once the OTC adoption curve flattens.
-- **Device trust (30-day skip).** *Surfaced by v0.7.0 — the
-  signed-in cookie already lasts 30 days via SessionMiddleware,
-  but every sign-in still requires a fresh OTC or passcode.* The
-  roadmap item-#9 candidate adds a "trust this device" affordance
-  on the verify step that issues a longer-lived rotating token,
-  so returning visitors on the same device skip both the OTC and
-  the passcode step. The shape question is whether the trust is a
-  signed cookie distinct from the session, a row in a `device_trust`
-  table keyed by a random device-id, or a property of the session
-  itself; and whether the trust survives password-equivalent events
-  — v0.10.0's passcode-change and passcode-clear gestures are the
-  v1 instances — or only survives explicit logout. Earns its
-  session as the v0.11.0 design pass.
-- **Cloudflare Turnstile (or equivalent) on `/auth/otc/request`.**
-  *Surfaced by v0.7.0 — the endpoint is now the new abuse hot
-  path.* Per-email cooldown stops the trivial loop; what it
-  doesn't stop is a distributed scrape that fans out across a
-  large invitee list to harvest the "this email is admitted vs.
-  this email is not" signal indirectly (timing differences, SMTP
-  bounce-rate observation). The roadmap item-#10 candidate gates
-  the request endpoint behind a one-step browser-side challenge
-  before the bcrypt hash + SMTP send. Open questions: which
-  provider (Turnstile is the default since it's free and
-  privacy-respecting; hCaptcha and reCAPTCHA are also viable);
-  how the deployment configures it (`TURNSTILE_SITE_KEY` +
-  `TURNSTILE_SECRET_KEY` env vars, gated by `if
-  config.turnstile_site_key:` at the handler so existing
-  deployments don't break); whether the verify endpoint also
-  gets a challenge (probably yes for parity); and how the test
-  harness mocks the challenge. Earns its session as the v0.12.0
-  design pass.
+- **Device trust (30-day skip).** *Settled in v0.11.0 (roadmap
+  item #9). The shape: a distinct `rfc_device_trust` cookie
+  (HttpOnly + Secure + SameSite=Lax + 30-day Max-Age) carrying a
+  server-issued opaque token, keyed against a `device_trust` table
+  whose rows store the bcrypt hash. `POST /auth/device-trust/start`
+  resolves a presented cookie at next visit. A
+  `/settings/notifications` "Trusted devices" section lists active
+  rows with per-row + bulk revoke. The trust outlives a sign-out
+  (sign-out clears the session cookie, not the device-trust
+  cookie) and is not affected by passcode set/change/clear — the
+  next two items below carry the remaining open questions.*
+- **Cross-device session revocation surface.** v0.11.0's
+  `/settings/notifications → Trusted devices` revokes the
+  long-lived device-trust grants. What it does NOT revoke is an
+  active session cookie sitting in another browser, or the
+  v0.10.0 passcode-failure-counter shape, or a stale
+  password-equivalent that some future release ships. The natural
+  next step is a single "active sessions and devices" surface
+  that lists everything currently authenticating as this user —
+  device-trust rows + active session cookies (if/when the
+  framework moves to server-side sessions) + future credential
+  shapes — and lets the user kill any of them with one gesture.
+  Earns its session when a second cross-cutting concern lands
+  (the most likely first trigger: future Yubikey / WebAuthn
+  support, which surfaces another credential to revoke).
+- **Password-equivalent change invalidates device trust.** v0.11.0
+  intentionally leaves device-trust rows live across a passcode
+  set / change / clear. The argument is structural: the user has
+  the v0.10.0 lockout, the v0.11.0 per-device revoke list, and a
+  fresh sign-in path via OTC, so the cookie is not a high-value
+  bypass relative to the keys-to-the-account a passcode change
+  signals. The argument against is the conventional "changing a
+  password should kill every active session" expectation users
+  bring from other systems. This earns its own session once the
+  evidence is in: either a security-review finding that says
+  "this is the wrong default," or user feedback that says "I
+  expected my old laptop to sign out when I changed my passcode."
+- **Device-trust window tunables via env.** v0.11.0 hard-codes
+  the 30-day window in `backend/app/device_trust.py`
+  (`TRUST_DURATION_DAYS = 30`). Surfacing it as an env var
+  (`DEVICE_TRUST_DURATION_DAYS`?) is small and obvious; deferring
+  follows the same pattern as the v0.10.0 passcode-lockout
+  hard-coding — name the tunable when a deployment wants it
+  different rather than shipping a knob that has no operator
+  asking for it.
+- **Cloudflare Turnstile on `/auth/otc/request`.** *Settled in
+  v0.12.0 (roadmap item #10).* The OTC request endpoint is now
+  gated behind a Turnstile siteverify call: the frontend renders
+  the official widget on the `/login` email-entry step (and on the
+  passcode step for the "Use a code instead" fallback dispatch),
+  the captured token rides in the request body as
+  `turnstile_token`, and the backend POSTs `secret` + `response`
+  to `challenges.cloudflare.com/turnstile/v0/siteverify` before
+  the bcrypt hash + SMTP send. The widget renders only on the
+  email-entry / passcode-fallback dispatch points — the OTC
+  verify step is bottlenecked on email delivery and protected by
+  the five-minute TTL + single-use row consume, so a second
+  challenge there would double the rate budget against the same
+  abuse path without measurably more protection (revisit if bots
+  adapt to the email-entry challenge specifically). Configured
+  via `CLOUDFLARE_TURNSTILE_SECRET` (Secret Manager) and
+  `VITE_TURNSTILE_SITE_KEY` (frontend build-time overlay); a
+  third var `TURNSTILE_REQUIRED` (default `false`) lets the
+  operator flip from "soft-fail when secret unset" (the dev /
+  pre-rollout shape) to "fail-closed when secret unset" (HTTP 500
+  "auth misconfigured", the production-locked shape). Tests mock
+  the siteverify HTTP call at the `httpx.post` boundary in
+  `app.turnstile`. The hCaptcha / reCAPTCHA alternatives noted in
+  the v0.7.0 surfacing are still viable substitutes for a future
+  deployment that wants them but the framework's tested path is
+  Turnstile.
 
 Candidates surfaced during v0.10.0 (user-set passcodes, §6.2 /
 roadmap item #8):

VERSION

@@ -1 +1 @@
-0.9.0
+0.18.0

backend/.env.example

@@ -92,3 +92,21 @@ OTC_TTL_MINUTES=10
 # loud-failure shape so the abuse path is visible). Set to 0 to
 # disable the cooldown — useful for tests but never in production.
 OTC_REQUEST_COOLDOWN_SECONDS=60
+
+# --- v0.12.0: CloudFlare Turnstile gate on OTC dispatch (§6.2, item #10) ---
+# Provision a Turnstile site at dash.cloudflare.com → Turnstile → Add
+# site. The site key (public) goes in `frontend/.env` as
+# VITE_TURNSTILE_SITE_KEY. The secret key (private) goes here and is
+# what the backend POSTs to /siteverify alongside the user's response
+# token. Leave both unset for dev/test paths; the gate stays open when
+# the secret is absent AND TURNSTILE_REQUIRED=false (the default).
+CLOUDFLARE_TURNSTILE_SECRET=
+
+# When `true`, /auth/otc/request fails closed (HTTP 500 "auth
+# misconfigured") if CLOUDFLARE_TURNSTILE_SECRET is unset. When `false`
+# (the default), a missing secret skips verification — useful in dev
+# and during the pre-rollout window when the operator hasn't wired
+# the secret yet. Flip to `true` once the secret is wired so a future
+# config drift surfaces as a loud 500 rather than a silent abuse-
+# defense disablement.
+TURNSTILE_REQUIRED=false

backend/app/api.py

@@ -22,10 +22,12 @@ from . import (
     api_branches,
     api_discussion,
     api_graduation,
+    api_invitations,
     api_notifications,
     api_prs,
     auth,
     db,
+    device_trust as device_trust_mod,
     docs as docs_mod,
     entry as entry_mod,
     cache,
@@ -101,6 +103,12 @@ def make_router(
     # Contribution still requires a PR (api_prs above); this surface
     # is for discussion that does not yet warrant a branch.
     router.include_router(api_discussion.make_router())
+    # v0.16.0 (roadmap item #12): owner-only invite for per-RFC
+    # contribution + discussion. The RFC's owner can invite specific
+    # users by email to either open PRs or join the discussion; non-
+    # invited users keep read access but cannot write (v0.6.0
+    # contract extended to per-RFC scope).
+    router.include_router(api_invitations.make_router())
 
     # ---------------------------------------------------------------
     # §17: /api/health — unauthenticated post-flight probe.
@@ -252,6 +260,68 @@ def make_router(
             notify.fan_out_new_beta_request(requester_user_id=user.user_id)
         return {"ok": True}
 
+    # ---------------------------------------------------------------
+    # v0.11.0: trust device for 30 days (§6.2, roadmap item #9).
+    #
+    # The mint path lives on the OAuth router (issuing the cookie is
+    # coupled to OTC/passcode verify). This module owns the read/revoke
+    # surface the /settings/devices page calls.
+    # ---------------------------------------------------------------
+
+    @router.get("/api/auth/me/devices")
+    async def list_my_devices(request: Request) -> dict[str, Any]:
+        """Active device-trust rows for the signed-in user.
+
+        Active = not revoked, not expired. The current request's
+        device (if any) is *not* singled out here — the surface
+        shows the same row shape for every device so the user can
+        revoke any of them without the page leaking which row
+        carries the cookie they're using right now.
+        """
+        user = auth.require_user(request)
+        rows = device_trust_mod.list_for_user(user.user_id)
+        return {
+            "items": [
+                {
+                    "id": r.id,
+                    "created_at": r.created_at,
+                    "expires_at": r.expires_at,
+                    "last_seen_at": r.last_seen_at,
+                    "user_agent": r.user_agent,
+                }
+                for r in rows
+            ]
+        }
+
+    @router.delete("/api/auth/me/devices/{device_id}")
+    async def revoke_my_device(device_id: int, request: Request) -> dict[str, Any]:
+        """Revoke a single device-trust row for the signed-in user.
+
+        The user-id scope is enforced in SQL so a hostile client
+        cannot revoke another user's row by guessing ids. A row that
+        doesn't exist, doesn't belong to this user, or is already
+        revoked reads as 404 — the wrong-vs-already-revoked
+        distinction would only help a probing client enumerate ids.
+        """
+        user = auth.require_user(request)
+        ok = device_trust_mod.revoke(user.user_id, device_id)
+        if not ok:
+            raise HTTPException(404, "Device not found")
+        return {"ok": True}
+
+    @router.delete("/api/auth/me/devices")
+    async def revoke_all_my_devices(request: Request) -> dict[str, Any]:
+        """Revoke every active device-trust row for the signed-in user.
+
+        The user's current request stays authenticated via its
+        session cookie; the device-trust cookie carried on the
+        current device is also revoked, but `rfc_session` keeps the
+        request flow alive until sign-out / expiry.
+        """
+        user = auth.require_user(request)
+        count = device_trust_mod.revoke_all(user.user_id)
+        return {"ok": True, "revoked": count}
+
     # ---------------------------------------------------------------
     # §7: the catalog
     # ---------------------------------------------------------------

backend/app/api_admin.py

@@ -11,6 +11,8 @@ The endpoints in this module:
   - `GET  /api/admin/users`                       — list users with role + mute
   - `POST /api/admin/users/<id>/role`             — set role per §6.1
   - `POST /api/admin/users/<id>/mute`             — set the §6.2 write-mute
+  - `POST /api/admin/users`                       — v0.17.0: create user + invite
+  - `GET  /api/admin/users/invites`               — v0.17.0: pending invites
   - `GET  /api/admin/audit`                       — paged `actions` log
   - `GET  /api/admin/permission-events`           — paged `permission_events` log
   - `GET  /api/admin/graduation-queue`            — super-drafts ready to graduate
@@ -33,8 +35,9 @@ from typing import Any
 from fastapi import APIRouter, HTTPException, Query, Request
 from pydantic import BaseModel, Field
 
-from . import auth, db
+from . import auth, db, email_invite, invites
 from .config import Config
+from .email import EmailConfig
 
 
 # ---------------------------------------------------------------------------
@@ -65,6 +68,32 @@ class AllowlistAddBody(BaseModel):
     note: str | None = Field(default=None, max_length=200)
 
 
+class CreateUserInviteBody(BaseModel):
+    """v0.17.0 / roadmap item #16 — admin-create user + invite email.
+
+    The admin types these fields on the "Create user + invite" modal on
+    `/admin/users`. The email + role are required; first/last name and
+    the optional custom message round out the body.
+
+    Bounds mirror the rest of the codebase:
+      * `email`: 320 chars — RFC 5321 envelope limit, same as
+        `OtcRequestBody` / `BetaRequestBody` / `AllowlistAddBody`.
+      * `first_name` / `last_name`: 120 chars — same as the v0.8.0
+        `BetaRequestBody` capture form.
+      * `role`: pydantic regex pinned to the §6.1 set so an unknown
+        role fails at the body bound (422) instead of landing as a
+        CHECK constraint violation in the migration.
+      * `custom_message`: 500 chars — the brief calls this out as
+        the max. The frontend modal shows a "remaining chars"
+        counter to match.
+    """
+    email: str = Field(min_length=3, max_length=320)
+    first_name: str = Field(default="", max_length=120)
+    last_name: str = Field(default="", max_length=120)
+    role: str = Field(pattern="^(owner|admin|contributor)$")
+    custom_message: str = Field(default="", max_length=500)
+
+
 # ---------------------------------------------------------------------------
 # Router
 # ---------------------------------------------------------------------------
@@ -90,6 +119,17 @@ def make_router(config: Config) -> APIRouter:
 
         `permission_decided_by_login` joins the deciding admin row so
         the UI can render "granted by @ben" without a second round-trip.
+
+        v0.16.0 (roadmap item #12) additive: each user row now carries
+        an `rfc_invitations` array — the per-RFC invitations the user
+        has accepted. This is the "permission-grant requests from
+        invited users" hook the roadmap text calls for: when a user
+        accepts a per-RFC invite and they're not yet platform-granted,
+        the admin sees "here because @ben invited them to <RFC> as
+        <role>" alongside their pending row, informing (not deciding)
+        the platform grant. The two write surfaces remain distinct —
+        the RFC's owner controls per-RFC roles; the admin controls
+        platform-grant state.
         """
         auth.require_admin(request)
         rows = db.conn().execute(
@@ -115,6 +155,62 @@ def make_router(config: Config) -> APIRouter:
                 u.display_name COLLATE NOCASE
             """
         ).fetchall()
+        # v0.16.0 — per-user accepted per-RFC invitations. One query
+        # over the full set, indexed bucket-by-user-id in Python so
+        # the per-row attachment below is O(1). Empty array for users
+        # who hold no accepted invitations.
+        invitation_rows = db.conn().execute(
+            """
+            SELECT c.user_id, c.rfc_slug, c.role_in_rfc, c.created_at,
+                   r.title AS rfc_title,
+                   i.id AS invitation_id, i.invitee_email,
+                   ui.gitea_login AS inviter_login,
+                   ui.display_name AS inviter_display
+              FROM rfc_collaborators c
+         LEFT JOIN cached_rfcs r ON r.slug = c.rfc_slug
+         LEFT JOIN rfc_invitations i ON i.id = c.invitation_id
+         LEFT JOIN users ui ON ui.id = i.inviter_user_id
+             ORDER BY c.created_at DESC
+            """
+        ).fetchall()
+        per_user_invites: dict[int, list[dict]] = {}
+        for ir in invitation_rows:
+            per_user_invites.setdefault(ir["user_id"], []).append({
+                "rfc_slug": ir["rfc_slug"],
+                "rfc_title": ir["rfc_title"] or ir["rfc_slug"],
+                "role_in_rfc": ir["role_in_rfc"],
+                "invited_at": ir["created_at"],
+                "invitation_id": ir["invitation_id"],
+                "invitee_email": ir["invitee_email"],
+                "inviter_login": ir["inviter_login"],
+                "inviter_display": ir["inviter_display"],
+            })
+        # v0.17.0 / roadmap item #16: a user row whose `last_seen_at`
+        # is NULL is one of two things — a brand-new row that was just
+        # provisioned (rare, and the v0.7.0 OTC verify path stamps
+        # last_seen_at on the same call that creates the row), or an
+        # admin-created invite-pending row (v0.17.0 — created by
+        # `POST /api/admin/users`). We surface a `pending_invite_id`
+        # field by joining through `user_invite_tokens` so the
+        # Users tab can render a "(pending invite)" badge alongside
+        # the role/state controls. Filters to invites that are
+        # neither expired nor claimed — once the invitee clicks
+        # through, the badge clears (and `last_seen_at` populates).
+        pending_invite_rows = db.conn().execute(
+            """
+            SELECT invited_user_id, id AS invite_id, expires_at
+              FROM user_invite_tokens
+             WHERE claimed_at IS NULL
+               AND datetime(expires_at) > datetime('now')
+            """
+        ).fetchall()
+        pending_invites = {
+            r["invited_user_id"]: {
+                "invite_id": r["invite_id"],
+                "expires_at": r["expires_at"],
+            }
+            for r in pending_invite_rows
+        }
         return {
             "items": [
                 {
@@ -133,6 +229,217 @@ def make_router(config: Config) -> APIRouter:
                     "permission_decided_at": r["permission_decided_at"],
                     "permission_decided_by_login": r["decided_by_login"],
                     "permission_decided_by_display": r["decided_by_display"],
+                    # v0.16.0 additive — never null, always an array.
+                    "rfc_invitations": per_user_invites.get(r["id"], []),
+                    # v0.17.0: present iff the row is invited-but-not-
+                    # claimed-yet. The frontend renders a "(pending
+                    # invite)" badge when this is non-null.
+                    "pending_invite": pending_invites.get(r["id"]),
+                }
+                for r in rows
+            ]
+        }
+
+    # ----- Create user + invite (v0.17.0 / roadmap item #16) -----
+
+    @router.post("/api/admin/users")
+    async def create_user_with_invite(
+        body: CreateUserInviteBody, request: Request,
+    ) -> dict[str, Any]:
+        """Provision a fresh `users` row with a pre-assigned role + send
+        an invite email carrying a claim link.
+
+        Refusals:
+          * `422` — the admin tries to invite their own email (no
+            self-invite; symmetric to `set_permission`'s self-flip
+            refusal and `set_role`'s self-downgrade refusal). Use
+            the existing role-change channel for self-edits.
+          * `422` — the admin tries to grant `owner` without being
+            owner themselves. §6.1: owner-zero is the only owner
+            bootstrap path; new owners come from a sitting owner's
+            hand. A 422 here matches the message shape; a 403 would
+            also be defensible, but staying with 422 keeps the
+            "your input is bad" framing.
+          * `409` — the email already maps to a `users` row. The
+            admin should use the existing role / grant gestures on
+            the existing user, not create a duplicate.
+          * `422` — pydantic-level: malformed email, role outside
+            the §6.1 set, custom_message over 500 chars.
+
+        On success:
+          1. The invitee `users` row lands with the chosen role and
+             `permission_state='granted'` (admin's hand is the grant)
+             and `last_seen_at IS NULL` (the "(pending invite)"
+             discriminator the listing surface joins through).
+          2. The `user_invite_tokens` row lands with the bcrypt-
+             hashed opaque token; the raw token rides only in the
+             email link.
+          3. The invite email dispatches with subject "You're
+             invited to <app> by <admin>" and the custom message
+             embedded in a clearly-delimited block if present.
+          4. A `permission_events` row records the admin-create
+             gesture so the §6.5 / `permissions` admin tab carries
+             the audit trail alongside the existing grant/revoke
+             flips.
+        """
+        viewer = auth.require_admin(request)
+        email_clean = body.email.strip().lower()
+        if "@" not in email_clean or len(email_clean.split("@")[-1]) < 2:
+            raise HTTPException(422, "Email looks malformed")
+
+        # Self-invite refusal. Compare the admin's own email
+        # case-insensitively against the invite target.
+        viewer_row = db.conn().execute(
+            "SELECT email FROM users WHERE id = ?", (viewer.user_id,)
+        ).fetchone()
+        viewer_email = (viewer_row["email"] or "").strip().lower() if viewer_row else ""
+        if viewer_email and viewer_email == email_clean:
+            raise HTTPException(
+                422,
+                "You cannot invite yourself — use the role-change channel "
+                "if you need to edit your own row",
+            )
+
+        # Owner-grant refusal: §6.1 says only a sitting owner can mint
+        # a new owner. An admin trying to invite-as-owner is refused
+        # at 422; the admin should ask the owner to issue the invite,
+        # or invite as `admin` and let the owner promote later.
+        if body.role == "owner" and viewer.role != "owner":
+            raise HTTPException(
+                422,
+                "Only an owner can invite a new owner — invite as admin and "
+                "ask the owner to promote, or have the owner issue this invite",
+            )
+
+        # Duplicate-email refusal. A pre-existing row (regardless of
+        # permission_state) means the admin should use the existing
+        # role / grant gestures, not create a parallel user.
+        existing = db.conn().execute(
+            "SELECT id FROM users WHERE email = ? COLLATE NOCASE LIMIT 1",
+            (email_clean,),
+        ).fetchone()
+        if existing is not None:
+            raise HTTPException(409, "A user with this email already exists")
+
+        # Create the invitee row + token row + send the email.
+        outcome = invites.create_invite(
+            email=email_clean,
+            first_name=body.first_name,
+            last_name=body.last_name,
+            role=body.role,
+            custom_message=body.custom_message,
+            created_by_admin_id=viewer.user_id,
+        )
+
+        # Audit row in permission_events so the admin Permissions tab
+        # carries the gesture. The before-state is "n/a" (the row
+        # did not exist); the after-state is the granted role. We
+        # use a new `event_kind='user_invited'` so the existing
+        # grant/revoke kinds stay scoped to their flip surface.
+        db.conn().execute(
+            """
+            INSERT INTO permission_events
+                (actor_user_id, subject_user_id, event_kind, details)
+            VALUES (?, ?, 'user_invited', ?)
+            """,
+            (
+                viewer.user_id,
+                outcome.invited_user_id,
+                json.dumps({
+                    "email": email_clean,
+                    "role": body.role,
+                    "invite_id": outcome.invite_id,
+                    "custom_message_chars": len(body.custom_message or ""),
+                }),
+            ),
+        )
+
+        # Build the claim URL using the same APP_URL the email module
+        # reads. The token rides as a query-string param to the
+        # frontend route `/invites/claim?token=…`; the frontend POSTs
+        # it back to `/api/invites/claim` which consumes the row.
+        cfg = EmailConfig.from_env()
+        from urllib.parse import urlencode
+        claim_url = f"{cfg.app_url}/invites/claim?{urlencode({'token': outcome.raw_token})}"
+
+        # Fetch the inviter display so the email body can render
+        # "Ben Stull (ben@example.com) has invited you to …". We
+        # read off the row fresh rather than trusting the session
+        # cookie's cached display_name.
+        inviter_row = db.conn().execute(
+            "SELECT display_name, email FROM users WHERE id = ?",
+            (viewer.user_id,),
+        ).fetchone()
+        inviter_display = (
+            (inviter_row["display_name"] if inviter_row else "") or viewer.display_name or "An admin"
+        )
+        inviter_email_for_body = (inviter_row["email"] if inviter_row else "") or viewer.email or ""
+
+        email_invite.send_invite_email(
+            to_address=email_clean,
+            claim_url=claim_url,
+            inviter_display=inviter_display,
+            inviter_email=inviter_email_for_body,
+            custom_message=body.custom_message,
+        )
+
+        return {
+            "ok": True,
+            "invite_id": outcome.invite_id,
+            "invited_user_id": outcome.invited_user_id,
+            "email": email_clean,
+            "role": body.role,
+        }
+
+    @router.get("/api/admin/users/invites")
+    async def list_user_invites(request: Request) -> dict[str, Any]:
+        """List active (not claimed, not expired) admin-issued invites.
+
+        Powers the admin's "I sent these but they haven't been claimed
+        yet" view. The frontend uses this alongside `list_users` —
+        the user-listing's `pending_invite` field carries the per-row
+        flag; this endpoint carries the full invite shape for a
+        dedicated drill-in surface.
+        """
+        auth.require_admin(request)
+        rows = invites.list_pending_invites()
+        # Join through to the admin display names so the surface can
+        # render "invited by @ben" without a second client call.
+        admin_ids = {r.created_by_admin_id for r in rows}
+        admin_lookup: dict[int, dict[str, str]] = {}
+        if admin_ids:
+            placeholders = ",".join("?" * len(admin_ids))
+            admin_rows = db.conn().execute(
+                f"SELECT id, gitea_login, display_name FROM users "
+                f"WHERE id IN ({placeholders})",
+                tuple(admin_ids),
+            ).fetchall()
+            admin_lookup = {
+                ar["id"]: {
+                    "gitea_login": ar["gitea_login"] or "",
+                    "display_name": ar["display_name"] or "",
+                }
+                for ar in admin_rows
+            }
+        return {
+            "items": [
+                {
+                    "id": r.id,
+                    "email": r.email,
+                    "role": r.role,
+                    "first_name": r.first_name,
+                    "last_name": r.last_name,
+                    "custom_message": r.custom_message,
+                    "created_at": r.created_at,
+                    "expires_at": r.expires_at,
+                    "invited_user_id": r.invited_user_id,
+                    "created_by_admin_id": r.created_by_admin_id,
+                    "created_by_login": admin_lookup.get(
+                        r.created_by_admin_id, {}
+                    ).get("gitea_login", ""),
+                    "created_by_display": admin_lookup.get(
+                        r.created_by_admin_id, {}
+                    ).get("display_name", ""),
                 }
                 for r in rows
             ]
@@ -365,6 +672,73 @@ def make_router(config: Config) -> APIRouter:
             "has_more": len(rows) == limit,
         }
 
+    @router.get("/api/admin/outbound-emails")
+    async def list_outbound_emails(
+        request: Request,
+        kind: str | None = None,
+        status: str | None = None,
+        to_address: str | None = None,
+        limit: int = Query(default=100, ge=1, le=500),
+        before_id: int | None = None,
+    ) -> dict[str, Any]:
+        """v0.18.0 Slice 4: read-only inspection of the
+        `outbound_emails` audit table.
+
+        Answers questions like "did this person ever get their
+        invite?" without grepping VM logs. Filterable by kind
+        ('otc' | 'invite' | 'notification' | 'bundle' | 'digest'),
+        status ('sent' | 'failed' | 'deferred' | 'bounced'), and
+        to_address; the latter is exact-match because the audit
+        question is usually "the specific person who said they
+        didn't receive it." Per the proposal, no admin UI ships
+        with v0.18.0 — operator queries via curl + jq for now.
+        """
+        auth.require_admin(request)
+        clauses: list[str] = []
+        args: list[Any] = []
+        if kind:
+            clauses.append("kind = ?")
+            args.append(kind)
+        if status:
+            clauses.append("status = ?")
+            args.append(status)
+        if to_address:
+            clauses.append("LOWER(to_address) = LOWER(?)")
+            args.append(to_address)
+        if before_id is not None:
+            clauses.append("id < ?")
+            args.append(before_id)
+        where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
+        rows = db.conn().execute(
+            f"""
+            SELECT id, to_address, from_address, subject, kind, sent_at,
+                   status, error, notification_id, message_id
+              FROM outbound_emails
+             {where}
+             ORDER BY id DESC
+             LIMIT ?
+            """,
+            (*args, limit),
+        ).fetchall()
+        return {
+            "items": [
+                {
+                    "id": r["id"],
+                    "to_address": r["to_address"],
+                    "from_address": r["from_address"],
+                    "subject": r["subject"],
+                    "kind": r["kind"],
+                    "sent_at": r["sent_at"],
+                    "status": r["status"],
+                    "error": r["error"],
+                    "notification_id": r["notification_id"],
+                    "message_id": r["message_id"],
+                }
+                for r in rows
+            ],
+            "has_more": len(rows) == limit,
+        }
+
     @router.get("/api/admin/permission-events")
     async def list_permission_events(
         request: Request,

backend/app/api_branches.py

@@ -279,6 +279,15 @@ def make_router(
     @router.post("/api/rfcs/{slug}/branches/main/promote-to-branch")
     async def promote_to_branch(slug: str, body: PromoteToBranchBody, request: Request) -> dict[str, Any]:
         viewer = auth.require_contributor(request)
+        # v0.16.0 (item #12): cutting a contribute branch is the
+        # PR-shaped write surface gate. A platform-granted user who is
+        # not invited as a per-RFC contributor cannot start work that
+        # only exists to land in a PR.
+        if not auth.can_contribute_to_rfc(viewer, slug):
+            raise HTTPException(
+                403,
+                "This RFC's owner has not invited you to contribute PRs",
+            )
         rfc = _require_active_rfc(slug)
         owner, repo = _repo_for(rfc)
         new_branch = (body.branch_name or "").strip()
@@ -331,6 +340,14 @@ def make_router(
     @router.post("/api/rfcs/{slug}/start-edit-branch")
     async def start_edit_branch(slug: str, body: StartEditBranchBody, request: Request) -> dict[str, Any]:
         viewer = auth.require_contributor(request)
+        # v0.16.0 (item #12): same per-RFC contribute gate as
+        # promote-to-branch — kicking off a super-draft edit branch is
+        # also PR-shaped work.
+        if not auth.can_contribute_to_rfc(viewer, slug):
+            raise HTTPException(
+                403,
+                "This RFC's owner has not invited you to contribute PRs",
+            )
         rfc = _require_super_draft(slug)
         owner, repo = _repo_for(rfc)
         new_branch = (body.branch_name or "").strip()

backend/app/api_discussion.py

@@ -116,6 +116,17 @@ def make_router() -> APIRouter:
     ) -> dict[str, Any]:
         viewer = auth.require_contributor(request)
         _require_rfc_readable(slug)
+        # v0.16.0 (roadmap item #12): the per-RFC discussion is now a
+        # gated surface. The platform-level `require_contributor` above
+        # ensures the user is signed in + admin-granted; this layer
+        # narrows further to "is this user named for this RFC?" The
+        # 403 here is structurally the v0.6.0 anon-write refusal
+        # extended to non-invited platform users.
+        if not auth.can_discuss_rfc(viewer, slug):
+            raise HTTPException(
+                403,
+                "This RFC's owner has not invited you to its discussion",
+            )
         cur = db.conn().execute(
             """
             INSERT INTO threads
@@ -175,6 +186,12 @@ def make_router() -> APIRouter:
     ) -> dict[str, Any]:
         viewer = auth.require_contributor(request)
         _require_rfc_readable(slug)
+        # v0.16.0 (item #12): same per-RFC gate as create_discussion_thread.
+        if not auth.can_discuss_rfc(viewer, slug):
+            raise HTTPException(
+                403,
+                "This RFC's owner has not invited you to its discussion",
+            )
         _require_discussion_thread(slug, thread_id)
         message_id = chat_layer.append_user_message(
             thread_id=thread_id,

backend/app/api_invitations.py

@@ -0,0 +1,575 @@
+"""v0.16.0 / §6 / §10 — owner-only invite for per-RFC PR or PR-less
+discussion (roadmap item #12).
+
+The RFC's owner can invite a specific email to one of two per-RFC roles:
+
+  * `contributor` — may open PRs against this RFC AND post in its
+    discussion (PR-permission strictly includes discussion-permission).
+  * `discussant` — may post in this RFC's PR-less discussion only.
+
+Non-invited users keep the v0.6.0 anonymous-read contract: they can
+read but cannot write/discuss the RFC. Reads are not narrowed by
+this item.
+
+Endpoints:
+
+  * `POST   /api/rfcs/{slug}/invitations`              — owner: create + email
+  * `GET    /api/rfcs/{slug}/invitations`              — owner: list pending/accepted
+  * `POST   /api/rfcs/{slug}/invitations/{id}/revoke`  — owner: revoke
+  * `GET    /api/invitations/accept`                   — token lookup (signed-in user)
+  * `POST   /api/invitations/accept`                   — token redeem (signed-in user)
+
+The accept endpoints are deliberately platform-scoped (not nested under
+the RFC slug) because the user clicking the email link only has the
+token and may not even know the slug yet. The GET shape lets the
+frontend show a confirmation page ("RFC <X> invited you to be a
+<role> — accept?") before the POST commits the membership.
+
+Permission gates (composed with `require_contributor`):
+
+  * Issue / list / revoke: `auth.can_invite_to_rfc` — RFC owner or
+    platform admin/owner.
+  * Accept: any platform-granted signed-in user; the gate is the
+    token, not the role. The token also constrains which email the
+    accept lands under — the accepting user's email must match the
+    invitation's invitee_email (case-insensitive). This prevents an
+    invited-but-not-the-account-holder situation from minting a
+    collaborator row under the wrong identity.
+
+Email shape: a single plain-text body sent via the existing SMTP path
+(reuses `EmailConfig.from_env()` like `email_otc.py` does). No
+unsubscribe footer — the email is transactional and per-invite, not a
+recurring notification. No tracking pixel.
+
+Admin-page hook: when an accept lands and the user's
+`permission_state` is still `pending`, that signals to the admin's
+`/admin/users` queue that the user is here because they accepted a
+per-RFC invitation — informing (not deciding) the admin's
+platform-grant call. v0.16.0 surfaces this via additive columns on
+the existing `GET /api/admin/users` listing (see `api_admin.py`'s
+diff in the same release) — no new endpoint, no restructure.
+"""
+from __future__ import annotations
+
+import logging
+import secrets
+import smtplib
+from email.message import EmailMessage
+from email.utils import formataddr
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field
+
+from . import auth, db
+from .email import EmailConfig, _SENT
+
+log = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Pydantic bodies
+# ---------------------------------------------------------------------------
+
+
+class CreateInvitationBody(BaseModel):
+    """The owner picks an email and a role-in-RFC. No custom-message
+    field — that belongs to item #16's platform-level invite surface,
+    not here.
+
+    We validate the email with a deliberately narrow pattern rather
+    than `pydantic.EmailStr` to avoid pulling in `email-validator` as
+    a dependency (and v0.7.0's OTC body does the same — see
+    `OTCRequestBody`'s shape). The validation here is intentionally
+    permissive: a local-part, an `@`, and a domain part with no
+    whitespace. Operator-side typo catching is the job of the email
+    transport; the framework only guards against obviously malformed
+    input."""
+    invitee_email: str = Field(min_length=3, max_length=320,
+                               pattern=r"^[^\s@]+@[^\s@]+$")
+    role_in_rfc: str = Field(pattern="^(contributor|discussant)$")
+
+
+class AcceptInvitationBody(BaseModel):
+    token: str = Field(min_length=1, max_length=200)
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+
+# 30-day TTL matches the device-trust window the framework already
+# ships (v0.11.0). A pending invitation past this is rejected at the
+# accept endpoint regardless of the row's `status` column.
+INVITATION_TTL_DAYS = 30
+
+
+# ---------------------------------------------------------------------------
+# Router
+# ---------------------------------------------------------------------------
+
+
+def make_router() -> APIRouter:
+    router = APIRouter()
+
+    # ---------------------------------------------------------------
+    # POST /api/rfcs/<slug>/invitations
+    # The owner creates an invitation. The endpoint mints the token,
+    # writes the row, and dispatches the email synchronously. A failure
+    # to send the email does NOT roll back the row — the owner can
+    # share the link directly out-of-band if SMTP is briefly down (the
+    # `GET /api/rfcs/<slug>/invitations` response carries the token
+    # for that fallback).
+    # ---------------------------------------------------------------
+
+    @router.post("/api/rfcs/{slug}/invitations")
+    async def create_invitation(slug: str, body: CreateInvitationBody, request: Request) -> dict[str, Any]:
+        viewer = auth.require_contributor(request)
+        rfc = _require_rfc(slug)
+        if not auth.can_invite_to_rfc(viewer, slug):
+            raise HTTPException(
+                403,
+                "Only the RFC's owner can invite collaborators",
+            )
+
+        invitee_email = body.invitee_email.strip()
+        role_in_rfc = body.role_in_rfc
+
+        # Refuse re-inviting an email that already has a pending
+        # invitation on this RFC at the same role. Different-role
+        # re-invite is allowed (upgrade discussant → contributor)
+        # — the new row supersedes the old in the UI listing's
+        # natural ordering, and acceptance of either picks up the
+        # corresponding role.
+        existing = db.conn().execute(
+            """
+            SELECT id FROM rfc_invitations
+             WHERE rfc_slug = ? AND invitee_email = ? COLLATE NOCASE
+               AND role_in_rfc = ? AND status = 'pending'
+             LIMIT 1
+            """,
+            (slug, invitee_email, role_in_rfc),
+        ).fetchone()
+        if existing:
+            raise HTTPException(
+                409,
+                f"{invitee_email} already has a pending {role_in_rfc} invitation for this RFC",
+            )
+
+        token = _mint_token()
+        cur = db.conn().execute(
+            """
+            INSERT INTO rfc_invitations
+                (rfc_slug, inviter_user_id, invitee_email, role_in_rfc,
+                 token, expires_at)
+            VALUES (?, ?, ?, ?, ?, datetime('now', ?))
+            """,
+            (
+                slug,
+                viewer.user_id,
+                invitee_email,
+                role_in_rfc,
+                token,
+                f"+{INVITATION_TTL_DAYS} days",
+            ),
+        )
+        invitation_id = cur.lastrowid
+
+        # Send the email — synchronous. A send failure logs and
+        # returns; the row stays so the owner can recover via the
+        # listing (which carries the token for an out-of-band share).
+        _send_invitation_email(
+            to_address=invitee_email,
+            inviter_display=viewer.display_name or viewer.gitea_login or "An RFC owner",
+            rfc_title=rfc["title"],
+            role_in_rfc=role_in_rfc,
+            token=token,
+        )
+
+        return {
+            "id": invitation_id,
+            "rfc_slug": slug,
+            "invitee_email": invitee_email,
+            "role_in_rfc": role_in_rfc,
+            "status": "pending",
+            "token": token,
+        }
+
+    # ---------------------------------------------------------------
+    # GET /api/rfcs/<slug>/invitations
+    # The owner's listing of every invitation on the RFC, regardless
+    # of status. Carries the token (for the resend / re-share path).
+    # ---------------------------------------------------------------
+
+    @router.get("/api/rfcs/{slug}/invitations")
+    async def list_invitations(slug: str, request: Request) -> dict[str, Any]:
+        viewer = auth.require_contributor(request)
+        _require_rfc(slug)
+        if not auth.can_invite_to_rfc(viewer, slug):
+            raise HTTPException(
+                403,
+                "Only the RFC's owner can view invitations",
+            )
+
+        rows = db.conn().execute(
+            """
+            SELECT i.id, i.invitee_email, i.role_in_rfc, i.status, i.token,
+                   i.expires_at, i.created_at, i.accepted_at,
+                   i.inviter_user_id, i.accepted_by_user_id,
+                   u_inviter.display_name AS inviter_display,
+                   u_inviter.gitea_login AS inviter_login,
+                   u_accept.display_name AS accepted_by_display,
+                   u_accept.gitea_login AS accepted_by_login
+              FROM rfc_invitations i
+         LEFT JOIN users u_inviter ON u_inviter.id = i.inviter_user_id
+         LEFT JOIN users u_accept ON u_accept.id = i.accepted_by_user_id
+             WHERE i.rfc_slug = ?
+             ORDER BY i.id DESC
+            """,
+            (slug,),
+        ).fetchall()
+
+        return {
+            "items": [
+                {
+                    "id": r["id"],
+                    "invitee_email": r["invitee_email"],
+                    "role_in_rfc": r["role_in_rfc"],
+                    "status": _effective_status(r),
+                    "token": r["token"],
+                    "expires_at": r["expires_at"],
+                    "created_at": r["created_at"],
+                    "accepted_at": r["accepted_at"],
+                    "inviter_display": r["inviter_display"],
+                    "inviter_login": r["inviter_login"],
+                    "accepted_by_display": r["accepted_by_display"],
+                    "accepted_by_login": r["accepted_by_login"],
+                }
+                for r in rows
+            ],
+        }
+
+    # ---------------------------------------------------------------
+    # POST /api/rfcs/<slug>/invitations/<id>/revoke
+    # Revokes a pending invitation. Already-accepted invitations
+    # cannot be "revoked" from this surface — the corresponding
+    # collaborator-removal surface is a §19.2 candidate; v0.16.0
+    # only lifts the *pending* link.
+    # ---------------------------------------------------------------
+
+    @router.post("/api/rfcs/{slug}/invitations/{invitation_id}/revoke")
+    async def revoke_invitation(slug: str, invitation_id: int, request: Request) -> dict[str, Any]:
+        viewer = auth.require_contributor(request)
+        _require_rfc(slug)
+        if not auth.can_invite_to_rfc(viewer, slug):
+            raise HTTPException(
+                403,
+                "Only the RFC's owner can revoke invitations",
+            )
+
+        row = db.conn().execute(
+            "SELECT id, status FROM rfc_invitations WHERE id = ? AND rfc_slug = ?",
+            (invitation_id, slug),
+        ).fetchone()
+        if row is None:
+            raise HTTPException(404, "Invitation not found")
+        if row["status"] != "pending":
+            raise HTTPException(
+                409,
+                f"Invitation is {row['status']}; only pending invitations can be revoked",
+            )
+
+        db.conn().execute(
+            "UPDATE rfc_invitations SET status = 'revoked' WHERE id = ?",
+            (invitation_id,),
+        )
+        return {"ok": True, "id": invitation_id, "status": "revoked"}
+
+    # ---------------------------------------------------------------
+    # GET /api/invitations/accept?token=...
+    # Lookup-only — returns what the invitation grants so the
+    # frontend can render a confirmation page before the POST. The
+    # token is required; no token, no peek.
+    # ---------------------------------------------------------------
+
+    @router.get("/api/invitations/accept")
+    async def preview_invitation(token: str, request: Request) -> dict[str, Any]:
+        viewer = auth.require_user(request)
+        row = _lookup_invitation_by_token(token)
+        if row is None:
+            raise HTTPException(404, "Invitation not found")
+        effective = _effective_status(row)
+        rfc = db.conn().execute(
+            "SELECT slug, title FROM cached_rfcs WHERE slug = ?", (row["rfc_slug"],),
+        ).fetchone()
+        return {
+            "rfc_slug": row["rfc_slug"],
+            "rfc_title": rfc["title"] if rfc else row["rfc_slug"],
+            "role_in_rfc": row["role_in_rfc"],
+            "status": effective,
+            "invitee_email": row["invitee_email"],
+            "email_matches_you": (viewer.email or "").strip().lower()
+                                == row["invitee_email"].strip().lower(),
+            "expires_at": row["expires_at"],
+        }
+
+    # ---------------------------------------------------------------
+    # POST /api/invitations/accept
+    # The accept gesture: token → collaborator row.
+    #
+    # Requires:
+    #   * an authenticated user (no token-only acceptance — we want
+    #     the per-user audit trail),
+    #   * a valid (pending, non-expired, non-revoked) invitation,
+    #   * the accepting user's email matches invitee_email
+    #     (case-insensitive).
+    #
+    # On success the row's status flips to 'accepted' and a
+    # rfc_collaborators row is inserted (or upgraded if the user
+    # already had a lower role). Idempotent: re-accepting the same
+    # already-accepted invitation reads as a 200 no-op with
+    # `changed=false`.
+    # ---------------------------------------------------------------
+
+    @router.post("/api/invitations/accept")
+    async def accept_invitation(body: AcceptInvitationBody, request: Request) -> dict[str, Any]:
+        viewer = auth.require_user(request)
+        row = _lookup_invitation_by_token(body.token)
+        if row is None:
+            raise HTTPException(404, "Invitation not found")
+
+        effective = _effective_status(row)
+        if effective == "revoked":
+            raise HTTPException(409, "Invitation was revoked")
+        if effective == "expired":
+            raise HTTPException(409, "Invitation has expired")
+
+        # Email match — case-insensitive. Empty viewer email cannot
+        # accept (an OAuth-only user with no captured email shape).
+        viewer_email = (viewer.email or "").strip().lower()
+        invitee_email = row["invitee_email"].strip().lower()
+        if not viewer_email or viewer_email != invitee_email:
+            raise HTTPException(
+                403,
+                "This invitation was sent to a different email; sign in with that address",
+            )
+
+        if effective == "accepted":
+            # Idempotent re-accept — surface the existing collaborator
+            # row without writing anything new.
+            collab = db.conn().execute(
+                "SELECT role_in_rfc FROM rfc_collaborators WHERE rfc_slug = ? AND user_id = ?",
+                (row["rfc_slug"], viewer.user_id),
+            ).fetchone()
+            return {
+                "ok": True,
+                "changed": False,
+                "rfc_slug": row["rfc_slug"],
+                "role_in_rfc": collab["role_in_rfc"] if collab else row["role_in_rfc"],
+            }
+
+        # First-time accept. Flip the invitation; upsert the
+        # collaborator. We do the upsert with ON CONFLICT so a
+        # user who already held a lower role gets upgraded, never
+        # downgraded (the MAX-style precedence is contributor >
+        # discussant; lower roles never overwrite higher).
+        with db.tx() as c:
+            c.execute(
+                """
+                UPDATE rfc_invitations
+                   SET status = 'accepted',
+                       accepted_at = datetime('now'),
+                       accepted_by_user_id = ?
+                 WHERE id = ?
+                """,
+                (viewer.user_id, row["id"]),
+            )
+            existing = c.execute(
+                "SELECT role_in_rfc FROM rfc_collaborators WHERE rfc_slug = ? AND user_id = ?",
+                (row["rfc_slug"], viewer.user_id),
+            ).fetchone()
+            target_role = _max_role(
+                existing["role_in_rfc"] if existing else None,
+                row["role_in_rfc"],
+            )
+            if existing is None:
+                c.execute(
+                    """
+                    INSERT INTO rfc_collaborators
+                        (rfc_slug, user_id, role_in_rfc, invitation_id)
+                    VALUES (?, ?, ?, ?)
+                    """,
+                    (row["rfc_slug"], viewer.user_id, target_role, row["id"]),
+                )
+            elif existing["role_in_rfc"] != target_role:
+                c.execute(
+                    """
+                    UPDATE rfc_collaborators
+                       SET role_in_rfc = ?, invitation_id = ?
+                     WHERE rfc_slug = ? AND user_id = ?
+                    """,
+                    (target_role, row["id"], row["rfc_slug"], viewer.user_id),
+                )
+
+        return {
+            "ok": True,
+            "changed": True,
+            "rfc_slug": row["rfc_slug"],
+            "role_in_rfc": target_role,
+        }
+
+    return router
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _require_rfc(slug: str):
+    """The invitation surface only operates on a known, non-withdrawn
+    RFC. We refuse 404 on unknown and 409 on withdrawn — mirrors the
+    discussion endpoints' `_require_rfc_readable` shape."""
+    row = db.conn().execute(
+        "SELECT slug, title, state FROM cached_rfcs WHERE slug = ?", (slug,),
+    ).fetchone()
+    if row is None:
+        raise HTTPException(404, "RFC not found")
+    if row["state"] == "withdrawn":
+        raise HTTPException(409, "RFC is withdrawn")
+    return row
+
+
+def _lookup_invitation_by_token(token: str):
+    return db.conn().execute(
+        """
+        SELECT id, rfc_slug, inviter_user_id, invitee_email, role_in_rfc,
+               status, token, expires_at, created_at, accepted_at,
+               accepted_by_user_id
+          FROM rfc_invitations
+         WHERE token = ?
+        """,
+        (token,),
+    ).fetchone()
+
+
+def _effective_status(row) -> str:
+    """The row's column status is the authoritative truth except for
+    `expired` — that is derived from `expires_at` at read time so an
+    unattended cron isn't required to flip rows. A revoked-then-
+    expired row reads as `revoked` (the explicit gesture wins)."""
+    column_status = row["status"]
+    if column_status != "pending":
+        return column_status
+    # Compare via SQL so the comparison is in sqlite-time, matching the
+    # `datetime('now')` insert. A simpler same-process comparison would
+    # work too, but routing through the DB keeps the timezone handling
+    # consistent with the inserts.
+    is_past = db.conn().execute(
+        "SELECT datetime(?) <= datetime('now') AS past",
+        (row["expires_at"],),
+    ).fetchone()["past"]
+    return "expired" if is_past else "pending"
+
+
+def _mint_token() -> str:
+    """A 256-bit URL-safe token. The token shape is opaque to the
+    consumer; the email link encodes it as a query param."""
+    return secrets.token_urlsafe(32)
+
+
+def _max_role(existing: str | None, new: str) -> str:
+    """contributor strictly dominates discussant. A re-accept that
+    would lower the role is a no-op (the existing role survives)."""
+    precedence = {"discussant": 0, "contributor": 1}
+    if existing is None:
+        return new
+    if precedence.get(new, 0) > precedence.get(existing, 0):
+        return new
+    return existing
+
+
+# ---------------------------------------------------------------------------
+# Email dispatch — transactional, no preferences honored
+# ---------------------------------------------------------------------------
+
+
+def _send_invitation_email(
+    *,
+    to_address: str,
+    inviter_display: str,
+    rfc_title: str,
+    role_in_rfc: str,
+    token: str,
+) -> bool:
+    """Compose and send the invitation email.
+
+    Like `email_otc.send_otc_email`, this writes its own envelope and
+    reuses `EmailConfig.from_env()` for the SMTP plumbing. The
+    `_SENT` buffer is appended either way so integration tests can
+    assert on the outbound shape without a real SMTP server.
+
+    Returns True on the happy path / dev fallback; False on SMTP
+    failure. The caller does not roll back the invitation row on
+    failure — the owner has the token in the create response and on
+    the listing surface for an out-of-band share.
+    """
+    cfg = EmailConfig.from_env()
+    subject = f"{inviter_display} invited you to {rfc_title} on {cfg.from_name}"
+    role_label = (
+        "open PRs against the RFC and join its discussion"
+        if role_in_rfc == "contributor"
+        else "join the RFC's discussion"
+    )
+    link = f"{cfg.app_url}/invitations/accept?token={token}"
+    body = (
+        f"{inviter_display} invited you to {rfc_title} on {cfg.from_name} as {role_in_rfc}.\n\n"
+        f"This invitation lets you {role_label}.\n\n"
+        f"Click to accept (you'll be asked to sign in first if you aren't already):\n\n"
+        f"    {link}\n\n"
+        f"The invitation expires in {INVITATION_TTL_DAYS} days. If you weren't expecting\n"
+        f"this, you can safely ignore the email.\n\n"
+        f"---\n"
+        f"{cfg.from_name} · {cfg.app_url}\n"
+    )
+    envelope = {
+        "to": to_address,
+        "from": formataddr((cfg.from_name, cfg.from_address)),
+        "subject": subject,
+        "body": body,
+        "kind": "rfc_invitation",
+    }
+    _SENT.append(envelope)
+
+    if not cfg.enabled:
+        log.info("invitation email disabled (EMAIL_ENABLED=0): to=%s", to_address)
+        return True
+    if not cfg.smtp_host:
+        # Dev fallback — surface the link at INFO so the operator can
+        # complete an accept flow without an SMTP relay.
+        log.info(
+            "invitation email (stdout fallback): to=%s rfc=%s role=%s link=%s",
+            to_address, rfc_title, role_in_rfc, link,
+        )
+        return True
+
+    try:
+        msg = EmailMessage()
+        msg["From"] = envelope["from"]
+        msg["To"] = to_address
+        msg["Subject"] = subject
+        msg.set_content(body)
+        smtp = smtplib.SMTP(cfg.smtp_host, cfg.smtp_port, timeout=30)
+        try:
+            if cfg.smtp_starttls:
+                smtp.starttls()
+            if cfg.smtp_user:
+                smtp.login(cfg.smtp_user, cfg.smtp_password)
+            smtp.send_message(msg)
+        finally:
+            smtp.quit()
+        return True
+    except Exception:
+        log.exception("invitation email send failed: to=%s", to_address)
+        return False

backend/app/api_notifications.py

@@ -73,6 +73,13 @@ class MarkReadBody(BaseModel):
 class BounceBody(BaseModel):
     email: str = Field(min_length=3, max_length=320)
     kind: str = Field(default="hard")  # 'hard' or 'complaint'
+    # v0.18.0 Slice 5: when the bounce provider includes the
+    # original Message-ID, the framework correlates it back to
+    # the matching `outbound_emails` row and stamps
+    # `status='bounced'`. Optional — providers that don't surface
+    # the Message-ID still flip the global opt-out via the email
+    # match, but lose the per-message attribution.
+    message_id: str | None = Field(default=None, max_length=1000)
 
 
 class CookieConsentBody(BaseModel):
@@ -443,6 +450,40 @@ def make_router(config: Config) -> APIRouter:
 
     # ----- Email: one-click unsubscribe + bounce webhook -----
 
+    # v0.18.0: the category → column map. The `all` synthetic
+    # category lands the bundle's one-click on the global opt-out
+    # flag (per `email._send_bundle` in v0.18.0 Slice 2 — a bundle
+    # spans multiple categories, so a per-category flip wouldn't
+    # honor the user's intent).
+    _CATEGORY_COLUMN: dict[str, str] = {
+        "personal-direct": "email_personal_direct",
+        "structural": "email_watched_structural",
+        "admin-actionable": "email_admin_actionable",
+        "all": "email_opt_out_all",
+    }
+
+    def _apply_unsubscribe(user_id: int, category: str) -> bool:
+        """Flip the matching column. Returns True on success, False
+        if the category is unknown. Idempotent — running twice on
+        the same (user, category) is harmless (it sets the column
+        to its current value)."""
+        column = _CATEGORY_COLUMN.get(category)
+        if column is None:
+            return False
+        # `all` sets the flag to 1 (opt out); per-category sets to 0
+        # (turn that category off). The column semantic is "1 means
+        # don't send"; the per-category booleans are "1 means do
+        # send". Different polarities, hence the case split.
+        if category == "all":
+            db.conn().execute(
+                f"UPDATE users SET {column} = 1 WHERE id = ?", (user_id,)
+            )
+        else:
+            db.conn().execute(
+                f"UPDATE users SET {column} = 0 WHERE id = ?", (user_id,)
+            )
+        return True
+
     @router.get("/api/email/unsubscribe")
     async def email_unsubscribe(t: str = Query(..., description="Signed token from the email footer")) -> HTMLResponse:
         try:
@@ -453,20 +494,51 @@ def make_router(config: Config) -> APIRouter:
                 "<p>Open the app to manage your notification preferences directly.</p>",
                 status_code=400,
             )
-        column = {
-            "personal-direct": "email_personal_direct",
-            "structural": "email_watched_structural",
-            "admin-actionable": "email_admin_actionable",
-        }.get(category)
-        if column is None:
+        if not _apply_unsubscribe(user_id, category):
             return HTMLResponse(
                 f"<h1>Unknown category</h1><p>{category}</p>", status_code=400
             )
-        db.conn().execute(f"UPDATE users SET {column} = 0 WHERE id = ?", (user_id,))
-        return HTMLResponse(
-            f"<h1>Unsubscribed</h1><p>You will no longer receive {category} emails. "
-            f"You can re-enable them in your notification preferences.</p>"
-        )
+        if category == "all":
+            body = (
+                "<h1>Unsubscribed</h1><p>You will no longer receive any email "
+                "from this app. You can re-enable individual categories from "
+                "your notification preferences after signing in.</p>"
+            )
+        else:
+            body = (
+                f"<h1>Unsubscribed</h1><p>You will no longer receive {category} emails. "
+                f"You can re-enable them in your notification preferences.</p>"
+            )
+        return HTMLResponse(body)
+
+    @router.post("/api/email/unsubscribe")
+    async def email_unsubscribe_post(
+        request: Request,
+        t: str = Query(..., description="Signed token from the List-Unsubscribe header"),
+    ) -> dict[str, Any]:
+        """v0.18.0: RFC 8058 one-click endpoint.
+
+        Gmail and Yahoo POST `List-Unsubscribe=One-Click` (as a
+        form-encoded body) to the URL in the `List-Unsubscribe`
+        header when the user clicks their MUA's "Unsubscribe"
+        button. The endpoint MUST accept POST (per the
+        `List-Unsubscribe-Post` header we advertise) and MUST be
+        idempotent.
+
+        The body content is checked loosely — RFC 8058 says it
+        SHOULD be exactly `List-Unsubscribe=One-Click`, but some
+        intermediaries strip / re-encode the body, so the
+        framework accepts any POST to the URL once the token
+        verifies. The bar is that the token signature carries the
+        authority; the body is hint-only.
+        """
+        try:
+            user_id, category = email_mod.verify_unsubscribe_token(t)
+        except BadSignature:
+            raise HTTPException(400, "Invalid or expired token")
+        if not _apply_unsubscribe(user_id, category):
+            raise HTTPException(400, f"Unknown category: {category}")
+        return {"ok": True, "category": category}
 
     @router.post("/api/webhooks/email-bounce")
     async def email_bounce(body: BounceBody, request: Request) -> dict[str, Any]:
@@ -490,16 +562,46 @@ def make_router(config: Config) -> APIRouter:
             import hmac as _hmac
             if not received or not _hmac.compare_digest(expected, received):
                 raise HTTPException(401, "Invalid webhook signature")
+        # v0.18.0 Slice 5: correlate the bounce back to the
+        # matching outbound_emails row if the provider supplied
+        # the Message-ID. The hard-bounce -> global-opt-out
+        # logic below still fires regardless; this is an
+        # additional audit signal.
+        correlated_row_id: int | None = None
+        if body.message_id:
+            correlated = db.conn().execute(
+                "SELECT id FROM outbound_emails WHERE message_id = ?",
+                (body.message_id,),
+            ).fetchone()
+            if correlated is not None:
+                correlated_row_id = correlated["id"]
+                db.conn().execute(
+                    "UPDATE outbound_emails SET status = 'bounced', "
+                    "error = COALESCE(error, '') || ? WHERE id = ?",
+                    (f"bounce ({body.kind})", correlated_row_id),
+                )
+                log.info(
+                    "email-bounce: correlated message_id=%s -> outbound_emails.id=%s",
+                    body.message_id, correlated_row_id,
+                )
+            else:
+                log.info(
+                    "email-bounce: message_id=%s did not match any "
+                    "outbound_emails row (provider may be replaying an old bounce, "
+                    "or the row was pruned)",
+                    body.message_id,
+                )
+
         row = db.conn().execute(
             "SELECT id FROM users WHERE LOWER(email) = LOWER(?)", (body.email,),
         ).fetchone()
         if row is None:
-            return {"ok": True, "matched": False}
+            return {"ok": True, "matched": False, "correlated_id": correlated_row_id}
         db.conn().execute(
             "UPDATE users SET email_opt_out_all = 1 WHERE id = ?", (row["id"],),
         )
         log.info("email-bounce: opted out user %s (%s)", row["id"], body.kind)
-        return {"ok": True, "matched": True}
+        return {"ok": True, "matched": True, "correlated_id": correlated_row_id}
 
     return router
 

backend/app/api_prs.py

@@ -112,6 +112,17 @@ def make_router(
     @router.post("/api/rfcs/{slug}/branches/{branch:path}/open-pr")
     async def open_pr(slug: str, branch: str, body: OpenPRBody, request: Request) -> dict[str, Any]:
         viewer = auth.require_contributor(request)
+        # v0.16.0 (item #12): opening a PR is the canonical PR-shaped
+        # write — the gate fires here even though the branch-cutting
+        # entry points also gate, since a user with prior branch access
+        # who's since had their per-RFC role revoked shouldn't be able
+        # to ship the PR. The branch-creation gate is the kickoff
+        # refusal; this one is the post-work refusal.
+        if not auth.can_contribute_to_rfc(viewer, slug):
+            raise HTTPException(
+                403,
+                "This RFC's owner has not invited you to contribute PRs",
+            )
         rfc = _require_active_rfc(slug)
         if branch == "main":
             raise HTTPException(409, "PRs open from non-main branches")

backend/app/auth.py

@@ -290,5 +290,159 @@ def require_admin(request: Request) -> SessionUser:
     return user
 
 
+# v0.16.0 (roadmap item #12): per-RFC membership helpers.
+#
+# These don't replace `require_contributor` — they layer on top of it for
+# endpoints that an RFC's owner can selectively open up. The "discussion"
+# and "PR" write surfaces consult `is_rfc_writer(...)` / `is_rfc_discussant(...)`
+# to admit users who are either platform-privileged (admin, RFC owner)
+# OR who hold an explicit invitation-accepted per-RFC role.
+#
+# The platform gate still fires first: a user whose
+# `permission_state != 'granted'` cannot write anywhere, invitation or
+# not. v0.16.0 doesn't loosen that — a per-RFC invitation is additive
+# *within* the granted-platform-user population. (Accepting an
+# invitation as a pending user surfaces in the admin-page hook per
+# the roadmap text; the platform grant remains the admin's decision.)
+
+
+def _rfc_owners_set(rfc_slug: str) -> set[str]:
+    """The gitea_logins named in the RFC's frontmatter owners array.
+
+    Read from `cached_rfcs.owners_json`. Returns an empty set if the RFC
+    isn't cached (the caller's earlier `_require_rfc_readable` will
+    already have rejected that case in practice).
+    """
+    import json as _json
+    row = db.conn().execute(
+        "SELECT owners_json FROM cached_rfcs WHERE slug = ?", (rfc_slug,),
+    ).fetchone()
+    if row is None:
+        return set()
+    try:
+        return set(_json.loads(row["owners_json"] or "[]"))
+    except Exception:
+        return set()
+
+
+def is_rfc_owner(user: SessionUser | None, rfc_slug: str) -> bool:
+    """True iff the user is named in the RFC's frontmatter `owners`
+    list. The platform-level admin/owner check is separate; per §6.1 an
+    app admin/owner has all per-RFC capabilities by construction, but
+    this predicate is intentionally narrow — it answers "is this
+    person on the RFC's owners line?" and nothing more.
+    """
+    if user is None:
+        return False
+    return user.gitea_login in _rfc_owners_set(rfc_slug)
+
+
+def is_rfc_collaborator(user: SessionUser | None, rfc_slug: str, *, role_in_rfc: str | None = None) -> bool:
+    """True iff the user has an accepted per-RFC collaborator row.
+
+    `role_in_rfc`:
+      * None — any role qualifies (the discussion-write check uses this
+        shape: contributor strictly includes discussant).
+      * 'contributor' — only the contributor role qualifies (the PR-write
+        check uses this shape).
+      * 'discussant' — only the discussant role qualifies (not used by
+        v0.16.0 endpoints; included for symmetry).
+    """
+    if user is None:
+        return False
+    if role_in_rfc is None:
+        row = db.conn().execute(
+            "SELECT 1 FROM rfc_collaborators WHERE rfc_slug = ? AND user_id = ? LIMIT 1",
+            (rfc_slug, user.user_id),
+        ).fetchone()
+        return row is not None
+    row = db.conn().execute(
+        "SELECT 1 FROM rfc_collaborators WHERE rfc_slug = ? AND user_id = ? AND role_in_rfc = ? LIMIT 1",
+        (rfc_slug, user.user_id, role_in_rfc),
+    ).fetchone()
+    return row is not None
+
+
+def can_discuss_rfc(user: SessionUser | None, rfc_slug: str) -> bool:
+    """v0.16.0 — admit to PR-less discussion writes on this RFC.
+
+    True if ANY of:
+      * platform admin/owner (the §6.1 maximal-capability path),
+      * the RFC has no frontmatter owners yet (the gate is open
+        until an owner exists to set it — relevant for super-drafts
+        pre-§13.1 claim),
+      * RFC owner (frontmatter `owners` membership),
+      * accepted per-RFC collaborator at any role (contributor strictly
+        includes discussant).
+
+    Returns False for anonymous viewers and for users whose
+    `permission_state != 'granted'` — the platform-level gate must hold
+    before any per-RFC layer can apply. The platform gate is also
+    enforced earlier in the request via `require_contributor`; the
+    helper here is defensive so callers that compose it with
+    `current_user` directly still respect the gate.
+    """
+    if user is None:
+        return False
+    if user.permission_state != "granted":
+        return False
+    if user.role in ("owner", "admin"):
+        return True
+    owners = _rfc_owners_set(rfc_slug)
+    if not owners:
+        # No owner to gate the invite-list — fall through to the
+        # platform-granted contract. The first §13.1 claim engages
+        # the gate; before that, anyone platform-granted can
+        # contribute (mirrors the v0.5.0 / v0.6.0 contract).
+        return True
+    if user.gitea_login in owners:
+        return True
+    return is_rfc_collaborator(user, rfc_slug, role_in_rfc=None)
+
+
+def can_contribute_to_rfc(user: SessionUser | None, rfc_slug: str) -> bool:
+    """v0.16.0 — admit to PR-shaped writes on this RFC.
+
+    True if ANY of:
+      * platform admin/owner,
+      * the RFC has no frontmatter owners yet (gate open until an
+        owner exists),
+      * RFC owner,
+      * accepted per-RFC collaborator at role 'contributor' (a
+        'discussant' row is NOT sufficient — PRs are the
+        higher-privilege surface).
+
+    Same `permission_state` and anonymous-viewer refusals as
+    `can_discuss_rfc`.
+    """
+    if user is None:
+        return False
+    if user.permission_state != "granted":
+        return False
+    if user.role in ("owner", "admin"):
+        return True
+    owners = _rfc_owners_set(rfc_slug)
+    if not owners:
+        # Same fall-through as can_discuss_rfc: until an owner exists,
+        # the gate is open.
+        return True
+    if user.gitea_login in owners:
+        return True
+    return is_rfc_collaborator(user, rfc_slug, role_in_rfc="contributor")
+
+
+def can_invite_to_rfc(user: SessionUser | None, rfc_slug: str) -> bool:
+    """v0.16.0 — only RFC owners (frontmatter) and platform admin/owner
+    can issue invitations. Per-RFC collaborators do not get the
+    invite-others power; that stays with the RFC's owner."""
+    if user is None:
+        return False
+    if user.permission_state != "granted":
+        return False
+    if user.role in ("owner", "admin"):
+        return True
+    return is_rfc_owner(user, rfc_slug)
+
+
 def new_state() -> str:
     return secrets.token_urlsafe(16)

backend/app/config.py

@@ -60,6 +60,20 @@ def load_config() -> Config:
 
     enabled = [m.strip() for m in _optional("ENABLED_MODELS", "claude").split(",") if m.strip()]
 
+    # v0.18.0: `GITEA_WEBHOOK_SECRET` is now mandatory (per the
+    # email + webhook hygiene proposal). An empty value used to
+    # silently accept unsigned webhook POSTs — that was the
+    # invisible-failure shape the proposal targets. Now the
+    # framework refuses to start when the secret is empty unless
+    # the operator opts into the dev-bypass with
+    # `RFC_APP_INSECURE_WEBHOOKS=1`. Local-dev deployments without
+    # a wired Gitea hook set the bypass; production MUST NOT.
+    insecure_webhooks = os.environ.get("RFC_APP_INSECURE_WEBHOOKS", "").strip() == "1"
+    if insecure_webhooks:
+        webhook_secret = _optional("GITEA_WEBHOOK_SECRET")
+    else:
+        webhook_secret = _required("GITEA_WEBHOOK_SECRET")
+
     return Config(
         gitea_url=_required("GITEA_URL").rstrip("/"),
         gitea_bot_user=_required("GITEA_BOT_USER"),
@@ -72,7 +86,7 @@ def load_config() -> Config:
         secret_key=_required("SECRET_KEY"),
         database_path=database_path,
         owner_gitea_login=_optional("OWNER_GITEA_LOGIN"),
-        webhook_secret=_optional("GITEA_WEBHOOK_SECRET"),
+        webhook_secret=webhook_secret,
         enabled_models=enabled,
         anthropic_api_key=_optional("ANTHROPIC_API_KEY"),
         google_api_key=_optional("GOOGLE_API_KEY"),

backend/app/device_trust.py

@@ -0,0 +1,351 @@
+"""§6.2 / v0.11.0: trust device for 30 days (roadmap item #9).
+
+After a successful OTC or passcode sign-in, a contributor may check
+"trust this device for 30 days." The framework then issues a
+server-issued opaque token, hashes it (bcrypt) for storage in the
+`device_trust` table, and sets a long-lived cookie carrying the raw
+token. On a subsequent visit, the cookie is presented at
+`/auth/device-trust/start`; if a non-expired, non-revoked row matches,
+the session is re-established without another OTC / passcode round
+trip.
+
+The shape:
+
+  * `issue(user_id, user_agent)` — mint a fresh CSPRNG token, hash it,
+    insert a row, and return the raw token + row id so the endpoint
+    can set the cookie. The 30-day expiry is the only knob; the
+    `revoked_at` column stays NULL.
+  * `lookup(raw_token)` — walk the user's active rows (the unique
+    index keys on the hash, so we read a small candidate set), check
+    the bcrypt hash in constant time, drop any row whose `expires_at`
+    has passed or whose `revoked_at` is non-NULL, and return the
+    matched row or None. On a hit, refresh `last_seen_at`.
+  * `list_for_user(user_id)` — return the active rows for the
+    /settings/devices surface. Revoked + expired rows are filtered out
+    so the surface only shows live trust grants.
+  * `revoke(user_id, row_id)` — stamp `revoked_at` on the row. The
+    next lookup refuses the cookie token (the row is dead).
+  * `revoke_all(user_id)` — bulk-revoke every active row for the user.
+    The /settings/devices surface's "revoke all" button calls this.
+
+Cookie shape: `rfc_device_trust`. HttpOnly, Secure, SameSite=Lax,
+Max-Age=2592000 (30 days), Path=/. The cookie value is the raw token;
+server-side storage is the hash. The cookie is "essential" per the
+v0.13.0 cookie-consent banner (it is part of authentication, not
+analytics), so the framework sets it regardless of analytics /
+other-cookies choices.
+
+Constant-time comparison: bcrypt's `checkpw` is already constant-time
+over the hash bytes. We walk the candidate set linearly with `_check`
+which delegates to `bcrypt.checkpw`; no early-exit shortcut leaks
+which row was the match.
+
+The raw token never appears in a log line or an exception message;
+the helpers carry the token only as a parameter and forget it after
+hashing.
+
+The cookie sits orthogonal to the §6.1 `permission_state` gate: a
+revoked or pending user with a valid device-trust cookie still
+re-establishes their session (the cookie identifies the user, not
+their admission state), and the existing `require_contributor` /
+`require_admin` dependencies in `auth.py` continue to refuse the
+unrelated write surfaces.
+"""
+from __future__ import annotations
+
+import logging
+import secrets
+from dataclasses import dataclass
+
+import bcrypt
+
+from . import db
+from .auth import SessionUser
+
+log = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Tunables — hard-coded in v0.11.0 (§19.2 candidate to env-ify later).
+# ---------------------------------------------------------------------------
+
+TRUST_DURATION_DAYS = 30
+COOKIE_NAME = "rfc_device_trust"
+COOKIE_MAX_AGE_SECONDS = TRUST_DURATION_DAYS * 24 * 60 * 60
+# 256 bits of CSPRNG entropy. `secrets.token_urlsafe(32)` yields ~43
+# URL-safe characters; the bcrypt hash is what's stored, so the raw
+# token only ever lives in the cookie.
+TOKEN_BYTES = 32
+# User-Agent header values seen in the wild can be unbounded; clamp
+# to a reasonable ceiling so a hostile UA doesn't bloat the row.
+USER_AGENT_MAX_LENGTH = 1024
+
+
+# ---------------------------------------------------------------------------
+# Issue
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class IssueOutcome:
+    """The shape returned from `issue`.
+
+    `raw_token` is the cookie value to send to the client; it never
+    appears in storage. `row_id` is the surrogate key for the
+    /settings/devices UI to address the row by id.
+    """
+    raw_token: str
+    row_id: int
+
+
+def _new_token() -> str:
+    return secrets.token_urlsafe(TOKEN_BYTES)
+
+
+def _hash(token: str) -> str:
+    return bcrypt.hashpw(token.encode("utf-8"), bcrypt.gensalt()).decode("ascii")
+
+
+def _check(token: str, token_hash: str) -> bool:
+    try:
+        return bcrypt.checkpw(token.encode("utf-8"), token_hash.encode("ascii"))
+    except (ValueError, TypeError):
+        return False
+
+
+def _trim_user_agent(ua: str) -> str:
+    ua = (ua or "").strip()
+    if len(ua) > USER_AGENT_MAX_LENGTH:
+        return ua[:USER_AGENT_MAX_LENGTH]
+    return ua
+
+
+def issue(user_id: int, user_agent: str) -> IssueOutcome:
+    """Mint a fresh device-trust token + row for `user_id`.
+
+    The row's expiry is set 30 days in the future. The hash, not the
+    raw token, lands in the database. The caller (the endpoint) sets
+    the cookie with the raw token returned here.
+    """
+    raw = _new_token()
+    h = _hash(raw)
+    ua = _trim_user_agent(user_agent)
+    cur = db.conn().execute(
+        f"""
+        INSERT INTO device_trust (user_id, device_token_hash, expires_at, user_agent)
+        VALUES (?, ?, datetime('now', '+{TRUST_DURATION_DAYS} days'), ?)
+        """,
+        (user_id, h, ua),
+    )
+    row_id = cur.lastrowid
+    return IssueOutcome(raw_token=raw, row_id=row_id)
+
+
+# ---------------------------------------------------------------------------
+# Lookup
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class LookupOutcome:
+    """The result of `lookup`.
+
+    `user` is populated only on a hit. `reason` distinguishes the
+    failure modes so the endpoint can decide whether to clear the
+    cookie ('expired', 'revoked', 'unknown') or just refuse ('invalid').
+    """
+    ok: bool
+    user: SessionUser | None
+    reason: str  # 'ok' | 'invalid' | 'unknown' | 'expired' | 'revoked'
+    row_id: int | None = None
+
+
+def lookup(raw_token: str) -> LookupOutcome:
+    """Resolve a presented cookie token to a user.
+
+    A hit refreshes `last_seen_at` on the matched row. A miss returns
+    a reason so the endpoint can clear the stale cookie if the row
+    was revoked or expired (vs. simply unknown, which probably means
+    the cookie was forged or the row was wiped by a /settings/devices
+    revoke from another browser).
+    """
+    raw = (raw_token or "").strip()
+    if not raw:
+        return LookupOutcome(ok=False, user=None, reason="invalid")
+
+    # The unique index on `device_token_hash` would let us SELECT by
+    # hash if bcrypt were a stable hash, but bcrypt incorporates a
+    # per-row salt — equal tokens produce different hashes. We walk
+    # the candidate set instead. In practice the set is small (a
+    # human has a handful of trusted devices) and bcrypt is cheap on
+    # the order of milliseconds; the walk is bounded by the user's
+    # active device count.
+    #
+    # We don't pre-filter by `revoked_at IS NULL` here so that a
+    # token presented for a recently-revoked row produces a
+    # 'revoked' outcome (the endpoint surfaces a different shape).
+    # Same for expired: we let the walk hit and classify after.
+    rows = db.conn().execute(
+        """
+        SELECT id, user_id, device_token_hash, expires_at, revoked_at
+          FROM device_trust
+         ORDER BY id DESC
+        """,
+    ).fetchall()
+
+    matched = None
+    for row in rows:
+        if _check(raw, row["device_token_hash"]):
+            matched = row
+            break
+
+    if matched is None:
+        return LookupOutcome(ok=False, user=None, reason="unknown")
+
+    if matched["revoked_at"] is not None:
+        return LookupOutcome(ok=False, user=None, reason="revoked", row_id=matched["id"])
+
+    expired = db.conn().execute(
+        "SELECT datetime(?) < datetime('now') AS expired",
+        (matched["expires_at"],),
+    ).fetchone()["expired"]
+    if expired:
+        return LookupOutcome(ok=False, user=None, reason="expired", row_id=matched["id"])
+
+    # Refresh last-seen so the /settings/devices surface can show the
+    # user when each device was last active. This is the only write
+    # the lookup path does on the hot read.
+    db.conn().execute(
+        "UPDATE device_trust SET last_seen_at = datetime('now') WHERE id = ?",
+        (matched["id"],),
+    )
+    user_row = db.conn().execute(
+        """
+        SELECT id, gitea_id, gitea_login, email, display_name, avatar_url, role, permission_state
+          FROM users
+         WHERE id = ?
+        """,
+        (matched["user_id"],),
+    ).fetchone()
+    if user_row is None:
+        # The user row was deleted but the device_trust row hadn't
+        # cascaded yet (shouldn't happen under the FK ON DELETE
+        # CASCADE — be defensive anyway). Treat as 'unknown' so the
+        # endpoint clears the cookie.
+        return LookupOutcome(ok=False, user=None, reason="unknown", row_id=matched["id"])
+
+    # Also stamp last_seen_at on the user row so the user's overall
+    # activity stamp keeps pace with cookie-only sign-ins.
+    db.conn().execute(
+        "UPDATE users SET last_seen_at = datetime('now') WHERE id = ?",
+        (matched["user_id"],),
+    )
+
+    return LookupOutcome(
+        ok=True,
+        user=SessionUser(
+            user_id=user_row["id"],
+            gitea_id=user_row["gitea_id"] or 0,
+            gitea_login=user_row["gitea_login"] or "",
+            display_name=user_row["display_name"],
+            email=user_row["email"] or "",
+            avatar_url=user_row["avatar_url"] or "",
+            role=user_row["role"],
+            permission_state=user_row["permission_state"] or "granted",
+        ),
+        reason="ok",
+        row_id=matched["id"],
+    )
+
+
+# ---------------------------------------------------------------------------
+# List / revoke (for the /settings/devices surface)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class DeviceRow:
+    """The shape the /settings/devices endpoint returns.
+
+    Note the absence of `device_token_hash` — the hash is structurally
+    private, and the surface has no use for it.
+    """
+    id: int
+    created_at: str
+    expires_at: str
+    last_seen_at: str
+    user_agent: str
+
+
+def list_for_user(user_id: int) -> list[DeviceRow]:
+    """Active device-trust rows for the user, freshest first.
+
+    Filters out revoked rows and rows whose expiry has passed; the
+    surface only shows live trust grants. A user wondering "which
+    devices are signed in" gets the answer that matches what the
+    framework would actually accept on a presented cookie.
+    """
+    rows = db.conn().execute(
+        """
+        SELECT id, created_at, expires_at, last_seen_at, user_agent
+          FROM device_trust
+         WHERE user_id = ?
+           AND revoked_at IS NULL
+           AND datetime(expires_at) > datetime('now')
+         ORDER BY last_seen_at DESC, id DESC
+        """,
+        (user_id,),
+    ).fetchall()
+    return [
+        DeviceRow(
+            id=row["id"],
+            created_at=row["created_at"],
+            expires_at=row["expires_at"],
+            last_seen_at=row["last_seen_at"],
+            user_agent=row["user_agent"] or "",
+        )
+        for row in rows
+    ]
+
+
+def revoke(user_id: int, row_id: int) -> bool:
+    """Revoke a single device-trust row for the given user.
+
+    Returns True iff a row was matched (still active, belongs to the
+    user). The user-id scope is enforced in SQL so a hostile client
+    cannot revoke another user's row by guessing ids.
+    """
+    cur = db.conn().execute(
+        """
+        UPDATE device_trust
+           SET revoked_at = datetime('now')
+         WHERE id = ?
+           AND user_id = ?
+           AND revoked_at IS NULL
+        """,
+        (row_id, user_id),
+    )
+    return cur.rowcount > 0
+
+
+def revoke_all(user_id: int) -> int:
+    """Revoke every active device-trust row for the user. Returns the
+    count of rows touched.
+
+    The /settings/devices "revoke all" button calls this. The user's
+    current request stays authenticated via its session cookie; the
+    device-trust cookie on the current device is also revoked, but
+    the session middleware's `rfc_session` cookie keeps the request
+    flow alive until the user signs out or the session cookie
+    expires.
+    """
+    cur = db.conn().execute(
+        """
+        UPDATE device_trust
+           SET revoked_at = datetime('now')
+         WHERE user_id = ?
+           AND revoked_at IS NULL
+        """,
+        (user_id,),
+    )
+    return cur.rowcount

backend/app/digest.py

@@ -180,7 +180,19 @@ def assemble_for_user(
 
     subject = _subject(eligible, cadence)
     body = _body(eligible, cadence, cfg)
-    sent = email_mod._deliver(cfg, email, subject, body)
+    # v0.18.0: the digest is the bulk-adjacent surface par excellence
+    # (it can carry weeks of accumulated activity), so it gets the
+    # full one-click unsubscribe to the global opt-out. Per-category
+    # opt-outs are managed from the preferences page; this footer is
+    # the "stop sending me anything" escape hatch Gmail and Yahoo
+    # expect for senders at this tier.
+    unsubscribe_url = email_mod.make_unsubscribe_url(user_id, "all")
+    sent = email_mod._deliver(
+        cfg, email, subject, body,
+        unsubscribe_mailto=cfg.unsubscribe_mailto,
+        unsubscribe_url=unsubscribe_url,
+        kind="digest",
+    )
     if not sent:
         return False
     ids = [r["id"] for r, _ in eligible]

backend/app/email.py

@@ -24,7 +24,6 @@ import os
 import smtplib
 from dataclasses import dataclass
 from datetime import datetime, time, timezone
-from email.message import EmailMessage
 from email.utils import formataddr
 from itertools import groupby
 from typing import Any
@@ -33,6 +32,7 @@ from urllib.parse import urlencode
 from itsdangerous import BadSignature, URLSafeSerializer
 
 from . import db
+from .email_envelope import build_envelope
 
 log = logging.getLogger(__name__)
 
@@ -69,6 +69,7 @@ class EmailConfig:
     app_url: str
     bundle_threshold: int
     enabled: bool
+    unsubscribe_mailto: str
 
     @classmethod
     def from_env(cls) -> "EmailConfig":
@@ -84,6 +85,16 @@ class EmailConfig:
             app_url=os.environ.get("APP_URL", "http://localhost:8000").rstrip("/"),
             bundle_threshold=int(os.environ.get("EMAIL_BUNDLE_THRESHOLD", "5")),
             enabled=os.environ.get("EMAIL_ENABLED", "1") not in ("0", "false", "False"),
+            # v0.18.0: the `List-Unsubscribe: <mailto:…>` target on
+            # invite + notification mail. Defaults to the From
+            # address when unset; a deployment can route opt-out
+            # mail to a separate mailbox (e.g., a humans-monitored
+            # account distinct from the no-reply notifications
+            # sender) by setting this explicitly.
+            unsubscribe_mailto=os.environ.get(
+                "EMAIL_UNSUBSCRIBE_MAILTO",
+                os.environ.get("EMAIL_FROM", "notifications@wiggleverse.local"),
+            ).strip(),
         )
 
 
@@ -98,6 +109,14 @@ def _signer() -> URLSafeSerializer:
 
 
 def make_unsubscribe_url(user_id: int, category: str) -> str:
+    """Build the §15.4 per-category one-click URL.
+
+    `category` is one of `personal-direct`, `structural`,
+    `admin-actionable` (the three per-category flags) or `all`
+    (v0.18.0: the bundle path, which sets `email_opt_out_all = 1`
+    because a bundle covers multiple categories and a per-category
+    opt-out wouldn't honor the user's intent).
+    """
     cfg = EmailConfig.from_env()
     token = _signer().dumps({"u": user_id, "c": category})
     qs = urlencode({"t": token})
@@ -250,7 +269,21 @@ def _send_one(user: Any, notif_id: int, payload: dict, category: str) -> None:
         return
     subject = _subject(payload)
     body = _body(payload, user["id"], category, cfg)
-    sent = _deliver(cfg, user["email"], subject, body)
+    # v0.18.0: notification mail is bulk-adjacent (a watcher can
+    # accumulate dozens of structural events on a busy RFC), so it
+    # carries the full one-click unsubscribe — Gmail and Yahoo
+    # require this for senders at OHM's volume tier per RFC 8058.
+    unsubscribe_url = make_unsubscribe_url(user["id"], category)
+    sent = _deliver(
+        cfg,
+        user["email"],
+        subject,
+        body,
+        unsubscribe_mailto=cfg.unsubscribe_mailto,
+        unsubscribe_url=unsubscribe_url,
+        kind="notification",
+        notification_id=notif_id,
+    )
     if not sent:
         return
     db.conn().execute(
@@ -305,23 +338,65 @@ def _deep_link(payload: dict, cfg: EmailConfig) -> str:
     return cfg.app_url
 
 
-def _deliver(cfg: EmailConfig, to_address: str, subject: str, body: str) -> bool:
+def _deliver(
+    cfg: EmailConfig,
+    to_address: str,
+    subject: str,
+    body: str,
+    *,
+    unsubscribe_mailto: str | None = None,
+    unsubscribe_url: str | None = None,
+    kind: str = "notification",
+    notification_id: int | None = None,
+) -> bool:
+    """Build the envelope via the shared `build_envelope` helper and
+    hand it to SMTP.
+
+    The `_SENT` buffer carries the helper's `EmailMessage` under
+    `message` plus the legacy `to`/`from`/`subject`/`body` keys for
+    backward-compatibility with tests that read those directly.
+    Newer tests can assert on the header surface by inspecting
+    `envelope["message"]`.
+
+    v0.18.0 Slice 4: also writes one row to `outbound_emails`
+    capturing the attempt. status='sent' on success, 'failed' on
+    SMTP exception, 'deferred' on the dev-fallback path (no
+    SMTP_HOST configured — the send didn't happen, but the row
+    records the attempt so the admin endpoint can answer "did the
+    framework try?").
+    """
+    msg = build_envelope(
+        to_address=to_address,
+        from_address=cfg.from_address,
+        from_name=cfg.from_name,
+        subject=subject,
+        body_plain=body,
+        unsubscribe_mailto=unsubscribe_mailto,
+        unsubscribe_url=unsubscribe_url,
+    )
     envelope = {
         "to": to_address,
         "from": formataddr((cfg.from_name, cfg.from_address)),
         "subject": subject,
         "body": body,
+        "message": msg,
+        "kind": kind,
     }
     _SENT.append(envelope)
+    message_id = msg["Message-ID"]
     if not cfg.smtp_host:
         log.info("email (stdout fallback): to=%s subject=%s", to_address, subject)
+        record_outbound(
+            to_address=to_address,
+            from_address=cfg.from_address,
+            subject=subject,
+            kind=kind,
+            status="deferred",
+            message_id=message_id,
+            notification_id=notification_id,
+        )
         return True
     try:
-        msg = EmailMessage()
-        msg["From"] = envelope["from"]
-        msg["To"] = to_address
-        msg["Subject"] = subject
-        msg.set_content(body)
         smtp = smtplib.SMTP(cfg.smtp_host, cfg.smtp_port, timeout=30)
         try:
             if cfg.smtp_starttls:
@@ -331,12 +406,78 @@ def _deliver(cfg: EmailConfig, to_address: str, subject: str, body: str) -> bool
             smtp.send_message(msg)
         finally:
             smtp.quit()
+        record_outbound(
+            to_address=to_address,
+            from_address=cfg.from_address,
+            subject=subject,
+            kind=kind,
+            status="sent",
+            message_id=message_id,
+            notification_id=notification_id,
+        )
         return True
-    except Exception:
+    except Exception as exc:
         log.exception("email send failed: to=%s subject=%s", to_address, subject)
+        record_outbound(
+            to_address=to_address,
+            from_address=cfg.from_address,
+            subject=subject,
+            kind=kind,
+            status="failed",
+            error=f"{type(exc).__name__}: {exc}",
+            message_id=message_id,
+            notification_id=notification_id,
+        )
         return False
 
 
+def record_outbound(
+    *,
+    to_address: str,
+    from_address: str,
+    subject: str,
+    kind: str,
+    status: str,
+    error: str | None = None,
+    notification_id: int | None = None,
+    message_id: str | None = None,
+) -> int | None:
+    """v0.18.0 Slice 4: write one row to `outbound_emails`.
+
+    Returns the inserted row's id, or `None` if the DB connection
+    isn't initialized (which happens in unit tests that don't boot
+    the full app — the write is best-effort and never raises).
+    """
+    try:
+        cur = db.conn().execute(
+            """
+            INSERT INTO outbound_emails
+                (to_address, from_address, subject, kind, sent_at, status,
+                 error, notification_id, message_id)
+            VALUES (?, ?, ?, ?, datetime('now'), ?, ?, ?, ?)
+            """,
+            (
+                to_address,
+                from_address,
+                subject,
+                kind,
+                status,
+                error,
+                notification_id,
+                message_id,
+            ),
+        )
+        return cur.lastrowid
+    except RuntimeError:
+        # db.conn() raises RuntimeError if init() hasn't been called.
+        # Pure-helper unit tests for build_envelope hit this path; the
+        # audit row is best-effort and not part of the contract.
+        return None
+    except Exception:
+        log.exception("outbound_emails write failed: to=%s subject=%s", to_address, subject)
+        return None
+
+
 # ---------------------------------------------------------------------------
 # Quiet-hours release pass — called from the digest job
 # ---------------------------------------------------------------------------
@@ -440,13 +581,27 @@ def _send_bundle(cfg: EmailConfig, user: Any, emailable: list) -> int:
         for r, _cat, extras in group_rows:
             summary = _summary_for(r["event_kind"], r["actor_display"], r["rfc_title"], extras)
             sections.append(f"  · {summary}")
+    # v0.18.0: the bundle covers multiple categories, so a
+    # per-category opt-out can't honor the user's intent. The
+    # `all` category lands at the §15.4 endpoint and sets
+    # `email_opt_out_all = 1`.
+    unsubscribe_url = make_unsubscribe_url(user["id"], "all")
     body = (
         "Activity on RFCs you watch, accumulated during your quiet hours:\n"
         + "\n".join(sections)
         + f"\n\nOpen your inbox: {cfg.app_url}/inbox\n"
         + f"Manage all preferences: {cfg.app_url}/settings/notifications\n"
+        + f"Unsubscribe from all email: {unsubscribe_url}\n"
+    )
+    sent = _deliver(
+        cfg,
+        user["email"],
+        subject,
+        body,
+        unsubscribe_mailto=cfg.unsubscribe_mailto,
+        unsubscribe_url=unsubscribe_url,
+        kind="bundle",
     )
-    sent = _deliver(cfg, user["email"], subject, body)
     if not sent:
         return 0
     ids = [r["id"] for r, _, _ in emailable]

backend/app/email_envelope.py

@@ -0,0 +1,143 @@
+"""v0.18.0 / roadmap items #18 + #20: a shared envelope builder.
+
+Every outbound mail in rfc-app today (OTC, admin-invite, watcher
+notification, "while you were away" bundle, per-RFC invite) constructs
+its own `email.message.EmailMessage` ad-hoc. The four sites diverged
+just enough to be a deliverability hazard: missing `Date`, missing
+`Message-ID`, no `Auto-Submitted`, no `List-Unsubscribe` on the
+bulk-adjacent paths, no `multipart/alternative` body.
+
+This module is the one place an `EmailMessage` is constructed. Every
+send path imports `build_envelope` and calls it; the headers that
+matter for inbox placement (Date, Message-ID, Auto-Submitted) land
+uniformly, and the per-kind variations (unsubscribe semantics,
+HTML alternative) are explicit arguments rather than buried in
+each call site.
+
+Per the v0.18.0 proposal at `~/git/ohm-infra/RFC-APP-EMAIL-HYGIENE-PROPOSAL.md`,
+the per-kind unsubscribe matrix is:
+
+  * OTC: no `List-Unsubscribe` (the recipient explicitly requested
+    the code; advertising an unsubscribe header would imply OHM has
+    them on a list, which it doesn't).
+  * Admin invite / per-RFC invite: `mailto:` form only (the
+    recipient isn't a user yet, so there's no per-user opt-out row
+    to flip; the operator handles ad-hoc opt-outs manually).
+  * Watcher notification / bundle: full `mailto:` + signed-URL
+    `List-Unsubscribe` plus `List-Unsubscribe-Post:
+    List-Unsubscribe=One-Click` per RFC 8058 (Gmail and Yahoo
+    enforce this for bulk-adjacent senders).
+
+The `is_transactional` flag governs `Auto-Submitted: auto-generated`,
+which prevents auto-responder loops on every kind of mail we send.
+All five mail kinds today are transactional in the SMTP sense (no
+human is at the From mailbox watching for replies), so the default
+is True; the argument is exposed for future symmetry.
+"""
+from __future__ import annotations
+
+from email.message import EmailMessage
+from email.utils import formataddr, formatdate, make_msgid
+
+
+def build_envelope(
+    *,
+    to_address: str,
+    from_address: str,
+    from_name: str,
+    subject: str,
+    body_plain: str,
+    body_html: str | None = None,
+    reply_to: str | None = None,
+    unsubscribe_mailto: str | None = None,
+    unsubscribe_url: str | None = None,
+    is_transactional: bool = True,
+    msgid_domain: str | None = None,
+) -> EmailMessage:
+    """Compose an `EmailMessage` with hardened headers.
+
+    `to_address` / `from_address` are bare RFC 5322 addresses;
+    `from_name` is the display label that goes through `formataddr`
+    so spaces / commas in the display string are encoded correctly.
+
+    `body_plain` is mandatory. `body_html`, if supplied, lands as the
+    second part of a `multipart/alternative` body — mail clients
+    that prefer HTML render it; clients that don't fall back to the
+    plain part. The text/plain part comes first per RFC 2046, so a
+    plain-text client that picks the first body gets the readable
+    text.
+
+    `reply_to`, when set, lets a send path point replies at a
+    different mailbox than the From line (e.g., a watcher
+    notification with From=notifications@... but Reply-To=
+    ohm@... so a confused recipient who hits Reply lands at a
+    monitored mailbox).
+
+    `unsubscribe_mailto` / `unsubscribe_url` populate
+    `List-Unsubscribe`. If `unsubscribe_url` is set, the helper also
+    emits `List-Unsubscribe-Post: List-Unsubscribe=One-Click` per
+    RFC 8058 — Gmail and Yahoo POST that payload on the user's
+    one-click action. (Send paths that wire `unsubscribe_url`
+    therefore MUST also expose a matching POST endpoint that accepts
+    the same token; see `api_notifications.py:email_unsubscribe`.)
+
+    `msgid_domain` defaults to the @-domain of `from_address` so
+    Message-IDs are aligned with the sending domain by default. A
+    deployment that wants the Message-ID domain to track a different
+    surface (e.g., a tracking-domain that's separate from the From
+    domain) can override.
+
+    `Date` is RFC 5322 formatted via `email.utils.formatdate`; the
+    `localtime=True` setting picks the running process's local
+    timezone, which is what every popular MUA does too. (A
+    deployment running in UTC stamps UTC; that's correct, not a
+    bug.)
+    """
+    msg = EmailMessage()
+    msg["From"] = formataddr((from_name, from_address))
+    msg["To"] = to_address
+    msg["Subject"] = subject
+    msg["Date"] = formatdate(localtime=True)
+    # If the caller didn't pin a Message-ID domain, derive it from the
+    # From address. `make_msgid` accepts None and falls back to the
+    # local hostname, which is the wrong shape for a deliverable
+    # message (the hostname might be `gke-pool-xxx`); a deployment
+    # without a configured From would surface that as a build-time
+    # config error elsewhere, so the fallback here is just defensive.
+    if msgid_domain is None:
+        if "@" in from_address:
+            msgid_domain = from_address.split("@", 1)[1]
+        else:
+            msgid_domain = "localhost"
+    msg["Message-ID"] = make_msgid(domain=msgid_domain)
+    if reply_to:
+        msg["Reply-To"] = reply_to
+    if is_transactional:
+        # RFC 3834: prevents auto-responders (vacation replies, etc.)
+        # from triggering on this message. Every kind of mail rfc-app
+        # sends today is transactional in this sense.
+        msg["Auto-Submitted"] = "auto-generated"
+    if unsubscribe_mailto or unsubscribe_url:
+        parts: list[str] = []
+        if unsubscribe_mailto:
+            parts.append(f"<mailto:{unsubscribe_mailto}>")
+        if unsubscribe_url:
+            parts.append(f"<{unsubscribe_url}>")
+        msg["List-Unsubscribe"] = ", ".join(parts)
+        if unsubscribe_url:
+            # RFC 8058 one-click. Gmail and Yahoo POST the payload
+            # `List-Unsubscribe=One-Click` to the URL on the user's
+            # one-click action; the matching POST endpoint must be
+            # idempotent and not require auth. See
+            # `api_notifications.py` for the receiver.
+            msg["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click"
+    if body_html:
+        # multipart/alternative: text/plain first, text/html second.
+        # `set_content` sets the first part (and the message's main
+        # body); `add_alternative` adds the second part and
+        # restructures the message as multipart/alternative.
+        msg.set_content(body_plain)
+        msg.add_alternative(body_html, subtype="html")
+    else:
+        msg.set_content(body_plain)
+    return msg

backend/app/email_invite.py

@@ -0,0 +1,166 @@
+"""Outbound admin-invite email — a thin wrapper over the existing SMTP layer.
+
+v0.17.0 / roadmap item #16: when an admin uses `POST /api/admin/users` to
+create-with-invite, this module composes and sends the invite envelope.
+
+Structurally distinct from:
+
+  * `email_otc.py` (v0.7.0) — that one carries a credential the user
+    just requested; this one carries a credential the admin is sending
+    unsolicited.
+  * `email.py` (§15.4 notification mailer) — that one is inbox-driven,
+    bundled, with category opt-outs; this one is a single transactional
+    outbound to a person who does not yet have an inbox.
+  * v0.9.0's `new_beta_request` admin notification — that one is
+    invitee-to-admin (an existing pending user asking to be let in);
+    this one is admin-to-invitee (an admin reaching out to seed access).
+
+So this module reuses `EmailConfig.from_env()` for the SMTP plumbing
+and the From identity, but writes its own envelope. In dev (no
+SMTP_HOST set), the envelope is logged at INFO level and pushed to
+the same `_SENT` buffer the notification mailer uses, so the
+integration tests can assert on the outbound shape without standing
+up an SMTP server.
+
+The send is synchronous. The admin endpoint returns 200 on the
+create-row half regardless of send outcome — a transient SMTP
+failure should not roll back the invite (an admin can re-send via a
+future "resend invite" gesture, deferred to a follow-up release).
+"""
+from __future__ import annotations
+
+import logging
+import smtplib
+from email.utils import formataddr
+
+from .email import EmailConfig, _SENT, record_outbound
+from .email_envelope import build_envelope
+
+log = logging.getLogger(__name__)
+
+
+def send_invite_email(
+    *,
+    to_address: str,
+    claim_url: str,
+    inviter_display: str,
+    inviter_email: str,
+    custom_message: str = "",
+) -> bool:
+    """Compose and send the admin-invite email. Returns True on the
+    happy path; False on SMTP failure. The notifier-side buffer
+    `_SENT` is appended either way so tests can assert on content.
+
+    The body names the inviting admin, embeds the optional custom
+    message in a clearly delimited block if present, and ships the
+    claim link. The subject names the inviter so the recipient can
+    recognize the sender at a glance in their inbox preview.
+    """
+    cfg = EmailConfig.from_env()
+    subject = _subject(inviter_display, cfg)
+    body = _body(claim_url, inviter_display, inviter_email, custom_message, cfg)
+    # v0.18.0: invite mail carries a `List-Unsubscribe: <mailto:…>`
+    # only (no signed URL) — the invitee isn't a user yet, so there
+    # is no per-user opt-out row to flip. The operator handles
+    # ad-hoc opt-outs from the mailto: target. Per the proposal's
+    # "Tradeoff discussion": the invite was unsolicited from the
+    # recipient's perspective, so the courtesy header is right;
+    # but it can't be a one-click URL because the row doesn't
+    # exist yet.
+    msg = build_envelope(
+        to_address=to_address,
+        from_address=cfg.from_address,
+        from_name=cfg.from_name,
+        subject=subject,
+        body_plain=body,
+        unsubscribe_mailto=cfg.unsubscribe_mailto,
+    )
+    envelope = {
+        "to": to_address,
+        "from": formataddr((cfg.from_name, cfg.from_address)),
+        "subject": subject,
+        "body": body,
+        "kind": "invite",
+        "message": msg,
+    }
+    _SENT.append(envelope)
+
+    message_id = msg["Message-ID"]
+    if not cfg.enabled:
+        log.info("invite email disabled (EMAIL_ENABLED=0): to=%s", to_address)
+        record_outbound(
+            to_address=to_address, from_address=cfg.from_address,
+            subject=subject, kind="invite", status="deferred", message_id=message_id,
+        )
+        return True
+    if not cfg.smtp_host:
+        # Dev fallback: surface the claim URL at INFO so the operator can
+        # complete a claim flow without an SMTP relay. In production
+        # SMTP_HOST is always set per OHM's overlay.
+        log.info("invite email (stdout fallback): to=%s claim_url=%s", to_address, claim_url)
+        record_outbound(
+            to_address=to_address, from_address=cfg.from_address,
+            subject=subject, kind="invite", status="deferred", message_id=message_id,
+        )
+        return True
+
+    try:
+        smtp = smtplib.SMTP(cfg.smtp_host, cfg.smtp_port, timeout=30)
+        try:
+            if cfg.smtp_starttls:
+                smtp.starttls()
+            if cfg.smtp_user:
+                smtp.login(cfg.smtp_user, cfg.smtp_password)
+            smtp.send_message(msg)
+        finally:
+            smtp.quit()
+        record_outbound(
+            to_address=to_address, from_address=cfg.from_address,
+            subject=subject, kind="invite", status="sent", message_id=message_id,
+        )
+        return True
+    except Exception as exc:
+        log.exception("invite email send failed: to=%s", to_address)
+        record_outbound(
+            to_address=to_address, from_address=cfg.from_address,
+            subject=subject, kind="invite", status="failed",
+            error=f"{type(exc).__name__}: {exc}", message_id=message_id,
+        )
+        return False
+
+
+def _subject(inviter_display: str, cfg: EmailConfig) -> str:
+    """e.g. "You're invited to Wiggleverse by Ben Stull"."""
+    inviter = inviter_display or "an admin"
+    return f"You're invited to {cfg.from_name} by {inviter}"
+
+
+def _body(
+    claim_url: str,
+    inviter_display: str,
+    inviter_email: str,
+    custom_message: str,
+    cfg: EmailConfig,
+) -> str:
+    inviter = inviter_display or "An admin"
+    inviter_suffix = f" ({inviter_email})" if inviter_email else ""
+    message_block = ""
+    if custom_message.strip():
+        # Indent the custom message so it reads as a clearly-delimited
+        # quote rather than running together with the framework's
+        # framing text. Per-line indent keeps multi-line messages
+        # visually grouped in plain-text mail clients.
+        indented = "\n".join(f"    {line}" for line in custom_message.strip().splitlines())
+        message_block = f"\nA personal note from {inviter}:\n\n{indented}\n"
+
+    return (
+        f"{inviter}{inviter_suffix} has invited you to {cfg.from_name}.\n"
+        f"{message_block}\n"
+        f"Click the link below to claim your account and sign in.\n"
+        f"This link is single-use and expires in 7 days.\n\n"
+        f"    {claim_url}\n\n"
+        f"If you weren't expecting this invitation, you can ignore this\n"
+        f"email — no account becomes active until you click the link.\n\n"
+        f"---\n"
+        f"{cfg.from_name} · {cfg.app_url}\n"
+    )

backend/app/email_otc.py

@@ -23,10 +23,10 @@ from __future__ import annotations
 
 import logging
 import smtplib
-from email.message import EmailMessage
 from email.utils import formataddr
 
-from .email import EmailConfig, _SENT
+from .email import EmailConfig, _SENT, record_outbound
+from .email_envelope import build_envelope
 
 log = logging.getLogger(__name__)
 
@@ -44,31 +44,48 @@ def send_otc_email(to_address: str, code: str) -> bool:
     cfg = EmailConfig.from_env()
     subject = f"Your sign-in code for {cfg.from_name}"
     body = _body(code, cfg)
+    # v0.18.0: OTC mail carries NO List-Unsubscribe — the recipient
+    # explicitly requested the code; advertising an unsubscribe
+    # header would imply OHM has them on a list, which it doesn't.
+    # See the proposal's "Tradeoff discussion" for the binding
+    # rationale.
+    msg = build_envelope(
+        to_address=to_address,
+        from_address=cfg.from_address,
+        from_name=cfg.from_name,
+        subject=subject,
+        body_plain=body,
+    )
     envelope = {
         "to": to_address,
         "from": formataddr((cfg.from_name, cfg.from_address)),
         "subject": subject,
         "body": body,
         "kind": "otc",
+        "message": msg,
     }
     _SENT.append(envelope)
 
+    message_id = msg["Message-ID"]
     if not cfg.enabled:
         log.info("otc email disabled (EMAIL_ENABLED=0): to=%s", to_address)
+        record_outbound(
+            to_address=to_address, from_address=cfg.from_address,
+            subject=subject, kind="otc", status="deferred", message_id=message_id,
+        )
         return True
     if not cfg.smtp_host:
         # Dev fallback: surface the code at INFO so the operator can
         # complete a sign-in flow without an SMTP relay. In production
         # SMTP_HOST is always set per OHM's overlay.
         log.info("otc email (stdout fallback): to=%s code=%s", to_address, code)
+        record_outbound(
+            to_address=to_address, from_address=cfg.from_address,
+            subject=subject, kind="otc", status="deferred", message_id=message_id,
+        )
         return True
 
     try:
-        msg = EmailMessage()
-        msg["From"] = envelope["from"]
-        msg["To"] = to_address
-        msg["Subject"] = subject
-        msg.set_content(body)
         smtp = smtplib.SMTP(cfg.smtp_host, cfg.smtp_port, timeout=30)
         try:
             if cfg.smtp_starttls:
@@ -78,9 +95,18 @@ def send_otc_email(to_address: str, code: str) -> bool:
             smtp.send_message(msg)
         finally:
             smtp.quit()
+        record_outbound(
+            to_address=to_address, from_address=cfg.from_address,
+            subject=subject, kind="otc", status="sent", message_id=message_id,
+        )
         return True
-    except Exception:
+    except Exception as exc:
         log.exception("otc email send failed: to=%s", to_address)
+        record_outbound(
+            to_address=to_address, from_address=cfg.from_address,
+            subject=subject, kind="otc", status="failed",
+            error=f"{type(exc).__name__}: {exc}", message_id=message_id,
+        )
         return False
 
 

backend/app/invites.py

@@ -0,0 +1,425 @@
+"""§6.1 / v0.17.0: admin-create user with role + invite email (roadmap item #16).
+
+Distinguishes from the v0.8.0 self-serve beta-access flow:
+
+  * **Self-serve (v0.8.0)** — anyone with an email can request OTC sign-in;
+    a fresh `users` row lands in `permission_state='pending'`; an admin
+    grants or revokes via the v0.9.0 user-management page.
+
+  * **Admin-create (v0.17.0)** — an admin types first/last/email/role
+    *before* the invitee has signed in. The framework provisions the
+    `users` row with the chosen role and `permission_state='granted'`
+    (the admin's hand is the grant) and `last_seen_at IS NULL` as the
+    "invited but not yet arrived" discriminator. An invite-token row
+    lands in `user_invite_tokens`; the admin's chosen `custom_message`
+    (if any) rides in the email body alongside the claim link.
+
+  * **Claim flow** — the invitee clicks the link, which lands them at
+    `/invites/claim?token=…`. The page POSTs `/api/invites/claim` with
+    the token. The framework verifies the token (not expired, not
+    claimed, hash matches), marks the row claimed, signs the user in,
+    and returns a payload telling the frontend whether to route to
+    passcode-set (if v0.10.0 passcode flow is in play and the user has
+    no passcode yet) or to `/`. **No OTC roundtrip** — clicking the
+    unique token in the email is itself proof of email control, per
+    the roadmap. This is the intentional UX shortcut for first
+    sign-in; subsequent sign-ins use the standard OTC / passcode
+    paths.
+
+The shape:
+
+  * `create_invite(...)` — provision the invitee `users` row + the
+    `user_invite_tokens` row, return the raw token for the admin
+    endpoint to put in the outbound email link.
+  * `claim(raw_token)` — validate the token, mark it claimed, return
+    the `SessionUser` the endpoint signs in. Distinguishes the failure
+    modes (`expired`, `claimed`, `unknown`, `invalid`) so the endpoint
+    can map them to HTTP 410 vs HTTP 404 cleanly.
+  * `list_pending_invites()` — return active invites for the admin
+    listing surface. Filters out claimed + expired rows so the surface
+    only shows live invites.
+
+Token shape: opaque DB token (256 bits of CSPRNG entropy via
+`secrets.token_urlsafe(32)`), bcrypt-hashed at rest. Opaque chosen
+over JWT because revocation is then a single SQL UPDATE — a JWT
+would be stateless but harder to invalidate, and admin-issued
+invites are exactly the kind of thing an admin should be able to
+yank back. The raw token only ever lives in the outbound email link
+and the inbound claim body; server-side storage is the hash.
+
+TTL: hard-coded to 7 days via `INVITE_TOKEN_TTL_DAYS`. Env-var
+configurability is a §19.2 candidate — the constant is exposed
+here as a single point of edit if a deployment wants to override.
+
+The 500-char ceiling on `custom_message` is enforced at the
+Pydantic body level in `api_admin.py`; this module trusts what
+the endpoint hands it.
+"""
+from __future__ import annotations
+
+import logging
+import secrets
+from dataclasses import dataclass
+
+import bcrypt
+
+from . import db
+from .auth import SessionUser
+
+log = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Tunables — intentionally hard-coded in v0.17.0 (§19.2 candidate to env-ify).
+# ---------------------------------------------------------------------------
+
+INVITE_TOKEN_TTL_DAYS = 7
+# 256 bits of CSPRNG entropy. `secrets.token_urlsafe(32)` yields ~43
+# URL-safe characters; the bcrypt hash is what's stored, so the raw
+# token only ever lives in the outbound email link.
+TOKEN_BYTES = 32
+# Free-text ceiling for the admin's optional custom message. Matched
+# at the Pydantic body bound in `api_admin.py`; mentioned here so the
+# bound is documented in one place.
+CUSTOM_MESSAGE_MAX_LENGTH = 500
+
+
+# ---------------------------------------------------------------------------
+# Token + hash helpers (mirror device_trust.py shape)
+# ---------------------------------------------------------------------------
+
+
+def _new_token() -> str:
+    return secrets.token_urlsafe(TOKEN_BYTES)
+
+
+def _hash(token: str) -> str:
+    return bcrypt.hashpw(token.encode("utf-8"), bcrypt.gensalt()).decode("ascii")
+
+
+def _check(token: str, token_hash: str) -> bool:
+    try:
+        return bcrypt.checkpw(token.encode("utf-8"), token_hash.encode("ascii"))
+    except (ValueError, TypeError):
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Create
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CreateOutcome:
+    """The shape returned from `create_invite`.
+
+    `raw_token` is what the admin endpoint puts in the outbound email
+    link; it never appears in storage. `invite_id` is the surrogate
+    key for the admin's "invites I've sent" listing. `invited_user_id`
+    is the freshly-provisioned `users` row id so the admin surface can
+    join through to the user-management page.
+    """
+    raw_token: str
+    invite_id: int
+    invited_user_id: int
+
+
+def create_invite(
+    *,
+    email: str,
+    first_name: str,
+    last_name: str,
+    role: str,
+    custom_message: str,
+    created_by_admin_id: int,
+) -> CreateOutcome:
+    """Provision the invitee `users` row + the `user_invite_tokens` row.
+
+    Caller (`api_admin.py`) is responsible for the admin-only auth check,
+    the self-email refusal (422), and the duplicate-email refusal (409).
+    This function trusts what it's handed and writes both rows
+    transactionally — the v0.10.0 `passcode.py` / v0.11.0 `device_trust.py`
+    helpers follow the same separation-of-concerns pattern.
+
+    The invitee `users` row is provisioned with:
+      * `permission_state='granted'` — the admin's hand is the grant;
+        the v0.8.0 self-serve `pending` queue is for the other path.
+      * `last_seen_at = NULL` — the discriminator for "invited but
+        not yet arrived" per the §16 / roadmap design. Every sign-in
+        path stamps `last_seen_at` to now, so a NULL value means the
+        invited user has not clicked through yet.
+      * `gitea_id = NULL`, `gitea_login = NULL` — same as a v0.7.0
+        OTC-provisioned user; the OAuth identity is grandfathered if
+        the user ever lands through that path.
+      * `display_name` defaults to "<first> <last>" (or local-part of
+        email if both are empty) so the user-management page reads a
+        sensible label before the user has signed in.
+      * `first_name` / `last_name` / `beta_request_reason` — the
+        first two from the admin's typed values; reason stays blank
+        (this user did not self-request access).
+    """
+    email_clean = email.strip()
+    first_clean = (first_name or "").strip()
+    last_clean = (last_name or "").strip()
+    display = " ".join(p for p in (first_clean, last_clean) if p).strip()
+    if not display:
+        display = email_clean.split("@", 1)[0] or email_clean
+
+    # 1. Provision the invitee users row. The grant is the admin's
+    # hand; no permission_events row is necessary for the grant itself
+    # (we are not transitioning from pending → granted, we are landing
+    # a fresh row directly into granted).
+    #
+    # Note on the "pending invite" discriminator: the brief floated
+    # `first_sign_in_at NULL` / `last_seen_at NULL` as the marker the
+    # admin user-management page reads off the row to render the
+    # "(pending invite)" badge. The schema didn't cooperate — the
+    # existing `users.last_seen_at` column is NOT NULL with a
+    # `datetime('now')` default (see `migrations/001_users_and_audit.sql`),
+    # and there is no `first_sign_in_at` column. Rather than introduce
+    # a schema migration to add one (the brief explicitly said "likely
+    # no `users` table changes"), the discriminator is the existence of
+    # an active row in `user_invite_tokens` joined on `invited_user_id`.
+    # The admin listing's `pending_invite` field joins through that
+    # table; the claim flow stamps `claimed_at` on the invite row,
+    # which clears the badge naturally. This shape keeps the
+    # discriminator scoped to the v0.17.0 surface and avoids
+    # double-tracking against an existing column.
+    cur = db.conn().execute(
+        """
+        INSERT INTO users (
+            gitea_id, gitea_login, email, display_name, avatar_url,
+            role, permission_state, first_name, last_name
+        )
+        VALUES (NULL, NULL, ?, ?, '', ?, 'granted', ?, ?)
+        """,
+        (email_clean, display, role, first_clean, last_clean),
+    )
+    invited_user_id = cur.lastrowid
+
+    # 2. Mint the token, hash it, write the invite row.
+    raw = _new_token()
+    h = _hash(raw)
+    cur = db.conn().execute(
+        f"""
+        INSERT INTO user_invite_tokens (
+            email, role, first_name, last_name, custom_message,
+            token_hash, expires_at, created_by_admin_id, invited_user_id
+        )
+        VALUES (?, ?, ?, ?, ?, ?, datetime('now', '+{INVITE_TOKEN_TTL_DAYS} days'), ?, ?)
+        """,
+        (
+            email_clean,
+            role,
+            first_clean,
+            last_clean,
+            (custom_message or "").strip(),
+            h,
+            created_by_admin_id,
+            invited_user_id,
+        ),
+    )
+    invite_id = cur.lastrowid
+    return CreateOutcome(
+        raw_token=raw,
+        invite_id=invite_id,
+        invited_user_id=invited_user_id,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Claim
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ClaimOutcome:
+    """The result of `claim`.
+
+    `user` is populated only on success. `reason` distinguishes the
+    failure modes so the endpoint can return distinct HTTP statuses
+    (HTTP 410 for expired/claimed — the token is dead; HTTP 400 for
+    unknown/invalid — the request shape is wrong).
+    """
+    ok: bool
+    user: SessionUser | None
+    reason: str  # 'ok' | 'invalid' | 'unknown' | 'expired' | 'claimed'
+    invite_id: int | None = None
+
+
+def claim(raw_token: str) -> ClaimOutcome:
+    """Validate the presented token and consume it.
+
+    Walks the active invite rows looking for a bcrypt hash match.
+    Mirrors `device_trust.lookup`: bcrypt's per-row salt means we
+    cannot SELECT by hash, but the set is small (a deployment's
+    outstanding invites at any moment) and bcrypt is cheap on the
+    order of milliseconds.
+
+    On a hit:
+      * Mark the row claimed (stamp `claimed_at = now`,
+        `claimed_by_user_id = invited_user_id` — the admin's
+        pre-provisioned row is the claimant).
+      * Stamp `last_seen_at = now` on the user row so the v0.9.0
+        admin user-management page no longer shows "(pending invite)".
+      * Return a populated `SessionUser` for the endpoint to sign in.
+
+    On a miss:
+      * `unknown` — no row matched. The token may have been forged or
+        the invite was admin-revoked.
+      * `expired` — row matched but `expires_at` is in the past.
+      * `claimed` — row matched but `claimed_at` is non-NULL. The
+        token was already consumed; the user must contact the admin
+        for a fresh invite.
+      * `invalid` — the token string itself was empty or unparseable.
+    """
+    raw = (raw_token or "").strip()
+    if not raw:
+        return ClaimOutcome(ok=False, user=None, reason="invalid")
+
+    rows = db.conn().execute(
+        """
+        SELECT id, token_hash, expires_at, claimed_at, invited_user_id, role
+          FROM user_invite_tokens
+         ORDER BY id DESC
+        """
+    ).fetchall()
+
+    matched = None
+    for row in rows:
+        if _check(raw, row["token_hash"]):
+            matched = row
+            break
+
+    if matched is None:
+        return ClaimOutcome(ok=False, user=None, reason="unknown")
+
+    if matched["claimed_at"] is not None:
+        return ClaimOutcome(
+            ok=False, user=None, reason="claimed", invite_id=matched["id"],
+        )
+
+    expired = db.conn().execute(
+        "SELECT datetime(?) < datetime('now') AS expired",
+        (matched["expires_at"],),
+    ).fetchone()["expired"]
+    if expired:
+        return ClaimOutcome(
+            ok=False, user=None, reason="expired", invite_id=matched["id"],
+        )
+
+    # Consume the row before signing in so a parallel claim of the same
+    # token cannot double-sign-in. (Mirrors `otc.verify_code`'s consume-
+    # before-provision shape.)
+    db.conn().execute(
+        """
+        UPDATE user_invite_tokens
+           SET claimed_at = datetime('now'),
+               claimed_by_user_id = invited_user_id
+         WHERE id = ?
+        """,
+        (matched["id"],),
+    )
+    # Stamp last_seen_at on the user row so the user's activity stamp
+    # is current after the claim (mirroring otc.verify_code's
+    # last-seen update on the provision path). The "(pending invite)"
+    # badge's clear is driven by the invite row's `claimed_at`
+    # transition above; this update is for the general user-listing's
+    # recency ordering.
+    db.conn().execute(
+        "UPDATE users SET last_seen_at = datetime('now') WHERE id = ?",
+        (matched["invited_user_id"],),
+    )
+
+    user_row = db.conn().execute(
+        """
+        SELECT id, gitea_id, gitea_login, email, display_name, avatar_url,
+               role, permission_state
+          FROM users
+         WHERE id = ?
+        """,
+        (matched["invited_user_id"],),
+    ).fetchone()
+    if user_row is None:
+        # The invitee user row was deleted between create_invite and
+        # claim (shouldn't happen under the FK ON DELETE CASCADE — the
+        # cascade would drop the invite row too — be defensive anyway).
+        return ClaimOutcome(
+            ok=False, user=None, reason="unknown", invite_id=matched["id"],
+        )
+
+    return ClaimOutcome(
+        ok=True,
+        user=SessionUser(
+            user_id=user_row["id"],
+            gitea_id=user_row["gitea_id"] or 0,
+            gitea_login=user_row["gitea_login"] or "",
+            display_name=user_row["display_name"],
+            email=user_row["email"] or "",
+            avatar_url=user_row["avatar_url"] or "",
+            role=user_row["role"],
+            permission_state=user_row["permission_state"] or "granted",
+        ),
+        reason="ok",
+        invite_id=matched["id"],
+    )
+
+
+# ---------------------------------------------------------------------------
+# List pending invites — for the admin's review surface
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class PendingInviteRow:
+    """The shape the `GET /api/admin/users/invites` endpoint returns.
+
+    Note the absence of `token_hash` — the hash is structurally private,
+    and the surface has no use for it. The raw token is also not on
+    the listing; it lives only in the email link.
+    """
+    id: int
+    email: str
+    role: str
+    first_name: str
+    last_name: str
+    custom_message: str
+    created_at: str
+    expires_at: str
+    created_by_admin_id: int
+    invited_user_id: int
+
+
+def list_pending_invites() -> list[PendingInviteRow]:
+    """Active invites (not claimed, not expired), freshest first.
+
+    The admin's "I sent these but they haven't been claimed yet" view.
+    Filters mirror the `device_trust.list_for_user` shape: the surface
+    only shows live records the framework would actually accept on a
+    presented token.
+    """
+    rows = db.conn().execute(
+        """
+        SELECT id, email, role, first_name, last_name, custom_message,
+               created_at, expires_at, created_by_admin_id, invited_user_id
+          FROM user_invite_tokens
+         WHERE claimed_at IS NULL
+           AND datetime(expires_at) > datetime('now')
+         ORDER BY created_at DESC, id DESC
+        """
+    ).fetchall()
+    return [
+        PendingInviteRow(
+            id=row["id"],
+            email=row["email"],
+            role=row["role"],
+            first_name=row["first_name"] or "",
+            last_name=row["last_name"] or "",
+            custom_message=row["custom_message"] or "",
+            created_at=row["created_at"],
+            expires_at=row["expires_at"],
+            created_by_admin_id=row["created_by_admin_id"],
+            invited_user_id=row["invited_user_id"],
+        )
+        for row in rows
+    ]

backend/app/main.py

@@ -10,8 +10,8 @@ import logging
 import secrets
 from contextlib import asynccontextmanager
 
-from fastapi import APIRouter, FastAPI, HTTPException, Request
-from fastapi.responses import RedirectResponse
+from fastapi import APIRouter, FastAPI, HTTPException, Request, Response
+from fastapi.responses import JSONResponse, RedirectResponse
 from pydantic import BaseModel, Field
 from starlette.middleware.sessions import SessionMiddleware
 
@@ -20,12 +20,15 @@ from . import (
     auth,
     cache,
     db,
+    device_trust as device_trust_mod,
     digest,
     email_otc,
     hygiene,
+    invites as invites_mod,
     otc,
     passcode as passcode_mod,
     providers as providers_mod,
+    turnstile,
     webhooks,
 )
 from .bot import Bot
@@ -38,11 +41,25 @@ log = logging.getLogger("rfc_app")
 
 class OtcRequestBody(BaseModel):
     email: str = Field(min_length=3, max_length=320)
+    # v0.12.0 / roadmap item #10: CloudFlare Turnstile token from the
+    # frontend widget. Optional in the body so a deployment that has
+    # not yet wired the Turnstile site key (or a dev environment with
+    # the widget intentionally skipped) still routes through the same
+    # endpoint; the backend turnstile.verify_token call decides whether
+    # to admit the request based on `TURNSTILE_REQUIRED` + presence of
+    # the secret.
+    turnstile_token: str | None = Field(default=None, max_length=4096)
 
 
 class OtcVerifyBody(BaseModel):
     email: str = Field(min_length=3, max_length=320)
     code: str = Field(min_length=1, max_length=16)
+    # v0.11.0 — "trust this device for 30 days" checkbox on the Login.jsx
+    # OTC step. When true and verify succeeds, the server issues a fresh
+    # device-trust row and sets the `rfc_device_trust` cookie on the
+    # response. Defaults to false so existing clients that don't send
+    # the flag continue to behave the way they did pre-v0.11.0.
+    trust_device: bool = False
 
 
 class PasscodeSetBody(BaseModel):
@@ -52,6 +69,27 @@ class PasscodeSetBody(BaseModel):
 class PasscodeVerifyBody(BaseModel):
     email: str = Field(min_length=3, max_length=320)
     passcode: str = Field(min_length=1, max_length=64)
+    # v0.11.0 — same trust-device opt-in as the OTC verify body.
+    trust_device: bool = False
+
+
+class InviteClaimBody(BaseModel):
+    """v0.17.0 / roadmap item #16 — claim an admin-issued invite token.
+
+    The frontend `/invites/claim?token=…` page reads the token from
+    the URL and POSTs it here. The body bound matches the
+    `secrets.token_urlsafe(32)` output shape (~43 URL-safe chars);
+    the upper bound stays generous in case `TOKEN_BYTES` is ever
+    raised. The token-shape is opaque to this layer — `invites.claim`
+    bcrypt-checks it against the active candidate set.
+    """
+    token: str = Field(min_length=1, max_length=512)
+    # v0.11.0-style opt-in: the claim flow's "trust this device" gesture
+    # is bundled here so the invitee can land trusted on first sign-in
+    # without an extra roundtrip. Defaults to false so the gesture is
+    # explicit (the frontend modal renders a checkbox alongside the
+    # claim CTA).
+    trust_device: bool = False
 
 
 @asynccontextmanager
@@ -117,6 +155,48 @@ def create_app() -> FastAPI:
 app = create_app()
 
 
+def _set_device_trust_cookie(response: Response, raw_token: str) -> None:
+    """Attach the v0.11.0 device-trust cookie to the response.
+
+    HttpOnly + Secure + SameSite=Lax + 30-day Max-Age + Path=/. The
+    cookie value is the raw token; server-side storage is the hash.
+    The cookie is "essential" per the v0.13.0 cookie-consent contract
+    (it is part of authentication), so we set it regardless of the
+    user's analytics / other-cookies choice.
+
+    Secure=True means the cookie is only ever sent over HTTPS. The
+    SessionMiddleware in `create_app` keeps `https_only=False` for
+    dev parity, but the device-trust cookie holds a 30-day credential
+    and must not travel cleartext — production deployments serve over
+    HTTPS, so Secure on the device-trust cookie is non-negotiable.
+    """
+    response.set_cookie(
+        key=device_trust_mod.COOKIE_NAME,
+        value=raw_token,
+        max_age=device_trust_mod.COOKIE_MAX_AGE_SECONDS,
+        path="/",
+        secure=True,
+        httponly=True,
+        samesite="lax",
+    )
+
+
+def _clear_device_trust_cookie(response: Response) -> None:
+    """Delete the device-trust cookie on the response.
+
+    Used when the framework detects a presented cookie that is
+    expired, revoked, or otherwise stale — the next request from
+    this device will not carry a dead token.
+    """
+    response.delete_cookie(
+        key=device_trust_mod.COOKIE_NAME,
+        path="/",
+        secure=True,
+        httponly=True,
+        samesite="lax",
+    )
+
+
 def _oauth_router(config) -> APIRouter:
     router = APIRouter()
 
@@ -164,7 +244,27 @@ def _oauth_router(config) -> APIRouter:
     # ---------------------------------------------------------------
 
     @router.post("/auth/otc/request")
-    async def otc_request(body: OtcRequestBody):
+    async def otc_request(body: OtcRequestBody, request: Request):
+        # v0.12.0 / roadmap item #10: gate the request on a successful
+        # Turnstile siteverify before the bcrypt hash + SMTP send. The
+        # check runs first so a failed challenge spends no rate budget
+        # and produces no envelope. When the operator has not wired the
+        # secret AND TURNSTILE_REQUIRED=false (the default), the gate
+        # opens — see `backend/app/turnstile.py` for the full matrix.
+        client_ip = request.client.host if request.client else None
+        ts = turnstile.verify_token(body.turnstile_token, client_ip=client_ip)
+        if not ts.ok:
+            if ts.reason == "misconfigured":
+                # TURNSTILE_REQUIRED=true but the secret is unset. This
+                # is an operator/config problem, not a client problem;
+                # surface as 500 so the operator notices in their logs
+                # rather than blaming the user's browser.
+                raise HTTPException(500, "auth misconfigured")
+            # missing-token / failed / network → uniform 400 so the
+            # response does not enumerate which leg of the challenge
+            # broke. The reason is in the server logs.
+            raise HTTPException(400, "verification failed")
+
         outcome = otc.request_code(body.email)
         if outcome.reason == "cooldown":
             # Loud failure per the rate-limit primitive — the abuse
@@ -177,7 +277,7 @@ def _oauth_router(config) -> APIRouter:
         return {"ok": True}
 
     @router.post("/auth/otc/verify")
-    async def otc_verify(body: OtcVerifyBody, request: Request):
+    async def otc_verify(body: OtcVerifyBody, request: Request, response: Response):
         result = otc.verify_code(body.email, body.code)
         if not result.ok or result.user is None:
             raise HTTPException(400, "Invalid or expired code")
@@ -202,6 +302,18 @@ def _oauth_router(config) -> APIRouter:
             and not last_name
             and not beta_request_reason
         )
+        # v0.11.0 — opt-in device trust. The checkbox lives on the
+        # Login.jsx OTC step; when true, the server mints a fresh
+        # device-trust row and sets the long-lived cookie. The cookie
+        # is "essential" per the v0.13.0 consent contract (it is part
+        # of authentication, not analytics) so it lands regardless of
+        # the user's analytics / other-cookies choice. We capture the
+        # User-Agent at issuance so the /settings/devices surface can
+        # render a rough device label.
+        if body.trust_device:
+            ua = request.headers.get("user-agent", "")
+            outcome = device_trust_mod.issue(result.user.user_id, ua)
+            _set_device_trust_cookie(response, outcome.raw_token)
         return {
             "ok": True,
             "user": {
@@ -254,12 +366,16 @@ def _oauth_router(config) -> APIRouter:
         return {"ok": True}
 
     @router.post("/auth/passcode/verify")
-    async def passcode_verify(body: PasscodeVerifyBody, request: Request):
+    async def passcode_verify(body: PasscodeVerifyBody, request: Request, response: Response):
         """Sign in with email + passcode. Returns the standard session
         payload on success; HTTP 423 with `locked_until` when the
         account is in the lockout window; HTTP 400 for every other
         failure (the wrong-vs-unknown distinction is intentionally
-        collapsed so a probing client cannot enumerate emails)."""
+        collapsed so a probing client cannot enumerate emails).
+
+        v0.11.0: the body's `trust_device` flag, if true, mints a
+        fresh device-trust row and sets the long-lived cookie. Same
+        opt-in contract as `/auth/otc/verify`."""
         result = passcode_mod.verify_passcode(body.email, body.passcode)
         if result.reason == "locked":
             raise HTTPException(
@@ -272,6 +388,10 @@ def _oauth_router(config) -> APIRouter:
         if not result.ok or result.user is None:
             raise HTTPException(400, "Invalid passcode")
         auth.store_session(request, result.user)
+        if body.trust_device:
+            ua = request.headers.get("user-agent", "")
+            outcome = device_trust_mod.issue(result.user.user_id, ua)
+            _set_device_trust_cookie(response, outcome.raw_token)
         return {
             "ok": True,
             "user": {
@@ -282,4 +402,151 @@ def _oauth_router(config) -> APIRouter:
             },
         }
 
+    # ---------------------------------------------------------------
+    # v0.17.0: admin-create user + invite claim (§6.1, roadmap item #16).
+    #
+    # The admin-create surface lives at POST /api/admin/users (see
+    # api_admin.py); this endpoint is the corresponding claim path the
+    # invitee hits when they click the link in their invite email.
+    # The frontend route `/invites/claim?token=…` reads the token from
+    # the URL and POSTs it here.
+    #
+    # The claim itself is the first-sign-in for the invitee: clicking
+    # the unique token in the email is proof of email control per the
+    # roadmap, so this endpoint skips the OTC step entirely on first
+    # sign-in. The session cookie lands; the response tells the
+    # frontend whether to route to passcode-set (if v0.10.0 passcode
+    # flow is in play and the user has not yet set a passcode) or to
+    # home.
+    #
+    # The endpoint is anonymous-reachable: the entire point is to
+    # establish the session, so we do not gate it on `require_user`.
+    # The trust-device opt-in mirrors the v0.11.0 OTC/passcode verify
+    # contract (the body's `trust_device` flag, when true, mints a
+    # fresh device-trust row on the same response so the invitee
+    # lands trusted on their first device).
+    # ---------------------------------------------------------------
+
+    @router.post("/api/invites/claim")
+    async def invites_claim(body: InviteClaimBody, request: Request, response: Response):
+        result = invites_mod.claim(body.token)
+        if result.reason == "expired":
+            # The token's TTL window passed without a claim. HTTP 410
+            # (Gone) so the frontend can render a "this invite has
+            # expired — please contact the admin for a fresh one"
+            # message distinct from the generic invalid-token shape.
+            raise HTTPException(410, "This invite has expired")
+        if result.reason == "claimed":
+            # The token was already consumed. HTTP 410 for the same
+            # reason — the row is dead either way.
+            raise HTTPException(410, "This invite has already been claimed")
+        if not result.ok or result.user is None:
+            # 'unknown' / 'invalid' — the token does not match any
+            # active invite row. HTTP 400 so it reads distinct from
+            # the dead-token shape above.
+            raise HTTPException(400, "Invalid invite token")
+
+        # Establish the session. From here on the invitee is signed
+        # in as the pre-provisioned user row carrying their
+        # pre-assigned role.
+        auth.store_session(request, result.user)
+
+        # v0.11.0 — opt-in device trust on the claim response. Same
+        # contract as OTC/passcode verify: when the body's flag is
+        # true, the server mints a fresh device-trust row and sets
+        # the long-lived cookie, so the invitee skips the email step
+        # on subsequent visits to the same browser.
+        if body.trust_device:
+            ua = request.headers.get("user-agent", "")
+            outcome = device_trust_mod.issue(result.user.user_id, ua)
+            _set_device_trust_cookie(response, outcome.raw_token)
+
+        # Has the user already set a passcode? (Could only happen via
+        # an admin pre-population path that doesn't exist yet, but
+        # the response shape mirrors `/api/auth/me` so the frontend
+        # can read it without a second call.) If `needs_passcode` is
+        # true and v0.10.0 passcode flow is in play, the frontend
+        # routes to /settings/notifications#sign-in to set a passcode
+        # immediately; otherwise it routes to /.
+        row = db.conn().execute(
+            "SELECT passcode_hash FROM users WHERE id = ?",
+            (result.user.user_id,),
+        ).fetchone()
+        has_passcode = bool(row and row["passcode_hash"])
+
+        return {
+            "ok": True,
+            "user": {
+                "id": result.user.user_id,
+                "display_name": result.user.display_name,
+                "email": result.user.email,
+                "role": result.user.role,
+                "permission_state": result.user.permission_state,
+            },
+            # Roadmap §16: the claim flow skips OTC entirely; the
+            # natural next step is passcode-set (so the invitee can
+            # sign back in without needing an email roundtrip on their
+            # second visit). The frontend uses this hint to decide
+            # whether to route to the passcode-set screen or to home.
+            "needs_passcode": not has_passcode,
+        }
+
+    # ---------------------------------------------------------------
+    # v0.11.0: trust device for 30 days (§6.2, roadmap item #9).
+    #
+    # The /auth/device-trust/start endpoint resolves a presented
+    # `rfc_device_trust` cookie. If it matches a non-expired,
+    # non-revoked row, the session is re-established and the client
+    # is told to skip OTC/passcode entry. A stale cookie (expired or
+    # revoked) is cleared on the response. A miss is structurally
+    # silent — the client falls back to the email step.
+    #
+    # The endpoint is anonymous-reachable: a returning visitor with
+    # the cookie hits this before the email step. We do not gate it
+    # on a session because the entire point is to establish one.
+    # ---------------------------------------------------------------
+
+    @router.post("/auth/device-trust/start")
+    async def device_trust_start(request: Request):
+        """Sign in via a presented device-trust cookie.
+
+        On a hit, re-establishes the session in the cookie store and
+        returns a user payload shaped like /auth/otc/verify (minus
+        `needs_profile`, which a returning device-trust user is
+        structurally past — they signed in at least once before).
+        On a miss, returns 401 + clears the stale cookie. An
+        'unknown' miss (cookie present but no row matches) also
+        clears, since the token is dead to the server either way.
+
+        Note on response construction: we return a `JSONResponse`
+        directly rather than raising `HTTPException` on the miss
+        path because FastAPI's exception handler builds a new
+        response from scratch and would drop any `set_cookie` /
+        `delete_cookie` calls. The hand-built `JSONResponse` lets
+        us attach the cookie-clear header alongside the 401.
+        """
+        raw = request.cookies.get(device_trust_mod.COOKIE_NAME, "")
+        if not raw:
+            return JSONResponse({"detail": "No device trust"}, status_code=401)
+        outcome = device_trust_mod.lookup(raw)
+        if not outcome.ok or outcome.user is None:
+            # Clear the stale cookie so subsequent requests don't
+            # keep replaying a dead token. We surface 401 in all
+            # cases so a probing client can't tell "your row was
+            # revoked" from "this token never existed".
+            response = JSONResponse({"detail": "Device trust invalid"}, status_code=401)
+            _clear_device_trust_cookie(response)
+            return response
+        auth.store_session(request, outcome.user)
+        return {
+            "ok": True,
+            "user": {
+                "id": outcome.user.user_id,
+                "display_name": outcome.user.display_name,
+                "email": outcome.user.email,
+                "role": outcome.user.role,
+                "permission_state": outcome.user.permission_state,
+            },
+        }
+
     return router

backend/app/turnstile.py

@@ -0,0 +1,148 @@
+"""§6.2 / v0.12.0 / roadmap item #10: CloudFlare Turnstile siteverify.
+
+The OTC request endpoint (`/auth/otc/request`) is the abuse hot path
+of the auth surface since v0.7.0 — the per-email cooldown stops the
+trivial back-to-back loop, but it does not stop a distributed scraper
+that fans out across a large invitee list to harvest the "this email
+is admitted vs. this email is not" signal indirectly (timing
+differences, SMTP bounce-rate observation). v0.12.0 gates the request
+endpoint behind a one-step browser-side Turnstile challenge before the
+bcrypt hash + SMTP send.
+
+Stateless: no DB writes, no schema change. The siteverify call to
+CloudFlare lives entirely in this module; the endpoint handler in
+`main.py` thin-wraps `verify_token`.
+
+Tunables (read at call time so tests can monkeypatch):
+
+  * `CLOUDFLARE_TURNSTILE_SECRET`  — the operator-provisioned secret
+    key from the Turnstile dashboard. Lives in GCP Secret Manager in
+    production; absent in tests (which monkeypatch the siteverify
+    transport). When unset, the behavior depends on `TURNSTILE_REQUIRED`:
+      - `TURNSTILE_REQUIRED=true`  → fail closed (`misconfigured`).
+      - `TURNSTILE_REQUIRED=false` (default) → skip verification entirely
+        and admit the request. This is the dev/test path and the
+        "operator hasn't wired the secret yet" path; production
+        deployments **should** set `TURNSTILE_REQUIRED=true` once the
+        secret is in place so a regression in the secret wiring fails
+        loudly instead of silently disabling abuse defense.
+
+  * `TURNSTILE_REQUIRED`           — `true` / `false` (default `false`).
+    When `false` and the secret is absent, the gate is open. When
+    `true` and the secret is absent, the endpoint refuses with a
+    misconfigured-auth shape rather than silently letting requests
+    through.
+
+  * `TURNSTILE_SITEVERIFY_URL`     — points at the real CloudFlare
+    endpoint by default. Override in tests to redirect at a mock
+    URL when `httpx.MockTransport` isn't ergonomic for the case.
+
+The siteverify contract is documented at
+https://developers.cloudflare.com/turnstile/get-started/server-side-validation/.
+We POST `secret` + `response` (and optionally `remoteip`) as form
+fields and read back `{"success": true|false, ...}`. Any network /
+parse failure on the siteverify call is treated as a verification
+failure (`network`) — the abuse path is to skip the challenge, so
+"can't reach CloudFlare" defaults to "refuse the request" when
+`TURNSTILE_REQUIRED=true`, and "admit" when `TURNSTILE_REQUIRED=false`.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+
+import httpx
+
+log = logging.getLogger(__name__)
+
+
+SITEVERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify"
+
+
+def _secret() -> str:
+    return os.environ.get("CLOUDFLARE_TURNSTILE_SECRET", "").strip()
+
+
+def _required() -> bool:
+    raw = os.environ.get("TURNSTILE_REQUIRED", "").strip().lower()
+    return raw in ("1", "true", "yes", "on")
+
+
+def _siteverify_url() -> str:
+    return os.environ.get("TURNSTILE_SITEVERIFY_URL", "").strip() or SITEVERIFY_URL
+
+
+@dataclass
+class VerifyOutcome:
+    """Result of a Turnstile siteverify call.
+
+    `ok`: the request **may proceed**. True both for "siteverify said
+    success" and for "no secret configured AND not required" (the
+    dev/test soft-fail path).
+
+    `reason`: one of
+      * 'ok'             — siteverify returned success.
+      * 'skipped'        — no secret configured, TURNSTILE_REQUIRED=false.
+                            The gate is open; the endpoint admits the request.
+      * 'misconfigured'  — TURNSTILE_REQUIRED=true but no secret in env.
+                            The endpoint fails closed with 500.
+      * 'missing-token'  — the client did not send a token at all and
+                            verification is required.
+      * 'failed'         — siteverify returned success=false. The
+                            endpoint refuses with 400.
+      * 'network'        — siteverify call raised. Treated as a failure
+                            under TURNSTILE_REQUIRED=true.
+    """
+    ok: bool
+    reason: str
+
+
+def verify_token(token: str | None, *, client_ip: str | None = None) -> VerifyOutcome:
+    """Validate a Turnstile token against CloudFlare's siteverify endpoint.
+
+    Returns a VerifyOutcome describing whether the calling endpoint
+    should proceed. The endpoint maps `ok=False` to an HTTP status per
+    the `reason`:
+
+      * 'misconfigured' → 500 "auth misconfigured"
+      * 'missing-token' / 'failed' / 'network' → 400 "verification failed"
+
+    Tests monkeypatch `httpx.post` (or set `TURNSTILE_SITEVERIFY_URL`
+    + a MockTransport client) to avoid touching the real CloudFlare
+    endpoint. No real keys are ever embedded in tests.
+    """
+    secret = _secret()
+    required = _required()
+
+    if not secret:
+        if required:
+            log.warning("Turnstile required but CLOUDFLARE_TURNSTILE_SECRET is unset; failing closed")
+            return VerifyOutcome(ok=False, reason="misconfigured")
+        # Dev/test/soft-fail path: no secret, not required → gate is open.
+        return VerifyOutcome(ok=True, reason="skipped")
+
+    if not token or not token.strip():
+        # Secret is set, so verification is in force. A missing token
+        # is a hard refuse — the frontend should have rendered the
+        # widget and collected one.
+        return VerifyOutcome(ok=False, reason="missing-token")
+
+    data = {"secret": secret, "response": token.strip()}
+    if client_ip:
+        data["remoteip"] = client_ip
+
+    try:
+        response = httpx.post(_siteverify_url(), data=data, timeout=10.0)
+        payload = response.json()
+    except Exception as exc:  # network, JSON parse, etc.
+        log.warning("Turnstile siteverify call failed: %s", exc)
+        return VerifyOutcome(ok=False, reason="network")
+
+    if payload.get("success") is True:
+        return VerifyOutcome(ok=True, reason="ok")
+
+    # `error-codes` is a list of strings on failure; we log the codes
+    # for the operator without surfacing them to the client.
+    log.info("Turnstile siteverify rejected token: %s", payload.get("error-codes"))
+    return VerifyOutcome(ok=False, reason="failed")

backend/app/webhooks.py

@@ -12,6 +12,7 @@ import hashlib
 import hmac
 import json
 import logging
+import os
 
 from fastapi import APIRouter, Header, HTTPException, Request
 
@@ -40,7 +41,27 @@ def make_router(config: Config, gitea: Gitea) -> APIRouter:
         x_gitea_signature: str = Header(default=""),
     ):
         body = await request.body()
-        if config.webhook_secret:
+        # v0.18.0: defense in depth. config.py refuses to start
+        # when the secret is empty unless `RFC_APP_INSECURE_WEBHOOKS=1`
+        # is set; this branch catches the dev-bypass case (the only
+        # path where `config.webhook_secret` can be empty) and surfaces
+        # it loudly to the client. A POST that lands here with an
+        # empty secret on a production deployment indicates a
+        # mis-configuration (somebody flipped the bypass in prod),
+        # and the loud 500 is the proposal's whole point.
+        insecure = os.environ.get("RFC_APP_INSECURE_WEBHOOKS", "").strip() == "1"
+        if not config.webhook_secret:
+            if not insecure:
+                log.error(
+                    "webhook receiver misconfigured: GITEA_WEBHOOK_SECRET is empty "
+                    "and RFC_APP_INSECURE_WEBHOOKS=1 is not set"
+                )
+                raise HTTPException(status_code=500, detail="Webhook receiver misconfigured")
+            log.warning(
+                "webhook receiver running with RFC_APP_INSECURE_WEBHOOKS=1 — "
+                "signature verification is DISABLED. Production deployments MUST NOT set this."
+            )
+        else:
             if not _verify_signature(body, x_gitea_signature, config.webhook_secret):
                 raise HTTPException(status_code=401, detail="Invalid signature")
 
@@ -68,6 +89,17 @@ def make_router(config: Config, gitea: Gitea) -> APIRouter:
                 slug = _slug_for_repo(repo_full)
                 if slug:
                     await cache.refresh_rfc_repo(config, gitea, slug)
+                else:
+                    # v0.18.0: the proposal's "unknown-repo logging"
+                    # gesture — a hook on a fork or a stale repo binding
+                    # used to silently 200-OK here, hiding the
+                    # misconfiguration. Now the operator sees it in
+                    # the log.
+                    log.info(
+                        "webhook received for unknown repo: repo_full=%s event=%s "
+                        "(no cached_rfcs row matched; hook may be on a fork or stale)",
+                        repo_full, event,
+                    )
         except Exception:
             log.exception("webhook refresh failed")
             raise HTTPException(status_code=500, detail="Refresh failed")

backend/migrations/017_device_trust.sql

@@ -0,0 +1,75 @@
+-- §6.2 / v0.11.0: trust device for 30 days (roadmap item #9).
+--
+-- After a successful OTC or passcode sign-in, the user can check
+-- "trust this device for 30 days." The framework then issues a
+-- server-issued opaque device-trust token, stores its hash on this
+-- table, and sets a long-lived HttpOnly + Secure + SameSite=Lax
+-- cookie carrying the raw token. On a subsequent visit, the cookie is
+-- presented at `/auth/device-trust/start`; if the server can match the
+-- hash to a non-expired non-revoked row, the user is signed in without
+-- another OTC / passcode round-trip.
+--
+-- v0.11.0 introduces no new env vars. The 30-day window is hard-coded
+-- in `backend/app/device_trust.py`; raising or lowering it (or making
+-- it user-selectable) is a §19.2 candidate, alongside the cross-device
+-- session-revocation surface this table will eventually share with the
+-- v0.10.0 passcode-lockout shape (see SPEC §19.2 / SESSIONS-AND-DEVICES).
+--
+-- Storage shape:
+--
+--   * `id` — surrogate key. Lets the revoke-device UI address a single
+--     row by id without leaking the token shape.
+--   * `user_id` — FK into users(id) with cascade on delete. A deleted
+--     user automatically loses every trusted device.
+--   * `device_token_hash` — bcrypt hash of the random opaque token
+--     issued at trust-time. The raw token only ever lives in the
+--     outbound `Set-Cookie` header and the inbound `Cookie` header;
+--     server-side storage is the hash, so a DB compromise does not
+--     hand attackers a stash of valid device tokens.
+--   * `created_at` — when the row was issued.
+--   * `expires_at` — `created_at + 30 days`. A row past this timestamp
+--     is dead; the lookup path refuses it without further checks.
+--   * `user_agent` — the User-Agent header captured at issuance.
+--     Stored verbatim (truncated to 1024 chars at the application
+--     layer) so the revoke-device UI can show a rough device label.
+--     Not used for any auth decision — purely a hint to the user
+--     reviewing their device list.
+--   * `last_seen_at` — refreshed every time the row authenticates a
+--     request. Lets the revoke-device UI surface "last used 3 days
+--     ago" so the user can tell which row corresponds to which
+--     device.
+--   * `revoked_at` — NULL means active; non-NULL stamps when the user
+--     (or admin) revoked the row. Lookups treat any non-NULL value
+--     as "this row is dead" without consulting the expiry; the
+--     revoke gesture is intentionally one-way (a revoked device must
+--     re-trust to come back online).
+--
+-- Indexing: a unique index on `device_token_hash` so collisions are
+-- detectable at insert time (the token space is 256 bits of CSPRNG
+-- entropy, so a collision is structurally impossible, but the
+-- declaration documents the invariant). A separate index on
+-- `(user_id, revoked_at)` so the revoke-device UI's list query is
+-- a covering walk.
+--
+-- The bcrypt dependency reused here was added in v0.7.0 for OTC and
+-- extended in v0.10.0 for passcodes; v0.11.0 needs no new dep.
+--
+-- The cookie shape: `rfc_device_trust` carries the raw token,
+-- HttpOnly, Secure, SameSite=Lax, Max-Age=2592000 (30 days). It is
+-- "essential" per the v0.13.0 cookie-consent banner (it is part of
+-- authentication, not analytics), so it is set regardless of the
+-- user's analytics / other-cookies choices.
+
+CREATE TABLE device_trust (
+    id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id             INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    device_token_hash   TEXT NOT NULL,
+    created_at          TEXT NOT NULL DEFAULT (datetime('now')),
+    expires_at          TEXT NOT NULL,
+    user_agent          TEXT NOT NULL DEFAULT '',
+    last_seen_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    revoked_at          TEXT
+);
+
+CREATE UNIQUE INDEX idx_device_trust_token_hash ON device_trust (device_token_hash);
+CREATE INDEX idx_device_trust_user ON device_trust (user_id, revoked_at);

backend/migrations/018_rfc_invitations.sql

@@ -0,0 +1,177 @@
+-- §6 / §10 / v0.16.0: owner-only invite for per-RFC contribution +
+-- discussion (roadmap item #12).
+--
+-- Distinct from a platform-level grant (`users.permission_state`,
+-- v0.8.0 / item #6). This row is per-RFC membership: the RFC's owner
+-- invites a specific email to either open PRs against that RFC
+-- (`role_in_rfc='contributor'`) or to participate in the RFC's PR-less
+-- discussion only (`role_in_rfc='discussant'`). Non-invited users keep
+-- the v0.6.0 anonymous-read contract — they can read but cannot
+-- write/discuss that specific RFC.
+--
+-- Coordinates with item #16's parallel work this wave: that item
+-- adds platform-wide invitation tokens; this one adds per-RFC
+-- collaboration rows. To avoid table-name + concept collisions the
+-- two surfaces are scoped distinctly — this migration owns slot 018
+-- and names everything `rfc_*` (RFC-scoped); #16 will use a later
+-- slot and name its tables under a different prefix (`invite_tokens`
+-- or similar) at the user/platform level.
+--
+-- Tables in this migration:
+--
+--   * `rfc_invitations` — one row per (rfc, invitee_email) invite
+--     issued by the RFC's owner. Carries the role-in-RFC the
+--     invitation grants, the opaque token the email link encodes,
+--     the lifecycle state, and the audit trail (who invited, when
+--     accepted, by which user_id if any).
+--
+--   * `rfc_collaborators` — one row per (rfc, user_id, role_in_rfc)
+--     after an invitation is accepted. This is the table the
+--     write-gate consults: "is the viewer named here for this RFC?"
+--     Separating the two means the invitation row carries the
+--     issue/accept lifecycle while the collaborator row is the
+--     compact membership-check substrate. A grant via collaborator
+--     can exist independently of a live invitation (admin-only
+--     direct insert is a §19.2 candidate; v0.16.0 only writes
+--     collaborator rows via the accept path).
+--
+-- Authorization model the application layer enforces on top of these
+-- rows (not encoded in SQL — the schema is just storage):
+--
+--   * Writes (open PR, post discussion message, open discussion
+--     thread) to an RFC require ONE of:
+--       (a) the viewer is named in this RFC's `rfc_collaborators`
+--           with the appropriate role_in_rfc, OR
+--       (b) the viewer holds a globally privileged role (admin,
+--           owner of the platform) per the existing §6 helpers, OR
+--       (c) the viewer is named in the RFC's frontmatter owners
+--           list (the §6 RFC-owner concept, which already grants
+--           the maximal per-RFC capability).
+--
+--   * Reads remain on the v0.6.0 anonymous-read contract — anyone
+--     can read any non-withdrawn RFC. Item #12 does not narrow this.
+--
+--   * Only the RFC's owner (per `cached_rfcs.owners_json`) can
+--     invite. App admins/owners also can (they have the maximal
+--     per-RFC capability by construction).
+--
+-- Storage shape — `rfc_invitations`:
+--
+--   * `id` — surrogate key; the revoke-by-id surface addresses a
+--     single row without leaking the token shape.
+--
+--   * `rfc_slug` — TEXT NOT NULL; the RFC the invitation scopes to.
+--     We FK against `cached_rfcs(slug)` so a withdrawn/deleted RFC
+--     cascades its invitations away cleanly. The §4 cache contract
+--     says cached_rfcs is rebuildable from Gitea; per the same
+--     contract, invitations are app-truth (no Git substrate), so
+--     the cascade is the right direction.
+--
+--   * `inviter_user_id` — the owner who issued the invite. ON
+--     DELETE SET NULL because losing the inviter's user row should
+--     not cascade-delete invitations they sent (the row stays as
+--     audit; the UI renders "by (deleted user)" the same way the
+--     audit log does for orphaned actors).
+--
+--   * `invitee_email` — TEXT NOT NULL; the email the invitation
+--     was sent to. Stored verbatim (case-preserved) so the email
+--     body can address the invitee in their original shape; the
+--     accept path matches case-insensitively.
+--
+--   * `role_in_rfc` — CHECK in {'contributor' | 'discussant'}.
+--     `contributor` lets the user open PRs against the RFC AND
+--     post in its discussion (PR-permission strictly includes
+--     discussion-permission); `discussant` only lets them post
+--     in discussion. Future roles (e.g., 'arbiter') would be
+--     additions; v0.16.0 ships the two.
+--
+--   * `status` — CHECK in {'pending' | 'accepted' | 'revoked' |
+--     'expired'}. Default 'pending'. `accepted` flips on the
+--     accept endpoint; `revoked` on the owner's revoke gesture;
+--     `expired` lazily on read (the accept endpoint refuses a
+--     row whose expires_at has passed, regardless of the column
+--     value).
+--
+--   * `token` — opaque high-entropy string the email link
+--     encodes. Stored verbatim (not hashed) because the
+--     invitation token is single-use and lower-stakes than a
+--     session token: it grants per-RFC role only, and is bounded
+--     by expires_at. Hashing the token here is a §19.2 candidate
+--     if/when the threat model demands it. UNIQUE so the accept
+--     path is a single-row lookup.
+--
+--   * `expires_at` — TEXT timestamp. Set to `created_at + 30 days`
+--     at insert time by the application layer. Accept refuses past
+--     this point; the row can still be revoked or re-issued.
+--
+--   * `created_at` — when the invitation was issued.
+--
+--   * `accepted_at` — when the invitee accepted (NULL until then).
+--
+--   * `accepted_by_user_id` — the user row that accepted. NULL
+--     until acceptance. On a fresh email (no platform user yet)
+--     the accept endpoint requires the invitee to sign in first
+--     via the v0.7.0 OTC path; that path provisions the user row,
+--     after which the accept call lands the user_id here.
+--
+-- Indexing:
+--
+--   * UNIQUE on `token` so the accept lookup is a primary-key-shape
+--     hit and accidental collisions are detectable at insert time.
+--   * (rfc_slug, status) for the owner's "list pending/accepted for
+--     this RFC" surface — the most frequent query.
+--   * (invitee_email, status) for a future cross-RFC "show me my
+--     pending invites" inbox; v0.16.0 doesn't ship that surface but
+--     the index slot is cheap and aligned with the data shape.
+--
+-- Storage shape — `rfc_collaborators`:
+--
+--   * `id` — surrogate key.
+--   * `rfc_slug` — TEXT NOT NULL FK cached_rfcs(slug) ON DELETE CASCADE.
+--   * `user_id` — INTEGER NOT NULL FK users(id) ON DELETE CASCADE.
+--     A deleted user loses every per-RFC role automatically (mirrors
+--     the device_trust / passcode cascade shape).
+--   * `role_in_rfc` — same CHECK as the invitation table.
+--   * `invitation_id` — INTEGER FK rfc_invitations(id) ON DELETE
+--     SET NULL. Audit pointer to the row that minted this
+--     collaborator; NULL is allowed so a future admin-direct grant
+--     path (a §19.2 candidate) can mint a collaborator with no
+--     originating invitation. v0.16.0 always populates this.
+--   * `created_at` — when the collaborator row was minted.
+--
+-- Indexing on collaborators:
+--   * UNIQUE on (rfc_slug, user_id) — a single user can hold at most
+--     one role per RFC. Re-accepting an invitation upgrades the row
+--     (discussant → contributor) but never duplicates.
+--   * (user_id) for "what RFCs am I a collaborator on?" reads.
+
+CREATE TABLE rfc_invitations (
+    id                      INTEGER PRIMARY KEY AUTOINCREMENT,
+    rfc_slug                TEXT NOT NULL REFERENCES cached_rfcs(slug) ON DELETE CASCADE,
+    inviter_user_id         INTEGER REFERENCES users(id) ON DELETE SET NULL,
+    invitee_email           TEXT NOT NULL,
+    role_in_rfc             TEXT NOT NULL CHECK (role_in_rfc IN ('contributor', 'discussant')),
+    status                  TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending', 'accepted', 'revoked', 'expired')),
+    token                   TEXT NOT NULL,
+    expires_at              TEXT NOT NULL,
+    created_at              TEXT NOT NULL DEFAULT (datetime('now')),
+    accepted_at             TEXT,
+    accepted_by_user_id     INTEGER REFERENCES users(id) ON DELETE SET NULL
+);
+
+CREATE UNIQUE INDEX idx_rfc_invitations_token ON rfc_invitations (token);
+CREATE INDEX idx_rfc_invitations_rfc_status ON rfc_invitations (rfc_slug, status);
+CREATE INDEX idx_rfc_invitations_email_status ON rfc_invitations (invitee_email, status);
+
+CREATE TABLE rfc_collaborators (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    rfc_slug        TEXT NOT NULL REFERENCES cached_rfcs(slug) ON DELETE CASCADE,
+    user_id         INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    role_in_rfc     TEXT NOT NULL CHECK (role_in_rfc IN ('contributor', 'discussant')),
+    invitation_id   INTEGER REFERENCES rfc_invitations(id) ON DELETE SET NULL,
+    created_at      TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE UNIQUE INDEX idx_rfc_collaborators_unique ON rfc_collaborators (rfc_slug, user_id);
+CREATE INDEX idx_rfc_collaborators_user ON rfc_collaborators (user_id);

backend/migrations/019_user_invite_tokens.sql

@@ -0,0 +1,105 @@
+-- §6.1 / v0.17.0: admin-create user with role + invite email (roadmap item #16).
+--
+-- Distinguishes from the v0.8.0 / v0.9.0 self-serve beta-access shape:
+-- here an *admin* creates a `users` row *before* the invited person has
+-- ever signed in, assigns them a role at creation time, and sends them
+-- an invite email carrying a claim link. The invitee clicks the link,
+-- the claim flow consumes the token (which is itself proof of email
+-- control), the row is marked claimed, and the user is signed in
+-- inheriting the pre-set role.
+--
+-- Migration slot 019 is allocated to this release. Slot 018 is reserved
+-- for the parallel #12 release (per-RFC invitation, owner-only) shipping
+-- in the same wave; the two features live in distinct tables
+-- (`user_invite_tokens` here vs. `rfc_invitations` there) so they
+-- coexist cleanly. Slot 016 was reserved+skipped by Session K during
+-- v0.9.0 integration; slot 017 is the v0.11.0 device-trust table.
+--
+-- Open-question decisions settled in this release (see CHANGELOG):
+--   * No `users` table changes — the brief floated `first_sign_in_at`
+--     / `last_seen_at IS NULL` as the "(pending invite)" discriminator,
+--     but the existing `users.last_seen_at` is NOT NULL with a
+--     `datetime('now')` default (migrations/001) and there is no
+--     `first_sign_in_at` column. Rather than land a schema migration to
+--     introduce one, the discriminator is the existence of an active
+--     (not-claimed, not-expired) row in `user_invite_tokens` joined on
+--     `invited_user_id`. The admin user-listing carries a
+--     `pending_invite` field populated via that join; on claim, the
+--     invite row's `claimed_at` populates and the badge clears.
+--     No new `permission_state` value is introduced either.
+--   * The token is opaque (random URL-safe string, bcrypt-hashed at
+--     rest), not a JWT, so admin revocation by row UPDATE works
+--     without distributing a key-rotation gesture.
+--   * The TTL is a constant (`INVITE_TOKEN_TTL_DAYS = 7` in
+--     `backend/app/invites.py`); env-var configurability is a follow-up.
+--   * Immediate-send (no admin-review-then-send queue) ships in this
+--     release; admin-preview is a future enhancement.
+--   * Bulk-invite (CSV paste) is deferred to a follow-up release;
+--     v0.17.0 is one-at-a-time.
+--
+-- Storage shape:
+--
+--   * `id` — surrogate key. Lets the admin "pending invites" listing
+--     address a row without leaking the token shape.
+--   * `email` — the address the invite was sent to (case-insensitive
+--     match at claim time, persisted verbatim for the audit trail).
+--   * `role` — the role the invitee inherits on first sign-in. Pinned
+--     via CHECK to the same set the §6.1 role flip accepts
+--     (`owner` / `admin` / `contributor`) so a future role-set drift
+--     fails loudly at insert rather than provisioning a ghost role.
+--   * `first_name` / `last_name` — captured at create time so the
+--     invitee skips the v0.8.0 capture-form step on first sign-in.
+--   * `custom_message` — optional free-text from the admin (max 500
+--     chars enforced at the API layer); embedded verbatim in the
+--     email body if present.
+--   * `token_hash` — bcrypt hash of the random opaque token. The
+--     raw token only ever lives in the outbound email link and the
+--     inbound claim body; server-side storage is the hash.
+--   * `expires_at` — `created_at + 7 days` (default at the app layer
+--     via `INVITE_TOKEN_TTL_DAYS`). A row past this stamp is dead;
+--     the claim path refuses with HTTP 410.
+--   * `created_at` — when the admin issued the invite.
+--   * `created_by_admin_id` — FK into users(id) for the admin who
+--     created the invite (no cascade; if the admin's row is deleted
+--     the invite history stays so the audit trail survives).
+--   * `claimed_at` — non-NULL once the invitee successfully claims.
+--     A second claim attempt against an already-claimed row returns
+--     HTTP 410.
+--   * `claimed_by_user_id` — FK into users(id) for the user row
+--     that consumed the token. In the common case this equals the
+--     freshly-provisioned row that was created at invite time; the
+--     FK lets the admin's "claimed" list join through.
+--   * `invited_user_id` — FK into users(id) for the pre-provisioned
+--     row. Created at invite time with `last_seen_at IS NULL` so the
+--     v0.9.0 admin user-management page can render a "(pending
+--     invite)" badge alongside existing users.
+--
+-- Indexing:
+--   * Unique index on `token_hash` documents the no-collision
+--     invariant (256 bits of CSPRNG entropy; collision is
+--     structurally impossible, the unique constraint catches a
+--     bug at insert time).
+--   * Index on `(email, claimed_at)` so the "is this email already
+--     invited?" pre-check the admin endpoint runs is a covering walk.
+--   * Index on `(created_by_admin_id, created_at DESC)` for the
+--     admin's "invites I've sent" listing.
+
+CREATE TABLE user_invite_tokens (
+    id                   INTEGER PRIMARY KEY AUTOINCREMENT,
+    email                TEXT NOT NULL,
+    role                 TEXT NOT NULL CHECK (role IN ('owner', 'admin', 'contributor')),
+    first_name           TEXT NOT NULL DEFAULT '',
+    last_name            TEXT NOT NULL DEFAULT '',
+    custom_message       TEXT NOT NULL DEFAULT '',
+    token_hash           TEXT NOT NULL,
+    expires_at           TEXT NOT NULL,
+    created_at           TEXT NOT NULL DEFAULT (datetime('now')),
+    created_by_admin_id  INTEGER NOT NULL REFERENCES users(id),
+    claimed_at           TEXT,
+    claimed_by_user_id   INTEGER REFERENCES users(id),
+    invited_user_id      INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE
+);
+
+CREATE UNIQUE INDEX idx_user_invite_tokens_hash ON user_invite_tokens (token_hash);
+CREATE INDEX idx_user_invite_tokens_email ON user_invite_tokens (email, claimed_at);
+CREATE INDEX idx_user_invite_tokens_admin ON user_invite_tokens (created_by_admin_id, created_at DESC);

backend/migrations/020_outbound_emails.sql

@@ -0,0 +1,30 @@
+-- v0.18.0 Slice 4: outbound_emails audit table.
+--
+-- Per the v0.18.0 email + webhook hygiene proposal §3, every send
+-- helper writes a row to this table before returning, regardless
+-- of outcome. status='sent' on success, 'failed' on exception,
+-- 'deferred' on the dev-fallback path (no SMTP_HOST configured).
+--
+-- The table is queried by `GET /api/admin/outbound-emails` to
+-- answer "did this person ever get their invite?" without having
+-- to grep VM logs, and by the v0.18.0 Slice 5 bounce-correlation
+-- hook (which looks up message_id when a POST lands at
+-- /api/webhooks/email-bounce and marks the matching row
+-- status='bounced').
+
+CREATE TABLE IF NOT EXISTS outbound_emails (
+    id              INTEGER PRIMARY KEY,
+    to_address      TEXT NOT NULL,
+    from_address    TEXT NOT NULL,
+    subject         TEXT NOT NULL,
+    kind            TEXT NOT NULL,     -- 'otc' | 'invite' | 'notification' | 'bundle' | 'digest' | 'rfc-invite'
+    sent_at         TEXT NOT NULL,     -- ISO 8601, time the send was attempted
+    status          TEXT NOT NULL,     -- 'sent' | 'failed' | 'deferred' | 'bounced'
+    error           TEXT,              -- exception class + message if status='failed'
+    notification_id INTEGER,           -- nullable FK to notifications.id for the watcher path
+    message_id      TEXT               -- the Message-ID header value, for bounce correlation
+);
+
+CREATE INDEX IF NOT EXISTS idx_outbound_emails_to        ON outbound_emails(to_address);
+CREATE INDEX IF NOT EXISTS idx_outbound_emails_sent_at   ON outbound_emails(sent_at);
+CREATE INDEX IF NOT EXISTS idx_outbound_emails_message   ON outbound_emails(message_id);

backend/tests/test_admin_create_user_invite_vertical.py

@@ -0,0 +1,728 @@
+"""End-to-end integration tests for v0.17.0's admin-create user +
+invite-email + claim-flow vertical (roadmap item #16, §6.1).
+
+The release lands three halves of the same surface:
+
+  * **Admin-create user** at `POST /api/admin/users`. The admin types
+    email, first/last name, role, and an optional custom message. The
+    framework provisions the invitee `users` row (granted, with the
+    chosen role) and writes a `user_invite_tokens` row carrying the
+    bcrypt-hashed opaque token. The "pending invite" discriminator is
+    the active `user_invite_tokens` row joined on `invited_user_id`,
+    not a NULL column on `users` (the existing `last_seen_at` column
+    is NOT NULL). An invite email dispatches via the existing SMTP
+    relay.
+
+  * **Pending-invite admin listing** at `GET /api/admin/users/invites`.
+    Lists active (not claimed, not expired) invites for the admin's
+    "I sent these but they haven't been claimed yet" view.
+
+  * **Claim** at `POST /api/invites/claim`. The invitee POSTs the token
+    they got via email; the framework verifies, marks the row claimed,
+    signs them in (skipping OTC on first sign-in per the roadmap), and
+    returns a `needs_passcode` hint for the frontend to route to the
+    passcode-set screen.
+
+The tests prove:
+
+  * The happy path: admin creates → invite row + email envelope land →
+    invitee claims with the token → session is established.
+  * Non-admin caller is refused 403.
+  * Self-invite is refused 422.
+  * Duplicate email is refused 409.
+  * Owner-grant by non-owner is refused 422.
+  * Malformed role is refused 422 (pydantic regex).
+  * Custom message over 500 chars is refused 422 (pydantic max_length).
+  * Claim with valid token: signs in + marks row claimed.
+  * Claim with expired token: HTTP 410.
+  * Claim with already-claimed token: HTTP 410.
+  * Claim with unknown token: HTTP 400.
+  * The admin-create gesture writes a `permission_events` row with
+    event_kind='user_invited'.
+  * The user listing surfaces the `pending_invite` field for invited-
+    but-not-yet-claimed users, and clears it after claim.
+"""
+from __future__ import annotations
+
+import json
+
+from test_propose_vertical import (  # noqa: F401 — fixtures land via import
+    FakeGitea,
+    app_with_fake_gitea,
+    provision_user_row,
+    sign_in_as,
+    tmp_env,
+)
+
+
+def _reset_outbound():
+    from app import email as email_mod
+    email_mod.reset_sent_envelopes()
+
+
+def _outbound_invite_envelopes(to_address: str | None = None) -> list[dict]:
+    """Pull the invite-kind envelopes off the shared notifier buffer.
+
+    Mirrors the OTC code-extraction helper in
+    test_admin_users_vertical.py — invite emails land in the same
+    `_SENT` buffer with `kind='invite'`.
+    """
+    from app import email as email_mod
+    out = []
+    for env in email_mod.sent_envelopes():
+        if env.get("kind") != "invite":
+            continue
+        if to_address is not None and env["to"] != to_address:
+            continue
+        out.append(env)
+    return out
+
+
+def _extract_claim_url(envelope: dict) -> str:
+    """Pull the claim URL out of the invite email body."""
+    for line in envelope["body"].splitlines():
+        line = line.strip()
+        if line.startswith("http") and "/invites/claim" in line:
+            return line
+    raise AssertionError(f"no claim URL in envelope body: {envelope['body']!r}")
+
+
+def _extract_claim_token(envelope: dict) -> str:
+    """Pull the `token` query-string param out of the claim URL."""
+    from urllib.parse import urlparse, parse_qs
+    url = _extract_claim_url(envelope)
+    qs = parse_qs(urlparse(url).query)
+    return qs["token"][0]
+
+
+# ---------------------------------------------------------------------------
+# Admin create + invite — happy path
+# ---------------------------------------------------------------------------
+
+
+def test_admin_create_user_invite_happy_path(app_with_fake_gitea):
+    """Admin creates → user row + invite-token row + email envelope all
+    land; the response carries the created ids and the inviter is the
+    admin who issued the gesture."""
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=100, login="adminzero", role="admin")
+        sign_in_as(
+            client, user_id=100, gitea_login="adminzero",
+            display_name="Admin Zero", role="admin",
+            email="adminzero@test",
+        )
+        _reset_outbound()
+
+        r = client.post(
+            "/api/admin/users",
+            json={
+                "email": "invitee@example.com",
+                "first_name": "Inv",
+                "last_name": "Tee",
+                "role": "contributor",
+                "custom_message": "We chatted at the conference — welcome!",
+            },
+        )
+        assert r.status_code == 200, r.text
+        body = r.json()
+        assert body["ok"] is True
+        assert body["email"] == "invitee@example.com"
+        assert body["role"] == "contributor"
+        assert body["invite_id"] > 0
+        assert body["invited_user_id"] > 0
+
+        # User row exists with the chosen role + granted. The "pending
+        # invite" discriminator is the active `user_invite_tokens` row,
+        # not a NULL column on `users` — see the invites.create_invite
+        # docstring for the reasoning.
+        row = db.conn().execute(
+            "SELECT role, permission_state, first_name, last_name "
+            "FROM users WHERE email = ? COLLATE NOCASE",
+            ("invitee@example.com",),
+        ).fetchone()
+        assert row is not None
+        assert row["role"] == "contributor"
+        assert row["permission_state"] == "granted"
+        assert row["first_name"] == "Inv"
+        assert row["last_name"] == "Tee"
+
+        # Invite-token row exists with the matching ids and the custom
+        # message persisted verbatim.
+        invite = db.conn().execute(
+            "SELECT email, role, custom_message, created_by_admin_id, "
+            "invited_user_id, claimed_at FROM user_invite_tokens WHERE id = ?",
+            (body["invite_id"],),
+        ).fetchone()
+        assert invite is not None
+        assert invite["email"] == "invitee@example.com"
+        assert invite["role"] == "contributor"
+        assert invite["custom_message"] == "We chatted at the conference — welcome!"
+        assert invite["created_by_admin_id"] == 100
+        assert invite["invited_user_id"] == body["invited_user_id"]
+        assert invite["claimed_at"] is None
+
+        # Email envelope landed with the invite kind and embeds the
+        # custom message + claim URL. The inviter display name comes
+        # off the DB row (which provision_user_row sets to
+        # login.capitalize()), not the sign_in_as cookie payload.
+        envelopes = _outbound_invite_envelopes(to_address="invitee@example.com")
+        assert len(envelopes) == 1
+        env = envelopes[0]
+        assert "Adminzero" in env["subject"] or "Adminzero" in env["body"]
+        assert "We chatted at the conference — welcome!" in env["body"]
+        # Claim URL is well-formed.
+        url = _extract_claim_url(env)
+        assert "/invites/claim?token=" in url
+
+        # `permission_events` row landed with event_kind='user_invited'.
+        ev = db.conn().execute(
+            "SELECT actor_user_id, subject_user_id, event_kind, details "
+            "FROM permission_events WHERE event_kind = 'user_invited'"
+        ).fetchall()
+        assert len(ev) == 1
+        assert ev[0]["actor_user_id"] == 100
+        assert ev[0]["subject_user_id"] == body["invited_user_id"]
+        details = json.loads(ev[0]["details"])
+        assert details["email"] == "invitee@example.com"
+        assert details["role"] == "contributor"
+
+
+# ---------------------------------------------------------------------------
+# Refusals on the admin-create endpoint
+# ---------------------------------------------------------------------------
+
+
+def test_admin_create_user_invite_refuses_non_admin(app_with_fake_gitea):
+    """A contributor caller is refused 403; an anonymous caller 401."""
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=110, login="contrib", role="contributor")
+        sign_in_as(
+            client, user_id=110, gitea_login="contrib",
+            display_name="Contrib", role="contributor",
+        )
+        r = client.post(
+            "/api/admin/users",
+            json={"email": "x@y.com", "role": "contributor"},
+        )
+        assert r.status_code == 403, r.text
+
+        client.cookies.clear()
+        r = client.post(
+            "/api/admin/users",
+            json={"email": "x@y.com", "role": "contributor"},
+        )
+        assert r.status_code == 401
+
+
+def test_admin_create_user_invite_refuses_self_email(app_with_fake_gitea):
+    """An admin trying to invite their own email is refused 422 —
+    self-invite is the wrong channel; the role-change endpoint exists
+    for self-edits."""
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=120, login="adm", role="admin")
+        # Manually set the admin's email since provision_user_row's
+        # fixture uses login@test; this is what we'll try to self-invite.
+        from app import db
+        db.conn().execute(
+            "UPDATE users SET email = ? WHERE id = ?",
+            ("selfinviter@example.com", 120),
+        )
+        sign_in_as(
+            client, user_id=120, gitea_login="adm",
+            display_name="Adm", role="admin",
+            email="selfinviter@example.com",
+        )
+        r = client.post(
+            "/api/admin/users",
+            json={
+                "email": "selfinviter@example.com",
+                "role": "contributor",
+            },
+        )
+        assert r.status_code == 422, r.text
+        assert "yourself" in r.json()["detail"].lower()
+
+
+def test_admin_create_user_invite_refuses_duplicate_email(app_with_fake_gitea):
+    """An admin trying to invite an email that already maps to a users
+    row is refused 409 — the existing role / grant gestures are the
+    right surface for an existing user."""
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=130, login="adminD", role="admin")
+        provision_user_row(user_id=131, login="existingone", role="contributor")
+        sign_in_as(
+            client, user_id=130, gitea_login="adminD",
+            display_name="Admin D", role="admin",
+        )
+        # provision_user_row sets email to <login>@test, so:
+        r = client.post(
+            "/api/admin/users",
+            json={
+                "email": "existingone@test",
+                "role": "contributor",
+            },
+        )
+        assert r.status_code == 409, r.text
+
+
+def test_admin_create_user_invite_owner_grant_refused_for_non_owner(app_with_fake_gitea):
+    """An admin (not owner) trying to invite a fresh user as `owner` is
+    refused 422 — §6.1's owner-zero is the only bootstrap path."""
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=140, login="adminNoOwner", role="admin")
+        sign_in_as(
+            client, user_id=140, gitea_login="adminNoOwner",
+            display_name="Admin", role="admin",
+        )
+        r = client.post(
+            "/api/admin/users",
+            json={
+                "email": "wouldbeowner@example.com",
+                "role": "owner",
+            },
+        )
+        assert r.status_code == 422, r.text
+
+
+def test_admin_create_user_invite_owner_can_invite_as_owner(app_with_fake_gitea):
+    """A sitting owner can invite a fresh user as `owner` — the §6.1
+    role-grant channel. Sanity check that the owner-grant path itself
+    works, paired with the refusal above."""
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=150, login="ownerzero", role="owner")
+        sign_in_as(
+            client, user_id=150, gitea_login="ownerzero",
+            display_name="Owner Zero", role="owner",
+        )
+        r = client.post(
+            "/api/admin/users",
+            json={
+                "email": "newowner@example.com",
+                "role": "owner",
+            },
+        )
+        assert r.status_code == 200, r.text
+        row = db.conn().execute(
+            "SELECT role FROM users WHERE email = ? COLLATE NOCASE",
+            ("newowner@example.com",),
+        ).fetchone()
+        assert row["role"] == "owner"
+
+
+def test_admin_create_user_invite_refuses_malformed_role(app_with_fake_gitea):
+    """The pydantic regex refuses any role outside the §6.1 set."""
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=160, login="adminR", role="admin")
+        sign_in_as(
+            client, user_id=160, gitea_login="adminR",
+            display_name="Admin R", role="admin",
+        )
+        r = client.post(
+            "/api/admin/users",
+            json={
+                "email": "ok@example.com",
+                "role": "superuser",
+            },
+        )
+        assert r.status_code == 422
+
+
+def test_admin_create_user_invite_refuses_long_custom_message(app_with_fake_gitea):
+    """Custom message over the 500-char ceiling is refused 422."""
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=170, login="adminM", role="admin")
+        sign_in_as(
+            client, user_id=170, gitea_login="adminM",
+            display_name="Admin M", role="admin",
+        )
+        r = client.post(
+            "/api/admin/users",
+            json={
+                "email": "ok@example.com",
+                "role": "contributor",
+                "custom_message": "x" * 501,
+            },
+        )
+        assert r.status_code == 422
+
+
+# ---------------------------------------------------------------------------
+# Claim flow
+# ---------------------------------------------------------------------------
+
+
+def test_claim_with_valid_token_signs_in_and_marks_claimed(app_with_fake_gitea):
+    """End-to-end: admin creates → invitee posts the token to
+    /api/invites/claim → session lands + row marked claimed +
+    last_seen_at stamps on the user row (the pending-invite
+    discriminator clears)."""
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=200, login="adminC", role="admin")
+        sign_in_as(
+            client, user_id=200, gitea_login="adminC",
+            display_name="Admin C", role="admin",
+        )
+        _reset_outbound()
+
+        r = client.post(
+            "/api/admin/users",
+            json={
+                "email": "claimant@example.com",
+                "first_name": "Clai",
+                "last_name": "Mant",
+                "role": "contributor",
+            },
+        )
+        assert r.status_code == 200
+        invite_id = r.json()["invite_id"]
+        invited_user_id = r.json()["invited_user_id"]
+
+        env = _outbound_invite_envelopes("claimant@example.com")[0]
+        token = _extract_claim_token(env)
+
+        # The invitee's request is anonymous (they have no session
+        # yet). We clear the admin's session cookie to simulate this.
+        client.cookies.clear()
+
+        r = client.post(
+            "/api/invites/claim",
+            json={"token": token},
+        )
+        assert r.status_code == 200, r.text
+        body = r.json()
+        assert body["ok"] is True
+        assert body["user"]["id"] == invited_user_id
+        assert body["user"]["role"] == "contributor"
+        assert body["user"]["permission_state"] == "granted"
+        # The user has no passcode set yet → frontend should route to
+        # passcode-set per the roadmap.
+        assert body["needs_passcode"] is True
+
+        # Row marked claimed; last_seen_at populated.
+        invite = db.conn().execute(
+            "SELECT claimed_at, claimed_by_user_id FROM user_invite_tokens "
+            "WHERE id = ?",
+            (invite_id,),
+        ).fetchone()
+        assert invite["claimed_at"] is not None
+        assert invite["claimed_by_user_id"] == invited_user_id
+
+        user_row = db.conn().execute(
+            "SELECT last_seen_at FROM users WHERE id = ?",
+            (invited_user_id,),
+        ).fetchone()
+        assert user_row["last_seen_at"] is not None
+
+
+def test_claim_with_expired_token_returns_410(app_with_fake_gitea):
+    """A token whose `expires_at` has passed surfaces as HTTP 410."""
+    from fastapi.testclient import TestClient
+    from app import db, invites
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=210, login="adminE", role="admin")
+        sign_in_as(
+            client, user_id=210, gitea_login="adminE",
+            display_name="Admin E", role="admin",
+        )
+        _reset_outbound()
+
+        # Create the invite, then back-date the expires_at to the past.
+        r = client.post(
+            "/api/admin/users",
+            json={
+                "email": "expired@example.com",
+                "role": "contributor",
+            },
+        )
+        assert r.status_code == 200
+        invite_id = r.json()["invite_id"]
+        db.conn().execute(
+            "UPDATE user_invite_tokens SET expires_at = datetime('now', '-1 day') "
+            "WHERE id = ?",
+            (invite_id,),
+        )
+        env = _outbound_invite_envelopes("expired@example.com")[0]
+        token = _extract_claim_token(env)
+
+        client.cookies.clear()
+        r = client.post("/api/invites/claim", json={"token": token})
+        assert r.status_code == 410, r.text
+        assert "expired" in r.json()["detail"].lower()
+
+
+def test_claim_with_already_claimed_token_returns_410(app_with_fake_gitea):
+    """Re-claiming an already-consumed token surfaces as HTTP 410."""
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=220, login="adminA", role="admin")
+        sign_in_as(
+            client, user_id=220, gitea_login="adminA",
+            display_name="Admin A", role="admin",
+        )
+        _reset_outbound()
+
+        r = client.post(
+            "/api/admin/users",
+            json={
+                "email": "twice@example.com",
+                "role": "contributor",
+            },
+        )
+        assert r.status_code == 200
+        env = _outbound_invite_envelopes("twice@example.com")[0]
+        token = _extract_claim_token(env)
+
+        client.cookies.clear()
+        # First claim succeeds.
+        r = client.post("/api/invites/claim", json={"token": token})
+        assert r.status_code == 200
+        # Second claim, with the same token, refuses with 410.
+        client.cookies.clear()
+        r = client.post("/api/invites/claim", json={"token": token})
+        assert r.status_code == 410, r.text
+        assert "already" in r.json()["detail"].lower()
+
+
+def test_claim_with_unknown_token_returns_400(app_with_fake_gitea):
+    """A token that doesn't match any active invite is HTTP 400."""
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        # No invite ever created; the token is whatever the attacker
+        # types in. The endpoint should refuse without disclosing
+        # whether the token "looked" right.
+        r = client.post(
+            "/api/invites/claim",
+            json={"token": "totally-made-up-token-string-that-is-not-real"},
+        )
+        assert r.status_code == 400, r.text
+
+
+# ---------------------------------------------------------------------------
+# Pending-invite admin listing
+# ---------------------------------------------------------------------------
+
+
+def test_pending_invites_listing_shows_active_invites_only(app_with_fake_gitea):
+    """The `GET /api/admin/users/invites` listing filters to active
+    invites — claimed and expired rows do not surface here (the admin
+    user-listing carries the per-row pending-invite badge for the
+    living rows; once claimed, the badge clears)."""
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=300, login="adminL", role="admin")
+        sign_in_as(
+            client, user_id=300, gitea_login="adminL",
+            display_name="Admin L", role="admin",
+        )
+        _reset_outbound()
+
+        # Create three invites: one stays pending, one we'll claim, one
+        # we'll back-date to expired.
+        for email in ("alive@ex.co", "claimed@ex.co", "expired@ex.co"):
+            r = client.post(
+                "/api/admin/users",
+                json={"email": email, "role": "contributor"},
+            )
+            assert r.status_code == 200
+
+        # Claim the middle one.
+        env = _outbound_invite_envelopes("claimed@ex.co")[0]
+        token_claim = _extract_claim_token(env)
+
+        # Expire the third one.
+        from app import db
+        db.conn().execute(
+            "UPDATE user_invite_tokens SET expires_at = datetime('now', '-1 day') "
+            "WHERE email = 'expired@ex.co'"
+        )
+
+        # The admin's session is still on the cookie. Claim works
+        # anonymously; we clear and restore.
+        admin_cookie = client.cookies.get("rfc_session")
+        client.cookies.clear()
+        r = client.post("/api/invites/claim", json={"token": token_claim})
+        assert r.status_code == 200
+        client.cookies.set("rfc_session", admin_cookie)
+
+        r = client.get("/api/admin/users/invites")
+        assert r.status_code == 200, r.text
+        items = r.json()["items"]
+        emails = sorted(i["email"] for i in items)
+        assert emails == ["alive@ex.co"]
+
+
+def test_pending_invite_badge_clears_after_claim(app_with_fake_gitea):
+    """The `/api/admin/users` listing surfaces `pending_invite` while
+    the invite is unclaimed; after the invitee claims, the row's
+    pending_invite is null."""
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=310, login="adminB", role="admin")
+        sign_in_as(
+            client, user_id=310, gitea_login="adminB",
+            display_name="Admin B", role="admin",
+        )
+        _reset_outbound()
+
+        r = client.post(
+            "/api/admin/users",
+            json={"email": "badgey@ex.co", "role": "contributor"},
+        )
+        assert r.status_code == 200
+        invited_id = r.json()["invited_user_id"]
+
+        # Before claim — pending_invite is populated.
+        r = client.get("/api/admin/users")
+        assert r.status_code == 200
+        row = next(u for u in r.json()["items"] if u["id"] == invited_id)
+        assert row["pending_invite"] is not None
+        assert row["pending_invite"]["invite_id"] > 0
+
+        # Claim.
+        env = _outbound_invite_envelopes("badgey@ex.co")[0]
+        token = _extract_claim_token(env)
+        admin_cookie = client.cookies.get("rfc_session")
+        client.cookies.clear()
+        r = client.post("/api/invites/claim", json={"token": token})
+        assert r.status_code == 200
+        client.cookies.set("rfc_session", admin_cookie)
+
+        # After claim — pending_invite is null.
+        r = client.get("/api/admin/users")
+        assert r.status_code == 200
+        row = next(u for u in r.json()["items"] if u["id"] == invited_id)
+        assert row["pending_invite"] is None
+
+
+def test_pending_invites_listing_admin_only(app_with_fake_gitea):
+    """The listing requires admin/owner; contributor gets 403."""
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=320, login="contribL", role="contributor")
+        sign_in_as(
+            client, user_id=320, gitea_login="contribL",
+            display_name="Contrib L", role="contributor",
+        )
+        r = client.get("/api/admin/users/invites")
+        assert r.status_code == 403
+
+
+# ---------------------------------------------------------------------------
+# v0.18.0: invite-envelope header shape — Slice 2
+#
+# Invite mail goes through `build_envelope` and MUST land Date,
+# Message-ID, Auto-Submitted, AND a `List-Unsubscribe: <mailto:…>`
+# (no URL — the invitee isn't a user yet, so no per-user opt-out
+# row exists). The mailto: target is the operator's `EMAIL_FROM`
+# by default; the operator can override via `EMAIL_UNSUBSCRIBE_MAILTO`.
+# ---------------------------------------------------------------------------
+
+
+def _provision_admin_and_send_invite(client, app_with_fake_gitea_fixture, *, to: str = "headers@ex.co"):
+    provision_user_row(user_id=400, login="adminH", role="admin")
+    sign_in_as(
+        client, user_id=400, gitea_login="adminH",
+        display_name="Admin H", role="admin",
+        email="adminh@test",
+    )
+    _reset_outbound()
+    r = client.post(
+        "/api/admin/users",
+        json={
+            "email": to,
+            "first_name": "Header",
+            "last_name": "Test",
+            "role": "contributor",
+            "custom_message": "",
+        },
+    )
+    assert r.status_code == 200, r.text
+    return _outbound_invite_envelopes(to)[-1]
+
+
+def test_invite_envelope_sets_date_messageid_autosubmitted(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+    from email.utils import parsedate_to_datetime
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        env = _provision_admin_and_send_invite(client, (app, _fake))
+        msg = env["message"]
+        assert parsedate_to_datetime(msg["Date"]) is not None
+        assert msg["Message-ID"].startswith("<") and msg["Message-ID"].endswith(">")
+        assert msg["Auto-Submitted"] == "auto-generated"
+
+
+def test_invite_envelope_has_mailto_list_unsubscribe_only(app_with_fake_gitea):
+    """The invitee isn't a user yet — no per-user opt-out URL is
+    available. The `List-Unsubscribe` MUST be a mailto: form, and
+    the `List-Unsubscribe-Post` header MUST be absent (the
+    one-click semantic requires a URL the MUA can POST to)."""
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        env = _provision_admin_and_send_invite(client, (app, _fake))
+        msg = env["message"]
+        lu = msg["List-Unsubscribe"]
+        assert lu is not None and lu.startswith("<mailto:")
+        # No URL part — invite is mailto-only.
+        assert "https://" not in lu and "http://" not in lu
+        assert msg["List-Unsubscribe-Post"] is None
+
+
+def test_invite_envelope_respects_email_unsubscribe_mailto_override(app_with_fake_gitea, monkeypatch):
+    """When `EMAIL_UNSUBSCRIBE_MAILTO` is set, the mailto: target on
+    `List-Unsubscribe` honors it (lets a deployment route opt-outs
+    to a humans-monitored mailbox distinct from the no-reply
+    sender)."""
+    from fastapi.testclient import TestClient
+
+    monkeypatch.setenv("EMAIL_UNSUBSCRIBE_MAILTO", "ohm@wiggleverse.org?subject=remove")
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        env = _provision_admin_and_send_invite(client, (app, _fake))
+        msg = env["message"]
+        assert "ohm@wiggleverse.org?subject=remove" in msg["List-Unsubscribe"]

backend/tests/test_device_trust_vertical.py

@@ -0,0 +1,494 @@
+"""End-to-end integration tests for the v0.11.0 trust-device vertical
+(§6.2, roadmap item #9).
+
+After a successful OTC or passcode sign-in with `trust_device=true`
+on the body, the server mints a fresh `device_trust` row and sets the
+`rfc_device_trust` cookie. On a subsequent visit, the cookie carries
+a session re-established by `POST /auth/device-trust/start`. The
+tests below prove:
+
+  * `trust_device=false` (default, including omitted) on OTC verify
+    does NOT set the device-trust cookie and does NOT insert a row.
+  * `trust_device=true` on OTC verify DOES set the cookie (HttpOnly +
+    Secure + SameSite=Lax + 30-day Max-Age) and DOES insert a row.
+    The row's hash is NOT the raw token; only the hash lives in the
+    database.
+  * Same shape for passcode verify.
+  * On a returning visit with the cookie, `POST /auth/device-trust/start`
+    re-establishes the session — `GET /api/auth/me` reads the right
+    user without an OTC roundtrip.
+  * `last_seen_at` refreshes on a successful lookup.
+  * `POST /auth/device-trust/start` with no cookie returns 401.
+  * `POST /auth/device-trust/start` with a forged / unknown cookie
+    returns 401 + clears the cookie.
+  * A revoked row refuses the cookie (401) and clears it.
+  * An expired row refuses the cookie (401) and clears it.
+  * `GET /api/auth/me/devices` lists the user's active rows.
+  * `DELETE /api/auth/me/devices/{id}` revokes a single row.
+  * `DELETE /api/auth/me/devices/{id}` for another user's row reads 404.
+  * `DELETE /api/auth/me/devices` revokes every active row.
+  * Constant-time path: bcrypt.checkpw guards lookup; the raw token
+    is never written to logs or to the DB.
+
+The fakes from `test_propose_vertical` give us a working app harness.
+The OTC envelope buffer from `test_otc_vertical` is reused for the
+OTC roundtrips this suite needs.
+"""
+from __future__ import annotations
+
+import pytest
+
+from test_propose_vertical import (  # noqa: F401
+    FakeGitea,
+    app_with_fake_gitea,
+    provision_user_row,
+    tmp_env,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers — mirror the OTC suite's outbound-buffer helpers.
+# ---------------------------------------------------------------------------
+
+
+COOKIE_NAME = "rfc_device_trust"
+
+# The device-trust cookie is set with Secure=True, which httpx (the
+# TestClient's underlying transport) will only return on an https
+# scheme. We use a `base_url="https://testserver"` so the cookie
+# roundtrips faithfully — that mirrors how production deployments
+# serve the framework (per the v0.11.0 upgrade-step requiring HTTPS).
+HTTPS_BASE = "https://testserver"
+
+
+def _reset_outbound():
+    from app import email as email_mod
+    email_mod.reset_sent_envelopes()
+
+
+def _outbound_otc_codes(to_address: str | None = None) -> list[str]:
+    from app import email as email_mod
+    out = []
+    for env in email_mod.sent_envelopes():
+        if env.get("kind") != "otc":
+            continue
+        if to_address is not None and env["to"] != to_address:
+            continue
+        for line in env["body"].splitlines():
+            tok = line.strip()
+            if tok.isdigit() and len(tok) == 6:
+                out.append(tok)
+                break
+    return out
+
+
+def _sign_in_via_otc(client, email: str, *, trust_device: bool = False) -> None:
+    r = client.post("/auth/otc/request", json={"email": email})
+    assert r.status_code == 200, r.text
+    code = _outbound_otc_codes(email)[-1]
+    body = {"email": email, "code": code, "trust_device": trust_device}
+    r = client.post("/auth/otc/verify", json=body)
+    assert r.status_code == 200, r.text
+
+
+def _device_rows_for_email(email: str) -> list[dict]:
+    from app import db
+    rows = db.conn().execute(
+        """
+        SELECT dt.*
+          FROM device_trust dt
+          JOIN users u ON u.id = dt.user_id
+         WHERE u.email = ? COLLATE NOCASE
+         ORDER BY dt.id
+        """,
+        (email,),
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+# ---------------------------------------------------------------------------
+# trust_device flag controls cookie issuance
+# ---------------------------------------------------------------------------
+
+
+def test_otc_verify_without_trust_device_does_not_issue_cookie(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app, base_url=HTTPS_BASE) as client:
+        _reset_outbound()
+        _sign_in_via_otc(client, "alice@example.com", trust_device=False)
+        # No cookie set on the response.
+        assert COOKIE_NAME not in {c.name for c in client.cookies.jar}
+        # No row inserted.
+        assert _device_rows_for_email("alice@example.com") == []
+
+
+def test_otc_verify_with_trust_device_issues_cookie_and_row(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app, base_url=HTTPS_BASE) as client:
+        _reset_outbound()
+        r = client.post("/auth/otc/request", json={"email": "alice@example.com"})
+        assert r.status_code == 200, r.text
+        code = _outbound_otc_codes("alice@example.com")[-1]
+        r = client.post(
+            "/auth/otc/verify",
+            json={"email": "alice@example.com", "code": code, "trust_device": True},
+            headers={"User-Agent": "Mozilla/5.0 (TestBrowser)"},
+        )
+        assert r.status_code == 200, r.text
+
+        # Cookie present on the response.
+        set_cookie = r.headers.get("set-cookie", "")
+        assert COOKIE_NAME in set_cookie
+        # Cookie attribute set asserts the spec'd shape. Starlette emits
+        # the attribute names case-insensitively (`samesite=lax`,
+        # `httponly`); we normalize when asserting.
+        lower = set_cookie.lower()
+        assert "httponly" in lower
+        assert "secure" in lower
+        assert "samesite=lax" in lower
+        assert "max-age=" in lower
+
+        # Row inserted; hash is not the raw token.
+        rows = _device_rows_for_email("alice@example.com")
+        assert len(rows) == 1
+        row = rows[0]
+        assert row["revoked_at"] is None
+        assert row["user_agent"] == "Mozilla/5.0 (TestBrowser)"
+        cookie_token = client.cookies.get(COOKIE_NAME)
+        assert cookie_token
+        assert cookie_token != row["device_token_hash"]
+        # bcrypt hash shape (starts with $2)
+        assert row["device_token_hash"].startswith("$2")
+
+
+def test_passcode_verify_with_trust_device_issues_cookie(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app, base_url=HTTPS_BASE) as client:
+        _reset_outbound()
+        _sign_in_via_otc(client, "alice@example.com")
+
+        # Set a passcode.
+        r = client.post("/auth/passcode/set", json={"passcode": "secret123"})
+        assert r.status_code == 200, r.text
+
+        # Sign out so the passcode verify path is the active sign-in.
+        client.cookies.clear()
+
+        # Passcode verify with trust_device=true issues a row.
+        r = client.post(
+            "/auth/passcode/verify",
+            json={"email": "alice@example.com", "passcode": "secret123", "trust_device": True},
+            headers={"User-Agent": "Test/Phone"},
+        )
+        assert r.status_code == 200, r.text
+        set_cookie = r.headers.get("set-cookie", "")
+        assert COOKIE_NAME in set_cookie
+
+        rows = _device_rows_for_email("alice@example.com")
+        assert len(rows) == 1
+        assert rows[0]["user_agent"] == "Test/Phone"
+
+
+# ---------------------------------------------------------------------------
+# /auth/device-trust/start
+# ---------------------------------------------------------------------------
+
+
+def test_device_trust_start_with_no_cookie_returns_401(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app, base_url=HTTPS_BASE) as client:
+        r = client.post("/auth/device-trust/start")
+        assert r.status_code == 401
+
+
+def test_device_trust_start_with_valid_cookie_establishes_session(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app, base_url=HTTPS_BASE) as client:
+        _reset_outbound()
+        # Trust the device.
+        r = client.post("/auth/otc/request", json={"email": "alice@example.com"})
+        assert r.status_code == 200, r.text
+        code = _outbound_otc_codes("alice@example.com")[-1]
+        r = client.post(
+            "/auth/otc/verify",
+            json={"email": "alice@example.com", "code": code, "trust_device": True},
+        )
+        assert r.status_code == 200, r.text
+        trust_cookie = client.cookies.get(COOKIE_NAME)
+        assert trust_cookie
+
+        # Clear the session cookie so only the device-trust cookie is in
+        # play. We keep `rfc_device_trust` and drop `rfc_session`.
+        for cookie in list(client.cookies.jar):
+            if cookie.name != COOKIE_NAME:
+                client.cookies.jar.clear(cookie.domain, cookie.path, cookie.name)
+
+        # The session cookie is gone — /api/auth/me reads anonymous.
+        me = client.get("/api/auth/me").json()
+        assert me["authenticated"] is False
+
+        # Hit the trust-start endpoint; the cookie re-establishes the session.
+        r = client.post("/auth/device-trust/start")
+        assert r.status_code == 200, r.text
+        assert r.json()["user"]["email"] == "alice@example.com"
+
+        # /api/auth/me now reads authenticated.
+        me = client.get("/api/auth/me").json()
+        assert me["authenticated"] is True
+        assert me["user"]["email"] == "alice@example.com"
+
+
+def test_device_trust_start_refreshes_last_seen_at(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app, base_url=HTTPS_BASE) as client:
+        _reset_outbound()
+        r = client.post("/auth/otc/request", json={"email": "alice@example.com"})
+        assert r.status_code == 200, r.text
+        code = _outbound_otc_codes("alice@example.com")[-1]
+        r = client.post(
+            "/auth/otc/verify",
+            json={"email": "alice@example.com", "code": code, "trust_device": True},
+        )
+        assert r.status_code == 200, r.text
+
+        # Force the existing row's last_seen_at into the past so we can
+        # assert the refresh moved it forward.
+        db.conn().execute(
+            """
+            UPDATE device_trust
+               SET last_seen_at = datetime('now', '-7 days')
+            """
+        )
+
+        # Hit the start endpoint.
+        r = client.post("/auth/device-trust/start")
+        assert r.status_code == 200, r.text
+
+        # last_seen_at is now recent (within the last minute).
+        row = db.conn().execute(
+            "SELECT last_seen_at, datetime('now') >= datetime(last_seen_at, '-1 minute') AS fresh FROM device_trust LIMIT 1"
+        ).fetchone()
+        assert row["fresh"] == 1
+
+
+def test_device_trust_start_with_revoked_row_refuses_and_clears(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app, base_url=HTTPS_BASE) as client:
+        _reset_outbound()
+        r = client.post("/auth/otc/request", json={"email": "alice@example.com"})
+        assert r.status_code == 200, r.text
+        code = _outbound_otc_codes("alice@example.com")[-1]
+        r = client.post(
+            "/auth/otc/verify",
+            json={"email": "alice@example.com", "code": code, "trust_device": True},
+        )
+        assert r.status_code == 200, r.text
+
+        # Revoke the row out-of-band.
+        db.conn().execute(
+            "UPDATE device_trust SET revoked_at = datetime('now')"
+        )
+
+        # Now the start endpoint refuses + clears the cookie.
+        r = client.post("/auth/device-trust/start")
+        assert r.status_code == 401
+        # The cookie is cleared via a Set-Cookie header with Max-Age=0
+        # (Starlette's `delete_cookie` shape).
+        set_cookie = r.headers.get("set-cookie", "")
+        assert COOKIE_NAME in set_cookie
+        assert "Max-Age=0" in set_cookie or 'expires=Thu, 01 Jan 1970' in set_cookie.lower().replace("expires=thu", "expires=Thu")
+
+
+def test_device_trust_start_with_expired_row_refuses_and_clears(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app, base_url=HTTPS_BASE) as client:
+        _reset_outbound()
+        r = client.post("/auth/otc/request", json={"email": "alice@example.com"})
+        assert r.status_code == 200, r.text
+        code = _outbound_otc_codes("alice@example.com")[-1]
+        r = client.post(
+            "/auth/otc/verify",
+            json={"email": "alice@example.com", "code": code, "trust_device": True},
+        )
+        assert r.status_code == 200, r.text
+
+        # Backdate the expiry into the past.
+        db.conn().execute(
+            "UPDATE device_trust SET expires_at = datetime('now', '-1 day')"
+        )
+
+        r = client.post("/auth/device-trust/start")
+        assert r.status_code == 401
+        set_cookie = r.headers.get("set-cookie", "")
+        assert COOKIE_NAME in set_cookie
+
+
+def test_device_trust_start_with_forged_cookie_refuses_and_clears(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app, base_url=HTTPS_BASE) as client:
+        # No real row; just paste a cookie value.
+        client.cookies.set(COOKIE_NAME, "definitely-not-a-real-token-value-xxx")
+        r = client.post("/auth/device-trust/start")
+        assert r.status_code == 401
+        set_cookie = r.headers.get("set-cookie", "")
+        assert COOKIE_NAME in set_cookie
+
+
+# ---------------------------------------------------------------------------
+# /api/auth/me/devices — list + revoke
+# ---------------------------------------------------------------------------
+
+
+def test_list_devices_requires_session(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app, base_url=HTTPS_BASE) as client:
+        r = client.get("/api/auth/me/devices")
+        assert r.status_code == 401
+
+
+def test_list_devices_returns_active_rows_only(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app, base_url=HTTPS_BASE) as client:
+        _reset_outbound()
+        _sign_in_via_otc(client, "alice@example.com", trust_device=True)
+
+        # Add a second trusted device by re-running the verify flow.
+        # OTC has a per-email cooldown, so drop the cooldown rather
+        # than waiting it out.
+        db.conn().execute("UPDATE otc_codes SET consumed_at = datetime('now', '-1 hour'), created_at = datetime('now', '-1 hour')")
+        r = client.post("/auth/otc/request", json={"email": "alice@example.com"})
+        assert r.status_code == 200, r.text
+        code = _outbound_otc_codes("alice@example.com")[-1]
+        r = client.post(
+            "/auth/otc/verify",
+            json={"email": "alice@example.com", "code": code, "trust_device": True},
+            headers={"User-Agent": "Test/Tablet"},
+        )
+        assert r.status_code == 200, r.text
+
+        # Revoke one row directly.
+        db.conn().execute(
+            "UPDATE device_trust SET revoked_at = datetime('now') WHERE id = 1"
+        )
+
+        # /api/auth/me/devices returns only the un-revoked one.
+        r = client.get("/api/auth/me/devices")
+        assert r.status_code == 200, r.text
+        items = r.json()["items"]
+        assert len(items) == 1
+        assert items[0]["user_agent"] == "Test/Tablet"
+
+
+def test_revoke_single_device_kills_the_row(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app, base_url=HTTPS_BASE) as client:
+        _reset_outbound()
+        _sign_in_via_otc(client, "alice@example.com", trust_device=True)
+
+        r = client.get("/api/auth/me/devices")
+        assert r.status_code == 200, r.text
+        items = r.json()["items"]
+        assert len(items) == 1
+        device_id = items[0]["id"]
+
+        # Revoke it.
+        r = client.delete(f"/api/auth/me/devices/{device_id}")
+        assert r.status_code == 200, r.text
+
+        # List is empty.
+        r = client.get("/api/auth/me/devices")
+        assert r.json()["items"] == []
+
+        # The row in the table has revoked_at populated.
+        row = db.conn().execute(
+            "SELECT revoked_at FROM device_trust WHERE id = ?", (device_id,)
+        ).fetchone()
+        assert row["revoked_at"] is not None
+
+
+def test_revoke_other_users_device_reads_404(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app, base_url=HTTPS_BASE) as client:
+        _reset_outbound()
+        # Alice trusts a device.
+        _sign_in_via_otc(client, "alice@example.com", trust_device=True)
+        alice_device_id = client.get("/api/auth/me/devices").json()["items"][0]["id"]
+
+        # Bob signs in (without a trusted device of his own).
+        client.cookies.clear()
+        db.conn().execute("UPDATE otc_codes SET consumed_at = datetime('now', '-1 hour'), created_at = datetime('now', '-1 hour')")
+        _sign_in_via_otc(client, "bob@example.com", trust_device=False)
+
+        # Bob tries to revoke Alice's row by id.
+        r = client.delete(f"/api/auth/me/devices/{alice_device_id}")
+        assert r.status_code == 404
+
+        # Alice's row is still active.
+        row = db.conn().execute(
+            "SELECT revoked_at FROM device_trust WHERE id = ?", (alice_device_id,)
+        ).fetchone()
+        assert row["revoked_at"] is None
+
+
+def test_revoke_all_devices_kills_every_active_row(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app, base_url=HTTPS_BASE) as client:
+        _reset_outbound()
+        _sign_in_via_otc(client, "alice@example.com", trust_device=True)
+
+        # Add a second device.
+        db.conn().execute("UPDATE otc_codes SET consumed_at = datetime('now', '-1 hour'), created_at = datetime('now', '-1 hour')")
+        r = client.post("/auth/otc/request", json={"email": "alice@example.com"})
+        assert r.status_code == 200, r.text
+        code = _outbound_otc_codes("alice@example.com")[-1]
+        r = client.post(
+            "/auth/otc/verify",
+            json={"email": "alice@example.com", "code": code, "trust_device": True},
+        )
+        assert r.status_code == 200, r.text
+
+        # Two active rows.
+        assert len(client.get("/api/auth/me/devices").json()["items"]) == 2
+
+        # Revoke all.
+        r = client.delete("/api/auth/me/devices")
+        assert r.status_code == 200, r.text
+        assert r.json()["revoked"] == 2
+
+        # List is empty.
+        assert client.get("/api/auth/me/devices").json()["items"] == []

backend/tests/test_e2e_smoke.py

@@ -22,6 +22,7 @@ import pytest
 from test_propose_vertical import (  # noqa: F401
     FakeGitea,
     app_with_fake_gitea,
+    grant_rfc_collaborator,
     provision_user_row,
     sign_in_as,
     tmp_env,
@@ -131,6 +132,11 @@ def test_full_user_lifecycle_propose_through_hygiene(app_with_fake_gitea):
         assert d["repo"] == "wiggleverse/rfc-0001-ohm"
 
         # --- 8. Alice opens a PR on the now-active RFC's per-RFC repo. ---
+        # v0.16.0 (item #12): ben is the RFC owner now; alice needs a
+        # per-RFC contributor invitation to cut a branch. In the
+        # production flow, ben would invite her via /invitations and
+        # she'd accept; we shortcut to the same end-state.
+        grant_rfc_collaborator(user_id=2, rfc_slug="ohm", role_in_rfc="contributor")
         sign_in_as(client, user_id=2, gitea_login="alice",
                    display_name="Alice", role="contributor", email="alice@test")
         r = client.post("/api/rfcs/ohm/branches/main/promote-to-branch", json={})
@@ -225,13 +231,17 @@ def test_bounce_webhook_refuses_unsigned_when_secret_configured(app_with_fake_gi
 
         # With the right header, the call passes the guard. (No matching
         # user exists, so we get {matched: False} — that's the v1 contract.)
+        # v0.18.0 Slice 5: the response now includes `correlated_id`
+        # (the outbound_emails row id that matched the bounce's
+        # `message_id`, if one was supplied). The body didn't pass a
+        # message_id, so correlated_id is None.
         r = client.post(
             "/api/webhooks/email-bounce",
             json={"email": "stranger@example.com", "kind": "hard"},
             headers={"X-Webhook-Secret": "shhh"},
         )
         assert r.status_code == 200, r.text
-        assert r.json() == {"ok": True, "matched": False}
+        assert r.json() == {"ok": True, "matched": False, "correlated_id": None}
 
 
 def test_bounce_webhook_open_when_secret_unset(app_with_fake_gitea):

backend/tests/test_email_envelope.py

@@ -0,0 +1,173 @@
+"""Unit tests for `app.email_envelope.build_envelope` (v0.18.0 Slice 1).
+
+These tests don't spin up the FastAPI app or touch the DB — they
+exercise the helper directly. The integration tests in
+test_otc_vertical / test_admin_create_user_invite_vertical /
+test_notifications_vertical exercise the helper's *use* via the
+shared `_SENT` buffer (the send path appends the envelope dict
+before invoking the helper).
+"""
+from __future__ import annotations
+
+from email.utils import parsedate_to_datetime
+
+from app.email_envelope import build_envelope
+
+
+def _base_kwargs(**overrides):
+    base = dict(
+        to_address="recipient@example.com",
+        from_address="notifications@ohm.wiggleverse.org",
+        from_name="OHM",
+        subject="A test subject",
+        body_plain="Hello, world.\n",
+    )
+    base.update(overrides)
+    return base
+
+
+# ---------------------------------------------------------------------------
+# Always-present headers
+# ---------------------------------------------------------------------------
+
+
+def test_envelope_sets_from_to_subject():
+    msg = build_envelope(**_base_kwargs())
+    assert msg["To"] == "recipient@example.com"
+    assert msg["Subject"] == "A test subject"
+    # `From` is the display-form: "OHM <notifications@ohm.wiggleverse.org>".
+    assert "OHM" in msg["From"]
+    assert "<notifications@ohm.wiggleverse.org>" in msg["From"]
+
+
+def test_envelope_sets_date_header_parseable():
+    msg = build_envelope(**_base_kwargs())
+    raw = msg["Date"]
+    assert raw, "Date header must be set"
+    # parsedate_to_datetime raises ValueError on malformed input.
+    dt = parsedate_to_datetime(raw)
+    assert dt is not None
+
+
+def test_envelope_sets_message_id_with_from_domain_by_default():
+    msg = build_envelope(**_base_kwargs())
+    mid = msg["Message-ID"]
+    assert mid, "Message-ID must be set"
+    # Shape per RFC 5322 / make_msgid: <random@domain>
+    assert mid.startswith("<") and mid.endswith(">")
+    assert "@ohm.wiggleverse.org>" in mid
+
+
+def test_envelope_message_id_domain_override():
+    msg = build_envelope(**_base_kwargs(msgid_domain="example.test"))
+    assert "@example.test>" in msg["Message-ID"]
+
+
+def test_envelope_message_id_falls_back_to_localhost_if_from_has_no_at():
+    # Defensive: a malformed from_address shouldn't crash the helper.
+    msg = build_envelope(**_base_kwargs(from_address="bare-no-at-sign"))
+    assert "@localhost>" in msg["Message-ID"]
+
+
+# ---------------------------------------------------------------------------
+# Auto-Submitted (RFC 3834)
+# ---------------------------------------------------------------------------
+
+
+def test_envelope_sets_auto_submitted_for_transactional_default():
+    msg = build_envelope(**_base_kwargs())
+    assert msg["Auto-Submitted"] == "auto-generated"
+
+
+def test_envelope_omits_auto_submitted_when_transactional_is_false():
+    msg = build_envelope(**_base_kwargs(is_transactional=False))
+    assert msg["Auto-Submitted"] is None
+
+
+# ---------------------------------------------------------------------------
+# Reply-To
+# ---------------------------------------------------------------------------
+
+
+def test_envelope_sets_reply_to_when_provided():
+    msg = build_envelope(**_base_kwargs(reply_to="ohm@wiggleverse.org"))
+    assert msg["Reply-To"] == "ohm@wiggleverse.org"
+
+
+def test_envelope_omits_reply_to_when_absent():
+    msg = build_envelope(**_base_kwargs())
+    assert msg["Reply-To"] is None
+
+
+# ---------------------------------------------------------------------------
+# List-Unsubscribe (the headers RFC 8058 / Gmail-Yahoo care about)
+# ---------------------------------------------------------------------------
+
+
+def test_envelope_no_list_unsubscribe_when_neither_given():
+    """OTC mail: the recipient explicitly requested the code; no
+    unsubscribe semantics. The header MUST be absent (presence would
+    imply OHM has the recipient on a list, which it doesn't)."""
+    msg = build_envelope(**_base_kwargs())
+    assert msg["List-Unsubscribe"] is None
+    assert msg["List-Unsubscribe-Post"] is None
+
+
+def test_envelope_mailto_only_list_unsubscribe():
+    """Admin invite / per-RFC invite: `mailto:` form only, no URL.
+    The recipient isn't a user yet, so there's no per-user opt-out
+    URL to flip; the operator handles ad-hoc opt-outs manually."""
+    msg = build_envelope(**_base_kwargs(
+        unsubscribe_mailto="ohm@wiggleverse.org?subject=remove",
+    ))
+    assert msg["List-Unsubscribe"] == "<mailto:ohm@wiggleverse.org?subject=remove>"
+    # NO List-Unsubscribe-Post when only a mailto is present — the
+    # one-click semantic requires a URL the MUA can POST to.
+    assert msg["List-Unsubscribe-Post"] is None
+
+
+def test_envelope_full_one_click_list_unsubscribe():
+    """Watcher notification / bundle: `mailto:` + signed-URL +
+    `List-Unsubscribe-Post: List-Unsubscribe=One-Click`. Gmail and
+    Yahoo enforce this for bulk-adjacent mail per RFC 8058."""
+    msg = build_envelope(**_base_kwargs(
+        unsubscribe_mailto="ohm@wiggleverse.org?subject=remove",
+        unsubscribe_url="https://ohm.wiggleverse.org/api/email/unsubscribe?t=abc",
+    ))
+    lu = msg["List-Unsubscribe"]
+    assert "<mailto:ohm@wiggleverse.org?subject=remove>" in lu
+    assert "<https://ohm.wiggleverse.org/api/email/unsubscribe?t=abc>" in lu
+    assert msg["List-Unsubscribe-Post"] == "List-Unsubscribe=One-Click"
+
+
+def test_envelope_url_only_list_unsubscribe_still_sets_post():
+    msg = build_envelope(**_base_kwargs(
+        unsubscribe_url="https://ohm.wiggleverse.org/api/email/unsubscribe?t=abc",
+    ))
+    assert msg["List-Unsubscribe"] == "<https://ohm.wiggleverse.org/api/email/unsubscribe?t=abc>"
+    assert msg["List-Unsubscribe-Post"] == "List-Unsubscribe=One-Click"
+
+
+# ---------------------------------------------------------------------------
+# Body shape — plain-only vs multipart/alternative
+# ---------------------------------------------------------------------------
+
+
+def test_envelope_plain_only_body_is_text_plain():
+    msg = build_envelope(**_base_kwargs())
+    # No HTML alternative -> single-part text/plain.
+    assert msg.get_content_type() == "text/plain"
+    assert msg.get_content().strip() == "Hello, world."
+
+
+def test_envelope_with_html_is_multipart_alternative():
+    msg = build_envelope(**_base_kwargs(body_html="<p>Hello, <b>world</b>.</p>"))
+    assert msg.get_content_type() == "multipart/alternative"
+    # Two parts: text/plain first (so plain-text clients picking the
+    # first part get the readable text), text/html second.
+    parts = list(msg.iter_parts())
+    assert len(parts) == 2
+    assert parts[0].get_content_type() == "text/plain"
+    assert parts[1].get_content_type() == "text/html"
+    assert "Hello, world." in parts[0].get_content()
+    assert "<b>world</b>" in parts[1].get_content()

backend/tests/test_graduation_vertical.py

@@ -34,6 +34,7 @@ import pytest
 from test_propose_vertical import (  # noqa: F401
     FakeGitea,
     app_with_fake_gitea,
+    grant_rfc_collaborator,
     provision_user_row,
     sign_in_as,
     tmp_env,
@@ -248,6 +249,9 @@ def test_graduate_refuses_when_body_edit_pr_open(app_with_fake_gitea):
         provision_user_row(user_id=2, login="alice", role="contributor")
         seed_owned_super_draft(fake, slug="ohm", title="OHM",
                                pitch=PITCH, owners=["ben"])
+        # v0.16.0 (item #12): ben is the RFC owner; alice needs a per-RFC
+        # contributor invitation to cut an edit branch on the super-draft.
+        grant_rfc_collaborator(user_id=2, rfc_slug="ohm", role_in_rfc="contributor")
         sign_in_as(client, user_id=2, gitea_login="alice",
                    display_name="Alice", role="contributor")
 
@@ -497,6 +501,8 @@ def test_pre_graduation_history_surfaces_edit_branch_threads(app_with_fake_gitea
         provision_user_row(user_id=2, login="alice", role="contributor")
         seed_owned_super_draft(fake, slug="ohm", title="OHM",
                                pitch=PITCH, owners=["ben"])
+        # v0.16.0 (item #12): alice needs per-RFC contributor access.
+        grant_rfc_collaborator(user_id=2, rfc_slug="ohm", role_in_rfc="contributor")
 
         # Alice cuts an edit branch and starts chatting on it.
         sign_in_as(client, user_id=2, gitea_login="alice",

backend/tests/test_notifications_vertical.py

@@ -612,3 +612,127 @@ def test_explicit_watch_set_overrides_auto(app_with_fake_gitea):
         # the user put them.
         assert row["set_by"] == "explicit"
         assert row["state"] == "following"
+
+
+# ---------------------------------------------------------------------------
+# v0.18.0 — envelope headers + RFC 8058 one-click POST endpoint
+#
+# Watcher notifications are bulk-adjacent (a busy RFC can produce
+# dozens of structural events); per the proposal, they MUST carry
+# `Date`, `Message-ID`, `Auto-Submitted`, full `List-Unsubscribe`
+# (mailto + signed URL), AND `List-Unsubscribe-Post:
+# List-Unsubscribe=One-Click` per RFC 8058. Gmail and Yahoo
+# enforce this for senders at OHM's volume tier.
+# ---------------------------------------------------------------------------
+
+
+def test_notification_envelope_carries_full_one_click_headers(app_with_fake_gitea):
+    """A `proposal_merged` event lands a watcher notification email
+    with the full one-click unsubscribe shape."""
+    from fastapi.testclient import TestClient
+    from email.utils import parsedate_to_datetime
+    from app import db, email as email_mod
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=2, login="alice", role="contributor")
+        provision_user_row(user_id=1, login="ben", role="owner")
+
+        sign_in_as(client, user_id=2, gitea_login="alice", display_name="Alice", role="contributor", email="alice@test")
+        r = client.post("/api/rfcs/propose", json={"title": "OHM", "slug": "ohm", "pitch": PITCH, "tags": []})
+        assert r.status_code == 200
+        email_mod.reset_sent_envelopes()
+        sign_in_as(client, user_id=1, gitea_login="ben", display_name="Ben", role="owner", email="ben@test")
+        merge_r = client.post(f"/api/proposals/{r.json()['pr_number']}/merge")
+        assert merge_r.status_code == 200, merge_r.text
+
+        envelopes = [e for e in email_mod.sent_envelopes() if e["to"] == "alice@test"]
+        assert envelopes, "watcher notification did not fire"
+        msg = envelopes[-1]["message"]
+        # Always-present headers from the helper.
+        assert parsedate_to_datetime(msg["Date"]) is not None
+        assert msg["Message-ID"].startswith("<") and msg["Message-ID"].endswith(">")
+        assert msg["Auto-Submitted"] == "auto-generated"
+        # Full one-click unsubscribe.
+        lu = msg["List-Unsubscribe"]
+        assert lu is not None
+        assert "<mailto:" in lu
+        # URL part carries the signed token per make_unsubscribe_url.
+        assert "/api/email/unsubscribe?t=" in lu
+        assert msg["List-Unsubscribe-Post"] == "List-Unsubscribe=One-Click"
+
+
+def test_email_unsubscribe_post_one_click_flips_category_off(app_with_fake_gitea):
+    """RFC 8058: Gmail/Yahoo POST `List-Unsubscribe=One-Click` to the
+    URL in the List-Unsubscribe header. The endpoint MUST accept POST
+    + the same token shape as the GET handler + return 200 + flip the
+    flag."""
+    from fastapi.testclient import TestClient
+    from app import db, email as email_mod
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=2, login="alice", role="contributor")
+        token = email_mod.make_unsubscribe_url(2, "personal-direct").split("t=", 1)[1]
+
+        r = client.post(
+            f"/api/email/unsubscribe?t={token}",
+            data={"List-Unsubscribe": "One-Click"},
+        )
+        assert r.status_code == 200, r.text
+        body = r.json()
+        assert body["ok"] is True
+        assert body["category"] == "personal-direct"
+
+        row = db.conn().execute(
+            "SELECT email_personal_direct FROM users WHERE id = 2"
+        ).fetchone()
+        assert row["email_personal_direct"] == 0
+
+
+def test_email_unsubscribe_post_all_sets_global_opt_out(app_with_fake_gitea):
+    """The v0.18.0 `all` synthetic category (used by the bundle +
+    digest paths) MUST set `email_opt_out_all = 1`."""
+    from fastapi.testclient import TestClient
+    from app import db, email as email_mod
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=2, login="alice", role="contributor")
+        token = email_mod.make_unsubscribe_url(2, "all").split("t=", 1)[1]
+        r = client.post(f"/api/email/unsubscribe?t={token}")
+        assert r.status_code == 200
+        assert r.json() == {"ok": True, "category": "all"}
+        row = db.conn().execute(
+            "SELECT email_opt_out_all FROM users WHERE id = 2"
+        ).fetchone()
+        assert row["email_opt_out_all"] == 1
+
+
+def test_email_unsubscribe_get_all_sets_global_opt_out(app_with_fake_gitea):
+    """GET handler also accepts the `all` category and lands the
+    global opt-out (so an MUA that doesn't honor RFC 8058 POST and
+    just opens the URL in a browser still works)."""
+    from fastapi.testclient import TestClient
+    from app import db, email as email_mod
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=2, login="alice", role="contributor")
+        token = email_mod.make_unsubscribe_url(2, "all").split("t=", 1)[1]
+        r = client.get(f"/api/email/unsubscribe?t={token}")
+        assert r.status_code == 200
+        assert "Unsubscribed" in r.text
+        row = db.conn().execute(
+            "SELECT email_opt_out_all FROM users WHERE id = 2"
+        ).fetchone()
+        assert row["email_opt_out_all"] == 1
+
+
+def test_email_unsubscribe_post_refuses_invalid_token(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        r = client.post("/api/email/unsubscribe?t=not-a-valid-token")
+        assert r.status_code == 400

backend/tests/test_otc_vertical.py

@@ -347,3 +347,53 @@ def test_otc_re_request_invalidates_prior_unused_code(app_with_fake_gitea, monke
         # The new code still works.
         r = client.post("/auth/otc/verify", json={"email": "alice@example.com", "code": second})
         assert r.status_code == 200
+
+
+# ---------------------------------------------------------------------------
+# v0.18.0: envelope headers — Slice 2
+#
+# OTC mail goes through `build_envelope` and MUST land Date,
+# Message-ID, and Auto-Submitted but MUST NOT carry a
+# List-Unsubscribe header (the recipient explicitly requested the
+# code; advertising a list semantic would be wrong).
+# ---------------------------------------------------------------------------
+
+
+def _last_otc_envelope():
+    from app import email as email_mod
+    otc = [e for e in email_mod.sent_envelopes() if e.get("kind") == "otc"]
+    assert otc, "no OTC envelope in the buffer"
+    return otc[-1]
+
+
+def test_otc_envelope_sets_date_messageid_autosubmitted(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+    from email.utils import parsedate_to_datetime
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        client.post("/auth/otc/request", json={"email": "headers@example.com"})
+        msg = _last_otc_envelope()["message"]
+        # Date is RFC 5322 parseable.
+        assert parsedate_to_datetime(msg["Date"]) is not None
+        # Message-ID is bracketed and carries the From-address @-domain.
+        mid = msg["Message-ID"]
+        assert mid.startswith("<") and mid.endswith(">")
+        # Auto-Submitted prevents auto-responder loops.
+        assert msg["Auto-Submitted"] == "auto-generated"
+
+
+def test_otc_envelope_has_no_list_unsubscribe(app_with_fake_gitea):
+    """The recipient explicitly typed their email and asked for a
+    code; the framework MUST NOT advertise a list semantic on this
+    mail. Per the v0.18.0 proposal's tradeoff discussion."""
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        client.post("/auth/otc/request", json={"email": "headers@example.com"})
+        msg = _last_otc_envelope()["message"]
+        assert msg["List-Unsubscribe"] is None
+        assert msg["List-Unsubscribe-Post"] is None

backend/tests/test_outbound_emails_vertical.py

@@ -0,0 +1,368 @@
+"""End-to-end integration tests for the v0.18.0 Slice 4
+outbound_emails audit table + admin endpoint.
+
+The release adds:
+  * `backend/migrations/020_outbound_emails.sql` — the audit table.
+  * `record_outbound()` in `email.py` — the write helper every send
+    path calls before returning, capturing status='sent' / 'failed'
+    / 'deferred' (the dev-fallback path when SMTP_HOST is unset).
+  * `GET /api/admin/outbound-emails` — admin-only listing, filterable
+    by kind / status / to_address.
+
+These tests prove:
+  * Sending OTC / invite / notification mail writes one row per send
+    (status='deferred' under tests since SMTP_HOST is unset).
+  * The Message-ID on the row matches the envelope's Message-ID
+    header (the seam Slice 5 uses for bounce correlation).
+  * `kind` is populated per send path.
+  * `GET /api/admin/outbound-emails` lists rows newest-first,
+    accepts filters, refuses non-admins.
+"""
+from __future__ import annotations
+
+from test_propose_vertical import (  # noqa: F401
+    FakeGitea,
+    app_with_fake_gitea,
+    provision_user_row,
+    sign_in_as,
+    tmp_env,
+)
+
+
+# ---------------------------------------------------------------------------
+# Write-on-send wiring
+# ---------------------------------------------------------------------------
+
+
+def test_otc_send_writes_outbound_row_with_message_id(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+    from app import db, email as email_mod
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        email_mod.reset_sent_envelopes()
+        r = client.post("/auth/otc/request", json={"email": "newcomer@ex.co"})
+        assert r.status_code == 200
+
+        # Audit row landed.
+        rows = db.conn().execute(
+            "SELECT id, to_address, kind, status, message_id, error "
+            "FROM outbound_emails WHERE to_address = 'newcomer@ex.co'"
+        ).fetchall()
+        assert len(rows) == 1
+        row = rows[0]
+        assert row["kind"] == "otc"
+        # No SMTP_HOST in tests -> 'deferred', not 'sent'.
+        assert row["status"] == "deferred"
+        assert row["error"] is None
+        # Message-ID matches the envelope's header (the seam Slice 5 uses).
+        envelopes = [e for e in email_mod.sent_envelopes() if e.get("kind") == "otc"]
+        assert envelopes
+        envelope_mid = envelopes[-1]["message"]["Message-ID"]
+        assert row["message_id"] == envelope_mid
+
+
+def test_invite_send_writes_outbound_row(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=500, login="adminQ", role="admin")
+        sign_in_as(
+            client, user_id=500, gitea_login="adminQ",
+            display_name="Admin Q", role="admin",
+            email="adminq@test",
+        )
+        r = client.post(
+            "/api/admin/users",
+            json={
+                "email": "invitee@ex.co",
+                "first_name": "Inv", "last_name": "Itee",
+                "role": "contributor", "custom_message": "",
+            },
+        )
+        assert r.status_code == 200, r.text
+
+        rows = db.conn().execute(
+            "SELECT kind, status, message_id FROM outbound_emails "
+            "WHERE to_address = 'invitee@ex.co'"
+        ).fetchall()
+        assert len(rows) == 1
+        assert rows[0]["kind"] == "invite"
+        assert rows[0]["status"] == "deferred"
+        assert rows[0]["message_id"] is not None
+
+
+def test_notification_send_writes_outbound_row_with_notification_id(app_with_fake_gitea):
+    """Watcher notifications carry a `notification_id` FK so the
+    admin can join through to the notifications table to see what
+    triggered the send."""
+    from fastapi.testclient import TestClient
+    from app import db, email as email_mod
+    from test_notifications_vertical import PITCH
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=2, login="alice", role="contributor")
+        provision_user_row(user_id=1, login="ben", role="owner")
+        sign_in_as(
+            client, user_id=2, gitea_login="alice",
+            display_name="Alice", role="contributor", email="alice@test",
+        )
+        r = client.post("/api/rfcs/propose", json={
+            "title": "OHM", "slug": "ohm", "pitch": PITCH, "tags": [],
+        })
+        email_mod.reset_sent_envelopes()
+        # Wipe pre-merge audit rows so the assertion below is unambiguous.
+        db.conn().execute("DELETE FROM outbound_emails")
+        sign_in_as(
+            client, user_id=1, gitea_login="ben",
+            display_name="Ben", role="owner", email="ben@test",
+        )
+        merge_r = client.post(f"/api/proposals/{r.json()['pr_number']}/merge")
+        assert merge_r.status_code == 200, merge_r.text
+
+        rows = db.conn().execute(
+            "SELECT kind, status, notification_id, message_id "
+            "FROM outbound_emails WHERE to_address = 'alice@test'"
+        ).fetchall()
+        assert rows, "no outbound_emails row for alice@test"
+        # At least one notification kind, with a populated FK.
+        notif_rows = [r for r in rows if r["kind"] == "notification"]
+        assert notif_rows
+        for nr in notif_rows:
+            assert nr["status"] == "deferred"
+            assert nr["notification_id"] is not None
+            assert nr["message_id"] is not None
+
+
+# ---------------------------------------------------------------------------
+# Admin endpoint
+# ---------------------------------------------------------------------------
+
+
+def test_admin_outbound_emails_lists_rows(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        # Generate a few rows.
+        client.post("/auth/otc/request", json={"email": "one@ex.co"})
+
+        provision_user_row(user_id=600, login="adminR", role="admin")
+        sign_in_as(
+            client, user_id=600, gitea_login="adminR",
+            display_name="Admin R", role="admin", email="adminr@test",
+        )
+        client.post("/api/admin/users", json={
+            "email": "two@ex.co", "first_name": "T", "last_name": "Wo",
+            "role": "contributor", "custom_message": "",
+        })
+
+        r = client.get("/api/admin/outbound-emails")
+        assert r.status_code == 200, r.text
+        items = r.json()["items"]
+        kinds = {it["kind"] for it in items}
+        assert "otc" in kinds
+        assert "invite" in kinds
+        # Newest-first.
+        ids = [it["id"] for it in items]
+        assert ids == sorted(ids, reverse=True)
+
+
+def test_admin_outbound_emails_filters_by_kind(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        client.post("/auth/otc/request", json={"email": "filter1@ex.co"})
+
+        provision_user_row(user_id=601, login="adminS", role="admin")
+        sign_in_as(
+            client, user_id=601, gitea_login="adminS",
+            display_name="Admin S", role="admin", email="admins@test",
+        )
+        client.post("/api/admin/users", json={
+            "email": "filter2@ex.co", "first_name": "F", "last_name": "Two",
+            "role": "contributor", "custom_message": "",
+        })
+
+        r = client.get("/api/admin/outbound-emails?kind=otc")
+        assert r.status_code == 200
+        items = r.json()["items"]
+        assert items
+        assert all(it["kind"] == "otc" for it in items)
+
+
+def test_admin_outbound_emails_filters_by_to_address(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        client.post("/auth/otc/request", json={"email": "TARGET@ex.co"})
+        client.post("/auth/otc/request", json={"email": "other@ex.co"})
+
+        provision_user_row(user_id=602, login="adminT", role="admin")
+        sign_in_as(
+            client, user_id=602, gitea_login="adminT",
+            display_name="Admin T", role="admin", email="admint@test",
+        )
+
+        # to_address filter is case-insensitive.
+        r = client.get("/api/admin/outbound-emails?to_address=target@ex.co")
+        assert r.status_code == 200
+        items = r.json()["items"]
+        assert items
+        assert all(it["to_address"].lower() == "target@ex.co" for it in items)
+
+
+def test_admin_outbound_emails_refuses_non_admin(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=700, login="contribU", role="contributor")
+        sign_in_as(
+            client, user_id=700, gitea_login="contribU",
+            display_name="Contrib U", role="contributor",
+        )
+        r = client.get("/api/admin/outbound-emails")
+        assert r.status_code == 403
+
+
+# ---------------------------------------------------------------------------
+# v0.18.0 Slice 5: bounce correlation
+# ---------------------------------------------------------------------------
+
+
+def test_bounce_with_message_id_marks_outbound_row_bounced(app_with_fake_gitea):
+    """When the bounce body includes the original `message_id`, the
+    framework looks it up in outbound_emails and stamps
+    status='bounced' on the matching row. The hard-bounce ->
+    global-opt-out logic still fires."""
+    from fastapi.testclient import TestClient
+    from app import db, email as email_mod
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=800, login="bouncey", role="contributor")
+        db.conn().execute("UPDATE users SET email = 'bouncey@ex.co' WHERE id = 800")
+
+        # Send something to bouncey to land an outbound_emails row.
+        email_mod.reset_sent_envelopes()
+        client.post("/auth/otc/request", json={"email": "bouncey@ex.co"})
+        row = db.conn().execute(
+            "SELECT id, message_id, status FROM outbound_emails "
+            "WHERE to_address = 'bouncey@ex.co'"
+        ).fetchone()
+        assert row is not None
+        original_id = row["id"]
+        message_id = row["message_id"]
+        assert row["status"] == "deferred"  # pre-bounce baseline
+
+        # Bounce comes in carrying that message_id.
+        r = client.post(
+            "/api/webhooks/email-bounce",
+            json={
+                "email": "bouncey@ex.co",
+                "kind": "hard",
+                "message_id": message_id,
+            },
+        )
+        assert r.status_code == 200
+        body = r.json()
+        assert body["matched"] is True
+        assert body["correlated_id"] == original_id
+
+        # Audit row stamped.
+        post = db.conn().execute(
+            "SELECT status, error FROM outbound_emails WHERE id = ?",
+            (original_id,),
+        ).fetchone()
+        assert post["status"] == "bounced"
+        assert "bounce (hard)" in (post["error"] or "")
+
+        # Hard-bounce global opt-out still fires.
+        urow = db.conn().execute(
+            "SELECT email_opt_out_all FROM users WHERE id = 800"
+        ).fetchone()
+        assert urow["email_opt_out_all"] == 1
+
+
+def test_bounce_with_unknown_message_id_does_not_crash(app_with_fake_gitea):
+    """A message_id the framework doesn't recognize logs but does
+    NOT 5xx — bounce providers replay old bounces, and the
+    framework can't refuse just because the row was pruned."""
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        r = client.post(
+            "/api/webhooks/email-bounce",
+            json={
+                "email": "nobody@ex.co",
+                "kind": "hard",
+                "message_id": "<not-in-our-db@ex.co>",
+            },
+        )
+        assert r.status_code == 200
+        assert r.json()["correlated_id"] is None
+
+
+def test_bounce_without_message_id_still_flips_opt_out(app_with_fake_gitea):
+    """Backward compat: providers that don't surface Message-ID
+    still get the legacy v1 behavior — match by email + flip the
+    global opt-out."""
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=801, login="legacybounce", role="contributor")
+        db.conn().execute("UPDATE users SET email = 'legacy@ex.co' WHERE id = 801")
+
+        r = client.post(
+            "/api/webhooks/email-bounce",
+            json={"email": "legacy@ex.co", "kind": "hard"},
+        )
+        assert r.status_code == 200
+        body = r.json()
+        assert body["matched"] is True
+        assert body["correlated_id"] is None
+
+        urow = db.conn().execute(
+            "SELECT email_opt_out_all FROM users WHERE id = 801"
+        ).fetchone()
+        assert urow["email_opt_out_all"] == 1
+
+
+def test_bounced_rows_show_in_admin_endpoint(app_with_fake_gitea):
+    """The admin endpoint surfaces bounced rows alongside the rest;
+    filtering by `status=bounced` isolates them."""
+    from fastapi.testclient import TestClient
+    from app import db, email as email_mod
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=802, login="adminB", role="admin")
+        sign_in_as(
+            client, user_id=802, gitea_login="adminB",
+            display_name="Admin B", role="admin", email="adminb@test",
+        )
+        email_mod.reset_sent_envelopes()
+        client.post("/auth/otc/request", json={"email": "willbounce@ex.co"})
+        row = db.conn().execute(
+            "SELECT message_id FROM outbound_emails WHERE to_address = 'willbounce@ex.co'"
+        ).fetchone()
+        client.post(
+            "/api/webhooks/email-bounce",
+            json={"email": "willbounce@ex.co", "kind": "hard", "message_id": row["message_id"]},
+        )
+
+        r = client.get("/api/admin/outbound-emails?status=bounced")
+        assert r.status_code == 200
+        items = r.json()["items"]
+        assert items
+        assert all(it["status"] == "bounced" for it in items)
+        assert any(it["to_address"] == "willbounce@ex.co" for it in items)

backend/tests/test_pr_flow_vertical.py

@@ -21,6 +21,7 @@ import pytest
 from test_propose_vertical import (  # noqa: F401
     FakeGitea,
     app_with_fake_gitea,
+    grant_rfc_collaborator,
     provision_user_row,
     sign_in_as,
     tmp_env,
@@ -140,6 +141,9 @@ def test_get_pr_returns_three_column_payload(app_with_fake_gitea):
         provision_user_row(user_id=3, login="bob", role="contributor")
         seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
         # Bob is the non-arbiter contributor — alice is seeded as an RFC owner.
+        # v0.16.0 (item #12): bob needs an accepted per-RFC contributor
+        # invitation to cut branches and open PRs on alice's RFC.
+        grant_rfc_collaborator(user_id=3, rfc_slug="ohm", role_in_rfc="contributor")
         sign_in_as(client, user_id=3, gitea_login="bob", display_name="Bob", role="contributor")
         branch, _ = _cut_branch_and_accept_change(
             client, fake, slug="ohm",
@@ -292,6 +296,9 @@ def test_merge_by_arbiter_advances_main_and_marks_pr_merged(app_with_fake_gitea)
         provision_user_row(user_id=1, login="ben", role="owner")
         seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
         # Bob is neither owner nor arbiter — the non-merge baseline.
+        # v0.16.0 (item #12): bob still needs an accepted contributor
+        # invitation to cut the branch + open the PR.
+        grant_rfc_collaborator(user_id=3, rfc_slug="ohm", role_in_rfc="contributor")
         sign_in_as(client, user_id=3, gitea_login="bob", display_name="Bob", role="contributor")
         branch, _ = _cut_branch_and_accept_change(
             client, fake, slug="ohm",
@@ -364,6 +371,10 @@ def test_resolution_branch_replays_clean_and_supersedes_on_merge(app_with_fake_g
         provision_user_row(user_id=3, login="bob", role="contributor")
         provision_user_row(user_id=1, login="ben", role="owner")
         seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+        # v0.16.0 (item #12): bob (a non-owner contributor) needs an
+        # accepted per-RFC invitation to cut a branch on alice's RFC.
+        # Alice is the seeded RFC owner so she doesn't need one.
+        grant_rfc_collaborator(user_id=3, rfc_slug="ohm", role_in_rfc="contributor")
 
         # Alice cuts a branch and accepts a change on it.
         sign_in_as(client, user_id=2, gitea_login="alice", display_name="Alice", role="contributor")

backend/tests/test_propose_vertical.py

@@ -395,6 +395,28 @@ def provision_user_row(*, user_id: int, login: str, role: str) -> None:
     )
 
 
+def grant_rfc_collaborator(*, user_id: int, rfc_slug: str, role_in_rfc: str = "contributor") -> None:
+    """v0.16.0 / item #12 test seam: directly insert an accepted-
+    invitation collaborator row so a non-owner contributor can pass
+    the per-RFC write gate without going through the email round-trip.
+
+    Equivalent in effect to the invitation→accept dance the production
+    code drives; lets v0.5.0/v0.6.0/v0.8.0 era tests preserve their
+    "alice owns OHM, bob contributes" shape without rewriting the
+    setup. The invitation_id is left NULL — collaborators minted via
+    a direct admin gesture (a §19.2 candidate) carry the same shape.
+    """
+    from app import db
+    db.conn().execute(
+        """
+        INSERT OR REPLACE INTO rfc_collaborators
+            (rfc_slug, user_id, role_in_rfc, invitation_id)
+        VALUES (?, ?, ?, NULL)
+        """,
+        (rfc_slug, user_id, role_in_rfc),
+    )
+
+
 # ---------------------------------------------------------------------------
 # Fixtures
 # ---------------------------------------------------------------------------
@@ -416,7 +438,11 @@ def tmp_env(monkeypatch):
         "SECRET_KEY": "test-secret-key-for-cookies",
         "DATABASE_PATH": str(db_path),
         "OWNER_GITEA_LOGIN": "ben",
-        "GITEA_WEBHOOK_SECRET": "",
+        # v0.18.0: `GITEA_WEBHOOK_SECRET` is now mandatory at startup
+        # per the email + webhook hygiene proposal. Tests bind a fake
+        # value so the framework boots; tests that want to exercise
+        # the dev-bypass path monkeypatch `RFC_APP_INSECURE_WEBHOOKS=1`.
+        "GITEA_WEBHOOK_SECRET": "test-webhook-secret-for-signature-verification",
         "ENABLED_MODELS": "claude",
     }
     for k, v in env.items():

backend/tests/test_rfc_invitations_vertical.py

@@ -0,0 +1,658 @@
+"""End-to-end integration tests for v0.16.0's owner-only invite for
+per-RFC PR or PR-less discussion (roadmap item #12, §6 / §10).
+
+The release lands a per-RFC membership layer:
+
+  * `rfc_invitations` — issued by the RFC's owner, addressed to an
+    email, granting one of two roles ('contributor' or 'discussant').
+  * `rfc_collaborators` — the accepted-invitation substrate; the
+    table the per-RFC write gate consults.
+
+The tests prove:
+
+  * Only the RFC's owner (or a platform admin/owner) can invite —
+    a platform-granted but non-owner user gets 403.
+  * Creating an invitation lands a row, mints a token, and queues
+    an envelope on the SMTP buffer.
+  * Re-inviting the same (email, role) on the same RFC returns 409.
+  * The accept endpoint requires the accepting user's email to match
+    the invitee_email (case-insensitive).
+  * Acceptance lands a rfc_collaborators row and flips the
+    invitation to 'accepted'.
+  * Re-accepting the same invitation is idempotent (200, changed=false).
+  * An expired invitation refuses 409 even if the row's column status
+    is still 'pending'.
+  * A revoked invitation refuses 409.
+  * The owner's listing carries pending + accepted in one response.
+  * The per-RFC discussion-write gate refuses a non-invited
+    platform-granted user 403 (was previously 200 before v0.16.0).
+  * The same gate admits a user who holds an accepted 'discussant'
+    invitation.
+  * The same gate admits a user who holds an accepted 'contributor'
+    invitation (contributor strictly includes discussion).
+  * The platform admin/owner is admitted regardless of per-RFC
+    membership (the platform-level capability path).
+  * The /api/admin/users listing carries `rfc_invitations` per-user
+    after an acceptance — the §17 admin surface hook.
+"""
+from __future__ import annotations
+
+# Reuse fixtures and helpers from the propose / RFC-view harnesses.
+from test_propose_vertical import (  # noqa: F401 — fixtures land via import
+    FakeGitea,
+    app_with_fake_gitea,
+    provision_user_row,
+    sign_in_as,
+    tmp_env,
+)
+from test_rfc_view_vertical import seed_active_rfc, SEED_BODY
+
+
+def _reset_outbound():
+    from app import email as email_mod
+    email_mod.reset_sent_envelopes()
+
+
+def _invitation_envelopes(to_address: str | None = None) -> list[dict]:
+    """Pluck v0.16.0 invitation envelopes out of the shared _SENT buffer.
+    Same access pattern as the OTC tests use for `kind='otc'`."""
+    from app import email as email_mod
+    out = []
+    for env in email_mod.sent_envelopes():
+        if env.get("kind") != "rfc_invitation":
+            continue
+        if to_address is not None and env["to"] != to_address:
+            continue
+        out.append(env)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Create / list / revoke (owner-side)
+# ---------------------------------------------------------------------------
+
+
+def test_owner_can_invite_creates_row_and_sends_email(app_with_fake_gitea):
+    """The end-to-end create gesture: RFC owner posts an invitation,
+    a row lands, the token comes back in the response, and an
+    `rfc_invitation`-kind envelope hits the SMTP buffer."""
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        # The frontmatter owner of the seeded RFC is "alice" (per
+        # seed_active_rfc's default), so we sign in as that user.
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+        sign_in_as(
+            client, user_id=1, gitea_login="alice",
+            display_name="Alice", role="contributor",
+        )
+
+        r = client.post(
+            "/api/rfcs/ohm/invitations",
+            json={"invitee_email": "newperson@example.com", "role_in_rfc": "contributor"},
+        )
+        assert r.status_code == 200, r.text
+        body = r.json()
+        assert body["rfc_slug"] == "ohm"
+        assert body["invitee_email"] == "newperson@example.com"
+        assert body["role_in_rfc"] == "contributor"
+        assert body["status"] == "pending"
+        assert body["token"] and len(body["token"]) > 16
+
+        # Row landed.
+        row = db.conn().execute(
+            "SELECT * FROM rfc_invitations WHERE id = ?", (body["id"],),
+        ).fetchone()
+        assert row["rfc_slug"] == "ohm"
+        assert row["invitee_email"] == "newperson@example.com"
+        assert row["inviter_user_id"] == 1
+        assert row["status"] == "pending"
+
+        # Email envelope went out.
+        envs = _invitation_envelopes("newperson@example.com")
+        assert len(envs) == 1
+        assert "OHM" in envs[0]["subject"]
+        assert body["token"] in envs[0]["body"]
+
+
+def test_non_owner_cannot_invite(app_with_fake_gitea):
+    """A platform-granted user who isn't in the RFC's frontmatter
+    owners list cannot invite — 403. Distinct from the
+    require_contributor gate (which would be 401 for anonymous)."""
+    from fastapi.testclient import TestClient
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        # alice is the RFC owner per the seed; bob is a regular
+        # platform-granted contributor with no per-RFC role.
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        provision_user_row(user_id=2, login="bob", role="contributor")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+        sign_in_as(
+            client, user_id=2, gitea_login="bob",
+            display_name="Bob", role="contributor",
+        )
+        r = client.post(
+            "/api/rfcs/ohm/invitations",
+            json={"invitee_email": "ignored@example.com", "role_in_rfc": "discussant"},
+        )
+        assert r.status_code == 403
+
+
+def test_platform_admin_can_invite_to_any_rfc(app_with_fake_gitea):
+    """Per §6.1 the platform admin/owner role carries the maximal
+    per-RFC capability, so admins can invite on any RFC even if
+    they're not in its owners list."""
+    from fastapi.testclient import TestClient
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        provision_user_row(user_id=99, login="adminzero", role="admin")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+        sign_in_as(
+            client, user_id=99, gitea_login="adminzero",
+            display_name="Admin Zero", role="admin",
+        )
+        r = client.post(
+            "/api/rfcs/ohm/invitations",
+            json={"invitee_email": "another@example.com", "role_in_rfc": "discussant"},
+        )
+        assert r.status_code == 200, r.text
+
+
+def test_anonymous_cannot_invite(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+        r = client.post(
+            "/api/rfcs/ohm/invitations",
+            json={"invitee_email": "x@example.com", "role_in_rfc": "discussant"},
+        )
+        assert r.status_code == 401
+
+
+def test_re_invite_same_email_and_role_returns_409(app_with_fake_gitea):
+    """Refuse a duplicate pending invitation for the same (email, role)
+    on the same RFC. A different role on the same email is allowed
+    (the owner may want to upgrade discussant → contributor)."""
+    from fastapi.testclient import TestClient
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+        sign_in_as(
+            client, user_id=1, gitea_login="alice",
+            display_name="Alice", role="contributor",
+        )
+
+        r1 = client.post(
+            "/api/rfcs/ohm/invitations",
+            json={"invitee_email": "dup@example.com", "role_in_rfc": "discussant"},
+        )
+        assert r1.status_code == 200
+        r2 = client.post(
+            "/api/rfcs/ohm/invitations",
+            json={"invitee_email": "dup@example.com", "role_in_rfc": "discussant"},
+        )
+        assert r2.status_code == 409
+
+        # Same email, different role is allowed.
+        r3 = client.post(
+            "/api/rfcs/ohm/invitations",
+            json={"invitee_email": "dup@example.com", "role_in_rfc": "contributor"},
+        )
+        assert r3.status_code == 200
+
+
+def test_owner_can_list_invitations(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+        sign_in_as(
+            client, user_id=1, gitea_login="alice",
+            display_name="Alice", role="contributor",
+        )
+
+        client.post("/api/rfcs/ohm/invitations",
+                    json={"invitee_email": "a@example.com", "role_in_rfc": "discussant"})
+        client.post("/api/rfcs/ohm/invitations",
+                    json={"invitee_email": "b@example.com", "role_in_rfc": "contributor"})
+
+        r = client.get("/api/rfcs/ohm/invitations")
+        assert r.status_code == 200, r.text
+        items = r.json()["items"]
+        emails = sorted(i["invitee_email"] for i in items)
+        assert emails == ["a@example.com", "b@example.com"]
+        assert all(i["status"] == "pending" for i in items)
+        # The inviter is named.
+        assert all(i["inviter_login"] == "alice" for i in items)
+
+
+def test_revoke_pending_invitation_works_already_accepted_refuses(app_with_fake_gitea):
+    """Revoke flips a pending invitation to 'revoked'. An already-
+    accepted invitation refuses 409 — accepted membership is removed
+    via a different (future) surface; the v0.16.0 revoke only lifts
+    the pending link."""
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+        sign_in_as(
+            client, user_id=1, gitea_login="alice",
+            display_name="Alice", role="contributor",
+        )
+
+        r = client.post(
+            "/api/rfcs/ohm/invitations",
+            json={"invitee_email": "revokee@example.com", "role_in_rfc": "discussant"},
+        )
+        invitation_id = r.json()["id"]
+
+        r = client.post(f"/api/rfcs/ohm/invitations/{invitation_id}/revoke")
+        assert r.status_code == 200
+        assert r.json()["status"] == "revoked"
+
+        # Re-revoke refuses 409.
+        r2 = client.post(f"/api/rfcs/ohm/invitations/{invitation_id}/revoke")
+        assert r2.status_code == 409
+
+        row = db.conn().execute(
+            "SELECT status FROM rfc_invitations WHERE id = ?", (invitation_id,),
+        ).fetchone()
+        assert row["status"] == "revoked"
+
+
+# ---------------------------------------------------------------------------
+# Accept (invitee-side)
+# ---------------------------------------------------------------------------
+
+
+def test_accept_invitation_lands_collaborator_row(app_with_fake_gitea):
+    """The end-to-end accept gesture: the invitee signs in, posts the
+    token, and an rfc_collaborators row lands at the issued role."""
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        # provision_user_row sets the email to "<login>@test", so the
+        # invitee row we'll create needs the same email shape.
+        provision_user_row(user_id=2, login="newbie", role="contributor")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+
+        # alice (owner) invites newbie@test.
+        sign_in_as(
+            client, user_id=1, gitea_login="alice",
+            display_name="Alice", role="contributor",
+        )
+        r = client.post(
+            "/api/rfcs/ohm/invitations",
+            json={"invitee_email": "newbie@test", "role_in_rfc": "contributor"},
+        )
+        assert r.status_code == 200, r.text
+        token = r.json()["token"]
+
+        # Switch to newbie, accept.
+        sign_in_as(
+            client, user_id=2, gitea_login="newbie",
+            display_name="Newbie", role="contributor",
+            email="newbie@test",
+        )
+        r = client.post("/api/invitations/accept", json={"token": token})
+        assert r.status_code == 200, r.text
+        body = r.json()
+        assert body["ok"] is True
+        assert body["changed"] is True
+        assert body["rfc_slug"] == "ohm"
+        assert body["role_in_rfc"] == "contributor"
+
+        # Collaborator row landed; invitation flipped.
+        collab = db.conn().execute(
+            "SELECT role_in_rfc FROM rfc_collaborators WHERE rfc_slug = 'ohm' AND user_id = 2",
+        ).fetchone()
+        assert collab is not None
+        assert collab["role_in_rfc"] == "contributor"
+
+        inv = db.conn().execute(
+            "SELECT status, accepted_by_user_id FROM rfc_invitations WHERE token = ?",
+            (token,),
+        ).fetchone()
+        assert inv["status"] == "accepted"
+        assert inv["accepted_by_user_id"] == 2
+
+
+def test_accept_refuses_when_email_does_not_match(app_with_fake_gitea):
+    """The accepting user's email must match the invitation's
+    invitee_email (case-insensitive)."""
+    from fastapi.testclient import TestClient
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        provision_user_row(user_id=2, login="mallory", role="contributor")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+
+        sign_in_as(client, user_id=1, gitea_login="alice",
+                   display_name="Alice", role="contributor")
+        r = client.post(
+            "/api/rfcs/ohm/invitations",
+            json={"invitee_email": "intended@example.com", "role_in_rfc": "discussant"},
+        )
+        token = r.json()["token"]
+
+        # mallory's email is "mallory@test", not "intended@example.com".
+        sign_in_as(client, user_id=2, gitea_login="mallory",
+                   display_name="Mallory", role="contributor",
+                   email="mallory@test")
+        r = client.post("/api/invitations/accept", json={"token": token})
+        assert r.status_code == 403
+
+
+def test_accept_refuses_revoked_invitation(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        provision_user_row(user_id=2, login="newbie", role="contributor")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+
+        sign_in_as(client, user_id=1, gitea_login="alice",
+                   display_name="Alice", role="contributor")
+        r = client.post(
+            "/api/rfcs/ohm/invitations",
+            json={"invitee_email": "newbie@test", "role_in_rfc": "discussant"},
+        )
+        invitation_id = r.json()["id"]
+        token = r.json()["token"]
+
+        client.post(f"/api/rfcs/ohm/invitations/{invitation_id}/revoke")
+
+        sign_in_as(client, user_id=2, gitea_login="newbie",
+                   display_name="Newbie", role="contributor",
+                   email="newbie@test")
+        r = client.post("/api/invitations/accept", json={"token": token})
+        assert r.status_code == 409
+
+
+def test_accept_refuses_expired_invitation(app_with_fake_gitea):
+    """An invitation past its `expires_at` is refused 409 even if
+    the row's column status is still 'pending'. We backdate the
+    expires_at directly to model the elapsed-window state."""
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        provision_user_row(user_id=2, login="newbie", role="contributor")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+
+        sign_in_as(client, user_id=1, gitea_login="alice",
+                   display_name="Alice", role="contributor")
+        r = client.post(
+            "/api/rfcs/ohm/invitations",
+            json={"invitee_email": "newbie@test", "role_in_rfc": "discussant"},
+        )
+        token = r.json()["token"]
+        invitation_id = r.json()["id"]
+
+        # Backdate.
+        db.conn().execute(
+            "UPDATE rfc_invitations SET expires_at = datetime('now', '-1 day') WHERE id = ?",
+            (invitation_id,),
+        )
+
+        sign_in_as(client, user_id=2, gitea_login="newbie",
+                   display_name="Newbie", role="contributor",
+                   email="newbie@test")
+        r = client.post("/api/invitations/accept", json={"token": token})
+        assert r.status_code == 409
+
+
+def test_accept_is_idempotent_on_re_accept(app_with_fake_gitea):
+    """Re-accepting the same already-accepted invitation reads as a
+    200 no-op with `changed=false`. The collaborator row is unchanged."""
+    from fastapi.testclient import TestClient
+    from app import db
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        provision_user_row(user_id=2, login="newbie", role="contributor")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+
+        sign_in_as(client, user_id=1, gitea_login="alice",
+                   display_name="Alice", role="contributor")
+        r = client.post(
+            "/api/rfcs/ohm/invitations",
+            json={"invitee_email": "newbie@test", "role_in_rfc": "discussant"},
+        )
+        token = r.json()["token"]
+
+        sign_in_as(client, user_id=2, gitea_login="newbie",
+                   display_name="Newbie", role="contributor",
+                   email="newbie@test")
+        r1 = client.post("/api/invitations/accept", json={"token": token})
+        assert r1.status_code == 200
+        assert r1.json()["changed"] is True
+
+        r2 = client.post("/api/invitations/accept", json={"token": token})
+        assert r2.status_code == 200
+        assert r2.json()["changed"] is False
+
+        # Still exactly one collaborator row.
+        rows = db.conn().execute(
+            "SELECT COUNT(*) AS n FROM rfc_collaborators WHERE rfc_slug = 'ohm' AND user_id = 2"
+        ).fetchone()
+        assert rows["n"] == 1
+
+
+# ---------------------------------------------------------------------------
+# Discussion-write gate enforcement
+# ---------------------------------------------------------------------------
+
+
+def test_non_invited_user_cannot_post_to_discussion(app_with_fake_gitea):
+    """v0.16.0 narrows the discussion-write gate: a platform-granted
+    user with no per-RFC role gets 403 when posting to the
+    discussion. (v0.6.0 left the gate at require_contributor only;
+    item #12 layers can_discuss_rfc on top.)"""
+    from fastapi.testclient import TestClient
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        provision_user_row(user_id=2, login="bob", role="contributor")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+
+        # bob is platform-granted but not in OHM's owners list and has
+        # no invitation. The thread-create surface refuses 403.
+        sign_in_as(client, user_id=2, gitea_login="bob",
+                   display_name="Bob", role="contributor")
+        r = client.post(
+            "/api/rfcs/ohm/discussion/threads",
+            json={"label": "Question", "message": "Should I be allowed?"},
+        )
+        assert r.status_code == 403
+
+
+def test_invited_discussant_can_post_to_discussion(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        provision_user_row(user_id=2, login="newbie", role="contributor")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+
+        # alice invites newbie as a discussant.
+        sign_in_as(client, user_id=1, gitea_login="alice",
+                   display_name="Alice", role="contributor")
+        r = client.post(
+            "/api/rfcs/ohm/invitations",
+            json={"invitee_email": "newbie@test", "role_in_rfc": "discussant"},
+        )
+        token = r.json()["token"]
+
+        # newbie accepts.
+        sign_in_as(client, user_id=2, gitea_login="newbie",
+                   display_name="Newbie", role="contributor",
+                   email="newbie@test")
+        client.post("/api/invitations/accept", json={"token": token})
+
+        # newbie can now post to the discussion.
+        r = client.post(
+            "/api/rfcs/ohm/discussion/threads",
+            json={"label": "Question", "message": "Now I can speak."},
+        )
+        assert r.status_code == 200, r.text
+
+
+def test_contributor_role_includes_discussion(app_with_fake_gitea):
+    """A 'contributor' per-RFC role strictly includes discussion
+    permission — accepting a contributor invitation admits the user
+    to the discussion endpoint too."""
+    from fastapi.testclient import TestClient
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        provision_user_row(user_id=2, login="newbie", role="contributor")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+
+        sign_in_as(client, user_id=1, gitea_login="alice",
+                   display_name="Alice", role="contributor")
+        r = client.post(
+            "/api/rfcs/ohm/invitations",
+            json={"invitee_email": "newbie@test", "role_in_rfc": "contributor"},
+        )
+        token = r.json()["token"]
+
+        sign_in_as(client, user_id=2, gitea_login="newbie",
+                   display_name="Newbie", role="contributor",
+                   email="newbie@test")
+        client.post("/api/invitations/accept", json={"token": token})
+
+        r = client.post(
+            "/api/rfcs/ohm/discussion/threads",
+            json={"label": "Q", "message": "Hello."},
+        )
+        assert r.status_code == 200
+
+
+def test_platform_admin_can_post_to_discussion_without_invitation(app_with_fake_gitea):
+    """Per §6.1 / item #12's permission shape: platform admins/owners
+    can write to any RFC's discussion regardless of per-RFC
+    membership."""
+    from fastapi.testclient import TestClient
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        provision_user_row(user_id=99, login="adminzero", role="admin")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+
+        sign_in_as(client, user_id=99, gitea_login="adminzero",
+                   display_name="Admin Zero", role="admin")
+        r = client.post(
+            "/api/rfcs/ohm/discussion/threads",
+            json={"label": "Admin chime", "message": "Drive-by from admin."},
+        )
+        assert r.status_code == 200
+
+
+def test_rfc_owner_can_post_to_discussion(app_with_fake_gitea):
+    """The frontmatter RFC owner is admitted by virtue of being on
+    the owners list — they don't need to invite themselves."""
+    from fastapi.testclient import TestClient
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+        sign_in_as(client, user_id=1, gitea_login="alice",
+                   display_name="Alice", role="contributor")
+        r = client.post(
+            "/api/rfcs/ohm/discussion/threads",
+            json={"label": "Owner thought", "message": "Kicking off the conversation."},
+        )
+        assert r.status_code == 200
+
+
+# ---------------------------------------------------------------------------
+# Admin-page hook (additive on /api/admin/users)
+# ---------------------------------------------------------------------------
+
+
+def test_admin_users_listing_surfaces_per_rfc_invitations(app_with_fake_gitea):
+    """v0.16.0 hook into the v0.9.0 admin user-management surface:
+    each user row carries an `rfc_invitations` array listing the
+    per-RFC roles they hold. Empty array for users without any."""
+    from fastapi.testclient import TestClient
+
+    app, fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        provision_user_row(user_id=1, login="alice", role="contributor")
+        provision_user_row(user_id=2, login="newbie", role="contributor")
+        provision_user_row(user_id=99, login="adminzero", role="admin")
+        seed_active_rfc(fake, slug="ohm", title="OHM", body=SEED_BODY)
+
+        # alice invites newbie; newbie accepts.
+        sign_in_as(client, user_id=1, gitea_login="alice",
+                   display_name="Alice", role="contributor")
+        r = client.post(
+            "/api/rfcs/ohm/invitations",
+            json={"invitee_email": "newbie@test", "role_in_rfc": "contributor"},
+        )
+        token = r.json()["token"]
+
+        sign_in_as(client, user_id=2, gitea_login="newbie",
+                   display_name="Newbie", role="contributor",
+                   email="newbie@test")
+        client.post("/api/invitations/accept", json={"token": token})
+
+        # Admin lists.
+        sign_in_as(client, user_id=99, gitea_login="adminzero",
+                   display_name="Admin Zero", role="admin")
+        r = client.get("/api/admin/users")
+        assert r.status_code == 200
+        items = r.json()["items"]
+        newbie_row = next(i for i in items if i["gitea_login"] == "newbie")
+        assert isinstance(newbie_row["rfc_invitations"], list)
+        assert len(newbie_row["rfc_invitations"]) == 1
+        invite = newbie_row["rfc_invitations"][0]
+        assert invite["rfc_slug"] == "ohm"
+        assert invite["role_in_rfc"] == "contributor"
+        assert invite["inviter_login"] == "alice"
+
+        # Users with no invitations carry an empty array, not null.
+        alice_row = next(i for i in items if i["gitea_login"] == "alice")
+        assert alice_row["rfc_invitations"] == []

backend/tests/test_turnstile_vertical.py

@@ -0,0 +1,220 @@
+"""End-to-end integration tests for the v0.12.0 CloudFlare Turnstile
+gate on `/auth/otc/request` (§6.2 / roadmap item #10).
+
+The release gates the OTC request endpoint behind a one-step
+browser-side Turnstile challenge before the bcrypt hash + SMTP send.
+The tests prove:
+
+  * Happy path: with the secret set, a valid token admits the request
+    and the OTC envelope lands.
+  * Failure path: with the secret set, a token siteverify rejects
+    refuses the request with 400 and produces no envelope.
+  * Missing-token: with the secret set, a request without a token
+    refuses with 400.
+  * Missing-secret-soft: with the secret unset AND
+    `TURNSTILE_REQUIRED=false` (the v0.12.0 default), the request
+    admits — this is the dev / "operator hasn't wired it yet" path.
+  * Missing-secret-hard: with the secret unset AND
+    `TURNSTILE_REQUIRED=true`, the request refuses with 500
+    "auth misconfigured" — the production fail-closed path once
+    the operator has flipped the policy.
+
+The Turnstile siteverify call is mocked at the `httpx.post` boundary
+inside `app.turnstile` so no real keys are needed and no real
+CloudFlare call is made. The Gitea fakes from `test_propose_vertical`
+remain in scope so the rest of the app boots cleanly.
+"""
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from test_propose_vertical import (  # noqa: F401
+    FakeGitea,
+    app_with_fake_gitea,
+    tmp_env,
+)
+
+
+def _reset_outbound():
+    from app import email as email_mod
+    email_mod.reset_sent_envelopes()
+
+
+def _outbound_otc_envelopes(to_address: str | None = None) -> list[dict]:
+    from app import email as email_mod
+    out = []
+    for env in email_mod.sent_envelopes():
+        if env.get("kind") != "otc":
+            continue
+        if to_address is not None and env["to"] != to_address:
+            continue
+        out.append(env)
+    return out
+
+
+def _patch_siteverify(monkeypatch, *, success: bool, error_codes: list[str] | None = None):
+    """Replace `httpx.post` inside `app.turnstile` with a stub that
+    returns the requested success shape. The stub does not touch the
+    real CloudFlare endpoint and never sees a real secret.
+    """
+    captured = {}
+
+    def fake_post(url, *, data=None, timeout=None, **kwargs):
+        captured["url"] = url
+        captured["data"] = data
+        body = {"success": bool(success)}
+        if error_codes is not None:
+            body["error-codes"] = error_codes
+        return SimpleNamespace(json=lambda: body)
+
+    from app import turnstile as turnstile_mod
+    monkeypatch.setattr(turnstile_mod.httpx, "post", fake_post)
+    return captured
+
+
+# ---------------------------------------------------------------------------
+# Happy path: secret set, token valid → admit + OTC envelope lands
+# ---------------------------------------------------------------------------
+
+
+def test_otc_request_admits_when_turnstile_token_is_valid(app_with_fake_gitea, monkeypatch):
+    from fastapi.testclient import TestClient
+
+    monkeypatch.setenv("CLOUDFLARE_TURNSTILE_SECRET", "test-secret-not-real")
+    monkeypatch.setenv("TURNSTILE_REQUIRED", "true")
+    captured = _patch_siteverify(monkeypatch, success=True)
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        r = client.post(
+            "/auth/otc/request",
+            json={"email": "alice@example.com", "turnstile_token": "fake-token-abc"},
+        )
+        assert r.status_code == 200, r.text
+        # The siteverify call was made with the secret + the token we sent.
+        assert captured["data"]["secret"] == "test-secret-not-real"
+        assert captured["data"]["response"] == "fake-token-abc"
+        # And the OTC dispatch ran — exactly one envelope to the address.
+        envs = _outbound_otc_envelopes("alice@example.com")
+        assert len(envs) == 1
+
+
+# ---------------------------------------------------------------------------
+# Failure path: secret set, siteverify says success=false → 400 + no envelope
+# ---------------------------------------------------------------------------
+
+
+def test_otc_request_refuses_when_turnstile_siteverify_fails(app_with_fake_gitea, monkeypatch):
+    from fastapi.testclient import TestClient
+
+    monkeypatch.setenv("CLOUDFLARE_TURNSTILE_SECRET", "test-secret-not-real")
+    monkeypatch.setenv("TURNSTILE_REQUIRED", "true")
+    _patch_siteverify(monkeypatch, success=False, error_codes=["invalid-input-response"])
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        r = client.post(
+            "/auth/otc/request",
+            json={"email": "alice@example.com", "turnstile_token": "fake-bad-token"},
+        )
+        assert r.status_code == 400, r.text
+        # The OTC bcrypt + SMTP path did not run — no envelope was buffered.
+        assert _outbound_otc_envelopes("alice@example.com") == []
+
+
+# ---------------------------------------------------------------------------
+# Missing-token: secret set, no token → 400 + no envelope
+# ---------------------------------------------------------------------------
+
+
+def test_otc_request_refuses_when_turnstile_token_is_missing(app_with_fake_gitea, monkeypatch):
+    from fastapi.testclient import TestClient
+
+    monkeypatch.setenv("CLOUDFLARE_TURNSTILE_SECRET", "test-secret-not-real")
+    monkeypatch.setenv("TURNSTILE_REQUIRED", "true")
+    # Even though we patch httpx.post, the missing-token check fires
+    # before the siteverify call — so the patch is here only as a
+    # safety net in case the implementation regresses to making the
+    # network call anyway.
+    _patch_siteverify(monkeypatch, success=False)
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        r = client.post(
+            "/auth/otc/request",
+            json={"email": "alice@example.com"},  # no turnstile_token field at all
+        )
+        assert r.status_code == 400, r.text
+        assert _outbound_otc_envelopes("alice@example.com") == []
+
+
+# ---------------------------------------------------------------------------
+# Missing-secret-soft: no secret, TURNSTILE_REQUIRED=false (default) → admit
+# ---------------------------------------------------------------------------
+
+
+def test_otc_request_admits_when_secret_unset_and_not_required(app_with_fake_gitea, monkeypatch):
+    """v0.12.0 default: the operator has not yet wired the Turnstile
+    secret and has not enabled `TURNSTILE_REQUIRED`. The gate stays
+    open — this is the dev / test / pre-rollout path. Once the
+    operator confirms the secret is in place and flips
+    `TURNSTILE_REQUIRED=true`, missing-secret becomes fail-closed
+    (covered in test_otc_request_refuses_when_required_but_secret_unset).
+    """
+    from fastapi.testclient import TestClient
+
+    monkeypatch.delenv("CLOUDFLARE_TURNSTILE_SECRET", raising=False)
+    monkeypatch.delenv("TURNSTILE_REQUIRED", raising=False)
+    # The httpx.post inside turnstile must not be called in this path —
+    # patch it to a sentinel that explodes if it ever runs.
+    from app import turnstile as turnstile_mod
+
+    def must_not_be_called(*a, **kw):
+        raise AssertionError("siteverify should not run when no secret is configured")
+
+    monkeypatch.setattr(turnstile_mod.httpx, "post", must_not_be_called)
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        r = client.post(
+            "/auth/otc/request",
+            json={"email": "alice@example.com"},
+        )
+        assert r.status_code == 200, r.text
+        # The OTC path ran end-to-end — one envelope to the address.
+        assert len(_outbound_otc_envelopes("alice@example.com")) == 1
+
+
+# ---------------------------------------------------------------------------
+# Missing-secret-hard: no secret, TURNSTILE_REQUIRED=true → 500 "misconfigured"
+# ---------------------------------------------------------------------------
+
+
+def test_otc_request_refuses_when_required_but_secret_unset(app_with_fake_gitea, monkeypatch):
+    """Once the operator has flipped `TURNSTILE_REQUIRED=true` to lock
+    down production, a missing secret stops being a soft-fail and
+    becomes a fail-closed 500. This is the regression-detection shape
+    the §20.4 upgrade-steps MAY block calls out — flip the flag once
+    the secret is wired so a future config drift fails loudly instead
+    of silently disabling abuse defense.
+    """
+    from fastapi.testclient import TestClient
+
+    monkeypatch.delenv("CLOUDFLARE_TURNSTILE_SECRET", raising=False)
+    monkeypatch.setenv("TURNSTILE_REQUIRED", "true")
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        _reset_outbound()
+        r = client.post(
+            "/auth/otc/request",
+            json={"email": "alice@example.com", "turnstile_token": "doesnt-matter"},
+        )
+        assert r.status_code == 500, r.text
+        assert _outbound_otc_envelopes("alice@example.com") == []

backend/tests/test_webhooks_vertical.py

@@ -0,0 +1,205 @@
+"""End-to-end integration tests for the Gitea webhook receiver
+(v0.18.0 Slice 3 — webhook tightening per the email + webhook
+hygiene proposal).
+
+The release changes the receiver from "verifies the signature only
+when a secret is configured; silently accepts unsigned POSTs
+otherwise" to "requires the secret unless `RFC_APP_INSECURE_WEBHOOKS=1`
+is set as an explicit dev-bypass." The startup-time check lives in
+`config.load_config()`; the request-time check lives in
+`webhooks.receive`.
+
+These tests prove:
+
+  * The framework refuses to start when `GITEA_WEBHOOK_SECRET` is
+    empty and the dev-bypass is not set.
+  * The dev-bypass (`RFC_APP_INSECURE_WEBHOOKS=1`) lets the
+    framework boot with an empty secret AND lets webhook POSTs
+    land without signature verification (a loud-warning log line
+    surfaces, but the request is accepted).
+  * Default path (secret bound): a POST with a valid signature
+    lands; a POST with an invalid signature gets 401; a POST with
+    no signature gets 401.
+  * Unknown-repo POSTs surface in the log (the "stale Gitea hook"
+    case the proposal targets).
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import logging
+
+import pytest
+
+from test_propose_vertical import (  # noqa: F401
+    FakeGitea,
+    app_with_fake_gitea,
+    tmp_env,
+)
+
+
+# ---------------------------------------------------------------------------
+# Startup-time secret check (config.load_config)
+# ---------------------------------------------------------------------------
+
+
+def test_config_refuses_to_load_with_empty_secret_and_no_bypass(monkeypatch, tmp_path):
+    """The framework MUST refuse to start when `GITEA_WEBHOOK_SECRET`
+    is empty unless `RFC_APP_INSECURE_WEBHOOKS=1` is set. This is
+    the v0.18.0 startup-loud-failure shape — silent acceptance was
+    the bug."""
+    monkeypatch.setenv("GITEA_URL", "http://gitea.test")
+    monkeypatch.setenv("GITEA_BOT_USER", "rfc-bot")
+    monkeypatch.setenv("GITEA_BOT_TOKEN", "bot-token")
+    monkeypatch.setenv("GITEA_ORG", "wiggleverse")
+    monkeypatch.setenv("OAUTH_CLIENT_ID", "cid")
+    monkeypatch.setenv("OAUTH_CLIENT_SECRET", "csec")
+    monkeypatch.setenv("SECRET_KEY", "test-secret-key")
+    monkeypatch.setenv("DATABASE_PATH", str(tmp_path / "test.db"))
+    monkeypatch.setenv("GITEA_WEBHOOK_SECRET", "")
+    monkeypatch.delenv("RFC_APP_INSECURE_WEBHOOKS", raising=False)
+
+    from app.config import load_config
+    with pytest.raises(RuntimeError, match="GITEA_WEBHOOK_SECRET"):
+        load_config()
+
+
+def test_config_loads_with_empty_secret_when_bypass_is_set(monkeypatch, tmp_path):
+    """The explicit `RFC_APP_INSECURE_WEBHOOKS=1` opt-in lets the
+    framework boot with an empty webhook secret. This is the
+    local-dev escape hatch."""
+    monkeypatch.setenv("GITEA_URL", "http://gitea.test")
+    monkeypatch.setenv("GITEA_BOT_USER", "rfc-bot")
+    monkeypatch.setenv("GITEA_BOT_TOKEN", "bot-token")
+    monkeypatch.setenv("GITEA_ORG", "wiggleverse")
+    monkeypatch.setenv("OAUTH_CLIENT_ID", "cid")
+    monkeypatch.setenv("OAUTH_CLIENT_SECRET", "csec")
+    monkeypatch.setenv("SECRET_KEY", "test-secret-key")
+    monkeypatch.setenv("DATABASE_PATH", str(tmp_path / "test.db"))
+    monkeypatch.setenv("GITEA_WEBHOOK_SECRET", "")
+    monkeypatch.setenv("RFC_APP_INSECURE_WEBHOOKS", "1")
+
+    from app.config import load_config
+    cfg = load_config()  # MUST NOT raise
+    assert cfg.webhook_secret == ""
+
+
+def test_config_loads_with_secret_set(monkeypatch, tmp_path):
+    """Sanity: the happy path (secret bound, bypass not set) loads
+    cleanly."""
+    monkeypatch.setenv("GITEA_URL", "http://gitea.test")
+    monkeypatch.setenv("GITEA_BOT_USER", "rfc-bot")
+    monkeypatch.setenv("GITEA_BOT_TOKEN", "bot-token")
+    monkeypatch.setenv("GITEA_ORG", "wiggleverse")
+    monkeypatch.setenv("OAUTH_CLIENT_ID", "cid")
+    monkeypatch.setenv("OAUTH_CLIENT_SECRET", "csec")
+    monkeypatch.setenv("SECRET_KEY", "test-secret-key")
+    monkeypatch.setenv("DATABASE_PATH", str(tmp_path / "test.db"))
+    monkeypatch.setenv("GITEA_WEBHOOK_SECRET", "my-real-secret")
+    monkeypatch.delenv("RFC_APP_INSECURE_WEBHOOKS", raising=False)
+
+    from app.config import load_config
+    cfg = load_config()
+    assert cfg.webhook_secret == "my-real-secret"
+
+
+# ---------------------------------------------------------------------------
+# Request-time signature verification (webhooks.receive)
+#
+# The default `app_with_fake_gitea` fixture binds
+# `GITEA_WEBHOOK_SECRET=test-webhook-secret-for-signature-verification`,
+# so these tests exercise the production path.
+# ---------------------------------------------------------------------------
+
+
+_SECRET = "test-webhook-secret-for-signature-verification"
+
+
+def _sign(body: bytes) -> str:
+    return hmac.new(_SECRET.encode("utf-8"), body, hashlib.sha256).hexdigest()
+
+
+def test_webhook_post_with_valid_signature_accepted(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        body = json.dumps({"repository": {"full_name": "wiggleverse/meta"}}).encode()
+        sig = _sign(body)
+        r = client.post(
+            "/api/webhooks/gitea",
+            content=body,
+            headers={
+                "X-Gitea-Event": "push",
+                "X-Gitea-Signature": sig,
+                "Content-Type": "application/json",
+            },
+        )
+        assert r.status_code == 200, r.text
+
+
+def test_webhook_post_with_invalid_signature_refused_401(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        body = json.dumps({"repository": {"full_name": "wiggleverse/meta"}}).encode()
+        r = client.post(
+            "/api/webhooks/gitea",
+            content=body,
+            headers={
+                "X-Gitea-Event": "push",
+                "X-Gitea-Signature": "0" * 64,  # wrong signature
+                "Content-Type": "application/json",
+            },
+        )
+        assert r.status_code == 401
+
+
+def test_webhook_post_with_missing_signature_refused_401(app_with_fake_gitea):
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        body = json.dumps({"repository": {"full_name": "wiggleverse/meta"}}).encode()
+        r = client.post(
+            "/api/webhooks/gitea",
+            content=body,
+            headers={
+                "X-Gitea-Event": "push",
+                "Content-Type": "application/json",
+            },
+        )
+        assert r.status_code == 401
+
+
+# ---------------------------------------------------------------------------
+# Unknown-repo logging (the "stale hook on a fork" surface)
+# ---------------------------------------------------------------------------
+
+
+def test_webhook_unknown_repo_logs_at_info(app_with_fake_gitea, caplog):
+    """Per the proposal: a hook on a fork or a stale Gitea binding
+    used to silently 200-OK. v0.18.0 surfaces it as an INFO log."""
+    from fastapi.testclient import TestClient
+
+    app, _fake = app_with_fake_gitea
+    with TestClient(app) as client:
+        body = json.dumps({"repository": {"full_name": "someone-else/unrelated"}}).encode()
+        sig = _sign(body)
+        with caplog.at_level(logging.INFO, logger="app.webhooks"):
+            r = client.post(
+                "/api/webhooks/gitea",
+                content=body,
+                headers={
+                    "X-Gitea-Event": "push",
+                    "X-Gitea-Signature": sig,
+                    "Content-Type": "application/json",
+                },
+            )
+        assert r.status_code == 200  # the handler still 200s; surface is the log line
+        assert any(
+            "unknown repo" in rec.message and "someone-else/unrelated" in rec.message
+            for rec in caplog.records
+        ), f"expected unknown-repo log line; got: {[r.message for r in caplog.records]}"

frontend/.env.example

@@ -49,3 +49,39 @@ VITE_PRIVACY_POLICY_URL=
 # Examples:
 #   VITE_COOKIES_POLICY_URL=https://wiggleverse.org/cookies
 VITE_COOKIES_POLICY_URL=
+
+# v0.12.0 / roadmap item #10: CloudFlare Turnstile site key (public).
+# Provision a Turnstile site at dash.cloudflare.com → Turnstile → Add
+# site. The site key (this var) is embedded into the frontend bundle at
+# build time and rendered by the Turnstile widget on the /login email-
+# entry step. The secret key (private) lives in the backend env as
+# CLOUDFLARE_TURNSTILE_SECRET — see backend/.env.example. Leave unset
+# in dev to skip the widget; the backend's TURNSTILE_REQUIRED policy
+# decides what happens to a tokenless request.
+#
+# Examples:
+#   VITE_TURNSTILE_SITE_KEY=0x4AAAAAAA...
+VITE_TURNSTILE_SITE_KEY=
+
+# v0.15.0 / roadmap item #13: Amplitude project API key (public).
+# Embedded in the frontend bundle at build time and used by the
+# analytics wrapper (`frontend/src/lib/analytics.js`) — which loads
+# `@amplitude/unified` (Analytics + Session Replay) when the user
+# has granted analytics consent (v0.13.0 cookie banner). Provision
+# an Amplitude project at app.amplitude.com → Projects → New, copy
+# the API key.
+#
+# Public by design: Amplitude browser keys are bundle-embedded
+# (visible in dev tools), same nature as VITE_TURNSTILE_SITE_KEY
+# (also public; the truly-secret half of that Turnstile pair is
+# CLOUDFLARE_TURNSTILE_SECRET on the backend). For deployments
+# behind flotilla, bind via `flotilla overlay set <deployment>
+# VITE_AMPLITUDE_API_KEY=<key>` — NOT `flotilla secret set`. The
+# vendor's installation wizard shows the key inline as a literal
+# string in the init call, confirming the public framing. Leave
+# unset in dev; the wrapper logs one console warning and no-ops
+# (the app continues to work).
+#
+# Examples:
+#   VITE_AMPLITUDE_API_KEY=01234567890abcdef01234567890abcd
+VITE_AMPLITUDE_API_KEY=

frontend/package-lock.json

@@ -1,13 +1,14 @@
 {
   "name": "rfc-app-frontend",
-  "version": "0.9.0",
+  "version": "0.15.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "rfc-app-frontend",
-      "version": "0.9.0",
+      "version": "0.15.0",
       "dependencies": {
+        "@amplitude/unified": "^1.1.9",
         "@codemirror/commands": "^6.10.3",
         "@codemirror/lang-markdown": "^6.5.0",
         "@codemirror/language": "^6.12.3",
@@ -30,6 +31,360 @@
         "vite": "^8.0.12"
       }
     },
+    "node_modules/@amplitude/analytics-browser": {
+      "version": "2.42.4",
+      "resolved": "https://registry.npmjs.org/@amplitude/analytics-browser/-/analytics-browser-2.42.4.tgz",
+      "integrity": "sha512-q1XUlaKQkLq2CFx8xsVEc+uekOwHlnDYyaMBzlQDf2vcEaPaQDb7LzJ7z4CFs4Jn9FyBGDNo4w3IYjv9L6xjGA==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-core": "2.48.2",
+        "@amplitude/plugin-autocapture-browser": "1.27.2",
+        "@amplitude/plugin-custom-enrichment-browser": "0.1.9",
+        "@amplitude/plugin-event-property-attribution-browser": "0.2.1",
+        "@amplitude/plugin-network-capture-browser": "1.10.1",
+        "@amplitude/plugin-page-url-enrichment-browser": "0.7.11",
+        "@amplitude/plugin-page-view-tracking-browser": "2.11.1",
+        "@amplitude/plugin-web-vitals-browser": "1.1.33",
+        "tslib": "^2.4.1"
+      }
+    },
+    "node_modules/@amplitude/analytics-client-common": {
+      "version": "2.4.48",
+      "resolved": "https://registry.npmjs.org/@amplitude/analytics-client-common/-/analytics-client-common-2.4.48.tgz",
+      "integrity": "sha512-jdRvu8ux3aIf74FvTDZuSFR1mutzdrIg1ebXYqpKizs9upXz1AJnHClkldSw9i4yu924AJ2wudxq6dccHWlNiA==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-connector": "^1.4.8",
+        "@amplitude/analytics-core": "2.48.2",
+        "@amplitude/analytics-types": "2.11.1",
+        "tslib": "^2.4.1"
+      }
+    },
+    "node_modules/@amplitude/analytics-connector": {
+      "version": "1.6.4",
+      "resolved": "https://registry.npmjs.org/@amplitude/analytics-connector/-/analytics-connector-1.6.4.tgz",
+      "integrity": "sha512-SpIv0IQMNIq6SH3UqFGiaZyGSc7PBZwRdq7lvP0pBxW8i4Ny+8zwI0pV+VMfMHQwWY3wdIbWw5WQphNjpdq1/Q==",
+      "license": "MIT"
+    },
+    "node_modules/@amplitude/analytics-core": {
+      "version": "2.48.2",
+      "resolved": "https://registry.npmjs.org/@amplitude/analytics-core/-/analytics-core-2.48.2.tgz",
+      "integrity": "sha512-r9O+hsTnTsDa1p6QdyC0KbBPXupzoWz9053RQB9XQz8078LM+5KCMbCKYOrSYniH4DH/OM2kOUEdJlwdxIl/IA==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-connector": "^1.6.4",
+        "@types/zen-observable": "0.8.3",
+        "safe-json-stringify": "1.2.0",
+        "tslib": "^2.4.1",
+        "zen-observable": "0.10.0"
+      }
+    },
+    "node_modules/@amplitude/analytics-types": {
+      "version": "2.11.1",
+      "resolved": "https://registry.npmjs.org/@amplitude/analytics-types/-/analytics-types-2.11.1.tgz",
+      "integrity": "sha512-wFEgb0t99ly2uJKm5oZ28Lti0Kh5RecR5XBkwfUpDzn84IoCIZ8GJTsMw/nThu8FZFc7xFDA4UAt76zhZKrs9A==",
+      "license": "MIT"
+    },
+    "node_modules/@amplitude/engagement-browser": {
+      "version": "1.0.9",
+      "resolved": "https://registry.npmjs.org/@amplitude/engagement-browser/-/engagement-browser-1.0.9.tgz",
+      "integrity": "sha512-zvPr0L5aLlOS3nG8scIkEEDMVK2y3MaMbgjYhMfYruhMpfsC/U0apov22nEc1RRrTwve2awEXruPRKf1TysqrQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-types": "^2.0.0"
+      }
+    },
+    "node_modules/@amplitude/experiment-core": {
+      "version": "0.13.1",
+      "resolved": "https://registry.npmjs.org/@amplitude/experiment-core/-/experiment-core-0.13.1.tgz",
+      "integrity": "sha512-ZHvR0dxTltasp8MiMcQ6qKsY20mWnODoy3oebGad6qaRR1ywpUi8IuLf5AwLTM35ZwgzEUTn9TEIWKLHpDwHMw==",
+      "license": "MIT",
+      "dependencies": {
+        "js-base64": "^3.7.5"
+      }
+    },
+    "node_modules/@amplitude/experiment-js-client": {
+      "version": "1.21.1",
+      "resolved": "https://registry.npmjs.org/@amplitude/experiment-js-client/-/experiment-js-client-1.21.1.tgz",
+      "integrity": "sha512-chE/4qQG/5Cgl93Wqj1NEdgOL5LkqySLlfk1EN0f+7bJa52HpkGFALA2FeCNYf31Z5CglEeKX6dUMgL7y33SIw==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-connector": "^1.6.4",
+        "@amplitude/experiment-core": "^0.13.1",
+        "@amplitude/ua-parser-js": "^0.7.31",
+        "base64-js": "1.5.1",
+        "unfetch": "4.1.0"
+      }
+    },
+    "node_modules/@amplitude/plugin-autocapture-browser": {
+      "version": "1.27.2",
+      "resolved": "https://registry.npmjs.org/@amplitude/plugin-autocapture-browser/-/plugin-autocapture-browser-1.27.2.tgz",
+      "integrity": "sha512-UTA/0IDw/f2nnK+S1XILqoI5pgUgMTEZokDS6+pC4wuYtmOS9uNAgKuyajzjW12uobybMHRpv7xLjCJ5khKGAg==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-core": "2.48.2",
+        "tslib": "^2.4.1"
+      }
+    },
+    "node_modules/@amplitude/plugin-custom-enrichment-browser": {
+      "version": "0.1.9",
+      "resolved": "https://registry.npmjs.org/@amplitude/plugin-custom-enrichment-browser/-/plugin-custom-enrichment-browser-0.1.9.tgz",
+      "integrity": "sha512-wemh2Tw3zgQ7sa7MUNyMGz9OR6VjTG4tlAMrLlDKbQ4tVkgNI3oAwOF7+0BA8qzgeMXX6iw+CEKaE+EC/okkuQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-core": "2.48.2",
+        "tslib": "^2.4.1"
+      }
+    },
+    "node_modules/@amplitude/plugin-event-property-attribution-browser": {
+      "version": "0.2.1",
+      "resolved": "https://registry.npmjs.org/@amplitude/plugin-event-property-attribution-browser/-/plugin-event-property-attribution-browser-0.2.1.tgz",
+      "integrity": "sha512-xqBCZe0DYsKyQ1eELN2LM8adXwRE2eOi3SnvSu9SkS0GDXBYWinuPCuLqyc/3uD5hY2FLACWvakpU0tr7GDJgg==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-core": "2.48.2",
+        "tslib": "^2.4.1"
+      }
+    },
+    "node_modules/@amplitude/plugin-experiment-browser": {
+      "version": "1.0.0-beta.28",
+      "resolved": "https://registry.npmjs.org/@amplitude/plugin-experiment-browser/-/plugin-experiment-browser-1.0.0-beta.28.tgz",
+      "integrity": "sha512-NQz267zLi7vl2G2lx10yUrEoGOCe5K9iqcPSIjbTavGu/XGvsmqLDqBHhg+EkdEMAPwypoXnmtPEs3RMhX+1MA==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-core": "2.48.2",
+        "@amplitude/experiment-js-client": "^1.15.5"
+      }
+    },
+    "node_modules/@amplitude/plugin-network-capture-browser": {
+      "version": "1.10.1",
+      "resolved": "https://registry.npmjs.org/@amplitude/plugin-network-capture-browser/-/plugin-network-capture-browser-1.10.1.tgz",
+      "integrity": "sha512-jROIAkUDPd25A/t8W5MpmsTiBat2qoJbCMoNBKKxLMNEaE8VYbheflByWLkm4enbHgWS7OveWy0i3Oc7uPCfAg==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-core": "2.48.2",
+        "tslib": "^2.4.1"
+      }
+    },
+    "node_modules/@amplitude/plugin-page-url-enrichment-browser": {
+      "version": "0.7.11",
+      "resolved": "https://registry.npmjs.org/@amplitude/plugin-page-url-enrichment-browser/-/plugin-page-url-enrichment-browser-0.7.11.tgz",
+      "integrity": "sha512-u9JhUP/VenJifCSbdTz2YZZiXAphs3efzd+qx1SRAIU6d1swPh0g/GVw3sTwvH+4MZtw3SwVC1OFxmz+f2QVyA==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-core": "2.48.2",
+        "tslib": "^2.4.1"
+      }
+    },
+    "node_modules/@amplitude/plugin-page-view-tracking-browser": {
+      "version": "2.11.1",
+      "resolved": "https://registry.npmjs.org/@amplitude/plugin-page-view-tracking-browser/-/plugin-page-view-tracking-browser-2.11.1.tgz",
+      "integrity": "sha512-tfXg6Uir6X1XuWsOOXE/EgZ9NvM7i2ktDdagydSrFN6OyVkMvqdjPKUZSSUPuHtOoomboi3WaZsTUfq1jkWP3w==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-core": "2.48.2",
+        "tslib": "^2.4.1"
+      }
+    },
+    "node_modules/@amplitude/plugin-session-replay-browser": {
+      "version": "1.31.0",
+      "resolved": "https://registry.npmjs.org/@amplitude/plugin-session-replay-browser/-/plugin-session-replay-browser-1.31.0.tgz",
+      "integrity": "sha512-b7kyYVEdW3EMR6cPXCfld+h8nQsuAR5o6vum8Glu+ofhFDfG4wj/mTJ0ITEaNbsJCfXniKQ3kFgTe6hTtxSFGQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-client-common": "2.4.48",
+        "@amplitude/analytics-core": "2.48.2",
+        "@amplitude/analytics-types": "2.11.1",
+        "@amplitude/rrweb-plugin-console-record": "2.0.0-alpha.40",
+        "@amplitude/rrweb-record": "2.0.0-alpha.40",
+        "@amplitude/session-replay-browser": "1.44.0",
+        "idb-keyval": "^6.2.1",
+        "tslib": "^2.4.1"
+      }
+    },
+    "node_modules/@amplitude/plugin-web-vitals-browser": {
+      "version": "1.1.33",
+      "resolved": "https://registry.npmjs.org/@amplitude/plugin-web-vitals-browser/-/plugin-web-vitals-browser-1.1.33.tgz",
+      "integrity": "sha512-33FzxMH1Lr2lhvr5DDy3xD1HHWEI4KPLQsMUXqDTldkLl/ENNeBWcsljQTTDJipmRdS32I79KJhuHRNaoXd6fg==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-core": "2.48.2",
+        "tslib": "^2.4.1",
+        "web-vitals": "5.1.0"
+      }
+    },
+    "node_modules/@amplitude/rrdom": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@amplitude/rrdom/-/rrdom-2.1.0.tgz",
+      "integrity": "sha512-2dAtxXL02usBV2CSOnScLd3WoVqWaeiGpxN8LuXJ0r/NpLJkW1k876v2tRKAz5NrxPwSdjihsMmwCIXHpJhHfA==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/rrweb-snapshot": "^2.1.0"
+      }
+    },
+    "node_modules/@amplitude/rrweb": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/@amplitude/rrweb/-/rrweb-2.1.1.tgz",
+      "integrity": "sha512-6uA+5VE/VHumaXPXTTLGRogd/K9MDwd01jGteppeLzsX0PvqlDyY5aIi35yh9+q1iS6ciPBn/2NRg0lg4cFIlw==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/rrdom": "^2.1.0",
+        "@amplitude/rrweb-snapshot": "^2.1.0",
+        "@amplitude/rrweb-types": "^2.1.0",
+        "@amplitude/rrweb-utils": "^2.1.0",
+        "@types/css-font-loading-module": "0.0.7",
+        "@xstate/fsm": "^1.4.0",
+        "base64-arraybuffer": "^1.0.1",
+        "mitt": "^3.0.0"
+      }
+    },
+    "node_modules/@amplitude/rrweb-packer": {
+      "version": "2.0.0-alpha.40",
+      "resolved": "https://registry.npmjs.org/@amplitude/rrweb-packer/-/rrweb-packer-2.0.0-alpha.40.tgz",
+      "integrity": "sha512-Btb6b9pS1IvDMbvyYxpUdTk9NRJugSoJjRCl7R6jP/iSlPWXoveJIwHaNFAS9ZmWUEK7HhyBJ8bKGFN3giUsDg==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/rrweb-types": "^2.0.0-alpha.40",
+        "fflate": "^0.4.4"
+      }
+    },
+    "node_modules/@amplitude/rrweb-plugin-console-record": {
+      "version": "2.0.0-alpha.40",
+      "resolved": "https://registry.npmjs.org/@amplitude/rrweb-plugin-console-record/-/rrweb-plugin-console-record-2.0.0-alpha.40.tgz",
+      "integrity": "sha512-vtY7T/kGFl62nC1u7ZUXQvU7ulB70cZGVHPRN/SO9fzVfsY7y6rCmBfoc2jS5KmISdlgkVzMjY2r/EE2Gk9AQA==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@amplitude/rrweb": "^2.0.0-alpha.40"
+      }
+    },
+    "node_modules/@amplitude/rrweb-record": {
+      "version": "2.0.0-alpha.40",
+      "resolved": "https://registry.npmjs.org/@amplitude/rrweb-record/-/rrweb-record-2.0.0-alpha.40.tgz",
+      "integrity": "sha512-5cJhQwzhymJWX5/XOtpWK0h2NLq9+t2YiO6ub0cdZ9F5AZizaRbsVH88int07DfX0YiXTKWbISezVuduCLqgSQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/rrweb": "^2.0.0-alpha.40",
+        "@amplitude/rrweb-types": "^2.0.0-alpha.40"
+      }
+    },
+    "node_modules/@amplitude/rrweb-snapshot": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@amplitude/rrweb-snapshot/-/rrweb-snapshot-2.1.0.tgz",
+      "integrity": "sha512-xYQvOW73ig+5M7caqilA8j0S6MHWUULLeJNK+2VVvUqv8mr4FMT2DUAQiVBGCImNlb9Gu2rLUfCScMnVxn+EDg==",
+      "license": "MIT",
+      "dependencies": {
+        "postcss": "^8.4.38"
+      }
+    },
+    "node_modules/@amplitude/rrweb-types": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@amplitude/rrweb-types/-/rrweb-types-2.1.0.tgz",
+      "integrity": "sha512-S73tBI/04A6HCHgnrUNeeVOvnDTEoQnNrmZGyrZncJwRlTIX+6BQSYtBFofMag8GnAy9gA+NtC0TL0CnluOWBw==",
+      "license": "MIT"
+    },
+    "node_modules/@amplitude/rrweb-utils": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@amplitude/rrweb-utils/-/rrweb-utils-2.1.0.tgz",
+      "integrity": "sha512-dTCDnSiMMHZ10utYHJ8dSd/xkjFgdF67y74PkOzAPcCKW1rLxyJYcFOA3uPL2b7cIVVmoel/5NTp5eflaUaJfQ==",
+      "license": "MIT"
+    },
+    "node_modules/@amplitude/session-replay-browser": {
+      "version": "1.44.0",
+      "resolved": "https://registry.npmjs.org/@amplitude/session-replay-browser/-/session-replay-browser-1.44.0.tgz",
+      "integrity": "sha512-8Ruep2TTDMcfVMKurSpBbVclBK/v8Lb3aSHFsYd/xOQ1E3CaKoAu39pplli28NWoUcW7unyVE7khkOa2zzn0Lw==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-client-common": "2.4.48",
+        "@amplitude/analytics-core": "2.48.2",
+        "@amplitude/analytics-types": "2.11.1",
+        "@amplitude/experiment-core": "0.7.2",
+        "@amplitude/rrweb-packer": "2.0.0-alpha.40",
+        "@amplitude/rrweb-plugin-console-record": "2.0.0-alpha.40",
+        "@amplitude/rrweb-record": "2.0.0-alpha.40",
+        "@amplitude/rrweb-types": "2.0.0-alpha.40",
+        "@amplitude/rrweb-utils": "2.0.0-alpha.40",
+        "@amplitude/targeting": "0.2.0",
+        "@rollup/plugin-replace": "^6.0.1",
+        "idb": "8.0.0",
+        "tslib": "^2.4.1"
+      }
+    },
+    "node_modules/@amplitude/session-replay-browser/node_modules/@amplitude/experiment-core": {
+      "version": "0.7.2",
+      "resolved": "https://registry.npmjs.org/@amplitude/experiment-core/-/experiment-core-0.7.2.tgz",
+      "integrity": "sha512-Wc2NWvgQ+bLJLeF0A9wBSPIaw0XuqqgkPKsoNFQrmS7r5Djd56um75In05tqmVntPJZRvGKU46pAp8o5tdf4mA==",
+      "license": "MIT",
+      "dependencies": {
+        "js-base64": "^3.7.5"
+      }
+    },
+    "node_modules/@amplitude/session-replay-browser/node_modules/@amplitude/rrweb-types": {
+      "version": "2.0.0-alpha.40",
+      "resolved": "https://registry.npmjs.org/@amplitude/rrweb-types/-/rrweb-types-2.0.0-alpha.40.tgz",
+      "integrity": "sha512-rP7CBDkzXupxOA7ukvC+zDYLuCtsz54TuJKC4+5O72Jsz4YdokLznKZRG34P6zXozfhGU0261qckk87lLY6mKQ==",
+      "license": "MIT"
+    },
+    "node_modules/@amplitude/session-replay-browser/node_modules/@amplitude/rrweb-utils": {
+      "version": "2.0.0-alpha.40",
+      "resolved": "https://registry.npmjs.org/@amplitude/rrweb-utils/-/rrweb-utils-2.0.0-alpha.40.tgz",
+      "integrity": "sha512-i1CCt6MCjlqoeNc+1Hse5bz+ZbASaWaIJ0WdJZvnQjUCHH29Xy/QFouyOuor73RZ+UWX4s2tYSrUIdmBepXk3w==",
+      "license": "MIT"
+    },
+    "node_modules/@amplitude/targeting": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/@amplitude/targeting/-/targeting-0.2.0.tgz",
+      "integrity": "sha512-/50ywTrC4hfcfJVBbh5DFbqMPPfaIOivZeb5Gb+OGM03QrA+lsUqdvtnKLNuWtceD4H6QQ2KFzPJ5aAJLyzVDA==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-client-common": ">=1 <3",
+        "@amplitude/analytics-core": ">=1 <3",
+        "@amplitude/analytics-types": ">=1 <3",
+        "@amplitude/experiment-core": "0.7.2",
+        "idb": "^8.0.0",
+        "tslib": "^2.4.1"
+      }
+    },
+    "node_modules/@amplitude/targeting/node_modules/@amplitude/experiment-core": {
+      "version": "0.7.2",
+      "resolved": "https://registry.npmjs.org/@amplitude/experiment-core/-/experiment-core-0.7.2.tgz",
+      "integrity": "sha512-Wc2NWvgQ+bLJLeF0A9wBSPIaw0XuqqgkPKsoNFQrmS7r5Djd56um75In05tqmVntPJZRvGKU46pAp8o5tdf4mA==",
+      "license": "MIT",
+      "dependencies": {
+        "js-base64": "^3.7.5"
+      }
+    },
+    "node_modules/@amplitude/ua-parser-js": {
+      "version": "0.7.33",
+      "resolved": "https://registry.npmjs.org/@amplitude/ua-parser-js/-/ua-parser-js-0.7.33.tgz",
+      "integrity": "sha512-wKEtVR4vXuPT9cVEIJkYWnlF++Gx3BdLatPBM+SZ1ztVIvnhdGBZR/mn9x/PzyrMcRlZmyi6L56I2J3doVBnjA==",
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/ua-parser-js"
+        },
+        {
+          "type": "paypal",
+          "url": "https://paypal.me/faisalman"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/@amplitude/unified": {
+      "version": "1.1.9",
+      "resolved": "https://registry.npmjs.org/@amplitude/unified/-/unified-1.1.9.tgz",
+      "integrity": "sha512-YPgQbp/vDQ92GshHs2hfUxoeRnR3rRBWCoQ6wXgFjXQ1uiJf2tP0CBZWdrCStSDuhcpo2rsCz/Ek2LGq5J6SIQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@amplitude/analytics-browser": "2.42.4",
+        "@amplitude/analytics-core": "2.48.2",
+        "@amplitude/engagement-browser": "^1.0.3",
+        "@amplitude/plugin-experiment-browser": "1.0.0-beta.28",
+        "@amplitude/plugin-session-replay-browser": "1.31.0"
+      }
+    },
     "node_modules/@antfu/install-pkg": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/@antfu/install-pkg/-/install-pkg-1.1.0.tgz",
@@ -264,6 +619,12 @@
         "import-meta-resolve": "^4.2.0"
       }
     },
+    "node_modules/@jridgewell/sourcemap-codec": {
+      "version": "1.5.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
+      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
+      "license": "MIT"
+    },
     "node_modules/@lezer/common": {
       "version": "1.5.2",
       "resolved": "https://registry.npmjs.org/@lezer/common/-/common-1.5.2.tgz",
@@ -657,6 +1018,49 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@rollup/plugin-replace": {
+      "version": "6.0.3",
+      "resolved": "https://registry.npmjs.org/@rollup/plugin-replace/-/plugin-replace-6.0.3.tgz",
+      "integrity": "sha512-J4RZarRvQAm5IF0/LwUUg+obsm+xZhYnbMXmXROyoSE1ATJe3oXSb9L5MMppdxP2ylNSjv6zFBwKYjcKMucVfA==",
+      "license": "MIT",
+      "dependencies": {
+        "@rollup/pluginutils": "^5.0.1",
+        "magic-string": "^0.30.3"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      },
+      "peerDependencies": {
+        "rollup": "^1.20.0||^2.0.0||^3.0.0||^4.0.0"
+      },
+      "peerDependenciesMeta": {
+        "rollup": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@rollup/pluginutils": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@rollup/pluginutils/-/pluginutils-5.3.0.tgz",
+      "integrity": "sha512-5EdhGZtnu3V88ces7s53hhfK5KSASnJZv8Lulpc04cWO3REESroJXg73DFsOmgbU2BhwV0E20bu2IDZb3VKW4Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "estree-walker": "^2.0.2",
+        "picomatch": "^4.0.2"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      },
+      "peerDependencies": {
+        "rollup": "^1.20.0||^2.0.0||^3.0.0||^4.0.0"
+      },
+      "peerDependenciesMeta": {
+        "rollup": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@tiptap/core": {
       "version": "3.23.6",
       "resolved": "https://registry.npmjs.org/@tiptap/core/-/core-3.23.6.tgz",
@@ -1109,6 +1513,12 @@
         "tslib": "^2.4.0"
       }
     },
+    "node_modules/@types/css-font-loading-module": {
+      "version": "0.0.7",
+      "resolved": "https://registry.npmjs.org/@types/css-font-loading-module/-/css-font-loading-module-0.0.7.tgz",
+      "integrity": "sha512-nl09VhutdjINdWyXxHWN/w9zlNCfr60JUqJbd24YXUuCwgeL0TpFSdElCwb6cxfB6ybE19Gjj4g0jsgkXxKv1Q==",
+      "license": "MIT"
+    },
     "node_modules/@types/d3": {
       "version": "7.4.3",
       "resolved": "https://registry.npmjs.org/@types/d3/-/d3-7.4.3.tgz",
@@ -1362,6 +1772,12 @@
         "@types/d3-selection": "*"
       }
     },
+    "node_modules/@types/estree": {
+      "version": "1.0.9",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
+      "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
+      "license": "MIT"
+    },
     "node_modules/@types/geojson": {
       "version": "7946.0.16",
       "resolved": "https://registry.npmjs.org/@types/geojson/-/geojson-7946.0.16.tgz",
@@ -1399,6 +1815,12 @@
       "integrity": "sha512-zFDAD+tlpf2r4asuHEj0XH6pY6i0g5NeAHPn+15wk3BV6JA69eERFXC1gyGThDkVa1zCyKr5jox1+2LbV/AMLg==",
       "license": "MIT"
     },
+    "node_modules/@types/zen-observable": {
+      "version": "0.8.3",
+      "resolved": "https://registry.npmjs.org/@types/zen-observable/-/zen-observable-0.8.3.tgz",
+      "integrity": "sha512-fbF6oTd4sGGy0xjHPKAt+eS2CrxJ3+6gQ3FGcBoIJR2TLAyCkCyI8JqZNy+FeON0AhVgNJoUumVoZQjBFUqHkw==",
+      "license": "MIT"
+    },
     "node_modules/@upsetjs/venn.js": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/@upsetjs/venn.js/-/venn.js-2.0.0.tgz",
@@ -1435,6 +1857,41 @@
         }
       }
     },
+    "node_modules/@xstate/fsm": {
+      "version": "1.6.5",
+      "resolved": "https://registry.npmjs.org/@xstate/fsm/-/fsm-1.6.5.tgz",
+      "integrity": "sha512-b5o1I6aLNeYlU/3CPlj/Z91ybk1gUsKT+5NAJI+2W4UjvS5KLG28K9v5UvNoFVjHV8PajVZ00RH3vnjyQO7ZAw==",
+      "license": "MIT"
+    },
+    "node_modules/base64-arraybuffer": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/base64-arraybuffer/-/base64-arraybuffer-1.0.2.tgz",
+      "integrity": "sha512-I3yl4r9QB5ZRY3XuJVEPfc2XhZO6YweFPI+UovAzn+8/hb3oJ6lnysaFcjVpkCPfVWFUDvoZ8kmVDP7WyRtYtQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6.0"
+      }
+    },
+    "node_modules/base64-js": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
+      "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT"
+    },
     "node_modules/commander": {
       "version": "7.2.0",
       "resolved": "https://registry.npmjs.org/commander/-/commander-7.2.0.tgz",
@@ -2021,6 +2478,12 @@
         "benchmarks"
       ]
     },
+    "node_modules/estree-walker": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-2.0.2.tgz",
+      "integrity": "sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==",
+      "license": "MIT"
+    },
     "node_modules/fast-equals": {
       "version": "5.4.0",
       "resolved": "https://registry.npmjs.org/fast-equals/-/fast-equals-5.4.0.tgz",
@@ -2048,6 +2511,12 @@
         }
       }
     },
+    "node_modules/fflate": {
+      "version": "0.4.8",
+      "resolved": "https://registry.npmjs.org/fflate/-/fflate-0.4.8.tgz",
+      "integrity": "sha512-FJqqoDBR00Mdj9ppamLa/Y7vxm+PRmNWA67N846RvsoYVMKB4q3y/de5PA7gUmRMYK/8CMz2GDZQmCRN1wBcWA==",
+      "license": "MIT"
+    },
     "node_modules/fsevents": {
       "version": "2.3.3",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
@@ -2081,6 +2550,18 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/idb": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/idb/-/idb-8.0.0.tgz",
+      "integrity": "sha512-l//qvlAKGmQO31Qn7xdzagVPPaHTxXx199MhrAFuVBTPqydcPYBWjkrbv4Y0ktB+GmWOiwHl237UUOrLmQxLvw==",
+      "license": "ISC"
+    },
+    "node_modules/idb-keyval": {
+      "version": "6.2.4",
+      "resolved": "https://registry.npmjs.org/idb-keyval/-/idb-keyval-6.2.4.tgz",
+      "integrity": "sha512-D/NzHWUmYJGXi++z67aMSrnisb9A3621CyRK5G89JyTlN13C8xf0g04DLxUKMufPem3e3L2JAXR6Z00OWy183Q==",
+      "license": "Apache-2.0"
+    },
     "node_modules/import-meta-resolve": {
       "version": "4.2.0",
       "resolved": "https://registry.npmjs.org/import-meta-resolve/-/import-meta-resolve-4.2.0.tgz",
@@ -2100,6 +2581,12 @@
         "node": ">=12"
       }
     },
+    "node_modules/js-base64": {
+      "version": "3.7.8",
+      "resolved": "https://registry.npmjs.org/js-base64/-/js-base64-3.7.8.tgz",
+      "integrity": "sha512-hNngCeKxIUQiEUN3GPJOkz4wF/YvdUdbNL9hsBcMQTkKzboD7T/q3OYOuuPZLUE6dBxSGpwhk5mwuDud7JVAow==",
+      "license": "BSD-3-Clause"
+    },
     "node_modules/katex": {
       "version": "0.16.47",
       "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.47.tgz",
@@ -2421,6 +2908,15 @@
       "integrity": "sha512-J8xewKD/Gk22OZbhpOVSwcs60zhd95ESDwezOFuA3/099925PdHJ7OFHNTGtajL3AlZkykD32HykiMo+BIBI8A==",
       "license": "MIT"
     },
+    "node_modules/magic-string": {
+      "version": "0.30.21",
+      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
+      "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.5"
+      }
+    },
     "node_modules/marked": {
       "version": "18.0.4",
       "resolved": "https://registry.npmjs.org/marked/-/marked-18.0.4.tgz",
@@ -2474,11 +2970,16 @@
         "node": ">= 20"
       }
     },
+    "node_modules/mitt": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/mitt/-/mitt-3.0.1.tgz",
+      "integrity": "sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==",
+      "license": "MIT"
+    },
     "node_modules/nanoid": {
       "version": "3.3.12",
       "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
       "integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==",
-      "dev": true,
       "funding": [
         {
           "type": "github",
@@ -2515,14 +3016,12 @@
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
       "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
-      "dev": true,
       "license": "ISC"
     },
     "node_modules/picomatch": {
       "version": "4.0.4",
       "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
       "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=12"
@@ -2551,7 +3050,6 @@
       "version": "8.5.15",
       "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz",
       "integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==",
-      "dev": true,
       "funding": [
         {
           "type": "opencollective",
@@ -2828,6 +3326,12 @@
       "integrity": "sha512-PdhdWy89SiZogBLaw42zdeqtRJ//zFd2PgQavcICDUgJT5oW10QCRKbJ6bg4r0/UY2M6BWd5tkxuGFRvCkgfHQ==",
       "license": "BSD-3-Clause"
     },
+    "node_modules/safe-json-stringify": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/safe-json-stringify/-/safe-json-stringify-1.2.0.tgz",
+      "integrity": "sha512-gH8eh2nZudPQO6TytOvbxnuhYBOvDBBLW52tz5q6X58lJcd/tkmqFR+5Z9adS8aJtURSXWThWy/xJtJwixErvg==",
+      "license": "MIT"
+    },
     "node_modules/safer-buffer": {
       "version": "2.1.2",
       "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
@@ -2850,7 +3354,6 @@
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
       "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
-      "dev": true,
       "license": "BSD-3-Clause",
       "engines": {
         "node": ">=0.10.0"
@@ -2907,9 +3410,13 @@
       "version": "2.8.1",
       "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
       "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
-      "dev": true,
-      "license": "0BSD",
-      "optional": true
+      "license": "0BSD"
+    },
+    "node_modules/unfetch": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/unfetch/-/unfetch-4.1.0.tgz",
+      "integrity": "sha512-crP/n3eAPUJxZXM9T80/yv0YhkTEx2K1D3h7D1AJM6fzsWZrxdyRuLN0JH/dkZh1LNH8LxCnBzoPFCPbb2iGpg==",
+      "license": "MIT"
     },
     "node_modules/use-sync-external-store": {
       "version": "1.6.0",
@@ -3016,6 +3523,18 @@
       "resolved": "https://registry.npmjs.org/w3c-keyname/-/w3c-keyname-2.2.8.tgz",
       "integrity": "sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==",
       "license": "MIT"
+    },
+    "node_modules/web-vitals": {
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/web-vitals/-/web-vitals-5.1.0.tgz",
+      "integrity": "sha512-ArI3kx5jI0atlTtmV0fWU3fjpLmq/nD3Zr1iFFlJLaqa5wLBkUSzINwBPySCX/8jRyjlmy1Volw1kz1g9XE4Jg==",
+      "license": "Apache-2.0"
+    },
+    "node_modules/zen-observable": {
+      "version": "0.10.0",
+      "resolved": "https://registry.npmjs.org/zen-observable/-/zen-observable-0.10.0.tgz",
+      "integrity": "sha512-iI3lT0iojZhKwT5DaFy2Ce42n3yFcLdFyOh01G7H0flMY60P8MJuVFEoJoNwXlmAyQ45GrjL6AcZmmlv8A5rbw==",
+      "license": "MIT"
     }
   }
 }

frontend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rfc-app-frontend",
   "private": true,
-  "version": "0.9.0",
+  "version": "0.18.0",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -9,6 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
+    "@amplitude/unified": "^1.1.9",
     "@codemirror/commands": "^6.10.3",
     "@codemirror/lang-markdown": "^6.5.0",
     "@codemirror/language": "^6.12.3",

frontend/src/App.css

@@ -455,6 +455,65 @@
 .otc-fallback a:hover { color: #1a1a1a; text-decoration: underline; }
 .otc-fallback-sep { color: #ccc; }
 
+/* v0.11.0 — "trust this device for 30 days" checkbox on the verify
+   step. Sits above the action row, padded so it doesn't crowd the
+   passcode/code input. */
+.otc-trust-device {
+  display: flex; align-items: center; gap: 8px;
+  font-size: 13px; color: #444;
+  margin: 8px 0 4px;
+  cursor: pointer;
+  user-select: none;
+}
+.otc-trust-device input[type="checkbox"] {
+  width: auto; margin: 0; cursor: pointer;
+}
+
+/* v0.11.0 — /settings/devices revoke-device UI. */
+.device-list {
+  list-style: none; padding: 0; margin: 12px 0 0;
+}
+.device-list-item {
+  display: flex; align-items: center; justify-content: space-between;
+  gap: 12px;
+  border: 1px solid #eee; border-radius: 6px;
+  padding: 10px 12px; margin: 0 0 8px;
+  background: #fafafa;
+}
+.device-list-item .device-meta {
+  flex: 1; min-width: 0;
+}
+.device-list-item .device-ua {
+  font-size: 13px; color: #1a1a1a;
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+.device-list-item .device-stamps {
+  font-size: 12px; color: #777;
+  margin-top: 2px;
+}
+.device-list-item button {
+  font-size: 12px; padding: 4px 10px;
+  border: 1px solid #ccc; border-radius: 4px;
+  background: white; cursor: pointer;
+}
+.device-list-item button:hover:not(:disabled) {
+  background: #f5f5f5;
+}
+.device-revoke-all {
+  margin-top: 8px;
+  font-size: 13px; padding: 6px 12px;
+  border: 1px solid #cb6a6a; border-radius: 4px;
+  background: white; color: #cb6a6a; cursor: pointer;
+}
+.device-revoke-all:hover:not(:disabled) {
+  background: #fff5f5;
+}
+.device-empty {
+  font-size: 13px; color: #777;
+  background: #fafafa; border: 1px solid #eee; border-radius: 6px;
+  padding: 12px;
+}
+
 /* --- Beta-pending page (post-OAuth-rejection) --- */
 
 .beta-pending {

frontend/src/App.jsx

@@ -1,6 +1,7 @@
-import { useEffect, useState } from 'react'
-import { Routes, Route, Link, useNavigate } from 'react-router-dom'
+import { useEffect, useRef, useState } from 'react'
+import { Routes, Route, Link, useLocation, useNavigate } from 'react-router-dom'
 import { getMe, subscribeToNotifications } from './api'
+import { anonymize, EVENTS, identify, track } from './lib/analytics'
 import Catalog from './components/Catalog.jsx'
 import Inbox from './components/Inbox.jsx'
 import RFCView from './components/RFCView.jsx'
@@ -14,6 +15,8 @@ import Philosophy from './components/Philosophy.jsx'
 import Docs from './components/Docs.jsx'
 import NotificationSettings from './components/NotificationSettings.jsx'
 import Admin from './components/Admin.jsx'
+import AcceptInvitation from './components/AcceptInvitation.jsx'
+import InviteClaim from './components/InviteClaim.jsx'
 import ToastHost, { showToast } from './components/ToastHost.jsx'
 import CookieConsentBanner from './components/CookieConsentBanner.jsx'
 import Privacy from './pages/Privacy.jsx'
@@ -34,6 +37,56 @@ export default function App() {
   // event that bumps this.
   const [consentReopenTick, setConsentReopenTick] = useState(0)
   const navigate = useNavigate()
+  const location = useLocation()
+  // v0.15.0 — Page Viewed event taxonomy. We fire on every
+  // route change; the analytics wrapper itself decides whether
+  // anything ships out (consent + key check). The first fire is
+  // also covered because `location` is set on mount.
+  const lastPathRef = useRef(null)
+  useEffect(() => {
+    const path = location.pathname + (location.search || '')
+    if (lastPathRef.current === path) return
+    lastPathRef.current = path
+    track(EVENTS.PAGE_VIEWED, { path: location.pathname })
+  }, [location.pathname, location.search])
+
+  // v0.15.0 + #21 Part C — bind the authenticated user id AND
+  // durable user properties to the analytics session when sign-in
+  // lands; reset on sign-out (viewer flips to null). The wrapper
+  // queues these calls until consent + init resolve, so the order
+  // is safe even on a cold load.
+  //
+  // Property bag passed to identify (set vs setOnce per #21 Part C):
+  //   set:     role, permission_state, passcode_set, device_trusted
+  //            (these can change mid-account-life — refresh each sign-in)
+  //   setOnce: first_sign_in_at, account_created_at
+  //            (immutable user-history markers — set on the first
+  //            sign-in that observes them, never overwritten)
+  //
+  // PII discipline: NO email, NO display_name, NO gitea_login passed
+  // through — Amplitude only sees opaque ids + enums + timestamps +
+  // booleans.
+  const lastUserIdRef = useRef(null)
+  useEffect(() => {
+    const uid = me?.authenticated ? me.user?.id : null
+    const viewer = me?.authenticated ? me.user : null
+    if (uid != null && lastUserIdRef.current !== uid) {
+      lastUserIdRef.current = uid
+      const props = {}
+      if (viewer?.role != null) props.role = viewer.role
+      if (viewer?.permission_state != null) props.permission_state = viewer.permission_state
+      if (viewer?.passcode_set != null) props.passcode_set = !!viewer.passcode_set
+      if (viewer?.device_trusted != null) props.device_trusted = !!viewer.device_trusted
+      if (viewer?.first_sign_in_at) props.first_sign_in_at = ['__setOnce__', viewer.first_sign_in_at]
+      if (viewer?.created_at) props.account_created_at = ['__setOnce__', viewer.created_at]
+      identify({ user_id: String(uid), properties: props })
+    } else if (uid == null && lastUserIdRef.current != null) {
+      // Sign-out edge — App-level reset is handled separately by the
+      // sign-out gesture that fires User Signed Out. Clear our local
+      // memo so a fresh sign-in re-fires identify.
+      lastUserIdRef.current = null
+    }
+  }, [me?.authenticated, me?.user?.id, me?.user?.role, me?.user?.permission_state, me?.user?.passcode_set, me?.user?.device_trusted])
 
   useEffect(() => {
     const handler = () => setConsentReopenTick(t => t + 1)
@@ -141,7 +194,20 @@ export default function App() {
             <>
               <span className="user-name">{viewer.display_name}</span>
               <span className={`user-role-badge role-${viewer.role}`}>{viewer.role}</span>
-              <a className="btn-link" href="/auth/logout">Sign out</a>
+              <a
+                className="btn-link"
+                href="/auth/logout"
+                onClick={() => {
+                  // v0.15.0 — fire the sign-out event before the
+                  // hard nav. The wrapper's track() is sync-enqueue;
+                  // the underlying SDK flush is best-effort across
+                  // navigation. anonymize() clears the user binding
+                  // so any post-nav anonymous events on the next
+                  // page aren't attributed to the prior user.
+                  track(EVENTS.USER_SIGNED_OUT)
+                  anonymize()
+                }}
+              >Sign out</a>
             </>
           ) : (
             <Link className="btn-signin-header" to="/login" title="Private beta — only invited emails can sign in">
@@ -156,6 +222,16 @@ export default function App() {
           <Route path="/welcome" element={<Landing />} />
           <Route path="/login" element={<Login />} />
           <Route path="/beta-pending" element={<BetaPending viewer={viewer} />} />
+          {/* v0.16.0 (item #12): per-RFC invitation acceptance landing.
+              Anonymous viewers see a sign-in prompt; signed-in users
+              see the preview + accept gesture. */}
+          <Route path="/invitations/accept" element={
+            <PolicyShell><AcceptInvitation viewer={viewer} /></PolicyShell>
+          } />
+          {/* v0.17.0 — roadmap item #16. The claim landing page for
+              admin-issued invites. Anonymous-reachable; the call
+              itself establishes the session on success. */}
+          <Route path="/invites/claim" element={<InviteClaim />} />
           <Route path="/philosophy" element={<PhilosophyWithSidebar viewer={viewer} />} />
           <Route path="/docs" element={<DocsWithSidebar viewer={viewer} />} />
           {/* §14.5 / §14.6: cookie-consent companions to /philosophy.

frontend/src/api.js

@@ -31,20 +31,33 @@ export async function getMe() {
 // migration — the new UI just no longer points at it primarily. These
 // two helpers drive the Login.jsx surface.
 
-export async function requestOtc(email) {
+export async function requestOtc(email, { turnstileToken } = {}) {
+  // v0.12.0 / roadmap item #10: when the Turnstile widget has produced
+  // a token, send it alongside the email so the backend can siteverify
+  // before the OTC dispatch. The backend treats a missing token as
+  // either soft-fail (no secret wired AND TURNSTILE_REQUIRED=false)
+  // or hard-fail (verification required) — the frontend stays
+  // uninvolved in the policy.
+  const body = { email }
+  if (turnstileToken) body.turnstile_token = turnstileToken
   const res = await fetch('/auth/otc/request', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ email }),
+    body: JSON.stringify(body),
   })
   return jsonOrThrow(res)
 }
 
-export async function verifyOtc(email, code) {
+export async function verifyOtc(email, code, { trustDevice = false } = {}) {
+  // v0.11.0 — `trustDevice` is the "trust this device for 30 days"
+  // checkbox on the Login.jsx OTC step. When true, the server mints
+  // a fresh device-trust row and sets the long-lived cookie; on
+  // subsequent visits, the cookie skips the OTC roundtrip via
+  // `startDeviceTrust()`.
   const res = await fetch('/auth/otc/verify', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ email, code }),
+    body: JSON.stringify({ email, code, trust_device: !!trustDevice }),
   })
   return jsonOrThrow(res)
 }
@@ -82,15 +95,44 @@ export async function checkPasscode(email) {
   return jsonOrThrow(res)
 }
 
-export async function verifyPasscode(email, passcode) {
+export async function verifyPasscode(email, passcode, { trustDevice = false } = {}) {
+  // v0.11.0 — same trust-device opt-in as `verifyOtc`.
   const res = await fetch('/auth/passcode/verify', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ email, passcode }),
+    body: JSON.stringify({ email, passcode, trust_device: !!trustDevice }),
   })
   return jsonOrThrow(res)
 }
 
+// ── v0.11.0: trust device for 30 days (§6.2, roadmap item #9) ─────────────
+//
+// On a returning visit with a valid device-trust cookie, `startDeviceTrust`
+// re-establishes the session without an OTC / passcode roundtrip. The
+// cookie is HttpOnly so the client cannot read it; the call is a pure POST
+// that the browser attaches the cookie to automatically.
+//
+// `listMyDevices`, `revokeMyDevice`, and `revokeAllMyDevices` drive the
+// /settings/devices revoke-device UI. The signed-in user is the implicit
+// subject; the cookie carries the session.
+
+export async function startDeviceTrust() {
+  const res = await fetch('/auth/device-trust/start', { method: 'POST' })
+  return jsonOrThrow(res)
+}
+
+export async function listMyDevices() {
+  return jsonOrThrow(await fetch('/api/auth/me/devices'))
+}
+
+export async function revokeMyDevice(deviceId) {
+  return jsonOrThrow(await fetch(`/api/auth/me/devices/${deviceId}`, { method: 'DELETE' }))
+}
+
+export async function revokeAllMyDevices() {
+  return jsonOrThrow(await fetch('/api/auth/me/devices', { method: 'DELETE' }))
+}
+
 export async function setPasscode(passcode) {
   // Requires an active session — the server returns 401 if not signed
   // in. The signed-in user is the implicit subject; the body carries
@@ -280,6 +322,48 @@ export async function resolveThread(slug, branch, threadId) {
   return jsonOrThrow(res)
 }
 
+// ── v0.16.0: owner-only invite for per-RFC PR or PR-less discussion ──────
+//
+// roadmap item #12 / §6 / §10. The RFC's owner invites specific emails
+// to one of two per-RFC roles ('contributor' or 'discussant'); the
+// invitee accepts via the email-encoded token after signing in. The
+// platform-level grant remains the admin's decision (per item #6 /
+// v0.8.0) — these endpoints control per-RFC membership only.
+
+export async function listRFCInvitations(slug) {
+  return jsonOrThrow(await fetch(`/api/rfcs/${slug}/invitations`))
+}
+
+export async function createRFCInvitation(slug, { inviteeEmail, roleInRFC }) {
+  const res = await fetch(`/api/rfcs/${slug}/invitations`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ invitee_email: inviteeEmail, role_in_rfc: roleInRFC }),
+  })
+  return jsonOrThrow(res)
+}
+
+export async function revokeRFCInvitation(slug, invitationId) {
+  const res = await fetch(`/api/rfcs/${slug}/invitations/${invitationId}/revoke`, {
+    method: 'POST',
+  })
+  return jsonOrThrow(res)
+}
+
+export async function previewInvitation(token) {
+  const params = new URLSearchParams({ token })
+  return jsonOrThrow(await fetch(`/api/invitations/accept?${params}`))
+}
+
+export async function acceptInvitation(token) {
+  const res = await fetch('/api/invitations/accept', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ token }),
+  })
+  return jsonOrThrow(res)
+}
+
 // ── v0.5.0: PR-less per-RFC discussion (§5 / §10) ────────────────────────
 //
 // The substrate is `threads.branch_name IS NULL` — the same threads
@@ -715,6 +799,53 @@ export async function removeAllowlistEmail(email) {
   }))
 }
 
+// v0.17.0 — roadmap item #16. Admin-create user + invite email with
+// optional custom message. The frontend modal on /admin/users wires
+// these two helpers; the claim helper drives the /invites/claim page
+// that the invitee lands on when they click the email link.
+//
+// `createUserInvite` returns `{ ok, invite_id, invited_user_id, email,
+// role }`. The 409 path (duplicate email) and 422 path (self-invite,
+// owner-grant-by-non-owner, malformed input) surface as thrown errors
+// via `jsonOrThrow` so the modal can render the server's message.
+//
+// `listUserInvites` returns the active-invites list for the admin's
+// "I sent these but they haven't been claimed yet" view. Active means
+// not claimed and not expired; once the invitee clicks through, the
+// row clears here and the user-listing's `pending_invite` badge
+// vanishes alongside.
+
+export async function createUserInvite({ email, first_name, last_name, role, custom_message }) {
+  return jsonOrThrow(await fetch('/api/admin/users', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      email,
+      first_name: first_name || '',
+      last_name: last_name || '',
+      role,
+      custom_message: custom_message || '',
+    }),
+  }))
+}
+
+export async function listUserInvites() {
+  return jsonOrThrow(await fetch('/api/admin/users/invites'))
+}
+
+// Claim an admin-issued invite token. Anonymous endpoint — the invitee
+// is not yet signed in; this call establishes the session on success.
+// `trustDevice` mirrors the v0.11.0 OTC/passcode opt-in: when true,
+// the server mints a fresh device-trust row + sets the long-lived
+// cookie so the invitee skips OTC on their next visit.
+export async function claimInvite(token, { trustDevice = false } = {}) {
+  return jsonOrThrow(await fetch('/api/invites/claim', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ token, trust_device: !!trustDevice }),
+  }))
+}
+
 export async function searchUsers(q) {
   const params = new URLSearchParams()
   if (q) params.set('q', q)

frontend/src/components/AcceptInvitation.jsx

@@ -0,0 +1,207 @@
+// AcceptInvitation.jsx — v0.16.0 / roadmap item #12.
+//
+// The /invitations/accept?token=... landing page the invitation email
+// links to. The page:
+//
+//   1. Reads `?token=...` from the URL.
+//   2. Calls GET /api/invitations/accept?token=... to preview what the
+//      invitation grants (RFC title, role-in-RFC, expiry, whether the
+//      currently-signed-in user's email matches the invitee's).
+//   3. Renders a confirmation surface — name the RFC, name the role,
+//      and either show "Accept" (when the email matches and the
+//      invitation is still pending) or a refusal message (expired,
+//      revoked, email mismatch).
+//   4. On accept, POST /api/invitations/accept lands the
+//      rfc_collaborators row and the page redirects to the RFC's view.
+//
+// For an anonymous viewer who lands here without signing in, the
+// preview call 401s and the page tells them to sign in. After
+// signing in (via the existing OTC/passcode surface at /login) they
+// can return to the same URL — the token is stable.
+
+import { useEffect, useState } from 'react'
+import { Link, useNavigate, useSearchParams } from 'react-router-dom'
+import { acceptInvitation, previewInvitation } from '../api'
+import { EVENTS, identify, track } from '../lib/analytics'
+
+export default function AcceptInvitation({ viewer }) {
+  const [searchParams] = useSearchParams()
+  const navigate = useNavigate()
+  const token = searchParams.get('token') || ''
+
+  const [preview, setPreview] = useState(null)
+  const [previewError, setPreviewError] = useState(null)
+  const [accepting, setAccepting] = useState(false)
+  const [acceptError, setAcceptError] = useState(null)
+
+  useEffect(() => {
+    if (!token) {
+      setPreviewError('No invitation token in the URL.')
+      return
+    }
+    if (!viewer) {
+      // Not signed in — the preview endpoint will 401. We surface a
+      // sign-in prompt without making the request.
+      return
+    }
+    previewInvitation(token)
+      .then(setPreview)
+      .catch(err => setPreviewError(err.message || 'Could not load invitation.'))
+  }, [token, viewer])
+
+  async function handleAccept() {
+    setAccepting(true)
+    setAcceptError(null)
+    try {
+      const result = await acceptInvitation(token)
+      // v0.16.0 + #21 Part C — re-identify with per-RFC invite
+      // properties on accept, BEFORE the track event fires, so the
+      // Amplitude user record carries the invite context from the
+      // moment of acceptance. setOnce on invited_at preserves the
+      // first-accepted timestamp if the same user accepts multiple
+      // RFC invitations.
+      if (viewer?.id != null) {
+        identify({
+          user_id: String(viewer.id),
+          properties: {
+            invited_at: ['__setOnce__', new Date().toISOString()],
+            last_invited_to_rfc: result.rfc_slug,
+            last_invite_role_in_rfc: result.role_in_rfc || preview?.role_in_rfc,
+            claim_method: 'rfc-invite',
+          },
+        })
+      }
+      track(EVENTS.INVITATION_ACCEPTED, {
+        rfc_slug: result.rfc_slug,
+        role_in_rfc: result.role_in_rfc || preview?.role_in_rfc,
+      })
+      navigate(`/rfc/${result.rfc_slug}`)
+    } catch (err) {
+      setAcceptError(err.message || 'Could not accept invitation.')
+    } finally {
+      setAccepting(false)
+    }
+  }
+
+  if (!token) {
+    return (
+      <div className="accept-invitation">
+        <h1>Invitation link is malformed</h1>
+        <p>No <code>token</code> parameter was found. Ask the person who
+          invited you to re-send the link.</p>
+        <p><Link to="/">Return to the catalog</Link></p>
+      </div>
+    )
+  }
+
+  if (!viewer) {
+    return (
+      <div className="accept-invitation">
+        <h1>Sign in to accept your invitation</h1>
+        <p>
+          You've been invited to collaborate on an RFC. Sign in first so we
+          can attach the membership to your account, then return to this
+          link.
+        </p>
+        <p>
+          <Link to="/login" className="btn-primary">Sign in</Link>
+        </p>
+      </div>
+    )
+  }
+
+  if (previewError) {
+    return (
+      <div className="accept-invitation">
+        <h1>Invitation unavailable</h1>
+        <p>{previewError}</p>
+        <p><Link to="/">Return to the catalog</Link></p>
+      </div>
+    )
+  }
+
+  if (!preview) {
+    return <div className="accept-invitation">Loading invitation…</div>
+  }
+
+  const { rfc_title, rfc_slug, role_in_rfc, status, invitee_email, email_matches_you } = preview
+
+  if (status === 'revoked') {
+    return (
+      <div className="accept-invitation">
+        <h1>Invitation revoked</h1>
+        <p>
+          The owner of <strong>{rfc_title}</strong> revoked this invitation.
+          Ask them to re-issue it if you should still have access.
+        </p>
+        <p><Link to={`/rfc/${rfc_slug}`}>Read the RFC anyway</Link></p>
+      </div>
+    )
+  }
+  if (status === 'expired') {
+    return (
+      <div className="accept-invitation">
+        <h1>Invitation expired</h1>
+        <p>
+          This invitation to <strong>{rfc_title}</strong> has expired. Ask
+          the RFC's owner to issue a fresh one.
+        </p>
+        <p><Link to={`/rfc/${rfc_slug}`}>Read the RFC anyway</Link></p>
+      </div>
+    )
+  }
+  if (status === 'accepted') {
+    return (
+      <div className="accept-invitation">
+        <h1>Already accepted</h1>
+        <p>
+          You've already accepted this invitation. You can{' '}
+          <Link to={`/rfc/${rfc_slug}`}>open {rfc_title}</Link> now.
+        </p>
+      </div>
+    )
+  }
+
+  if (!email_matches_you) {
+    return (
+      <div className="accept-invitation">
+        <h1>This invitation is for a different account</h1>
+        <p>
+          This invitation was sent to <strong>{invitee_email}</strong>. You're
+          currently signed in as <strong>{viewer.email || viewer.gitea_login}</strong>.
+          Sign out and sign back in with the invited address to accept.
+        </p>
+        <p><a className="btn-link" href="/auth/logout">Sign out</a></p>
+      </div>
+    )
+  }
+
+  return (
+    <div className="accept-invitation">
+      <h1>Join {rfc_title}</h1>
+      <p>
+        You've been invited to <strong>{rfc_title}</strong> as a{' '}
+        <strong>{role_in_rfc}</strong>.
+      </p>
+      <p style={{ color: '#666' }}>
+        {role_in_rfc === 'contributor'
+          ? 'Contributors can open PRs against this RFC and join its discussion.'
+          : 'Discussants can post in this RFC\'s discussion.'}
+      </p>
+      {acceptError && <div className="error-banner">{acceptError}</div>}
+      <p>
+        <button
+          type="button"
+          className="btn-primary"
+          onClick={handleAccept}
+          disabled={accepting}
+        >
+          {accepting ? 'Accepting…' : `Accept and open ${rfc_title}`}
+        </button>
+      </p>
+      <p>
+        <Link to={`/rfc/${rfc_slug}`}>or just read the RFC without accepting</Link>
+      </p>
+    </div>
+  )
+}

frontend/src/components/Admin.jsx

@@ -23,7 +23,15 @@ import {
   listAllowlist,
   addAllowlistEmail,
   removeAllowlistEmail,
+  createUserInvite,
 } from '../api.js'
+import { EVENTS, track } from '../lib/analytics.js'
+
+// v0.17.0 — roadmap item #16. The max length the backend enforces
+// (Pydantic body bound + `invites.CUSTOM_MESSAGE_MAX_LENGTH`); kept
+// here so the modal's "remaining chars" counter stays in lockstep
+// with the server-side bound.
+const CUSTOM_MESSAGE_MAX_LENGTH = 500
 
 const TABS = [
   { path: 'users', label: 'Users' },
@@ -89,6 +97,10 @@ function UsersTab() {
   const [busy, setBusy] = useState({})
   const [error, setError] = useState(null)
   const [stateFilter, setStateFilter] = useState('all')
+  // v0.17.0 — roadmap item #16. The "Create user + invite" modal's
+  // open/closed state. The modal is local to UsersTab (it only opens
+  // from the header button) and refreshes the listing on success.
+  const [inviteModalOpen, setInviteModalOpen] = useState(false)
 
   async function refresh() {
     setError(null)
@@ -133,6 +145,12 @@ function UsersTab() {
     setError(null)
     try {
       await setUserPermission(userId, state)
+      // v0.15.0 — analytics: fire on a successful §6.1 grant/revoke.
+      // action collapses the {pending → granted, revoked → granted}
+      // edges onto `grant`, and `granted → revoked` onto `revoke`,
+      // matching the roadmap's two-arm taxonomy.
+      const action = state === 'granted' ? 'grant' : 'revoke'
+      track(EVENTS.ADMIN_PERMISSION_DECISION, { action, target_user_id: String(userId) })
       // Refresh the full row so permission_decided_{at,by_*} update too.
       await refresh()
     } catch (e) {
@@ -172,8 +190,28 @@ function UsersTab() {
           retain their v0.7.0 semantics — promote to admin to remove a
           user's ability to write without silencing them.
         </p>
+        {/* v0.17.0 — roadmap item #16. The "Create user + invite"
+            affordance opens a modal that provisions a fresh users row
+            with the chosen role and sends an invite email with a
+            single-use claim link. */}
+        <div className="admin-tab-actions">
+          <button
+            type="button"
+            className="btn-primary"
+            onClick={() => setInviteModalOpen(true)}
+          >Create user + invite</button>
+        </div>
       </header>
       {error && <p className="settings-note warning">{error}</p>}
+      {inviteModalOpen && (
+        <CreateUserInviteModal
+          onClose={() => setInviteModalOpen(false)}
+          onSuccess={async () => {
+            setInviteModalOpen(false)
+            await refresh()
+          }}
+        />
+      )}
 
       <div className="admin-filter-chips">
         {STATE_CHIPS.map(chip => (
@@ -224,12 +262,26 @@ function UserRow({ user: u, busy, onChangeRole, onToggleMute, onFlipPermission }
   const state = u.permission_state || 'granted'
   const fullName = [u.first_name, u.last_name].filter(Boolean).join(' ').trim()
   const handle = u.gitea_login ? `@${u.gitea_login}` : (u.email || u.display_name)
+  // v0.17.0 — roadmap item #16. The user's row may also be the
+  // "(pending invite)" shape: admin-created via POST /api/admin/users,
+  // not yet claimed via /api/invites/claim. The backend's user-listing
+  // surfaces this via `pending_invite` (object with invite_id +
+  // expires_at) or null. The badge sits inline next to the handle so
+  // the admin sees at a glance which rows are real users vs. unclaimed
+  // invites.
+  const pendingInvite = u.pending_invite
   return (
     <>
       <tr>
         <td>
           <div className="user-cell">
             <span className="user-handle">{handle}</span>
+            {pendingInvite && (
+              <span
+                className="invite-badge"
+                title={`Admin-created invite; expires ${pendingInvite.expires_at}`}
+              >(pending invite)</span>
+            )}
             <span className="muted">
               {fullName || u.display_name}
               {u.email ? ` · ${u.email}` : ''}
@@ -319,6 +371,173 @@ function PermissionCell({ user: u, busy, onFlipPermission }) {
   )
 }
 
+// ── Create user + invite modal (v0.17.0 / roadmap item #16) ────────────────
+//
+// The "Create user + invite" affordance on the Users tab opens this
+// modal. Admin types email, first name, last name, role, and (optionally)
+// a custom message to embed in the invite email. On submit, calls
+// `POST /api/admin/users` which provisions the row + sends the email.
+// The 409 path (duplicate email) and 422 path (self-invite, owner-
+// grant-by-non-owner, malformed input) surface the server's message
+// inline; the success path closes the modal and refreshes the listing.
+//
+// The modal lives in this file rather than a separate component
+// because it has one caller (UsersTab), reuses the existing modal
+// stylesheet from /admin's chrome, and shares the
+// CUSTOM_MESSAGE_MAX_LENGTH constant defined at the top of the file.
+
+function CreateUserInviteModal({ onClose, onSuccess }) {
+  const [email, setEmail] = useState('')
+  const [firstName, setFirstName] = useState('')
+  const [lastName, setLastName] = useState('')
+  const [role, setRole] = useState('contributor')
+  const [customMessage, setCustomMessage] = useState('')
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState(null)
+  const [success, setSuccess] = useState(null)
+
+  const remaining = CUSTOM_MESSAGE_MAX_LENGTH - customMessage.length
+
+  async function handleSubmit(event) {
+    event.preventDefault()
+    const trimmedEmail = email.trim()
+    if (!trimmedEmail) {
+      setError('Email is required')
+      return
+    }
+    setBusy(true)
+    setError(null)
+    setSuccess(null)
+    try {
+      const result = await createUserInvite({
+        email: trimmedEmail,
+        first_name: firstName.trim(),
+        last_name: lastName.trim(),
+        role,
+        custom_message: customMessage,
+      })
+      // v0.17.0 + #21 Part C — Amplitude wiring. target_user_id is
+      // the OHM user id the invite-create gesture provisioned;
+      // initial_role is what the invitee inherits on claim.
+      // custom_message_chars is a coarse signal of admin effort
+      // (0 = template-only, 1+ = personalized). No PII.
+      track(EVENTS.USER_INVITED, {
+        target_user_id: result.invited_user_id != null
+          ? String(result.invited_user_id) : null,
+        initial_role: result.role,
+        custom_message_chars: (customMessage || '').length,
+      })
+      setSuccess(`Invite sent to ${result.email} (${result.role}).`)
+      // Brief delay so the admin sees the success state, then close
+      // and let the parent refresh the listing.
+      setTimeout(() => { onSuccess?.() }, 600)
+    } catch (e) {
+      setError(e.message || 'Unable to send invite')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <div className="modal-backdrop" onClick={onClose}>
+      <div className="modal-panel" onClick={e => e.stopPropagation()}>
+        <header className="modal-header">
+          <h3>Create user + invite</h3>
+          <button
+            type="button"
+            className="btn-link-quiet"
+            onClick={onClose}
+            disabled={busy}
+            aria-label="Close"
+          >×</button>
+        </header>
+        <p className="muted">
+          Provisions a fresh user row with the chosen role and sends an
+          invite email carrying a single-use claim link. The link
+          expires in 7 days. The invitee clicks through to claim
+          their account — no OTC roundtrip is required on first sign-in.
+        </p>
+        <form onSubmit={handleSubmit} className="create-user-invite-form">
+          <label>
+            <span>Email</span>
+            <input
+              type="email"
+              value={email}
+              onChange={e => setEmail(e.target.value)}
+              required
+              disabled={busy}
+              autoFocus
+              maxLength={320}
+            />
+          </label>
+          <div className="form-row">
+            <label>
+              <span>First name</span>
+              <input
+                type="text"
+                value={firstName}
+                onChange={e => setFirstName(e.target.value)}
+                disabled={busy}
+                maxLength={120}
+              />
+            </label>
+            <label>
+              <span>Last name</span>
+              <input
+                type="text"
+                value={lastName}
+                onChange={e => setLastName(e.target.value)}
+                disabled={busy}
+                maxLength={120}
+              />
+            </label>
+          </div>
+          <label>
+            <span>Role</span>
+            <select
+              value={role}
+              onChange={e => setRole(e.target.value)}
+              disabled={busy}
+            >
+              <option value="contributor">Contributor</option>
+              <option value="admin">Admin</option>
+              <option value="owner">Owner (owner-only)</option>
+            </select>
+          </label>
+          <label>
+            <span>
+              Custom message (optional){' '}
+              <span className={`muted${remaining < 0 ? ' warning' : ''}`}>
+                {remaining} chars left
+              </span>
+            </span>
+            <textarea
+              value={customMessage}
+              onChange={e => setCustomMessage(e.target.value)}
+              disabled={busy}
+              rows={4}
+              maxLength={CUSTOM_MESSAGE_MAX_LENGTH}
+              placeholder="Optional — embedded in the invite email."
+            />
+          </label>
+          {error && <p className="settings-note warning">{error}</p>}
+          {success && <p className="settings-note success">{success}</p>}
+          <div className="modal-actions">
+            <button type="button" onClick={onClose} disabled={busy}>Cancel</button>
+            <button
+              type="submit"
+              className="btn-primary"
+              disabled={busy || !email.trim() || remaining < 0}
+            >
+              {busy ? 'Sending…' : 'Send invite'}
+            </button>
+          </div>
+        </form>
+      </div>
+    </div>
+  )
+}
+
 // ── Private-beta allowlist (`migrations/011_allowlist.sql`) ────────────────
 
 function AllowlistTab() {

frontend/src/components/InvitationsModal.jsx

@@ -0,0 +1,202 @@
+// InvitationsModal.jsx — v0.16.0 / roadmap item #12.
+//
+// The RFC owner's surface for issuing per-RFC invitations and watching
+// who has accepted. Opens from the RFC view's header strip when the
+// viewer is the RFC's owner (or a platform admin/owner). Non-owner
+// viewers never see the trigger.
+//
+// The modal shows two stacked sections:
+//
+//   1. "Invite someone" — email input + role picker
+//      (contributor | discussant) + Send. The send goes through the
+//      backend's POST /api/rfcs/<slug>/invitations, which both writes
+//      the row and dispatches the email to the invitee. Success
+//      refreshes the list below and clears the input.
+//
+//   2. "Existing invitations" — every invitation (pending +
+//      accepted + revoked + expired) on this RFC, with revoke
+//      buttons on the pending ones. The status of each row is the
+//      effective status (the backend recomputes expired-from-pending
+//      at read time so an unattended cron isn't required).
+//
+// No custom-message field — that belongs to item #16's platform-
+// level surface, not here. No bulk-invite — one email at a time
+// keeps the gesture deliberate.
+
+import { useEffect, useState } from 'react'
+import {
+  createRFCInvitation,
+  listRFCInvitations,
+  revokeRFCInvitation,
+} from '../api'
+import { EVENTS, track } from '../lib/analytics'
+
+const ROLE_OPTIONS = [
+  { value: 'contributor', label: 'Contributor — can open PRs and join discussion' },
+  { value: 'discussant', label: 'Discussant — can join discussion only' },
+]
+
+export default function InvitationsModal({ slug, rfcTitle, onClose }) {
+  const [invitations, setInvitations] = useState(null)
+  const [loadError, setLoadError] = useState(null)
+  const [inviteeEmail, setInviteeEmail] = useState('')
+  const [roleInRFC, setRoleInRFC] = useState('contributor')
+  const [submitting, setSubmitting] = useState(false)
+  const [submitError, setSubmitError] = useState(null)
+  const [submitSuccess, setSubmitSuccess] = useState(null)
+  const [revokingId, setRevokingId] = useState(null)
+
+  async function refresh() {
+    setLoadError(null)
+    try {
+      const r = await listRFCInvitations(slug)
+      setInvitations(r.items || [])
+    } catch (e) {
+      setLoadError(e.message)
+    }
+  }
+
+  useEffect(() => { refresh() /* eslint-disable-line react-hooks/exhaustive-deps */ }, [slug])
+
+  async function handleSend(e) {
+    e.preventDefault()
+    const email = inviteeEmail.trim()
+    if (!email) return
+    setSubmitting(true)
+    setSubmitError(null)
+    setSubmitSuccess(null)
+    try {
+      await createRFCInvitation(slug, { inviteeEmail: email, roleInRFC })
+      // v0.16.0 + #21 Part C — Amplitude wiring. No PII (the email
+      // is the inviter's input, not the invitee's identity in our
+      // analytics; we record the rfc_slug + role_in_rfc so a future
+      // invite→accept correlation has both halves).
+      track(EVENTS.INVITATION_SENT, { rfc_slug: slug, role_in_rfc: roleInRFC })
+      setSubmitSuccess(`Invitation sent to ${email}.`)
+      setInviteeEmail('')
+      await refresh()
+    } catch (err) {
+      setSubmitError(err.message || 'Failed to send invitation.')
+    } finally {
+      setSubmitting(false)
+    }
+  }
+
+  async function handleRevoke(invitationId) {
+    setRevokingId(invitationId)
+    try {
+      await revokeRFCInvitation(slug, invitationId)
+      await refresh()
+    } catch (err) {
+      setSubmitError(err.message || 'Failed to revoke invitation.')
+    } finally {
+      setRevokingId(null)
+    }
+  }
+
+  return (
+    <div className="modal-overlay" onClick={e => { if (e.target === e.currentTarget) onClose() }}>
+      <div className="modal" style={{ maxWidth: 640 }}>
+        <div className="modal-header">
+          <h2>Invitations — {rfcTitle || slug}</h2>
+          <button className="modal-close" onClick={onClose}>×</button>
+        </div>
+        <div className="modal-body">
+          <p style={{ marginTop: 0, color: '#666' }}>
+            Invite people by email to contribute PRs against this RFC or to
+            join its discussion. Anyone with the link can read this RFC;
+            this surface controls who can <em>write</em>.
+          </p>
+
+          <form onSubmit={handleSend} className="invitations-form" style={{ marginTop: 16 }}>
+            <label htmlFor="invitee-email">Invitee email</label>
+            <input
+              id="invitee-email"
+              type="email"
+              value={inviteeEmail}
+              onChange={e => setInviteeEmail(e.target.value)}
+              placeholder="someone@example.com"
+              autoFocus
+              required
+            />
+            <label htmlFor="invitee-role" style={{ marginTop: 10 }}>Role on this RFC</label>
+            <select
+              id="invitee-role"
+              value={roleInRFC}
+              onChange={e => setRoleInRFC(e.target.value)}
+            >
+              {ROLE_OPTIONS.map(opt => (
+                <option key={opt.value} value={opt.value}>{opt.label}</option>
+              ))}
+            </select>
+            <div style={{ marginTop: 12, display: 'flex', gap: 8, alignItems: 'center' }}>
+              <button type="submit" className="btn-primary" disabled={submitting}>
+                {submitting ? 'Sending…' : 'Send invitation'}
+              </button>
+              {submitError && <span style={{ color: '#c33' }}>{submitError}</span>}
+              {submitSuccess && <span style={{ color: '#383' }}>{submitSuccess}</span>}
+            </div>
+          </form>
+
+          <hr style={{ margin: '20px 0' }} />
+
+          <h3 style={{ margin: '0 0 8px' }}>Existing invitations</h3>
+          {loadError && <div className="error-banner">{loadError}</div>}
+          {invitations === null && <div>Loading…</div>}
+          {invitations !== null && invitations.length === 0 && (
+            <div style={{ color: '#666' }}>No invitations have been sent yet.</div>
+          )}
+          {invitations !== null && invitations.length > 0 && (
+            <table style={{ width: '100%', borderCollapse: 'collapse' }}>
+              <thead>
+                <tr>
+                  <th style={{ textAlign: 'left', padding: 4 }}>Email</th>
+                  <th style={{ textAlign: 'left', padding: 4 }}>Role</th>
+                  <th style={{ textAlign: 'left', padding: 4 }}>Status</th>
+                  <th style={{ textAlign: 'left', padding: 4 }}>Sent</th>
+                  <th style={{ padding: 4 }}></th>
+                </tr>
+              </thead>
+              <tbody>
+                {invitations.map(inv => (
+                  <tr key={inv.id} style={{ borderTop: '1px solid #eee' }}>
+                    <td style={{ padding: 4 }}>{inv.invitee_email}</td>
+                    <td style={{ padding: 4 }}>{inv.role_in_rfc}</td>
+                    <td style={{ padding: 4 }}>
+                      <span className={`invitation-status status-${inv.status}`}>
+                        {inv.status}
+                      </span>
+                      {inv.status === 'accepted' && inv.accepted_by_display && (
+                        <span style={{ color: '#666', marginLeft: 6 }}>
+                          by {inv.accepted_by_display}
+                        </span>
+                      )}
+                    </td>
+                    <td style={{ padding: 4, color: '#666' }}>
+                      {inv.created_at?.slice(0, 10) || ''}
+                    </td>
+                    <td style={{ padding: 4, textAlign: 'right' }}>
+                      {inv.status === 'pending' && (
+                        <button
+                          type="button"
+                          className="btn-link"
+                          onClick={() => handleRevoke(inv.id)}
+                          disabled={revokingId === inv.id}
+                        >
+                          {revokingId === inv.id ? 'Revoking…' : 'Revoke'}
+                        </button>
+                      )}
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          )}
+        </div>
+        <div className="modal-footer">
+          <button type="button" className="btn-link" onClick={onClose}>Close</button>
+        </div>
+      </div>
+    </div>
+  )
+}

frontend/src/components/InviteClaim.jsx

@@ -0,0 +1,173 @@
+// v0.17.0 — roadmap item #16. The claim flow's landing page.
+//
+// The admin's invite email carries a link to /invites/claim?token=…;
+// the invitee clicks through and lands here. The page reads the
+// token from the URL, posts it to /api/invites/claim, and on success
+// routes either to the passcode-set screen (if v0.10.0 passcode flow
+// is in play and the user has no passcode yet) or to home.
+//
+// Anonymous-reachable: the entire point of the call is to establish
+// the session; we do not pre-check authentication.
+//
+// Failure modes the backend distinguishes:
+//   * 410 — token is expired or already claimed (the row is dead).
+//   * 400 — token doesn't match any active invite (forged, revoked,
+//     or wiped).
+//
+// We surface both as the same "this invite link isn't valid" shape
+// for the invitee — the detail message from the server reads
+// distinctively enough that the admin can debug from logs, and the
+// invitee just needs to know they should contact the admin for a
+// fresh link.
+
+import { useEffect, useState } from 'react'
+import { useLocation, useNavigate } from 'react-router-dom'
+import { claimInvite } from '../api.js'
+import { EVENTS, identify, track } from '../lib/analytics.js'
+
+export default function InviteClaim() {
+  const location = useLocation()
+  const navigate = useNavigate()
+  const [status, setStatus] = useState('working') // 'working' | 'ok' | 'failed'
+  const [error, setError] = useState(null)
+  const [trustDevice, setTrustDevice] = useState(false)
+  const [submitted, setSubmitted] = useState(false)
+  const [user, setUser] = useState(null)
+  const [needsPasscode, setNeedsPasscode] = useState(false)
+
+  const params = new URLSearchParams(location.search)
+  const token = params.get('token') || ''
+
+  async function performClaim() {
+    if (!token) {
+      setStatus('failed')
+      setError('No invite token in the URL.')
+      return
+    }
+    setSubmitted(true)
+    setStatus('working')
+    setError(null)
+    try {
+      const result = await claimInvite(token, { trustDevice })
+      setUser(result.user)
+      setNeedsPasscode(!!result.needs_passcode)
+      // v0.17.0 + #21 Part C — identify the new user with their OHM
+      // user_id BEFORE firing any track() event, so the Amplitude
+      // user record is created with the OHM id from the first event
+      // rather than as an anonymous device that retroactively links.
+      // setOnce on invited_at + invited_by_admin_id + initial_role so
+      // these are immutable user-history markers on the Amplitude
+      // record.
+      if (result.user?.id != null) {
+        const setOnceProps = {
+          claim_method: 'admin-invite',
+        }
+        if (result.invited_at) setOnceProps.invited_at = ['__setOnce__', result.invited_at]
+        if (result.invited_by_admin_id != null) {
+          setOnceProps.invited_by_admin_id = ['__setOnce__', String(result.invited_by_admin_id)]
+        }
+        if (result.user.role) setOnceProps.initial_role = ['__setOnce__', result.user.role]
+        identify({
+          user_id: String(result.user.id),
+          properties: setOnceProps,
+        })
+      }
+      track(EVENTS.INVITE_CLAIMED, {
+        invited_by_admin_id: result.invited_by_admin_id != null
+          ? String(result.invited_by_admin_id) : null,
+        initial_role: result.user?.role,
+        needs_passcode: !!result.needs_passcode,
+        trust_device: trustDevice,
+      })
+      setStatus('ok')
+    } catch (e) {
+      setStatus('failed')
+      setError(e.message || 'Unable to claim invite')
+    }
+  }
+
+  // Pre-flight: if the URL has no token at all, fail fast so the
+  // invitee sees the missing-token shape immediately rather than
+  // an empty form.
+  useEffect(() => {
+    if (!token) {
+      setStatus('failed')
+      setError('This claim link is missing its token.')
+    }
+  }, [token])
+
+  // On a successful claim, route the user onward. The brief calls
+  // this out: route to passcode-set if v0.10.0 passcode flow is in
+  // play and the user has no passcode yet; otherwise route to home.
+  useEffect(() => {
+    if (status !== 'ok') return
+    const timeout = setTimeout(() => {
+      if (needsPasscode) {
+        navigate('/settings/notifications#sign-in', { replace: true })
+      } else {
+        navigate('/', { replace: true })
+      }
+    }, 1200)
+    return () => clearTimeout(timeout)
+  }, [status, needsPasscode, navigate])
+
+  return (
+    <div className="invite-claim-page">
+      <div className="invite-claim-panel">
+        <h1>Claim your account</h1>
+        {!submitted && status === 'working' && token && (
+          <>
+            <p>
+              You've been invited to this deployment. Click the button below
+              to claim your account and sign in. This link is single-use and
+              expires 7 days after it was sent.
+            </p>
+            <label className="claim-trust-toggle">
+              <input
+                type="checkbox"
+                checked={trustDevice}
+                onChange={e => setTrustDevice(e.target.checked)}
+              />
+              {' '}Trust this device for 30 days (skip the email step on
+              your next visit from this browser).
+            </label>
+            <div className="claim-actions">
+              <button
+                type="button"
+                className="btn-primary"
+                onClick={performClaim}
+              >Claim my account</button>
+            </div>
+          </>
+        )}
+        {submitted && status === 'working' && (
+          <p>Claiming…</p>
+        )}
+        {status === 'ok' && (
+          <>
+            <p className="settings-note success">
+              Welcome{user?.display_name ? `, ${user.display_name}` : ''}!
+              You're signed in.
+            </p>
+            <p className="muted">
+              {needsPasscode
+                ? 'Redirecting you to set a passcode so you can sign in without an email roundtrip next time…'
+                : 'Redirecting you to the home page…'}
+            </p>
+          </>
+        )}
+        {status === 'failed' && (
+          <>
+            <p className="settings-note warning">
+              {error || "This invite link isn't valid."}
+            </p>
+            <p className="muted">
+              If you believe this is a mistake, contact the admin who
+              sent you the invite — they can issue a fresh link.
+            </p>
+          </>
+        )}
+      </div>
+    </div>
+  )
+}

frontend/src/components/Login.jsx

@@ -1,7 +1,17 @@
-// Login.jsx — the composed sign-in surface (§6.2) after the v0.10.0
-// (passcodes, roadmap item #8) rebase onto v0.8.0 (beta-access-request
-// capture, §6.1 / §14.1, roadmap item #6). v0.7.0 (roadmap item #5)
-// established the email + OTC scaffolding both releases extended.
+// Login.jsx — the composed sign-in surface (§6.2) after the v0.12.0
+// (CloudFlare Turnstile gate on OTC dispatch, roadmap item #10) /
+// v0.10.0 (passcodes, roadmap item #8) rebase onto v0.8.0
+// (beta-access-request capture, §6.1 / §14.1, roadmap item #6). v0.7.0
+// (roadmap item #5) established the email + OTC scaffolding the later
+// releases extended.
+//
+// v0.12.0: the email-entry step renders a Turnstile widget. The token
+// it produces is sent to `/auth/otc/request` alongside the email. The
+// passcode step also renders a widget for the "Use a code instead"
+// fallback dispatch (same backend endpoint, same gate). When the
+// `VITE_TURNSTILE_SITE_KEY` build var is unset, the widget renders
+// nothing — the form still submits and the backend's TURNSTILE_REQUIRED
+// policy decides admission.
 //
 // Four-to-six-step flow (most users see three; the longest path is
 // pending-user with no passcode, who never sees the passcode steps):
@@ -72,7 +82,10 @@ import {
   checkPasscode,
   verifyPasscode,
   setPasscode as apiSetPasscode,
+  startDeviceTrust,
 } from '../api'
+import TurnstileWidget, { turnstileEnabled } from './TurnstileWidget'
+import { EVENTS, track } from '../lib/analytics'
 
 export default function Login() {
   // Steps: 'email' → 'passcode' or 'code' → (on the OTC path, after
@@ -84,12 +97,31 @@ export default function Login() {
   const [code, setCode] = useState('')
   const [passcode, setPasscode] = useState('')
   const [newPasscode, setNewPasscode] = useState('')
+  // v0.11.0 — "trust this device for 30 days" checkbox, shared by the
+  // OTC and passcode verify steps. The flag rides on the verify POST;
+  // a checked box mints a device-trust row server-side and sets the
+  // long-lived `rfc_device_trust` cookie. Defaults off so the user
+  // makes an explicit choice — auth credentials shouldn't persist by
+  // default.
+  const [trustDevice, setTrustDevice] = useState(false)
   // v0.8.0 — capture-profile fields.
   const [firstName, setFirstName] = useState('')
   const [lastName, setLastName] = useState('')
   const [reason, setReason] = useState('')
   const [status, setStatus] = useState('')
   const [busy, setBusy] = useState(false)
+  // v0.12.0: Turnstile token captured by the widget. `null` means no
+  // challenge solved yet (or the site key is unset, in which case the
+  // widget surfaces null on mount). The token is single-use; we clear
+  // it back to null right after we send it so a second request on the
+  // same form remount re-challenges. `turnstileReady` is true once the
+  // widget has produced a token OR the widget is not configured at
+  // build time (no site key) — the submit button reads from it so the
+  // form locks up when the operator has wired Turnstile but the user
+  // hasn't solved the challenge yet.
+  const [turnstileToken, setTurnstileToken] = useState(null)
+  const turnstileOn = turnstileEnabled()
+  const turnstileReady = !turnstileOn || !!turnstileToken
   const emailRef = useRef(null)
   const codeRef = useRef(null)
   const passcodeRef = useRef(null)
@@ -105,6 +137,33 @@ export default function Login() {
     else if (step === 'set-passcode') newPasscodeRef.current?.focus()
   }, [step])
 
+  // v0.11.0 — on mount, try the device-trust cookie path. If the
+  // browser still carries a valid `rfc_device_trust` cookie from a
+  // prior "trust this device" gesture, the server re-establishes the
+  // session without any user input and we redirect home. The cookie
+  // is HttpOnly so we can't peek at it; we just call the endpoint and
+  // see whether it returns 200. 401 (no cookie / invalid / revoked)
+  // is the structural-silent case — the user proceeds to the email
+  // step normally. We do not surface any UI about the attempt; a
+  // failure should be invisible.
+  useEffect(() => {
+    let cancelled = false
+    ;(async () => {
+      try {
+        await startDeviceTrust()
+        if (!cancelled) {
+          // v0.15.0 — analytics: device-trust cookie path is one of
+          // three sign-in methods the taxonomy distinguishes.
+          track(EVENTS.USER_SIGNED_IN, { method: 'trust-device' })
+          window.location.assign('/')
+        }
+      } catch (_) {
+        // No trusted device — fall through to the email step.
+      }
+    })()
+    return () => { cancelled = true }
+  }, [])
+
   async function submitEmail(e) {
     e.preventDefault()
     if (!email.trim() || !email.includes('@')) {
@@ -119,13 +178,22 @@ export default function Login() {
         setStep('passcode')
         setStatus('')
       } else {
-        await requestOtc(email.trim())
+        await requestOtc(email.trim(), { turnstileToken })
+        // v0.12.0: the token is single-use; drop it so a re-request
+        // from the code step (via "Use a different email" → back to
+        // email) starts with a fresh challenge.
+        setTurnstileToken(null)
         setStep('code')
         setStatus('Check your inbox — a six-digit code is on the way.')
       }
     } catch (err) {
+      // Any failure consumes the token from CloudFlare's side; clear
+      // so the widget re-renders a fresh challenge on retry.
+      setTurnstileToken(null)
       if (err.status === 429) {
         setStatus('Slow down — wait a minute before requesting another code.')
+      } else if (err.status === 400) {
+        setStatus("Couldn't verify you're human. Please retry the challenge.")
       } else {
         setStatus(err.message || 'Could not start sign-in. Try again.')
       }
@@ -143,7 +211,11 @@ export default function Login() {
     setBusy(true)
     setStatus('')
     try {
-      await verifyPasscode(email.trim(), passcode.trim())
+      await verifyPasscode(email.trim(), passcode.trim(), { trustDevice })
+      // v0.15.0 — analytics: passcode is the second of three
+      // sign-in methods. trust-device gets credited separately when
+      // the cookie-driven path fires above.
+      track(EVENTS.USER_SIGNED_IN, { method: 'passcode' })
       // Reload so App.jsx's getMe() picks up the fresh session. A
       // returning passcode user is by definition already past the
       // §6.1 capture step (they couldn't have set a passcode while
@@ -156,17 +228,29 @@ export default function Login() {
         // fresh code in the user's inbox immediately.
         setPasscode('')
         try {
-          await requestOtc(email.trim())
+          // v0.12.0: pass whatever token the widget on the passcode
+          // step has produced. If the operator has Turnstile required
+          // and the user hasn't solved the passcode-step widget, the
+          // backend refuses and we bounce them back to email-entry
+          // with a clear status (see catch below).
+          await requestOtc(email.trim(), { turnstileToken })
+          setTurnstileToken(null)
           setStep('code')
           setStatus(
             'Too many failed attempts. We sent a one-time code to your email — use it to sign in.',
           )
         } catch (e2) {
+          setTurnstileToken(null)
           if (e2.status === 429) {
             setStep('code')
             setStatus(
               'Too many failed attempts. Wait a minute, then request a one-time code to sign in.',
             )
+          } else if (e2.status === 400) {
+            setStep('email')
+            setStatus(
+              'Too many failed attempts. Solve the challenge below to receive a one-time code.',
+            )
           } else {
             setStatus(
               'Too many failed attempts. Use the "Use a code instead" link to sign in via email.',
@@ -189,7 +273,12 @@ export default function Login() {
     setBusy(true)
     setStatus('')
     try {
-      await verifyOtc(email.trim(), code.trim())
+      await verifyOtc(email.trim(), code.trim(), { trustDevice })
+      // v0.15.0 — analytics: OTC is the third sign-in method.
+      // We fire it here regardless of whether the user then lands
+      // in capture-profile or offer-passcode — sign-in has happened
+      // server-side either way.
+      track(EVENTS.USER_SIGNED_IN, { method: 'otc' })
       // OTC verified — the server has signed in the user. Fetch the
       // canonical /api/auth/me to decide where to land:
       //   * needs_profile  → §6.1 capture (then /beta-pending).
@@ -246,6 +335,11 @@ export default function Login() {
         last_name: ln,
         beta_request_reason: why,
       })
+      // v0.15.0 — analytics: a successful capture-profile submit is
+      // the moment a beta-access request lands. No PII in the event
+      // body (no name, no reason text); the count + timestamp is
+      // what the funnel needs.
+      track(EVENTS.BETA_ACCESS_REQUESTED)
       // Hard-load so App.jsx re-fetches /api/auth/me and picks up
       // the captured fields. The user stays permission_state='pending'
       // until an admin grants access — the next thing they should
@@ -314,17 +408,27 @@ export default function Login() {
 
   async function fallbackToOtc() {
     // Manual "Use a code instead" from the passcode step. Same shape
-    // as the email-step OTC dispatch.
+    // as the email-step OTC dispatch. v0.12.0: pass through whatever
+    // Turnstile token the passcode-step widget has produced (or null
+    // when the widget is disabled at build time).
     setBusy(true)
     setStatus('')
     try {
-      await requestOtc(email.trim())
+      await requestOtc(email.trim(), { turnstileToken })
+      setTurnstileToken(null)
       setPasscode('')
       setStep('code')
       setStatus('Check your inbox — a six-digit code is on the way.')
     } catch (err) {
+      setTurnstileToken(null)
       if (err.status === 429) {
         setStatus('Slow down — wait a minute before requesting another code.')
+      } else if (err.status === 400) {
+        // v0.12.0: the widget rejected or no token was sent. Bounce
+        // the user back to the email step so they get a fresh
+        // challenge alongside the email input.
+        setStep('email')
+        setStatus("Couldn't verify you're human. Please retry the challenge.")
       } else {
         setStatus(err.message || 'Could not request a code. Try again.')
       }
@@ -357,7 +461,18 @@ export default function Login() {
               required
               disabled={busy}
             />
-            <button type="submit" disabled={busy || !email.trim()}>
+            {/*
+              v0.12.0: CloudFlare Turnstile widget. Renders nothing
+              when VITE_TURNSTILE_SITE_KEY is unset (and turnstileReady
+              defaults to true in that case so the submit gate doesn't
+              lock up). On every challenge the widget calls onToken
+              with the fresh token; we feed it to /auth/otc/request.
+            */}
+            <TurnstileWidget onToken={setTurnstileToken} />
+            <button
+              type="submit"
+              disabled={busy || !email.trim() || !turnstileReady}
+            >
               {busy ? 'Checking…' : 'Continue'}
             </button>
           </form>
@@ -378,6 +493,30 @@ export default function Login() {
               required
               disabled={busy}
             />
+            {/* v0.11.0 — trust device for 30 days. The checkbox lives
+                on the verify step so the user makes the trust gesture
+                in the same breath as signing in. Off by default; the
+                user opts in deliberately. */}
+            <label className="otc-trust-device">
+              <input
+                type="checkbox"
+                checked={trustDevice}
+                onChange={e => setTrustDevice(e.target.checked)}
+                disabled={busy}
+              />
+              <span>Trust this device for 30 days</span>
+            </label>
+            {/*
+              v0.12.0: a second Turnstile widget for the
+              "Use a code instead" fallback dispatch. The passcode
+              verify path does not consume a Turnstile token (it has
+              its own 5-attempt lockout shape from v0.10.0), but if
+              the user falls back to OTC the same /auth/otc/request
+              endpoint runs and needs a token. We render the widget
+              on this step too so the fallback works without bouncing
+              back to email-entry first.
+            */}
+            <TurnstileWidget onToken={setTurnstileToken} />
             <div className="otc-actions">
               <button type="submit" disabled={busy || !passcode.trim()}>
                 {busy ? 'Signing in…' : 'Sign in'}
@@ -386,7 +525,7 @@ export default function Login() {
                 type="button"
                 className="btn-link-quiet"
                 onClick={fallbackToOtc}
-                disabled={busy}
+                disabled={busy || !turnstileReady}
               >
                 Use a code instead
               </button>
@@ -420,6 +559,17 @@ export default function Login() {
               required
               disabled={busy}
             />
+            {/* v0.11.0 — trust device for 30 days. Same shape as the
+                passcode step; the user opts in deliberately. */}
+            <label className="otc-trust-device">
+              <input
+                type="checkbox"
+                checked={trustDevice}
+                onChange={e => setTrustDevice(e.target.checked)}
+                disabled={busy}
+              />
+              <span>Trust this device for 30 days</span>
+            </label>
             <div className="otc-actions">
               <button type="submit" disabled={busy || code.length !== 6}>
                 {busy ? 'Signing in…' : 'Sign in'}

frontend/src/components/NotificationSettings.jsx

@@ -32,6 +32,9 @@ import {
   getMe,
   setPasscode,
   clearPasscode,
+  listMyDevices,
+  revokeMyDevice,
+  revokeAllMyDevices,
 } from '../api.js'
 import { getConsent, onConsentChange, hydrateFromServer } from '../lib/consent.js'
 
@@ -54,11 +57,126 @@ export default function NotificationSettings({ viewer }) {
       <WatchesSection />
       <MutesSection viewer={viewer} />
       <SignInSection />
+      <DevicesSection />
       <PrivacyCookiesSection />
     </div>
   )
 }
 
+// ── v0.11.0: trusted devices (§6.2, roadmap item #9) ──────────────────────
+//
+// Lists the user's active device-trust rows and lets them revoke any
+// or all. A revoke marks the row dead server-side; the matching
+// device's next visit will be refused and the cookie cleared. The
+// surface intentionally does not single out the row whose cookie the
+// current request carries — every row reads identically, so the user
+// can revoke "this device" alongside any other from a single page.
+
+function DevicesSection() {
+  const [devices, setDevices] = useState(null)
+  const [error, setError] = useState(null)
+  const [busy, setBusy] = useState(false)
+
+  useEffect(() => {
+    refresh()
+  }, [])
+
+  async function refresh() {
+    try {
+      const { items } = await listMyDevices()
+      setDevices(items || [])
+      setError(null)
+    } catch (e) {
+      setError(e.message || 'Could not load trusted devices.')
+    }
+  }
+
+  async function onRevoke(deviceId) {
+    setBusy(true)
+    try {
+      await revokeMyDevice(deviceId)
+      await refresh()
+    } catch (e) {
+      setError(e.message || 'Could not revoke device.')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  async function onRevokeAll() {
+    if (!confirm('Revoke trust on every device, including this one? You will be asked to sign in via email next time.')) {
+      return
+    }
+    setBusy(true)
+    try {
+      await revokeAllMyDevices()
+      await refresh()
+    } catch (e) {
+      setError(e.message || 'Could not revoke devices.')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <SectionShell
+      title="Trusted devices"
+      subtitle="Devices where you've checked “Trust this device for 30 days.” Sign-in is automatic on these devices until the trust expires or you revoke it."
+    >
+      {devices === null && <p className="settings-note">Loading…</p>}
+      {devices !== null && devices.length === 0 && (
+        <p className="device-empty">
+          No trusted devices. Sign in and check “Trust this device for 30 days”
+          to add the device you're on now.
+        </p>
+      )}
+      {devices !== null && devices.length > 0 && (
+        <>
+          <ul className="device-list">
+            {devices.map(d => (
+              <li key={d.id} className="device-list-item">
+                <div className="device-meta">
+                  <div className="device-ua">{d.user_agent || 'Unknown device'}</div>
+                  <div className="device-stamps">
+                    Trusted {formatStamp(d.created_at)} · last seen {formatStamp(d.last_seen_at)} · expires {formatStamp(d.expires_at)}
+                  </div>
+                </div>
+                <button
+                  type="button"
+                  onClick={() => onRevoke(d.id)}
+                  disabled={busy}
+                  title="Revoke trust on this device"
+                >
+                  Revoke
+                </button>
+              </li>
+            ))}
+          </ul>
+          <button
+            type="button"
+            className="device-revoke-all"
+            onClick={onRevokeAll}
+            disabled={busy}
+          >
+            Revoke all devices
+          </button>
+        </>
+      )}
+      {error && <p className="settings-note warning">{error}</p>}
+    </SectionShell>
+  )
+}
+
+function formatStamp(stamp) {
+  // The server emits SQLite `datetime('now')` strings (UTC, no
+  // timezone marker). Parse defensively; fall back to the raw stamp
+  // if Date can't make sense of it.
+  if (!stamp) return '—'
+  const d = new Date(stamp.replace(' ', 'T') + 'Z')
+  if (Number.isNaN(d.getTime())) return stamp
+  return d.toLocaleString()
+}
+
 // ── §6.2 sign-in (v0.10.0 / roadmap item #8): passcode management ──────────
 
 function SignInSection() {

frontend/src/components/PRModal.jsx

@@ -10,6 +10,7 @@
 
 import { useEffect, useState } from 'react'
 import { draftPRText, openPR } from '../api'
+import { EVENTS, track } from '../lib/analytics'
 
 export default function PRModal({ slug, branch, branchIsPrivate, onClose, onOpened }) {
   const [title, setTitle] = useState('')
@@ -39,6 +40,9 @@ export default function PRModal({ slug, branch, branchIsPrivate, onClose, onOpen
     setError(null)
     try {
       const { pr_number } = await openPR(slug, branch, { title: title.trim(), description: description.trim() })
+      // v0.15.0 — analytics: fire on §10.2 PR-open success. slug
+      // and pr_number are the join keys; title/description stay out.
+      track(EVENTS.PR_OPENED, { rfc_slug: slug, pr_number })
       onOpened?.(pr_number)
     } catch (e) {
       setError(e.message)

frontend/src/components/PRView.jsx

@@ -22,6 +22,7 @@ import {
   startResolutionBranch,
   withdrawPR,
 } from '../api'
+import { EVENTS, track } from '../lib/analytics'
 
 export default function PRView({ viewer }) {
   const { slug, prNumber: prNumberParam } = useParams()
@@ -135,6 +136,10 @@ export default function PRView({ viewer }) {
         anchorPayload: reviewDraft?.anchorPayload || {},
         quote: reviewDraft?.quote || null,
       })
+      // v0.15.0 — analytics: fire on §10.4 review-comment success.
+      // surface=pr distinguishes this from RFC discussion comments.
+      // No body text or quote material in the event.
+      track(EVENTS.COMMENT_POSTED, { rfc_slug: slug, pr_number: prNumber, surface: 'pr' })
       setReviewText('')
       setReviewDraft(null)
       await refresh()

frontend/src/components/ProposeModal.jsx

@@ -11,6 +11,7 @@
 
 import { useEffect, useState } from 'react'
 import { proposeRFC } from '../api'
+import { EVENTS, track } from '../lib/analytics'
 
 function slugify(title) {
   return title
@@ -52,6 +53,10 @@ export default function ProposeModal({ viewer, onClose, onSubmitted }) {
         pitch: pitch.trim(),
         tags,
       })
+      // v0.15.0 — analytics: fire on the §9.1 propose-RFC submit.
+      // Slug is a stable, low-cardinality identifier (kebab-case
+      // ascii); title and pitch stay out of the event body.
+      track(EVENTS.RFC_PROPOSED, { rfc_slug: slug })
       onSubmitted?.(result)
     } catch (err) {
       setError(err.message || 'Submission failed.')

frontend/src/components/RFCDiscussionPanel.jsx

@@ -18,6 +18,7 @@ import {
   postDiscussionMessage,
   resolveDiscussionThread,
 } from '../api'
+import { EVENTS, track } from '../lib/analytics'
 
 export default function RFCDiscussionPanel({ slug, viewer }) {
   const [threads, setThreads] = useState([])
@@ -100,6 +101,10 @@ export default function RFCDiscussionPanel({ slug, viewer }) {
         void message_id
       }
       setComposer('')
+      // v0.15.0 — analytics: fire on a successful discussion post.
+      // surface=discussion distinguishes this from PR review comments
+      // which fire from PRView with surface=pr. No body text.
+      track(EVENTS.COMMENT_POSTED, { rfc_slug: slug, surface: 'discussion' })
     } catch (err) {
       setError(err.message)
     } finally {

frontend/src/components/RFCView.jsx

@@ -43,7 +43,9 @@ import RFCDiscussionPanel from './RFCDiscussionPanel.jsx'
 import ChangePanel, { diffWords } from './ChangePanel.jsx'
 import PRModal from './PRModal.jsx'
 import GraduateDialog from './GraduateDialog.jsx'
+import InvitationsModal from './InvitationsModal.jsx'
 import { claimOwnership } from '../api'
+import { EVENTS, track } from '../lib/analytics'
 
 const MANUAL_IDLE_MS = 5 * 60 * 1000   // §8.6 idle window; exact value is impl detail.
 const MANUAL_DEBOUNCE_MS = 800
@@ -121,7 +123,15 @@ export default function RFCView({ viewer }) {
   const [drawerOpen, setDrawerOpen] = useState(false)
 
   useEffect(() => {
-    getRFC(slug).then(setEntry).catch(err => setError(err.message))
+    getRFC(slug).then(entry => {
+      setEntry(entry)
+      // v0.15.0 — analytics: fire RFC Viewed once per slug load.
+      // We key on the slug param rather than the loaded entry so a
+      // re-render doesn't double-fire; the slug is the stable
+      // identifier. id is included for join-friendliness in the
+      // Amplitude dashboard.
+      track(EVENTS.RFC_VIEWED, { rfc_slug: slug, rfc_id: entry?.id })
+    }).catch(err => setError(err.message))
     listModels(slug)
       .then(({ models, default: def }) => {
         setModels(models || [])
@@ -139,6 +149,11 @@ export default function RFCView({ viewer }) {
   const [showMetadataPane, setShowMetadataPane] = useState(false)
   const [showGraduateDialog, setShowGraduateDialog] = useState(false)
   const [claimError, setClaimError] = useState(null)
+  // v0.16.0 (item #12): the per-RFC invitations modal. Visible only to
+  // RFC owners (frontmatter) and platform admin/owner — the backend
+  // gates the underlying endpoints regardless, so a leaked toggle
+  // can't actually leak anything.
+  const [showInvitationsModal, setShowInvitationsModal] = useState(false)
 
   // Load main view + branch view whenever slug/branch changes.
   useEffect(() => {
@@ -624,6 +639,20 @@ export default function RFCView({ viewer }) {
               Graduate to RFC repo
             </button>
           )}
+          {/* v0.16.0 (item #12): owner-only invitations affordance.
+              Shown when the viewer is named in the RFC's frontmatter
+              `owners` list or holds a platform admin/owner role.
+              Available on both super-drafts and active RFCs. */}
+          {viewer && (viewer.role === 'owner' || viewer.role === 'admin' || (entry?.owners || []).includes(viewer.gitea_login)) && (
+            <button
+              type="button"
+              className="btn-link"
+              onClick={() => setShowInvitationsModal(true)}
+              title="Invite collaborators to this RFC"
+            >
+              Invitations
+            </button>
+          )}
         </div>
       </div>
       {claimError && (
@@ -856,6 +885,14 @@ export default function RFCView({ viewer }) {
         />
       )}
 
+      {showInvitationsModal && (
+        <InvitationsModal
+          slug={slug}
+          rfcTitle={entry?.title}
+          onClose={() => setShowInvitationsModal(false)}
+        />
+      )}
+
       {showMetadataPane && (
         <MetadataPaneModal
           slug={slug}

frontend/src/components/TurnstileWidget.jsx

@@ -0,0 +1,120 @@
+// TurnstileWidget.jsx — v0.12.0 / roadmap item #10.
+//
+// Renders the CloudFlare Turnstile JS widget on the email-entry step of
+// `/login`. Reads the site key from `import.meta.env.VITE_TURNSTILE_SITE_KEY`
+// (Vite convention — VITE_* prefix is build-time embedded). When the
+// site key is unset/empty, this component renders nothing and reports
+// a `null` token through `onToken` so the parent form can still submit.
+// The backend's `TURNSTILE_REQUIRED` policy decides what happens to a
+// request that arrives without a token; the frontend is intentionally
+// not in that loop. See `backend/app/turnstile.py` for the matrix.
+//
+// The CloudFlare script is loaded once per page on first widget mount.
+// Subsequent mounts (e.g. user goes back to email-entry after a failed
+// OTC request) reuse the script tag and re-render the widget on the
+// fresh container `div`. Unmounting removes the widget instance via
+// `turnstile.remove(widgetId)` so a remount produces a new challenge
+// rather than reusing a stale, already-consumed token.
+//
+// Turnstile contract:
+//   * `data-callback` fires with the token string on a successful
+//     challenge; the token is single-use and expires after ~5 minutes.
+//   * `data-error-callback` fires on a failed challenge (network,
+//     blocked, etc.); we surface a `null` token so the parent shows
+//     a retry hint.
+//   * `data-expired-callback` fires when the token times out before
+//     submission; we also drop to `null` and re-render so the user
+//     gets a fresh challenge on retry.
+//
+// We do **not** import the CloudFlare script at build time; loading it
+// dynamically here keeps the bundle clean of an external request the
+// page may not need (anonymous viewers reading RFCs never see Login).
+
+import { useEffect, useRef } from 'react'
+
+const TURNSTILE_SCRIPT_URL = 'https://challenges.cloudflare.com/turnstile/v0/api.js'
+const SITE_KEY = import.meta.env.VITE_TURNSTILE_SITE_KEY || ''
+
+// Promise-keyed: only one script tag, only one resolution chain.
+let scriptLoadPromise = null
+
+function loadTurnstileScript() {
+  if (typeof window === 'undefined') return Promise.resolve(null)
+  if (window.turnstile) return Promise.resolve(window.turnstile)
+  if (scriptLoadPromise) return scriptLoadPromise
+
+  scriptLoadPromise = new Promise((resolve, reject) => {
+    const existing = document.querySelector(`script[src="${TURNSTILE_SCRIPT_URL}"]`)
+    if (existing) {
+      existing.addEventListener('load', () => resolve(window.turnstile))
+      existing.addEventListener('error', reject)
+      return
+    }
+    const script = document.createElement('script')
+    script.src = TURNSTILE_SCRIPT_URL
+    script.async = true
+    script.defer = true
+    script.addEventListener('load', () => resolve(window.turnstile))
+    script.addEventListener('error', reject)
+    document.head.appendChild(script)
+  })
+  return scriptLoadPromise
+}
+
+export function turnstileEnabled() {
+  return !!SITE_KEY
+}
+
+export default function TurnstileWidget({ onToken, theme = 'auto' }) {
+  const containerRef = useRef(null)
+  const widgetIdRef = useRef(null)
+
+  useEffect(() => {
+    if (!SITE_KEY) {
+      // No site key configured → surface a null token immediately so
+      // the parent form's submit-disabled gate doesn't lock up
+      // waiting on a challenge that will never arrive. The backend
+      // decides whether a tokenless request is admitted.
+      onToken?.(null)
+      return undefined
+    }
+
+    let cancelled = false
+    loadTurnstileScript()
+      .then(turnstile => {
+        if (cancelled || !turnstile || !containerRef.current) return
+        widgetIdRef.current = turnstile.render(containerRef.current, {
+          sitekey: SITE_KEY,
+          theme,
+          callback: token => onToken?.(token),
+          'error-callback': () => onToken?.(null),
+          'expired-callback': () => onToken?.(null),
+        })
+      })
+      .catch(() => {
+        // Script load failure — surface null so the parent can decide
+        // what to do (today: still let submit through; the backend
+        // policy decides admission).
+        if (!cancelled) onToken?.(null)
+      })
+
+    return () => {
+      cancelled = true
+      if (widgetIdRef.current && window.turnstile) {
+        try {
+          window.turnstile.remove(widgetIdRef.current)
+        } catch (_) {
+          // Already gone or never registered — nothing to clean up.
+        }
+        widgetIdRef.current = null
+      }
+    }
+    // We intentionally do not list `onToken` in the dependency array;
+    // a parent re-rendering with a fresh closure should not tear down
+    // and rebuild the widget (which would consume a fresh challenge).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  if (!SITE_KEY) return null
+  return <div ref={containerRef} className="turnstile-widget" />
+}

frontend/src/lib/analytics.js

@@ -0,0 +1,384 @@
+// analytics.js — v0.15.0 / roadmap item #13.
+//
+// Wrapper around `@amplitude/unified` (Amplitude Analytics +
+// Session Replay) that gates SDK initialization on the user's
+// cookie/privacy consent (v0.13.0, `frontend/src/lib/consent.js`,
+// SPEC §14.5). The wrapper presents a stable surface to the rest
+// of the app:
+//
+//     import { track, identify, anonymize } from './lib/analytics'
+//
+//     track('RFC Viewed', { rfc_slug: 'open-human-model' })
+//     identify({ user_id: 'u_123' })
+//     anonymize()  // call on sign-out
+//
+// At first import the wrapper:
+//   1. Calls `bootstrap()` once, which reads `getConsent()` and
+//      subscribes to `onConsentChange()`. If consent.analytics is
+//      true, it lazily imports the Amplitude SDK and calls
+//      `amplitude.initAll(API_KEY, { analytics: { autocapture: true },
+//                                     sessionReplay: { sampleRate: 1 } })`.
+//      If consent.analytics is false (or undecided), the SDK is
+//      not loaded — no network request, no cookies, no session
+//      replay recording. A later consent change to `true` triggers
+//      init at that moment.
+//   2. The wrapper queues `track()` and `identify()` calls made
+//      before init finishes (lazy import + consent grant), and
+//      drains the queue when init completes.
+//   3. If the user later flips consent from granted → denied, the
+//      wrapper calls `amplitude.setOptOut(true)` so subsequent
+//      events are dropped client-side and session replay stops
+//      recording (the SDK is still loaded — we cannot unload a
+//      script — but it stops firing).
+//
+// Consent precedence ladder:
+//
+//     consent.analytics === true   → init + track
+//     consent.analytics === false  → no init; or if already init,
+//                                    setOptOut(true)
+//     consent.recorded_at === null → treat as denied (banner is up;
+//                                    the user has not yet chosen)
+//
+// Session replay scope: this release ships session replay at
+// `sampleRate: 1` (100% of sessions are recorded for full-DOM
+// playback). That is the vendor-recommended default for new
+// Amplitude deployments. The v0.13.0 consent banner's single
+// "analytics" toggle gates both events and session replay together —
+// a separate consent category for session-replay specifically is a
+// §19.2 follow-up.
+//
+// API key resolution:
+//
+//     The build-time env var `VITE_AMPLITUDE_API_KEY` carries the
+//     Amplitude project's API key. When it is unset/empty, the
+//     wrapper logs one console warning and no-ops — every public
+//     function becomes a deterministic no-op so dev environments
+//     (and deployments that intentionally don't ship analytics)
+//     keep working. The deploy gesture wires the key via flotilla's
+//     `overlay set` verb (see CHANGELOG for the operator gesture):
+//     Amplitude browser keys are bundle-embedded by design (visible
+//     to anyone with dev tools, same nature as the v0.12.0
+//     `VITE_TURNSTILE_SITE_KEY`), so the binding is overlay, not
+//     secret.
+//
+// PII discipline:
+//
+//     `identify({ user_id })` SHOULD pass only the opaque server-
+//     side user id (the `viewer.id` integer or string). DO NOT pass
+//     email, display name, IP, or any other PII through the SDK.
+//     Event properties SHOULD likewise stay limited to ids and
+//     enums; free-text fields (titles, comment bodies) MUST NOT be
+//     sent.
+//
+// Event taxonomy: defined in `EVENTS` below. Callers SHOULD use
+// one of these names rather than firing arbitrary strings — that
+// keeps the Amplitude dashboard coherent over time.
+
+import { getConsent, onConsentChange } from './consent.js'
+
+const API_KEY = import.meta.env.VITE_AMPLITUDE_API_KEY || ''
+
+// Public taxonomy. Keep this short and stable — new entries should
+// land via a release, not ad-hoc. The strings match the Amplitude
+// dashboard names exactly (Title Case, spaces, no punctuation).
+export const EVENTS = Object.freeze({
+  PAGE_VIEWED: 'Page Viewed',
+  RFC_VIEWED: 'RFC Viewed',
+  USER_SIGNED_IN: 'User Signed In',
+  USER_SIGNED_OUT: 'User Signed Out',
+  RFC_PROPOSED: 'RFC Proposed',
+  PR_OPENED: 'PR Opened',
+  COMMENT_POSTED: 'Comment Posted',
+  BETA_ACCESS_REQUESTED: 'Beta Access Requested',
+  ADMIN_PERMISSION_DECISION: 'Admin Permission Decision',
+  // v0.16.0 / item #12 — per-RFC owner invites.
+  INVITATION_SENT: 'Invitation Sent',
+  INVITATION_ACCEPTED: 'Invitation Accepted',
+  // v0.17.0 / item #16 — admin-create user + invite email.
+  USER_INVITED: 'User Invited',
+  INVITE_CLAIMED: 'Invite Claimed',
+})
+
+// Internal state.
+let _bootstrapped = false
+let _amplitude = null       // The dynamically imported SDK module.
+let _initPromise = null     // Pending init (lazy import + sdk.init).
+let _initialized = false    // True after sdk.init has resolved.
+let _warnedNoKey = false
+let _pendingUserId = null   // identify() called before init resolves.
+let _pendingProperties = null  // identify({ properties }) or
+                               // setUserProperties() before init.
+const _queue = []           // {kind: 'track'|'identify'|'anonymize'|
+                            //  'setUserProperties', ...}
+
+function warnNoKey() {
+  if (_warnedNoKey) return
+  _warnedNoKey = true
+  // eslint-disable-next-line no-console
+  console.warn(
+    '[analytics] VITE_AMPLITUDE_API_KEY is unset; analytics events ' +
+    'and session replay will not be sent. This is expected in dev; ' +
+    'in production it means the operator has not yet run ' +
+    '`flotilla overlay set <deployment> VITE_AMPLITUDE_API_KEY=<key>`.',
+  )
+}
+
+function consentGranted() {
+  const c = getConsent()
+  return !!(c && c.recorded_at && c.analytics)
+}
+
+// Apply a {key: value} property bag as an Amplitude Identify event.
+// Used by both `identify({ properties })` and `setUserProperties`.
+function applyProperties(props) {
+  if (!_initialized || !_amplitude || !props) return
+  try {
+    const id = new _amplitude.Identify()
+    for (const [k, v] of Object.entries(props)) {
+      if (v === undefined || v === null) continue
+      if (Array.isArray(v) && v.length === 2 && v[0] === '__setOnce__') {
+        id.setOnce(k, v[1])
+      } else {
+        id.set(k, v)
+      }
+    }
+    _amplitude.identify(id)
+  } catch (_) {
+    // SDK errors are non-fatal; analytics is best-effort.
+  }
+}
+
+// Drain the queue. Called once init resolves.
+function drainQueue() {
+  if (!_initialized || !_amplitude) return
+  if (_pendingUserId != null) {
+    try { _amplitude.setUserId(_pendingUserId) } catch (_) {}
+    _pendingUserId = null
+  }
+  if (_pendingProperties != null) {
+    applyProperties(_pendingProperties)
+    _pendingProperties = null
+  }
+  while (_queue.length > 0) {
+    const item = _queue.shift()
+    try {
+      if (item.kind === 'track') {
+        _amplitude.track(item.name, item.props || {})
+      } else if (item.kind === 'identify') {
+        if (item.user_id != null) _amplitude.setUserId(item.user_id)
+        if (item.properties != null) applyProperties(item.properties)
+      } else if (item.kind === 'setUserProperties') {
+        applyProperties(item.properties)
+      } else if (item.kind === 'anonymize') {
+        _amplitude.reset()
+      }
+    } catch (_) {
+      // SDK errors are non-fatal; analytics is best-effort.
+    }
+  }
+}
+
+// Lazy import + init. Resolves once the SDK is ready to take events.
+// Idempotent: subsequent calls return the same promise.
+async function initSdk() {
+  if (_initPromise) return _initPromise
+  if (!API_KEY) {
+    warnNoKey()
+    // Resolve immediately with a no-op shape; the wrapper's public
+    // functions check API_KEY and short-circuit, so this never
+    // actually runs SDK code.
+    _initPromise = Promise.resolve(null)
+    return _initPromise
+  }
+  _initPromise = (async () => {
+    try {
+      const mod = await import('@amplitude/unified')
+      // The unified package exposes `initAll`, `track`,
+      // `setUserId`, `reset`, `setOptOut` as named functions.
+      // We hold the module so the queue drainer can call them
+      // by name.
+      _amplitude = mod
+      // initAll wires up both Analytics and Session Replay in one
+      // call. Vendor-recommended init shape from the Amplitude
+      // installation wizard:
+      //   - analytics.autocapture: true — auto-instruments page
+      //     views, session start/end, clicks, and form interactions.
+      //     Our explicit `track('Page Viewed', …)` etc. layer on top
+      //     for app-specific names that survive renames.
+      //   - sessionReplay.sampleRate: 1 — record 100% of sessions
+      //     for full-DOM playback. Gated by the v0.13.0 consent
+      //     banner just like the rest of the SDK; never starts
+      //     recording without explicit analytics opt-in.
+      const ret = mod.initAll(API_KEY, {
+        analytics: { autocapture: true },
+        sessionReplay: { sampleRate: 1 },
+      })
+      // initAll returns an AmplitudeReturn with a `.promise` accessor
+      // (consistent with the legacy `init`). Some unified builds
+      // resolve synchronously; await defensively.
+      if (ret && ret.promise) await ret.promise
+      _initialized = true
+      drainQueue()
+    } catch (err) {
+      // Init failure is non-fatal; keep the wrapper alive so future
+      // calls no-op. Log once for the operator.
+      // eslint-disable-next-line no-console
+      console.warn('[analytics] Amplitude init failed:', err)
+      _initialized = false
+    }
+    return _amplitude
+  })()
+  return _initPromise
+}
+
+// Bootstrap is called lazily on first track/identify. It wires the
+// consent subscription so a later flip from denied→granted triggers
+// init at that moment, and granted→denied flips the opt-out.
+function bootstrap() {
+  if (_bootstrapped) return
+  _bootstrapped = true
+  if (consentGranted()) {
+    // Fire-and-forget; the queue catches any events that arrive
+    // before init resolves.
+    initSdk()
+  }
+  onConsentChange(snapshot => {
+    const allowed = !!(snapshot && snapshot.recorded_at && snapshot.analytics)
+    if (allowed && !_initPromise) {
+      initSdk()
+    } else if (allowed && _initialized && _amplitude) {
+      // Re-enable in case we previously opted out.
+      try { _amplitude.setOptOut(false) } catch (_) {}
+    } else if (!allowed && _initialized && _amplitude) {
+      // Granted → denied. Stop firing. We cannot unload the script
+      // tag; setOptOut is the SDK's contract for "drop subsequent
+      // events client-side".
+      try { _amplitude.setOptOut(true) } catch (_) {}
+    }
+  })
+}
+
+/** Fire a track event. Safe to call before consent / init resolve;
+ *  the call is queued and drained once both are true. Drops the
+ *  event silently if API_KEY is empty (with a one-shot warn) or
+ *  consent.analytics is false. */
+export function track(name, props) {
+  if (!API_KEY) { warnNoKey(); return }
+  bootstrap()
+  if (!consentGranted()) return
+  if (_initialized && _amplitude) {
+    try { _amplitude.track(name, props || {}) } catch (_) {}
+    return
+  }
+  _queue.push({ kind: 'track', name, props })
+}
+
+/** Attach an authenticated user id and optional durable properties.
+ *  Pass `{ user_id: '<opaque-id>', properties?: { role, first_sign_in_at, … } }`.
+ *  DO NOT pass email, display name, or other PII as user_id or in
+ *  properties. Idempotent — subsequent calls with the same id are
+ *  cheap; properties are merged into the Amplitude user record.
+ *
+ *  To mark a property as setOnce (immutable after first write),
+ *  pass `properties: { first_sign_in_at: ['__setOnce__', '2026-05-28T…'] }`.
+ *  Bare values use Amplitude's `.set()` (mutable).
+ *
+ *  Pattern (per #21 Part C):
+ *    - On sign-in success in App.jsx: identify with viewer.id + the
+ *      durable property bag (role, permission_state, first_sign_in_at
+ *      setOnce, passcode_set, device_trusted_count, account_created_at
+ *      setOnce).
+ *    - On invite-claim success in InviteClaim.jsx / AcceptInvitation.jsx:
+ *      identify with the new viewer.id + invitation-derived properties
+ *      (invited_by_admin_id, invited_at setOnce, initial_role, claim_method)
+ *      BEFORE firing any track() — so the Amplitude user record is
+ *      created with the OHM user_id from the first event, not as an
+ *      anonymous device that retroactively links. */
+export function identify({ user_id, properties } = {}) {
+  if (!API_KEY) { warnNoKey(); return }
+  if (user_id == null && properties == null) return
+  bootstrap()
+  if (!consentGranted()) {
+    // Hold for when consent lands; identify-on-sign-in is a common
+    // race with the consent banner choice.
+    if (user_id != null) _pendingUserId = user_id
+    if (properties != null) {
+      _pendingProperties = { ..._pendingProperties, ...properties }
+    }
+    return
+  }
+  if (_initialized && _amplitude) {
+    try {
+      if (user_id != null) _amplitude.setUserId(user_id)
+      if (properties != null) applyProperties(properties)
+    } catch (_) {}
+    return
+  }
+  if (user_id != null) _pendingUserId = user_id
+  if (properties != null) {
+    _pendingProperties = { ..._pendingProperties, ...properties }
+  }
+  _queue.push({ kind: 'identify', user_id, properties })
+}
+
+/** Update durable user properties on the current Amplitude user
+ *  record mid-session — for state changes that shouldn't wait for the
+ *  next sign-in to surface (role grant/revoke, passcode set, device
+ *  trusted, etc.). Same property shape as `identify({ properties })`.
+ *  setOnce values use the `['__setOnce__', value]` sentinel pattern.
+ *  Has no effect if no identify has happened yet — set the user_id
+ *  via `identify()` first.
+ *
+ *  Per #21 Part C: call this from any surface where the user's
+ *  Amplitude-relevant state changes mid-session, so the dashboard
+ *  stays current. */
+export function setUserProperties(properties) {
+  if (!API_KEY) { warnNoKey(); return }
+  if (properties == null) return
+  bootstrap()
+  if (!consentGranted()) {
+    _pendingProperties = { ..._pendingProperties, ...properties }
+    return
+  }
+  if (_initialized && _amplitude) {
+    applyProperties(properties)
+    return
+  }
+  _pendingProperties = { ..._pendingProperties, ...properties }
+  _queue.push({ kind: 'setUserProperties', properties })
+}
+
+/** Reset the user binding. Call this on sign-out so the next page
+ *  navigations are attributed to a fresh anonymous device id. Has
+ *  no effect when analytics is disabled.
+ *
+ *  Per #21 Part C: clears both the user_id binding AND the pending
+ *  property cache, so a subsequent sign-in as a different user
+ *  starts with a fully fresh slate (no carry-over properties from
+ *  the previous user). */
+export function anonymize() {
+  if (!API_KEY) { warnNoKey(); return }
+  _pendingUserId = null
+  _pendingProperties = null
+  bootstrap()
+  if (!consentGranted()) return
+  if (_initialized && _amplitude) {
+    try { _amplitude.reset() } catch (_) {}
+    return
+  }
+  _queue.push({ kind: 'anonymize' })
+}
+
+/** Test helper — exposed for unit tests, not for app code.
+ *  Resets module-level state so a fresh bootstrap cycle can be
+ *  exercised. */
+export function __resetForTests() {
+  _bootstrapped = false
+  _amplitude = null
+  _initPromise = null
+  _initialized = false
+  _warnedNoKey = false
+  _pendingUserId = null
+  _pendingProperties = null
+  _queue.length = 0
+}