@debugg-ai/debugg-ai-mcp 4.2.2 → 4.4.0

package/dist/services/tunnel/protocol/errors.js

@@ -0,0 +1,51 @@
+/**
+ * Debugg tunnel wire protocol v1 — error types.
+ *
+ * STUB (bead debugg_ai_mcp-xkoh.1.3, phase 2.1): these are data-only classes, so
+ * they are complete; every behavioural module in this directory is a stub that
+ * throws until phase 4.1.
+ */
+import { ErrorCode } from './constants.js';
+/**
+ * The peer (or our own encoder's caller) violated the wire spec. Always carries
+ * ErrorCode.PROTOCOL_ERROR — the code exists so callers can treat it uniformly
+ * with StreamResetError.
+ */
+export class ProtocolError extends Error {
+    code = ErrorCode.PROTOCOL_ERROR;
+    constructor(message) {
+        super(message);
+        this.name = 'ProtocolError';
+    }
+}
+/**
+ * A stream ended early. `code` is an ErrorCode value; an unknown code seen on
+ * the wire is normalised to ErrorCode.RESET before it gets here. `remote` is
+ * true when the peer sent the RST, false when this side originated it (a cap
+ * refusal, a GOAWAY drain deadline).
+ */
+export class StreamResetError extends Error {
+    code;
+    remote;
+    constructor(code, message, remote = false) {
+        super(message ?? `tunnel stream reset (code ${code})`);
+        this.name = 'StreamResetError';
+        this.code = code;
+        this.remote = remote;
+    }
+}
+/**
+ * The session is gone: the websocket closed, the peer went silent, or a fatal
+ * protocol error tore it down. `closeCode` is the websocket close code
+ * (1000, or 4000 + ErrorCode, or 1006 for an abrupt socket loss).
+ */
+export class SessionClosedError extends Error {
+    closeCode;
+    reason;
+    constructor(closeCode, reason = '') {
+        super(`tunnel session closed (${closeCode}${reason ? `: ${reason}` : ''})`);
+        this.name = 'SessionClosedError';
+        this.closeCode = closeCode;
+        this.reason = reason;
+    }
+}

package/dist/services/tunnel/protocol/handshake.js

