@wirebench/engine 2.2.0 → 3.1.0-rc.1

package/dist/http/transcript-cap.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The cap History puts on a long exchange: both ends kept, then a byte budget.
+ *
+ * In `http/` because a WebSocket session's frames and a REST event stream's rows are capped the same
+ * way, and a protocol folder imports core and itself, never another protocol (protocol modules spec
+ * §7.2). `ws/transcript.ts` re-exports every name, under the names they have always had.
+ */
+export declare const WS_HISTORY_HEAD = 400;
+export declare const WS_HISTORY_TAIL = 100;
+export declare const WS_HISTORY_MAX_BYTES = 1048576;
+export interface CapLimits {
+    readonly head: number;
+    readonly tail: number;
+    readonly maxBytes: number;
+}
+/**
+ * Caps a list at both ends: the first `head` and the last `tail` items are kept whole (unless the
+ * whole list already fits), then a byte budget is spent front-to-back, stripping the payload (via
+ * `strip`) of any kept item that would blow the budget. `strip` returns `undefined` when the item has
+ * no payload to lose, in which case it is kept as-is.
+ */
+export declare function capByEnds<T>(items: readonly T[], limits: CapLimits, sizeOf: (item: T) => number, strip: (item: T) => T | undefined): {
+    readonly items: readonly T[];
+    readonly truncated: boolean;
+    readonly omitted: number;
+};

package/dist/http/transcript-cap.js

@@ -0,0 +1,36 @@
+/**
+ * The cap History puts on a long exchange: both ends kept, then a byte budget.
+ *
+ * In `http/` because a WebSocket session's frames and a REST event stream's rows are capped the same
+ * way, and a protocol folder imports core and itself, never another protocol (protocol modules spec
+ * §7.2). `ws/transcript.ts` re-exports every name, under the names they have always had.
+ */
+export const WS_HISTORY_HEAD = 400;
+export const WS_HISTORY_TAIL = 100;
+export const WS_HISTORY_MAX_BYTES = 1_048_576;
+/**
+ * Caps a list at both ends: the first `head` and the last `tail` items are kept whole (unless the
+ * whole list already fits), then a byte budget is spent front-to-back, stripping the payload (via
+ * `strip`) of any kept item that would blow the budget. `strip` returns `undefined` when the item has
+ * no payload to lose, in which case it is kept as-is.
+ */
+export function capByEnds(items, limits, sizeOf, strip) {
+    const limit = limits.head + limits.tail;
+    const kept = items.length <= limit ? [...items] : [...items.slice(0, limits.head), ...items.slice(-limits.tail)];
+    const omitted = items.length - kept.length;
+    let budget = limits.maxBytes;
+    let stripped = false;
+    const capped = kept.map((item) => {
+        const size = sizeOf(item);
+        if (size <= budget) {
+            budget -= size;
+            return item;
+        }
+        const strippedItem = strip(item);
+        if (strippedItem === undefined)
+            return item;
+        stripped = true;
+        return strippedItem;
+    });
+    return { items: capped, truncated: omitted > 0 || stripped, omitted };
+}

package/dist/http/types.d.ts

