Skip to main content

@enclave-vm/broker

Tool broker and session management for the EnclaveJS streaming runtime. It runs scripts in an @enclave-vm/core sandbox on your server, gives them the tools you register, and streams what happens as events, in process or over HTTP. The broker does not authenticate callers, limit request rates or encrypt sessions. Put authentication in front of its routes, and tell the routes who the caller is (see Who may see a session).

Installation

Quick Start

A script calls a tool with callTool(name, args). broker.execute() resolves with the final result; the events of the run are handed to onEvent.

Broker Configuration

createBroker reads sessions, enclave, limits and history. Any other key is ignored and reported with a warning. In particular, securityLevel at the top level has no effect: write enclave: { securityLevel }.

Limits

The limits of the broker bound every session. A session created in process can name its own value for a limit (the other limits keep the broker’s values); a session created over HTTP can only lower maxToolCalls and its lifetime.

Tools and Secrets

Arguments are validated against argsSchema before the handler runs. Secrets are handed to the handler only and are not part of any event. Tool arguments and the result of a script are part of the events: keep secrets out of them.

Sessions

broker.execute() creates a session, runs the script and removes the session. To keep a session around, create it yourself:
A session id names one session: createSession({ sessionId }) throws for an id that is in use, and when sessions.maxSessions sessions are registered. A finished session stays registered, so that it can be replayed, until the next cleanup.

What a session keeps

A session keeps its most recent events for replays, up to history.maxEvents events and history.maxBytes bytes. When a bound is reached the oldest events are dropped; session.firstReplayableSeq is the lowest sequence number from which everything is still kept.

Cancelling

A session runs in the broker’s process, on its thread. Cancelling a session aborts the tool call in flight and refuses every later one. It does not interrupt a script that is computing: such a script holds the thread until it ends or reaches toolTimeoutMs.
One script that computes without calling a tool blocks every other session of the broker for up to toolTimeoutMs. Keep that limit low, and run the broker in a process of its own when you serve callers you do not trust.

HTTP API

Express Integration

To mount the routes under a prefix, register them on an Express router and mount the router:
createExpressRouter is deprecated: it registers no route. For another framework, adapt its request and response to BrokerRequest and BrokerResponse and call the handlers of handler.getRoutes().

Who may see a session

Without an identify hook the routes do not tell callers apart. Whoever can reach them can list every session, read its state, replay its events (tool arguments and the final result included) and end it. Authentication in front of the routes does not change that: an authenticated caller still reaches the sessions of every other caller.
With identify, every session belongs to the caller that created it:
  • GET /sessions lists the caller’s own sessions.
  • Reading, replaying and ending a session is answered only for its owner. Another caller gets 404, the answer of an id that does not exist.
  • A request for which the hook returns nothing, or throws, is answered with 401.
  • A session created in process has no owner and is not reachable over the routes, unless you create it with owner.
The hook identifies a caller; it does not verify a credential. Do that in your own middleware or inside the hook. It separates sessions, not data: a tool handler receives its arguments and a context with the id of its session, not the caller. A tool that reads data restricted per caller applies that restriction itself, with the owner of its session (broker.getSession(context.sessionId as SessionId)?.owner, the caller the hook returned), or leaves it to the data store.

Handler Options

CORS is on by default for every origin: a page of any origin can call a broker its visitor’s browser can reach. Set allowedOrigins, or cors: false, for anything but a public demo.
The routes answer the preflight (OPTIONS) themselves, and a browser sends it without the credential: authentication in front of the routes has to let OPTIONS requests through to them.
  • maxStreamsPerSession bounds the streams one session has open (the request that created it and the replay streams). A further one is answered with 429.
  • maxBufferedBytes: a reader that falls behind by more is disconnected. When it is the creator of the session, the session is cancelled.

The Request Body of POST /sessions

The body is validated as a whole; a request that does not pass is answered with 400 and creates no session.
  • config values are positive integers. maxToolCalls and maxExecutionMs cannot exceed the broker’s limits (a larger value is lowered to them), and heartbeatIntervalMs is kept between 1 second and 5 minutes.
  • sessionId is s_ followed by 1 to 128 characters of A-Z a-z 0-9 . _ : ~ -. An id in use is answered with 409.
  • filter has bounds: 16 rules, 32 patterns, 256 characters per pattern.
  • encryption: { mode: 'required' } is refused: the broker does not encrypt sessions.

Answers

An error answer is { code, message } with a fixed message.

Event Filtering

Filter which events are sent to a client.

Type-Based Filtering

Content-Based Filtering

A rule matches when its type filter and its content filter both match; a filter matches when one of its rules does. Without field, a pattern is matched against the payload as JSON text.
  • Evaluating one event takes a bounded time: regular expressions and globs run under regexTimeoutMs (100 ms by default). The budgetMs option of createEventFilter bounds all evaluations of one filter together.
  • An event the filter could not evaluate (a pattern that does not compile, an evaluation that ran out of time) is not sent, in either mode.
  • In exclude mode a glob is matched as text: * also matches / and a leading dot. In include mode a glob follows path rules.
  • A filter that arrives in a request gets at most 100 ms per event and 500 ms per stream, and its globs are matched without brace and extglob expansion.

Always-Allowed Events

session_init and final are sent whatever the filter says, unless the configuration sets its own alwaysAllow list.
A filter is a convenience for the client, not a confidentiality control. Data that a client must not see has to stay out of the events: out of tool arguments and out of the result of the script.

Tools from OpenAPI

  • A failure while polling is reported with the error event when it has a listener, and in getStats() either way. The tools of the last specification that was applied stay registered; tools are replaced in one step, and a source never replaces a tool it does not manage.
  • A path parameter fills its own segment of the path. A value that would leave the segment empty or turn it into . or .. fails the call.
  • auth and loaderOptions.headers go to the origin of baseUrl only: not to a specification on another origin (the source’s headers are for the specification host), and not along a redirect to another origin. A header parameter of the specification cannot replace them.
  • Upstream responses are read up to loaderOptions.maxResponseBytes (10 MB by default), specifications up to maxSpecBytes (32 MB), and fetching a specification is bounded by fetchTimeoutMs.
Generate tools only for the operations a script may call: a script decides their arguments.