unnbound-events 2.0.21-beta.0 → 2.1.0-beta.0

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { createEnqueuer } from './lib/enqueue';
 export type { ServerErrorOptions } from './lib/error';
 export { ServerError } from './lib/error';
 export type { EventMetadata, EventSource, IncomingEvent, IncomingRequest } from './lib/event';
+export type { As2Prepared, As2RawRequest } from './lib/routing/as2';
+export { as2Endpoint } from './lib/routing/as2';
 export type { Handler } from './lib/routing/endpoint';
 export type { MiddlewareHandler } from './lib/routing/middleware';
 export type { EventVariables, MaybePromise } from './lib/routing/types';

package/dist/index.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createServer = exports.ServerError = exports.createEnqueuer = void 0;
+exports.createServer = exports.as2Endpoint = exports.ServerError = exports.createEnqueuer = void 0;
 var enqueue_1 = require("./lib/enqueue");
 Object.defineProperty(exports, "createEnqueuer", { enumerable: true, get: function () { return enqueue_1.createEnqueuer; } });
 var error_1 = require("./lib/error");
 Object.defineProperty(exports, "ServerError", { enumerable: true, get: function () { return error_1.ServerError; } });
+var as2_1 = require("./lib/routing/as2");
+Object.defineProperty(exports, "as2Endpoint", { enumerable: true, get: function () { return as2_1.as2Endpoint; } });
 var server_1 = require("./lib/server");
 Object.defineProperty(exports, "createServer", { enumerable: true, get: function () { return server_1.createServer; } });

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

@@ -0,0 +1,37 @@
+import type { EventHandlerResult } from '../event';
+import { type Handler } from './endpoint';
+import type { EventVariables, MaybePromise } from './types';
+/** Raw wire request handed to the platform verification call, byte-exact. */
+export interface As2RawRequest {
+    headers: Record<string, string>;
+    body: ArrayBuffer | Uint8Array | string | undefined;
+}
+/**
+ * Result of the platform verification call. `as2.receive` results carry the exchange's
+ * canonical customer trace (recovered from the ledger for a loopback, server-minted for
+ * an external inbound); `as2.confirm` results deliberately do not — an async MDN
+ * callback is its own execution and stays on its own trace, linked by Message-ID.
+ */
+export interface As2Prepared {
+    customerTraceId?: string | null;
+}
+/**
+ * Verify-then-bind AS2 endpoint. The public `x-unnbound-trace-id` header is never AS2
+ * continuation authority: the route starts on a fresh trace, runs `prepare` (the hidden
+ * `as2.receive`/`as2.confirm` platform call) before any customer request span exists,
+ * and only a verified ledger-backed trace may re-bind the request. Unverified traffic
+ * 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.
+ *
+ * ```ts
+ * server.post('/as2/inbound', as2Endpoint(
+ *   ({ headers, body }) => as2.receive({ headers, body: Buffer.from(body as ArrayBuffer), partner: 'AS2_PARTNER' }),
+ *   async (result) => {
+ *     if (result.kind !== 'received') return result.response;
+ *     await processDocument(result.payload);
+ *     return (await result.acknowledge()).response;
+ *   },
+ * ));
+ * ```
+ */
+export declare const as2Endpoint: <V extends object, P extends object>(prepare: (request: As2RawRequest, event: EventVariables<V>) => Promise<P>, handler: (prepared: P, event: EventVariables<V>) => MaybePromise<EventHandlerResult>) => Handler<EventVariables<V>>;

