@better-auth/sso 1.7.0-rc.2 → 1.7.0-rc.3

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { t as PACKAGE_VERSION } from "./version-m-Zfjx6T.mjs";
+import { t as PACKAGE_VERSION } from "./version-xoFrTW0m.mjs";
 import { APIError, addOAuthServerContext, createAuthEndpoint, createAuthMiddleware, getSessionFromCtx, sessionMiddleware } from "better-auth/api";
 import { XMLParser, XMLValidator } from "fast-xml-parser";
 import { X509Certificate } from "node:crypto";
@@ -11,15 +11,16 @@ import { classifyHost, isPublicRoutableHost } from "@better-auth/core/utils/host
 import { betterFetch } from "@better-fetch/fetch";
 import { createRemoteJWKSet, customFetch, jwtVerify } from "jose";
 import { base64, base64Url } from "@better-auth/utils/base64";
-import { defineErrorCodes } from "@better-auth/core/utils/error-codes";
+import { createHash } from "@better-auth/utils/hash";
+import { DOMParser } from "@xmldom/xmldom";
 import * as samlifyNamespace from "samlify";
 import samlifyDefault from "samlify";
+import { defineErrorCodes } from "@better-auth/core/utils/error-codes";
 import { parseInputData, toZodSchema } from "better-auth/db";
 import { isAPIError } from "@better-auth/core/utils/is-api-error";
 import { HIDE_METADATA, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, authorizationCodeRequest, createAuthorizationURL, createPrivateKeyJwtClientAssertionGetter, generateGenericState, generateState, getOAuth2Tokens, parseGenericState, parseState } from "better-auth";
 import { deleteSessionCookie, setAccountCookie, setSessionCookie } from "better-auth/cookies";
 import { additionalAuthorizationParamsSchema, handleOAuthUserInfo } from "better-auth/oauth2";
