@cloudwerk/security 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,424 @@
+import { C as CSRFMiddlewareOptions, a as SetCsrfCookieOptions, b as SecurityHeadersOptions, c as CSPOptions, d as CSPDirectives, O as OriginValidationOptions, R as RequestedWithOptions, e as SecurityMiddlewareOptions } from './types-DtbmXdeT.js';
+export { f as CSPDirectiveValue, g as CookieAttributes, S as SecureFetchOptions } from './types-DtbmXdeT.js';
+import { Middleware } from '@cloudwerk/core';
+
+/**
+ * @cloudwerk/security - CSRF Middleware
+ *
+ * Provides CSRF (Cross-Site Request Forgery) protection for mutation requests.
+ * Uses the double-submit cookie pattern for stateless CSRF protection.
+ */
+
+/**
+ * Create CSRF protection middleware.
+ *
+ * Validates that mutation requests (POST, PUT, PATCH, DELETE) include a valid
+ * CSRF token that matches the token in the cookie. Uses the double-submit
+ * cookie pattern for stateless CSRF protection.
+ *
+ * The token can be provided via:
+ * 1. Request header (X-CSRF-Token by default) - for AJAX requests
+ * 2. Form field (csrf_token by default) - for traditional form submissions
+ *
+ * @param options - Middleware configuration options
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * // In middleware.ts
+ * import { csrfMiddleware } from '@cloudwerk/security/middleware'
+ *
+ * export const middleware = csrfMiddleware()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Exclude webhook paths
+ * export const middleware = csrfMiddleware({
+ *   excludePaths: ['/api/webhooks/stripe', '/api/webhooks/github'],
+ * })
+ * ```
+ */
+declare function csrfMiddleware(options?: CSRFMiddlewareOptions): Middleware;
+
+/**
+ * @cloudwerk/security - CSRF Token Utilities
+ *
+ * Functions for generating, setting, and verifying CSRF tokens.
+ */
+
+/** Default CSRF cookie name */
+declare const DEFAULT_CSRF_COOKIE_NAME = "cloudwerk.csrf-token";
+/** Default CSRF header name */
+declare const DEFAULT_CSRF_HEADER_NAME = "X-CSRF-Token";
+/** Default CSRF form field name */
+declare const DEFAULT_CSRF_FORM_FIELD_NAME = "csrf_token";
+/**
+ * Generate a cryptographically secure CSRF token.
+ *
+ * Uses Web Crypto API for secure random number generation.
+ *
+ * @returns A URL-safe base64-encoded random token
+ *
+ * @example
+ * ```typescript
+ * import { generateCsrfToken } from '@cloudwerk/security'
+ *
+ * const token = generateCsrfToken()
+ * // 'Yx8nK2pQ...' (43 characters)
+ * ```
+ */
+declare function generateCsrfToken(): string;
+/**
+ * Set a CSRF cookie on a response.
+ *
+ * Creates a new response with the CSRF cookie set. The cookie is accessible
+ * to JavaScript (not httpOnly) so that SPA frameworks can read it and include
+ * it in request headers.
+ *
+ * @param response - The response to add the cookie to
+ * @param token - The CSRF token to set (generate with generateCsrfToken())
+ * @param options - Cookie configuration options
+ * @returns A new response with the Set-Cookie header added
+ *
+ * @example
+ * ```typescript
+ * import { generateCsrfToken, setCsrfCookie } from '@cloudwerk/security'
+ *
+ * export function GET(request: Request) {
+ *   const token = generateCsrfToken()
+ *   const response = new Response(JSON.stringify({ csrfToken: token }))
+ *   return setCsrfCookie(response, token)
+ * }
+ * ```
+ */
+declare function setCsrfCookie(response: Response, token: string, options?: SetCsrfCookieOptions): Response;
+/**
+ * Get the CSRF token from a request's cookie.
+ *
+ * @param request - The request to extract the token from
+ * @param cookieName - The cookie name to look for
+ * @returns The CSRF token or null if not found
+ */
+declare function getCsrfTokenFromCookie(request: Request, cookieName?: string): string | null;
+/**
+ * Get the CSRF token from a request's header.
+ *
+ * @param request - The request to extract the token from
+ * @param headerName - The header name to look for
+ * @returns The CSRF token or null if not found
+ */
+declare function getCsrfTokenFromHeader(request: Request, headerName?: string): string | null;
+/**
+ * Get the CSRF token from a request's form body.
+ *
+ * @param request - The request to extract the token from (will be cloned)
+ * @param fieldName - The form field name to look for
+ * @returns The CSRF token or null if not found
+ */
+declare function getCsrfTokenFromFormBody(request: Request, fieldName?: string): Promise<string | null>;
+/**
+ * Verify a CSRF token against the token in the cookie.
+ *
+ * Uses timing-safe comparison to prevent timing attacks.
+ *
+ * @param cookieToken - The token from the cookie
+ * @param requestToken - The token from the request (header or form body)
+ * @returns True if tokens match
+ *
+ * @example
+ * ```typescript
+ * import { verifyCsrfToken, getCsrfTokenFromCookie, getCsrfTokenFromHeader } from '@cloudwerk/security'
+ *
+ * const cookieToken = getCsrfTokenFromCookie(request)
+ * const headerToken = getCsrfTokenFromHeader(request)
+ *
+ * if (cookieToken && headerToken && verifyCsrfToken(cookieToken, headerToken)) {
+ *   // Token is valid
+ * }
+ * ```
+ */
+declare function verifyCsrfToken(cookieToken: string, requestToken: string): boolean;
+/**
+ * Rotate the CSRF token on a response.
+ *
+ * Generates a new CSRF token and sets it as a cookie. This should be called
+ * after successful authentication to bind the CSRF token to the new session
+ * and prevent session fixation attacks.
+ *
+ * @param response - The response to add the new CSRF cookie to
+ * @param options - Cookie configuration options
+ * @returns A new response with the rotated CSRF token cookie
+ *
+ * @example
+ * ```typescript
+ * import { rotateCsrfToken } from '@cloudwerk/security'
+ *
+ * // After successful login
+ * export async function handleLogin(request: Request) {
+ *   const user = await validateCredentials(request)
+ *   const session = await createSession(user)
+ *
+ *   let response = createAuthResponse(user, session)
+ *   response = rotateCsrfToken(response)
+ *   return response
+ * }
+ * ```
+ */
+declare function rotateCsrfToken(response: Response, options?: SetCsrfCookieOptions): Response;
+
+/**
+ * @cloudwerk/security - Security Headers Middleware
+ *
+ * Sets standard security headers on responses.
+ */
+
+/**
+ * Create security headers middleware.
+ *
+ * Sets standard security headers on all responses:
+ * - X-Content-Type-Options: nosniff
+ * - X-Frame-Options: DENY
+ * - Referrer-Policy: strict-origin-when-cross-origin
+ * - X-XSS-Protection: 0 (disabled, modern browsers handle XSS)
+ * - X-Permitted-Cross-Domain-Policies: none
+ * - X-DNS-Prefetch-Control: off
+ *
+ * @param options - Header configuration options
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * import { securityHeadersMiddleware } from '@cloudwerk/security/middleware'
+ *
+ * // Use defaults
+ * export const middleware = securityHeadersMiddleware()
+ *
+ * // Custom configuration
+ * export const middleware = securityHeadersMiddleware({
+ *   frameOptions: 'SAMEORIGIN',
+ *   crossOriginOpenerPolicy: 'same-origin',
+ * })
+ * ```
+ */
+declare function securityHeadersMiddleware(options?: SecurityHeadersOptions): Middleware;
+
+/**
+ * @cloudwerk/security - Content Security Policy Middleware
+ *
+ * Generates and sets Content-Security-Policy headers.
+ */
+
+/**
+ * Generate a cryptographically secure nonce for CSP.
+ *
+ * @returns A base64-encoded random nonce
+ */
+declare function generateNonce(): string;
+/**
+ * Generate a Content-Security-Policy header string from directives.
+ *
+ * @param directives - CSP directives object
+ * @param nonce - Optional nonce to include in script-src and style-src
+ * @returns CSP header string
+ *
+ * @example
+ * ```typescript
+ * const csp = generateCSPHeader({
+ *   defaultSrc: ["'self'"],
+ *   scriptSrc: ["'self'", 'https://cdn.example.com'],
+ *   styleSrc: ["'self'", "'unsafe-inline'"],
+ * })
+ * // "default-src 'self'; script-src 'self' https://cdn.example.com; style-src 'self' 'unsafe-inline'"
+ * ```
+ */
+declare function generateCSPHeader(directives: CSPDirectives, nonce?: string): string;
+/**
+ * Create CSP middleware.
+ *
+ * Generates and sets Content-Security-Policy (or Content-Security-Policy-Report-Only)
+ * headers on responses.
+ *
+ * @param options - CSP configuration options
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * import { cspMiddleware } from '@cloudwerk/security/middleware'
+ *
+ * export const middleware = cspMiddleware({
+ *   directives: {
+ *     defaultSrc: ["'self'"],
+ *     scriptSrc: ["'self'", 'https://cdn.example.com'],
+ *     styleSrc: ["'self'", "'unsafe-inline'"],
+ *     imgSrc: ["'self'", 'data:', 'https:'],
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Report-only mode for testing
+ * export const middleware = cspMiddleware({
+ *   directives: {
+ *     defaultSrc: ["'self'"],
+ *     reportUri: '/api/csp-report',
+ *   },
+ *   reportOnly: true,
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With nonce generation for inline scripts
+ * export const middleware = cspMiddleware({
+ *   directives: {
+ *     defaultSrc: ["'self'"],
+ *     scriptSrc: ["'self'"],
+ *   },
+ *   useNonce: true,
+ * })
+ *
+ * // In your page, access the nonce via context:
+ * // const nonce = context.get('cspNonce')
+ * // <script nonce={nonce}>...</script>
+ * ```
+ */
+declare function cspMiddleware(options?: CSPOptions): Middleware;
+
+/**
+ * @cloudwerk/security - Origin Validation Middleware
+ *
+ * Validates Origin and Referer headers to prevent cross-origin attacks.
+ */
+
+/**
+ * Create origin validation middleware.
+ *
+ * Validates that mutation requests (POST, PUT, PATCH, DELETE) come from
+ * allowed origins. This helps prevent CSRF attacks by rejecting requests
+ * from unknown origins.
+ *
+ * @param options - Validation options
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * import { originValidationMiddleware } from '@cloudwerk/security/middleware'
+ *
+ * export const middleware = originValidationMiddleware({
+ *   allowedOrigins: ['https://myapp.com', 'https://admin.myapp.com'],
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Allow all subdomains of a host
+ * export const middleware = originValidationMiddleware({
+ *   allowedHosts: ['myapp.com'],
+ *   allowSubdomains: true,
+ * })
+ * ```
+ */
+declare function originValidationMiddleware(options?: OriginValidationOptions): Middleware;
+
+/**
+ * @cloudwerk/security - X-Requested-With Validation Middleware
+ *
+ * Requires X-Requested-With header to force CORS preflight for cross-origin requests.
+ */
+
+/**
+ * Create X-Requested-With validation middleware.
+ *
+ * Requires mutation requests to include an `X-Requested-With` header.
+ * This forces CORS preflight for cross-origin requests, providing an
+ * additional layer of protection against CSRF attacks.
+ *
+ * The X-Requested-With header is a custom header that cannot be set
+ * cross-origin without a CORS preflight. By requiring it, we ensure
+ * that cross-origin requests must pass CORS checks.
+ *
+ * @param options - Validation options
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * import { requestedWithMiddleware } from '@cloudwerk/security/middleware'
+ *
+ * // Default: requires X-Requested-With: XMLHttpRequest
+ * export const middleware = requestedWithMiddleware()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom header value
+ * export const middleware = requestedWithMiddleware({
+ *   requiredValue: 'fetch',
+ *   excludePaths: ['/api/webhooks'],
+ * })
+ * ```
+ */
+declare function requestedWithMiddleware(options?: RequestedWithOptions): Middleware;
+
+/**
+ * @cloudwerk/security - Combined Security Middleware
+ *
+ * All-in-one middleware that combines CSRF, security headers, CSP,
+ * origin validation, and X-Requested-With validation.
+ */
+
+/**
+ * Create a combined security middleware.
+ *
+ * This middleware composes multiple security protections with sensible defaults:
+ * - **csrf**: Enabled by default - validates CSRF tokens on mutation requests
+ * - **requestedWith**: Enabled by default - requires X-Requested-With header
+ * - **headers**: Enabled by default - sets security headers (nosniff, DENY, etc.)
+ * - **csp**: Disabled by default - requires app-specific configuration
+ * - **origin**: Disabled by default - requires allowedOrigins configuration
+ *
+ * @param options - Configuration options for each protection
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * import { securityMiddleware } from '@cloudwerk/security/middleware'
+ *
+ * // Use with all defaults
+ * export const middleware = securityMiddleware()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Full configuration
+ * export const middleware = securityMiddleware({
+ *   allowedOrigins: ['https://myapp.com'],
+ *   csrf: {
+ *     excludePaths: ['/api/webhooks/stripe'],
+ *   },
+ *   csp: {
+ *     directives: {
+ *       defaultSrc: ["'self'"],
+ *       scriptSrc: ["'self'", 'https://cdn.example.com'],
+ *     },
+ *     reportOnly: true,
+ *   },
+ *   headers: {
+ *     frameOptions: 'SAMEORIGIN',
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Disable specific protections
+ * export const middleware = securityMiddleware({
+ *   csrf: false,            // Disable CSRF
+ *   requestedWith: false,   // Disable X-Requested-With
+ * })
+ * ```
+ */
+declare function securityMiddleware(options?: SecurityMiddlewareOptions): Middleware;
+
+export { CSPDirectives, CSPOptions, CSRFMiddlewareOptions, DEFAULT_CSRF_COOKIE_NAME, DEFAULT_CSRF_FORM_FIELD_NAME, DEFAULT_CSRF_HEADER_NAME, OriginValidationOptions, RequestedWithOptions, SecurityHeadersOptions, SecurityMiddlewareOptions, SetCsrfCookieOptions, cspMiddleware, csrfMiddleware, generateCSPHeader, generateCsrfToken, generateNonce, getCsrfTokenFromCookie, getCsrfTokenFromFormBody, getCsrfTokenFromHeader, originValidationMiddleware, requestedWithMiddleware, rotateCsrfToken, securityHeadersMiddleware, securityMiddleware, setCsrfCookie, verifyCsrfToken };