@orthacms/identity-provider-saml 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-saml
+
+Part of [Ortha CMS](https://github.com/ortha-source/ortha-cms).
+
+```sh
+npm install @orthacms/identity-provider-saml
+```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createSamlProvider } from './lib/saml-provider';
+export type { SamlProviderConfig } from './lib/config';
+//# 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,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSamlProvider = void 0;
+var saml_provider_1 = require("./lib/saml-provider");
+Object.defineProperty(exports, "createSamlProvider", { enumerable: true, get: function () { return saml_provider_1.createSamlProvider; } });

package/dist/lib/config.d.ts

@@ -0,0 +1,85 @@
+/** How one SAML identity provider is reached and read. */
+export interface SamlProviderConfig {
+    /** The IdP's single-sign-on URL — where the AuthnRequest is sent. */
+    entryPoint: string;
+    /**
+     * The IdP's signing certificate(s), PEM or bare base64. Several may be
+     * given so a certificate rollover does not need a redeploy timed to the
+     * minute.
+     *
+     * There is no discovery here and no JWKS: SAML trust is a certificate an
+     * operator copies from their IdP, which is why it is required and why a
+     * rollover is a configuration change rather than something the adapter can
+     * pick up on its own.
+     */
+    idpCert: string | string[];
+    /**
+     * This CMS's entity id — the `Issuer` on the AuthnRequest, and what the IdP
+     * has registered as the service provider.
+     */
+    issuer: string;
+    /** Button text. Defaults to `SAML`. */
+    label?: string;
+    /**
+     * The attribute holding a **stable** identifier for the person, when the
+     * `NameID` is not one.
+     *
+     * Worth setting whenever the IdP's NameID format is `emailAddress`: an
+     * address is not a stable identifier, and the core refuses a profile whose
+     * subject is one. Point this at an immutable directory id instead.
+     */
+    subjectAttribute?: string;
+    /**
+     * The attribute holding the email address. Defaults to trying the usual
+     * spellings, which differ per IdP more than anything else in SAML does.
+     */
+    emailAttribute?: string;
+    /** The attribute holding group membership, when a deployment maps roles. */
+    groupsAttribute?: string;
+    /** The attribute holding a display name. */
+    nameAttribute?: string;
+    /**
+     * Whether an address this IdP asserts counts as **verified**.
+     *
+     * Defaults to `false`, and this is the setting most likely to be reached
+     * for. **SAML has no verification claim at all** — no assertion carries the
+     * equivalent of `email_verified`, so there is nothing an adapter could read
+     * and be honest about. Setting this is an operator asserting that their
+     * directory is authoritative for the addresses it reports, which is usually
+     * true of a corporate IdP and is still not something to assume on their
+     * behalf: it is the only gate on a first sign-in claiming an existing
+     * account.
+     */
+    emailVerified?: boolean;
+    /** The SP private key, when the IdP requires signed AuthnRequests. */
+    privateKey?: string;
+    /** The SP certificate that goes with {@link privateKey}. */
+    signingCert?: string;
+    /** Whether to require the IdP to sign its assertions. Defaults to `true`. */
+    wantAssertionsSigned?: boolean;
+    /** Whether to require a signed response envelope. Defaults to `true`. */
+    wantAuthnResponseSigned?: boolean;
+    /** Accepted clock skew, in seconds. Defaults to 60. */
+    clockToleranceSeconds?: number;
+}
+/** Defaults applied once, so no code path has to remember them. */
+export interface ResolvedSamlConfig extends SamlProviderConfig {
+    label: string;
+    emailVerified: boolean;
+    wantAssertionsSigned: boolean;
+    wantAuthnResponseSigned: boolean;
+    clockToleranceSeconds: number;
+}
+/** The attributes an email is read from, in order, when none is configured. */
+export declare const DEFAULT_EMAIL_ATTRIBUTES: readonly ["email", "mail", "urn:oid:0.9.2342.19200300.100.1.3", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"];
+/** The attributes a display name is read from, when none is configured. */
+export declare const DEFAULT_NAME_ATTRIBUTES: readonly ["displayName", "cn", "name", "http://schemas.microsoft.com/identity/claims/displayname"];
+/**
+ * Applies the defaults and rejects a configuration that cannot work.
+ *
+ * Eager, at construction, because every SSO failure looks identical by design:
+ * a missing certificate would otherwise reach an operator as the same blank
+ * "that sign-in did not complete" as a cancelled consent screen.
+ */
+export declare function resolveSamlConfig(config: SamlProviderConfig): ResolvedSamlConfig;
+//# 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,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IAC/B,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;OASG;IACH,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,yEAAyE;IACzE,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,uDAAuD;IACvD,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,OAAO,CAAC;IACvB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,uBAAuB,EAAE,OAAO,CAAC;IACjC,qBAAqB,EAAE,MAAM,CAAC;CACjC;AAED,+EAA+E;AAC/E,eAAO,MAAM,wBAAwB,uIAK3B,CAAC;AAEX,2EAA2E;AAC3E,eAAO,MAAM,uBAAuB,oGAK1B,CAAC;AAEX;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC7B,MAAM,EAAE,kBAAkB,GAC3B,kBAAkB,CA2CpB"}

package/dist/lib/config.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_NAME_ATTRIBUTES = exports.DEFAULT_EMAIL_ATTRIBUTES = void 0;
+exports.resolveSamlConfig = resolveSamlConfig;
+/** The attributes an email is read from, in order, when none is configured. */
+exports.DEFAULT_EMAIL_ATTRIBUTES = [
+    'email',
+    'mail',
+    'urn:oid:0.9.2342.19200300.100.1.3',
+    'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'
+];
+/** The attributes a display name is read from, when none is configured. */
+exports.DEFAULT_NAME_ATTRIBUTES = [
+    'displayName',
+    'cn',
+    'name',
+    'http://schemas.microsoft.com/identity/claims/displayname'
+];
+/**
+ * Applies the defaults and rejects a configuration that cannot work.
+ *
+ * Eager, at construction, because every SSO failure looks identical by design:
+ * a missing certificate would otherwise reach an operator as the same blank
+ * "that sign-in did not complete" as a cancelled consent screen.
+ */
+function resolveSamlConfig(config) {
+    let entry;
+    try {
+        entry = new URL(config.entryPoint);
+    }
+    catch {
+        throw new Error(`createSamlProvider needs an absolute entryPoint URL; got "${config.entryPoint}".`);
+    }
+    if (entry.protocol !== 'https:' && entry.hostname !== 'localhost') {
+        throw new Error(`createSamlProvider refuses the non-HTTPS entryPoint "${config.entryPoint}": the assertion would cross the network in clear text. Only localhost is exempt, for development.`);
+    }
+    if (!config.issuer.trim()) {
+        throw new Error('createSamlProvider needs an issuer — the entity id your identity provider has registered for this application.');
+    }
+    const certs = Array.isArray(config.idpCert)
+        ? config.idpCert
+        : [config.idpCert];
+    if (certs.length === 0 || certs.some((cert) => !cert?.trim())) {
+        throw new Error("createSamlProvider needs the identity provider's signing certificate. SAML has no discovery document and no key endpoint — the certificate is the whole of the trust relationship, so there is nothing to fall back to.");
+    }
+    if (config.privateKey && !config.signingCert) {
+        throw new Error('createSamlProvider was given a privateKey with no signingCert. An identity provider validates a signed AuthnRequest against the certificate you registered with it, so the pair has to travel together.');
+    }
+    return {
+        ...config,
+        label: config.label ?? 'SAML',
+        // Never defaulted to true. See the field's own note: there is no claim
+        // to read, so `true` can only ever be an operator's assertion.
+        emailVerified: config.emailVerified ?? false,
+        wantAssertionsSigned: config.wantAssertionsSigned ?? true,
+        wantAuthnResponseSigned: config.wantAuthnResponseSigned ?? true,
+        clockToleranceSeconds: config.clockToleranceSeconds ?? 60
+    };
+}

package/dist/lib/profile.d.ts

@@ -0,0 +1,27 @@
+import { type SsoProfile } from '@orthacms/identity-domain';
+import { type ResolvedSamlConfig } from './config';
+/** The parts of a validated SAML profile this adapter reads. */
+export interface SamlAssertionProfile {
+    /** The `NameID`. */
+    nameID?: unknown;
+    /** Its format URI — `transient` is refused; see below. */
+    nameIDFormat?: unknown;
+    /** The IdP's session identifier, for back-channel logout. */
+    sessionIndex?: unknown;
+    /** Everything else the assertion carried, keyed by attribute name. */
+    attributes?: Record<string, unknown>;
+    /** node-saml also lifts some attributes onto the profile itself. */
+    [key: string]: unknown;
+}
+/**
+ * Turns a validated assertion into the normalised profile the CMS resolves
+ * accounts with.
+ *
+ * Separated from the adapter so it can be tested exhaustively without a signed
+ * assertion: signature validation belongs to `@node-saml/node-saml` and is not
+ * re-implemented here, but *which field means what* is this adapter's own
+ * decision and is where the interesting mistakes live. SAML's attribute names
+ * differ per identity provider more than anything else about it does.
+ */
+export declare function toProfile(assertion: SamlAssertionProfile, config: ResolvedSamlConfig): SsoProfile;
+//# sourceMappingURL=profile.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../src/lib/profile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAClF,OAAO,EAGH,KAAK,kBAAkB,EAC1B,MAAM,UAAU,CAAC;AAElB,gEAAgE;AAChE,MAAM,WAAW,oBAAoB;IACjC,oBAAoB;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,oEAAoE;IACpE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAMD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACrB,SAAS,EAAE,oBAAoB,EAC/B,MAAM,EAAE,kBAAkB,GAC3B,UAAU,CAkCZ"}

package/dist/lib/profile.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toProfile = toProfile;
+const identity_domain_1 = require("@orthacms/identity-domain");
+const config_1 = require("./config");
+/** The `NameID` format that is explicitly *not* stable. */
+const TRANSIENT_FORMAT = 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient';
+/**
+ * Turns a validated assertion into the normalised profile the CMS resolves
+ * accounts with.
+ *
+ * Separated from the adapter so it can be tested exhaustively without a signed
+ * assertion: signature validation belongs to `@node-saml/node-saml` and is not
+ * re-implemented here, but *which field means what* is this adapter's own
+ * decision and is where the interesting mistakes live. SAML's attribute names
+ * differ per identity provider more than anything else about it does.
+ */
+function toProfile(assertion, config) {
+    const subject = readSubject(assertion, config);
+    const email = readEmail(assertion, config);
+    if (!email) {
+        throw new identity_domain_1.SsoVerificationError(`the assertion carried no email attribute. Configure emailAttribute to name the one your identity provider sends.`);
+    }
+    if (subject.toLowerCase() === email) {
+        // The core refuses this too, but naming the fix here is what turns a
+        // blank "sign-in did not complete" into something an operator can act
+        // on: the NameID format is `emailAddress`, and an address follows a
+        // person's mailbox rather than the person.
+        throw new identity_domain_1.SsoVerificationError('the NameID is the email address, which is not a stable identifier. Configure the identity provider to send a persistent NameID, or set subjectAttribute to an immutable directory id.');
+    }
+    return {
+        subject,
+        email,
+        // No claim exists to read — see `SamlProviderConfig.emailVerified`.
+        // This is the operator's assertion, reported faithfully as such.
+        emailVerified: config.emailVerified,
+        name: readName(assertion, config),
+        ...(config.groupsAttribute
+            ? { groups: readGroups(attribute(assertion, config.groupsAttribute)) }
+            : {}),
+        sessionId: typeof assertion.sessionIndex === 'string'
+            ? assertion.sessionIndex
+            : null
+    };
+}
+/** The stable identifier: a configured attribute, or the `NameID`. */
+function readSubject(assertion, config) {
+    if (config.subjectAttribute) {
+        const value = attribute(assertion, config.subjectAttribute);
+        const subject = firstString([value]);
+        if (!subject) {
+            throw new identity_domain_1.SsoVerificationError(`the assertion carried no "${config.subjectAttribute}" attribute to key this person on`);
+        }
+        return subject;
+    }
+    if (assertion.nameIDFormat === TRANSIENT_FORMAT) {
+        // A transient NameID is a different value on every sign-in — that is
+        // its entire purpose. Keying a link on one would create a new link, and
+        // a new account under provisioning, every single time.
+        throw new identity_domain_1.SsoVerificationError('the identity provider sent a transient NameID, which is a different value on every sign-in. Configure a persistent NameID, or set subjectAttribute.');
+    }
+    const nameId = firstString([assertion.nameID]);
+    if (!nameId) {
+        throw new identity_domain_1.SsoVerificationError('the assertion carried no NameID and no subjectAttribute is configured');
+    }
+    return nameId;
+}
+/** The address, from the configured attribute or the usual spellings. */
+function readEmail(assertion, config) {
+    const names = config.emailAttribute
+        ? [config.emailAttribute]
+        : config_1.DEFAULT_EMAIL_ATTRIBUTES;
+    const found = firstString(names.map((name) => attribute(assertion, name)));
+    if (found) {
+        return found.toLowerCase();
+    }
+    // Last resort: some identity providers put the address in the NameID and
+    // send no attribute at all. Only usable when it actually looks like one.
+    const nameId = firstString([assertion.nameID]);
+    return nameId?.includes('@') ? nameId.toLowerCase() : null;
+}
+/** A display name, or `null`. */
+function readName(assertion, config) {
+    const names = config.nameAttribute
+        ? [config.nameAttribute]
+        : config_1.DEFAULT_NAME_ATTRIBUTES;
+    return firstString(names.map((name) => attribute(assertion, name)));
+}
+/**
+ * One attribute, looked for in both places node-saml puts them: the
+ * `attributes` bag, and lifted onto the profile itself.
+ */
+function attribute(assertion, name) {
+    return assertion.attributes?.[name] ?? assertion[name];
+}
+/**
+ * Group membership, normalised.
+ *
+ * A SAML attribute with one value arrives as a string and with several as an
+ * array — the same attribute, two shapes, depending on how many groups the
+ * person happens to be in. Anything else is dropped rather than coerced: a
+ * group list nobody can read is safer empty than guessed at, because a
+ * role-mapping handler acts on it.
+ */
+function readGroups(raw) {
+    if (Array.isArray(raw)) {
+        return raw.filter((item) => typeof item === 'string');
+    }
+    return typeof raw === 'string' && raw.trim() ? [raw.trim()] : [];
+}
+/** The first non-empty string among `values`, trimmed. */
+function firstString(values) {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim()) {
+            return value.trim();
+        }
+        if (Array.isArray(value)) {
+            const first = value.find((item) => typeof item === 'string' && !!item.trim());
+            if (first) {
+                return first.trim();
+            }
+        }
+    }
+    return null;
+}

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

