diff --git a/README.md b/README.md index 91b6fc1..cdd93dd 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ things stand is in [`docs/HANDOVER.md`](./docs/HANDOVER.md). | `packages/contracts` | `@crosscode/contracts`: the shared JSON formats (zod schemas, JSON Schema, TypeScript types, sample payloads) used by every product, including Cross Events and the Hub | Phase 0, in progress | | `packages/ui` | `@crosscode/ui`: shared UI for the Website, App and Accounts | Placeholder, filled in during the Website phase | | `apps/accounts` | Accounts: the per-church sign-in (OpenID Connect) | Placeholder (phase 3) | -| `apps/website` | Church Website | Placeholder (phase 4) | +| `apps/website` | Church Website | Placeholder (phase 5) | | `apps/app` | Church App (PWA) | Placeholder (phase 6) | Cross Events (`joshua/hope-events`) moves in as `apps/events` in Events 2.2.0 diff --git a/docs/ACCOUNTS-1.0-PLAN.md b/docs/ACCOUNTS-1.0-PLAN.md index d1822f7..1f118e1 100644 --- a/docs/ACCOUNTS-1.0-PLAN.md +++ b/docs/ACCOUNTS-1.0-PLAN.md @@ -11,10 +11,10 @@ as a product: its pages carry the church's name and colours ("Sign in to Hope Fa 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, +**Who uses 1.0:** Cross Events **3.0** (phase 4, moved before the Website on 2026-11-19, ROADMAP +decision 38) moves its users across with their password hashes and 2FA; until then Events keeps its +own sign-in. The Church Website (phase 5) is built on it from its first release. 1.0 itself 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:** @@ -215,7 +215,7 @@ and its sign-in pages need the name, logo and colours before anything else exist 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 +`church.updated` call. The Website (phase 5) 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. @@ -297,7 +297,7 @@ phone-first. 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 +4. **Churches get Accounts with Events 3.0** (phase 4) or with the Website (phase 5), whichever comes first for them (decision 6). Until then nothing uses it, so it isn't installed for its own sake. ## Changes while building @@ -354,6 +354,6 @@ Confirmed by Joshua on 2026-11-18 (1, 4, 5 and 6 asked directly; the rest as pro ## 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). + or Accounts' own screen is the only place. Decide with the Website plan (phase 5). - Session lengths (30 days with "Keep me signed in") are a starting point; check them with Joshua before release. diff --git a/docs/EVENTS-2.4-PLAN.md b/docs/EVENTS-2.4-PLAN.md index 0ca5944..51f66d8 100644 --- a/docs/EVENTS-2.4-PLAN.md +++ b/docs/EVENTS-2.4-PLAN.md @@ -14,7 +14,7 @@ feed, **shows** events from linked products, and builds its SEO data with the ne settings page that says "No other products yet". The Website and App don't exist yet, so the "show events from" side is built and tested against -sample feeds (§8). It's ready for the Website (phase 4) without another Events release. +sample feeds (§8). It's ready for the Website (phase 5) without another Events release. **Done when:** @@ -422,7 +422,7 @@ Proposed in this plan, to confirm before building: - **Who owns the church profile (`crosscode.church/1`)** once there's more than one product? Events builds one from its own settings for its JSON-LD in 2.4.0, but doesn't serve it to - siblings. The Website (phase 4) is the natural owner; decide before phase 4. + siblings. The Website (phase 5) is the natural owner; decide before phase 5. - **Event `summary` and `tags`** go out empty because Events has no such fields. Add them in a later 2.x if the Website's event cards need them. - **A "cancelled" state in Events** (shown as cancelled rather than disappearing) would map to diff --git a/docs/EVENTS-3.0-PLAN.md b/docs/EVENTS-3.0-PLAN.md new file mode 100644 index 0000000..19b76d6 --- /dev/null +++ b/docs/EVENTS-3.0-PLAN.md @@ -0,0 +1,460 @@ +# Cross Events 3.0.0 — signing in through Accounts + +Phase **4** of [ROADMAP-v3.md](./ROADMAP-v3.md) (§3 "Moving Cross Events onto Accounts", §8, §9; +decisions 2, 14, 15, 17, 24, 38). Written 2026-11-19. **Not started; decisions below still to be +confirmed.** Moved before the Website on 2026-11-19 (decision 38), so this is the first product +that really signs people in through [Accounts](./ACCOUNTS-1.0-PLAN.md). + +**What 3.0.0 is:** Cross Events stops keeping passwords. Sign-in, sign-up, forgot password, 2FA, +the news question and the privacy notice move to the church's Accounts +(`accounts.`), and Events signs people in as an OIDC client with +`packages/auth-client`. Every existing Events user is copied into Accounts **with their password +hash, 2FA method and authenticator secret, consent and notice acceptance**, so nobody resets +anything. Roles, campus scopes, registrations, tickets and every other piece of Events data stay +in Events, keyed by the account's `sub`. + +It's a major version because it can't run without Accounts: a church needs Accounts installed and +connected before its Events can move. + +**Done when:** + +- `events@3.0.0`, `accounts@1.1.0` and `contracts@1.8.0` are tagged and pushed; the Hub refuses + to update an Events install to 3.0 until its church has Accounts 1.1.0 (decision 24). +- An Events 2.4.x install with real-looking data (the `ministry` and `multicampus` demo profiles) + updates to 3.0 and moves its users to Accounts with one admin action; afterwards every + imported person signs in with their **old password**, and an authenticator user with their + **old authenticator**, without resetting anything. +- Signing in from any Events page (an event page, `register?ticket=…`, the dashboard, a ticket + link) lands back on that exact page, through 2FA, a password reset, sign-up and a new privacy + notice; old `/login?redirect=…` links still work (ROADMAP §9 "Release checks"). +- Supervisors and admins can't use Events without 2FA (`acr_values=mfa`). +- Signing out of Events signs the person out of Accounts and every other product, and signing + out elsewhere ends their Events session. +- "Download my data" in Accounts includes Events' part; "Delete my account" waits while the + person has an open registration for an upcoming event (Events answers `deferred`). +- It updates and installs through the agent on the VM next to Accounts. +- crosscode-site says Cross Events signs in through the church's shared account, with updated + screenshots (ROADMAP §9, "Updating crosscode-site"). + +## Contents + +1. [Before starting](#before-starting) +2. [The shape](#1-the-shape) +3. [Users: `sub`, guests and roles](#2-users-sub-guests-and-roles) +4. [Signing in and out](#3-signing-in-and-out) +5. [Moving the users (the import)](#4-moving-the-users-the-import) +6. [Turning it on: the move, step by step](#5-turning-it-on-the-move-step-by-step) +7. [What moves to Accounts, page by page](#6-what-moves-to-accounts-page-by-page) +8. [Privacy: export, delete, retention](#7-privacy-export-delete-retention) +9. [Accounts 1.1.0](#8-accounts-110) +10. [New installs](#9-new-installs) +11. [Security](#10-security) +12. [What changes in each repo](#11-what-changes-in-each-repo) +13. [Testing](#12-testing) +14. [Releasing and rolling it out](#13-releasing-and-rolling-it-out) +15. [Decisions to confirm](#decisions-to-confirm) +16. [Still open](#still-open) + +--- + +## Before starting + +- **Accounts 1.0.x is proven first:** its VM test and a run on real Postgres + (ACCOUNTS-1.0-PLAN, "Not yet"). 3.0 is the first thing that puts real people on it, so those + have to pass before any 3.0 code is merged. +- **Events 2.4.x's e2e run on Postgres and VM test** (EVENTS-2.4-PLAN §8) are done: 3.0 builds on + 2.4's Linked products and Connect, which are what register Events as an OIDC client. +- `apps/events` and `apps/accounts` build and test clean on `main` (`npm run check`). +- **Module format:** `@crosscode/auth-client` and `openid-client` 6 are ESM only, and the Events + backend is CommonJS. Check the Node version on the servers allows `require()` of ESM (Node 22.12+ + / 20.19+); otherwise give `auth-client` a CommonJS build too (`tsup --format esm,cjs`). Decide + this first, since every sign-in path goes through it. + +## 1. The shape + +``` + Events (events.hopefamily.co.za) Accounts (accounts.hopefamily.co.za) + ───────────────────────────────── ───────────────────────────────────── + /login?redirect=/events/camp/register ──302──▶ /api/auth/signin?returnTo=… (Events backend) + │ PKCE + state(returnTo), pending cookie + ▼ + ──302──▶ authorize → /signin?uid=… (password, 2FA, + reset, sign-up, notice, news: all Accounts) + /api/auth/callback ◀──302── code ──────────────── ┘ + │ finishSignIn → claims (sub, name, email, phone, news, notice) + │ find or make the Events User by sub, update the local copy, check role / 2FA + ▼ + /auth/complete#handoff → frontend swaps the one-time handoff for Events' own token + ▼ + /events/camp/register (the exact page the person started on) + + Accounts → Events (signed with the link's secret, ACCOUNTS-1.0-PLAN §6): + POST /api/auth/backchannel-logout end that person's Events sessions + POST /api/accounts/v1/events user.updated · user.export · user.deleted +``` + +- **Events keeps its own session** (ACCOUNTS-1.0 decision 3: products keep their own sessions, no + refresh tokens). That is today's Events token, with `tokenVersion`, so every API route, the + check-in scanner, impersonation and `protect` keep working unchanged. Only how a token is + *obtained* changes (§3). +- **No password, 2FA secret or recovery code is kept in Events** once the move is finished (§5). + The columns stay in 3.0 so the move can be undone; 3.1 drops them. +- Accounts' address comes from Linked products (the Hub-listed URL Events 2.4 already connects + to), so there is **no new `.env` variable** for the address. The link secret is the one Connect + already stores. + +## 2. Users: `sub`, guests and roles + +**Recommended change from ROADMAP §3:** instead of making `User.id` equal the account's `sub`, +Events gets a new column **`User.accountId`** (nullable, unique). See decision 1. + +- For every imported user, Accounts **creates the account with the Events user's id as its `sub`** + (`Account.id = User.id`), and Events sets `accountId = id`. So for everyone who exists today, + `sub` and `User.id` are equal, which is what the roadmap wanted, and no foreign key in Events + is rewritten. +- The column matters for the cases where they can't be equal: + - **Guests** (`guest+…@guest.local`, made by staff at the door or by a registration without an + account, `utils/accountMatch.js`, `registrationAdmin.ts`) are not people who sign in. They are + **not imported** and keep `accountId = null`. When someone later signs in through Accounts with + the same **verified** email as a guest record, Events links them (`accountId` set on the guest + row), as `accountMatch.js` already matches today. + - **An email already in Accounts** under another `sub` (a person who made an account before the + move, e.g. through a test product or another product): the import doesn't overwrite it. Events + links that User to the existing account (`accountId` = the existing `sub`), and the person + keeps the **Accounts** password. These are listed in the move report (§5). + - **Deleted** (`@deleted.invalid`, `@deleted.local`) and anonymised users: not imported, + `accountId = null`, nothing changes. +- **Roles stay in Events** (`admin`, `supervisor`, `staff`, `user`) with campus scopes, as today + (ACCOUNTS-1.0-PLAN §2). Someone new to Events who signs in through Accounts arrives as `user`. +- **Accounts admins:** the move asks which Events admins should also be Accounts admins (default: + every Events `admin`, ticked; decision 4). They need 2FA, which Events admins already have. +- `isActive = false` users are imported as `deactivated`; they can't sign in anywhere until an + Accounts admin reactivates them (an Events admin reactivating them in Events calls Accounts, §8). + +## 3. Signing in and out + +### Starting a sign-in + +- **One backend route:** `GET /api/auth/signin?returnTo=` calls + `auth.startSignIn(returnTo, { requireTwoFactor, loginHint })`, sets the pending cookie + (`HttpOnly; Secure; SameSite=Lax; Path=/api/auth`, 10 minutes) and redirects to Accounts. + `returnTo` goes through `safeReturnPath` (a relative path starting with a single `/`; anything + else becomes `/`). +- **`/login` stays a page** in the frontend, but only forwards: `/login?redirect=…` → + `/api/auth/signin?returnTo=…`. So every old link, email, PDF and QR code with + `/login?redirect=` keeps working (ROADMAP §3). +- `useRequireAuth` and every "Sign in" link (49 files reference `/login`) use one helper, + `signInHref(returnTo = current path + query)`, so they all return to the page they were on. +- `/register` forwards the same way with `prompt=create` (Accounts opens on sign-up) and the same + return path. Sign-up being off in Accounts (staff-only churches) shows Accounts' own message. +- `/forgot-password` forwards to Accounts' forgot-password, with the return path. +- `/reset-password` and `/activate-account` links already in people's inboxes: the page says the + church's sign-in has moved and offers "Set a new password" (Accounts' forgot-password, email + filled in when the token still identifies the person). + +### 2FA for staff + +`requiresTwoFactor(user)` is unchanged (supervisors and admins always; settings may add staff). +Events doesn't know the person's role until after the callback, so: + +1. The first sign-in asks for nothing extra. +2. At the callback, if the Events user's role needs 2FA and the ID token's `acr` / `amr` (`mfa`) doesn't + show it, Events starts **a second sign-in with `acr_values=mfa`** straight away (same + `returnTo`). Accounts asks for 2FA, or sets it up first if the person has none. The person sees + one 2FA prompt, not two sign-ins, because the Accounts session is already there. +3. A user whose role is raised to supervisor in Events gets step 2 on their next sign-in. + +The Events "trusted device" (`TrustedDevice`, skip 2FA for 30 days) goes away: that decision is +Accounts' now ("Keep me signed in"). + +### The callback + +`GET /api/auth/callback`: + +1. `auth.finishSignIn(url, pendingCookie)`; clear the cookie. Errors (expired, refused, bad + claims) show a short page with "Try again" (a fresh sign-in with the same `returnTo`). +2. Find the User by `accountId = sub`. Not found: link a guest with the same verified email (§2), + or make a new `user`. +3. Update the local copy from the claims: name, email, phone, `newsEmail` / `newsWhatsApp`, + `noticeVersionAccepted`, `lastLoginAt`. Keep the ID token (for sign-out's `id_token_hint`) in + a server-side row keyed to the Events session, not in the browser. +4. `isActive = false` in Events: a "Your access to Events has been turned off, ask the office" + page (the Accounts account is fine; it's Events access that's off). +5. Make a **one-time handoff code** (random, 60 seconds, single use, hashed in the database) and + redirect to `/auth/complete#`. The page posts it to `POST /api/auth/handoff`, which + answers with Events' usual token and user, exactly as `/auth/login` did. The frontend stores it + as today and goes to `returnTo`. + +The fragment keeps the code out of server logs and `Referer`. A handoff can't be swapped twice. + +### Signing out + +- **Sign out** in Events: bump the user's `tokenVersion` (ends their Events sessions), then send + the browser to `auth.signOutUrl(idToken)`. Accounts ends its session and the back-channel logout + reaches every product; the browser comes back to Events' home page signed out. +- **Back-channel logout** (`POST /api/auth/backchannel-logout`): `auth.verifyLogoutToken`, then bump + that user's `tokenVersion`. Events tokens are short-lived and checked against `tokenVersion` on + every request, so the next API call fails and the frontend shows signed out. +- **Impersonation** is unchanged: it's an Events session an admin starts in Events, not a sign-in. + +## 4. Moving the users (the import) + +### What's copied + +| Events | Accounts | Notes | +|--------|----------|-------| +| `User.id` | `Account.id` (the `sub`) | §2 | +| name, email (lower-case), `phoneNumber` | name, email, phone | `givenName` / `familyName` left empty | +| `password` (bcrypt or Argon2id) | `passwordHash` | Accounts already verifies both and re-hashes bcrypt on sign-in | +| — | `emailVerified` | `true` if they have ever signed in (`lastLoginAt` set) or activated; otherwise `false`, and Accounts verifies the email on first sign-in | +| `twoFactorEnabled` + `twoFactorMethod` | `twoFactorMethod` | `authenticator` → `totp`; email / WhatsApp as they are | +| `totpSecret` (encrypted with Events' key), `totpLastStep` | `totpSecret` (encrypted with Accounts' key), `totpLastStep` | decrypted in Events, sent encrypted (§10), encrypted again by Accounts | +| unused `RecoveryCode`s | — | **Not copied**, see decision 2. People with 2FA get new codes after their first sign-in | +| `failedAttempts`, `lockUntil` | `failedSignIns`, `lockedUntil` | so a lockout in progress isn't lifted by moving | +| `newsEmail`, `newsWhatsApp`, `newsAskedAt` | the same | | +| `CommunicationConsent` history | `ConsentChange` | `source: "events_import"`; POPIA proof isn't lost | +| `noticeVersionAccepted`, `NoticeAcceptance` | `noticeVersionAccepted`, `NoticeAcceptance` | | +| `PrivacyNotice` versions | `PrivacyNotice` (same version numbers) | only if Accounts has published none of its own yet; otherwise the move stops and asks (decision 5) | +| `lastLoginAt`, `isActive` | `lastSignInAt`, `status` | | +| `role = admin` | `role = admin` | only those ticked (§2) | + +**Not copied:** `SecurityEvent` (Events' login history) stays in Events, readable as before and +expiring under its retention rule; Accounts' `LoginEvent` starts at the move. `TrustedDevice`, +`PasswordReset` and pending 2FA challenges are dropped. Events' notification preference +(`notificationPreference`: how Events itself sends tickets and reminders) stays in Events. + +**The church profile:** if Accounts' church profile has no name or logo yet, the move fills them +from Events' site settings (organisation name, logo, primary colour), so the sign-in page looks +like the church straight away. Events keeps its own settings in 3.0 (see Still open). + +### How it's sent + +- A new **link call**, `POST /api/accounts/v1/import` (contracts 1.8.0, + `crosscode.identity-import/1`), signed with the link secret like every other link call + (`LINK_HEADERS`), in **batches of 200 people**. +- Secrets in the payload (password hashes, TOTP secrets) are additionally **encrypted with a key + derived from the link secret** (AES-256-GCM, `HKDF(linkSecret, "crosscode.identity-import/1")`), + so they never show up in a proxy log or an error report even if TLS is terminated in between. +- **Idempotent:** Accounts upserts by `id`; sending a batch twice changes nothing. A batch answers + per person: `created`, `updated`, `linked` (email already there under another `sub`, with that + `sub`), or `refused` (with why: bad email, duplicate email in the batch). +- Only allowed **while the move is in progress** for that link (Accounts 1.1.0 keeps a flag per + linked product, set by the move's first call and cleared by its last), and only from a product + of type `events`. + +## 5. Turning it on: the move, step by step + +**3.0.0 starts with local sign-in still working**, so updating a church to 3.0 changes nothing +for its people until an admin moves sign-in (decision 3). Then: + +1. **Settings → Sign-in** (new, admins only) says where sign-in stands: *In Cross Events* → + *Moving* → *Through Accounts*. It needs Accounts **connected** under Linked products; if it + isn't, it says so with a link there. +2. **Check:** a dry run, nothing written. It shows how many people would be created, linked to an + existing account, skipped (guests, deleted), and anything that would stop the move (Accounts + older than 1.1.0, a notice conflict, emails Accounts would refuse). The admin ticks which Events + admins also become Accounts admins. +3. **Move:** Events stops new sign-ins for a moment (people already signed in stay signed in; + the sign-in page says "One moment, we're updating the sign-in"), sends every batch, then + **checks** by asking Accounts for the count and a hash of the imported ids. Only when they + match does it switch: `auth_mode = accounts`. Typically under a minute for a few thousand people + (Argon2 isn't run; hashes are copied). +4. If anything fails, it stays on *In Cross Events* with the error, and the move can be run again + (it's idempotent). +5. **After the switch:** existing Events sessions keep working (the token didn't change), so + nobody is thrown out mid-registration. Their next sign-in goes through Accounts. +6. A **move report** (also in the audit log): counts, the people linked to an existing account, + and the admins made Accounts admins. Emailed to the admin who ran it. +7. **Undo**, for 14 days: switches `auth_mode` back to `local`. The Events password columns were + kept, so people sign in with the password they had **at the move**; changes made in Accounts + since then (a new password, 2FA set up) don't come back to Events, and the page says so. After + 14 days, a job clears Events' password hashes, TOTP secrets and recovery codes, and Undo goes. + +The Hub can also start the move (decision 3 alternative): not in 3.0; the button is in Events. + +## 6. What moves to Accounts, page by page + +| Events today | 3.0 | +|--------------|-----| +| `/login`, `/register`, `/forgot-password` | Forward to Accounts with the return path (§3) | +| `/reset-password`, `/activate-account` | "Sign-in has moved" + Set a new password (§3) | +| Login code page (2FA challenge) | Gone; Accounts asks | +| Profile: name, email, phone | Shown read-only, with **Change in your account** (Accounts' account page, coming back to the Events profile). Notification preference stays editable in Events | +| Profile: password, 2FA, recovery codes, trusted devices | **Your sign-in and security** → Accounts' account page | +| News question and notice prompts after login | Gone; Accounts asks before coming back (`newsPromptPending` / `noticePromptPending` are always false in `auth_mode = accounts`) | +| Privacy centre: download my data, delete my account | Link to Accounts (§7). The Events-only items stay (what Events holds, consent history for Events messages) | +| Privacy centre: my login history | Events' old history, plus "Recent sign-ins are in your account" | +| Admin → Users: add a person | Creates or finds the account in Accounts (§8, `people.ensure`), then sets the Events role. Accounts sends the "set your password" email instead of Events' activation link | +| Admin → Users: reset 2FA, unlock, resend activation | Call Accounts (§8), audited in both | +| Admin → Users: deactivate | Turns off **Events** access (`isActive`); "also deactivate their account everywhere" is a separate tick that asks Accounts | +| Admin → Users: change email / name | Through Accounts (`people.update`), then `user.updated` updates Events' copy | +| Admin → 2FA methods per staff account (2.3.0) | Read from the claims at sign-in (`two_factor`), shown as before | +| Settings → Privacy notice versions | Managed in Accounts; Events' screen links there | +| Settings → 2FA for staff roles | Stays in Events (it decides when Events sends `acr_values=mfa`) | +| Broadcasts "News & announcements" audience | Unchanged: uses the local `newsEmail` / `newsWhatsApp`, kept current from the claims and `user.updated` | +| Unsubscribe links in news messages | Turn news off in Accounts through `people.consent` (§8), so it's off for every product; the page still works without signing in | +| Setup wizard (new install) | §9 | + +All of this applies only in `auth_mode = accounts`; in `local` (before the move, or after Undo) +Events works as 2.4. + +## 7. Privacy: export, delete, retention + +Events answers Accounts' signed calls at `POST /api/accounts/v1/events` (`auth.verifyAccountsCall`): + +- **`user.updated`:** update the local copy (name, email, phone, news consent, notice version). + Unknown `sub`: answer ok and ignore. +- **`user.export`:** Events' part as `crosscode.identity/1` export sections: registrations, tickets, + payments, check-ins, certificates, form answers, Events-only consent history, login history + before the move. This is what Events' own "Download my data" bundles today + (`churchExport.ts`, the privacy centre export), reshaped into sections. +- **`user.deleted`:** the existing Events rules (anonymise; refunds and financial records kept as + the law requires). **`deferred`** with `retryAfter` while the person has an open registration + for an upcoming event, as Events does today; Accounts asks again. +- **Retention of inactive accounts** moves to Accounts (ACCOUNTS-1.0-PLAN §6). Events' inactivity + job stops warning and deleting people with an `accountId`; it still cleans up guests and old + Events-only data as today. +- **Access log:** Events keeps logging admins viewing a person's Events data; Accounts logs the + account side. + +## 8. Accounts 1.1.0 + +What Events 3.0 needs from Accounts, all as link calls signed with the link secret and allowed +only for a connected product: + +- **`POST /api/accounts/v1/import`** (§4), with the per-link "move in progress" flag, the + dry-run mode (`check: true`) and the final count / hash check. +- **`people.ensure`:** find an account by email or make one (no password; sends the church's "set + your password" email with a link back to the product). For Admin → Users → Add. +- **`people.update`**, **`people.resetTwoFactor`**, **`people.unlock`**, **`people.deactivate`**, + **`people.consent`** (news off, from an unsubscribe link): what an Events admin can already do, + done to the account. Each is checked against the calling product's link, audited in Accounts + with the product and the Events admin's `sub`, and limited to people that product knows. +- **`prompt=create`** opens sign-up directly (sign-up is in 1.0; this is the entry point). +- **Legacy reset and activation tokens:** none; Events shows "Set a new password" instead (§3). +- **The ID token's `amr` / `acr`** say whether 2FA was used on this sign-in (already in 1.0; make + sure `acr` is `mfa` exactly when a second factor was used, which §3 relies on). +- Accounts' WHATS-NEW notes the Events move; Events 3.0's WHATS-NEW says + `## 3.0.0 — requires accounts 1.1.0` (decision 24, the Hub and the `crosscode` script refuse the + update until it's met). + +## 9. New installs + +- **Hub New install of Events 3.x** installs **Accounts first** if the church doesn't have it + (an `install` job for Accounts, then an `add-product` job for Events), as New install already + does for a church's first product (Hub 2.3.0). +- **Connect happens by itself** for a new install: the setup wizard (or the Hub's install + record) connects Events to the church's Accounts using the Hub's Linked products, so no admin + has to find the button. +- **The setup wizard** no longer makes an admin with a password. Its last step is **Sign in with + your church account**: the person who completes the wizard (holding the setup token) signs in + through Accounts (making an account if needed), and that `sub` becomes Events' first `admin`. + `SETUP_TOKEN_GRACE_SECONDS` still lets them finish before 2FA is set up; Accounts then asks for + 2FA because Events sends `acr_values=mfa` for admins. +- A new install starts in `auth_mode = accounts`; there's nobody to move. +- Demo data (`crosscode demo`, `npm run demo:*`): demo people are made in Accounts too (through + the import call with the demo's known password), so a demo site can be signed in to as before. + +## 10. Security + +- Exact-match redirect URIs (Connect registers `/api/auth/callback`), PKCE, `nonce`, + state checked, `safeReturnPath` on every return: all from `auth-client` and Accounts 1.0. +- The pending-sign-in cookie and the handoff code are single use and short-lived; the handoff goes + in the URL fragment, never the query. +- Import payloads: signed **and** encrypted (§4); only while a move is in progress; only from a + connected Events install; every batch audited in both apps. A stolen link secret already allows + the 1.0 calls; the import adds no new secret. +- After the move, Events holds **no password hash or 2FA secret** once Undo expires (14 days). +- `/api/auth/*` rate-limited as `/auth/login` is today. +- Tokens: Events' existing token rules (pinned HS256, `tokenVersion`) are unchanged; back-channel + logout makes `tokenVersion` the single switch for "this person is signed out". + +## 11. What changes in each repo + +| Repo | Change | Version | +|------|--------|---------| +| `crosscode-platform` `apps/events` | §2–§7 and §9: `User.accountId`, `/api/auth/*`, the handoff, `auth_mode`, Settings → Sign-in (check / move / undo), `/api/accounts/v1/events`, forwarding pages, profile and privacy centre links, admin user actions through Accounts, setup wizard, demo data. Migration guide (`MIGRATING-TO-3.md`, as `MIGRATING-TO-2.md`) | `events@3.0.0` | +| `crosscode-platform` `apps/accounts` | §8: import, `people.*` calls, `prompt=create`, per-link move flag | `accounts@1.1.0` | +| `crosscode-platform` `packages/contracts` | `crosscode.identity-import/1` (batch, per-person result, check), the `people.*` call schemas, paths | `contracts@1.8.0` | +| `crosscode-platform` `packages/auth-client` | `verifyAccountsCall` already there; add `callAccounts()` (signed link calls to Accounts) and, if needed, a CommonJS build (Before starting) | workspace | +| `crosscode-platform` `scripts/` | Nothing new expected: `deploy` already updates Accounts first and checks `requires accounts …`. Check `crosscode demo` for §9 | — | +| `events-hub` | New install of Events 3.x adds Accounts first and connects them (§9); release requirements already work (decision 24). Vendored contracts 1.8.0 | Hub `v2.5.0` | +| `crosscode-site` | Cross Events page: sign-in through the church's shared account; screenshots of the sign-in (ROADMAP §9) | `v1.6.0` | + +## 12. Testing + +- **Unit (Jest, Events):** the callback (new user, existing by `sub`, guest linked by verified + email, unverified email not linked, deactivated in Events), the 2FA step-up decision from + `acr`, handoff (single use, expiry), `safeReturnPath` on every entry point, back-channel logout + bumping `tokenVersion`, `user.*` handlers including `deferred`, the import batch builder + (mapping `authenticator` → `totp`, guests and deleted skipped, secrets encrypted). +- **Unit (Jest, Accounts):** import upsert and idempotency, `linked` on an existing email, refused + outside a move or from a non-Events link, imported bcrypt and Argon2id passwords sign in, an + imported TOTP secret produces valid codes, `people.*` limited to the product's people. +- **The move, end to end, on Postgres:** load the `multicampus` demo into Events 2.4.1, update to + 3.0, run Check then Move, then sign in as a sample of the demo people (bcrypt, Argon2id, + authenticator, email 2FA, a locked-out person stays locked), then Undo and sign in locally. +- **Playwright (the release checks, ROADMAP §9):** Events and Accounts running together (Accounts' + `e2e/server.ts` approach for Accounts, the Events e2e Postgres for Events). From a deep link + (`/events//register?ticket=…`): sign in, sign in with 2FA, password reset, sign-up, a new + notice: each lands back on that page. `/login?redirect=` still works; `?redirect=https://evil` + and `//evil` land on `/`. A supervisor without 2FA is made to set it up. Signing out of Events + signs out of Accounts and the test product; signing out of the test product ends the Events + session. +- **VM:** a church with Events 2.4.1 (adopted) gets Accounts through the Hub (`add-product`), + Connect, update Events to 3.0 through the agent (refused before Accounts 1.1.0), Move, sign in + through the real proxies; then a New install of Events 3.0 for a second church (Accounts first, + connected, setup wizard). Uninstall exports include both. + +## 13. Releasing and rolling it out + +1. `contracts@1.8.0` → Hub `v2.5.0` (vendored contracts) deployed. +2. `accounts@1.1.0` tagged after its tests and the move test. +3. `events@3.0.0` tagged after the e2e and VM runs, with `MIGRATING-TO-3.md`. +4. crosscode-site `v1.6.0`. +5. **Per church:** install Accounts (`add-product` from the Hub) → Connect → update Events to + 3.0 (nothing changes for members yet) → tell the church office → **Move** at a quiet time, not + the day before a big event's registrations close → watch the first day's sign-ins (Accounts' + login events, Events' audit log) → after 14 days the Undo window closes and the old secrets are + cleared. **The demo site first, then Hope Family Church**, then the rest. + +## Decisions to confirm + +Proposed; confirm with Joshua before building. + +1. **`User.accountId` instead of rewriting `User.id`** (§2). Every imported person still gets + `sub = User.id`; the column handles guests, deleted people and emails already in Accounts + without rewriting every foreign key in Events. *Changes the wording of ROADMAP §3 ("keeps its + id, now equal to the account sub"), which stays true for every imported person.* +2. **Recovery codes are not carried over** (§4). Events stores them as an HMAC keyed with its + `JWT_SECRET` (10 characters), and Accounts as a SHA-256 (12 characters), so Accounts can't + check an Events code without being given Events' `JWT_SECRET`, which also signs Events' tokens + and encrypts its settings. Instead, people with 2FA are shown 10 new recovery codes in + Accounts right after their first sign-in (their authenticator itself carries over, so they're + never locked out). *Changes ROADMAP §3 ("unused recovery codes" carried over).* The + alternative is a legacy-code check that calls Events, which keeps Events in every recovery + sign-in forever. +3. **The move is an admin action after the update, with 14 days' Undo** (§5), not part of the + database migration when 3.0 is deployed. Updating and moving can then be done on different + days, a failed move changes nothing, and `crosscode deploy` stays a normal deploy. The cost is + that 3.0 carries the local sign-in for one more release (removed in 3.1). +4. **Every Events admin becomes an Accounts admin by default** at the move (ticked, can be + unticked), so the church office can manage sign-in from day one. +5. **Events' privacy notice versions become Accounts' versions**, numbers kept, when Accounts + has none of its own; otherwise the move stops and an admin chooses which wins. +6. **Events keeps its own session token** (not a new cookie session) and gets it through a + one-time handoff after the callback (§3), so the whole API, the scanner and impersonation are + untouched. Moving Events' token from `localStorage` to an HttpOnly cookie is worth doing, but + separately. +7. **Unsubscribe from news turns it off in Accounts** (every product), since consent lives there + now (§6). + +## Still open + +- Whether Events reads the church profile from Accounts (name, logo, colours, campuses) instead + of its own site settings. Not needed for sign-in; suggested for 3.1 together with the Website + plan (ACCOUNTS-1.0-PLAN "Still open"). +- Session lengths in Accounts (30 days with "Keep me signed in") against Events' current token + lifetime: people shouldn't be signed out of Events more often than today. +- How Hub stats for Events report 2FA per staff account after the move (from the claims Events + saves at sign-in, or only from Accounts). diff --git a/docs/HANDOVER.md b/docs/HANDOVER.md index 214a8fa..db2436d 100644 --- a/docs/HANDOVER.md +++ b/docs/HANDOVER.md @@ -1,6 +1,6 @@ # Handover — Cross Code, all products -Last updated: 2026-11-18. **The plan is [ROADMAP-v3.md](./ROADMAP-v3.md)** (decided 2026-11-03, +Last updated: 2026-11-19. **The plan is [ROADMAP-v3.md](./ROADMAP-v3.md)** (decided 2026-11-03, decisions table near the end). This file says where each phase stands and what comes next. Product-specific notes (where the code lives, known gaps) stay with each product: Cross Events' are in [`apps/events/docs/HANDOVER.md`](../apps/events/docs/HANDOVER.md), and the Hub's are in @@ -32,7 +32,8 @@ every release). | 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) | **Released** 2026-11-18 (`events@2.4.0`, `contracts@1.4.0`, Hub `v2.2.0`, crosscode-site `v1.4.0`; [EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md)). **Before any church gets it:** the Events e2e run on Postgres and the VM test (EVENTS-2.4-PLAN §8) | | 3 | Accounts 1.0.0 (+ contracts 1.5.0, agent 1.1.0, Hub 2.3.0) | **Released** 2026-11-18 (`accounts@1.0.0`, `contracts@1.5.0`, `agent@1.1.0`, Hub `v2.3.0`, crosscode-site `v1.5.0`; [ACCOUNTS-1.0-PLAN.md](./ACCOUNTS-1.0-PLAN.md)). 37 backend and 8 Playwright tests pass without Postgres. **Before installing it for a church:** the VM test and a run on real Postgres; a Hub release source for `accounts@` tags | -| 4–7 | Website 1.0.0 → Events 3.0.0 → App 1.0.0 → App 1.x | Not started | +| 4 | Cross Events 3.0.0: sign-in through Accounts, users migrated with their password hashes and 2FA | **Next.** Moved before the Website on 2026-11-19 (ROADMAP decision 38). Planned: [EVENTS-3.0-PLAN.md](./EVENTS-3.0-PLAN.md) (with contracts 1.8.0, Accounts 1.1.0, Hub 2.5.0); its decisions still to be confirmed | +| 5–7 | Website 1.0.0 → App 1.0.0 → App 1.x | Not started | ## Next up diff --git a/docs/ROADMAP-v3.md b/docs/ROADMAP-v3.md index 325b549..5affd91 100644 --- a/docs/ROADMAP-v3.md +++ b/docs/ROADMAP-v3.md @@ -26,6 +26,9 @@ The Hub can now trigger changes, but no site depends on it to keep running and t polls (it has no URL or open port). Rule 2 (§1), §5, §8 and §9 are updated; decisions 27–37 change decisions 10 and 23. +**Updated 2026-11-19:** phases 4 and 5 swapped: **Cross Events 3.0.0** (sign-in through Accounts) +comes before the **Church Website** (§9, decision 38). + --- ## Contents @@ -617,9 +620,9 @@ 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. **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 | +| 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. [ACCOUNTS-1.0-PLAN.md](./ACCOUNTS-1.0-PLAN.md) (with contracts 1.5.0, `packages/auth-client`, Hub 2.3.0). **Released 2026-11-18** (`accounts@1.0.0`, 1.0.1 on 2026-11-19); the VM test and a run on real Postgres are still to do before a church gets it | Every later product signs in through it | +| 4 | **Cross Events 3.0.0** | Sign-in moves to Accounts; user migration keeping password hashes; migration guide. **Planned 2026-11-19:** [EVENTS-3.0-PLAN.md](./EVENTS-3.0-PLAN.md) (with contracts 1.8.0, Accounts 1.1.0, Hub 2.5.0; decisions to confirm) | Breaking change, so a major version. **Moved before the Website on 2026-11-19** (decision 38): Events is the product churches use today, so Accounts is proven on real users first, and the Website then starts with a church whose people already have accounts | +| 5 | **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. Built on Accounts from day one | | 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 | | 7 | Church App 1.x | Reading plans, sermons, groups, pastoral care, serving, giving links, directory | After House of Prayer is in use | @@ -641,8 +644,8 @@ At the end of each phase, update it in the same sitting and deploy it (its `DEPL | 1d Agent 1.0.0 + Hub 2.1.0 | Nothing (it changes how installs are run, not what churches buy) | | 2 Events 2.4.0 | "Works with the Church Website and App" (event feed, Linked products) on the Cross Events page, as "coming" until those ship | | 3 Accounts 1.0.0 | "One sign-in for all your church's products" on the Products page. Accounts isn't sold, so no page or price of its own | -| 4 Website 1.0.0 | **Church Website goes on sale:** `status: "available"` and its own page in `src/data/products.mjs` / `src/pages/products/`, R99 + storage add-on in `pricing.mjs`, **a showcase of the four templates** (a page per template with screenshots of the same demo church in each), screenshots from a demo church (fictional people only), FAQ, home page, contact form product list, `SoftwareApplication` JSON-LD (§11) | -| 5 Events 3.0.0 | Cross Events page: sign-in through the church's shared account. Update screenshots that show the login | +| 4 Events 3.0.0 | Cross Events page: sign-in through the church's shared account. Update screenshots that show the login | +| 5 Website 1.0.0 | **Church Website goes on sale:** `status: "available"` and its own page in `src/data/products.mjs` / `src/pages/products/`, R99 + storage add-on in `pricing.mjs`, **a showcase of the four templates** (a page per template with screenshots of the same demo church in each), screenshots from a demo church (fictional people only), FAQ, home page, contact form product list, `SoftwareApplication` JSON-LD (§11) | | 6 App 1.0.0 | **Church App goes on sale:** own page, active-member tiers in `pricing.mjs`, House of Prayer screenshots, the bundle examples from §10 | | 7 App 1.x | New modules added to the App page's feature list as each one ships | @@ -846,6 +849,12 @@ ranking. | 36 | `.env` configuration | **Database and other server values are set once per server in the Hub**, stored encrypted and sent encrypted to that server's agent with each job. `.env` files come from a per-product template; updates only append new variables; secrets are generated on the server and never leave it | | 37 | Server stats | Every agent reports RAM, CPU, disk and PM2 processes every minute; the Hub keeps minutes for 7 days and hours for 90 days, shows spikes, and emails alerts | +**Added 2026-11-19** + +| # | Question | Decision | +|---|----------|----------| +| 38 | Order after Accounts | **Cross Events 3.0.0 (sign-in through Accounts) is phase 4, the Church Website phase 5** (swapped). Events is what churches use today, so Accounts is proven on real users and their migrated passwords and 2FA first; the Website then starts with a church whose people already have accounts | + ## Still open Nothing. crosscode-site is updated at the end of each phase (§9, "Updating crosscode-site"); the diff --git a/docs/VERSIONS.md b/docs/VERSIONS.md index 85157b6..d525d5f 100644 --- a/docs/VERSIONS.md +++ b/docs/VERSIONS.md @@ -29,7 +29,7 @@ on each run, so merging to `main` and pushing releases it. Its changes are liste | `@crosscode/auth-client` | `packages/auth-client` | 1.0.0 (released with Accounts 1.0.0) | | `@crosscode/seo` | `packages/seo` | 1.0.0 (released with Events 2.4.0) | | `@crosscode/ui` | `packages/ui` | 0.1.0 | -| Website | `apps/website` | 0.0.0 (not started, phase 4) | +| Website | `apps/website` | 0.0.0 (not started, phase 5) | | App | `apps/app` | 0.0.0 (not started, phase 6) | These shared packages ship inside the apps that use them, from the same checkout, so they don't