@revealui/auth 0.5.0 → 0.5.1

package/dist/server/sso/saml.js

@@ -0,0 +1,392 @@
+/**
+ * Enterprise SAML 2.0 SP helpers (GAP-464 Phase 3).
+ *
+ * Wraps @node-saml/node-saml so HTTP routes get typed ok/err results matching
+ * the OIDC pure layer. Hardlines:
+ * - Never accept a Response without IdP certificate material (signature path).
+ * - SP-initiated AuthnRequest only for MVP (IdP-initiated is a follow-up).
+ * - InResponseTo checked when present (replay resistance).
+ */
+import { SAML, ValidateInResponseTo } from '@node-saml/node-saml';
+// ---------------------------------------------------------------------------
+// PEM helpers
+// ---------------------------------------------------------------------------
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/**
+ * Normalize a certificate string to PEM CERTIFICATE block if bare base64.
+ */
+export function normalizeIdpCertPem(cert) {
+    const trimmed = cert.trim();
+    if (trimmed.includes('BEGIN CERTIFICATE') || trimmed.includes('BEGIN PUBLIC KEY')) {
+        return trimmed;
+    }
+    // Strip whitespace from bare base64
+    let compact = '';
+    for (const ch of trimmed) {
+        if (ch !== ' ' && ch !== '\n' && ch !== '\r' && ch !== '\t') {
+            compact += ch;
+        }
+    }
+    const lines = [];
+    for (let i = 0; i < compact.length; i += 64) {
+        lines.push(compact.slice(i, i + 64));
+    }
+    return `-----BEGIN CERTIFICATE-----\n${lines.join('\n')}\n-----END CERTIFICATE-----`;
+}
+// ---------------------------------------------------------------------------
+// IdP metadata parse (string scans; no authored regex)
+// ---------------------------------------------------------------------------
+function extractXmlAttribute(xml, tagHint, attrName) {
+    // Find a tag containing tagHint, then attrName="..."
+    let searchFrom = 0;
+    while (searchFrom < xml.length) {
+        const tagStart = xml.indexOf('<', searchFrom);
+        if (tagStart === -1)
+            return null;
+        const tagEnd = xml.indexOf('>', tagStart);
+        if (tagEnd === -1)
+            return null;
+        const tag = xml.slice(tagStart, tagEnd + 1);
+        if (tag.includes(tagHint) && !tag.startsWith('</') && !tag.startsWith('<!--')) {
+            const attrKey = `${attrName}="`;
+            const attrPos = tag.indexOf(attrKey);
+            if (attrPos !== -1) {
+                const valueStart = attrPos + attrKey.length;
+                const valueEnd = tag.indexOf('"', valueStart);
+                if (valueEnd !== -1) {
+                    return tag.slice(valueStart, valueEnd);
+                }
+            }
+        }
+        searchFrom = tagEnd + 1;
+    }
+    return null;
+}
+function extractFirstX509Certificate(xml) {
+    const open = '<X509Certificate>';
+    const openAlt = '<ds:X509Certificate>';
+    let start = xml.indexOf(open);
+    let openLen = open.length;
+    if (start === -1) {
+        start = xml.indexOf(openAlt);
+        openLen = openAlt.length;
+    }
+    if (start === -1)
+        return null;
+    const contentStart = start + openLen;
+    const close = xml.indexOf('</', contentStart);
+    if (close === -1)
+        return null;
+    return xml.slice(contentStart, close).trim();
+}
+function extractSsoLocation(xml) {
+    // Prefer HTTP-Redirect SingleSignOnService Location
+    let searchFrom = 0;
+    let fallback = null;
+    while (searchFrom < xml.length) {
+        const tagStart = xml.indexOf('SingleSignOnService', searchFrom);
+        if (tagStart === -1)
+            break;
+        // Walk back to '<'
+        let open = tagStart;
+        while (open > 0 && xml[open] !== '<')
+            open--;
+        const tagEnd = xml.indexOf('>', tagStart);
+        if (tagEnd === -1)
+            break;
+        const tag = xml.slice(open, tagEnd + 1);
+        const bindingKey = 'Binding="';
+        const locKey = 'Location="';
+        const bindingPos = tag.indexOf(bindingKey);
+        const locPos = tag.indexOf(locKey);
+        if (locPos !== -1) {
+            const valueStart = locPos + locKey.length;
+            const valueEnd = tag.indexOf('"', valueStart);
+            if (valueEnd !== -1) {
+                const location = tag.slice(valueStart, valueEnd);
+                if (bindingPos !== -1) {
+                    const bStart = bindingPos + bindingKey.length;
+                    const bEnd = tag.indexOf('"', bStart);
+                    const binding = bEnd !== -1 ? tag.slice(bStart, bEnd) : '';
+                    if (binding.includes('HTTP-Redirect')) {
+                        return location;
+                    }
+                    if (!fallback)
+                        fallback = location;
+                }
+                else if (!fallback) {
+                    fallback = location;
+                }
+            }
+        }
+        searchFrom = tagEnd + 1;
+    }
+    return fallback;
+}
+/**
+ * Parse IdP metadata XML for entityID, SSO entry point, and signing cert.
+ * Uses linear string scans (no authored regex) for CodeQL / no-regex hardline.
+ */
+export function parseIdpMetadataXml(xml) {
+    if (!isNonEmptyString(xml)) {
+        return { ok: false, reason: 'missing_xml', message: 'IdP metadata XML is required' };
+    }
+    const entityId = extractXmlAttribute(xml, 'EntityDescriptor', 'entityID') ||
+        extractXmlAttribute(xml, 'md:EntityDescriptor', 'entityID');
+    if (!entityId) {
+        return {
+            ok: false,
+            reason: 'missing_entity_id',
+            message: 'IdP metadata missing EntityDescriptor entityID',
+        };
+    }
+    const entryPoint = extractSsoLocation(xml);
+    if (!entryPoint) {
+        return {
+            ok: false,
+            reason: 'missing_sso_url',
+            message: 'IdP metadata missing SingleSignOnService Location',
+        };
+    }
+    const rawCert = extractFirstX509Certificate(xml);
+    if (!rawCert) {
+        return {
+            ok: false,
+            reason: 'missing_cert',
+            message: 'IdP metadata missing X509Certificate',
+        };
+    }
+    return {
+        ok: true,
+        entityId,
+        entryPoint,
+        idpCertPem: normalizeIdpCertPem(rawCert),
+    };
+}
+// ---------------------------------------------------------------------------
+// SAML service construction
+// ---------------------------------------------------------------------------
+function createSamlInstance(config) {
+    const idpCert = normalizeIdpCertPem(config.idpCertPem);
+    const options = {
+        callbackUrl: config.callbackUrl,
+        entryPoint: config.entryPoint,
+        issuer: config.spEntityId,
+        idpCert,
+        audience: config.spEntityId,
+        wantAssertionsSigned: true,
+        wantAuthnResponseSigned: true,
+        validateInResponseTo: ValidateInResponseTo.ifPresent,
+        acceptedClockSkewMs: config.acceptedClockSkewMs ?? 5 * 60 * 1000,
+        identifierFormat: 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
+    };
+    if (config.spPrivateKeyPem) {
+        options.privateKey = config.spPrivateKeyPem;
+    }
+    if (config.spPublicCertPem) {
+        options.publicCert = config.spPublicCertPem;
+    }
+    return new SAML(options);
+}
+// ---------------------------------------------------------------------------
+// SP metadata + AuthnRequest redirect
+// ---------------------------------------------------------------------------
+/**
+ * Generate SP metadata XML for customer IdP configuration.
+ */
+export function buildSamlSpMetadata(config) {
+    if (!isNonEmptyString(config.idpCertPem)) {
+        throw new Error('idpCertPem is required to construct SP metadata service');
+    }
+    const saml = createSamlInstance(config);
+    // decryptionCert null when no encryption; publicCert optional for signing
+    return saml.generateServiceProviderMetadata(null, config.spPublicCertPem ? config.spPublicCertPem : null);
+}
+/**
+ * Build SP-initiated AuthnRequest redirect URL (HTTP-Redirect binding).
+ * `relayState` should be the signed SSO state token (CSRF + account binding).
+ */
+export async function buildSamlAuthorizeUrl(config, relayState) {
+    if (!(isNonEmptyString(config.callbackUrl) && isNonEmptyString(config.entryPoint))) {
+        return {
+            ok: false,
+            reason: 'missing_config',
+            message: 'callbackUrl and entryPoint are required',
+        };
+    }
+    if (!isNonEmptyString(config.idpCertPem)) {
+        return {
+            ok: false,
+            reason: 'missing_cert',
+            message: 'IdP signing certificate is required',
+        };
+    }
+    if (!isNonEmptyString(config.spEntityId)) {
+        return {
+            ok: false,
+            reason: 'missing_config',
+            message: 'spEntityId is required',
+        };
+    }
+    try {
+        const saml = createSamlInstance(config);
+        const url = await saml.getAuthorizeUrlAsync(relayState, undefined, {});
+        return { ok: true, url };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: 'build_failed',
+            message: err instanceof Error ? err.message : 'Failed to build SAML AuthnRequest URL',
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Response validation
+// ---------------------------------------------------------------------------
+function mapValidateError(err) {
+    const message = err instanceof Error ? err.message : 'SAML response validation failed';
+    const lower = message.toLowerCase();
+    if (lower.includes('signature') || lower.includes('invalid document')) {
+        return { reason: 'invalid_signature', message };
+    }
+    if (lower.includes('expired') || lower.includes('notonorafter') || lower.includes('not before')) {
+        return { reason: 'expired', message };
+    }
+    if (lower.includes('audience')) {
+        return { reason: 'audience_mismatch', message };
+    }
+    if (lower.includes('inresponseto') || lower.includes('replay')) {
+        return { reason: 'replay', message };
+    }
+    return { reason: 'validation_failed', message };
+}
+function profileToAssertion(profile) {
+    const subject = typeof profile.nameID === 'string' ? profile.nameID.trim() : '';
+    if (!subject)
+        return null;
+    const attributes = {};
+    // Profile is a claim bag ([attributeName: string]: unknown) plus fixed fields
+    for (const [key, value] of Object.entries(profile)) {
+        if (key === 'getAssertionXml' || key === 'getAssertion' || key === 'getSamlResponseXml') {
+            continue;
+        }
+        if (typeof value === 'function')
+            continue;
+        attributes[key] = value;
+    }
+    if (typeof profile.email === 'string') {
+        attributes.email = profile.email;
+    }
+    const msGroups = profile['http://schemas.microsoft.com/ws/2008/06/identity/claims/groups'];
+    if (Array.isArray(msGroups)) {
+        attributes.groups = msGroups;
+    }
+    if (typeof profile.mail === 'string') {
+        attributes.mail = profile.mail;
+    }
+    const email = (typeof profile.email === 'string' && profile.email) ||
+        (typeof profile.mail === 'string' && profile.mail) ||
+        (subject.includes('@') ? subject : undefined);
+    const displayName = profile.displayName;
+    const cn = profile.cn;
+    const name = (typeof displayName === 'string' && displayName) || (typeof cn === 'string' && cn) || undefined;
+    return {
+        subject,
+        email,
+        name,
+        attributes,
+        profile,
+    };
+}
+/**
+ * Validate a SAMLResponse from HTTP-POST binding.
+ * Requires IdP cert; rejects unsigned / bad-signature responses.
+ */
+export async function validateSamlPostResponse(config, samlResponseBase64) {
+    if (!isNonEmptyString(samlResponseBase64)) {
+        return {
+            ok: false,
+            reason: 'missing_response',
+            message: 'SAMLResponse is required',
+        };
+    }
+    if (!isNonEmptyString(config.idpCertPem)) {
+        return {
+            ok: false,
+            reason: 'missing_cert',
+            message: 'IdP signing certificate is required; unsigned responses are rejected',
+        };
+    }
+    try {
+        const saml = createSamlInstance(config);
+        const { profile, loggedOut } = await saml.validatePostResponseAsync({
+            SAMLResponse: samlResponseBase64,
+        });
+        if (loggedOut) {
+            return {
+                ok: false,
+                reason: 'logged_out',
+                message: 'SAML response was a logout response',
+            };
+        }
+        if (!profile) {
+            return {
+                ok: false,
+                reason: 'validation_failed',
+                message: 'SAML validation returned no profile',
+            };
+        }
+        const assertion = profileToAssertion(profile);
+        if (!assertion) {
+            return {
+                ok: false,
+                reason: 'missing_name_id',
+                message: 'SAML assertion missing NameID / subject',
+            };
+        }
+        return { ok: true, assertion };
+    }
+    catch (err) {
+        const mapped = mapValidateError(err);
+        return { ok: false, reason: mapped.reason, message: mapped.message };
+    }
+}
+/**
+ * Fetch and parse IdP metadata from a URL (test-connection + seed entryPoint/cert).
+ */
+export async function fetchIdpMetadata(metadataUrl, options) {
+    if (!isNonEmptyString(metadataUrl)) {
+        return { ok: false, reason: 'missing_xml', message: 'metadata URL is required' };
+    }
+    const fetchImpl = options?.fetchImpl ?? fetch;
+    const timeoutMs = options?.timeoutMs ?? 10_000;
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetchImpl(metadataUrl, { signal: controller.signal });
+            if (!res.ok) {
+                return {
+                    ok: false,
+                    reason: 'missing_xml',
+                    message: `IdP metadata fetch failed with HTTP ${res.status}`,
+                };
+            }
+            const text = await res.text();
+            return parseIdpMetadataXml(text);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: 'missing_xml',
+            message: err instanceof Error ? err.message : 'IdP metadata fetch failed',
+        };
+    }
+}

