Compare commits

...
8 Commits
Author SHA1 Message Date
joshua ac017395df Merge branch 'docs/events-3-first' 2026-11-19 12:50:28 +02:00
joshuaandClaude Opus 5.5 258f8b820d docs: plan for Cross Events 3.0 (sign-in through Accounts)
EVENTS-3.0-PLAN.md: User.accountId, sign-in through auth-client with a
one-time handoff to Events' own token, 2FA step-up for staff, the user
import into Accounts (hashes, authenticator secrets, consent, notices),
an admin-run move with 14 days' undo, and what Accounts 1.1.0, contracts
1.8.0 and Hub 2.5.0 need. Linked from the roadmap and handover.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 12:37:28 +02:00
joshuaandClaude Opus 5.5 9985444937 docs: Events 3.0 (sign-in through Accounts) before the Website
Phases 4 and 5 swapped in ROADMAP-v3 (decision 38): Cross Events 3.0.0 is
phase 4, the Church Website phase 5. Phase 3 marked released; handover,
versions, README and the Accounts and Events 2.4 plans follow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 12:32:48 +02:00
joshuaandClaude Opus 5.5 2fd88b1337 Merge branch 'feat/seed-demo-from-hub'
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 10:53:56 +02:00
joshuaandClaude Opus 5.5 3e46d22bc6 docs: VERSIONS.md and HANDOVER for events@2.4.1, contracts@1.7.0, agent@1.2.0, Hub 2.4.0
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 10:43:21 +02:00
joshuaandClaude Opus 5.5 6ac17a6a62 Events 2.4.1: the default logo is the Cross Code logo, not Hope Family Church's
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 10:38:35 +02:00
joshuaandClaude Opus 5.5 f2a5df029a Demo data from the Hub: crosscode demo, the seed-demo job, set-demo fixes
- scripts: `crosscode demo <church> --profile … [--admin-email …]`: backup,
  set-demo.js as the site's user, reload, wait for /health.
- Contracts 1.7.0: the seed-demo job, DEMO_PROFILES, SEED_DEMO_MIN_AGENT.
- Agent 1.2.0: seed-demo → crosscode demo.
- Events 2.4.1: set-demo.js stops with a clear message when it can't read
  .env (was "client password must be a string", then a hang); keeps the
  oldest admin when the default one isn't on the site; --admin-email=.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 10:37:16 +02:00
