/**
 * CORS configuration for a DyNTS app's Express instance.
 *
 * Per FR-041 (subdomain-per-service architecture): each app whitelists which
 * client origins may call its API. The allowlist is per-environment (test list
 * differs from prod list). Without an explicit override, no CORS headers are
 * emitted (back-compat: existing apps without CORS keep their same-origin
 * behavior intact).
 *
 * Mounted by `DyNTS_AppServer.mountCors(express)` after BodyParser middleware,
 * before route mounting. Echoes a matching `Access-Control-Allow-Origin` (NOT
 * wildcard) because credentials (`Access-Control-Allow-Credentials: true`) is
 * required for the Bearer JWT cross-domain auth flow.
 */
export interface DyNTS_Cors_Settings {
  /**
   * Allowed origins. Three forms accepted:
   * - Explicit array of full origin URLs (`https://organizer.futdevpro.hu`).
   * - Predicate function for regex/pattern matching (`(origin) => /\.futdevpro\.hu$/.test(origin)`).
   * - `'*'` for wildcard — UNSAFE with `allowCredentials: true`. Use only on test or
   *   open public endpoints that do NOT carry credentials.
   */
  allowedOrigins: string[] | ((origin: string) => boolean) | '*';

  /**
   * Allow credentials (cookies, Authorization headers). Default: `true`.
   * Required for the Bearer JWT flow used cross-domain (auth.futdevpro.hu →
   * organizer.futdevpro.hu etc.).
   */
  allowCredentials?: boolean;

  /**
   * HTTP methods allowed cross-origin. Default:
   * `['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS']`.
   */
  allowedMethods?: string[];

  /**
   * Request headers the browser may send cross-origin. Default:
   * `['Authorization', 'Content-Type', 'X-Admin-Key', 'X-Requested-With']`.
   * Add app-specific headers (e.g. `X-Trace-Id`) by passing the full extended list.
   */
  allowedHeaders?: string[];

  /**
   * Headers the browser may read from cross-origin responses (beyond the
   * CORS-safelisted ones). Default: `['Content-Length', 'Content-Type']`.
   */
  exposedHeaders?: string[];

  /**
   * Preflight cache duration in seconds. Default: `86400` (24h) — minimizes
   * OPTIONS request overhead.
   */
  maxAgeSeconds?: number;
}