package/dist/lib/routing/as2.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.as2Endpoint = void 0;
+const unnbound_logger_sdk_1 = require("unnbound-logger-sdk");
+const error_1 = require("../error");
+const utils_1 = require("../utils");
+const endpoint_1 = require("./endpoint");
+/**
+ * Verify-then-bind AS2 endpoint. The public `x-unnbound-trace-id` header is never AS2
+ * continuation authority: the route starts on a fresh trace, runs `prepare` (the hidden
+ * `as2.receive`/`as2.confirm` platform call) before any customer request span exists,
+ * and only a verified ledger-backed trace may re-bind the request. Unverified traffic
+ * 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.
+ *
+ * ```ts
+ * server.post('/as2/inbound', as2Endpoint(
+ *   ({ headers, body }) => as2.receive({ headers, body: Buffer.from(body as ArrayBuffer), partner: 'AS2_PARTNER' }),
+ *   async (result) => {
+ *     if (result.kind !== 'received') return result.response;
+ *     await processDocument(result.payload);
+ *     return (await result.acknowledge()).response;
+ *   },
+ * ));
+ * ```
+ */
+// P is constrained to object, not As2Prepared: prepared results are unions whose
+// members don't all carry customerTraceId (e.g. inFlight/parked), and TypeScript's
+// 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)();
+        let prepared;
+        try {
+            prepared = await (0, unnbound_logger_sdk_1.withTrace)(() => prepare({ headers: event.request.headers, body: event.request.body }, event), {
+                traceId: requestTraceId,
+            });
+        }
+        catch (error) {
+            return (0, unnbound_logger_sdk_1.withTrace)(async () => {
+                const failure = error_1.ServerError.fromError(error);
+                // Bookend the request on its own failure trace: the span records the sanitized
+                // AS2 payload and rethrows; the wire response carries no protocol claims.
+                await (0, unnbound_logger_sdk_1.startSpan)('Event request', () => Promise.reject(failure), (o) => (0, utils_1.buildAs2IncomingPayload)(event, o)).catch(() => undefined);
+                const result = failure.toJson();
+                return { ...result, headers: (0, endpoint_1.attachTraceHeaders)(result.headers) };
+            }, { traceId: requestTraceId });
+        }
+        const verified = prepared.customerTraceId;
+        const traceId = (0, utils_1.isCanonicalTraceId)(verified) ? verified : requestTraceId;
+        return (0, unnbound_logger_sdk_1.withTrace)(async () => {
+            // Response trace headers must be attached inside this scope: respondWith runs after
+            // the re-bound trace exits and would otherwise advertise the pre-bind trace.
+            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 };
+                }, (o) => (0, utils_1.buildAs2IncomingPayload)(event, o));
+                return { ...result, headers: (0, endpoint_1.attachTraceHeaders)(result.headers) };
+            }
+            catch (error) {
+                // The span above already logged the failure on the bound trace; respond with the
+                // sanitized shape instead of rethrowing into the header-derived middleware trace.
+                const result = error_1.ServerError.fromError(error).toJson();
+                return { ...result, headers: (0, endpoint_1.attachTraceHeaders)(result.headers) };
+            }
+        }, { traceId });
+    });
+};
+exports.as2Endpoint = as2Endpoint;

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

@@ -3,6 +3,7 @@ import type { EventHandlerResult, StrictEventHandlerResult } from '../event';
 import { type MiddlewareHandler } from './middleware';
 import type { EventEnvironment, EventVariables, MaybePromise } from './types';
 export type Handler<I, R = EventHandlerResult> = (input: I) => MaybePromise<R>;
