Access Control

Accept untrusted worker connections through RBAC-gated listeners served by the iii-worker-manager worker.

The iii-worker-manager worker owns the connections between workers and the engine. It always runs a trusted listener (on 49134 by default) that your own workers connect to through III_URL. To let an untrusted client connect, a browser tab, a third-party process, anything you do not run yourself, you add an RBAC-gated listener: a second port where every connection is authenticated by a function you write and every call is checked against an allowlist.

iii-worker-manager is always running, so there is nothing to add; you configure it directly in config.yaml. This page is a quick tour of RBAC listeners. For the full configuration see the iii-worker-manager worker docs.

Trusted and RBAC listeners

The default 49134 listener is trusted: any worker that reaches it can register functions and call anything. That is fine for workers you run yourself, but not for a browser or other untrusted worker. An RBAC listener runs on its own port, gates every connection through an auth function, and restricts each session to an allowlist of functions.

Declaring any iii-worker-manager in config.yaml replaces the default 49134 trusted listener. You must also declare the trusted 49134 listener yourself alongside the RBAC one, otherwise your own workers lose the port they connect through.

Declare both listeners: the trusted one your own workers keep using on 49134, and an RBAC-gated one on a separate port (here 3110, for browsers and other untrusted connections):

config.yaml

workers:
  # ...
  # Trusted listener for your own workers. Replaces the default 49134.
  - name: iii-worker-manager
    config:
      port: 49134
  # Browser-facing, RBAC-gated listener on a separate port.
  - name: iii-worker-manager
    config:
      host: 127.0.0.1
      port: 3110
      rbac:
        auth_function_id: auth::browser
        expose_functions:
          - match: "link::create"
            namespace: browser
          - match: "stream::*"
            namespace: browser

auth_function_id names a function the worker invokes once per connection to authorize the worker to connect (or reject it if authorization fails). That is covered in the next section.

auth_function_id resolves in the default namespace. Register the auth worker there. An auth worker in another namespace makes the listener reject every connection.

expose_functions is the allowlist of function IDs a session may call. Each entry is either a glob match("...") on the function ID or a metadata: selector that matches any function registered with that metadata:

expose_functions:
  - match("public::*") # any function with the public:: id prefix
  - match("engine::functions::list") # one specific function
  - metadata:
      public: true # any function whose metadata.public is true

Namespace-scoped function rules

An expose_functions rule without a namespace applies to default only. Add namespace when the session must call a function in another namespace:

expose_functions:
  - match: "orders::*"
    namespace: orders
  - metadata:
      public: true
    namespace: analytics

The match value supports * wildcards for the function id. The namespace value is an exact match and does not support wildcards. Add one rule for each namespace that the session can access.

A function’s metadata is an arbitrary JSON object set when the function is registered, so you can shape it however your access model needs and gate on exactly the fields you choose, for example { public: true }, { tier: "premium" }, or { scopes: ["read"] }.

All access should be gated system-side. You should never rely on an untrusted worker to define what they can or can’t have access to. For example metadata.public = true in the above example is defined and managed by the trusted iii-worker-manager and is not part of a payload sent by the worker.

Write the auth function

The auth function runs during the WebSocket upgrade, before the client is connected. It receives the request’s headers, query parameters, and client IP, and returns the session’s permissions. Throw to reject the connection.

The auth function can grant multiple authorizations so a single function can be used to authorize multiple types of workers. In practice this is a balance between authorizing similar workers and separating dissimilar workers to separate iii-worker-manager definitions. You can define any number of iii-worker-managers in iii’s configuration.

Node / TypeScript

src/index.ts

import { registerWorker } from "iii-sdk";

const worker = registerWorker(process.env.III_URL ?? "ws://localhost:49134", {
  workerName: "auth",
});

worker.registerFunction(
  "auth::browser",
  async (input: {
    headers: Record<string, string>;
    query_params: Record<string, string[]>;
    ip_address: string;
  }) => {
    const token = input.query_params.token?.[0];
    if (token !== (process.env.BROWSER_TOKEN ?? "dev-token")) {
      throw new Error("unauthorized");
    }
    return {
      allowed_functions: [], // extra IDs to allow beyond expose_functions
      forbidden_functions: [], // denied even if matched; supersedes allowed
      allow_trigger_type_registration: false, // can the worker register its own trigger types
      allow_function_registration: true, // can the worker register its own callbacks
      context: { source: "browser" }, // forwarded to middleware on every call
    };
  },
);

Python

src/main.py

import os
from iii import register_worker, InitOptions

worker = register_worker(
    os.environ.get("III_URL", "ws://localhost:49134"),
    InitOptions(worker_name="auth"),
)

def browser(req: dict) -> dict:
    token = (req.get("query_params", {}).get("token") or [None])[0]
    if token != os.environ.get("BROWSER_TOKEN", "dev-token"):
        raise Exception("unauthorized")
    return {
        "allowed_functions": [],  # extra IDs to allow beyond expose_functions
        "forbidden_functions": [],  # denied even if matched; supersedes allowed
        "allow_trigger_type_registration": False,  # register its own trigger types
        "allow_function_registration": True,  # register its own callbacks
        "context": {"source": "browser"},  # forwarded to middleware on every call
    }

worker.register_function("auth::browser", browser)

Rust

src/main.rs

use iii_helpers::worker_connection_manager::AuthInput;
use iii_sdk::protocol::TriggerRequest;
use iii_sdk::{InitOptions, MiddlewareFunctionInput, RegisterFunction, register_worker};
use serde_json::{json, Value};

