# @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 ```ts 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) ```ts 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./` (`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).