+export declare const markSelfTraced: <I>(handler: (input: I) => Promise<StrictEventHandlerResult>) => Handler<I>;
 export interface Endpoint<I> {
     (path: string, handler: Handler<I>): MaybePromise<void>;
     (path: string, middleware: MiddlewareHandler<I>, handler: Handler<I>): MaybePromise<void>;

package/dist/lib/routing/endpoint.js

@@ -1,9 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.attachTraceHeaders = exports.respondWith = exports.patchEndpoint = exports.parseEndpointArguments = exports.buildEndpointArguments = void 0;
+exports.attachTraceHeaders = exports.respondWith = exports.patchEndpoint = exports.parseEndpointArguments = exports.buildEndpointArguments = exports.markSelfTraced = void 0;
 const unnbound_logger_sdk_1 = require("unnbound-logger-sdk");
 const utils_1 = require("../utils");
 const middleware_1 = require("./middleware");
+/**
+ * Marks a handler that owns its customer trace and request span. The generic endpoint
+ * wrapper binds the header-derived trace before running a handler; AS2 endpoints must
+ * instead verify the protocol exchange first and only then choose the trace, so their
+ * wrapper (see routing/as2.ts) emits the request span itself and returns a strict result.
+ */
+const selfTraced = Symbol.for('unnbound-events.selfTraced');
+const markSelfTraced = (handler) => {
+    return Object.assign(handler, { [selfTraced]: true });
+};
+exports.markSelfTraced = markSelfTraced;
+const isSelfTraced = (handler) => selfTraced in handler;
 const buildEndpointArguments = (...args) => {
     const { path, middlewares, handler } = (0, exports.parseEndpointArguments)(...args);
     const patchedHandler = (0, exports.patchEndpoint)(handler);
@@ -21,10 +33,12 @@ const patchEndpoint = (handler) => {
         const state = context.get('state');
         // We have to recalculate the params because the handler path might contain url params
         state.request.params = { ...state.request.params, ...context.req.param() };
-        const result = await (0, unnbound_logger_sdk_1.startSpan)('Event request', async () => {
-            const result = await handler(state);
-            return { status: result?.status ?? 204, headers: result?.headers, body: result?.body };
-        }, (o) => (0, utils_1.buildIncomingPayload)(state, o));
+        const result = isSelfTraced(handler)
+            ? await handler(state)
+            : await (0, unnbound_logger_sdk_1.startSpan)('Event request', async () => {
+                const result = await handler(state);
+                return { status: result?.status ?? 204, headers: result?.headers, body: result?.body };
+            }, (o) => (0, utils_1.buildIncomingPayload)(state, o));
         return (0, exports.respondWith)(context, result);
     };
 };
@@ -33,13 +47,9 @@ const respondWith = (context, result) => {
     const headers = (0, exports.attachTraceHeaders)(result.headers);
     if (!result.body)
         return context.body(null, result.status, headers);
-    // Binary bodies (Buffer/Uint8Array/ArrayBuffer) go out verbatim — JSON-serializing
-    // them corrupts wire protocols like AS2, whose signed S/MIME MDN response must be
-    // byte-exact. Buffers can be views over a pooled ArrayBuffer, so slice to the view.
+    // Signed protocol responses such as AS2 MDNs must remain byte-exact.
     if (result.body instanceof Uint8Array || result.body instanceof ArrayBuffer) {
-        const bytes = result.body instanceof ArrayBuffer
-            ? result.body
-            : result.body.buffer.slice(result.body.byteOffset, result.body.byteOffset + result.body.byteLength);
+        const bytes = result.body instanceof ArrayBuffer ? result.body : Uint8Array.from(result.body).buffer;
         return context.body(bytes, result.status, headers);
     }
     return context.json(result.body, result.status, headers);

package/dist/lib/utils.d.ts

@@ -3,6 +3,7 @@ import { type Maybe } from 'unnbound-logger-sdk/dist/types';
 import type { EventHandlerResult, EventMetadata, EventSource, IncomingEvent, IncomingRequest, MatchedIncomingRequest, StrictEventHandlerResult } from './event';
 export declare const normalizeHeaders: (headers: Record<string, string | string[]>) => Record<string, string>;
 export declare const getIncomingEvent: (event: HonoRequest) => Promise<IncomingEvent<MatchedIncomingRequest>>;
+export declare const isCanonicalTraceId: (value: string | undefined | null) => value is string;
 export declare const getMetadataFromRequest: (request: IncomingRequest, source: EventSource) => EventMetadata;
 interface ForwardedMetadata {
     source: EventSource;
@@ -25,7 +26,25 @@ export declare const buildIncomingPayload: (event: IncomingEvent<MatchedIncoming
         incoming: boolean;
         request: {
             headers: Record<string, string>;
-            body: unknown;
+            body: object;
+        };
+        response?: StrictEventHandlerResult | undefined;
+    };
+};
+export declare const buildAs2IncomingPayload: (event: IncomingEvent<MatchedIncomingRequest>, result?: Maybe<EventHandlerResult>) => {
+    type: string;
+    source: EventSource;
+    delay: number | undefined;
+    http: {
+        url: string;
+        method: string;
+        query: Record<string, any>;
+        params: Record<string, string> | undefined;
+        ip: string | undefined;
+        incoming: boolean;
+        request: {
+            headers: Record<string, string>;
+            body: object;
         };
         response?: StrictEventHandlerResult | undefined;
     };

package/dist/lib/utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.batchArray = exports.buildIncomingPayload = exports.serializeMetadata = exports.getMetadataFromRequest = exports.getIncomingEvent = exports.normalizeHeaders = void 0;
+exports.batchArray = exports.buildAs2IncomingPayload = exports.buildIncomingPayload = exports.serializeMetadata = exports.getMetadataFromRequest = exports.isCanonicalTraceId = exports.getIncomingEvent = exports.normalizeHeaders = void 0;
 const unnbound_logger_sdk_1 = require("unnbound-logger-sdk");
 const trace_1 = require("unnbound-logger-sdk/dist/trace");
 const types_1 = require("unnbound-logger-sdk/dist/types");
@@ -61,11 +61,22 @@ const parseBody = async (request, headers) => {
         return undefined;
     }
 };
-const getMetadataFromRequest = (request, source) => ({
-    traceId: request.headers[types_1.defaultTraceHeaderKey] ?? (0, unnbound_logger_sdk_1.getTraceId)(),
-    messageId: request.headers[types_1.defaultMessageHeaderKey] ?? (0, trace_1.getMessageId)(),
-    source,
-});
+/**
+ * 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.
+ */
+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);
+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)(),
+        messageId: request.headers[types_1.defaultMessageHeaderKey] ?? (0, trace_1.getMessageId)(),
+        source,
+    };
+};
 exports.getMetadataFromRequest = getMetadataFromRequest;
 const sourceKey = 'x-unnbound-source';
 const timestampKey = 'x-unnbound-timestamp';
