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:
@@ -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,
|
||||
|
||||
@@ -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>;
|
||||
|
||||
@@ -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";
|
||||
|
||||
@@ -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}`,
|
||||
};
|
||||
}
|
||||
@@ -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());
|
||||
}
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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,
|
||||
|
||||
Reference in New Issue
Block a user