@cyanmycelium/mcp-broker-provider 0.2.0 → 0.3.0

package/dist/index.js

@@ -53,6 +53,177 @@ function tunnelErrorOf(payload) {
   return error;
 }
 
+// src/broker.client.ts
+var CALLER_META_KEY = "io.cyanmycelium/caller";
+var TRACEPARENT_META_KEY = "traceparent";
+var TELEMETRY_NOTIFICATION_METHOD = "broker/telemetry";
+var AUDIT_RESULT_NOTIFICATION_METHOD = "broker/audit/result";
+var TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+var TRACE_ID = /^[0-9a-f]{32}$/;
+var SPAN_ID = /^[0-9a-f]{16}$/;
+var UNIX_NANO = /^(0|[1-9][0-9]{0,19})$/;
+function parseTraceparent(value) {
+  if (typeof value !== "string") return void 0;
+  const match = TRACEPARENT.exec(value);
+  if (!match || /^0+$/.test(match[1]) || /^0+$/.test(match[2])) return void 0;
+  return { version: "00", traceId: match[1], parentId: match[2], traceFlags: match[3] };
+}
+function formatTraceparent(context) {
+  return `${context.version}-${context.traceId}-${context.parentId}-${context.traceFlags}`;
+}
+function traceparentOf(meta) {
+  return parseTraceparent(meta?.[TRACEPARENT_META_KEY]);
+}
+function withTraceparent(meta, context) {
+  const encoded = formatTraceparent(context);
+  if (!parseTraceparent(encoded)) throw new TypeError("traceparent must be a valid W3C version 00 context");
+  return { ...meta ?? {}, [TRACEPARENT_META_KEY]: encoded };
+}
+function childTraceparent(parent, spanId) {
+  if (!SPAN_ID.test(spanId) || /^0+$/.test(spanId)) throw new TypeError("spanId must be 16 lowercase hexadecimal characters and not all zero");
+  return { ...parent, parentId: spanId };
+}
+function validAttributes(attributes) {
+  if (attributes === void 0) return true;
+  const entries = Object.entries(attributes);
+  return entries.length <= 64 && entries.every(
+    ([key, value]) => key.length > 0 && key.length <= 128 && (typeof value === "boolean" || typeof value === "string" && value.length <= 4096 || typeof value === "number" && Number.isFinite(value))
+  );
+}
+function validSpan(span) {
+  return TRACE_ID.test(span.traceId) && !/^0+$/.test(span.traceId) && SPAN_ID.test(span.spanId) && !/^0+$/.test(span.spanId) && (span.parentSpanId === void 0 || SPAN_ID.test(span.parentSpanId) && !/^0+$/.test(span.parentSpanId)) && span.name.length > 0 && span.name.length <= 256 && UNIX_NANO.test(span.startTimeUnixNano) && UNIX_NANO.test(span.endTimeUnixNano) && (span.kind === void 0 || Number.isInteger(span.kind) && span.kind >= 0 && span.kind <= 5) && validAttributes(span.attributes) && (span.events === void 0 || span.events.length <= 32 && span.events.every((event) => event.name.length > 0 && event.name.length <= 256 && UNIX_NANO.test(event.timeUnixNano) && validAttributes(event.attributes))) && (span.status === void 0 || Number.isInteger(span.status.code) && span.status.code >= 0 && span.status.code <= 2 && (span.status.message === void 0 || span.status.message.length <= 1024));
+}
+function callerReferenceOf(meta) {
+  const value = meta?.[CALLER_META_KEY];
+  if (typeof value !== "object" || value === null) return void 0;
+  const { ref, correlationId, traceId } = value;
+  return typeof ref === "string" && typeof correlationId === "string" ? { ref, correlationId, ...typeof traceId === "string" ? { traceId } : {} } : void 0;
+}
+var BrokerRequestError = class extends Error {
+  constructor(message, code, data) {
+    super(message);
+    this.code = code;
+    this.data = data;
+    this.name = "BrokerRequestError";
+  }
+  code;
+  data;
+};
+var ID_PREFIX = "provider-broker-";
+var BrokerClient = class {
+  _write;
+  _writeTelemetry;
+  _timeoutMs;
+  _waiting = /* @__PURE__ */ new Map();
+  _next = 1;
+  constructor(write, options = {}, writeTelemetry) {
+    this._write = write;
+    this._writeTelemetry = writeTelemetry ?? ((frame) => {
+      write(frame);
+      return true;
+    });
+    this._timeoutMs = Math.max(0, options.requestTimeoutMs ?? 0);
+  }
+  /**
+   * Declares this provider's authorization domain. Resolves when the broker
+   * accepted it; rejects with a {@link BrokerRequestError} whose `data.errors`
+   * lists every problem otherwise. Until it resolves, serve nothing that
+   * needs a decision.
+   */
+  declare(declaration) {
+    return this._request("broker/authorization/declare", declaration);
+  }
+  /** Asks for one decision per check. */
+  authorize(query) {
+    return this._request("broker/authorize", query);
+  }
+  /**
+   * Reports what happened after a decision, so the broker's audit shows the
+   * outcome next to the decision. A notification: nothing comes back, and a
+   * report the broker cannot match is counted on its side.
+   */
+  reportResult(report) {
+    if (typeof report?.decisionId !== "string" || report.decisionId.length === 0) throw new TypeError("decisionId must be the non-empty id the broker returned");
+    if (report.result !== "success" && report.result !== "failure" && report.result !== "refused") throw new TypeError('result must be "success", "failure" or "refused"');
+    const params = {
+      decisionId: report.decisionId,
+      result: report.result,
+      ...report.nativeStatus !== void 0 ? { nativeStatus: report.nativeStatus } : {},
+      ...report.errorCode !== void 0 ? { errorCode: report.errorCode } : {}
+    };
+    this._write(JSON.stringify({ jsonrpc: "2.0", method: AUDIT_RESULT_NOTIFICATION_METHOD, params }));
+  }
+  /** Emits one complete provider span, or returns false when the link is down. */
+  span(span) {
+    if (!validSpan(span)) throw new TypeError("span is not a valid broker telemetry span");
+    return this._writeTelemetry(
+      JSON.stringify({
+        jsonrpc: "2.0",
+        method: TELEMETRY_NOTIFICATION_METHOD,
+        params: { version: 1, signal: "traces", span }
+      })
+    );
+  }
+  /** Number of requests still waiting for the broker. */
+  get pendingCount() {
+    return this._waiting.size;
+  }
+  /**
+   * Consumes a frame when it answers one of this client's requests. Returns
+   * `true` when it did, and the frame must not reach the MCP server.
+   * @internal Called by the transports.
+   */
+  handleIncoming(frame) {
+    if (this._waiting.size === 0 || !frame.includes(ID_PREFIX)) return false;
+    let message;
+    try {
+      message = JSON.parse(frame);
+    } catch {
+      return false;
+    }
+    if (typeof message.id !== "string" || message.method !== void 0) return false;
+    const waiting = this._waiting.get(message.id);
+    if (!waiting) return false;
+    this._waiting.delete(message.id);
+    if (waiting.timer) clearTimeout(waiting.timer);
+    if (message.error) {
+      waiting.reject(
+        new BrokerRequestError(String(message.error.message ?? "broker error"), typeof message.error.code === "number" ? message.error.code : void 0, message.error.data)
+      );
+    } else {
+      waiting.resolve(message.result);
+    }
+    return true;
+  }
+  /**
+   * Fails every waiting request: the socket they went out on is gone, and a
+   * reconnected one will not carry their answers.
+   * @internal Called by the transports.
+   */
+  rejectAll(reason) {
+    for (const [id, waiting] of this._waiting) {
+      if (waiting.timer) clearTimeout(waiting.timer);
+      waiting.reject(new BrokerRequestError(`${reason} (request ${id})`));
+    }
+    this._waiting.clear();
+  }
+  _request(method, params) {
+    const id = `${ID_PREFIX}${this._next++}`;
+    return new Promise((resolve, reject) => {
+      const timer = this._timeoutMs > 0 ? setTimeout(() => {
+        this._waiting.delete(id);
+        reject(
+          new BrokerRequestError(
+            `The broker did not answer ${method} within ${this._timeoutMs}ms. A broker older than 1.4.1 drops methods it does not know; ${method} needs broker 1.5.0 or later.`
+          )
+        );
+      }, this._timeoutMs) : null;
+      this._waiting.set(id, { resolve, reject, timer });
+      this._write(JSON.stringify({ jsonrpc: "2.0", id, method, params }));
+    });
+  }
+};
+
 // src/transport.support.ts
 var PENDING_FRAME_LIMIT = 64;
 var PendingFrames = class {
@@ -173,11 +344,32 @@ function warnIfSlotScopedPath(wsUrl) {
     `[mcp-provider] MultiplexTransport is connecting to "${wsUrl}", whose path "${path}" is a slot-scoped provider endpoint. That endpoint carries plain JSON-RPC frames, while MultiplexTransport writes multiplex envelopes { provider, payload }, which the broker never unwraps, so nothing sent here is answered. Either publish through new DirectTransport("${wsUrl}"), or point MultiplexTransport at the shared multiplex base "${withPath(url, DEFAULT_MULTIPLEX_PATH)}". ` + RECONFIGURED_HINT
   );
 }
