diff --git a/packages/contracts/package.json b/packages/contracts/package.json index f2b0daa..87a37bf 100644 --- a/packages/contracts/package.json +++ b/packages/contracts/package.json @@ -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", diff --git a/packages/contracts/samples/church-changed.json b/packages/contracts/samples/church-changed.json new file mode 100644 index 0000000..d0040ed --- /dev/null +++ b/packages/contracts/samples/church-changed.json @@ -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" +} diff --git a/packages/contracts/schemas/church-changed.json b/packages/contracts/schemas/church-changed.json new file mode 100644 index 0000000..41da10c --- /dev/null +++ b/packages/contracts/schemas/church-changed.json @@ -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" + ] +} diff --git a/packages/contracts/scripts/json-schemas.cjs b/packages/contracts/scripts/json-schemas.cjs index 68789a3..91783b6 100644 --- a/packages/contracts/scripts/json-schemas.cjs +++ b/packages/contracts/scripts/json-schemas.cjs @@ -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, diff --git a/packages/contracts/src/church.ts b/packages/contracts/src/church.ts index 911a51f..5c7791e 100644 --- a/packages/contracts/src/church.ts +++ b/packages/contracts/src/church.ts @@ -97,3 +97,20 @@ export const churchSchema = z export type Church = z.infer; export type Campus = z.infer; export type ServiceTime = z.infer; + +/** + * 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; diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts index d75dbc4..566c8d4 100644 --- a/packages/contracts/src/index.ts +++ b/packages/contracts/src/index.ts @@ -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"; diff --git a/packages/contracts/src/oidc.ts b/packages/contracts/src/oidc.ts new file mode 100644 index 0000000..5dcb453 --- /dev/null +++ b/packages/contracts/src/oidc.ts @@ -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 `/api/oidc`; discovery is at `/.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}`, + }; +} diff --git a/packages/contracts/src/signing.ts b/packages/contracts/src/signing.ts index 4036742..4de824e 100644 --- a/packages/contracts/src/signing.ts +++ b/packages/contracts/src/signing.ts @@ -283,3 +283,12 @@ export function verifyLink(message: Record, 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()); +} diff --git a/packages/contracts/tests/hub-signing.test.ts b/packages/contracts/tests/hub-signing.test.ts index b3753da..b5ab420 100644 --- a/packages/contracts/tests/hub-signing.test.ts +++ b/packages/contracts/tests/hub-signing.test.ts @@ -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", + }); + }); +}); diff --git a/packages/contracts/tests/json-schemas.test.ts b/packages/contracts/tests/json-schemas.test.ts index 984d614..5b7bba5 100644 --- a/packages/contracts/tests/json-schemas.test.ts +++ b/packages/contracts/tests/json-schemas.test.ts @@ -36,6 +36,7 @@ const SAMPLE_SCHEMA: Record = { "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", diff --git a/packages/contracts/tests/samples.test.ts b/packages/contracts/tests/samples.test.ts index 731b229..2527b57 100644 --- a/packages/contracts/tests/samples.test.ts +++ b/packages/contracts/tests/samples.test.ts @@ -8,6 +8,7 @@ import { eventFeedSchema, eventSchema, hub, + churchChangedSchema, linkConnectSchema, linkConnectedSchema, linkDisconnectSchema, @@ -39,6 +40,7 @@ const SCHEMAS: Record = { "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,