@csrf-armor/express/dist/adapter.d.ts

Express.js adapter for CSRF Armor - Advanced CSRF protection for Express.js applications

import { CsrfAdapter, CsrfRequest, CsrfResponse, RequiredCsrfConfig } from "@csrf-armor/core";
import express from "express";

//#region src/adapter.d.ts

/**
 * Express.js adapter for CSRF protection.
 *
 * This adapter implements the CsrfAdapter interface to provide CSRF protection
 * for Express.js applications. It handles request/response transformation,
 * token extraction from various sources, and cookie/header management.
 *
 * @example
 * ```typescript
 * import { CsrfProtection } from '@csrf-armor/core';
 * import { ExpressAdapter } from '@csrf-armor/express';
 *
 * const csrf = new CsrfProtection(new ExpressAdapter(), {
 *   secret: 'your-secret-key',
 *   strategy: 'signed-double-submit'
 * });
 * ```
 */
declare class ExpressAdapter implements CsrfAdapter<express.Request, express.Response> {
  /**
   * Extracts CSRF-relevant data from an Express.js request.
   *
   * Converts an Express Request object into a standardized CsrfRequest format
   * that can be processed by the core CSRF protection logic. Handles header
   * normalization, cookie extraction, and body access.
   *
   * @param req - Express.js request object
   * @returns Normalized CSRF request object
   *
   * @example
   * ```typescript
   * const adapter = new ExpressAdapter();
   * const csrfRequest = adapter.extractRequest(req);
   * // csrfRequest contains normalized headers, cookies, and body
   * ```
   */
  extractRequest(req: express.Request): CsrfRequest;
  /**
   * Sets a cookie on the Express.js response with CSRF protection options.
   *
   * Converts CSRF armor cookie options to Express.js cookie format,
   * including proper maxAge conversion (seconds to milliseconds).
   *
   * @param res - Express.js response object
   * @param name - Cookie name
   * @param value - Cookie value
   * @param options - CSRF cookie options
   *
   * @private
   */
  private setCookie;
  /**
   * Sets HTTP headers on the Express.js response.
   *
   * Handles both Map and object-based header formats from the CSRF response.
   *
   * @param res - Express.js response object
   * @param headers - Headers to set (Map or object format)
   *
   * @private
   */
  private setHeaders;
  /**
   * Applies CSRF protection data to an Express.js response.
   *
   * Sets headers and cookies on the Express response based on the CSRF
   * protection results. This includes CSRF tokens, strategy hints, and
   * security cookies.
   *
   * @param res - Express.js response object to modify
   * @param csrfResponse - CSRF response data containing headers and cookies
   * @returns The modified Express.js response object
   *
   * @example
   * ```typescript
   * const adapter = new ExpressAdapter();
   * const modifiedResponse = adapter.applyResponse(res, {
   *   headers: new Map([['x-csrf-token', 'abc123']]),
   *   cookies: new Map([['csrf-token', { value: 'def456', options: { httpOnly: true } }]])
   * });
   * ```
   */
  applyResponse(res: express.Response, csrfResponse: CsrfResponse): express.Response;
  /**
   * Extracts CSRF token from various locations in an Express.js request.
   *
   * Attempts to find the CSRF token in the following order:
   * 1. HTTP headers (e.g., X-CSRF-Token)
   * 2. URL query parameters
   * 3. Request body (form data or JSON)
   *
   * This method handles relative URLs safely by providing a base URL for parsing.
   *
   * @param request - Normalized CSRF request object
   * @param config - CSRF configuration containing token field names
   * @returns The extracted token string, or undefined if not found
   *
   * @example
   * ```typescript
   * const adapter = new ExpressAdapter();
   * const token = await adapter.getTokenFromRequest(csrfRequest, {
   *   token: { headerName: 'X-CSRF-Token', fieldName: 'csrf_token' }
   * });
   * // Returns token from header, query param, or body
   * ```
   */
  getTokenFromRequest(request: CsrfRequest, config: RequiredCsrfConfig): Promise<string | undefined>;
}
//# sourceMappingURL=adapter.d.ts.map
//#endregion
export { ExpressAdapter };
//# sourceMappingURL=adapter.d.ts.map