unnbound-events 3.1.0 → 3.1.1

package/dist/lib/routing/as2.d.ts

@@ -23,6 +23,11 @@ export interface As2Prepared {
  * fails on its own sanitized trace and can assert nothing. Request/response headers are
  * logged through the AS2 allowlist — Receipt-Delivery-Option and Subject never appear.
  *
+ * Do not attach route middleware that can answer an as2Endpoint request itself (auth
+ * shims, rate limiters): a middleware early-return never reaches this wrapper, so it is
+ * logged through the generic header policy on the public header-derived trace instead of
+ * the AS2 policy above. Rejection logic belongs inside `prepare`/`handler`.
+ *
  * ```ts
  * // identity/partner are plain objects built inline from ordinary scalar workflow
  * // variables — never a variable name passed to `as2.receive`/`as2.send` (see

package/dist/lib/routing/as2.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.as2Endpoint = void 0;
+const node_crypto_1 = require("node:crypto");
 const unnbound_logger_sdk_1 = require("unnbound-logger-sdk");
 const error_1 = require("../error");
 const utils_1 = require("../utils");
@@ -12,22 +13,40 @@ const response_1 = require("./response");
  * import `@ontemper/as2` (the dependency runs the other way), so the shape is read defensively.
  */
 const RETRYABLE_AS2_STATUSES = [502, 503, 504];
+/**
+ * Permanent client errors the partner must NOT re-send: an oversized document is 413, a
+ * malformed/undecryptable envelope is 400/422. Collapsing these to 500 tells the partner it
+ * was a transient server fault, so it retries a payload that can never succeed.
+ */
+const PERMANENT_AS2_STATUSES = [400, 413, 422];
 /**
  * AS2 partners drive their re-send behaviour off the status code, so collapsing every failure to
- * a flat 500 throws away the one signal telling them to try again — the same signal the
- * in-flight/parked path already sends deliberately as a 503. Lift the transient statuses onto the
- * wire; the message stays generic so no internal detail reaches the partner.
+ * a flat 500 throws away the one signal telling them what to do — retry a transient fault, or
+ * stop resending a permanently bad payload. Lift both classes onto the wire from the platform's
+ * `As2SdkError` status; the message stays generic so no internal detail reaches the partner.
+ * Anything unrecognized still collapses to 500.
  */
 const toWireFailure = (error) => {
     if (error && typeof error === 'object') {
         const { name, status } = error;
-        const retryable = RETRYABLE_AS2_STATUSES.find((candidate) => candidate === status);
-        if (name === 'As2SdkError' && retryable) {
-            return new error_1.ServerError({
-                message: 'AS2 message could not be processed; retry later',
-                status: retryable,
-                cause: error,
-            });
+        if (name === 'As2SdkError') {
+            // .find (not .some) so the matched literal narrows to StatusCode without a cast.
+            const retryable = RETRYABLE_AS2_STATUSES.find((candidate) => candidate === status);
+            if (retryable) {
+                return new error_1.ServerError({
+                    message: 'AS2 message could not be processed; retry later',
+                    status: retryable,
+                    cause: error,
+                });
+            }
+            const permanent = PERMANENT_AS2_STATUSES.find((candidate) => candidate === status);
+            if (permanent) {
+                return new error_1.ServerError({
+                    message: 'AS2 message was rejected and should not be resent',
+                    status: permanent,
+                    cause: error,
+                });
+            }
         }
     }
     return error_1.ServerError.fromError(error);
@@ -40,6 +59,11 @@ const toWireFailure = (error) => {
  * fails on its own sanitized trace and can assert nothing. Request/response headers are
  * logged through the AS2 allowlist — Receipt-Delivery-Option and Subject never appear.
  *
+ * Do not attach route middleware that can answer an as2Endpoint request itself (auth
+ * shims, rate limiters): a middleware early-return never reaches this wrapper, so it is
+ * logged through the generic header policy on the public header-derived trace instead of
+ * the AS2 policy above. Rejection logic belongs inside `prepare`/`handler`.
+ *
  * ```ts
  * // identity/partner are plain objects built inline from ordinary scalar workflow
  * // variables — never a variable name passed to `as2.receive`/`as2.send` (see
@@ -75,7 +99,12 @@ const toWireFailure = (error) => {
 // weak-type check would reject those. The As2Prepared contract is read defensively.
 const as2Endpoint = (prepare, handler) => {
     return (0, endpoint_1.markSelfTraced)(async (event) => {
-        const requestTraceId = (0, unnbound_logger_sdk_1.getTraceId)();
+        // Mint a fresh pre-verification trace, do NOT read the ambient one: getIncomingEvent has
+        // already adopted a partner-supplied canonical x-unnbound-trace-id by the time this wrapper
+        // runs, so getTraceId() would return a trace the partner chose. Unverified traffic must not
+        // be able to select the trace its prepare/failure/inFlight/parked spans land on — only a
+        // ledger-verified customerTraceId may re-bind below.
+        const requestTraceId = (0, node_crypto_1.randomUUID)();
         let prepared;
         try {
             prepared = await (0, unnbound_logger_sdk_1.withTrace)(() => prepare({ headers: event.request.headers, body: event.request.body }, event), {
@@ -100,7 +129,7 @@ const as2Endpoint = (prepare, handler) => {
             try {
                 const result = await (0, unnbound_logger_sdk_1.startSpan)('Event request', async () => {
                     const result = await handler(prepared, event);
-                    return { status: result?.status ?? 204, headers: result?.headers, body: result?.body };
+                    return { status: (0, response_1.resolveStatus)(result), headers: result?.headers, body: result?.body };
                 }, (o) => (0, utils_1.buildAs2IncomingPayload)(event, o));
                 return { ...result, headers: (0, response_1.attachTraceHeaders)(result.headers) };
             }

package/dist/lib/routing/middleware.d.ts

@@ -1,7 +1,7 @@
 import type { MiddlewareHandler as HonoMiddlewareHandler, Next } from 'hono';
 import type { EventHandlerResult } from '../event';
 import type { EventEnvironment, EventVariables, MaybePromise } from './types';
-export type MiddlewareHandler<I> = (input: I, next: Next) => MaybePromise<EventHandlerResult | void>;
+export type MiddlewareHandler<I> = (input: I, next: Next) => MaybePromise<EventHandlerResult | undefined> | Promise<void>;
 export interface Middleware<I> {
     (...middlewares: MiddlewareHandler<I>[]): MaybePromise<void>;
     (path: string, ...middlewares: MiddlewareHandler<I>[]): MaybePromise<void>;

package/dist/lib/utils.d.ts

@@ -20,7 +20,7 @@ export declare const buildIncomingPayload: (event: IncomingEvent<MatchedIncoming
     http: {
         url: string;
         method: string;
-        query: Record<string, any>;
+        query: Record<string, any> | undefined;
         params: Record<string, string> | undefined;
         ip: string | undefined;
         incoming: boolean;
@@ -42,7 +42,7 @@ export declare const buildAs2IncomingPayload: (event: IncomingEvent<MatchedIncom
     http: {
         url: string;
         method: string;
-        query: Record<string, any>;
+        query: Record<string, any> | undefined;
         params: Record<string, string> | undefined;
         ip: string | undefined;
         incoming: boolean;

package/dist/lib/utils.js

@@ -46,18 +46,57 @@ const getIncomingRequest = async (request) => {
         params: parseParams(request),
     };
 };
+/**
+ * Outer body ceiling for EVERY workflow endpoint, matched to the ingress contract
+ * (apps/ingress `maxRequestBodySize`, 100 MiB) — this reader runs for all routes before
+ * dispatch, so a tighter value here silently shrinks the supported payload of unrelated
+ * customer endpoints and strands queued S3-backed events in the 64–100 MiB band. AS2's own
+ * far tighter bounds live downstream where the route is known (the API route's 48 MiB
+ * bodyLimit and the engine's 24 MiB raw ceiling); per-tenant AS2 flood protection is T-3265.
+ * The cap still bounds one request from the declared length, or as the stream crosses it,
+ * before a full copy materializes.
+ */
+const MAX_REQUEST_BODY_BYTES = 100 * 1024 * 1024;
 const readBody = async (request) => {
+    const declared = Number(request.header('content-length') ?? Number.NaN);
+    if (Number.isFinite(declared) && declared > MAX_REQUEST_BODY_BYTES) {
+        throw new error_1.ServerError({ status: 413, message: 'Request body too large.' });
+    }
     try {
-        return await request.arrayBuffer();
+        const stream = request.raw.body;
+        if (!stream)
+            return new ArrayBuffer(0);
+        const chunks = [];
+        let total = 0;
+        const reader = stream.getReader();
+        while (true) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            total += next.value.byteLength;
+            if (total > MAX_REQUEST_BODY_BYTES) {
+                await reader.cancel();
+                throw new error_1.ServerError({ status: 413, message: 'Request body too large.' });
+            }
+            chunks.push(next.value);
+        }
+        const bytes = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return bytes.buffer;
     }
     catch (error) {
+        if (error instanceof error_1.ServerError)
+            throw error;
         throw new error_1.ServerError({ status: 400, message: 'Failed to read request body.', cause: error });
     }
 };
 /**
- * The customer trace ID the product groups logs by — a logger-SDK UUID. Public callers
- * can set the trace header, so anything non-canonical (oversized values, W3C
- * traceparents, arbitrary strings) is ignored and a fresh trace is minted instead.
+ * AS2's verify-then-bind boundary uses this to accept only ledger-owned trace IDs.
+ * Generic event routes preserve their historical correlation-header contract below.
  */
 const CANONICAL_TRACE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const isCanonicalTraceId = (value) => typeof value === 'string' && CANONICAL_TRACE_ID.test(value);
@@ -65,7 +104,7 @@ exports.isCanonicalTraceId = isCanonicalTraceId;
 const getMetadataFromRequest = (request, source) => {
     const headerTraceId = request.headers[types_1.defaultTraceHeaderKey];
     return {
-        traceId: (0, exports.isCanonicalTraceId)(headerTraceId) ? headerTraceId : (0, unnbound_logger_sdk_1.getTraceId)(),
+        traceId: headerTraceId || (0, unnbound_logger_sdk_1.getTraceId)(),
         messageId: request.headers[types_1.defaultMessageHeaderKey] ?? (0, trace_1.getMessageId)(),
         source,
     };
@@ -164,15 +203,30 @@ const buildResponsePayloadWith = (headersPolicy, result) => {
         body: body ? describeBody(body, declaredHeaders?.['content-type']) : undefined,
     };
 };
-const buildIncomingPayloadWith = (headersPolicy) => (event, result) => {
+/**
+ * Drop the URL's search component so no query-string credential (a `?token=…` on the
+ * inbound AS2 endpoint) survives into customer-visible trace data. The AS2 header allowlist
+ * already scrubs sensitive headers; the URL and its parsed query bypassed it entirely.
+ */
+const stripUrlQuery = (rawUrl) => {
+    try {
+        const url = new URL(rawUrl);
+        url.search = '';
+        return url.toString();
+    }
+    catch {
+        return rawUrl.split('?', 1)[0] ?? rawUrl;
+    }
+};
+const buildIncomingPayloadWith = (headersPolicy, redactUrlQuery = false) => (event, result) => {
     return {
         type: 'http',
         source: event.metadata.source,
         delay: event.metadata.source === 'queue' ? Date.now() - event.timestamp : undefined,
         http: {
-            url: event.request.url,
+            url: redactUrlQuery ? stripUrlQuery(event.request.url) : event.request.url,
             method: event.request.method.toLowerCase(),
-            query: event.request.query,
+            query: redactUrlQuery ? undefined : event.request.query,
             params: event.request.params,
             ip: (0, utils_1.normalizeIp)(event.request.headers['cf-connecting-ip'] ??
                 event.request.headers['x-forwarded-for'] ??
@@ -191,7 +245,7 @@ const buildIncomingPayloadWith = (headersPolicy) => (event, result) => {
     };
 };
 exports.buildIncomingPayload = buildIncomingPayloadWith(headersForTrace);
-exports.buildAs2IncomingPayload = buildIncomingPayloadWith(as2HeadersForTrace);
+exports.buildAs2IncomingPayload = buildIncomingPayloadWith(as2HeadersForTrace, true);
 const batchArray = (array, size) => {
     return [...Array(Math.ceil(array.length / size))].map((_, i) => array.slice(i * size, i * size + size));
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "unnbound-events",
   "description": "Unified events SDK to handle HTTP routes and queued messages with a single routing API.",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "author": "Unnbound Team",