@vorionsys/security 1.0.0

package/dist/api/middleware/dpop-enforcement.d.ts

@@ -0,0 +1,176 @@
+/**
+ * DPoP Enforcement Middleware
+ *
+ * Fastify plugin that enforces DPoP (Demonstrating Proof-of-Possession) proof
+ * validation on protected endpoints. Integrates with the existing DPoP service
+ * to provide sender-constrained token validation per RFC 9449.
+ *
+ * Features:
+ * - Per-route DPoP enforcement configuration (required, optional, none)
+ * - Access token binding validation
+ * - Replay attack prevention via JTI cache
+ * - Security monitoring via structured logging
+ * - Metrics for validation success/failure rates
+ *
+ * @packageDocumentation
+ */
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import { DPoPService, DPoPError, createDPoPService } from '../../security/dpop.js';
+import type { DPoPConfig, DPoPVerificationResult, JTICache, TrustTier } from '../../security/types.js';
+/**
+ * DPoP enforcement mode for a route
+ */
+export type DPoPEnforcementMode = 'required' | 'optional' | 'none';
+/**
+ * Route-level DPoP configuration
+ */
+export interface RouteDPoPConfig {
+    /** DPoP enforcement mode */
+    dpop: DPoPEnforcementMode;
+}
+/**
+ * Route pattern with DPoP configuration
+ */
+export interface DPoPRoutePattern {
+    /** HTTP method (GET, POST, etc.) or '*' for all methods */
+    method: string | '*';
+    /** URL pattern (exact match or with wildcards) */
+    pattern: string;
+    /** DPoP enforcement mode */
+    dpop: DPoPEnforcementMode;
+}
+/**
+ * DPoP enforcement plugin options
+ */
+export interface DPoPEnforcementOptions {
+    /** DPoP service instance (optional, will create default if not provided) */
+    dpopService?: DPoPService;
+    /** DPoP configuration for service creation */
+    dpopConfig?: Partial<DPoPConfig>;
+    /** JTI cache implementation (optional, defaults to in-memory) */
+    jtiCache?: JTICache;
+    /** Default enforcement mode for unspecified routes */
+    defaultMode?: DPoPEnforcementMode;
+    /** Route-specific DPoP configurations */
+    routeConfigs?: DPoPRoutePattern[];
+    /** Paths to skip DPoP enforcement entirely */
+    skipPaths?: string[];
+    /** Trust tier to extract from request for tier-based enforcement */
+    extractTrustTier?: (request: FastifyRequest) => TrustTier | undefined;
+    /** Log all DPoP decisions (for debugging) */
+    logDecisions?: boolean;
+    /** Base URL for URI validation (defaults to request protocol + host) */
+    baseUrl?: string;
+}
+/**
+ * DPoP validation context attached to request
+ */
+export interface DPoPContext {
+    /** Whether DPoP was validated */
+    validated: boolean;
+    /** DPoP key thumbprint (JWK thumbprint of proof key) */
+    keyThumbprint?: string;
+    /** Enforcement mode applied */
+    enforcementMode: DPoPEnforcementMode;
+    /** Validation timestamp */
+    validatedAt?: string;
+    /** Error if validation failed */
+    error?: string;
+    /** Error code if validation failed */
+    errorCode?: string;
+}
+/**
+ * Extended Fastify request with DPoP context
+ */
+declare module 'fastify' {
+    interface FastifyRequest {
+        /** DPoP validation context */
+        dpopContext?: DPoPContext;
+        /** DPoP key thumbprint (shortcut for dpopContext.keyThumbprint) */
+        dpopKeyThumbprint?: string;
+    }
+    interface FastifyInstance {
+        /** DPoP service instance */
+        dpopService?: DPoPService;
+    }
+}
+/**
+ * Async hook handler type
+ */
+type AsyncHookHandler = (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+/**
+ * DPoP Enforcement Plugin
+ *
+ * Registers DPoP proof validation middleware for protected endpoints.
+ * Supports route-level configuration for required, optional, or no enforcement.
+ *
+ * @example
+ * ```typescript
+ * await fastify.register(dpopEnforcementPlugin, {
+ *   defaultMode: 'required',
+ *   routeConfigs: [
+ *     { method: '*', pattern: '/public/*', dpop: 'none' },
+ *     { method: 'POST', pattern: '/api/v1/auth/token', dpop: 'optional' },
+ *   ],
+ * });
+ * ```
+ */
+export declare const dpopEnforcementPlugin: (fastify: FastifyInstance, options: DPoPEnforcementOptions) => Promise<void>;
+/**
+ * Create a route-specific DPoP configuration
+ *
+ * Use this with Fastify route options for per-route DPoP requirements.
+ *
+ * @example
+ * ```typescript
+ * fastify.post('/api/v1/sensitive', {
+ *   config: { dpop: dpopRequired() },
+ * }, handler);
+ * ```
+ */
+export declare function dpopRequired(): RouteDPoPConfig;
+/**
+ * Create a route config for optional DPoP
+ */
+export declare function dpopOptional(): RouteDPoPConfig;
+/**
+ * Create a route config for no DPoP enforcement
+ */
+export declare function dpopNone(): RouteDPoPConfig;
+/**
+ * Create a preHandler hook that enforces DPoP for a specific route
+ *
+ * Use this when you need per-route DPoP enforcement outside the plugin.
+ *
+ * @example
+ * ```typescript
+ * fastify.post('/api/v1/sensitive', {
+ *   preHandler: requireDPoP(),
+ * }, handler);
+ * ```
+ */
+export declare function requireDPoP(dpopService?: DPoPService, options?: Partial<DPoPEnforcementOptions>): AsyncHookHandler;
+/**
+ * Create a preHandler that accepts optional DPoP proof
+ */
+export declare function optionalDPoP(dpopService?: DPoPService, options?: Partial<DPoPEnforcementOptions>): AsyncHookHandler;
+/**
+ * Check if request has validated DPoP proof
+ */
+export declare function hasDPoPProof(request: FastifyRequest): boolean;
+/**
+ * Get DPoP key thumbprint from request
+ */
+export declare function getDPoPKeyThumbprint(request: FastifyRequest): string | undefined;
+/**
+ * Get full DPoP context from request
+ */
+export declare function getDPoPContext(request: FastifyRequest): DPoPContext | undefined;
+/**
+ * Check if DPoP validation failed
+ */
+export declare function dpopValidationFailed(request: FastifyRequest): boolean;
+export { DPoPService, DPoPError, createDPoPService, };
+export type { DPoPConfig, DPoPVerificationResult, JTICache, TrustTier, };
+export default dpopEnforcementPlugin;
+//# sourceMappingURL=dpop-enforcement.d.ts.map

package/dist/api/middleware/dpop-enforcement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dpop-enforcement.d.ts","sourceRoot":"","sources":["../../../src/api/middleware/dpop-enforcement.ts"],"names":[],"mappings":"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"}