@@ -22,6 +22,18 @@ export interface HttpRequest {
      * resource needs the choice. 303 always becomes a `GET`: that is what the status means.
      */
     readonly preserveMethodOnRedirect?: boolean;
+    /**
+     * Credentials the caller put on this request for its own origin only, beyond the `Authorization`,
+     * `Proxy-Authorization` and `Cookie` headers every cross-origin hop drops anyway: an API key's
+     * custom header, or the query parameter carrying it.
+     *
+     * On a redirect hop to any other origin the named headers are removed and a parameter with the
+     * given name *and* value is stripped from the `Location`, so a server that echoes the key into it
+     * cannot pass it on. On a hop back to the original origin they are applied again: the headers
+     * with their values as sent on the first request, and the parameter appended when the `Location`
+     * does not already carry it.
+     */
+    readonly originCredentials?: OriginCredentials;
     /** Maximum response body size to buffer, in bytes. Undefined = unlimited. */
     readonly maxSizeBytes?: number;
     readonly signal?: AbortSignal;
@@ -40,6 +52,45 @@ export interface HttpRequest {
      * HTTP is always HTTP/1.1 — there is no ALPN to negotiate over.
      */
     readonly allowH2?: boolean;
+    /**
+     * Opt-in streaming. When set, the final (non-redirect) response is offered to the hook; a sink it
+     * returns receives the body as it arrives instead of it being buffered, the request's deadline
+     * stops applying once the headers are in, and `maxSizeBytes` does not apply. A hook that returns
+     * `undefined` leaves the response buffered exactly as without one.
+     */
+    readonly stream?: HttpStreamHook;
+    /**
+     * The cookie jar, hop by hop (cookie jar spec §1.4). Every attempt's `Cookie` header is what
+     * `header` answers for that attempt's URL, given the hand-set one; every response, a redirect's
+     * included, is reported to `received` with its own URL. Absent: headers go out as given.
+     */
+    readonly cookies?: HttpCookieHook;
+}
+/** What {@link HttpRequest.originCredentials} names: the credential headers and query parameters. */
+export interface OriginCredentials {
+    /** Header names, matched case-insensitively. */
+    readonly headers?: readonly string[];
+    /** Query parameters as the caller added them to the URL, before encoding. */
+    readonly query?: readonly {
+        readonly name: string;
+        readonly value: string;
+    }[];
+}
+/** Where an accepted stream's body goes, chunk by chunk, already decompressed when `decompress` is on. */
+export interface HttpStreamSink {
+    onChunk(bytes: Uint8Array): void;
+}
+/** Decides, from the final response's status and headers, whether its body is streamed. */
+export interface HttpStreamHook {
+    /** Called once with the final (non-redirect) response; returning a sink switches to streaming. */
+    accept(status: number, headers: Readonly<Record<string, string>>): HttpStreamSink | undefined;
+}
+/** How a send carries and stores cookies per hop; see {@link HttpRequest.cookies}. */
+export interface HttpCookieHook {
+    /** The `Cookie` header for a request to `url`; `handSet` is the one the request sets itself, if any. */
+    header(url: string, handSet: string | undefined): string | undefined;
+    /** What a response to `url` set, as its raw headers. */
+    received(url: string, rawHeaders: readonly (readonly [string, string])[]): void;
 }
 /**
  * TLS options, passed through to undici's connector. The Task 49 UI will
@@ -118,6 +169,14 @@ export interface HttpExchange {
      * peer chain verified, and the chain itself. Absent for plain HTTP.
      */
     readonly tls?: SslInfo;
+    /**
+     * Present only when a stream hook accepted the response: who ended the stream. `body` and
+     * `rawBody` are then empty and `rawResponse` holds the status line and headers only.
+     */
+    readonly streamEnd?: {
+        readonly by: 'server' | 'client' | 'error';
+        readonly error?: string;
+    };
 }
 /** Stable, machine-readable classification for {@link HttpError}. */
 export type HttpErrorCode = 'timeout' | 'aborted' | 'connection-refused' | 'dns' | 'tls'

