Compare commits

..
22 Commits
Author SHA1 Message Date
joshua 4cc30c1445 Merge branch 'docs/website-plan-confirmed' 2026-11-21 00:16:01 +02:00
joshuaandClaude Opus 5.5 d91d956e78 docs: Website 1.0 plan decisions confirmed; full storage stops uploads
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 00:16:00 +02:00
joshua 9f07ecf0dd Merge branch 'docs/website-1.0-plan' 2026-11-21 00:13:10 +02:00
joshuaandClaude Opus 5.5 74df4aa7b5 docs: plan the Church Website 1.0.0 (phase 5)
WEBSITE-1.0-PLAN.md: templates with section variants, style settings and custom
pages; one Publish after a clickable preview; Coming soon; contact details only;
messages from YouTube or by link; brand style and footer shared with Events 3.7;
no address moves in 1.0. ROADMAP decisions 40-47, §6, §9, §10, §11.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 00:13:10 +02:00
joshua 72a6283024 Merge branch 'docs/deployed-and-phase-5' 2026-11-21 00:00:56 +02:00
joshuaandClaude Opus 5.5 86711699cf docs: everything up to the 2026-11-20 releases deployed; phase 5 (Website) next
HANDOVER phase table and Next up, VERSIONS deployed table, and the Website/ui
placeholders now say phase 5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 00:00:55 +02:00
joshua d28029e96e Merge branch 'fix/accounts-backups-local-changes' 2026-11-20 15:55:08 +02:00
joshuaandClaude Opus 5.5 e65e26202a crosscode script: Accounts' pre-deploy dumps don't stop a deploy
The dump made before each Accounts deploy (apps/accounts/backend/backups/)
counted as a file added by hand on Accounts below 1.3.0, which has no
.gitignore for it, so the next deploy stopped. Untracked files in that
folder no longer count (CROSSCODE_OWN_DIRS in lib/common.sh).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:55:07 +02:00
joshua ca55142f6f Merge branch 'docs/hub-2.10.0' 2026-11-20 14:44:52 +02:00
joshuaandClaude Opus 5.5 1b94814f67 docs: Hub 2.10.0 (emails, FastPanel ^~ /api/) in HANDOVER, VERSIONS and AGENT-1.0-PLAN §11
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 14:44:52 +02:00
joshua 0b70a87669 Merge branch 'fix/branding-upload-routing' 2026-11-20 14:28:16 +02:00
joshuaandClaude Opus 5.5 ead07ef932 docs: Events 3.6.1 in CHANGELOG, VERSIONS and HANDOVER (FastPanel sites)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 14:28:15 +02:00
joshuaandClaude Opus 5.5 d8312f4b33 Events 3.6.1: branding uploads work behind a proxy with extension rules
The logo/favicon upload succeeded, but the check that the site can show it
got a 404: on events-demo every /api/... path ending in a file extension
(.png, .ico, .pdf, .json) went to Next.js instead of the backend.

