feat(auth): add native SAML 2.0 SSO integration

Add SAML 2.0 as a second SSO protocol alongside OIDC under a unified
authMode/ssoType model. SP flows via @node-saml/node-saml: AuthnRequest
generation, ACS POST assertion handling, SP metadata export, and admin
config test endpoint. Replay-protected via saml_state cookie (httpOnly,
SameSite=Lax) matched against InResponseTo; wantAssertionsSigned enforced.

- src/lib/auth/saml.js: SAML instance builder, X.509 cert formatter, claim pickers
- 4 routes under src/app/api/auth/saml/: start, acs, metadata, test
- settingsRepo: ssoType + saml* defaults; login/status routes dispatch by type
- profile page: SSO protocol switcher, IdP metadata XML + cert uploaders
- login page: dynamic SAML sign-in button; Header: SAML user badge

tests/auth/saml.test.js

@@ -0,0 +1,40 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  formatX509Certificate,
+  isSamlConfigured,
+  generateSamlMetadata,
+  pickSamlEmail,
+  pickSamlDisplayName,
+} from "../../src/lib/auth/saml.js";
+
+test("formatX509Certificate normalizes Base64 strings into PEM blocks", () => {
+  const rawBase64 = "MIIC1234567890123456789012345678901234567890123456789012345678901234567890";
+  const formatted = formatX509Certificate(rawBase64);
+  assert.match(formatted, /-----BEGIN CERTIFICATE-----/);
+  assert.match(formatted, /-----END CERTIFICATE-----/);
+  assert.equal(formatX509Certificate(""), "");
+});
+
+test("isSamlConfigured checks required fields", () => {
+  assert.equal(isSamlConfigured({ samlEntryPoint: "https://idp.com/sso", samlCert: "cert" }), true);
+  assert.equal(isSamlConfigured({ samlEntryPoint: "https://idp.com/sso" }), false);
+  assert.equal(isSamlConfigured({}), false);
+});
+
+test("generateSamlMetadata produces valid SP XML", () => {
+  const settings = {
+    samlEntryPoint: "https://idp.example.com/sso",
+    samlIssuer: "urn:9router:sp",
+    samlCert: "MIIC123456789012345678901234567890123456789012345678901234567890",
+  };
+  const xml = generateSamlMetadata("https://localhost:20127", settings);
+  assert.match(xml, /entityID="urn:9router:sp"/);
+  assert.match(xml, /Location="https:\/\/localhost:20127\/api\/auth\/saml\/acs"/);
+});
+
+test("Claims Extraction pickSamlEmail & pickSamlDisplayName", () => {
+  const profile = { email: "test@example.com", name: "Test User" };
+  assert.equal(pickSamlEmail(profile, {}), "test@example.com");
+  assert.equal(pickSamlDisplayName(profile, {}), "Test User");
+});

tests/unit/saml.test.js