package/dist/http/webhook-signature.d.ts

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+export type SignatureAlgorithm = 'sha1' | 'sha256' | 'sha512';
+export type SignatureScheme = {
+    readonly kind: 'hmac';
+    readonly algorithm: SignatureAlgorithm;
+    readonly encoding: 'hex' | 'base64';
+    /** e.g. `X-Signature`. */
+    readonly header: string;
+    /** e.g. `sha256=`; required on verify when set, and stripped before comparing. */
+    readonly prefix?: string;
+} | {
+    readonly kind: 'timestamped';
+    readonly header: string;
+    readonly toleranceSec: number;
+} | {
+    readonly kind: 'standard';
+    readonly toleranceSec: number;
+};
+/** Why a verification failed, in the order the checks run. */
+export declare const SIGNATURE_FAILURES: readonly ["missing-header", "malformed-header", "mismatch", "stale-timestamp", "key-error"];
+export type SignatureFailure = (typeof SIGNATURE_FAILURES)[number];
+export type SignatureVerdict = {
+    readonly verdict: 'verified';
+} | {
+    readonly verdict: 'failed';
+    readonly reason: SignatureFailure;
+};
+/** Five minutes either way, as the Standard Webhooks specification suggests. */
+export declare const DEFAULT_SIGNATURE_TOLERANCE_SEC = 300;
+/** Whether `text` is non-empty, canonical, padded base64 (one definition, shared with the server's key config). */
+export declare function isCanonicalBase64(text: string): boolean;
+/**
+ * A scheme as the server's API and the project files accept it. Not annotated as
+ * `z.ZodType<SignatureScheme>`: its output has `prefix?: string | undefined`, which
+ * `exactOptionalPropertyTypes` will not assign; {@link toSignatureScheme} closes that gap.
+ */
+export declare const signatureSchemeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"hmac">;
+    algorithm: z.ZodEnum<{
+        sha256: "sha256";
+        sha1: "sha1";
+        sha512: "sha512";
+    }>;
+    encoding: z.ZodEnum<{
+        base64: "base64";
+        hex: "hex";
+    }>;
+    header: z.ZodString;
+    prefix: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"timestamped">;
+    header: z.ZodString;
+    toleranceSec: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"standard">;
+    toleranceSec: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>], "kind">;
+/** A parsed scheme with an absent (or empty) prefix truly absent. */
+export declare function toSignatureScheme(parsed: z.output<typeof signatureSchemeSchema>): SignatureScheme;
+/**
+ * The names of the headers {@link signWebhook} writes under `scheme`, in order: what a record of a
+ * signed send holds, so a replay can tell whether it carries a signature.
+ */
+export declare function signatureHeaderNames(scheme: SignatureScheme): readonly string[];
+/**
+ * The headers that sign `body`. Every value is computed over the exact bytes given, so the caller
+ * signs what goes on the wire, after every expansion and encoding.
+ *
+ * @throws WirebenchError `webhook-signing-secret` for a `standard` secret whose `whsec_` tail is not base64
+ */
+export declare function signWebhook(scheme: SignatureScheme, secret: string, body: Uint8Array, options?: {
+    readonly now?: Date;
+    readonly id?: string;
+}): readonly (readonly [name: string, value: string])[];
+/**
+ * Whether `body` arrived correctly signed under `scheme` and `secret`. Checks run header present →
+ * header parses → timestamp → digest. Never throws: anything unexpected is `failed: key-error`.
+ */
+export declare function verifyWebhook(scheme: SignatureScheme, secret: string, headers: readonly (readonly [string, string])[], body: Uint8Array, options?: {
+    readonly now?: Date;
+}): SignatureVerdict;

package/dist/http/webhook-signature.js

