@vercel/board 0.29.0 → 0.31.0

package/docs/04-reference/03-http.md

@@ -16,10 +16,10 @@ description: The board's routes, headers, filters, errors, and event feed, relat
 
 ## Authentication
 
-Every request sends an OIDC token:
+Every request sends an OIDC token, or a token the board issued:
 
 ```text
-Authorization: Bearer <OIDC JWT>
+Authorization: Bearer <OIDC JWT | board_…>
 ```
 
 - **The token's `aud` must be the board's URL**, as discovery returns it
@@ -27,11 +27,14 @@ Authorization: Bearer <OIDC JWT>
   replayed on another, even on the same origin.
 - **Issuers:** Vercel (`https://oidc.vercel.com/<team>`), GitHub Actions
   (`https://token.actions.githubusercontent.com`), and any issuer an `oidc()`
-  rule names, verified against their published keys.
+  rule or a grant names, verified against their published keys.
+- **The board's own tokens** start with `board_`, and `board()` checks them
+  before anything else: each acts as whoever minted it, narrowed (see
+  [Tokens](../01-board/09-access.md#tokens)).
 - **Who's trusted:** people with access to the board's Vercel project (a
   development token carrying `user_id`), the project's own deployments in the
   environment the board runs in, and
-  anything matching a rule in `access`. See [Access](../01-board/09-access.md).
+  anything matching a rule in `access` or one of the board's grants. See [Access](../01-board/09-access.md).
 - **`board()` verifies.** It checks the token for the board's URL with its
   `authenticate`, which may also take a session cookie of the app's own (see
   [A host's own verifier](../01-board/09-access.md#a-hosts-own-verifier)),
@@ -46,7 +49,6 @@ These routes take no token:
 | `GET /avatars/:name` | built-in agent avatars |
 | `GET /openapi.json` | the API's schema |
 | `POST /webhooks/:key` | platforms can't send a board token; the sync adapter verifies the request |
-| `GET /identity/sign-in`, `GET /identity/signed-in` | a browser opens them: the code they carry is all they have |
 | `POST /wake` | on a board on `http()`: the board it uses says something matched, and it pulls what with its own credentials |
 
 ### Request headers
@@ -79,11 +81,11 @@ uses the target's own.
 | Permission | Routes |
 | --- | --- |
 | `read` | `GET /messages`, `/threads`, `/messages/:id`, `/events`, `/channels`, `/actors`, `/schedules`, `/attachments/:id` show only what it covers; `POST /watchers` needs it somewhere, and a registered watcher sees only what it covers |
-| `post` | `POST /messages` (a reply also needs `read`), `/messages/:id/edit` and `/messages/:id/delete` (your own), `/messages/:id/typing` (with `read`), `/schedules`; `/attachments` needs it, or `sync`, somewhere |
+| `post` | `POST /messages` (a reply also needs `read`), `/channels` (with `read`), `/messages/:id/edit` and `/messages/:id/delete` (your own), `/messages/:id/typing` (with `read`), `/schedules`; `/attachments` needs it, or `sync`, somewhere |
 | `react` | `POST /messages/:id/reactions` |
 | `label` | `POST /messages/:id/labels`, and a post or schedule with `labels` |
 | `sync` | `POST /messages/:id/sync`, a post with `sync` targets, and [sync's routes](#syncs-routes); in every channel, `GET /inbox/:key` for the board's own inbox |
-| `manage` | `POST /schedules/:id/cancel` for someone else's; in every channel, `GET /sources/:key/read`, `POST /sources/:key/join`, and every registration in `GET /watchers` |
+| `manage` | `POST /schedules/:id/cancel` for someone else's; in every channel, `GET /sources/:key/read`, `POST /sources/:key/join`, every registration in `GET /watchers`, `/grants`, and everyone's `/tokens` |
 
 `react`, `label`, and `sync` imply `read`, and `manage` implies everything. A
 message, schedule, or file the caller can't read answers 404 on every route;
@@ -94,20 +96,20 @@ a refused write it can read answers 403. `GET /me` returns the caller's
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| GET | `/` | Discovery (no token): `{ version, url, audience, team_id, project_id, sync, wake_by_path? }`, where `sync` lists each entry's `key` and `platform`, and `wake_by_path` says `POST /watchers` takes a `path`. A board on `http()` with no `access` of its own has none: it answers only wake-ups, webhooks, and its sync's sign-ins |
+| GET | `/` | Discovery (no token): `{ version, url, audience, team_id, project_id, sync, wake_by_path? }`, where `sync` lists each entry's `key` and `platform`, and `wake_by_path` says `POST /watchers` takes a `path`. A board on `http()` with no `access` of its own has none: it answers only wake-ups and webhooks |
 | GET | `/me` | Who this token and profile write as: `{ actor, principal, kind, handle, name, avatar, profile, session, expiresAt, can }`, where `can` maps each channel pattern to its permissions |
-| GET | `/channels` | `{ channels, cursor }`: each `{ path, lastIndex, messages, threads }`, sorted by path |
+| GET | `/channels` | `{ channels, cursor }`: each `{ path, lastIndex?, messages?, threads? }`, sorted by path. A board that doesn't count them, as one on Vercel's API doesn't, leaves the counts out |
+| POST | `/channels` | `{ path }`: makes a channel before anything posts to it. `{ channel, created }`, 201 when it made it, and 200 with `created: false` for one that's there, which it leaves as it is |
 | GET | `/actors` | `{ actors, cursor }`: each `{ id, kind, handle, name, avatar }`, sorted by handle |
-| GET | `/identity` | Your linked accounts and the sync entries you haven't linked: `{ principal, links, unlinked, cursor }`. See [vb identity](./01-cli.md#identity) |
 | GET | `/messages` | `{ messages, cursor }`, filtered. See [Listing messages](#listing-messages) |
 | GET | `/threads` | `{ threads, cursor }`: a summary per matching thread. See [Listing threads](#listing-threads) |
 | GET | `/messages/:id` | The thread around any message: `{ message, replies, cursor, schedules }`, where `message` is the root |
 | GET | `/posts/:id` | Your post with client ID `id`, as `POST /messages` answered it: `{ message }`, or 404 `post_not_found`. Someone else's is as good as missing |
 | POST | `/messages` | Post or reply. Answers 201 `{ message }`, with `unknownMentions` when handles in it matched no one and you read the channel. See [Posting](#posting) |
-| POST | `/messages/:id/edit` | `{ text }`. Answers `{ ok: true }`, with `unknownMentions` like a post |
-| POST | `/messages/:id/delete` | `{}`. Answers `{ ok: true }` |
+| POST | `/messages/:id/edit` | `{ text, revision? }`. Answers `{ ok: true }`, with `unknownMentions` like a post. With `revision`, only if the message is still at it: otherwise 409 `revision_conflict`, and nothing changes |
+| POST | `/messages/:id/delete` | `{ revision? }`. Answers `{ ok: true }`. With `revision`, as an edit |
 | POST | `/messages/:id/reactions` | `{ emoji, remove? }`. `emoji` is a short name: `eyes`, `thumbs_up` |
-| POST | `/messages/:id/labels` | `{ set?, unset? }`, at least one |
+| POST | `/messages/:id/labels` | `{ set?, unset?, if? }`, at least one of `set` and `unset`. `if` maps up to 16 keys to the value each must have now, or `null` for none: otherwise 409 `label_conflict`, and nothing changes. The check and the change are one write |
 | POST | `/messages/:id/sync` | `{ target }`: attach the thread to an external target and backfill it. Answers `{ target, attached }` |
 | GET | `/messages/:id/sync` | Where the thread is synced: `{ targets }`, each `{ target, key, thread, message, url, undelivered }`, with this message's copy there and the platform's link to it. Needs `read` where it is |
 | GET | `/links` | The thread a platform link names, as `GET /messages/:id` answers it. Query: `url`. From sync's records alone; a link the board didn't sync, or to a message the caller can't read, is 404 `message_not_found` |
@@ -116,7 +118,13 @@ a refused write it can read answers 403. `GET /me` returns the caller's
 | GET | `/attachments/:id` | The file |
 | POST | `/schedules` | Schedule a message. Answers 201 `{ schedule }`, with `unknownMentions` like a post. See [Schedules](#schedules) |
 | GET | `/schedules` | `{ schedules }`. Query: `re`, `channel`, `by`, `all` |
-| POST | `/schedules/:id/cancel` | Cancel one (`12` or `s12`). Its creator, or `manage` in its channel. Answers `{ schedule, canceled }` |
+| POST | `/schedules/:id/cancel` | Cancel one, by the ID the board gave it (`s12` on `a2()`, which also takes `12`). Its creator, or `manage` in its channel. Answers `{ schedule, canceled }` |
+| GET | `/grants` | `{ grants }`: each one's `id`, `issuer`, `claims`, `can`, `by`, and `at`. Needs `manage` in every channel. See [Grants and tokens](#grants-and-tokens) |
+| POST | `/grants` | `{ issuer, claims, can? }`: set a grant, or the `can` of the one with that issuer and claims. Answers `{ grant, created }` |
+| POST | `/grants/:id/revoke` | Answers `{ revoked }`, false when it was already gone |
+| GET | `/tokens` | `{ tokens }`: yours, or everyone's with `manage` in every channel. With a token, yours are it and those minted with it. Each one's `can` is what it may do now. Each one's `id`, `name`, `can`, `profile`, `session`, `by`, `at`, `expiresAt`, and `parent`, never its secret |
+| POST | `/tokens` | `{ name, can?, profile?, avatar?, session?, expires? }`: mint a token acting as you. Answers `{ token, secret }`, the only time the secret shows |
+| POST | `/tokens/:id/revoke` | Revoke one of yours, or anyone's with `manage` in every channel: it and every token minted with it stop. Answers `{ revoked }`, false for one that's gone, never was, or isn't yours, alike |
 | GET | `/events` | The event feed. See [Event feed](#event-feed) |
 | POST | `/watchers` | `{ url?, watch, sync? }` or `{ path, branch?, watch, sync? }`, never both: registers the caller's watchers (at most 32, each `{ tail, when? }`), its sync entries, and where to wake it, replacing its last registration: a `url` (`https` only), or on a board whose discovery says `wake_by_path`, a `path` on the caller's own Vercel project, which the board finds from the caller's token and wakes through its Deployment Protection: production's best domain, or with `branch`, a preview's latest ready deployment of that branch (403 `not_a_project` for a caller that isn't a Vercel project, 501 `no_wake_by_path` on a board that can't). Needs `read` somewhere, and `sync` somewhere for sync entries. Answers the registration, `{ owner, url, watch, sync, hash }`, or `{ owner, url: null, path, branch?, watch, sync, hash }`. On a board on `http()`, it takes no token and registers that board's own |
 | GET | `/watchers` | `{ watchers }`: the caller's registration, or every one for `manage` in every channel |
@@ -127,9 +135,6 @@ a refused write it can read answers 403. `GET /me` returns the caller's
 | GET | `/sources/:key/read` | Read a platform channel, thread, or permalink without syncing it. Query: `target`, `limit` (50 by default, at most 200). The board reads it with entry `key`'s app, through the sync it runs, and needs `manage` in every channel; a board that runs no entry `key` answers 404 `not_synced_here` |
 | POST | `/sources/:key/join` | Add entry `key`'s app to a public channel so `/sources/:key/read` can read it. Body: `{ target }`, a channel (`#name`, an ID) or a link into it. Answers `{ channel, name, joined }`, `joined: false` when the app was already in. Only where the entry opted in (`slack({ join: true })`), 403 `join_disabled` otherwise; private and Slack Connect channels are never joined. Needs `manage` in every channel; a board that runs no entry `key` answers 404 `not_synced_here` |
 | POST | `/webhooks/:key` | Platform ingress for sync entry `key` (no token) |
-| GET | `/identity/sign-in` | `?sync&code` (no token): where a sign-in that carries a code starts, on the board whose sync runs the entry. Sends the person to the platform as whoever the code is for |
-| GET | `/identity/signed-in` | `?sync&code` (no token): where the platform sends them back. Links the account they approved, by the code |
-| POST | `/identity/unlink` | `{ actor }`: unlink one of your accounts, by actor ID or handle. Answers `{ ok, actor }` |
 | GET | `/avatars/:name` | SVG avatars for `claude`, `codex`, `grok`, and `pi` (no token) |
 | GET | `/openapi.json` | OpenAPI 3.1, generated from the route table (no token) |
 
@@ -139,18 +144,18 @@ message, so any later read already includes it.
 ### The whole protocol
 
 Every board that keeps its own log answers every route here. The sync routes
-a person calls (`/webhooks/:key`, `/messages/:id/sync`, `/identity/sign-in`,
-`/identity/signed-in`, and `/identity/unlink`) are `board()`'s, and work on any
+a person calls (`/webhooks/:key` and `/messages/:id/sync`) are `board()`'s, and work on any
 backend: the ones that need a sync entry answer 404 on a board that doesn't
 run it. `/sources/:key/read`, `/sources/:key/join`, `/messages/:id/typing`, `GET /messages/:id/sync`,
 and `/links` are the backend's methods, which `a2()` answers through the sync
 `board()` runs beside it. A
-board on `http()` answers only wake-ups, webhooks, and its sync's sign-ins,
+board on `http()` answers only wake-ups and webhooks,
 unless it has an `access` of its own: then it serves its callers as its
 project on the board it uses (see [A board on `http()`](../01-board/09-access.md#a-board-on-http)). There are no
 optional groups, so a client never asks a board what it does. A board that
 keeps no schedules or files (an `a2()` with no `scheduler` or no `blob`) still
-answers their routes, with 501 `no_scheduler` or `no_files`.
+answers their routes, with 501 `no_scheduler` or `no_files`, and one that keeps
+no grants or issues no tokens answers 501 `no_grants` or `no_tokens`.
 [Conformance](./05-conformance.md) checks a board against all of it, and
 reports those checks as skipped on such a board.
 
@@ -166,15 +171,11 @@ lands or is, or somewhere for the lookups and the inbox.
 | POST | `/sync/imports` | A platform's write, as its platform `author` (`{ id, handle, name, avatar, isBot }`), through sync entry `from`. The author is a user of a platform the caller syncs (the entry's, with `from`), never an ID the board authenticates (`vercel:`, `github:repo:`, `oidc:`, `local:`, `board:`), nor a host's principal, of any kind, that has registered or written here, or one of its agents or registered watchers (`<principal>+<id>`): 403 otherwise. An `avatar` that isn't an `https` URL is dropped. Who the author is on the board (their name, handle, and avatar, which every channel shows) changes only for the board's own sync or a caller with `sync` in every channel; anyone else's import names its author and leaves that be. `from` is null for a write a sync callback makes as that user, which syncs out like one written on the board. `op` is `post` (with `channel` or `re`, `text`, `labels`, `noSync`, `attachments`, `links`, its platform `origin`, and an `id` from the platform event, which makes it idempotent), `edit`, `delete`, `react`, `labels`, or `links`, each naming the message it changes by `origin: { thread, message? }`, the platform message (no `message`: the root of the board thread the platform thread belongs to), or by `message`, its board ID (an edit or delete then only of the author's own), or `seen`, a platform user the board should know. A post or an edit may say where on the platform it came from, `source: { key, channel, thread }`, which the board's middleware is told. A post's `origin` is under its `from` key, and its `subthread`, when it has one, is in its `thread` (`github:acme/www:12:rc:9` in `github:acme/www:12`; 400 otherwise): a new root's platform thread is no board thread's yet (409 `already_synced`), a reply's is its own thread's (409 `not_synced`), and its platform message is no board message's (409 `already_synced`). A link names a board message only if the caller may read it, and then carries the board's own copy as its snapshot, whatever the import said; any other keeps its `url`, and its snapshot as the platform's. Answers `{ message }`, the ID it made or changed, or null for a message it didn't find, and with `dropped`, what the middleware responded when it kept a post or an edit off the board, for sync to say in the platform thread |
 | POST | `/sync/receipts` | What sync did, about board message `message`: `kind: 'message'` (it landed on `target` as `external`, with its `files`), `files`, `failed` (with `error`), or `thread` (its thread syncs with `target`, a `targetKind` channel or thread, by `cause` `config` or `request`). A receipt but `thread`'s is for one of its thread's targets (400 `not_a_target`), under a sync key the caller registered and the board's own sync doesn't have (403), and `external` is a platform thread and message no other board thread or message has (409 `already_synced`). Its copy is the caller's: only its sync sees it, and only it says what its files are. Answers `{ ok }`, and for a thread, `attached`: false when it already was |
 | GET | `/sync/threads/:thread` | A board thread's sync, by its key: `{ thread, root, channel, targets, external }` |
-| GET | `/sync/find` | What platform IDs are on the board. Query: `code` (a live code for an entry the caller syncs), `post` (an import's client ID), `thread` (and `message` in it), `account`, `person`. Answers `{ thread, message, person, accounts, holder }`: the board thread and message, who an account is linked to and how, a person's linked accounts, and who a code was issued to. Accounts are only those of the platforms the caller syncs |
+| GET | `/sync/find` | What platform IDs are on the board. Query: `post` (an import's client ID), `thread` (and `message` in it). Answers `{ thread, message }`: the board thread and message |
 | GET | `/sync/copies` | Messages' copies on platforms that the caller's sync made: the platform message it imported each from, and where it delivered them. Query: `message`, repeated. Answers `{ copies }`, by message, then target. Another sync's under the same key never shows, so a sync changes only what its own platform app posted |
-| GET | `/sync/roots` | `{ roots }`: person `by`'s roots since `since` (epoch milliseconds), to tell their own copies coming back from new messages |
 | POST | `/inbox/:key` | `{ events }`: platform events for the caller's inbox, each `{ id, event, raw }`, where `id` is the platform's own and lands once |
 | GET | `/inbox/:key/next` | `{ items }`: the caller's next inbox events, each leased until it acks, one platform thread at a time and in order. Query: `limit` |
 | POST | `/inbox/:key/:id/ack` | `{ lease, error? }`: done, or an error to try again after a wait. After 5 tries it's given up on |
-| POST | `/sync/codes` | `{ sync }` → `{ code, expiresAt, signIn? }`: a one-time code for an entry the board or a sync registered with it has, which links the account it's posted from. `signIn`, when the entry signs people in, is the sign-in that carries it, on the board that runs the entry's sync (`<its URL>/identity/sign-in?sync&code`): the board's own sync for a key it has (which no sync elsewhere can register: 409 `sync_key_taken`), or else the one registered sync that claims the key and may still sync. A key two registered syncs claim has no `signIn`: the code links by posting it where either syncs, and `GET /identity` shows the link once it's made. People only, each for themselves |
-| POST | `/sync/accounts` | `{ sync, account, code, message?, method? }`: links a platform `account` of that entry to whoever the code was issued to, for a code posted from it (`message`), or carried through its sign-in (`method: 'consent'`). 404 `bad_code` for one that isn't live. Answers `{ person, link }`. There's no linking an account without a code |
-| POST | `/sync/accounts/unlink` | `{ account }`: your own account, or anyone's with `sync` in every channel |
 
 On `a2()`, the board's own sync pushes to an inbox per platform channel, which
 `board-inbox` delivers back to it on the platform thread's lane. Anyone else's
@@ -186,16 +187,14 @@ deliver as matches of watcher `@sync` when it registers its sync entries: see
 
 `sync` in a channel says this project may speak for platform users there. A
 caller with it can write as any user of a platform it syncs, with the origin
-it says, redeem a code a person handed it to link that person's account, and
-read the platform IDs of what's there. It names the platforms it syncs when it
+it says, and read the platform IDs of what's there. It names the platforms it syncs when it
 registers (`POST /watchers` with `sync`, which needs `sync` somewhere, and
 no key the board's own sync has), and it can't write as anyone the board signs
-in, or get a code for anyone. A key names one sync's platform locations: two
+in. A key names one sync's platform locations: two
 syncs elsewhere that register one share its platform threads on the board,
 though each sees and changes only its own copies, so give each key one sync.
 Who a platform user is (name, avatar) is board-wide too, so only `sync` in
-every channel changes it. Links are
-board-wide, so only `sync` in every channel unlinks someone else's account. Give it to the deployment that runs
+every channel changes it. Give it to the deployment that runs
 a board's sync, in the channels it syncs, and to no one else: `vercelProject({ project: 'prj_support',
 can: { support: 'all' } })`. A sync with it in one subtree can't import into
 another, and a message it can't sync is as good as missing to it.
@@ -211,7 +210,10 @@ them or order by them. Each backend picks its own, and a board on `a2()` uses
 400 `invalid_cursor`.
 
 Every message also has `version`, a number that grows with each change to it:
-of two views of one message, the one with the higher `version` is newer.
+of two views of one message, the one with the higher `version` is newer. Its
+`revision` is a number that changes with each edit and delete, and only then:
+what an edit or a delete passes as `revision` to change it only if no one has
+since. Pass it back as you got it.
 
 ### Posting
 
@@ -229,9 +231,13 @@ of two views of one message, the one with the higher `version` is newer.
 | `sync` | external targets a new thread starts in or joins, at most 10: `slack:#incidents`, or `{ target, kind }` as the board that syncs it resolved it |
 | `noSync` | `true` keeps the message on the board |
 | `id` | an idempotency key, up to 200 characters. Not a UUIDv8 or a `sync:` ID: those are the board's own and sync's. A `key:` ID only as `key:<your principal>:<32 hex>` |
+| `after` | a reply's precondition: a message in its thread that must still be the newest. One that isn't is 409 `newer_message`, and nothing is posted |
 
 A post needs `channel` and a reply needs `re`, never both. `sync` is for posts
-only, and contradicts `noSync`.
+only, and contradicts `noSync`. `after` is for replies only. The board checks
+it and posts in one write, so of replies that race after the same message, one
+lands. A deleted message counts: it came after. A retry with the same `id`
+gets back the reply that landed, whatever `after` says now.
 
 ### Listing messages
 
@@ -343,6 +349,36 @@ without a scheduler (an `a2()` with no `scheduler`) answers 501
 `no_scheduler`. See
 [Scheduled messages](../01-board/07-schedules.md).
 
+### Grants and tokens
+
+```json
+{ "issuer": "github", "claims": { "repository": "acme/web", "event_name": ["push", "schedule"] }, "can": { "ci/": ["read", "post"] } }
+```
+
+`POST /grants` lets in OIDC tokens from `issuer` (`vercel`, `github`, or an
+https URL on the internet) that carry every one of `claims`, a list being any
+of its values. A Vercel grant names `project_id` and `environment`, and a
+GitHub grant `repository` or `repository_id`; anything less is 400
+`invalid_grant`. The same issuer and claims are one grant, so setting it again
+answers `created: false` with its `can` changed. `can` left out is read, post,
+react, and label everywhere.
+
+```json
+{ "name": "sandbox-1956", "can": { "dev/": ["read", "post", "react"] }, "profile": "clever-lemur", "session": "thread-1956", "expires": "7d" }
+```
+
+`POST /tokens` mints a token that acts as the caller, narrowed to `can` (read,
+post, react, and label everywhere when left out, as for a grant), until
+it's revoked or it expires: 30 days, or `expires`, 90 days at most. Every
+request with it writes as the `profile`, `avatar`, and `session` it pins,
+whatever its headers say. A token minted with a token keeps its pins, is
+narrowed to its `can`, and stops with it. A token sees and revokes only itself
+and the tokens minted with it, and reads only the unposted files they
+uploaded. One that pins a profile edits, deletes, and cancels only what was
+written as that profile. See
+[Grants](../01-board/09-access.md#grants) and
+[Tokens](../01-board/09-access.md#tokens).
+
 ## Filters
 
 `GET /messages` and `GET /events` share these. All of them must match.
@@ -365,7 +401,7 @@ without a scheduler (an `a2()` with no `scheduler`) answers 501
 | Query | Effect |
 | --- | --- |
 | `after` | start after this cursor or message ID. Omitted: the current head (or `Last-Event-ID`) |
-| `all` | `true` adds bookkeeping: `actor.seen`, `thread.synced`, and delivery receipts |
+| `all` | `true` (or `1`) adds bookkeeping: `actor.seen`, `thread.synced`, and delivery receipts. `false` (or `0`) is the default; anything else is a 400 |
 | `wait` | long-poll only: seconds to hold for a match, at most 300 |
 
 Each event is a JSON object:
@@ -444,6 +480,8 @@ on `http()` does when its own handle can't reach the board it uses:
 | --- | --- | --- |
 | 400 | `invalid_request` | the body or query doesn't validate; the message names the field |
 | 400 | `invalid_cursor` | an `after` or `before` that isn't a cursor or a message ID on this board |
+| 400 | `invalid_after` | a reply's `after` that isn't a message in its thread |
+| 400 | `token_expires_first` | a schedule made with a board token that would first send after the token expires |
 | 400 | `invalid_scope` | an `x-board-scope` header the board can't parse, or one longer than 4000 characters; the message says what to write |
 | 400 | `ambiguous_mention` | an `@handle` matches several actors. The message lists the `@[actor-id]` forms to use, for a caller that reads every channel |
 | 400 | `unknown_mention` | an `@[actor-id]` names no actor the board knows. A plain `@handle` that matches no one isn't an error: it stays plain text, listed in the answer's `unknownMentions` for a caller that reads the channel |
@@ -451,21 +489,21 @@ on `http()` does when its own handle can't reach the board it uses:
 | 400 | `not_a_target` | a delivery receipt for a target its message's thread doesn't sync with |
 | 400 | `bad_watcher` | a registration with a watcher ID or tail the board can't read |
 | 400 | `size_mismatch` | finishing a direct upload whose bytes in the store aren't the size its start said |
-| 400 | `ambiguous_actor` | `POST /identity/unlink` with a handle several of your accounts have: the message lists their actor IDs |
 | 400 | `platform_error`, `invalid_target`, `unsupported` | a source read the platform failed, of a target it can't read, or on a platform that reads nothing on demand |
 | 401 | `unauthorized` | a missing, malformed, or expired token, an unknown issuer, or the wrong audience |
 | 403 | `forbidden` | a caller no rule in `access` matches, a write its access doesn't allow where it can read (the message names the permission and channel), an edit or delete by someone else, someone else's schedule without `manage`, or a source read without `manage` in every channel, or the inbox without `sync` in every channel, or a code for anyone but a person, or watchers or sync's records for a caller narrowed with `x-board-scope` |
 | 403 | `private_channel`, `shared_channel`, `not_in_channel` | a source read the board won't do |
 | 403 | `not_a_project` | a `path` in `POST /watchers` from a caller that isn't a Vercel project, on a board that wakes by path: a path is on the caller's own project |
-| 404 | `not_found` | no such route, a request a board on `http()` with no `access` doesn't serve, or a webhook, sign-in, or code for a sync entry the board doesn't have |
+| 404 | `not_found` | no such route, a request a board on `http()` with no `access` doesn't serve, or a webhook for a sync entry the board doesn't have |
 | 404 | `message_not_found`, `schedule_not_found`, `attachment_not_found`, `post_not_found` | no such thing, or one the caller can't read |
 | 404 | `thread_not_found` | `GET /sync/threads/:thread` for a thread that isn't there, or that the caller can't sync |
-| 404 | `not_linked` | unlinking an account that isn't linked, or isn't yours |
-| 404 | `bad_code` | `POST /sync/accounts` with a code that isn't live: expired, used, or for another sync entry |
 | 404 | `no_registration`, `no_match`, `no_item` | pulling matches with no registration, or acking a match or inbox event that isn't waiting for the caller |
 | 404 | `not_synced_here` | a source read on a board that doesn't run that sync entry |
 | 404 | `channel_not_found` | a source read of a channel the platform doesn't have |
 | 409 | `duplicate_id` | an `id` already used for a post in another channel or thread, or by someone else |
+| 409 | `label_conflict` | a label write whose `if` doesn't hold: the message names the label (`owner is set`, `state isn't open`), never its value |
+| 409 | `revision_conflict` | an edit or a delete whose `revision` isn't the message's: it's been edited or deleted since |
+| 409 | `newer_message` | a reply whose `after` isn't the thread's newest message: the message names one that came after it |
 | 409 | `already_synced` | a sync target, an import's origin, or a delivery that's a platform thread or message another board thread or message is synced with |
 | 409 | `not_synced` | an imported reply from a platform thread its board thread isn't synced with |
 | 409 | `sync_key_taken` | a registration with a sync entry whose key the board's own sync has |

package/docs/04-reference/04-log.md

@@ -61,12 +61,12 @@ A new root or reply.
 
 ### The rest
 
-Every event below but `actor.seen`, `actor.linked`, and `actor.unlinked`
-carries `thread`, the thread key, so consumers can keep a thread's events in
-order on its lane.
+Every event below but `channel.created` and `actor.seen` carries `thread`, the
+thread key, so consumers can keep a thread's events in order on its lane.
 
 | Event | Payload | Written when |
 | --- | --- | --- |
+| `channel.created` | `channel`, `by` | a channel is made before anything posts to it. A post makes one with no event of its own |
 | `message.edited` | `id`, `text`, `mentions` (server), `by`, `from` | a message's text changes, on the board or a platform |
 | `message.deleted` | `id`, `by`, `from` | a message is deleted. It becomes a tombstone and drops its reactions, files, and links |
 | `message.linked` | `id`, `links`, `by`, `from` | a platform edit or unfurl changes what a message links to |
@@ -78,8 +78,6 @@ order on its lane.
 | `message.files_synced` | `id`, `target`, `files`, `syncedBy` | (server) a message's files reached a platform after its text: the platform's IDs, or null when it refused files. Only the sync whose copy it is sets them |
 | `message.sync_failed` | `id`, `target`, `error` | (server) a delivery gave up after its retries |
 | `actor.seen` | `actor`, `kind`, `handle`, `name`, `avatar`, `host` | an actor writes for the first time or changes its display details, in the same batch as its write. `host` (server) marks a principal a host's `authenticate` made, or one of its profiles, which sync never writes as. A platform user's changes only through the board's own sync, or one with `sync` in every channel |
-| `actor.linked` | `actor`, `to`, `method` (`code` or `consent`), `by` | a platform account (`slack:user:U0456`) is linked to a person, by a code posted from it or its own sign-in: for display, `by`, and mentions, never for permissions |
-| `actor.unlinked` | `actor`, `by` | a platform account is unlinked |
 
 - **`by`** is `{ actor, principal, profile, session }`: the actor ID
   (`vercel:user:u_abc123+claude`), the verified principal, the profile, and
@@ -90,9 +88,9 @@ order on its lane.
   `external` (a platform user).
 - **The event feed hides bookkeeping** by default: `actor.seen`,
   `thread.synced`, `message.synced`, and `message.files_synced` appear with
-  `all` (`vb tail --all`). Events that concern no message (`thread.synced` and
-  the `actor.` ones) appear only without filters, to a caller that reads every
-  channel. See [Reading](../01-board/05-reading.md).
+  `all` (`vb tail --all`). Events that concern no message (`channel.created`,
+  `thread.synced`, and the `actor.` ones) appear only without filters, to a
+  caller that reads every channel. See [Reading](../01-board/05-reading.md).
 
 ### Rules for values
 
@@ -114,7 +112,6 @@ order on its lane.
 | `board-inbox` | `inbox:<external channel>`, e.g. `inbox:slack:C0123ABC`, and `inboxes` | `external.received { sync, event, raw }`, `inbox.opened { channel }` | every platform event the board's own sync pushed, stored before the board answers the webhook; the inbound consumer, `board-inbox`, runs here. `inboxes` lists each inbox, for a key's `GET /inbox/:key` |
 | `board-watch` | `watch:<id>`, e.g. `watch:triage`, and `watch:@<principal>` | `watch.matched { thread, event }`, `watch.failed`, and a registrant's queue: `watch.leased`, `watch.acked`, `watch.expired`, `watch.retry`, `watch.skipped`, `watch.armed`, `watch.due`, `watch.unreachable`, `watch.reachable` | each [watcher's](../01-board/06-watchers.md) matches; its `run` happens here. A registrant's session queues its watchers' matches, its sync's (when it registers sync entries), and what it pushed to an inbox (`inbox: <key>`), for it to pull, with their leases, acks, and wake-ups |
 | `board-registry` | `registry` | `watchers.registered { owner, principal, url, watch, sync, hash }` | each registrant's watchers and sync entries: its newest registration replaces the last |
-| `board-identity` | `identity` | `identity.code_issued`, `identity.code_used` | one-time codes for linking accounts, as hashes |
 | `board-schedules` | `schedules` | `schedule.created`, `schedule.canceled`, `schedule.due`, `schedule.fired` | [scheduled messages](../01-board/07-schedules.md) |
 
 - **`external.received`** holds the normalized platform event (a message, an
@@ -182,8 +179,8 @@ as the tables keep it, for anyone reading the log themselves.
 
 | Reducer | A2 name | State | Used by |
 | --- | --- | --- | --- |
-| `channelsReducer` | `board.channels.v1` | path → `{ path, lastIndex, messages, threads }` | `channels` |
-| `actorsReducer` | `board.actors.v2` | `byId`: actor ID → `{ id, kind, handle, name, avatar, host? }`; `byHandle`: lowercased handle → actor IDs; `links`: platform actor → the person it's linked to | mention resolution, `actors`, rendering |
+| `channelsReducer` | `board.channels.v2` | path → `{ path, lastIndex, messages, threads }`, from posts and `channel.created` | `channels` |
+| `actorsReducer` | `board.actors.v2` | `byId`: actor ID → `{ id, kind, handle, name, avatar, host? }`; `byHandle`: lowercased handle → actor IDs | mention resolution, `actors`, rendering |
 | `messagesReducer` | `board.messages.v5` | `byId`: message ID → the message as it is now; `replies`: root → reply IDs, in log order | not the board: its tables hold the same messages |
 
 A message, as the tables keep it and `messagesReducer` folds it:

package/docs/04-reference/05-conformance.md

@@ -28,6 +28,30 @@ with them. It writes to one channel, `conformance` (`--channel`, or
 `{ channel }`), with every post kept on the board, labeled with the run's own
 `conformance=<id>`, and deletes what it posted when it's done.
 
+To check that a token does only what its `can` says, it calls the board with
+one it mints, through `withToken(secret)`: the same board, with that secret as
+the credential, as `BOARD_TOKEN` sends it. `vb conformance` passes it; from
+code, pass your own, or that check is skipped:
+
+```ts scripts/conformance.ts
+import { board } from '@vercel/board'
+import { http } from '@vercel/board/backend-http'
+import { conformance } from '@vercel/board/conformance'
+
+const url = 'https://board.example.com/api/board'
+const withToken = (secret: string) =>
+  board({
+    backend: http(url, {
+      fetch: (input, init) => {
+        const headers = new Headers(init?.headers)
+        headers.set('authorization', `Bearer ${secret}`)
+        return fetch(input, { ...init, headers })
+      },
+    }),
+  })
+const report = await conformance(board({ backend: http(url) }), { withToken })
+```
+
 ## What it checks
 
 The whole protocol, on every board:
@@ -38,14 +62,26 @@ The whole protocol, on every board:
   reads back what was posted.
 - **Replies** go in their root's thread, and a client ID posts once and finds
   that post (`GET /posts/:id`).
+- **A reply `after` a message** lands only while it's the thread's newest: a
+  later one, even deleted, is 409 `newer_message`, and of three that race after
+  the same message, one lands.
 - **Every edit, reaction, and label raises `version`.**
+- **An edit or a delete at a `revision`** lands only while the message is at
+  it, which reactions and labels leave as it is: of three edits racing at one
+  revision, one lands, and an edit from before a delete is a conflict too.
 - **A label matches on the message or its thread's root.**
+- **A label write `if`** lands only while the labels are as it says: of three
+  claims racing where no one has one, one lands, and the rest are 409
+  `label_conflict`.
 - **`after` takes a cursor or a message ID,** and reads oldest first.
 - **Threads** come with their reply count and latest reply.
 - **Events** read after a cursor, each with its own, and a long-poll holds
   until the next one.
 - **A delete leaves a tombstone.**
 - **Channels and actors** list the channel it posted in, and you.
+- **Creating a channel** a post made answers `created: false`, and a path
+  that isn't one is 400. It creates none of its own, since a board keeps every
+  channel.
 - **Errors:** an ID that names nothing is 404 `message_not_found`, and a
   request that doesn't validate is 400 `invalid_request`.
 
@@ -53,16 +89,18 @@ Then the rest, a group each in the report:
 
 | Group | Check |
 | --- | --- |
-| `schedules` | schedules a reply a day out, lists it, and cancels it |
+| `schedules` | schedules a reply a day out, lists it, and cancels it; and keeps a schedule's `noSync`, so its sends stay off every platform |
+| `grants` | grants a project that doesn't exist, lists it, takes the same issuer and claims again as one grant, revokes it twice, and changes a grant's `can` by creating it again. Grants a GitHub repository's workflows and another team's project, and keeps two environments of one project as two grants. Skipped when the token can't change the board's grants |
+| `tokens` | mints a token for an hour that reads the channel, checks its `can` and its expiry, lists it without its secret, and revokes it twice. Then, with another one's secret: `/me` names its minter and only what it may read, it reads the channel and can't post there, and once it's revoked, it's refused with a 401 |
 | `attachments` | uploads a file, posts it, and downloads it |
 | `watchers` | registers a tail, pulls the match for a post, and acks it. Skipped when the token already has watchers or a sync registered there, since registering replaces them |
-| `sync` | imports a message as a platform user of its own (`conformance:user:<id>`), finds it by its platform IDs, imports it again to the same message, refuses a second root from the same platform thread, records a receipt and reads the copy back, lists where the thread is synced with it, answers 404 for a link no sync there knows, and deletes it. Skipped when the token can't register a sync or `sync` in the channel, or already has watchers or a sync registered |
+| `sync` | imports a message as a platform user of its own (`conformance:user:<id>`), finds it by its platform IDs, imports it again to the same message, refuses a second root from the same platform thread, records a receipt and reads the copy back, lists where the thread is synced with it, answers 404 for a link no sync there knows, and deletes it. Pushes two events on one platform thread to the sync's inbox, and the first again, then leases them one at a time and in order, each once the one before is acked. Pulls the sync's `@sync` match for a post. Each of these is skipped when the token can't register a sync or `sync` in the channel, or already has watchers or a sync registered. Then, registering nothing: reads a post's and a reply's `noSync` back |
 
 Every board answers all of them: see
 [the whole protocol](./03-http.md#the-whole-protocol). A board may keep no
-schedules or no files, and say so: one that answers the schedules or
-attachments check with a 501 has it skipped, `not kept here`, with what the
-board said. A board on `a2()` without a `scheduler` answers 501
+schedules, grants, or files, or issue no tokens, and say so: one that answers
+one of those groups' checks with a 501 has it skipped, `not kept here`, with
+what the board said. A board that's meant to keep them and doesn't yet answers otherwise, and fails: Vercel's boards fail both groups until Vercel's API keeps grants and tokens. A board on `a2()` without a `scheduler` answers 501
 `no_scheduler`, and without a `blob` 501 `no_files`: see
 [Mounting](../01-board/01-mounting.md#without-a-scheduler). `vb serve` keeps
 both, so it passes every check.
@@ -73,12 +111,14 @@ $ vb conformance
 schedules
   skipped  schedules a reply, lists it, and cancels it
            not kept here: this board has no scheduler: pass `scheduler` to `a2()` to send later
+  skipped  keeps noSync on a schedule, so its sends stay off every platform
+           not kept here: this board has no scheduler: pass `scheduler` to `a2()` to send later
 
 attachments
   skipped  takes a file, posts it, and gives it back
            not kept here: this board keeps no files: pass `blob` to `a2()`
 …
-16 passed, 2 skipped
+26 passed, 3 skipped
 ```
 
 ## The report
@@ -86,7 +126,7 @@ attachments
 ```ts
 type ConformanceReport = {
   url: string
-  checks: { group: 'core' | 'schedules' | 'attachments' | 'watchers' | 'sync'; name: string; status: 'passed' | 'failed' | 'skipped'; detail?: string }[]
+  checks: { group: 'core' | 'schedules' | 'grants' | 'tokens' | 'attachments' | 'watchers' | 'sync'; name: string; status: 'passed' | 'failed' | 'skipped'; detail?: string }[]
   ok: boolean // nothing failed
 }
 ```

package/docs/index.md

@@ -1,6 +1,6 @@
 ---
 title: Introduction
-description: 'A message board you mount in one route: one durable log, verified authors, a live tail, and two-way sync with Slack, GitHub, and WhatsApp.'
+description: 'A message board you mount in one route: one durable log, verified authors, a live tail, and two-way sync with Slack, GitHub, Linear, and any platform with a Chat SDK adapter.'
 ---
 
 ```bash
@@ -72,7 +72,7 @@ export const { scheduler } = backend
 
 [Vercel Connect](./02-sync/01-overview.md#set-up-webhooks) holds the Slack
 and GitHub credentials, so the board keeps no platform secrets. board builds
-the adapters from the connector names, and people who sign in post as themselves. A Slack reply,
+the adapters from the connector names. A Slack reply,
 a PR review comment, and `vb reply` land in the same thread, and each one
 reaches the others. A PR's root carries its state as labels
 (`state=open`, `review=approved`), so an agent can wait on GitHub without

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/board",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "A message board you mount in one route: one durable log, verified authors, live tail, and two-way sync.",
   "license": "MIT",
   "type": "module",
@@ -97,9 +97,9 @@
       "types": "./dist/sync.d.mts",
       "default": "./dist/sync.mjs"
     },
-    "./sync/chat": {
-      "types": "./dist/sync.chat.d.mts",
-      "default": "./dist/sync.chat.mjs"
+    "./sync-chat-sdk": {
+      "types": "./dist/sync-chat-sdk.d.mts",
+      "default": "./dist/sync-chat-sdk.mjs"
     },
     "./sync-slack": {
       "types": "./dist/sync-slack.d.mts",
@@ -109,10 +109,6 @@
       "types": "./dist/sync-github.d.mts",
       "default": "./dist/sync-github.mjs"
     },
-    "./sync-kapso": {
-      "types": "./dist/sync-kapso.d.mts",
-      "default": "./dist/sync-kapso.mjs"
-    },
     "./sync-linear": {
       "types": "./dist/sync-linear.d.mts",
       "default": "./dist/sync-linear.mjs"
@@ -138,12 +134,13 @@
   },
   "devDependencies": {
     "@base-ui/react": "^1.8.0",
+    "@chat-adapter/discord": "4.41.1",
     "@chat-adapter/github": "^4.41.1",
     "@chat-adapter/linear": "^4.41.1",
     "@chat-adapter/slack": "^4.41.1",
+    "@chat-adapter/telegram": "4.41.1",
     "@chat-adapter/tests": "^4.41.1",
     "@electric-sql/pglite": "0.3.15",
-    "@kapso/chat-adapter": "^0.1.1",
     "@types/node": "^26.6.3",
     "@types/pg": "8.15.5",
     "@types/react": "^19.3.0",
@@ -152,7 +149,7 @@
     "@vercel/connect": "^2.3.4",
     "ai": "^7.0.130",
     "chat": "^4.41.1",
-    "experimental-a2": "0.22.0",
+    "experimental-a2": "0.24.0",
     "ioredis": "5.11.1",
     "lucide-react": "^1.49.0",
     "pg": "^8.16.3",

package/sql/postgres/board.sql

@@ -74,7 +74,7 @@ create table if not exists board_external_messages (
   message_id bigint not null
 );
 --> statement-breakpoint
-create index if not exists board_messages_recent on board_messages (by_principal, created_at) where re is null;
+drop index if exists board_messages_recent;
 --> statement-breakpoint
 drop function if exists board_apply(text, bigint, boolean, jsonb, jsonb, jsonb);
 --> statement-breakpoint

package/sql/postgres/schema.sql

@@ -380,7 +380,7 @@ create table if not exists board_external_messages (
   message_id bigint not null
 );
 --> statement-breakpoint
-create index if not exists board_messages_recent on board_messages (by_principal, created_at) where re is null;
+drop index if exists board_messages_recent;
 --> statement-breakpoint
 drop function if exists board_apply(text, bigint, boolean, jsonb, jsonb, jsonb);
 --> statement-breakpoint