@peac/middleware-core 0.10.9

package/dist/index.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * PEAC Middleware Core
+ *
+ * Framework-agnostic middleware primitives for PEAC receipt issuance.
+ *
+ * This package provides the core building blocks for integrating PEAC
+ * receipt issuance into any HTTP framework. For framework-specific
+ * implementations, see:
+ * - `@peac/middleware-express` for Express.js
+ *
+ * @example
+ * ```typescript
+ * import { createReceipt, validateConfig, wrapResponse } from '@peac/middleware-core';
+ *
+ * // Validate configuration at startup
+ * validateConfig(config);
+ *
+ * // In request handler
+ * const result = await createReceipt(config, requestCtx, responseCtx);
+ *
+ * // Add headers
+ * for (const [key, value] of Object.entries(result.headers)) {
+ *   res.setHeader(key, value);
+ * }
+ *
+ * // Handle body transport
+ * if (result.bodyWrapper) {
+ *   res.json(result.bodyWrapper);
+ * } else {
+ *   res.json(originalBody);
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryRateLimitStore = exports.createReceiptWithClaims = exports.createReceipt = exports.buildReceiptResult = exports.buildResponseHeaders = exports.wrapResponse = exports.selectTransport = exports.applyDefaults = exports.MAX_PATH_LENGTH = exports.CONFIG_DEFAULTS = exports.ConfigError = exports.validateConfigAsync = exports.validateConfig = void 0;
+// Configuration
+var config_js_1 = require("./config.js");
+Object.defineProperty(exports, "validateConfig", { enumerable: true, get: function () { return config_js_1.validateConfig; } });
+Object.defineProperty(exports, "validateConfigAsync", { enumerable: true, get: function () { return config_js_1.validateConfigAsync; } });
+Object.defineProperty(exports, "ConfigError", { enumerable: true, get: function () { return config_js_1.ConfigError; } });
+Object.defineProperty(exports, "CONFIG_DEFAULTS", { enumerable: true, get: function () { return config_js_1.CONFIG_DEFAULTS; } });
+Object.defineProperty(exports, "MAX_PATH_LENGTH", { enumerable: true, get: function () { return config_js_1.MAX_PATH_LENGTH; } });
+Object.defineProperty(exports, "applyDefaults", { enumerable: true, get: function () { return config_js_1.applyDefaults; } });
+// Transport
+var transport_js_1 = require("./transport.js");
+Object.defineProperty(exports, "selectTransport", { enumerable: true, get: function () { return transport_js_1.selectTransport; } });
+Object.defineProperty(exports, "wrapResponse", { enumerable: true, get: function () { return transport_js_1.wrapResponse; } });
+Object.defineProperty(exports, "buildResponseHeaders", { enumerable: true, get: function () { return transport_js_1.buildResponseHeaders; } });
+Object.defineProperty(exports, "buildReceiptResult", { enumerable: true, get: function () { return transport_js_1.buildReceiptResult; } });
+// Receipt generation
+var receipt_js_1 = require("./receipt.js");
+Object.defineProperty(exports, "createReceipt", { enumerable: true, get: function () { return receipt_js_1.createReceipt; } });
+Object.defineProperty(exports, "createReceiptWithClaims", { enumerable: true, get: function () { return receipt_js_1.createReceiptWithClaims; } });
+var rate_limit_js_1 = require("./rate-limit.js");
+Object.defineProperty(exports, "MemoryRateLimitStore", { enumerable: true, get: function () { return rate_limit_js_1.MemoryRateLimitStore; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;;;AAeH,gBAAgB;AAChB,yCAOqB;AANnB,2GAAA,cAAc,OAAA;AACd,gHAAA,mBAAmB,OAAA;AACnB,wGAAA,WAAW,OAAA;AACX,4GAAA,eAAe,OAAA;AACf,4GAAA,eAAe,OAAA;AACf,0GAAA,aAAa,OAAA;AAGf,YAAY;AACZ,+CAKwB;AAJtB,+GAAA,eAAe,OAAA;AACf,4GAAA,YAAY,OAAA;AACZ,oHAAA,oBAAoB,OAAA;AACpB,kHAAA,kBAAkB,OAAA;AAGpB,qBAAqB;AACrB,2CAAsE;AAA7D,2GAAA,aAAa,OAAA;AAAE,qHAAA,uBAAuB,OAAA;AAI/C,iDAAuD;AAA9C,qHAAA,oBAAoB,OAAA"}

package/dist/rate-limit.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Rate-limit store interface and bounded in-memory implementation.
+ *
+ * Provides a pluggable rate-limit store abstraction. The default
+ * MemoryRateLimitStore uses LRU eviction to bound memory usage.
+ *
+ * For production multi-instance deployments, implement RateLimitStore
+ * backed by Redis or similar shared storage.
+ */
+/**
+ * Pluggable rate-limit store interface.
+ *
+ * Increment returns the current count and window reset time.
+ * Implementations must handle window expiry and cleanup.
+ */
+export interface RateLimitStore {
+    increment(key: string, windowMs: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    reset(key: string): Promise<void>;
+}
+export interface MemoryRateLimitStoreOptions {
+    /** Maximum number of tracked keys before LRU eviction (default: 10000) */
+    maxKeys?: number;
+}
+/**
+ * Bounded in-memory rate-limit store with LRU eviction.
+ *
+ * - Expired windows are lazily cleaned on access
+ * - When maxKeys is exceeded, the least-recently-accessed entry is evicted
+ * - Suitable for single-instance deployments (state lost on restart)
+ */
+export declare class MemoryRateLimitStore implements RateLimitStore {
+    private readonly store;
+    private readonly maxKeys;
+    constructor(options?: MemoryRateLimitStoreOptions);
+    increment(key: string, windowMs: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    reset(key: string): Promise<void>;
+    /** Number of tracked keys */
+    get size(): number;
+    /** Remove all entries */
+    clear(): void;
+    private evictIfNeeded;
+}
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtF,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC;AASD,MAAM,WAAW,2BAA2B;IAC1C,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,YAAW,cAAc;IACzD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,CAAC,EAAE,2BAA2B;IAI3C,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAsBrF,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,6BAA6B;IAC7B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,yBAAyB;IACzB,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,aAAa;CAWtB"}

package/dist/rate-limit.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Rate-limit store interface and bounded in-memory implementation.
+ *
+ * Provides a pluggable rate-limit store abstraction. The default
+ * MemoryRateLimitStore uses LRU eviction to bound memory usage.
+ *
+ * For production multi-instance deployments, implement RateLimitStore
+ * backed by Redis or similar shared storage.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryRateLimitStore = void 0;
+/**
+ * Bounded in-memory rate-limit store with LRU eviction.
+ *
+ * - Expired windows are lazily cleaned on access
+ * - When maxKeys is exceeded, the least-recently-accessed entry is evicted
+ * - Suitable for single-instance deployments (state lost on restart)
+ */
+class MemoryRateLimitStore {
+    store = new Map();
+    maxKeys;
+    constructor(options) {
+        this.maxKeys = options?.maxKeys ?? 10_000;
+    }
+    async increment(key, windowMs) {
+        const now = Date.now();
+        let entry = this.store.get(key);
+        if (!entry || now >= entry.resetAt) {
+            // Expired or new -- start fresh window
+            entry = { count: 0, resetAt: now + windowMs, lastAccess: now };
+        }
+        entry.count++;
+        entry.lastAccess = now;
+        // Re-set to maintain Map insertion order (most recent last)
+        this.store.delete(key);
+        this.store.set(key, entry);
+        // Evict oldest entries if over capacity
+        this.evictIfNeeded();
+        return { count: entry.count, resetAt: entry.resetAt };
+    }
+    async reset(key) {
+        this.store.delete(key);
+    }
+    /** Number of tracked keys */
+    get size() {
+        return this.store.size;
+    }
+    /** Remove all entries */
+    clear() {
+        this.store.clear();
+    }
+    evictIfNeeded() {
+        while (this.store.size > this.maxKeys) {
+            // Map iterates in insertion order -- first key is oldest
+            const oldestKey = this.store.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.store.delete(oldestKey);
+            }
+            else {
+                break;
+            }
+        }
+    }
+}
+exports.MemoryRateLimitStore = MemoryRateLimitStore;
+//# sourceMappingURL=rate-limit.js.map

package/dist/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAyBH;;;;;;GAMG;AACH,MAAa,oBAAoB;IACd,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAC;IACvC,OAAO,CAAS;IAEjC,YAAY,OAAqC;QAC/C,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,MAAM,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,GAAW,EAAE,QAAgB;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAEhC,IAAI,CAAC,KAAK,IAAI,GAAG,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YACnC,uCAAuC;YACvC,KAAK,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,GAAG,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;QACjE,CAAC;QAED,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,KAAK,CAAC,UAAU,GAAG,GAAG,CAAC;QAEvB,4DAA4D;QAC5D,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAE3B,wCAAwC;QACxC,IAAI,CAAC,aAAa,EAAE,CAAC;QAErB,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;IACxD,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,GAAW;QACrB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,6BAA6B;IAC7B,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,yBAAyB;IACzB,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAEO,aAAa;QACnB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YACtC,yDAAyD;YACzD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YACjD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC/B,CAAC;iBAAM,CAAC;gBACN,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAvDD,oDAuDC"}

package/dist/receipt.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Receipt Generation
+ *
+ * Creates PEAC receipts from request/response context.
+ *
+ * This module produces **attestation receipts** - lightweight signed tokens
+ * that attest to API interactions. For full payment receipts with amt/cur/payment
+ * fields, use @peac/protocol directly.
+ *
+ * @packageDocumentation
+ */
+import type { MiddlewareConfig, RequestContext, ResponseContext, ReceiptResult, ReceiptClaimsInput } from './types.js';
+/**
+ * Create a receipt for a request/response pair
+ *
+ * This is the main function for middleware receipt generation.
+ * It validates configuration, builds claims, signs the receipt,
+ * and determines the appropriate transport profile.
+ *
+ * By default, includes minimal interaction binding (method, path, status)
+ * in the `ext[MIDDLEWARE_INTERACTION_KEY]` field for evidentiary value.
+ *
+ * @param config - Middleware configuration
+ * @param request - Request context
+ * @param response - Response context
+ * @returns Receipt result with JWS, headers, and optional body wrapper
+ *
+ * @example
+ * ```typescript
+ * const result = await createReceipt(config, requestCtx, responseCtx);
+ *
+ * // Add headers to response
+ * for (const [key, value] of Object.entries(result.headers)) {
+ *   res.setHeader(key, value);
+ * }
+ *
+ * // If body transport, use wrapped body
+ * if (result.bodyWrapper) {
+ *   res.json(result.bodyWrapper);
+ * }
+ * ```
+ */
+export declare function createReceipt(config: MiddlewareConfig, request: RequestContext, response: ResponseContext): Promise<ReceiptResult>;
+/**
+ * Create a receipt with explicit claims (bypasses context extraction)
+ *
+ * Use this when you have explicit claims and don't need context extraction.
+ * Does NOT include automatic interaction binding.
+ *
+ * @param config - Middleware configuration
+ * @param claims - Explicit claims to include
+ * @param responseBody - Optional response body for body transport
+ * @returns Receipt result
+ */
+export declare function createReceiptWithClaims(config: MiddlewareConfig, claims: ReceiptClaimsInput & {
+    aud: string;
+}, responseBody?: unknown): Promise<ReceiptResult>;
+//# sourceMappingURL=receipt.d.ts.map

package/dist/receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.d.ts","sourceRoot":"","sources":["../src/receipt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAiJpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,eAAe,GACxB,OAAO,CAAC,aAAa,CAAC,CAsFxB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,kBAAkB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,EAC5C,YAAY,CAAC,EAAE,OAAO,GACrB,OAAO,CAAC,aAAa,CAAC,CAgDxB"}

package/dist/receipt.js

@@ -0,0 +1,256 @@
+"use strict";
+/**
+ * Receipt Generation
+ *
+ * Creates PEAC receipts from request/response context.
+ *
+ * This module produces **attestation receipts** - lightweight signed tokens
+ * that attest to API interactions. For full payment receipts with amt/cur/payment
+ * fields, use @peac/protocol directly.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReceipt = createReceipt;
+exports.createReceiptWithClaims = createReceiptWithClaims;
+const uuidv7_1 = require("uuidv7");
+const crypto_1 = require("@peac/crypto");
+const schema_1 = require("@peac/schema");
+const config_js_1 = require("./config.js");
+const transport_js_1 = require("./transport.js");
+/**
+ * Create a lowercase header lookup map for case-insensitive access
+ *
+ * HTTP headers are case-insensitive per RFC 7230, but different frameworks
+ * may provide them with different casing. This normalizes to lowercase.
+ */
+function normalizeHeaders(headers) {
+    const normalized = {};
+    for (const [key, value] of Object.entries(headers)) {
+        normalized[key.toLowerCase()] = value;
+    }
+    return normalized;
+}
+/**
+ * Get a header value (case-insensitive)
+ */
+function getHeader(headers, name) {
+    const value = headers[name.toLowerCase()];
+    if (value === undefined)
+        return undefined;
+    return Array.isArray(value) ? value[0] : value;
+}
+/**
+ * Normalize issuer URL (remove trailing slashes for consistency)
+ *
+ * Uses explicit loop instead of regex to avoid ReDoS with quantifiers.
+ */
+function normalizeIssuer(issuer) {
+    let end = issuer.length;
+    while (end > 0 && issuer[end - 1] === '/') {
+        end--;
+    }
+    return end === issuer.length ? issuer : issuer.slice(0, end);
+}
+/**
+ * Process path for interaction binding based on mode
+ *
+ * - 'minimal': Strip query string, truncate to MAX_PATH_LENGTH
+ * - 'full': Keep full path with query string, truncate to MAX_PATH_LENGTH
+ *
+ * @param path - Original request path (may include query string)
+ * @param mode - Interaction binding mode
+ * @returns Processed path
+ */
+function processPath(path, mode) {
+    let processedPath = path;
+    // Strip query string in minimal mode (privacy-safe default)
+    if (mode === 'minimal') {
+        const queryIndex = path.indexOf('?');
+        if (queryIndex !== -1) {
+            processedPath = path.substring(0, queryIndex);
+        }
+    }
+    // Truncate to maximum length (DoS protection)
+    if (processedPath.length > config_js_1.MAX_PATH_LENGTH) {
+        processedPath = processedPath.substring(0, config_js_1.MAX_PATH_LENGTH);
+    }
+    return processedPath;
+}
+/**
+ * Extract audience from request context
+ *
+ * Derives audience from the request host or origin header (case-insensitive).
+ */
+function extractAudience(normalizedHeaders) {
+    // Try to get from Host header (case-insensitive)
+    const host = getHeader(normalizedHeaders, 'host');
+    if (host) {
+        // Assume HTTPS for audience
+        return `https://${host}`;
+    }
+    // Fallback to origin header
+    const origin = getHeader(normalizedHeaders, 'origin');
+    if (origin) {
+        return origin;
+    }
+    // Should not happen with proper request context
+    return 'https://localhost';
+}
+/**
+ * Convert JWK private key to raw bytes
+ */
+function jwkToPrivateKeyBytes(jwk) {
+    return (0, crypto_1.base64urlDecode)(jwk.d);
+}
+/**
+ * Create a receipt for a request/response pair
+ *
+ * This is the main function for middleware receipt generation.
+ * It validates configuration, builds claims, signs the receipt,
+ * and determines the appropriate transport profile.
+ *
+ * By default, includes minimal interaction binding (method, path, status)
+ * in the `ext[MIDDLEWARE_INTERACTION_KEY]` field for evidentiary value.
+ *
+ * @param config - Middleware configuration
+ * @param request - Request context
+ * @param response - Response context
+ * @returns Receipt result with JWS, headers, and optional body wrapper
+ *
+ * @example
+ * ```typescript
+ * const result = await createReceipt(config, requestCtx, responseCtx);
+ *
+ * // Add headers to response
+ * for (const [key, value] of Object.entries(result.headers)) {
+ *   res.setHeader(key, value);
+ * }
+ *
+ * // If body transport, use wrapped body
+ * if (result.bodyWrapper) {
+ *   res.json(result.bodyWrapper);
+ * }
+ * ```
+ */
+async function createReceipt(config, request, response) {
+    // Validate configuration
+    (0, config_js_1.validateConfig)(config);
+    // Apply defaults
+    const fullConfig = (0, config_js_1.applyDefaults)(config);
+    // Normalize headers for case-insensitive access
+    const normalizedHeaders = normalizeHeaders(request.headers);
+    // Generate receipt ID (UUIDv7 for time-ordering)
+    const rid = (0, uuidv7_1.uuidv7)();
+    // Get current timestamp
+    const iat = Math.floor(Date.now() / 1000);
+    const exp = iat + fullConfig.expiresIn;
+    // Normalize issuer and extract audience
+    const normalizedIssuer = normalizeIssuer(config.issuer);
+    const audience = extractAudience(normalizedHeaders);
+    // Build base claims
+    const claims = {
+        iss: normalizedIssuer,
+        aud: audience,
+        iat,
+        exp,
+        rid,
+    };
+    // Add interaction binding unless disabled
+    if (fullConfig.interactionBinding !== 'off') {
+        const processedPath = processPath(request.path, fullConfig.interactionBinding);
+        const interactionBinding = {
+            method: request.method.toUpperCase(),
+            path: processedPath,
+            status: response.statusCode,
+        };
+        claims.ext = {
+            [schema_1.MIDDLEWARE_INTERACTION_KEY]: interactionBinding,
+        };
+    }
+    // Apply custom claims if generator is provided
+    if (config.claimsGenerator) {
+        const customClaims = await config.claimsGenerator(request);
+        // Override audience if provided
+        if (customClaims.aud) {
+            claims.aud = customClaims.aud;
+        }
+        // Add subject if provided
+        if (customClaims.sub) {
+            claims.sub = customClaims.sub;
+        }
+        // Merge extensions (custom claims override defaults)
+        if (customClaims.ext) {
+            claims.ext = { ...claims.ext, ...customClaims.ext };
+        }
+    }
+    // Sign the receipt
+    const privateKeyBytes = jwkToPrivateKeyBytes(config.signingKey);
+    const receipt = await (0, crypto_1.sign)(claims, privateKeyBytes, config.keyId);
+    // Determine transport profile
+    const transport = (0, transport_js_1.selectTransport)(receipt, fullConfig);
+    // Generate pointer URL if needed
+    let pointerUrl;
+    if (transport === 'pointer' && config.pointerUrlGenerator) {
+        pointerUrl = await config.pointerUrlGenerator(receipt);
+    }
+    // Build complete result
+    return (0, transport_js_1.buildReceiptResult)({
+        receipt,
+        transport,
+        pointerUrl,
+        originalBody: response.body,
+    });
+}
+/**
+ * Create a receipt with explicit claims (bypasses context extraction)
+ *
+ * Use this when you have explicit claims and don't need context extraction.
+ * Does NOT include automatic interaction binding.
+ *
+ * @param config - Middleware configuration
+ * @param claims - Explicit claims to include
+ * @param responseBody - Optional response body for body transport
+ * @returns Receipt result
+ */
+async function createReceiptWithClaims(config, claims, responseBody) {
+    // Validate configuration
+    (0, config_js_1.validateConfig)(config);
+    // Apply defaults
+    const fullConfig = (0, config_js_1.applyDefaults)(config);
+    // Generate receipt ID
+    const rid = (0, uuidv7_1.uuidv7)();
+    // Get current timestamp
+    const iat = Math.floor(Date.now() / 1000);
+    const exp = iat + fullConfig.expiresIn;
+    // Normalize issuer
+    const normalizedIssuer = normalizeIssuer(config.issuer);
+    // Build claims
+    const receiptClaims = {
+        iss: normalizedIssuer,
+        aud: claims.aud,
+        iat,
+        exp,
+        rid,
+        ...(claims.sub && { sub: claims.sub }),
+        ...(claims.ext && { ext: claims.ext }),
+    };
+    // Sign the receipt
+    const privateKeyBytes = jwkToPrivateKeyBytes(config.signingKey);
+    const receipt = await (0, crypto_1.sign)(receiptClaims, privateKeyBytes, config.keyId);
+    // Determine transport profile
+    const transport = (0, transport_js_1.selectTransport)(receipt, fullConfig);
+    // Generate pointer URL if needed
+    let pointerUrl;
+    if (transport === 'pointer' && config.pointerUrlGenerator) {
+        pointerUrl = await config.pointerUrlGenerator(receipt);
+    }
+    // Build complete result
+    return (0, transport_js_1.buildReceiptResult)({
+        receipt,
+        transport,
+        pointerUrl,
+        originalBody: responseBody,
+    });
+}
+//# sourceMappingURL=receipt.js.map

