> ## Documentation Index
> Fetch the complete documentation index at: https://iii.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  `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](https://workers.iii.dev/workers/iii-worker-manager).
</Note>

## 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.

<Warning>
  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.
</Warning>

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):

```yaml config.yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
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")
          - match("stream::*")
```

`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.

`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:

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
expose_functions:
  - match("public::*") # any function under the public:: namespace
  - match("engine::functions::list") # one specific function
  - metadata:
      public: true # any function whose metadata.public is true
```

A function's [`metadata`](./functions#attach-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"] }`.

<Warning>
  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.
</Warning>

## 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.**

<Note>
  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-manager`s in iii's configuration.
</Note>

<Tabs>
  <Tab title="Node / TypeScript">
    ```typescript src/index.ts theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    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
        };
      },
    );
    ```
  </Tab>

  <Tab title="Python">
    ```python src/main.py theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    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)
    ```
  </Tab>

  <Tab title="Rust">
    ```rust src/main.rs theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    use iii_sdk::{AuthInput, InitOptions, MiddlewareFunctionInput, RegisterFunction, TriggerRequest, 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::IIIError::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
        }))
    }));
    ```
  </Tab>
</Tabs>

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                                                          |
| --------------------------------- | ---------------------------------------------------------------- |
| `allowed_functions`               | Function IDs to allow in addition to `expose_functions`.         |
| `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. |

## 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:

```typescript src/iii.ts theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
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)}`);
```

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](/tutorials/linkly/frontend).

## 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.

```yaml config.yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
- name: iii-worker-manager
  config:
    port: 3110
    middleware_function_id: auth::middleware
    rbac:
      auth_function_id: auth::browser
      expose_functions:
        - match("link::create")
```

<Tabs>
  <Tab title="Node / TypeScript">
    ```typescript src/index.ts theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    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 });
      },
    );
    ```
  </Tab>

  <Tab title="Python">
    ```python src/main.py theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    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)
    ```
  </Tab>

  <Tab title="Rust">
    ```rust src/main.rs theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    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
            }
        }),
    );
    ```
  </Tab>
</Tabs>

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.