Files
crosscode-platform/packages/contracts
joshuaandClaude Opus 5.5 90a98a4306 contracts 1.3.0: agent jobs, reports, stats, join/poll, env templates, church export
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>
2026-11-17 12:02:24 +02:00
..

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