@@ -0,0 +1,25 @@
+import { type SsoProvider } from '@orthacms/identity-domain';
+import { type SamlProviderConfig } from './config';
+/**
+ * SAML 2.0 sign-in — HTTP-Redirect for the request, HTTP-POST for the response.
+ *
+ * **Its own package, and the reason `callbackMethod` is in the port's
+ * descriptor from the first release.** SAML's response is not a redirect: the
+ * identity provider returns the person by POSTing a form to the callback, so
+ * this adapter declares `'POST'` and the plugin mounts the route that serves
+ * it. Nothing about the seam had to change to add a second protocol shape,
+ * which was the whole bet.
+ *
+ * **`@node-saml/node-saml` does the XML.** Canonicalisation, signature
+ * validation, and the conditions checks are its job. That is a deliberate
+ * dependency: XML signature validation has a long history of wrapping attacks
+ * that turn on parser details, and it is not a place to demonstrate
+ * independence. ADR-0012 permits it here for exactly this reason and forbids it
+ * in `identity-domain` and `identity-server`.
+ *
+ * What *this* file owns is everything the library has no opinion about: which
+ * attribute means what, that a transient NameID cannot key a link, and that
+ * `RelayState` is where the core's `state` travels.
+ */
+export declare function createSamlProvider(config: SamlProviderConfig): SsoProvider;
+//# sourceMappingURL=saml-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"saml-provider.d.ts","sourceRoot":"","sources":["../../src/lib/saml-provider.ts"],"names":[],"mappings":"AACA,OAAO,EAOH,KAAK,WAAW,EAEnB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAGtE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,WAAW,CAgH1E"}