@@ -0,0 +1,144 @@
+import { describe, it, expect } from "vitest";
+import {
+  formatX509Certificate,
+  isSamlConfigured,
+  generateSamlMetadata,
+  pickSamlEmail,
+  pickSamlDisplayName,
+  validateSamlResponse,
+} from "../../src/lib/auth/saml.js";
+import { mergeWithDefaults } from "../../src/lib/db/repos/settingsRepo.js";
+
+describe("SAML 2.0 Auth Engine Utilities", () => {
+  describe("formatX509Certificate", () => {
+    it("formats raw Base64 string into standard 64-column PEM block", () => {
+      const rawBase64 = "MIIC1234567890123456789012345678901234567890123456789012345678901234567890";
+      const formatted = formatX509Certificate(rawBase64);
+      expect(formatted).toContain("-----BEGIN CERTIFICATE-----");
+      expect(formatted).toContain("-----END CERTIFICATE-----");
+      expect(formatted).toContain("MIIC123456789012345678901234567890123456789012345678901234567890");
+      expect(formatted).toContain("\n1234567890\n");
+    });
+
+    it("cleans existing PEM header/footer and extra whitespace", () => {
+      const rawPem = `
+        -----BEGIN CERTIFICATE-----
+        MIIC123456789012345678901234567890123456789012345678901234567890
+        1234567890
+        -----END CERTIFICATE-----
+      `;
+      const formatted = formatX509Certificate(rawPem);
+      expect(formatted).toContain("-----BEGIN CERTIFICATE-----");
+      expect(formatted.match(/BEGIN CERTIFICATE/g)?.length).toBe(1);
+    });
+
+    it("returns empty string for null, undefined, or invalid inputs", () => {
+      expect(formatX509Certificate(null)).toBe("");
+      expect(formatX509Certificate(undefined)).toBe("");
+      expect(formatX509Certificate("   ")).toBe("");
+    });
+  });
+
+  describe("isSamlConfigured", () => {
+    it("returns true when entryPoint and cert are non-empty", () => {
+      expect(
+        isSamlConfigured({
+          samlEntryPoint: "https://idp.example.com/sso",
+          samlCert: "dummy-cert",
+        })
+      ).toBe(true);
+    });
+
+    it("returns false if entryPoint or cert is missing", () => {
+      expect(isSamlConfigured({ samlEntryPoint: "https://idp.example.com/sso" })).toBe(false);
+      expect(isSamlConfigured({ samlCert: "dummy-cert" })).toBe(false);
+      expect(isSamlConfigured({})).toBe(false);
+    });
+  });
+
+  describe("generateSamlMetadata", () => {
+    it("generates valid SP XML metadata with Entity ID and ACS binding", () => {
+      const settings = {
+        samlEntryPoint: "https://idp.example.com/sso",
+        samlIssuer: "urn:9router:sp",
+        samlCert: "MIIC123456789012345678901234567890123456789012345678901234567890",
+      };
+      const xml = generateSamlMetadata("https://localhost:20127", settings);
+      expect(xml).toContain('entityID="urn:9router:sp"');
+      expect(xml).toContain('Location="https://localhost:20127/api/auth/saml/acs"');
+      expect(xml).toContain('WantAssertionsSigned="true"');
+    });
+  });
+
+  describe("InResponseTo Replay Validation", () => {
+    it("throws error when expectedRequestId is supplied but InResponseTo is missing", async () => {
+      const settings = { samlCert: "dummy-cert" };
+      const rawXml = Buffer.from('<Response ID="123"></Response>').toString("base64");
+      await expect(
+        validateSamlResponse(null, { SAMLResponse: rawXml }, "req-123", settings)
+      ).rejects.toThrow(/InResponseTo mismatch/);
+    });
+
+    it("throws error when expectedRequestId is supplied but InResponseTo does not match", async () => {
+      const settings = { samlCert: "dummy-cert" };
+      const rawXml = Buffer.from('<Response InResponseTo="wrong-id"></Response>').toString("base64");
+      await expect(
+        validateSamlResponse(null, { SAMLResponse: rawXml }, "req-123", settings)
+      ).rejects.toThrow(/InResponseTo mismatch/);
+    });
+
+    it("throws error if samlCert is not configured", async () => {
+      const rawXml = Buffer.from('<Response ID="123"></Response>').toString("base64");
+      await expect(
+        validateSamlResponse(null, { SAMLResponse: rawXml }, "req-123", {})
+      ).rejects.toThrow(/Certificate/);
+    });
+  });
+
+  describe("Claims Extraction", () => {
+    const mockProfile = {
+      email: "user@example.com",
+      displayName: "Jane Doe",
+      "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress": ["custom@example.com"],
+      customEmail: "custom-email@example.com",
+      customName: "Custom User",
+    };
+
+    it("pickSamlEmail extracts custom attribute or common claims", () => {
+      expect(pickSamlEmail(mockProfile, {})).toBe("user@example.com");
+      expect(
+        pickSamlEmail(mockProfile, { samlAttributeEmail: "customEmail" })
+      ).toBe("custom-email@example.com");
+      expect(
+        pickSamlEmail(
+          { "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress": ["custom@example.com"] },
+          {}
+        )
+      ).toBe("custom@example.com");
+    });
+
+    it("pickSamlDisplayName extracts custom attribute, common names, or falls back to email", () => {
+      expect(pickSamlDisplayName(mockProfile, {})).toBe("Jane Doe");
+      expect(
+        pickSamlDisplayName(mockProfile, { samlAttributeName: "customName" })
+      ).toBe("Custom User");
+      expect(
+        pickSamlDisplayName({ email: "user@example.com" }, {})
+      ).toBe("user@example.com");
+      expect(
+        pickSamlDisplayName({ givenName: "Alice", surname: "Smith" }, {})
+      ).toBe("Alice Smith");
+    });
+  });
+
+  describe("Settings Repository Defaults", () => {
+    it("mergeWithDefaults safely populates SAML defaults for existing installations", () => {
+      const merged = mergeWithDefaults({ authMode: "password" });
+      expect(merged.ssoType).toBe("oidc");
+      expect(merged.samlIssuer).toBe("urn:9router:sp");
+      expect(merged.samlLoginLabel).toBe("Sign in with SAML SSO");
+      expect(merged.samlAttributeEmail).toBe("email");
+      expect(merged.samlAttributeName).toBe("name");
+    });
+  });
+});