- crosscode.event/1 and crosscode.event-feed/1 (feed, event.changed webhook), with session and registration rules; parseEventFeed skips and reports bad events instead of failing the whole feed. - crosscode.church/1: branding, campuses, service times, contact, links. - crosscode.identity/1: sign-in claims and the user.updated / user.deleted / user.export back-channel calls and replies. - Sign-in return helpers (isSafeReturnPath, encodeState/decodeState, isRegisteredRedirectUri) so every product returns people to the page they came from in the same safe way. - Hub protocol v2: product on register/heartbeat, stats per product, install public key, linked products, customerId/product in licences. - @crosscode/contracts/signing (Node only): the Hub's HMAC scheme. - Samples for every contract in samples/, checked by the tests (120). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@crosscode/contracts
Everything that crosses between Cross Code products is defined once, here (ROADMAP-v3 §2):
zod schemas, TypeScript types and sample payloads (samples/). Every product, including Cross
Events and the Hub, uses it, so the key fields are the same in every product's JSON.
| Contract | Schema name | Used for | Source |
|---|---|---|---|
| Event | crosscode.event/1 |
One event, as every product publishes and reads it | src/event.ts |
| Event feed | crosscode.event-feed/1 |
GET /api/feed/v1/events?updatedSince= and the event.changed webhook |
src/event.ts |
| Church | crosscode.church/1 |
The church profile: name, branding, campuses, service times, contact details, product links | src/church.ts |
| Identity | crosscode.identity/1 |
Accounts' sign-in claims and back-channel calls (user.updated, user.deleted, user.export) and their replies |
src/identity.ts |
| Sign-in return | — | The return-path check and OIDC state every product uses (ROADMAP-v3 §3) |
src/return-to.ts |
| Hub protocol v2 | protocolVersion: 2 |
Register, heartbeat (stats per product), linked products, update requests, AI, licence token | src/hub.ts (exported as hub) |
| Signing | — | HMAC request signing for the Hub and for product links (Node only) | src/signing.ts (@crosscode/contracts/signing) |
Using it
import { eventSchema, parseEventFeed, eventKey, hub } from "@crosscode/contracts";
import { verify, LINK_HEADERS } from "@crosscode/contracts/signing"; // Node only
const result = parseEventFeed(await res.json());
if (result.ok) {
for (const event of result.feed.events) upsert(eventKey(event), event);
for (const bad of result.rejected) log.warn("Skipped an event from the feed", bad);
}
- Parse at the edge:
schema.safeParse(body)on everything that comes in, and build what goes out with the types (CrosscodeEvent,Church,hub.HeartbeatRequest, …). - Feeds: use
parseEventFeed. A bad event is skipped and reported, never blocking the rest. - Unknown fields are dropped, not refused, so a newer producer never breaks an older consumer.
Sign-in return (ROADMAP-v3 §3)
import { encodeState, decodeState, safeReturnPath, isRegisteredRedirectUri } from "@crosscode/contracts";
// Product, before redirecting to Accounts:
const nonce = randomBase64Url(24); // also set as an HttpOnly cookie
const state = encodeState({ nonce, returnTo: req.originalUrl });
// Product, on /auth/callback:
const s = decodeState(req.query.state);
if (!s || s.nonce !== req.cookies.signInNonce) return res.redirect("/");
res.redirect(s.returnTo); // always a safe same-site path
// Accounts, on the authorisation request:
if (!isRegisteredRedirectUri(params.redirect_uri, client.redirectUris)) refuse();
isSafeReturnPath accepts a path on the same site only (a single leading /, no scheme or host,
no \, control characters or whitespace, even after percent-decoding). Anything else falls back
to the product's home page.
Signing
hex(HMAC-SHA256(secret, timestamp + "." + rawBody)), the same scheme as the Hub heartbeat, with
a five-minute clock window. HUB_HEADERS (X-Hub-Install, X-Hub-Timestamp, X-Hub-Signature)
for install → Hub; LINK_HEADERS (X-Crosscode-Sender, -Timestamp, -Signature) for
event.changed webhooks and Accounts back-channel calls, with the secret set up by Connect.
Verify the raw bytes before parsing the JSON.
Versioning
- Every payload carries its
schemaname:crosscode.<name>/<major>(parseSchemaName,isSchema). - Adding an optional field keeps the version. Consumers ignore fields they don't know.
- Removing or renaming a field, adding a value to an enum, or changing a meaning needs a new
major (
/2). The old one is served alongside it until every install has updated. - Hub protocol: the Hub accepts the current and the previous
protocolVersion(HUB_PROTOCOL_VERSIONS).
Installing
Published to Gitea's package registry. In the consuming repo's .npmrc:
@crosscode:registry=https://c-git.crosscode.co.za/api/packages/joshua/npm/
Works with both require (Cross Events backend, Hub) and import (Next.js apps).