diff --git a/apps/events/backend/scripts/export-church.ts b/apps/events/backend/scripts/export-church.ts new file mode 100644 index 0000000..65d5a25 --- /dev/null +++ b/apps/events/backend/scripts/export-church.ts @@ -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 + */ +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 '); + 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(() => {})); diff --git a/apps/events/backend/src/app.js b/apps/events/backend/src/app.js index 95cf2b8..451f429 100644 --- a/apps/events/backend/src/app.js +++ b/apps/events/backend/src/app.js @@ -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) diff --git a/apps/events/backend/src/hub/client.js b/apps/events/backend/src/hub/client.js index 53d5f87..ce5ff3b 100644 --- a/apps/events/backend/src/hub/client.js +++ b/apps/events/backend/src/hub/client.js @@ -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 }; diff --git a/apps/events/backend/src/services/churchExport.ts b/apps/events/backend/src/services/churchExport.ts new file mode 100644 index 0000000..f8560e0 --- /dev/null +++ b/apps/events/backend/src/services/churchExport.ts @@ -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; // 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(); + 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 { + 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; +} diff --git a/apps/events/backend/tests/churchExport.test.ts b/apps/events/backend/tests/churchExport.test.ts new file mode 100644 index 0000000..7ccf812 --- /dev/null +++ b/apps/events/backend/tests/churchExport.test.ts @@ -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([]); + }); +}); diff --git a/apps/events/backend/tests/hubConnectFromEnv.test.js b/apps/events/backend/tests/hubConnectFromEnv.test.js new file mode 100644 index 0000000..e8891c8 --- /dev/null +++ b/apps/events/backend/tests/hubConnectFromEnv.test.js @@ -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); + }); +}); diff --git a/apps/events/env.template.json b/apps/events/env.template.json new file mode 100644 index 0000000..b0f8581 --- /dev/null +++ b/apps/events/env.template.json @@ -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 } + ] + } +}