Files
crosscode-platform/packages/contracts
joshuaandClaude Opus 5.5 ea1575f716 Contracts: event, event feed, church, identity, sign-in return, Hub protocol v2
- 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>
2026-11-04 09:47:40 +02:00
..

@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 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).