@better-auth/sso 1.4.7-beta.2 → 1.4.7-beta.4

package/dist/index.mjs

@@ -4,11 +4,51 @@ import { APIError, createAuthEndpoint, sessionMiddleware } from "better-auth/api
 import { generateRandomString } from "better-auth/crypto";
 import * as z from "zod/v4";
 import { BetterFetchError, betterFetch } from "@better-fetch/fetch";
-import { createAuthorizationURL, generateState, parseState, validateAuthorizationCode, validateToken } from "better-auth";
+import { HIDE_METADATA, createAuthorizationURL, generateState, parseState, validateAuthorizationCode, validateToken } from "better-auth";
 import { setSessionCookie } from "better-auth/cookies";
 import { handleOAuthUserInfo } from "better-auth/oauth2";
 import { decodeJwt } from "jose";
 
+//#region src/authn-request-store.ts
+/**
+* Default TTL for AuthnRequest records (5 minutes).
+* This should be sufficient for most IdPs while protecting against stale requests.
+*/
+const DEFAULT_AUTHN_REQUEST_TTL_MS = 300 * 1e3;
+/**
+* In-memory implementation of AuthnRequestStore.
+* ⚠️ Only suitable for testing or single-instance non-serverless deployments.
+* For production, rely on the default behavior (uses verification table)
+* or provide a custom Redis-backed store.
+*/
+function createInMemoryAuthnRequestStore() {
+	const store = /* @__PURE__ */ new Map();
+	const cleanup = () => {
+		const now = Date.now();
+		for (const [id, record] of store.entries()) if (record.expiresAt < now) store.delete(id);
+	};
+	const cleanupInterval = setInterval(cleanup, 60 * 1e3);
+	if (typeof cleanupInterval.unref === "function") cleanupInterval.unref();
+	return {
+		async save(record) {
+			store.set(record.id, record);
+		},
+		async get(id) {
+			const record = store.get(id);
+			if (!record) return null;
+			if (record.expiresAt < Date.now()) {
+				store.delete(id);
+				return null;
+			}
+			return record;
+		},
+		async delete(id) {
+			store.delete(id);
+		}
+	};
+}
+
+//#endregion
 //#region src/routes/domain-verification.ts
 const domainVerificationBodySchema = z.object({ providerId: z.string() });
 const requestDomainVerification = (options) => {
@@ -183,6 +223,300 @@ const verifyDomain = (options) => {
 	});
 };
 
