Events: env template, church export, register with HUB_LICENCE_KEY

- apps/events/env.template.json (crosscode.env-template/1): every .env
  variable with its layer (server, defaults, install, generated).
- scripts/export-church.ts writes crosscode.church-export/1 (export-only
  references, no internal ids or secrets) for crosscode export.
- Installs made from the Hub register by themselves on first start when
  HUB_LICENCE_KEY is set (retries while the Hub is unreachable).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-17 12:06:01 +02:00
co-authored by Claude Opus 5.5
parent 90a98a4306
commit 350ab9f4e8
7 changed files with 378 additions and 2 deletions
@@ -0,0 +1,57 @@
/**
* Writes the church's data as crosscode.church-export/1 (src/services/churchExport.ts) into a
* folder: export.json and README.txt. `crosscode export` runs it, copies public/uploads into the
* folder's uploads/ and zips it. Run from backend/: npx tsx scripts/export-church.ts --out-dir <dir>
*/
import 'dotenv/config';
import fs from 'node:fs';
import path from 'node:path';
import { buildExport, readExportInput } from '../src/services/churchExport';
import { prisma } from '../src/v2/legacy';
const README = `Your church's data from Cross Events
=====================================
export.json holds your events, people, registrations, payments, check-ins and volunteer
rosters, in plain terms (crosscode.church-export/1). Records refer to each other with short
references made for this file: "p12" is a person, "e3" an event, "t5" a ticket type and "r40"
a registration. They mean nothing outside this file.
people everyone with an account: name, email, phone, role, what they agreed to
events each event with its sessions and ticket types (prices in cents)
registrations who registered for what, the people attending, their answers to the form
payments amounts in cents, how and when they were paid, the provider's reference
checkIns who was checked in to which event, and when
rosters volunteer roles and who served
settings the site's name, contact details and branding
files uploaded files, in the uploads/ folder next to this file
Not included: passwords, security codes and logs about how the site ran.
`;
function listFiles(dir: string, base = dir): { path: string; bytes: number }[] {
if (!fs.existsSync(dir)) return [];
return fs.readdirSync(dir, { withFileTypes: true }).flatMap(d => {
const full = path.join(dir, d.name);
if (d.isDirectory()) return d.name === 'tickets-temp' ? [] : listFiles(full, base);
if (!d.isFile() || !/^[A-Za-z0-9._-]+$/.test(d.name)) return [];
return [{ path: `uploads/${path.relative(base, full).split(path.sep).join('/')}`, bytes: fs.statSync(full).size }];
});
}
async function main() {
const i = process.argv.indexOf('--out-dir');
const out = i > 0 ? process.argv[i + 1] : '';
if (!out) throw new Error('Usage: export-church.ts --out-dir <dir>');
fs.mkdirSync(out, { recursive: true });
const { version } = require('../package.json') as { version: string };
const data = buildExport(await readExportInput(version));
data.files = listFiles(path.join(__dirname, '..', 'public', 'uploads'));
fs.writeFileSync(path.join(out, 'export.json'), `${JSON.stringify(data, null, 2)}\n`);
fs.writeFileSync(path.join(out, 'README.txt'), README);
console.log(`export.json: ${data.people.length} people, ${data.events.length} events, ${data.registrations.length} registrations, ${data.files.length} files`);
}
main()
.catch(e => { console.error(`Export failed: ${(e as Error).message}`); process.exitCode = 1; })
.finally(() => prisma.$disconnect().catch(() => {}));
+3 -1
View File
@@ -396,7 +396,9 @@ app.listen(PORT, () => {
// backup, temp cleanup) run on the pg-boss job queue — see src/jobs/index.js.
require('./jobs').startJobs().catch(e => console.warn('[jobs] Not started:', e?.message || e));
// Check in with the Hub 30 s after starting, so the licence is fresh without waiting 15 minutes.
// Installs made from the Hub register by themselves (HUB_LICENCE_KEY), then check in with the
// Hub 30 s after starting, so the licence is fresh without waiting 15 minutes.
require('./hub/client').connectFromEnv().catch(() => {});
require('./hub/client').heartbeatSoon();
// Scheduled emails worker (polling)
+30 -1
View File
@@ -216,4 +216,33 @@ function heartbeatSoon(delayMs = 30 * 1000) {
soonTimer.unref?.();
}
module.exports = { PROTOCOL_VERSION, HUB_KEYS, hubUrl, HubError, signedPost, connect, heartbeat, heartbeatSoon, requestUpdate, cancelUpdateRequest, snoozeUpdate };
/**
* Installs made from the Hub (crosscode install, docs/AGENT-1.0-PLAN.md §7) have the licence key in
* HUB_LICENCE_KEY: the site registers by itself on its first start, instead of in /setup. Does
* nothing once registered, or without the key. Retries a few times (the Hub may be briefly
* unreachable); a refused key is logged and left for /setup. Never throws.
*/
async function connectFromEnv({ attempts = 5, delayMs = 60 * 1000, sleep = ms => new Promise(r => setTimeout(r, ms).unref?.()) } = {}) {
const key = String(process.env.HUB_LICENCE_KEY || '').trim();
if (!key) return { connected: false, reason: 'no_key' };
for (let i = 1; i <= attempts; i++) {
try {
const stored = await read(['hub_install_id']);
if (stored.hub_install_id) return { connected: false, reason: 'already' };
const name = String(process.env.HUB_ADMIN_NAME || '').trim() || null;
const email = String(process.env.HUB_ADMIN_EMAIL || '').trim() || null;
await connect(key, name || email ? { name, email } : null);
console.log('[hub] Registered with the Hub using HUB_LICENCE_KEY.');
return { connected: true };
} catch (e) {
const status = e?.statusCode || 0;
console.warn(`[hub] Registering with HUB_LICENCE_KEY failed (attempt ${i} of ${attempts}):`, e?.message || e);
// The Hub said no (unknown, revoked or in-use key): retrying won't help.
if (status >= 400 && status < 500) return { connected: false, reason: e?.code || 'refused' };
if (i < attempts) await sleep(delayMs);
}
}
return { connected: false, reason: 'unreachable' };
}
module.exports = { PROTOCOL_VERSION, HUB_KEYS, hubUrl, HubError, signedPost, connect, connectFromEnv, heartbeat, heartbeatSoon, requestUpdate, cancelUpdateRequest, snoozeUpdate };
@@ -0,0 +1,142 @@
/**
* The church's data when it leaves: crosscode.church-export/1 (packages/contracts,
* docs/AGENT-1.0-PLAN.md §9). Plain terms and our own field names: no tables, Prisma models or
* internal ids. Records point at each other with references made for the export (p1, e1, t1, r1)
* that mean nothing outside the file. `crosscode export` runs scripts/export-church.ts, which
* writes this as export.json next to the uploads.
*
* Not included: passwords, 2FA secrets, tokens, provider keys, audit and access logs (they're
* about the site's running, not the church's data), and analytics.
*/
import { prisma } from '../v2/legacy';
type Row = Record<string, any>; // eslint-disable-line @typescript-eslint/no-explicit-any -- rows from Prisma
const iso = (d: unknown): string | null => (d instanceof Date ? d.toISOString() : d ? new Date(String(d)).toISOString() : null);
const cents = (rand: unknown): number => Math.round(Number(rand || 0) * 100);
/** Hands out p1, p2 … for ids, in the order they're first seen. */
class Refs {
private map = new Map<string, string>();
constructor(private prefix: string) {}
of(id: string | null | undefined): string | null {
if (!id) return null;
let r = this.map.get(id);
if (!r) {
r = `${this.prefix}${this.map.size + 1}`;
this.map.set(id, r);
}
return r;
}
has(id: string | null | undefined): boolean {
return !!id && this.map.has(id);
}
}
/** Settings worth giving back (never secrets: those are stored encrypted under other keys). */
export const EXPORT_SETTING_KEYS = [
'org_name', 'org_tagline', 'org_email', 'org_phone', 'org_address', 'org_website', 'brand_primary_color', 'logo_url', 'favicon_url',
'app_name', 'timezone', 'currency', 'privacy_contact_email',
];
export type ExportInput = {
users: Row[]; events: Row[]; registrations: Row[]; payments: Row[]; usages: Row[]; slots: Row[]; roles: Row[];
settings: Row[]; fields: Row[]; version: string;
};
/** Builds the export from rows (kept separate from the database reads, so it can be tested). */
export function buildExport(input: ExportInput, now = new Date()) {
const people = new Refs('p');
const events = new Refs('e');
const tickets = new Refs('t');
const regs = new Refs('r');
const labels = new Map(input.fields.map(f => [f.id, String(f.label)]));
const settings = Object.fromEntries(input.settings.filter(s => EXPORT_SETTING_KEYS.includes(s.key)).map(s => [s.key, String(s.value)]));
const out = {
schema: 'crosscode.church-export/1' as const,
exportedAt: now.toISOString(),
product: 'events' as const,
productVersion: input.version,
church: { name: settings.org_name || 'Church', timezone: process.env.APP_TIMEZONE || 'Africa/Johannesburg' },
people: input.users.map(u => ({
ref: people.of(u.id)!,
name: String(u.name || ''),
email: u.email || null,
phone: u.phoneNumber || null,
role: String(u.role || 'user'),
createdAt: iso(u.createdAt),
consent: { email: typeof u.newsEmail === 'boolean' ? u.newsEmail : null, whatsapp: typeof u.newsWhatsApp === 'boolean' ? u.newsWhatsApp : null, privacyNoticeAcceptedAt: null },
})),
events: input.events.map(e => ({
ref: events.of(e.id)!,
title: String(e.title || ''),
description: e.description || null,
startsAt: iso(e.startDate),
endsAt: iso(e.endDate),
location: e.location || null,
sessions: (e.sessions || []).map((s: Row) => ({ label: s.label || null, startsAt: iso(s.startsAt), endsAt: iso(s.endsAt) })),
ticketTypes: (e.eventOptions || []).map((o: Row) => ({ ref: tickets.of(o.id)!, name: String(o.name || ''), priceCents: cents(o.price), currency: 'ZAR' })),
capacity: null as number | null,
published: !!e.isActive && !e.isHidden,
})),
registrations: input.registrations.filter(r => events.has(r.eventId)).map(r => ({
ref: regs.of(r.id)!,
eventRef: events.of(r.eventId)!,
personRef: people.has(r.userId) ? people.of(r.userId) : null,
status: String(r.status),
createdAt: iso(r.createdAt),
attendees: (r.attendees || []).map((a: Row) => ({
name: String(a.name || ''),
email: a.email || null,
ticketTypeRef: tickets.has(a.eventOptionId) ? tickets.of(a.eventOptionId) : null,
checkedInAt: iso(a.ticket?.usages?.[0]?.scannedAt),
})),
answers: (r.formResponses || []).flatMap((fr: Row) => (fr.answers || []).map((x: Row) => ({ question: labels.get(x.fieldId) || 'Question', answer: String(x.value ?? '') }))),
})),
payments: input.payments.map(p => ({
registrationRef: regs.has(p.registrationId) ? regs.of(p.registrationId) : null,
amountCents: cents(p.amount),
currency: 'ZAR',
method: String(p.method || 'unknown'),
status: String(p.status || 'completed'),
paidAt: iso(p.createdAt),
reference: p.externalId || null,
})),
checkIns: input.usages.filter(u => events.has(u.ticket?.eventId)).map(u => ({
eventRef: events.of(u.ticket.eventId)!,
personRef: people.has(u.ticket?.holderUserId || u.ticket?.userId) ? people.of(u.ticket.holderUserId || u.ticket.userId) : null,
name: u.ticket?.attendee?.name || null,
at: iso(u.scannedAt),
})),
rosters: input.slots.map(s => {
const role = input.roles.find(r => r.id === s.roleId);
return {
eventRef: role && events.has(role.eventId) ? events.of(role.eventId) : null,
role: String(role?.name || 'Volunteer'),
personRef: people.has(s.userId) ? people.of(s.userId) : null,
startsAt: iso(role?.startsAt),
endsAt: iso(role?.endsAt),
};
}),
settings,
files: [] as { path: string; bytes: number }[],
};
return out;
}
/** Reads everything the export needs. */
export async function readExportInput(version: string): Promise<ExportInput> {
const [users, events, registrations, payments, usages, slots, roles, settings, fields] = await Promise.all([
prisma.user.findMany({ orderBy: { createdAt: 'asc' } }),
prisma.event.findMany({ orderBy: { startDate: 'asc' }, include: { sessions: { orderBy: { order: 'asc' } }, eventOptions: true } }),
prisma.registration.findMany({ orderBy: { createdAt: 'asc' }, include: { attendees: { orderBy: { order: 'asc' }, include: { ticket: { include: { usages: { orderBy: { scannedAt: 'asc' }, take: 1 } } } } }, formResponses: { include: { answers: true } } } }),
prisma.payment.findMany({ orderBy: { createdAt: 'asc' } }),
prisma.ticketUsage.findMany({ orderBy: { scannedAt: 'asc' }, include: { ticket: { include: { attendee: true } } } }),
prisma.volunteerSlot.findMany(),
prisma.servingRole.findMany(),
prisma.appSetting.findMany(),
prisma.eventFormField.findMany(),
]);
return { users, events, registrations, payments, usages, slots, roles, settings, fields, version } as ExportInput;
}
@@ -0,0 +1,56 @@
// The church's data when it leaves (crosscode.church-export/1): plain terms, export-only
// references, no internal ids and no secrets.
jest.mock('../src/config/db', () => ({}));
import { buildExport } from '../src/services/churchExport';
const d = (s: string) => new Date(s);
const input = {
version: '2.3.0',
users: [
{ id: 'u-uuid-1', name: 'Thandi', email: 't@x.org', phoneNumber: '+27821234567', role: 'admin', createdAt: d('2026-01-01T08:00:00Z'), newsEmail: true, newsWhatsApp: false, password: '$2b$hash', tokenVersion: 3 },
{ id: 'u-uuid-2', name: 'Sipho', email: 's@x.org', phoneNumber: null, role: 'user', createdAt: d('2026-02-01T08:00:00Z'), newsEmail: false, newsWhatsApp: true },
],
events: [{
id: 'ev-uuid-1', title: 'Camp', description: null, startDate: d('2026-12-04T16:00:00Z'), endDate: d('2026-12-06T12:00:00Z'), location: 'Camp X', isActive: true, isHidden: false,
sessions: [{ id: 's-1', label: 'Friday', startsAt: d('2026-12-04T16:00:00Z'), endsAt: d('2026-12-04T21:00:00Z') }],
eventOptions: [{ id: 'opt-uuid-1', name: 'Camper', price: 600 }],
}],
registrations: [{
id: 'reg-uuid-1', eventId: 'ev-uuid-1', userId: 'u-uuid-2', status: 'paid', createdAt: d('2026-11-01T09:00:00Z'),
attendees: [{ id: 'att-1', name: 'Sipho', email: 's@x.org', eventOptionId: 'opt-uuid-1', ticket: { usages: [{ scannedAt: d('2026-12-04T16:30:00Z') }] } }],
formResponses: [{ answers: [{ fieldId: 'f-1', value: 'None' }] }],
}],
payments: [{ id: 'pay-1', registrationId: 'reg-uuid-1', amount: 600, method: 'card', status: 'completed', createdAt: d('2026-11-01T09:05:00Z'), externalId: 'YOCO-1' }],
usages: [{ id: 'use-1', scannedAt: d('2026-12-04T16:30:00Z'), ticket: { eventId: 'ev-uuid-1', userId: 'u-uuid-2', holderUserId: null, attendee: { name: 'Sipho' } } }],
slots: [{ id: 'slot-1', roleId: 'role-1', userId: 'u-uuid-1' }],
roles: [{ id: 'role-1', eventId: 'ev-uuid-1', name: 'Kitchen', startsAt: null, endsAt: null }],
settings: [{ key: 'org_name', value: 'Hope Church' }, { key: 'smtp_password', value: 'enc:secret' }, { key: 'hub_install_secret', value: 'x' }],
fields: [{ id: 'f-1', label: 'Dietary needs' }],
};
describe('church export', () => {
const out = buildExport(input, new Date('2026-11-20T12:00:00Z'));
test('uses export-only references that link up', () => {
expect(out.people.map(p => p.ref)).toEqual(['p1', 'p2']);
expect(out.events[0]).toMatchObject({ ref: 'e1', ticketTypes: [{ ref: 't1', priceCents: 60000 }], published: true });
expect(out.registrations[0]).toMatchObject({ ref: 'r1', eventRef: 'e1', personRef: 'p2', attendees: [{ ticketTypeRef: 't1', checkedInAt: '2026-12-04T16:30:00.000Z' }], answers: [{ question: 'Dietary needs', answer: 'None' }] });
expect(out.payments[0]).toMatchObject({ registrationRef: 'r1', amountCents: 60000, reference: 'YOCO-1' });
expect(out.checkIns[0]).toMatchObject({ eventRef: 'e1', personRef: 'p2', name: 'Sipho' });
expect(out.rosters[0]).toMatchObject({ eventRef: 'e1', role: 'Kitchen', personRef: 'p1' });
expect(out.church.name).toBe('Hope Church');
});
test('has no internal ids and no secrets', () => {
const text = JSON.stringify(out);
for (const secret of ['uuid', '$2b$hash', 'enc:secret', 'hub_install_secret', 'smtp_password', 'tokenVersion', 'password']) expect(text).not.toContain(secret);
const keys: string[] = [];
const walk = (v: unknown): void => {
if (Array.isArray(v)) v.forEach(walk);
else if (v && typeof v === 'object') for (const [k, x] of Object.entries(v)) { keys.push(k); walk(x); }
};
walk(out);
expect(keys.filter(k => /^(id|.*Id|uuid|_id)$/.test(k))).toEqual([]);
});
});
@@ -0,0 +1,62 @@
// Installs made from the Hub register by themselves with HUB_LICENCE_KEY (AGENT-1.0-PLAN §7).
const mockSettings = new Map();
jest.mock('../src/config/db', () => ({
appSetting: {
findMany: jest.fn(async ({ where }) => [...mockSettings].filter(([key]) => where.key.in.includes(key)).map(([key, value]) => ({ key, value }))),
upsert: jest.fn(async ({ where, create }) => { mockSettings.set(where.key, create.value); }),
deleteMany: jest.fn(async ({ where }) => { mockSettings.delete(where.key); }),
},
}));
jest.mock('../src/hub/report', () => ({ APP_VERSION: '2.3.0', installInfo: async () => ({ name: 'Hope', url: 'https://events.hope.co.za', version: '2.3.0' }) }));
jest.mock('../src/hub/publicKey', () => ({ hubPublicKey: () => 'pem' }));
jest.mock('../src/hub/licence', () => ({ verifyToken: () => ({ installId: 'inst_1' }), clearLicenceCache: () => {} }));
const hub = require('../src/hub/client');
const reply = (status, body) => ({ ok: status < 400, status, json: async () => body });
const noSleep = async () => {};
describe('registering with HUB_LICENCE_KEY', () => {
let bodies;
beforeEach(() => {
mockSettings.clear();
bodies = [];
process.env.HUB_LICENCE_KEY = 'CEH-7K2M-9QXA-P4RT-WD8C';
process.env.HUB_ADMIN_NAME = 'Jane Admin';
process.env.HUB_ADMIN_EMAIL = 'jane@hope.co.za';
global.fetch = jest.fn(async (_url, opts) => {
bodies.push(JSON.parse(opts.body));
return reply(201, { installId: 'inst_1', installSecret: 's3cret', licence: 'hel1.x.y', heartbeatIntervalMinutes: 15 });
});
});
afterEach(() => {
delete global.fetch;
delete process.env.HUB_LICENCE_KEY;
delete process.env.HUB_ADMIN_NAME;
delete process.env.HUB_ADMIN_EMAIL;
});
test('registers once, with the admin contact, and stores the install', async () => {
expect(await hub.connectFromEnv({ sleep: noSleep })).toEqual({ connected: true });
expect(bodies[0]).toMatchObject({ licenceKey: 'CEH-7K2M-9QXA-P4RT-WD8C', install: { adminContact: { name: 'Jane Admin', email: 'jane@hope.co.za' } } });
expect(mockSettings.get('hub_install_id')).toBe('inst_1');
expect(await hub.connectFromEnv({ sleep: noSleep })).toEqual({ connected: false, reason: 'already' });
expect(global.fetch).toHaveBeenCalledTimes(1);
});
test('does nothing without the key', async () => {
delete process.env.HUB_LICENCE_KEY;
expect(await hub.connectFromEnv({ sleep: noSleep })).toEqual({ connected: false, reason: 'no_key' });
expect(global.fetch).not.toHaveBeenCalled();
});
test('a refused key isn\'t tried again; an unreachable Hub is', async () => {
global.fetch = jest.fn(async () => reply(404, { code: 'LICENCE_NOT_FOUND', message: 'Unknown key' }));
expect(await hub.connectFromEnv({ sleep: noSleep })).toEqual({ connected: false, reason: 'LICENCE_NOT_FOUND' });
expect(global.fetch).toHaveBeenCalledTimes(1);
global.fetch = jest.fn(async () => { throw new Error('ECONNREFUSED'); });
expect(await hub.connectFromEnv({ attempts: 3, sleep: noSleep })).toEqual({ connected: false, reason: 'unreachable' });
expect(global.fetch).toHaveBeenCalledTimes(3);
});
});
+28
View File
@@ -0,0 +1,28 @@
{
"schema": "crosscode.env-template/1",
"product": "events",
"files": {
"backend/.env": [
{ "name": "NODE_ENV", "layer": "generated", "required": true, "description": "production" },
{ "name": "PORT", "layer": "install", "from": "{apiPort}", "required": true, "description": "The backend's port (from the Hub's port list)" },
{ "name": "DATABASE_URL", "layer": "generated", "required": true, "description": "Made on the server with a new password; never leaves it" },
{ "name": "JWT_SECRET", "layer": "generated", "required": true, "description": "Also encrypts stored secrets: never change it" },
{ "name": "FRONTEND_URL", "layer": "install", "from": "https://{domain}", "required": true },
{ "name": "APP_BASE_URL", "layer": "install", "from": "https://{domain}", "required": true },
{ "name": "BACKEND_URL", "layer": "install", "from": "https://{domain}", "required": true, "description": "The same address: the backend is under /api (2.2.0+)" },
{ "name": "TRUST_PROXY", "layer": "server", "required": true, "description": "Behind frp: loopback" },
{ "name": "APP_TIMEZONE", "layer": "install", "default": "Africa/Johannesburg" },
{ "name": "HUB_URL", "layer": "defaults", "default": "https://hub.crosscode.co.za" },
{ "name": "HUB_HEARTBEAT_ENABLED", "layer": "defaults", "default": "true" },
{ "name": "HUB_LICENCE_KEY", "layer": "install", "description": "With it the site registers with the Hub by itself when it first starts" },
{ "name": "HUB_ADMIN_NAME", "layer": "install", "description": "The site admin, sent to the Hub on registering" },
{ "name": "HUB_ADMIN_EMAIL", "layer": "install" },
{ "name": "BACKUP_ENABLED", "layer": "defaults", "default": "true" },
{ "name": "DAILY_SUMMARY_ENABLED", "layer": "defaults", "default": "true" },
{ "name": "SENTRY_DSN", "layer": "defaults" }
],
"frontend/.env.production": [
{ "name": "NEXT_PUBLIC_API_URL", "layer": "install", "from": "https://{domain}", "required": true }
]
}
}