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>
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.0andcontracts@1.5.0are 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
- The shape
- Accounts, passwords and 2FA
- OpenID Connect
- Products as clients: Connect
- Sign-in flow and returning to the page
- Privacy: notice, consent, export, delete
- The church profile
- Screens
- Hub, licence and servers
- Security
- What changes in each repo
- Testing
- Releasing and rolling it out
- Decisions
- 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-providermounted 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, productaccounts), 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/uigets 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=mfaand 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/1method name istotp; Events 2.3 calls itauthenticator. 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 newpackages/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 andpackages/auth-clientare 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). Scopesopenid profile email phonepluscrosscodefor 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_uriexact 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_PATHSin 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):
- The product sends the person to
/api/oidc/authwith PKCE, a nonce, andstate=encodeState({ nonce, returnTo: <path and query> }); the nonce also goes in an HttpOnly cookie. - 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 theuid, 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. - Accounts finishes the interaction; oidc-provider redirects to the registered
redirect_uriwith the code and the untouchedstate. - 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.updatedto every linked product. - Download my data: Accounts' own part (profile, sign-ins, consents) plus a
user.exportcall to every linked product; the answers (crosscode.identity/1export 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.deletedto each product; adeferredreply (e.g. an open registration for an upcoming event) is asked again after itsretryAfter; the account is anonymised once every product has answereddeleted. Admins see the state per product. - Back-channel calls (
POST <product>/api/accounts/v1/events) go through aDeliverytable 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 andapps/accounts/WHATS-NEW.md(already in the release-source table). crosscode:scripts/products/accounts.shwith the same hooks as Events,accountsinSUPPORTED_PRODUCTS,crosscode install … --products accounts,…(served onaccounts.<address>),crosscode add <church> accountsfor existing churches, anddeploythen 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
accountsas a product (releaseTagSchema,productSchema); the frp port list gets its two ports. - Cross Code address:
accounts.<church>.crosscode.co.zalikeevents.…; 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;
statereturned untouched;safeReturnPathon the product side;return_tonever accepted from a query string on Accounts' own pages. - PKCE required; authorization codes single-use, 60 seconds;
noncerequired. - Only the configured domain is served (nginx
server_name,TRUST_PROXYas Events). - Rate limits and lockout (§2);
LoginEventfor 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_secretderivation, back-channel signing and retries, deferred deletion, the export bundle. - OIDC: a test product built on
packages/auth-clientruns against the real provider in the tests: discovery, PKCE required (a request without it is refused), wrongredirect_urirefused, code reuse refused, ID token claims fitcrosscode.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/1gets anaccountssection).
13. Releasing and rolling it out
contracts@1.5.0, then Hubv2.3.0(vendored contracts) deployed.accounts@1.0.0tagged after the e2e and VM runs.- crosscode-site
v1.5.0. - 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):
- 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. - Connect registers the OIDC client (§4), with the client secret derived from the link's secret; no client registration screen.
- Products keep their own sessions; no refresh tokens; sign-out everywhere by back-channel logout (§3).
- Accounts never goes read-only on a lapsed licence: only admins see a banner (§9).
- Sign-up is on by default (members can create an account), and an admin can switch it off (staff-only churches).
- Accounts is installed with a church's first Website, or with Events 3.0, not before.
- Events' sign-in code is copied, not shared (§1);
packages/auth-clientis the shared piece, on the product side. acr_values=mfalets 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.