@@ -0,0 +1,134 @@
+/**
+ * Debugg tunnel wire protocol v1 — the websocket handshake.
+ *
+ * This module validates the SHAPE of a handshake only. Whether a tunnelKey is
+ * real is the tunnel server's business (it asks the debugg API's internal verify
+ * endpoint) — the protocol just guarantees both ends agree on how the question
+ * is asked and how a refusal is phrased.
+ *
+ * Check order is version (426) -> tunnel id (400) -> authorization (401), so an
+ * old client is told to upgrade even when its token is also bad.
+ */
+import { HandshakeError, HandshakeStatus, Header, RequestHeader, SUPPORTED_PROTOCOL_VERSIONS, TUNNEL_ID_PATTERN, } from './constants.js';
+const JSON_CONTENT_TYPE = { 'Content-Type': 'application/json' };
+function headerValue(headers, name) {
+    const raw = headers[name] ?? headers[name.toLowerCase()];
+    if (raw === undefined)
+        return undefined;
+    return Array.isArray(raw) ? raw.join(', ') : raw;
+}
+/** Build the request headers a client sends with its upgrade request. */
+export function buildHandshakeHeaders(request) {
+    const versions = request.versions ?? SUPPORTED_PROTOCOL_VERSIONS;
+    const headers = {
+        [RequestHeader.AUTHORIZATION]: `Bearer ${request.tunnelKey}`,
+        [RequestHeader.TUNNEL_ID]: request.tunnelId,
+        [RequestHeader.PROTOCOL]: versions.join(', '),
+    };
+    if (request.clientVersion)
+        headers[RequestHeader.CLIENT_VERSION] = request.clientVersion;
+    return headers;
+}
+/**
+ * Pick the highest version both ends speak from an X-Debugg-Tunnel-Protocol
+ * header value, or null when there is none. Tolerates whitespace, a repeated
+ * header and versions we don't know; anything non-numeric is simply not a
+ * version and is ignored.
+ */
+export function negotiateProtocolVersion(offered, supported = SUPPORTED_PROTOCOL_VERSIONS) {
+    if (offered === undefined)
+        return null;
+    const tokens = (Array.isArray(offered) ? offered.join(',') : offered).split(',');
+    let best = null;
+    for (const token of tokens) {
+        const trimmed = token.trim();
+        if (!/^\d+$/.test(trimmed))
+            continue;
+        const version = Number(trimmed);
+        if (!supported.includes(version))
+            continue;
+        if (best === null || version > best)
+            best = version;
+    }
+    return best;
+}
+/**
+ * Server side: validate an upgrade request's headers.
+ */
+export function validateHandshakeRequest(headers, supported = SUPPORTED_PROTOCOL_VERSIONS) {
+    const version = negotiateProtocolVersion(headerValue(headers, Header.PROTOCOL), supported);
+    if (version === null) {
+        return {
+            ok: false,
+            status: HandshakeStatus.UPGRADE_REQUIRED,
+            error: HandshakeError.UNSUPPORTED_PROTOCOL_VERSION,
+            responseHeaders: { [RequestHeader.SUPPORTED]: supported.join(', '), ...JSON_CONTENT_TYPE },
+            body: { error: HandshakeError.UNSUPPORTED_PROTOCOL_VERSION, supported: [...supported] },
+        };
+    }
+    const tunnelId = headerValue(headers, Header.TUNNEL_ID);
+    if (!tunnelId || !TUNNEL_ID_PATTERN.test(tunnelId)) {
+        return {
+            ok: false,
+            status: HandshakeStatus.BAD_REQUEST,
+            error: HandshakeError.BAD_TUNNEL_ID,
+            responseHeaders: { ...JSON_CONTENT_TYPE },
+            body: { error: HandshakeError.BAD_TUNNEL_ID },
+        };
+    }
+    const authorization = headerValue(headers, Header.AUTHORIZATION);
+    const bearer = authorization ? /^bearer\s+(\S.*)$/i.exec(authorization) : null;
+    if (!bearer) {
+        return {
+            ok: false,
+            status: HandshakeStatus.UNAUTHORIZED,
+            error: HandshakeError.UNAUTHORIZED,
+            responseHeaders: { ...JSON_CONTENT_TYPE },
+            body: { error: HandshakeError.UNAUTHORIZED },
+        };
+    }
+    const accepted = {
+        ok: true,
+        version,
+        tunnelId,
+        tunnelKey: bearer[1].trim(),
+        responseHeaders: { [RequestHeader.PROTOCOL]: String(version) },
+    };
+    const clientVersion = headerValue(headers, Header.CLIENT_VERSION);
+    if (clientVersion)
+        accepted.clientVersion = clientVersion;
+    return accepted;
+}
+function parseVersionList(value) {
+    if (value === undefined)
+        return undefined;
+    const versions = value
+        .split(',')
+        .map((token) => token.trim())
+        .filter((token) => /^\d+$/.test(token))
+        .map(Number);
+    return versions.length > 0 ? versions : undefined;
+}
+/** Client side: interpret whatever came back instead of (or alongside) a 101. */
+export function interpretHandshakeResponse(status, headers, offered = SUPPORTED_PROTOCOL_VERSIONS) {
+    if (status === HandshakeStatus.SWITCHING_PROTOCOLS) {
+        const echoed = negotiateProtocolVersion(headerValue(headers, Header.PROTOCOL), offered);
+        if (echoed === null) {
+            // No echo, or a version we never offered: the peer is not speaking a
+            // protocol we understand, and pretending otherwise corrupts the stream.
+            return { ok: false, status, retryable: false };
+        }
+        return { ok: true, version: echoed };
+    }
+    const failure = {
+        ok: false,
+        status,
+        retryable: status === 429 || status >= 500,
+    };
+    if (status === HandshakeStatus.UPGRADE_REQUIRED) {
+        const supported = parseVersionList(headerValue(headers, Header.SUPPORTED));
+        if (supported)
+            failure.supported = supported;
+    }
+    return failure;
+}

package/dist/services/tunnel/protocol/index.js

@@ -0,0 +1,17 @@
+/**
+ * Debugg tunnel wire protocol v1 — public surface.
+ *
+ * The MCP tunnel client (services/tunnel/) and the debugg tunnel server both
+ * import from here and nowhere deeper. Conformance vectors for any copy of this
+ * module live in ./vectors/.
+ *
+ * Spec: bead debugg_ai_mcp-xkoh.1.2. Design: docs/debugg-tunnel-server-design-2026-09-19.md §3.
+ */
+export * from './constants.js';
+export * from './errors.js';
+export * from './codec.js';
+export * from './transport.js';
+export * from './stream.js';
+export * from './session.js';
+export * from './handshake.js';
+export * from './conformance.js';