@better-auth/sso 1.5.0-beta.1 → 1.5.0-beta.10

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-state.ts

@@ -0,0 +1,78 @@
+import type { GenericEndpointContext, StateData } from "better-auth";
+import { generateGenericState, parseGenericState } from "better-auth";
+import { generateRandomString } from "better-auth/crypto";
+import { APIError } from "better-call";
+
+export async function generateRelayState(
+	c: GenericEndpointContext,
+	link:
+		| {
+				email: string;
+				userId: string;
+		  }
+		| undefined,
+	additionalData: Record<string, any> | false | undefined,
+) {
+	const callbackURL = c.body.callbackURL;
+	if (!callbackURL) {
+		throw new APIError("BAD_REQUEST", {
+			message: "callbackURL is required",
+		});
+	}
+
+	const codeVerifier = generateRandomString(128);
+	const stateData: StateData = {
+		...(additionalData ? additionalData : {}),
+		callbackURL,
+		codeVerifier,
+		errorURL: c.body.errorCallbackURL,
+		newUserURL: c.body.newUserCallbackURL,
+		link,
+		/**
+		 * This is the actual expiry time of the state
+		 */
+		expiresAt: Date.now() + 10 * 60 * 1000,
+		requestSignUp: c.body.requestSignUp,
+	};
+
+	try {
+		return generateGenericState(c, stateData, {
+			cookieName: "relay_state",
+		});
+	} catch (error) {
+		c.context.logger.error(
+			"Failed to create verification for relay state",
+			error,
+		);
+		throw new APIError("INTERNAL_SERVER_ERROR", {
+			message: "State error: Unable to create verification for relay state",
+			cause: error,
+		});
+	}
+}
+
+export async function parseRelayState(c: GenericEndpointContext) {
+	const state = c.body.RelayState;
+	const errorURL =
+		c.context.options.onAPIError?.errorURL || `${c.context.baseURL}/error`;
+
+	let parsedData: StateData;
+
+	try {
+		parsedData = await parseGenericState(c, state, {
+			cookieName: "relay_state",
+		});
+	} catch (error) {
+		c.context.logger.error("Failed to parse relay state", error);
+		throw new APIError("BAD_REQUEST", {
+			message: "State error: failed to validate relay state",
+			cause: error,
+		});
+	}
+
+	if (!parsedData.errorURL) {
+		parsedData.errorURL = errorURL;
+	}
+
+	return parsedData;
+}