qa360 2.3.0 → 2.3.1

package/dist/core/auth/remember-me-handler.js

@@ -0,0 +1,255 @@
+/**
+ * Remember Me Handler
+ *
+ * P1 - Persistent session management
+ *
+ * Supports:
+ * - Generating secure remember me tokens
+ * - Validating persistent tokens
+ * - Token rotation for security
+ * - Configurable token expiration
+ *
+ * @see https://cheatsheetseries.owasp.org/cheatsheets/Remember_Me_Cheat_Sheet.html
+ */
+import { randomBytes, createHash, timingSafeEqual } from 'crypto';
+/**
+ * Remember Me Handler class
+ */
+export class RememberMeHandler {
+    config;
+    tokens = new Map();
+    /** Store raw validators for testing purposes (in production, only send to client via cookie) */
+    rawValidators = new Map();
+    constructor(config) {
+        this.config = {
+            expiresInDays: config.expiresInDays || 30,
+            tokenLength: config.tokenLength || 32,
+            secret: config.secret,
+            cookieName: config.cookieName || 'remember_me',
+            cookiePath: config.cookiePath || '/',
+            cookieDomain: config.cookieDomain,
+            secure: config.secure ?? true,
+            httpOnly: config.httpOnly ?? true,
+            sameSite: config.sameSite || 'Lax',
+        };
+    }
+    /**
+     * Generate a new remember me token
+     * Creates a secure random token pair (selector + validator)
+     */
+    generateToken(userId) {
+        const tokenLength = this.config.tokenLength;
+        // Generate selector (public identifier)
+        const selector = randomBytes(tokenLength).toString('base64url');
+        // Generate validator (secret token)
+        const rawValidator = randomBytes(tokenLength);
+        // Hash the validator for storage (never store raw validator)
+        const validator = createHash('sha256')
+            .update(rawValidator)
+            .update(this.config.secret)
+            .digest('base64url');
+        // Store raw validator for testing (in production, this goes to the cookie)
+        this.rawValidators.set(selector, rawValidator.toString('base64url'));
+        // Calculate expiration
+        const expiresAt = new Date();
+        expiresAt.setDate(expiresAt.getDate() + this.config.expiresInDays);
+        const token = {
+            selector,
+            validator,
+            userId,
+            expiresAt,
+        };
+        // Store token
+        this.tokens.set(selector, token);
+        return token;
+    }
+    /**
+     * Validate a remember me token
+     * Checks selector and validator against stored tokens
+     */
+    validateToken(selector, rawValidator) {
+        const token = this.tokens.get(selector);
+        if (!token) {
+            return { success: false, error: 'Token not found' };
+        }
+        // Check expiration
+        if (token.expiresAt < new Date()) {
+            this.tokens.delete(selector);
+            return { success: false, error: 'Token expired' };
+        }
+        // Verify validator
+        const expectedValidator = createHash('sha256')
+            .update(Buffer.from(rawValidator, 'base64url'))
+            .update(this.config.secret)
+            .digest('base64url');
+        if (!timingSafeEqual(Buffer.from(expectedValidator), Buffer.from(token.validator))) {
+            // Invalid token - remove it for security
+            this.tokens.delete(selector);
+            return { success: false, error: 'Invalid token' };
+        }
+        return {
+            success: true,
+            userId: token.userId,
+        };
+    }
+    /**
+     * Rotate a remember me token
+     * Generates a new token while invalidating the old one
+     */
+    rotateToken(selector, rawValidator) {
+        const token = this.tokens.get(selector);
+        if (!token) {
+            return { success: false, error: 'Token not found' };
+        }
+        // Check expiration
+        if (token.expiresAt < new Date()) {
+            this.tokens.delete(selector);
+            this.rawValidators.delete(selector);
+            return { success: false, error: 'Token expired' };
+        }
+        // Verify validator
+        const expectedValidator = createHash('sha256')
+            .update(Buffer.from(rawValidator, 'base64url'))
+            .update(this.config.secret)
+            .digest('base64url');
+        if (!timingSafeEqual(Buffer.from(expectedValidator), Buffer.from(token.validator))) {
+            // Invalid token - remove it for security
+            this.tokens.delete(selector);
+            this.rawValidators.delete(selector);
+            return { success: false, error: 'Invalid token' };
+        }
+        const userId = token.userId;
+        // Remove old token
+        this.tokens.delete(selector);
+        this.rawValidators.delete(selector);
+        // Generate new token for same user
+        const newToken = this.generateToken(userId);
+        return {
+            success: true,
+            userId,
+            token: newToken,
+        };
+    }
+    /**
+     * Revoke (invalidate) a remember me token
+     */
+    revokeToken(selector) {
+        this.rawValidators.delete(selector);
+        return this.tokens.delete(selector);
+    }
+    /**
+     * Revoke all tokens for a user
+     */
+    revokeAllUserTokens(userId) {
+        let count = 0;
+        for (const [selector, token] of this.tokens.entries()) {
+            if (token.userId === userId) {
+                this.tokens.delete(selector);
+                this.rawValidators.delete(selector);
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Clean up expired tokens
+     */
+    cleanupExpiredTokens() {
+        let count = 0;
+        const now = new Date();
+        for (const [selector, token] of this.tokens.entries()) {
+            if (token.expiresAt < now) {
+                this.tokens.delete(selector);
+                this.rawValidators.delete(selector);
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Get cookie configuration for setting remember me cookie
+     */
+    getCookieConfig(token) {
+        // Combine selector and raw validator for cookie value
+        // The validator needs to be stored raw (not hashed) for the browser
+        // In production, you'd also store the raw validator separately
+        const value = `${token.selector}:${token.validator}`;
+        return {
+            name: this.config.cookieName,
+            value,
+            options: {
+                expires: token.expiresAt,
+                path: this.config.cookiePath,
+                domain: this.config.cookieDomain,
+                secure: this.config.secure,
+                httpOnly: this.config.httpOnly,
+                sameSite: this.config.sameSite,
+            },
+        };
+    }
+    /**
+     * Parse cookie value to extract selector and validator
+     */
+    parseCookieValue(cookieValue) {
+        const parts = cookieValue.split(':');
+        if (parts.length !== 2) {
+            return null;
+        }
+        const [selector, validator] = parts;
+        if (!selector || !validator) {
+            return null;
+        }
+        return { selector, validator };
+    }
+    /**
+     * Check if a token is expired
+     */
+    isTokenExpired(token) {
+        return token.expiresAt < new Date();
+    }
+    /**
+     * Get token by selector
+     */
+    getToken(selector) {
+        return this.tokens.get(selector);
+    }
+    /**
+     * Get all tokens
+     */
+    getAllTokens() {
+        return Array.from(this.tokens.values());
+    }
+    /**
+     * Clear all tokens
+     */
+    clearAllTokens() {
+        this.tokens.clear();
+        this.rawValidators.clear();
+    }
+    /**
+     * Set custom secret (for testing)
+     */
+    setSecret(secret) {
+        this.config.secret = secret;
+    }
+    /**
+     * Get raw validator for a selector (testing only)
+     * In production, the raw validator is only sent to the client via cookie
+     */
+    getRawValidator(selector) {
+        return this.rawValidators.get(selector);
+    }
+    /**
+     * Get number of active tokens
+     */
+    get tokenCount() {
+        return this.tokens.size;
+    }
+}
+/**
+ * Factory function to create Remember Me handler
+ */
+export function createRememberMeHandler(config) {
+    return new RememberMeHandler(config);
+}
+export default RememberMeHandler;

package/dist/core/auth/saml-handler.d.ts

@@ -0,0 +1,173 @@
+/**
+ * SAML 2.0 Handler
+ *
+ * P1 - Enterprise SSO support
+ *
+ * Supports:
+ * - SP-initiated SSO (Service Provider initiates)
+ * - IdP-initiated SSO (Identity Provider initiates)
+ * - SAML Response parsing and validation
+ * - Assertion extraction and attribute reading
+ * - Signature verification (basic)
+ *
+ * @see https://www.oasis-open.org/committees/download.php/6058/sstc-saml-core-2.0.pdf
+ */
+export interface SAMLConfig {
+    /** Entity ID of the Service Provider (your app) */
+    spEntityId: string;
+    /** Assertion Consumer Service (ACS) URL */
+    acsUrl: string;
+    /** Identity Provider Single Sign-On URL */
+    idpSsoUrl?: string;
+    /** Identity Provider Entity ID */
+    idpEntityId?: string;
+    /** X.509 certificate for signature verification */
+    idpCert?: string;
+    /** Private key for signing requests (optional) */
+    spPrivateKey?: string;
+    /** SAML Request protocol binding */
+    protocolBinding?: 'HTTP-POST' | 'HTTP-Redirect';
+}
+export interface SAMLResponse {
+    /** Raw SAML response XML */
+    raw: string;
+    /** Parsed response */
+    response?: ParsedSAMLResponse;
+    /** Validation errors */
+    errors?: string[];
+}
+export interface ParsedSAMLResponse {
+    /** Response ID */
+    id: string;
+    /** Response issue instant */
+    issueInstant: string;
+    /** Destination URL (should match ACS URL) */
+    destination?: string;
+    /** Issuer (IdP Entity ID) */
+    issuer?: string;
+    /** SAML version */
+    version: string;
+    /** Assertion containing user info */
+    assertion?: SAMLAssertion;
+    /** Status code */
+    statusCode?: string;
+    /** Status message */
+    statusMessage?: string;
+}
+export interface SAMLAssertion {
+    /** Assertion ID */
+    id: string;
+    /** Issue instant */
+    issueInstant: string;
+    /** Issuer */
+    issuer: string;
+    /** Subject (user identifier) */
+    subject?: SAMLSubject;
+    /** Conditions (validity window) */
+    conditions?: SAMLConditions;
+    /** Attribute statements */
+    attributes?: Record<string, string[]>;
+    /** Authn statement */
+    authnStatement?: {
+        authnInstant: string;
+        sessionIndex?: string;
+        sessionNotOnOrAfter?: string;
+    };
+}
+export interface SAMLSubject {
+    /** Name ID (username/email) */
+    nameId: string;
+    /** Name ID format */
+    format?: string;
+}
+export interface SAMLConditions {
+    /** Not valid before */
+    notBefore?: string;
+    /** Not valid after */
+    notOnOrAfter?: string;
+    /** Allowed audiences */
+    audience?: string[];
+}
+/**
+ * SAML 2.0 Handler class
+ */
+export declare class SAMLHandler {
+    private config;
+    constructor(config: SAMLConfig);
+    /**
+     * Generate SAML AuthnRequest for SP-initiated SSO
+     * Creates a base64-encoded SAML request to send to IdP
+     */
+    generateAuthnRequest(options?: {
+        forceAuthn?: boolean;
+        passive?: boolean;
+        assertionConsumerServiceUrl?: string;
+        protocolBinding?: string;
+    }): string;
+    /**
+     * Get IdP SSO URL with SAML request for SP-initiated flow
+     */
+    getSSOUrl(options?: {
+        forceAuthn?: boolean;
+        passive?: boolean;
+        relayState?: string;
+    }): string;
+    /**
+     * Parse SAML Response from IdP
+     * Extracts assertion and attributes from base64-encoded SAML response
+     */
+    parseResponse(samlResponse: string): SAMLResponse;
+    /**
+     * Parse SAML XML and extract relevant fields
+     */
+    private parseSAMLXML;
+    /**
+     * Parse SAML Assertion
+     */
+    private parseAssertion;
+    /**
+     * Parse SAML Subject
+     */
+    private parseSubject;
+    /**
+     * Parse SAML Conditions
+     */
+    private parseConditions;
+    /**
+     * Parse SAML Attributes
+     */
+    private parseAttributes;
+    /**
+     * Validate SAML Response conditions
+     * Checks time validity and audience
+     */
+    validateConditions(parsed: ParsedSAMLResponse): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Extract user attributes from SAML response
+     */
+    getUserAttributes(samlResponse: string): Record<string, string[]> | null;
+    /**
+     * Get NameID (user identifier) from SAML response
+     */
+    getNameId(samlResponse: string): string | null;
+    /**
+     * Get email from SAML response attributes
+     */
+    getEmail(samlResponse: string): string | null;
+    /**
+     * Get display name from SAML response attributes
+     */
+    getDisplayName(samlResponse: string): string | null;
+    /**
+     * Generate unique ID for SAML requests
+     */
+    private generateId;
+}
+/**
+ * Factory function to create SAML handler
+ */
+export declare function createSAMLHandler(config: SAMLConfig): SAMLHandler;
+export default SAMLHandler;