Contracts 1.5.0: OIDC client paths, client secret from the link, church.changed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-18 13:15:27 +02:00
co-authored by Claude Opus 5.5
parent 6c284099ef
commit 45c6539bf1
11 changed files with 137 additions and 2 deletions
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/contracts",
"version": "1.4.0",
"version": "1.5.0",
"description": "The shared JSON formats used by every Cross Code product: zod schemas, JSON Schema, TypeScript types and sample payloads",
"license": "UNLICENSED",
"type": "commonjs",
@@ -0,0 +1,6 @@
{
"schema": "crosscode.church/1",
"type": "church.changed",
"occurredAt": "2026-11-20T10:00:00.000Z",
"updatedAt": "2026-11-20T09:59:58.000Z"
}
@@ -0,0 +1,31 @@
{
"$id": "https://c-git.crosscode.co.za/joshua/crosscode-platform/raw/branch/main/packages/contracts/schemas/church-changed.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"schema": {
"type": "string",
"const": "crosscode.church/1"
},
"type": {
"type": "string",
"const": "church.changed"
},
"occurredAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
},
"required": [
"schema",
"type",
"occurredAt",
"updatedAt"
]
}
@@ -52,6 +52,7 @@ function contracts(c) {
"agent-job-config": c.agent.jobConfigSchema,
"env-template": c.agent.envTemplateSchema,
"church-export": c.churchExportSchema,
"church-changed": c.churchChangedSchema,
"link-connect": c.linkConnectSchema,
"link-connected": c.linkConnectedSchema,
"link-disconnect": c.linkDisconnectSchema,
+17
View File
@@ -97,3 +97,20 @@ export const churchSchema = z
export type Church = z.infer<typeof churchSchema>;
export type Campus = z.infer<typeof campusSchema>;
export type ServiceTime = z.infer<typeof serviceTimeSchema>;
/**
* Where the church profile lives (contracts 1.5.0): **Accounts owns it** (docs/ACCOUNTS-1.0-PLAN.md
* §7, decision 1) and serves it publicly at `profile`; products read it from there. When it
* changes, Accounts sends `church.changed` (signed with the link's secret, `LINK_HEADERS`) to
* each linked product at `changed`, which then fetches the profile again.
*/
export const CHURCH_PATHS = { profile: "/api/church/v1", changed: "/api/church/v1/changed" } as const;
/** The `church.changed` webhook: a hint to fetch `GET /api/church/v1` again. */
export const churchChangedSchema = z.object({
schema: z.literal(CHURCH_SCHEMA),
type: z.literal("church.changed"),
occurredAt: dateTimeSchema,
updatedAt: dateTimeSchema,
});
export type ChurchChanged = z.infer<typeof churchChangedSchema>;
+1
View File
@@ -9,6 +9,7 @@ export * from "./church";
export * from "./identity";
export * from "./return-to";
export * from "./link";
export * from "./oidc";
export * as hub from "./hub";
export * as agent from "./agent";
export * from "./church-export";
+49
View File
@@ -0,0 +1,49 @@
/**
* Signing in through Accounts (contracts 1.5.0, docs/ACCOUNTS-1.0-PLAN.md §3–5).
*
* Every product is registered with its church's Accounts by **Connect** (`crosscode.link/1`): the
* product's Hub install id is its `client_id`, its client secret is derived from the link's secret
* (`oidcClientSecret` in `@crosscode/contracts/signing`), and its addresses are these fixed paths on
* the product's own address, so nothing is typed in and only exact matches are accepted.
*/
/** On the product's address. */
export const OIDC_CLIENT_PATHS = {
/** `redirect_uri`: the code comes back here, with the `state` the product sent. */
callback: "/api/auth/callback",
/** `post_logout_redirect_uri`: where signing out ends. */
postLogout: "/",
/** `backchannel_logout_uri`: Accounts tells the product a session ended (OIDC Back-Channel Logout). */
backchannelLogout: "/api/auth/backchannel-logout",
} as const;
/** On Accounts' address. */
export const OIDC_PROVIDER_PATHS = {
/** The issuer is `<accounts url>/api/oidc`; discovery is at `<issuer>/.well-known/openid-configuration`. */
issuer: "/api/oidc",
} as const;
/** Where a product takes Accounts' back-channel calls (`crosscode.identity/1`: user.updated, user.deleted, user.export). */
export const ACCOUNTS_CALL_PATH = "/api/accounts/v1/events";
/** The scopes a product asks for. `crosscode` adds news consent, the 2FA method and the notice version. */
export const OIDC_SCOPES = ["openid", "profile", "email", "phone", "crosscode"] as const;
/** `acr_values` a product sends to require 2FA on this sign-in (e.g. for its staff roles). */
export const ACR_MFA = "mfa";
export interface OidcClientAddresses {
redirectUri: string;
postLogoutRedirectUri: string;
backchannelLogoutUri: string;
}
/** The exact addresses registered for a product at `productUrl` (its address as the Hub lists it). */
export function oidcClientAddresses(productUrl: string): OidcClientAddresses {
const base = productUrl.replace(/\/+$/, "");
return {
redirectUri: `${base}${OIDC_CLIENT_PATHS.callback}`,
postLogoutRedirectUri: `${base}${OIDC_CLIENT_PATHS.postLogout}`,
backchannelLogoutUri: `${base}${OIDC_CLIENT_PATHS.backchannelLogout}`,
};
}
+9
View File
@@ -283,3 +283,12 @@ export function verifyLink(message: Record<string, unknown>, publicKeyPem: strin
}
return ed25519Verify(raw, jobSigningInput(message), message.signature) ? { ok: true } : { ok: false, code: "BAD_SIGNATURE" };
}
/**
* A product's OIDC client secret at its church's Accounts (contracts 1.5.0): derived from the
* secret of the product's link with Accounts, so Connect sets up both and there's no second secret
* to exchange or store. base64url of HMAC-SHA256(linkSecret, "crosscode.oidc-client/1").
*/
export function oidcClientSecret(linkSecret: string): string {
return b64u(createHmac("sha256", linkSecret).update("crosscode.oidc-client/1").digest());
}
+19 -1
View File
@@ -1,5 +1,5 @@
import { createHmac, generateKeyPairSync } from "node:crypto";
import { hub, linkConnectSchema, linkConnectedSchema } from "../src";
import { hub, linkConnectSchema, linkConnectedSchema, oidcClientAddresses } from "../src";
import * as s from "../src/signing";
import { HUB_HEADERS, LINK_HEADERS, sign, signedHeaders, verify } from "../src/signing";
import { sample } from "./helpers";
@@ -139,3 +139,21 @@ describe("product links (crosscode.link/1)", () => {
expect(hub.heartbeatRequestSchema.safeParse({ ...sample("hub-heartbeat-events.json"), publicKey: "nope" }).success).toBe(false);
});
});
describe("signing in through Accounts (contracts 1.5.0)", () => {
it("derives the OIDC client secret from the link secret, stably and per link", () => {
const a = s.newLinkSecret();
expect(s.oidcClientSecret(a)).toBe(s.oidcClientSecret(a));
expect(s.oidcClientSecret(a)).toMatch(/^[A-Za-z0-9_-]{43}$/);
expect(s.oidcClientSecret(a)).not.toBe(s.oidcClientSecret(s.newLinkSecret()));
expect(s.oidcClientSecret(a)).not.toBe(a);
});
it("gives every product the same fixed addresses", () => {
expect(oidcClientAddresses("https://www.hope.co.za/")).toEqual({
redirectUri: "https://www.hope.co.za/api/auth/callback",
postLogoutRedirectUri: "https://www.hope.co.za/",
backchannelLogoutUri: "https://www.hope.co.za/api/auth/backchannel-logout",
});
});
});
@@ -36,6 +36,7 @@ const SAMPLE_SCHEMA: Record<string, string> = {
"hub-heartbeat-response.json": "hub-heartbeat-response",
"hub-licence-payload.json": "hub-licence-payload",
"church-export.json": "church-export",
"church-changed.json": "church-changed",
"link-connect.json": "link-connect",
"link-connected.json": "link-connected",
"link-disconnect.json": "link-disconnect",
+2
View File
@@ -8,6 +8,7 @@ import {
eventFeedSchema,
eventSchema,
hub,
churchChangedSchema,
linkConnectSchema,
linkConnectedSchema,
linkDisconnectSchema,
@@ -39,6 +40,7 @@ const SCHEMAS: Record<string, z.ZodType> = {
"hub-heartbeat-response.json": hub.heartbeatResponseSchema,
"hub-licence-payload.json": hub.licencePayloadSchema,
"church-export.json": churchExportSchema,
"church-changed.json": churchChangedSchema,
"link-connect.json": linkConnectSchema,
"link-connected.json": linkConnectedSchema,
"link-disconnect.json": linkDisconnectSchema,