@cyanmycelium/mcp-broker-provider 0.2.0 → 0.3.0

package/README.md

@@ -95,6 +95,106 @@ Either form sends the registration notification with `params: { aggregate: true
 
 **Wire the message handler before you connect.** The broker runs `initialize` against a newly aggregated provider immediately, and a provider that does not answer is dropped from `_all` silently. Handing the transport to an MCP server does this for you, since the server assigns `onMessage` before calling `connect()`. Assigning it yourself, after connecting, loses the handshake and the provider never appears in the aggregate.
 
+## Letting the broker decide (broker 1.5.0)
+
+A provider that serves its own kind of resource can declare an authorization
+domain and ask the broker for decisions, instead of carrying a policy of its
+own. Both transports expose the broker's methods as `transport.broker`:
+
+```ts
+import { DirectTransport, callerReferenceOf } from "@cyanmycelium/mcp-broker-provider";
+
+const transport = new DirectTransport("ws://broker:3000/provider/scada");
+// ... start the MCP server on it, then:
+await transport.broker.declare({
+    version: "2026-10-01.1",
+    domain: "scada",
+    namespace: { resource: "/production/site1" },
+    capabilities: ["scada.observe", "scada.control"],
+    resources: [
+        {
+            resource: "uns://production/site1/line1/motor01/speed_sp",
+            resourcePath: "/production/site1/line1/motor01/speed_sp",
+            limits: { minValue: 0, maxValue: 1500 },
+        },
+    ],
+    resultsRequired: ["scada.control"],
+});
+
+// In a tool handler (mcp-core 1.4.0 hands the adapter the request's _meta):
+const caller = callerReferenceOf(request?.meta);
+const { decisions } = await transport.broker.authorize({
+    principal: { type: "caller-ref", ref: caller!.ref },
+    checks: [{ capability: "scada.control", resource: "uns://production/site1/line1/motor01/speed_sp", resourcePath: "/production/site1/line1/motor01/speed_sp" }],
+});
+// decisions[0]: { effect: "allow-with-constraints", allowed: false, obligations: { constraints: { minValue: 0, maxValue: 1500 } }, ... }
+
+// Once the write is done, or refused by a constraint:
+transport.broker.reportResult({ decisionId: decisions[0].decisionId, result: "success", nativeStatus: "Good" });
+```
+
+- `effect` is `allow`, `deny` or `allow-with-constraints`. The last one comes
+  with the resource's declared limits in `obligations.constraints`; apply them
+  right before executing. `allowed` is `true` only for a plain `allow`, so code
+  that reads `allowed` alone refuses a constrained allow instead of ignoring
+  its limits.
+- `reportResult()` is a notification: nothing comes back. The broker writes the
+  outcome next to the decision in its audit, and `broker_diagnose` reports
+  decisions of `resultsRequired` capabilities still unreported.
+
+- The provider needs its own identity on the broker (an entry in the security
+  file's `providers` table), which means presenting a secret:
+  `new DirectTransport(url, { secret })`, sent as `X-Provider-Token`. Node 22
+  and later can; a browser cannot, so this is for Node and native providers.
+- To test all of this without an authorization server, start the broker with
+  `startTestBroker()` from `@cyanmycelium/mcp-broker/testing`
+  ([guide](../broker/docs/testing.md)).
+- The broker's answers are taken off the socket before the MCP server sees
+  them. A refused request rejects with `BrokerRequestError` (`code`, `data`).
+- There is no timeout by default: a broker from 1.4.1 on answers at once. Set
+  `brokerRequestTimeoutMs` only to talk to an older one, which drops methods it
+  does not know.
+
+## Distributed traces (broker 1.5.0)
+
+Every addressed request arriving from broker 1.5 carries W3C Trace Context in
+`params._meta.traceparent`. Read it from the request metadata, create a SERVER
+span, then propagate a child context when this provider calls another slot:
+
+```ts
+import {
+    childTraceparent,
+    traceparentOf,
+    withTraceparent,
+} from "@cyanmycelium/mcp-broker-provider";
+
+const incoming = traceparentOf(request?.meta);
+const downstreamMeta = incoming
+    ? withTraceparent(undefined, childTraceparent(incoming, clientSpanId))
+    : undefined;
+```
+
+Completed spans are validated before emission:
+
+```ts
+const emitted = transport.broker.span({
+    traceId,
+    spanId,
+    parentSpanId,
+    name: "modbus.read",
+    kind: 3,
+    startTimeUnixNano,
+    endTimeUnixNano,
+    attributes: { "modbus.unit_id": 1 },
+});
+```
+
+The call is a notification and never waits for an answer. The broker consumes
+`broker/telemetry`, sends it through its bounded exporter queue, and never
+broadcasts it to MCP clients. It returns `false` and drops the span when the
+provider link is down, so telemetry never occupies the transport queue ahead
+of MCP control traffic. See [the complete telemetry contract](../../../docs/telemetry.md).
+
 ## Diagnostics
 
 This stack used to fail quietly. The transports now name what went wrong, on the console, because a browser-hosted provider has nowhere else to report:

package/dist/index.d.ts

@@ -1,6 +1,238 @@
 export { ITunnelRegisterOptions, TUNNEL_REGISTER_METHOD, TunnelEnvelope, TunnelError, TunnelErrorCode, TunnelErrorCodes, decodeEnvelope, encodeEnvelope, encodeEnvelopeMessage, encodeErrorEnvelope, encodeRegisterEnvelope, encodeRegisterFrame, envelopeFrame, tunnelErrorOf } from './protocol/index.js';
 import { IMessageTransport } from '@cyanmycelium/mcp-core';
 
+/**
+ * Talks to the broker itself, over the provider's own socket: declaring an
+ * authorization domain, and asking for decisions.
+ *
+ * Requires broker 1.5.0 or later. An older broker does not know these methods:
+ * from 1.4.1 it refuses them at once with `-32601`; 1.4.0 and earlier drop
+ * them and never answer, which is why {@link IBrokerClientOptions.requestTimeoutMs}
+ * exists, off by default.
+ */
+/** The `params._meta` key under which the broker passes the caller reference with each request. */
+declare const CALLER_META_KEY = "io.cyanmycelium/caller";
+/** W3C Trace Context carrier used by MCP requests. */
+declare const TRACEPARENT_META_KEY = "traceparent";
+/** Provider-to-broker telemetry notification. */
+declare const TELEMETRY_NOTIFICATION_METHOD = "broker/telemetry";
+/** Provider-to-broker notification reporting what happened after a decision. */
+declare const AUDIT_RESULT_NOTIFICATION_METHOD = "broker/audit/result";
+interface ITraceParent {
+    readonly version: "00";
+    readonly traceId: string;
+    readonly parentId: string;
+    readonly traceFlags: string;
+}
+type TelemetryAttributeValue = string | number | boolean;
+interface ITelemetryEvent {
+    readonly name: string;
+    readonly timeUnixNano: string;
+    readonly attributes?: Readonly<Record<string, TelemetryAttributeValue>>;
+}
+interface ITelemetrySpan {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId?: string;
+    readonly name: string;
+    readonly kind?: number;
+    readonly startTimeUnixNano: string;
+    readonly endTimeUnixNano: string;
+    readonly attributes?: Readonly<Record<string, TelemetryAttributeValue>>;
+    readonly events?: readonly ITelemetryEvent[];
+    readonly status?: {
+        readonly code: number;
+        readonly message?: string;
+    };
+}
+/** Parses the W3C version 00 traceparent representation used in MCP metadata. */
+declare function parseTraceparent(value: unknown): ITraceParent | undefined;
+declare function formatTraceparent(context: ITraceParent): string;
+/** Reads `params._meta.traceparent`, returning `undefined` when it is malformed. */
+declare function traceparentOf(meta: Readonly<Record<string, unknown>> | undefined): ITraceParent | undefined;
+/** Returns a metadata copy carrying the supplied validated trace context. */
+declare function withTraceparent(meta: Readonly<Record<string, unknown>> | undefined, context: ITraceParent): Readonly<Record<string, unknown>>;
+/** Continues a trace using the caller's span as the new W3C parent id. */
+declare function childTraceparent(parent: ITraceParent, spanId: string): ITraceParent;
+/** What the broker hands a declaring provider with each request, under {@link CALLER_META_KEY}. */
+interface ICallerReference {
+    /** Opaque. Valid on this slot, while the request it came with is pending. */
+    readonly ref: string;
+    /** Ties the decisions and the eventual report to the client request. */
+    readonly correlationId: string;
+    /** W3C trace id carried by the MCP request. */
+    readonly traceId?: string;
+}
+/**
+ * Reads the caller reference out of a request's `params._meta`, or
+ * `undefined` when there is none (the broker only adds it once a declaration
+ * was accepted). With mcp-core 1.4.0, pass `request?.meta` from the context
+ * an adapter receives.
+ */
+declare function callerReferenceOf(meta: Readonly<Record<string, unknown>> | undefined): ICallerReference | undefined;
+/**
+ * Engineering limits of one resource. They hold for every caller, and the
+ * broker returns them with each allow on that resource as
+ * `obligations.constraints`, for the provider to apply.
+ */
+interface IResourceLimits {
+    readonly minValue?: number;
+    readonly maxValue?: number;
+    readonly allowedValues?: readonly (string | number | boolean | null)[];
+    readonly destinations?: readonly string[];
+}
+/** One resource of a declaration: the provider's own identifier, and the path the broker evaluates. */
+interface IDeclaredResource {
+    readonly resource: string;
+    readonly resourcePath: string;
+    readonly effect?: string;
+    readonly limits?: IResourceLimits;
+}
+/** `broker/authorization/declare` parameters. Describes; grants nothing. */
+interface IAuthorizationDeclaration {
+    readonly version: string;
+    readonly domain: string;
+    readonly namespace: {
+        readonly resource: string;
+    };
+    readonly capabilities: readonly string[];
+    readonly resources?: readonly IDeclaredResource[];
+    readonly protects?: readonly string[];
+    /**
+     * Declared capabilities whose allowed decisions this provider promises to
+     * report with {@link BrokerClient.reportResult}. One not reported in time
+     * shows up in `broker_diagnose`.
+     */
+    readonly resultsRequired?: readonly string[];
+}
+interface IDeclarationAccepted {
+    readonly accepted: true;
+    readonly version: string;
+    readonly policyVersion: string;
+}
+/** One question: may (the caller) do `capability` on this resource? */
+interface IAuthorizationCheck {
+    readonly capability: string;
+    readonly resource: string;
+    readonly resourcePath: string;
+    readonly attributes?: Readonly<Record<string, unknown>>;
+}
+/** `broker/authorize` parameters. */
+interface IAuthorizationQuery {
+    /** On whose behalf: the caller of a pending request, or the provider itself. Never an identity. */
+    readonly principal: {
+        readonly type: "caller-ref";
+        readonly ref: string;
+    } | {
+        readonly type: "provider";
+    };
+    /** Only for `{ type: "provider" }`; a caller reference carries its own. */
+    readonly correlationId?: string;
+    /** Optional W3C trace id for provider-initiated work. */
+    readonly traceId?: string;
+    readonly checks: readonly IAuthorizationCheck[];
+}
+/** What an allow comes with. */
+interface IAuthorizationObligations {
+    /** The declared limits of the resource. Apply them right before executing. */
+    readonly constraints?: IResourceLimits;
+}
+interface IAuthorizationDecision {
+    readonly decisionId: string;
+    /** `allow-with-constraints`: allowed, within `obligations`. */
+    readonly effect: "allow" | "deny" | "allow-with-constraints";
+    /**
+     * `true` only for an unconditional `allow`. A provider that reads only
+     * this field therefore refuses a constrained allow rather than ignoring
+     * its constraints; read `effect` to apply them.
+     */
+    readonly allowed: boolean;
+    readonly reason: string;
+    readonly policies?: readonly string[];
+    readonly obligations?: IAuthorizationObligations;
+}
+/** `broker/audit/result` parameters: the outcome of what a decision allowed or refused. */
+interface IAuditResult {
+    /** The `decisionId` the broker returned. */
+    readonly decisionId: string;
+    readonly result: "success" | "failure" | "refused";
+    /** The protocol's own status (`Good`, an exception code, ...). */
+    readonly nativeStatus?: string;
+    /** The provider's error code, when it failed or refused. */
+    readonly errorCode?: string;
+}
+interface IAuthorizationAnswer {
+    readonly policyVersion: string;
+    /** One per check, in the same order. */
+    readonly decisions: readonly IAuthorizationDecision[];
+}
+/** The broker refused a request, or never answered it. */
+declare class BrokerRequestError extends Error {
+    /** JSON-RPC error code; `undefined` for a timeout or a closed socket. */
+    readonly code?: number | undefined;
+    /** The error's `data`, e.g. `{ errors: [...] }` for a refused declaration. */
+    readonly data?: unknown | undefined;
+    constructor(message: string, 
+    /** JSON-RPC error code; `undefined` for a timeout or a closed socket. */
+    code?: number | undefined, 
+    /** The error's `data`, e.g. `{ errors: [...] }` for a refused declaration. */
+    data?: unknown | undefined);
+}
+interface IBrokerClientOptions {
+    /**
+     * Rejects a request the broker did not answer within this many ms. Off by
+     * default: a broker from 1.4.1 on answers every request at once, refusals
+     * included, so waiting is never the normal path. Set it only to talk to an
+     * older broker, which drops what it does not know.
+     */
+    readonly requestTimeoutMs?: number;
+}
+/**
+ * The `broker/*` methods of one provider slot. Reached as `transport.broker`
+ * on {@link DirectTransport} and {@link MultiplexTransport}; the transport
+ * routes the broker's answers here before anything reaches the MCP server.
+ */
+declare class BrokerClient {
+    private readonly _write;
+    private readonly _writeTelemetry;
+    private readonly _timeoutMs;
+    private readonly _waiting;
+    private _next;
+    constructor(write: (frame: string) => void, options?: IBrokerClientOptions, writeTelemetry?: (frame: string) => boolean);
+    /**
+     * 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: IAuthorizationDeclaration): Promise<IDeclarationAccepted>;
+    /** Asks for one decision per check. */
+    authorize(query: IAuthorizationQuery): Promise<IAuthorizationAnswer>;
+    /**
+     * 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: IAuditResult): void;
+    /** Emits one complete provider span, or returns false when the link is down. */
+    span(span: ITelemetrySpan): boolean;
+    /** Number of requests still waiting for the broker. */
+    get pendingCount(): number;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string): void;
+    private _request;
+}
+
 /** Options accepted by {@link DirectTransport}. */
 interface IDirectTransportOptions {
     /**
@@ -22,6 +254,25 @@ interface IDirectTransportOptions {
      * the provider silently never appears in `_all`.
      */
     aggregate?: boolean;
+    /**
+     * Rejects a `broker.declare()` / `broker.authorize()` the broker did not
+     * answer within this many ms. Off by default: a broker from 1.4.1 on answers
+     * at once. Only for an older broker, which drops methods it does not know.
+     */
+    brokerRequestTimeoutMs?: number;
+    /**
+     * The provider secret, sent as the `X-Provider-Token` header of the
+     * WebSocket handshake. Required by a broker that authenticates providers
+     * (`providerSecret`, or the security file's `providers` table, where it is
+     * what gives this provider its own identity).
+     *
+     * **Node only.** Node's `WebSocket` (22 and later) accepts handshake
+     * headers; a browser's does not, and a browser provider cannot
+     * authenticate (terminate provider auth in a reverse proxy instead).
+     */
+    secret?: string;
+    /** Extra handshake headers, Node only, like {@link secret}. */
+    headers?: Readonly<Record<string, string>>;
 }
 /**
  * 1:1 WebSocket transport, wraps a single `WebSocket` connection to a broker
@@ -40,6 +291,7 @@ interface IDirectTransportOptions {
 declare class DirectTransport implements IMessageTransport {
     private readonly _wsUrl;
     private readonly _aggregate;
+    private readonly _headers;
     private readonly _pending;
     /** Throttles the "wrote to a closed transport" line, which repeats per frame. */
     private readonly _afterCloseNotice;