-import { createHash } from "@better-auth/utils/hash";
 //#region src/constants.ts
 /**
 * SAML Constants
@@ -817,6 +818,102 @@ function mapDiscoveryErrorToAPIError(error) {
 	}
 }
 //#endregion
+//#region src/provider-reference.ts
+const SSO_PROVIDER_STATE_KEY = "ssoProviderReference";
+function serializeCanonical(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return `[${value.map((entry) => entry === void 0 ? "null" : serializeCanonical(entry)).join(",")}]`;
+	switch (typeof value) {
+		case "boolean":
+		case "number":
+		case "string": return JSON.stringify(value);
+		case "object": return `{${Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, entry]) => `${JSON.stringify(key)}:${serializeCanonical(entry)}`).join(",")}}`;
+		default: throw new TypeError("SSO provider configuration must be JSON-serializable");
+	}
+}
+function withoutOIDCSecret(configuration) {
+	if (!configuration) return void 0;
+	const result = { ...configuration };
+	result.clientSecret = void 0;
+	return result;
+}
+function withoutSAMLPrivateKeys(configuration) {
+	if (!configuration) return void 0;
+	return {
+		...configuration,
+		privateKey: void 0,
+		idpMetadata: {
+			...configuration.idpMetadata,
+			privateKey: void 0,
+			privateKeyPass: void 0,
+			encPrivateKey: void 0,
+			encPrivateKeyPass: void 0
+		},
+		spMetadata: configuration.spMetadata ? {
+			...configuration.spMetadata,
+			privateKey: void 0,
+			privateKeyPass: void 0,
+			encPrivateKey: void 0,
+			encPrivateKeyPass: void 0
+		} : void 0
+	};
+}
+function getProviderSource(provider) {
+	return typeof provider.id === "string" && provider.id.length > 0 ? {
+		type: "persisted",
+		recordId: provider.id
+	} : { type: "configured" };
+}
+async function computeProviderAuthenticationFingerprint(provider) {
+	const digest = await createHash("SHA-256").digest(serializeCanonical({
+		domain: provider.domain,
+		domainVerified: "domainVerified" in provider ? provider.domainVerified : void 0,
+		issuer: provider.issuer,
+		organizationId: provider.organizationId,
+		oidcConfig: withoutOIDCSecret(provider.oidcConfig),
+		samlConfig: withoutSAMLPrivateKeys(provider.samlConfig)
+	}));
+	return base64Url.encode(new Uint8Array(digest), { padding: false });
+}
+async function computeSSOProviderReference(provider) {
+	return {
+		providerId: provider.providerId,
+		source: getProviderSource(provider),
+		authenticationConfigurationFingerprint: await computeProviderAuthenticationFingerprint(provider)
+	};
+}
+function isRecord$2(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseSSOProviderReference(value) {
+	if (!isRecord$2(value) || !isRecord$2(value.source)) return null;
+	const providerId = value.providerId;
+	const authenticationConfigurationFingerprint = value.authenticationConfigurationFingerprint;
+	const source = value.source;
+	if (typeof providerId !== "string" || providerId.length === 0 || typeof authenticationConfigurationFingerprint !== "string" || authenticationConfigurationFingerprint.length === 0) return null;
+	if (source.type === "configured") return {
+		providerId,
+		source: { type: "configured" },
+		authenticationConfigurationFingerprint
+	};
+	if (source.type === "persisted" && typeof source.recordId === "string" && source.recordId.length > 0) return {
+		providerId,
+		source: {
+			type: "persisted",
+			recordId: source.recordId
+		},
+		authenticationConfigurationFingerprint
+	};
+	return null;
+}
+async function isCurrentSSOProviderReference(provider, reference) {
+	if (!reference || reference.providerId !== provider.providerId) return false;
+	const source = getProviderSource(provider);
+	if (source.type !== reference.source.type) return false;
+	if (source.type === "persisted" && (reference.source.type !== "persisted" || source.recordId !== reference.source.recordId)) return false;
+	return reference.authenticationConfigurationFingerprint === await computeProviderAuthenticationFingerprint(provider);
+}
+//#endregion
 //#region src/saml/parser.ts
 const xmlParser = new XMLParser({
 	ignoreAttributes: false,
@@ -1030,8 +1127,12 @@ function validateConfigAlgorithms(config, options = {}) {
 		});
 	}
 }
+const saml = typeof samlifyNamespace.SPMetadata === "function" && typeof samlifyNamespace.setSchemaValidator === "function" ? samlifyNamespace : samlifyDefault ?? samlifyNamespace;
 //#endregion
 //#region src/saml/assertions.ts
+const SAML_ASSERTION_NAMESPACE = "urn:oasis:names:tc:SAML:2.0:assertion";
+const SAML_PROTOCOL_NAMESPACE = "urn:oasis:names:tc:SAML:2.0:protocol";
+const XML_SIGNATURE_NAMESPACE = "http://www.w3.org/2000/09/xmldsig#";
 function countAssertions(xml) {
 	let parsed;
 	try {
@@ -1071,6 +1172,39 @@ function validateSingleAssertion(samlResponse) {
 		code: "SAML_MULTIPLE_ASSERTIONS"
 	});
 }
+function assertionSignatureFailure() {
+	return new APIError("BAD_REQUEST", {
+		code: "SAML_ASSERTION_SIGNATURE_REQUIRED",
+		message: "SAML assertion signature is required"
+	});
+}
+/**
+* Verifies that the sole plaintext SAML Assertion, rather than only its
+* enclosing Response, is authenticated by an XML signature from the IdP.
+*/
+function verifySAMLAssertionSignature(samlContent, verificationOptions) {
+	try {
+		const document = new DOMParser({ onError: (_level, message) => {
+			throw new Error(message);
+		} }).parseFromString(samlContent, "text/xml");
+		const response = document.documentElement;
+		if (!response || response.localName !== "Response" || response.namespaceURI !== SAML_PROTOCOL_NAMESPACE) throw assertionSignatureFailure();
+		const assertionElements = Array.from(response.childNodes).filter((node) => node.nodeType === 1 && node.localName === "Assertion" && node.namespaceURI === SAML_ASSERTION_NAMESPACE);
+		const assertion = assertionElements.at(0);
+		if (assertionElements.length !== 1 || !assertion) throw assertionSignatureFailure();
+		if (Array.from(assertion.childNodes).filter((node) => node.nodeType === 1 && node.localName === "Signature" && node.namespaceURI === XML_SIGNATURE_NAMESPACE).length !== 1) throw assertionSignatureFailure();
+		for (const node of Array.from(response.childNodes)) if (node.nodeType === 1 && node.localName === "Signature") response.removeChild(node);
+		const assertionId = assertion.getAttribute("ID");
+		if (!assertionId) throw assertionSignatureFailure();
+		const [verified, authenticatedAssertion] = saml.SamlLib.verifySignature(document.toString(), verificationOptions);
+		if (!verified || !authenticatedAssertion) throw assertionSignatureFailure();
+		const authenticatedRoot = new DOMParser().parseFromString(authenticatedAssertion, "text/xml").documentElement;
+		if (!authenticatedRoot || authenticatedRoot.localName !== "Assertion" || authenticatedRoot.namespaceURI !== SAML_ASSERTION_NAMESPACE || authenticatedRoot.getAttribute("ID") !== assertionId) throw assertionSignatureFailure();
+	} catch (error) {
+		if (error instanceof APIError && error.body?.code === "SAML_ASSERTION_SIGNATURE_REQUIRED") throw error;
+		throw assertionSignatureFailure();
+	}
+}
 //#endregion
 //#region src/saml/error-codes.ts
 const SAML_ERROR_CODES = defineErrorCodes({
@@ -1116,6 +1250,7 @@ function validateCertSources(config) {
 //#region src/saml/response-binding.ts
 const SAML_HTTP_POST_BINDING = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST";
 const SAML_BEARER_CONFIRMATION_METHOD = "urn:oasis:names:tc:SAML:2.0:cm:bearer";
+const SAML_METADATA_NAMESPACE = "urn:oasis:names:tc:SAML:2.0:metadata";
 function toNode(value) {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
 	return value;
@@ -1147,11 +1282,75 @@ function parseSAMLContent(samlContent) {
 		code: "SAML_RESPONSE_INVALID_XML"
 	});
 }
+function directMetadataChildren(element, localName) {
+	return Array.from(element.childNodes).filter((node) => node.nodeType === 1 && node.localName === localName && node.namespaceURI === SAML_METADATA_NAMESPACE);
+}
+function parseXMLSchemaBoolean(value) {
+	if (value === null) return false;
+	switch (value.trim()) {
+		case "true":
+		case "1": return true;
+		case "false":
+		case "0": return false;
+		default: throw new Error("Invalid XML Schema boolean");
+	}
+}
+function isAbsoluteHttpUrl(value) {
+	if (value.includes("#")) return false;
+	try {
+		const url = new URL(value);
+		return url.protocol === "http:" || url.protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+/**
+* Parses the security- and identity-relevant parts of SAML service-provider
+* metadata without relying on local-name-only XML matching.
+*/
+function parseSAMLServiceProviderMetadata(metadata) {
+	const document = new DOMParser({ onError: (_level, message) => {
+		throw new Error(message);
+	} }).parseFromString(metadata, "text/xml");
+	const entityDescriptor = document.documentElement;
+	if (!entityDescriptor || entityDescriptor.localName !== "EntityDescriptor" || entityDescriptor.namespaceURI !== SAML_METADATA_NAMESPACE) throw new Error("Invalid SAML EntityDescriptor");
+	const entityID = entityDescriptor.getAttribute("entityID")?.trim();
+	if (!entityID) throw new Error("Missing SAML entityID");
+	const serviceProviderDescriptors = directMetadataChildren(entityDescriptor, "SPSSODescriptor");
+	if (serviceProviderDescriptors.length === 0) throw new Error("SAML metadata must contain an SPSSODescriptor");
+	const acceptedServiceProviderDescriptors = new Set(serviceProviderDescriptors);
+	for (const element of Array.from(document.getElementsByTagName("*"))) {
+		if (element.localName === "EntityDescriptor" && element !== entityDescriptor) throw new Error("Invalid nested SAML EntityDescriptor");
+		if (element.localName === "SPSSODescriptor" && !acceptedServiceProviderDescriptors.has(element)) throw new Error("Invalid SAML SPSSODescriptor namespace or position");
+		if ((element.localName === "AssertionConsumerService" || element.localName === "NameIDFormat") && (element.namespaceURI !== SAML_METADATA_NAMESPACE || !element.parentNode || !acceptedServiceProviderDescriptors.has(element.parentNode))) throw new Error(`Invalid SAML ${element.localName} namespace or position`);
+	}
+	const postAssertionConsumerServiceUrls = [];
+	const nameIDFormats = [];
+	let wantAssertionsSigned = false;
+	for (const descriptor of serviceProviderDescriptors) {
+		wantAssertionsSigned = parseXMLSchemaBoolean(descriptor.getAttribute("WantAssertionsSigned")) || wantAssertionsSigned;
+		for (const nameIDFormat of directMetadataChildren(descriptor, "NameIDFormat")) {
+			const value = nameIDFormat.textContent?.trim();
+			if (value) nameIDFormats.push(value);
+		}
+		for (const service of directMetadataChildren(descriptor, "AssertionConsumerService")) {
+			if (service.getAttribute("Binding") !== "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST") continue;
+			const location = service.getAttribute("Location")?.trim();
+			if (!location || !isAbsoluteHttpUrl(location)) throw new Error("Invalid SAML POST AssertionConsumerService");
+			postAssertionConsumerServiceUrls.push(location);
+		}
+	}
+	return {
+		entityID,
+		nameIDFormats: [...new Set(nameIDFormats)],
+		postAssertionConsumerServiceUrls: [...new Set(postAssertionConsumerServiceUrls)],
+		wantAssertionsSigned
+	};
+}
 function getSAMLPostAssertionConsumerServiceUrls(metadata) {
 	if (!metadata) return [];
 	try {
-		const locations = toNodeArray(findNode(toNode(xmlParser.parse(metadata)), "SPSSODescriptor")).flatMap((descriptor) => toNodeArray(descriptor.AssertionConsumerService).filter((service) => service["@_Binding"] === SAML_HTTP_POST_BINDING).map((service) => service["@_Location"]).filter((location) => typeof location === "string" && !!location));
-		return [...new Set(locations)];
+		return parseSAMLServiceProviderMetadata(metadata).postAssertionConsumerServiceUrls;
 	} catch {
 		return [];
 	}
@@ -1251,7 +1450,7 @@ function errorRedirectUrl(base, error, description) {
 * samlify's parsed output (not at the top level).
 */
 async function validateInResponseTo(c, ctx) {
-	if (ctx.options.enableInResponseToValidation === false) return;
+	if (ctx.options.enableInResponseToValidation === false) return null;
 	const inResponseTo = ctx.extract.response?.inResponseTo;
 	const allowIdpInitiated = ctx.options.allowIdpInitiated ?? false;
 	if (inResponseTo) {
@@ -1277,10 +1476,23 @@ async function validateInResponseTo(c, ctx) {
 			});
 			throw c.redirect(errorRedirectUrl(ctx.redirectUrl, "invalid_saml_response", "Provider mismatch"));
 		}
+		const providerReference = parseSSOProviderReference(storedRequest.providerReference);
+		if (!providerReference) {
+			c.context.logger.error("SAML InResponseTo validation failed: provider reference missing or invalid", {
+				inResponseTo,
+				providerId: ctx.providerId
+			});
+			throw c.redirect(errorRedirectUrl(ctx.redirectUrl, "invalid_state", "SSO provider reference missing or invalid"));
+		}
+		return {
+			...storedRequest,
+			providerReference
+		};
 	} else if (!allowIdpInitiated) {
 		c.context.logger.error("SAML IdP-initiated SSO rejected: InResponseTo missing and allowIdpInitiated is false", { providerId: ctx.providerId });
 		throw c.redirect(errorRedirectUrl(ctx.redirectUrl, "unsolicited_response", "IdP-initiated SSO not allowed"));
 	}
+	return null;
 }
 /**
 * Validates the AudienceRestriction of a SAML assertion.
@@ -1310,7 +1522,93 @@ function validateAudience(c, ctx) {
 		throw c.redirect(errorRedirectUrl(ctx.redirectUrl, "invalid_saml_response", "Audience mismatch"));
 	}
 }
-const saml = typeof samlifyNamespace.SPMetadata === "function" && typeof samlifyNamespace.setSchemaValidator === "function" ? samlifyNamespace : samlifyDefault ?? samlifyNamespace;
+//#endregion
+//#region src/user-resolution.ts
+const SSO_AUTHENTICATION_FAILURE = Symbol("SSO_AUTHENTICATION_FAILURE");
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.trim().length > 0;
+}
+function isSSOUserResolution(value) {
+	if (!isRecord$1(value)) return false;
+	if (value.action === "continue") return true;
+	if (value.action === "link") return isNonEmptyString(value.userId) && (value.profile === "preserve" || value.profile === "update");
+	return value.action === "reject" && isNonEmptyString(value.code) && (value.message === void 0 || typeof value.message === "string");
+}
+function logFailure(logger, message) {
+	try {
+		logger.error(message);
+	} catch {}
+}
+function resolutionFailure() {
+	return new APIError("INTERNAL_SERVER_ERROR", {
+		code: "SSO_USER_RESOLUTION_FAILED",
+		message: "Unable to resolve the SSO user"
+	});
+}
+async function resolveSSOUser(resolveUser, input, database, logger) {
+	let resolution;
+	try {
+		resolution = await resolveUser(input, { database });
+	} catch {
+		logFailure(logger, "SSO user resolution failed");
+		throw resolutionFailure();
+	}
+	if (!isSSOUserResolution(resolution)) {
+		logFailure(logger, "SSO user resolver returned an invalid decision");
+		throw resolutionFailure();
+	}
+	return resolution;
+}
+function assertSSOUserResolutionNativeTransactionSupport(adapter) {
+	assertSSONativeTransactionSupport(adapter, {
+		code: "SSO_USER_RESOLUTION_REQUIRES_NATIVE_TRANSACTIONS",
+		message: "SSO user resolution requires a database adapter with native transaction support"
+	});
+}
+function assertSSONativeTransactionSupport(adapter, error) {
+	if (typeof adapter.options?.adapterConfig.transaction === "function") return;
+	throw new APIError("NOT_IMPLEMENTED", {
+		code: error.code,
+		message: error.message
+	});
+}
+async function assertSSOUserResolutionAsyncContextSupport(getStorage = getCurrentDBAdapterAsyncLocalStorage) {
+	await assertSSOAsyncContextSupport({
+		code: "SSO_USER_RESOLUTION_REQUIRES_ASYNC_CONTEXT",
+		message: "SSO user resolution requires database transaction async context support"
+	}, getStorage);
+}
+async function assertSSOAsyncContextSupport(error, getStorage = getCurrentDBAdapterAsyncLocalStorage) {
+	try {
+		await getStorage();
+	} catch {
+		throw new APIError("NOT_IMPLEMENTED", {
+			code: error.code,
+			message: error.message
+		});
+	}
+}
+function assertSSOUserResolutionSessionStorage(options) {
+	if (!options.secondaryStorage || options.session?.storeSessionInDatabase === true && options.session.preserveSessionInDatabase !== true) return;
+	throw new APIError("NOT_IMPLEMENTED", {
+		code: "SSO_USER_RESOLUTION_REQUIRES_DATABASE_SESSIONS",
+		message: "SSO user resolution requires database-backed sessions with database fallback"
+	});
+}
+function requireSuccessfulSSOAuthentication(result) {
+	if (!result.error) return result;
+	throw Object.assign(/* @__PURE__ */ new Error("SSO authentication failed"), {
+		[SSO_AUTHENTICATION_FAILURE]: true,
+		result
+	});
+}
+function getFailedSSOAuthenticationResult(error) {
+	if (!(error instanceof Error) || !(SSO_AUTHENTICATION_FAILURE in error) || error[SSO_AUTHENTICATION_FAILURE] !== true || !("result" in error)) return;
+	return error.result;
+}
 //#endregion
 //#region src/routes/helpers.ts
 /**
@@ -1349,6 +1647,7 @@ function createSP(config, baseURL, providerId, opts) {
 	const sloLocation = `${baseURL}/sso/saml2/sp/slo/${providerId}`;
 	const acsUrl = `${baseURL}/sso/saml2/sp/acs/${providerId}`;
 	let metadata = spData?.metadata;
+	assertSAMLServiceProviderMetadataPolicy(config);
 	if (!metadata) metadata = saml.SPMetadata({
 		entityID: spData?.entityID || config.issuer,
 		assertionConsumerService: [{
@@ -1362,7 +1661,7 @@ function createSP(config, baseURL, providerId, opts) {
 			Binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
 			Location: sloLocation
 		}] : void 0,
-		wantMessageSigned: config.wantAssertionsSigned || false,
+		wantAssertionsSigned: config.wantAssertionsSigned || false,
 		authnRequestsSigned: config.authnRequestsSigned || false,
 		nameIDFormat: config.identifierFormat ? [config.identifierFormat] : void 0
 	}).getMetadata() || "";
@@ -1380,6 +1679,42 @@ function createSP(config, baseURL, providerId, opts) {
 		clockDrifts: opts?.clockSkew && opts?.clockSkew !== 0 ? [-opts.clockSkew, opts.clockSkew] : void 0
 	});
 }
+/**
+* Ensures custom SP metadata cannot weaken the configured assertion-signing
+* policy. This is safe to call before persisting a provider configuration.
+*/
+function assertSAMLServiceProviderMetadataPolicy(config) {
+	const policy = deriveSAMLServiceProviderPolicy(config);
+	if (config.wantAssertionsSigned !== true || policy.wantAssertionsSigned) return;
+	throw new APIError("BAD_REQUEST", {
+		code: "SAML_SP_METADATA_ASSERTION_SIGNATURE_MISMATCH",
+		message: "SAML service provider metadata must require signed assertions"
+	});
+}
+function assertSAMLMetadataSize(metadata, kind, maxMetadataSize) {
+	if (metadata && new TextEncoder().encode(metadata).length > maxMetadataSize) throw new APIError("BAD_REQUEST", { message: `${kind} metadata exceeds maximum allowed size (${maxMetadataSize} bytes)` });
+}
+/**
+* Parses custom SP metadata and returns its effective verification policy.
+*
+* Configurations without custom metadata use the code-defined policy directly.
+* Invalid or unusable custom metadata throws an API error with the
+* `SAML_INVALID_SP_METADATA` code.
+*/
+function deriveSAMLServiceProviderPolicy(config) {
+	const metadata = config.spMetadata?.metadata;
+	if (!metadata) return { wantAssertionsSigned: config.wantAssertionsSigned === true };
+	try {
+		const parsedMetadata = parseSAMLServiceProviderMetadata(metadata);
+		if (!parsedMetadata.postAssertionConsumerServiceUrls.length) throw new Error("Unusable SAML service provider metadata");
+		return { wantAssertionsSigned: parsedMetadata.wantAssertionsSigned };
+	} catch {
+		throw new APIError("BAD_REQUEST", {
+			code: "SAML_INVALID_SP_METADATA",
+			message: "Invalid SAML service provider metadata"
+		});
+	}
+}
 function assertSAMLIdentityProviderAuthority(config) {
 	if (config.idpMetadata?.metadata || config.idpMetadata?.entityID) return;
 	throw new APIError("BAD_REQUEST", { message: "SAML manual IdP configuration requires idpMetadata.entityID; issuer identifies the service provider and cannot identify the IdP" });
@@ -1409,6 +1744,13 @@ function createIdP(config) {
 		encPrivateKeyPass: idpData.encPrivateKeyPass
 	});
 }
+/**
+* Derive the verified SAML identity-provider entity ID using the same metadata
+* parsing and manual-configuration validation as SAML authentication.
+*/
+function deriveSAMLIdentityProviderEntityID(config) {
+	return createIdP(config).entityMeta.getEntityID();
+}
 function escapeHtml(str) {
 	if (!str) return "";
 	return String(str).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
@@ -1586,24 +1928,13 @@ const OIDC_IDENTITY_BOUNDARY_FIELDS = [
 	"tokenEndpoint",
 	"userInfoEndpoint"
 ];
-const SAML_IDENTITY_BOUNDARY_FIELDS = [
-	"audience",
-	"callbackUrl",
-	"entryPoint",
-	"identifierFormat"
-];
-const SAML_IDP_BOUNDARY_FIELDS = [
-	"metadata",
-	"entityID",
-	"singleSignOnService"
-];
-const SAML_SP_BOUNDARY_FIELDS = ["metadata", "entityID"];
-function isRecord$2(value) {
+const SAML_IDENTITY_BOUNDARY_FIELDS = ["audience", "callbackUrl"];
+function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function stableStringify(value) {
 	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
-	if (isRecord$2(value)) return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
+	if (isRecord(value)) return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
 	return JSON.stringify(value) ?? String(value);
 }
 function identityValueChanged(current, updated) {
@@ -1616,7 +1947,34 @@ function oidcIdentityBoundaryChanged(current, updated) {
 	return hasChangedField(current, updated, OIDC_IDENTITY_BOUNDARY_FIELDS);
 }
 function samlIdentityBoundaryChanged(current, updated) {
-	return hasChangedField(current, updated, SAML_IDENTITY_BOUNDARY_FIELDS) || hasChangedField(current.idpMetadata, updated.idpMetadata, SAML_IDP_BOUNDARY_FIELDS) || hasChangedField(current.spMetadata, updated.spMetadata, SAML_SP_BOUNDARY_FIELDS);
+	const currentIdentityProvider = createIdP(current).entityMeta;
+	const updatedIdentityProvider = createIdP(updated).entityMeta;
+	let currentServiceProvider;
+	let updatedServiceProvider;
+	try {
+		currentServiceProvider = current.spMetadata?.metadata ? parseSAMLServiceProviderMetadata(current.spMetadata.metadata) : null;
+		updatedServiceProvider = updated.spMetadata?.metadata ? parseSAMLServiceProviderMetadata(updated.spMetadata.metadata) : null;
+	} catch {
+		return true;
+	}
+	const effectiveIdentityBoundary = (config) => {
+		const identityProvider = config === current ? currentIdentityProvider : updatedIdentityProvider;
+		const serviceProvider = config === current ? currentServiceProvider : updatedServiceProvider;
+		return {
+			idpEntityId: identityProvider.getEntityID(),
+			idpRedirectService: identityProvider.getSingleSignOnService("redirect"),
+			idpPostService: identityProvider.getSingleSignOnService("post"),
+			spEntityId: serviceProvider?.entityID ?? config.spMetadata?.entityID ?? config.issuer,
+			spNameIDFormat: serviceProvider?.nameIDFormats.at(0) ?? config.identifierFormat,
+			spPostServices: serviceProvider ? getSAMLPostAssertionConsumerServiceUrls(config.spMetadata?.metadata) : config.callbackUrl ? [config.callbackUrl] : [],
+			wantAssertionsSigned: serviceProvider?.wantAssertionsSigned ?? config.wantAssertionsSigned === true
+		};
+	};
+	const trustAnchors = (identityProvider) => {
+		const certificates = identityProvider.getX509Certificate("signing");
+		return (Array.isArray(certificates) ? certificates : certificates ? [certificates] : []).map((certificate) => normalizePem(certificate) ?? certificate).sort();
+	};
+	return hasChangedField(current, updated, SAML_IDENTITY_BOUNDARY_FIELDS) || identityValueChanged(trustAnchors(currentIdentityProvider), trustAnchors(updatedIdentityProvider)) || identityValueChanged(effectiveIdentityBoundary(current), effectiveIdentityBoundary(updated));
 }
 function parseConfigSnapshot(config, configType) {
 	if (!config) return;
@@ -1632,19 +1990,67 @@ function ssoProviderIdentityBoundaryChanged(current, updated) {
 	const updatedOidcConfig = parseConfigSnapshot(updated.oidcConfig, "OIDC");
 	return Boolean(currentOidcConfig && (!updatedOidcConfig || oidcIdentityBoundaryChanged(currentOidcConfig, updatedOidcConfig)));
 }
-async function lockSSOProviderRow(adapter, providerId) {
-	return (await getCurrentAdapter(adapter)).update({
+async function lockSSOProviderRow(context, provider) {
+	const where = [...provider.id ? [{
+		field: "id",
+		value: provider.id
+	}] : [], {
+		field: "providerId",
+		value: provider.providerId
+	}];
+	return (await getCurrentAdapter(context.adapter)).update({
 		model: "ssoProvider",
-		where: [{
-			field: "providerId",
-			value: providerId
-		}],
-		update: { providerId }
+		where,
+		update: { providerId: provider.providerId }
+	});
+}
+async function guardSSOProviderMutation(options, mutation, provider, database, logger) {
+	if (!options?.guardProviderMutation) return;
+	const oidcConfig = provider.oidcConfig ? parseConfigSnapshot(provider.oidcConfig, "OIDC") : void 0;
+	const samlConfig = provider.samlConfig ? parseConfigSnapshot(provider.samlConfig, "SAML") : void 0;
+	const providerReference = await computeSSOProviderReference({
+		...provider,
+		organizationId: provider.organizationId ?? void 0,
+		oidcConfig,
+		samlConfig
+	});
+	try {
+		await options.guardProviderMutation({
+			...mutation,
+			provider: {
+				id: provider.id,
+				providerId: provider.providerId,
+				organizationId: provider.organizationId ?? null
+			},
+			providerReference
+		}, { database });
+	} catch {
+		try {
+			logger.error("SSO provider mutation guard rejected the mutation");
+		} catch {}
+		throw new APIError("CONFLICT", {
+			code: "SSO_PROVIDER_MUTATION_REJECTED",
+			message: "SSO provider mutation is not allowed"
+		});
+	}
+}
+async function assertProviderMutationGuardCapabilities(options, adapter) {
+	if (!options?.guardProviderMutation) return;
+	assertSSONativeTransactionSupport(adapter, {
+		code: "SSO_PROVIDER_MUTATION_GUARD_REQUIRES_NATIVE_TRANSACTIONS",
+		message: "SSO provider mutation guards require a database adapter with native transaction support"
+	});
+	await assertSSOAsyncContextSupport({
+		code: "SSO_PROVIDER_MUTATION_GUARD_REQUIRES_ASYNC_CONTEXT",
+		message: "SSO provider mutation guards require database transaction async context support"
 	});
 }
 async function lockSSOProviderForAccountLink(ctx, provider) {
 	if (typeof provider.id !== "string") return;
-	const lockedProvider = await lockSSOProviderRow(ctx.context.adapter, provider.providerId);
+	const lockedProvider = await lockSSOProviderRow(ctx.context, {
+		id: provider.id,
+		providerId: provider.providerId
+	});
 	if (!lockedProvider) throw new APIError("CONFLICT", {
 		code: "SSO_PROVIDER_CHANGED",
 		message: "SSO provider changed while account linking was in progress"
@@ -1913,10 +2319,14 @@ const updateSSOProvider = (options) => {
 		const { issuer, domain, samlConfig, oidcConfig } = body;
 		const additionalFields = parseSSOProviderAdditionalFields(options, body, "update");
 		if (!issuer && !domain && !samlConfig && !oidcConfig && Object.keys(additionalFields).length === 0) throw new APIError("BAD_REQUEST", { message: "No fields provided for update" });
-		await checkProviderAccess(ctx, providerId);
+		const authorizedProvider = await checkProviderAccess(ctx, providerId);
+		await assertProviderMutationGuardCapabilities(options, ctx.context.adapter);
 		const fullProvider = await runWithTransaction(ctx.context.adapter, async () => {
 			const trx = await getCurrentAdapter(ctx.context.adapter);
-			const existingProvider = await lockSSOProviderRow(ctx.context.adapter, providerId);
+			const existingProvider = await lockSSOProviderRow(ctx.context, {
+				id: authorizedProvider.id,
+				providerId
+			});
 			if (!existingProvider) throw new APIError("NOT_FOUND", { message: "Provider not found" });
 			const updateData = { ...additionalFields };
 			let providerIdentityBoundaryChanged = body.issuer !== void 0 && body.issuer !== existingProvider.issuer;
@@ -1926,10 +2336,9 @@ const updateSSOProvider = (options) => {
 				if (body.domain !== existingProvider.domain) updateData.domainVerified = false;
 			}
 			if (body.samlConfig) {
-				if (body.samlConfig.idpMetadata?.metadata) {
-					const maxMetadataSize = options?.saml?.maxMetadataSize ?? 102400;
-					if (new TextEncoder().encode(body.samlConfig.idpMetadata.metadata).length > maxMetadataSize) throw new APIError("BAD_REQUEST", { message: `IdP metadata exceeds maximum allowed size (${maxMetadataSize} bytes)` });
-				}
+				const maxMetadataSize = options?.saml?.maxMetadataSize ?? 102400;
+				assertSAMLMetadataSize(body.samlConfig.idpMetadata?.metadata, "IdP", maxMetadataSize);
+				assertSAMLMetadataSize(body.samlConfig.spMetadata?.metadata, "SP", maxMetadataSize);
 				if (body.samlConfig.signatureAlgorithm !== void 0 || body.samlConfig.digestAlgorithm !== void 0) validateConfigAlgorithms({
 					signatureAlgorithm: body.samlConfig.signatureAlgorithm,
 					digestAlgorithm: body.samlConfig.digestAlgorithm
@@ -1938,6 +2347,7 @@ const updateSSOProvider = (options) => {
 				const updatedSamlConfig = mergeSAMLConfig(currentSamlConfig, body.samlConfig, updateData.issuer || currentSamlConfig.issuer || existingProvider.issuer);
 				validateCertSources(updatedSamlConfig);
 				assertSAMLIdentityProviderAuthority(updatedSamlConfig);
+				assertSAMLServiceProviderMetadataPolicy(updatedSamlConfig);
 				if (samlIdentityBoundaryChanged(currentSamlConfig, updatedSamlConfig)) providerIdentityBoundaryChanged = true;
 				updateData.samlConfig = JSON.stringify(updatedSamlConfig);
 			}
@@ -1955,6 +2365,10 @@ const updateSSOProvider = (options) => {
 				if (oidcIdentityBoundaryChanged(currentOidcConfig, updatedOidcConfig)) providerIdentityBoundaryChanged = true;
 				updateData.oidcConfig = JSON.stringify(updatedOidcConfig);
 			}
+			await guardSSOProviderMutation(options, {
+				action: "update",
+				isAuthenticationBoundaryChange: providerIdentityBoundaryChanged
+			}, existingProvider, trx, ctx.context.logger);
 			if (providerIdentityBoundaryChanged) {
 				if (await trx.findOne({
 					model: "account",
@@ -1985,7 +2399,7 @@ const updateSSOProvider = (options) => {
 		return ctx.json(sanitizeProvider(fullProvider, ctx.context.baseURL, options));
 	});
 };
-const deleteSSOProvider = () => {
+const deleteSSOProvider = (options) => {
 	return createAuthEndpoint("/sso/delete-provider", {
 		method: "POST",
 		use: [sessionMiddleware],
@@ -2002,9 +2416,16 @@ const deleteSSOProvider = () => {
 		} }
 	}, async (ctx) => {
 		const { providerId } = ctx.body;
-		await checkProviderAccess(ctx, providerId);
+		const authorizedProvider = await checkProviderAccess(ctx, providerId);
+		await assertProviderMutationGuardCapabilities(options, ctx.context.adapter);
 		await runWithTransaction(ctx.context.adapter, async () => {
 			const trx = await getCurrentAdapter(ctx.context.adapter);
+			const existingProvider = await lockSSOProviderRow(ctx.context, {
+				id: authorizedProvider.id,
+				providerId
+			});
+			if (!existingProvider) throw new APIError("NOT_FOUND", { message: "Provider not found" });
+			await guardSSOProviderMutation(options, { action: "delete" }, existingProvider, trx, ctx.context.logger);
 			await trx.deleteMany({
 				model: "account",
 				where: [{
@@ -2015,6 +2436,9 @@ const deleteSSOProvider = () => {
 			await trx.delete({
 				model: "ssoProvider",
 				where: [{
+					field: "id",
+					value: existingProvider.id
+				}, {
 					field: "providerId",
 					value: providerId
 				}]
@@ -2144,82 +2568,8 @@ const verifyDomain = (options) => {
 	});
 };
 //#endregion
-//#region src/provider-reference.ts
-const SSO_PROVIDER_STATE_KEY = "ssoProviderReference";
-function serializeCanonical(value) {
-	if (value === null) return "null";
-	if (Array.isArray(value)) return `[${value.map((entry) => entry === void 0 ? "null" : serializeCanonical(entry)).join(",")}]`;
-	switch (typeof value) {
-		case "boolean":
-		case "number":
-		case "string": return JSON.stringify(value);
-		case "object": return `{${Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, entry]) => `${JSON.stringify(key)}:${serializeCanonical(entry)}`).join(",")}}`;
-		default: throw new TypeError("SSO provider configuration must be JSON-serializable");
-	}
-}
-function withoutOIDCSecret(configuration) {
-	if (!configuration) return void 0;
-	const result = { ...configuration };
-	result.clientSecret = void 0;
-	return result;
-}
-function getProviderSource(provider) {
-	return typeof provider.id === "string" && provider.id.length > 0 ? {
-		type: "persisted",
-		recordId: provider.id
-	} : { type: "configured" };
-}
-async function computeProviderAuthenticationFingerprint(provider) {
-	const digest = await createHash("SHA-256").digest(serializeCanonical({
-		domain: provider.domain,
-		domainVerified: "domainVerified" in provider ? provider.domainVerified : void 0,
-		issuer: provider.issuer,
-		organizationId: provider.organizationId,
-		oidcConfig: withoutOIDCSecret(provider.oidcConfig)
-	}));
-	return base64Url.encode(new Uint8Array(digest), { padding: false });
-}
-async function computeSSOProviderReference(provider) {
-	return {
-		providerId: provider.providerId,
-		source: getProviderSource(provider),
-		authenticationConfigurationFingerprint: await computeProviderAuthenticationFingerprint(provider)
-	};
-}
-function isRecord$1(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function parseSSOProviderReference(value) {
-	if (!isRecord$1(value) || !isRecord$1(value.source)) return null;
-	const providerId = value.providerId;
-	const authenticationConfigurationFingerprint = value.authenticationConfigurationFingerprint;
-	const source = value.source;
-	if (typeof providerId !== "string" || providerId.length === 0 || typeof authenticationConfigurationFingerprint !== "string" || authenticationConfigurationFingerprint.length === 0) return null;
-	if (source.type === "configured") return {
-		providerId,
-		source: { type: "configured" },
-		authenticationConfigurationFingerprint
-	};
-	if (source.type === "persisted" && typeof source.recordId === "string" && source.recordId.length > 0) return {
-		providerId,
-		source: {
-			type: "persisted",
-			recordId: source.recordId
-		},
-		authenticationConfigurationFingerprint
-	};
-	return null;
-}
-async function isCurrentSSOProviderReference(provider, reference) {
-	if (!reference || reference.providerId !== provider.providerId) return false;
-	const source = getProviderSource(provider);
-	if (source.type !== reference.source.type) return false;
-	if (source.type === "persisted" && (reference.source.type !== "persisted" || source.recordId !== reference.source.recordId)) return false;
-	return reference.authenticationConfigurationFingerprint === await computeProviderAuthenticationFingerprint(provider);
-}
-//#endregion
 //#region src/saml-state.ts
-async function generateRelayState(c, link) {
+async function generateRelayState(c, link, providerReference) {
 	const callbackURL = c.body.callbackURL;
 	if (!callbackURL) throw new APIError("BAD_REQUEST", { message: "callbackURL is required" });
 	const stateData = {
@@ -2232,7 +2582,8 @@ async function generateRelayState(c, link) {
 		* This is the actual expiry time of the state
 		*/
 		expiresAt: Date.now() + 600 * 1e3,
-		requestSignUp: c.body.requestSignUp
+		requestSignUp: c.body.requestSignUp,
+		serverContext: providerReference ? { [SSO_PROVIDER_STATE_KEY]: providerReference } : void 0
 	};
 	try {
 		return generateGenericState(c, stateData, { cookieName: "relay_state" });
@@ -2268,81 +2619,6 @@ async function parseRelayState(c) {
 	return parsedData;
 }
 //#endregion
-//#region src/user-resolution.ts
-const SSO_AUTHENTICATION_FAILURE = Symbol("SSO_AUTHENTICATION_FAILURE");
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isNonEmptyString(value) {
-	return typeof value === "string" && value.trim().length > 0;
-}
-function isSSOUserResolution(value) {
-	if (!isRecord(value)) return false;
-	if (value.action === "continue") return true;
-	if (value.action === "link") return isNonEmptyString(value.userId) && (value.profile === "preserve" || value.profile === "update");
-	return value.action === "reject" && isNonEmptyString(value.code) && (value.message === void 0 || typeof value.message === "string");
-}
-function logFailure(logger, message, error) {
-	try {
-		logger.error(message, ...error === void 0 ? [] : [error]);
-	} catch {}
-}
-function resolutionFailure() {
-	return new APIError("INTERNAL_SERVER_ERROR", {
-		code: "SSO_USER_RESOLUTION_FAILED",
-		message: "Unable to resolve the SSO user"
-	});
-}
-async function resolveSSOUser(resolveUser, input, database, logger) {
-	let resolution;
-	try {
-		resolution = await resolveUser(input, { database });
-	} catch (error) {
-		logFailure(logger, "SSO user resolution failed", error);
-		throw resolutionFailure();
-	}
-	if (!isSSOUserResolution(resolution)) {
-		logFailure(logger, "SSO user resolver returned an invalid decision");
-		throw resolutionFailure();
-	}
-	return resolution;
-}
-function assertSSOUserResolutionNativeTransactionSupport(adapter) {
-	if (typeof adapter.options?.adapterConfig.transaction === "function") return;
-	throw new APIError("NOT_IMPLEMENTED", {
-		code: "SSO_USER_RESOLUTION_REQUIRES_NATIVE_TRANSACTIONS",
-		message: "SSO user resolution requires a database adapter with native transaction support"
-	});
-}
-async function assertSSOUserResolutionAsyncContextSupport(getStorage = getCurrentDBAdapterAsyncLocalStorage) {
-	try {
-		await getStorage();
-	} catch {
-		throw new APIError("NOT_IMPLEMENTED", {
-			code: "SSO_USER_RESOLUTION_REQUIRES_ASYNC_CONTEXT",
-			message: "SSO user resolution requires database transaction async context support"
-		});
-	}
-}
-function assertSSOUserResolutionSessionStorage(options) {
-	if (!options.secondaryStorage || options.session?.storeSessionInDatabase === true && options.session.preserveSessionInDatabase !== true) return;
-	throw new APIError("NOT_IMPLEMENTED", {
-		code: "SSO_USER_RESOLUTION_REQUIRES_DATABASE_SESSIONS",
-		message: "SSO user resolution requires database-backed sessions with database fallback"
-	});
-}
-function requireSuccessfulSSOAuthentication(result) {
-	if (!result.error) return result;
-	throw Object.assign(/* @__PURE__ */ new Error("SSO authentication failed"), {
-		[SSO_AUTHENTICATION_FAILURE]: true,
-		result
-	});
-}
-function getFailedSSOAuthenticationResult(error) {
-	if (!(error instanceof Error) || !(SSO_AUTHENTICATION_FAILURE in error) || error[SSO_AUTHENTICATION_FAILURE] !== true || !("result" in error)) return;
-	return error.result;
-}
-//#endregion
 //#region src/saml/timestamp.ts
 /**
 * Validates SAML assertion timestamp conditions (NotBefore/NotOnOrAfter).
@@ -2385,6 +2661,10 @@ function validateSAMLTimestamp(conditions, options = {}) {
 }
 //#endregion
 //#region src/routes/saml-pipeline.ts
+function isSameSSOProviderReference(left, right) {
+	if (left.providerId !== right.providerId || left.authenticationConfigurationFingerprint !== right.authenticationConfigurationFingerprint || left.source.type !== right.source.type) return false;
+	return left.source.type === "configured" ? true : right.source.type === "persisted" && left.source.recordId === right.source.recordId;
+}
 function getSafeRedirectCandidate(url, callbackPathname, appOrigin, isTrustedOrigin) {
 	if (!url) return;
 	if (url.startsWith("/")) {
@@ -2499,10 +2779,11 @@ async function processSAMLResponse(ctx, params, options) {
 	if (new TextEncoder().encode(params.SAMLResponse).length > maxResponseSize) throw new APIError("BAD_REQUEST", { message: `SAML response exceeds maximum allowed size (${maxResponseSize} bytes)` });
 	const SAMLResponse = params.SAMLResponse.replace(/\s+/g, "");
 	let relayState = null;
+	let relayStateValidationFailed = false;
 	if (params.RelayState) try {
 		relayState = await parseRelayState(ctx);
 	} catch {
-		relayState = null;
+		relayStateValidationFailed = true;
 	}
 	const provider = await findSAMLProvider(providerId, options, ctx.context.adapter);
 	if (!provider?.samlConfig) throw new APIError("NOT_FOUND", { message: "No SAML provider found" });
@@ -2515,6 +2796,7 @@ async function processSAMLResponse(ctx, params, options) {
 	const samlRedirectUrl = getSafeRedirectUrl(redirectCandidates, currentCallbackPath, appOrigin, (url, settings) => ctx.context.isTrustedOrigin(url, settings));
 	const samlErrorRedirectUrl = getSafeRedirectUrl([relayState?.errorURL, samlRedirectUrl], currentCallbackPath, appOrigin, (url, settings) => ctx.context.isTrustedOrigin(url, settings));
 	params.onErrorRedirectResolved?.(samlErrorRedirectUrl);
+	const stateProviderReference = parseSSOProviderReference(relayState?.serverContext?.[SSO_PROVIDER_STATE_KEY]);
 	validateSingleAssertion(SAMLResponse);
 	let parsedResponse;
 	try {
@@ -2523,15 +2805,9 @@ async function processSAMLResponse(ctx, params, options) {
 			RelayState: params.RelayState || void 0
 		} });
 		if (!parsedResponse?.extract) throw new Error("Invalid SAML response structure");
-	} catch (error) {
-		ctx.context.logger.error("SAML response validation failed", {
-			error,
-			samlResponsePreview: SAMLResponse.slice(0, 200)
-		});
-		throw new APIError("BAD_REQUEST", {
-			message: "Invalid SAML response",
-			details: error instanceof Error ? error.message : String(error)
-		});
+	} catch {
+		ctx.context.logger.error("SAML response validation failed");
+		throw new APIError("BAD_REQUEST", { message: "Invalid SAML response" });
 	}
 	const { extract } = parsedResponse;
 	const samlContent = parsedResponse.samlContent;
@@ -2544,9 +2820,14 @@ async function processSAMLResponse(ctx, params, options) {
 	const expectedAudiences = [sp.entityMeta.getEntityID(), parsedSamlConfig.audience];
 	const assertionConsumerServiceUrl = sp.entityMeta.getAssertionConsumerService(SAML_HTTP_POST_BINDING);
 	const expectedRecipients = getExpectedSAMLRecipients(parsedSamlConfig, ctx.context.baseURL, providerId, currentCallbackPath, assertionConsumerServiceUrl);
+	const serviceProviderPolicy = deriveSAMLServiceProviderPolicy(parsedSamlConfig);
 	let samlBindingContent;
 	try {
 		samlBindingContent = await getSAMLResponseBindingContent(sp, samlContent);
+		if (serviceProviderPolicy.wantAssertionsSigned) verifySAMLAssertionSignature(samlBindingContent, {
+			metadata: idp.entityMeta,
+			signatureAlgorithm: idp.entitySetting.requestSignatureAlgorithm
+		});
 		validateSAMLResponseBinding(samlBindingContent, {
 			expectedAudiences,
 			expectedRecipients
@@ -2555,27 +2836,20 @@ async function processSAMLResponse(ctx, params, options) {
 		if (isAPIError(error)) {
 			ctx.context.logger.error("SAML response binding validation failed", {
 				providerId,
-				code: error.body?.code,
-				expectedAudiences: expectedAudiences.filter(Boolean),
-				expectedRecipients: expectedRecipients.filter(Boolean)
+				code: error.body?.code
 			});
 			throw ctx.redirect(buildSAMLRedirectUrl(samlErrorRedirectUrl, {
 				error: "invalid_saml_response",
 				error_description: error.body?.message || error.message || "Invalid SAML response"
 			}));
 		}
-		ctx.context.logger.error("SAML response binding validation failed", {
-			providerId,
-			error,
-			expectedAudiences: expectedAudiences.filter(Boolean),
-			expectedRecipients: expectedRecipients.filter(Boolean)
-		});
+		ctx.context.logger.error("SAML response binding validation failed", { providerId });
 		throw ctx.redirect(buildSAMLRedirectUrl(samlErrorRedirectUrl, {
 			error: "invalid_saml_response",
 			error_description: "SAML response binding could not be validated"
 		}));
 	}
-	await validateInResponseTo(ctx, {
+	const requestProviderReference = (await validateInResponseTo(ctx, {
 		extract,
 		providerId,
 		options: {
@@ -2583,7 +2857,24 @@ async function processSAMLResponse(ctx, params, options) {
 			allowIdpInitiated: options?.saml?.allowIdpInitiated
 		},
 		redirectUrl: samlErrorRedirectUrl
-	});
+	}))?.providerReference;
+	if (relayStateValidationFailed) throw ctx.redirect(buildSAMLRedirectUrl(samlErrorRedirectUrl, {
+		error: "invalid_state",
+		error_description: "invalid_or_expired_relay_state"
+	}));
+	if (relayState && !stateProviderReference) throw ctx.redirect(buildSAMLRedirectUrl(samlErrorRedirectUrl, {
+		error: "invalid_state",
+		error_description: "sso_provider_reference_missing_or_invalid"
+	}));
+	if (stateProviderReference && requestProviderReference && !isSameSSOProviderReference(stateProviderReference, requestProviderReference)) throw ctx.redirect(buildSAMLRedirectUrl(samlErrorRedirectUrl, {
+		error: "invalid_state",
+		error_description: "sso_provider_reference_mismatch"
+	}));
+	const providerReference = stateProviderReference ?? requestProviderReference ?? await computeSSOProviderReference(provider);
+	if (!await isCurrentSSOProviderReference(provider, providerReference)) throw ctx.redirect(buildSAMLRedirectUrl(samlErrorRedirectUrl, {
+		error: "invalid_state",
+		error_description: "sso_provider_changed_during_authentication"
+	}));
 	validateAudience(ctx, {
 		extract,
 		expectedAudience: parsedSamlConfig.audience || sp.entityMeta.getEntityID(),
@@ -2619,6 +2910,9 @@ async function processSAMLResponse(ctx, params, options) {
 		}
 	} else ctx.context.logger.warn("Could not extract assertion ID for replay protection", { providerId });
 	const attributes = extract.attributes || {};
+	const providerAttributes = {};
+	for (const [name, value] of Object.entries(attributes)) if (typeof value === "string") providerAttributes[name] = value;
+	else if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) providerAttributes[name] = value;
 	const mapping = parsedSamlConfig.mapping ?? {};
 	const attr = (key) => {
 		const value = attributes[key];
@@ -2633,31 +2927,63 @@ async function processSAMLResponse(ctx, params, options) {
 	};
 	if (!userInfo.id || !userInfo.email) {
 		ctx.context.logger.error("Missing essential user info from SAML response", {
-			attributes: Object.keys(attributes),
-			mapping,
-			extractedId: userInfo.id,
-			extractedEmail: userInfo.email
+			providerId,
+			attributeNames: Object.keys(attributes),
+			hasNameId: Boolean(userInfo.id),
+			hasEmail: Boolean(userInfo.email)
 		});
 		throw new APIError("BAD_REQUEST", { message: "Unable to extract user ID or email from SAML response" });
 	}
+	const providerUserAttributes = Object.fromEntries(Object.entries(userInfo).filter(([key]) => key !== "id"));
+	const providerUser = {
+		...providerUserAttributes,
+		email: userInfo.email,
+		name: userInfo.name || userInfo.email,
+		image: typeof providerUserAttributes.image === "string" ? providerUserAttributes.image : void 0,
+		emailVerified: userInfo.emailVerified
+	};
+	const accountKey = {
+		issuer,
+		providerAccountId: userInfo.id
+	};
 	const isTrustedProvider = "domainVerified" in provider && !!provider.domainVerified && validateEmailDomain(userInfo.email, provider.domain);
 	const callbackUrl = redirectCandidates.some(Boolean) ? samlRedirectUrl : ctx.context.baseURL;
 	const errorUrl = samlErrorRedirectUrl;
 	let result;
 	try {
+		if (options?.resolveUser) {
+			assertSSOUserResolutionNativeTransactionSupport(ctx.context.adapter);
+			assertSSOUserResolutionSessionStorage(ctx.context.options);
+			await assertSSOUserResolutionAsyncContextSupport();
+		}
 		result = await runWithTransaction(ctx.context.adapter, async () => {
 			await lockSSOProviderForAccountLink(ctx, provider);
-			return handleOAuthUserInfo(ctx, {
+			const currentProvider = await findSAMLProvider(providerId, options, await getCurrentAdapter(ctx.context.adapter));
+			if (!currentProvider || !await isCurrentSSOProviderReference(currentProvider, providerReference)) throw new APIError("CONFLICT", {
+				code: "SSO_PROVIDER_CHANGED",
+				message: "SSO provider changed while account linking was in progress"
+			});
+			const resolution = options?.resolveUser ? await resolveSSOUser(options.resolveUser, {
+				protocol: "saml",
+				providerId: provider.providerId,
+				accountKey,
+				providerUser,
+				providerAttributes,
+				providerReference
+			}, await getCurrentAdapter(ctx.context.adapter), ctx.context.logger) : void 0;
+			if (resolution?.action === "reject") throw new APIError("FORBIDDEN", {
+				code: resolution.code,
+				...resolution.message === void 0 ? {} : { message: resolution.message }
+			});
+			const authentication = await handleOAuthUserInfo(ctx, {
 				userInfo: {
-					email: userInfo.email,
-					name: userInfo.name || userInfo.email,
-					id: userInfo.id,
-					emailVerified: userInfo.emailVerified
+					...providerUser,
+					id: userInfo.id
 				},
 				account: {
 					providerId,
-					issuer,
-					providerAccountId: userInfo.id,
+					issuer: accountKey.issuer,
+					providerAccountId: accountKey.providerAccountId,
 					accessToken: "",
 					refreshToken: ""
 				},
@@ -2671,15 +2997,26 @@ async function processSAMLResponse(ctx, params, options) {
 					}
 				},
 				isTrustedProvider,
-				trustProviderByName: false
+				trustProviderByName: false,
+				selectedUser: resolution?.action === "link" ? {
+					userId: resolution.userId,
+					profile: resolution.profile
+				} : void 0,
+				deferNonDatabaseWrites: !!options?.resolveUser,
+				requireExactAccountBinding: !!options?.resolveUser
 			});
-		});
+			return options?.resolveUser ? requireSuccessfulSSOAuthentication(authentication) : authentication;
+		}, { onAfterCommitHookError() {
+			ctx.context.logger.error("Committed SSO authentication after-hook failed");
+		} });
 	} catch (e) {
-		if (isAPIError(e) && e.body?.code) throw ctx.redirect(buildSAMLRedirectUrl(errorUrl, {
+		const failedAuthentication = getFailedSSOAuthenticationResult(e);
+		if (failedAuthentication) result = failedAuthentication;
+		else if (isAPIError(e) && e.body?.code) throw ctx.redirect(buildSAMLRedirectUrl(errorUrl, {
 			error: e.body.code,
 			...e.body.message ? { error_description: e.body.message } : {}
 		}));
-		throw e;
+		else throw e;
 	}
 	if (result.error) throw ctx.redirect(buildSAMLRedirectUrl(callbackUrl, { error: result.error.split(" ").join("_") }));
 	const { session, user } = result.data;
@@ -2701,6 +3038,7 @@ async function processSAMLResponse(ctx, params, options) {
 		provider,
 		provisioningOptions: options?.organizationProvisioning
 	});
+	if ("accountCookie" in result && result.accountCookie) await setAccountCookie(ctx, result.accountCookie);
 	await setSessionCookie(ctx, {
 		session,
 		user
@@ -2953,9 +3291,10 @@ const registerSSOProvider = (options) => {
 		})).length >= limit) throw new APIError("FORBIDDEN", { message: "You have reached the maximum number of SSO providers" });
 		const body = ctx.body;
 		const additionalFields = parseSSOProviderAdditionalFields(options, body, "create");
-		if (body.samlConfig?.idpMetadata?.metadata) {
+		if (body.samlConfig) {
 			const maxMetadataSize = options?.saml?.maxMetadataSize ?? 102400;
-			if (new TextEncoder().encode(body.samlConfig.idpMetadata.metadata).length > maxMetadataSize) throw new APIError("BAD_REQUEST", { message: `IdP metadata exceeds maximum allowed size (${maxMetadataSize} bytes)` });
+			assertSAMLMetadataSize(body.samlConfig.idpMetadata?.metadata, "IdP", maxMetadataSize);
+			assertSAMLMetadataSize(body.samlConfig.spMetadata?.metadata, "SP", maxMetadataSize);
 		}
 		if (ctx.body.organizationId) {
 			const member = await ctx.context.adapter.findOne({
@@ -2981,18 +3320,6 @@ const registerSSOProvider = (options) => {
 			ctx.context.logger.warn(`SSO provider registration rejected for reserved providerId: ${body.providerId}`);
 			throw new APIError("UNPROCESSABLE_ENTITY", { message: "This providerId is reserved and cannot be used for an SSO provider" });
 		}
-		if (ctx.context.hasPlugin("scim")) {
-			if (await ctx.context.adapter.findOne({
-				model: "scimProvider",
-				where: [{
-					field: "providerId",
-					value: body.providerId
-				}]
-			})) {
-				ctx.context.logger.warn(`SSO provider registration rejected for SCIM providerId: ${body.providerId}`);
-				throw new APIError("UNPROCESSABLE_ENTITY", { message: "This providerId is already used by a SCIM provider and cannot be used for an SSO provider" });
-			}
-		}
 		if (await ctx.context.adapter.findOne({
 			model: "ssoProvider",
 			where: [{
@@ -3072,6 +3399,10 @@ const registerSSOProvider = (options) => {
 			}, options?.saml?.algorithms);
 			validateCertSources(body.samlConfig);
 			assertSAMLIdentityProviderAuthority(body.samlConfig);
+			assertSAMLServiceProviderMetadataPolicy({
+				...body.samlConfig,
+				issuer: body.issuer
+			});
 			const hasIdpMetadata = body.samlConfig.idpMetadata?.metadata;
 			let hasEntryPoint = false;
 			if (body.samlConfig.entryPoint) try {
@@ -3344,7 +3675,8 @@ const signInSSO = (options) => {
 			const parsedSamlConfig = typeof provider.samlConfig === "object" ? provider.samlConfig : safeJsonParse(provider.samlConfig);
 			if (!parsedSamlConfig) throw new APIError("BAD_REQUEST", { message: "Invalid SAML configuration" });
 			if (parsedSamlConfig.authnRequestsSigned && !parsedSamlConfig.spMetadata?.privateKey && !parsedSamlConfig.privateKey) throw new APIError("BAD_REQUEST", { message: "authnRequestsSigned is enabled but no privateKey provided in spMetadata or samlConfig" });
-			const { state: relayState } = await generateRelayState(ctx, void 0);
+			const providerReference = await computeSSOProviderReference(provider);
+			const { state: relayState } = await generateRelayState(ctx, void 0, providerReference);
 			const sp = createSP(parsedSamlConfig, ctx.context.baseURL, provider.providerId, { relayState });
 			const idp = createIdP(parsedSamlConfig);
 			const loginRequest = sp.createLoginRequest(idp, "redirect");
@@ -3354,6 +3686,7 @@ const signInSSO = (options) => {
 				const record = {
 					id: loginRequest.id,
 					providerId: provider.providerId,
+					providerReference,
 					createdAt: Date.now(),
 					expiresAt: Date.now() + ttl
 				};
@@ -3422,7 +3755,8 @@ async function handleOIDCCallback(ctx, options, providerId, stateData, parsedPro
 	if (!code || error) redirectOIDCError(error || "invalid_request", error_description || (error ? error : "authorization_code_not_found"));
 	const provider = await resolveOIDCProvider(ctx, options, providerId);
 	if (!provider) throw ctx.redirect(`${errorURL || callbackURL}?error=invalid_provider&error_description=provider not found`);
-	if (!await isCurrentSSOProviderReference(provider, providerReference)) redirectOIDCError("invalid_state", "sso_provider_changed_during_authentication");
+	const acceptedProviderReference = providerReference ?? redirectOIDCError("invalid_state", "missing_sso_provider_reference");
+	if (!await isCurrentSSOProviderReference(provider, acceptedProviderReference)) redirectOIDCError("invalid_state", "sso_provider_changed_during_authentication");
 	if (options?.domainVerification?.enabled && !("domainVerified" in provider && provider.domainVerified)) throw new APIError("UNAUTHORIZED", { message: "Provider domain has not been verified" });
 	let config = provider.oidcConfig;
 	if (!config) throw ctx.redirect(`${errorURL || callbackURL}?error=invalid_provider&error_description=provider not found`);
@@ -3570,7 +3904,7 @@ async function handleOIDCCallback(ctx, options, providerId, stateData, parsedPro
 		linked = await runWithTransaction(ctx.context.adapter, async () => {
 			await lockSSOProviderForAccountLink(ctx, provider);
 			const currentProvider = await resolveOIDCProvider(ctx, options, providerId, await getCurrentAdapter(ctx.context.adapter));
-			if (!currentProvider || !await isCurrentSSOProviderReference(currentProvider, providerReference)) throw new APIError("CONFLICT", {
+			if (!currentProvider || !await isCurrentSSOProviderReference(currentProvider, acceptedProviderReference)) throw new APIError("CONFLICT", {
 				code: "SSO_PROVIDER_CHANGED",
 				message: "SSO provider changed while account linking was in progress"
 			});
@@ -3579,7 +3913,9 @@ async function handleOIDCCallback(ctx, options, providerId, stateData, parsedPro
 				providerId: provider.providerId,
 				accountKey,
 				providerUser,
-				providerClaims: rawProfile ?? {}
+				providerClaims: rawProfile ?? {},
+				verifiedIdTokenClaims: verifiedIdToken?.payload ?? {},
+				providerReference: acceptedProviderReference
 			}, await getCurrentAdapter(ctx.context.adapter), ctx.context.logger) : void 0;
 			if (resolution?.action === "reject") throw new APIError("FORBIDDEN", {
 				code: resolution.code,
@@ -4097,7 +4433,7 @@ function sso(options) {
 		listSSOProviders: listSSOProviders(optionsWithStore),
 		getSSOProvider: getSSOProvider(optionsWithStore),
 		updateSSOProvider: updateSSOProvider(optionsWithStore),
-		deleteSSOProvider: deleteSSOProvider()
+		deleteSSOProvider: deleteSSOProvider(optionsWithStore)
 	};
 	if (options?.domainVerification?.enabled) {
 		const domainVerificationEndpoints = {
@@ -4206,4 +4542,4 @@ function sso(options) {
 	};
 }
 //#endregion
-export { DEFAULT_CLOCK_SKEW_MS, DEFAULT_MAX_SAML_METADATA_SIZE, DEFAULT_MAX_SAML_RESPONSE_SIZE, DataEncryptionAlgorithm, DigestAlgorithm, DiscoveryError, KeyEncryptionAlgorithm, REQUIRED_DISCOVERY_FIELDS, SignatureAlgorithm, computeDiscoveryUrl, discoverOIDCConfig, fetchDiscoveryDocument, needsRuntimeDiscovery, normalizeDiscoveryUrls, normalizeUrl, selectTokenEndpointAuthMethod, sso, validateDiscoveryDocument, validateDiscoveryUrl, validateSAMLTimestamp };
+export { DEFAULT_CLOCK_SKEW_MS, DEFAULT_MAX_SAML_METADATA_SIZE, DEFAULT_MAX_SAML_RESPONSE_SIZE, DataEncryptionAlgorithm, DigestAlgorithm, DiscoveryError, KeyEncryptionAlgorithm, REQUIRED_DISCOVERY_FIELDS, SignatureAlgorithm, computeDiscoveryUrl, deriveSAMLIdentityProviderEntityID, deriveSAMLServiceProviderPolicy, discoverOIDCConfig, fetchDiscoveryDocument, needsRuntimeDiscovery, normalizeDiscoveryUrls, normalizeUrl, selectTokenEndpointAuthMethod, sso, validateDiscoveryDocument, validateDiscoveryUrl, validateSAMLTimestamp };