Files

@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 schema name: 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).