rbac-proxy
v1.1.7RBAC boundary proxy for the iii worker protocol — auth, gating, namespacing, middleware, and engine:: result filtering on its own port.
Install
iii trigger compose::add worker=rbac-proxyRun in your project with the iii engine running. Exact versions are immutable and digest-pinned.
rbac-proxy
A standalone iii worker that puts the engine's role-based access control in front of the engine instead of inside it. It opens its own configurable WebSocket port, speaks the iii worker protocol verbatim, and transparently reverse-proxies every frame — functions and channels — to a trusted engine listener, while at the boundary it:
- serves only the engine endpoints you list in
rbac.expose_endpoints(/,/ws/channels/*,/otel;/alone without the key, nothing with an empty list), and no other path at all, - authenticates each connection (the operator's
auth_function_id), - gates every invocation in the namespace it is made in (vendored
is_function_allowed: forbidden > scoped grant > allowed > infrastructure carve-out >expose_functions> deny), and the namespace a connection may declare, - gates observers: an observer needs the session to be allowed to call both the function it observes and its target, and the frames a worker exchanges about the observers of its own functions pass for those functions only (Observers),
- namespaces a session's registrations behind
function_registration_prefix, - runs middleware and the two registration hooks (functions and observers), and
- rewrites the results of the six
engine::*discovery functions so a caller only ever sees the surface it is allowed to invoke, - pins identities: a proxied worker registers as
rbac-proxy:<prefix>::<declared name>(rbac-proxy:<session id>:<declared name>for a session withoutfunction_registration_prefix), unless the auth function granted that name inworker_names(one live session at a time, never anrbac-proxy:name), and anengine::*call is forwarded only as a direct call (a queued one is refused), so a session never runs anything as a trusted worker or as another prefix's worker, and - forwards only the frame types it knows, and only text frames from the client: anything else, a binary frame included, is dropped, so a protocol addition stays closed until the proxy learns to gate it.
It is the ade reverse-proxy pattern (src/proxy.rs: one
outbound engine WebSocket per inbound connection) with an RBAC interceptor
spliced into the pump, plus relays for /ws/channels/{id} and /otel.
The RBAC decision logic is vendored verbatim from the engine
(engine/src/workers/worker/rbac_config.rs), so a connection through
rbac-proxy is gated byte-for-byte as the same connection through an engine
iii-worker-manager RBAC listener would be — the proxy is just a different,
out-of-process home for the same contract (it can front a remote or managed
engine, scale and harden independently, and shrink an auth bug's blast radius
to the proxy alone).
Full design: tech-specs/2026-06-rbac-proxy-worker/.
Install
iii call compose::add worker=rbac-proxyRequires a trusted engine listener with no rbac block (the proxy is the
public door; the engine port stays internal) and the configuration worker
(required boot dependency).
Run
rbac-proxy --url ws://127.0.0.1:49134--url— the engine WebSocket URL for the proxy's control connection, and the default upstream for the data plane.--config <file.yaml>— optional one-time seed installed as theconfigurationentry'sinitial_valuewhen none exists yet.--manifest— print the publish manifest as JSON and exit.
Before you start: expose the endpoints
rbac-proxy serves the engine endpoints listed in rbac.expose_endpoints.
Without the key it serves the worker endpoint / only, as earlier versions
did (minus channels), and logs a warning; with an empty list it serves
nothing. The warning repeats at startup and on every config change.
Most setups want all three of the engine's endpoints:
rbac:
expose_endpoints:
- match("/") # workers: the iii protocol, gated by RBAC
- match("/ws/channels/*") # channels (streams between functions)
- match("/otel") # telemetry: worker logs, traces and metrics| Endpoint | What it carries | Leave it out and |
|---|---|---|
/ |
The worker protocol. Each connection is authenticated by auth_function_id, then every frame is checked against the RBAC rules. |
No worker can connect. |
/ws/channels/{id} |
Channel sockets. Relayed as is; the engine checks each channel's access key, as it does for direct connections. | Functions that stream through channels fail. |
/otel |
Telemetry from the SDK. Authenticated by the same auth function as / before the upgrade, then relayed as is (see below). |
Workers log Failed to connect to engine WebSocket and their telemetry is not exported. |
Rules use the expose_functions wildcard syntax over the request path:
match("/otel") or { match: "/otel" }, where * matches any run of
characters and the pattern must match the whole path. A bare "/otel"
is an error that tells you to write match("/otel"). Only these three
endpoints are ever served: any other path (/ws/channels/a/b, /otel/v2,
/admin) is a 404, whatever the rules match, so an endpoint the engine
adds later stays closed until the proxy learns to handle it. A refused
request gets a bare 404 not found; the rule that would expose it is logged
for the operator, not returned. rbac-proxy::status lists the rules in force.
Telemetry is not attributed. The engine names relayed spans, logs and
metrics by the service.name inside them, and through the proxy every sender
has the proxy's address. So a client accepted on /otel can write telemetry
under any service name, another worker's or another tenant's included, and
send messages up to tungstenite's limits (64 MiB per message, 16 MiB per
frame). Expose /otel only to clients you trust with that: the auth
function is told the endpoint (endpoint: "/otel", see below) and can refuse
it per credential.
Upgrading from an earlier version: earlier versions always served /
and /ws/channels/* and never /otel, and refuse the expose_endpoints
key, so set it after upgrading. Until you do, the new version serves /, so
workers stay connected; channels need match("/ws/channels/*").
Configuration
Config lives in the configuration worker under id rbac-proxy (no committed
config.yaml; WorkerConfig::default() seeds first boot, with engine_url
defaulting to --url). Equivalent YAML an operator would configuration::set:
host: 0.0.0.0
port: 49200 # the public RBAC port
engine_url: ws://127.0.0.1:49134 # the trusted internal engine listener
expose_worker_internals: false # strip pid/ip/metrics from engine::workers::* results
middleware_function_id: my-project::middleware-function
rbac:
auth_function_id: my-project::auth-function
expose_endpoints: # nothing is served without these (see above)
- match("/")
- match("/ws/channels/*")
- match("/otel")
on_function_registration_function_id: my-project::on-function-reg
on_observer_registration_function_id: my-project::on-observer-reg
expose_functions:
- match("api::*") # wildcard, anchored both ends, * = any run of chars
- match("*::public")
- metadata: # all keys AND'd; filters OR'd
public: true
- match: "orders::*" # scoped to a namespace (the others answer in `default`)
namespace: ordersNamespaces work as in the engine's RBAC: a rule answers in the namespace it
names, default when it names none. The auth function may return scoped
grants (namespaces: { orders: ["svc::*"] }); their keys are then the only
namespaces a connection may declare, and allowed_functions applies in
default only.
The auth function receives { headers, query_params, ip_address, endpoint },
endpoint being the path being opened ("/" or "/otel"), so it can grant
an endpoint per credential.
The auth function may also return worker_names: ["mcp-server"], which rbac-proxy
adds on top of the engine's auth result. A worker that declares one of these
names keeps it, instead of getting rbac-proxy:<...>:<name>. Names must match
exactly; patterns are not supported, and names starting with rbac-proxy: are
ignored (those are the names the proxy gives sessions). Grant a name when
something waits for the worker by name, such as compose readiness. One live
session at a time holds a granted name; another session declaring it
meanwhile gets its own rbac-proxy:<...>:<name>. A worker connected to the
engine directly under the same name would share it, so only grant names no
trusted worker uses, to credentials you trust to be that worker:
// my-project::auth-function
if (headers.authorization === `Bearer ${process.env.MCP_TOKEN}`)
// allowed_functions matches exact ids; a pattern goes in namespaces.
return { namespaces: { default: ["*"] }, worker_names: ["mcp-server"] }The registration hooks are the engine's, with the engine's input and answer:
| Hook | Input | An object answer may replace |
|---|---|---|
on_function_registration_function_id |
{ function_id, description, metadata, namespace, private, observable, args_format?, context } |
function_id, description, metadata, private, observable, args_format |
on_observer_registration_function_id |
{ observer_id, function_id, namespace, args, filters, target_function_id, target_namespace, metadata, context } |
function_id, target_function_id, args, filters, metadata |
A hook that throws or answers anything but an object denies: a denied
function registration is dropped, as the engine drops it, and a denied
observer is refused with FORBIDDEN. Hooks see bare ids (before the session
prefix). rbac keys of entries stored before 0.26 are ignored with one
warn each, naming the setting to use, so such an entry loads.
A call through the middleware waits up to 610 s for it (a middleware that forwards with its own timeout should use 600 s or less), and a connection that does not finish its upgrade headers within 10 s is closed.
Hot reload: a host/port change rebinds the public listener (last-good on
bind failure — the previous listener and config are kept); everything else
(engine_url, rbac.*, middleware_function_id, expose_worker_internals)
takes effect on the next connection.
Observers
Workers behind the proxy observe functions and host observable functions as they do against the engine. The engine runs observers for a proxied connection with no RBAC session, so the proxy gates every observe frame:
- Features.
observe.v1,observe.v2andlocal-dispatch.v1are kept in what the worker declares and what the engine answers. Withmiddleware_function_idset,functionregisteredreaches the worker withlocal_dispatch: falsefor every function except the ones the connection registeredprivate: true: a call that runs in-process never reaches the middleware, and the connection's own calls of a private function skip it (see Registrations).large-messages.v1is removed (the proxy forwards text frames only). - Observing. An
observerunson_observer_registration_function_id, then needs the session to be allowed to call both the observed function and the target, each in the namespace it names. The session's own registrations pass and resolve to their prefixed ids. Refused withFORBIDDEN: anengine::*target (an observer's target runs with no session behind it), and as the observed function the infrastructure carve-out, the discovery functions,engine::observers::*and the engine events whose calls list functions, workers or observers (engine::on-functions-changed,engine::on-workers-changed,engine::on-observers-changed). TheObservedenvelope iii delivers for an observer the connection created names the observed function without the prefix; a call through that observer reaches the target with the payload as the host sent it. A refusal of anobserveunder an id whose earlierobservewaits for the engine's answer goes out right after that answer, so the worker hears the answers in the order it sent the observes. Eachobserveresultanswers the oldest unansweredobserveunder its id, and a refusal is thatobserve's final answer. An observer is the connection's once the engine accepts it, unless the connection'sunobserveof the id followed itsobserve. A refusal also sends the engine anunobserveof the id, unless the worker sent one after thatobserveor observes the id again: aReattachgives the connection the observers of the worker's previous connection with no RBAC check, and the replay of one the session may no longer have is refused here (or, rewritten otherwise by the registration hook, by the engine). - Hosting.
functionregistered,observeradded,observerremoved,observerack,invocationsobservedandlocalinvocationstatspass for the functions the connection registered, with the session prefix removed toward the worker and applied toward the engine. A call through an observer (iii.call({ observer, payload })) passes for an observer the engine announced to the connection as the host of its function; any other getsNOT_FUNCTION_OWNER.invocationresult.matchedanddelivered, andoutput_is_input, pass as sent, and the engine checks them. - Registrations.
private,observableandargs_formatonregisterfunctionpass to the engine. The connection's calls of its own private functions skip the middleware, which runs on the proxy's control connection, a connection a private function refuses: they run in-process oncefunctionregisteredofferslocal_dispatch, and go straight to the engine otherwise. - Back on a new connection. An
observethat names the id of a suspended observer replaces it when it comes from a connection under the same worker name in the same namespace (the observe v2 rule for a worker that restarts). The worker name carries the session prefix, so a restarted worker under the same prefix takes its observers back (a queue consumer keeps its backlog), and anobserveof the id from a session under another prefix getsOBSERVER_ID_CONFLICTuntil the grace period ends. A session without a prefix declaresrbac-proxy:<session id>:<declared name>, with the id the proxy gives each connection: nothing else tells two such sessions apart, so a session declaring another's name neither shuts it out (one live worker per name) nor takes its suspended observers. Its own reconnect keeps them byReattach; anobserveunder its id from a new session is another worker's. - Call chains. A
callera worker sets on a call or a report is kept only when it names a call the engine routed to that connection and the connection has not answered yet; the proxy writes it from that call, so a worker cannot place its calls in another worker's call chain. - Discovery.
engine::observers::listandengine::observers::getshow the observers the connection created and the ones whose observed function and target it may call, with the prefix removed.engine::observers::disposedisposes only observers the connection created.
Frame types the iii protocol does not have, including the binding messages
of SDKs before 0.26, are dropped with one warn per connection and frame
type, naming the replacement.
Every function is observable unless it is registered observable: false.
The auth function receives the upgrade's headers, bearer tokens included, and
the middleware and the hooks receive payloads and session context: register
them with observable: false. Details:
protocol-interception.md § Observers.
Security. Only the proxy's RBAC port should face untrusted networks. Set
auth_function_id: with none, every upgrade is refused. The stored default has none, so a proxy that lost its configuration stays closed.
Functions
| Function | Input | Output |
|---|---|---|
rbac-proxy::status |
{} |
{ host, port, engine_url, rbac_enabled, expose_endpoints, active_connections, version } |
rbac-proxy::session |
{} |
{ proxied: true, session_id, function_registration_prefix, worker_names, policy: { auth_function, expose_functions, expose_endpoints } } |
rbac-proxy::status is a read-only health and identity probe: the bound
host and port, the upstream engine URL with any user:pass@ redacted,
whether an auth function is configured, the live connection count and the
worker version.
rbac-proxy::session answers "is this connection behind rbac-proxy?",
while rbac-proxy::status reports on the proxy as a whole. The proxy's
interceptor answers the session probe for every proxied connection and never
forwards it, so a worker connected straight to the engine gets
function_not_found. No expose rule applies to it (it is not a function on
the engine), but forbidden_functions does: an auth function that lists
rbac-proxy::session denies it with FORBIDDEN. policy is the
configuration the session runs under: whether an auth function is
configured, the expose_functions rules as written (they apply to every
session, in every namespace) and the endpoint rules in force. A client reads
the globs to decide what to warn its users about, for example a match("*")
without an auth function.
A worker that must only run behind the proxy (the mcp worker does) calls
it at boot and refuses to start on function_not_found. This guards against
a misconfigured URL, not against an attacker: anything that can register
functions on the engine directly could register a fake rbac-proxy::session
there. The proxy refuses to register that id for the connections it serves.
The proxy hosts no observable event source. Two internal functions are the
targets of its own observers; both are never agent-callable (denied in
iii-permissions.yaml) and answer { ok: true }:
| Function | Observes | Receives | Does |
|---|---|---|---|
rbac-proxy::on-config-change |
configuration::on-updated, filters { "input.id": { "$eq": <config id> }, "input.event_type": { "$eq": "configuration:updated" } }, capture: [output] |
the Observed envelope, the ConfigurationEvent at output |
re-reads the entry with configuration::get (the event itself is ignored) and applies it; the proxy also reloads once when the observer becomes active, for an update made during boot |
rbac-proxy::on-functions-changed |
engine::on-functions-changed, capture: [] |
the Observed envelope, without payloads |
invalidates the discovery catalog cache (a 5 s TTL bounds staleness either way) |
The config id is rbac-proxy, or III_CONFIG_NAME when set.
Local development & testing
cargo test # engine-free unit tests + golden schema + manifest
UPDATE_GOLDENS=1 cargo test # regenerate tests/golden/ after an intentional surface changetests/integration.rs boots a real iii engine + the proxy and drives a
downstream worker through the proxy port (exposed call, forbidden call, an
observer with a forbidden target, channel round-trip, filtered discovery, a
call in another namespace, an accepted observer, an engine event that cannot
be observed). The engine is III_BIN or the iii on PATH,
started from a temporary directory with a private HOME, on free ports picked
at boot, never the default 49134. It self-skips when there is no iii
binary or the proxy does not come up (e.g. the
configuration worker is not deployed).
tests/observe_protocol.rs runs iii's observe wire fixtures (vendored in
tests/fixtures/protocol/observe/) through the interceptor.