package/dist/server/sso/state.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Enterprise SSO signed state cookie (GAP-464).
+ *
+ * Separate from social OAuth generateOAuthState / verifyOAuthState so enterprise
+ * IdP bindings (accountId + providerId + PKCE) never overload provider enums.
+ *
+ * Cookie value: `<state>.<hmac-hex>` where state is base64url(JSON payload)
+ * and HMAC-SHA256 is over the state string using REVEALUI_SECRET.
+ */
+export interface SsoStatePayload {
+    accountId: string;
+    providerId: string;
+    redirectTo: string;
+    nonce: string;
+    codeVerifier: string;
+}
+export interface GenerateSsoStateInput {
+    accountId: string;
+    providerId: string;
+    redirectTo: string;
+}
+export interface GenerateSsoStateResult {
+    /** Opaque state query param sent to the IdP */
+    state: string;
+    /** Value for the httpOnly SSO state cookie (`state.hmac`) */
+    cookieValue: string;
+    /** S256 PKCE code_challenge for the authorization request */
+    codeChallenge: string;
+}
+export interface VerifiedSsoState {
+    accountId: string;
+    providerId: string;
+    redirectTo: string;
+    nonce: string;
+    codeVerifier: string;
+}
+/**
+ * Generate a signed SSO state token with PKCE verifier.
+ */
+export declare function generateSsoState(input: GenerateSsoStateInput): GenerateSsoStateResult;
+/**
+ * Verify a signed SSO state token from the callback.
+ * Returns null on any integrity / shape failure (does not throw for bad input).
+ */
+export declare function verifySsoState(state: string | null | undefined, cookieValue: string | null | undefined): VerifiedSsoState | null;
+//# sourceMappingURL=state.d.ts.map

