@orthacms/identity-provider-oidc 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ortha CMS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @orthacms/identity-provider-oidc
+
+Part of [Ortha CMS](https://github.com/ortha-source/ortha-cms).
+
+```sh
+npm install @orthacms/identity-provider-oidc
+```

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createOidcProvider } from './lib/oidc-provider';
+export type { OidcProviderConfig, OidcEndpoints } from './lib/config';
+export { createAuth0Provider, createEntraProvider, createGoogleProvider, createKeycloakProvider, createOktaProvider } from './lib/presets';
+export type { PresetConfig } from './lib/presets';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,YAAY,EACR,kBAAkB,EAClB,aAAa,EAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EACH,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,EACtB,kBAAkB,EACrB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOktaProvider = exports.createKeycloakProvider = exports.createGoogleProvider = exports.createEntraProvider = exports.createAuth0Provider = exports.createOidcProvider = void 0;
+var oidc_provider_1 = require("./lib/oidc-provider");
+Object.defineProperty(exports, "createOidcProvider", { enumerable: true, get: function () { return oidc_provider_1.createOidcProvider; } });
+var presets_1 = require("./lib/presets");
+Object.defineProperty(exports, "createAuth0Provider", { enumerable: true, get: function () { return presets_1.createAuth0Provider; } });
+Object.defineProperty(exports, "createEntraProvider", { enumerable: true, get: function () { return presets_1.createEntraProvider; } });
+Object.defineProperty(exports, "createGoogleProvider", { enumerable: true, get: function () { return presets_1.createGoogleProvider; } });
+Object.defineProperty(exports, "createKeycloakProvider", { enumerable: true, get: function () { return presets_1.createKeycloakProvider; } });
+Object.defineProperty(exports, "createOktaProvider", { enumerable: true, get: function () { return presets_1.createOktaProvider; } });

package/dist/lib/claims.d.ts

@@ -0,0 +1,16 @@
+import { type SsoProfile } from '@orthacms/identity-domain';
+import type { ResolvedOidcConfig } from './config';
+/** An identity token's verified payload, as far as this adapter reads it. */
+export type IdTokenClaims = Record<string, unknown>;
+/**
+ * Turns verified claims into the normalised profile the CMS resolves accounts
+ * with.
+ *
+ * Every decision here is about being **faithful** rather than convenient: the
+ * subject is `sub` and only `sub`, the email is whichever configured claim is
+ * present first, and `email_verified` is reported exactly as the provider sent
+ * it. The one place an operator can influence the answer is
+ * `emailVerifiedWhenAbsent`, and only when the claim is missing entirely.
+ */
+export declare function toProfile(claims: IdTokenClaims, config: ResolvedOidcConfig): SsoProfile;
+//# sourceMappingURL=claims.d.ts.map

package/dist/lib/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../../src/lib/claims.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAClF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACrB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,kBAAkB,GAC3B,UAAU,CA2BZ"}

