Files
crosscode-platform/docs/ACCOUNTS-1.0-PLAN.md
T
joshuaandClaude Opus 5.5 f202a5a88e Accounts 1.0.0 frontend and @crosscode/ui
Sign-in steps (password, sign-up, email code, two-step sign-in and its
setup with recovery codes, privacy notice, news question), forgot and
reset password, the account page, admin (people, deletions, church
profile, linked products, settings, notice, licence, audit) and setup.
Strict CSP with a nonce per page; church colours from the profile.
@crosscode/ui gets its first components (shell, card, fields, buttons).
Plan: roles stay in each product (asked 2026-11-18).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 13:42:45 +02:00

22 KiB

Accounts 1.0.0 — one sign-in for every product of a church

Phase 3 of ROADMAP-v3.md (§3, §8, §9; decisions 2, 14, 15, 17). Written 2026-11-18. Decisions confirmed 2026-11-18 (all as proposed); 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
  2. Accounts, passwords and 2FA
  3. OpenID Connect
  4. Products as clients: Connect
  5. Sign-in flow and returning to the page
  6. Privacy: notice, consent, export, delete
  7. The church profile
  8. Screens
  9. Hub, licence and servers
  10. Security
  11. What changes in each repo
  12. Testing
  13. Releasing and rolling it out
  14. Decisions
  15. 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.

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 <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).

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

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.