@flink-app/oidc-plugin 1.0.0

package/dist/schemas/OidcTokenSet.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/claims-mapper.d.ts

@@ -0,0 +1,46 @@
+import OidcProfile from "../schemas/OidcProfile";
+/**
+ * Map OIDC claims to normalized profile
+ *
+ * Extracts standard OIDC claims from the ID token and UserInfo response
+ * and maps them to a consistent profile structure.
+ *
+ * Standard OIDC claims reference:
+ * https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
+ *
+ * @param claims - OIDC claims from ID token and/or UserInfo endpoint
+ * @returns Normalized user profile
+ */
+export declare function mapClaimsToProfile(claims: Record<string, any>): OidcProfile;
+/**
+ * Extract custom claims using claim mapping configuration
+ *
+ * Allows extracting custom claims from the ID token using dot notation.
+ * Supports nested claim paths.
+ *
+ * @param claims - OIDC claims from ID token
+ * @param claimMapping - Map of field names to claim paths
+ * @returns Object with extracted custom claims
+ *
+ * Example:
+ * ```typescript
+ * const claims = {
+ *   sub: '123',
+ *   email: 'user@example.com',
+ *   'custom:department': 'Engineering',
+ *   'custom:role': 'Admin',
+ *   groups: ['engineers', 'admins']
+ * };
+ *
+ * const mapping = {
+ *   department: 'custom:department',
+ *   role: 'custom:role',
+ *   groups: 'groups'
+ * };
+ *
+ * const custom = extractCustomClaims(claims, mapping);
+ * // { department: 'Engineering', role: 'Admin', groups: ['engineers', 'admins'] }
+ * ```
+ */
+export declare function extractCustomClaims(claims: Record<string, any>, claimMapping: Record<string, string>): Record<string, any>;
+//# sourceMappingURL=claims-mapper.d.ts.map

package/dist/utils/claims-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims-mapper.d.ts","sourceRoot":"","sources":["../../src/utils/claims-mapper.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,wBAAwB,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,CA4B3E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAW1H"}