package/dist/lib/saml-provider.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSamlProvider = createSamlProvider;
+const node_saml_1 = require("@node-saml/node-saml");
+const identity_domain_1 = require("@orthacms/identity-domain");
+const config_1 = require("./config");
+const profile_1 = require("./profile");
+/**
+ * SAML 2.0 sign-in — HTTP-Redirect for the request, HTTP-POST for the response.
+ *
+ * **Its own package, and the reason `callbackMethod` is in the port's
+ * descriptor from the first release.** SAML's response is not a redirect: the
+ * identity provider returns the person by POSTing a form to the callback, so
+ * this adapter declares `'POST'` and the plugin mounts the route that serves
+ * it. Nothing about the seam had to change to add a second protocol shape,
+ * which was the whole bet.
+ *
+ * **`@node-saml/node-saml` does the XML.** Canonicalisation, signature
+ * validation, and the conditions checks are its job. That is a deliberate
+ * dependency: XML signature validation has a long history of wrapping attacks
+ * that turn on parser details, and it is not a place to demonstrate
+ * independence. ADR-0012 permits it here for exactly this reason and forbids it
+ * in `identity-domain` and `identity-server`.
+ *
+ * What *this* file owns is everything the library has no opinion about: which
+ * attribute means what, that a transient NameID cannot key a link, and that
+ * `RelayState` is where the core's `state` travels.
+ */
+function createSamlProvider(config) {
+    const resolved = (0, config_1.resolveSamlConfig)(config);
+    const descriptor = Object.freeze({
+        kind: 'saml',
+        label: resolved.label,
+        callbackMethod: 'POST'
+    });
+    /**
+     * One configured `SAML` instance per callback URL.
+     *
+     * The library takes the callback URL at construction while the port supplies
+     * it per request, and in practice there is exactly one — so this is a cache
+     * of size one that survives a deployment changing its public base URL
+     * without a restart, rather than rebuilding an XML validator on every
+     * sign-in.
+     */
+    const instances = new Map();
+    const samlFor = (callbackUrl) => {
+        const existing = instances.get(callbackUrl);
+        if (existing) {
+            return existing;
+        }
+        const saml = new node_saml_1.SAML({
+            callbackUrl,
+            entryPoint: resolved.entryPoint,
+            issuer: resolved.issuer,
+            idpCert: resolved.idpCert,
+            wantAssertionsSigned: resolved.wantAssertionsSigned,
+            wantAuthnResponseSigned: resolved.wantAuthnResponseSigned,
+            acceptedClockSkewMs: resolved.clockToleranceSeconds * 1000,
+            // The core already guarantees one-time use: the attempt row is
+            // burned before anything is exchanged. Asking the library to keep
+            // its own in-memory `InResponseTo` cache on top would add a second,
+            // per-process store that a multi-instance deployment gets wrong —
+            // and it would be the one that decides, since it runs first.
+            validateInResponseTo: node_saml_1.ValidateInResponseTo.never,
+            ...(resolved.privateKey ? { privateKey: resolved.privateKey } : {}),
+            ...(resolved.signingCert
+                ? { publicCert: resolved.signingCert }
+                : {})
+        });
+        instances.set(callbackUrl, saml);
+        return saml;
+    };
+    return {
+        descriptor: () => descriptor,
+        async authorize(request) {
+            // `RelayState` is SAML's spelling of `state`: an opaque value the
+            // identity provider echoes back untouched. The core mints it, and
+            // it is the only thing tying a response to an attempt — SAML has no
+            // nonce and no PKCE.
+            const url = await samlFor(request.redirectUri).getAuthorizeUrlAsync(request.state, undefined, {});
+            return { url };
+        },
+        async complete(callback) {
+            const { params } = callback;
+            if (params['RelayState'] !== callback.state) {
+                throw new identity_domain_1.SsoVerificationError('the echoed RelayState is not the one this attempt stored');
+            }
+            const response = params['SAMLResponse'];
+            if (!response) {
+                throw new identity_domain_1.SsoVerificationError('the form carried no SAMLResponse');
+            }
+            let profile;
+            try {
+                const validated = await samlFor(callback.redirectUri).validatePostResponseAsync({
+                    SAMLResponse: response,
+                    RelayState: params['RelayState']
+                });
+                profile = validated.profile;
+            }
+            catch (error) {
+                throw new identity_domain_1.SsoVerificationError(`the assertion did not validate (${error instanceof Error ? error.message : String(error)})`);
+            }
+            if (!profile) {
+                throw new identity_domain_1.SsoVerificationError('the response validated but carried no assertion');
+            }
+            return (0, profile_1.toProfile)(profile, resolved);
+        },
+        logoutUrl(_request) {
+            // Deliberately not implemented. SAML single logout is its own
+            // signed, bidirectional exchange — not a URL to redirect to — and
+            // pretending otherwise would send people to an endpoint that
+            // rejects them. Ending the CMS session still works; the identity
+            // provider's does not end with it, which is the honest answer.
+            return null;
+        }
+    };
+}

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

