@hammadj/better-auth-sso 1.5.0-beta.9

package/src/saml/algorithms.ts

@@ -0,0 +1,338 @@
+import { APIError } from "better-auth/api";
+import { findNode, xmlParser } from "./parser";
+
+export const SignatureAlgorithm = {
+	RSA_SHA1: "http://www.w3.org/2000/09/xmldsig#rsa-sha1",
+	RSA_SHA256: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
+	RSA_SHA384: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha384",
+	RSA_SHA512: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512",
+	ECDSA_SHA256: "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256",
+	ECDSA_SHA384: "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384",
+	ECDSA_SHA512: "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512",
+} as const;
+
+export const DigestAlgorithm = {
+	SHA1: "http://www.w3.org/2000/09/xmldsig#sha1",
+	SHA256: "http://www.w3.org/2001/04/xmlenc#sha256",
+	SHA384: "http://www.w3.org/2001/04/xmldsig-more#sha384",
+	SHA512: "http://www.w3.org/2001/04/xmlenc#sha512",
+} as const;
+
+export const KeyEncryptionAlgorithm = {
+	RSA_1_5: "http://www.w3.org/2001/04/xmlenc#rsa-1_5",
+	RSA_OAEP: "http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p",
+	RSA_OAEP_SHA256: "http://www.w3.org/2009/xmlenc11#rsa-oaep",
+} as const;
+
+export const DataEncryptionAlgorithm = {
+	TRIPLEDES_CBC: "http://www.w3.org/2001/04/xmlenc#tripledes-cbc",
+	AES_128_CBC: "http://www.w3.org/2001/04/xmlenc#aes128-cbc",
+	AES_192_CBC: "http://www.w3.org/2001/04/xmlenc#aes192-cbc",
+	AES_256_CBC: "http://www.w3.org/2001/04/xmlenc#aes256-cbc",
+	AES_128_GCM: "http://www.w3.org/2009/xmlenc11#aes128-gcm",
+	AES_192_GCM: "http://www.w3.org/2009/xmlenc11#aes192-gcm",
+	AES_256_GCM: "http://www.w3.org/2009/xmlenc11#aes256-gcm",
+} as const;
+
+const DEPRECATED_SIGNATURE_ALGORITHMS: readonly string[] = [
+	SignatureAlgorithm.RSA_SHA1,
+];
+
+const DEPRECATED_KEY_ENCRYPTION_ALGORITHMS: readonly string[] = [
+	KeyEncryptionAlgorithm.RSA_1_5,
+];
+
+const DEPRECATED_DATA_ENCRYPTION_ALGORITHMS: readonly string[] = [
+	DataEncryptionAlgorithm.TRIPLEDES_CBC,
+];
+
+const DEPRECATED_DIGEST_ALGORITHMS: readonly string[] = [DigestAlgorithm.SHA1];
+
+const SECURE_SIGNATURE_ALGORITHMS: readonly string[] = [
+	SignatureAlgorithm.RSA_SHA256,
+	SignatureAlgorithm.RSA_SHA384,
+	SignatureAlgorithm.RSA_SHA512,
+	SignatureAlgorithm.ECDSA_SHA256,
+	SignatureAlgorithm.ECDSA_SHA384,
+	SignatureAlgorithm.ECDSA_SHA512,
+];
+
+const SECURE_DIGEST_ALGORITHMS: readonly string[] = [
+	DigestAlgorithm.SHA256,
+	DigestAlgorithm.SHA384,
+	DigestAlgorithm.SHA512,
+];
+
+const SHORT_FORM_SIGNATURE_TO_URI: Record<string, string> = {
+	sha1: SignatureAlgorithm.RSA_SHA1,
+	sha256: SignatureAlgorithm.RSA_SHA256,
+	sha384: SignatureAlgorithm.RSA_SHA384,
+	sha512: SignatureAlgorithm.RSA_SHA512,
+	"rsa-sha1": SignatureAlgorithm.RSA_SHA1,
+	"rsa-sha256": SignatureAlgorithm.RSA_SHA256,
+	"rsa-sha384": SignatureAlgorithm.RSA_SHA384,
+	"rsa-sha512": SignatureAlgorithm.RSA_SHA512,
+	"ecdsa-sha256": SignatureAlgorithm.ECDSA_SHA256,
+	"ecdsa-sha384": SignatureAlgorithm.ECDSA_SHA384,
+	"ecdsa-sha512": SignatureAlgorithm.ECDSA_SHA512,
+};
+
+const SHORT_FORM_DIGEST_TO_URI: Record<string, string> = {
+	sha1: DigestAlgorithm.SHA1,
+	sha256: DigestAlgorithm.SHA256,
+	sha384: DigestAlgorithm.SHA384,
+	sha512: DigestAlgorithm.SHA512,
+};
+
+function normalizeSignatureAlgorithm(alg: string): string {
+	return SHORT_FORM_SIGNATURE_TO_URI[alg.toLowerCase()] ?? alg;
+}
+
+function normalizeDigestAlgorithm(alg: string): string {
+	return SHORT_FORM_DIGEST_TO_URI[alg.toLowerCase()] ?? alg;
+}
+
+export type DeprecatedAlgorithmBehavior = "reject" | "warn" | "allow";
+
+export interface AlgorithmValidationOptions {
+	onDeprecated?: DeprecatedAlgorithmBehavior;
+	allowedSignatureAlgorithms?: string[];
+	allowedDigestAlgorithms?: string[];
+	allowedKeyEncryptionAlgorithms?: string[];
+	allowedDataEncryptionAlgorithms?: string[];
+}
+
+function extractEncryptionAlgorithms(xml: string): {
+	keyEncryption: string | null;
+	dataEncryption: string | null;
+} {
+	try {
+		const parsed = xmlParser.parse(xml);
+
+		const encryptedKey = findNode(parsed, "EncryptedKey") as Record<
+			string,
+			unknown
+		> | null;
+		const keyEncMethod = encryptedKey?.EncryptionMethod as Record<
+			string,
+			unknown
+		> | null;
+		const keyAlg = keyEncMethod?.["@_Algorithm"] as string | undefined;
+
+		const encryptedData = findNode(parsed, "EncryptedData") as Record<
+			string,
+			unknown
+		> | null;
+		const dataEncMethod = encryptedData?.EncryptionMethod as Record<
+			string,
+			unknown
+		> | null;
+		const dataAlg = dataEncMethod?.["@_Algorithm"] as string | undefined;
+
+		return {
+			keyEncryption: keyAlg || null,
+			dataEncryption: dataAlg || null,
+		};
+	} catch {
+		return {
+			keyEncryption: null,
+			dataEncryption: null,
+		};
+	}
+}
+
+function hasEncryptedAssertion(xml: string): boolean {
+	try {
+		const parsed = xmlParser.parse(xml);
+		return findNode(parsed, "EncryptedAssertion") !== null;
+	} catch {
+		return false;
+	}
+}
+
+function handleDeprecatedAlgorithm(
+	message: string,
+	behavior: DeprecatedAlgorithmBehavior,
+	errorCode: string,
+): void {
+	switch (behavior) {
+		case "reject":
+			throw new APIError("BAD_REQUEST", {
+				message,
+				code: errorCode,
+			});
+		case "warn":
+			console.warn(`[SAML Security Warning] ${message}`);
+			break;
+		case "allow":
+			break;
+	}
+}
+
+function validateSignatureAlgorithm(
+	algorithm: string | null | undefined,
+	options: AlgorithmValidationOptions = {},
+): void {
+	if (!algorithm) {
+		return;
+	}
+
+	const { onDeprecated = "warn", allowedSignatureAlgorithms } = options;
+
+	if (allowedSignatureAlgorithms) {
+		if (!allowedSignatureAlgorithms.includes(algorithm)) {
+			throw new APIError("BAD_REQUEST", {
+				message: `SAML signature algorithm not in allow-list: ${algorithm}`,
+				code: "SAML_ALGORITHM_NOT_ALLOWED",
+			});
+		}
+		return;
+	}
+
+	if (DEPRECATED_SIGNATURE_ALGORITHMS.includes(algorithm)) {
+		handleDeprecatedAlgorithm(
+			`SAML response uses deprecated signature algorithm: ${algorithm}. Please configure your IdP to use SHA-256 or stronger.`,
+			onDeprecated,
+			"SAML_DEPRECATED_ALGORITHM",
+		);
+		return;
+	}
+
+	if (!SECURE_SIGNATURE_ALGORITHMS.includes(algorithm)) {
+		throw new APIError("BAD_REQUEST", {
+			message: `SAML signature algorithm not recognized: ${algorithm}`,
+			code: "SAML_UNKNOWN_ALGORITHM",
+		});
+	}
+}
+
+function validateEncryptionAlgorithms(
+	algorithms: { keyEncryption: string | null; dataEncryption: string | null },
+	options: AlgorithmValidationOptions = {},
+): void {
+	const {
+		onDeprecated = "warn",
+		allowedKeyEncryptionAlgorithms,
+		allowedDataEncryptionAlgorithms,
+	} = options;
+
+	const { keyEncryption, dataEncryption } = algorithms;
+
+	if (keyEncryption) {
+		if (allowedKeyEncryptionAlgorithms) {
+			if (!allowedKeyEncryptionAlgorithms.includes(keyEncryption)) {
+				throw new APIError("BAD_REQUEST", {
+					message: `SAML key encryption algorithm not in allow-list: ${keyEncryption}`,
+					code: "SAML_ALGORITHM_NOT_ALLOWED",
+				});
+			}
+		} else if (DEPRECATED_KEY_ENCRYPTION_ALGORITHMS.includes(keyEncryption)) {
+			handleDeprecatedAlgorithm(
+				`SAML response uses deprecated key encryption algorithm: ${keyEncryption}. Please configure your IdP to use RSA-OAEP.`,
+				onDeprecated,
+				"SAML_DEPRECATED_ALGORITHM",
+			);
+		}
+	}
+
+	if (dataEncryption) {
+		if (allowedDataEncryptionAlgorithms) {
+			if (!allowedDataEncryptionAlgorithms.includes(dataEncryption)) {
+				throw new APIError("BAD_REQUEST", {
+					message: `SAML data encryption algorithm not in allow-list: ${dataEncryption}`,
+					code: "SAML_ALGORITHM_NOT_ALLOWED",
+				});
+			}
+		} else if (DEPRECATED_DATA_ENCRYPTION_ALGORITHMS.includes(dataEncryption)) {
+			handleDeprecatedAlgorithm(
+				`SAML response uses deprecated data encryption algorithm: ${dataEncryption}. Please configure your IdP to use AES-GCM.`,
+				onDeprecated,
+				"SAML_DEPRECATED_ALGORITHM",
+			);
+		}
+	}
+}
+
+export function validateSAMLAlgorithms(
+	response: { sigAlg?: string | null; samlContent: string },
+	options?: AlgorithmValidationOptions,
+): void {
+	validateSignatureAlgorithm(response.sigAlg, options);
+
+	if (hasEncryptedAssertion(response.samlContent)) {
+		const encAlgs = extractEncryptionAlgorithms(response.samlContent);
+		validateEncryptionAlgorithms(encAlgs, options);
+	}
+}
+
+export interface ConfigAlgorithmValidationOptions {
+	onDeprecated?: DeprecatedAlgorithmBehavior;
+	allowedSignatureAlgorithms?: string[];
+	allowedDigestAlgorithms?: string[];
+}
+
+export function validateConfigAlgorithms(
+	config: {
+		signatureAlgorithm?: string | undefined;
+		digestAlgorithm?: string | undefined;
+	},
+	options: ConfigAlgorithmValidationOptions = {},
+): void {
+	const {
+		onDeprecated = "warn",
+		allowedSignatureAlgorithms,
+		allowedDigestAlgorithms,
+	} = options;
+
+	if (config.signatureAlgorithm) {
+		const normalized = normalizeSignatureAlgorithm(config.signatureAlgorithm);
+		if (allowedSignatureAlgorithms) {
+			const normalizedAllowList = allowedSignatureAlgorithms.map(
+				normalizeSignatureAlgorithm,
+			);
+			if (!normalizedAllowList.includes(normalized)) {
+				throw new APIError("BAD_REQUEST", {
+					message: `SAML signature algorithm not in allow-list: ${config.signatureAlgorithm}`,
+					code: "SAML_ALGORITHM_NOT_ALLOWED",
+				});
+			}
+		} else if (DEPRECATED_SIGNATURE_ALGORITHMS.includes(normalized)) {
+			handleDeprecatedAlgorithm(
+				`SAML config uses deprecated signature algorithm: ${config.signatureAlgorithm}. Consider using SHA-256 or stronger.`,
+				onDeprecated,
+				"SAML_DEPRECATED_CONFIG_ALGORITHM",
+			);
+		} else if (!SECURE_SIGNATURE_ALGORITHMS.includes(normalized)) {
+			throw new APIError("BAD_REQUEST", {
+				message: `SAML signature algorithm not recognized: ${config.signatureAlgorithm}`,
+				code: "SAML_UNKNOWN_ALGORITHM",
+			});
+		}
+	}
+
+	if (config.digestAlgorithm) {
+		const normalized = normalizeDigestAlgorithm(config.digestAlgorithm);
+		if (allowedDigestAlgorithms) {
+			const normalizedAllowList = allowedDigestAlgorithms.map(
+				normalizeDigestAlgorithm,
+			);
+			if (!normalizedAllowList.includes(normalized)) {
+				throw new APIError("BAD_REQUEST", {
+					message: `SAML digest algorithm not in allow-list: ${config.digestAlgorithm}`,
+					code: "SAML_ALGORITHM_NOT_ALLOWED",
+				});
+			}
+		} else if (DEPRECATED_DIGEST_ALGORITHMS.includes(normalized)) {
+			handleDeprecatedAlgorithm(
+				`SAML config uses deprecated digest algorithm: ${config.digestAlgorithm}. Consider using SHA-256 or stronger.`,
+				onDeprecated,
+				"SAML_DEPRECATED_CONFIG_ALGORITHM",
+			);
+		} else if (!SECURE_DIGEST_ALGORITHMS.includes(normalized)) {
+			throw new APIError("BAD_REQUEST", {
+				message: `SAML digest algorithm not recognized: ${config.digestAlgorithm}`,
+				code: "SAML_UNKNOWN_ALGORITHM",
+			});
+		}
+	}
+}

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

@@ -0,0 +1,13 @@
+export {
+	type AlgorithmValidationOptions,
+	type ConfigAlgorithmValidationOptions,
+	DataEncryptionAlgorithm,
+	type DeprecatedAlgorithmBehavior,
+	DigestAlgorithm,
+	KeyEncryptionAlgorithm,
+	SignatureAlgorithm,
+	validateConfigAlgorithms,
+	validateSAMLAlgorithms,
+} from "./algorithms";
+
+export { validateSingleAssertion } from "./assertions";