@peac/middleware-core 0.10.9

package/dist/transport.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Transport Profile Selection and Response Wrapping
+ *
+ * Implements transport profile selection and body wrapping per TRANSPORT-PROFILES.md.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectTransport = selectTransport;
+exports.wrapResponse = wrapResponse;
+exports.buildResponseHeaders = buildResponseHeaders;
+exports.buildReceiptResult = buildReceiptResult;
+const kernel_1 = require("@peac/kernel");
+const crypto_1 = require("@peac/crypto");
+const config_js_1 = require("./config.js");
+/**
+ * Maximum pointer header size (prevents oversized headers)
+ */
+const MAX_POINTER_HEADER_SIZE = 2048;
+/**
+ * Validate pointer URL for safety (SSRF prevention and header injection)
+ *
+ * @throws Error if URL is invalid or unsafe
+ */
+function validatePointerUrl(url) {
+    // Must be absolute HTTPS URL
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error('Pointer URL is not a valid URL');
+    }
+    if (parsed.protocol !== 'https:') {
+        throw new Error('Pointer URL must use HTTPS');
+    }
+    // Prevent header injection via URL content
+    // RFC 8941 quoted strings cannot contain " or \ without escaping
+    if (url.includes('"') || url.includes('\\')) {
+        throw new Error('Pointer URL contains invalid characters for structured header');
+    }
+    // Control characters are never valid in headers
+    // eslint-disable-next-line no-control-regex
+    if (/[\x00-\x1f\x7f]/.test(url)) {
+        throw new Error('Pointer URL contains control characters');
+    }
+    // Sanity check on length to prevent oversized headers
+    if (url.length > MAX_POINTER_HEADER_SIZE) {
+        throw new Error(`Pointer URL exceeds maximum length (${MAX_POINTER_HEADER_SIZE})`);
+    }
+}
+/**
+ * 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, {});
+ * ```
+ */
+function selectTransport(receipt, config = {}) {
+    const preferredTransport = config.transport ?? config_js_1.CONFIG_DEFAULTS.transport;
+    const maxHeaderSize = config.maxHeaderSize ?? config_js_1.CONFIG_DEFAULTS.maxHeaderSize;
+    // Pointer is only used when explicitly configured
+    if (preferredTransport === 'pointer') {
+        return 'pointer';
+    }
+    // Body is used when explicitly configured
+    if (preferredTransport === 'body') {
+        return 'body';
+    }
+    // For header preference, check size and fallback to body if needed
+    // Header profile uses the receipt directly as the header value
+    const receiptBytes = new TextEncoder().encode(receipt);
+    if (receiptBytes.length > maxHeaderSize) {
+        return 'body';
+    }
+    return 'header';
+}
+/**
+ * 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);
+ * ```
+ */
+function wrapResponse(data, receipt) {
+    return {
+        data,
+        peac_receipt: receipt,
+    };
+}
+/**
+ * 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
+ */
+async function buildResponseHeaders(receipt, transport, pointerUrl) {
+    switch (transport) {
+        case 'header':
+            return {
+                [kernel_1.HEADERS.receipt]: receipt,
+            };
+        case 'pointer': {
+            if (!pointerUrl) {
+                throw new Error('pointerUrl is required for pointer transport');
+            }
+            // Validate pointer URL (SSRF prevention, header injection prevention)
+            validatePointerUrl(pointerUrl);
+            // Compute SHA-256 digest of receipt (lowercase hex)
+            const digestHex = await (0, crypto_1.sha256Hex)(receipt);
+            // RFC 8941 structured header dictionary format with quoted strings
+            return {
+                [kernel_1.HEADERS.receiptPointer]: `sha256="${digestHex}", url="${pointerUrl}"`,
+            };
+        }
+        case 'body':
+            // No headers for body profile
+            return {};
+        default:
+            throw new Error(`Unknown transport profile: ${transport}`);
+    }
+}
+/**
+ * Build complete receipt result with headers and optional body wrapper
+ *
+ * @param input - Receipt and transport information
+ * @returns Complete receipt result ready for response
+ */
+async function buildReceiptResult(input) {
+    const headers = await buildResponseHeaders(input.receipt, input.transport, input.pointerUrl);
+    const result = {
+        receipt: input.receipt,
+        transport: input.transport,
+        headers,
+    };
+    // Add body wrapper for body transport
+    if (input.transport === 'body' && input.originalBody !== undefined) {
+        result.bodyWrapper = wrapResponse(input.originalBody, input.receipt);
+    }
+    return result;
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,131 @@
+/**
+ * PEAC Middleware Core Types
+ *
+ * Framework-agnostic type definitions for PEAC receipt issuance middleware.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Ed25519 private key in JWK format
+ */
+export interface Ed25519PrivateJwk {
+    kty: 'OKP';
+    crv: 'Ed25519';
+    /** Public key (base64url, 32 bytes) */
+    x: string;
+    /** Private key (base64url, 32 bytes) */
+    d: string;
+}
+/**
+ * Interaction binding mode for privacy control
+ *
+ * - 'minimal': Include method, path (no query), status (default)
+ * - 'off': Do not include interaction binding
+ * - 'full': Include method, full path with query string, status
+ */
+export type InteractionBindingMode = 'minimal' | 'off' | 'full';
+/**
+ * Middleware configuration for PEAC receipt issuance
+ */
+export interface MiddlewareConfig {
+    /** Issuer URL (becomes `iss` claim). Must be HTTPS. */
+    issuer: string;
+    /** Ed25519 private key in JWK format */
+    signingKey: Ed25519PrivateJwk;
+    /** Key ID for JWKS lookup (appears in JWS header `kid`) */
+    keyId: string;
+    /** Receipt expiration in seconds (default: 300) */
+    expiresIn?: number;
+    /** Transport profile preference (default: 'header') */
+    transport?: 'header' | 'body' | 'pointer';
+    /** Maximum header size in bytes before fallback to body (default: 4096) */
+    maxHeaderSize?: number;
+    /**
+     * Interaction binding mode (default: 'minimal')
+     *
+     * Controls what request/response data is included in the receipt:
+     * - 'minimal': method, path (no query string), status (default, privacy-safe)
+     * - 'off': No interaction binding included
+     * - 'full': method, full path with query string, status
+     *
+     * Privacy note: Query strings often contain API keys, tokens, or PII.
+     * Use 'minimal' (default) unless you explicitly need query parameters.
+     */
+    interactionBinding?: InteractionBindingMode;
+    /** Pointer URL generator for 'pointer' transport */
+    pointerUrlGenerator?: (receipt: string) => Promise<string>;
+    /** Custom claims generator */
+    claimsGenerator?: (context: RequestContext) => Promise<Partial<ReceiptClaimsInput>>;
+}
+/**
+ * Request context captured for receipt generation
+ */
+export interface RequestContext {
+    /** HTTP method (GET, POST, etc.) */
+    method: string;
+    /** Request path (e.g., '/api/data') */
+    path: string;
+    /** Request headers */
+    headers: Record<string, string | string[] | undefined>;
+    /** Request body (if available) */
+    body?: unknown;
+    /** Request timestamp (Unix milliseconds) */
+    timestamp: number;
+}
+/**
+ * Response context for receipt generation
+ */
+export interface ResponseContext {
+    /** HTTP status code */
+    statusCode: number;
+    /** Response headers */
+    headers: Record<string, string | string[] | undefined>;
+    /** Response body (if available) */
+    body?: unknown;
+}
+/**
+ * Custom claims that can be added to receipts
+ */
+export interface ReceiptClaimsInput {
+    /** Subject identifier (optional) */
+    sub?: string;
+    /** Audience override (defaults to request origin) */
+    aud?: string;
+    /** Additional extensions */
+    ext?: Record<string, unknown>;
+}
+/**
+ * Result of receipt creation
+ */
+export interface ReceiptResult {
+    /** JWS compact serialization of the receipt */
+    receipt: string;
+    /** Transport profile used */
+    transport: 'header' | 'body' | 'pointer';
+    /** Headers to add to the response */
+    headers: Record<string, string>;
+    /** Wrapped body (for body transport profile) */
+    bodyWrapper?: {
+        data: unknown;
+        peac_receipt: string;
+    };
+}
+/**
+ * Validation error for middleware configuration
+ */
+export interface ConfigValidationError {
+    field: string;
+    message: string;
+}
+/**
+ * Transport profile selection input
+ */
+export interface TransportSelectionInput {
+    /** Receipt JWS string */
+    receipt: string;
+    /** Preferred transport from config */
+    transport?: 'header' | 'body' | 'pointer';
+    /** Maximum header size */
+    maxHeaderSize?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * PEAC Middleware Core Types
+ *
+ * Framework-agnostic type definitions for PEAC receipt issuance middleware.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@peac/middleware-core",
+  "version": "0.10.9",
+  "description": "Framework-agnostic middleware primitives for PEAC receipt issuance",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/peacprotocol/peac.git",
+    "directory": "packages/middleware-core"
+  },
+  "author": "jithinraj <7850727+jithinraj@users.noreply.github.com>",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/peacprotocol/peac/issues"
+  },
+  "homepage": "https://github.com/peacprotocol/peac#readme",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "uuidv7": "^0.6.3",
+    "@peac/kernel": "0.10.9",
+    "@peac/schema": "0.10.9",
+    "@peac/crypto": "0.10.9"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.1.0"
+  },
+  "scripts": {
+    "prebuild": "rm -rf dist tsconfig.tsbuildinfo",
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  }
+}