package/dist/utils/claims-mapper.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapClaimsToProfile = mapClaimsToProfile;
+exports.extractCustomClaims = extractCustomClaims;
+/**
+ * Map OIDC claims to normalized profile
+ *
+ * Extracts standard OIDC claims from the ID token and UserInfo response
+ * and maps them to a consistent profile structure.
+ *
+ * Standard OIDC claims reference:
+ * https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
+ *
+ * @param claims - OIDC claims from ID token and/or UserInfo endpoint
+ * @returns Normalized user profile
+ */
+function mapClaimsToProfile(claims) {
+    return {
+        // Required - subject identifier (unique user ID)
+        id: claims.sub,
+        // Email
+        email: claims.email,
+        emailVerified: claims.email_verified,
+        // Name fields
+        name: claims.name,
+        givenName: claims.given_name,
+        familyName: claims.family_name,
+        middleName: claims.middle_name,
+        // Username
+        username: claims.preferred_username || claims.username,
+        // Picture
+        picture: claims.picture,
+        // Phone
+        phoneNumber: claims.phone_number,
+        phoneNumberVerified: claims.phone_number_verified,
+        // Keep all raw claims for custom access
+        raw: claims,
+    };
+}
+/**
+ * Extract custom claims using claim mapping configuration
+ *
+ * Allows extracting custom claims from the ID token using dot notation.
+ * Supports nested claim paths.
+ *
+ * @param claims - OIDC claims from ID token
+ * @param claimMapping - Map of field names to claim paths
+ * @returns Object with extracted custom claims
+ *
+ * Example:
+ * ```typescript
+ * const claims = {
+ *   sub: '123',
+ *   email: 'user@example.com',
+ *   'custom:department': 'Engineering',
+ *   'custom:role': 'Admin',
+ *   groups: ['engineers', 'admins']
+ * };
+ *
+ * const mapping = {
+ *   department: 'custom:department',
+ *   role: 'custom:role',
+ *   groups: 'groups'
+ * };
+ *
+ * const custom = extractCustomClaims(claims, mapping);
+ * // { department: 'Engineering', role: 'Admin', groups: ['engineers', 'admins'] }
+ * ```
+ */
+function extractCustomClaims(claims, claimMapping) {
+    const customClaims = {};
+    for (const [fieldName, claimPath] of Object.entries(claimMapping)) {
+        const value = getClaimByPath(claims, claimPath);
+        if (value !== undefined) {
+            customClaims[fieldName] = value;
+        }
+    }
+    return customClaims;
+}
+/**
+ * Get claim value by path (supports dot notation)
+ *
+ * @param claims - Claims object
+ * @param path - Claim path (e.g., "custom:department" or "address.street_address")
+ * @returns Claim value or undefined if not found
+ */
+function getClaimByPath(claims, path) {
+    // Handle direct access first (for paths with colons like "custom:department")
+    if (path in claims) {
+        return claims[path];
+    }
+    // Handle nested paths with dot notation
+    const parts = path.split(".");
+    let value = claims;
+    for (const part of parts) {
+        if (value && typeof value === "object" && part in value) {
+            value = value[part];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return value;
+}

package/dist/utils/encryption-utils.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Validate encryption secret meets minimum requirements
+ *
+ * @param secret - Secret to validate
+ * @throws Error if secret is invalid
+ */
+export declare function validateEncryptionSecret(secret: string): void;
+/**
+ * Encrypt a token using AES-256-GCM
+ *
+ * Uses Galois/Counter Mode (GCM) which provides both confidentiality
+ * and authenticity (prevents tampering).
+ *
+ * Format: iv:authTag:encryptedData (all hex-encoded)
+ *
+ * @param token - Plain text token to encrypt
+ * @param secret - Encryption secret (at least 32 characters)
+ * @returns Encrypted token with IV and auth tag
+ */
+export declare function encryptToken(token: string, secret: string): string;
+/**
+ * Decrypt a token using AES-256-GCM
+ *
+ * Validates the auth tag to ensure the data hasn't been tampered with.
+ *
+ * @param encryptedToken - Encrypted token from encryptToken()
+ * @param secret - Encryption secret used during encryption
+ * @returns Decrypted plain text token
+ * @throws Error if decryption fails or auth tag is invalid
+ */
+export declare function decryptToken(encryptedToken: string, secret: string): string;
+//# sourceMappingURL=encryption-utils.d.ts.map

package/dist/utils/encryption-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption-utils.d.ts","sourceRoot":"","sources":["../../src/utils/encryption-utils.ts"],"names":[],"mappings":"AAmBA;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAQ7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAYlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAoB3E"}

package/dist/utils/encryption-utils.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateEncryptionSecret = validateEncryptionSecret;
+exports.encryptToken = encryptToken;
+exports.decryptToken = decryptToken;
+const crypto_1 = require("crypto");
+const ALGORITHM = "aes-256-gcm";
+const IV_LENGTH = 16;
+const AUTH_TAG_LENGTH = 16;
+const SALT_LENGTH = 32;
+/**
+ * Derive a 32-byte encryption key from a secret
+ *
+ * Uses SHA-256 to create a consistent key length from any secret.
+ *
+ * @param secret - Secret string (e.g., client secret)
+ * @returns 32-byte key suitable for AES-256
+ */
+function deriveKey(secret) {
+    return (0, crypto_1.createHash)("sha256").update(secret).digest();
+}
+/**
+ * Validate encryption secret meets minimum requirements
+ *
+ * @param secret - Secret to validate
+ * @throws Error if secret is invalid
+ */
+function validateEncryptionSecret(secret) {
+    if (!secret) {
+        throw new Error("Encryption secret is required");
+    }
+    if (secret.length < 32) {
+        throw new Error("Encryption secret must be at least 32 characters");
+    }
+}
+/**
+ * Encrypt a token using AES-256-GCM
+ *
+ * Uses Galois/Counter Mode (GCM) which provides both confidentiality
+ * and authenticity (prevents tampering).
+ *
+ * Format: iv:authTag:encryptedData (all hex-encoded)
+ *
+ * @param token - Plain text token to encrypt
+ * @param secret - Encryption secret (at least 32 characters)
+ * @returns Encrypted token with IV and auth tag
+ */
+function encryptToken(token, secret) {
+    const key = deriveKey(secret);
+    const iv = (0, crypto_1.randomBytes)(IV_LENGTH);
+    const cipher = (0, crypto_1.createCipheriv)(ALGORITHM, key, iv);
+    let encrypted = cipher.update(token, "utf8", "hex");
+    encrypted += cipher.final("hex");
+    const authTag = cipher.getAuthTag();
+    // Format: iv:authTag:encryptedData
+    return `${iv.toString("hex")}:${authTag.toString("hex")}:${encrypted}`;
+}
+/**
+ * Decrypt a token using AES-256-GCM
+ *
+ * Validates the auth tag to ensure the data hasn't been tampered with.
+ *
+ * @param encryptedToken - Encrypted token from encryptToken()
+ * @param secret - Encryption secret used during encryption
+ * @returns Decrypted plain text token
+ * @throws Error if decryption fails or auth tag is invalid
+ */
+function decryptToken(encryptedToken, secret) {
+    const parts = encryptedToken.split(":");
+    if (parts.length !== 3) {
+        throw new Error("Invalid encrypted token format");
+    }
+    const [ivHex, authTagHex, encryptedData] = parts;
+    const key = deriveKey(secret);
+    const iv = Buffer.from(ivHex, "hex");
+    const authTag = Buffer.from(authTagHex, "hex");
+    const decipher = (0, crypto_1.createDecipheriv)(ALGORITHM, key, iv);
+    decipher.setAuthTag(authTag);
+    let decrypted = decipher.update(encryptedData, "hex", "utf8");
+    decrypted += decipher.final("utf8");
+    return decrypted;
+}

package/dist/utils/error-utils.d.ts

@@ -0,0 +1,65 @@
+import { OidcError } from "../OidcPluginOptions";
+/**
+ * Standard OIDC error codes
+ */
+export declare const OidcErrorCodes: {
+    readonly INVALID_PROVIDER: "invalid_provider";
+    readonly PROVIDER_NOT_CONFIGURED: "provider_not_configured";
+    readonly DISCOVERY_FAILED: "discovery_failed";
+    readonly MISSING_CODE: "missing_code";
+    readonly MISSING_STATE: "missing_state";
+    readonly INVALID_STATE: "invalid_state";
+    readonly INVALID_RESPONSE_TYPE: "invalid_response_type";
+    readonly SESSION_NOT_FOUND: "session_not_found";
+    readonly SESSION_EXPIRED: "session_expired";
+    readonly TOKEN_EXCHANGE_FAILED: "token_exchange_failed";
+    readonly INVALID_TOKEN: "invalid_token";
+    readonly ID_TOKEN_VALIDATION_FAILED: "id_token_validation_failed";
+    readonly USERINFO_FAILED: "userinfo_failed";
+    readonly PROFILE_EXTRACTION_FAILED: "profile_extraction_failed";
+    readonly JWT_GENERATION_FAILED: "jwt_generation_failed";
+    readonly ACCESS_DENIED: "access_denied";
+    readonly UNAUTHORIZED_CLIENT: "unauthorized_client";
+    readonly INVALID_REQUEST: "invalid_request";
+    readonly UNSUPPORTED_RESPONSE_TYPE: "unsupported_response_type";
+    readonly INVALID_SCOPE: "invalid_scope";
+    readonly SERVER_ERROR: "server_error";
+    readonly TEMPORARILY_UNAVAILABLE: "temporarily_unavailable";
+};
+/**
+ * Create a standardized OIDC error object
+ *
+ * @param code - Error code from OidcErrorCodes
+ * @param message - Human-readable error message
+ * @param details - Additional error details for debugging
+ * @returns OIDC error object
+ */
+export declare function createOidcError(code: string, message: string, details?: any): OidcError;
+/**
+ * Validate provider name format
+ *
+ * Provider names must be alphanumeric with optional hyphens/underscores
+ * to ensure they work correctly in URLs.
+ *
+ * @param provider - Provider name to validate
+ * @throws OidcError if invalid
+ */
+export declare function validateProvider(provider: string): void;
+/**
+ * Validate response type parameter
+ *
+ * @param responseType - Response type from query parameter
+ * @throws OidcError if invalid
+ */
+export declare function validateResponseType(responseType?: string): void;
+/**
+ * Map IdP error codes to user-friendly messages
+ *
+ * Maps OAuth 2.0 / OIDC error codes from the IdP to our standardized
+ * error format with helpful messages.
+ *
+ * @param error - Error object or string from IdP
+ * @returns Standardized OIDC error
+ */
+export declare function handleProviderError(error: any): OidcError;
+//# sourceMappingURL=error-utils.d.ts.map

package/dist/utils/error-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-utils.d.ts","sourceRoot":"","sources":["../../src/utils/error-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;CAoCjB,CAAC;AAEX;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,SAAS,CAgBvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CASvD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAMhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,GAAG,GAAG,SAAS,CAsDzD"}

package/dist/utils/error-utils.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OidcErrorCodes = void 0;
+exports.createOidcError = createOidcError;
+exports.validateProvider = validateProvider;
+exports.validateResponseType = validateResponseType;
+exports.handleProviderError = handleProviderError;
+/**
+ * Standard OIDC error codes
+ */
+exports.OidcErrorCodes = {
+    // Configuration errors
+    INVALID_PROVIDER: "invalid_provider",
+    PROVIDER_NOT_CONFIGURED: "provider_not_configured",
+    DISCOVERY_FAILED: "discovery_failed",
+    // Request validation errors
+    MISSING_CODE: "missing_code",
+    MISSING_STATE: "missing_state",
+    INVALID_STATE: "invalid_state",
+    INVALID_RESPONSE_TYPE: "invalid_response_type",
+    // Session errors
+    SESSION_NOT_FOUND: "session_not_found",
+    SESSION_EXPIRED: "session_expired",
+    // Token exchange errors
+    TOKEN_EXCHANGE_FAILED: "token_exchange_failed",
+    INVALID_TOKEN: "invalid_token",
+    ID_TOKEN_VALIDATION_FAILED: "id_token_validation_failed",
+    // User/Profile errors
+    USERINFO_FAILED: "userinfo_failed",
+    PROFILE_EXTRACTION_FAILED: "profile_extraction_failed",
+    // JWT generation errors
+    JWT_GENERATION_FAILED: "jwt_generation_failed",
+    // IdP errors (from authorization endpoint)
+    ACCESS_DENIED: "access_denied",
+    UNAUTHORIZED_CLIENT: "unauthorized_client",
+    INVALID_REQUEST: "invalid_request",
+    UNSUPPORTED_RESPONSE_TYPE: "unsupported_response_type",
+    INVALID_SCOPE: "invalid_scope",
+    SERVER_ERROR: "server_error",
+    TEMPORARILY_UNAVAILABLE: "temporarily_unavailable",
+};
+/**
+ * Create a standardized OIDC error object
+ *
+ * @param code - Error code from OidcErrorCodes
+ * @param message - Human-readable error message
+ * @param details - Additional error details for debugging
+ * @returns OIDC error object
+ */
+function createOidcError(code, message, details) {
+    const error = {
+        code,
+        message,
+    };
+    if (details) {
+        error.details = details;
+    }
+    // Make it throwable
+    const throwableError = new Error(message);
+    throwableError.code = code;
+    throwableError.details = details;
+    return throwableError;
+}
+/**
+ * Validate provider name format
+ *
+ * Provider names must be alphanumeric with optional hyphens/underscores
+ * to ensure they work correctly in URLs.
+ *
+ * @param provider - Provider name to validate
+ * @throws OidcError if invalid
+ */
+function validateProvider(provider) {
+    if (!provider) {
+        throw createOidcError(exports.OidcErrorCodes.INVALID_PROVIDER, "Provider name is required", { provider });
+    }
+    // Allow alphanumeric, hyphens, underscores
+    if (!/^[a-zA-Z0-9_-]+$/.test(provider)) {
+        throw createOidcError(exports.OidcErrorCodes.INVALID_PROVIDER, "Provider name must be alphanumeric (hyphens and underscores allowed)", { provider });
+    }
+}
+/**
+ * Validate response type parameter
+ *
+ * @param responseType - Response type from query parameter
+ * @throws OidcError if invalid
+ */
+function validateResponseType(responseType) {
+    if (responseType && responseType !== "json") {
+        throw createOidcError(exports.OidcErrorCodes.INVALID_RESPONSE_TYPE, 'Invalid response_type. Must be "json" or omitted for redirect', {
+            responseType,
+        });
+    }
+}
+/**
+ * Map IdP error codes to user-friendly messages
+ *
+ * Maps OAuth 2.0 / OIDC error codes from the IdP to our standardized
+ * error format with helpful messages.
+ *
+ * @param error - Error object or string from IdP
+ * @returns Standardized OIDC error
+ */
+function handleProviderError(error) {
+    const errorCode = typeof error === "string" ? error : error.error || error.code;
+    const errorDescription = error.error_description || error.message;
+    // Map common OAuth/OIDC errors
+    switch (errorCode) {
+        case "access_denied":
+            return createOidcError(exports.OidcErrorCodes.ACCESS_DENIED, "User denied authorization", {
+                originalError: errorCode,
+                description: errorDescription,
+            });
+        case "unauthorized_client":
+            return createOidcError(exports.OidcErrorCodes.UNAUTHORIZED_CLIENT, "Client not authorized for this request", {
+                originalError: errorCode,
+                description: errorDescription,
+            });
+        case "invalid_request":
+            return createOidcError(exports.OidcErrorCodes.INVALID_REQUEST, "Invalid authorization request", {
+                originalError: errorCode,
+                description: errorDescription,
+            });
+        case "unsupported_response_type":
+            return createOidcError(exports.OidcErrorCodes.UNSUPPORTED_RESPONSE_TYPE, "Response type not supported by IdP", {
+                originalError: errorCode,
+                description: errorDescription,
+            });
+        case "invalid_scope":
+            return createOidcError(exports.OidcErrorCodes.INVALID_SCOPE, "Invalid or unsupported scope", {
+                originalError: errorCode,
+                description: errorDescription,
+            });
+        case "server_error":
+            return createOidcError(exports.OidcErrorCodes.SERVER_ERROR, "IdP server error", {
+                originalError: errorCode,
+                description: errorDescription,
+            });
+        case "temporarily_unavailable":
+            return createOidcError(exports.OidcErrorCodes.TEMPORARILY_UNAVAILABLE, "IdP temporarily unavailable", {
+                originalError: errorCode,
+                description: errorDescription,
+            });
+        default:
+            return createOidcError(exports.OidcErrorCodes.SERVER_ERROR, errorDescription || "Unknown IdP error", {
+                originalError: errorCode,
+                description: errorDescription,
+            });
+    }
+}

package/dist/utils/response-utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Format token response for the client
+ *
+ * Supports two response formats:
+ * 1. JSON response (for API clients)
+ * 2. Redirect with token in URL fragment (for web browsers)
+ *
+ * URL fragments are used for security - they are NOT sent to the server
+ * in HTTP requests and are only accessible to client-side JavaScript.
+ *
+ * @param token - JWT token for the application
+ * @param user - User object
+ * @param redirectUrl - URL to redirect to
+ * @param responseType - "json" or undefined (redirect)
+ * @returns Flink response object
+ */
+export declare function formatTokenResponse(token: string, user: any, redirectUrl: string, responseType?: "json"): any;
+//# sourceMappingURL=response-utils.d.ts.map

package/dist/utils/response-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-utils.d.ts","sourceRoot":"","sources":["../../src/utils/response-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,GAAG,CAwB7G"}

package/dist/utils/response-utils.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatTokenResponse = formatTokenResponse;
+/**
+ * Format token response for the client
+ *
+ * Supports two response formats:
+ * 1. JSON response (for API clients)
+ * 2. Redirect with token in URL fragment (for web browsers)
+ *
+ * URL fragments are used for security - they are NOT sent to the server
+ * in HTTP requests and are only accessible to client-side JavaScript.
+ *
+ * @param token - JWT token for the application
+ * @param user - User object
+ * @param redirectUrl - URL to redirect to
+ * @param responseType - "json" or undefined (redirect)
+ * @returns Flink response object
+ */
+function formatTokenResponse(token, user, redirectUrl, responseType) {
+    // JSON response for API clients
+    if (responseType === "json") {
+        return {
+            data: {
+                user,
+                token,
+            },
+        };
+    }
+    // Redirect response for web browsers
+    // Token is in URL fragment (#token=...) for security
+    const separator = redirectUrl.includes("#") ? "&" : "#";
+    const tokenFragment = `token=${encodeURIComponent(token)}`;
+    const finalUrl = `${redirectUrl}${separator}${tokenFragment}`;
+    return {
+        status: 302,
+        headers: {
+            Location: finalUrl,
+        },
+        data: {},
+    };
+}

package/dist/utils/state-utils.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Generate cryptographically secure state parameter for CSRF protection
+ *
+ * The state parameter is used to prevent CSRF attacks by ensuring the
+ * callback request originated from our initiate request.
+ *
+ * @returns Random 32-byte hex string
+ */
+export declare function generateState(): string;
+/**
+ * Generate cryptographically secure session ID
+ *
+ * @returns Random 16-byte hex string
+ */
+export declare function generateSessionId(): string;
+/**
+ * Generate cryptographically secure nonce for ID token replay protection
+ *
+ * The nonce is included in the authorization request and must be present
+ * in the ID token claims to prevent replay attacks.
+ *
+ * @returns Random 16-byte hex string
+ */
+export declare function generateNonce(): string;
+/**
+ * Validate state parameter using constant-time comparison
+ *
+ * Uses timing-safe comparison to prevent timing attacks that could
+ * reveal information about the expected state value.
+ *
+ * @param providedState - State from callback request
+ * @param expectedState - State from session
+ * @returns true if states match, false otherwise
+ */
+export declare function validateState(providedState: string, expectedState: string): boolean;
+//# sourceMappingURL=state-utils.d.ts.map

package/dist/utils/state-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-utils.d.ts","sourceRoot":"","sources":["../../src/utils/state-utils.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAoBnF"}

package/dist/utils/state-utils.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateState = generateState;
+exports.generateSessionId = generateSessionId;
+exports.generateNonce = generateNonce;
+exports.validateState = validateState;
+const crypto_1 = require("crypto");
+/**
+ * Generate cryptographically secure state parameter for CSRF protection
+ *
+ * The state parameter is used to prevent CSRF attacks by ensuring the
+ * callback request originated from our initiate request.
+ *
+ * @returns Random 32-byte hex string
+ */
+function generateState() {
+    return (0, crypto_1.randomBytes)(32).toString("hex");
+}
+/**
+ * Generate cryptographically secure session ID
+ *
+ * @returns Random 16-byte hex string
+ */
+function generateSessionId() {
+    return (0, crypto_1.randomBytes)(16).toString("hex");
+}
+/**
+ * Generate cryptographically secure nonce for ID token replay protection
+ *
+ * The nonce is included in the authorization request and must be present
+ * in the ID token claims to prevent replay attacks.
+ *
+ * @returns Random 16-byte hex string
+ */
+function generateNonce() {
+    return (0, crypto_1.randomBytes)(16).toString("hex");
+}
+/**
+ * Validate state parameter using constant-time comparison
+ *
+ * Uses timing-safe comparison to prevent timing attacks that could
+ * reveal information about the expected state value.
+ *
+ * @param providedState - State from callback request
+ * @param expectedState - State from session
+ * @returns true if states match, false otherwise
+ */
+function validateState(providedState, expectedState) {
+    if (!providedState || !expectedState) {
+        return false;
+    }
+    // Convert to buffers for constant-time comparison
+    const providedBuffer = Buffer.from(providedState, "utf8");
+    const expectedBuffer = Buffer.from(expectedState, "utf8");
+    // Buffers must be same length for timingSafeEqual
+    if (providedBuffer.length !== expectedBuffer.length) {
+        return false;
+    }
+    try {
+        return (0, crypto_1.timingSafeEqual)(providedBuffer, expectedBuffer);
+    }
+    catch (error) {
+        // timingSafeEqual throws if lengths differ (shouldn't happen due to check above)
+        return false;
+    }
+}