EVENTS-2.4-PLAN.md: protocol v2 (public key in the v2 heartbeat, Hub 2.2.0), Linked products and Connect (crosscode.link/1, contracts 1.4.0), the event feed, showing sibling events, and packages/seo. Six decisions to confirm. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
24 KiB
Cross Events 2.4.0 — protocol v2, Linked products, the event feed and packages/seo
Phase 2 of ROADMAP-v3.md (§4, §5 "Sibling discovery", §9, §11; decisions 5, 20). Written 2026-11-18. Not started.
What 2.4.0 is: Cross Events becomes a full member of a church stack. It reports to the Hub as
product: "events" (protocol v2), shows the church's other products under Settings → Linked
products with a Connect button, publishes its public events as a crosscode.event-feed/1
feed, shows events from linked products, and builds its SEO data with the new shared
packages/seo. Nothing changes for a church that has only Cross Events, apart from a new
settings page that says "No other products yet".
The Website and App don't exist yet, so the "show events from" side is built and tested against sample feeds (§8). It's ready for the Website (phase 4) without another Events release.
Done when:
events@2.4.0,contracts@1.4.0and Hubv2.2.0are tagged and pushed.- An Events install updated to 2.4.0 moves itself to protocol v2 with no admin action, and the Hub shows it as v2 with a public key.
- The feed passes the contract (
parseEventFeedwith nothing rejected) for every event in the e2e seed, and a sample Website feed shows up in Events with a canonical link to its origin. - crosscode-site says "Works with the Church Website and App (coming)" on the Cross Events page (ROADMAP §9, "Updating crosscode-site").
Contents
- Before starting
- Protocol v2
- Linked products and Connect
- Publishing: the feed
- Showing events from linked products
packages/seo- Settings, audit log and help
- What changes in each repo
- Testing
- Releasing and rolling it out
- Decisions
- Still open
Before starting
- The rollout (ROLLOUT-1.0.md) is at least past step 1, so production runs Hub 2.1.x. 2.4.0 needs Hub 2.2.0 (§1) and is released after it, but neither depends on the church servers being adopted.
apps/eventsbuilds and tests clean onmain(npm run check), as the baseline.- Events uses
@crosscode/contractsas a workspace dependency for the first time (backend and frontend). The backend is CommonJS with some TypeScript; the package ships both builds, sorequire('@crosscode/contracts')works as it is.
1. Protocol v2
Today src/hub/client.js speaks protocol 1 (PROTOCOL_VERSION = 1). v2 is in
@crosscode/contracts (hub.*) and the Hub has accepted it since 2.0.0
(hub-protocol.md §6).
The problem: hub-protocol.md says an install moves to v2 by registering again with its
licence key and a public key. Events never stored the licence key (it's only sent once, from
/setup or "Connect to Hub"), so every church admin would have to find and retype it. The v2
heartbeat also has no way to send a public key.
The fix (Hub 2.2.0, contracts 1.4.0): the v2 heartbeat gets an optional publicKey (PEM).
The heartbeat is already signed with the install secret, so the Hub knows it's that install. The
Hub saves the key when the install has none, and refuses a different key
(409 PUBLIC_KEY_MISMATCH) unless Joshua clears it on the install's page (for a restored server
that lost its key). An optional field keeps the protocol at version 2 and the contract at /1
(ROADMAP §2, "Versioning").
What Events does:
| Step | Detail |
|---|---|
| Key pair | On first start of 2.4.0, generate an Ed25519 key pair (generateEd25519 from @crosscode/contracts/signing). Private key encrypted in AppSetting hub_private_key (same encrypt as the install secret), public key in hub_public_key. Both added to HUB_KEYS, so the generic settings endpoints never show them. Never regenerated unless missing |
| Heartbeat | protocolVersion: 2, product: "events", publicKey until the Hub has acknowledged it (hub_public_key_ack), Events stats as in v1. Body checked with hub.heartbeatRequestSchema before sending (a bug shows in tests, not as a 400 in production) |
| Register | /setup and "Connect to Hub" register with v2 straight away (product, install.publicKey) |
| Reply | Reads linkedProducts (§2) and the licence's customerId / product; everything else as v1 |
| Falling back | If the Hub answers 400 UNSUPPORTED_PROTOCOL (a Hub older than 2.0), send v1 and keep trying v2 once a day. Not expected in production; it keeps a restored old Hub from cutting installs off |
hub-protocol.md §6 "Moving an install to v2" is rewritten to describe this (both copies).
2. Linked products and Connect
Settings → Linked products (site admins only) lists the church's other installs from the
last heartbeat's linkedProducts (cached in AppSetting hub_linked_products, so a Hub outage
changes nothing; ROADMAP §5). For each: product name, address, and its state: Not connected
· Connected (since when, by whom) · Connected, last sync failed (when, why).
With Events only, the page says the church has no other Cross Code products yet, with a link to crosscode.co.za.
Connect
The Hub tells each install which siblings exist and their public keys. Connect turns that
into a working link: a shared secret for signed calls between the two, and the feed settings.
New contract: crosscode.link/1 in packages/contracts/src/link.ts.
A (Events) B (e.g. Website)
admin clicks Connect
makes a 32-byte secret S
POST {B.url}/api/links/v1/connect ───────────────► 1. A is in B's own cached linkedProducts
{ (same Hub customer), by installId
schema: "crosscode.link/1", 2. the Ed25519 signature checks out against
type: "link.connect", the publicKey the Hub listed for A
from: { product, installId, url }, 3. `to.installId` is B; issuedAt within
to: { installId }, 5 minutes; nonce not seen before
secret: S, 4. stores S (encrypted), marks A connected
issuedAt, nonce, ◄── 200 { schema, type: "link.connected",
signature: <Ed25519 over the canonical JSON> from: {…B}, publicKey check, signature }
}
checks B's signed reply with B's Hub-listed key
stores S (encrypted), marks B connected
- Trust comes from the Hub's list on both sides. B accepts A only if A appears in B's
linkedProductswith that exact key, so only installs of the same church can link, and only ones the Hub knows. The Hub is still not on the path at the time of the call (rule 2): both sides use their cached lists. - No approval step on B. Both installs belong to the same church; whoever is admin on either
side can connect. B's Linked products page shows "Connected by Cross Events on 18 Nov" and
either side can Disconnect (a signed
link.disconnect; both drop the secret). - Connecting again replaces the secret (e.g. after a restored backup lost it).
- After Connect, every call between the two (the
event.changedwebhook now, Accounts' back-channel later) usesLINK_HEADERSHMAC with S, as@crosscode/contracts/signingalready defines. - Errors are
crosscode.link/1{ message, code }:NOT_LINKED(A isn't in B's list: "Wait for the next Hub heartbeat, up to 15 minutes, or check the Hub"),BAD_SIGNATURE,STALE_REQUEST,REPLAYED,WRONG_INSTALL. - Key format: the Hub lists keys as PEM, while the agent helpers in
signing.tstake raw base64url. contracts 1.4.0 addsed25519PublicFromPem/signLink/verifyLinkso no product converts by hand. - Events also answers Connect, since a Website will usually be the one clicking it.
POST /api/links/v1/connectand/disconnectare public routes, rate-limited per IP, outside/api/v2(they're a cross-product contract, like the feed).
Stored per link in a new table, not in AppSetting:
model ProductLink {
installId String @id // the sibling's Hub install id
product String // website | app | accounts
url String
publicKey String // as listed by the Hub when connected
secret String // encrypted
connectedAt DateTime
connectedBy String? // a user id when connected here, null when the sibling did it
showEvents Boolean @default(false) // "Show events from" (§4)
lastSyncAt DateTime?
lastSyncError String?
lastGoodAt DateTime?
}
If a sibling disappears from linkedProducts (uninstalled, or the licence moved), the link stays
but shows No longer listed by the Hub. Its events keep showing until an admin removes the
link, so a Hub mistake can't empty the church's event list.
3. Publishing: the feed
GET /api/feed/v1/events?updatedSince=<ISO> → crosscode.event-feed/1 (ROADMAP §4,
"Transport"). Public, no sign-in: it only carries what the public event pages already show. It
answers only when Publish my events is on (default on; otherwise 404 FEED_OFF).
Which events
The same rule as the public pages, publicEventWhere() in src/utils/series.js: isActive, not
isHidden, goLiveAt passed. Plus:
- Events that ended more than 30 days ago are left out of a full fetch (no
updatedSince). An event that ends doesn't go intodeleted: siblings keep their copy and drop it from "upcoming" themselves. - An event's campus goes out as
campus: { slug, name },nullfor all campuses. - Never in the feed: kids check-in and volunteer options, contact name/phone/email (the church's contact for an event can be a person), the attendee form, prices of staff-only options.
updatedAt and deleted that are actually right
An event's public face changes without its row changing: it goes live when goLiveAt passes,
registration closes at the deadline, and it fills up as tickets sell. Event.updatedAt misses
all three, and Events never deletes an event (deleteEvent deactivates it). So the feed is kept
in a table of what was last published:
model FeedEntry {
eventId String @id
hash String // sha256 of the canonical crosscode.event/1 payload
payload Json
changedAt DateTime // the event's `updatedAt` in the feed
removedAt DateTime? // set when it stops being public: goes into `deleted`
}
- A
feed-refreshjob (pg-boss, every 5 minutes, and queued straight after an event, option, session or registration change through the existing Prisma extension inconfig/db.js) builds each candidate event'scrosscode.event/1, compares the hash and bumpschangedAtonly when something a sibling would see has changed. An event that stopped being public getsremovedAt. - The feed answers from this table:
events= rows withchangedAt > updatedSinceand noremovedAt;deleted= rows withremovedAt > updatedSince. With noupdatedSince, every row withoutremovedAt. Rows removed more than 90 days ago are cleaned up. - When the job changes anything, it sends
event.changed(eventChangedSchema, at most 100 ids) to every connected link, signed with that link's secret, using the retries and SSRF rules ofutils/webhooks.js(1 min, 5 min, 30 min, 2 h, then give up; the 15-minute poll catches up).
Building crosscode.event/1 from an Event
A new src/feed/toCrosscodeEvent.ts, checked against eventSchema in tests for every e2e seed
event:
| Field | From |
|---|---|
id |
Event.id (already a UUID) |
origin |
{ product: "events", installId: hub_install_id, url: <APP_URL>/events/<id> } |
status |
published (Events has no "cancelled" state today: cancelling is deactivating, so it goes into deleted) |
summary |
null (no such field yet) |
description |
The plain-text description with markdown characters escaped, so it reads the same when rendered as markdown |
imageUrl |
picture, made absolute |
timezone |
The site timezone (TIMEZONE) |
startsAt / endsAt / allDay / sessions |
utils/sessions.js (already keeps start/end in step with the sessions); allDay: false |
location |
{ name: location, address: null, onlineUrl: null }, or null |
series |
{ id, name } |
tags |
[] (no tags in Events yet) |
registration |
mode: origin when requiresRegistration, else contact; url the event page; status from the same rules as the event page (not_open before go-live, closed after the deadline or late-join cut-off, full when every limited main option is sold out, waitlist when full with a waitlist); priceFrom = the lowest current public price (early-bird and variants as in eventSchema.ts today), null when free |
4. Showing events from linked products
Per connected link: Show events from this product (off by default; ROADMAP §4 "Show events from"). When on:
- Sync: a
feed-syncjob per link every 15 minutes, and straight away on a validevent.changed(POST /api/feed/v1/changed, verified withLINK_HEADERSand that link's secret). It fetches?updatedSince=<lastGoodAt minus 5 minutes>, 15 s timeout, parses withparseEventFeed(rejected events are logged, never block the rest), and upserts intoImportedEvent. One failing link never holds up another (separate jobs). - The last good copy stays. A failed sync only sets
lastSyncError; admins see "Last synced 2 hours ago" on Linked products and on the dashboard's event list. - Read-only, keyed by
origin.product+id(eventKey), and never re-published: the feed only ever readsEvent, so no loops (ROADMAP §4 rules). - Turning Show events from off, or removing the link, deletes that link's imported events.
model ImportedEvent {
key String @id // eventKey(): "<product>:<id>"
linkId String // ProductLink.installId
payload Json // the crosscode.event/1 as received
startsAt DateTime // copied out for sorting and "upcoming"
endsAt DateTime
campusSlug String?
updatedAt DateTime
@@index([linkId])
@@index([startsAt])
}
Where they show: on the public Events list, the home page's upcoming events and campus
pages (by campus.slug, when it matches one of Events' campuses; otherwise under all campuses),
mixed in by date, with a small "From the church website" label. Not in the dashboard's event
tools, reports, check-in or anything that registers people.
Their page: /events/linked/<product>/<id>: title, dates, sessions, place, image, the
description rendered as markdown with HTML off (react-markdown, new dependency), and one button
by registration.mode: More details / Register linking to the origin (origin /
external), or the contact instructions (contact). The page has
<link rel="canonical"> to origin.url (ROADMAP §11, "Imported events"), is left out of
sitemap.xml, and has no Event JSON-LD (the origin's page carries it, so search engines see
one event).
5. packages/seo
A new workspace, @crosscode/seo (ROADMAP §11): the schema.org builders and meta helpers every
product will use, built on @crosscode/contracts. Pure functions, no framework, ESM + CJS like
contracts, its own Jest tests.
| Export | What |
|---|---|
eventJsonLd(event: CrosscodeEvent, opts) |
Event JSON-LD from crosscode.event/1: eventStatus (EventCancelled for cancelled), attendance mode (OnlineEventAttendanceMode / Mixed… from location.onlineUrl), Place or VirtualLocation, offers from registration (SoldOut for full, validFrom from opensAt), sessions as subEvent |
churchJsonLd(church: Church) |
Church (a schema.org Organization subtype): name, logo, address, geo, phone, service times as openingHoursSpecification-style Event entries, sameAs social links. Used for the Website's home page later; Events uses it as the event organizer |
canonicalUrl(base, path) |
Drops tracking parameters (src, utm_*, fbclid, gclid) and the trailing slash rule in one place |
pageMeta({ title, description, … }) |
Title length and description trimming rules (60 / 155 characters), used for the Website's warnings later |
Events moves onto it: frontend/src/lib/eventSchema.ts is replaced. The public event detail
answer gains crosscodeEvent (the same builder as the feed, §3), and the page calls
eventJsonLd with it. Nothing gets worse for Google: today's JSON-LD gives a price range
(AggregateOffer low–high); crosscode.event/1 only has priceFrom. eventJsonLd takes an
optional priceRange for the origin's own page, so Events keeps sending the high price. A
snapshot test compares the old and new JSON-LD for each seed event; the only allowed
differences are additions (subEvent, organizer as a Church).
The organizer comes from a crosscode.church/1 that Events builds from its own site settings
(name, logo, colours, contact email). Sharing that profile with siblings is not part of 2.4.0
(see Still open).
6. Settings, audit log and help
- Settings → Linked products (new page): the list, Connect / Disconnect, Show events from, last sync. Settings → Site → Publish my events (on by default) with one line on what it shares ("Your public events, as they appear on your events page. Never anyone's details.").
- Audit log (
utils/adminAudit.js):product_link_connected,product_link_disconnected,feed_publish_toggled,feed_show_toggled. Connections made by the sibling are logged with no user. - Help: a "Linked products" help article, and the setting descriptions. What's new for 2.4.0: "Ready for the Church Website and App: your events can show on them, and theirs here. Nothing changes until you have them."
- Readiness checks (
utils/readiness.js): warn when a link's last sync failed for more than a day.
7. What changes in each repo
| Repo | Change | Version |
|---|---|---|
crosscode-platform packages/contracts |
crosscode.link/1 (link.ts: connect, connected, disconnect, errors), optional publicKey on the v2 heartbeat, ed25519PublicFromPem / signLink / verifyLink, JSON Schema and samples for each |
contracts@1.4.0 |
crosscode-platform packages/seo |
New (§5) | Not tagged on its own: a workspace, versioned with its first user like ui |
crosscode-platform apps/events |
§1–§6. Migrations: ProductLink, FeedEntry, ImportedEvent. New deps: @crosscode/contracts, @crosscode/seo (workspace), react-markdown |
events@2.4.0 |
crosscode-platform docs/ |
hub-protocol.md §6 (heartbeat publicKey, moving to v2), ROADMAP §9 phase 2 marked done, HANDOVER |
— |
events-hub |
v2 heartbeat accepts and saves publicKey (409 PUBLIC_KEY_MISMATCH for a different one), Clear public key button on the install page (2FA again, audited), vendored contracts-1.4.0.tgz, its copy of hub-protocol.md |
Hub v2.2.0 |
crosscode-site |
"Works with the Church Website and App" on the Cross Events page, marked coming (src/data/cross-events.mjs) |
v1.4.0 |
New .env variables: none planned. If one turns up, it goes in all three templates
(HANDOVER, "Things to remember").
8. Testing
Unit and integration (Jest, in npm run check):
- contracts:
crosscode.link/1samples parse;signLink/verifyLinkrefuse a changed body, another key, a staleissuedAtand a replayed nonce. - seo:
eventJsonLd/churchJsonLdfor every contract sample; the old-vs-new snapshot (§5). - Events, Hub client: the v2 heartbeat body passes
hub.heartbeatRequestSchema; the key pair is made once;publicKeystops being sent after the ack; falling back to v1 onUNSUPPORTED_PROTOCOL. - Events, feed: every e2e seed event passes
eventSchema; hidden, inactive, not-yet-live and kids/volunteer data never appear;updatedSincereturns exactly what changed, including go-live, deadline and selling out with noEventrow change; deactivating puts it indeleted; feed off →404 FEED_OFF. - Events, Connect: accepted from a listed sibling; refused when not listed, with a key other than the listed one, stale, replayed or for another install; disconnect from either side.
- Events, sync: a sample Website feed with one invalid event (the rest import, the bad one is
logged); the source down (last copy kept, error shown);
event.changedwith a bad signature refused; imported events never in our own feed. - Hub (
events-hub): v2 heartbeat with a key saves it; the same key is fine; a different one is409; Clear lets a new one in.
e2e (Playwright, apps/events/e2e): a small fake "Website" (a fixture server in the e2e
setup serving samples/event-feed.json and answering Connect) to click through Linked products
→ Connect → Show events from → the imported event on /events → its page with the canonical link
and the origin's button; sitemap.xml doesn't list it. The §11 checks (title, description,
canonical, og:image, one <h1>, JSON-LD parses) on the event page and the imported event page.
On the VM (as in AGENT-1.0-PLAN §13), before tagging: two installs of Events can't be linked (one per product per customer), so the VM run uses the fake Website from e2e as a second site behind frp, against Hub 2.2.0. Check: an existing 2.3.x install updated through the agent moves itself to v2 and appears with a key on the Hub; Connect works across the two servers; turning the fake Website off keeps its events showing with "last synced".
9. Releasing and rolling it out
Order, each with its CHANGELOG entry and npm run check first:
contracts@1.4.0(platform), then the packed.tgzintoevents-hub/backend/vendor/.- Hub
v2.2.0, deployed (events-hub/deployment.md). events@2.4.0(itsWHATS-NEW.mdheading needs norequires: against a Hub before 2.2.0 it still works, only Linked products stays empty).- crosscode-site
v1.4.0, deployed. - Each church updated through the Hub (a scheduled update, ROLLOUT-1.0 §5).
Decisions
Proposed in this plan, to confirm before building:
- Moving to v2 needs no admin action: the v2 heartbeat carries the install's public key (optional field), instead of re-registering with the licence key (§1). Needs Hub 2.2.0.
- Connect needs no approval on the other side, and trust comes from each side's own cached Hub list (§2).
- Publish my events is on by default (it only shares what the public pages already show); Show events from is off by default per link.
- The feed is built from a
FeedEntrytable, not straight fromEvent, so go-live, deadlines and selling out are reported as changes (§3). - Imported events get their own page in Events with a canonical link to the origin, rather than linking straight out from the list (§4).
- Ended events stay out of
deleted; a full fetch covers events that ended up to 30 days ago.
Still open
- Who owns the church profile (
crosscode.church/1) once there's more than one product? Events builds one from its own settings for its JSON-LD in 2.4.0, but doesn't serve it to siblings. The Website (phase 4) is the natural owner; decide before phase 4. - Event
summaryandtagsgo out empty because Events has no such fields. Add them in a later 2.x if the Website's event cards need them. - A "cancelled" state in Events (shown as cancelled rather than disappearing) would map to
status: "cancelled". Not in 2.4.0.