@csrf-armor/core/dist/constants.mjs

Framework-agnostic CSRF protection core functionality

import { generateSecureSecret } from "./crypto.mjs";

//#region src/constants.ts
/**
* HTTP methods that are considered safe and don't require CSRF protection.
*
* These methods are defined by RFC 7231 as safe methods that should not have
* side effects on the server. CSRF attacks typically target state-changing
* operations, so these methods can safely bypass CSRF validation.
*
* @public
* @example
* ```typescript
* import { SAFE_METHODS } from '@csrf-armor/core';
*
* if (SAFE_METHODS.includes(request.method)) {
*   // Skip CSRF validation for safe methods
*   return next();
* }
* ```
*/
const SAFE_METHODS = [
	"GET",
	"HEAD",
	"OPTIONS"
];
/**
* Suffix appended to server-side CSRF cookies for signed strategies.
* Server cookies contain the signature or validation data.
*
* @internal
*/
const SERVER_CSRF_COOKIE_SUFFIX = "-server";
/**
* Default HTTP header name for CSRF tokens.
* Commonly used in AJAX requests and API calls.
*
* @internal
*/
const CSRF_TOKEN_HEADER = "x-csrf-token";
/**
* HTTP header name used to communicate the CSRF strategy to clients.
* Helps debugging and allows clients to adapt their token handling.
*
* @internal
*/
const CSRF_STRATEGY_HEADER = "x-csrf-strategy";
/**
* Default length for cryptographic nonces in most CSRF strategies.
* Provides 256 bits of entropy for strong security.
*
* @internal
*/
const DEFAULT_NONCE_LENGTH = 32;
/**
* Shorter nonce length used specifically for origin-check strategy.
* Since origin-check relies primarily on origin validation, a smaller
* nonce is sufficient for preventing replay attacks.
*
* @internal
*/
const ORIGIN_CHECK_NONCE_LENGTH = 16;
/**
* Default cookie configuration for CSRF tokens.
*
* Provides secure defaults suitable for most web applications:
* - `secure: true` - Requires HTTPS (should be overridden for development)
* - `httpOnly: false` - Allows JavaScript access for SPA token retrieval
* - `sameSite: 'lax'` - Provides CSRF protection while allowing normal navigation
* - `path: '/'` - Makes cookie available across the entire application
*
* @public
* @example
* ```typescript
* import { DEFAULT_COOKIE_OPTIONS } from '@csrf-armor/core';
*
* const customConfig = {
*   ...DEFAULT_COOKIE_OPTIONS,
*   secure: false, // For development
*   domain: '.example.com' // For subdomain sharing
* };
* ```
*/
const DEFAULT_COOKIE_OPTIONS = {
	name: "csrf-token",
	secure: true,
	httpOnly: false,
	sameSite: "lax",
	path: "/"
};
/**
* Default CSRF protection configuration.
*
* Provides a complete, secure configuration suitable for production use:
* - Uses `signed-double-submit` strategy for maximum security
* - 1-hour token expiry with automatic reissue at 500 seconds
* - Standard header and field names for broad compatibility
* - Secure cookie defaults
*
* **Security Note**: The default secret is randomly generated and will be
* different on each application restart. For production, always provide
* a consistent secret key.
*
* @public
* @example
* ```typescript
* import { DEFAULT_CONFIG } from '@csrf-armor/core';
*
* // Use defaults with custom secret
* const config = {
*   ...DEFAULT_CONFIG,
*   secret: process.env.CSRF_SECRET || 'your-secret-key'
* };
*
* // Override specific settings
* const customConfig = {
*   ...DEFAULT_CONFIG,
*   strategy: 'double-submit',
*   token: {
*     ...DEFAULT_CONFIG.token,
*     expiry: 7200 // 2 hours
*   }
* };
* ```
*/
const DEFAULT_CONFIG = {
	strategy: "signed-double-submit",
	token: {
		expiry: 3600,
		headerName: "X-CSRF-Token",
		fieldName: "csrf_token",
		reissueThreshold: 500
	},
	cookie: DEFAULT_COOKIE_OPTIONS,
	secret: generateSecureSecret(),
	allowedOrigins: [],
	excludePaths: [],
	skipContentTypes: []
};

//#endregion
export { CSRF_STRATEGY_HEADER, CSRF_TOKEN_HEADER, DEFAULT_CONFIG, DEFAULT_NONCE_LENGTH, ORIGIN_CHECK_NONCE_LENGTH, SAFE_METHODS, SERVER_CSRF_COOKIE_SUFFIX };
//# sourceMappingURL=constants.mjs.map