@@ -0,0 +1,227 @@
+/**
+ * Signing and verifying webhooks (spec `2026-09-29-wirebench-webhook-signatures-design.md` §2): three
+ * generic schemes over the exact body bytes. One implementation serves the sender (`sendRest`'s
+ * `sign`) and the receiver (the server's verification on receipt), so each side proves the other.
+ *
+ * Pure over bytes: `node:crypto` supplies the HMAC, the constant-time compare and the random id.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { z } from 'zod';
+import { WirebenchError } from '../errors.js';
+/** Why a verification failed, in the order the checks run. */
+export const SIGNATURE_FAILURES = [
+    'missing-header',
+    'malformed-header',
+    'mismatch',
+    'stale-timestamp',
+    'key-error',
+];
+/** Five minutes either way, as the Standard Webhooks specification suggests. */
+export const DEFAULT_SIGNATURE_TOLERANCE_SEC = 300;
+/** An HTTP field name: RFC 9110 §5.1's `token`. */
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+const HEX = /^[0-9a-fA-F]+$/;
+/** Canonical, padded base64 only: `Buffer.from(…, 'base64')` would silently skip anything else. */
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+/** Whether `text` is non-empty, canonical, padded base64 (one definition, shared with the server's key config). */
+export function isCanonicalBase64(text) {
+    return text.length > 0 && BASE64.test(text);
+}
+const UNIX_SECONDS = /^\d{1,15}$/;
+const STANDARD_SECRET_PREFIX = 'whsec_';
+const DIGEST_BYTES = { sha1: 20, sha256: 32, sha512: 64 };
+const headerName = z.string().min(1).max(100).regex(HEADER_NAME);
+const tolerance = z.number().int().min(1).max(86_400).default(DEFAULT_SIGNATURE_TOLERANCE_SEC);
+/**
+ * A scheme as the server's API and the project files accept it. Not annotated as
+ * `z.ZodType<SignatureScheme>`: its output has `prefix?: string | undefined`, which
+ * `exactOptionalPropertyTypes` will not assign; {@link toSignatureScheme} closes that gap.
+ */
+export const signatureSchemeSchema = z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal('hmac'),
+        algorithm: z.enum(['sha1', 'sha256', 'sha512']),
+        encoding: z.enum(['hex', 'base64']),
+        header: headerName,
+        prefix: z
+            .string()
+            .max(32)
+            .regex(/^[\x21-\x7e]*$/)
+            .optional(),
+    }),
+    z.object({ kind: z.literal('timestamped'), header: headerName, toleranceSec: tolerance }),
+    z.object({ kind: z.literal('standard'), toleranceSec: tolerance }),
+]);
+/** A parsed scheme with an absent (or empty) prefix truly absent. */
+export function toSignatureScheme(parsed) {
+    if (parsed.kind !== 'hmac')
+        return parsed;
+    const { prefix, ...rest } = parsed;
+    return prefix === undefined || prefix === '' ? rest : { ...rest, prefix };
+}
+const utf8 = (text) => Buffer.from(text, 'utf8');
+function mac(algorithm, key, ...parts) {
+    const hmac = createHmac(algorithm, key);
+    for (const part of parts)
+        hmac.update(part);
+    return hmac.digest();
+}
+/** The key bytes: base64 after `whsec_`, else the secret's own UTF-8. `undefined` for a bad base64. */
+function standardKey(secret) {
+    if (!secret.startsWith(STANDARD_SECRET_PREFIX))
+        return utf8(secret);
+    const encoded = secret.slice(STANDARD_SECRET_PREFIX.length);
+    return isCanonicalBase64(encoded) ? Buffer.from(encoded, 'base64') : undefined;
+}
+const unixSeconds = (now) => Math.floor(now.getTime() / 1000);
+/**
+ * The names of the headers {@link signWebhook} writes under `scheme`, in order: what a record of a
+ * signed send holds, so a replay can tell whether it carries a signature.
+ */
+export function signatureHeaderNames(scheme) {
+    return scheme.kind === 'standard' ? ['webhook-id', 'webhook-timestamp', 'webhook-signature'] : [scheme.header];
+}
+/**
+ * The headers that sign `body`. Every value is computed over the exact bytes given, so the caller
+ * signs what goes on the wire, after every expansion and encoding.
+ *
+ * @throws WirebenchError `webhook-signing-secret` for a `standard` secret whose `whsec_` tail is not base64
+ */
+export function signWebhook(scheme, secret, body, options = {}) {
+    const now = options.now ?? new Date();
+    switch (scheme.kind) {
+        case 'hmac':
+            return [
+                [scheme.header, `${scheme.prefix ?? ''}${mac(scheme.algorithm, secret, body).toString(scheme.encoding)}`],
+            ];
+        case 'timestamped': {
+            const t = String(unixSeconds(now));
+            return [[scheme.header, `t=${t},v1=${mac('sha256', secret, utf8(`${t}.`), body).toString('hex')}`]];
+        }
+        case 'standard': {
+            const key = standardKey(secret);
+            if (key === undefined) {
+                throw new WirebenchError('webhook-signing-secret', 'The signing secret starts with whsec_ but the rest is not base64');
+            }
+            const id = options.id ?? `msg_${randomBytes(16).toString('hex')}`;
+            const t = String(unixSeconds(now));
+            return [
+                ['webhook-id', id],
+                ['webhook-timestamp', t],
+                ['webhook-signature', `v1,${mac('sha256', key, utf8(`${id}.${t}.`), body).toString('base64')}`],
+            ];
+        }
+    }
+}
+const VERIFIED = { verdict: 'verified' };
+const failed = (reason) => ({ verdict: 'failed', reason });
+/** The first header named `name`, any case, trimmed. */
+function headerValue(headers, name) {
+    const lower = name.toLowerCase();
+    return headers.find(([key]) => key.toLowerCase() === lower)?.[1].trim();
+}
+/** A received digest as bytes, or `undefined` unless it is `encoding` of exactly `bytes` bytes. */
+function decodeDigest(text, encoding, bytes) {
+    const valid = encoding === 'hex' ? HEX.test(text) && text.length === bytes * 2 : isCanonicalBase64(text);
+    if (!valid)
+        return undefined;
+    const decoded = Buffer.from(text, encoding);
+    return decoded.length === bytes ? decoded : undefined;
+}
+const same = (a, b) => a.length === b.length && timingSafeEqual(a, b);
+const within = (t, now, toleranceSec) => Math.abs(unixSeconds(now) - t) <= toleranceSec;
+const isDefined = (value) => value !== undefined;
+function verifyHmac(scheme, secret, headers, body) {
+    let value = headerValue(headers, scheme.header);
+    if (value === undefined)
+        return failed('missing-header');
+    const prefix = scheme.prefix ?? '';
+    if (prefix !== '') {
+        if (!value.startsWith(prefix))
+            return failed('malformed-header');
+        value = value.slice(prefix.length);
+    }
+    const received = decodeDigest(value, scheme.encoding, DIGEST_BYTES[scheme.algorithm]);
+    if (received === undefined)
+        return failed('malformed-header');
+    return same(received, mac(scheme.algorithm, secret, body)) ? VERIFIED : failed('mismatch');
+}
+/** `t=<seconds>,v1=<hex>[,v1=…]`; unknown keys and parts without `=` are ignored. */
+function parseTimestamped(value) {
+    let t;
+    const v1 = [];
+    for (const part of value.split(',')) {
+        const at = part.indexOf('=');
+        if (at === -1)
+            continue;
+        const key = part.slice(0, at).trim();
+        const text = part.slice(at + 1).trim();
+        if (key === 't') {
+            if (t !== undefined || !UNIX_SECONDS.test(text))
+                return undefined;
+            t = text;
+        }
+        else if (key === 'v1') {
+            const digest = decodeDigest(text, 'hex', 32);
+            if (digest !== undefined)
+                v1.push(digest);
+        }
+    }
+    return t === undefined || v1.length === 0 ? undefined : { t, v1 };
+}
+function verifyTimestamped(scheme, secret, headers, body, now) {
+    const value = headerValue(headers, scheme.header);
+    if (value === undefined)
+        return failed('missing-header');
+    const parsed = parseTimestamped(value);
+    if (parsed === undefined)
+        return failed('malformed-header');
+    if (!within(Number(parsed.t), now, scheme.toleranceSec))
+        return failed('stale-timestamp');
+    // Signed over the timestamp exactly as sent, not re-formatted.
+    const expected = mac('sha256', secret, utf8(`${parsed.t}.`), body);
+    return parsed.v1.some((candidate) => same(candidate, expected)) ? VERIFIED : failed('mismatch');
+}
+function verifyStandard(scheme, secret, headers, body, now) {
+    const id = headerValue(headers, 'webhook-id');
+    const t = headerValue(headers, 'webhook-timestamp');
+    const signature = headerValue(headers, 'webhook-signature');
+    if (id === undefined || t === undefined || signature === undefined)
+        return failed('missing-header');
+    if (!UNIX_SECONDS.test(t))
+        return failed('malformed-header');
+    const candidates = signature
+        .split(/\s+/)
+        .filter((entry) => entry.startsWith('v1,'))
+        .map((entry) => decodeDigest(entry.slice(3), 'base64', 32))
+        .filter(isDefined);
+    if (candidates.length === 0)
+        return failed('malformed-header');
+    if (!within(Number(t), now, scheme.toleranceSec))
+        return failed('stale-timestamp');
+    const key = standardKey(secret);
+    if (key === undefined)
+        return failed('key-error');
+    const expected = mac('sha256', key, utf8(`${id}.${t}.`), body);
+    return candidates.some((candidate) => same(candidate, expected)) ? VERIFIED : failed('mismatch');
+}
+/**
+ * Whether `body` arrived correctly signed under `scheme` and `secret`. Checks run header present →
+ * header parses → timestamp → digest. Never throws: anything unexpected is `failed: key-error`.
+ */
+export function verifyWebhook(scheme, secret, headers, body, options = {}) {
+    const now = options.now ?? new Date();
+    try {
+        switch (scheme.kind) {
+            case 'hmac':
+                return verifyHmac(scheme, secret, headers, body);
+            case 'timestamped':
+                return verifyTimestamped(scheme, secret, headers, body, now);
+            case 'standard':
+                return verifyStandard(scheme, secret, headers, body, now);
+        }
+    }
+    catch {
+        return failed('key-error');
+    }
+}

