# 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. **Decisions confirmed 2026-11-18** (all as proposed). **Partly built 2026-11-18** on `feat/accounts-1.0` (not merged): the app, contracts 1.5.0, `packages/auth-client`, `packages/ui` and the deploy hooks. Not yet: Hub 2.3.0, `crosscode install`/`add` for Accounts, the Playwright run and the VM test. See [Changes while building](#changes-while-building). **What Accounts is:** a small OpenID Connect provider per church, at `accounts.`. 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. [Changes while building](#changes-while-building) 15. [Decisions](#decisions) 16. [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= ──► 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. **Roles stay in each product** (ROADMAP §3; asked by Joshua 2026-11-18). Accounts knows who someone is, never what they may do in a product: its own `member` / `admin` are only about Accounts (who manages sign-in settings, people and the church profile). Cross Events keeps its `User` table with its four roles (`admin`, `supervisor`, `staff`, `user`), campus scopes and all its data; in 3.0 only the user's id becomes the account's `sub`. When someone signs in to Events through Accounts, Events finds its own user by `sub` and applies that role, as today; someone new to Events arrives as `user` and an Events admin promotes them there. The ID token carries no roles, so no product can give anyone a role in another. An Events admin isn't an Accounts admin (or the other way round) unless someone makes them one; the 3.0 migration asks which Events admins should also manage Accounts. Events still requires 2FA for its staff roles by sending `acr_values=mfa`. ## 3. OpenID Connect - **`oidc-provider`** (panva, 9.x) on the backend, **`openid-client`** (6.x) in each product (a new `packages/auth-client`, §11). Pinned to releases at least two weeks old: oidc-provider **9.13.3**, openid-client **6.8.9**. Both are ES modules only, so the Accounts backend and `packages/auth-client` are ES modules (TypeScript, `module: nodenext`), tested with Node's own test runner through tsx. - **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 `/api/auth/callback` | | `post_logout_redirect_uris` | exactly `/` | | `backchannel_logout_uri` | `/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: })`; 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 /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.
`), `crosscode add 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..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. ## Changes while building 1. **"Download my data" is one JSON file**, not a ZIP: every product's part as `crosscode.identity/1` export sections, plus the products that didn't answer in 24 hours. 2. **The Accounts session is oidc-provider's own**, and the account page signs in like a product (`accounts-self`, `/api/self/signin`), so there's one session to end everywhere. 3. **`church.changed`** is a hint at its own path (`/api/church/v1/changed`, contracts 1.5.0, like `event.changed`), not a new `crosscode.identity/1` call type (that would need `/2`). contracts 1.5.0 also exports `churchObjectSchema` (the profile without its cross-field checks). 4. **A product that's disconnected after a deletion was approved** doesn't hold it up. 5. **Tests run the whole app on a real port** with an in-memory database and messenger and a test product on openid-client (`backend/tests/`, 37 tests): every sign-in path in §5, PKCE and redirect refusals, 2FA set-up and recovery codes, back-channel logout, signed calls, deferred deletion, export, Connect, admin rules. oidc-provider refuses private addresses for back-channel logout; `LINKS_ALLOW_PRIVATE` (testing only) lets it reach 127.0.0.1. 6. **Accounts' part of a church export** is `accounts.json` (the church profile and people, no secrets) next to the other products' files. 7. **`/api/health` reads the version from package.json** (PM2 doesn't set npm's variables), so `crosscode deploy` can check it. ## Decisions Confirmed by Joshua on 2026-11-18 (1, 4, 5 and 6 asked directly; the rest as proposed): 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.