Files
crosscode-platform/packages/contracts/README.md
T
joshuaandClaude Opus 5.5 9e94c82502 Contracts 1.0.0: generated JSON Schema for every contract
- schemas/: JSON Schema (draft 2020-12) generated from the zod schemas by
  npm run build (scripts/json-schemas.cjs), exported as
  @crosscode/contracts/schemas/*
- Test: files match the zod schemas, every sample passes them (Ajv)
- Version 1.0.0, CHANGELOG and README

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 14:30:37 +02:00

91 lines
4.8 KiB
Markdown

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