+function handshakeHeaders(options) {
+  const headers = { ...options?.headers ?? {} };
+  if (options?.secret) headers["x-provider-token"] = options.secret;
+  return Object.keys(headers).length > 0 ? headers : void 0;
+}
+function openWebSocket(url, headers) {
+  if (typeof WebSocket === "undefined") {
+    throw new Error(
+      `Cannot open ${url}: this runtime has no global WebSocket (Node before 22). Assign one before connecting: import { WebSocket } from "ws"; globalThis.WebSocket = WebSocket as unknown as typeof globalThis.WebSocket;`
+    );
+  }
+  if (!headers) return new WebSocket(url);
+  try {
+    return new WebSocket(url, { headers });
+  } catch (error) {
+    throw new Error(
+      `Cannot open ${url} with handshake headers (secret / headers): this runtime's WebSocket does not accept them. Node 22 and later do; a browser never does, so a browser provider cannot authenticate to the broker. ${error.message}`
+    );
+  }
+}
 
 // src/direct.transport.ts
 var DirectTransport = class {
   _wsUrl;
   _aggregate;
+  _headers;
   _pending;
   /** Throttles the "wrote to a closed transport" line, which repeats per frame. */
   _afterCloseNotice = new ThrottledNotice();
@@ -187,10 +379,26 @@ var DirectTransport = class {
   onOpen = null;
   onClose = null;
   onError = null;
+  /**
+   * The broker's own methods for this slot: declaring an authorization
+   * domain, asking for decisions. Its answers are taken off the socket
+   * before {@link onMessage} sees anything.
+   */
+  broker;
   constructor(wsUrl, options) {
     this._wsUrl = wsUrl;
     this._aggregate = options?.aggregate;
+    this._headers = handshakeHeaders(options);
     this._pending = new PendingFrames(`DirectTransport ${wsUrl}`);
+    this.broker = new BrokerClient(
+      (frame) => this.send(frame),
+      { requestTimeoutMs: options?.brokerRequestTimeoutMs },
+      (frame) => {
+        if (this._ws?.readyState !== WebSocket.OPEN) return false;
+        this._ws.send(frame);
+        return true;
+      }
+    );
   }
   get isOpen() {
     return this._ws?.readyState === WebSocket.OPEN;
@@ -201,7 +409,7 @@ var DirectTransport = class {
    */
   connect() {
     warnIfMultiplexPath(this._wsUrl);
-    const ws = new WebSocket(this._wsUrl);
+    const ws = openWebSocket(this._wsUrl, this._headers);
     this._closed = false;
     this._ws = ws;
     ws.onopen = () => {
@@ -218,11 +426,13 @@ var DirectTransport = class {
       if (this._ws !== ws) return;
       this._ws = null;
       const discarded = this._pending.clear();
+      this.broker.rejectAll(`DirectTransport: the socket to ${this._wsUrl} closed before the broker answered`);
       const error = this._closeError(event, discarded);
       if (error) this.onError?.(new Error(error));
       this.onClose?.();
     };
     ws.onmessage = (event) => {
+      if (this.broker.handleIncoming(event.data)) return;
       this.onMessage?.(event.data);
     };
   }
@@ -287,6 +497,9 @@ var MultiplexSocket = class _MultiplexSocket {
   /** Per-URL cache so all transports targeting the same tunnel share one socket. */
   static _instances = /* @__PURE__ */ new Map();
   _wsUrl;
+  /** Cache key: the URL, and the handshake headers, since two secrets are two identities and need two sockets. */
+  _key;
+  _headers;
   _transports = /* @__PURE__ */ new Map();
   /** Aggregate opt-in per slot, absent when the caller did not express one. */
   _aggregates = /* @__PURE__ */ new Map();
@@ -302,16 +515,19 @@ var MultiplexSocket = class _MultiplexSocket {
   _pathWarned = false;
   /** Throttles the "wrote to a closed tunnel" line, which repeats per frame. */
   _afterStopNotice = new ThrottledNotice();
-  constructor(wsUrl) {
+  constructor(wsUrl, key, headers) {
     this._wsUrl = wsUrl;
+    this._key = key;
+    this._headers = headers;
     this._pending = new PendingFrames(`MultiplexSocket ${wsUrl}`);
   }
-  /** Returns (or creates) the singleton socket for a given tunnel URL. */
-  static getOrCreate(wsUrl) {
-    let instance = _MultiplexSocket._instances.get(wsUrl);
+  /** Returns (or creates) the singleton socket for a given tunnel URL and handshake headers. */
+  static getOrCreate(wsUrl, headers) {
+    const key = headers ? `${wsUrl}\0${JSON.stringify(Object.entries(headers).sort())}` : wsUrl;
+    let instance = _MultiplexSocket._instances.get(key);
     if (!instance) {
-      instance = new _MultiplexSocket(wsUrl);
-      _MultiplexSocket._instances.set(wsUrl, instance);
+      instance = new _MultiplexSocket(wsUrl, key, headers);
+      _MultiplexSocket._instances.set(key, instance);
     }
     return instance;
   }
@@ -342,7 +558,7 @@ var MultiplexSocket = class _MultiplexSocket {
       this._ws?.close();
       this._ws = null;
       this._dead = true;
-      _MultiplexSocket._instances.delete(this._wsUrl);
+      _MultiplexSocket._instances.delete(this._key);
     }
   }
   /**
@@ -356,9 +572,9 @@ var MultiplexSocket = class _MultiplexSocket {
   _revive() {
     this._dead = false;
     this._stopped = false;
-    const live = _MultiplexSocket._instances.get(this._wsUrl);
+    const live = _MultiplexSocket._instances.get(this._key);
     if (!live) {
-      _MultiplexSocket._instances.set(this._wsUrl, this);
+      _MultiplexSocket._instances.set(this._key, this);
       return;
     }
     if (live !== this) {
@@ -399,13 +615,19 @@ var MultiplexSocket = class _MultiplexSocket {
     }
     this._pending.push(frame);
   }
+  /** Sends low-priority telemetry only while the shared link is open. */
+  sendTelemetry(provider, data) {
+    if (this._ws?.readyState !== WebSocket.OPEN) return false;
+    this._ws.send(encodeEnvelope(provider, data));
+    return true;
+  }
   // ── Connection lifecycle ────────────────────────────────────────────────
   _connect() {
     if (!this._pathWarned) {
       this._pathWarned = true;
       warnIfSlotScopedPath(this._wsUrl);
     }
-    const ws = new WebSocket(this._wsUrl);
+    const ws = openWebSocket(this._wsUrl, this._headers);
     const notices = {
       notEnvelope: new ThrottledNotice(),
       unknownProvider: new ThrottledNotice(),
@@ -433,6 +655,7 @@ var MultiplexSocket = class _MultiplexSocket {
       if (this._ws !== ws) return;
       this._ws = null;
       for (const transport of this._transports.values()) {
+        transport.broker.rejectAll(`MultiplexTransport: the shared socket to ${this._wsUrl} closed before the broker answered`);
         transport.onClose?.();
       }
       if (!this._stopped) {
@@ -482,7 +705,7 @@ var MultiplexSocket = class _MultiplexSocket {
         return;
       }
     }
-    transport.onMessage?.(envelopeFrame(envelope));
+    transport._receive(envelopeFrame(envelope));
   }
   _scheduleReconnect() {
     const base = 1e3;
@@ -512,10 +735,30 @@ var MultiplexTransport = class _MultiplexTransport {
   onOpen = null;
   onClose = null;
   onError = null;
+  /**
+   * The broker's own methods for this slot: declaring an authorization
+   * domain, asking for decisions. Its answers are taken off the socket
+   * before {@link onMessage} sees anything.
+   */
+  broker;
   constructor(name, socket, options) {
     this._name = name;
     this._socket = socket;
     this._aggregate = options?.aggregate;
+    this.broker = new BrokerClient(
+      (frame) => this.send(frame),
+      { requestTimeoutMs: options?.brokerRequestTimeoutMs },
+      (frame) => this._socket.sendTelemetry(this._name, frame)
+    );
+  }
+  /**
+   * One frame from the broker for this slot: the broker's answer to one of
+   * {@link broker}'s requests, or MCP traffic for the server.
+   * @internal Called by the shared socket.
+   */
+  _receive(frame) {
+    if (this.broker.handleIncoming(frame)) return;
+    this.onMessage?.(frame);
   }
   /**
    * Convenience factory: creates a {@link MultiplexTransport} backed by a
@@ -528,7 +771,7 @@ var MultiplexTransport = class _MultiplexTransport {
    *              {@link DirectTransport} and is warned about on connect.
    */
   static create(name, wsUrl, options) {
-    return new _MultiplexTransport(name, MultiplexSocket.getOrCreate(wsUrl), options);
+    return new _MultiplexTransport(name, MultiplexSocket.getOrCreate(wsUrl, handshakeHeaders(options)), options);
   }
   get isOpen() {
     return this._socket.isOpen;
@@ -565,6 +808,6 @@ var MultiplexTransport = class _MultiplexTransport {
   }
 };
 
-export { DirectTransport, MultiplexTransport, TUNNEL_REGISTER_METHOD, TunnelErrorCodes, decodeEnvelope, encodeEnvelope, encodeEnvelopeMessage, encodeErrorEnvelope, encodeRegisterEnvelope, encodeRegisterFrame, envelopeFrame, tunnelErrorOf };
+export { AUDIT_RESULT_NOTIFICATION_METHOD, BrokerClient, BrokerRequestError, CALLER_META_KEY, DirectTransport, MultiplexTransport, TELEMETRY_NOTIFICATION_METHOD, TRACEPARENT_META_KEY, TUNNEL_REGISTER_METHOD, TunnelErrorCodes, callerReferenceOf, childTraceparent, decodeEnvelope, encodeEnvelope, encodeEnvelopeMessage, encodeErrorEnvelope, encodeRegisterEnvelope, encodeRegisterFrame, envelopeFrame, formatTraceparent, parseTraceparent, traceparentOf, tunnelErrorOf, withTraceparent };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map