/**
 * Express.js Middleware for PEAC Receipt Issuance
 *
 * Intercepts responses and adds PEAC receipts automatically.
 *
 * @packageDocumentation
 */
import type { Request, Response, RequestHandler } from 'express';
import { type MiddlewareConfig, type RequestContext } from '@peac/middleware-core';
/**
 * Express-specific middleware configuration
 */
export interface ExpressMiddlewareConfig extends MiddlewareConfig {
    /** Skip receipt generation for certain routes */
    skip?: (req: Request) => boolean;
    /** Custom audience extraction from request */
    audienceExtractor?: (req: Request) => string;
    /** Custom subject extraction from request */
    subjectExtractor?: (req: Request) => string | undefined;
    /** Error handler for receipt generation failures */
    onError?: (error: Error, req: Request, res: Response) => void;
}
/**
 * Symbol to store PEAC context on request
 */
declare const PEAC_CONTEXT_KEY: unique symbol;
/**
 * Request with PEAC context attached
 */
export interface RequestWithPeacContext extends Request {
    [PEAC_CONTEXT_KEY]?: RequestContext;
}
/**
 * Check if a request has PEAC context
 */
export declare function hasPeacContext(req: Request): req is RequestWithPeacContext;
/**
 * Get the PEAC receipt from a response (for testing/debugging)
 *
 * @param res - Express response object
 * @returns Receipt JWS if present, undefined otherwise
 */
export declare function getReceiptFromResponse(res: Response): string | undefined;
/**
 * Express middleware that adds PEAC receipts to responses
 *
 * The middleware intercepts `res.json()` and `res.send()` to inject
 * PEAC receipts into responses. For header transport (default), the
 * receipt is added as a `PEAC-Receipt` header. For body transport,
 * the response is wrapped in a `{ data, peac_receipt }` structure.
 *
 * @param config - Middleware configuration
 * @returns Express request handler
 *
 * @example
 * ```typescript
 * import express from 'express';
 * import { peacMiddleware } from '@peac/middleware-express';
 *
 * const app = express();
 *
 * // Add PEAC middleware
 * app.use(peacMiddleware({
 *   issuer: 'https://api.example.com',
 *   signingKey: privateKey,
 *   keyId: 'prod-2026-02',
 * }));
 *
 * app.get('/api/data', (req, res) => {
 *   res.json({ items: [1, 2, 3] });
 *   // PEAC-Receipt header automatically added
 * });
 * ```
 */
export declare function peacMiddleware(config: ExpressMiddlewareConfig): RequestHandler;
/**
 * Create middleware with synchronous receipt generation (blocking)
 *
 * This variant waits for receipt generation before sending the response.
 * Use this when you need to guarantee the receipt is in the response,
 * but be aware it adds latency.
 *
 * @param config - Middleware configuration
 * @returns Express request handler
 */
export declare function peacMiddlewareSync(config: ExpressMiddlewareConfig): RequestHandler;
export {};
//# sourceMappingURL=middleware.d.ts.map