# Hub protocol (version 1) The contract between a **Cross Events install** (the church's site) and the **Cross Events Hub** (`events-hub.crosscode.co.za`). A copy of this file lives in both repositories (`joshua/hope-events` → `docs/hub-protocol.md`, `joshua/events-hub` → `docs/hub-protocol.md`); change both together. Principles: - **Install → Hub only.** The install always starts the conversation; the Hub never calls into an install. Works behind firewalls, and the Hub has no access to church data. - **No personal information** is ever sent — counts, versions and health only. Income is sent as a range, never an amount. - **A Hub outage never switches a church off.** Licences are signed tokens the install verifies offline with the Hub's public key. - Every request carries `protocolVersion`. The Hub accepts the current and the previous version, so installs waiting to update keep working. All bodies are JSON (`Content-Type: application/json`). Times are ISO 8601 UTC strings. Errors are `{ "message": "...", "code": "..." }` with a 4xx/5xx status. --- ## 1. Public key ``` GET /api/public-key → 200 { "protocolVersions": [1], "keyId": "k1", "algorithm": "Ed25519", "publicKey": "-----BEGIN PUBLIC KEY-----\n…" } ``` Installs ship with the Hub's public key built in (and may refresh it from here). The private key exists only on the Hub server. ## 2. Register an install Sent once, at the end of `/setup` (licence step) or from Site settings → "Connect to Hub". ``` POST /api/installs/register { "protocolVersion": 1, "licenceKey": "CEH-7K2M-9QXA-P4RT-WD8C", "install": { "name": "Hope Family Church", "url": "https://events.hopefamily.co.za", "adminContact": { "name": "Jane Admin", "email": "jane@hopefamily.co.za" }, "version": "1.41.0", "timezone": "Africa/Johannesburg", "server": { "node": "20.18.0", "postgres": "16.4", "os": "linux 6.8" }, "features": { "whatsapp": true, "paymentProviders": ["yoco", "payfast"], "campuses": false } } } → 201 { "installId": "inst_…", "installSecret": "…", // shown once; the install stores it encrypted "licence": "", "heartbeatIntervalMinutes": 15, "latestVersion": "1.41.0", "releases": [ … ], // as in the heartbeat reply (§3); Hub 1.4.0+ "notices": [ … ] } ``` - `404 LICENCE_NOT_FOUND` — unknown key. `403 LICENCE_REVOKED` — revoked licences can't register. - One licence = one install. Registering again **from the same URL** re-registers (new secret, same `installId`). From a different URL → `409 LICENCE_IN_USE` until Joshua releases the licence in the Hub (e.g. after a move to a new domain). - The `adminContact` is the one piece of personal information: a work contact for the church's admin, so Joshua can reach them. It is not used for anything else. - Rate-limited per IP. ## 3. Heartbeat Every `heartbeatIntervalMinutes` (15) from the install's job queue. ``` POST /api/installs/heartbeat X-Hub-Install: inst_… X-Hub-Timestamp: 2026-10-24T08:15:00.000Z X-Hub-Signature: { "protocolVersion": 1, "version": "1.41.0", "health": { "uptimeSeconds": 86400, "db": true, "jobs": { "mode": "queue", "failedLast24h": 0 }, "lastBackupAt": "2026-10-24T00:00:12.000Z", // null if none "disk": { "freeBytes": 21474836480, "totalBytes": 53687091200 }, // null if unknown "errorsLast24h": 0, // null if not tracked "pendingMigrations": 0 }, "stats": { "users": 412, "events": { "active": 3, "upcoming": 5, "total": 61 }, "registrations": { "last30d": 88, "total": 2310 }, "tickets": { "last30d": 140, "total": 3901 }, "checkIns": { "last30d": 96 }, "messages": { "email30d": 610, "whatsapp30d": 233 }, "paymentProviders": ["yoco", "payfast"], "campuses": false, // Site settings → Campuses on/off "campusCount": 0, // active campuses (0 while off; Cross Events 1.43.0+) "income": { "last30d": "R5 001–R20 000", "allTime": "R150 001–R250 000", "eventIncome12m": "R100 001–R150 000" } // eventIncome12m: Cross Events 2.0.2+ } } → 200 { "licence": "", "latestVersion": "1.42.0", "releases": [ // Hub 1.4.0+: newer than the version sent, newest first, at most 20 { "version": "1.42.0", "releasedAt": "2026-10-27T10:00:00.000Z", "urgent": false, "notes": "- Event series\n- Fixed: …" } ], "notices": [ // Hub 1.4.0+: the provider's banners for this install { "id": "…", "level": "maintenance", "title": "Planned maintenance", "message": "…", "startsAt": "2026-11-01T16:00:00.000Z", "endsAt": "2026-11-01T16:30:00.000Z", "updatedAt": "…" } ], "serverTime": "…" } ``` - **`releases`** — what's new in each version, so the church can decide whether to ask for the update. The Hub takes the versions from the Cross Events repository's `v*` tags and the notes from its `WHATS-NEW.md`. `notes` is plain text; lines starting with `- ` are a list. `urgent` marks security or serious bug fixes: the install shows those in red and doesn't let admins put them off. The highest release is `latestVersion`. - **`notices`** — banners Joshua posts on the Hub's Notices page (`level`: `info`, `maintenance` or `warning`). Sent until `endsAt`, including ones that haven't started, so the install shows each one from `startsAt` without waiting for a heartbeat. The install shows them to site admins and supervisors. Notices can also be emailed; that happens on the Hub, not through the install. - A Hub older than 1.4.0 sends neither field; the install then shows no notes and no notices. - The signature covers the exact bytes sent. Requests more than **5 minutes** off the Hub's clock are refused (`401 STALE_REQUEST`); a bad signature is `401 BAD_SIGNATURE`; an unknown or released install is `404 INSTALL_NOT_FOUND` (the install should show "Reconnect to Hub"). - **Income bands** (worked out on the install; the amount never leaves it): `R0–R1 000`, `R1 001–R5 000`, `R5 001–R20 000`, `R20 001–R50 000`, `R50 001–R100 000`, `R100 001–R150 000`, `R150 001–R250 000`, `R250 001–R400 000`, `R400 001–R700 000`, `R700 001–R1 000 000`, `R1 000 001–R2 500 000`, `R2 500 001–R5 000 000`, `R5 000 001–R10 000 000`, `over R10 000 000`. Before Cross Events 2.0.2 the bands stopped at `over R100 000`, and donations applied to a registration were counted twice. - **`eventIncome12m`** (Cross Events 2.0.2+) is the band of the last 365 days' event income: payments less refunds, without donations or sponsorships. Cross Code's licence tiers are billed on it, so every tier edge is a band edge. Older installs don't send it. - The Hub keeps every heartbeat for 30 days, then one per install per day. ## 3a. Update request Sent when a site admin presses **Request update** (Site settings → Licence). Installs never update themselves and never show the deploy command; the request tells Joshua, who updates the server. Signed exactly like the heartbeat. ``` POST /api/installs/update-request X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3) { "protocolVersion": 1, "version": "1.41.2" } → 201 { "requestedAt": "2026-10-27T09:00:00.000Z", "version": "1.42.0", "alreadyRequested": false, "changed": false } → 200 { …, "alreadyRequested": true, "changed": false } // a request for the latest is already open: not emailed again → 200 { …, "alreadyRequested": true, "changed": true, "previousVersion": "1.42.0" } // the open request was for an older version: it now asks for the latest ``` - The Hub opens an `update_requested` alert on the install (shown under Alerts) and emails the alert address once. It is resolved when a heartbeat reports a newer version than before. - **Changing a request (Hub 1.5.0):** when a request is open for a version that has since been overtaken, asking again moves it on to the latest version — the alert says "latest is 1.47.3 (changed from 1.47.0)" and the alert address is emailed once about the change. `version` is always the version now asked for. A Hub before 1.5.0 doesn't send `changed`; installs then withdraw the request and ask again (two emails, same result). - `409 UP_TO_DATE` — the install already runs the Hub's latest version (or none is set). - Errors as in §3 (`INSTALL_NOT_FOUND`, `STALE_REQUEST`, `BAD_SIGNATURE`). Rate-limited (10 an hour per IP). A Hub older than this section answers `404 NOT_FOUND`. - No personal information: not who pressed the button (the Hub already has the admin contact). ### Withdrawing it Sent when a site admin presses **Withdraw request**. Signed like the heartbeat. ``` POST /api/installs/update-request/cancel X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3) { "protocolVersion": 1 } → 200 { "cancelled": true } // the open request was resolved, and Joshua is emailed → 200 { "cancelled": false } // there was no open request ``` - The Hub resolves the `update_requested` alert and records `update_request_withdrawn` in the install's history. Rate-limited with update requests. A Hub older than 1.4.0 answers `404 NOT_FOUND`. - **"Not now"** (no reminders until the next version) stays on the install; the Hub isn't told. ## 3b. AI (Cross Events 2.0, Hub 1.6.0) Installs never hold the Claude API key. Each AI helper call goes through the Hub, which adds the key, checks the licence's monthly cap, calls Claude and meters the call. Both requests are signed exactly like the heartbeat. The install keeps its prompts; the Hub stores **no prompt or response text** — only the install, helper name, tokens, cost and time. ### Status ``` POST /api/installs/ai/status X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3) { "protocolVersion": 1 } → 200 { "enabled": true, "capReached": false, "capCents": 5000, "usedCents": 812.4, "usedPercent": 16, "renewsOn": "2026-12-01" } ``` - **`enabled: false`** — hide the AI buttons everywhere: the licence's cap is R0, the licence isn't active (suspended, revoked, or past its grace days), or the Hub's AI isn't set up. - **`capReached: true`** — show the buttons **disabled** ("This month's AI allowance is used up — it renews on 1 December"). Reached means there isn't room left for even a small call. - Amounts are cents (rand) as **charged** to the church, with fractions (a call costs a fraction of a cent). The month is South African time; `renewsOn` is the 1st of the next month. ### A helper call ``` POST /api/installs/ai/complete X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3) { "protocolVersion": 1, "helper": "draft_event", // lower-case name, for usage reports "system": "…", // the helper's fixed instructions (cached by Claude) "input": "…", // this request's text "schema": { … }, // optional JSON schema: the reply is JSON in that shape "maxTokens": 2000, // 1–8000 "effort": "low" // optional: low (default) | medium | high } → 200 { "output": "…" | { … }, // text, or the parsed JSON when a schema was given "usage": { "inputTokens": 1840, "outputTokens": 420 }, "chargedCents": 0.31, "status": { …as above… } } ``` - **Errors** are `{ code, message, status }` — `status` is the new AI status, so buttons can disable straight after the call that used up the allowance: - `402 AI_CAP_REACHED` — this call could pass the cap (checked before calling Claude). - `403 AI_OFF` (cap R0) · `403 LICENCE_INACTIVE` · `503 AI_NOT_CONFIGURED` (Hub not set up). - `422 AI_REFUSED` — Claude declined. `502 AI_INCOMPLETE` — the answer hit `maxTokens`. `502 AI_FAILED` — not usable (e.g. JSON in the wrong shape). These still cost what was used. - `503 AI_BUSY` / `503 AI_UNAVAILABLE` — Claude unreachable or rate-limited; nothing is charged. - `400 BAD_REQUEST`, `413 AI_INPUT_TOO_LARGE` (about 90 000 tokens), and the §3 errors. - **Metering:** real cost = tokens × the model's price × the exchange rate set in the Hub; charged = real × (1 + markup). The cap counts charged rand. Before calling Claude the Hub holds the worst case (an over-estimate of the prompt, plus `maxTokens`) against the cap in one transaction per install, so calls at the same moment can't pass it; afterwards the hold becomes the real amount. - Rate-limited to 60 a minute per IP (against runaway loops; money is limited by the cap). - A Hub older than 1.6.0 answers `404 NOT_FOUND`: the install treats that as "AI off". ## 4. Licence token `hel1..` — `payload` is base64url JSON, `signature` is the base64url Ed25519 signature of the ASCII string `hel1.`. ```json { "v": 1, "licenceId": "lic_…", "installId": "inst_…", "customer": "Hope Family Church", "plan": "standard", "status": "active", // active | suspended | revoked "licenceExpiresAt": "2027-10-31T21:59:59.000Z", // null = no end date "graceDays": 14, "issuedAt": "2026-10-24T08:15:00.000Z", "validUntil": "2026-11-23T08:15:00.000Z", // issuedAt + 30 days "limits": { "aiMonthlyCapCents": 0 } // the AI cap (§3b); 0 = AI off } ``` ### What the install does with it The install keeps the newest valid token (signature checks out, `installId` matches) and works out its state: | State | When | What happens | |-------|------|--------------| | **active** | `status` is active and now is before `min(licenceExpiresAt, validUntil)` | Everything works | | **grace** | after that date, for up to `graceDays` | Everything works; **only site admins** see a banner "Licence needs renewing — X days left" | | **suspended** | `status` is suspended, or grace has run out | Read-only: events can't be created or edited; no new registrations or payments. Tickets still scan; admins can view and export all data; privacy requests still work | | **revoked** | `status` is revoked | Same as suspended, with a permanent banner | | **unlicensed** | never connected, or the Hub answered `INSTALL_NOT_FOUND` (the install drops its token) | Same as suspended (events can't be created or edited either); admins see "Connect to Hub" | `validUntil` is refreshed by every heartbeat, so a Hub outage only matters after 30 days (then grace starts). Blocking the Hub can't keep a suspended licence active for more than 30 days. ## 5. Versioning - `protocolVersion` goes up only for changes an older install can't handle. Adding optional fields to a heartbeat or a token doesn't need a new version — both sides ignore fields they don't know. - The Hub accepts protocol `N` and `N-1`; anything else is `400 UNSUPPORTED_PROTOCOL`.