- 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>
91 lines
4.8 KiB
Markdown
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).
|