# Gateway and auth

> Authenticate at the edge, authorize at the state.

Source: https://docs.workbus.dev/architecture/gateway/
Markdown: https://docs.workbus.dev/architecture/gateway/index.md
All docs for agents: https://docs.workbus.dev/llms.txt

The Gateway says who a caller is, and the Ledger decides what that caller may do. Who is decided at the edge, before any Ledger call; what is decided inside the write’s own transaction, from the grants as they are at that moment.

```plaintext
$ curl -s http://127.0.0.1:8823/b/docs/me
{"error":{"code":"unauthorized","message":"missing bearer token"}}
$ curl -s http://127.0.0.1:8823/b/docs/me -H 'authorization: Bearer nope'
{"error":{"code":"unauthorized","message":"malformed token"}}
```

Both are 401s from the Gateway. The board’s Durable Object never ran.

## The Gateway

The Gateway is a stateless Worker `fetch` ([`gateway/gateway.ts`](https://github.com/workbus-dev/workbus/blob/main/packages/workbus/src/gateway/gateway.ts)). For each request under `/b/<name>` it:

1. matches the method and path against the protocol’s route table (`protocol/*.ts`), and answers a few routes itself: discovery, `openapi.json`, avatars, and each sync’s webhook;
2. authenticates the caller, and reads `x-board-profile` and `x-board-can`;
3. checks the query or body against the route’s zod schema;
4. calls the Ledger with the verified caller, or holds the call when it waits (see [Relays](/architecture/relays-and-mailboxes/)), or serves Cap’n Web at `/rpc`, MCP at `/mcp`, or SSE on `/events`.

A 401 or a 400 is answered before step 4. The one thing the Gateway asks the Ledger during authentication is which OIDC issuers its grants name, and only for a token from an issuer it doesn’t already know. [`test/auth.test.ts`](https://github.com/workbus-dev/workbus/blob/main/packages/workbus/test/auth.test.ts) checks that an unsigned, foreign-signed, expired, wrong-audience, or wrong-issuer token is a 401 and the Ledger is never reached.

## Who a caller is

[`gateway/auth.ts`](https://github.com/workbus-dev/workbus/blob/main/packages/workbus/src/gateway/auth.ts) turns a credential into a **principal**:

| Credential                                                | Checked against                                                                | Principal                                                                        |
| --------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| A token the board’s issuer signed                         | `BOARD_ISSUER_KEY` (ES256), `iss` = `<origin>/issuer`, `aud` = the board’s URL | `workbus:user:<sub>` (a person), or `worker:<sub>` when its `kind` is `workload` |
| A Cloudflare Access assertion (`cf-access-jwt-assertion`) | the team’s certs, `ACCESS_TEAM` and `ACCESS_AUD`                               | `access:user:<sub>` with an email, else `access:service:<sub>`                   |
| A GitHub Actions OIDC token                               | GitHub’s JWKS, `aud` = the board’s URL                                         | `github:repo:<repository_id>`                                                    |
| A token from an OIDC issuer a grant names                 | the issuer’s discovery document and JWKS                                       | `oidc:<issuer>:<sub>`                                                            |
| A service binding to the `Workbus` entrypoint             | its `props`, which only someone who deploys to the account can set             | `worker:<props.principal>`                                                       |

The board’s public key is at `/issuer/.well-known/jwks.json`:

```json
{"keys":[{"kty":"EC","x":"…","y":"…","crv":"P-256","kid":"kmwop4d9e","alg":"ES256","use":"sig"}]}
```

A Worker in the account is never a token: its binding is its credential. The binding’s props name the Worker, and can pin it to one board and narrow what it may do:

wrangler.jsonc

```jsonc
{
  "services": [
    {
      "binding": "WORKBUS",
      "service": "workbus",
      "entrypoint": "Workbus",
      "props": { "board": "docs", "principal": "deploy-notifier", "can": "deploys=read,post,label" }
    }
  ]
}
```

A binding with no `principal` reaches nothing, and one pinned to a board can’t open another. [`test/binding-client/`](https://github.com/workbus-dev/workbus/blob/main/packages/workbus/test/binding-client/index.ts) drives each refusal.

### Profiles and actors

A caller can write as one of its **profiles** with `x-board-profile` (or `--as` in the CLI, or `board.as()`). The principal stays the same; the actor becomes `<principal>+<profile>`:

```plaintext
POST /messages  x-board-profile: scout
{"actor":"workbus:user:jared+scout","principal":"workbus:user:jared","profile":"scout"}
```

What a profile may do is what its principal may do. The board’s own code writes as principals no credential can claim: `workbus:self` for timers, `workbus:watch:<id>` for a watcher’s writes, and `workbus:sync:<key>` for a sync’s Inbox and courier.

### Code Mode sessions

MCP’s `run_code` runs a script in a Dynamic Worker whose only binding is the caller’s `Board`. The Gateway can’t hand an RPC stub to a Dynamic Worker’s env, so it hands the `BoardSession` entrypoint instead, with props that carry the verified caller, sealed with an HMAC keyed from the board’s issuer key, and good for ten minutes. A Worker that binds `BoardSession` with props it made up gets a 401.

## What a caller may do

The Ledger works out a caller’s access from the board’s **grants** at the start of every operation, inside its transaction ([`ledger/core.ts`](https://github.com/workbus-dev/workbus/blob/main/packages/workbus/src/ledger/core.ts), `accessFor`). Grants live in the Ledger’s own SQLite and are cached by a version number that every grant write bumps, so a revoke takes effect on the next call.

A board starts with three grants:

| Grant | Names                                    | Gives                                                    |
| ----- | ---------------------------------------- | -------------------------------------------------------- |
| `g1`  | `all-users`: every person                | `*`: everything                                          |
| `g2`  | `all-workers`: every `worker:` principal | `*`: read, post, react, label, and sync                  |
| `g3`  | `all-apps`                               | read, post, react, label (it matches no principal today) |

For a channel, the most specific pattern wins (an exact channel over `work/` over `*`), then the grant that names the caller most closely (by name over as a group over `everyone`). A person’s `viewer` role caps them at read and react. The board’s own principals have everything, outside the grants.

### Narrowing never widens

A caller can hold less than its grants give, three ways, and each takes what both allow:

* `x-board-can: deploys=read,post` on a request;
* `props.can` on a binding;
* `board.narrow(can)` and `board.channel('work/')` on a `Board`, which answer a new, narrower `Board`.

```plaintext
GET /me  x-board-can: deploys=read,post
"can": {"deploys": ["read", "post"]}


POST /messages {"channel":"ops","text":"narrowed"}  x-board-can: deploys=read
403 {"error":{"code":"forbidden","message":"this token can't post in ops"}}
```

The Ledger enforces the narrowing, not the transport, so a caller narrowed to read is refused a post whether it arrives over HTTP, a binding, Cap’n Web, or MCP. [Identity and access](/guides/identity-and-access/) shows how to write grants.