- next.config.ts: /api/* and /uploads/* that reach the site are passed to
  the backend (beforeFiles rewrites) via the new BACKEND_INTERNAL_URL
  (http://127.0.0.1:<apiPort>, from env.template.json on deploy). The e2e
  E2E_API_PROXY uses the same rewrites.
- nginx written by both installers and shown in DEPLOYMENT.md: /api/ and
  /uploads/ use location ^~ so no regex location can take them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 14:08:11 +02:00
joshua a9239d429a Merge branch 'feat/signin-notices' 2026-11-20 13:54:04 +02:00
joshuaandClaude Opus 5.5 405b5f1b92 Accounts 1.6.0: a "New sign-in" email (and WhatsApp) after every sign-in
As Cross Events' own sign-in sends: when, the site, rough location and device, with what to do if
it wasn't them. WhatsApp too for a verified number. Admins can turn it off (signin_notices).
Fire-and-forget: never holds up or fails a sign-in.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 13:54:03 +02:00
joshuaandClaude Opus 5.5 c8c5db46bc docs: HANDOVER.md Next up for the latest releases
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 13:29:23 +02:00
joshua 031fb11e02 Merge branch 'docs/handover-2026-11-20' 2026-11-20 13:28:31 +02:00
joshuaandClaude Opus 5.5 16d3ffe6ba docs: HANDOVER.md for the 2026-11-20 releases
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 13:28:31 +02:00
joshua eac6564e11 Merge branch 'feat/people-check' 2026-11-20 13:26:51 +02:00
joshuaandClaude Opus 5.5 8f78fcc75c Events 3.6.0, Accounts 1.5.0, contracts 1.14.0: the nightly people check
- Contracts 1.14.0: people.check in crosscode.identity-request/1 (500 subs) and its reply
  (active / deactivated / deleted / unknown, profile for the first two).
- Accounts 1.5.0: answers people.check with profiles only for people the product knows; the reply
  isn't stored.
- Events 3.6.0: accounts-people-check job (04:30): fixes out-of-date copies, handles deleted
  accounts as user.deleted, counts unknown people and stops (changing nothing) when most of a page
  is unknown; skipped with an Accounts older than 1.5.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 13:26:50 +02:00
joshua cacbb16895 Merge branch 'fix/accounts-link' 2026-11-20 12:56:39 +02:00
joshuaandClaude Opus 5.5 08b58ae310 Events 3.5.0, contracts 1.13.0, agent 1.3.1: demo data keeps the Accounts link; sign-in health for the Hub
- Events: loading demo data emptied ProductLink but kept auth_mode, so a site in Accounts mode had
  no link and nobody could sign in (ACCOUNTS_UNAVAILABLE on events-demo). set-demo.js keeps
  ProductLink and LinkNonce; a site in Accounts mode without a link reconnects at its next
  heartbeat; sign-in failures are kept and sent in the heartbeat (stats.signIn).
- Contracts 1.13.0: stats.signIn in the Cross Events heartbeat.
- Agent 1.3.1: 1.3.0 reported itself as 1.2.0 (AGENT_VERSION not bumped).
- What's New notes for Events 3.4.0 / 3.5.0 and Accounts 1.4.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 12:56:37 +02:00
58 changed files with 1669 additions and 119 deletions
+47
View File
@@ -2,6 +2,53 @@
Each package and app has its own section and its own tags (`contracts@1.0.0`, `accounts@1.0.0`, …).
## crosscode script - 2026-11-20 (no tag: servers run `main`)
- **Fix:** the database dump made before each Accounts deploy (`apps/accounts/backend/backups/`)
counted as a file added by hand on Accounts below 1.3.0 (no `.gitignore` for it yet), so the
next deploy stopped with "changed or added by hand". Untracked files in that folder no longer
count (`CROSSCODE_OWN_DIRS` in `lib/common.sh`).
## events@3.6.1 - 2026-11-20
- **Events 3.6.1 (fix):** uploading a logo or favicon failed with "uploaded, but the site can't
show it yet" behind a proxy with a file-extension rule (FastPanel's static-file handling sent
`/api/uploads/…png` to the frontend). The site now passes `/api/*` and `/uploads/*` that reach
it on to the backend (new `BACKEND_INTERNAL_URL`, added on deploy).
- **crosscode script:** the nginx site it writes uses `location ^~ /api/` and `^~ /uploads/`.
## accounts@1.6.0 - 2026-11-20
- **Accounts 1.6.0:** a "New sign-in" email (and WhatsApp for a verified number) after every
sign-in, as Cross Events' own sign-in did; Sign-in settings → `signin_notices` turns it off.
## events@3.6.0, accounts@1.5.0, contracts@1.14.0 - 2026-11-20
A nightly check that each site's copies of people match their church accounts, for changes that
never arrived.
- **Contracts 1.14.0:** `people.check` in `crosscode.identity-request/1` (`PEOPLE_CHECK_MAX` 500)
and `peopleCheckReplySchema` (each sub `active` / `deactivated` / `deleted` / `unknown`, with the
profile for the first two). Samples and JSON Schema `people-check-reply`.
- **Accounts 1.5.0:** answers it, only with profiles of people the product knows.
- **Events 3.6.0:** the `accounts-people-check` job (04:30): fixes out-of-date copies, handles
deleted accounts as `user.deleted`, and stops if most people are unknown (wrong Accounts?).
## events@3.5.0, contracts@1.13.0, agent@1.3.1 - 2026-11-20
- **Agent 1.3.1:** agent 1.3.0 still reported itself as 1.2.0 (`AGENT_VERSION` in `src/stats.ts`
wasn't bumped with `package.json`), so the Hub refused `.env` jobs on it. Use 1.3.1.
Loading demo data left a site that signs in through Accounts with no Accounts link, so nobody could
sign in (`ACCOUNTS_UNAVAILABLE`, found on events-demo). The Hub (2.9.0) now sees it.
- **Contracts 1.13.0:** `stats.signIn` in the Cross Events heartbeat (mode, the linked Accounts,
the last sign-in failure; optional).
- **Events 3.5.0:** `set-demo.js` keeps `ProductLink` and `LinkNonce`; a site in Accounts mode
without a link reconnects at its next heartbeat even after an earlier auto-connect; sign-in
failures (start, finish, Accounts unreachable) are kept and sent to the Hub; What's New notes for
3.4.0 (and Accounts 1.4.0) that were missing.
## events@3.4.0, accounts@1.4.0, contracts@1.12.0, agent@1.3.0, crosscode script - 2026-11-20
Background jobs are switched on and off (and rescheduled) from each site's admin, over the .env;
+24
View File
@@ -1,5 +1,29 @@
# Changelog — Accounts
## [1.6.0] - 2026-11-20
### Added
- **"New sign-in" notices**, as Cross Events' own sign-in sends (`src/accounts/signInNotice.ts`):
after each completed sign-in (the interaction reaching done, so not the silent ones a second
product gets from an existing session), an email with when, the site, rough location and device
(`newSignInEmail` in `src/lib/emails.ts`), and a WhatsApp message when the person has a verified
number and WhatsApp is set up. Location from ip-api.com in production only, never for private
addresses. Fire-and-forget: never holds up or fails a sign-in. Admins can turn it off:
`signin_notices` (Sign-in settings, on by default). In Accounts mode Cross Events no longer sends
its own, so before this nobody was told.
## [1.5.0] - 2026-11-20
Needs contracts 1.14.0.
### Added
- `people.check` (contracts 1.14.0): for up to 500 subs, the current profile of each person the
product knows (`active` / `deactivated`), `deleted` for a deleted account, `unknown` for anyone
else (no profile). Audited once per request (`people_checked_by_product`, counts only); the reply
isn't stored for retries, since it holds profiles. Cross Events 3.6.0 asks nightly.
## [1.4.0] - 2026-11-20
Works with every Cross Events 3.x and contracts 1.11.0 or later.
+22
View File
@@ -3,6 +3,28 @@
What each version changes for the church, in plain language (read by the Hub like Cross Events'
WHATS-NEW.md; a section shows once its version is tagged).
## 1.6.0
- **You're told about each sign-in.** After someone signs in, they get an email saying when, roughly
where, on what device and to which site, with what to do if it wasn't them, as Cross Events
does for its own sign-in. People with a confirmed WhatsApp number get it on WhatsApp too.
Admins can turn this off under Sign-in settings.
## 1.5.0
- Your church's sites can now check every night that the details they keep for each person match
their church account (Cross Events 3.6.0 does), so a change that didn't reach a site is fixed the
next morning.
## 1.4.0
- **Better-looking emails.** Sign-in codes, password links, "your account is ready" and the other
emails from your church account now look like Cross Events' emails: your church's colour and logo
at the top, a clear button, and your church's contact details at the bottom.
- Admins: **Admin → Background jobs** shows what Accounts does on a schedule (backups, privacy
requests, tidying up), when it last ran, and lets you run a job now, switch it off or change when
it runs.
## 1.3.0
- Your account and the admin pages have a new look, like Cross Events: a menu down the side, and
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/accounts-backend",
"version": "1.4.0",
"version": "1.6.0",
"description": "Cross Code Accounts: the church's sign-in (OpenID Connect provider), account pages API and admin API",
"private": true,
"type": "module",
@@ -0,0 +1,58 @@
/**
* "New sign-in" notices (1.6.0), as Cross Events sends for its own sign-in: after each completed
* sign-in, an email to the person, and a WhatsApp message too when they have a verified number and
* WhatsApp is set up. Admins can turn them off (Sign-in settings, `signin_notices`). Never holds up
* or fails the sign-in.
*
* The rough location comes from the IP (ip-api.com, as Cross Events), in production only, and never
* for private addresses.
*/
import type { Ctx } from '../context.js';
import { newSignInEmail } from '../lib/emails.js';
import { productName } from '../oidc/clients.js';
const PRIVATE_IP = /^(::1$|127\.|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|fc|fd|fe80|::ffff:(127|10|192\.168)\.)/i;
/** "Chrome on Windows" from a user agent; the raw string when it can't tell. */
export function describeDevice(ua: string | null | undefined): string {
const s = String(ua || '');
if (!s) return 'Unknown device';
const browser = /Edg\//.test(s) ? 'Edge' : /OPR\/|Opera/.test(s) ? 'Opera' : /Firefox\//.test(s) ? 'Firefox'
: /SamsungBrowser\//.test(s) ? 'Samsung Internet' : /Chrome\//.test(s) ? 'Chrome' : /Safari\//.test(s) ? 'Safari' : null;
const os = /iPhone|iPad|iPod/.test(s) ? 'iPhone or iPad' : /Android/.test(s) ? 'Android' : /Windows/.test(s) ? 'Windows'
: /Mac OS X|Macintosh/.test(s) ? 'a Mac' : /CrOS/.test(s) ? 'a Chromebook' : /Linux/.test(s) ? 'Linux' : null;
if (browser && os) return `${browser} on ${os}`;
return browser || os || s.slice(0, 120);
}
async function roughLocation(ctx: Ctx, ip: string | null): Promise<string> {
if (!ip || PRIVATE_IP.test(ip) || !ctx.config.production) return 'Unknown';
try {
const res = await fetch(`http://ip-api.com/json/${encodeURIComponent(ip.replace(/^::ffff:/, ''))}?fields=status,city,regionName,country`, { signal: AbortSignal.timeout(3000) });
const geo = (await res.json()) as { status?: string; city?: string; regionName?: string; country?: string };
const parts = geo.status === 'success' ? [geo.city, geo.regionName, geo.country].filter(Boolean) : [];
return parts.length ? parts.join(', ') : 'Unknown';
} catch {
return 'Unknown';
}
}
export async function sendSignInNotice(ctx: Ctx, o: { accountId: string; ip: string | null; userAgent: string | null; clientId: string | null }): Promise<'sent' | 'off' | 'failed'> {
try {
if (!(await ctx.settings.bool('signin_notices', true))) return 'off';
const a = await ctx.db.account.findUnique({ where: { id: o.accountId } });
if (!a || a.status !== 'active') return 'off';
const link = o.clientId ? await ctx.db.productLink.findUnique({ where: { installId: o.clientId } }) : null;
const site = link ? productName(link.product) : o.clientId === 'accounts-self' ? 'Your account page' : null;
const when = ctx.now().toLocaleString('en-ZA', { timeZone: ctx.config.timezone, dateStyle: 'medium', timeStyle: 'short' });
const msg = await newSignInEmail(ctx, { name: a.name, when, location: await roughLocation(ctx, o.ip), device: describeDevice(o.userAgent), site });
await ctx.messenger.email({ to: a.email, subject: msg.subject, text: msg.text, html: msg.html });
if (a.phone && a.phoneVerified && (await ctx.messenger.whatsappReady())) {
await ctx.messenger.whatsapp({ to: a.phone, text: msg.whatsapp }).catch((e: Error) => console.warn('[sign-in notice] WhatsApp:', e.message));
}
return 'sent';
} catch (e) {
console.warn('[sign-in notice] not sent:', (e as Error).message);
return 'failed';
}
}
@@ -8,7 +8,8 @@ import type Provider from 'oidc-provider';
import { decodeState, encodeState, safeReturnPath } from '@crosscode/contracts';
import type { Ctx } from '../context.js';
import { ApiError, handle, limit } from '../http.js';
import { loginEvent } from '../lib/audit.js';
import { clientIp, loginEvent } from '../lib/audit.js';
import { sendSignInNotice } from '../accounts/signInNotice.js';
import { resetPasswordEmail } from '../lib/emails.js';
import { hashToken, randomToken } from '../lib/crypto.js';
import { hashPassword, passwordProblem } from '../lib/passwords.js';
@@ -44,6 +45,8 @@ export function interactionRouter(ctx: Ctx, provider: Provider) {
const clientId = String(details.params.client_id ?? '') || null;
await loginEvent(ctx, pending.accountId, 'sign_in', req, { clientId, detail: { amr: pending.amr } });
await signedInThrough(ctx, clientId, pending.accountId);
// 1.6.0: "New sign-in" email (and WhatsApp), as Cross Events; never waited for.
if (pending.accountId) void sendSignInNotice(ctx, { accountId: pending.accountId, ip: clientIp(req), userAgent: req.get('user-agent') ?? null, clientId });
await ctx.db.pendingSignIn.deleteMany({ where: { uid: pending.uid } });
return { stage: 'done', redirectTo, ...extra };
}
+17
View File
@@ -206,3 +206,20 @@ export async function testEmail(ctx: Ctx, o: { from?: string } = {}): Promise<Bu
: 'Email from Accounts works.';
return { subject: o.from ? `Test email from ${b.name}'s sign-in` : 'Test email from Accounts', text, html: layout(b, body, 'A test email: email works.') };
}
/** A sign-in happened (1.6.0, as Cross Events' "New login detected"). `whatsapp`: the same in a few lines. */
export async function newSignInEmail(ctx: Ctx, o: { name?: string | null; when: string; location: string; device: string; site: string | null }): Promise<Built & { whatsapp: string }> {
const b = await brand(ctx);
const row = (k: string, v: string) => `<tr><td style="padding:10px 14px;border-top:1px solid #f1f5f9;color:#64748b;font-size:13px;font-weight:600;width:34%">${esc(k)}</td><td style="padding:10px 14px;border-top:1px solid #f1f5f9;color:#1e293b;font-size:14px;word-break:break-word">${esc(v)}</td></tr>`;
const body = title('New sign-in', `Someone signed in to your ${b.name} account`)
+ hello(o.name)
+ `<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="border:1px solid #e2e8f0;border-radius:8px;overflow:hidden;margin:0 0 8px 0">`
+ row('When', o.when) + (o.site ? row('Signed in to', o.site) : '') + row('Where (roughly)', o.location) + row('Device', o.device)
+ '</table>'
+ callout(`<strong>Not you?</strong> Change your password straight away from your account page, and let the church office know${contactLine(b)}.`, 'warning')
+ small('If this was you, there\'s nothing to do.');
const lines = [`When: ${o.when}`, ...(o.site ? [`Signed in to: ${o.site}`] : []), `Where (roughly): ${o.location}`, `Device: ${o.device}`];
const text = `Hello ${o.name || 'there'},\n\nSomeone signed in to your ${b.name} account.\n\n${lines.join('\n')}\n\nIf this wasn't you, change your password straight away and let the church office know${b.email ? ` (${b.email})` : ''}.\nIf it was you, there's nothing to do.`;
const whatsapp = `🔐 *New sign-in*\n\nHello ${o.name || 'there'}, someone signed in to your *${b.name}* account.\n\n${lines.join('\n')}\n\nNot you? Change your password straight away and let the church office know.`;
return { subject: `New sign-in to your ${b.name} account`, text, html: layout(b, body, `New sign-in: ${o.when}, ${o.device}.`), whatsapp };
}
+1 -1
View File
@@ -9,7 +9,7 @@ export const SECRET_SETTINGS = new Set(['smtp_pass', 'wawp_access_token', 'hub_i
/** The settings an admin may read and change through the generic settings API. */
export const ADMIN_SETTINGS = new Set([
'signup_enabled', 'two_factor_required_for_admins', 'session_days',
'signup_enabled', 'two_factor_required_for_admins', 'session_days', 'signin_notices',
'smtp_host', 'smtp_port', 'smtp_user', 'smtp_pass', 'smtp_from', 'smtp_secure',
'wawp_access_token', 'wawp_instance_id',
]);
+19 -2
View File
@@ -27,7 +27,7 @@ import { newAccountEmail, testEmail } from '../lib/emails.js';
import { hashToken, randomToken } from '../lib/crypto.js';
import { appVersion } from '../lib/version.js';
import { BUILT_IN_VERSION } from '../privacy/notice.js';
import { emailProblem, normaliseEmail, profileChanged, setNewsConsent } from '../accounts/service.js';
import { emailProblem, normaliseEmail, profileChanged, profileOf, setNewsConsent } from '../accounts/service.js';
import { turnOff } from '../accounts/twoFactor.js';
import { signOutEverywhere } from '../oidc/sessions.js';
import { anonymise } from '../privacy/deletion.js';
@@ -303,6 +303,22 @@ async function handle(ctx: Ctx, provider: Provider, link: ProductLink, secret: s
await logRequest(ctx, link, r, 'demo_people_removed_by_product', null, req, { removed, kept: kept.length });
return reply({ removed, kept });
}
case 'people.check': {
// 1.5.0: the product's regular check that its copies are current. Profiles only for people
// this product knows; a deleted account is said to be deleted (its sub was that person's).
const subs = [...new Set(r.subs)];
const known = new Set((await ctx.db.productPerson.findMany({ where: { linkId: link.installId, accountId: { in: subs } }, select: { accountId: true } })).map((p) => p.accountId));
const accounts = new Map((await ctx.db.account.findMany({ where: { id: { in: subs } } })).map((a) => [a.id, a]));
const people = subs.map((sub) => {
const a = accounts.get(sub);
if (a?.status === 'deleted') return { sub, status: 'deleted' as const, profile: null };
if (!a || !known.has(sub)) return { sub, status: 'unknown' as const, profile: null };
return { sub, status: a.status === 'deactivated' ? 'deactivated' as const : 'active' as const, profile: profileOf(a) };
});
const count = (s: string) => people.filter((p) => p.status === s).length;
await logRequest(ctx, link, r, 'people_checked_by_product', null, req, { checked: people.length, deleted: count('deleted'), unknown: count('unknown') });
return reply({ people });
}
case 'church.branding': {
const changed = await applyLook(ctx, r.church, r.overwrite);
await logRequest(ctx, link, r, 'church_look_from_product', null, req, { changed, overwrite: r.overwrite });
@@ -382,7 +398,8 @@ export function requestsRouter(ctx: Ctx, provider: Provider) {
}
const out = await handle(ctx, provider, link, secret, request, req);
// Checks write nothing, so they needn't be remembered.
const isCheck = 'check' in request && request.check;
// people.check (1.5.0) only reads, and its reply holds profiles: never kept.
const isCheck = ('check' in request && request.check) || request.type === 'people.check';
if (!isCheck) {
await ctx.db.productRequest.create({ data: { requestId: request.requestId, linkId: link.installId, type: request.type, reply: out as never, createdAt: ctx.now() } }).catch(() => {});
}
@@ -199,6 +199,29 @@ describe('people.* from a product', () => {
assert.equal(again.body.created, true);
});
test('1.5.0 people.check: profiles of the product\'s people, deleted accounts, and unknown for the rest; never stored', async () => {
const ensure = (name: string, email: string) => ask({ type: 'people.ensure', name, email, phone: null, returnUrl: 'https://events.hope.test/' }).then((r) => r.body.sub as string);
const known = await ensure('Check Known', 'check.known@hope.test');
const gone = await ensure('Check Gone', 'check.gone@hope.test');
await h.db.account.update({ where: { id: gone }, data: { status: 'deleted' } });
const off = await ensure('Check Off', 'check.off@hope.test');
await h.db.account.update({ where: { id: off }, data: { status: 'deactivated' } });
const stranger = (await h.makeAccount({ email: 'check.stranger@hope.test' })).id as string;
const nobody = crypto.randomUUID();
const requestId = crypto.randomUUID();
const res = await ask({ type: 'people.check', subs: [known, gone, off, stranger, nobody] }, { requestId });
assert.equal(res.status, 200, JSON.stringify(res.body));
const bySub = Object.fromEntries((res.body.people as { sub: string; status: string; profile: { name: string } | null }[]).map((p) => [p.sub, p]));
assert.equal(bySub[known]!.status, 'active');
assert.equal(bySub[known]!.profile!.name, 'Check Known');
assert.equal(bySub[gone]!.status, 'deleted');
assert.equal(bySub[gone]!.profile, null);
assert.equal(bySub[off]!.status, 'deactivated');
assert.deepEqual([bySub[stranger]!.status, bySub[stranger]!.profile], ['unknown', null], 'not known through this product: no profile');
assert.equal(bySub[nobody]!.status, 'unknown');
assert.equal(await h.db.productRequest.findUnique({ where: { requestId } }), null, 'the reply holds profiles: not kept');
});
test('a retry with the same request id gets the same answer; a bad signature is refused', async () => {
const requestId = crypto.randomUUID();
const body = { type: 'people.ensure', name: 'Retry', email: 'retry@hope.test', phone: null, returnUrl: 'https://events.hope.test/' };
@@ -0,0 +1,50 @@
// 1.6.0: a "New sign-in" email (and WhatsApp) after each sign-in, as Cross Events sends.
import assert from 'node:assert/strict';
import { after, before, describe, test } from 'node:test';
import { startHarness, type Harness } from './support/harness.js';
import { describeDevice, sendSignInNotice } from '../src/accounts/signInNotice.js';
import type { MemoryMessenger } from '../src/lib/messages.js';
let h: Harness;
before(async () => { h = await startHarness(); });
after(async () => { await h.close(); });
const CHROME_WIN = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0 Safari/537.36';
describe('sign-in notices', () => {
test('an email with when, where, the device and the site; WhatsApp too for a verified number', async () => {
const m = h.ctx.messenger as MemoryMessenger;
const a = await h.makeAccount({ email: 'notice.person@hope.test' });
assert.equal(await sendSignInNotice(h.ctx, { accountId: a.id as string, ip: '127.0.0.1', userAgent: CHROME_WIN, clientId: 'accounts-self' }), 'sent');
const mail = m.emails.filter((e) => e.to === 'notice.person@hope.test').at(-1)!;
assert.match(mail.subject, /^New sign-in to your .+ account$/);
assert.match(mail.text, /Device: Chrome on Windows/);
assert.match(mail.text, /Signed in to: Your account page/);
assert.match(mail.html ?? '', /Not you\?/);
await h.db.account.update({ where: { id: a.id as string }, data: { phone: '+27821234567', phoneVerified: true } });
m.whatsappOn = true;
const before = m.whatsapps.length;
await sendSignInNotice(h.ctx, { accountId: a.id as string, ip: null, userAgent: null, clientId: null });
assert.equal(m.whatsapps.length, before + 1);
assert.match(m.whatsapps.at(-1)!.text, /New sign-in/);
m.whatsappOn = false;
});
test('admins can switch them off; a failing email never throws', async () => {
const m = h.ctx.messenger as MemoryMessenger;
const a = await h.makeAccount({ email: 'notice.off@hope.test' });
await h.ctx.settings.set('signin_notices', 'false');
assert.equal(await sendSignInNotice(h.ctx, { accountId: a.id as string, ip: null, userAgent: null, clientId: null }), 'off');
await h.ctx.settings.set('signin_notices', null);
m.emailOn = false;
assert.equal(await sendSignInNotice(h.ctx, { accountId: a.id as string, ip: null, userAgent: null, clientId: null }), 'failed');
m.emailOn = true;
});
test('device names', () => {
assert.equal(describeDevice(CHROME_WIN), 'Chrome on Windows');
assert.equal(describeDevice('Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 Version/17.0 Mobile/15E148 Safari/604.1'), 'Safari on iPhone or iPad');
assert.equal(describeDevice(null), 'Unknown device');
});
});
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/accounts-frontend",
"version": "1.4.0",
"version": "1.6.0",
"private": true,
"description": "Cross Code Accounts: the church's sign-in pages, the account page and admin",
"scripts": {
@@ -57,7 +57,7 @@ export function Admin({ section = "people" }: { section?: AdminSection }) {
{section === "deletions" && <Deletions flash={flash} />}
{section === "church" && <Church flash={flash} />}
{section === "linked" && <Linked flash={flash} />}
{section === "signin" && <Settings flash={flash} keys={["signup_enabled", "two_factor_required_for_admins", "session_days"]} />}
{section === "signin" && <Settings flash={flash} keys={["signup_enabled", "two_factor_required_for_admins", "signin_notices", "session_days"]} />}
{section === "messages" && <Settings flash={flash} keys={["smtp_host", "smtp_port", "smtp_user", "smtp_pass", "smtp_from", "smtp_secure", "wawp_access_token", "wawp_instance_id"]} />}
{section === "notice" && <NoticeTab flash={flash} />}
{section === "backups" && <Backups flash={flash} />}
@@ -252,6 +252,7 @@ function Linked({ flash }: { flash: Flash }) {
const SETTING_LABELS: Record<string, [string, "bool" | "text" | "secret" | "number"]> = {
signup_enabled: ["Members can create their own account", "bool"],
two_factor_required_for_admins: ["Admins must use two-step sign-in", "bool"],
signin_notices: ["Tell people by email (and WhatsApp) each time they sign in", "bool"],
session_days: ['Days "Keep me signed in" lasts', "number"],
smtp_host: ["SMTP server", "text"], smtp_port: ["SMTP port", "number"], smtp_user: ["SMTP user name", "text"], smtp_pass: ["SMTP password", "secret"],
smtp_from: ["Send from (email address)", "text"], smtp_secure: ["Use TLS from the start (port 465)", "bool"],
@@ -266,7 +267,7 @@ function Settings({ flash, keys }: { flash: Flash; keys: string[] }) {
return () => { alive = false; };
}, []);
if (!values) return <p className="text-gray-600">Loading…</p>;
const defaults: Record<string, boolean> = { signup_enabled: true, two_factor_required_for_admins: true };
const defaults: Record<string, boolean> = { signup_enabled: true, two_factor_required_for_admins: true, signin_notices: true };
return (
<Card>
<form onSubmit={async (e) => {
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/agent",
"version": "1.3.0",
"version": "1.3.1",
"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",
+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.2.0";
export const AGENT_VERSION = "1.3.1";
function run(cmd: string, args: string[], timeoutMs = 10_000): Promise<string | null> {
return new Promise((resolve) => {
+50
View File
@@ -5,6 +5,56 @@ 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/).
## [3.6.1] - 2026-11-20
### Fixed
- **Uploading a logo or favicon under Settings → Branding failed on some servers** with "The logo was
uploaded, but the site can't show it yet". The upload worked, but on a server whose proxy has a
rule for file extensions (static-file caching) every `/api/…` path ending in `.png`, `.ico`,
`.pdf`, `.json` and so on went to the site (Next.js), which answered 404. So the check after the
upload failed, as did pictures, certificate PDFs and `/api/v2/openapi.json`. Two changes:
- The site passes `/api/*` and `/uploads/*` that reach it on to the backend
(`next.config.ts` rewrites, `beforeFiles`). New frontend setting `BACKEND_INTERNAL_URL`
(`http://127.0.0.1:<apiPort>`, added to `.env.production` on deploy). Unset, nothing is
passed on, as before. The end-to-end tests' `E2E_API_PROXY` uses the same rewrites.
- The nginx site the installers write (and DEPLOYMENT.md) sends `/api/` and `/uploads/` to the
backend with `location ^~`, so no regex location can take them. Existing servers keep their
nginx file: change it by hand (DEPLOYMENT.md §4).
## [3.6.0] - 2026-11-20
Works with any Accounts; the people check needs Accounts 1.5.0 (with an older one it's skipped).
### Added
- **The nightly people check** (`accounts-people-check`, 04:30, `ACCOUNTS_PEOPLE_CHECK_ENABLED`,
`src/accounts/peopleCheck.ts`). In Accounts mode it sends every linked person's `sub` to
Accounts, 500 at a time (`people.check`, contracts 1.14.0), and: updates the local copy where the
name, email, phone or news choices differ (as `user.updated`); handles deleted accounts as
`user.deleted` (anonymised, or deferred while there's a registration for an event that hasn't
ended); counts deactivated and unknown people. When more than half a page (10+) is unknown, the
site is probably linked to the wrong Accounts: the check stops, changes nothing for them, fails
(Background jobs, the Hub's "jobs failing") and records why (the Hub's "sign-in failed" alert).
## [3.5.0] - 2026-11-20
### Fixed
- **After "Load demo data" nobody could sign in** ("Sign-in isn't available right now",
`ACCOUNTS_UNAVAILABLE`). `scripts/set-demo.js` emptied `ProductLink` (it keeps only a few tables)
but kept `AppSetting`, so the site stayed in Accounts mode with no Accounts link, and
`accounts_auto_connected` stopped it reconnecting. Demo data now keeps `ProductLink` and
`LinkNonce`, and a site in Accounts mode without a link connects to the Accounts the Hub lists at
its next heartbeat whatever happened before (a site on its own sign-in still keeps an admin's
Disconnect).
### Added
- Heartbeat `stats.signIn` (contracts 1.13.0): the sign-in mode, the linked Accounts (install id and
address) and the last failure to start or finish a sign-in (`accounts_last_signin_error`, cleared
by the next sign-in that works). The Hub 2.9.0 alerts on it.
## [3.4.0] - 2026-11-20
### Added
+26 -15
View File
@@ -127,13 +127,17 @@ server {
access_log /var/log/nginx/hope-events.access.log hope_proxy;
# Visitors only reach this through the VPS over HTTPS, so tell the app so.
location ~ ^/(api|uploads|health|docs)(/|$) {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
# For the backend locations below ("location /" sets its own).
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
# The API and uploaded files go to the backend. Keep the ^~: without it, any regex location
# (e.g. one that caches *.png or *.css) wins and sends /api/uploads/…/logo.png to the site.
location ^~ /api/ { proxy_pass http://127.0.0.1:5000; }
location ^~ /uploads/ { proxy_pass http://127.0.0.1:5000; }
location ~ ^/(api|uploads|health|docs)(/|$) { proxy_pass http://127.0.0.1:5000; }
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
@@ -147,7 +151,10 @@ server {
```
The VPS nginx/Caddy must redirect plain HTTP to HTTPS and pass the `Host` header through to frps
unchanged (frps picks the site by its host name). For nginx on the VPS, roughly:
unchanged (frps picks the site by its host name). Send every path through as it is: no
`location ~* \.(png|css|js…)$` caching rules for this site on the VPS, which would send
`/api/uploads/…/logo.png` to the site instead of the backend. (Since 3.6.1 the site passes such
requests on to the backend itself, but they're slower that way.) For nginx on the VPS, roughly:
```nginx
server {
@@ -188,13 +195,17 @@ server {
client_max_body_size 25m;
access_log /var/log/nginx/hope-events.access.log hope_proxy;
location ~ ^/(api|uploads|health|docs)(/|$) {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
# For the backend locations below ("location /" sets its own).
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
# The API and uploaded files go to the backend. Keep the ^~: without it, any regex location
# (e.g. one that caches *.png or *.css) wins and sends /api/uploads/…/logo.png to the site.
location ^~ /api/ { proxy_pass http://127.0.0.1:5000; }
location ^~ /uploads/ { proxy_pass http://127.0.0.1:5000; }
location ~ ^/(api|uploads|health|docs)(/|$) { proxy_pass http://127.0.0.1:5000; }
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
+28
View File
@@ -12,6 +12,34 @@ 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".
-->
## 3.6.1
- **Fix:** uploading a logo or site icon under Settings → Branding could fail with "uploaded, but
the site can't show it yet", depending on how the server is set up. Uploaded pictures, certificate
downloads and the like now show on those servers too.
## 3.6.0
- **People's details are checked every night.** Cross Events compares everyone's name, email,
phone and news choices with their church account and fixes any that are out of date, and handles
accounts that were deleted, in case a change never reached this site. You can see it, run it or
switch it off under Settings → Background jobs. It needs Accounts 1.5.0.
## 3.5.0
- **Fix:** after loading demo data, nobody could sign in: the site forgot its link to the church's
sign-in (Accounts). Demo data keeps it now, and a site that lost it connects again by itself
within about 15 minutes of updating.
- When signing in fails, Cross Code is told why, so it can help sooner.
## 3.4.0
- **Switch background jobs on and off yourself.** Settings → Background jobs has a switch for each
job (reminders, backups, the daily summary and so on) and lets you change when it runs, with ready
choices such as "every 15 minutes" or "daily at 07:00". It works straight away, no restart needed,
and one click puts a job back to how the server normally runs it.
- **Run now** works for a job that's switched off too, for when you want it once.
## 3.3.0
- **Fix:** a new logo or favicon sometimes didn't show after saving. It's saved and shown properly
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/events-backend",
"version": "3.4.0",
"version": "3.6.1",
"description": "Event Management System Backend",
"main": "src/index.js",
"scripts": {
+3
View File
@@ -76,6 +76,9 @@ const LIST_ONLY = process.argv.includes('--list');
const KEEP_TABLES = new Set([
'_prisma_migrations', 'AppSetting', 'User',
'SecurityEvent', 'PasswordReset', 'TwoFactorChallenge', 'TrustedDevice',
// 3.5.0: the links to the church's other products (Accounts above all: in Accounts mode, without
// its link nobody can sign in). Their feeds are data and go.
'ProductLink', 'LinkNonce',
]);
const SCHEDULED_EMAILS_PATH = path.resolve(__dirname, '../data/scheduled-emails.json');
@@ -7,12 +7,16 @@
import { connectTo } from '../links/connect';
import { linkedProducts } from '../links/store';
import { accountsLink } from './client';
import { getSetting, setSetting } from './mode';
import { getSetting, setSetting, viaAccounts } from './mode';
export const AUTO_KEY = 'accounts_auto_connected';
export async function connectAccountsIfListed(now = new Date()): Promise<'connected' | 'skipped'> {
if (await getSetting(AUTO_KEY)) return 'skipped';
// 3.5.0: a site that signs in through Accounts but has lost its link (before 3.5.0, loading demo
// data deleted it) can't sign anyone in, so it reconnects whatever was done before. A site on its
// own sign-in keeps an admin's Disconnect.
const stranded = (await viaAccounts()) && !(await accountsLink());
if ((await getSetting(AUTO_KEY)) && !stranded) return 'skipped';
if (await accountsLink()) {
await setSetting(AUTO_KEY, now.toISOString());
return 'skipped';
@@ -0,0 +1,102 @@
/**
* The nightly people check (3.6.0, contracts 1.14.0 `people.check`, Accounts 1.5.0): Accounts tells
* Events about every change (`user.updated`, `user.deleted`), retried for about a week; this catches
* whatever never arrived (a link that was down, as after a demo load before 3.5.0). For everyone here
* with an account it asks Accounts, a page at a time, and:
*
* - updates the local copy when the profile differs (as `user.updated` does);
* - handles a deleted account as `user.deleted` does (anonymised, or deferred while the person has a
* registration for an event that hasn't ended);
* - only counts people Accounts doesn't know through this site (`unknown`). When most of a page is
* unknown, Events is probably linked to the wrong Accounts: the check stops and fails, so it
* shows on Background jobs and the Hub, and nothing is changed for those people.
*/
import { PEOPLE_CHECK_MAX, peopleCheckReplySchema, type PeopleCheckReply, type Profile } from '@crosscode/contracts';
import { accounts, accountsLink } from './client';
import { handleAccountsCall } from './calls';
import { viaAccounts } from './mode';
import { recordSignInError } from './status';
import { updateLocalCopy } from './signin';
/* eslint-disable @typescript-eslint/no-require-imports -- CommonJS */
const prisma = require('../config/db');
/* eslint-enable @typescript-eslint/no-require-imports */
type Local = { id: string; accountId: string; name: string; email: string; phoneNumber: string | null; newsEmail: boolean; newsWhatsApp: boolean };
export type PeopleCheckResult = { checked: number; updated: number; deleted: number; deferred: number; deactivated: number; unknown: number } | { skipped: string };
/** Asks Accounts about these subs (tests replace it). */
export type Ask = (subs: string[]) => Promise<PeopleCheckReply>;
const defaultAsk: Ask = async (subs) => {
const auth = await accounts();
const raw = await auth.request({ type: 'people.check', actor: null, subs }, { timeoutMs: 120000 });
return peopleCheckReplySchema.parse(raw);
};
/** Whether the local copy already says what the profile says (only what Events keeps). */
export function sameAsLocal(u: Local, p: Profile): boolean {
return u.name === p.name
&& u.email.toLowerCase() === p.email.toLowerCase()
&& (u.phoneNumber ?? null) === (p.phone_number ?? null)
&& u.newsEmail === p.news_consent.email
&& u.newsWhatsApp === p.news_consent.whatsapp;
}
/** More than this share of a page unknown (with at least MIN_FOR_ALARM people) stops the check. */
const UNKNOWN_ALARM = 0.5;
const MIN_FOR_ALARM = 10;
export async function runPeopleCheck(opts: { ask?: Ask; pageSize?: number } = {}): Promise<PeopleCheckResult> {
if (!(await viaAccounts())) return { skipped: 'This site uses its own sign-in.' };
if (!(await accountsLink())) return { skipped: 'Accounts isn\'t linked.' };
const ask = opts.ask ?? defaultAsk;
const size = Math.min(opts.pageSize ?? PEOPLE_CHECK_MAX, PEOPLE_CHECK_MAX);
const out = { checked: 0, updated: 0, deleted: 0, deferred: 0, deactivated: 0, unknown: 0 };
let cursor: string | undefined;
for (;;) {
const page: Local[] = await prisma.user.findMany({
where: { accountId: { not: null } },
select: { id: true, accountId: true, name: true, email: true, phoneNumber: true, newsEmail: true, newsWhatsApp: true },
orderBy: { id: 'asc' },
take: size,
...(cursor ? { cursor: { id: cursor }, skip: 1 } : {}),
});
if (!page.length) break;
cursor = page[page.length - 1]!.id;
const bySub = new Map(page.map((u) => [u.accountId, u]));
let reply: PeopleCheckReply;
try {
reply = await ask(page.map((u) => u.accountId));
} catch (e) {
// Accounts before 1.5.0 doesn't know people.check: nothing to do until it's updated.
const err = e as { code?: string; message?: string };
if (err.code === 'INVALID_REQUEST' && /\btype\b/.test(err.message ?? '')) return { skipped: 'The church\'s Accounts is older than 1.5.0, which this check needs.' };
throw e;
}
const unknown = reply.people.filter((p) => p.status === 'unknown').length;
if (page.length >= MIN_FOR_ALARM && unknown / page.length > UNKNOWN_ALARM) {
const message = `Accounts doesn't know ${unknown} of ${page.length} people here: is this site linked to the church's own Accounts? Nothing was changed for them.`;
await recordSignInError('PEOPLE_UNKNOWN', message);
throw new Error(message);
}
for (const p of reply.people) {
const u = bySub.get(p.sub);
if (!u) continue; // not one we asked about
out.checked++;
if (p.status === 'unknown') { out.unknown++; continue; }
if (p.status === 'deleted') {
const r = await handleAccountsCall({ type: 'user.deleted', sub: p.sub } as never) as { status?: string };
if (r.status === 'deferred') out.deferred++; else out.deleted++;
continue;
}
if (p.status === 'deactivated') out.deactivated++;
if (p.profile && !sameAsLocal(u, p.profile)) {
await updateLocalCopy(u.id, p.profile);
out.updated++;
}
}
if (page.length < size) break;
}
return out;
}
+9 -2
View File
@@ -20,6 +20,7 @@ import { siteUrl } from '../feed/context';
import { accounts, AccountsUnavailable } from './client';
import { viaAccounts } from './mode';
import { handleAccountsCall } from './calls';
import { clearSignInError, recordSignInError } from './status';
/* eslint-disable @typescript-eslint/no-require-imports -- CommonJS */
const prisma = require('../config/db');
@@ -144,7 +145,10 @@ async function startSignIn(req: Request, res: Response) {
return res.redirect(303, url);
} catch (e) {
console.warn('[accounts] sign-in could not start:', (e as Error).message);
return problem(res, e instanceof AccountsUnavailable ? 'ACCOUNTS_UNAVAILABLE' : 'START_FAILED', returnTo);
const failed = e instanceof AccountsUnavailable ? 'ACCOUNTS_UNAVAILABLE' : 'START_FAILED';
// 3.5.0: the reason goes to the Hub with the next heartbeat (the page only says "try again").
await recordSignInError(failed, (e as Error).message);
return problem(res, failed, returnTo);
}
}
@@ -158,7 +162,8 @@ async function callback(req: Request, res: Response) {
let auth;
try {
auth = await accounts();
} catch {
} catch (e) {
await recordSignInError('ACCOUNTS_UNAVAILABLE', (e as Error).message);
return problem(res, 'ACCOUNTS_UNAVAILABLE');
}
let signed;
@@ -168,8 +173,10 @@ async function callback(req: Request, res: Response) {
} catch (e) {
const code = (e as { code?: string }).code;
console.warn('[accounts] sign-in could not finish:', (e as Error).message);
if (code !== 'NO_PENDING') await recordSignInError('FINISH_FAILED', (e as Error).message);
return problem(res, code === 'NO_PENDING' ? 'EXPIRED' : 'FINISH_FAILED');
}
await clearSignInError();
const { claims, returnTo, idToken } = signed;
const found = await userForClaims(claims);
@@ -0,0 +1,32 @@
/**
* How people sign in here, for the Hub (3.5.0, heartbeat `stats.signIn`, contracts 1.13.0): the
* mode, the Accounts this site is linked to, and the last sign-in that failed to start or finish.
* A site in `accounts` mode without a link can't sign anyone in; the Hub raises an alert for it.
*/
import { accountsLink } from './client';
import { authMode, getSetting, setSetting } from './mode';
export const LAST_ERROR_KEY = 'accounts_last_signin_error';
type LastError = { at: string; code: string; message: string };
/** Keeps the last failure (a code and a sentence; never tokens or cookies). */
export async function recordSignInError(code: string, message: string, now = new Date()): Promise<void> {
const value: LastError = { at: now.toISOString(), code: code.slice(0, 60), message: message.replace(/\s+/g, ' ').slice(0, 500) };
await setSetting(LAST_ERROR_KEY, JSON.stringify(value)).catch(() => {});
}
/** A sign-in that worked clears it. */
export async function clearSignInError(): Promise<void> {
if (await getSetting(LAST_ERROR_KEY).catch(() => null)) await setSetting(LAST_ERROR_KEY, null).catch(() => {});
}
export async function signInStatus(): Promise<{ mode: 'local' | 'accounts'; accounts: { installId: string; url: string } | null; lastError: LastError | null }> {
const [mode, link, raw] = await Promise.all([authMode(), accountsLink(), getSetting(LAST_ERROR_KEY).catch(() => null)]);
let lastError: LastError | null = null;
try {
const parsed = raw ? JSON.parse(raw) : null;
if (parsed && typeof parsed.at === 'string' && typeof parsed.code === 'string' && typeof parsed.message === 'string') lastError = parsed;
} catch { /* an unreadable value is no error */ }
return { mode, accounts: link ? { installId: link.installId, url: link.url } : null, lastError };
}
+3
View File
@@ -145,10 +145,13 @@ async function stats(now = new Date()) {
const live = await liveNow(now).catch(() => undefined);
const campusesOn = await campusesEnabled().catch(() => false);
const campusCount = campusesOn ? await prisma.campus.count({ where: { archivedAt: null } }) : 0;
// 3.5.0: how people sign in (the Hub flags a site in Accounts mode without a link, or failing).
const signIn = await require('../accounts/status').signInStatus().catch(() => undefined);
return {
users,
events: { active: activeEvents, upcoming: upcomingEvents, total: totalEvents },
...(live ? { live } : {}),
...(signIn ? { signIn } : {}),
registrations: { last30d: regs30, total: regsTotal },
tickets: { last30d: tickets30, total: ticketsTotal },
checkIns: { last30d: checkIns30 },
+5
View File
@@ -98,6 +98,11 @@ const JOBS = [
name: 'backup', label: 'Database backup', cron: '0 2 * * *', env: 'BACKUP_ENABLED',
run: async () => ({ file: (await require('../utils/backupUtils').runBackup()).filename }),
},
{
// 3.6.0: catch any change from Accounts that never arrived (accounts/peopleCheck.ts).
name: 'accounts-people-check', label: 'Accounts: check everyone\'s details here match their church account', cron: '30 4 * * *', env: 'ACCOUNTS_PEOPLE_CHECK_ENABLED',
run: () => require('../accounts/peopleCheck').runPeopleCheck(),
},
{
// 3.0.0 (docs/EVENTS-3.0-PLAN.md §5): 14 days after sign-in moved to Accounts, Events' old
// passwords and 2FA secrets go; sign-in records (for signing out of Accounts) after 40 days.
@@ -7,7 +7,9 @@ let mockLink: object | null = null;
jest.mock('../src/links/connect', () => ({ connectTo: async (...args: unknown[]) => { mockConnects.push(args); mockLink = { installId: args[0] }; } }));
jest.mock('../src/links/store', () => ({ linkedProducts: async () => mockListed }));
jest.mock('../src/accounts/client', () => ({ accountsLink: async () => mockLink }));
let mockMode = 'local';
jest.mock('../src/accounts/mode', () => ({
viaAccounts: async () => mockMode === 'accounts',
getSetting: async (k: string) => mockSettings.get(k) ?? null,
setSetting: async (k: string, v: string | null) => { if (v === null) mockSettings.delete(k); else mockSettings.set(k, v); },
}));
@@ -21,6 +23,7 @@ beforeEach(() => {
mockConnects.length = 0;
mockListed = [];
mockLink = null;
mockMode = 'local';
});
test('connects to the Accounts the Hub lists, as the system, once', async () => {
@@ -46,3 +49,13 @@ test('already connected by an admin: just remembers it', async () => {
expect(mockConnects).toEqual([]);
expect(mockSettings.has(AUTO_KEY)).toBe(true);
});
test('3.5.0: a site in Accounts mode that lost its link (a demo load before 3.5.0) connects again', async () => {
mockSettings.set(AUTO_KEY, '2026-11-19T10:00:00.000Z');
mockListed = [{ installId: ACCOUNTS, product: 'accounts' }];
// On its own sign-in, an earlier Disconnect stays.
expect(await connectAccountsIfListed()).toBe('skipped');
mockMode = 'accounts';
expect(await connectAccountsIfListed()).toBe('connected');
expect(mockConnects).toEqual([[ACCOUNTS, { id: null, role: 'system' }, null, expect.any(Date)]]);
});
@@ -0,0 +1,83 @@
// 3.6.0: the nightly people check against Accounts (contracts 1.14.0 people.check).
type U = { id: string; accountId: string; name: string; email: string; phoneNumber: string | null; newsEmail: boolean; newsWhatsApp: boolean };
let mockUsers: U[] = [];
const mockUpdated: string[] = [];
const mockCalls: { type: string; sub: string }[] = [];
const mockErrors: string[] = [];
let mockMode = true;
let mockLinked = true;
let mockDeferred = new Set<string>();
jest.mock('../src/config/db', () => ({
user: {
findMany: async ({ take, cursor }: { take: number; cursor?: { id: string } }) => {
const sorted = [...mockUsers].sort((a, b) => a.id.localeCompare(b.id));
const start = cursor ? sorted.findIndex((u) => u.id === cursor.id) + 1 : 0;
return sorted.slice(start, start + take);
},
},
}));
jest.mock('../src/accounts/mode', () => ({ viaAccounts: async () => mockMode }));
jest.mock('../src/accounts/client', () => ({ accountsLink: async () => (mockLinked ? { installId: 'acc-1' } : null), accounts: async () => { throw new Error('not in tests'); } }));
jest.mock('../src/accounts/signin', () => ({ updateLocalCopy: async (id: string) => { mockUpdated.push(id); } }));
jest.mock('../src/accounts/calls', () => ({
handleAccountsCall: async (c: { type: string; sub: string }) => { mockCalls.push(c); return { status: mockDeferred.has(c.sub) ? 'deferred' : 'deleted' }; },
}));
jest.mock('../src/accounts/status', () => ({ recordSignInError: async (_c: string, m: string) => { mockErrors.push(m); } }));
import type { PeopleCheckReply, Profile } from '@crosscode/contracts';
import { runPeopleCheck, sameAsLocal } from '../src/accounts/peopleCheck';
const sub = (n: number) => `00000000-0000-4000-8000-${String(n).padStart(12, '0')}`;
const user = (n: number, over: Partial<U> = {}): U => ({ id: `u${String(n).padStart(3, '0')}`, accountId: sub(n), name: `Person ${n}`, email: `p${n}@hope.test`, phoneNumber: null, newsEmail: false, newsWhatsApp: false, ...over });
const profile = (u: U, over: Partial<Profile> = {}): Profile => ({ name: u.name, given_name: null, family_name: null, email: u.email, email_verified: true, phone_number: u.phoneNumber, phone_number_verified: false, news_consent: { email: u.newsEmail, whatsapp: u.newsWhatsApp }, ...over });
beforeEach(() => {
mockUsers = []; mockUpdated.length = 0; mockCalls.length = 0; mockErrors.length = 0;
mockMode = true; mockLinked = true; mockDeferred = new Set();
});
test('updates only copies that differ, handles deleted accounts as user.deleted does, counts the rest', async () => {
mockUsers = [user(1), user(2), user(3), user(4), user(5)];
mockDeferred = new Set([sub(4)]);
const ask = async (subs: string[]): Promise<PeopleCheckReply> => ({
schema: 'crosscode.identity-request/1',
people: subs.map((s) => {
const u = mockUsers.find((x) => x.accountId === s)!;
if (s === sub(1)) return { sub: s, status: 'active' as const, profile: profile(u) };
if (s === sub(2)) return { sub: s, status: 'active' as const, profile: profile(u, { name: 'New Name', news_consent: { email: true, whatsapp: false } }) };
if (s === sub(3) || s === sub(4)) return { sub: s, status: 'deleted' as const, profile: null };
return { sub: s, status: 'unknown' as const, profile: null };
}),
});
expect(await runPeopleCheck({ ask, pageSize: 2 })).toEqual({ checked: 5, updated: 1, deleted: 1, deferred: 1, deactivated: 0, unknown: 1 });
expect(mockUpdated).toEqual(['u002']);
expect(mockCalls.map((c) => [c.type, c.sub])).toEqual([['user.deleted', sub(3)], ['user.deleted', sub(4)]]);
});
test('stops, changing nothing, when Accounts knows hardly anyone (linked to the wrong Accounts?)', async () => {
mockUsers = Array.from({ length: 12 }, (_, i) => user(i + 1));
const ask = async (subs: string[]): Promise<PeopleCheckReply> => ({ schema: 'crosscode.identity-request/1', people: subs.map((s) => ({ sub: s, status: 'unknown' as const, profile: null })) });
await expect(runPeopleCheck({ ask })).rejects.toThrow(/doesn't know 12 of 12/);
expect(mockCalls).toEqual([]);
expect(mockErrors).toHaveLength(1);
});
test('skipped on its own sign-in, or without a link', async () => {
mockMode = false;
expect(await runPeopleCheck({ ask: async () => { throw new Error('asked'); } })).toEqual({ skipped: expect.any(String) });
mockMode = true; mockLinked = false;
expect(await runPeopleCheck({ ask: async () => { throw new Error('asked'); } })).toEqual({ skipped: expect.any(String) });
});
test('sameAsLocal ignores email case and what Events doesn\'t keep', () => {
const u = user(1, { email: 'Jane@Hope.test' });
expect(sameAsLocal(u, profile(u, { email: 'jane@hope.test', email_verified: false, given_name: 'Jane' }))).toBe(true);
expect(sameAsLocal(u, profile(u, { phone_number: '+27821234567' }))).toBe(false);
});
test('an Accounts before 1.5.0 (people.check unknown there) skips the check instead of failing every night', async () => {
mockUsers = [user(1)];
const ask = async () => { throw Object.assign(new Error('Not a crosscode.identity-request/1 request: type Invalid input'), { code: 'INVALID_REQUEST' }); };
expect(await runPeopleCheck({ ask })).toEqual({ skipped: expect.stringContaining('1.5.0') });
});
@@ -0,0 +1,32 @@
// 3.5.0: how people sign in, for the Hub (heartbeat stats.signIn, contracts 1.13.0).
import { hub } from '@crosscode/contracts';
const mockSettings = new Map<string, string>();
let mockMode = 'accounts';
let mockLink: object | null = null;
jest.mock('../src/accounts/client', () => ({ accountsLink: async () => mockLink }));
jest.mock('../src/accounts/mode', () => ({
authMode: async () => mockMode,
getSetting: async (k: string) => mockSettings.get(k) ?? null,
setSetting: async (k: string, v: string | null) => { if (v === null) mockSettings.delete(k); else mockSettings.set(k, v); },
}));
import { clearSignInError, recordSignInError, signInStatus } from '../src/accounts/status';
beforeEach(() => { mockSettings.clear(); mockMode = 'accounts'; mockLink = null; });
test('Accounts mode without a link, and why the last sign-in failed', async () => {
await recordSignInError('ACCOUNTS_UNAVAILABLE', 'Accounts isn\'t connected.\nConnect it under Settings → Linked products.', new Date('2026-11-20T10:00:00.000Z'));
const s = await signInStatus();
expect(s).toEqual({ mode: 'accounts', accounts: null, lastError: { at: '2026-11-20T10:00:00.000Z', code: 'ACCOUNTS_UNAVAILABLE', message: 'Accounts isn\'t connected. Connect it under Settings → Linked products.' } });
// It fits the heartbeat's contract.
expect(hub.eventsStatsSchema.shape.signIn.safeParse(s).success).toBe(true);
await clearSignInError();
expect((await signInStatus()).lastError).toBeNull();
});
test('linked: the Accounts install and its address', async () => {
mockLink = { installId: 'acc-1', url: 'https://accounts.hope.test', secret: 'x', updatedAt: new Date() };
expect((await signInStatus()).accounts).toEqual({ installId: 'acc-1', url: 'https://accounts.hope.test' });
});
+6
View File
@@ -108,6 +108,12 @@
"layer": "install",
"from": "https://{domain}",
"required": true
},
{
"name": "BACKEND_INTERNAL_URL",
"layer": "install",
"from": "http://127.0.0.1:{apiPort}",
"description": "The backend on this server: requests for /api or /uploads that reach the site are passed to it (3.6.1)"
}
]
}
+23 -4
View File
@@ -1,6 +1,15 @@
import type { NextConfig } from "next";
import { withSentryConfig } from "@sentry/nextjs";
// Requests for the backend (/api, /uploads) that reach the site anyway are passed to it (3.6.1).
// On a server nginx sends those paths to the backend, but a proxy in front can send some to the
// site instead: one with a rule for file extensions (static-file caching) sent every
// /api/uploads/…png here, so an uploaded logo never showed. BACKEND_INTERNAL_URL is the backend on
// this server (http://127.0.0.1:<port>), never the public address, which would come straight back
// here. The end-to-end tests set E2E_API_PROXY (3.0.0): the site and its API on one address, as
// nginx does, so Accounts' sign-in comes back to <site>/api/auth/callback.
const backend = (process.env.BACKEND_INTERNAL_URL || process.env.E2E_API_PROXY || "").replace(/\/+$/, "");
const nextConfig: NextConfig = {
// The end-to-end tests run their own dev server; a separate build folder keeps it
// from clashing with one already running.
@@ -12,10 +21,20 @@ const nextConfig: NextConfig = {
compiler: {
removeConsole: process.env.NODE_ENV === 'production',
},
// The end-to-end tests only (3.0.0): the site and its API on one address, as nginx does on a
// server, so Accounts' sign-in comes back to <site>/api/auth/callback. Unset everywhere else.
...(process.env.E2E_API_PROXY
? { async rewrites() { return [{ source: '/api/:path*', destination: `${process.env.E2E_API_PROXY}/api/:path*` }]; } }
...(backend
? {
// beforeFiles: ahead of every page, so a dynamic route like /[redirectUrl] never catches them.
async rewrites() {
return {
beforeFiles: [
{ source: '/api/:path*', destination: `${backend}/api/:path*` },
{ source: '/uploads/:path*', destination: `${backend}/uploads/:path*` },
],
afterFiles: [],
fallback: [],
};
},
}
: {}),
};
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/events-frontend",
"version": "3.4.0",
"version": "3.6.1",
"private": true,
"scripts": {
"dev": "next dev",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/events",
"version": "3.4.0",
"version": "3.6.1",
"main": "index.js",
"scripts": {
"dev:backend": "cd backend && npm run dev",
+11 -8
View File
@@ -116,7 +116,7 @@ else
echo " backend/.env exists — kept"
fi
if [ ! -f "$DIR/frontend/.env.production" ]; then
echo "NEXT_PUBLIC_API_URL=$SITE_URL" > "$DIR/frontend/.env.production"
printf 'NEXT_PUBLIC_API_URL=%s\nBACKEND_INTERNAL_URL=http://127.0.0.1:%s\n' "$SITE_URL" "$API_PORT" > "$DIR/frontend/.env.production"
fi
if [ ! -f "$DIR/ecosystem.config.js" ]; then
sed -e "s/'hope-events-backend'/'$NAME-backend'/" -e "s/'hope-events-frontend'/'$NAME-frontend'/" -e "s/-p 3000/-p $WEB_PORT/" \
@@ -140,14 +140,17 @@ server {
server_name $DOMAIN;
client_max_body_size 25m;
# For the backend locations below ("location /" sets its own).
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
# The API, uploaded files, health and API docs go to the backend; everything else to the site.
location ~ ^/(api|uploads|health|docs)(/|\$) {
proxy_pass http://127.0.0.1:$API_PORT;
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
}
# ^~ so a regex location added later (e.g. caching *.png) can't send /api/…/logo.png to the site.
location ^~ /api/ { proxy_pass http://127.0.0.1:$API_PORT; }
location ^~ /uploads/ { proxy_pass http://127.0.0.1:$API_PORT; }
location ~ ^/(api|uploads|health|docs)(/|\$) { proxy_pass http://127.0.0.1:$API_PORT; }
location / {
proxy_pass http://127.0.0.1:$WEB_PORT;
proxy_http_version 1.1;
+1 -1
View File
@@ -1,3 +1,3 @@
# Church Website
Placeholder: the church's public website and its admin. Built in phase 4 of ROADMAP-v3 (see §6 there).
Placeholder: the church's public website and its admin. Built in phase 5 of ROADMAP-v3 (see §6 there).
+1 -1
View File
@@ -2,5 +2,5 @@
"name": "@crosscode/website",
"version": "0.0.0",
"private": true,
"description": "Placeholder: Church Website, built in phase 4 (ROADMAP-v3 §6)"
"description": "Placeholder: Church Website, built in phase 5 (ROADMAP-v3 §6)"
}
+2 -1
View File
@@ -354,6 +354,7 @@ 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 5).
or Accounts' own screen is the only place. Decide with the Website plan (phase 5). **Decided 2026-11-21 (WEBSITE-1.0-PLAN decision 10):**
through Accounts' API, live at once.
- Session lengths (30 days with "Keep me signed in") are a starting point; check them with Joshua
before release.
+17 -9
View File
@@ -382,16 +382,24 @@ All in the Hub (Jobs page, with the full report) and by email:
```
Set up in FastPanel: events.hope.co.za (Hope Family Church, Cross Events)
1. Add the site events.hope.co.za.
2. Proxy:
/api → http://127.0.0.1:20011 (backend; Events 2.2.0+, older
releases also need /uploads, /health, /docs)
everything else → http://127.0.0.1:20010 (frontend)
Pass the Host header and X-Forwarded-For / X-Forwarded-Proto: https.
Allow uploads up to 25 MB.
1. Add the site events.hope.co.za as a proxy to http://127.0.0.1:20010 (the frontend). Pass the
Host header and X-Forwarded-For / X-Forwarded-Proto: https, and allow uploads up to 25 MB.
2. Send /api to the backend: add this to the site's nginx configuration. Keep the ^~: without
it FastPanel's static-file rule sends every /api path with a file extension to the frontend.
location ^~ /api/ {
proxy_pass http://127.0.0.1:20011;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
location = /api { proxy_pass http://127.0.0.1:20011; }
3. Turn on Let's Encrypt for the site.
4. DNS: events.hope.co.za → <central server IP> (checked: ✅ points there / ⚠ not yet)
5. Then click "Proxy done" in the Hub: <link>
4. DNS: events.hope.co.za → <central server IP> (checked: points there / not yet)
5. Click "Proxy done" in the Hub. It checks the site, its /api and a file under /api, then
makes it live: <link>
Central check: both ports are open in frps and only on 127.0.0.1.
```
+75 -20
View File
@@ -1,6 +1,6 @@
# Handover — Cross Code, all products
Last updated: 2026-11-19. **The plan is [ROADMAP-v3.md](./ROADMAP-v3.md)** (decided 2026-11-03,
Last updated: 2026-11-21. **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
@@ -25,28 +25,70 @@ every release).
| Phase | What | State |
|-------|------|-------|
| 0 | contracts 1.0.0 / 1.1.0 | **Released** 2026-11-04. Not published to a registry (decision 22): the Hub gets a packed release committed to its repo (`backend/vendor/`) |
| 1 | Hub 2.0.x | **Released** (`v2.0.0` 2026-11-05, `v2.0.1` AI tokens and `v2.0.2` refunds / voiding refunded invoices, 2026-11-17). **Not deployed yet:** `events-hub/deployment.md` → "Upgrading to 2.0" (run `check-hub2` first). Deploy straight to the latest 2.1.x (below) |
| 1b | Cross Events 2.2.0: moved here as `apps/events`, the `crosscode` script | **Released** 2026-11-17 (`events@2.2.0`, with AI use in tokens and the backend under `/api`). **VM tested 2026-11-17** (EVENTS-2.2-PLAN §6, all passing after fixes). **Not rolled out:** servers still run `hope-events` `v2.1.1` until each install is adopted |
| 1c | Cross Events 2.3.x: authenticator app 2FA (TOTP + recovery codes) | **Released** 2026-11-17 (`events@2.3.0`). **`events@2.3.1`** 2026-11-18: Next.js 16.4.6 (security advisories for 16.2.0–16.4.4), so roll out 2.3.1, not 2.3.0. crosscode-site `v1.3.0` lists it (merged and tagged, **not deployed**) |
| 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 | Cross Events 3.0.0: sign-in through Accounts, users migrated with their password hashes and 2FA | **Released** 2026-11-19 (`events@3.0.0`, `accounts@1.1.0`, `contracts@1.8.0`, Hub `v2.5.0`, crosscode-site `v1.6.0`; [EVENTS-3.0-PLAN.md](./EVENTS-3.0-PLAN.md)). Tested on Postgres 18: both migrations, `test:accounts` on real databases (14/14), the Events e2e suite (111, incl. `sign-in-accounts.spec.ts`). **Not VM tested yet.** Roll out: Hub 2.5.0 deployed first, then per church Accounts 1.1.0 → Events 3.0 → Move (MIGRATING-TO-3.md); crosscode-site 1.6.0 once the first church has moved |
| 5–7 | Website 1.0.0 → App 1.0.0 → App 1.x | Not started |
| 0 | contracts 1.0.0 → 1.14.0 | **Released and in use.** Not published to a registry (decision 22): the Hub gets a packed release committed to its repo (`backend/vendor/`) |
| 1 | Hub 2.0 → 2.10.0 | **Released, deployed and tested** (Hub `v2.10.0`) |
| 1b | Cross Events 2.2.0: moved here as `apps/events`, the `crosscode` script | **Released, rolled out and tested.** Every install adopted onto the monorepo |
| 1c | Cross Events 2.3.x: authenticator app 2FA | **Released and rolled out** (carried into Accounts in phase 4) |
| 1d | Agent 1.x + Hub 2.1+ | **Released, rolled out and tested** (agent `1.3.1` on every server; the central server's agent is read-only) |
| 2 | Cross Events 2.4.0: protocol v2, Linked products, event feed, `packages/seo` | **Released, rolled out and tested** ([EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md)) |
| 3 | Accounts 1.0.0 | **Released, rolled out and tested** (now `accounts@1.6.0`; [ACCOUNTS-1.0-PLAN.md](./ACCOUNTS-1.0-PLAN.md)) |
| 4 | Cross Events 3.0.0: sign-in through Accounts | **Released, rolled out and tested** (now `events@3.6.1`; [EVENTS-3.0-PLAN.md](./EVENTS-3.0-PLAN.md)). Churches sign in through their Accounts; crosscode-site `v1.6.0` deployed |
| 4+ | Running it: jobs from the dashboard, styled emails, .env from the Hub, sign-in health, the nightly people check | **Released, deployed and tested** 2026-11-20 (below) |
| 5 | Church Website 1.0.0 | **Planned** 2026-11-21: [WEBSITE-1.0-PLAN.md](./WEBSITE-1.0-PLAN.md) (all decisions confirmed). Not started |
| 6–7 | App 1.0.0 → App 1.x | Not started |
## Released 2026-11-20
All tagged, pushed, deployed and tested (confirmed by Joshua 2026-11-21). Details in [CHANGELOG.md](../CHANGELOG.md), the apps' CHANGELOGs
and What's New, and [VERSIONS.md](./VERSIONS.md).
| Release | What |
|---------|------|
| `events@3.4.0`, `accounts@1.4.0`, `contracts@1.12.0`, `agent@1.3.0`, Hub `v2.8.0` | Background jobs switched on/off and rescheduled from each site's admin (saved in `job_overrides`, wins over the .env, applies at once; Accounts gets an Admin → Background jobs page). Accounts' emails styled as Events' (`src/lib/emails.ts`). The Hub reads and changes an install's .env (`env-read` / `env-set` jobs → `crosscode env`; secrets never leave the server; the file is put back if the site doesn't start; the frontend's file triggers a rebuild) |
| `events@3.5.0`, `contracts@1.13.0`, `agent@1.3.1`, Hub `v2.9.0` | **Fix:** "Load demo data" deleted the Accounts link (`set-demo.js` truncated `ProductLink`), so events-demo couldn't sign anyone in (`ACCOUNTS_UNAVAILABLE`). Demo data keeps the link; a site in Accounts mode without a link reconnects at its next heartbeat. Heartbeat `stats.signIn`; Hub alerts: not linked (critical), wrong Accounts, sign-in failing, an Accounts nothing links to. **Agent 1.3.0 reported itself as 1.2.0**: use 1.3.1 |
| `accounts@1.6.0` | A "New sign-in" email (and WhatsApp) after every sign-in; Sign-in settings → `signin_notices` turns it off |
| Hub `v2.10.0` | Every Hub email laid out as Events' and Accounts' (`src/utils/emailLayout.js`: header with the logo, button, notes, job steps, code blocks; plain text kept). The FastPanel email gives `location ^~ /api/` as config to paste; Proxy done checks a file under `/api` reaches the backend. Billing emails unchanged |
| `events@3.6.1` | **Fix:** logo/favicon uploads failed on events-demo ("uploaded, but the site can't show it yet"). FastPanel's static-file rule sent every `/api/…` path with a file extension (`.png`, `.pdf`, …) to the frontend. The site now passes `/api/*` and `/uploads/*` on to the backend (`BACKEND_INTERNAL_URL`); the installers' nginx uses `location ^~`. Change each FastPanel site too (below) |
| `events@3.6.0`, `accounts@1.5.0`, `contracts@1.14.0` | The nightly people check (`accounts-people-check`, 04:30): `people.check` 500 subs at a time; fixes out-of-date copies, handles deleted accounts as `user.deleted`, stops (changing nothing) when most people are unknown. Skipped with an Accounts before 1.5.0 |
## FastPanel sites (central server)
FastPanel's nginx on the central server is the only router for sites behind frp: the church
server has no nginx. Its static-file handling adds a regex location for file extensions
(`png|jpg|ico|svg|css|js|pdf|txt|…`) that falls back to the site's main proxy, the frontend. A
plain `location /api` loses to it, so `/api/uploads/…/logo.png` reached Next.js and got a 404
(fixed in the site by Events 3.6.1, but slower and without the visitor's IP). In each Events
site's nginx config in FastPanel, the backend locations must be `^~` (a prefix match that no
regex can override):
```nginx
location ^~ /api/ {
proxy_pass http://127.0.0.1:<api port>;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
location = /api { proxy_pass http://127.0.0.1:<api port>; }
```
Since **Hub 2.10.0** the FastPanel email (AGENT-1.0-PLAN §11) gives this block to paste, and
**Proxy done** refuses a site whose `/api/proxy-check.png` reaches the frontend. Sites set up
before that need the change by hand, and so does the Hub's own site (`events-hub`,
`/api/…/statement.pdf`; its deployment.md §8). Check after a change:
`curl -sI https://<domain>/api/health.png` must not say `X-Powered-By: Next.js` (a 404 is fine).
## Next up
1. **Roll out**, in the order in [ROLLOUT-1.0.md](./ROLLOUT-1.0.md) (with the latest patch
releases: Hub 2.1.1, agent 1.0.1, Events 2.3.1): Hub 2.1 (make and back up
the job-signing key first) → the central server's agent (check `proxy_bind_addr = 127.0.0.1`)
→ each church server's agent → **adopt** the demo site, then each church (Link existing → Move
onto the monorepo) → a throwaway New install to prove FASTPANEL, DNS and Let's Encrypt.
2. **Deploy crosscode-site `v1.3.0`** (secure sign-in in the features and the brochure).
3. **Archive `hope-events`** once every install reports 2.2.0 or later (EVENTS-2.2-PLAN §7).
4. **Cross Events 2.4.0** (phase 2) is built on branches: run `npm run test:e2e` in `apps/events`
(with the e2e Postgres) and the VM test in EVENTS-2.4-PLAN §8, then merge and release in its
order (contracts 1.4.0 → Hub 2.2.0, deployed → Events 2.4.0 → crosscode-site 1.4.0).
Everything up to and including the 2026-11-20 releases is deployed, rolled out and tested
(VERSIONS.md, "Deployed / rolled out").
1. **Phase 5, Church Website 1.0.0** (ROADMAP §6, §9). Planned in
[WEBSITE-1.0-PLAN.md](./WEBSITE-1.0-PLAN.md): decisions all confirmed 2026-11-21. Order:
contracts 1.15.0 → Accounts 1.7.0 → Events 3.7.0 (shared fonts and footer) → Hub 2.11.0 →
`website@1.0.0` → Hope Family Church → a second church → crosscode-site 1.7.0.
2. **Archive `hope-events`** if it isn't yet (every install now reports 2.2.0 or later;
EVENTS-2.2-PLAN §7).
## The VM test (2026-11-17)
@@ -95,6 +137,19 @@ rollout.
- **AI for a church:** set the licence's monthly AI cap above R0 on the Hub; with no cap the
buttons don't show (rules in Events' handover, "AI rules"). Churches see tokens; only the Hub
shows rand (markup 15% by default).
- **The agent's version is in two places:** `apps/agent/package.json` *and* `AGENT_VERSION` in
`apps/agent/src/stats.ts` (what it reports to the Hub). Bump both; the agent's test checks they match,
so run `npm run check` *after* the bump (1.3.0 shipped reporting 1.2.0).
- **Background jobs:** each job's switch and schedule can be set in the site's admin (Events and
Accounts, AppSetting `job_overrides`); that wins over the .env flag and `JOB_SCHEDULE_<NAME>`.
`JOBS_ENABLED=false` still turns everything off. A new job gets a `label` and, if it may be turned
off from the .env, an `env` flag.
- **An install's .env from the Hub** (install page → Settings (.env), agent 1.3.0+): plain values
only. Names matching `SECRET_ENV_NAME` (contracts) / `SECRET_NAME` (`scripts/lib/envedit.cjs`;
keep them in step) and generated values can't be read or changed from the Hub. Changing an
address there doesn't change the Hub's domain for the install or FastPanel.
- **Demo data keeps the links** to the church's other products (`KEEP_TABLES` in
`apps/events/backend/scripts/set-demo.js`). Anything that must survive a demo load goes there.
- **Releasing:** branch → merge → tag (`<product>@<version>` here, `v<version>` in events-hub and
crosscode-site) → push, with a CHANGELOG entry, and `npm run check` first. Pushes to c-git often
fail authentication the first time; retry once. A push can also hang waiting on a login prompt
+40 -8
View File
@@ -29,6 +29,12 @@ 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).
**Updated 2026-11-21:** the Church Website (phase 5) is planned in
[WEBSITE-1.0-PLAN.md](./WEBSITE-1.0-PLAN.md): more room to customise each template, one Publish for
the whole site after a clickable preview, Coming soon until then, a brand style and footer shared
with Cross Events (3.7), and no address moves or redirects in 1.0 (§6, §9, §10, §11; decisions
40–48).
---
## Contents
@@ -398,6 +404,11 @@ picks one; its **logo and colours come from the church profile** (`crosscode.chu
release for every church using them. More templates can be added in later releases.
- Every template meets the same bar: tested in Playwright (layout at phone / tablet / desktop,
axe accessibility) and with the §11 SEO checks.
- **Room to make it their own** (decision 40): every section type comes in two or three
**variants** (e.g. the hero as photo, video, collage, split or text only), **style settings**
(font pairing, corners, section colour, spacing, buttons, image treatment, header) and **custom
pages** built from blocks. No free layout or custom CSS. The font pairing and corners are part of
the church's shared brand style (decision 47). Details in WEBSITE-1.0-PLAN §3.
### Admin (`www.church.co.za/admin`, signed in through Accounts)
@@ -407,13 +418,18 @@ picks one; its **logo and colours come from the church profile** (`crosscode.chu
- Pages and sections, About, Leadership, Ministries, Messages, Media library, Contact and
service times, Navigation, Settings (including SEO and search engine verification, §11).
- **Events:** simple events, plus the feed settings (§4) and sync health.
- **Draft → preview → publish**, archive instead of delete, an audit log of who changed what.
- **Draft → preview → publish** (decision 41): every change is a draft; the preview is the whole
site, fully clickable, at phone / tablet / desktop width, and can be shared by link; **one
Publish** puts every change live; every published version is kept and can be restored. Until the
first publish the site shows **Coming soon** (decision 42). Archive instead of delete, an audit
log of who changed what.
- **Roles:** Owner, Admin, Editor, Ministry leader (own ministry only), Viewer.
### Not in the first release
Prayer requests and other forms with personal information (they belong in the App), a member
directory, online giving processing.
Prayer requests and other forms with personal information (they belong in the App; the Contact
page is contact details only, decision 43), a member directory, online giving processing, moving
to the church's own domain with redirects (decision 45).
---
@@ -625,7 +641,7 @@ Planned in [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md). In short:
| 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. [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 confirmed 2026-11-19) | 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 |
| 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. **Planned 2026-11-21:** [WEBSITE-1.0-PLAN.md](./WEBSITE-1.0-PLAN.md) (with contracts 1.15.0, Accounts 1.7.0, Events 3.7.0 for the shared fonts and footer, Hub 2.11.0) | 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 |
@@ -695,7 +711,7 @@ charged **once per church**, not per product.
| Option | Price | What it means |
|--------|-------|---------------|
| **Own domain** | R0 | The church already has a domain (e.g. `hopefamily.co.za`). They, or whoever manages it, add the DNS records we send. We look after the certificates |
| **Cross Code address** | **+R10 / month** | For churches that don't want a domain of their own: `hopefamily.crosscode.co.za`, with the products at `events.hopefamily.crosscode.co.za`, `app.hopefamily.crosscode.co.za` and so on. Can move to a domain of their own at any time (old addresses redirect for 12 months). Trials use this address for free |
| **Cross Code address** | **+R10 / month** | For churches that don't want a domain of their own: `hopefamily.crosscode.co.za`, with the products at `events.hopefamily.crosscode.co.za`, `app.hopefamily.crosscode.co.za` and so on. Can move to a domain of their own (old addresses redirect for 12 months; not before Website 1.0, decision 45). Trials use this address for free |
| **Domain included** | **+R25 / month** | We register a `.co.za` or `.org.za` **in the church's name**, renew it every year and manage the DNS. Other endings (`.com`, `.church`, `.org`) are charged at cost on top. If the church leaves, the domain is transferred to them, free |
### Church Website: one price plus storage
@@ -709,7 +725,8 @@ charged **once per church**, not per product.
Uploads are photos, documents and sermon notes. Sermon audio and video are linked (YouTube,
Spotify, SoundCloud…) rather than uploaded, so most churches never need extra storage. Admins see
how much they've used in the website's settings and get an email at 80%. Storage is counted per
church and reported to the Hub, which bills the add-on.
church and reported to the Hub, which bills the add-on. **When it's full, uploads stop** until more
is bought (decision 48); what's already uploaded keeps showing.
### Church App: on active members
@@ -783,7 +800,8 @@ data from the same `crosscode.event/1` and `crosscode.church/1`. Cross Events mo
When a church moves from the Cross Code address to its own domain (§10), every old URL
**301-redirects** to the same page on the new domain for 12 months, so it keeps its search
ranking.
ranking. **Not in Website 1.0** (decision 45): moving addresses, with a Hub job for all of a
church's products, comes in a later release.
### Checks (in every product's tests)
@@ -859,7 +877,21 @@ ranking.
| 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 |
| 39 | Emergency updates now | An emergency update (reason and 2FA, as before) can run **as soon as possible**, at the agent's next poll (within a minute), as well as at a time at least 15 minutes away. The church is told it's happening now. When the church's Events heartbeat shows an event on now (a session or a one-day event, or check-ins in the last hour), the Hub names it and needs a second "yes". Hub 2.7.0, Events 3.2.0 |
**Added 2026-11-21** (phase 5, [WEBSITE-1.0-PLAN.md](./WEBSITE-1.0-PLAN.md))
| # | Question | Decision |
|---|----------|----------|
| 40 | Enough customisation | Keep **four templates**, each with **section variants**, **style settings** and **custom pages from blocks**, within limits that keep every site designed, accessible and fast. No free layout, custom CSS or custom fonts. More templates can come in 1.x, but not instead of this |
| 41 | Publishing | Every change is a draft. A **fully clickable preview** of the whole site (shareable by a 7-day link) and **one Publish for the whole site**; any pending change can be discarded; every published version is kept and can be restored |
| 42 | Before the first publish | The public address shows a **Coming soon** page from the church profile (logo, service times, contact, links to Events), `noindex` |
| 43 | Contact page | **Contact details only**, no form |
| 44 | Shared vs Website-only content | The church profile (`crosscode.church/1`) gains the **brand style** (font pairing, corners). Leaders, ministries, About, giving and messages are **Website-only for now**; the App plan decides whether they move into the profile |
| 45 | Moving to the church's own domain | **Not in Website 1.0**, and no Hub "Change address" job yet (§10, §11 "Moving addresses") |
| 46 | Messages | **From a YouTube channel or playlist automatically** (latest video as the latest message), or **by hand** with a YouTube or Spotify link |
| 47 | Feeling like one church | The **brand style and footer are shared**: the Website, Accounts' pages and **Cross Events 3.7**'s public pages use the church's fonts, corners and one `ChurchFooter`, with links between the products |
| 48 | Full storage | Admins are emailed at 80% and 100%; at 100% **uploads stop** until more storage is bought (Get more storage asks the Hub; the new limit arrives with the licence) |
## Still open
Nothing. crosscode-site is updated at the end of each phase (§9, "Updating crosscode-site"); the
Nothing for the roadmap. WEBSITE-1.0-PLAN lists its own proposals still to confirm. crosscode-site is updated at the end of each phase (§9, "Updating crosscode-site"); the
Website and App move from "coming later" to their own pages and prices when they ship.
+39 -13
View File
@@ -1,6 +1,6 @@
# Versions — the latest release of everything
Last updated: 2026-11-20. Taken from the git tags, which is what a release is here (branch → merge →
Last updated: 2026-11-21. Taken from the git tags, which is what a release is here (branch → merge →
tag → push, see [HANDOVER.md](./HANDOVER.md) "Releasing"). **Update this file with every release.**
"Released" means tagged and pushed. Whether a release is **deployed** or rolled out is recorded
@@ -10,13 +10,13 @@ separately below; the two often differ.
| What | Repo | Latest | Tag | Released |
|------|------|--------|-----|----------|
| Cross Events | `crosscode-platform` (`apps/events`) | **3.4.0** | `events@3.4.0` | 2026-11-20 |
| Accounts | `crosscode-platform` (`apps/accounts`) | **1.4.0** | `accounts@1.4.0` | 2026-11-20 |
| Server agent | `crosscode-platform` (`apps/agent`) | **1.3.0** | `agent@1.3.0` | 2026-11-20 |
| Contracts | `crosscode-platform` (`packages/contracts`) | **1.12.0** | `contracts@1.12.0` | 2026-11-20 |
| Cross Code Hub | `events-hub` | **2.8.0** | `v2.8.0` | 2026-11-20 |
| Cross Events | `crosscode-platform` (`apps/events`) | **3.6.1** | `events@3.6.1` | 2026-11-20 |
| Accounts | `crosscode-platform` (`apps/accounts`) | **1.6.0** | `accounts@1.6.0` | 2026-11-20 |
| Server agent | `crosscode-platform` (`apps/agent`) | **1.3.1** | `agent@1.3.1` | 2026-11-20 |
| Contracts | `crosscode-platform` (`packages/contracts`) | **1.14.0** | `contracts@1.14.0` | 2026-11-20 |
| Cross Code Hub | `events-hub` | **2.10.0** | `v2.10.0` | 2026-11-20 |
| crosscode.co.za | `crosscode-site` | **1.6.0** | `v1.6.0` | 2026-11-19 |
| `crosscode` script | `crosscode-platform` (`scripts/`) | `main` | none | 2026-11-20 (last change: `crosscode env`) |
| `crosscode` script | `crosscode-platform` (`scripts/`) | `main` | none | 2026-11-20 (last change: Accounts' pre-deploy dumps don't stop a deploy) |
The `crosscode` script has no version: every server's copy (`/opt/crosscode/tools`) pulls `main`
on each run, so merging to `main` and pushing releases it. Its changes are listed in
@@ -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.1.0 (released with Events 3.0.0 and Accounts 1.1.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 5) |
| Website | `apps/website` | 0.0.0 (phase 5, being planned) |
| 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,6 +37,31 @@ need their own tags until something outside this repo depends on them.
## What each latest release was for
- **`crosscode` script (2026-11-20, later):** the database dump made before each Accounts deploy
(`backend/backups/`) no longer stops the next deploy as "added by hand" on Accounts below 1.3.0.
Released by pushing `main`; the next Hub job pulls it.
- **Hub 2.10.0:** every Hub email (job reports, alerts, emails to church admins, notices) laid out
as Events' and Accounts' are. The FastPanel email gives `location ^~ /api/` to paste, and Proxy
done refuses a site whose `/api` files reach the frontend. No migration.
- **Events 3.6.1 (fix):** logo and favicon uploads failed on events-demo: FastPanel's static-file
rule sent every `/api/…` path with a file extension to the frontend. The site now passes those on
to the backend. Also change the FastPanel site (HANDOVER.md, "FastPanel sites"). No migration.
- **Accounts 1.6.0:** a "New sign-in" email (and WhatsApp) after every sign-in, as Cross Events'
own sign-in sends; admins can turn it off. No migration.
- **Events 3.6.0 + Accounts 1.5.0 + contracts 1.14.0:** a nightly people check (Events asks Accounts
about everyone with an account, 500 at a time, `people.check`): out-of-date copies are fixed,
deleted accounts handled as `user.deleted`, and it stops if most people are unknown. Update
Accounts first (Events skips the check with an older one). No migrations; the Hub is unchanged.
- **Events 3.5.0 + contracts 1.13.0 + agent 1.3.1 + Hub 2.9.0:** loading demo data no longer deletes
the Accounts link (on events-demo nobody could sign in); a site in Accounts mode without a link
reconnects at its next heartbeat; the heartbeat says how the site signs in and the last failure,
and the Hub alerts when it isn't linked, is linked wrongly or sign-ins fail. **Agent 1.3.0
reported itself as 1.2.0**, so the Hub refused its .env jobs: install 1.3.1. No migrations.
- **Events 3.4.0 + Accounts 1.4.0 + contracts 1.12.0 + agent 1.3.0 + Hub 2.8.0:** background jobs
switched on and off (and rescheduled) from each site's admin, over the .env (saved in the
database, no migration); Accounts' emails styled as Cross Events'; the Hub shows an install's
@@ -114,8 +139,9 @@ 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.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 |
| crosscode.co.za | not recorded | | Handover: `v1.3.0` was merged and tagged but not deployed |
| Hub | 2.10.0 | 2026-11-20 | |
| Agent on church-server1 | 1.3.1 | 2026-11-20 | |
| Agent on the central server | 1.3.1 | 2026-11-20 | Read-only (decision 35) |
| Cross Events (churches) | 3.6.1 | 2026-11-20 | Every install adopted onto the monorepo and signing in through Accounts |
| Accounts (churches) | 1.6.0 | 2026-11-20 | |
| crosscode.co.za | 1.6.0 | 2026-11-20 | |
+399
View File
@@ -0,0 +1,399 @@
# Church Website 1.0.0 — the church's own public site
Phase **5** of [ROADMAP-v3.md](./ROADMAP-v3.md) (§6, §9, §10, §11; decisions 19, 20, 40–47).
Written 2026-11-21. **All decisions confirmed by Joshua on 2026-11-21** (12 changed: a full
storage stops uploads). Not started.
**What the Website is:** the church's public site at `www.<church's address>` (or
`<church>.crosscode.co.za` on the Cross Code address), plus its admin at `/admin`. Admins sign in
through the church's Accounts. The church picks one of **four templates** and makes it its own with
section layouts, style settings and its own pages. Changes are drafts until an admin **previews**
the whole site and presses **Publish**. Until the first publish, visitors see a **Coming soon**
page. The Website, Cross Events and (later) the App share the church's **brand style** (colours,
logo, fonts, corners) and **footer**, so the three feel like one church.
**Who uses 1.0:** Hope Family Church first, then a second test church on a different template, to
prove it repeats. Then it goes on sale (crosscode-site, ROADMAP §9).
**Done when:**
- `website@1.0.0`, `contracts@1.15.0`, `accounts@1.7.0`, `events@3.7.0` and Hub `v2.11.0` are
tagged; the Hub installs the Website from New install (after Accounts) and lists its releases.
- All four templates pass the same checks (§13) at phone, tablet and desktop sizes: layout, axe, the
§11 SEO checks, and Lighthouse (SEO 100, accessibility 95+, performance 90+).
- An editor can change anything, preview the whole site as a visitor would, share the preview, and
publish it all at once. An earlier version can be restored.
- Switching template keeps all content, and the preview shows the switch before it goes live.
- Cross Events' public pages use the church's fonts and the shared footer.
- Hope Family Church and a second church are live on different templates.
- crosscode-site sells it (ROADMAP §9, "Updating crosscode-site").
## Contents
1. [The shape](#1-the-shape)
2. [Content: shared and Website-only](#2-content-shared-and-website-only)
3. [Templates and customisation](#3-templates-and-customisation)
4. [Drafts, preview and publish](#4-drafts-preview-and-publish)
5. [Coming soon](#5-coming-soon)
6. [Pages](#6-pages)
7. [Messages](#7-messages)
8. [Events](#8-events)
9. [Connected with Events and the App](#9-connected-with-events-and-the-app)
10. [Admin, roles and storage](#10-admin-roles-and-storage)
11. [Hub, licence and servers](#11-hub-licence-and-servers)
12. [What changes in each repo](#12-what-changes-in-each-repo)
13. [Testing](#13-testing)
14. [Releasing and rolling it out](#14-releasing-and-rolling-it-out)
15. [Decisions](#decisions)
16. [Still open](#still-open)
## 1. The shape
`apps/website`, the same stack as Events and Accounts (decision 8 in the roadmap): an **Express +
Prisma + pg-boss backend** (TypeScript) and a **Next.js frontend**, one PostgreSQL database, served
on one address with `/api` to the backend (`location ^~ /api/` in FastPanel, HANDOVER "FastPanel
sites").
```
visitor ─► www.hopefamily.co.za ─► Next.js (server-rendered from the published version, cached)
│ template + section variants + style → HTML
editor ──► /admin (signed in through Accounts, @crosscode/auth-client)
edits the working copy ─► /admin/preview: the whole site from the working copy
Publish ─► a new SiteVersion (snapshot) ─► public pages revalidated
backend: content API (/api/v1/admin/…), public API (/api/v1/site/…), uploads (/api/uploads/…),
event feed (/api/links/v1/*, as Events 2.4), Hub client (protocol v2, product "website"),
jobs (YouTube feed, storage count, sitemap, feed sync)
Accounts ── crosscode.church/1 (name, logo, colours, service times, contact, social, brand style)
Events ──── crosscode.event/1 (the event feed, both directions)
```
- **Rendering:** public pages are server components rendered from the **latest published
version** and cached; Publish revalidates them. Preview renders the same components from the
**working copy**, uncached. Visitors and the preview run the same code, so the preview is exactly
what will go live.
- **Shared packages:** `@crosscode/ui` (branded shell, footer, fonts, form fields, now also the
public site's building blocks), `@crosscode/seo` (meta, JSON-LD, sitemap), `@crosscode/auth-client`
(sign-in), `@crosscode/contracts`.
## 2. Content: shared and Website-only
**The rule:** facts that more than one product shows live in the **church profile**
(`crosscode.church/1`, owned by Accounts). How the Website presents them, and anything only the
Website shows, lives in the **Website's own database**. Leaders, ministries, About, giving and
messages stay **Website-only for now** (decision 5), and can move into the profile when the App needs
them (phase 6–7).
| Shared: `crosscode.church/1` | Website-only |
|---|---|
| Already there: name, short name, logo, icon, colours, campuses, service times, contact, social, links | Template, section variants, style settings other than fonts and corners (§3), homepage order |
| **New in contracts 1.15.0:** `branding.style`: `fontPairing` (an id from the shared list, §3) and `corners` (`sharp` / `soft` / `round`). Optional and additive, so a minor version | Pages, sections and blocks, navigation, custom pages |
| | About (story, mission, vision, values, beliefs), Plan your visit, Leaders, Ministries, Give |
| | Messages and series (§7), simple events (§8), media library, per-page SEO |
| | Drafts, published versions, preview links |
- **Editing shared facts from the Website** (decision 10): the Website's admin shows the profile's
fields where they're used (service times on the Service times screen, the logo on Branding) and
saves them through **Accounts' API** with the admin's token, as ACCOUNTS-1.0-PLAN §7 proposed.
Accounts → Church profile stays the other way in.
- **Shared facts aren't drafts:** Accounts has no draft state, and Events shows the profile too.
A change to a shared fact goes live in every product straight away, and the Website's screens
say so ("Changes here show on all your church's sites at once"). The preview always shows the
current profile.
- **Legal pages:** the privacy notice is Accounts' (the version people agreed to), linked from the
footer. The Website adds its own terms and safeguarding pages from starter text.
- **Content is never tied to a template.** Every section stores its data (validated with a zod
schema per section type) and its chosen variant. Switching template keeps the data, and each
template maps every variant to its nearest look.
## 3. Templates and customisation
Four templates, decided in decision 19: **Heritage, Bold, Community, Clean** (ROADMAP §6). Rather
than adding more templates (more looks, but churches on the same one still look the same), each
template has room to vary in four ways, within limits that keep every site designed, accessible
and fast (decision 1).
**1. Template = structure.** The header and navigation style, the page rhythm, the default homepage
order and which variant each section starts with.
**2. Section variants.** Every section type comes in two or three layouts, and every template can
render every variant in its own style.
| Section | Variants |
|---|---|
| Hero | Photo · Video (muted, with a still for phones and reduced motion) · Collage · Split (image and text) · Text only |
| Service times and location | Panel · Inline strip · With map |
| Welcome / introduction | Text · Image and text · With pastor's photo and quote |
| Ministries | Cards · List · Alternating bands |
| Team / leaders | Faces grid · List · Featured (one large, rest small) |
| Upcoming events | Cards · List · Calendar strip |
| Latest message | Large video · Card · Compact |
| Invitation (call to action) | Banner · Centred · Image background |
**3. Style settings**, on one screen with a live preview:
| Setting | Options | Shared? |
|---|---|---|
| Font pairing | 8 pairings in a shared list (self-hosted, no Google Fonts requests); each template marks 3 as recommended, all 8 work everywhere | **Shared** (Events, Accounts, App) |
| Corners | Sharp · Soft · Round | **Shared** |
| Colours | From the profile (primary, accent); tints and shades built and contrast-checked (WCAG AA, darkened or lightened automatically, with a note why) | **Shared** (already) |
| Section colour | Light · Tinted (the church colour as a soft background) · Mixed with dark bands | Website |
| Spacing | Airy · Compact | Website |
| Buttons | Solid · Outline · Pill | Website |
| Image treatment | Natural · Black and white · Duotone in the church colour | Website |
| Header | Each template's options (e.g. Bold: transparent over the hero, or solid) | Website |
**4. Pages from blocks.** Besides the fixed pages (§6), churches add **custom pages** (Youth camp,
Our history, Kids…) from blocks: text, image and text, gallery, quote, video, FAQ, map, people
cards, call to action, divider. Blocks come in the same variants and follow the style settings.
**Not in 1.0:** free drag-and-drop layout, custom CSS, custom fonts. Each would break phone
layouts, accessibility or speed for some churches, and create support work. More templates can come
in 1.x (they're part of the product, ROADMAP §1 rule 3).
**Photos:** the setup checklist explains what photos work (people, not buildings; landscape for
heroes). The duotone treatment makes uneven photos look consistent. Every image needs alt text.
Uploads are resized into responsive sizes (WebP and JPEG).
## 4. Drafts, preview and publish
Decision 2: **one Publish for the whole site.**
- **The working copy** is the content tables the admin edits. **A published version** is an
immutable snapshot of all of them (`SiteVersion`: JSON, who, when, an optional note). Visitors
always see the latest published version.
- **Pending changes:** the admin header shows "N changes not published". The Publish screen lists
each change (page, section, setting; who made it, when), and any one can be **discarded** (back
to its published value).
- **Preview** (`/admin/preview`, or the Preview button anywhere): the whole site from the working
copy, **fully clickable** (navigation, events, messages, video), with a bar on top: phone /
tablet / desktop width, "Back to editing", the change count and **Publish**. The bar is outside
the page, so the page is laid out exactly as it will be.
- **Share a preview:** a link (`/preview/<token>`) for someone without an account, e.g. the pastor.
It expires after 7 days (or when revoked), shows the working copy as it is when opened, sends
`noindex`, and can't edit or publish.
- **Version history:** every publish is kept. **Restore** copies a version back into the working
copy, so it's previewed and published like any other change; nothing is lost.
- **Two editors at once:** one shared working copy, saved per field. A field changed by someone else
since it was opened warns before it's overwritten. Publish publishes everyone's changes, and the
list shows whose they are.
- **What doesn't wait for Publish** (decision 9): simple events and messages are things that happen
rather than the site's design, so each has its own Publish (and messages found automatically on
YouTube appear on their own, §7). Changes to shared profile facts go live straight away (§2).
- **Template switch:** the new template is a pending change like any other, so the whole site can be
previewed in it before publishing.
- Every publish, discard and restore is in the audit log.
## 5. Coming soon
Decision 3: until the site's **first publish**, the public address shows a **Coming soon** page, not
an empty site.
- From the church profile: logo, name, colours and fonts, service times and address, contact
details, social links, and buttons to the church's Events (and App) when they're linked. A short
"Our new website is on its way" line the admin can change.
- `noindex`, an empty sitemap, `robots.txt` as usual. Real HTTP 200, so the church's details are
still useful to someone who finds the address.
- Signed-in admins see a banner on it: "Your site isn't published yet. Preview it or publish it."
- After the first publish there is no going back to Coming soon in 1.0 (unpublishing isn't needed).
## 6. Pages
As ROADMAP §6, with these changes:
- **Contact:** **contact details only** (decision 4): address with a map, phone, email, WhatsApp,
service times, social links. No contact form (personal information belongs in the App, §6 "Not in
the first release").
- **Give:** information and the church's provider links (SnapScan, Zapper, PayFast page, bank
details as text). No giving processed.
- **Events:** list, detail, calendar, past (§8).
- **Messages:** list, series, detail (§7).
- **Home:** the sections in the template's order; the church can reorder, hide and show them.
- Every page: unique title and description, canonical, Open Graph image (generated from the logo and
colours when the page has none), JSON-LD (`Church` on home and contact, `Event`, `VideoObject`,
`BreadcrumbList`), exactly one `<h1>`, `lang="en-ZA"`. Slug changes get a 301 to the new slug
(within the site; moving domains is decision 6).
## 7. Messages
Decision 7: two ways in, chosen in **Messages → Settings**:
- **From YouTube, automatically.** The admin gives the church's **channel** or a **playlist** (a
playlist is better when the channel has other uploads). A job reads YouTube's public feed
(`youtube.com/feeds/videos.xml?channel_id=…` / `?playlist_id=…`, no API key) every hour, and each
new video becomes a message (title, date, thumbnail, video). Admins can add the speaker, series,
Bible passage and notes afterwards, or hide one. The newest is the home page's **Latest message**.
- **By hand.** Add a message with a **YouTube or Spotify link** (episode or show) and the same
details.
Both can be used together. Embeds load only when clicked (a thumbnail first), use
`youtube-nocookie.com`, and set `VideoObject` (or `PodcastEpisode` for Spotify) JSON-LD. Audio and
video are never uploaded (ROADMAP §10), so they don't count towards storage.
## 8. Events
- **Simple events** made in the Website (title, date and time, place, description, image, an
optional link). Only Cross Events takes registrations and payments (roadmap decision 4).
- **The event feed** as Events 2.4: Settings → Linked products, "Publish my events" and "Show events
from". Events from Cross Events show in the template's event cards and link through to Cross
Events for registering.
- **Imported events** carry `<link rel="canonical">` to the origin's page and aren't in the
Website's sitemap (ROADMAP §11). A source that's down keeps its last events showing.
## 9. Connected with Events and the App
Decision 8. The three products look like one church without looking like each other:
- **Brand style is shared** (§2, §3): the same colours, logo, font pairing and corners in the
Website, in Cross Events' public pages and Accounts' sign-in pages, and later in the App.
- **One footer.** `@crosscode/ui` gets a `ChurchFooter` built from the profile (logo, service times,
address, contact, social, links to the church's Website, Events and App, the privacy notice). The
Website uses it in every template (styled by the template), Events 3.7 and Accounts 1.7 use it on
their public pages.
- **Links between products:** each product's header has a link to the others that exist (from the
profile's `links`): "Events", "Website", later "App".
- **One sign-in and account menu** (already, through Accounts).
- **Events 3.7.0:** public pages (event list and detail, registration, the church's home) use the
shared fonts, corners and footer. Admin and staff screens stay as they are. Nothing else changes.
## 10. Admin, roles and storage
**Admin** (`/admin`, as ROADMAP §6): dashboard with the setup checklist ("Choose your template"
first, previewed with the church's own logo, colours and content, or sample content), pending
changes and recent edits; Template and style; Pages; About; Leaders; Ministries; Messages; Events;
Media library; Contact and service times; Navigation; Settings (SEO, search engine verification,
linked products, email); Version history; Audit log. Each field shows the Google-style snippet
preview and SEO warnings where they apply (ROADMAP §11).
**Roles** (per product, held in the Website; proposed in decision 11):
| Role | Can |
|---|---|
| Owner | Everything, including roles and the licence |
| Admin | Everything but the licence and Owners |
| Editor | Edit everything, preview, share previews, **publish** |
| Ministry leader | Edit their own ministry's page and events; their changes wait for an Editor or above to publish |
| Viewer | See the admin and the preview, change nothing |
Admin roles can require 2FA through Accounts (`acr_values=mfa`, ACCOUNTS-1.0-PLAN decision 8): on by
default for Owner and Admin.
**Storage** (ROADMAP §10): 5 GB of uploads included. Settings shows what's used; admins get an email
at 80% and at 100%. **When it's full, uploads stop** (decision 12) until more storage is bought:
the media library and every upload field say so, with **Get more storage** (Settings → Storage).
That asks the Hub, as Request update does, and the Hub emails Joshua. Once he adds a 5 GB step to the
licence, the new limit reaches the site with the next heartbeat answer (within a minute or so) and
uploads work again. Everything already uploaded keeps showing; only new uploads are refused. The
limit is the licence's (5 GB plus the steps bought), never the site's own setting. An upload is
only freed when neither the working copy nor the last 10 published versions use it.
## 11. Hub, licence and servers
- **Hub protocol v2, product `website`.** The heartbeat's `websiteStatsSchema` is already in the
contracts (pages, messages, events, editors, storage). A Website licence needs the church's
Accounts, installed first (as Events 3.x).
- **Hub 2.11.0:** New install offers the Website; release sync for `website@` tags and
`apps/website/WHATS-NEW.md`; its env template; the Website's price (R99) and the storage add-on
(R20 per extra 5 GB, sent to the site with the licence as its storage limit, and the "Get more storage"
request with its email to Joshua) in `frontend/src/lib/tiers.ts` and `backend/src/utils/billing/tiers.js`, in
step with crosscode-site; the FastPanel email for `www.` (and the bare domain sent to `www.` with a
301, for an own domain) or `<church>.crosscode.co.za`.
- **`crosscode`:** `scripts/products/website.sh` with the same hooks as Events and Accounts (`website`
is already in `PRODUCT_ORDER`), `website.env.template.json`, `crosscode add <church> website`. The
env template in three places, plus any value rules (HANDOVER, "A new .env variable").
- **Agent:** none expected. The job schemas already take `website` (`releaseTagSchema`, `PRODUCTS`).
The frp port list gets the Website's two ports.
- **Accounts 1.7.0:** `branding.style` on the church profile (and Accounts → Church profile), the
Website as a client through Connect (as Events), the profile API allowing the Website's admins to
save, the shared fonts and footer on its pages.
- **Uninstall:** the church export (`crosscode.church-export/1`) gets a `website` section (content,
versions' notes, messages, events) and the uploaded media, as Events' export does its uploads.
- **Demo church:** `npm run demo` loads a fictional church (fictional people and photos only) into
each template, for the crosscode-site screenshots and the Hub's demo sites.
## 12. What changes in each repo
| Repo | Change | Version |
|------|--------|---------|
| `crosscode-platform` `apps/website` | New (§1–§11), with `CHANGELOG.md`, `WHATS-NEW.md`, `env.template.json`, e2e, demo data | `website@1.0.0` |
| `crosscode-platform` `packages/contracts` | `branding.style` (`fontPairing`, `corners`) on `crosscode.church/1`, the font pairing ids, a `website` part of the church export | `contracts@1.15.0` |
| `crosscode-platform` `packages/ui` | Fonts (self-hosted), the theme from the profile (colours, fonts, corners as CSS variables), `ChurchFooter`, links between products, the public site's building blocks | workspace |
| `crosscode-platform` `packages/seo` | `Church`, `VideoObject`, `PodcastEpisode`, `BreadcrumbList` builders, the generated share image | workspace |
| `crosscode-platform` `apps/accounts` | `branding.style` in the church profile, the shared fonts and footer, the Website's admins saving the profile | `accounts@1.7.0` |
| `crosscode-platform` `apps/events` | Public pages with the shared fonts, corners and footer | `events@3.7.0` |
| `crosscode-platform` `scripts/` | `products/website.sh`, `website.env.template.json`, bats tests | — |
| `events-hub` | Website in New install, its releases, env template, prices and storage add-on, FastPanel email | Hub `v2.11.0` |
| `crosscode-site` | Church Website on sale (ROADMAP §9): its page, prices, a page per template, screenshots of the demo church, FAQ, `SoftwareApplication` JSON-LD | `v1.7.0` |
## 13. Testing
- **Unit (Jest):** section schemas and variants, the palette builder and contrast fixes, publish /
discard / restore, pending change lists, preview tokens (expiry, revoke, no edit rights), roles
(a Ministry leader can't publish or edit another ministry), the YouTube feed parser (channel,
playlist, duplicates, a removed video), storage counting, uploads refused when full (and allowed again when the licence's limit goes
up), uploads kept by older versions.
- **Playwright, every template at phone / tablet / desktop:** the demo church's pages look right
(screenshots compared), axe has no violations, the §11 checks (title, description, canonical,
`og:image`, one `<h1>`, JSON-LD parses, sitemap, `robots.txt`, `noindex` where it should be).
- **Playwright, the flows:** Coming soon before the first publish; edit → preview (click through
the site) → publish → the public site changes; discard one change; a shared preview link works
signed out and stops after revoking; restore an older version; switch template in preview and
back without losing anything; sign in from a deep admin page and land back on it (through 2FA).
- **Lighthouse (mobile):** home, an event and a message in each template: SEO 100,
accessibility 95+, performance 90+.
- **Events 3.7:** the e2e suite still passes, and its public pages show the church's fonts and the
shared footer.
- **The release checks** (ROADMAP §9) for the Website, and the **VM test**: install the Website
next to Accounts and Events through the agent, update it, uninstall it with its export.
## 14. Releasing and rolling it out
1. `contracts@1.15.0`, then `accounts@1.7.0` (the profile's brand style), then `events@3.7.0`.
2. Hub `v2.11.0` (vendored contracts 1.15.0) deployed.
3. `website@1.0.0` tagged after the e2e, Lighthouse and VM runs.
4. **Hope Family Church:** Accounts 1.7.0 and Events 3.7.0 first, then New install → Website. The
site shows Coming soon while the church builds it, and goes live with its first publish.
5. **A second test church** on a different template.
6. crosscode-site `v1.7.0`: the Website on sale.
## Decisions
Made by Joshua on 2026-11-21:
1. **Customisation within limits:** four templates, each with section variants, style settings and
custom pages from blocks (§3). No free layout, custom CSS or custom fonts. More templates later,
not instead.
2. **One Publish for the whole site,** after a fully clickable preview (§4), with a shareable preview
link and version history.
3. **Coming soon** until the first publish (§5).
4. **Contact page: details only,** no form (§6).
5. **Leaders, ministries, About, giving and messages are Website-only** for now (§2). Only the brand
style (font pairing, corners) is added to the shared profile.
6. **No address move or redirects in 1.0,** and no Hub "Change address" job yet. Moving to the
church's own domain (ROADMAP §10, §11 "Moving addresses") comes later.
7. **Messages from a YouTube channel or playlist automatically, or by hand with a YouTube or
Spotify link** (§7).
8. **The three products feel connected:** shared brand style and footer, and **Events 3.7** uses the
shared fonts and footer on its public pages (§9).
Proposed and confirmed on 2026-11-21 (12 changed):
9. **Simple events and messages publish on their own,** not with the site's Publish; YouTube messages
appear automatically (§4, §7).
10. **The Website's admin edits shared profile facts through Accounts' API,** and they go live
straight away (§2). Answers ACCOUNTS-1.0-PLAN's "Still open".
11. **Editors can publish; Ministry leaders' changes wait** for an Editor or above (§10).
12. **A full storage stops uploads** until more is bought (admins emailed at 80% and 100%; "Get more
storage" asks the Hub; §10). Changed from the proposal, which let uploads carry on and billed
afterwards.
13. **Fonts are self-hosted** (no Google Fonts requests, for POPIA and speed), from a shared list of 8
pairings (§3).
14. **Coming soon is a real page (HTTP 200) with `noindex`,** not a 503 (§5).
## Still open
- The 8 font pairings and the exact variants per template: settled with the template designs, early
in the build.
- Whether the App (phase 6) moves leaders, ministries and giving into `crosscode.church/1` or reads
them from the Website. Decide with the App plan.
+6 -6
View File
@@ -46,7 +46,7 @@
},
"apps/accounts/backend": {
"name": "@crosscode/accounts-backend",
"version": "1.4.0",
"version": "1.6.0",
"hasInstallScript": true,
"dependencies": {
"@crosscode/contracts": "*",
@@ -83,7 +83,7 @@
},
"apps/accounts/frontend": {
"name": "@crosscode/accounts-frontend",
"version": "1.4.0",
"version": "1.6.0",
"dependencies": {
"@crosscode/contracts": "*",
"@crosscode/ui": "*",
@@ -109,7 +109,7 @@
},
"apps/agent": {
"name": "@crosscode/agent",
"version": "1.3.0",
"version": "1.3.1",
"license": "UNLICENSED",
"dependencies": {
"@crosscode/contracts": "*",
@@ -128,7 +128,7 @@
},
"apps/events/backend": {
"name": "@crosscode/events-backend",
"version": "3.4.0",
"version": "3.6.1",
"hasInstallScript": true,
"dependencies": {
"@cj-tech-master/excelts": "^10.2.0",
@@ -178,7 +178,7 @@
},
"apps/events/frontend": {
"name": "@crosscode/events-frontend",
"version": "3.4.0",
"version": "3.6.1",
"dependencies": {
"@crosscode/contracts": "*",
"@crosscode/seo": "*",
@@ -21276,7 +21276,7 @@
},
"packages/contracts": {
"name": "@crosscode/contracts",
"version": "1.12.0",
"version": "1.14.0",
"license": "UNLICENSED",
"dependencies": {
"zod": "^4.6.7"
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/contracts",
"version": "1.12.0",
"version": "1.14.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",
@@ -0,0 +1,32 @@
{
"schema": "crosscode.identity-request/1",
"people": [
{
"sub": "6b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e",
"status": "active",
"profile": {
"name": "Thandi Mokoena",
"given_name": "Thandi",
"family_name": "Mokoena",
"email": "thandi@example.com",
"email_verified": true,
"phone_number": "+27821234567",
"phone_number_verified": false,
"news_consent": {
"email": true,
"whatsapp": false
}
}
},
{
"sub": "7c3d4e5f-6a7b-4c8d-8e9f-1a2b3c4d5e6f",
"status": "deleted",
"profile": null
},
{
"sub": "8d4e5f6a-7b8c-4d9e-9f0a-2b3c4d5e6f7a",
"status": "unknown",
"profile": null
}
]
}
@@ -0,0 +1,11 @@
{
"schema": "crosscode.identity-request/1",
"actor": null,
"requestId": "9e4f5a6b-7c8d-4e9f-8a0b-2c3d4e5f6a7b",
"type": "people.check",
"subs": [
"6b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e",
"7c3d4e5f-6a7b-4c8d-8e9f-1a2b3c4d5e6f",
"8d4e5f6a-7b8c-4d9e-9f0a-2b3c4d5e6f7a"
]
}
@@ -324,6 +324,77 @@
"eventsNow",
"checkInsLastHour"
]
},
"signIn": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"local",
"accounts"
]
},
"accounts": {
"anyOf": [
{
"type": "object",
"properties": {
"installId": {
"type": "string",
"maxLength": 100
},
"url": {
"type": "string",
"maxLength": 500
}
},
"required": [
"installId",
"url"
]
},
{
"type": "null"
}
]
},
"lastError": {
"anyOf": [
{
"type": "object",
"properties": {
"at": {
"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))$"
},
"code": {
"type": "string",
"maxLength": 60
},
"message": {
"type": "string",
"maxLength": 500
}
},
"required": [
"at",
"code",
"message"
]
},
{
"type": "null"
}
]
}
},
"required": [
"mode",
"accounts",
"lastError"
]
}
},
"required": [
@@ -856,6 +856,53 @@
"subs"
]
},
{
"type": "object",
"properties": {
"schema": {
"type": "string",
"const": "crosscode.identity-request/1"
},
"requestId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"actor": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
]
},
"type": {
"type": "string",
"const": "people.check"
},
"subs": {
"minItems": 1,
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"required": [
"schema",
"requestId",
"actor",
"type",
"subs"
]
},
{
"type": "object",
"properties": {
@@ -0,0 +1,130 @@
{
"$id": "https://c-git.crosscode.co.za/joshua/crosscode-platform/raw/branch/main/packages/contracts/schemas/people-check-reply.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"schema": {
"type": "string",
"const": "crosscode.identity-request/1"
},
"people": {
"maxItems": 500,
"type": "array",
"items": {
"type": "object",
"properties": {
"sub": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"status": {
"type": "string",
"enum": [
"active",
"deactivated",
"deleted",
"unknown"
]
},
"profile": {
"anyOf": [
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"given_name": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"family_name": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
]
},
"email": {
"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,}$"
},
"email_verified": {
"type": "boolean"
},
"phone_number": {
"anyOf": [
{
"type": "string",
"pattern": "^\\+[1-9]\\d{6,14}$"
},
{
"type": "null"
}
]
},
"phone_number_verified": {
"type": "boolean"
},
"news_consent": {
"type": "object",
"properties": {
"email": {
"type": "boolean"
},
"whatsapp": {
"type": "boolean"
}
},
"required": [
"email",
"whatsapp"
]
}
},
"required": [
"name",
"given_name",
"family_name",
"email",
"email_verified",
"phone_number",
"phone_number_verified",
"news_consent"
]
},
{
"type": "null"
}
]
}
},
"required": [
"sub",
"status",
"profile"
]
}
}
},
"required": [
"schema",
"people"
]
}
@@ -67,6 +67,7 @@ function contracts(c) {
"messaging-status-reply": c.messagingStatusReplySchema,
"messaging-test-reply": c.messagingTestReplySchema,
"people-remove-demo-reply": c.peopleRemoveDemoReplySchema,
"people-check-reply": c.peopleCheckReplySchema,
};
}
+12
View File
@@ -196,6 +196,18 @@ export const eventsStatsSchema = z.object({
* 30 minutes), and tickets checked in during the last hour. Optional: older installs don't send it.
*/
live: z.object({ eventsNow: count, checkInsLastHour: count }).optional(),
/**
* 1.13.0: how people sign in, so the Hub can flag a site that can't. `mode`: Cross Events' own
* sign-in or the church's Accounts; `accounts`: the Accounts install it's linked to (null: not
* linked, which with mode `accounts` means nobody can sign in); `lastError`: the last time
* starting or finishing a sign-in failed (cleared by the next one that works). Optional: older
* installs don't send it.
*/
signIn: z.object({
mode: z.enum(["local", "accounts"]),
accounts: z.object({ installId: z.string().max(100), url: z.string().max(500) }).nullable(),
lastError: z.object({ at: dateTimeSchema, code: z.string().max(60), message: z.string().max(500) }).nullable(),
}).optional(),
});
/** Church Website. `storage` is what the extra-storage add-on is billed on (ROADMAP-v3 §10). */
+29 -2
View File
@@ -1,6 +1,6 @@
import { z } from "zod";
import { dateTimeSchema, emailSchema, idSchema, phoneSchema } from "./common";
import { twoFactorMethodSchema } from "./identity";
import { profileSchema, twoFactorMethodSchema } from "./identity";
import { schemaName } from "./schema-name";
/**
@@ -171,6 +171,33 @@ export const peopleRemoveDemoSchema = base.extend({
subs: z.array(idSchema).max(REMOVE_DEMO_MAX),
});
/** Subs per `people.check`. */
export const PEOPLE_CHECK_MAX = 500;
/**
* 1.14.0: the product's regular check that its copies of people are current (Cross Events does it
* nightly), in case a `user.updated` or `user.deleted` never arrived. Accounts answers for each sub
* with the current profile, or says the account was deleted, or that it doesn't know the person
* through this product (`unknown`; never a reason to delete anything).
*/
export const peopleCheckSchema = base.extend({
type: z.literal("people.check"),
subs: z.array(idSchema).min(1).max(PEOPLE_CHECK_MAX),
});
export const PEOPLE_CHECK_STATUSES = ["active", "deactivated", "deleted", "unknown"] as const;
export const peopleCheckReplySchema = z.object({
schema: z.literal(IDENTITY_REQUEST_SCHEMA),
people: z.array(z.object({
sub: idSchema,
status: z.enum(PEOPLE_CHECK_STATUSES),
/** The profile as `user.updated` sends it; null for `deleted` and `unknown`. */
profile: profileSchema.nullable(),
})).max(PEOPLE_CHECK_MAX),
});
export type PeopleCheckReply = z.infer<typeof peopleCheckReplySchema>;
// ─── messaging.* (contracts 1.9.0) ───────────────────────────────────────────
/** SMTP settings as Cross Events and Accounts both keep them (`smtp_*`). `pass` sealed; null: keep the saved one. */
@@ -216,7 +243,7 @@ export const churchBrandingSchema = base.extend({ type: z.literal("church.brandi
export const identityRequestSchema = z.discriminatedUnion("type", [
importBeginSchema, importBatchSchema, importFinishSchema, importAbortSchema,
peopleEnsureSchema, peopleUpdateSchema, peopleResetTwoFactorSchema, peopleUnlockSchema, peopleSetActiveSchema, peopleNewsOffSchema,
peopleRemoveDemoSchema, messagingStatusSchema, messagingTestSchema, messagingSetSchema, churchBrandingSchema,
peopleRemoveDemoSchema, peopleCheckSchema, messagingStatusSchema, messagingTestSchema, messagingSetSchema, churchBrandingSchema,
]);
export type IdentityRequest = z.infer<typeof identityRequestSchema>;
export type IdentityRequestType = IdentityRequest["type"];
@@ -50,6 +50,8 @@ const SAMPLE_SCHEMA: Record<string, string> = {
"messaging-test-reply.json": "messaging-test-reply",
"people-remove-demo.json": "identity-request",
"people-remove-demo-reply.json": "people-remove-demo-reply",
"people-check.json": "identity-request",
"people-check-reply.json": "people-check-reply",
};
describe("JSON Schema (schemas/)", () => {
+3 -1
View File
@@ -17,7 +17,7 @@ import {
importBatchReplySchema,
peopleEnsureReplySchema,
messagingTestReplySchema,
peopleRemoveDemoReplySchema,
peopleRemoveDemoReplySchema, peopleCheckReplySchema,
userDeletedReplySchema,
userExportReplySchema,
} from "../src";
@@ -59,6 +59,8 @@ const SCHEMAS: Record<string, z.ZodType> = {
"messaging-test-reply.json": messagingTestReplySchema,
"people-remove-demo.json": identityRequestSchema,
"people-remove-demo-reply.json": peopleRemoveDemoReplySchema,
"people-check.json": identityRequestSchema,
"people-check-reply.json": peopleCheckReplySchema,
};
describe("samples", () => {
+1 -1
View File
@@ -2,7 +2,7 @@
Shared UI for the products a church's members see: the branded shell, cards, buttons, form fields
and notices. First used by Accounts' sign-in and account pages (phase 3); the Church Website and
App build on it (phases 4 and 6).
App build on it (phases 5 and 6).
- Plain React + Tailwind, no runtime dependencies. Apps compile the source
(`transpilePackages: ["@crosscode/ui"]` in `next.config.ts`) and add
+18 -4
View File
@@ -355,10 +355,24 @@ node_major() { node -p 'process.versions.node.split(".")[0]' 2>/dev/null || echo
# Files changed or added by hand in a checkout (ignored files such as .env, uploads, backups and
# the install's ecosystem.config.js never count). The PM2 configs this script makes for each
# install never count either, also in checkouts of releases that don't ignore them yet (Accounts
# 1.0–1.1 has no .gitignore for its ecosystem.config.cjs).
# 1.0–1.1 has no .gitignore for its ecosystem.config.cjs). Nor do the files in the folders this
# script writes into (Accounts below 1.3.0 doesn't ignore the database dumps made before each
# deploy, so the dump would stop the very deploy that brings the .gitignore).
CROSSCODE_OWN_FILES=(apps/events/ecosystem.config.js apps/accounts/ecosystem.config.cjs)
CROSSCODE_OWN_DIRS=(apps/accounts/backend/backups/)
local_changes() {
git_in "$1" status --porcelain --untracked-files=all | awk -v own="${CROSSCODE_OWN_FILES[*]}" '
BEGIN { n = split(own, f, " "); for (i = 1; i <= n; i++) skip[f[i]] = 1 }
!(substr($0, 1, 2) == "??" && substr($0, 4) in skip)'
git_in "$1" status --porcelain --untracked-files=all |
awk -v own="${CROSSCODE_OWN_FILES[*]}" -v dirs="${CROSSCODE_OWN_DIRS[*]}" '
BEGIN {
n = split(own, f, " "); for (i = 1; i <= n; i++) skip[f[i]] = 1
m = split(dirs, d, " ")
}
{
if (substr($0, 1, 2) == "??") {
path = substr($0, 4)
if (path in skip) next
for (i = 1; i <= m; i++) if (index(path, d[i]) == 1) next
}
print
}'
}
+10 -7
View File
@@ -517,15 +517,18 @@ server {
server_name $domain;
client_max_body_size 25m;
# For the backend locations below ("location /" sets its own).
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
# The API, uploaded files, health and API docs go to the backend; everything else to the site.
# (From Events 2.2.0 everything is under /api; the other paths are for older releases.)
location ~ ^/(api|uploads|health|docs)(/|\$) {
proxy_pass http://127.0.0.1:$api;
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
}
# ^~ so a regex location added later (e.g. caching *.png) can't send /api/…/logo.png to the site.
location ^~ /api/ { proxy_pass http://127.0.0.1:$api; }
location ^~ /uploads/ { proxy_pass http://127.0.0.1:$api; }
location ~ ^/(api|uploads|health|docs)(/|\$) { proxy_pass http://127.0.0.1:$api; }
location / {
proxy_pass http://127.0.0.1:$web;
proxy_http_version 1.1;
+14
View File
@@ -159,6 +159,20 @@ cc() { bash "$CROSSCODE_HOME/crosscode" "$@"; }
[[ "$output" == *"apps/accounts/notes.txt"* ]]
}
@test "the database dumps crosscode makes don't count as changes by hand" {
# Accounts below 1.3.0 has no .gitignore for backend/backups/.
mkdir -p "$CROSSCODE_SITES/hope/events/apps/accounts/backend/backups"
echo "dump" > "$CROSSCODE_SITES/hope/events/apps/accounts/backend/backups/accounts-20261119-221205.sql.gz"
run cc deploy hope events --version events@2.2.1 --check
[ "$status" -eq 0 ]
# A file merely named like the folder still counts.
echo "notes" > "$CROSSCODE_SITES/hope/events/apps/accounts/backend/backups.txt"
run cc deploy hope events --version events@2.2.1 --check
[ "$status" -eq 1 ]
[[ "$output" == *"apps/accounts/backend/backups.txt"* ]]
[[ "$output" != *"accounts-20261119-221205.sql.gz"* ]]
}
@test "--allow-local-changes deploys with a file added by hand" {
echo "notes" > "$CROSSCODE_SITES/hope/events/apps/events/notes.txt"
run cc deploy hope events --version events@2.2.1