package/dist/receipt.js.map

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

package/dist/transport.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Transport Profile Selection and Response Wrapping
+ *
+ * Implements transport profile selection and body wrapping per TRANSPORT-PROFILES.md.
+ *
+ * @packageDocumentation
+ */
+import type { MiddlewareConfig } from './types.js';
+/**
+ * Calculate receipt size and determine appropriate transport
+ *
+ * Falls back from header to body if receipt exceeds maxHeaderSize.
+ * Pointer transport is only used if explicitly configured (never auto-selected).
+ *
+ * @param receipt - JWS compact serialization
+ * @param config - Transport configuration (optional fields)
+ * @returns Selected transport profile
+ *
+ * @example
+ * ```typescript
+ * const transport = selectTransport(receipt, { maxHeaderSize: 4096 });
+ * // Returns 'header' if receipt fits, 'body' otherwise
+ *
+ * // Also accepts empty config for defaults
+ * const transport = selectTransport(receipt, {});
+ * ```
+ */
+export declare function selectTransport(receipt: string, config?: Partial<Pick<MiddlewareConfig, 'transport' | 'maxHeaderSize'>>): 'header' | 'body' | 'pointer';
+/**
+ * Wrap a response body with a PEAC receipt (for body transport profile)
+ *
+ * Creates a wrapper object containing the original data and the receipt.
+ * Per TRANSPORT-PROFILES.md, the body format is:
+ * `{ "data": <original>, "peac_receipt": "<jws>" }`
+ *
+ * @param data - Original response body
+ * @param receipt - JWS compact serialization
+ * @returns Wrapped response body
+ *
+ * @example
+ * ```typescript
+ * const original = { items: [1, 2, 3] };
+ * const wrapped = wrapResponse(original, receipt);
+ * // { data: { items: [1, 2, 3] }, peac_receipt: "eyJ..." }
+ * res.json(wrapped);
+ * ```
+ */
+export declare function wrapResponse<T>(data: T, receipt: string): {
+    data: T;
+    peac_receipt: string;
+};
+/**
+ * Build response headers for a receipt based on transport profile
+ *
+ * For header profile: adds PEAC-Receipt header
+ * For pointer profile: adds PEAC-Receipt-Pointer header
+ * For body profile: returns empty headers (receipt is in body)
+ *
+ * @param receipt - JWS compact serialization
+ * @param transport - Transport profile to use
+ * @param pointerUrl - URL for pointer profile (required if transport is 'pointer')
+ * @returns Headers to add to response
+ */
+export declare function buildResponseHeaders(receipt: string, transport: 'header' | 'body' | 'pointer', pointerUrl?: string): Promise<Record<string, string>>;
+/**
+ * Input for building complete receipt result
+ */
+export interface BuildReceiptResultInput {
+    receipt: string;
+    transport: 'header' | 'body' | 'pointer';
+    pointerUrl?: string;
+    originalBody?: unknown;
+}
+/**
+ * Build complete receipt result with headers and optional body wrapper
+ *
+ * @param input - Receipt and transport information
+ * @returns Complete receipt result ready for response
+ */
+export declare function buildReceiptResult(input: BuildReceiptResultInput): Promise<{
+    receipt: string;
+    transport: 'header' | 'body' | 'pointer';
+    headers: Record<string, string>;
+    bodyWrapper?: {
+        data: unknown;
+        peac_receipt: string;
+    };
+}>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA2CnD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,OAAO,CAAC,IAAI,CAAC,gBAAgB,EAAE,WAAW,GAAG,eAAe,CAAC,CAAM,GAC1E,QAAQ,GAAG,MAAM,GAAG,SAAS,CAsB/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAK3F;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,EACxC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA4BjC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;CACvD,CAAC,CAoBD"}