package/dist/import-detect.d.ts

@@ -1,10 +1,10 @@
 /**
  * Format detection for API definition imports: WSDL, OpenAPI / Swagger, Postman Collections,
- * Protocol Buffers (`.proto`) and legacy single-XML SOAP projects.
+ * AsyncAPI, Protocol Buffers (`.proto`) and legacy single-XML SOAP projects.
  *
  * Inspects document text, file names, or URLs to classify definition formats before or during import.
  */
-export type ImportFormatKind = 'openapi' | 'postman' | 'wsdl' | 'proto' | 'legacy-soap-project' | 'unknown';
+export type ImportFormatKind = 'openapi' | 'asyncapi' | 'postman' | 'wsdl' | 'proto' | 'legacy-soap-project' | 'unknown';
 export interface DetectedImportFormat {
     readonly kind: ImportFormatKind;
     readonly label: string;

package/dist/import-detect.js

@@ -1,6 +1,6 @@
 /**
  * Format detection for API definition imports: WSDL, OpenAPI / Swagger, Postman Collections,
- * Protocol Buffers (`.proto`) and legacy single-XML SOAP projects.
+ * AsyncAPI, Protocol Buffers (`.proto`) and legacy single-XML SOAP projects.
  *
  * Inspects document text, file names, or URLs to classify definition formats before or during import.
  */
@@ -102,6 +102,9 @@ export function detectImportFormat(input) {
                     confidence: 'definite',
                 };
             }
