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

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @better-auth/sso@1.5.0-beta.2 build /home/runner/work/better-auth/better-auth/packages/sso
+> @better-auth/sso@1.5.0-beta.4 build /home/runner/work/better-auth/better-auth/packages/sso
 > tsdown
 
 ℹ tsdown v0.17.2 powered by rolldown v1.0.0-beta.53
@@ -7,10 +7,10 @@
 ℹ entry: src/index.ts, src/client.ts
 ℹ tsconfig: tsconfig.json
 ℹ Build start
-ℹ dist/index.mjs             97.24 kB │ gzip: 18.91 kB
+ℹ dist/index.mjs             99.53 kB │ gzip: 19.50 kB
 ℹ dist/client.mjs             0.15 kB │ gzip:  0.14 kB
 ℹ dist/index.d.mts            1.67 kB │ gzip:  0.57 kB
 ℹ dist/client.d.mts           0.49 kB │ gzip:  0.30 kB
-ℹ dist/index-D4Ey-vkQ.d.mts  44.21 kB │ gzip:  9.10 kB
-ℹ 5 files, total: 143.76 kB
-✔ Build complete in 15849ms
+ℹ dist/index-BLMoKtp1.d.mts  44.35 kB │ gzip:  9.16 kB
+ℹ 5 files, total: 146.19 kB
+✔ Build complete in 17118ms

package/LICENSE.md

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

package/dist/client.d.mts

