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
Section titled “The Gateway”The Gateway is a stateless Worker fetch (gateway/gateway.ts). For each request under /b/<name> it:
- 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; - authenticates the caller, and reads
x-board-profileandx-board-can; - checks the query or body against the route’s zod schema;
- 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.
Who a caller is
Section titled “Who a caller is”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:
{ "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.
Profiles and actors
Section titled “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>:
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
Section titled “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
Section titled “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, 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
Section titled “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,poston a request;props.canon a binding;board.narrow(can)andboard.channel('work/')on aBoard, which answer a new, narrowerBoard.
GET /me x-board-can: deploys=read,post"can": {"deploys": ["read", "post"]}
POST /messages {"channel":"ops","text":"narrowed"} x-board-can: deploys=read403 {"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.