+//#endregion
+//#region src/oidc/types.ts
+/**
+* Custom error class for OIDC discovery failures.
+* Can be caught and mapped to APIError at the edge.
+*/
+var DiscoveryError = class DiscoveryError extends Error {
+	code;
+	details;
+	constructor(code, message, details, options) {
+		super(message, options);
+		this.name = "DiscoveryError";
+		this.code = code;
+		this.details = details;
+		if (Error.captureStackTrace) Error.captureStackTrace(this, DiscoveryError);
+	}
+};
+/**
+* Required fields that must be present in a valid discovery document.
+*/
+const REQUIRED_DISCOVERY_FIELDS = [
+	"issuer",
+	"authorization_endpoint",
+	"token_endpoint",
+	"jwks_uri"
+];
+
+//#endregion
+//#region src/oidc/discovery.ts
+/**
+* OIDC Discovery Pipeline
+*
+* Implements OIDC discovery document fetching, validation, and hydration.
+* This module is used both at provider registration time (to persist validated config)
+* and at runtime (to hydrate legacy providers that are missing metadata).
+*
+* @see https://openid.net/specs/openid-connect-discovery-1_0.html
+*/
+/** Default timeout for discovery requests (10 seconds) */
+const DEFAULT_DISCOVERY_TIMEOUT = 1e4;
+/**
+* Main entry point: Discover and hydrate OIDC configuration from an issuer.
+*
+* This function:
+* 1. Computes the discovery URL from the issuer
+* 2. Validates the discovery URL (stub for now)
+* 3. Fetches the discovery document
+* 4. Validates the discovery document (issuer match + required fields)
+* 5. Normalizes URLs (stub for now)
+* 6. Selects token endpoint auth method
+* 7. Merges with existing config (existing values take precedence)
+*
+* @param params - Discovery parameters
+* @returns Hydrated OIDC configuration ready for persistence
+* @throws DiscoveryError on any failure
+*/
+async function discoverOIDCConfig(params) {
+	const { issuer, existingConfig, timeout = DEFAULT_DISCOVERY_TIMEOUT } = params;
+	const discoveryUrl = params.discoveryEndpoint || existingConfig?.discoveryEndpoint || computeDiscoveryUrl(issuer);
+	validateDiscoveryUrl(discoveryUrl);
+	const discoveryDoc = await fetchDiscoveryDocument(discoveryUrl, timeout);
+	validateDiscoveryDocument(discoveryDoc, issuer);
+	const normalizedDoc = normalizeDiscoveryUrls(discoveryDoc, issuer);
+	const tokenEndpointAuth = selectTokenEndpointAuthMethod(normalizedDoc, existingConfig?.tokenEndpointAuthentication);
+	return {
+		issuer: existingConfig?.issuer ?? normalizedDoc.issuer,
+		discoveryEndpoint: existingConfig?.discoveryEndpoint ?? discoveryUrl,
+		authorizationEndpoint: existingConfig?.authorizationEndpoint ?? normalizedDoc.authorization_endpoint,
+		tokenEndpoint: existingConfig?.tokenEndpoint ?? normalizedDoc.token_endpoint,
+		jwksEndpoint: existingConfig?.jwksEndpoint ?? normalizedDoc.jwks_uri,
+		userInfoEndpoint: existingConfig?.userInfoEndpoint ?? normalizedDoc.userinfo_endpoint,
+		tokenEndpointAuthentication: existingConfig?.tokenEndpointAuthentication ?? tokenEndpointAuth,
+		scopesSupported: existingConfig?.scopesSupported ?? normalizedDoc.scopes_supported
+	};
+}
+/**
+* Compute the discovery URL from an issuer URL.
+*
+* Per OIDC Discovery spec, the discovery document is located at:
+* <issuer>/.well-known/openid-configuration
+*
+* Handles trailing slashes correctly.
+*/
+function computeDiscoveryUrl(issuer) {
+	return `${issuer.endsWith("/") ? issuer.slice(0, -1) : issuer}/.well-known/openid-configuration`;
+}
+/**
+* Validate a discovery URL before fetching.
+*
+* @param url - The discovery URL to validate
+* @throws DiscoveryError if URL is invalid
+*/
+function validateDiscoveryUrl(url) {
+	try {
+		const parsed = new URL(url);
+		if (parsed.protocol !== "https:" && parsed.protocol !== "http:") throw new DiscoveryError("discovery_invalid_url", `Discovery URL must use HTTP or HTTPS protocol: ${url}`, {
+			url,
+			protocol: parsed.protocol
+		});
+	} catch (error) {
+		if (error instanceof DiscoveryError) throw error;
+		throw new DiscoveryError("discovery_invalid_url", `Invalid discovery URL: ${url}`, { url }, { cause: error });
+	}
+}
+/**
+* Fetch the OIDC discovery document from the IdP.
+*
+* @param url - The discovery endpoint URL
+* @param timeout - Request timeout in milliseconds
+* @returns The parsed discovery document
+* @throws DiscoveryError on network errors, timeouts, or invalid responses
+*/
+async function fetchDiscoveryDocument(url, timeout = DEFAULT_DISCOVERY_TIMEOUT) {
+	try {
+		const response = await betterFetch(url, {
+			method: "GET",
+			timeout
+		});
+		if (response.error) {
+			const { status } = response.error;
+			if (status === 404) throw new DiscoveryError("discovery_not_found", "Discovery endpoint not found", {
+				url,
+				status
+			});
+			if (status === 408) throw new DiscoveryError("discovery_timeout", "Discovery request timed out", {
+				url,
+				timeout
+			});
+			throw new DiscoveryError("discovery_unexpected_error", `Unexpected discovery error: ${response.error.statusText}`, {
+				url,
+				...response.error
+			});
+		}
+		if (!response.data) throw new DiscoveryError("discovery_invalid_json", "Discovery endpoint returned an empty response", { url });
+		const data = response.data;
+		if (typeof data === "string") throw new DiscoveryError("discovery_invalid_json", "Discovery endpoint returned invalid JSON", {
+			url,
+			bodyPreview: data.slice(0, 200)
+		});
+		return data;
+	} catch (error) {
+		if (error instanceof DiscoveryError) throw error;
+		if (error instanceof Error && error.name === "AbortError") throw new DiscoveryError("discovery_timeout", "Discovery request timed out", {
+			url,
+			timeout
+		});
+		throw new DiscoveryError("discovery_unexpected_error", `Unexpected error during discovery: ${error instanceof Error ? error.message : String(error)}`, { url }, { cause: error });
+	}
+}
+/**
+* Validate a discovery document.
+*
+* Checks:
+* 1. All required fields are present
+* 2. Issuer matches the configured issuer (case-sensitive, exact match)
+*
+* Invariant: If this function returns without throwing, the document is safe
+* to use for hydrating OIDC config (required fields present, issuer matches
+* configured value, basic structural sanity verified).
+*
+* @param doc - The discovery document to validate
+* @param configuredIssuer - The expected issuer value
+* @throws DiscoveryError if validation fails
+*/
+function validateDiscoveryDocument(doc, configuredIssuer) {
+	const missingFields = [];
+	for (const field of REQUIRED_DISCOVERY_FIELDS) if (!doc[field]) missingFields.push(field);
+	if (missingFields.length > 0) throw new DiscoveryError("discovery_incomplete", `Discovery document is missing required fields: ${missingFields.join(", ")}`, { missingFields });
+	if ((doc.issuer.endsWith("/") ? doc.issuer.slice(0, -1) : doc.issuer) !== (configuredIssuer.endsWith("/") ? configuredIssuer.slice(0, -1) : configuredIssuer)) throw new DiscoveryError("issuer_mismatch", `Discovered issuer "${doc.issuer}" does not match configured issuer "${configuredIssuer}"`, {
+		discovered: doc.issuer,
+		configured: configuredIssuer
+	});
+}
+/**
+* Normalize URLs in the discovery document.
+*
+* @param doc - The discovery document
+* @param _issuerBase - The base issuer URL
+* @returns The normalized discovery document
+*/
+function normalizeDiscoveryUrls(doc, _issuerBase) {
+	return doc;
+}
+/**
+* Normalize a single URL endpoint.
+*
+* @param endpoint - The endpoint URL to normalize
+* @param _issuerBase - The base issuer URL
+* @returns The normalized endpoint URL
+*/
+function normalizeUrl(endpoint, _issuerBase) {
+	return endpoint;
+}
+/**
+* Select the token endpoint authentication method.
+*
+* @param doc - The discovery document
+* @param existing - Existing authentication method from config
+* @returns The selected authentication method
+*/
+function selectTokenEndpointAuthMethod(doc, existing) {
+	if (existing) return existing;
+	const supported = doc.token_endpoint_auth_methods_supported;
+	if (!supported || supported.length === 0) return "client_secret_basic";
+	if (supported.includes("client_secret_basic")) return "client_secret_basic";
+	if (supported.includes("client_secret_post")) return "client_secret_post";
+	return "client_secret_basic";
+}
+/**
+* Check if a provider configuration needs runtime discovery.
+*
+* Returns true if we need discovery at runtime to complete the token exchange
+* and validation. Specifically checks for:
+* - `tokenEndpoint` - required for exchanging authorization code for tokens
+* - `jwksEndpoint` - required for validating ID token signatures
+*
+* Note: `authorizationEndpoint` is handled separately in the sign-in flow,
+* so it's not checked here.
+*
+* @param config - Partial OIDC config from the provider
+* @returns true if runtime discovery should be performed
+*/
+function needsRuntimeDiscovery(config) {
+	if (!config) return true;
+	return !config.tokenEndpoint || !config.jwksEndpoint;
+}
+
+//#endregion
+//#region src/oidc/errors.ts
+/**
+* OIDC Discovery Error Mapping
+*
+* Maps DiscoveryError codes to appropriate APIError responses.
+* Used at the boundary between the discovery pipeline and HTTP handlers.
+*/
+/**
+* Maps a DiscoveryError to an appropriate APIError for HTTP responses.
+*
+* Error code mapping:
+* - discovery_invalid_url       → 400 BAD_REQUEST
+* - discovery_not_found         → 400 BAD_REQUEST
+* - discovery_invalid_json      → 400 BAD_REQUEST
+* - discovery_incomplete        → 400 BAD_REQUEST
+* - issuer_mismatch             → 400 BAD_REQUEST
+* - unsupported_token_auth_method → 400 BAD_REQUEST
+* - discovery_timeout           → 502 BAD_GATEWAY
+* - discovery_unexpected_error  → 502 BAD_GATEWAY
+*
+* @param error - The DiscoveryError to map
+* @returns An APIError with appropriate status and message
+*/
+function mapDiscoveryErrorToAPIError(error) {
+	switch (error.code) {
+		case "discovery_timeout": return new APIError("BAD_GATEWAY", {
+			message: `OIDC discovery timed out: ${error.message}`,
+			code: error.code
+		});
+		case "discovery_unexpected_error": return new APIError("BAD_GATEWAY", {
+			message: `OIDC discovery failed: ${error.message}`,
+			code: error.code
+		});
+		case "discovery_not_found": return new APIError("BAD_REQUEST", {
+			message: `OIDC discovery endpoint not found. The issuer may not support OIDC discovery, or the URL is incorrect. ${error.message}`,
+			code: error.code
+		});
+		case "discovery_invalid_url": return new APIError("BAD_REQUEST", {
+			message: `Invalid OIDC discovery URL: ${error.message}`,
+			code: error.code
+		});
+		case "discovery_invalid_json": return new APIError("BAD_REQUEST", {
+			message: `OIDC discovery returned invalid data: ${error.message}`,
+			code: error.code
+		});
+		case "discovery_incomplete": return new APIError("BAD_REQUEST", {
+			message: `OIDC discovery document is missing required fields: ${error.message}`,
+			code: error.code
+		});
+		case "issuer_mismatch": return new APIError("BAD_REQUEST", {
+			message: `OIDC issuer mismatch: ${error.message}`,
+			code: error.code
+		});
+		case "unsupported_token_auth_method": return new APIError("BAD_REQUEST", {
+			message: `Incompatible OIDC provider: ${error.message}`,
+			code: error.code
+		});
+		default:
+			error.code;
+			return new APIError("INTERNAL_SERVER_ERROR", {
+				message: `Unexpected discovery error: ${error.message}`,
+				code: "discovery_unexpected_error"
+			});
+	}
+}
+
 //#endregion
 //#region src/utils.ts
 /**
@@ -213,6 +547,48 @@ const validateEmailDomain = (email, domain) => {
 
 //#endregion
 //#region src/routes/sso.ts
+const AUTHN_REQUEST_KEY_PREFIX = "saml-authn-request:";
+/** Default clock skew tolerance: 5 minutes */
+const DEFAULT_CLOCK_SKEW_MS = 300 * 1e3;
+/**
+* Validates SAML assertion timestamp conditions (NotBefore/NotOnOrAfter).
+* Prevents acceptance of expired or future-dated assertions.
+* @throws {APIError} If timestamps are invalid, expired, or not yet valid
+*/
+function validateSAMLTimestamp(conditions, options = {}) {
+	const clockSkew = options.clockSkew ?? DEFAULT_CLOCK_SKEW_MS;
+	if (!(conditions?.notBefore || conditions?.notOnOrAfter)) {
+		if (options.requireTimestamps) throw new APIError("BAD_REQUEST", {
+			message: "SAML assertion missing required timestamp conditions",
+			details: "Assertions must include NotBefore and/or NotOnOrAfter conditions"
+		});
+		options.logger?.warn("SAML assertion accepted without timestamp conditions", { hasConditions: !!conditions });
+		return;
+	}
+	const now = Date.now();
+	if (conditions?.notBefore) {
+		const notBeforeTime = new Date(conditions.notBefore).getTime();
+		if (Number.isNaN(notBeforeTime)) throw new APIError("BAD_REQUEST", {
+			message: "SAML assertion has invalid NotBefore timestamp",
+			details: `Unable to parse NotBefore value: ${conditions.notBefore}`
+		});
+		if (now < notBeforeTime - clockSkew) throw new APIError("BAD_REQUEST", {
+			message: "SAML assertion is not yet valid",
+			details: `Current time is before NotBefore (with ${clockSkew}ms clock skew tolerance)`
+		});
+	}
+	if (conditions?.notOnOrAfter) {
+		const notOnOrAfterTime = new Date(conditions.notOnOrAfter).getTime();
+		if (Number.isNaN(notOnOrAfterTime)) throw new APIError("BAD_REQUEST", {
+			message: "SAML assertion has invalid NotOnOrAfter timestamp",
+			details: `Unable to parse NotOnOrAfter value: ${conditions.notOnOrAfter}`
+		});
+		if (now > notOnOrAfterTime + clockSkew) throw new APIError("BAD_REQUEST", {
+			message: "SAML assertion has expired",
+			details: `Current time is after NotOnOrAfter (with ${clockSkew}ms clock skew tolerance)`
+		});
+	}
+}
 const spMetadataQuerySchema = z.object({
 	providerId: z.string(),
 	format: z.enum(["xml", "json"]).default("xml")
@@ -263,6 +639,7 @@ const ssoProviderBodySchema = z.object({
 		tokenEndpointAuthentication: z.enum(["client_secret_post", "client_secret_basic"]).optional(),
 		jwksEndpoint: z.string({}).meta({ description: "The JWKS endpoint" }).optional(),
 		discoveryEndpoint: z.string().optional(),
+		skipDiscovery: z.boolean().meta({ description: "Skip OIDC discovery during registration. When true, you must provide authorizationEndpoint, tokenEndpoint, and jwksEndpoint manually." }).optional(),
 		scopes: z.array(z.string(), {}).meta({ description: "The scopes to request. Defaults to ['openid', 'email', 'profile', 'offline_access']" }).optional(),
 		pkce: z.boolean({}).meta({ description: "Whether to use PKCE for the authorization flow" }).default(true).optional(),
 		mapping: z.object({
@@ -530,27 +907,64 @@ const registerSSOProvider = (options) => {
 			ctx.context.logger.info(`SSO provider creation attempt with existing providerId: ${body.providerId}`);
 			throw new APIError("UNPROCESSABLE_ENTITY", { message: "SSO provider with this providerId already exists" });
 		}
+		let hydratedOIDCConfig = null;
+		if (body.oidcConfig && !body.oidcConfig.skipDiscovery) try {
+			hydratedOIDCConfig = await discoverOIDCConfig({
+				issuer: body.issuer,
+				existingConfig: {
+					discoveryEndpoint: body.oidcConfig.discoveryEndpoint,
+					authorizationEndpoint: body.oidcConfig.authorizationEndpoint,
+					tokenEndpoint: body.oidcConfig.tokenEndpoint,
+					jwksEndpoint: body.oidcConfig.jwksEndpoint,
+					userInfoEndpoint: body.oidcConfig.userInfoEndpoint,
+					tokenEndpointAuthentication: body.oidcConfig.tokenEndpointAuthentication
+				}
+			});
+		} catch (error) {
+			if (error instanceof DiscoveryError) throw mapDiscoveryErrorToAPIError(error);
+			throw error;
+		}
+		const buildOIDCConfig = () => {
+			if (!body.oidcConfig) return null;
+			if (body.oidcConfig.skipDiscovery) return JSON.stringify({
+				issuer: body.issuer,
+				clientId: body.oidcConfig.clientId,
+				clientSecret: body.oidcConfig.clientSecret,
+				authorizationEndpoint: body.oidcConfig.authorizationEndpoint,
+				tokenEndpoint: body.oidcConfig.tokenEndpoint,
+				tokenEndpointAuthentication: body.oidcConfig.tokenEndpointAuthentication || "client_secret_basic",
+				jwksEndpoint: body.oidcConfig.jwksEndpoint,
+				pkce: body.oidcConfig.pkce,
+				discoveryEndpoint: body.oidcConfig.discoveryEndpoint || `${body.issuer}/.well-known/openid-configuration`,
+				mapping: body.oidcConfig.mapping,
+				scopes: body.oidcConfig.scopes,
+				userInfoEndpoint: body.oidcConfig.userInfoEndpoint,
+				overrideUserInfo: ctx.body.overrideUserInfo || options?.defaultOverrideUserInfo || false
+			});
+			if (!hydratedOIDCConfig) return null;
+			return JSON.stringify({
+				issuer: hydratedOIDCConfig.issuer,
+				clientId: body.oidcConfig.clientId,
+				clientSecret: body.oidcConfig.clientSecret,
+				authorizationEndpoint: hydratedOIDCConfig.authorizationEndpoint,
+				tokenEndpoint: hydratedOIDCConfig.tokenEndpoint,
+				tokenEndpointAuthentication: hydratedOIDCConfig.tokenEndpointAuthentication,
+				jwksEndpoint: hydratedOIDCConfig.jwksEndpoint,
+				pkce: body.oidcConfig.pkce,
+				discoveryEndpoint: hydratedOIDCConfig.discoveryEndpoint,
+				mapping: body.oidcConfig.mapping,
+				scopes: body.oidcConfig.scopes,
+				userInfoEndpoint: hydratedOIDCConfig.userInfoEndpoint,
+				overrideUserInfo: ctx.body.overrideUserInfo || options?.defaultOverrideUserInfo || false
+			});
+		};
 		const provider = await ctx.context.adapter.create({
 			model: "ssoProvider",
 			data: {
 				issuer: body.issuer,
 				domain: body.domain,
 				domainVerified: false,
-				oidcConfig: body.oidcConfig ? JSON.stringify({
-					issuer: body.issuer,
-					clientId: body.oidcConfig.clientId,
-					clientSecret: body.oidcConfig.clientSecret,
-					authorizationEndpoint: body.oidcConfig.authorizationEndpoint,
-					tokenEndpoint: body.oidcConfig.tokenEndpoint,
-					tokenEndpointAuthentication: body.oidcConfig.tokenEndpointAuthentication,
-					jwksEndpoint: body.oidcConfig.jwksEndpoint,
-					pkce: body.oidcConfig.pkce,
-					discoveryEndpoint: body.oidcConfig.discoveryEndpoint || `${body.issuer}/.well-known/openid-configuration`,
-					mapping: body.oidcConfig.mapping,
-					scopes: body.oidcConfig.scopes,
-					userInfoEndpoint: body.oidcConfig.userInfoEndpoint,
-					overrideUserInfo: ctx.body.overrideUserInfo || options?.defaultOverrideUserInfo || false
-				}) : null,
+				oidcConfig: buildOIDCConfig(),
 				samlConfig: body.samlConfig ? JSON.stringify({
 					issuer: body.issuer,
 					entryPoint: body.samlConfig.entryPoint,
@@ -781,6 +1195,21 @@ const signInSSO = (options) => {
 			});
 			const loginRequest = sp.createLoginRequest(idp, "redirect");
 			if (!loginRequest) throw new APIError("BAD_REQUEST", { message: "Invalid SAML request" });
+			if (loginRequest.id && (options?.saml?.authnRequestStore || options?.saml?.enableInResponseToValidation)) {
+				const ttl = options?.saml?.requestTTL ?? DEFAULT_AUTHN_REQUEST_TTL_MS;
+				const record = {
+					id: loginRequest.id,
+					providerId: provider.providerId,
+					createdAt: Date.now(),
+					expiresAt: Date.now() + ttl
+				};
+				if (options?.saml?.authnRequestStore) await options.saml.authnRequestStore.save(record);
+				else await ctx.context.internalAdapter.createVerificationValue({
+					identifier: `${AUTHN_REQUEST_KEY_PREFIX}${record.id}`,
+					value: JSON.stringify(record),
+					expiresAt: new Date(record.expiresAt)
+				});
+			}
 			return ctx.json({
 				url: `${loginRequest.context}&RelayState=${encodeURIComponent(body.callbackURL)}`,
 				redirect: true
@@ -801,7 +1230,7 @@ const callbackSSO = (options) => {
 		query: callbackSSOQuerySchema,
 		allowedMediaTypes: ["application/x-www-form-urlencoded", "application/json"],
 		metadata: {
-			isAction: false,
+			...HIDE_METADATA,
 			openapi: {
 				operationId: "handleSSOCallback",
 				summary: "Callback URL for SSO provider",
@@ -986,7 +1415,7 @@ const callbackSSOSAML = (options) => {
 		method: "POST",
 		body: callbackSSOSAMLBodySchema,
 		metadata: {
-			isAction: false,
+			...HIDE_METADATA,
 			allowedMediaTypes: ["application/x-www-form-urlencoded", "application/json"],
 			openapi: {
 				operationId: "handleSAMLCallback",
@@ -1069,22 +1498,10 @@ const callbackSSOSAML = (options) => {
 		});
 		let parsedResponse;
 		try {
-			const decodedResponse = Buffer.from(SAMLResponse, "base64").toString("utf-8");
-			try {
-				parsedResponse = await sp.parseLoginResponse(idp, "post", { body: {
-					SAMLResponse,
-					RelayState: RelayState || void 0
-				} });
-			} catch (parseError) {
-				const nameIDMatch = decodedResponse.match(/<saml2:NameID[^>]*>([^<]+)<\/saml2:NameID>/);
-				if (!nameIDMatch) throw parseError;
-				parsedResponse = { extract: {
-					nameID: nameIDMatch[1],
-					attributes: { nameID: nameIDMatch[1] },
-					sessionIndex: {},
-					conditions: {}
-				} };
-			}
+			parsedResponse = await sp.parseLoginResponse(idp, "post", { body: {
+				SAMLResponse,
+				RelayState: RelayState || void 0
+			} });
 			if (!parsedResponse?.extract) throw new Error("Invalid SAML response structure");
 		} catch (error) {
 			ctx.context.logger.error("SAML response validation failed", {
@@ -1097,6 +1514,53 @@ const callbackSSOSAML = (options) => {
 			});
 		}
 		const { extract } = parsedResponse;
+		validateSAMLTimestamp(extract.conditions, {
+			clockSkew: options?.saml?.clockSkew,
+			requireTimestamps: options?.saml?.requireTimestamps,
+			logger: ctx.context.logger
+		});
+		const inResponseTo = extract.inResponseTo;
+		if (options?.saml?.authnRequestStore || options?.saml?.enableInResponseToValidation) {
+			const allowIdpInitiated = options?.saml?.allowIdpInitiated !== false;
+			if (inResponseTo) {
+				let storedRequest = null;
+				if (options?.saml?.authnRequestStore) storedRequest = await options.saml.authnRequestStore.get(inResponseTo);
+				else {
+					const verification = await ctx.context.internalAdapter.findVerificationValue(`${AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`);
+					if (verification) try {
+						storedRequest = JSON.parse(verification.value);
+						if (storedRequest && storedRequest.expiresAt < Date.now()) storedRequest = null;
+					} catch {
+						storedRequest = null;
+					}
+				}
+				if (!storedRequest) {
+					ctx.context.logger.error("SAML InResponseTo validation failed: unknown or expired request ID", {
+						inResponseTo,
+						providerId: provider.providerId
+					});
+					const redirectUrl = RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
+					throw ctx.redirect(`${redirectUrl}?error=invalid_saml_response&error_description=Unknown+or+expired+request+ID`);
+				}
+				if (storedRequest.providerId !== provider.providerId) {
+					ctx.context.logger.error("SAML InResponseTo validation failed: provider mismatch", {
+						inResponseTo,
+						expectedProvider: storedRequest.providerId,
+						actualProvider: provider.providerId
+					});
+					if (options?.saml?.authnRequestStore) await options.saml.authnRequestStore.delete(inResponseTo);
+					else await ctx.context.internalAdapter.deleteVerificationByIdentifier(`${AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`);
+					const redirectUrl = RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
+					throw ctx.redirect(`${redirectUrl}?error=invalid_saml_response&error_description=Provider+mismatch`);
+				}
+				if (options?.saml?.authnRequestStore) await options.saml.authnRequestStore.delete(inResponseTo);
+				else await ctx.context.internalAdapter.deleteVerificationByIdentifier(`${AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`);
+			} else if (!allowIdpInitiated) {
+				ctx.context.logger.error("SAML IdP-initiated SSO rejected: InResponseTo missing and allowIdpInitiated is false", { providerId: provider.providerId });
+				const redirectUrl = RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
+				throw ctx.redirect(`${redirectUrl}?error=unsolicited_response&error_description=IdP-initiated+SSO+not+allowed`);
+			}
+		}
 		const attributes = extract.attributes || {};
 		const mapping = parsedSamlConfig.mapping ?? {};
 		const userInfo = {
@@ -1223,7 +1687,7 @@ const acsEndpoint = (options) => {
 		params: acsEndpointParamsSchema,
 		body: acsEndpointBodySchema,
 		metadata: {
-			isAction: false,
+			...HIDE_METADATA,
 			allowedMediaTypes: ["application/x-www-form-urlencoded", "application/json"],
 			openapi: {
 				operationId: "handleSAMLAssertionConsumerService",
@@ -1285,26 +1749,10 @@ const acsEndpoint = (options) => {
 		}) : saml.IdentityProvider({ metadata: idpData.metadata });
 		let parsedResponse;
 		try {
-			let decodedResponse = Buffer.from(SAMLResponse, "base64").toString("utf-8");
-			if (!decodedResponse.includes("StatusCode")) {
-				const insertPoint = decodedResponse.indexOf("</saml2:Issuer>");
-				if (insertPoint !== -1) decodedResponse = decodedResponse.slice(0, insertPoint + 14) + "<saml2:Status><saml2:StatusCode Value=\"urn:oasis:names:tc:SAML:2.0:status:Success\"/></saml2:Status>" + decodedResponse.slice(insertPoint + 14);
-			} else if (!decodedResponse.includes("saml2:Success")) decodedResponse = decodedResponse.replace(/<saml2:StatusCode Value="[^"]+"/, "<saml2:StatusCode Value=\"urn:oasis:names:tc:SAML:2.0:status:Success\"");
-			try {
-				parsedResponse = await sp.parseLoginResponse(idp, "post", { body: {
-					SAMLResponse,
-					RelayState: RelayState || void 0
-				} });
-			} catch (parseError) {
-				const nameIDMatch = decodedResponse.match(/<saml2:NameID[^>]*>([^<]+)<\/saml2:NameID>/);
-				if (!nameIDMatch) throw parseError;
-				parsedResponse = { extract: {
-					nameID: nameIDMatch[1],
-					attributes: { nameID: nameIDMatch[1] },
-					sessionIndex: {},
-					conditions: {}
-				} };
-			}
+			parsedResponse = await sp.parseLoginResponse(idp, "post", { body: {
+				SAMLResponse,
+				RelayState: RelayState || void 0
+			} });
 			if (!parsedResponse?.extract) throw new Error("Invalid SAML response structure");
 		} catch (error) {
 			ctx.context.logger.error("SAML response validation failed", {
@@ -1317,6 +1765,53 @@ const acsEndpoint = (options) => {
 			});
 		}
 		const { extract } = parsedResponse;
+		validateSAMLTimestamp(extract.conditions, {
+			clockSkew: options?.saml?.clockSkew,
+			requireTimestamps: options?.saml?.requireTimestamps,
+			logger: ctx.context.logger
+		});
+		const inResponseToAcs = extract.inResponseTo;
+		if (options?.saml?.authnRequestStore || options?.saml?.enableInResponseToValidation) {
+			const allowIdpInitiated = options?.saml?.allowIdpInitiated !== false;
+			if (inResponseToAcs) {
+				let storedRequest = null;
+				if (options?.saml?.authnRequestStore) storedRequest = await options.saml.authnRequestStore.get(inResponseToAcs);
+				else {
+					const verification = await ctx.context.internalAdapter.findVerificationValue(`${AUTHN_REQUEST_KEY_PREFIX}${inResponseToAcs}`);
+					if (verification) try {
+						storedRequest = JSON.parse(verification.value);
+						if (storedRequest && storedRequest.expiresAt < Date.now()) storedRequest = null;
+					} catch {
+						storedRequest = null;
+					}
+				}
+				if (!storedRequest) {
+					ctx.context.logger.error("SAML InResponseTo validation failed: unknown or expired request ID", {
+						inResponseTo: inResponseToAcs,
+						providerId
+					});
+					const redirectUrl = RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
+					throw ctx.redirect(`${redirectUrl}?error=invalid_saml_response&error_description=Unknown+or+expired+request+ID`);
+				}
+				if (storedRequest.providerId !== providerId) {
+					ctx.context.logger.error("SAML InResponseTo validation failed: provider mismatch", {
+						inResponseTo: inResponseToAcs,
+						expectedProvider: storedRequest.providerId,
+						actualProvider: providerId
+					});
+					if (options?.saml?.authnRequestStore) await options.saml.authnRequestStore.delete(inResponseToAcs);
+					else await ctx.context.internalAdapter.deleteVerificationByIdentifier(`${AUTHN_REQUEST_KEY_PREFIX}${inResponseToAcs}`);
+					const redirectUrl = RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
+					throw ctx.redirect(`${redirectUrl}?error=invalid_saml_response&error_description=Provider+mismatch`);
+				}
+				if (options?.saml?.authnRequestStore) await options.saml.authnRequestStore.delete(inResponseToAcs);
+				else await ctx.context.internalAdapter.deleteVerificationByIdentifier(`${AUTHN_REQUEST_KEY_PREFIX}${inResponseToAcs}`);
+			} else if (!allowIdpInitiated) {
+				ctx.context.logger.error("SAML IdP-initiated SSO rejected: InResponseTo missing and allowIdpInitiated is false", { providerId });
+				const redirectUrl = RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
+				throw ctx.redirect(`${redirectUrl}?error=unsolicited_response&error_description=IdP-initiated+SSO+not+allowed`);
+			}
+		}
 		const attributes = extract.attributes || {};
 		const mapping = parsedSamlConfig.mapping ?? {};
 		const userInfo = {
@@ -1439,18 +1934,19 @@ saml.setSchemaValidator({ async validate(xml) {
 	throw "ERR_INVALID_XML";
 } });
 function sso(options) {
+	const optionsWithStore = options;
 	let endpoints = {
 		spMetadata: spMetadata(),
-		registerSSOProvider: registerSSOProvider(options),
-		signInSSO: signInSSO(options),
-		callbackSSO: callbackSSO(options),
-		callbackSSOSAML: callbackSSOSAML(options),
-		acsEndpoint: acsEndpoint(options)
+		registerSSOProvider: registerSSOProvider(optionsWithStore),
+		signInSSO: signInSSO(optionsWithStore),
+		callbackSSO: callbackSSO(optionsWithStore),
+		callbackSSOSAML: callbackSSOSAML(optionsWithStore),
+		acsEndpoint: acsEndpoint(optionsWithStore)
 	};
 	if (options?.domainVerification?.enabled) {
 		const domainVerificationEndpoints = {
-			requestDomainVerification: requestDomainVerification(options),
-			verifyDomain: verifyDomain(options)
+			requestDomainVerification: requestDomainVerification(optionsWithStore),
+			verifyDomain: verifyDomain(optionsWithStore)
 		};
 		endpoints = {
 			...endpoints,
@@ -1512,4 +2008,4 @@ function sso(options) {
 }
 
 //#endregion
-export { sso };
+export { DEFAULT_AUTHN_REQUEST_TTL_MS, DEFAULT_CLOCK_SKEW_MS, DiscoveryError, REQUIRED_DISCOVERY_FIELDS, computeDiscoveryUrl, createInMemoryAuthnRequestStore, discoverOIDCConfig, fetchDiscoveryDocument, needsRuntimeDiscovery, normalizeDiscoveryUrls, normalizeUrl, selectTokenEndpointAuthMethod, sso, validateDiscoveryDocument, validateDiscoveryUrl, validateSAMLTimestamp };