package/dist/lib/claims.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toProfile = toProfile;
+const identity_domain_1 = require("@orthacms/identity-domain");
+/**
+ * Turns verified claims into the normalised profile the CMS resolves accounts
+ * with.
+ *
+ * Every decision here is about being **faithful** rather than convenient: the
+ * subject is `sub` and only `sub`, the email is whichever configured claim is
+ * present first, and `email_verified` is reported exactly as the provider sent
+ * it. The one place an operator can influence the answer is
+ * `emailVerifiedWhenAbsent`, and only when the claim is missing entirely.
+ */
+function toProfile(claims, config) {
+    const subject = claims['sub'];
+    if (typeof subject !== 'string' || subject === '') {
+        throw new identity_domain_1.SsoVerificationError('the identity token carries no `sub`, so there is nothing stable to key a link on');
+    }
+    const email = firstString(claims, config.emailClaims);
+    if (!email) {
+        throw new identity_domain_1.SsoVerificationError(`the identity token carries no address in ${config.emailClaims.join(', ')} — request the "email" scope, or point emailClaims at the claim this provider uses`);
+    }
+    return {
+        subject,
+        email,
+        emailVerified: readEmailVerified(claims, config),
+        name: readName(claims),
+        ...(config.groupsClaim
+            ? { groups: readGroups(claims[config.groupsClaim]) }
+            : {}),
+        sessionId: typeof claims['sid'] === 'string' ? claims['sid'] : null
+    };
+}
+/**
+ * Whether the provider vouches for the address.
+ *
+ * Three cases, and the middle one is the whole point:
+ *
+ * - the claim is present and boolean → that value, always, including `false`;
+ * - the claim is present as the string `"true"`/`"false"` → some providers send
+ *   it that way, and reading `"false"` as truthy would be the worst possible
+ *   parsing bug to have here;
+ * - the claim is absent → `emailVerifiedWhenAbsent`, which defaults to `false`
+ *   and can only be turned on by an operator asserting that their directory is
+ *   authoritative.
+ */
+function readEmailVerified(claims, config) {
+    const raw = claims['email_verified'];
+    if (typeof raw === 'boolean') {
+        return raw;
+    }
+    if (raw === 'true') {
+        return true;
+    }
+    if (raw === 'false') {
+        return false;
+    }
+    return config.emailVerifiedWhenAbsent;
+}
+/** A display name from the usual claims, or `null`. */
+function readName(claims) {
+    const name = claims['name'];
+    if (typeof name === 'string' && name.trim()) {
+        return name.trim();
+    }
+    const given = claims['given_name'];
+    const family = claims['family_name'];
+    const joined = [given, family]
+        .filter((part) => typeof part === 'string' && !!part.trim())
+        .join(' ')
+        .trim();
+    return joined || null;
+}
+/**
+ * Group claims, normalised to a string array.
+ *
+ * Providers disagree on the shape: an array (the common case), a single string
+ * (one group), or a space-separated string (a few). Anything else is dropped
+ * rather than coerced — a group list nobody can read is safer empty than
+ * guessed at, because the next phase maps these to roles.
+ */
+function readGroups(raw) {
+    if (Array.isArray(raw)) {
+        return raw.filter((item) => typeof item === 'string');
+    }
+    if (typeof raw === 'string' && raw.trim()) {
+        return raw.trim().split(/\s+/);
+    }
+    return [];
+}
+/** The first configured claim that holds a non-empty string, lower-cased. */
+function firstString(claims, names) {
+    for (const name of names) {
+        const value = claims[name];
+        if (typeof value === 'string' && value.trim()) {
+            return value.trim().toLowerCase();
+        }
+    }
+    return null;
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,130 @@
+/** The endpoints an adapter needs, when discovery is unavailable or overridden. */
+export interface OidcEndpoints {
+    /** Where the browser is sent to authorize. */
+    authorization: string;
+    /** Where the authorization code is exchanged. */
+    token: string;
+    /** Where the signing keys are published. */
+    jwks: string;
+    /** RP-initiated logout, when the provider offers one. */
+    endSession?: string;
+}
+/** How one OIDC identity provider is reached and read. */
+export interface OidcProviderConfig {
+    /**
+     * The issuer, exactly as it appears in the `iss` claim — e.g.
+     * `https://accounts.google.com`. Discovery is fetched from
+     * `<issuer>/.well-known/openid-configuration`, and every identity token is
+     * verified against this value.
+     *
+     * It is compared byte for byte, because that is what the check is worth:
+     * an issuer that "looks right" is exactly what a malicious token supplies.
+     */
+    issuer: string;
+    /** The client id registered with the provider. */
+    clientId: string;
+    /**
+     * The client secret, when the provider issued one.
+     *
+     * Optional because PKCE makes a public client viable, and some
+     * deployments prefer one. When present it is sent with HTTP Basic
+     * (`client_secret_basic`), which the spec prefers and every provider here
+     * accepts.
+     */
+    clientSecret?: string;
+    /** Button text on the sign-in page. Defaults to the issuer's host. */
+    label?: string;
+    /**
+     * Scopes to request. Defaults to `openid profile email` — `openid` is
+     * mandatory, and without `email` there is nothing to match an account on.
+     */
+    scopes?: readonly string[];
+    /**
+     * Extra authorization parameters, verbatim. This is where a provider's own
+     * knobs go: Google's `hd` to pin a hosted domain, `prompt=select_account`,
+     * Okta's `idp`. Reserved protocol parameters cannot be overridden here.
+     */
+    authorizationParams?: Readonly<Record<string, string>>;
+    /**
+     * Endpoints to use instead of discovery. Supply all three to skip the
+     * discovery request entirely — useful for a provider behind a network
+     * whose discovery document is not reachable from the CMS.
+     */
+    endpoints?: OidcEndpoints;
+    /**
+     * The claim carrying group membership, when the deployment maps groups to
+     * roles. Unset means groups are not read at all — the CMS should not
+     * collect a claim nobody asked it to use.
+     */
+    groupsClaim?: string;
+    /**
+     * The claim to read the email from, in order of preference. Defaults to
+     * `email`, then `preferred_username`, then `upn` — the three spellings
+     * that cover the shipped presets.
+     */
+    emailClaims?: readonly string[];
+    /**
+     * Whether to treat an address as verified when the provider sends **no**
+     * `email_verified` claim at all.
+     *
+     * Defaults to `false`, and the default is the safe one: `emailVerified` is
+     * the only gate on a first sign-in claiming an existing account, so
+     * inventing a `true` would turn "sign in with your work account" into "sign
+     * in with any account that types the right address".
+     *
+     * Some providers — Microsoft Entra ID most notably — simply never emit the
+     * claim. Setting this is an operator asserting that *this* directory is
+     * authoritative for the addresses it reports. That assertion may be
+     * perfectly true; it is just not something an adapter may make on the
+     * operator's behalf. A provider that sends `email_verified: false` is
+     * always taken at its word, whatever this is set to.
+     */
+    emailVerifiedWhenAbsent?: boolean;
+    /**
+     * How long a discovery document is reused, in milliseconds. Defaults to one
+     * hour. Signing keys are cached separately and refetched on an unknown
+     * `kid`, so this only bounds how stale an *endpoint* can be.
+     */
+    discoveryCacheMs?: number;
+    /**
+     * Accepted clock skew when checking `exp` and `iat`, in seconds. Defaults
+     * to 60.
+     *
+     * Small on purpose. Some tolerance is necessary — two machines are never
+     * exactly in step — but a generous one silently extends the life of every
+     * token the provider issues, which is the opposite of what these claims are
+     * for.
+     */
+    clockToleranceSeconds?: number;
+    /**
+     * The `fetch` used for discovery and the token exchange. Injected so a test
+     * can drive the adapter with no network; production leaves it unset and
+     * gets the platform's.
+     */
+    fetch?: typeof globalThis.fetch;
+}
+/** Defaults applied once, so no code path has to remember them. */
+export interface ResolvedOidcConfig extends OidcProviderConfig {
+    label: string;
+    scopes: readonly string[];
+    emailClaims: readonly string[];
+    emailVerifiedWhenAbsent: boolean;
+    discoveryCacheMs: number;
+    clockToleranceSeconds: number;
+    fetch: typeof globalThis.fetch;
+}
+/** The scopes requested when a deployment names none. */
+export declare const DEFAULT_SCOPES: readonly ["openid", "profile", "email"];
+/** The claims an email is read from, in order, when a deployment names none. */
+export declare const DEFAULT_EMAIL_CLAIMS: readonly ["email", "preferred_username", "upn"];
+/**
+ * Applies the defaults and rejects a configuration that cannot work.
+ *
+ * Eager, at construction, like `CopilotPlugin`'s option check: an issuer that
+ * is not a URL or a missing client id would otherwise surface as a failed
+ * sign-in — and every failed SSO sign-in looks identical to every other, by
+ * design, so the one error a person sees would say nothing about the typo that
+ * caused it.
+ */
+export declare function resolveOidcConfig(config: OidcProviderConfig): ResolvedOidcConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/lib/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC1B,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IAC/B;;;;;;;;OAQG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC;;;;;;;;;;;;;;;OAeG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACnC;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,uBAAuB,EAAE,OAAO,CAAC;IACjC,gBAAgB,EAAE,MAAM,CAAC;IACzB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CAClC;AAED,yDAAyD;AACzD,eAAO,MAAM,cAAc,yCAA0C,CAAC;AAEtE,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,iDAIvB,CAAC;AAEX;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC7B,MAAM,EAAE,kBAAkB,GAC3B,kBAAkB,CAoCpB"}

package/dist/lib/config.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_EMAIL_CLAIMS = exports.DEFAULT_SCOPES = void 0;
+exports.resolveOidcConfig = resolveOidcConfig;
+/** The scopes requested when a deployment names none. */
+exports.DEFAULT_SCOPES = ['openid', 'profile', 'email'];
+/** The claims an email is read from, in order, when a deployment names none. */
+exports.DEFAULT_EMAIL_CLAIMS = [
+    'email',
+    'preferred_username',
+    'upn'
+];
+/**
+ * Applies the defaults and rejects a configuration that cannot work.
+ *
+ * Eager, at construction, like `CopilotPlugin`'s option check: an issuer that
+ * is not a URL or a missing client id would otherwise surface as a failed
+ * sign-in — and every failed SSO sign-in looks identical to every other, by
+ * design, so the one error a person sees would say nothing about the typo that
+ * caused it.
+ */
+function resolveOidcConfig(config) {
+    let issuerUrl;
+    try {
+        issuerUrl = new URL(config.issuer);
+    }
+    catch {
+        throw new Error(`createOidcProvider needs an absolute issuer URL; got "${config.issuer}".`);
+    }
+    if (issuerUrl.protocol !== 'https:' && issuerUrl.hostname !== 'localhost') {
+        throw new Error(`createOidcProvider refuses the non-HTTPS issuer "${config.issuer}": identity tokens and the client secret would cross the network in clear text. Only localhost is exempt, for development.`);
+    }
+    if (!config.clientId.trim()) {
+        throw new Error('createOidcProvider needs a clientId — it is how the provider knows which application is asking.');
+    }
+    const scopes = config.scopes ?? exports.DEFAULT_SCOPES;
+    if (!scopes.includes('openid')) {
+        throw new Error(`createOidcProvider needs the "openid" scope — without it the provider returns no identity token, and there is nothing to verify. Got: ${scopes.join(' ')}.`);
+    }
+    return {
+        ...config,
+        label: config.label ?? issuerUrl.hostname,
+        scopes,
+        emailClaims: config.emailClaims ?? exports.DEFAULT_EMAIL_CLAIMS,
+        emailVerifiedWhenAbsent: config.emailVerifiedWhenAbsent ?? false,
+        discoveryCacheMs: config.discoveryCacheMs ?? 3_600_000,
+        clockToleranceSeconds: config.clockToleranceSeconds ?? 60,
+        fetch: config.fetch ?? globalThis.fetch
+    };
+}

package/dist/lib/discovery.d.ts

@@ -0,0 +1,47 @@
+import type { OidcEndpoints, ResolvedOidcConfig } from './config';
+/**
+ * Resolves a provider's endpoints, from configuration or from discovery, and
+ * caches the answer.
+ *
+ * **Single-flight.** The in-flight promise is shared, so ten people signing in
+ * during the same second produce one discovery request rather than ten. Without
+ * it, the first traffic after a restart is the moment the CMS is least polite
+ * to the identity provider — which is also the moment an operator is most
+ * likely to be watching.
+ *
+ * The cache holds only the *successful* answer. A failed discovery is not
+ * cached, because caching it would extend a transient outage into a fixed
+ * window during which every sign-in fails for a reason that has already gone
+ * away.
+ */
+export declare class EndpointResolver {
+    private readonly config;
+    private cached;
+    private inFlight;
+    constructor(config: ResolvedOidcConfig);
+    /**
+     * The endpoints already in hand — configured, or from a discovery document
+     * fetched earlier — without fetching one.
+     *
+     * For the synchronous parts of the port. `logoutUrl` is declared sync
+     * because a caller building a redirect has nowhere to await, so it can only
+     * answer from what is already known; before the first sign-in that is
+     * nothing, and `null` is the correct answer then.
+     */
+    cachedEndpoints(): OidcEndpoints | null;
+    /** The endpoints, fetching and caching a discovery document if needed. */
+    endpoints(): Promise<OidcEndpoints>;
+    private discover;
+}
+/**
+ * The well-known discovery URL for an issuer.
+ *
+ * The path is appended to the issuer's own path rather than replacing it —
+ * `https://login.example.com/realms/acme` discovers at
+ * `…/realms/acme/.well-known/openid-configuration`, which is what Keycloak,
+ * Auth0's custom domains and every multi-tenant provider actually serve.
+ * Treating the issuer as an origin is the classic way to make this work against
+ * Google and fail against everything else.
+ */
+export declare function discoveryUrl(issuer: string): string;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/lib/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/lib/discovery.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAWlE;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAgB;IAKb,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,MAAM,CACL;IACT,OAAO,CAAC,QAAQ,CAAuC;gBAE1B,MAAM,EAAE,kBAAkB;IAEvD;;;;;;;;OAQG;IACH,eAAe,IAAI,aAAa,GAAG,IAAI;IAUvC,0EAA0E;IACpE,SAAS,IAAI,OAAO,CAAC,aAAa,CAAC;YAyB3B,QAAQ;CA+CzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/lib/discovery.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EndpointResolver = void 0;
+exports.discoveryUrl = discoveryUrl;
+const identity_domain_1 = require("@orthacms/identity-domain");
+/**
+ * Resolves a provider's endpoints, from configuration or from discovery, and
+ * caches the answer.
+ *
+ * **Single-flight.** The in-flight promise is shared, so ten people signing in
+ * during the same second produce one discovery request rather than ten. Without
+ * it, the first traffic after a restart is the moment the CMS is least polite
+ * to the identity provider — which is also the moment an operator is most
+ * likely to be watching.
+ *
+ * The cache holds only the *successful* answer. A failed discovery is not
+ * cached, because caching it would extend a transient outage into a fixed
+ * window during which every sign-in fails for a reason that has already gone
+ * away.
+ */
+class EndpointResolver {
+    config;
+    cached = null;
+    inFlight = null;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * The endpoints already in hand — configured, or from a discovery document
+     * fetched earlier — without fetching one.
+     *
+     * For the synchronous parts of the port. `logoutUrl` is declared sync
+     * because a caller building a redirect has nowhere to await, so it can only
+     * answer from what is already known; before the first sign-in that is
+     * nothing, and `null` is the correct answer then.
+     */
+    cachedEndpoints() {
+        if (this.config.endpoints) {
+            return this.config.endpoints;
+        }
+        if (this.cached && this.cached.expiresAt > Date.now()) {
+            return this.cached.endpoints;
+        }
+        return null;
+    }
+    /** The endpoints, fetching and caching a discovery document if needed. */
+    async endpoints() {
+        if (this.config.endpoints) {
+            return this.config.endpoints;
+        }
+        if (this.cached && this.cached.expiresAt > Date.now()) {
+            return this.cached.endpoints;
+        }
+        if (this.inFlight) {
+            return this.inFlight;
+        }
+        this.inFlight = this.discover()
+            .then((endpoints) => {
+            this.cached = {
+                endpoints,
+                expiresAt: Date.now() + this.config.discoveryCacheMs
+            };
+            return endpoints;
+        })
+            .finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+    async discover() {
+        const url = discoveryUrl(this.config.issuer);
+        let response;
+        try {
+            response = await this.config.fetch(url, {
+                headers: { accept: 'application/json' }
+            });
+        }
+        catch (error) {
+            throw new identity_domain_1.SsoVerificationError(`the provider's discovery document at ${url} could not be fetched (${error instanceof Error ? error.message : String(error)})`);
+        }
+        if (!response.ok) {
+            throw new identity_domain_1.SsoVerificationError(`the provider's discovery document at ${url} answered ${response.status}`);
+        }
+        const document = (await response.json());
+        // The issuer is checked here as well as on the token, because a
+        // discovery document that names a different issuer means this adapter
+        // is pointed at the wrong place — and the resulting failure would
+        // otherwise appear one step later, as an unexplained token rejection.
+        if (document.issuer !== this.config.issuer) {
+            throw new identity_domain_1.SsoVerificationError(`the discovery document at ${url} names issuer "${String(document.issuer)}", not the configured "${this.config.issuer}"`);
+        }
+        return {
+            authorization: requireUrl(document.authorization_endpoint, 'authorization_endpoint', url),
+            token: requireUrl(document.token_endpoint, 'token_endpoint', url),
+            jwks: requireUrl(document.jwks_uri, 'jwks_uri', url),
+            ...(typeof document.end_session_endpoint === 'string'
+                ? { endSession: document.end_session_endpoint }
+                : {})
+        };
+    }
+}
+exports.EndpointResolver = EndpointResolver;
+/**
+ * The well-known discovery URL for an issuer.
+ *
+ * The path is appended to the issuer's own path rather than replacing it —
+ * `https://login.example.com/realms/acme` discovers at
+ * `…/realms/acme/.well-known/openid-configuration`, which is what Keycloak,
+ * Auth0's custom domains and every multi-tenant provider actually serve.
+ * Treating the issuer as an origin is the classic way to make this work against
+ * Google and fail against everything else.
+ */
+function discoveryUrl(issuer) {
+    return `${issuer.replace(/\/+$/, '')}/.well-known/openid-configuration`;
+}
+/** Reads a required absolute URL out of a discovery document. */
+function requireUrl(value, field, source) {
+    if (typeof value !== 'string' || !value) {
+        throw new identity_domain_1.SsoVerificationError(`the discovery document at ${source} has no usable ${field}`);
+    }
+    return value;
+}

package/dist/lib/oidc-provider.d.ts

@@ -0,0 +1,22 @@
+import { type SsoProvider } from '@orthacms/identity-domain';
+import { type OidcProviderConfig } from './config';
+/**
+ * A generic OpenID Connect adapter: authorization code flow, PKCE, and identity
+ * tokens verified against the provider's published keys.
+ *
+ * One adapter covers most of the market — Okta, Auth0, Keycloak, Google, Entra
+ * ID, Authentik, Zitadel, JumpCloud, Ping and GitLab all speak this. That is
+ * why SSO diverges from the copilot's package-per-vendor shape: the copilot
+ * splits because the *SDKs* differ, and here the wire does not. The named
+ * vendors are presets over this, in `presets.ts`.
+ *
+ * **`jose` does the cryptography.** `createRemoteJWKSet` caches the provider's
+ * keys, refetches on an unknown `kid` (which is how key rotation is survived)
+ * and rate-limits that refetch (which is what stops a stream of junk tokens
+ * from turning this CMS into a load generator aimed at someone else's identity
+ * provider). Hand-rolling JWT and JWKS validation is not where to demonstrate
+ * independence — ADR-0012 permits the dependency here for exactly this reason,
+ * and forbids it in `identity-domain` and `identity-server`.
+ */
+export declare function createOidcProvider(config: OidcProviderConfig): SsoProvider;
+//# sourceMappingURL=oidc-provider.d.ts.map

package/dist/lib/oidc-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc-provider.d.ts","sourceRoot":"","sources":["../../src/lib/oidc-provider.ts"],"names":[],"mappings":"AAOA,OAAO,EAQH,KAAK,WAAW,EAEnB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAuCtE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAC9B,MAAM,EAAE,kBAAkB,GAC3B,WAAW,CA0Rb"}

package/dist/lib/oidc-provider.js

@@ -0,0 +1,260 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOidcProvider = createOidcProvider;
+const node_crypto_1 = require("node:crypto");
+const jose_1 = require("jose");
+const identity_domain_1 = require("@orthacms/identity-domain");
+const claims_1 = require("./claims");
+const config_1 = require("./config");
+const discovery_1 = require("./discovery");
+/**
+ * Protocol parameters an operator's `authorizationParams` may not overwrite.
+ *
+ * Every one of them is either a security control the core owns (`state`,
+ * `nonce`, the PKCE pair) or the thing that decides what flow is running
+ * (`response_type`, `redirect_uri`). A config typo that silently replaced one
+ * would not fail — it would produce a sign-in that works and is not protected.
+ */
+const RESERVED_PARAMS = new Set([
+    'response_type',
+    'client_id',
+    'redirect_uri',
+    'scope',
+    'state',
+    'nonce',
+    'code_challenge',
+    'code_challenge_method'
+]);
+/**
+ * The claim that marks a token as a back-channel logout notification.
+ *
+ * Checked because everything *else* about a logout token matches an identity
+ * token — same issuer, same audience, same signing key. Without this check,
+ * anyone holding a stolen identity token could sign its owner out at will.
+ */
+const BACKCHANNEL_LOGOUT_EVENT = 'http://schemas.openid.net/event/backchannel-logout';
+/**
+ * A generic OpenID Connect adapter: authorization code flow, PKCE, and identity
+ * tokens verified against the provider's published keys.
+ *
+ * One adapter covers most of the market — Okta, Auth0, Keycloak, Google, Entra
+ * ID, Authentik, Zitadel, JumpCloud, Ping and GitLab all speak this. That is
+ * why SSO diverges from the copilot's package-per-vendor shape: the copilot
+ * splits because the *SDKs* differ, and here the wire does not. The named
+ * vendors are presets over this, in `presets.ts`.
+ *
+ * **`jose` does the cryptography.** `createRemoteJWKSet` caches the provider's
+ * keys, refetches on an unknown `kid` (which is how key rotation is survived)
+ * and rate-limits that refetch (which is what stops a stream of junk tokens
+ * from turning this CMS into a load generator aimed at someone else's identity
+ * provider). Hand-rolling JWT and JWKS validation is not where to demonstrate
+ * independence — ADR-0012 permits the dependency here for exactly this reason,
+ * and forbids it in `identity-domain` and `identity-server`.
+ */
+function createOidcProvider(config) {
+    const resolved = (0, config_1.resolveOidcConfig)(config);
+    const endpoints = new discovery_1.EndpointResolver(resolved);
+    const descriptor = Object.freeze({
+        kind: 'oidc',
+        label: resolved.label,
+        callbackMethod: 'GET'
+    });
+    /**
+     * The key set, built once and reused.
+     *
+     * Lazy, because the JWKS URL may come from discovery, and a provider that
+     * is unreachable at boot must not stop the CMS from starting — SSO is one
+     * way in, not the only one.
+     */
+    let keys = null;
+    const keySet = async () => {
+        if (!keys) {
+            const { jwks } = await endpoints.endpoints();
+            keys = (0, jose_1.createRemoteJWKSet)(new URL(jwks), {
+                // A `kid` this set has not seen triggers a refetch, which is
+                // how a rotated signing key is picked up without a restart…
+                cacheMaxAge: 600_000,
+                // …and this is the floor between two such refetches, so a
+                // stream of tokens bearing invented `kid`s cannot turn into a
+                // stream of requests aimed at the provider.
+                cooldownDuration: 30_000,
+                // The same `fetch` the rest of the adapter uses. Without this,
+                // key fetching would quietly bypass a configured HTTP proxy —
+                // and a test's stubbed transport — while discovery and the
+                // token exchange honoured it, which is the kind of split that
+                // works everywhere except the one deployment that needed it.
+                // jose types this hook loosely on purpose; see its own note.
+                [jose_1.customFetch]: resolved.fetch
+            });
+        }
+        return keys;
+    };
+    return {
+        descriptor: () => descriptor,
+        async authorize(request) {
+            const { authorization } = await endpoints.endpoints();
+            const url = new URL(authorization);
+            for (const [key, value] of Object.entries(resolved.authorizationParams ?? {})) {
+                if (RESERVED_PARAMS.has(key)) {
+                    throw new Error(`The OIDC provider "${resolved.label}" tries to set the reserved authorization parameter "${key}". That parameter is either a security control the CMS owns (state, nonce, PKCE) or the one that decides which flow runs — overriding it would produce a sign-in that appears to work and is not protected.`);
+                }
+                url.searchParams.set(key, value);
+            }
+            url.searchParams.set('response_type', 'code');
+            url.searchParams.set('client_id', resolved.clientId);
+            url.searchParams.set('redirect_uri', request.redirectUri);
+            url.searchParams.set('scope', [...new Set([...resolved.scopes, ...(request.scopes ?? [])])].join(' '));
+            url.searchParams.set('state', request.state);
+            url.searchParams.set('nonce', request.nonce);
+            // The challenge, never the verifier: the browser carries this URL,
+            // and the verifier is the half that must not travel with it.
+            url.searchParams.set('code_challenge', challengeFor(request.codeVerifier));
+            url.searchParams.set('code_challenge_method', 'S256');
+            return { url: url.toString() };
+        },
+        async complete(callback) {
+            const { params } = callback;
+            // A provider's own refusal comes back as a parameter, not an HTTP
+            // error, so it has to be read before anything else is attempted.
+            if (typeof params['error'] === 'string' && params['error']) {
+                throw new identity_domain_1.SsoVerificationError(`the provider answered error=${params['error']}${params['error_description']
+                    ? ` (${params['error_description']})`
+                    : ''}`);
+            }
+            const code = params['code'];
+            if (!code) {
+                throw new identity_domain_1.SsoVerificationError('the response carried no authorization code');
+            }
+            const idToken = await exchange(code, callback);
+            const claims = await verify(idToken, callback);
+            return (0, claims_1.toProfile)(claims, resolved);
+        },
+        logoutUrl(request) {
+            // Synchronous by contract, so this answers only from a discovery
+            // document already in hand. Before the first sign-in there is none,
+            // and `null` is the correct answer then: the CMS session ends
+            // either way, and the provider's simply does not.
+            const endSession = endpoints.cachedEndpoints()?.endSession;
+            if (!endSession) {
+                return null;
+            }
+            const url = new URL(endSession);
+            url.searchParams.set('client_id', resolved.clientId);
+            url.searchParams.set('post_logout_redirect_uri', request.returnTo);
+            return url.toString();
+        },
+        async verifyLogoutToken(token) {
+            let claims;
+            try {
+                const verified = await (0, jose_1.jwtVerify)(token, await keySet(), {
+                    issuer: resolved.issuer,
+                    audience: resolved.clientId,
+                    clockTolerance: resolved.clockToleranceSeconds,
+                    // The spec gives logout tokens their own `typ`. Providers
+                    // are inconsistent about sending it, so it is not required
+                    // — the `events` claim below is the check that actually
+                    // separates a logout token from an identity one.
+                    typ: undefined
+                });
+                claims = verified.payload;
+            }
+            catch (error) {
+                throw new identity_domain_1.SsoVerificationError(`the logout token did not verify (${error instanceof Error ? error.message : String(error)})`);
+            }
+            // Without this, a **stolen identity token** would be accepted here:
+            // same issuer, same audience, same signature, and it names a `sub`.
+            // Anyone who obtained one could then sign that person out at will.
+            // The `events` claim is what says "this token is a logout
+            // notification and nothing else".
+            const events = claims['events'];
+            if (typeof events !== 'object' ||
+                events === null ||
+                !(BACKCHANNEL_LOGOUT_EVENT in events)) {
+                throw new identity_domain_1.SsoVerificationError('the token carries no back-channel logout event, so it is not a logout token');
+            }
+            // The spec forbids a `nonce` on a logout token, precisely because
+            // its presence means somebody handed us an identity token.
+            if ('nonce' in claims) {
+                throw new identity_domain_1.SsoVerificationError('the logout token carries a nonce, which only an identity token has');
+            }
+            const sessionId = typeof claims['sid'] === 'string' ? claims['sid'] : null;
+            const subject = typeof claims['sub'] === 'string' ? claims['sub'] : null;
+            if (!sessionId && !subject) {
+                throw new identity_domain_1.SsoVerificationError('the logout token names neither a session nor a subject');
+            }
+            return { sessionId, subject };
+        }
+    };
+    /** Spends the authorization code and the PKCE verifier for a token. */
+    async function exchange(code, callback) {
+        const { token } = await endpoints.endpoints();
+        const body = new URLSearchParams({
+            grant_type: 'authorization_code',
+            code,
+            // Sent again, and it must match the authorization request byte for
+            // byte: most providers bind the code to it, and a mismatch comes
+            // back as a flat `invalid_grant` with nothing pointing at the cause.
+            redirect_uri: callback.redirectUri,
+            code_verifier: callback.codeVerifier,
+            client_id: resolved.clientId
+        });
+        const headers = {
+            'content-type': 'application/x-www-form-urlencoded',
+            accept: 'application/json'
+        };
+        if (resolved.clientSecret) {
+            // `client_secret_basic`: the spec prefers it, every shipped preset
+            // accepts it, and it keeps the secret out of a body that
+            // intermediaries are more likely to log.
+            headers['authorization'] = `Basic ${Buffer.from(`${encodeURIComponent(resolved.clientId)}:${encodeURIComponent(resolved.clientSecret)}`).toString('base64')}`;
+        }
+        let response;
+        try {
+            response = await resolved.fetch(token, {
+                method: 'POST',
+                headers,
+                body: body.toString()
+            });
+        }
+        catch (error) {
+            throw new identity_domain_1.SsoVerificationError(`the token exchange could not reach ${token} (${error instanceof Error ? error.message : String(error)})`);
+        }
+        const payload = (await response
+            .json()
+            .catch(() => ({})));
+        if (!response.ok) {
+            throw new identity_domain_1.SsoVerificationError(`the token exchange answered ${response.status}${payload.error ? ` (${String(payload.error)})` : ''}`);
+        }
+        if (typeof payload.id_token !== 'string' || !payload.id_token) {
+            throw new identity_domain_1.SsoVerificationError('the token response carried no identity token, so there is nothing to verify');
+        }
+        return payload.id_token;
+    }
+    /** Verifies signature, issuer, audience, expiry — and the nonce. */
+    async function verify(idToken, callback) {
+        let claims;
+        try {
+            const verified = await (0, jose_1.jwtVerify)(idToken, await keySet(), {
+                issuer: resolved.issuer,
+                audience: resolved.clientId,
+                clockTolerance: resolved.clockToleranceSeconds
+            });
+            claims = verified.payload;
+        }
+        catch (error) {
+            throw new identity_domain_1.SsoVerificationError(`the identity token did not verify (${error instanceof Error ? error.message : String(error)})`);
+        }
+        // Checked here rather than left to `jwtVerify`, because it is not a
+        // property of the token — it is the link between this token and the
+        // attempt the browser started. Without it a token captured from another
+        // attempt, still validly signed and unexpired, would be accepted.
+        if (claims['nonce'] !== callback.nonce) {
+            throw new identity_domain_1.SsoVerificationError('the identity token carries a nonce from a different attempt');
+        }
+        return claims;
+    }
+}
+/** The PKCE `S256` challenge for a verifier. */
+function challengeFor(codeVerifier) {
+    return (0, node_crypto_1.createHash)('sha256').update(codeVerifier).digest('base64url');
+}

package/dist/lib/presets.d.ts

@@ -0,0 +1,70 @@
+import type { SsoProvider } from '@orthacms/identity-domain';
+import type { OidcProviderConfig } from './config';
+/** What every preset needs; the rest of {@link OidcProviderConfig} still applies. */
+export type PresetConfig = Omit<OidcProviderConfig, 'issuer'> & Partial<Pick<OidcProviderConfig, 'issuer'>>;
+/**
+ * Google Workspace.
+ *
+ * Emits `email` and `email_verified` properly, so nothing here has to be
+ * asserted on the operator's behalf.
+ *
+ * `hostedDomain` sets Google's `hd` parameter, which asks Google to show only
+ * accounts in that domain. Treat it as a convenience, **not** a security
+ * control: it shapes the account chooser, and the CMS's own rules — a verified
+ * address matching an existing active account — are what actually decide who
+ * gets in.
+ */
+export declare function createGoogleProvider(config: PresetConfig & {
+    hostedDomain?: string;
+}): SsoProvider;
+/**
+ * Microsoft Entra ID (formerly Azure AD).
+ *
+ * `tenantId` builds the issuer. Use the directory's own GUID rather than
+ * `common` or `organizations`: those multi-tenant issuers accept accounts from
+ * **any** Microsoft directory, which is almost never what a CMS wants, and the
+ * issuer check that would normally catch a foreign token cannot help when the
+ * issuer is deliberately everyone's.
+ *
+ * **Entra does not emit `email_verified`.** A first sign-in therefore cannot
+ * claim an existing account until an operator sets `emailVerifiedWhenAbsent:
+ * true`, asserting that this directory is authoritative for the addresses it
+ * reports. That assertion is usually true for a corporate tenant; it is simply
+ * not one an adapter may make on the operator's behalf. Entra also often
+ * reports the address in `preferred_username` rather than `email`, which the
+ * default claim order already covers.
+ */
+export declare function createEntraProvider(config: PresetConfig & {
+    tenantId: string;
+}): SsoProvider;
+/**
+ * Okta.
+ *
+ * `domain` is the org's host (`acme.okta.com`), optionally with a custom
+ * authorization server (`authorizationServerId`, e.g. `default`). Okta's
+ * default org server issues at the bare domain; a custom one issues at
+ * `/oauth2/<id>`, and the two are different issuers — pointing at the wrong one
+ * fails at discovery rather than mysteriously later, which is why the issuer is
+ * built here rather than typed by hand.
+ */
+export declare function createOktaProvider(config: PresetConfig & {
+    domain: string;
+    authorizationServerId?: string;
+}): SsoProvider;
+/** Auth0. `domain` is the tenant host (`acme.eu.auth0.com` or a custom one). */
+export declare function createAuth0Provider(config: PresetConfig & {
+    domain: string;
+}): SsoProvider;
+/**
+ * Keycloak. `baseUrl` is the server root, `realm` the realm name.
+ *
+ * Groups are not in the token by default — a client scope has to map them. Pass
+ * `groupsClaim: 'groups'` once that mapper exists, and not before: a claim that
+ * is never sent reads as "this person is in no groups", which a future
+ * role-mapping handler would quietly act on.
+ */
+export declare function createKeycloakProvider(config: PresetConfig & {
+    baseUrl: string;
+    realm: string;
+}): SsoProvider;
+//# sourceMappingURL=presets.d.ts.map

package/dist/lib/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../src/lib/presets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD,qFAAqF;AACrF,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC,GACzD,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEhD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAChC,MAAM,EAAE,YAAY,GAAG;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD,WAAW,CAeb;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAC/B,MAAM,EAAE,YAAY,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC5C,WAAW,CAOb;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAC9B,MAAM,EAAE,YAAY,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1E,WAAW,CAUb;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAC/B,MAAM,EAAE,YAAY,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1C,WAAW,CAWb;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAClC,MAAM,EAAE,YAAY,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC1D,WAAW,CAOb"}

package/dist/lib/presets.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGoogleProvider = createGoogleProvider;
+exports.createEntraProvider = createEntraProvider;
+exports.createOktaProvider = createOktaProvider;
+exports.createAuth0Provider = createAuth0Provider;
+exports.createKeycloakProvider = createKeycloakProvider;
+const oidc_provider_1 = require("./oidc-provider");
+/**
+ * Google Workspace.
+ *
+ * Emits `email` and `email_verified` properly, so nothing here has to be
+ * asserted on the operator's behalf.
+ *
+ * `hostedDomain` sets Google's `hd` parameter, which asks Google to show only
+ * accounts in that domain. Treat it as a convenience, **not** a security
+ * control: it shapes the account chooser, and the CMS's own rules — a verified
+ * address matching an existing active account — are what actually decide who
+ * gets in.
+ */
+function createGoogleProvider(config) {
+    const { hostedDomain, ...rest } = config;
+    return (0, oidc_provider_1.createOidcProvider)({
+        issuer: 'https://accounts.google.com',
+        label: 'Google',
+        ...rest,
+        ...(hostedDomain
+            ? {
+                authorizationParams: {
+                    hd: hostedDomain,
+                    ...config.authorizationParams
+                }
+            }
+            : {})
+    });
+}
+/**
+ * Microsoft Entra ID (formerly Azure AD).
+ *
+ * `tenantId` builds the issuer. Use the directory's own GUID rather than
+ * `common` or `organizations`: those multi-tenant issuers accept accounts from
+ * **any** Microsoft directory, which is almost never what a CMS wants, and the
+ * issuer check that would normally catch a foreign token cannot help when the
+ * issuer is deliberately everyone's.
+ *
+ * **Entra does not emit `email_verified`.** A first sign-in therefore cannot
+ * claim an existing account until an operator sets `emailVerifiedWhenAbsent:
+ * true`, asserting that this directory is authoritative for the addresses it
+ * reports. That assertion is usually true for a corporate tenant; it is simply
+ * not one an adapter may make on the operator's behalf. Entra also often
+ * reports the address in `preferred_username` rather than `email`, which the
+ * default claim order already covers.
+ */
+function createEntraProvider(config) {
+    const { tenantId, ...rest } = config;
+    return (0, oidc_provider_1.createOidcProvider)({
+        issuer: `https://login.microsoftonline.com/${tenantId}/v2.0`,
+        label: 'Microsoft',
+        ...rest
+    });
+}
+/**
+ * Okta.
+ *
+ * `domain` is the org's host (`acme.okta.com`), optionally with a custom
+ * authorization server (`authorizationServerId`, e.g. `default`). Okta's
+ * default org server issues at the bare domain; a custom one issues at
+ * `/oauth2/<id>`, and the two are different issuers — pointing at the wrong one
+ * fails at discovery rather than mysteriously later, which is why the issuer is
+ * built here rather than typed by hand.
+ */
+function createOktaProvider(config) {
+    const { domain, authorizationServerId, ...rest } = config;
+    const host = domain.startsWith('http') ? domain : `https://${domain}`;
+    return (0, oidc_provider_1.createOidcProvider)({
+        issuer: authorizationServerId
+            ? `${host}/oauth2/${authorizationServerId}`
+            : host,
+        label: 'Okta',
+        ...rest
+    });
+}
+/** Auth0. `domain` is the tenant host (`acme.eu.auth0.com` or a custom one). */
+function createAuth0Provider(config) {
+    const { domain, ...rest } = config;
+    const host = domain.startsWith('http') ? domain : `https://${domain}`;
+    return (0, oidc_provider_1.createOidcProvider)({
+        // Auth0 issues with a trailing slash, and the `iss` claim is compared
+        // byte for byte. Omitting it is the single most common way to get a
+        // working discovery document and a token that will not verify.
+        issuer: `${host.replace(/\/+$/, '')}/`,
+        label: 'Auth0',
+        ...rest
+    });
+}
+/**
+ * Keycloak. `baseUrl` is the server root, `realm` the realm name.
+ *
+ * Groups are not in the token by default — a client scope has to map them. Pass
+ * `groupsClaim: 'groups'` once that mapper exists, and not before: a claim that
+ * is never sent reads as "this person is in no groups", which a future
+ * role-mapping handler would quietly act on.
+ */
+function createKeycloakProvider(config) {
+    const { baseUrl, realm, ...rest } = config;
+    return (0, oidc_provider_1.createOidcProvider)({
+        issuer: `${baseUrl.replace(/\/+$/, '')}/realms/${realm}`,
+        label: 'Keycloak',
+        ...rest
+    });
+}

package/dist/lib/test-support.d.ts

@@ -0,0 +1,68 @@
+import { generateKeyPair } from 'jose';
+import type { SsoAuthorizeRequest, SsoCallback } from '@orthacms/identity-domain';
+export declare const ISSUER = "https://idp.test";
+export declare const CLIENT_ID = "ortha-cms";
+export declare const REDIRECT_URI = "https://cms.test/api/auth/sso/idp/callback";
+/** The one-attempt secrets a core would have minted. */
+export declare const CORE_SECRETS: SsoAuthorizeRequest;
+/** What one scripted provider answers with. */
+export interface StubOptions {
+    /** Claims to merge into (or delete from) the identity token. */
+    claims?: Record<string, unknown>;
+    /** Sign with a key the published JWKS does not contain. */
+    signWithForeignKey?: boolean;
+    /** Answer the token endpoint with this status instead of 200. */
+    tokenStatus?: number;
+    /** Answer the token endpoint with this body instead of an id_token. */
+    tokenBody?: Record<string, unknown>;
+    /** Answer discovery with these fields merged in. */
+    discovery?: Record<string, unknown>;
+    /** Fail the discovery request with this status. */
+    discoveryStatus?: number;
+}
+/** A stubbed identity provider: discovery, JWKS and a token endpoint. */
+export interface StubIdp {
+    /** Drop-in for `fetch`. */
+    fetch: typeof globalThis.fetch;
+    /**
+     * The key the stub signs with, for tokens a test mints itself.
+     *
+     * Typed from `generateKeyPair`'s own return rather than as `CryptoKey`:
+     * that name comes from the DOM lib, which these Node-targeted packages do
+     * not include.
+     */
+    privateKey: Awaited<ReturnType<typeof generateKeyPair>>['privateKey'];
+    /** How many requests reached each endpoint. */
+    calls: {
+        discovery: number;
+        jwks: number;
+        token: number;
+    };
+    /** The last form body the token endpoint received. */
+    lastTokenBody: URLSearchParams | null;
+    /** The last `Authorization` header the token endpoint received. */
+    lastTokenAuth: string | null;
+}
+/**
+ * Builds a stubbed OpenID provider that signs **real** identity tokens.
+ *
+ * Signing for real is what makes the tampering scenario mean something: a
+ * flipped byte fails because `jose` verifies a signature, not because a flag
+ * says so. It is also the only way to check that the adapter rejects a token
+ * signed by a key the provider does not publish, which is the failure a
+ * signature check exists to catch.
+ */
+export declare function stubIdp(options?: StubOptions): Promise<StubIdp>;
+/**
+ * Signs a back-channel logout token with the stub's key.
+ *
+ * A real signature, like the identity tokens: the checks under test are "did
+ * this verify" and "is this actually a logout token", and a hand-built string
+ * could only exercise the second.
+ */
+export declare function signLogoutToken(idp: StubIdp, claims?: Record<string, unknown>): Promise<string>;
+/** The event claim that marks a token as a logout notification. */
+export declare const BACKCHANNEL_LOGOUT_EVENT = "http://schemas.openid.net/event/backchannel-logout";
+/** The callback the core would build from a provider's redirect back. */
+export declare function callbackWith(overrides?: Record<string, string>): SsoCallback;
+//# sourceMappingURL=test-support.d.ts.map

package/dist/lib/test-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-support.d.ts","sourceRoot":"","sources":["../../src/lib/test-support.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,eAAe,EAAqB,MAAM,MAAM,CAAC;AAWrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAElF,eAAO,MAAM,MAAM,qBAAqB,CAAC;AACzC,eAAO,MAAM,SAAS,cAAc,CAAC;AACrC,eAAO,MAAM,YAAY,+CACuB,CAAC;AAEjD,wDAAwD;AACxD,eAAO,MAAM,YAAY,EAAE,mBAK1B,CAAC;AAEF,+CAA+C;AAC/C,MAAM,WAAW,WAAW;IACxB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,2DAA2D;IAC3D,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,mDAAmD;IACnD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,yEAAyE;AACzE,MAAM,WAAW,OAAO;IACpB,2BAA2B;IAC3B,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAC/B;;;;;;OAMG;IACH,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;IACtE,+CAA+C;IAC/C,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D,sDAAsD;IACtD,aAAa,EAAE,eAAe,GAAG,IAAI,CAAC;IACtC,mEAAmE;IACnE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CA+EzE;AAUD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACjC,GAAG,EAAE,OAAO,EACZ,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACrC,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,uDACmB,CAAC;AAEzD,yEAAyE;AACzE,wBAAgB,YAAY,CACxB,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACvC,WAAW,CAYb"}

package/dist/lib/test-support.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BACKCHANNEL_LOGOUT_EVENT = exports.CORE_SECRETS = exports.REDIRECT_URI = exports.CLIENT_ID = exports.ISSUER = void 0;
+exports.stubIdp = stubIdp;
+exports.signLogoutToken = signLogoutToken;
+exports.callbackWith = callbackWith;
+const jose_1 = require("jose");
+exports.ISSUER = 'https://idp.test';
+exports.CLIENT_ID = 'ortha-cms';
+exports.REDIRECT_URI = 'https://cms.test/api/auth/sso/idp/callback';
+/** The one-attempt secrets a core would have minted. */
+exports.CORE_SECRETS = {
+    redirectUri: exports.REDIRECT_URI,
+    state: 'state-2f6a1c9d',
+    nonce: 'nonce-8b0e47aa',
+    codeVerifier: 'verifier-4c1d55e0f39b2a7681ce'
+};
+/**
+ * Builds a stubbed OpenID provider that signs **real** identity tokens.
+ *
+ * Signing for real is what makes the tampering scenario mean something: a
+ * flipped byte fails because `jose` verifies a signature, not because a flag
+ * says so. It is also the only way to check that the adapter rejects a token
+ * signed by a key the provider does not publish, which is the failure a
+ * signature check exists to catch.
+ */
+async function stubIdp(options = {}) {
+    const { privateKey, publicKey } = await (0, jose_1.generateKeyPair)('RS256', {
+        extractable: true
+    });
+    const foreign = await (0, jose_1.generateKeyPair)('RS256', { extractable: true });
+    const publicJwk = {
+        ...(await (0, jose_1.exportJWK)(publicKey)),
+        kid: 'test-key',
+        alg: 'RS256',
+        use: 'sig'
+    };
+    const state = {
+        fetch: (() => Promise.reject(new Error('unset'))),
+        privateKey,
+        calls: { discovery: 0, jwks: 0, token: 0 },
+        lastTokenBody: null,
+        lastTokenAuth: null
+    };
+    const claims = {
+        sub: 'idp-subject-1',
+        email: 'ada@example.com',
+        email_verified: true,
+        name: 'Ada Lovelace',
+        nonce: exports.CORE_SECRETS.nonce,
+        ...options.claims
+    };
+    for (const [key, value] of Object.entries(options.claims ?? {})) {
+        if (value === undefined) {
+            delete claims[key];
+        }
+    }
+    const idToken = await new jose_1.SignJWT(claims)
+        .setProtectedHeader({ alg: 'RS256', kid: 'test-key' })
+        .setIssuer(exports.ISSUER)
+        .setAudience(exports.CLIENT_ID)
+        .setIssuedAt()
+        .setExpirationTime('5m')
+        .sign(options.signWithForeignKey ? foreign.privateKey : privateKey);
+    state.fetch = (async (input, init) => {
+        const url = typeof input === 'string' ? input : input.toString();
+        if (url.includes('.well-known/openid-configuration')) {
+            state.calls.discovery += 1;
+            if (options.discoveryStatus) {
+                return json({}, options.discoveryStatus);
+            }
+            return json({
+                issuer: exports.ISSUER,
+                authorization_endpoint: `${exports.ISSUER}/authorize`,
+                token_endpoint: `${exports.ISSUER}/token`,
+                jwks_uri: `${exports.ISSUER}/jwks`,
+                end_session_endpoint: `${exports.ISSUER}/logout`,
+                ...options.discovery
+            });
+        }
+        if (url.endsWith('/jwks')) {
+            state.calls.jwks += 1;
+            return json({ keys: [publicJwk] });
+        }
+        if (url.endsWith('/token')) {
+            state.calls.token += 1;
+            state.lastTokenBody = new URLSearchParams(String(init?.body ?? ''));
+            state.lastTokenAuth =
+                (init?.headers ?? {})['authorization'] ?? null;
+            if (options.tokenStatus && options.tokenStatus !== 200) {
+                return json(options.tokenBody ?? {}, options.tokenStatus);
+            }
+            return json(options.tokenBody ?? { id_token: idToken });
+        }
+        throw new Error(`stub IdP got an unexpected request: ${url}`);
+    });
+    return state;
+}
+/** A JSON `Response`, as the stub's endpoints answer with. */
+function json(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json' }
+    });
+}
+/**
+ * Signs a back-channel logout token with the stub's key.
+ *
+ * A real signature, like the identity tokens: the checks under test are "did
+ * this verify" and "is this actually a logout token", and a hand-built string
+ * could only exercise the second.
+ */
+async function signLogoutToken(idp, claims = {}) {
+    const payload = {
+        events: { [exports.BACKCHANNEL_LOGOUT_EVENT]: {} },
+        sid: 'provider-session-1',
+        sub: 'idp-subject-1',
+        ...claims
+    };
+    for (const [key, value] of Object.entries(claims)) {
+        if (value === undefined) {
+            delete payload[key];
+        }
+    }
+    return new jose_1.SignJWT(payload)
+        .setProtectedHeader({ alg: 'RS256', kid: 'test-key' })
+        .setIssuer(exports.ISSUER)
+        .setAudience(exports.CLIENT_ID)
+        .setIssuedAt()
+        .setExpirationTime('5m')
+        .sign(idp.privateKey);
+}
+/** The event claim that marks a token as a logout notification. */
+exports.BACKCHANNEL_LOGOUT_EVENT = 'http://schemas.openid.net/event/backchannel-logout';
+/** The callback the core would build from a provider's redirect back. */
+function callbackWith(overrides = {}) {
+    return {
+        params: {
+            code: 'authorization-code-1',
+            state: exports.CORE_SECRETS.state,
+            ...overrides
+        },
+        state: exports.CORE_SECRETS.state,
+        nonce: exports.CORE_SECRETS.nonce,
+        codeVerifier: exports.CORE_SECRETS.codeVerifier,
+        redirectUri: exports.REDIRECT_URI
+    };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "@orthacms/identity-provider-oidc",
+    "version": "0.4.0",
+    "description": "@orthacms/identity-provider-oidc — part of Ortha CMS.",
+    "license": "MIT",
+    "homepage": "https://github.com/ortha-source/ortha-cms/tree/main/packages/identity/provider-oidc",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ortha-source/ortha-cms.git",
+        "directory": "packages/identity/provider-oidc"
+    },
+    "bugs": {
+        "url": "https://github.com/ortha-source/ortha-cms/issues"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist"
+    ],
+    "dependencies": {
+        "@orthacms/identity-domain": "^0.4.0",
+        "jose": "^6.2.0",
+        "tslib": "^2.3.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}