let url = std::env::var("III_URL").unwrap_or_else(|_| "ws://localhost:49134".into());
let worker = register_worker(&url, InitOptions::default());

worker.register_function("auth::browser", RegisterFunction::new(|input: AuthInput| {
    let token = input.query_params.get("token").and_then(|v| v.first());
    let expected = std::env::var("BROWSER_TOKEN").unwrap_or_else(|_| "dev-token".into());
    if token.map(String::as_str) != Some(expected.as_str()) {
        return Err(iii_sdk::Error::Handler("unauthorized".into()));
    }
    Ok(json!({
        "allowed_functions": [],          // extra IDs to allow beyond expose_functions
        "forbidden_functions": [],        // denied even if matched; supersedes allowed
        "allow_trigger_type_registration": false, // register its own trigger types
        "allow_function_registration": true,      // register its own callbacks
        "context": { "source": "browser" },       // forwarded to middleware on every call
    }))
}));

The auth worker itself connects to the trusted 49134 port; it is one of your own workers. Only the untrusted client connects through 3110.

The returned object is an AuthResult:

Field	Meaning
namespaces	Grants per namespace: { "orders": ["svc::*"] }. See below.
allowed_functions	Function IDs to allow in addition to expose_functions, in default only.
forbidden_functions	Function IDs to deny even if they match. Takes precedence.
allowed_trigger_types	Trigger types the session may bind. Omit to allow all.
allow_trigger_type_registration	Whether the session may register new trigger types.
allow_function_registration	Whether the session may register functions (defaults to true).
context	Arbitrary object forwarded to the middleware on every call.
function_registration_prefix	Optional prefix applied to every function the session registers.

Scope a session to namespaces

namespaces maps a namespace to the function IDs the session may call inside it. An entry accepts an exact ID or a wildcard, in either the bare or the match("...") spelling expose_functions uses:

{
  "namespaces": {
    "orders": ["svc::*", "billing::charge"],
    "analytics": []
  }
}

The keys carry a second meaning: they are the namespaces the session may declare on engine::workers::register. A session holding this result registers in orders or analytics; declaring default, or any other namespace, is refused with FORBIDDEN. An entry with an empty list, like analytics above, grants the namespace and no functions inside it — the session may register there and reaches only what expose_functions exposes.

Return an empty namespaces (or omit it) to leave the session unscoped: it declares any namespace, and only allowed_functions and expose_functions apply.

allowed_functions applies in default only. A grant listed there does not answer in orders, even for a session scoped to it. Put per-namespace grants in namespaces.

forbidden_functions is the exception: it holds in every namespace, and it wins over both namespaces and the infrastructure functions every worker needs.

Connect a client

A browser connects with iii-browser-sdk pointed at the RBAC port. Browsers cannot set custom WebSocket headers, so the token travels as a query parameter, the same one auth::browser reads:

src/iii.ts

import { registerWorker } from "iii-browser-sdk";

const token = import.meta.env.VITE_BROWSER_TOKEN ?? "dev-token";
export const worker = registerWorker(`ws://localhost:3110?token=${encodeURIComponent(token)}`, {
  namespace: "browser",
});

The session can now call only the functions expose_functions (plus allowed_functions) permit. For an end-to-end walkthrough that turns a browser tab into a worker, see Ch. 7: Bring in the browser.

Intercept calls with middleware

Set middleware_function_id on the listener to run a function on every invocation that comes through the RBAC port. It receives the call plus the session context from the auth result, and acts as a proxy: forward the (optionally rewritten) call and return its result, or throw to reject.

config.yaml

- name: iii-worker-manager
  config:
    port: 3110
    middleware_function_id: auth::middleware
    rbac:
      auth_function_id: auth::browser
      expose_functions:
        - match: "link::create"
          namespace: browser

Node / TypeScript

src/index.ts

worker.registerFunction(
  "auth::middleware",
  async (input: {
    function_id: string;
    payload: Record<string, unknown>;
    context: Record<string, unknown>;
  }) => {
    // stamp the authenticated caller onto every payload, then forward the call
    const payload = { ...input.payload, _source: input.context.source };
    return worker.trigger({ function_id: input.function_id, payload });
  },
);

Python

src/main.py

def middleware(req: dict) -> dict:
    # stamp the authenticated caller onto every payload, then forward the call
    payload = {**req["payload"], "_source": req["context"]["source"]}
    return worker.trigger({"function_id": req["function_id"], "payload": payload})

worker.register_function("auth::middleware", middleware)

Rust

src/main.rs

let mw = worker.clone();
worker.register_function(
    "auth::middleware",
    RegisterFunction::new_async(move |input: MiddlewareFunctionInput| {
        let worker = mw.clone();
        async move {
            // stamp the authenticated caller onto every payload, then forward the call
            let mut payload = input.payload.clone();
            if let Some(obj) = payload.as_object_mut() {
                obj.insert(
                    "_source".into(),
                    input.context.get("source").cloned().unwrap_or(Value::Null),
                );
            }
            worker
                .trigger(TriggerRequest {
                    function_id: input.function_id,
                    payload,
                    action: None,
                    timeout_ms: None,
                })
                .await
        }
    }),
);

The rbac block also accepts on_function_registration_function_id, on_trigger_registration_function_id, and on_trigger_type_registration_function_id hooks. Each runs when an untrusted session registers a function, trigger, or trigger type, and can remap the registration (return the mapped fields) or throw to deny it.