@@ -0,0 +1,45 @@
+import type { SsoAuthorizeRequest, SsoCallback } from '@orthacms/identity-domain';
+export declare const ENTRY_POINT = "https://idp.test/sso";
+export declare const SP_ISSUER = "https://cms.test/saml";
+export declare const IDP_ISSUER = "https://idp.test";
+export declare const CALLBACK = "https://cms.test/api/auth/sso/saml/callback";
+/** The one-attempt secrets a core would have minted. */
+export declare const CORE_SECRETS: SsoAuthorizeRequest;
+/** A throwaway signing identity for the scripted identity provider. */
+export interface SigningIdentity {
+    privateKey: string;
+    cert: string;
+}
+/**
+ * Generates a self-signed certificate for the scripted identity provider.
+ *
+ * A real key and a real certificate, because the assertions below are **really
+ * signed**: the only interesting thing about a SAML adapter's failure paths is
+ * that a response which does not verify is refused, and a fixture nobody signed
+ * could not show that.
+ */
+export declare function signingIdentity(): Promise<SigningIdentity>;
+/** What one scripted assertion says. */
+export interface AssertionOptions {
+    nameId?: string;
+    nameIdFormat?: string;
+    sessionIndex?: string;
+    attributes?: Record<string, string | string[]>;
+    /** Skip the attribute statement entirely. */
+    omitAttributes?: boolean;
+    /** Backdate the assertion so its conditions have expired. */
+    expired?: boolean;
+    /** Sign with this identity instead of the one the adapter trusts. */
+    signWith?: SigningIdentity;
+    /**
+     * A non-success status — SAML's way of saying "the person did not
+     * authenticate". There is no `error` query parameter on this protocol; a
+     * refusal is a `StatusCode` inside a signed response.
+     */
+    status?: string;
+}
+/** Builds a signed `Response`, base64-encoded as the form field carries it. */
+export declare function signedResponse(idp: SigningIdentity, options?: AssertionOptions): string;
+/** The callback the core would build from an identity provider's form POST. */
+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":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAElF,eAAO,MAAM,WAAW,yBAAyB,CAAC;AAClD,eAAO,MAAM,SAAS,0BAA0B,CAAC;AACjD,eAAO,MAAM,UAAU,qBAAqB,CAAC;AAC7C,eAAO,MAAM,QAAQ,gDAAgD,CAAC;AAEtE,wDAAwD;AACxD,eAAO,MAAM,YAAY,EAAE,mBAO1B,CAAC;AAEF,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,eAAe,CAAC,CAKhE;AAED,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC/C,6CAA6C;IAC7C,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAKD,+EAA+E;AAC/E,wBAAgB,cAAc,CAC1B,GAAG,EAAE,eAAe,EACpB,OAAO,GAAE,gBAAqB,GAC/B,MAAM,CAiFR;AAkCD,+EAA+E;AAC/E,wBAAgB,YAAY,CACxB,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACvC,WAAW,CAWb"}

