Files
crosscode-platform/apps/events/backend/src/hub/client.js
T
joshuaandClaude Opus 5.5 8a930d07c6 Events 2.4.0 backend: protocol v2, Linked products, the event feed
- Hub client: register and heartbeat on protocol v2 with the site's
  Ed25519 key (sent on the heartbeat until the Hub has it); falls back to
  v1 for a day if the Hub refuses v2, so the licence always refreshes.
- crosscode.link/1 Connect / Disconnect, both directions, trusted through
  the Hub's cached linkedProducts (ProductLink, LinkNonce).
- GET /api/feed/v1/events from FeedEntry (go-live, closing and selling
  out are changes; deactivated events go in deleted), event.changed to
  connected products, and showing their events (ImportedEvent).
- /api/v2/linked-products, /api/v2/linked-events; /events/:id/full gains
  crosscodeEvent and priceRangeCents for the JSON-LD.
- Contracts: FEED_PATHS, typesVersions for @crosscode/contracts/signing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 12:24:29 +02:00

370 lines
16 KiB
JavaScript

/**
* Talking to the Cross Events Hub (docs/hub-protocol.md): register with a licence key, then a
* signed heartbeat every 15 minutes, and a signed update request (or withdrawal) when an admin
* asks. Install → Hub only. Stored in AppSetting:
* hub_install_id, hub_install_secret (encrypted), hub_licence (signed token),
* hub_last_heartbeat_at, hub_last_error, hub_latest_version,
* hub_releases, hub_notices (JSON from the last heartbeat: what's new, provider's notices),
* hub_update_requested_at, hub_update_requested_version,
* hub_update_snoozed_version ("Not now" for that version; set here, not by the Hub),
* hub_v1_until (the Hub refused protocol v2: speak v1 until then; 2.4.0),
* and this site's key pair and the Hub's list of the church's other products (links/store.ts).
* These keys are kept out of the generic settings endpoints (settingsController).
*
* Protocol (2.4.0, docs/EVENTS-2.4-PLAN.md §1): register and heartbeat speak **v2**
* (`product: "events"`, this site's public key, the church's other products in the reply). An
* install that registered with v1 moves over by sending its key on the heartbeat (Hub 2.2.0
* saves it), so nobody needs the licence key again. If the Hub refuses a v2 body (a Hub before
* 2.0, or a body the Hub's contract doesn't accept), the same heartbeat goes again as v1 and v1
* is used for a day: the licence must keep refreshing whatever happens. Update requests and AI
* calls stay v1, which every Hub accepts.
*/
const crypto = require('crypto');
const prisma = require('../config/db');
const { encrypt, decrypt } = require('../utils/encryption');
const { verifyToken, clearLicenceCache } = require('./licence');
const report = require('./report');
const { hub } = require('@crosscode/contracts');
const store = require('../links/store');
/** Update requests and AI calls (as in v1; the Hub answers both versions). */
const PROTOCOL_VERSION = 1;
/** Register and heartbeat (2.4.0). */
const HEARTBEAT_PROTOCOL = 2;
const V1_FALLBACK_MS = 24 * 60 * 60 * 1000;
const TIMEOUT_MS = 15000;
const HUB_KEYS = ['hub_install_id', 'hub_install_secret', 'hub_licence', 'hub_last_heartbeat_at', 'hub_last_error', 'hub_latest_version', 'hub_update_requested_at', 'hub_update_requested_version', 'hub_releases', 'hub_notices', 'hub_update_snoozed_version', 'hub_v1_until', ...store.KEY_SETTINGS];
function hubUrl() {
return String(process.env.HUB_URL || 'https://events-hub.crosscode.co.za').replace(/\/$/, '');
}
class HubError extends Error {
constructor(message, code, status, data = null) {
super(message);
this.code = code;
this.statusCode = status;
// The Hub's whole error body (AI errors carry the new AI status, protocol §3b).
this.data = data;
}
}
async function save(values) {
for (const [key, value] of Object.entries(values)) {
if (value === null) await prisma.appSetting.deleteMany({ where: { key } });
else await prisma.appSetting.upsert({ where: { key }, update: { value: String(value) }, create: { key, value: String(value) } });
}
clearLicenceCache();
}
/** What's new and the provider's notices from a register/heartbeat reply (a Hub before 1.4.0 sends neither). */
function fromHub(data) {
return {
hub_releases: Array.isArray(data.releases) ? JSON.stringify(data.releases.slice(0, 20)) : null,
hub_notices: Array.isArray(data.notices) ? JSON.stringify(data.notices.slice(0, 20)) : null,
};
}
async function read(keys) {
const rows = await prisma.appSetting.findMany({ where: { key: { in: keys } } });
return Object.fromEntries(rows.map(r => [r.key, r.value]));
}
async function post(path, body, headers = {}, timeoutMs = TIMEOUT_MS) {
const raw = JSON.stringify(body);
let res;
try {
res = await fetch(`${hubUrl()}${path}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', ...(typeof headers === 'function' ? headers(raw) : headers) },
body: raw,
signal: AbortSignal.timeout(timeoutMs),
});
} catch (e) {
throw new HubError(`The Hub (${hubUrl()}) could not be reached: ${e?.message || e}`, 'HUB_UNREACHABLE', 502);
}
const data = await res.json().catch(() => ({}));
if (!res.ok) throw new HubError(data.message || `The Hub answered ${res.status}`, data.code || 'HUB_ERROR', res.status, data);
return data;
}
/**
* POST signed with the install secret (§3). Throws NOT_CONNECTED when there is no connection.
* AI calls wait longer than the default (Claude can take a while to write).
*/
async function signedPost(path, body, { timeoutMs = TIMEOUT_MS } = {}) {
const s = await read(['hub_install_id', 'hub_install_secret']);
if (!s.hub_install_id || !s.hub_install_secret) throw new HubError('This site isn\'t connected to the Hub yet.', 'NOT_CONNECTED', 400);
const secret = decrypt(s.hub_install_secret);
return post(path, body, raw => {
const timestamp = new Date().toISOString();
return {
'X-Hub-Install': s.hub_install_id,
'X-Hub-Timestamp': timestamp,
'X-Hub-Signature': crypto.createHmac('sha256', secret).update(`${timestamp}.${raw}`).digest('hex'),
};
}, timeoutMs);
}
/** Register this install with a licence key. Returns the licence claims. */
async function connect(licenceKey, adminContact) {
if (!require('./publicKey').hubPublicKey()) {
throw new HubError('This version of Cross Events has no Hub key built in, so it can\'t check licences yet.', 'NO_PUBLIC_KEY', 500);
}
const install = await report.installInfo();
if (!/^https?:\/\//.test(install.url)) {
throw new HubError('Set the site\'s web address first (FRONTEND_URL on the server, or Site settings → Organisation).', 'NO_SITE_URL', 400);
}
const v1Body = {
protocolVersion: PROTOCOL_VERSION,
licenceKey: String(licenceKey || '').trim(),
install: { ...install, adminContact: adminContact ? { name: adminContact.name || null, email: adminContact.email || null } : null },
};
// v2 (2.4.0): the product and this site's public key, so the church's other products can link.
// Anything wrong with the key (or a Hub that only speaks v1) registers with v1 instead.
const publicKeyPem = await ownPublicKey();
const v2Body = { ...v1Body, protocolVersion: HEARTBEAT_PROTOCOL, licenceKey: v1Body.licenceKey.toUpperCase(), product: 'events', install: { ...v1Body.install, publicKey: publicKeyPem } };
const v2 = !!publicKeyPem && !(await v1Only()) && hub.registerRequestSchema.safeParse(v2Body).success;
let data;
let sentV2 = v2;
try {
data = await post('/api/installs/register', v2 ? v2Body : v1Body);
} catch (e) {
if (!v2 || !refusedV2(e)) throw e;
await useV1ForADay();
sentV2 = false;
data = await post('/api/installs/register', v1Body);
}
const claims = verifyToken(data.licence);
if (!claims || claims.installId !== data.installId) {
throw new HubError('The Hub answered with a licence this install can\'t verify. Is HUB_URL pointing at the right Hub?', 'BAD_LICENCE', 502);
}
await save({
hub_install_id: data.installId,
hub_install_secret: encrypt(data.installSecret),
hub_licence: data.licence,
hub_last_heartbeat_at: new Date().toISOString(),
hub_last_error: null,
hub_latest_version: data.latestVersion || null,
...fromHub(data),
});
if (sentV2) {
try {
await store.saveLinkedProducts(data.linkedProducts);
// Registered with the key, so the Hub has it.
await store.setPublicKeyStatus('matches');
} catch (e) {
console.warn('[hub] Could not save the linked products:', e?.message || e);
}
}
return claims;
}
/** This site's public key, or null when it can't be made or read (then v1 is used). */
async function ownPublicKey() {
try {
return (await store.keyPair()).publicKeyPem;
} catch (e) {
console.warn('[hub] No key pair for protocol v2, using v1:', e?.message || e);
return null;
}
}
/** Whether the Hub refused a v2 body (too old for v2, or a contract it doesn't accept): retry as v1. */
function refusedV2(e) {
return e instanceof HubError && e.statusCode === 400 && ['UNSUPPORTED_PROTOCOL', 'INVALID_REQUEST'].includes(e.code);
}
async function v1Only() {
const until = (await read(['hub_v1_until'])).hub_v1_until;
return !!until && new Date(until).getTime() > Date.now();
}
async function useV1ForADay() {
await save({ hub_v1_until: new Date(Date.now() + V1_FALLBACK_MS).toISOString() });
}
/**
* The health as protocol v2 wants it: every field there (a part that couldn't be read is
* reported as nothing wrong rather than left out).
*/
function v2Health(h) {
return {
...h,
jobs: h.jobs || { mode: 'unknown', failedLast24h: 0 },
pendingMigrations: Number.isInteger(h.pendingMigrations) ? h.pendingMigrations : 0,
};
}
/**
* The heartbeat body: v2 when it fits the contract (with the public key until the Hub has it),
* otherwise v1. Returns { body, v2 }.
*/
async function heartbeatBody() {
const health = await report.health();
const stats = await report.stats();
const v1 = { protocolVersion: PROTOCOL_VERSION, version: report.APP_VERSION, health, stats };
if (await v1Only()) return { body: v1, v2: false };
const publicKeyPem = await ownPublicKey();
if (!publicKeyPem) return { body: v1, v2: false };
const status = await store.publicKeyStatus().catch(() => null);
const v2 = {
protocolVersion: HEARTBEAT_PROTOCOL,
product: 'events',
version: report.APP_VERSION,
health: v2Health(health),
stats,
...(status === 'saved' || status === 'matches' ? {} : { publicKey: publicKeyPem }),
};
const check = hub.heartbeatRequestSchema.safeParse(v2);
if (!check.success) {
console.warn('[hub] The v2 heartbeat doesn\'t fit the contract, sending v1:', check.error.issues.slice(0, 3).map(i => `${i.path.join('.')} ${i.message}`).join('; '));
return { body: v1, v2: false };
}
return { body: v2, v2: true };
}
/** Send a heartbeat (the `hub-heartbeat` job). Skips quietly when not connected. */
async function heartbeat() {
const s = await read(['hub_install_id', 'hub_install_secret']);
if (!s.hub_install_id || !s.hub_install_secret) return { skipped: 'not connected' };
let { body, v2 } = await heartbeatBody();
try {
let data;
try {
data = await signedPost('/api/installs/heartbeat', body);
} catch (e) {
if (!v2 || !refusedV2(e)) throw e;
console.warn(`[hub] The Hub refused a v2 heartbeat (${e.code}: ${e.message}); using v1 for a day.`);
await useV1ForADay();
({ body, v2 } = await heartbeatBody());
data = await signedPost('/api/installs/heartbeat', body);
}
if (v2) {
try {
await store.saveLinkedProducts(data.linkedProducts);
if (typeof data.publicKeyStatus === 'string') await store.setPublicKeyStatus(data.publicKeyStatus);
} catch (e) {
console.warn('[hub] Could not save the linked products:', e?.message || e);
}
}
const claims = verifyToken(data.licence);
await save({
// Keep the old token if the new one doesn't check out (never accept an unverified one).
...(claims && claims.installId === s.hub_install_id ? { hub_licence: data.licence } : {}),
hub_last_heartbeat_at: new Date().toISOString(),
hub_last_error: null,
hub_latest_version: data.latestVersion || null,
...fromHub(data),
});
return { ok: true, status: claims?.status || null, protocol: v2 ? 2 : 1 };
} catch (e) {
await save({ hub_last_error: `${new Date().toISOString()} ${e.code || ''} ${e.message}`.slice(0, 500) });
// The Hub doesn't know this install any more (licence released): drop the connection and the
// licence, so the site is unlicensed (read-only) and shows "Connect" until a key is entered.
if (e.code === 'INSTALL_NOT_FOUND') {
await save({ hub_install_id: null, hub_install_secret: null, hub_licence: null });
return { ok: false, reconnect: true };
}
throw e;
}
}
/** a < b as x.y.z versions. */
function olderThan(a, b) {
const pa = String(a || '').split('.').map(n => parseInt(n, 10) || 0);
const pb = String(b || '').split('.').map(n => parseInt(n, 10) || 0);
for (let i = 0; i < 3; i++) if (pa[i] !== pb[i]) return pa[i] < pb[i];
return false;
}
/**
* Ask the Hub for this site to be updated (§3a). Joshua is told; the site never updates itself.
* Asking again after a newer version came out moves the request on to it (`changed`). A Hub before
* 1.5.0 can't do that (it doesn't send `changed`), so the old request is withdrawn and made again.
* Returns { requestedAt, version, alreadyRequested, changed, previousVersion }.
*/
async function requestUpdate() {
const ask = async () => {
try {
return await signedPost('/api/installs/update-request', { protocolVersion: PROTOCOL_VERSION, version: report.APP_VERSION });
} catch (e) {
if (e.code === 'NOT_FOUND') throw new HubError('The Hub doesn\'t take update requests yet. Please contact your provider.', 'NOT_SUPPORTED', 502);
throw e;
}
};
let data = await ask();
if (data.alreadyRequested && data.changed === undefined) {
const asked = (await read(['hub_update_requested_version'])).hub_update_requested_version || null;
if (!asked || olderThan(asked, data.version)) {
await cancelUpdateRequest();
data = { ...(await ask()), changed: true, previousVersion: asked };
}
}
await save({ hub_update_requested_at: data.requestedAt, hub_update_requested_version: data.version || null });
return data;
}
/** Withdraw the update request (§3a): the provider is told not to update after all. */
async function cancelUpdateRequest() {
try {
await signedPost('/api/installs/update-request/cancel', { protocolVersion: PROTOCOL_VERSION });
} catch (e) {
if (e.code === 'NOT_FOUND') throw new HubError('The Hub can\'t withdraw update requests yet. Please contact your provider.', 'NOT_SUPPORTED', 502);
throw e;
}
await save({ hub_update_requested_at: null, hub_update_requested_version: null });
}
/** "Not now": no update reminders until a newer version than `version` is out. Null turns them back on. */
async function snoozeUpdate(version) {
await save({ hub_update_snoozed_version: version || null });
}
/**
* A heartbeat soon (on startup, and after connecting), so a licence change on the Hub shows
* without waiting for the next 15-minute run. Never throws; skipped when the job is switched off.
*/
let soonTimer = null;
function heartbeatSoon(delayMs = 30 * 1000) {
if (String(process.env.JOBS_ENABLED || 'true').toLowerCase() === 'false') return;
if (String(process.env.HUB_HEARTBEAT_ENABLED || 'true').toLowerCase() === 'false') return;
clearTimeout(soonTimer);
soonTimer = setTimeout(() => {
heartbeat().catch(e => console.warn('[hub] Heartbeat failed:', e?.message || e));
}, delayMs);
soonTimer.unref?.();
}
/**
* 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, HEARTBEAT_PROTOCOL, HUB_KEYS, heartbeatBody, hubUrl, HubError, signedPost, connect, connectFromEnv, heartbeat, heartbeatSoon, requestUpdate, cancelUpdateRequest, snoozeUpdate };