@@ -49,6 +301,12 @@ declare class DirectTransport implements IMessageTransport {
     onOpen: (() => void) | null;
     onClose: (() => void) | null;
     onError: ((error: Error) => void) | 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.
+     */
+    readonly broker: BrokerClient;
     constructor(wsUrl: string, options?: IDirectTransportOptions);
     get isOpen(): boolean;
     /**
@@ -89,6 +347,9 @@ declare class MultiplexSocket {
     /** Per-URL cache so all transports targeting the same tunnel share one socket. */
     private static readonly _instances;
     private readonly _wsUrl;
+    /** Cache key: the URL, and the handshake headers, since two secrets are two identities and need two sockets. */
+    private readonly _key;
+    private readonly _headers;
     private readonly _transports;
     /** Aggregate opt-in per slot, absent when the caller did not express one. */
     private readonly _aggregates;
@@ -105,8 +366,8 @@ declare class MultiplexSocket {
     /** Throttles the "wrote to a closed tunnel" line, which repeats per frame. */
     private readonly _afterStopNotice;
     private constructor();
-    /** Returns (or creates) the singleton socket for a given tunnel URL. */
-    static getOrCreate(wsUrl: string): MultiplexSocket;
+    /** Returns (or creates) the singleton socket for a given tunnel URL and handshake headers. */
+    static getOrCreate(wsUrl: string, headers?: Record<string, string>): MultiplexSocket;
     get isOpen(): boolean;
     register(name: string, transport: MultiplexTransport, aggregate?: boolean): void;
     unregister(name: string): void;
@@ -131,6 +392,8 @@ declare class MultiplexSocket {
      */
     private _announceProvider;
     send(provider: string, data: string): void;
+    /** Sends low-priority telemetry only while the shared link is open. */
+    sendTelemetry(provider: string, data: string): boolean;
     private _connect;
     /** Writes out everything queued while the socket was down. */
     private _flush;
@@ -159,6 +422,25 @@ interface IMultiplexTransportOptions {
      * appears in `_all`.
      */
     aggregate?: boolean;
+    /**
+     * Rejects a `broker.declare()` / `broker.authorize()` the broker did not
+     * answer within this many ms. Off by default: a broker from 1.4.1 on answers
+     * at once. Only for an older broker, which drops methods it does not know.
+     */
+    brokerRequestTimeoutMs?: number;
+    /**
+     * The provider secret, sent as the `X-Provider-Token` header of the
+     * WebSocket handshake. Required by a broker that authenticates providers
+     * (`providerSecret`, or the security file's `providers` table, where it is
+     * what gives this provider its own identity).
+     *
+     * **Node only.** Node's `WebSocket` (22 and later) accepts handshake
+     * headers; a browser's does not, and a browser provider cannot
+     * authenticate (terminate provider auth in a reverse proxy instead).
+     */
+    secret?: string;
+    /** Extra handshake headers, Node only, like {@link secret}. */
+    headers?: Readonly<Record<string, string>>;
 }
 /**
  * A transport that multiplexes multiple MCP servers over a single shared
@@ -180,7 +462,19 @@ declare class MultiplexTransport implements IMessageTransport {
     onOpen: (() => void) | null;
     onClose: (() => void) | null;
     onError: ((error: Error) => void) | 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.
+     */
+    readonly broker: BrokerClient;
     constructor(name: string, socket: MultiplexSocket, options?: IMultiplexTransportOptions);
+    /**
+     * 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: string): void;
     /**
      * Convenience factory: creates a {@link MultiplexTransport} backed by a
      * shared {@link MultiplexSocket} for the given tunnel URL.
@@ -211,4 +505,4 @@ declare class MultiplexTransport implements IMessageTransport {
     close(): void;
 }
 
-export { DirectTransport, type IDirectTransportOptions, type IMultiplexTransportOptions, MultiplexTransport };
+export { AUDIT_RESULT_NOTIFICATION_METHOD, BrokerClient, BrokerRequestError, CALLER_META_KEY, DirectTransport, type IAuditResult, type IAuthorizationAnswer, type IAuthorizationCheck, type IAuthorizationDecision, type IAuthorizationDeclaration, type IAuthorizationObligations, type IAuthorizationQuery, type IBrokerClientOptions, type ICallerReference, type IDeclarationAccepted, type IDeclaredResource, type IDirectTransportOptions, type IMultiplexTransportOptions, type IResourceLimits, type ITelemetryEvent, type ITelemetrySpan, type ITraceParent, MultiplexTransport, TELEMETRY_NOTIFICATION_METHOD, TRACEPARENT_META_KEY, type TelemetryAttributeValue, callerReferenceOf, childTraceparent, formatTraceparent, parseTraceparent, traceparentOf, withTraceparent };