package/dist/server/sso/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/server/sso/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB;AAaD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,sBAAsB,CA2BrF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC,gBAAgB,GAAG,IAAI,CAyDzB"}

package/dist/server/sso/state.js

@@ -0,0 +1,101 @@
+/**
+ * Enterprise SSO signed state cookie (GAP-464).
+ *
+ * Separate from social OAuth generateOAuthState / verifyOAuthState so enterprise
+ * IdP bindings (accountId + providerId + PKCE) never overload provider enums.
+ *
+ * Cookie value: `<state>.<hmac-hex>` where state is base64url(JSON payload)
+ * and HMAC-SHA256 is over the state string using REVEALUI_SECRET.
+ */
+import crypto from 'node:crypto';
+function requireSecret() {
+    const secret = process.env.REVEALUI_SECRET;
+    if (!secret) {
+        throw new Error('REVEALUI_SECRET is required for SSO state signing. ' +
+            'Set it in your environment variables.');
+    }
+    return secret;
+}
+/**
+ * Generate a signed SSO state token with PKCE verifier.
+ */
+export function generateSsoState(input) {
+    const { accountId, providerId, redirectTo } = input;
+    if (!(accountId && providerId)) {
+        throw new Error('accountId and providerId are required for SSO state');
+    }
+    const nonce = crypto.randomBytes(16).toString('hex');
+    const codeVerifier = crypto.randomBytes(32).toString('base64url');
+    const codeChallenge = crypto.createHash('sha256').update(codeVerifier).digest('base64url');
+    const payload = {
+        accountId,
+        providerId,
+        redirectTo,
+        nonce,
+        codeVerifier,
+    };
+    const state = Buffer.from(JSON.stringify(payload)).toString('base64url');
+    const secret = requireSecret();
+    // lgtm[js/insufficient-password-hash] - HMAC-SHA256 for SSO CSRF state, not password hashing
+    const hmac = crypto.createHmac('sha256', secret).update(state).digest('hex');
+    return {
+        state,
+        cookieValue: `${state}.${hmac}`,
+        codeChallenge,
+    };
+}
+/**
+ * Verify a signed SSO state token from the callback.
+ * Returns null on any integrity / shape failure (does not throw for bad input).
+ */
+export function verifySsoState(state, cookieValue) {
+    if (!(state && cookieValue))
+        return null;
+    const dotIdx = cookieValue.lastIndexOf('.');
+    if (dotIdx === -1)
+        return null;
+    const storedState = cookieValue.substring(0, dotIdx);
+    const storedHmac = cookieValue.substring(dotIdx + 1);
+    if (storedState.length !== state.length ||
+        !crypto.timingSafeEqual(Buffer.from(storedState), Buffer.from(state))) {
+        return null;
+    }
+    const secret = requireSecret();
+    // lgtm[js/insufficient-password-hash] - HMAC-SHA256 for SSO CSRF state, not password hashing
+    const expectedHmac = crypto.createHmac('sha256', secret).update(state).digest('hex');
+    // Both are hex-encoded SHA-256 HMACs — must be exactly 64 hex characters.
+    if (storedHmac.length !== 64 || expectedHmac.length !== 64)
+        return null;
+    try {
+        if (!crypto.timingSafeEqual(Buffer.from(storedHmac, 'hex'), Buffer.from(expectedHmac, 'hex'))) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(Buffer.from(state, 'base64url').toString());
+        if (typeof parsed.accountId !== 'string' ||
+            typeof parsed.providerId !== 'string' ||
+            typeof parsed.redirectTo !== 'string' ||
+            typeof parsed.nonce !== 'string' ||
+            typeof parsed.codeVerifier !== 'string' ||
+            !parsed.accountId ||
+            !parsed.providerId ||
+            !parsed.nonce ||
+            !parsed.codeVerifier) {
+            return null;
+        }
+        return {
+            accountId: parsed.accountId,
+            providerId: parsed.providerId,
+            redirectTo: parsed.redirectTo,
+            nonce: parsed.nonce,
+            codeVerifier: parsed.codeVerifier,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revealui/auth",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Database-backed session auth for Hono and Next.js — bcrypt, OAuth, brute-force protection, rate limiting, password reset. Ships with RevealUI.",
   "keywords": [
     "auth",
@@ -10,15 +10,17 @@
   ],
   "license": "MIT",
   "dependencies": {
+    "@node-saml/node-saml": "5.1.0",
     "@simplewebauthn/server": "^13.3.2",
     "bcryptjs": "^3.0.3",
     "drizzle-orm": "^0.45.2",
+    "jose": "^5.10.0",
     "zod": "^4.4.3",
     "@revealui/config": "0.6.0",
-    "@revealui/contracts": "0.8.1",
-    "@revealui/core": "0.12.2",
+    "@revealui/contracts": "0.8.2",
+    "@revealui/core": "0.12.4",
     "@revealui/db": "0.10.0",
-    "@revealui/security": "0.6.0"
+    "@revealui/security": "0.6.1"
   },
   "devDependencies": {
     "@simplewebauthn/browser": "^13.3.0",
@@ -27,9 +29,11 @@
     "@types/react": "^19.2.17",
     "@vitest/coverage-v8": "^4.1.10",
     "happy-dom": "^20.10.6",
-    "react": "^19.2.7",
+    "react": "19.2.8",
+    "selfsigned": "2.4.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
+    "xml-crypto": "6.1.2",
     "@revealui/dev": "0.1.0"
   },
   "engines": {