unnbound-events 3.0.0-beta.2 → 3.1.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-response.typecheck.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/routing/as2-response.typecheck.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+function assertAs2ResponseAssignableToHandlerResult(response) {
+    // If As2HttpResponse ever widens `status` back to `number`, or StrictEventHandlerResult's
+    // `status` narrows further than Hono's StatusCode, this return stops compiling.
+    return response;
+}
+// Referenced so `noUnusedLocals`-style checks never flag this fixture as dead code.
+void assertAs2ResponseAssignableToHandlerResult;

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

@@ -0,0 +1,56 @@
+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
+ * // identity/partner are plain objects built inline from ordinary scalar workflow
+ * // variables — never a variable name passed to `as2.receive`/`as2.send` (see
+ * // @ontemper/as2's README). partner.mdn.to only matters for outbound `as2.send`.
+ * const identity = { as2Id: 'ACME-TEMPER', keypairs: [{ certPem: process.env.AS2_CERT_PEM!, keyPem: process.env.AS2_KEY_PEM! }] };
+ * const partner = { as2Id: 'ACME', url: process.env.ACME_AS2_URL!, certs: [process.env.ACME_CERT_PEM!] };
+ *
+ * server.post('/as2/inbound', as2Endpoint(
+ *   ({ headers, body }) => as2.receive({ headers, body: Buffer.from(body as ArrayBuffer), partner, identity }),
+ *   async (result) => {
+ *     if (result.kind === 'received') {
+ *       // Delivery is at-least-once, so make processing idempotent by Message-ID.
+ *       await processDocument(result.payload);
+ *       const receipt = await result.acknowledge();
+ *       // Async MDN partners get no receipt unless you deliver it explicitly — the
+ *       // response below is deliberately an empty 200 in that mode.
+ *       if (receipt.mdnMode === 'async' && receipt.mdn && receipt.mdnDeliveryUrl) {
+ *         await as2.deliverMdn(receipt.mdn, receipt.mdnDeliveryUrl);
+ *       }
+ *       return receipt.response;
+ *     }
+ *     // Duplicate retries need the same async redelivery, or the partner never settles.
+ *     if (result.kind === 'duplicate' && result.mdnMode === 'async' && result.mdn && result.mdnDeliveryUrl) {
+ *       await as2.deliverMdn(result.mdn, result.mdnDeliveryUrl);
+ *     }
+ *     return result.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,118 @@
+"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");
+const response_1 = require("./response");
+/**
+ * Transient platform failures a partner should re-send against. `As2SdkError` already computed
+ * these from the platform response, but it arrives here as a plain unknown — this package cannot
+ * import `@ontemper/as2` (the dependency runs the other way), so the shape is read defensively.
+ */
+const RETRYABLE_AS2_STATUSES = [502, 503, 504];
+/**
+ * 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.
+ */
+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,
+            });
+        }
+    }
+    return error_1.ServerError.fromError(error);
+};
+/**
+ * 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
+ * // identity/partner are plain objects built inline from ordinary scalar workflow
+ * // variables — never a variable name passed to `as2.receive`/`as2.send` (see
+ * // @ontemper/as2's README). partner.mdn.to only matters for outbound `as2.send`.
+ * const identity = { as2Id: 'ACME-TEMPER', keypairs: [{ certPem: process.env.AS2_CERT_PEM!, keyPem: process.env.AS2_KEY_PEM! }] };
+ * const partner = { as2Id: 'ACME', url: process.env.ACME_AS2_URL!, certs: [process.env.ACME_CERT_PEM!] };
+ *
+ * server.post('/as2/inbound', as2Endpoint(
+ *   ({ headers, body }) => as2.receive({ headers, body: Buffer.from(body as ArrayBuffer), partner, identity }),
+ *   async (result) => {
+ *     if (result.kind === 'received') {
+ *       // Delivery is at-least-once, so make processing idempotent by Message-ID.
+ *       await processDocument(result.payload);
+ *       const receipt = await result.acknowledge();
+ *       // Async MDN partners get no receipt unless you deliver it explicitly — the
+ *       // response below is deliberately an empty 200 in that mode.
+ *       if (receipt.mdnMode === 'async' && receipt.mdn && receipt.mdnDeliveryUrl) {
+ *         await as2.deliverMdn(receipt.mdn, receipt.mdnDeliveryUrl);
+ *       }
+ *       return receipt.response;
+ *     }
+ *     // Duplicate retries need the same async redelivery, or the partner never settles.
+ *     if (result.kind === 'duplicate' && result.mdnMode === 'async' && result.mdn && result.mdnDeliveryUrl) {
+ *       await as2.deliverMdn(result.mdn, result.mdnDeliveryUrl);
+ *     }
+ *     return result.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 = toWireFailure(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, response_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, response_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.
+                // `acknowledge()` runs in here too, so a transient platform failure keeps its
+                // retryable status rather than becoming an indistinguishable 500.
+                const result = toWireFailure(error).toJson();
+                return { ...result, headers: (0, response_1.attachTraceHeaders)(result.headers) };
+            }
+        }, { traceId });
+    });
+};
+exports.as2Endpoint = as2Endpoint;

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

@@ -1,8 +1,9 @@
 import type { Context } from 'hono';
-import type { EventHandlerResult } from '../event';
+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,10 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.patchEndpoint = exports.parseEndpointArguments = exports.buildEndpointArguments = void 0;
+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");
 const response_1 = require("./response");
+/**
+ * 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);
@@ -22,10 +34,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: (0, response_1.resolveStatus)(result), 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: (0, response_1.resolveStatus)(result), headers: result?.headers, body: result?.body };
+            }, (o) => (0, utils_1.buildIncomingPayload)(state, o));
         return (0, response_1.respondWith)(context, result);
     };
 };

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 } 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: Pick<IncomingRequest, 'headers'>, source: EventSource) => EventMetadata;
 interface ForwardedMetadata {
     source: EventSource;
@@ -34,5 +35,27 @@ export declare const buildIncomingPayload: (event: IncomingEvent<MatchedIncoming
         } | 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: unknown;
+        };
+        response?: {
+            status: import("hono/utils/http-status").StatusCode;
+            headers: Record<string, string>;
+            body: unknown;
+        } | undefined;
+    };
+};
 export declare const batchArray: <T>(array: T[], size: number) => T[][];
 export {};

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");
@@ -54,11 +54,22 @@ const readBody = async (request) => {
         throw new error_1.ServerError({ status: 400, message: 'Failed to read request body.', cause: error });
     }
 };
-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';
@@ -112,13 +123,36 @@ const headersForTrace = (headers) => Object.fromEntries(Object.entries(headers).
     name,
     REDACTED_TRACE_HEADERS.has(name.toLowerCase()) ? '[redacted]' : value,
 ]));
-const buildResponsePayload = (result) => {
+// 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 buildResponsePayloadWith = (headersPolicy, result) => {
     const declaredHeaders = result?.headers
         ? Object.fromEntries(Object.entries((0, exports.normalizeHeaders)(result.headers)).map(([name, value]) => [name.toLowerCase(), value]))
         : undefined;
     // Binary responses keep declared headers; JSON gets the SDK default.
     // The declared content type also controls trace decoding.
-    const traceHeaders = headersForTrace(declaredHeaders ?? {});
+    const traceHeaders = headersPolicy(declaredHeaders ?? {});
     const status = (0, response_1.resolveStatus)(result);
     // Mirror the wire: respondWith drops the body on contentless statuses, so the
     // trace must not claim one — nor a content type for a body never sent.
@@ -130,7 +164,7 @@ const buildResponsePayload = (result) => {
         body: body ? describeBody(body, declaredHeaders?.['content-type']) : undefined,
     };
 };
-const buildIncomingPayload = (event, result) => {
+const buildIncomingPayloadWith = (headersPolicy) => (event, result) => {
     return {
         type: 'http',
         source: event.metadata.source,
@@ -145,18 +179,19 @@ const buildIncomingPayload = (event, result) => {
                 event.request.headers['x-real-ip']),
             incoming: true,
             request: {
-                headers: headersForTrace(event.request.headers),
+                headers: headersPolicy(event.request.headers),
                 body: describeBody(event.request.body, event.request.headers['content-type']),
             },
             ...(result && {
                 response: result.error
-                    ? buildResponsePayload(error_1.ServerError.fromError(result.error).toJson())
-                    : buildResponsePayload(result.result),
+                    ? buildResponsePayloadWith(headersPolicy, error_1.ServerError.fromError(result.error).toJson())
+                    : buildResponsePayloadWith(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": "3.0.0-beta.2",
+  "version": "3.1.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"
   },
   "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"
+  }
+}