Compare commits
8
Commits
contracts@1.6.0
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
ac017395df | ||
|
|
258f8b820d | ||
|
|
9985444937 | ||
|
|
2fd88b1337 | ||
|
|
3e46d22bc6 | ||
|
|
6ac17a6a62 | ||
|
|
f2a5df029a | ||
|
|
126beaad70 |
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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];
|
||||
|
||||
@@ -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) => {
|
||||
|
||||
@@ -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"]);
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -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,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": {
|
||||
|
||||
@@ -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,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,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",
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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) |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
@@ -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
@@ -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
@@ -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 |
|
||||
|
||||
Generated
+4
-4
@@ -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,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",
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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>;
|
||||
|
||||
@@ -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
@@ -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\"." ;;
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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" ]
|
||||
}
|
||||
Reference in New Issue
Block a user