|
|
|
@@ -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.<church's address>`), 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=<path>` 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#<code>`. 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 <accounts>/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 `<events url>/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/<slug>/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).
|