joshuaandClaude Opus 5.5 126beaad70 docs: VERSIONS.md for accounts@1.0.1, contracts@1.6.0, Hub 2.3.3
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 10:26:30 +02:00
32 changed files with 882 additions and 56 deletions
+17
View File
@@ -2,6 +2,23 @@
Each package and app has its own section and its own tags (`contracts@1.0.0`, `accounts@1.0.0`, …).
## events@2.4.1, contracts@1.7.0, agent@1.2.0, crosscode script - 2026-11-19
Demo data from the Hub, for installs marked as demo sites (Hub 2.4.0).
- **Scripts: `crosscode demo <church> --profile <small|events|ministry|multicampus>
[--admin-email <email>]`.** Takes a backup, loads the demo set as the site's user (who alone
can read its `.env`), then reloads Events and waits for `/health`. Stops before the data if the
backup fails, and doesn't reload after a failed seed.
- **Contracts 1.7.0:** the `seed-demo` job (`church`, `profile`, optional `adminEmail`; 15
minutes), `DEMO_PROFILES`, `SEED_DEMO_MIN_AGENT`.
- **Agent 1.2.0:** runs `seed-demo` jobs as `crosscode demo`. Older agents refuse them, so the
Hub checks the agent's version first.
- **Events 2.4.1:** `set-demo.js` says to run as the site's user instead of failing with "client
password must be a string" and hanging; keeps the site's oldest admin when the default isn't
there. The default logo (before a church uploads one) is the Cross Code logo, not Hope Family
Church's. Details in `apps/events/CHANGELOG.md`.
## accounts@1.0.1, contracts@1.6.0, crosscode script - 2026-11-19
A server configuration with `TRUST_PROXY=TRUE` made an Events install build for minutes, then
+1 -1
View File
@@ -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
+7 -3
View File
@@ -1,10 +1,12 @@
{
"name": "@crosscode/agent",
"version": "1.1.1",
"version": "1.2.0",
"private": true,
"description": "The server agent: runs the crosscode script for signed jobs from Cross Code Hub, reports stats (docs/AGENT-1.0-PLAN.md)",
"license": "UNLICENSED",
"bin": { "crosscode-agent": "./dist/cli.js" },
"bin": {
"crosscode-agent": "./dist/cli.js"
},
"scripts": {
"build": "tsup",
"typecheck": "tsc -p tsconfig.json --noEmit",
@@ -14,5 +16,7 @@
"@crosscode/contracts": "*",
"zod": "^4.6.7"
},
"engines": { "node": ">=24" }
"engines": {
"node": ">=24"
}
}
+2
View File
@@ -48,6 +48,8 @@ export function crosscodeArgs(job: agent.AgentJob, opts: { exportFile?: string }
return ["adopt", job.args.church, "--undo"];
case "restart":
return ["restart", job.args.church, ...(job.args.product ? [job.args.product] : [])];
case "seed-demo":
return ["demo", job.args.church, "--profile", job.args.profile, ...(job.args.adminEmail ? ["--admin-email", job.args.adminEmail] : [])];
case "export":
if (!opts.exportFile) throw new Error("export needs a file to write");
return ["export", job.args.church, "--out", opts.exportFile];
+1 -1
View File
@@ -12,7 +12,7 @@ import { paths } from "./paths";
* the tools that are there; anything missing is null rather than an error.
*/
export const AGENT_VERSION = "1.1.1";
export const AGENT_VERSION = "1.2.0";
function run(cmd: string, args: string[], timeoutMs = 10_000): Promise<string | null> {
return new Promise((resolve) => {
+6
View File
@@ -39,6 +39,12 @@ describe("crosscode arguments for each job", () => {
expect(crosscodeArgs(parsed({ type: "status", args: {} }))).toEqual(["status", "--no-fetch"]);
});
it("seed-demo: crosscode demo with the profile, and the admin kept when the Hub names one", () => {
expect(crosscodeArgs(parsed({ type: "seed-demo", args: { church: "hope", profile: "ministry" } }))).toEqual(["demo", "hope", "--profile", "ministry"]);
expect(crosscodeArgs(parsed({ type: "seed-demo", args: { church: "hope", profile: "events", adminEmail: "jane@hope.test" } })))
.toEqual(["demo", "hope", "--profile", "events", "--admin-email", "jane@hope.test"]);
});
it("export writes to the file the agent gives", () => {
const j = parsed({ type: "export", args: { church: "hope", exportId: "exp_abcdefgh" } });
expect(crosscodeArgs(j, { exportFile: "/var/lib/crosscode-agent/exports/exp_abcdefgh.zip" })).toEqual(["export", "hope", "--out", "/var/lib/crosscode-agent/exports/exp_abcdefgh.zip"]);
+14
View File
@@ -5,6 +5,20 @@ All notable changes to this project are documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project follows [Semantic Versioning](https://semver.org/).
## [2.4.1] - 2026-11-19
### Fixed
- **Demo data on a server** (`scripts/set-demo.js`): run as anyone but the site's user, `.env`
(mode 600) couldn't be read, so `DATABASE_URL` was missing and pg failed with "client password
must be a string", then hung. It now stops at once and says to run it as the site's user (or
`crosscode demo`, which the Hub uses).
- **The default logo** (before a church uploads its own) was still Hope Family Church's artwork; it's
now the Cross Code logo (`frontend/src/app/default_logo.png`).
- The admin account kept can be named with `--admin-email=` (or `DEMO_ADMIN_EMAIL`, as before).
When none is named and joshua@crosscode.co.za isn't on the site, the oldest admin is kept, so a
site installed from the Hub (with the church's own admin) can be seeded.
## [2.4.0] - 2026-11-18
Protocol v2, Linked products, the event feed and `packages/seo` (ROADMAP-v3 phase 2,
+1 -1
View File
@@ -26,7 +26,7 @@ in-process settings cache TTL) without a server restart.
| `primary_color` | Legacy `accent_color` value if present, else `#4F46E5` (indigo) on the website / `#1e3a5f` (navy) in emails | See [Two different fallbacks](#two-different-fallbacks-for-primary_color) below — this is the one setting with a genuine inconsistency worth knowing about. Drives buttons, links, nav highlights, and the email header/CTA. The Branding tab warns when it is under 4.5:1 against white (too light for white text and links) and offers a darker shade (1.50.0). |
| `secondary_color` | `210 40% 96.1%` background / near-black text (light gray "wash", shadcn's stock theme) | The Branding tab's color picker *pre-fills* `#8B5CF6` as a suggested starting point, but that's only a UI default — if you never hit Save, the actual site uses the light-gray fallback, not violet. |
| `accent_color` | `210 40% 96.1%` background / near-black text (same light gray as Secondary) | Same story as Secondary — the picker pre-fills `#EC4899` (pink) as a suggestion only. |
| `logo_url` | Bundled logo (`frontend/src/app/church_logo.jpg`) | Shown in the navbar. This is still the original Hope Family Church artwork checked into the repo — swap the file (or upload a real logo via the Branding tab) before deploying for a different organisation. |
| `logo_url` | Bundled Cross Code logo (`frontend/src/app/default_logo.png`) | Shown in the navbar until the church uploads its own (Site settings → Branding, or `/setup`). |
| `favicon_url` | `frontend/public/favicon.ico` (the site's original generic favicon) | Shown in the browser tab. |
### Two different fallbacks for `primary_color`
+6
View File
@@ -12,6 +12,12 @@ Write for church admins, not developers: no environment variables, endpoints or
developer log is CHANGELOG.md. A tagged version without a section here shows "No details given".
-->
## 2.4.1
- Until you upload your own logo (Site settings → Branding), the site now shows the Cross Code
logo.
- A fix for setting up demonstration sites.
## 2.4.0
- **Ready for the Church Website and App.** When your church has them, your events can show on
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/events-backend",
"version": "2.4.0",
"version": "2.4.1",
"description": "Event Management System Backend",
"main": "src/index.js",
"scripts": {
+26 -6
View File
@@ -16,8 +16,9 @@
* campus-limited staff, a series across campuses, kids check-in and rosters at two
* campuses.
*
* Everything is removed first EXCEPT the site settings (AppSetting) and the admin
* account (DEMO_ADMIN_EMAIL, default joshua@crosscode.co.za). Dates are relative to
* Everything is removed first EXCEPT the site settings (AppSetting) and one admin
* account (--admin-email= or DEMO_ADMIN_EMAIL; else joshua@crosscode.co.za, else the oldest admin).
* Dates are relative to
* today, so the upcoming events are always in the future whenever this is run.
*
* No emails or WhatsApp messages are sent. Demo people use @example.com addresses and
@@ -40,7 +41,18 @@ const fs = require('fs');
const crypto = require('crypto');
const readline = require('readline');
require('dotenv').config({ path: path.resolve(__dirname, '../.env') });
const ENV_FILE = path.resolve(__dirname, '../.env');
const loaded = require('dotenv').config({ path: ENV_FILE, quiet: true });
// Without DATABASE_URL the pg driver fails with "client password must be a string" and hangs. The
// usual reason on a server: .env is readable only by the site's own user (mode 600).
if (!process.env.DATABASE_URL && !process.argv.includes('--list')) {
const denied = loaded.error && loaded.error.code === 'EACCES';
console.error(denied
? `Can't read ${ENV_FILE}: it belongs to the site's user. Run this as that user, e.g.\n sudo -u <site user> npm run demo:ministry\nor, as root: crosscode demo <church> --profile ministry`
: `DATABASE_URL isn't set (${loaded.error ? `${ENV_FILE}: ${loaded.error.code || loaded.error.message}` : `not in ${ENV_FILE}`}). Nothing was changed.`);
process.exit(1);
}
const { hashPassword } = require('../src/config/auth');
const { v4: uuidv4 } = require('uuid');
@@ -49,7 +61,11 @@ const { applyBundles } = require('../src/utils/bundles');
const prisma = createPrismaClient();
const ADMIN_EMAIL = (process.env.DEMO_ADMIN_EMAIL || 'joshua@crosscode.co.za').trim().toLowerCase();
// The account kept: --admin-email= or DEMO_ADMIN_EMAIL (must exist), else joshua@crosscode.co.za
// if it's there, else the oldest admin (a site installed from the Hub has its own admin).
const ADMIN_ARG = (process.argv.find(a => a.startsWith('--admin-email=')) || '').slice('--admin-email='.length);
const ADMIN_NAMED = (ADMIN_ARG || process.env.DEMO_ADMIN_EMAIL || '').trim().toLowerCase();
const ADMIN_EMAIL = ADMIN_NAMED || 'joshua@crosscode.co.za';
const DEMO_PASSWORD = 'Demo@1234';
const SKIP_PROMPT = process.argv.includes('--yes') || process.argv.includes('-y');
const PROFILE_NAME = (process.argv.find(a => a.startsWith('--profile=')) || '--profile=events').split('=')[1].trim().toLowerCase();
@@ -1846,9 +1862,13 @@ async function main() {
return;
}
admin = await prisma.user.findFirst({ where: { email: { equals: ADMIN_EMAIL, mode: 'insensitive' } } });
if (!admin && !ADMIN_NAMED) {
admin = await prisma.user.findFirst({ where: { role: 'admin' }, orderBy: { createdAt: 'asc' } });
if (admin) console.log(`Keeping the site's first admin, ${admin.email} (${ADMIN_EMAIL} isn't here).`);
}
if (!admin) {
console.error(`Admin account ${ADMIN_EMAIL} was not found — nothing was changed.`);
console.error('Set DEMO_ADMIN_EMAIL to the account you want to keep.');
console.error(`Admin account ${ADMIN_NAMED || 'to keep'} was not found — nothing was changed.`);
console.error('Name the account to keep with --admin-email= or DEMO_ADMIN_EMAIL (or finish /setup first).');
process.exitCode = 1;
return;
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/events-frontend",
"version": "2.4.0",
"version": "2.4.1",
"private": true,
"scripts": {
"dev": "next dev",
Binary file not shown.

Before

Width:  |  Height:  |  Size: 42 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

@@ -6,7 +6,7 @@ import { usePathname } from "next/navigation";
import { useAuth } from "@/hooks/useAuth";
import { useSiteSettings } from "@/contexts/SiteSettingsContext";
import { BottomNav } from "./BottomNav";
import churchLogo from "@/app/church_logo.jpg";
import defaultLogo from "@/app/default_logo.png";
import { appName } from "@/lib/siteConfig";
import { resolveToApiOrigin } from "@/lib/api";
import { hardNavigate } from "@/lib/navigation";
@@ -67,8 +67,8 @@ export const Navbar = () => {
<img src={logoSrc} alt="Logo" className="h-10 w-auto object-contain rounded-sm" />
) : (
<Image
src={churchLogo}
alt="Church logo"
src={defaultLogo}
alt="Logo"
width={50}
height={50}
className="rounded-sm object-contain"
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/events",
"version": "2.4.0",
"version": "2.4.1",
"main": "index.js",
"scripts": {
"dev:backend": "cd backend && npm run dev",
+7 -7
View File
@@ -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.
+1
View File
@@ -101,6 +101,7 @@ build differs from this plan, see [Changes while building](#changes-while-buildi
| `deploy` | `crosscode deploy <church> [products] [--version …] --json` | emergency only |
| `adopt` / `adopt-undo` | `crosscode adopt …` | no |
| `restart` | `crosscode restart <church> [product]` (PM2 reload) | no |
| `seed-demo` | `crosscode demo <church> --profile <profile> [--admin-email …]` (backup, demo data, reload; agent 1.2.0+) | no, but only for installs marked as demo sites in the Hub, and typing the short name |
| `export` | `crosscode export <church> --json` (§9) | no |
| `uninstall` | `crosscode uninstall <church> --json` | **yes**, and typing the short name |
| `purge` | `crosscode purge <church>` (deletes the 30-day keep, §9) | no (scheduled at uninstall) |
+2 -2
View File
@@ -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
+460
View File
@@ -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).
+6 -2
View File
@@ -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
@@ -84,6 +85,9 @@ rollout.
the app refuses some values at startup (as Events does a `TRUST_PROXY` it can't parse), add a
rule to both `checkEnvValue` in `packages/contracts/src/agent.ts` (the Hub) and `VALUE_RULES` in
`scripts/lib/envtpl.cjs` (the server), so a bad value stops before an install's build.
- **Demo data:** Hub → the install's page → Mark as a demo site → Load demo data (Hub 2.4.0, agent
1.2.0; `crosscode demo <church> --profile …` on the server). By hand, run `npm run demo:*` as the
site's user (`sudo -u cc-<church> …`): only that user can read the `.env`.
- **A new Events install never takes over an existing database**: moving an existing site is
`adopt`, not a New install pointed at the old database.
- **Prisma in the monorepo:** each app other than Events sets its own generator `output`, so
+14 -5
View File
@@ -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
+23 -14
View File
@@ -10,11 +10,11 @@ separately below; the two often differ.
| What | Repo | Latest | Tag | Released |
|------|------|--------|-----|----------|
| Cross Events | `crosscode-platform` (`apps/events`) | **2.4.0** | `events@2.4.0` | 2026-11-18 |
| Accounts | `crosscode-platform` (`apps/accounts`) | **1.0.0** | `accounts@1.0.0` | 2026-11-18 |
| Server agent | `crosscode-platform` (`apps/agent`) | **1.1.1** | `agent@1.1.1` | 2026-11-18 |
| Contracts | `crosscode-platform` (`packages/contracts`) | **1.5.0** | `contracts@1.5.0` | 2026-11-18 |
| Cross Code Hub | `events-hub` | **2.3.2** | `v2.3.2` | 2026-11-19 |
| Cross Events | `crosscode-platform` (`apps/events`) | **2.4.1** | `events@2.4.1` | 2026-11-19 |
| Accounts | `crosscode-platform` (`apps/accounts`) | **1.0.1** | `accounts@1.0.1` | 2026-11-19 |
| Server agent | `crosscode-platform` (`apps/agent`) | **1.2.0** | `agent@1.2.0` | 2026-11-19 |
| Contracts | `crosscode-platform` (`packages/contracts`) | **1.7.0** | `contracts@1.7.0` | 2026-11-19 |
| Cross Code Hub | `events-hub` | **2.4.0** | `v2.4.0` | 2026-11-19 |
| crosscode.co.za | `crosscode-site` | **1.5.0** | `v1.5.0` | 2026-11-18 |
| `crosscode` script | `crosscode-platform` (`scripts/`) | `main` | none | 2026-11-19 (last change) |
@@ -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
@@ -37,18 +37,27 @@ need their own tags until something outside this repo depends on them.
## What each latest release was for
- **Events 2.4.0:** protocol v2, Linked products, the event feed, `packages/seo`
([EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md)). 2.3.1 is the version for churches until 2.4.0's
- **Events 2.4.1:** the default logo is the Cross Code logo; the demo script says to run as the
site's user (instead of "client password must be a string") and keeps the site's oldest admin.
2.4.0: protocol v2, Linked products, the event feed, `packages/seo`
([EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md)). 2.3.1 is the version for churches until 2.4.x's
e2e run on Postgres and VM test are done.
- **Accounts 1.0.0:** the church's sign-in (OpenID Connect provider)
- **Accounts 1.0.1:** `TRUST_PROXY=loopback` (the value behind frp) now turns proxy trust on; it
used to turn it off. 1.0.0 was the church's sign-in (OpenID Connect provider)
([ACCOUNTS-1.0-PLAN.md](./ACCOUNTS-1.0-PLAN.md)). Needs the VM test and a run on real Postgres
before a church gets it.
- **Agent 1.1.1:** stats keep going while a job runs; reports its real version.
- **Contracts 1.5.0:** the Accounts contracts (OIDC client paths, scopes, church events).
- **Hub 2.3.2:** installs no longer get stuck "Uninstalling" when the export fails; a failed
- **Agent 1.2.0:** runs `seed-demo` jobs (`crosscode demo`). 1.1.1: stats keep going while a job
runs.
- **Contracts 1.7.0:** the `seed-demo` job. 1.6.0: `agent.checkEnvValue` / `invalidValues`,
settings the apps can't start with.
- **Hub 2.4.0:** demo sites: mark an Events install as a demo site and load demo data from its
page (needs agent 1.2.0 on that server). 2.3.3: refuses a server setting the apps can't start with (`TRUST_PROXY=TRUE`) when it's
saved and before a job. 2.3.2: installs no longer get stuck "Uninstalling" when the export fails; a failed
install's record can be removed (and uninstall is refused for it).
- **crosscode.co.za 1.5.0:** lists Accounts.
- **`crosscode` script (2026-11-19):** a failed install prints each PM2 app's last log lines before
- **`crosscode` script (2026-11-19):** `crosscode demo <church> --profile …` (backup, demo data,
restart); a value the app can't start with stops an install before the
build (`VALUE_RULES` in `lib/envtpl.cjs`); a failed install prints each PM2 app's last log lines before
removing it, so the Hub's job log shows why the backend didn't start.
## Deployed / rolled out
@@ -58,7 +67,7 @@ you deploy one.
| What | Running | Since | Notes |
|------|---------|-------|-------|
| Hub | 2.x (exact version not recorded) | | It runs agent jobs (installs on church-server1, 2026-11-18), so it's past 2.1. **2.3.2 not deployed yet** |
| Hub | 2.x (exact version not recorded) | | It runs agent jobs (installs on church-server1, 2026-11-18), so it's past 2.1. **2.4.0 not deployed yet** (it has a migration) |
| Agent on church-server1 | not recorded | | |
| Agent on the central server | not recorded | | |
| Cross Events (churches) | not recorded | | `hope-events` and `cross-events-demo` heartbeat as 2.1.1 and 2.3.1 |
+4 -4
View File
@@ -108,7 +108,7 @@
},
"apps/agent": {
"name": "@crosscode/agent",
"version": "1.1.1",
"version": "1.2.0",
"license": "UNLICENSED",
"dependencies": {
"@crosscode/contracts": "*",
@@ -127,7 +127,7 @@
},
"apps/events/backend": {
"name": "@crosscode/events-backend",
"version": "2.4.0",
"version": "2.4.1",
"hasInstallScript": true,
"dependencies": {
"@cj-tech-master/excelts": "^10.2.0",
@@ -176,7 +176,7 @@
},
"apps/events/frontend": {
"name": "@crosscode/events-frontend",
"version": "2.4.0",
"version": "2.4.1",
"dependencies": {
"@crosscode/contracts": "*",
"@crosscode/seo": "*",
@@ -21274,7 +21274,7 @@
},
"packages/contracts": {
"name": "@crosscode/contracts",
"version": "1.6.0",
"version": "1.7.0",
"license": "UNLICENSED",
"dependencies": {
"zod": "^4.6.7"
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/contracts",
"version": "1.6.0",
"version": "1.7.0",
"description": "The shared JSON formats used by every Cross Code product: zod schemas, JSON Schema, TypeScript types and sample payloads",
"license": "UNLICENSED",
"type": "commonjs",
+111
View File
@@ -743,6 +743,117 @@
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"schema": {
"type": "string",
"const": "crosscode.agent-job/1"
},
"id": {
"type": "string",
"pattern": "^job_[A-Za-z0-9_-]{8,64}$"
},
"serverId": {
"type": "string",
"pattern": "^srv_[A-Za-z0-9_-]{8,64}$"
},
"config": {
"anyOf": [
{
"type": "object",
"properties": {
"alg": {
"type": "string",
"const": "x25519-hkdf-sha256-aes-256-gcm"
},
"epk": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$"
},
"iv": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16}$"
},
"ciphertext": {
"type": "string",
"maxLength": 200000,
"pattern": "^[A-Za-z0-9_-]+$"
}
},
"required": [
"alg",
"epk",
"iv",
"ciphertext"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"notBefore": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"signature": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{86}$"
},
"type": {
"type": "string",
"const": "seed-demo"
},
"args": {
"type": "object",
"properties": {
"church": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{1,30}$"
},
"profile": {
"type": "string",
"enum": [
"small",
"events",
"ministry",
"multicampus"
]
},
"adminEmail": {
"type": "string",
"maxLength": 254,
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
}
},
"required": [
"church",
"profile"
],
"additionalProperties": false
}
},
"required": [
"schema",
"id",
"serverId",
"notBefore",
"expiresAt",
"signature",
"type",
"args"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
@@ -24,6 +24,7 @@
"adopt",
"adopt-undo",
"restart",
"seed-demo",
"export",
"uninstall",
"purge",
+16 -2
View File
@@ -54,6 +54,14 @@ export type AgentMode = z.infer<typeof agentModeSchema>;
// Jobs (crosscode.agent-job/1)
// ---------------------------------------------------------------------------------------------
/** Cross Events' demo data sets (`apps/events/backend/scripts/set-demo.js`). */
export const DEMO_PROFILES = ["small", "events", "ministry", "multicampus"] as const;
export const demoProfileSchema = z.enum(DEMO_PROFILES);
export type DemoProfile = z.infer<typeof demoProfileSchema>;
/** The first agent that runs `seed-demo` jobs (an older one refuses the unknown type). */
export const SEED_DEMO_MIN_AGENT = "1.2.0";
/** Each job type and the arguments it takes. Unknown keys are refused, not stripped. */
export const jobArgsSchemas = {
/** `crosscode install <church> --products … --frp --json` */
@@ -81,6 +89,12 @@ export const jobArgsSchemas = {
"adopt-undo": z.strictObject({ church: shortNameSchema }),
/** `crosscode restart <church> [product] --json` (PM2 reload) */
restart: z.strictObject({ church: shortNameSchema, product: productSchema.optional() }),
/**
* `crosscode demo <church> --profile <profile> [--admin-email <email>] --json`: replaces Cross
* Events' data with a demo set (a backup is taken first). The Hub only makes it for installs
* marked as demo sites. `adminEmail`: the account kept (default: the release's own choice).
*/
"seed-demo": z.strictObject({ church: shortNameSchema, profile: demoProfileSchema, adminEmail: z.email().max(254).optional() }),
/** `crosscode export <church> --out <zip> --json`; the agent encrypts the ZIP and uploads it under `exportId`. */
export: z.strictObject({ church: shortNameSchema, exportId: z.string().regex(/^exp_[A-Za-z0-9_-]{8,64}$/) }),
/** `crosscode uninstall <church> --json` */
@@ -105,7 +119,7 @@ export const CENTRAL_JOB_TYPES: readonly JobType[] = ["check-ports", "status", "
/** Time limits per job type, in minutes (§3). A job past it is stopped and reported as failed. */
export const JOB_TIME_LIMIT_MINUTES: Record<JobType, number> = {
install: 30, "add-product": 30, deploy: 20, adopt: 30, "adopt-undo": 15, restart: 5, export: 20,
install: 30, "add-product": 30, deploy: 20, adopt: 30, "adopt-undo": 15, restart: 5, "seed-demo": 15, export: 20,
uninstall: 20, purge: 10, "update-agent": 15, "check-ports": 2, status: 3,
};
@@ -149,7 +163,7 @@ function jobOf<T extends JobType>(type: T) {
}
export const agentJobSchema = z.discriminatedUnion("type", [
jobOf("install"), jobOf("add-product"), jobOf("deploy"), jobOf("adopt"), jobOf("adopt-undo"), jobOf("restart"),
jobOf("install"), jobOf("add-product"), jobOf("deploy"), jobOf("adopt"), jobOf("adopt-undo"), jobOf("restart"), jobOf("seed-demo"),
jobOf("export"), jobOf("uninstall"), jobOf("purge"), jobOf("update-agent"), jobOf("check-ports"), jobOf("status"),
]);
export type AgentJob = z.infer<typeof agentJobSchema>;
+13
View File
@@ -154,6 +154,19 @@ describe("exports", () => {
});
});
describe("seed-demo jobs", () => {
const args = (a: Record<string, unknown>) => agent.jobArgsSchemas["seed-demo"].safeParse(a).success;
it("take a known profile, and an admin email only when it is one", () => {
expect(args({ church: "hope", profile: "ministry" })).toBe(true);
expect(args({ church: "hope", profile: "events", adminEmail: "jane@hope.test" })).toBe(true);
expect(args({ church: "hope", profile: "everything" })).toBe(false);
expect(args({ church: "hope", profile: "small", adminEmail: "not an email; rm -rf /" })).toBe(false);
expect(args({ church: "hope", profile: "small", extra: 1 })).toBe(false);
expect(agent.JOB_TYPES).toContain("seed-demo");
expect(agent.CENTRAL_JOB_TYPES).not.toContain("seed-demo");
});
});
describe("env templates", () => {
it("lists the required server and defaults values that are missing", () => {
const template = agent.envTemplateSchema.parse({
+3 -1
View File
@@ -96,6 +96,7 @@ crosscode: Cross Code installs on this server ($(git -C "${CROSSCODE_FROM:-.}" r
crosscode adopt <church> --events-dir <old folder> move an existing Cross Events install here
crosscode adopt <church> --undo go back to the old folder (within 14 days)
crosscode restart <church> [events] reload the PM2 processes
crosscode demo <church> --profile <profile> replace Events' data with a demo set
crosscode export <church> --out <file.zip> the church's data and uploads
crosscode uninstall <church> --confirm <church> remove it (a final backup is kept 30 days)
crosscode purge <church> --confirm <church> delete what uninstall kept
@@ -112,6 +113,7 @@ case "$command" in
install) cmd_install "$@" ;;
adopt) cmd_adopt "$@" ;;
restart) cmd_restart "$@" ;;
demo) cmd_demo "$@" ;;
export) cmd_export "$@" ;;
uninstall) cmd_uninstall "$@" ;;
purge) cmd_purge "$@" ;;
@@ -123,7 +125,7 @@ case "$command" in
install) install_usage ;;
add) add_usage ;;
adopt) adopt_usage ;;
restart|export|uninstall|purge) manage_usage ;;
restart|demo|export|uninstall|purge) manage_usage ;;
*) usage ;;
esac ;;
*) usage; die "Unknown command \"$command\"." ;;
+50
View File
@@ -6,6 +6,10 @@ CROSSCODE_REMOVED="${CROSSCODE_REMOVED:-$CROSSCODE_SITES/.removed}"
manage_usage() {
cat <<'EOF'
crosscode restart <church> [events] reload the products' PM2 processes
crosscode demo <church> --profile <profile> [--admin-email <email>]
replace Cross Events' data with a demo set
(small, events, ministry, multicampus); a backup
is taken first, one admin account is kept
crosscode export <church> --out <file.zip> the church's data (crosscode.church-export/1) and uploads
crosscode uninstall <church> --confirm <church>
final backup and uploads kept in
@@ -52,6 +56,52 @@ cmd_restart() {
done
}
DEMO_PROFILES="small events ministry multicampus"
# Replaces Events' data with a demo set (apps/events/backend/scripts/set-demo.js), as the site's
# user (its .env is readable only by that user). The Hub sends it only for installs marked as demo
# sites. Afterwards Events is reloaded: the demo switches campuses on or off.
cmd_demo() {
local church="" profile="" email="" dir user app
while [ $# -gt 0 ]; do
case "$1" in
--profile) [ $# -ge 2 ] || die "--profile needs a value."; profile="$2"; shift 2 ;;
--admin-email) [ $# -ge 2 ] || die "--admin-email needs a value."; email="$2"; shift 2 ;;
-h|--help) manage_usage; return 0 ;;
-*) die "Unknown option $1 (crosscode help demo)." ;;
*) [ -z "$church" ] || die "One church at a time."; church="$1"; shift ;;
esac
done
[ -n "$church" ] || die "Name the church."
[[ " $DEMO_PROFILES " == *" $profile "* ]] || die "--profile: one of $DEMO_PROFILES."
[ -z "$email" ] || [[ "$email" =~ ^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$ ]] || die "--admin-email: not an email address."
require_root
load_church "$church"
church_has_product events || die "$church has no Cross Events."
# shellcheck source=/dev/null
source "$CROSSCODE_HOME/products/events.sh"
dir="$(pvar events DIR)"
user="$(pvar events USER)"
app="$(events_app "$dir")"
[ -f "$app/backend/scripts/set-demo.js" ] || die "This release of Events ($(checkout_ref "$dir" events)) has no demo data."
step "Events: backup first"
events_backup "$dir" "$user" || die "The backup failed, so the demo data wasn't loaded."
step "Events: demo data ($profile)"
local -a env_args=()
# DEMO_ADMIN_EMAIL rather than --admin-email=: releases before 2.4.1 only read the variable.
[ -z "$email" ] || env_args=("DEMO_ADMIN_EMAIL=$email")
run_as "$user" "$app/backend" env "${env_args[@]+"${env_args[@]}"}" node scripts/set-demo.js "--profile=$profile" --yes ||
die "The demo data wasn't loaded (see above). If it got as far as changing anything, the backup from just now has the data from before."
step "Events: reloading PM2"
events_reload "$dir" "$user"
step "Events: waiting for it to answer"
wait_for_version "$(events_health_url)" "$(events_expected_version "$dir")" 60 ||
die "Events didn't answer after the reload (sudo -u $user pm2 logs)."
}
cmd_export() {
local church="" out="" p tmp dir user bytes
while [ $# -gt 0 ]; do
+83
View File
@@ -0,0 +1,83 @@
#!/usr/bin/env bats
# crosscode demo (lib/manage.sh): argument checks, then backup → demo data as the site's user →
# reload, in that order, and nothing after a step that fails.
setup() {
export CROSSCODE_NO_UPDATE=1
CC="$BATS_TEST_DIRNAME/../crosscode"
TMP="$BATS_TEST_TMPDIR"
CALLS="$TMP/calls"
: > "$CALLS"
# shellcheck source=../lib/common.sh
source "$BATS_TEST_DIRNAME/../lib/common.sh"
# shellcheck source=../lib/manage.sh
source "$BATS_TEST_DIRNAME/../lib/manage.sh"
# A church with Events, and Events' hooks recording what they'd do.
export CROSSCODE_HOME="$TMP/home"
mkdir -p "$CROSSCODE_HOME/products" "$TMP/sites/hope/events/apps/events/backend/scripts"
touch "$TMP/sites/hope/events/apps/events/backend/scripts/set-demo.js"
cat > "$CROSSCODE_HOME/products/events.sh" <<EOF
events_app() { printf '%s/apps/events' "\$1"; }
events_backup() { echo "backup \$2" >> "$CALLS"; [ -z "\${FAIL_BACKUP:-}" ]; }
events_reload() { echo "reload \$2" >> "$CALLS"; }
events_health_url() { echo http://127.0.0.1:20001/health; }
events_expected_version() { echo 2.4.1; }
EOF
require_root() { :; }
load_church() { [ "$1" = hope ] || die "There's no church $1 here."; }
church_has_product() { [ "$1" = events ]; }
pvar() { case "$2" in DIR) echo "$TMP/sites/hope/events" ;; USER) echo cc-hope ;; esac; }
checkout_ref() { echo events@2.4.1; }
wait_for_version() { echo "wait $2" >> "$CALLS"; }
run_as() { local user="$1" dir="$2"; shift 2; echo "run $user ${dir#"$TMP"/} $*" >> "$CALLS"; [ -z "${FAIL_SEED:-}" ]; }
}
@test "the profile and admin email are checked before anything else" {
CROSSCODE_HOME= run bash "$CC" demo hope
[ "$status" -eq 1 ]
[[ "$output" == *"--profile: one of small events ministry multicampus"* ]]
CROSSCODE_HOME= run bash "$CC" demo hope --profile everything
[ "$status" -eq 1 ]
CROSSCODE_HOME= run bash "$CC" demo hope --profile small --admin-email 'x; rm -rf /'
[ "$status" -eq 1 ]
[[ "$output" == *"not an email address"* ]]
CROSSCODE_HOME= run bash "$CC" help demo
[[ "$output" == *"crosscode demo <church> --profile"* ]]
}
@test "backup, then the demo as the site's user (no prompt), then a reload" {
run cmd_demo hope --profile ministry
[ "$status" -eq 0 ]
[ "$(cat "$CALLS")" = "backup cc-hope
run cc-hope sites/hope/events/apps/events/backend env node scripts/set-demo.js --profile=ministry --yes
reload cc-hope
wait 2.4.1" ]
}
@test "the admin to keep goes in DEMO_ADMIN_EMAIL (older releases only read that)" {
run cmd_demo hope --profile small --admin-email jane@hope.test
[ "$status" -eq 0 ]
grep -qx 'run cc-hope sites/hope/events/apps/events/backend env DEMO_ADMIN_EMAIL=jane@hope.test node scripts/set-demo.js --profile=small --yes' "$CALLS"
}
@test "a failed backup stops it before the data is touched" {
FAIL_BACKUP=1 run cmd_demo hope --profile small
[ "$status" -eq 1 ]
[[ "$output" == *"The backup failed"* ]]
[ "$(cat "$CALLS")" = "backup cc-hope" ]
}
@test "a failed demo isn't followed by a reload" {
FAIL_SEED=1 run cmd_demo hope --profile small
[ "$status" -eq 1 ]
! grep -q reload "$CALLS"
}
@test "a release without the demo script is refused" {
rm "$TMP/sites/hope/events/apps/events/backend/scripts/set-demo.js"
run cmd_demo hope --profile small
[ "$status" -eq 1 ]
[[ "$output" == *"has no demo data"* ]]
[ ! -s "$CALLS" ]
}