package/dist/lib/test-support.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CORE_SECRETS = exports.CALLBACK = exports.IDP_ISSUER = exports.SP_ISSUER = exports.ENTRY_POINT = void 0;
+exports.signingIdentity = signingIdentity;
+exports.signedResponse = signedResponse;
+exports.callbackWith = callbackWith;
+const xml_crypto_1 = require("xml-crypto");
+const selfsigned_1 = require("selfsigned");
+exports.ENTRY_POINT = 'https://idp.test/sso';
+exports.SP_ISSUER = 'https://cms.test/saml';
+exports.IDP_ISSUER = 'https://idp.test';
+exports.CALLBACK = 'https://cms.test/api/auth/sso/saml/callback';
+/** The one-attempt secrets a core would have minted. */
+exports.CORE_SECRETS = {
+    redirectUri: exports.CALLBACK,
+    state: 'state-2f6a1c9d',
+    // Present and unused: SAML has neither a nonce nor PKCE, and `RelayState`
+    // carries the whole of the replay defence.
+    nonce: 'nonce-8b0e47aa',
+    codeVerifier: 'verifier-4c1d55e0f39b2a7681ce'
+};
+/**
+ * Generates a self-signed certificate for the scripted identity provider.
+ *
+ * A real key and a real certificate, because the assertions below are **really
+ * signed**: the only interesting thing about a SAML adapter's failure paths is
+ * that a response which does not verify is refused, and a fixture nobody signed
+ * could not show that.
+ */
+async function signingIdentity() {
+    const pems = await (0, selfsigned_1.generate)([{ name: 'commonName', value: 'idp.test' }], {
+        keySize: 2048
+    });
+    return { privateKey: pems.private, cert: pems.cert };
+}
+const PERSISTENT = 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent';
+/** Builds a signed `Response`, base64-encoded as the form field carries it. */
+function signedResponse(idp, options = {}) {
+    const now = Date.now();
+    const issued = new Date(options.expired ? now - 3_600_000 : now);
+    const expires = new Date(options.expired ? now - 3_540_000 : now + 300_000);
+    const iso = (date) => date.toISOString();
+    const attributes = options.omitAttributes
+        ? ''
+        : `<saml:AttributeStatement>${Object.entries(options.attributes ?? {
+            email: 'ada@example.com',
+            displayName: 'Ada Lovelace'
+        })
+            .map(([name, value]) => {
+            const values = Array.isArray(value) ? value : [value];
+            return `<saml:Attribute Name="${name}">${values
+                .map((item) => `<saml:AttributeValue>${item}</saml:AttributeValue>`)
+                .join('')}</saml:Attribute>`;
+        })
+            .join('')}</saml:AttributeStatement>`;
+    // A real refusal carries a status and **no assertion** — there is nobody to
+    // assert anything about. Building it any other way would test a shape no
+    // identity provider emits.
+    if (options.status && !options.status.endsWith(':Success')) {
+        const refusal = `<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ` +
+            `xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ` +
+            `ID="_response1" Version="2.0" IssueInstant="${iso(issued)}" ` +
+            `Destination="${exports.CALLBACK}">` +
+            `<saml:Issuer>${exports.IDP_ISSUER}</saml:Issuer>` +
+            `<samlp:Status><samlp:StatusCode Value="${options.status}"/></samlp:Status>` +
+            `</samlp:Response>`;
+        return Buffer.from(sign(refusal, options.signWith ?? idp, 'Response'), 'utf8').toString('base64');
+    }
+    const xml = `<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ` +
+        `xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ` +
+        `ID="_response1" Version="2.0" IssueInstant="${iso(issued)}" ` +
+        `Destination="${exports.CALLBACK}">` +
+        `<saml:Issuer>${exports.IDP_ISSUER}</saml:Issuer>` +
+        `<samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></samlp:Status>` +
+        `<saml:Assertion ID="_assertion1" Version="2.0" IssueInstant="${iso(issued)}">` +
+        `<saml:Issuer>${exports.IDP_ISSUER}</saml:Issuer>` +
+        `<saml:Subject>` +
+        `<saml:NameID Format="${options.nameIdFormat ?? PERSISTENT}">${options.nameId ?? 'idp-subject-1'}</saml:NameID>` +
+        `<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">` +
+        `<saml:SubjectConfirmationData NotOnOrAfter="${iso(expires)}" Recipient="${exports.CALLBACK}"/>` +
+        `</saml:SubjectConfirmation>` +
+        `</saml:Subject>` +
+        `<saml:Conditions NotBefore="${iso(issued)}" NotOnOrAfter="${iso(expires)}">` +
+        `<saml:AudienceRestriction><saml:Audience>${exports.SP_ISSUER}</saml:Audience></saml:AudienceRestriction>` +
+        `</saml:Conditions>` +
+        `<saml:AuthnStatement AuthnInstant="${iso(issued)}" SessionIndex="${options.sessionIndex ?? 'idp-session-1'}">` +
+        `<saml:AuthnContext><saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef></saml:AuthnContext>` +
+        `</saml:AuthnStatement>` +
+        attributes +
+        `</saml:Assertion>` +
+        `</samlp:Response>`;
+    const signer = options.signWith ?? idp;
+    // Assertion first, then the whole response: an outer signature has to cover
+    // the inner one, so signing in the other order invalidates it immediately.
+    const signedAssertion = sign(xml, signer, 'Assertion');
+    const signed = sign(signedAssertion, signer, 'Response');
+    return Buffer.from(signed, 'utf8').toString('base64');
+}
+/** Adds an enveloped signature over one element, in place. */
+function sign(xml, identity, element) {
+    const sig = new xml_crypto_1.SignedXml({
+        privateKey: identity.privateKey,
+        publicCert: identity.cert,
+        signatureAlgorithm: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
+        canonicalizationAlgorithm: 'http://www.w3.org/2001/10/xml-exc-c14n#'
+    });
+    sig.addReference({
+        xpath: `//*[local-name(.)='${element}']`,
+        transforms: [
+            'http://www.w3.org/2000/09/xmldsig#enveloped-signature',
+            'http://www.w3.org/2001/10/xml-exc-c14n#'
+        ],
+        digestAlgorithm: 'http://www.w3.org/2001/04/xmlenc#sha256'
+    });
+    sig.computeSignature(xml, {
+        // Immediately after the element's own `Issuer`, which is where the
+        // schema puts a signature and where every identity provider emits it.
+        location: {
+            reference: `//*[local-name(.)='${element}']/*[local-name(.)='Issuer']`,
+            action: 'after'
+        }
+    });
+    return sig.getSignedXml();
+}
+/** The callback the core would build from an identity provider's form POST. */
+function callbackWith(overrides = {}) {
+    return {
+        params: {
+            RelayState: exports.CORE_SECRETS.state,
+            ...overrides
+        },
+        state: exports.CORE_SECRETS.state,
+        nonce: exports.CORE_SECRETS.nonce,
+        codeVerifier: exports.CORE_SECRETS.codeVerifier,
+        redirectUri: exports.CALLBACK
+    };
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "@orthacms/identity-provider-saml",
+    "version": "0.4.0",
+    "description": "@orthacms/identity-provider-saml — part of Ortha CMS.",
+    "license": "MIT",
+    "homepage": "https://github.com/ortha-source/ortha-cms/tree/main/packages/identity/provider-saml",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ortha-source/ortha-cms.git",
+        "directory": "packages/identity/provider-saml"
+    },
+    "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": {
+        "@node-saml/node-saml": "^5.1.0",
+        "@orthacms/identity-domain": "^0.4.0",
+        "selfsigned": "^5.5.0",
+        "tslib": "^2.3.0",
+        "xml-crypto": "^6.1.2"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}