@@ -76,24 +87,61 @@ const serializeMetadata = (metadata) => ({
 exports.serializeMetadata = serializeMetadata;
 const deserializeMetadata = (request) => ({
     source: request.headers[sourceKey],
-    timestamp: request.headers[timestampKey] ? Number.parseInt(request.headers[timestampKey]) : undefined,
+    timestamp: request.headers[timestampKey] ? Number.parseInt(request.headers[timestampKey], 10) : undefined,
 });
-/** Trace-safe body representation: binary bodies become a marker, not a byte dump. */
 const describeBody = (body) => {
     if (body instanceof Uint8Array || body instanceof ArrayBuffer) {
         return { binary: true, byteLength: body.byteLength };
     }
     return (0, utils_1.safeJsonParse)(body);
 };
-const buildResponsePayload = (result) => ({
+// Trace payloads are shipped to the logging pipeline; credentials must never ride along
+// regardless of body shape (JSON, text, or binary — e.g. AS2's signed/encrypted MIME).
+const REDACTED_TRACE_HEADERS = new Set([
+    'authorization',
+    'proxy-authorization',
+    'cookie',
+    'set-cookie',
+    'x-service-token',
+    'x-api-key',
+    'x-auth-token',
+]);
+const headersForTrace = (headers) => Object.fromEntries(Object.entries(headers).map(([name, value]) => [
+    name,
+    REDACTED_TRACE_HEADERS.has(name.toLowerCase()) ? '[redacted]' : value,
+]));
+// AS2 routes carry partner-controlled protocol headers, so logging flips from a
+// redaction denylist to an allowlist: protocol identity/framing and Temper correlation
+// headers pass; everything else is redacted. Receipt-Delivery-Option (its URL may embed
+// query credentials) and Subject (business metadata) are deliberately NOT listed.
+const AS2_TRACE_HEADER_ALLOWLIST = new Set([
+    'as2-from',
+    'as2-to',
+    'as2-version',
+    'content-length',
+    'content-transfer-encoding',
+    'content-type',
+    'date',
+    'disposition-notification-options',
+    'disposition-notification-to',
+    'message-id',
+    'mime-version',
+    'x-message-id',
+    'x-unnbound-trace-id',
+]);
+const as2HeadersForTrace = (headers) => Object.fromEntries(Object.entries(headers).map(([name, value]) => [
+    name,
+    AS2_TRACE_HEADER_ALLOWLIST.has(name.toLowerCase()) ? value : '[redacted]',
+]));
+const buildResponsePayload = (headersPolicy, result) => ({
     status: result?.status ?? 204,
-    headers: {
+    headers: headersPolicy({
         'content-type': 'application/json; charset=utf-8',
         ...(result?.headers ? (0, exports.normalizeHeaders)(result.headers) : undefined),
-    },
+    }),
     body: result?.body ? describeBody(result.body) : undefined,
 });
-const buildIncomingPayload = (event, result) => {
+const buildIncomingPayloadWith = (headersPolicy) => (event, result) => {
     return {
         type: 'http',
         source: event.metadata.source,
@@ -108,18 +156,19 @@ const buildIncomingPayload = (event, result) => {
                 event.request.headers['x-real-ip']),
             incoming: true,
             request: {
-                headers: event.request.headers,
+                headers: headersPolicy(event.request.headers),
                 body: describeBody(event.request.body),
             },
             ...(result && {
                 response: result.error
-                    ? buildResponsePayload(error_1.ServerError.fromError(result.error).toJson())
-                    : buildResponsePayload(result.result),
+                    ? buildResponsePayload(headersPolicy, error_1.ServerError.fromError(result.error).toJson())
+                    : buildResponsePayload(headersPolicy, result.result),
             }),
         },
     };
 };
-exports.buildIncomingPayload = buildIncomingPayload;
+exports.buildIncomingPayload = buildIncomingPayloadWith(headersForTrace);
+exports.buildAs2IncomingPayload = buildIncomingPayloadWith(as2HeadersForTrace);
 const batchArray = (array, size) => {
     return [...Array(Math.ceil(array.length / size))].map((_, i) => array.slice(i * size, i * size + size));
 };

package/package.json

@@ -1,19 +1,9 @@
 {
   "name": "unnbound-events",
   "description": "Unified events SDK to handle HTTP routes and queued messages with a single routing API.",
-  "version": "2.0.21-beta.0",
+  "version": "2.1.0-beta.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "format": "biome format --write .",
-    "format:check": "biome format .",
-    "prepublishOnly": "pnpm run build",
-    "start:example": "tsx watch examples/node-server.ts",
-    "version:bump": "npm version patch"
-  },
   "author": "Unnbound Team",
   "license": "MIT",
   "repository": {
@@ -30,7 +20,7 @@
     "@hono/node-server": "^1.19.11",
     "axios": "1.16.0",
     "hono": "^4.12.21",
-    "unnbound-logger-sdk": "^3.0.34"
+    "unnbound-logger-sdk": "3.1.0-beta.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.12",
@@ -45,5 +35,14 @@
   "engines": {
     "node": ">=22"
   },
-  "sideEffects": false
-}
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "start:example": "tsx watch examples/node-server.ts",
+    "version:bump": "npm version patch"
+  }
+}