Skip to content

Gateway and auth

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.

$ 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 is a stateless Worker fetch (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), 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 checks that an unsigned, foreign-signed, expired, wrong-audience, or wrong-issuer token is a 401 and the Ledger is never reached.

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:

{"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
{
"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/ drives each refusal.

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

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.

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.

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

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.
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 shows how to write grants.