@sigil-security/policy 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,423 @@
+/**
+ * Describes where a CSRF token was found in the request.
+ *
+ * Transport precedence (strict order per SPECIFICATION.md §8.3):
+ * 1. Custom header (X-CSRF-Token)
+ * 2. Request body (JSON)
+ * 3. Request body (form)
+ * 4. None (no token found)
+ *
+ * Query parameter transport is NEVER allowed.
+ */
+type TokenSource = {
+    readonly from: 'header';
+    readonly value: string;
+} | {
+    readonly from: 'body-json';
+    readonly value: string;
+} | {
+    readonly from: 'body-form';
+    readonly value: string;
+} | {
+    readonly from: 'none';
+};
+/**
+ * Normalized request metadata extracted from HTTP requests.
+ *
+ * **CRITICAL:** This is a plain object — NOT a framework-specific Request, req, res,
+ * or any HTTP object. The runtime layer is responsible for extracting RequestMetadata
+ * from framework objects (Express, Fastify, Hono, etc.).
+ *
+ * The policy layer NEVER touches raw HTTP objects.
+ */
+interface RequestMetadata {
+    /** HTTP method (uppercase: GET, POST, PUT, PATCH, DELETE, etc.) */
+    readonly method: string;
+    /** Origin header value, or null if absent */
+    readonly origin: string | null;
+    /** Referer header value, or null if absent */
+    readonly referer: string | null;
+    /** Sec-Fetch-Site header: same-origin, same-site, cross-site, none, or null */
+    readonly secFetchSite: string | null;
+    /** Sec-Fetch-Mode header: cors, navigate, no-cors, same-origin, websocket, or null */
+    readonly secFetchMode: string | null;
+    /** Sec-Fetch-Dest header: document, embed, font, image, script, style, etc., or null */
+    readonly secFetchDest: string | null;
+    /** Content-Type header value (without parameters), or null if absent */
+    readonly contentType: string | null;
+    /** Describes how the CSRF token was transported */
+    readonly tokenSource: TokenSource;
+    /** Optional: explicit client type override header (X-Client-Type) */
+    readonly clientType?: string | undefined;
+}
+/**
+ * Result of a policy validation check.
+ *
+ * - `allowed: true` — request passes this policy check
+ * - `allowed: false` — request fails with an internal reason (NEVER exposed to client)
+ */
+type PolicyResult = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+};
+/**
+ * A single validation policy that examines request metadata.
+ *
+ * Policies are composable via `createPolicyChain`.
+ * Each policy is a pure function of `RequestMetadata` — no side effects, no I/O.
+ */
+interface PolicyValidator {
+    /** Unique identifier for this policy (for logging/metrics) */
+    readonly name: string;
+    /** Validate request metadata against this policy */
+    validate(metadata: RequestMetadata): PolicyResult;
+}
+/** Legacy browser handling mode for Fetch Metadata policy */
+type LegacyBrowserMode = 'degraded' | 'strict';
+/** Configuration for Fetch Metadata policy */
+interface FetchMetadataConfig {
+    /** How to handle requests without Fetch Metadata headers (default: 'degraded') */
+    readonly legacyBrowserMode?: LegacyBrowserMode | undefined;
+}
+/** Configuration for Origin policy */
+interface OriginConfig {
+    /** List of allowed origins (e.g., ['https://example.com', 'https://api.example.com']) */
+    readonly allowedOrigins: readonly string[];
+}
+/** Configuration for Method policy */
+interface MethodConfig {
+    /** HTTP methods that require CSRF protection (default: POST, PUT, PATCH, DELETE) */
+    readonly protectedMethods?: readonly string[] | undefined;
+}
+/** Configuration for Content-Type policy */
+interface ContentTypeConfig {
+    /** Allowed Content-Type values (default: application/json, application/x-www-form-urlencoded, multipart/form-data) */
+    readonly allowedContentTypes?: readonly string[] | undefined;
+}
+/** Risk tier for context binding per SPECIFICATION.md §6.2 */
+type RiskTier = 'low' | 'medium' | 'high';
+/** Configuration for context binding policy */
+interface ContextBindingConfig {
+    /** Risk tier determining binding strictness */
+    readonly tier: RiskTier;
+    /**
+     * Grace period in milliseconds for session rotation tolerance.
+     * Only applies to 'medium' tier (soft-fail with grace period).
+     * Default: 5 minutes (300_000 ms)
+     */
+    readonly gracePeriodMs?: number | undefined;
+}
+/** Configuration for token transport extraction */
+interface TokenTransportConfig {
+    /** Custom header name (default: 'x-csrf-token') */
+    readonly headerName?: string | undefined;
+    /** JSON body field name (default: 'csrf_token') */
+    readonly jsonFieldName?: string | undefined;
+    /** Form body field name (default: 'csrf_token') */
+    readonly formFieldName?: string | undefined;
+}
+/** Result of token transport extraction */
+type TokenTransportResult = {
+    readonly found: true;
+    readonly source: TokenSource;
+    readonly warnings: readonly string[];
+} | {
+    readonly found: false;
+    readonly reason: string;
+};
+/** Detected client mode per SPECIFICATION.md §8.2 */
+type ClientMode = 'browser' | 'api';
+/** Default HTTP methods requiring CSRF protection */
+declare const DEFAULT_PROTECTED_METHODS: readonly string[];
+/** Default allowed Content-Type values */
+declare const DEFAULT_ALLOWED_CONTENT_TYPES: readonly string[];
+/** Default token header name */
+declare const DEFAULT_HEADER_NAME = "x-csrf-token";
+/** Default one-shot token header name */
+declare const DEFAULT_ONESHOT_HEADER_NAME = "x-csrf-one-shot-token";
+/** Default JSON body field name for CSRF token */
+declare const DEFAULT_JSON_FIELD_NAME = "csrf_token";
+/** Default form body field name for CSRF token */
+declare const DEFAULT_FORM_FIELD_NAME = "csrf_token";
+/** Default grace period for medium-tier context binding (5 minutes) */
+declare const DEFAULT_CONTEXT_GRACE_PERIOD_MS: number;
+
+/**
+ * Creates a Fetch Metadata policy validator.
+ *
+ * Validates requests using the `Sec-Fetch-Site` header (W3C Fetch Metadata):
+ * - `same-origin` → allow
+ * - `same-site` → allow (log warning for cross-origin subdomain)
+ * - `cross-site` → reject (state-changing request from external origin)
+ * - `none` → reject (browser extension or untrusted origin)
+ * - Header absent → depends on `legacyBrowserMode`:
+ *   - `'degraded'` (default) → allow (fallback to Origin + Token validation)
+ *   - `'strict'` → reject (modern browser required)
+ *
+ * @param config - Optional configuration for legacy browser handling
+ * @returns PolicyValidator for Fetch Metadata
+ */
+declare function createFetchMetadataPolicy(config?: FetchMetadataConfig): PolicyValidator;
+
+/**
+ * Creates an Origin/Referer policy validator.
+ *
+ * Validates request provenance using Origin and Referer headers:
+ * - If Origin header present → strict match against allowed origins
+ * - If Origin absent → Referer header fallback (extract origin from URL)
+ * - Both absent → reject (no provenance signal)
+ *
+ * @param config - Configuration with list of allowed origins
+ * @returns PolicyValidator for Origin/Referer
+ */
+declare function createOriginPolicy(config: OriginConfig): PolicyValidator;
+
+/**
+ * Creates an HTTP Method policy validator.
+ *
+ * This policy acts as a **gate**: it determines whether the request's HTTP method
+ * requires CSRF protection. Safe methods (GET, HEAD, OPTIONS) are allowed through
+ * immediately. Protected methods (POST, PUT, PATCH, DELETE) pass the gate too —
+ * the actual token validation is done by the runtime layer.
+ *
+ * **Usage in policy chains:** This policy never rejects. The runtime layer uses
+ * `isProtectedMethod()` to decide whether to run the CSRF validation pipeline
+ * at all. This policy is included in the chain for audit/metrics purposes
+ * (knowing which policies were evaluated).
+ *
+ * @param config - Optional configuration with custom protected methods
+ * @returns PolicyValidator for HTTP method classification
+ */
+declare function createMethodPolicy(config?: MethodConfig): PolicyValidator;
+/**
+ * Checks whether an HTTP method requires CSRF protection.
+ *
+ * This is the primary utility used by the runtime layer to determine
+ * whether to run the full policy chain + token validation for a request.
+ *
+ * Uses a pre-built Set for default methods to avoid per-call allocation.
+ *
+ * @param method - HTTP method string
+ * @param protectedMethods - Custom protected methods list (default: POST, PUT, PATCH, DELETE)
+ * @returns true if the method requires CSRF protection
+ */
+declare function isProtectedMethod(method: string, protectedMethods?: readonly string[]): boolean;
+
+/**
+ * Creates a Content-Type policy validator.
+ *
+ * Restricts requests to known-safe Content-Type values:
+ * - `application/json` (default)
+ * - `application/x-www-form-urlencoded` (default)
+ * - `multipart/form-data` (default)
+ *
+ * **Security (L6 fix):** State-changing methods (POST, PUT, PATCH, DELETE)
+ * WITHOUT a Content-Type header are now rejected. Safe methods (GET, HEAD,
+ * OPTIONS) without Content-Type are still allowed (no body expected).
+ *
+ * Content-Type parameters (charset, boundary) are stripped before comparison.
+ *
+ * Per SPECIFICATION.md §8.3: Content-Type mismatch (e.g., claiming JSON but
+ * sending form data) is handled by the runtime layer, not the policy layer.
+ *
+ * @param config - Optional configuration with custom allowed Content-Types
+ * @returns PolicyValidator for Content-Type restriction
+ */
+declare function createContentTypePolicy(config?: ContentTypeConfig): PolicyValidator;
+
+/**
+ * Configuration for client mode detection.
+ */
+interface ModeDetectionConfig {
+    /**
+     * When true, the `X-Client-Type: api` header override is disabled.
+     * Clients cannot self-declare as API mode to bypass Fetch Metadata and
+     * Origin validation. Mode is determined solely by `Sec-Fetch-Site` presence.
+     *
+     * **Security (M3 fix):** A server with permissive CORS configuration
+     * (`Access-Control-Allow-Headers: *`) would allow cross-origin attackers
+     * to set `X-Client-Type: api` and bypass browser-specific policies.
+     * Set this to `true` if CORS cannot be tightly controlled.
+     *
+     * Default: `false` (override allowed for backward compatibility)
+     */
+    readonly disableClientModeOverride?: boolean | undefined;
+}
+/**
+ * Detects client mode (browser vs API) from request metadata.
+ *
+ * Mode detection logic (per SPECIFICATION.md §8.2):
+ *
+ * 1. Manual override: `X-Client-Type: api` → Force API Mode (unless disabled)
+ * 2. `Sec-Fetch-Site` header present → Browser Mode
+ *    (modern browsers always send Fetch Metadata headers)
+ * 3. `Sec-Fetch-Site` header absent → API Mode
+ *    (non-browser clients: mobile apps, CLI, services)
+ *
+ * **Browser Mode:**
+ * - Full multi-layer validation: Fetch Metadata + Origin + Token
+ * - All policies in the chain are enforced
+ *
+ * **API Mode:**
+ * - Token-only validation (no Fetch Metadata enforcement)
+ * - Context binding recommended (API key hash)
+ * - Fetch Metadata and Origin policies are relaxed
+ *
+ * @param metadata - Normalized request metadata
+ * @param config - Optional mode detection configuration
+ * @returns 'browser' or 'api'
+ */
+declare function detectClientMode(metadata: RequestMetadata, config?: ModeDetectionConfig): ClientMode;
+
+/**
+ * Result of context binding validation with tier-specific behavior.
+ */
+interface ContextBindingResult {
+    /** Whether the context matches */
+    readonly matches: boolean;
+    /** Whether the result should be enforced (fail-closed) or logged (soft-fail) */
+    readonly enforced: boolean;
+    /** Whether the request is within the grace period (medium tier only) */
+    readonly inGracePeriod: boolean;
+    /** Risk tier that was applied */
+    readonly tier: RiskTier;
+}
+/**
+ * Evaluates context binding based on risk tier.
+ *
+ * Risk Tier Model (per SPECIFICATION.md §6.2):
+ *
+ * | Tier   | Binding              | Failure Mode           | Use Case       |
+ * |--------|----------------------|------------------------|----------------|
+ * | Low    | Optional / soft-fail | Log only               | Read endpoints |
+ * | Medium | Session ID hash      | Log + allow (grace)    | Settings       |
+ * | High   | Session+User+Origin  | Reject + audit         | Transfers      |
+ *
+ * @param contextMatches - Whether the context hash matches
+ * @param config - Context binding configuration with risk tier
+ * @param sessionAge - Age of the current session in milliseconds (for grace period)
+ * @returns ContextBindingResult with tier-specific behavior
+ */
+declare function evaluateContextBinding(contextMatches: boolean, config: ContextBindingConfig, sessionAge?: number): ContextBindingResult;
+/**
+ * Creates a context binding policy validator.
+ *
+ * This policy checks whether context binding validation should result in
+ * a hard rejection. For low-tier endpoints, context mismatch is logged
+ * but allowed. For high-tier, it's a hard reject.
+ *
+ * **Note:** The actual context hash comparison is performed by `@sigil-security/core`.
+ * This policy determines the *enforcement behavior* based on the risk tier.
+ *
+ * Since the policy layer doesn't have access to token internals, this validator
+ * works with pre-computed context match results passed via metadata extensions.
+ *
+ * @param config - Context binding configuration
+ * @returns PolicyValidator for context binding enforcement
+ */
+declare function createContextBindingPolicy(_config: ContextBindingConfig): PolicyValidator;
+
+/**
+ * Result of a policy chain evaluation.
+ *
+ * Includes all PolicyResult fields plus metadata about which policies
+ * were evaluated and which ones failed (for internal logging only).
+ */
+type PolicyChainResult = {
+    readonly allowed: true;
+    readonly evaluated: readonly string[];
+    readonly failures: readonly string[];
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+    readonly evaluated: readonly string[];
+    readonly failures: readonly string[];
+};
+/**
+ * Creates a composite policy validator from multiple individual policies.
+ *
+ * **CRITICAL:** All policies in the chain are executed regardless of individual
+ * results. There is NO short-circuit evaluation. This follows the Deterministic
+ * Failure Model from SPECIFICATION.md §5.8:
+ *
+ * - Every policy runs, even if an earlier one fails
+ * - First failure reason is captured (for internal logging)
+ * - All failure names are collected (for metrics)
+ * - Single exit point, deterministic execution path
+ *
+ * @param policies - Array of PolicyValidator instances to compose
+ * @returns A composite PolicyValidator that runs all policies
+ */
+declare function createPolicyChain(policies: readonly PolicyValidator[]): PolicyValidator;
+/**
+ * Evaluates a chain of policies against request metadata.
+ *
+ * Returns a detailed result including all evaluated and failed policy names.
+ * No short-circuit: ALL policies execute regardless of individual results.
+ *
+ * **Security (M4 fix):** An empty policy chain fails closed. A configuration
+ * bug that produces an empty chain MUST NOT silently approve all requests.
+ *
+ * @param policies - Array of policies to evaluate
+ * @param metadata - Normalized request metadata
+ * @returns Detailed chain evaluation result
+ */
+declare function evaluatePolicyChain(policies: readonly PolicyValidator[], metadata: RequestMetadata): PolicyChainResult;
+
+/**
+ * Resolves token transport from request metadata.
+ *
+ * Transport precedence (strict order per SPECIFICATION.md §8.3):
+ *
+ * 1. **Custom Header** (recommended): `X-CSRF-Token`
+ * 2. **Request Body** (JSON): `{ "csrf_token": "..." }`
+ * 3. **Request Body** (form): `csrf_token=...`
+ * 4. **Query Parameter**: NEVER allowed (deprecated, insecure — reject with warning)
+ *
+ * Rules:
+ * - First valid token found is used
+ * - Multiple tokens → first match wins, warning logged
+ * - Token source is captured for audit logging
+ *
+ * @param metadata - Normalized request metadata with token source
+ * @param _config - Optional transport configuration
+ * @returns TokenTransportResult with found token and any warnings
+ */
+declare function resolveTokenTransport(metadata: RequestMetadata, _config?: TokenTransportConfig): TokenTransportResult;
+/**
+ * Validates that a token source is acceptable.
+ *
+ * Verifies the token was transported via an approved channel:
+ * - Header: always acceptable
+ * - Body (JSON or form): acceptable
+ * - Query parameter: NEVER acceptable
+ *
+ * @param source - The token source to validate
+ * @returns true if the transport method is acceptable
+ */
+declare function isValidTokenTransport(source: TokenSource): boolean;
+/**
+ * Returns the expected header name for CSRF tokens.
+ *
+ * @param config - Optional transport configuration
+ * @returns Header name (lowercase)
+ */
+declare function getTokenHeaderName(config?: TokenTransportConfig): string;
+/**
+ * Returns the expected JSON field name for CSRF tokens.
+ *
+ * @param config - Optional transport configuration
+ * @returns JSON field name
+ */
+declare function getTokenJsonFieldName(config?: TokenTransportConfig): string;
+/**
+ * Returns the expected form field name for CSRF tokens.
+ *
+ * @param config - Optional transport configuration
+ * @returns Form field name
+ */
+declare function getTokenFormFieldName(config?: TokenTransportConfig): string;
+
+export { type ClientMode, type ContentTypeConfig, type ContextBindingConfig, type ContextBindingResult, DEFAULT_ALLOWED_CONTENT_TYPES, DEFAULT_CONTEXT_GRACE_PERIOD_MS, DEFAULT_FORM_FIELD_NAME, DEFAULT_HEADER_NAME, DEFAULT_JSON_FIELD_NAME, DEFAULT_ONESHOT_HEADER_NAME, DEFAULT_PROTECTED_METHODS, type FetchMetadataConfig, type LegacyBrowserMode, type MethodConfig, type ModeDetectionConfig, type OriginConfig, type PolicyChainResult, type PolicyResult, type PolicyValidator, type RequestMetadata, type RiskTier, type TokenSource, type TokenTransportConfig, type TokenTransportResult, createContentTypePolicy, createContextBindingPolicy, createFetchMetadataPolicy, createMethodPolicy, createOriginPolicy, createPolicyChain, detectClientMode, evaluateContextBinding, evaluatePolicyChain, getTokenFormFieldName, getTokenHeaderName, getTokenJsonFieldName, isProtectedMethod, isValidTokenTransport, resolveTokenTransport };