@@ -1,4 +1,4 @@
-import { t as SSOPlugin } from "./index-D4Ey-vkQ.mjs";
+import { t as SSOPlugin } from "./index-BLMoKtp1.mjs";
 
 //#region src/client.d.ts
 interface SSOClientOptions {

package/dist/{index-D4Ey-vkQ.d.mts → index-BLMoKtp1.d.mts}

@@ -1249,6 +1249,13 @@ declare function selectTokenEndpointAuthMethod(doc: OIDCDiscoveryDocument, exist
 declare function needsRuntimeDiscovery(config: Partial<HydratedOIDCConfig> | undefined): boolean;
 //#endregion
 //#region src/index.d.ts
+declare module "@better-auth/core" {
+  interface BetterAuthPluginRegistry<Auth, Context> {
+    sso: {
+      creator: typeof sso;
+    };
+  }
+}
 type DomainVerificationEndpoints = {
   requestDomainVerification: ReturnType<typeof requestDomainVerification>;
   verifyDomain: ReturnType<typeof verifyDomain>;

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { A as DataEncryptionAlgorithm, C as TimestampValidationOptions, D as SSOOptions, E as SAMLConfig, M as DigestAlgorithm, N as KeyEncryptionAlgorithm, O as SSOProvider, P as SignatureAlgorithm, S as SAMLConditions, T as OIDCConfig, _ as REQUIRED_DISCOVERY_FIELDS, a as fetchDiscoveryDocument, b as DEFAULT_MAX_SAML_METADATA_SIZE, c as normalizeUrl, d as validateDiscoveryUrl, f as DiscoverOIDCConfigParams, g as OIDCDiscoveryDocument, h as HydratedOIDCConfig, i as discoverOIDCConfig, j as DeprecatedAlgorithmBehavior, k as AlgorithmValidationOptions, l as selectTokenEndpointAuthMethod, m as DiscoveryErrorCode, n as sso, o as needsRuntimeDiscovery, p as DiscoveryError, r as computeDiscoveryUrl, s as normalizeDiscoveryUrls, t as SSOPlugin, u as validateDiscoveryDocument, v as RequiredDiscoveryField, w as validateSAMLTimestamp, x as DEFAULT_MAX_SAML_RESPONSE_SIZE, y as DEFAULT_CLOCK_SKEW_MS } from "./index-D4Ey-vkQ.mjs";
+import { A as DataEncryptionAlgorithm, C as TimestampValidationOptions, D as SSOOptions, E as SAMLConfig, M as DigestAlgorithm, N as KeyEncryptionAlgorithm, O as SSOProvider, P as SignatureAlgorithm, S as SAMLConditions, T as OIDCConfig, _ as REQUIRED_DISCOVERY_FIELDS, a as fetchDiscoveryDocument, b as DEFAULT_MAX_SAML_METADATA_SIZE, c as normalizeUrl, d as validateDiscoveryUrl, f as DiscoverOIDCConfigParams, g as OIDCDiscoveryDocument, h as HydratedOIDCConfig, i as discoverOIDCConfig, j as DeprecatedAlgorithmBehavior, k as AlgorithmValidationOptions, l as selectTokenEndpointAuthMethod, m as DiscoveryErrorCode, n as sso, o as needsRuntimeDiscovery, p as DiscoveryError, r as computeDiscoveryUrl, s as normalizeDiscoveryUrls, t as SSOPlugin, u as validateDiscoveryDocument, v as RequiredDiscoveryField, w as validateSAMLTimestamp, x as DEFAULT_MAX_SAML_RESPONSE_SIZE, y as DEFAULT_CLOCK_SKEW_MS } from "./index-BLMoKtp1.mjs";
 export { AlgorithmValidationOptions, DEFAULT_CLOCK_SKEW_MS, DEFAULT_MAX_SAML_METADATA_SIZE, DEFAULT_MAX_SAML_RESPONSE_SIZE, DataEncryptionAlgorithm, DeprecatedAlgorithmBehavior, DigestAlgorithm, DiscoverOIDCConfigParams, DiscoveryError, DiscoveryErrorCode, HydratedOIDCConfig, KeyEncryptionAlgorithm, OIDCConfig, OIDCDiscoveryDocument, REQUIRED_DISCOVERY_FIELDS, RequiredDiscoveryField, SAMLConditions, SAMLConfig, SSOOptions, SSOPlugin, SSOProvider, SignatureAlgorithm, TimestampValidationOptions, computeDiscoveryUrl, discoverOIDCConfig, fetchDiscoveryDocument, needsRuntimeDiscovery, normalizeDiscoveryUrls, normalizeUrl, selectTokenEndpointAuthMethod, sso, validateDiscoveryDocument, validateDiscoveryUrl, validateSAMLTimestamp };

package/dist/index.mjs

@@ -9,6 +9,7 @@ import { HIDE_METADATA, createAuthorizationURL, generateState, parseState, valid
 import { setSessionCookie } from "better-auth/cookies";
 import { handleOAuthUserInfo } from "better-auth/oauth2";
 import { decodeJwt } from "jose";
+import { base64 } from "@better-auth/utils/base64";
 
 //#region src/linking/org-assignment.ts
 /**
@@ -662,6 +663,41 @@ function mapDiscoveryErrorToAPIError(error) {
 	}
 }
 
+//#endregion
+//#region src/saml/parser.ts
+const xmlParser = new XMLParser({
+	ignoreAttributes: false,
+	attributeNamePrefix: "@_",
+	removeNSPrefix: true,
+	processEntities: false
+});
+function findNode(obj, nodeName) {
+	if (!obj || typeof obj !== "object") return null;
+	const record = obj;
+	if (nodeName in record) return record[nodeName];
+	for (const value of Object.values(record)) if (Array.isArray(value)) for (const item of value) {
+		const found = findNode(item, nodeName);
+		if (found) return found;
+	}
+	else if (typeof value === "object" && value !== null) {
+		const found = findNode(value, nodeName);
+		if (found) return found;
+	}
+	return null;
+}
+function countAllNodes(obj, nodeName) {
+	if (!obj || typeof obj !== "object") return 0;
+	let count = 0;
+	const record = obj;
+	if (nodeName in record) {
+		const node = record[nodeName];
+		count += Array.isArray(node) ? node.length : 1;
+	}
+	for (const value of Object.values(record)) if (Array.isArray(value)) for (const item of value) count += countAllNodes(item, nodeName);
+	else if (typeof value === "object" && value !== null) count += countAllNodes(value, nodeName);
+	return count;
+}
+
 //#endregion
 //#region src/saml/algorithms.ts
 const SignatureAlgorithm = {
@@ -735,26 +771,6 @@ function normalizeSignatureAlgorithm(alg) {
 function normalizeDigestAlgorithm(alg) {
 	return SHORT_FORM_DIGEST_TO_URI[alg.toLowerCase()] ?? alg;
 }
-const xmlParser = new XMLParser({
-	ignoreAttributes: false,
-	attributeNamePrefix: "@_",
-	removeNSPrefix: true,
-	processEntities: false
-});
-function findNode(obj, nodeName) {
-	if (!obj || typeof obj !== "object") return null;
-	const record = obj;
-	if (nodeName in record) return record[nodeName];
-	for (const value of Object.values(record)) if (Array.isArray(value)) for (const item of value) {
-		const found = findNode(item, nodeName);
-		if (found) return found;
-	}
-	else if (typeof value === "object" && value !== null) {
-		const found = findNode(value, nodeName);
-		if (found) return found;
-	}
-	return null;
-}
 function extractEncryptionAlgorithms(xml) {
 	try {
 		const parsed = xmlParser.parse(xml);
@@ -863,6 +879,49 @@ function validateConfigAlgorithms(config, options = {}) {
 	}
 }
 
+//#endregion
+//#region src/saml/assertions.ts
+/** @lintignore used in tests */
+function countAssertions(xml) {
+	let parsed;
+	try {
+		parsed = xmlParser.parse(xml);
+	} catch {
+		throw new APIError("BAD_REQUEST", {
+			message: "Failed to parse SAML response XML",
+			code: "SAML_INVALID_XML"
+		});
+	}
+	const assertions = countAllNodes(parsed, "Assertion");
+	const encryptedAssertions = countAllNodes(parsed, "EncryptedAssertion");
+	return {
+		assertions,
+		encryptedAssertions,
+		total: assertions + encryptedAssertions
+	};
+}
+function validateSingleAssertion(samlResponse) {
+	let xml;
+	try {
+		xml = new TextDecoder().decode(base64.decode(samlResponse));
+		if (!xml.includes("<")) throw new Error("Not XML");
+	} catch {
+		throw new APIError("BAD_REQUEST", {
+			message: "Invalid base64-encoded SAML response",
+			code: "SAML_INVALID_ENCODING"
+		});
+	}
+	const counts = countAssertions(xml);
+	if (counts.total === 0) throw new APIError("BAD_REQUEST", {
+		message: "SAML response contains no assertions",
+		code: "SAML_NO_ASSERTION"
+	});
+	if (counts.total > 1) throw new APIError("BAD_REQUEST", {
+		message: `SAML response contains ${counts.total} assertions, expected exactly 1`,
+		code: "SAML_MULTIPLE_ASSERTIONS"
+	});
+}
+
 //#endregion
 //#region src/utils.ts
 /**
@@ -1854,6 +1913,7 @@ const callbackSSOSAML = (options) => {
 			wantMessageSigned: parsedSamlConfig.wantAssertionsSigned || false,
 			nameIDFormat: parsedSamlConfig.identifierFormat ? [parsedSamlConfig.identifierFormat] : void 0
 		});
+		validateSingleAssertion(SAMLResponse);
 		let parsedResponse;
 		try {
 			parsedResponse = await sp.parseLoginResponse(idp, "post", { body: {
@@ -2090,6 +2150,16 @@ const acsEndpoint = (options) => {
 			}],
 			signingCert: idpData?.cert || parsedSamlConfig.cert
 		}) : saml.IdentityProvider({ metadata: idpData.metadata });
+		try {
+			validateSingleAssertion(SAMLResponse);
+		} catch (error) {
+			if (error instanceof APIError) {
+				const redirectUrl = RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
+				const errorCode = error.body?.code === "SAML_MULTIPLE_ASSERTIONS" ? "multiple_assertions" : "no_assertion";
+				throw ctx.redirect(`${redirectUrl}?error=${errorCode}&error_description=${encodeURIComponent(error.message)}`);
+			}
+			throw error;
+		}
 		let parsedResponse;
 		try {
 			parsedResponse = await sp.parseLoginResponse(idp, "post", { body: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@better-auth/sso",
   "author": "Bereket Engida",
-  "version": "1.5.0-beta.2",
+  "version": "1.5.0-beta.4",
   "type": "module",
   "main": "dist/index.mjs",
   "types": "dist/index.d.mts",
@@ -52,6 +52,7 @@
     }
   },
   "dependencies": {
+    "@better-auth/utils": "0.3.0",
     "@better-fetch/fetch": "1.1.21",
     "fast-xml-parser": "^5.2.5",
     "jose": "^6.1.0",
@@ -59,22 +60,24 @@
     "zod": "^4.1.12"
   },
   "devDependencies": {
-    "@better-auth/utils": "0.3.0",
     "@types/body-parser": "^1.19.6",
     "@types/express": "^5.0.5",
-    "better-call": "1.1.7",
+    "better-call": "1.1.8",
     "body-parser": "^2.2.1",
     "express": "^5.1.0",
     "oauth2-mock-server": "^8.2.0",
     "tsdown": "^0.17.2",
-    "better-auth": "1.5.0-beta.2"
+    "@better-auth/core": "1.5.0-beta.4",
+    "better-auth": "1.5.0-beta.4"
   },
   "peerDependencies": {
-    "better-auth": "1.5.0-beta.2"
+    "@better-auth/utils": "0.3.0",
+    "@better-auth/core": "1.5.0-beta.4",
+    "better-auth": "1.5.0-beta.4"
   },
   "scripts": {
     "test": "vitest",
-    "coverage": "vitest run --coverage",
+    "coverage": "vitest run --coverage --coverage.provider=istanbul",
     "lint:package": "publint run --strict",
     "lint:types": "attw --profile esm-only --pack .",
     "build": "tsdown",

package/src/index.ts

@@ -41,6 +41,15 @@ import type { OIDCConfig, SAMLConfig, SSOOptions, SSOProvider } from "./types";
 
 export type { SAMLConfig, OIDCConfig, SSOOptions, SSOProvider };
 
+declare module "@better-auth/core" {
+	// biome-ignore lint/correctness/noUnusedVariables: Auth and Context need to be same as declared in the module
+	interface BetterAuthPluginRegistry<Auth, Context> {
+		sso: {
+			creator: typeof sso;
+		};
+	}
+}
+
 export {
 	computeDiscoveryUrl,
 	type DiscoverOIDCConfigParams,

package/src/routes/sso.ts

@@ -47,7 +47,11 @@ import {
 	discoverOIDCConfig,
 	mapDiscoveryErrorToAPIError,
 } from "../oidc";
-import { validateConfigAlgorithms, validateSAMLAlgorithms } from "../saml";
+import {
+	validateConfigAlgorithms,
+	validateSAMLAlgorithms,
+	validateSingleAssertion,
+} from "../saml";
 import type { OIDCConfig, SAMLConfig, SSOOptions, SSOProvider } from "../types";
 import { safeJsonParse, validateEmailDomain } from "../utils";
 
@@ -1835,6 +1839,8 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 					: undefined,
 			});
 
+			validateSingleAssertion(SAMLResponse);
+
 			let parsedResponse: FlowResult;
 			try {
 				parsedResponse = await sp.parseLoginResponse(idp, "post", {
@@ -2272,6 +2278,23 @@ export const acsEndpoint = (options?: SSOOptions) => {
 						metadata: idpData.metadata,
 					});
 
+			try {
+				validateSingleAssertion(SAMLResponse);
+			} catch (error) {
+				if (error instanceof APIError) {
+					const redirectUrl =
+						RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
+					const errorCode =
+						error.body?.code === "SAML_MULTIPLE_ASSERTIONS"
+							? "multiple_assertions"
+							: "no_assertion";
+					throw ctx.redirect(
+						`${redirectUrl}?error=${errorCode}&error_description=${encodeURIComponent(error.message)}`,
+					);
+				}
+				throw error;
+			}
+
 			// Parse and validate SAML response
 			let parsedResponse: FlowResult;
 			try {

package/src/saml/algorithms.ts

@@ -1,5 +1,5 @@
 import { APIError } from "better-auth/api";
-import { XMLParser } from "fast-xml-parser";
+import { findNode, xmlParser } from "./parser";
 
 export const SignatureAlgorithm = {
 	RSA_SHA1: "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
@@ -102,37 +102,6 @@ export interface AlgorithmValidationOptions {
 	allowedDataEncryptionAlgorithms?: string[];
 }
 
-const xmlParser = new XMLParser({
-	ignoreAttributes: false,
-	attributeNamePrefix: "@_",
-	removeNSPrefix: true,
-	processEntities: false,
-});
-
-function findNode(obj: unknown, nodeName: string): unknown {
-	if (!obj || typeof obj !== "object") return null;
-
-	const record = obj as Record<string, unknown>;
-
-	if (nodeName in record) {
-		return record[nodeName];
-	}
-
-	for (const value of Object.values(record)) {
-		if (Array.isArray(value)) {
-			for (const item of value) {
-				const found = findNode(item, nodeName);
-				if (found) return found;
-			}
-		} else if (typeof value === "object" && value !== null) {
-			const found = findNode(value, nodeName);
-			if (found) return found;
-		}
-	}
-
-	return null;
-}
-
 function extractEncryptionAlgorithms(xml: string): {
 	keyEncryption: string | null;
 	dataEncryption: string | null;

package/src/saml/assertions.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, it } from "vitest";
+import { countAssertions, validateSingleAssertion } from "./assertions";
+
+describe("validateSingleAssertion", () => {
+	const encode = (xml: string) => Buffer.from(xml).toString("base64");
+
+	describe("valid responses (exactly 1 assertion)", () => {
+		it("should accept response with single assertion", () => {
+			const xml = `
+				<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
+					<saml:Assertion ID="123">
+						<saml:Subject><saml:NameID>user@example.com</saml:NameID></saml:Subject>
+					</saml:Assertion>
+				</samlp:Response>
+			`;
+			expect(() => validateSingleAssertion(encode(xml))).not.toThrow();
+		});
+
+		it("should accept response with single encrypted assertion", () => {
+			const xml = `
+				<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
+					<saml:EncryptedAssertion>
+						<xenc:EncryptedData>...</xenc:EncryptedData>
+					</saml:EncryptedAssertion>
+				</samlp:Response>
+			`;
+			expect(() => validateSingleAssertion(encode(xml))).not.toThrow();
+		});
+	});
+
+	describe("no assertions", () => {
+		it("should reject response with no assertions", () => {
+			const xml = `
+				<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
+					<samlp:Status>
+						<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
+					</samlp:Status>
+				</samlp:Response>
+			`;
+			expect(() => validateSingleAssertion(encode(xml))).toThrow(
+				"SAML response contains no assertions",
+			);
+		});
+	});
+
+	describe("multiple assertions", () => {
+		it("should reject response with multiple unencrypted assertions", () => {
+			const xml = `
+				<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
+					<saml:Assertion ID="assertion1">
+						<saml:Subject><saml:NameID>user@example.com</saml:NameID></saml:Subject>
+					</saml:Assertion>
+					<saml:Assertion ID="assertion2">
+						<saml:Subject><saml:NameID>attacker@evil.com</saml:NameID></saml:Subject>
+					</saml:Assertion>
+				</samlp:Response>
+			`;
+			expect(() => validateSingleAssertion(encode(xml))).toThrow(
+				"SAML response contains 2 assertions, expected exactly 1",
+			);
+		});
+
+		it("should reject response with multiple encrypted assertions", () => {
+			const xml = `
+				<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
+					<saml:EncryptedAssertion>
+						<xenc:EncryptedData>...</xenc:EncryptedData>
+					</saml:EncryptedAssertion>
+					<saml:EncryptedAssertion>
+						<xenc:EncryptedData>...</xenc:EncryptedData>
+					</saml:EncryptedAssertion>
+				</samlp:Response>
+			`;
+			expect(() => validateSingleAssertion(encode(xml))).toThrow(
+				"SAML response contains 2 assertions, expected exactly 1",
+			);
+		});
+
+		it("should reject response with mixed assertion types", () => {
+			const xml = `
+				<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
+					<saml:Assertion ID="plain-assertion">
+						<saml:Subject><saml:NameID>user@example.com</saml:NameID></saml:Subject>
+					</saml:Assertion>
+					<saml:EncryptedAssertion>
+						<xenc:EncryptedData>...</xenc:EncryptedData>
+					</saml:EncryptedAssertion>
+				</samlp:Response>
+			`;
+			expect(() => validateSingleAssertion(encode(xml))).toThrow(
+				"SAML response contains 2 assertions, expected exactly 1",
+			);
+		});
+	});
+
+	describe("XSW attack patterns", () => {
+		it("should reject assertion injected in Extensions element", () => {
+			const xml = `
+				<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
+					<samlp:Extensions>
+						<saml:Assertion ID="injected-assertion">
+							<saml:Subject><saml:NameID>attacker@evil.com</saml:NameID></saml:Subject>
+						</saml:Assertion>
+					</samlp:Extensions>
+					<saml:Assertion ID="legitimate-assertion">
+						<saml:Subject><saml:NameID>user@example.com</saml:NameID></saml:Subject>
+					</saml:Assertion>
+				</samlp:Response>
+			`;
+			expect(() => validateSingleAssertion(encode(xml))).toThrow(
+				"SAML response contains 2 assertions, expected exactly 1",
+			);
+		});
+
+		it("should reject assertion wrapped in arbitrary element", () => {
+			const xml = `
+				<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
+					<Wrapper>
+						<saml:Assertion ID="wrapped-assertion">
+							<saml:Subject><saml:NameID>attacker@evil.com</saml:NameID></saml:Subject>
+						</saml:Assertion>
+					</Wrapper>
+					<saml:Assertion ID="legitimate-assertion">
+						<saml:Subject><saml:NameID>user@example.com</saml:NameID></saml:Subject>
+					</saml:Assertion>
+				</samlp:Response>
+			`;
+			expect(() => validateSingleAssertion(encode(xml))).toThrow(
+				"SAML response contains 2 assertions, expected exactly 1",
+			);
+		});
+
+		it("should reject deeply nested injected assertion", () => {
+			const xml = `
+				<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
+					<Level1>
+						<Level2>
+							<Level3>
+								<saml:Assertion ID="deep-injected">
+									<saml:Subject><saml:NameID>attacker@evil.com</saml:NameID></saml:Subject>
+								</saml:Assertion>
+							</Level3>
+						</Level2>
+					</Level1>
+					<saml:Assertion ID="legitimate-assertion">
+						<saml:Subject><saml:NameID>user@example.com</saml:NameID></saml:Subject>
+					</saml:Assertion>
+				</samlp:Response>
+			`;
+			expect(() => validateSingleAssertion(encode(xml))).toThrow(
+				"SAML response contains 2 assertions, expected exactly 1",
+			);
+		});
+	});
+
+	describe("namespace handling", () => {
+		it("should handle assertion without namespace prefix", () => {
+			const xml = `
+				<Response>
+					<Assertion ID="123">
+						<Subject><NameID>user@example.com</NameID></Subject>
+					</Assertion>
+				</Response>
+			`;
+			expect(() => validateSingleAssertion(encode(xml))).not.toThrow();
+		});
+
+		it("should handle assertion with saml2: prefix", () => {
+			const xml = `
+				<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
+					<saml2:Assertion ID="123">
+						<saml2:Subject><saml2:NameID>user@example.com</saml2:NameID></saml2:Subject>
+					</saml2:Assertion>
+				</saml2p:Response>
+			`;
+			expect(() => validateSingleAssertion(encode(xml))).not.toThrow();
+		});
+
+		it("should handle assertion with custom prefix", () => {
+			const xml = `
+				<custom:Response xmlns:custom="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:myprefix="urn:oasis:names:tc:SAML:2.0:assertion">
+					<myprefix:Assertion ID="123">
+						<myprefix:Subject><myprefix:NameID>user@example.com</myprefix:NameID></myprefix:Subject>
+					</myprefix:Assertion>
+				</custom:Response>
+			`;
+			expect(() => validateSingleAssertion(encode(xml))).not.toThrow();
+		});
+	});
+});
+
+describe("countAssertions", () => {
+	it("should return separate counts for assertions and encrypted assertions", () => {
+		const xml = `
+			<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
+				<saml:Assertion ID="plain">
+					<saml:Subject><saml:NameID>user@example.com</saml:NameID></saml:Subject>
+				</saml:Assertion>
+				<saml:EncryptedAssertion>
+					<xenc:EncryptedData>...</xenc:EncryptedData>
+				</saml:EncryptedAssertion>
+			</samlp:Response>
+		`;
+		const counts = countAssertions(xml);
+		expect(counts.assertions).toBe(1);
+		expect(counts.encryptedAssertions).toBe(1);
+		expect(counts.total).toBe(2);
+	});
+
+	it("should not count AssertionConsumerService as assertion", () => {
+		const xml = `
+			<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
+				<md:SPSSODescriptor>
+					<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://example.com/acs"/>
+				</md:SPSSODescriptor>
+			</md:EntityDescriptor>
+		`;
+		const counts = countAssertions(xml);
+		expect(counts.assertions).toBe(0);
+		expect(counts.total).toBe(0);
+	});
+});
+
+describe("error handling", () => {
+	const encode = (str: string) => Buffer.from(str).toString("base64");
+
+	it("should reject invalid base64 input", () => {
+		expect(() => validateSingleAssertion("not-valid-base64!!!")).toThrow(
+			"Invalid base64-encoded SAML response",
+		);
+	});
+
+	it("should reject non-XML content", () => {
+		const notXml = encode("this is not xml at all");
+		expect(() => validateSingleAssertion(notXml)).toThrow(
+			"Invalid base64-encoded SAML response",
+		);
+	});
+});

package/src/saml/assertions.ts

@@ -0,0 +1,62 @@
+import { base64 } from "@better-auth/utils/base64";
+import { APIError } from "better-auth/api";
+import { countAllNodes, xmlParser } from "./parser";
+
+export interface AssertionCounts {
+	assertions: number;
+	encryptedAssertions: number;
+	total: number;
+}
+
+/** @lintignore used in tests */
+export function countAssertions(xml: string): AssertionCounts {
+	let parsed: unknown;
+	try {
+		parsed = xmlParser.parse(xml);
+	} catch {
+		throw new APIError("BAD_REQUEST", {
+			message: "Failed to parse SAML response XML",
+			code: "SAML_INVALID_XML",
+		});
+	}
+
+	const assertions = countAllNodes(parsed, "Assertion");
+	const encryptedAssertions = countAllNodes(parsed, "EncryptedAssertion");
+
+	return {
+		assertions,
+		encryptedAssertions,
+		total: assertions + encryptedAssertions,
+	};
+}
+
+export function validateSingleAssertion(samlResponse: string): void {
+	let xml: string;
+	try {
+		xml = new TextDecoder().decode(base64.decode(samlResponse));
+		if (!xml.includes("<")) {
+			throw new Error("Not XML");
+		}
+	} catch {
+		throw new APIError("BAD_REQUEST", {
+			message: "Invalid base64-encoded SAML response",
+			code: "SAML_INVALID_ENCODING",
+		});
+	}
+
+	const counts = countAssertions(xml);
+
+	if (counts.total === 0) {
+		throw new APIError("BAD_REQUEST", {
+			message: "SAML response contains no assertions",
+			code: "SAML_NO_ASSERTION",
+		});
+	}
+
+	if (counts.total > 1) {
+		throw new APIError("BAD_REQUEST", {
+			message: `SAML response contains ${counts.total} assertions, expected exactly 1`,
+			code: "SAML_MULTIPLE_ASSERTIONS",
+		});
+	}
+}

package/src/saml/index.ts

@@ -9,3 +9,5 @@ export {
 	validateConfigAlgorithms,
 	validateSAMLAlgorithms,
 } from "./algorithms";
+
+export { validateSingleAssertion } from "./assertions";

package/src/saml/parser.ts

@@ -0,0 +1,56 @@
+import { XMLParser } from "fast-xml-parser";
+
+export const xmlParser = new XMLParser({
+	ignoreAttributes: false,
+	attributeNamePrefix: "@_",
+	removeNSPrefix: true,
+	processEntities: false,
+});
+
+export function findNode(obj: unknown, nodeName: string): unknown {
+	if (!obj || typeof obj !== "object") return null;
+
+	const record = obj as Record<string, unknown>;
+
+	if (nodeName in record) {
+		return record[nodeName];
+	}
+
+	for (const value of Object.values(record)) {
+		if (Array.isArray(value)) {
+			for (const item of value) {
+				const found = findNode(item, nodeName);
+				if (found) return found;
+			}
+		} else if (typeof value === "object" && value !== null) {
+			const found = findNode(value, nodeName);
+			if (found) return found;
+		}
+	}
+
+	return null;
+}
+
+export function countAllNodes(obj: unknown, nodeName: string): number {
+	if (!obj || typeof obj !== "object") return 0;
+
+	let count = 0;
+	const record = obj as Record<string, unknown>;
+
+	if (nodeName in record) {
+		const node = record[nodeName];
+		count += Array.isArray(node) ? node.length : 1;
+	}
+
+	for (const value of Object.values(record)) {
+		if (Array.isArray(value)) {
+			for (const item of value) {
+				count += countAllNodes(item, nodeName);
+			}
+		} else if (typeof value === "object" && value !== null) {
+			count += countAllNodes(value, nodeName);
+		}
+	}
+
+	return count;
+}

package/src/saml.test.ts

@@ -2614,3 +2614,351 @@ describe("SAML SSO - Assertion Replay Protection", () => {
 		expect(acsLocation).toContain("error=replay_detected");
 	});
 });
+
+describe("SAML SSO - Single Assertion Validation", () => {
+	it("should reject SAML response with multiple assertions on callback endpoint", async () => {
+		const { auth, signInWithTestUser } = await getTestInstance({
+			plugins: [sso()],
+		});
+
+		const { headers } = await signInWithTestUser();
+
+		await auth.api.registerSSOProvider({
+			body: {
+				providerId: "multi-assertion-callback-provider",
+				issuer: "http://localhost:8081",
+				domain: "http://localhost:8081",
+				samlConfig: {
+					entryPoint: "http://localhost:8081/api/sso/saml2/idp/post",
+					cert: certificate,
+					callbackUrl: "http://localhost:3000/dashboard",
+					wantAssertionsSigned: false,
+					signatureAlgorithm: "sha256",
+					digestAlgorithm: "sha256",
+					idpMetadata: {
+						metadata: idpMetadata,
+					},
+					spMetadata: {
+						metadata: spMetadata,
+					},
+					identifierFormat:
+						"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
+				},
+			},
+			headers,
+		});
+
+		const multiAssertionResponse = `
+			<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
+				<saml2:Issuer>http://localhost:8081</saml2:Issuer>
+				<saml2p:Status>
+					<saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
+				</saml2p:Status>
+				<saml2:Assertion ID="assertion-1">
+					<saml2:Issuer>http://localhost:8081</saml2:Issuer>
+					<saml2:Subject>
+						<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">legitimate@example.com</saml2:NameID>
+					</saml2:Subject>
+				</saml2:Assertion>
+				<saml2:Assertion ID="assertion-2">
+					<saml2:Issuer>http://localhost:8081</saml2:Issuer>
+					<saml2:Subject>
+						<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">attacker@evil.com</saml2:NameID>
+					</saml2:Subject>
+				</saml2:Assertion>
+			</saml2p:Response>
+		`;
+
+		const encodedResponse = Buffer.from(multiAssertionResponse).toString(
+			"base64",
+		);
+
+		await expect(
+			auth.api.callbackSSOSAML({
+				body: {
+					SAMLResponse: encodedResponse,
+					RelayState: "http://localhost:3000/dashboard",
+				},
+				params: {
+					providerId: "multi-assertion-callback-provider",
+				},
+			}),
+		).rejects.toMatchObject({
+			body: {
+				code: "SAML_MULTIPLE_ASSERTIONS",
+			},
+		});
+	});
+
+	it("should reject SAML response with multiple assertions on ACS endpoint", async () => {
+		const { auth, signInWithTestUser } = await getTestInstance({
+			plugins: [sso()],
+		});
+
+		const { headers } = await signInWithTestUser();
+
+		await auth.api.registerSSOProvider({
+			body: {
+				providerId: "multi-assertion-acs-provider",
+				issuer: "http://localhost:8081",
+				domain: "http://localhost:8081",
+				samlConfig: {
+					entryPoint: "http://localhost:8081/api/sso/saml2/idp/post",
+					cert: certificate,
+					callbackUrl: "http://localhost:3000/dashboard",
+					wantAssertionsSigned: false,
+					signatureAlgorithm: "sha256",
+					digestAlgorithm: "sha256",
+					idpMetadata: {
+						metadata: idpMetadata,
+					},
+					spMetadata: {
+						metadata: spMetadata,
+					},
+					identifierFormat:
+						"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
+				},
+			},
+			headers,
+		});
+
+		const multiAssertionResponse = `
+			<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
+				<saml2:Issuer>http://localhost:8081</saml2:Issuer>
+				<saml2p:Status>
+					<saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
+				</saml2p:Status>
+				<saml2:Assertion ID="assertion-1">
+					<saml2:Issuer>http://localhost:8081</saml2:Issuer>
+					<saml2:Subject>
+						<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">legitimate@example.com</saml2:NameID>
+					</saml2:Subject>
+				</saml2:Assertion>
+				<saml2:Assertion ID="assertion-2">
+					<saml2:Issuer>http://localhost:8081</saml2:Issuer>
+					<saml2:Subject>
+						<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">attacker@evil.com</saml2:NameID>
+					</saml2:Subject>
+				</saml2:Assertion>
+			</saml2p:Response>
+		`;
+
+		const encodedResponse = Buffer.from(multiAssertionResponse).toString(
+			"base64",
+		);
+
+		const response = await auth.handler(
+			new Request(
+				"http://localhost:3000/api/auth/sso/saml2/sp/acs/multi-assertion-acs-provider",
+				{
+					method: "POST",
+					headers: {
+						"Content-Type": "application/x-www-form-urlencoded",
+					},
+					body: new URLSearchParams({
+						SAMLResponse: encodedResponse,
+						RelayState: "http://localhost:3000/dashboard",
+					}),
+				},
+			),
+		);
+
+		expect(response.status).toBe(302);
+		const location = response.headers.get("location") || "";
+		expect(location).toContain("error=multiple_assertions");
+	});
+
+	it("should reject SAML response with no assertions", async () => {
+		const { auth, signInWithTestUser } = await getTestInstance({
+			plugins: [sso()],
+		});
+
+		const { headers } = await signInWithTestUser();
+
+		await auth.api.registerSSOProvider({
+			body: {
+				providerId: "no-assertion-provider",
+				issuer: "http://localhost:8081",
+				domain: "http://localhost:8081",
+				samlConfig: {
+					entryPoint: "http://localhost:8081/api/sso/saml2/idp/post",
+					cert: certificate,
+					callbackUrl: "http://localhost:3000/dashboard",
+					wantAssertionsSigned: false,
+					signatureAlgorithm: "sha256",
+					digestAlgorithm: "sha256",
+					idpMetadata: {
+						metadata: idpMetadata,
+					},
+					spMetadata: {
+						metadata: spMetadata,
+					},
+					identifierFormat:
+						"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
+				},
+			},
+			headers,
+		});
+
+		const noAssertionResponse = `
+			<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
+				<saml2:Issuer>http://localhost:8081</saml2:Issuer>
+				<saml2p:Status>
+					<saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
+				</saml2p:Status>
+			</saml2p:Response>
+		`;
+
+		const encodedResponse = Buffer.from(noAssertionResponse).toString("base64");
+
+		await expect(
+			auth.api.callbackSSOSAML({
+				body: {
+					SAMLResponse: encodedResponse,
+					RelayState: "http://localhost:3000/dashboard",
+				},
+				params: {
+					providerId: "no-assertion-provider",
+				},
+			}),
+		).rejects.toMatchObject({
+			body: {
+				code: "SAML_NO_ASSERTION",
+			},
+		});
+	});
+
+	it("should reject SAML response with XSW-style assertion injection in Extensions", async () => {
+		const { auth, signInWithTestUser } = await getTestInstance({
+			plugins: [sso()],
+		});
+
+		const { headers } = await signInWithTestUser();
+
+		await auth.api.registerSSOProvider({
+			body: {
+				providerId: "xsw-injection-provider",
+				issuer: "http://localhost:8081",
+				domain: "http://localhost:8081",
+				samlConfig: {
+					entryPoint: "http://localhost:8081/api/sso/saml2/idp/post",
+					cert: certificate,
+					callbackUrl: "http://localhost:3000/dashboard",
+					wantAssertionsSigned: false,
+					signatureAlgorithm: "sha256",
+					digestAlgorithm: "sha256",
+					idpMetadata: {
+						metadata: idpMetadata,
+					},
+					spMetadata: {
+						metadata: spMetadata,
+					},
+					identifierFormat:
+						"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
+				},
+			},
+			headers,
+		});
+
+		const xswInjectionResponse = `
+			<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
+				<saml2:Issuer>http://localhost:8081</saml2:Issuer>
+				<saml2p:Status>
+					<saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
+				</saml2p:Status>
+				<saml2p:Extensions>
+					<saml2:Assertion ID="injected-assertion">
+						<saml2:Issuer>http://localhost:8081</saml2:Issuer>
+						<saml2:Subject>
+							<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">attacker@evil.com</saml2:NameID>
+						</saml2:Subject>
+					</saml2:Assertion>
+				</saml2p:Extensions>
+				<saml2:Assertion ID="legitimate-assertion">
+					<saml2:Issuer>http://localhost:8081</saml2:Issuer>
+					<saml2:Subject>
+						<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">user@example.com</saml2:NameID>
+					</saml2:Subject>
+				</saml2:Assertion>
+			</saml2p:Response>
+		`;
+
+		const encodedResponse =
+			Buffer.from(xswInjectionResponse).toString("base64");
+
+		await expect(
+			auth.api.callbackSSOSAML({
+				body: {
+					SAMLResponse: encodedResponse,
+					RelayState: "http://localhost:3000/dashboard",
+				},
+				params: {
+					providerId: "xsw-injection-provider",
+				},
+			}),
+		).rejects.toMatchObject({
+			body: {
+				code: "SAML_MULTIPLE_ASSERTIONS",
+			},
+		});
+	});
+
+	it("should accept valid SAML response with exactly one assertion", async () => {
+		const { auth, signInWithTestUser } = await getTestInstance({
+			plugins: [sso()],
+		});
+
+		const { headers } = await signInWithTestUser();
+
+		await auth.api.registerSSOProvider({
+			body: {
+				providerId: "single-assertion-provider",
+				issuer: "http://localhost:8081",
+				domain: "http://localhost:8081",
+				samlConfig: {
+					entryPoint: "http://localhost:8081/api/sso/saml2/idp/post",
+					cert: certificate,
+					callbackUrl: "http://localhost:3000/dashboard",
+					wantAssertionsSigned: false,
+					signatureAlgorithm: "sha256",
+					digestAlgorithm: "sha256",
+					idpMetadata: {
+						metadata: idpMetadata,
+					},
+					spMetadata: {
+						metadata: spMetadata,
+					},
+					identifierFormat:
+						"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
+				},
+			},
+			headers,
+		});
+
+		let samlResponse: any;
+		await betterFetch("http://localhost:8081/api/sso/saml2/idp/post", {
+			onSuccess: async (context) => {
+				samlResponse = await context.data;
+			},
+		});
+
+		const response = await auth.handler(
+			new Request(
+				"http://localhost:3000/api/auth/sso/saml2/callback/single-assertion-provider",
+				{
+					method: "POST",
+					headers: {
+						"Content-Type": "application/x-www-form-urlencoded",
+					},
+					body: new URLSearchParams({
+						SAMLResponse: samlResponse.samlResponse,
+						RelayState: "http://localhost:3000/dashboard",
+					}),
+				},
+			),
+		);
+
+		expect(response.status).toBe(302);
+		expect(response.headers.get("location")).not.toContain("error");
+	});
+});

package/tsconfig.json

@@ -6,6 +6,9 @@
   "references": [
     {
       "path": "../better-auth/tsconfig.json"
+    },
+    {
+      "path": "../core/tsconfig.json"
     }
   ]
 }