Jobs of fixed types with strict argument schemas, signed by the Hub with Ed25519 over canonical JSON. Agent requests signed with the server's Ed25519 key. Config sealed to the server's X25519 key (X25519 + HKDF + AES-256-GCM; Node has no XSalsa20). Exports encrypted with a key that only travels in the download link. 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, JSON Schema (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.
JSON Schema
schemas/ has a JSON Schema (draft 2020-12) for every contract, for consumers that don't use
TypeScript or zod (e.g. @crosscode/contracts/schemas/event.json). They are generated from the
zod schemas by npm run build; commit them with the change (a test fails when they're out of
date). They allow unknown fields, like the zod schemas. The zod schemas stay the source of truth:
a few checks can't be written in JSON Schema (e.g. startsAt / endsAt matching the sessions,
only Cross Events using registration.mode: "origin"), so use the zod schemas where you can.
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).