docs: plan for Accounts 1.0.0 (phase 3)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-18 13:10:54 +02:00
co-authored by Claude Opus 5.5
parent 78dd903b2d
commit 6bdabeb871
3 changed files with 313 additions and 2 deletions
+310
View File
@@ -0,0 +1,310 @@
# Accounts 1.0.0 — one sign-in for every product of a church
Phase **3** of [ROADMAP-v3.md](./ROADMAP-v3.md) (§3, §8, §9; decisions 2, 14, 15, 17). Written
2026-11-18. **Not started.** The decisions at the end are proposed, to confirm before building.
**What Accounts is:** a small OpenID Connect provider per church, at `accounts.<church's address>`.
People sign in there once and are signed in to all of the church's products. Members never see it
as a product: its pages carry the church's name and colours ("Sign in to Hope Family Church").
Admins see it as **Accounts** (people, sign-in settings, linked products, the church profile).
Each product keeps its own roles and data, keyed by the account's `sub`.
**Who uses 1.0:** the Church Website (phase 4) is built on it from its first release. Cross Events
keeps its own sign-in until **3.0** (phase 5), which moves its users across with their password
hashes and 2FA. So 1.0 is tested against a test product (a small OIDC client in the e2e tests), and
everything Events 3.0 will need (bcrypt and Argon2id hashes, authenticator secrets, recovery codes,
notice versions) is supported from the start.
**Done when:**
- `accounts@1.0.0` and `contracts@1.5.0` are tagged; the Hub (2.3.0) installs Accounts from New
install and lists its releases.
- A test product signs in through Accounts with PKCE, comes back to the exact page it started on
(through 2FA, a password reset, sign-up and a new privacy notice), and a foreign return address
is refused (ROADMAP §9 "Release checks").
- Signing out of one product signs the person out of all of them.
- "Download my data" and "Delete my account" reach every linked product, and a product's
"not yet" (`deferred`) is retried.
- It installs, updates and uninstalls through the agent on the VM, next to Events.
- crosscode-site says "One sign-in for all your church's products" on the Products page.
## Contents
1. [The shape](#1-the-shape)
2. [Accounts, passwords and 2FA](#2-accounts-passwords-and-2fa)
3. [OpenID Connect](#3-openid-connect)
4. [Products as clients: Connect](#4-products-as-clients-connect)
5. [Sign-in flow and returning to the page](#5-sign-in-flow-and-returning-to-the-page)
6. [Privacy: notice, consent, export, delete](#6-privacy-notice-consent-export-delete)
7. [The church profile](#7-the-church-profile)
8. [Screens](#8-screens)
9. [Hub, licence and servers](#9-hub-licence-and-servers)
10. [Security](#10-security)
11. [What changes in each repo](#11-what-changes-in-each-repo)
12. [Testing](#12-testing)
13. [Releasing and rolling it out](#13-releasing-and-rolling-it-out)
14. [Decisions](#decisions)
15. [Still open](#still-open)
---
## 1. The shape
`apps/accounts` in this repo, the same stack as Events (decision 8): an **Express + Prisma +
pg-boss backend** (TypeScript throughout, no v1 history) and a **Next.js frontend** for the pages,
one PostgreSQL database, served on one address with `/api` to the backend (as Events 2.2.0).
```
product (Website, App, Events 3.0) accounts.hopefamily.co.za
────────────────────────────────── ─────────────────────────────────────────────
"Sign in" ─── /oidc/auth?…&state=<return path> ──► oidc-provider (backend, /api/oidc)
│ interaction → /signin?uid=… (Next.js page)
│ password → 2FA → notice / news question
/api/auth/callback ◄── code ────────────────────── │ ← finished interaction
token exchange (PKCE, client secret) ──────────► │ ID token with crosscode.identity/1 claims
own session cookie, then the page from `state`
back-channel (pg-boss, signed):
POST /api/accounts/v1/events ◄──────────────────── user.updated · user.deleted · user.export
POST /api/auth/backchannel-logout ◄─────────────── signed out everywhere
```
- **Backend** `apps/accounts/backend`: `oidc-provider` mounted at `/api/oidc` (discovery at
`/.well-known/openid-configuration`, rewritten by nginx and the Next config to the backend), the
sign-in API the pages use (`/api/v2/interaction/…`), the account API (`/api/v2/me/…`), admin
(`/api/v2/admin/…`), the cross-product routes as Events 2.4 (`/api/links/v1/*`), Hub client
(protocol v2, product `accounts`), jobs.
- **Frontend** `apps/accounts/frontend`: sign-in, 2FA, forgot / reset password, sign-up, the news
question, privacy notice, the account page, admin, `/setup`. Branded from the church profile
(§7). `@crosscode/ui` gets its first real components here (the branded shell, forms, buttons),
so the Website starts from them.
- **Nothing is shared with Events at runtime.** The 2FA, TOTP, recovery codes, password and
privacy notice code are **copied** from Events into Accounts and tidied up (Events' copy goes away
in 3.0), not moved into a shared package that both would have to release together.
## 2. Accounts, passwords and 2FA
What Accounts holds (ROADMAP §3 "What lives where"):
| Model | What |
|-------|------|
| `Account` | `id` (the `sub`, UUID), name, given/family name, email (unique, verified flag), phone (verified flag), password hash, `role` (`member` · `admin`: Accounts' own, never a product role), status (`active` · `deactivated` · `deleted`), created / last sign-in |
| `TwoFactor` | method (`email` · `whatsapp` · `totp`), TOTP secret (encrypted), last TOTP step (no code used twice); `RecoveryCode` (hashed, single use) |
| `LoginEvent` | sign-ins, failures, lockouts, resets, 2FA changes: what Events calls its security log, shown to the person and admins |
| `PrivacyNotice` / `NoticeAcceptance` | versions and who accepted which, when |
| `NewsConsent` | email / WhatsApp, with when and how it was given (POPIA proof) |
| `AccessLog` | admins viewing or exporting a person (as Events) |
| `ProductLink`, `LinkNonce` | the church's linked products (as Events 2.4) |
| `OidcPayload` | oidc-provider's storage (sessions, grants, codes) in Postgres via its adapter interface |
| `Delivery` | back-channel calls and their retries (§6) |
- **Passwords:** Argon2id (`@node-rs/argon2`, Events' parameters). Hashes imported from Events
that are still **bcrypt** verify too and are re-hashed on the next sign-in, as Events does.
At least 8 characters, as Events.
- **Lockout** and rate limits as Events (per account and per IP); forgot-password never says
whether an account exists (Events 1.51.17).
- **2FA:** email, WhatsApp (WAWP, as Events), or an authenticator app, with 10 recovery codes.
**Required for Accounts admins.** Products can ask for it for their own roles (an Events
supervisor must have 2FA): a product sends `acr_values=mfa` and Accounts asks for 2FA on that
sign-in even if the person doesn't use it otherwise, setting it up first if they have none.
- The `crosscode.identity/1` method name is `totp`; Events 2.3 calls it `authenticator`. The 3.0
migration maps it.
## 3. OpenID Connect
- **`oidc-provider`** (panva, 9.x) on the backend, **`openid-client`** (6.x) in each product
(a small helper in `@crosscode/contracts` or a new `packages/auth-client`, §11). Versions pinned
to releases at least two weeks old when building.
- **Authorization code flow with PKCE (S256), required for every client**; no implicit or hybrid
flows, no device flow, no dynamic registration (§4 registers clients).
- **Signing keys:** ES256, made on first start and stored encrypted; `crosscode accounts rotate-keys`
(or an admin button) adds a new key and keeps the old one for verifying until tokens signed with
it have expired.
- **Claims:** the ID token and userinfo carry `crosscode.identity/1` (`sub`, name, email, phone,
verified flags, `news_consent`, `amr`, `two_factor`, `privacy_notice_version`). Scopes
`openid profile email phone` plus `crosscode` for the news consent and notice version.
- **Tokens:** ID token 10 minutes; access token 10 minutes (only for userinfo); **no refresh
tokens**: each product keeps its own session after sign-in, as Events does today. The Accounts
session (the browser's cookie at `accounts.…`) lasts 30 days with "Keep me signed in", otherwise
until the browser closes; a product sending someone back finds them still signed in.
- **Sign-out everywhere:** RP-initiated logout (`end_session`, `post_logout_redirect_uri` exact
match, ROADMAP §3) plus **OIDC Back-Channel Logout** to every product the session signed in to,
so they end their own sessions. A product that misses it still ends its session when its own
session expires.
## 4. Products as clients: Connect
There's no client registration screen. **Connect** (Settings → Linked products, Events 2.4's
`crosscode.link/1`) between a product and Accounts **also registers the product as an OIDC client**:
| OIDC client field | From |
|-------------------|------|
| `client_id` | the product's Hub install id |
| `client_secret` | derived from the link's secret: `HMAC-SHA256(secret, "crosscode.oidc-client/1")`, so there's no second secret to exchange or store |
| `redirect_uris` | exactly `<product url>/api/auth/callback` |
| `post_logout_redirect_uris` | exactly `<product url>/` |
| `backchannel_logout_uri` | `<product url>/api/auth/backchannel-logout` |
- The paths are fixed for every product (`OIDC_PATHS` in contracts 1.5.0), so nothing is typed in.
- Only installs the Hub lists for the same church can connect (as Events 2.4), and the URL is the
one the Hub lists, so a product can't register someone else's address.
- Disconnecting removes the client; that product's sign-ins stop working at once.
- The same link signs the back-channel calls (§6) with `LINK_HEADERS`.
## 5. Sign-in flow and returning to the page
ROADMAP §3, "Sign-in always returns you to where you came from", with the contracts' helpers
(`encodeState`, `decodeState`, `safeReturnPath`, `isRegisteredRedirectUri`):
1. The product sends the person to `/api/oidc/auth` with PKCE, a nonce, and `state` =
`encodeState({ nonce, returnTo: <path and query> })`; the nonce also goes in an HttpOnly cookie.
2. oidc-provider starts an **interaction** and redirects to `/signin?uid=…`. Every later step
(password, 2FA, "forgot password" and the reset link, creating an account, the news question,
accepting a new notice) carries the `uid`, so the interaction survives all of them. A reset link
opened in another browser finishes the reset and then asks to sign in again there, still
returning to the product.
3. Accounts finishes the interaction; oidc-provider redirects to the registered `redirect_uri`
with the code and the untouched `state`.
4. The product checks the state's nonce against its cookie, exchanges the code, starts its own
session and redirects to `safeReturnPath(state.returnTo)`.
Opening `accounts.…` directly shows the account page (or sign-in, then the account page).
## 6. Privacy: notice, consent, export, delete
The church is one responsible party (ROADMAP §3, "POPIA"):
- **Privacy notice** versions and acceptance as Events 1.x/2.x (`privacyNotice.js`), now in
Accounts. A new version is asked for before returning to the product (§5). The Events notice
versions move across in 3.0.
- **News consent** (email / WhatsApp) asked once, as Events' "news question"; changes send
`user.updated` to every linked product.
- **Download my data:** Accounts' own part (profile, sign-ins, consents) plus a `user.export` call
to every linked product; the answers (`crosscode.identity/1` export sections) are bundled into
one ZIP, ready within a few minutes, with an email when it is. A product that doesn't answer in
24 hours is listed as missing in the ZIP.
- **Delete my account:** deactivates the account at once (signed out everywhere), then waits for an
admin to approve (as Events). On approval, `user.deleted` to each product; a `deferred` reply
(e.g. an open registration for an upcoming event) is asked again after its `retryAfter`; the
account is anonymised once every product has answered `deleted`. Admins see the state per product.
- **Back-channel calls** (`POST <product>/api/accounts/v1/events`) go through a `Delivery` table and
pg-boss: signed with the link's secret, retried (1 min, 5 min, 30 min, 2 h, 12 h, then daily for a
week), with their state on the admin's person page.
- Access log for admins viewing or exporting a person; retention of inactive accounts (Events' rule:
warn, then anonymise) moves to Accounts with 3.0.
## 7. The church profile
**Accounts owns `crosscode.church/1`** (decision 1 below): it's the one product every church has,
and its sign-in pages need the name, logo and colours before anything else exists. Admins edit it
under **Accounts → Church profile** (name, short name, logo, colours, campuses, service times,
contact details, social links). It's served at `GET /api/church/v1` (public, cached; the
`links` filled in from the linked products) and announced to linked products with a signed
`church.updated` call. The Website (phase 4) reads it and shows its own form for it, saving
through Accounts' API with the admin's token. Events keeps its own settings until 3.0, then reads
the profile too.
## 8. Screens
| Who | Screens |
|-----|---------|
| Everyone | Sign in · 2FA (code, app, recovery code) · Forgot password · Reset password · Create an account (if the church allows sign-up, on by default) · Verify email · News question · Privacy notice |
| Account holder | **My account**: profile (name, email with re-verification, phone), password, 2FA (set up, change, recovery codes), signed-in devices and recent sign-ins, privacy (download my data, delete my account, news consent, notice) |
| Accounts admin | **People** (search, profile, sign-ins, reset 2FA, deactivate, approve deletion, access-logged) · **Sign-in settings** (allow sign-up, 2FA required for whom, session length) · **Linked products** (as Events 2.4: Connect, which products sign people in) · **Church profile** (§7) · **Privacy** (notice versions, deletion requests) · **Email and WhatsApp** (SMTP, WAWP, as Events) · **Licence** · **Audit log** |
| First run | `/setup`: the church profile's basics, the first admin (with 2FA), email settings. A Hub install registers by itself from `HUB_LICENCE_KEY` (as Events 2.3) |
All pages: the church's branding, `noindex`, blocked in `robots.txt` (ROADMAP §11), WCAG 2.2 AA,
phone-first.
## 9. Hub, licence and servers
- **Hub protocol v2, product `accounts`**, `CCA-` licences (Hub 2.0 already knows the product and its
stats: accounts, 2FA methods, linked products). **Accounts is never charged** (ROADMAP §5) and
**doesn't go read-only**: a lapsed licence shows a banner to admins only; members can always
sign in (decision 4), so a billing problem never locks a church's members out of every product.
- **Hub 2.3.0:** a customer gets an Accounts licence with its first product (no price, not on
invoices); New install offers Accounts and installs it first; release sync for `accounts@` tags
and `apps/accounts/WHATS-NEW.md` (already in the release-source table).
- **`crosscode`:** `scripts/products/accounts.sh` with the same hooks as Events, `accounts` in
`SUPPORTED_PRODUCTS`, `crosscode install … --products accounts,…` (served on `accounts.<address>`),
`crosscode add <church> accounts` for existing churches, and `deploy` then updates Accounts first,
as ROADMAP §8 always meant. The env template in three places (HANDOVER: "A new .env variable").
- **Agent:** the install and uninstall jobs already take `accounts` as a product
(`releaseTagSchema`, `productSchema`); the frp port list gets its two ports.
- **Cross Code address:** `accounts.<church>.crosscode.co.za` like `events.…`; FastPanel, DNS and
Let's Encrypt by hand as for Events (decision 34).
## 10. Security
- Cookies: the Accounts session `Secure; HttpOnly; SameSite=Lax`; interaction cookies scoped to
`/api/oidc`. CSRF tokens on every form post. Strict CSP on every page (no inline scripts).
- Exact-match redirect URIs only; `state` returned untouched; `safeReturnPath` on the product side;
`return_to` never accepted from a query string on Accounts' own pages.
- PKCE required; authorization codes single-use, 60 seconds; `nonce` required.
- Only the configured domain is served (nginx `server_name`, `TRUST_PROXY` as Events).
- Rate limits and lockout (§2); `LoginEvent` for every sign-in and change; admin actions audited.
- Secrets (signing keys, TOTP secrets, link secrets, SMTP/WAWP passwords) encrypted at rest, as
Events.
- A `security.txt`, and the release checks' Playwright cases (§12) in CI.
## 11. What changes in each repo
| Repo | Change | Version |
|------|--------|---------|
| `crosscode-platform` `apps/accounts` | New (§1–§10), with `CHANGELOG.md`, `WHATS-NEW.md`, `env.template.json`, e2e | `accounts@1.0.0` |
| `crosscode-platform` `packages/contracts` | `OIDC_PATHS`, `oidcClientSecret()` (derived from a link secret), `church.updated`, the `/api/church/v1` and `/api/accounts/v1/events` paths; `crosscode.identity/1` unchanged | `contracts@1.5.0` |
| `crosscode-platform` `packages/auth-client` | New: the product side of §5 on `openid-client` (start sign-in with state and PKCE, callback, back-channel logout, `user.*` call verification), so the Website, App and Events 3.0 share one | workspace |
| `crosscode-platform` `packages/ui` | The branded shell, forms and buttons, from Accounts' pages | workspace |
| `crosscode-platform` `scripts/` | `products/accounts.sh`, `accounts.env.template.json`, `SUPPORTED_PRODUCTS`, `add`, bats tests | — |
| `crosscode-platform` `apps/events` | Nothing until 3.0, except **Linked products accepting Accounts** for Connect (it already lists it) | — |
| `events-hub` | Accounts licence with the first product, New install with Accounts, its env template, its releases | Hub `v2.3.0` |
| `crosscode-site` | "One sign-in for all your church's products" (Products page) | `v1.5.0` |
## 12. Testing
- **Unit (Jest):** passwords (Argon2id and bcrypt), lockout, TOTP and recovery codes, the
interaction steps, client registration from a link, `client_secret` derivation, back-channel
signing and retries, deferred deletion, the export bundle.
- **OIDC:** a test product built on `packages/auth-client` runs against the real provider in the
tests: discovery, PKCE required (a request without it is refused), wrong `redirect_uri` refused,
code reuse refused, ID token claims fit `crosscode.identity/1`, back-channel logout reaches it.
Where practical, the OpenID Foundation's conformance suite (basic and config profiles) is run
once before release.
- **Playwright (the release checks, ROADMAP §9):** signing in from a deep link lands back on that
page, including through 2FA, a password reset, sign-up and a new notice; a foreign or absolute
return URL is refused; signing out of one product signs out of all; "Download my data" includes
the test product's part; deleting waits for a deferred product.
- **VM:** install Accounts and Events side by side through the agent, update Accounts, uninstall
it with its export (`crosscode.church-export/1` gets an `accounts` section).
## 13. Releasing and rolling it out
1. `contracts@1.5.0`, then Hub `v2.3.0` (vendored contracts) deployed.
2. `accounts@1.0.0` tagged after the e2e and VM runs.
3. crosscode-site `v1.5.0`.
4. **Churches get Accounts with the Website** (phase 4) or with Events 3.0, whichever comes first
for them (decision 6). Until then nothing uses it, so it isn't installed for its own sake.
## Decisions
Proposed, to confirm before building:
1. **Accounts owns the church profile** (`crosscode.church/1`, §7). It's the one product every
church has, and it needs the branding first. This answers the 2.4 plan's open question.
2. **Connect registers the OIDC client** (§4), with the client secret derived from the link's
secret; no client registration screen.
3. **Products keep their own sessions; no refresh tokens**; sign-out everywhere by back-channel
logout (§3).
4. **Accounts never goes read-only on a lapsed licence**: only admins see a banner (§9).
5. **Sign-up is on by default** (members can create an account), and an admin can switch it off
(staff-only churches).
6. **Accounts is installed with a church's first Website, or with Events 3.0**, not before.
7. **Events' sign-in code is copied, not shared** (§1); `packages/auth-client` is the shared
piece, on the product side.
8. **`acr_values=mfa`** lets a product require 2FA for its own roles (§2).
## Still open
- Whether the Website's admin edits the church profile through Accounts' API (as proposed in §7)
or Accounts' own screen is the only place. Decide with the Website plan (phase 4).
- Session lengths (30 days with "Keep me signed in") are a starting point; check them with Joshua
before release.
+2 -1
View File
@@ -29,7 +29,8 @@ for each phase and the rollout checklist ([ROLLOUT-1.0.md](./ROLLOUT-1.0.md)).
| 1c | Cross Events 2.3.x: authenticator app 2FA (TOTP + recovery codes) | **Released** 2026-11-17 (`events@2.3.0`). **`events@2.3.1`** 2026-11-18: Next.js 16.4.6 (security advisories for 16.2.0–16.4.4), so roll out 2.3.1, not 2.3.0. crosscode-site `v1.3.0` lists it (merged and tagged, **not deployed**) |
| 1d | Agent 1.0.x + Hub 2.1.x (+ contracts 1.3.0) | **Released** 2026-11-17 (`agent@1.0.0`, `contracts@1.3.0`, Hub `v2.1.0`). **VM tested** end to end (AGENT-1.0-PLAN §13: joins, installs behind frp, scheduled / batch / missed updates, uninstall with export and purge, forged and replayed jobs). 2026-11-18: **`agent@1.0.1`** (the agent answers status on the central server itself) and Hub **`v2.1.1`** (adopt passes the church's address; Link takes the short name as a name). **Not rolled out**: use agent 1.0.1 and Hub 2.1.1 |
| 2 | Cross Events 2.4.0: protocol v2, Linked products, event feed, `packages/seo` (+ contracts 1.4.0, Hub 2.2.0) | **Built** 2026-11-18 ([EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md), decisions taken as proposed, "Changes while building" there): `feat/events-2.4` here, `feat/link-public-key` in events-hub, `feat/linked-products` in crosscode-site. Unit tests pass. **Not tagged:** the e2e spec and the VM test haven't run (no Postgres on the dev machine) |
| 3–7 | Accounts 1.0.0 → Website 1.0.0 → Events 3.0.0 → App 1.0.0 → App 1.x | Not started |
| 3 | Accounts 1.0.0 (+ contracts 1.5.0, Hub 2.3.0) | **Planned** 2026-11-18: [ACCOUNTS-1.0-PLAN.md](./ACCOUNTS-1.0-PLAN.md), eight decisions to confirm before building |
| 4–7 | Website 1.0.0 → Events 3.0.0 → App 1.0.0 → App 1.x | Not started |
## Next up
+1 -1
View File
@@ -617,7 +617,7 @@ Planned in [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md). In short:
| 1c | **Cross Events 2.3.0** | **Authenticator app 2FA** (TOTP) next to email and WhatsApp, with recovery codes; admins can see which method each staff account uses. **Released 2026-11-17** (`events@2.3.0`) | Independent and useful now; the Accounts migration later carries it over |
| 1d | **Agent 1.0.0 + Hub 2.1.0** (contracts 1.3.0) | **Server agent** on every server (polls only, signed jobs, runs the `crosscode` script); Hub: Servers page with stats and alerts, server configuration, frp port list, New install with a choice of server, scheduled / emergency / batch updates with notice to the church, uninstall with an encrypted JSON export, emailed reports. [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md). **Released 2026-11-17** after the VM test; rollout in [ROLLOUT-1.0.md](./ROLLOUT-1.0.md) | Right after 1b (it runs the `crosscode` script), so every new church from then on is installed from the Hub. Can run alongside 1c |
| 2 | **Cross Events 2.4.0** | Reports `product: "events"` (protocol v2), **Linked products**, the event feed (publish + show events from siblings), `packages/seo` (§11) with canonical links for imported events. **Planned and built 2026-11-18:** [EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md) (also needs contracts 1.4.0 and Hub 2.2.0, for a public key in the v2 heartbeat); not tagged yet | Small; ready for when the Website exists |
| 3 | **Accounts 1.0.0** | OIDC provider, sign-in, 2FA (email, WhatsApp, authenticator app), password reset, consent and notice, export / delete fan-out, admin, install script | The Website is built on it from day one |
| 3 | **Accounts 1.0.0** | OIDC provider, sign-in, 2FA (email, WhatsApp, authenticator app), password reset, consent and notice, export / delete fan-out, admin, install script. **Planned 2026-11-18:** [ACCOUNTS-1.0-PLAN.md](./ACCOUNTS-1.0-PLAN.md) (with contracts 1.5.0, `packages/auth-client`, Hub 2.3.0) | The Website is built on it from day one |
| 4 | **Church Website 1.0.0** | Public site with the **four templates** (§6), admin, simple events + feed, SEO (§11), Hope Family Church as the first church, then a second test church on a different template to prove it repeats | More churches need a website than an app; it also covers the "website only" case |
| 5 | **Cross Events 3.0.0** | Sign-in moves to Accounts; user migration keeping password hashes; migration guide | Breaking change, so a major version, after Accounts is proven on the Website |
| 6 | **Church App 1.0.0** | Foundation (PWA, branding, Accounts), House of Prayer, announcements, devotionals, events (simple + feed) | Starts with shared users and the feed already in place |