@webpieces/http-server 0.4.641 → 0.4.642

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/http-server",
-  "version": "0.4.641",
+  "version": "0.4.642",
   "description": "WebPieces server with filter chain and dependency injection",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -22,10 +22,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@webpieces/core-context": "0.4.641",
-    "@webpieces/core-util": "0.4.641",
-    "@webpieces/gcp-identity": "0.4.641",
-    "@webpieces/http-routing": "0.4.641",
+    "@webpieces/core-context": "0.4.642",
+    "@webpieces/core-util": "0.4.642",
+    "@webpieces/gcp-identity": "0.4.642",
+    "@webpieces/http-routing": "0.4.642",
     "cors": "2.8.5",
     "express": "5.1.0",
     "inversify": "7.10.4"

package/src/ExpressWrapper.d.ts

@@ -1,5 +1,15 @@
 import { Request, Response, NextFunction } from 'express';
 import { RequestContextHeaders } from '@webpieces/core-context';
+/**
+ * The cap on an inbound body, in bytes. Reading stops and the request is refused the moment a body
+ * crosses it — the bytes already read are dropped, nothing further is buffered.
+ *
+ * There was NO limit at all before, which was a latent memory DoS on every route and an outright one
+ * on a webhook route: `{ rawBody: true }` retains what it reads, and a webhook url is public by
+ * construction, so the endpoint most likely to be flooded was also the one that held on to the flood.
+ * 10 MiB is comfortably above any api DTO and well under Cloud Run's own 32 MiB request limit.
+ */
+export declare const MAX_BODY_BYTES: number;
 export declare class ExpressWrapper {
     private clientMethod;
     private path;
@@ -11,6 +21,15 @@ export declare class ExpressWrapper {
      * the request Content-Type header — the annotation is the single source of truth.
      */
     private formPost;
+    /**
+     * True for an @Endpoint(..., { rawBody: true }) route: RETAIN the verbatim bytes + the
+     * absolute url on the published {@link HttpRequest}, so an @AuthWebhook hook can verify a
+     * vendor signature over what the sender actually transmitted. Also switches the JSON parse
+     * failure from "throw now" to "hold it for AuthFilter" — see {@link RawRequest.bodyParseError}.
+     */
+    private rawBody;
+    /** The inbound body cap for this route. See {@link MAX_BODY_BYTES}. */
+    private maxBodyBytes;
     constructor(clientMethod: (requestDto: unknown) => Promise<unknown>, path: string, 
     /** Owns the wire<->context transfer, both directions. Stateless framework singleton. */
     headers: RequestContextHeaders, 
@@ -19,7 +38,16 @@ export declare class ExpressWrapper {
      * application/x-www-form-urlencoded (flat) instead of JSON. Driven by the ANNOTATION, not
      * the request Content-Type header — the annotation is the single source of truth.
      */
-    formPost?: boolean);
+    formPost?: boolean, 
+    /**
+     * True for an @Endpoint(..., { rawBody: true }) route: RETAIN the verbatim bytes + the
+     * absolute url on the published {@link HttpRequest}, so an @AuthWebhook hook can verify a
+     * vendor signature over what the sender actually transmitted. Also switches the JSON parse
+     * failure from "throw now" to "hold it for AuthFilter" — see {@link RawRequest.bodyParseError}.
+     */
+    rawBody?: boolean, 
+    /** The inbound body cap for this route. See {@link MAX_BODY_BYTES}. */
+    maxBodyBytes?: number);
     execute(req: Request, res: Response, next: NextFunction): Promise<void>;
     executeTryCatch(req: Request, res: Response, next: NextFunction): Promise<void>;
     executeImpl(req: Request, res: Response, next: NextFunction): Promise<void>;
@@ -35,10 +63,34 @@ export declare class ExpressWrapper {
      * in-process with no transport at all.
      */
     private toWebpiecesRequest;
+    /**
+     * The absolute url AS THE SENDER ADDRESSED IT — the string a vendor like Twilio signed.
+     *
+     * `x-forwarded-proto` / `x-forwarded-host` WIN when present, because behind a TLS-terminating
+     * proxy (Cloud Run, any load balancer) express's own view is wrong in both halves: `req.protocol`
+     * reads `http` and the Host header is the internal one, while the vendor signed the public
+     * `https://...` url the customer configured. Reconstructing naively therefore fails 100% of the
+     * time in production and works 100% of the time locally — the worst possible pairing, so this is
+     * stated here and pinned by a test rather than left to each app.
+     *
+     * These headers are attacker-controllable when nothing strips them, and that is ACCEPTABLE here
+     * precisely because of what the value is used for: a forged url produces a signature that does not
+     * verify, i.e. a 401. It grants nothing. (It is used for verification only — never for a redirect.)
+     */
+    private absoluteUrl;
+    private firstForwarded;
     private readExpressHeaders;
     /**
-     * Read raw request body as text.
-     * Used to manually parse JSON (instead of express.json() middleware).
+     * Read the raw request body as BYTES (we parse manually rather than mounting express.json()).
+     *
+     * Bytes, not a growing string: a per-chunk `toString()` splits any multi-byte character that
+     * straddles a chunk boundary into two replacement characters, so the body a webhook hook verified
+     * would not be the body the vendor signed.
+     *
+     * REFUSES a body over {@link maxBodyBytes} the moment it crosses the line — the chunks read so far
+     * are dropped and the stream is destroyed, so an oversize body is never fully buffered. It answers
+     * 400 rather than 401 even on a webhook route, unavoidably: there is no way to authenticate a
+     * caller whose request we are refusing to finish reading, and that ordering is the point.
      */
     private readRequestBody;
     /**

package/src/ExpressWrapper.js

@@ -1,16 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ExpressWrapper = void 0;
+exports.ExpressWrapper = exports.MAX_BODY_BYTES = void 0;
 const core_util_1 = require("@webpieces/core-util");
 const core_context_1 = require("@webpieces/core-context");
 // The logging backend prepends this logger name to every line, so messages below carry NO
 // "[ExpressWrapper]" literal of their own — that would print the name twice.
 const log = core_util_1.LogManager.getLogger('ExpressWrapper');
+/**
+ * The cap on an inbound body, in bytes. Reading stops and the request is refused the moment a body
+ * crosses it — the bytes already read are dropped, nothing further is buffered.
+ *
+ * There was NO limit at all before, which was a latent memory DoS on every route and an outright one
+ * on a webhook route: `{ rawBody: true }` retains what it reads, and a webhook url is public by
+ * construction, so the endpoint most likely to be flooded was also the one that held on to the flood.
+ * 10 MiB is comfortably above any api DTO and well under Cloud Run's own 32 MiB request limit.
+ */
+exports.MAX_BODY_BYTES = 10 * 1024 * 1024;
 class ExpressWrapper {
     clientMethod;
     path;
     headers;
     formPost;
+    rawBody;
+    maxBodyBytes;
     constructor(
     // webpieces-disable no-any-unknown -- request/response DTOs are erased at the routing boundary
     clientMethod, path, 
@@ -21,11 +33,22 @@ class ExpressWrapper {
      * application/x-www-form-urlencoded (flat) instead of JSON. Driven by the ANNOTATION, not
      * the request Content-Type header — the annotation is the single source of truth.
      */
-    formPost = false) {
+    formPost = false, 
+    /**
+     * True for an @Endpoint(..., { rawBody: true }) route: RETAIN the verbatim bytes + the
+     * absolute url on the published {@link HttpRequest}, so an @AuthWebhook hook can verify a
+     * vendor signature over what the sender actually transmitted. Also switches the JSON parse
+     * failure from "throw now" to "hold it for AuthFilter" — see {@link RawRequest.bodyParseError}.
+     */
+    rawBody = false, 
+    /** The inbound body cap for this route. See {@link MAX_BODY_BYTES}. */
+    maxBodyBytes = exports.MAX_BODY_BYTES) {
         this.clientMethod = clientMethod;
         this.path = path;
         this.headers = headers;
         this.formPost = formPost;
+        this.rawBody = rawBody;
+        this.maxBodyBytes = maxBodyBytes;
     }
     async execute(req, res, next) {
         // MOVED: Wrap entire request in RequestContext.run()
@@ -46,14 +69,18 @@ class ExpressWrapper {
         }
     }
     async executeImpl(req, res, next) {
-        // 1. Translate express's request into the transport-neutral HttpRequest webpieces speaks.
-        const httpRequest = this.toWebpiecesRequest(req);
-        // 2. Parse the request body. The PARSER is chosen by the @Endpoint annotation (this.formPost),
+        // 1. Parse the request body. The PARSER is chosen by the @Endpoint annotation (this.formPost),
         //    NOT the request Content-Type header — the annotation is the single source of truth.
         // webpieces-disable no-any-unknown -- request/response DTOs are erased at the routing boundary
         let requestDto = {};
+        let raw;
         if (['POST', 'PUT', 'PATCH'].includes(req.method)) {
-            const bodyText = await this.readRequestBody(req);
+            // Read BYTES, not text. Concatenating per-chunk toString() corrupted any multi-byte
+            // character that straddled a chunk boundary — invisible on small bodies, and fatal for a
+            // signature computed over the bytes.
+            const bodyBytes = await this.readRequestBody(req);
+            const bodyText = bodyBytes.toString('utf8');
+            let parseError;
             if (this.formPost) {
                 // application/x-www-form-urlencoded → flat key→value. URLSearchParams is lenient
                 // (never throws) — right for EXTERNAL webhooks (e.g. Twilio) that post form-encoded.
@@ -68,10 +95,21 @@ class ExpressWrapper {
                 }
                 catch (err) {
                     const error = (0, core_util_1.toError)(err);
-                    throw new core_util_1.HttpBadRequestError('Request body is not valid JSON', undefined, undefined, error);
+                    // On a raw-body (webhook) route the failure is HELD, not thrown: AuthFilter must
+                    // answer 401 to an unauthenticated caller rather than 400, because "your JSON was
+                    // bad" tells that caller it got past auth. Everywhere else, fail now as before.
+                    if (!this.rawBody) {
+                        throw new core_util_1.HttpBadRequestError('Request body is not valid JSON', undefined, undefined, error);
+                    }
+                    parseError = error;
                 }
             }
+            if (this.rawBody) {
+                raw = new core_context_1.RawRequest(this.absoluteUrl(req), bodyBytes, req.socket?.remoteAddress, parseError);
+            }
         }
+        // 2. Translate express's request into the transport-neutral HttpRequest webpieces speaks.
+        const httpRequest = this.toWebpiecesRequest(req, raw);
         // 3. Publish the transport-neutral HttpRequest, then move its headers into the context and
         //    mint a request id if the caller sent none. BOTH happen above the api boundary, because
         //    http-routing requires an already-established, already-filled request scope — it never
@@ -95,8 +133,35 @@ class ExpressWrapper {
      * filter chain and controllers never see express, which is what lets the same chain run
      * in-process with no transport at all.
      */
-    toWebpiecesRequest(req) {
-        return new core_context_1.HttpRequest(req.method, this.path, this.readExpressHeaders(req));
+    toWebpiecesRequest(req, raw) {
+        return new core_context_1.HttpRequest(req.method, this.path, this.readExpressHeaders(req), raw);
+    }
+    /**
+     * The absolute url AS THE SENDER ADDRESSED IT — the string a vendor like Twilio signed.
+     *
+     * `x-forwarded-proto` / `x-forwarded-host` WIN when present, because behind a TLS-terminating
+     * proxy (Cloud Run, any load balancer) express's own view is wrong in both halves: `req.protocol`
+     * reads `http` and the Host header is the internal one, while the vendor signed the public
+     * `https://...` url the customer configured. Reconstructing naively therefore fails 100% of the
+     * time in production and works 100% of the time locally — the worst possible pairing, so this is
+     * stated here and pinned by a test rather than left to each app.
+     *
+     * These headers are attacker-controllable when nothing strips them, and that is ACCEPTABLE here
+     * precisely because of what the value is used for: a forged url produces a signature that does not
+     * verify, i.e. a 401. It grants nothing. (It is used for verification only — never for a redirect.)
+     */
+    absoluteUrl(req) {
+        const forwardedProto = req.headers['x-forwarded-proto'];
+        const forwardedHost = req.headers['x-forwarded-host'];
+        // A proxy chain sends a comma-separated list; the FIRST entry is the original client's hop.
+        const proto = this.firstForwarded(forwardedProto) ?? req.protocol;
+        const host = this.firstForwarded(forwardedHost) ?? req.get('host') ?? '';
+        return `${proto}://${host}${req.originalUrl ?? req.url ?? this.path}`;
+    }
+    firstForwarded(value) {
+        const raw = Array.isArray(value) ? value[0] : value;
+        const first = raw?.split(',')[0]?.trim();
+        return first === undefined || first === '' ? undefined : first;
     }
     readExpressHeaders(req) {
         const headers = new Map();
@@ -113,17 +178,37 @@ class ExpressWrapper {
         return headers;
     }
     /**
-     * Read raw request body as text.
-     * Used to manually parse JSON (instead of express.json() middleware).
+     * Read the raw request body as BYTES (we parse manually rather than mounting express.json()).
+     *
+     * Bytes, not a growing string: a per-chunk `toString()` splits any multi-byte character that
+     * straddles a chunk boundary into two replacement characters, so the body a webhook hook verified
+     * would not be the body the vendor signed.
+     *
+     * REFUSES a body over {@link maxBodyBytes} the moment it crosses the line — the chunks read so far
+     * are dropped and the stream is destroyed, so an oversize body is never fully buffered. It answers
+     * 400 rather than 401 even on a webhook route, unavoidably: there is no way to authenticate a
+     * caller whose request we are refusing to finish reading, and that ordering is the point.
      */
     async readRequestBody(req) {
         return new Promise((resolve, reject) => {
-            let body = '';
-            req.on('data', (chunk) => {
-                body += chunk.toString();
+            let chunks = [];
+            let size = 0;
+            // A socket emits Buffers; a stream someone put in string mode (or a test's Readable.from)
+            // emits strings. Normalize to bytes ONCE, here, so everything downstream counts and
+            // concatenates the same units.
+            req.on('data', (data) => {
+                const chunk = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');
+                size += chunk.length;
+                if (size > this.maxBodyBytes) {
+                    chunks = [];
+                    req.destroy();
+                    reject(new core_util_1.HttpBadRequestError(`Request body exceeds the ${this.maxBodyBytes} byte limit`));
+                    return;
+                }
+                chunks.push(chunk);
             });
             req.on('end', () => {
-                resolve(body);
+                resolve(Buffer.concat(chunks));
             });
             req.on('error', (err) => {
                 reject(err);

package/src/ExpressWrapper.js.map

@@ -1 +1 @@
-{"version":3,"file":"ExpressWrapper.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/ExpressWrapper.ts"],"names":[],"mappings":"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","sourcesContent":["import { Request, Response, NextFunction } from 'express';\nimport {\n    ProtocolError,\n    ClientRegistry,\n    HttpError,\n    HttpBadRequestError,\n    HttpVendorError,\n    HttpUserError,\n    HttpNotFoundError,\n    HttpTimeoutError,\n    HttpUnauthorizedError,\n    HttpForbiddenError,\n    HttpInternalServerError,\n    HttpBadGatewayError,\n    HttpGatewayTimeoutError,\n    toError,\n    LogManager,\n} from '@webpieces/core-util';\nimport { RequestContext, HttpRequest, RequestContextHeaders } from '@webpieces/core-context';\n\n// The logging backend prepends this logger name to every line, so messages below carry NO\n// \"[ExpressWrapper]\" literal of their own — that would print the name twice.\nconst log = LogManager.getLogger('ExpressWrapper');\n\nexport class ExpressWrapper {\n    constructor(\n        // webpieces-disable no-any-unknown -- request/response DTOs are erased at the routing boundary\n        private clientMethod: (requestDto: unknown) => Promise<unknown>,\n        private path: string,\n        /** Owns the wire<->context transfer, both directions. Stateless framework singleton. */\n        private headers: RequestContextHeaders,\n        /**\n         * True for an @Endpoint(..., { formPost: true }) route: parse the body as\n         * application/x-www-form-urlencoded (flat) instead of JSON. Driven by the ANNOTATION, not\n         * the request Content-Type header — the annotation is the single source of truth.\n         */\n        private formPost: boolean = false,\n    ) {\n    }\n\n    public async execute(req: Request, res: Response, next: NextFunction): Promise<void> {\n        // MOVED: Wrap entire request in RequestContext.run()\n        // This establishes AsyncLocalStorage context for the request\n        await RequestContext.run(async () => {\n            await this.executeTryCatch(req, res, next);\n        });\n    }\n\n    public async executeTryCatch(req: Request, res: Response, next: NextFunction): Promise<void> {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- ExpressWrapper catches errors to translate to HTTP responses\n        try {\n            await this.executeImpl(req, res, next);\n        } catch (err: unknown) {\n            const error = toError(err);\n            // 5. Handle errors\n            this.handleError(res, error);\n        }\n    }\n\n    public async executeImpl(req: Request, res: Response, next: NextFunction): Promise<void> {\n        // 1. Translate express's request into the transport-neutral HttpRequest webpieces speaks.\n        const httpRequest = this.toWebpiecesRequest(req);\n\n        // 2. Parse the request body. The PARSER is chosen by the @Endpoint annotation (this.formPost),\n        //    NOT the request Content-Type header — the annotation is the single source of truth.\n        // webpieces-disable no-any-unknown -- request/response DTOs are erased at the routing boundary\n        let requestDto: unknown = {};\n        if (['POST', 'PUT', 'PATCH'].includes(req.method)) {\n            const bodyText = await this.readRequestBody(req);\n            if (this.formPost) {\n                // application/x-www-form-urlencoded → flat key→value. URLSearchParams is lenient\n                // (never throws) — right for EXTERNAL webhooks (e.g. Twilio) that post form-encoded.\n                requestDto = Object.fromEntries(new URLSearchParams(bodyText));\n            } else {\n                // JSON (default, SYMMETRIC with the client's JSON.stringify). A non-JSON body is a\n                // CLIENT error → 400, not the raw 500 an unguarded JSON.parse would throw.\n                // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- translate parse failure to a 400 HttpError\n                try {\n                    requestDto = bodyText ? JSON.parse(bodyText) : {};\n                } catch (err: unknown) {\n                    const error = toError(err);\n                    throw new HttpBadRequestError('Request body is not valid JSON', undefined, undefined, error);\n                }\n            }\n        }\n\n        // 3. Publish the transport-neutral HttpRequest, then move its headers into the context and\n        //    mint a request id if the caller sent none. BOTH happen above the api boundary, because\n        //    http-routing requires an already-established, already-filled request scope — it never\n        //    builds one for you. This is the \"translation layer\" every transport must provide.\n        this.headers.fillFromRequest(httpRequest);\n\n        // 4. Invoke the api CLIENT method — the SAME proxy tests use. Its filter chain + controller\n        //    run here, reading the context filled above; the chain never touches express `req`.\n        const result = await this.clientMethod(requestDto);\n\n        // 5. Serialize the response DTO to JSON (SYMMETRIC with client's response.json())\n        const responseJson = JSON.stringify(result);\n        res.status(200).setHeader('Content-Type', 'application/json').send(responseJson);\n    }\n\n    /**\n     * Read HTTP headers from Express request.\n     * Returns Map of header name (lowercase) -> array of values.\n     *\n     * HTTP spec allows multiple values for same header name.\n     */\n    /**\n     * express Request -> webpieces {@link HttpRequest}. THE translation layer: below this line the\n     * filter chain and controllers never see express, which is what lets the same chain run\n     * in-process with no transport at all.\n     */\n    private toWebpiecesRequest(req: Request): HttpRequest {\n        return new HttpRequest(req.method, this.path, this.readExpressHeaders(req));\n    }\n\n    private readExpressHeaders(req: Request): Map<string, string[]> {\n        const headers = new Map<string, string[]>();\n\n        // Express stores headers in req.headers as Record<string, string | string[]>\n        for (const [name, value] of Object.entries(req.headers)) {\n            const lowerName = name.toLowerCase();\n\n            if (typeof value === 'string') {\n                headers.set(lowerName, [value]);\n            } else if (Array.isArray(value)) {\n                headers.set(lowerName, value);\n            }\n        }\n\n        return headers;\n    }\n\n    /**\n     * Read raw request body as text.\n     * Used to manually parse JSON (instead of express.json() middleware).\n     */\n    private async readRequestBody(req: Request): Promise<string> {\n        return new Promise((resolve: (body: string) => void, reject: (err: Error) => void) => {\n            let body = '';\n            req.on('data', (chunk: Buffer) => {\n                body += chunk.toString();\n            });\n            req.on('end', () => {\n                resolve(body);\n            });\n            req.on('error', (err: Error) => {\n                reject(err);\n            });\n        });\n    }\n\n    /**\n     * Handle errors - translate to JSON ProtocolError (SYMMETRIC with ClientErrorTranslator).\n     * PUBLIC so wrapExpress can call it for symmetric error handling.\n     * Maps HttpError subclasses to appropriate HTTP status codes and ProtocolError response.\n     *\n     * Maps all HttpError types (must match ClientErrorTranslator.translateError()):\n     * - HttpUserError → 266 (with errorCode)\n     * - HttpBadRequestError → 400 (with field, guiAlertMessage)\n     * - HttpUnauthorizedError → 401\n     * - HttpForbiddenError → 403\n     * - HttpNotFoundError → 404\n     * - HttpTimeoutError → 408\n     * - HttpInternalServerError → 500\n     * - HttpBadGatewayError → 502\n     * - HttpGatewayTimeoutError → 504\n     * - HttpVendorError → 598 (with waitSeconds)\n     */\n    // webpieces-disable no-any-unknown -- a thrown error is genuinely unknown until narrowed below\n    public handleError(res: Response, error: unknown): void {\n        if (res.headersSent) {\n            return;\n        }\n\n        // App-registered translations win, so an app can serialize its OWN error types (e.g. a\n        // custom 460) AND override built-ins. `undefined` means \"not mine\" — fall through to the\n        // built-in instanceof-HttpError ladder below, which stays the generic default. Symmetric\n        // with the client's ClientErrorTranslator, which consults tryTranslateFromWire() first.\n        if (error instanceof Error) {\n            const wire = ClientRegistry.tryTranslateToWire(error);\n            if (wire !== undefined) {\n                res.status(wire.statusCode)\n                    .setHeader('Content-Type', 'application/json')\n                    .send(JSON.stringify(wire.protocolError));\n                return;\n            }\n        }\n\n        const protocolError = new ProtocolError();\n\n        if (error instanceof HttpError) {\n            // Set common fields for all HttpError types\n            protocolError.message = error.message;\n            protocolError.subType = error.subType;\n            protocolError.name = error.name;\n\n            // Set type-specific fields (MUST match ClientErrorTranslator)\n            if (error instanceof HttpUserError) {\n                log.info(`User Error: ${error.message}`);\n                protocolError.errorCode = error.errorCode;\n            } else if (error instanceof HttpBadRequestError) {\n                log.info(`Bad Request: ${error.message}`);\n                protocolError.field = error.field;\n                protocolError.guiAlertMessage = error.guiMessage;\n            } else if (error instanceof HttpNotFoundError) {\n                log.info(`Not Found: ${error.message}`);\n            } else if (error instanceof HttpTimeoutError) {\n                log.error(`Timeout Error: ${error.message}`);\n            } else if (error instanceof HttpVendorError) {\n                log.error(`Vendor Error: ${error.message}`);\n                protocolError.waitSeconds = error.waitSeconds;\n            } else if (error instanceof HttpUnauthorizedError) {\n                log.info(`Unauthorized: ${error.message}`);\n            } else if (error instanceof HttpForbiddenError) {\n                log.info(`Forbidden: ${error.message}`);\n            } else if (error instanceof HttpInternalServerError) {\n                log.error(`Internal Server Error: ${error.message}`);\n            } else if (error instanceof HttpBadGatewayError) {\n                log.error(`Bad Gateway: ${error.message}`);\n            } else if (error instanceof HttpGatewayTimeoutError) {\n                log.error(`Gateway Timeout: ${error.message}`);\n            } else {\n                log.info(`Generic HttpError: ${error.message}`);\n            }\n\n            // Serialize ProtocolError to JSON (SYMMETRIC with client)\n            const responseJson = JSON.stringify(protocolError);\n            res.status(error.code).setHeader('Content-Type', 'application/json').send(responseJson);\n        } else {\n            // Unknown error - 500\n            const err = toError(error);\n            protocolError.message = 'Internal Server Error';\n            log.error('Unexpected error:', err);\n            const responseJson = JSON.stringify(protocolError);\n            res.status(500).setHeader('Content-Type', 'application/json').send(responseJson);\n        }\n    }\n}\n"]}
+{"version":3,"file":"ExpressWrapper.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/ExpressWrapper.ts"],"names":[],"mappings":"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","sourcesContent":["import { Request, Response, NextFunction } from 'express';\nimport {\n    ProtocolError,\n    ClientRegistry,\n    HttpError,\n    HttpBadRequestError,\n    HttpVendorError,\n    HttpUserError,\n    HttpNotFoundError,\n    HttpTimeoutError,\n    HttpUnauthorizedError,\n    HttpForbiddenError,\n    HttpInternalServerError,\n    HttpBadGatewayError,\n    HttpGatewayTimeoutError,\n    toError,\n    LogManager,\n} from '@webpieces/core-util';\nimport { RequestContext, HttpRequest, RawRequest, RequestContextHeaders } from '@webpieces/core-context';\n\n// The logging backend prepends this logger name to every line, so messages below carry NO\n// \"[ExpressWrapper]\" literal of their own — that would print the name twice.\nconst log = LogManager.getLogger('ExpressWrapper');\n\n/**\n * The cap on an inbound body, in bytes. Reading stops and the request is refused the moment a body\n * crosses it — the bytes already read are dropped, nothing further is buffered.\n *\n * There was NO limit at all before, which was a latent memory DoS on every route and an outright one\n * on a webhook route: `{ rawBody: true }` retains what it reads, and a webhook url is public by\n * construction, so the endpoint most likely to be flooded was also the one that held on to the flood.\n * 10 MiB is comfortably above any api DTO and well under Cloud Run's own 32 MiB request limit.\n */\nexport const MAX_BODY_BYTES = 10 * 1024 * 1024;\n\nexport class ExpressWrapper {\n    constructor(\n        // webpieces-disable no-any-unknown -- request/response DTOs are erased at the routing boundary\n        private clientMethod: (requestDto: unknown) => Promise<unknown>,\n        private path: string,\n        /** Owns the wire<->context transfer, both directions. Stateless framework singleton. */\n        private headers: RequestContextHeaders,\n        /**\n         * True for an @Endpoint(..., { formPost: true }) route: parse the body as\n         * application/x-www-form-urlencoded (flat) instead of JSON. Driven by the ANNOTATION, not\n         * the request Content-Type header — the annotation is the single source of truth.\n         */\n        private formPost: boolean = false,\n        /**\n         * True for an @Endpoint(..., { rawBody: true }) route: RETAIN the verbatim bytes + the\n         * absolute url on the published {@link HttpRequest}, so an @AuthWebhook hook can verify a\n         * vendor signature over what the sender actually transmitted. Also switches the JSON parse\n         * failure from \"throw now\" to \"hold it for AuthFilter\" — see {@link RawRequest.bodyParseError}.\n         */\n        private rawBody: boolean = false,\n        /** The inbound body cap for this route. See {@link MAX_BODY_BYTES}. */\n        private maxBodyBytes: number = MAX_BODY_BYTES,\n    ) {\n    }\n\n    public async execute(req: Request, res: Response, next: NextFunction): Promise<void> {\n        // MOVED: Wrap entire request in RequestContext.run()\n        // This establishes AsyncLocalStorage context for the request\n        await RequestContext.run(async () => {\n            await this.executeTryCatch(req, res, next);\n        });\n    }\n\n    public async executeTryCatch(req: Request, res: Response, next: NextFunction): Promise<void> {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- ExpressWrapper catches errors to translate to HTTP responses\n        try {\n            await this.executeImpl(req, res, next);\n        } catch (err: unknown) {\n            const error = toError(err);\n            // 5. Handle errors\n            this.handleError(res, error);\n        }\n    }\n\n    public async executeImpl(req: Request, res: Response, next: NextFunction): Promise<void> {\n        // 1. Parse the request body. The PARSER is chosen by the @Endpoint annotation (this.formPost),\n        //    NOT the request Content-Type header — the annotation is the single source of truth.\n        // webpieces-disable no-any-unknown -- request/response DTOs are erased at the routing boundary\n        let requestDto: unknown = {};\n        let raw: RawRequest | undefined;\n        if (['POST', 'PUT', 'PATCH'].includes(req.method)) {\n            // Read BYTES, not text. Concatenating per-chunk toString() corrupted any multi-byte\n            // character that straddled a chunk boundary — invisible on small bodies, and fatal for a\n            // signature computed over the bytes.\n            const bodyBytes = await this.readRequestBody(req);\n            const bodyText = bodyBytes.toString('utf8');\n            let parseError: Error | undefined;\n            if (this.formPost) {\n                // application/x-www-form-urlencoded → flat key→value. URLSearchParams is lenient\n                // (never throws) — right for EXTERNAL webhooks (e.g. Twilio) that post form-encoded.\n                requestDto = Object.fromEntries(new URLSearchParams(bodyText));\n            } else {\n                // JSON (default, SYMMETRIC with the client's JSON.stringify). A non-JSON body is a\n                // CLIENT error → 400, not the raw 500 an unguarded JSON.parse would throw.\n                // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- translate parse failure to a 400 HttpError\n                try {\n                    requestDto = bodyText ? JSON.parse(bodyText) : {};\n                } catch (err: unknown) {\n                    const error = toError(err);\n                    // On a raw-body (webhook) route the failure is HELD, not thrown: AuthFilter must\n                    // answer 401 to an unauthenticated caller rather than 400, because \"your JSON was\n                    // bad\" tells that caller it got past auth. Everywhere else, fail now as before.\n                    if (!this.rawBody) {\n                        throw new HttpBadRequestError('Request body is not valid JSON', undefined, undefined, error);\n                    }\n                    parseError = error;\n                }\n            }\n            if (this.rawBody) {\n                raw = new RawRequest(this.absoluteUrl(req), bodyBytes, req.socket?.remoteAddress, parseError);\n            }\n        }\n\n        // 2. Translate express's request into the transport-neutral HttpRequest webpieces speaks.\n        const httpRequest = this.toWebpiecesRequest(req, raw);\n\n        // 3. Publish the transport-neutral HttpRequest, then move its headers into the context and\n        //    mint a request id if the caller sent none. BOTH happen above the api boundary, because\n        //    http-routing requires an already-established, already-filled request scope — it never\n        //    builds one for you. This is the \"translation layer\" every transport must provide.\n        this.headers.fillFromRequest(httpRequest);\n\n        // 4. Invoke the api CLIENT method — the SAME proxy tests use. Its filter chain + controller\n        //    run here, reading the context filled above; the chain never touches express `req`.\n        const result = await this.clientMethod(requestDto);\n\n        // 5. Serialize the response DTO to JSON (SYMMETRIC with client's response.json())\n        const responseJson = JSON.stringify(result);\n        res.status(200).setHeader('Content-Type', 'application/json').send(responseJson);\n    }\n\n    /**\n     * Read HTTP headers from Express request.\n     * Returns Map of header name (lowercase) -> array of values.\n     *\n     * HTTP spec allows multiple values for same header name.\n     */\n    /**\n     * express Request -> webpieces {@link HttpRequest}. THE translation layer: below this line the\n     * filter chain and controllers never see express, which is what lets the same chain run\n     * in-process with no transport at all.\n     */\n    private toWebpiecesRequest(req: Request, raw?: RawRequest): HttpRequest {\n        return new HttpRequest(req.method, this.path, this.readExpressHeaders(req), raw);\n    }\n\n    /**\n     * The absolute url AS THE SENDER ADDRESSED IT — the string a vendor like Twilio signed.\n     *\n     * `x-forwarded-proto` / `x-forwarded-host` WIN when present, because behind a TLS-terminating\n     * proxy (Cloud Run, any load balancer) express's own view is wrong in both halves: `req.protocol`\n     * reads `http` and the Host header is the internal one, while the vendor signed the public\n     * `https://...` url the customer configured. Reconstructing naively therefore fails 100% of the\n     * time in production and works 100% of the time locally — the worst possible pairing, so this is\n     * stated here and pinned by a test rather than left to each app.\n     *\n     * These headers are attacker-controllable when nothing strips them, and that is ACCEPTABLE here\n     * precisely because of what the value is used for: a forged url produces a signature that does not\n     * verify, i.e. a 401. It grants nothing. (It is used for verification only — never for a redirect.)\n     */\n    private absoluteUrl(req: Request): string {\n        const forwardedProto = req.headers['x-forwarded-proto'];\n        const forwardedHost = req.headers['x-forwarded-host'];\n        // A proxy chain sends a comma-separated list; the FIRST entry is the original client's hop.\n        const proto = this.firstForwarded(forwardedProto) ?? req.protocol;\n        const host = this.firstForwarded(forwardedHost) ?? req.get('host') ?? '';\n        return `${proto}://${host}${req.originalUrl ?? req.url ?? this.path}`;\n    }\n\n    private firstForwarded(value: string | string[] | undefined): string | undefined {\n        const raw = Array.isArray(value) ? value[0] : value;\n        const first = raw?.split(',')[0]?.trim();\n        return first === undefined || first === '' ? undefined : first;\n    }\n\n    private readExpressHeaders(req: Request): Map<string, string[]> {\n        const headers = new Map<string, string[]>();\n\n        // Express stores headers in req.headers as Record<string, string | string[]>\n        for (const [name, value] of Object.entries(req.headers)) {\n            const lowerName = name.toLowerCase();\n\n            if (typeof value === 'string') {\n                headers.set(lowerName, [value]);\n            } else if (Array.isArray(value)) {\n                headers.set(lowerName, value);\n            }\n        }\n\n        return headers;\n    }\n\n    /**\n     * Read the raw request body as BYTES (we parse manually rather than mounting express.json()).\n     *\n     * Bytes, not a growing string: a per-chunk `toString()` splits any multi-byte character that\n     * straddles a chunk boundary into two replacement characters, so the body a webhook hook verified\n     * would not be the body the vendor signed.\n     *\n     * REFUSES a body over {@link maxBodyBytes} the moment it crosses the line — the chunks read so far\n     * are dropped and the stream is destroyed, so an oversize body is never fully buffered. It answers\n     * 400 rather than 401 even on a webhook route, unavoidably: there is no way to authenticate a\n     * caller whose request we are refusing to finish reading, and that ordering is the point.\n     */\n    private async readRequestBody(req: Request): Promise<Buffer> {\n        return new Promise((resolve: (body: Buffer) => void, reject: (err: Error) => void) => {\n            let chunks: Buffer[] = [];\n            let size = 0;\n            // A socket emits Buffers; a stream someone put in string mode (or a test's Readable.from)\n            // emits strings. Normalize to bytes ONCE, here, so everything downstream counts and\n            // concatenates the same units.\n            req.on('data', (data: Buffer | string) => {\n                const chunk = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');\n                size += chunk.length;\n                if (size > this.maxBodyBytes) {\n                    chunks = [];\n                    req.destroy();\n                    reject(new HttpBadRequestError(\n                        `Request body exceeds the ${this.maxBodyBytes} byte limit`,\n                    ));\n                    return;\n                }\n                chunks.push(chunk);\n            });\n            req.on('end', () => {\n                resolve(Buffer.concat(chunks));\n            });\n            req.on('error', (err: Error) => {\n                reject(err);\n            });\n        });\n    }\n\n    /**\n     * Handle errors - translate to JSON ProtocolError (SYMMETRIC with ClientErrorTranslator).\n     * PUBLIC so wrapExpress can call it for symmetric error handling.\n     * Maps HttpError subclasses to appropriate HTTP status codes and ProtocolError response.\n     *\n     * Maps all HttpError types (must match ClientErrorTranslator.translateError()):\n     * - HttpUserError → 266 (with errorCode)\n     * - HttpBadRequestError → 400 (with field, guiAlertMessage)\n     * - HttpUnauthorizedError → 401\n     * - HttpForbiddenError → 403\n     * - HttpNotFoundError → 404\n     * - HttpTimeoutError → 408\n     * - HttpInternalServerError → 500\n     * - HttpBadGatewayError → 502\n     * - HttpGatewayTimeoutError → 504\n     * - HttpVendorError → 598 (with waitSeconds)\n     */\n    // webpieces-disable no-any-unknown -- a thrown error is genuinely unknown until narrowed below\n    public handleError(res: Response, error: unknown): void {\n        if (res.headersSent) {\n            return;\n        }\n\n        // App-registered translations win, so an app can serialize its OWN error types (e.g. a\n        // custom 460) AND override built-ins. `undefined` means \"not mine\" — fall through to the\n        // built-in instanceof-HttpError ladder below, which stays the generic default. Symmetric\n        // with the client's ClientErrorTranslator, which consults tryTranslateFromWire() first.\n        if (error instanceof Error) {\n            const wire = ClientRegistry.tryTranslateToWire(error);\n            if (wire !== undefined) {\n                res.status(wire.statusCode)\n                    .setHeader('Content-Type', 'application/json')\n                    .send(JSON.stringify(wire.protocolError));\n                return;\n            }\n        }\n\n        const protocolError = new ProtocolError();\n\n        if (error instanceof HttpError) {\n            // Set common fields for all HttpError types\n            protocolError.message = error.message;\n            protocolError.subType = error.subType;\n            protocolError.name = error.name;\n\n            // Set type-specific fields (MUST match ClientErrorTranslator)\n            if (error instanceof HttpUserError) {\n                log.info(`User Error: ${error.message}`);\n                protocolError.errorCode = error.errorCode;\n            } else if (error instanceof HttpBadRequestError) {\n                log.info(`Bad Request: ${error.message}`);\n                protocolError.field = error.field;\n                protocolError.guiAlertMessage = error.guiMessage;\n            } else if (error instanceof HttpNotFoundError) {\n                log.info(`Not Found: ${error.message}`);\n            } else if (error instanceof HttpTimeoutError) {\n                log.error(`Timeout Error: ${error.message}`);\n            } else if (error instanceof HttpVendorError) {\n                log.error(`Vendor Error: ${error.message}`);\n                protocolError.waitSeconds = error.waitSeconds;\n            } else if (error instanceof HttpUnauthorizedError) {\n                log.info(`Unauthorized: ${error.message}`);\n            } else if (error instanceof HttpForbiddenError) {\n                log.info(`Forbidden: ${error.message}`);\n            } else if (error instanceof HttpInternalServerError) {\n                log.error(`Internal Server Error: ${error.message}`);\n            } else if (error instanceof HttpBadGatewayError) {\n                log.error(`Bad Gateway: ${error.message}`);\n            } else if (error instanceof HttpGatewayTimeoutError) {\n                log.error(`Gateway Timeout: ${error.message}`);\n            } else {\n                log.info(`Generic HttpError: ${error.message}`);\n            }\n\n            // Serialize ProtocolError to JSON (SYMMETRIC with client)\n            const responseJson = JSON.stringify(protocolError);\n            res.status(error.code).setHeader('Content-Type', 'application/json').send(responseJson);\n        } else {\n            // Unknown error - 500\n            const err = toError(error);\n            protocolError.message = 'Internal Server Error';\n            log.error('Unexpected error:', err);\n            const responseJson = JSON.stringify(protocolError);\n            res.status(500).setHeader('Content-Type', 'application/json').send(responseJson);\n        }\n    }\n}\n"]}

package/src/WebpiecesExpressRouter.js

@@ -119,8 +119,9 @@ class WebpiecesExpressRouter {
         let count = 0;
         for (const [methodName, endpointPath] of Object.entries(endpoints)) {
             const path = basePath + endpointPath;
-            // The parser is chosen by the @Endpoint annotation, not the request Content-Type.
-            const wrapper = this.middleware.createExpressWrapper(apiClient.client[methodName], path, (0, http_routing_1.isFormPost)(apiClient.api, methodName));
+            // The parser is chosen by the @Endpoint annotation, not the request Content-Type — and
+            // so is whether the verbatim bytes survive the parse for an @AuthWebhook hook to verify.
+            const wrapper = this.middleware.createExpressWrapper(apiClient.client[methodName], path, (0, http_routing_1.isFormPost)(apiClient.api, methodName), (0, http_routing_1.isRawBody)(apiClient.api, methodName));
             // All webpieces routes are POST (the api-tier convention).
             this.registerHandler(app, 'POST', path, wrapper.execute.bind(wrapper));
             count++;

package/src/WebpiecesExpressRouter.js.map

@@ -1 +1 @@
-{"version":3,"file":"WebpiecesExpressRouter.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/WebpiecesExpressRouter.ts"],"names":[],"mappings":"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","sourcesContent":["import { Express } from 'express';\nimport { ApiFactory, ApiClient, getApiPath, getEndpoints, isFormPost, WebpiecesConfig } from '@webpieces/http-routing';\nimport { LogManager } from '@webpieces/core-util';\nimport { WebpiecesMiddleware, ExpressRouteHandler } from './WebpiecesMiddleware';\n\nconst log = LogManager.getLogger('WebpiecesExpressRouter');\n\n/** The value returned by express `app.listen(...)` (a node http.Server). */\ntype HttpServer = ReturnType<Express['listen']>;\n\n/**\n * WebpiecesExpressRouter - the express layer that sits ON TOP of a node-only\n * {@link ApiFactory} (a WebpiecesRouter). It is the ONLY place express lifecycle lives.\n *\n * It never reaches into routing internals: it asks the ApiFactory for `apiClients()` — each\n * an api + routeMeta + composed filter-chain→controller impl — and binds each to an express\n * route (`app.<verb>(path, handler)`) invoked when the matching HTTP request arrives. The\n * RouteBuilder stays hidden inside the ApiFactory.\n *\n * ```typescript\n * const apiFactory = await WebpiecesRouterFactory.create(config, { appBindings });\n * apiFactory.addRoutes(SaveApi, SaveController);\n * const express = new WebpiecesExpressRouter(apiFactory);\n *\n * // legacy / side-by-side: mount onto an existing app; you own listen + your middleware\n * express.bindExpress(existingApp);\n *\n * // non-legacy: add webpieces global middleware + listen for you\n * await express.bindAndStartExpress(express(), 8080);\n * ```\n */\nexport class WebpiecesExpressRouter {\n    private readonly middleware = new WebpiecesMiddleware();\n\n    constructor(private readonly apiFactory: ApiFactory) {}\n\n    /**\n     * Mount the webpieces routes (each fully self-contained: own body parse, RequestContext,\n     * express-tier + api-tier filter chain, error→JSON) onto the caller's express app.\n     *\n     * Adds NO global app.use() middleware, so it is safe to attach to a legacy app whose other\n     * routes must stay untouched. The caller owns app.listen() and any global middleware.\n     */\n    bindExpress(app: Express): void {\n        let count = 0;\n        for (const apiClient of this.apiFactory.apiClients()) {\n            count += this.mountApiClient(app, apiClient);\n        }\n        log.info(`Mounted ${count} webpieces route(s) onto express`);\n    }\n\n    /**\n     * Add the webpieces global middleware (optional CORS), bind the routes, mount the top-level\n     * error handler AFTER them, then app.listen(port). Convenience for a non-legacy webpieces server where\n     * webpieces owns the whole express app. Resolves with the http.Server once listening.\n     *\n     * CORS is mounted ONLY when `config.corsOrigins` is non-empty — see the note below and\n     * {@link WebpiecesMiddleware.corsMiddleware}.\n     */\n    async bindAndStartExpress(\n        app: Express,\n        port: number = 8080,\n        config?: WebpiecesConfig,\n    ): Promise<HttpServer> {\n        // Global middleware layers (outermost first) — only for a webpieces-owned app.\n        // CORS is OPT-IN, and stays OFF in production. A server that serves its own browser app does\n        // not need it — a browser applies no cors check to a same-origin request — so mounting it\n        // would only hand credentialed cross-origin read access to whatever it allows, for nothing.\n        // It is needed solely when a browser on ANOTHER origin calls this api: `ng serve` in dev, or\n        // a UI hosted on a different host. Those say so via corsOrigins.\n        const corsOrigins = config?.corsOrigins ?? [];\n        if (corsOrigins.length > 0) {\n            app.use(this.middleware.corsMiddleware(config));\n        }\n\n        this.bindExpress(app);\n\n        // Top-level error handler is mounted LAST (AFTER the routes). Express only forwards a\n        // downstream failure to a 4-arg error middleware that sits BELOW the failing route — it does\n        // NOT bubble errors back up through next(). See WebpiecesMiddleware.errorHandler.\n        app.use(this.middleware.errorHandler.bind(this.middleware));\n\n        return new Promise<HttpServer>(\n            (resolve: (server: HttpServer) => void, reject: (err: Error) => void) => {\n                const server: HttpServer = app.listen(port, (error?: Error) => {\n                    if (error) {\n                        log.error(`Failed to start on port ${port}:`, error);\n                        reject(error);\n                        return;\n                    }\n                    log.info(`Listening on http://localhost:${port}`);\n                    this.logStartupBanner(port);\n                    resolve(server);\n                });\n            },\n        );\n    }\n\n    /**\n     * The \"Svr Ready!!\" ASCII banner, LOCAL DEV ONLY (skipped on Cloud Run, where `K_SERVICE` is set and\n     * every line becomes its own structured log entry — a multi-line banner there is pure noise). Copied\n     * verbatim from the production service it was ported from, so a familiar splash marks \"the server is up and reachable\".\n     */\n    private logStartupBanner(port: number): void {\n        if (process.env['K_SERVICE']) {\n            return;\n        }\n        log.info(`\n ___                           _____               _\n/  _|                          | _ \\\\             | |\n\\\\ \\`--.  _ _ ___   ___ _ _  | |_/ /_  _ _  _| |_   _\n \\`--. \\\\/ _ \\\\ '_\\\\ \\\\ / / _ \\\\ '_| |    // _ \\\\/ _\\` |/ _\\` | | | |\n/\\\\_/ /  _/ |   \\\\ V /  _/ |    | |\\\\ \\\\  _/ (_| | (_| | |_| |\n\\\\___/ \\\\_|_|    \\\\_/ \\\\_|_|    \\\\_| \\\\_\\\\_|\\\\_,_|\\\\_,_|\\\\_, |\n                                                         _/ |\n                                                        |_/\n\n  Svr Ready!!  port=${port}\n`);\n    }\n\n    /**\n     * Bind EACH method of one ApiClient. The api's @ApiPath/@Endpoint decorators give the paths;\n     * for each we wrap the matching client method (the proxy — RequestContext.run + header read +\n     * JSON body parse + error→ProtocolError all live in the wrapper/chain) and register the route.\n     * This is one-to-one with a test: an HTTP POST maps straight to `client[method](dto)`.\n     *\n     * @returns the number of routes mounted for this api.\n     */\n    private mountApiClient(app: Express, apiClient: ApiClient): number {\n        const basePath = getApiPath(apiClient.api) || '';\n        const endpoints = getEndpoints(apiClient.api) || {};\n        let count = 0;\n        for (const [methodName, endpointPath] of Object.entries(endpoints)) {\n            const path = basePath + endpointPath;\n            // The parser is chosen by the @Endpoint annotation, not the request Content-Type.\n            const wrapper = this.middleware.createExpressWrapper(\n                apiClient.client[methodName],\n                path,\n                isFormPost(apiClient.api, methodName),\n            );\n            // All webpieces routes are POST (the api-tier convention).\n            this.registerHandler(app, 'POST', path, wrapper.execute.bind(wrapper));\n            count++;\n        }\n        return count;\n    }\n\n    private registerHandler(\n        app: Express,\n        httpMethod: string,\n        path: string,\n        expressHandler: ExpressRouteHandler,\n    ): void {\n        switch (httpMethod.toLowerCase()) {\n            case 'get':\n                app.get(path, expressHandler);\n                break;\n            case 'post':\n                app.post(path, expressHandler);\n                break;\n            case 'put':\n                app.put(path, expressHandler);\n                break;\n            case 'delete':\n                app.delete(path, expressHandler);\n                break;\n            case 'patch':\n                app.patch(path, expressHandler);\n                break;\n            default:\n                log.warn(`Unknown HTTP method: ${httpMethod}`);\n        }\n    }\n}\n"]}
+{"version":3,"file":"WebpiecesExpressRouter.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/WebpiecesExpressRouter.ts"],"names":[],"mappings":"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","sourcesContent":["import { Express } from 'express';\nimport { ApiFactory, ApiClient, getApiPath, getEndpoints, isFormPost, isRawBody, WebpiecesConfig } from '@webpieces/http-routing';\nimport { LogManager } from '@webpieces/core-util';\nimport { WebpiecesMiddleware, ExpressRouteHandler } from './WebpiecesMiddleware';\n\nconst log = LogManager.getLogger('WebpiecesExpressRouter');\n\n/** The value returned by express `app.listen(...)` (a node http.Server). */\ntype HttpServer = ReturnType<Express['listen']>;\n\n/**\n * WebpiecesExpressRouter - the express layer that sits ON TOP of a node-only\n * {@link ApiFactory} (a WebpiecesRouter). It is the ONLY place express lifecycle lives.\n *\n * It never reaches into routing internals: it asks the ApiFactory for `apiClients()` — each\n * an api + routeMeta + composed filter-chain→controller impl — and binds each to an express\n * route (`app.<verb>(path, handler)`) invoked when the matching HTTP request arrives. The\n * RouteBuilder stays hidden inside the ApiFactory.\n *\n * ```typescript\n * const apiFactory = await WebpiecesRouterFactory.create(config, { appBindings });\n * apiFactory.addRoutes(SaveApi, SaveController);\n * const express = new WebpiecesExpressRouter(apiFactory);\n *\n * // legacy / side-by-side: mount onto an existing app; you own listen + your middleware\n * express.bindExpress(existingApp);\n *\n * // non-legacy: add webpieces global middleware + listen for you\n * await express.bindAndStartExpress(express(), 8080);\n * ```\n */\nexport class WebpiecesExpressRouter {\n    private readonly middleware = new WebpiecesMiddleware();\n\n    constructor(private readonly apiFactory: ApiFactory) {}\n\n    /**\n     * Mount the webpieces routes (each fully self-contained: own body parse, RequestContext,\n     * express-tier + api-tier filter chain, error→JSON) onto the caller's express app.\n     *\n     * Adds NO global app.use() middleware, so it is safe to attach to a legacy app whose other\n     * routes must stay untouched. The caller owns app.listen() and any global middleware.\n     */\n    bindExpress(app: Express): void {\n        let count = 0;\n        for (const apiClient of this.apiFactory.apiClients()) {\n            count += this.mountApiClient(app, apiClient);\n        }\n        log.info(`Mounted ${count} webpieces route(s) onto express`);\n    }\n\n    /**\n     * Add the webpieces global middleware (optional CORS), bind the routes, mount the top-level\n     * error handler AFTER them, then app.listen(port). Convenience for a non-legacy webpieces server where\n     * webpieces owns the whole express app. Resolves with the http.Server once listening.\n     *\n     * CORS is mounted ONLY when `config.corsOrigins` is non-empty — see the note below and\n     * {@link WebpiecesMiddleware.corsMiddleware}.\n     */\n    async bindAndStartExpress(\n        app: Express,\n        port: number = 8080,\n        config?: WebpiecesConfig,\n    ): Promise<HttpServer> {\n        // Global middleware layers (outermost first) — only for a webpieces-owned app.\n        // CORS is OPT-IN, and stays OFF in production. A server that serves its own browser app does\n        // not need it — a browser applies no cors check to a same-origin request — so mounting it\n        // would only hand credentialed cross-origin read access to whatever it allows, for nothing.\n        // It is needed solely when a browser on ANOTHER origin calls this api: `ng serve` in dev, or\n        // a UI hosted on a different host. Those say so via corsOrigins.\n        const corsOrigins = config?.corsOrigins ?? [];\n        if (corsOrigins.length > 0) {\n            app.use(this.middleware.corsMiddleware(config));\n        }\n\n        this.bindExpress(app);\n\n        // Top-level error handler is mounted LAST (AFTER the routes). Express only forwards a\n        // downstream failure to a 4-arg error middleware that sits BELOW the failing route — it does\n        // NOT bubble errors back up through next(). See WebpiecesMiddleware.errorHandler.\n        app.use(this.middleware.errorHandler.bind(this.middleware));\n\n        return new Promise<HttpServer>(\n            (resolve: (server: HttpServer) => void, reject: (err: Error) => void) => {\n                const server: HttpServer = app.listen(port, (error?: Error) => {\n                    if (error) {\n                        log.error(`Failed to start on port ${port}:`, error);\n                        reject(error);\n                        return;\n                    }\n                    log.info(`Listening on http://localhost:${port}`);\n                    this.logStartupBanner(port);\n                    resolve(server);\n                });\n            },\n        );\n    }\n\n    /**\n     * The \"Svr Ready!!\" ASCII banner, LOCAL DEV ONLY (skipped on Cloud Run, where `K_SERVICE` is set and\n     * every line becomes its own structured log entry — a multi-line banner there is pure noise). Copied\n     * verbatim from the production service it was ported from, so a familiar splash marks \"the server is up and reachable\".\n     */\n    private logStartupBanner(port: number): void {\n        if (process.env['K_SERVICE']) {\n            return;\n        }\n        log.info(`\n ___                           _____               _\n/  _|                          | _ \\\\             | |\n\\\\ \\`--.  _ _ ___   ___ _ _  | |_/ /_  _ _  _| |_   _\n \\`--. \\\\/ _ \\\\ '_\\\\ \\\\ / / _ \\\\ '_| |    // _ \\\\/ _\\` |/ _\\` | | | |\n/\\\\_/ /  _/ |   \\\\ V /  _/ |    | |\\\\ \\\\  _/ (_| | (_| | |_| |\n\\\\___/ \\\\_|_|    \\\\_/ \\\\_|_|    \\\\_| \\\\_\\\\_|\\\\_,_|\\\\_,_|\\\\_, |\n                                                         _/ |\n                                                        |_/\n\n  Svr Ready!!  port=${port}\n`);\n    }\n\n    /**\n     * Bind EACH method of one ApiClient. The api's @ApiPath/@Endpoint decorators give the paths;\n     * for each we wrap the matching client method (the proxy — RequestContext.run + header read +\n     * JSON body parse + error→ProtocolError all live in the wrapper/chain) and register the route.\n     * This is one-to-one with a test: an HTTP POST maps straight to `client[method](dto)`.\n     *\n     * @returns the number of routes mounted for this api.\n     */\n    private mountApiClient(app: Express, apiClient: ApiClient): number {\n        const basePath = getApiPath(apiClient.api) || '';\n        const endpoints = getEndpoints(apiClient.api) || {};\n        let count = 0;\n        for (const [methodName, endpointPath] of Object.entries(endpoints)) {\n            const path = basePath + endpointPath;\n            // The parser is chosen by the @Endpoint annotation, not the request Content-Type — and\n            // so is whether the verbatim bytes survive the parse for an @AuthWebhook hook to verify.\n            const wrapper = this.middleware.createExpressWrapper(\n                apiClient.client[methodName],\n                path,\n                isFormPost(apiClient.api, methodName),\n                isRawBody(apiClient.api, methodName),\n            );\n            // All webpieces routes are POST (the api-tier convention).\n            this.registerHandler(app, 'POST', path, wrapper.execute.bind(wrapper));\n            count++;\n        }\n        return count;\n    }\n\n    private registerHandler(\n        app: Express,\n        httpMethod: string,\n        path: string,\n        expressHandler: ExpressRouteHandler,\n    ): void {\n        switch (httpMethod.toLowerCase()) {\n            case 'get':\n                app.get(path, expressHandler);\n                break;\n            case 'post':\n                app.post(path, expressHandler);\n                break;\n            case 'put':\n                app.put(path, expressHandler);\n                break;\n            case 'delete':\n                app.delete(path, expressHandler);\n                break;\n            case 'patch':\n                app.patch(path, expressHandler);\n                break;\n            default:\n                log.warn(`Unknown HTTP method: ${httpMethod}`);\n        }\n    }\n}\n"]}

package/src/WebpiecesMiddleware.d.ts

@@ -106,7 +106,10 @@ export declare class WebpiecesMiddleware {
      * @param path - The route path (used to build the HttpRequest).
      * @param formPost - True for an @Endpoint(..., { formPost: true }) route (parse body as
      *   urlencoded, not JSON). Default false = JSON.
+     * @param rawBody - True for an @Endpoint(..., { rawBody: true }) route: retain the verbatim
+     *   bytes + absolute url on the HttpRequest so an @AuthWebhook hook can verify a vendor
+     *   signature over them. Default false = the bytes are dropped once parsed.
      * @returns ExpressWrapper instance
      */
-    createExpressWrapper(clientMethod: (requestDto: unknown) => Promise<unknown>, path: string, formPost?: boolean): ExpressWrapper;
+    createExpressWrapper(clientMethod: (requestDto: unknown) => Promise<unknown>, path: string, formPost?: boolean, rawBody?: boolean): ExpressWrapper;
 }

package/src/WebpiecesMiddleware.js

@@ -189,12 +189,15 @@ let WebpiecesMiddleware = class WebpiecesMiddleware {
      * @param path - The route path (used to build the HttpRequest).
      * @param formPost - True for an @Endpoint(..., { formPost: true }) route (parse body as
      *   urlencoded, not JSON). Default false = JSON.
+     * @param rawBody - True for an @Endpoint(..., { rawBody: true }) route: retain the verbatim
+     *   bytes + absolute url on the HttpRequest so an @AuthWebhook hook can verify a vendor
+     *   signature over them. Default false = the bytes are dropped once parsed.
      * @returns ExpressWrapper instance
      */
     createExpressWrapper(
     // webpieces-disable no-any-unknown -- request/response DTOs are erased at the routing boundary
-    clientMethod, path, formPost = false) {
-        return new ExpressWrapper_1.ExpressWrapper(clientMethod, path, this.headers, formPost);
+    clientMethod, path, formPost = false, rawBody = false) {
+        return new ExpressWrapper_1.ExpressWrapper(clientMethod, path, this.headers, formPost, rawBody);
     }
 };
 exports.WebpiecesMiddleware = WebpiecesMiddleware;

package/src/WebpiecesMiddleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"WebpiecesMiddleware.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/WebpiecesMiddleware.ts"],"names":[],"mappings":"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","sourcesContent":["import { Request, Response, NextFunction, RequestHandler } from 'express';\nimport cors from 'cors';\nimport { provideFrameworkSingleton, WebpiecesConfig } from '@webpieces/http-routing';\nimport { toError } from '@webpieces/core-util';\nimport { RequestContextHeaders } from '@webpieces/core-context';\nimport { LogManager } from '@webpieces/core-util';\nimport { ExpressWrapper } from './ExpressWrapper';\n\nconst log = LogManager.getLogger('WebpiecesMiddleware');\n// CORS mount/allow/block lines log under their own name (not [WebpiecesMiddleware]); the backend\n// prepends \"[CORS]\" for us, so the message strings below carry no literal prefix of their own.\nconst corsLog = LogManager.getLogger('CORS');\n\n/**\n * Express route handler function type. Lives in http-server (the express adapter),\n * NOT in the node-only http-routing package, so http-routing stays express-free.\n * Used by WebpiecesExpressRouter to register handlers Express can call.\n */\nexport type ExpressRouteHandler = (\n    req: Request,\n    res: Response,\n    next: NextFunction,\n) => Promise<void>;\n\n/**\n * WebpiecesMiddleware - Express middleware for WebPieces server.\n *\n * This class contains all Express middleware used by WebpiecesServer:\n * 1. errorHandler - Top-level 4-arg error middleware, returns HTML 500 page. Mounted AFTER the\n *    routes so express can forward downstream failures to it (express routes errors DOWN a\n *    separate pipeline, it does not bubble them back up through next()). Last-resort net only:\n *    api routes translate their own errors to JSON inside the filter chain (ExpressWrapper).\n * 2. corsMiddleware - Opt-in CORS (mounted only when corsOrigins is non-empty).\n *\n * Per-request logging is intentionally NOT here — the api filter chain's LogApiCall already logs\n * every request/response with full context (requestId, method, path, body), so a plain express\n * START/END line would only duplicate it with less information.\n *\n * Route dispatch happens via Express's registered route handlers (the per-route ExpressWrapper),\n * NOT via this middleware.\n *\n * NEW: ExpressWrapper simplified - no longer handles JSON or headers\n * - JSON parsing/serialization moved to JsonFilter\n * - Header transfer moved to ContextFilter (injects PlatformHeadersExtension directly)\n * - ExpressWrapper just creates RouterReqResp and invokes filter chain\n *\n * Extension vs Plugin pattern:\n * - Extensions (DI-level): Contribute capabilities to framework (headers, converters, etc.)\n * - Plugins (App-level): Provide complete features with modules + routes (Hibernate, Jackson, etc.)\n */\n@provideFrameworkSingleton()\nexport class WebpiecesMiddleware {\n    /** The ONE wire<->context transfer, handed to every route's ExpressWrapper. Stateless. */\n    private readonly headers = new RequestContextHeaders();\n\n\n    /**\n     * Top-level error handler — the last-ditch catch-all. MUST be mounted AFTER all routes (see\n     * {@link WebpiecesExpressRouter}). The 4-argument `(err, req, res, next)` signature is what\n     * tells express this is an error-handling middleware: express's router forwards ANY downstream\n     * failure to it — synchronous throws AND rejected async-handler promises alike (the router does\n     * `promise.then(null, err => next(err))`, and a `next(err)` with a truthy arg jumps straight to\n     * the first 4-arg middleware). This is why a `try { await next() } catch` wrapper is NOT needed\n     * (and would not work) — express `next()` is not promise-aware, so it never hands the parent the\n     * downstream promise; errors travel down this separate pipeline instead of bubbling back up.\n     *\n     * Returns an HTML 500 page. Api routes translate their own errors to JSON inside the filter\n     * chain (JsonFilter/ExpressWrapper), so this normally only fires for failures OUTSIDE a route\n     * (body parsing, unmatched paths, a bug in the wrapper itself).\n     */\n    // webpieces-disable no-any-unknown -- a thrown/forwarded express error is genuinely unknown until narrowed\n    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- express needs the 4-arg (err,req,res,next) arity to recognize this as error-handling middleware\n    errorHandler(err: unknown, req: Request, res: Response, next: NextFunction): void {\n        const error = toError(err);\n        log.error(`Unhandled error: ${req.method} ${req.path}`, error);\n        if (res.headersSent) {\n            return;\n        }\n        // Return HTML error page (not JSON - api routes translate JSON errors in their filter chain)\n        res.status(500).send(`\n          <!DOCTYPE html>\n          <html>\n          <head><title>Server Error</title></head>\n          <body>\n            <h1>You hit a server error</h1>\n            <p>An unexpected error occurred while processing your request.</p>\n            <pre>${error.message}</pre>\n          </body>\n          </html>\n        `);\n    }\n\n    /**\n     * CORS middleware. DO NOT MOUNT UNCONDITIONALLY — {@link WebpiecesExpressRouter.bindAndStartExpress}\n     * mounts it ONLY when {@link WebpiecesConfig.corsOrigins} is non-empty, and that is the point.\n     *\n     * CORS exists solely to let a browser on a DIFFERENT origin call this api — in practice\n     * `ng serve` on :4200 hitting an api on :8080 during development, or a UI hosted on a different\n     * host than the api. A server that serves its own browser app needs NO cors at all, because a\n     * browser does not apply cors to a same-origin request. So in production this middleware is\n     * normally ABSENT, and absent is the safe state: every origin it allows gains the right to make\n     * CREDENTIALED cross-origin calls and READ the responses. Mounting it unconditionally (as the\n     * old corsForLocalhost did) handed that right to anything on the victim's localhost, in prod,\n     * for no benefit whatsoever.\n     *\n     * When mounted, allows: a request with NO Origin (curl, server-to-server, a CLI); the server's\n     * OWN origin; and EXACTLY the origins in `corsOrigins` — nothing is implicit. Anything else gets\n     * a clean 403, never the HTML 500 the old `callback(new Error(...))` produced.\n     *\n     * SAME-ORIGIN MUST STAY ALLOWED even though a same-origin request needs no cors headers, because\n     * a browser attaches an `Origin` header to EVERY POST — including a same-origin POST — and every\n     * webpieces route is a POST. Once mounted, this middleware SEES that origin, so if it did not\n     * allow it, it would 403 the server's own UI. That was the production bug.\n     *\n     * The same-origin test compares HOST ONLY, deliberately. Behind a TLS-terminating proxy (Cloud\n     * Run, any load balancer) `req.protocol` is `http` while the browser's `Origin` says `https`, so\n     * comparing full origins would reject the server's own origin on every deploy.\n     *\n     * @returns Express middleware handler for CORS\n     */\n    corsMiddleware(config?: WebpiecesConfig): RequestHandler {\n        const allowedOrigins = config?.corsOrigins ?? [];\n        corsLog.info(\n            `CORS MOUNTED. Allowing same-origin + [${allowedOrigins.join(', ')}]. ` +\n                `Every other browser origin gets a 403.`,\n        );\n\n        const handler = cors({\n            origin: true, // reflect the request origin — we have already vetted it below\n            credentials: true,\n            methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],\n            allowedHeaders: '*',\n            exposedHeaders: '*',\n            maxAge: 3600,\n        });\n\n        return (req: Request, res: Response, next: NextFunction): void => {\n            const origin = req.headers.origin;\n            if (!origin) {\n                // No Origin -> not a browser cross-origin request; nothing to negotiate.\n                next();\n                return;\n            }\n            if (this.isOriginAllowed(origin, req.get('host'), allowedOrigins)) {\n                handler(req, res, next);\n                return;\n            }\n            corsLog.info(`Blocked origin: ${origin}`);\n            res.status(403).json({\n                name: 'CorsError',\n                message: `CORS not allowed for origin: ${origin}`,\n            });\n        };\n    }\n\n    /**\n     * Same-origin (HOST ONLY — see corsMiddleware() on why the scheme is deliberately ignored), or an\n     * explicit entry in corsOrigins. NOTHING is implicit: localhost is allowed only if the config\n     * asked for it, so a production server that enables cors for a cross-host UI does not silently\n     * open the door to localhost as well.\n     */\n    private isOriginAllowed(origin: string, host: string | undefined, allowedOrigins: string[]): boolean {\n        let originHost: string;\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- a malformed Origin is untrusted browser input, not a server fault; it must become a 403 here, never bubble to the 500 chokepoint\n        try {\n            originHost = new URL(origin).host;\n        } catch (err: unknown) {\n            const error = toError(err);\n            corsLog.info(`Malformed Origin header '${origin}': ${error.message}`);\n            return false;\n        }\n        if (host !== undefined && originHost === host) {\n            return true; // same-origin: the server's own UI calling its own api\n        }\n        return allowedOrigins.some((allowed: string): boolean => this.matchesOrigin(origin, allowed));\n    }\n\n    /**\n     * Exact origin match, except a `*` in the PORT position matches any port: `http://localhost:*`\n     * is what a developer writes, because the angular dev-server port moves around.\n     *\n     * The `*` is deliberately NOT a general wildcard — it never spans a host, and what follows the\n     * prefix must be a real (digits-only) port. So `http://localhost:*` cannot be tricked into\n     * matching `http://localhost.evil.com`, and a bare `*` matches nothing at all.\n     */\n    private matchesOrigin(origin: string, allowed: string): boolean {\n        if (allowed === origin) {\n            return true;\n        }\n        const wildcardSuffix = ':*';\n        if (!allowed.endsWith(wildcardSuffix)) {\n            return false;\n        }\n        const prefix = allowed.slice(0, -wildcardSuffix.length);\n        if (!origin.startsWith(`${prefix}:`)) {\n            return false;\n        }\n        const port = origin.slice(prefix.length + 1);\n        return /^\\d+$/.test(port);\n    }\n\n    /**\n     * Create an ExpressWrapper for a route.\n     * The wrapper handles the full request/response cycle (symmetric design): it publishes the\n     * HttpRequest + fills the context, then invokes the api client method (the proxy).\n     *\n     * @param clientMethod - The api client's method for this route (dto → response); the proxy\n     *   runs the filter chain + controller.\n     * @param path - The route path (used to build the HttpRequest).\n     * @param formPost - True for an @Endpoint(..., { formPost: true }) route (parse body as\n     *   urlencoded, not JSON). Default false = JSON.\n     * @returns ExpressWrapper instance\n     */\n    createExpressWrapper(\n        // webpieces-disable no-any-unknown -- request/response DTOs are erased at the routing boundary\n        clientMethod: (requestDto: unknown) => Promise<unknown>,\n        path: string,\n        formPost: boolean = false,\n    ): ExpressWrapper {\n        return new ExpressWrapper(clientMethod, path, this.headers, formPost);\n    }\n}\n"]}
+{"version":3,"file":"WebpiecesMiddleware.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/WebpiecesMiddleware.ts"],"names":[],"mappings":"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","sourcesContent":["import { Request, Response, NextFunction, RequestHandler } from 'express';\nimport cors from 'cors';\nimport { provideFrameworkSingleton, WebpiecesConfig } from '@webpieces/http-routing';\nimport { toError } from '@webpieces/core-util';\nimport { RequestContextHeaders } from '@webpieces/core-context';\nimport { LogManager } from '@webpieces/core-util';\nimport { ExpressWrapper } from './ExpressWrapper';\n\nconst log = LogManager.getLogger('WebpiecesMiddleware');\n// CORS mount/allow/block lines log under their own name (not [WebpiecesMiddleware]); the backend\n// prepends \"[CORS]\" for us, so the message strings below carry no literal prefix of their own.\nconst corsLog = LogManager.getLogger('CORS');\n\n/**\n * Express route handler function type. Lives in http-server (the express adapter),\n * NOT in the node-only http-routing package, so http-routing stays express-free.\n * Used by WebpiecesExpressRouter to register handlers Express can call.\n */\nexport type ExpressRouteHandler = (\n    req: Request,\n    res: Response,\n    next: NextFunction,\n) => Promise<void>;\n\n/**\n * WebpiecesMiddleware - Express middleware for WebPieces server.\n *\n * This class contains all Express middleware used by WebpiecesServer:\n * 1. errorHandler - Top-level 4-arg error middleware, returns HTML 500 page. Mounted AFTER the\n *    routes so express can forward downstream failures to it (express routes errors DOWN a\n *    separate pipeline, it does not bubble them back up through next()). Last-resort net only:\n *    api routes translate their own errors to JSON inside the filter chain (ExpressWrapper).\n * 2. corsMiddleware - Opt-in CORS (mounted only when corsOrigins is non-empty).\n *\n * Per-request logging is intentionally NOT here — the api filter chain's LogApiCall already logs\n * every request/response with full context (requestId, method, path, body), so a plain express\n * START/END line would only duplicate it with less information.\n *\n * Route dispatch happens via Express's registered route handlers (the per-route ExpressWrapper),\n * NOT via this middleware.\n *\n * NEW: ExpressWrapper simplified - no longer handles JSON or headers\n * - JSON parsing/serialization moved to JsonFilter\n * - Header transfer moved to ContextFilter (injects PlatformHeadersExtension directly)\n * - ExpressWrapper just creates RouterReqResp and invokes filter chain\n *\n * Extension vs Plugin pattern:\n * - Extensions (DI-level): Contribute capabilities to framework (headers, converters, etc.)\n * - Plugins (App-level): Provide complete features with modules + routes (Hibernate, Jackson, etc.)\n */\n@provideFrameworkSingleton()\nexport class WebpiecesMiddleware {\n    /** The ONE wire<->context transfer, handed to every route's ExpressWrapper. Stateless. */\n    private readonly headers = new RequestContextHeaders();\n\n\n    /**\n     * Top-level error handler — the last-ditch catch-all. MUST be mounted AFTER all routes (see\n     * {@link WebpiecesExpressRouter}). The 4-argument `(err, req, res, next)` signature is what\n     * tells express this is an error-handling middleware: express's router forwards ANY downstream\n     * failure to it — synchronous throws AND rejected async-handler promises alike (the router does\n     * `promise.then(null, err => next(err))`, and a `next(err)` with a truthy arg jumps straight to\n     * the first 4-arg middleware). This is why a `try { await next() } catch` wrapper is NOT needed\n     * (and would not work) — express `next()` is not promise-aware, so it never hands the parent the\n     * downstream promise; errors travel down this separate pipeline instead of bubbling back up.\n     *\n     * Returns an HTML 500 page. Api routes translate their own errors to JSON inside the filter\n     * chain (JsonFilter/ExpressWrapper), so this normally only fires for failures OUTSIDE a route\n     * (body parsing, unmatched paths, a bug in the wrapper itself).\n     */\n    // webpieces-disable no-any-unknown -- a thrown/forwarded express error is genuinely unknown until narrowed\n    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- express needs the 4-arg (err,req,res,next) arity to recognize this as error-handling middleware\n    errorHandler(err: unknown, req: Request, res: Response, next: NextFunction): void {\n        const error = toError(err);\n        log.error(`Unhandled error: ${req.method} ${req.path}`, error);\n        if (res.headersSent) {\n            return;\n        }\n        // Return HTML error page (not JSON - api routes translate JSON errors in their filter chain)\n        res.status(500).send(`\n          <!DOCTYPE html>\n          <html>\n          <head><title>Server Error</title></head>\n          <body>\n            <h1>You hit a server error</h1>\n            <p>An unexpected error occurred while processing your request.</p>\n            <pre>${error.message}</pre>\n          </body>\n          </html>\n        `);\n    }\n\n    /**\n     * CORS middleware. DO NOT MOUNT UNCONDITIONALLY — {@link WebpiecesExpressRouter.bindAndStartExpress}\n     * mounts it ONLY when {@link WebpiecesConfig.corsOrigins} is non-empty, and that is the point.\n     *\n     * CORS exists solely to let a browser on a DIFFERENT origin call this api — in practice\n     * `ng serve` on :4200 hitting an api on :8080 during development, or a UI hosted on a different\n     * host than the api. A server that serves its own browser app needs NO cors at all, because a\n     * browser does not apply cors to a same-origin request. So in production this middleware is\n     * normally ABSENT, and absent is the safe state: every origin it allows gains the right to make\n     * CREDENTIALED cross-origin calls and READ the responses. Mounting it unconditionally (as the\n     * old corsForLocalhost did) handed that right to anything on the victim's localhost, in prod,\n     * for no benefit whatsoever.\n     *\n     * When mounted, allows: a request with NO Origin (curl, server-to-server, a CLI); the server's\n     * OWN origin; and EXACTLY the origins in `corsOrigins` — nothing is implicit. Anything else gets\n     * a clean 403, never the HTML 500 the old `callback(new Error(...))` produced.\n     *\n     * SAME-ORIGIN MUST STAY ALLOWED even though a same-origin request needs no cors headers, because\n     * a browser attaches an `Origin` header to EVERY POST — including a same-origin POST — and every\n     * webpieces route is a POST. Once mounted, this middleware SEES that origin, so if it did not\n     * allow it, it would 403 the server's own UI. That was the production bug.\n     *\n     * The same-origin test compares HOST ONLY, deliberately. Behind a TLS-terminating proxy (Cloud\n     * Run, any load balancer) `req.protocol` is `http` while the browser's `Origin` says `https`, so\n     * comparing full origins would reject the server's own origin on every deploy.\n     *\n     * @returns Express middleware handler for CORS\n     */\n    corsMiddleware(config?: WebpiecesConfig): RequestHandler {\n        const allowedOrigins = config?.corsOrigins ?? [];\n        corsLog.info(\n            `CORS MOUNTED. Allowing same-origin + [${allowedOrigins.join(', ')}]. ` +\n                `Every other browser origin gets a 403.`,\n        );\n\n        const handler = cors({\n            origin: true, // reflect the request origin — we have already vetted it below\n            credentials: true,\n            methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],\n            allowedHeaders: '*',\n            exposedHeaders: '*',\n            maxAge: 3600,\n        });\n\n        return (req: Request, res: Response, next: NextFunction): void => {\n            const origin = req.headers.origin;\n            if (!origin) {\n                // No Origin -> not a browser cross-origin request; nothing to negotiate.\n                next();\n                return;\n            }\n            if (this.isOriginAllowed(origin, req.get('host'), allowedOrigins)) {\n                handler(req, res, next);\n                return;\n            }\n            corsLog.info(`Blocked origin: ${origin}`);\n            res.status(403).json({\n                name: 'CorsError',\n                message: `CORS not allowed for origin: ${origin}`,\n            });\n        };\n    }\n\n    /**\n     * Same-origin (HOST ONLY — see corsMiddleware() on why the scheme is deliberately ignored), or an\n     * explicit entry in corsOrigins. NOTHING is implicit: localhost is allowed only if the config\n     * asked for it, so a production server that enables cors for a cross-host UI does not silently\n     * open the door to localhost as well.\n     */\n    private isOriginAllowed(origin: string, host: string | undefined, allowedOrigins: string[]): boolean {\n        let originHost: string;\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- a malformed Origin is untrusted browser input, not a server fault; it must become a 403 here, never bubble to the 500 chokepoint\n        try {\n            originHost = new URL(origin).host;\n        } catch (err: unknown) {\n            const error = toError(err);\n            corsLog.info(`Malformed Origin header '${origin}': ${error.message}`);\n            return false;\n        }\n        if (host !== undefined && originHost === host) {\n            return true; // same-origin: the server's own UI calling its own api\n        }\n        return allowedOrigins.some((allowed: string): boolean => this.matchesOrigin(origin, allowed));\n    }\n\n    /**\n     * Exact origin match, except a `*` in the PORT position matches any port: `http://localhost:*`\n     * is what a developer writes, because the angular dev-server port moves around.\n     *\n     * The `*` is deliberately NOT a general wildcard — it never spans a host, and what follows the\n     * prefix must be a real (digits-only) port. So `http://localhost:*` cannot be tricked into\n     * matching `http://localhost.evil.com`, and a bare `*` matches nothing at all.\n     */\n    private matchesOrigin(origin: string, allowed: string): boolean {\n        if (allowed === origin) {\n            return true;\n        }\n        const wildcardSuffix = ':*';\n        if (!allowed.endsWith(wildcardSuffix)) {\n            return false;\n        }\n        const prefix = allowed.slice(0, -wildcardSuffix.length);\n        if (!origin.startsWith(`${prefix}:`)) {\n            return false;\n        }\n        const port = origin.slice(prefix.length + 1);\n        return /^\\d+$/.test(port);\n    }\n\n    /**\n     * Create an ExpressWrapper for a route.\n     * The wrapper handles the full request/response cycle (symmetric design): it publishes the\n     * HttpRequest + fills the context, then invokes the api client method (the proxy).\n     *\n     * @param clientMethod - The api client's method for this route (dto → response); the proxy\n     *   runs the filter chain + controller.\n     * @param path - The route path (used to build the HttpRequest).\n     * @param formPost - True for an @Endpoint(..., { formPost: true }) route (parse body as\n     *   urlencoded, not JSON). Default false = JSON.\n     * @param rawBody - True for an @Endpoint(..., { rawBody: true }) route: retain the verbatim\n     *   bytes + absolute url on the HttpRequest so an @AuthWebhook hook can verify a vendor\n     *   signature over them. Default false = the bytes are dropped once parsed.\n     * @returns ExpressWrapper instance\n     */\n    createExpressWrapper(\n        // webpieces-disable no-any-unknown -- request/response DTOs are erased at the routing boundary\n        clientMethod: (requestDto: unknown) => Promise<unknown>,\n        path: string,\n        formPost: boolean = false,\n        rawBody: boolean = false,\n    ): ExpressWrapper {\n        return new ExpressWrapper(clientMethod, path, this.headers, formPost, rawBody);\n    }\n}\n"]}