+            if (typeof parsed['asyncapi'] === 'string') {
+                return { kind: 'asyncapi', label: `AsyncAPI ${parsed['asyncapi']}`, confidence: 'definite' };
+            }
             if (typeof parsed['openapi'] === 'string') {
                 return {
                     kind: 'openapi',
@@ -125,6 +128,9 @@ export function detectImportFormat(input) {
             }
         }
         // 4. Pattern matching fallback on raw text
+        if (/^asyncapi\s*:\s*['"]?[23]\./m.test(text)) {
+            return { kind: 'asyncapi', label: 'AsyncAPI', confidence: 'probable' };
+        }
         if (/^\s*openapi\s*:\s*['"]?3\.[012]/m.test(text)) {
             return { kind: 'openapi', label: 'OpenAPI 3.x', confidence: 'probable' };
         }
@@ -158,6 +164,9 @@ export function detectImportFormat(input) {
         if (target.includes('postman_collection') || target.endsWith('.postman.json')) {
             return { kind: 'postman', label: 'Postman Collection', confidence: 'probable' };
         }
+        if (target.includes('asyncapi')) {
+            return { kind: 'asyncapi', label: 'AsyncAPI', confidence: 'probable' };
+        }
         if (target.includes('openapi') ||
             target.includes('swagger') ||
             target.endsWith('.yaml') ||