@civitai/sdk 0.3.0 → 0.5.0

package/BREAKING.md

@@ -7,17 +7,19 @@ API catch up.
 ## Data moved from the bridge to the API
 
 A block used to ask the host for data over `postMessage`. It now calls the
-public `/api/v1` API (`app.site`) and the orchestrator (`app.orchestration`)
-itself, with the token `initialize()` gives it. Routes are added to `/api/v1` as apps need them, so several old
+public `/api/v1` API (`app.site`) itself, with the token `initialize()` gives
+it. `app.orchestration` reaches the orchestrator directly and is the escape
+hatch for an app that is its own principal — a block submitting generations
+uses the `blocks/workflows/*` routes instead, for the reasons below. Routes are added to `/api/v1` as apps need them, so several old
 messages have no destination yet.
 
 | Old message(s) | Now | Status |
 |---|---|---|
-| `GET_VIEWER` | `app.site.get('me')` | Route exists |
-| `SUBMIT_WORKFLOW`, `ESTIMATE_WORKFLOW`, `POLL_WORKFLOW`, `CANCEL_WORKFLOW`, `QUERY_APP_WORKFLOWS`, `CANCEL_APP_WORKFLOW` | `app.orchestration` | Works with an OAuth token |
-| `GET_IMAGES_BY_IDS` | `GET /api/v1/images?ids=1,2,3` | Batch, up to **100** ids per request. Misses are reported by OMISSION — see below |
-| `APP_STORAGE_*` | — | No v1 route |
-| `SHARED_*` | `GET\|POST /api/v1/blocks/shared-storage/*` | **Route exists** — nine of them; see *Shared storage* below |
+| `GET_VIEWER` | `app.site.get('blocks/me')` | Route exists. 🔴 **Not `site.get('me')`** — that resolves to `/api/v1/me`, an `AuthedEndpoint` that does not accept a block token |
+| `SUBMIT_WORKFLOW`, `ESTIMATE_WORKFLOW`, `POLL_WORKFLOW`, `CANCEL_WORKFLOW`, `QUERY_APP_WORKFLOWS`, `CANCEL_APP_WORKFLOW` | `POST /api/v1/blocks/workflows/{submit,estimate,poll,cancel,query}` | **Routes exist.** 🔴 Use these, **not** `app.orchestration` — see *What a direct orchestrator call loses* below |
+| `GET_IMAGES_BY_IDS` | `GET /api/v1/blocks/images?ids=1,2,3` | Batch, up to **100** ids per request. Misses are reported by OMISSION — see below. 🔴 **Not `/api/v1/images`** — that is a `PublicEndpoint`; it ignores your token and answers with anonymous public results rather than erroring |
+| `APP_STORAGE_*` | `POST /api/v1/blocks/app-storage/*` | **Routes exist** — five of them (`get`, `set`, `delete`, `list`, `quota`), civitai#5085. This row said "No v1 route"; that is no longer true. See *App storage* below |
+| `SHARED_*` | `GET\|POST /api/v1/blocks/shared-storage/*` | **Routes exist** — eleven of them; see *Shared storage* below |
 | `GET_BUZZ_BALANCE` | `GET /api/v1/blocks/buzz` | **Route exists.** Returns `{ blue, green, yellow }` — a bare object, three numbers |
 | `GET_BUZZ_ACCOUNTS`, `GET_BUZZ_TRANSACTIONS` | — | No v1 route |
 | `CREATE_POST_FROM_APP` | — | No v1 route, **and deliberately staying on the bridge** — see below |
@@ -26,33 +28,33 @@ messages have no destination yet.
 | `GET_DAILY_COMPENSATION`, `GET_WILDCARD_PACK`, `TRACK_EVENT` | — | Not carried |
 
 ⚠ `TRACK_EVENT` is filed above beside two one-consumer capabilities, which understates it: it is emitted by
-`useBlockAnalytics`, used by **all 7 fleet apps across 40 files**. It is listed as *not carried* because **it has
+`useBlockAnalytics`, which the fleet apps call widely. It is listed as *not carried* because **it has
 no host handler today either** — `hostHandlerParity.ts` marks both hosts N/A, *"analytics fire-and-forget; no
-host-side sink wired (dropped, never hangs)"*. So those 40 call sites are already no-ops; this is net-new
+host-side sink wired (dropped, never hangs)"*. So those call sites are already no-ops; this is net-new
 capability rather than a migration gap.
 
-## 🔴 Before you call ANY block REST route: the scope-binding trap
+## Scope binding is per-route
 
-The request-time scope-binding check runs over **every scope on your block token**, not just the one the route
-requires. So a scope you declared for an unrelated feature can reject a call that has nothing to do with it,
-with an error naming a scope you never invoked.
+A route that declares a required scope binds **that scope, and only that one**, against your block context.
+`GET /api/v1/models/{id}` declares `models:read:self` and 403s unless `?id` equals the model your block
+renders beside; `GET /api/v1/blocks/buzz` declares `buzz:read:self` and does not look at your other scopes.
 
-The common case: an app declaring **`models:read:self`** calls `GET /api/v1/blocks/buzz`. That scope's binding
-wants `query.id` (or `query.modelId`) to match the model in your block context; a buzz request carries neither,
-so it **403s** with `models:read:self bound to different modelId`.
+⚠ A route that declares **no** required scope binds nothing. `GET /api/v1/blocks/models` accepts any valid
+block token, clamped only by the token's maturity ceiling — declaring `models:read:self` is not what gates
+it, and requesting it for that route buys consent surface you do not need.
 
-**Workaround — pass a param the handler ignores:**
+⚠ **This changed on 2026-09-23** (civitai#5063, fixed by #5067). Before that the check ran over *every* scope on
+the token, so an unrelated declared scope could 403 a call — an app declaring `models:read:self` got
+`models:read:self bound to different modelId` from `blocks/buzz`. **If you carry a workaround for that — a
+`{ query: { id: context.modelId } }` passed to a route that does not use it — you can drop it.**
 
-```ts
-await app.site.get('blocks/buzz', { query: { id: context.modelId } });
-```
-
-Applies to all ten current block REST routes (`blocks/buzz` and the nine under `blocks/shared-storage/`).
-Tracked as civitai/civitai#5063. The anon-read case below is the same bug with no workaround.
+One thing remains token-wide, and it is deny-by-default: a token carrying a scope the platform does not
+recognise is rejected outright. That is a registration-time mistake, which the manifest validator catches
+first.
 
 ## Shared storage
 
-Nine routes under `/api/v1/blocks/shared-storage/`. Reads take `apps:storage:shared:read`, writes take
+Eleven routes under `/api/v1/blocks/shared-storage/`. Reads take `apps:storage:shared:read`, writes take
 `apps:storage:shared:write` — both scopes already existed; neither is new.
 
 | Method | Path | Scope |
@@ -72,18 +74,13 @@ bridge already called, so behaviour is identical on both transports.
   entirely. An anon read still requires: a valid block token, the `apps:storage:shared:read` scope, an
   approved app, a non-revoked instance, and the feature flag enabled.
 
-  🔴 **BUT NOT TODAY, if your app also declares `apps:storage:shared:write`.** An anon token still carries
-  that scope (it is consent-exempt, so the anon mint does not strip it), and the request-time scope-binding
-  check runs over **every** scope on the token rather than the one the route needs — so it reaches the write
-  scope's "requires authenticated subject" rule and returns **403 for an anonymous read**.
-
-  There is no call-site workaround: an app cannot un-declare the write scope it needs in order to make its
-  read path work. Tracked as civitai/civitai#5063.
-
-  ⚠ **This is a behaviour change from the bridge, so check it before porting.** `SHARED_*` over `postMessage`
-  gates anonymity **per operation** — an anon read passes there today. On REST it currently does not. If your
-  app's premise is signed-out browsing, that path breaks on migration until #5063 lands.
-- **Anonymous viewers may NEVER write or vote.** Every write resolves to `401` for an anon subject.
+  ⚠ **This was briefly broken and is fixed.** Until 2026-09-23 an app that *also* declared
+  `apps:storage:shared:write` got a **403 on an anonymous read**, because the binding check ran over every
+  scope on the token and reached the write scope's "requires authenticated subject" rule. civitai#5063, fixed
+  by #5067 — binding is now per-route, so the read scope's own (absent) binding is all that applies.
+  **Signed-out browsing works on REST; if you deferred a migration over this, it is unblocked.**
+- **Anonymous viewers may NEVER write or vote.** An anon write is rejected by the write scope's own binding in
+  `withBlockScope`, before the handler runs, so it surfaces as **`403`** rather than the handler's own `401`.
 - **Authenticated writers must clear a minimum-trust gate.** After the anon check, writes call
   `assertSharedWriteTrust` — account age, paid tier, and verified email *or* a linked OAuth account. A signed-in
   viewer is not automatically a permitted writer.
@@ -94,14 +91,42 @@ bridge already called, so behaviour is identical on both transports.
 
 ### Error body
 
-The nine routes return `{ message }` on a 4xx. ⚠ The two oldest siblings (`top`, `increment`) return `{ error }`.
-That divergence is deliberate: the newer routes go through the shared error chokepoint rather than forwarding a
-raw database error string, which on this surface can name the app's schema and the offending row value. Write
-clients against `{ message }`; treat `{ error }` as legacy.
+🔴 **Which key carries the reason depends on WHERE the request died, so read both.** There are three shapes:
+
+| Refused by | Body |
+|---|---|
+| `withBlockScope` — bad token, revoked instance, unapproved app, missing scope, failed binding | `{ error }` **only** |
+| a route's own prologue — wrong method, missing param | `{ error }` only |
+| the service layer, through the shared error chokepoint | `{ message }` |
+| `restErrorBody` | `{ error, message, code }` |
+
+An earlier version of this section said to write clients against `{ message }` and treat `{ error }` as legacy.
+**That is wrong**: every middleware rejection — including the anonymous-write 403 above — carries no `message`
+at all, so a client following it logs `undefined` for the refusals it most needs to see. Read
+`message ?? error`, and treat the HTTP status as the thing you branch on.
+
+The chokepoint does matter for one thing, and that part stands: the newer routes do not forward a raw database
+error string, which on this surface can name the app's schema and the offending row value.
+
+## App storage
+
+Five routes under `/api/v1/blocks/app-storage/` — `get`, `set`, `delete`, `list`, `quota` (civitai#5085).
+Reads take `apps:storage:read`, writes take `apps:storage:write`. The SDK wraps them as `AppClient.storage`.
+
+⚠ **The migration delta: anonymous viewers get 403, where the bridge resolved an anonymous read to `null`.**
+Gate on `viewer` rather than reading an empty result as "nothing stored". Whether 403 is the intended policy
+per operation is open as civitai#5089.
+
+`updatedAt` is still revived to a `Date` by the client, as `useAppStorage` did, so consumers need no change.
+
+The client's own contract — block-token-only, every-failure-rejects, `nextCursor`, and the wire-vs-stored
+distinction between `set`'s `sizeBytes` and `getQuota`'s `usedBytes` — is in **README.md § App storage** and
+in the TSDoc that generates `api/public-api.md`. That TSDoc is regenerated and diffed by `api:check` in CI, so
+it is the copy that cannot rot; this file deliberately does not restate it.
 
 ## Batch image fetch
 
-`GET /api/v1/images?ids=1,2,3` — up to **100** ids, matching the ceiling the `GET_IMAGES_BY_IDS` bridge message
+`GET /api/v1/blocks/images?ids=1,2,3` — up to **100** ids, matching the ceiling the `GET_IMAGES_BY_IDS` bridge message
 already enforced.
 
 🔴 **Misses are reported by omission.** An id you may not see and an id that does not exist are both simply
@@ -131,22 +156,38 @@ that `publishGenerationOutputs` does not already serve.
 
 ## What a direct orchestrator call loses
 
+🔴 **This is the sharpest trap in the migration, because the wrong version compiles.** Substituting
+`app.orchestration` for the block workflow routes **type-checks and passes tests**; what it drops is
+server-side policy that no local check can miss.
+
 Submitting through the host went through civitai's own `blocks.submitWorkflow`,
 which added controls a direct call does not get:
 
 - **Spend caps.** A per-call `buzzBudget`, a per-viewer daily cap and a per-app
   daily cap, all enforced by civitai. A direct call has only the orchestrator's
   per-token budget, taken from the viewer's consent.
+- **The maturity clamp.** The block path applies the viewer's browsing-level
+  ceiling. A direct call does not.
 - **Attribution.** civitai tagged each workflow with the app and block it came
   from. The orchestrator records the token's OAuth client internally but not on
   the workflow, so per-app reporting needs an orchestrator change.
 
+✅ **The `/api/v1/blocks/workflows/*` routes keep all of it** — they delegate to the same procedures the
+bridge called. They are the replacement; `app.orchestration` is the raw orchestrator and is the escape hatch
+for an app that is genuinely its own principal.
+
+⚠ Same shape, one level subtler: `orchestration.queryWorkflows({ tags })` versus
+`POST /api/v1/blocks/workflows/query`. The **route forces the app tag server-side from the verified token**;
+the client takes `tags` from the caller. Swapping one for the other relocates a trust boundary into the
+iframe, and nothing about the call site looks different.
+
 ## Host UI still carried
 
 On `app.host`: `requestSignIn`, `download` (was `SAVE_IMAGE`),
 `openResourcePicker`, `openBuzzPurchase`, `openImageUpload`,
-`publishGenerationOutputs`, `resize`, `reportError`, `navigate` and
-`onVisibilityChange`. Consent is `app.requestGrants` (was `requestConsent`).
+`publishGenerationOutputs`, `resize`, **`autoResize`**, `reportError`, `navigate`
+and `onVisibilityChange`. Reach for `autoResize(element)` over bare `resize` —
+it wires the `ResizeObserver` for you and returns a stop function. Consent is `app.requestGrants` (was `requestConsent`).
 
 `publishGenerationOutputs` keeps `usePublishGenerationOutputs`'s wire exactly —
 `workflowId` plus `imageIndexes`, never a url — and drops one field. `title`
@@ -172,7 +213,11 @@ every output.
   (see *Behaviour* below) — pass a `signal` for the bound your app wants.
 
 Not carried: `OPEN_CHECKPOINT_PICKER` (use `openResourcePicker` with
-`resourceType: 'Checkpoint'`), `SET_USER_CHECKPOINT` (inert on a page).
+`resourceType: 'Checkpoint'`).
+
+⚠ **`SET_USER_CHECKPOINT` is carried after all**, as `POST /api/v1/blocks/user-checkpoint/set` — the route's
+own docstring calls itself its REST twin. Pass `versionId: null` to clear. It remains inert on a page surface,
+which is what the old "not carried" line was reaching for, but a model-slot block can persist through it.
 
 ## Behaviour
 
@@ -181,29 +226,58 @@ Not carried: `OPEN_CHECKPOINT_PICKER` (use `openResourcePicker` with
 | Host failures | free-text `error` on each reply | `BridgeError` with a `code` |
 | Request deadlines | per-message client timeouts | none; pass an `AbortSignal` |
 | A refused grant | rejected | resolves `false` |
-| React hooks | 38 | none — plain functions; bind them in your framework |
+| React hooks | 37 | none — plain functions; bind them in your framework |
 
 ## Waiting on the host
 
 For a block to use the API at all, civitai has to:
 
-1. Mint an OAuth access token for the app's own client (`appblk-<slug>`) and
+1. ~~Mint an OAuth access token for the app's own client (`appblk-<slug>`) and
    send it in `BLOCK_INIT` and `TOKEN_REFRESH`, instead of or beside the block
-   JWT. The auth hub currently bars `appblk-*` clients from its flows.
-
-   🔴 **That bar is deliberate security, not an oversight.** App-block clients exist only as the policy ceiling
-   for block-token minting; letting them drive the interactive authorization-code or device flows would mint a
-   real account bearer token, and an app-block owner could phish a viewer through the consent screen into
-   account takeover. The bar is enforced in four places, the load-bearing one being an empty `grants` list
-   written into the client row at approve time. **Removing it is re-opening a signed-off security finding, not
-   a config change.**
-
-   ⚠ There may be no need to. The block JWT is **not** limited to `/api/v1/blocks/*` by any route or claim check
-   — it works wherever a handler is wrapped, and `GET /api/v1/models/{id}` is already dual-auth today. Widening
-   what the existing block token is accepted on may reach the same destination without touching OAuth at all.
-   The question that decides between the two paths is whether a block must act **without an open host page**:
-   the block JWT lives ~15 minutes and is refreshed by the host page's session, so the block holds no refresh
-   credential of its own. If background work is required, OAuth becomes necessary rather than optional.
+   JWT.~~
+   ⚠ **BUILT, AND DARK.** The manifest gained an `auth` field
+   (`"block-token"` | `"oauth"`, default `"block-token"`) in the canonical schema; `block-oauth-scope.ts`
+   and `/api/v1/block-tokens` mint an OAuth app token when a manifest asks for it.
+
+   🔴 **But the mint is FLAG-GATED, and the failure is silent.** The call site is
+   `manifestWantsOauthToken(app.manifest) && env.APP_BLOCK_OAUTH_TOKENS_ENABLED`, and that env var is
+   `.default(false)`. **Wherever it is off, a manifest declaring `auth: "oauth"` silently receives the BLOCK
+   token**, and a general `/api/v1` call then fails as unauthorised. Since the SDK narrowed its token-kind
+   guard, that refusal carries the explanation: `app.site` appends the `auth: "oauth"` opt-in to the API's own
+   401/403 on any route outside `blocks/*`, and `app.orchestration` refuses before the request. `initialize()`
+   itself no longer rejects — being handed the block token is the DEFAULT here, not a failure, and rejecting it
+   also blocked the `consent_required` prompt below.
+
+   This file ships in the npm tarball and cannot be corrected after publication, so it deliberately does not
+   record whether the flag is on today — that would be frozen into every published version.
+
+   **What you can tell from inside the block, and what you cannot:**
+
+   | signal | means |
+   |---|---|
+   | `viewer === null` | an anonymous viewer. Definitive — no OAuth token is minted for one, whatever the flag. Gate on this; it is a frozen wire field |
+   | signed in, `token.kind === 'oauth'` | the mint succeeded, so the flag is on for you |
+   | signed in, `token.kind` absent or `'block'` | **not separable.** Could be the flag, or a scope this viewer has not granted. `kind` is optional and hosts predating hub-minted OAuth omit it |
+
+   The third row is the one to design around: it is the ordinary case today, and a block cannot tell those two
+   apart. What it CAN do is the thing the platform expects either way — treat the rejection as a prompt to
+   sign in or to request consent, rather than as a configuration question. `app.requestGrants()` reaches the
+   host's consent dialog on a block token, so that prompt is available from a block that holds one.
+
+   ✅ **The phishing finding is not re-opened**, which is why this could ship at all. The token is minted
+   **server-side** by the host (`mintOauthAppToken`) against scopes already approved for the app; the
+   `appblk-*` bar on the auth hub's **interactive** authorization-code and device flows stands untouched.
+   That bar was never the blocker for this path — driving the consent screen was.
+
+   ⚠ Still true, and still the cheaper route for most apps: the block JWT is **not** limited to
+   `/api/v1/blocks/*` by any route or claim check — it works wherever a handler is wrapped. Today that is
+   most `/api/v1/blocks/*` routes plus `/api/v1/models/{id}` — the 35 routes wrapped in `withBlockScope`.
+   🔴 **Not `/api/v1/me`**, which is an `AuthedEndpoint`; blocks use `/api/v1/blocks/me`. And four `blocks/*`
+   routes (`dev-token`, `submissions`, `submit-version`, `withdraw`) are not wrapped either. Widening what the existing block token is accepted on reaches most destinations without
+   OAuth at all. The question that decides between the two is whether a block must act **without an open host
+   page**: the block JWT lives ~15 minutes and is refreshed by the host page's session, so the block holds no
+   refresh credential of its own. If background work is required, OAuth becomes necessary rather than
+   optional.
 
 2. ~~Let a browser send `Authorization` to `/api/v1` from the app's registered origins.~~
    ✅ **DONE** — shipped 2026-09-22 (civitai#5028). `Authorization` is named explicitly in the allowed-headers
@@ -212,8 +286,13 @@ For a block to use the API at all, civitai has to:
 
 3. Add the `/api/v1` routes above as apps need them, and scope checks.
 
-   Partially done — shared storage, Buzz balance and batch images have landed; per-app-user storage
-   (`APP_STORAGE_*`) is the largest remaining gap at 5 of 7 fleet apps.
+   Largely done — shared storage, Buzz balance, batch images, collections, gated images, generation
+   resources, tips, the workflow routes and **per-app-user storage** (`APP_STORAGE_*`, civitai#5085) have all
+   landed.
+
+   What remains is not storage: `GET_BUZZ_ACCOUNTS` / `GET_BUZZ_TRANSACTIONS`, `GET_DAILY_COMPENSATION`,
+   and `GET_WILDCARD_PACK`. `OPEN_IMAGE_UPLOAD` now has an SDK host request (`app.host.openImageUpload`,
+   see *Host UI still carried*); what it has no twin of is a REST route, and it is not getting one.
 
    ⚠ **Scope checks are a separate item and are not a prerequisite for the routes above.** Every block scope
    these routes need already exists, is consent-described and is context-bound, so each route is scope-gated on

package/README.md

@@ -27,6 +27,15 @@ if (picked && (await app.requestGrants(['ai:write:budgeted']))) {
 }
 ```
 
+> 🔴 **If you are a BLOCK, do not copy the `app.orchestration` call above.** That
+> reaches the orchestrator directly and carries none of the controls the block
+> path applies — the per-call Buzz budget, the per-viewer and per-app daily caps,
+> the maturity clamp, and the `app-block:<appId>` attribution tag. Submit through
+> `POST /api/v1/blocks/workflows/submit` instead. The substitution type-checks and
+> passes tests, which is why it is worth saying here: the snippet above is written
+> for an app that is its own principal, not for a block. `BREAKING.md` §*What a
+> direct orchestrator call loses* has the detail.
+
 An app calls the Civitai API and the orchestrator as the viewer, with a token.
 Reading images, creating posts, running a workflow — all of it is an API call.
 A block additionally asks its host page to show the host's own UI.
@@ -51,9 +60,50 @@ Both give you:
 A block's `app` also has `host`, `viewer`, `context`, `settings`, `theme` and
 `onChange(listener)`. Outside a block they do not exist, and the types say so.
 
-> **Not yet end to end for blocks.** The host still mints a block-scoped JWT,
-> which `/api/v1` and the orchestrator do not accept; they take API keys and
-> OAuth tokens. Apps with one of those work today, from a browser or a server.
+A block opts in by declaring `auth: "oauth"` in its `block.manifest.json`. The
+host then hands it a real OAuth access token that `/api/v1`, the orchestrator
+and the MCP accept, and consent — including `requestGrants` — goes through the
+host's consent dialog.
+
+### When the token is the block-scoped one
+
+`initialize()` starts either way. A block-scoped token for a signed-in viewer is
+**not** an error in itself: the host's OAuth mint is flag-gated, so an opted-in
+block can legitimately receive the block token, and that token serves the
+`/api/v1/blocks/*` routes it was minted for, `GET /api/v1/models/{id}`, and
+`app.storage` — which an OAuth token cannot reach at all. What it does not reach
+is the rest of `/api/v1`, the orchestrator or the MCP. So the refusal sits at the
+surface, not at startup:
+
+| You call | Holding a block token, signed in |
+|---|---|
+| `app.storage.*` | Works. This is the token app storage requires |
+| `app.site` on `blocks/…` | Works. These are the routes the token was minted for |
+| `app.site.get('me')` and the rest of `/api/v1` | The API's own 401/403, with `auth: "oauth"` named in the message. `status` and `body` are untouched, so a caller can still branch on them |
+| `app.orchestration.*` | Rejects **before** the request with a `CivitaiError` naming `auth: "oauth"` — the orchestrator accepts no block token on any route, so there is nothing to learn from making the call |
+| `app.requestGrants(...)` | Works. Goes to the host's consent dialog, so a `consent_required` fallback can still prompt |
+
+Anonymous viewers are untouched: no OAuth token is minted for one whatever the
+manifest says, so the manifest is not their fix — `host.requestSignIn()` is. A
+host that predates the `kind` field sends none, and behaves as it always did.
+
+> ⚠ Two limits on that middle row, and neither is a bug to be tuned away.
+>
+> **The SDK does not know which `/api/v1` routes accept the token**, so its
+> message does not say. The route is a string this client never interprets, and
+> which routes are dual-auth is the server's to change without a release here —
+> so the message names `blocks/*` (the token's own mint namespace) and states
+> plainly that the rest is not known from here, leaving the advice conditional:
+> *if* this path needs an OAuth token, declare it. `GET /api/v1/models/{id}` is
+> in fact accepted — it is the one dual-auth route today — so a refusal there
+> gets the same conditional annotation; `BREAKING.md` records the route map as it
+> stood when this version was published, and the `models:read:self` binding that
+> route applies.
+>
+> **"Does not reach" is not always "refuses."** A *public* route such as
+> `/api/v1/images` ignores an unusable token and answers **anonymously** instead
+> of erroring. Nothing at the client seam tells that apart from a successful
+> authenticated read, so prefer the `blocks/*` twin.
 
 ## Signing in outside civitai.com
 

package/dist/app/index.d.ts

@@ -6,7 +6,16 @@ import { type GrantOptions, type Scope, type TokenOptions, type TokenSessionOpti
 import { type SiteClient } from '../site/index.js';
 import { type StorageClient } from '../storage/index.js';
 export interface AppClient {
-    /** The public Civitai REST API (`/api/v1`), as the viewer. */
+    /**
+     * The public Civitai REST API (`/api/v1`), as the viewer.
+     *
+     * Routes are addressed by path, so this client cannot know in advance which
+     * ones an app will call — nor which of them accept a block-scoped token. That
+     * set is the server's, and `BREAKING.md` records it as it stood when this
+     * version was published. What
+     * this client does instead is EXPLAIN a refusal it actually sees, naming the
+     * `auth: "oauth"` manifest opt-in where the token kind could be the reason.
+     */
     readonly site: SiteClient;
     /**
      * The viewer's own per-app key/value store.
@@ -17,7 +26,14 @@ export interface AppClient {
      * reading an empty result as "nothing stored".
      */
     readonly storage: StorageClient;
-    /** The orchestrator's workflows, as the viewer. */
+    /**
+     * The orchestrator's workflows, as the viewer.
+     *
+     * 🔴 The orchestrator accepts no block-scoped token on any route, so unlike
+     * {@link AppClient.site} this destination IS known ahead of the call: a block
+     * holding one is refused here up front, with the manifest fix, rather than
+     * spending a request to be told.
+     */
     readonly orchestration: OrchestrationClient;
     /** Asks for more scopes. `false` when they cannot be granted — a refusal is an answer. */
     requestGrants(scopes: readonly Scope[], opts?: GrantOptions): Promise<boolean>;

package/dist/app/index.js

@@ -1,7 +1,7 @@
-import { BridgeError } from '../core/errors.js';
+import { BridgeError, CivitaiError } from '../core/errors.js';
 import { getTransport } from '../core/get-transport.js';
 import { createHost, createHostSession } from '../host/index.js';
-import { createHttp } from '../http/index.js';
+import { ApiError, createHttp } from '../http/index.js';
 import { createOrchestrationClient, DEFAULT_ORCHESTRATION_URL, } from '../orchestration/index.js';
 import { createTokenSession, } from '../session/index.js';
 import { createSiteClient, DEFAULT_SITE_URL } from '../site/index.js';
@@ -14,8 +14,9 @@ export async function initialize(options = {}) {
     const transport = options.transport ?? getTransport();
     await ready(transport, options.timeoutMs ?? DEFAULT_INIT_TIMEOUT_MS, options.signal);
     const snapshot = () => transport.snapshot.get();
+    const holdsBlockTokenNow = holdsBlockToken(snapshot);
     return {
-        ...createAppClient(createHostSession(transport), options),
+        ...createAppClient(createHostSession(transport), options, holdsBlockTokenNow),
         host: createHost(transport),
         get viewer() {
             return snapshot().viewer;
@@ -32,19 +33,122 @@ export async function initialize(options = {}) {
         onChange: (listener) => transport.snapshot.subscribe(listener),
     };
 }
-function createAppClient(session, options) {
+/**
+ * 🔴 THE ONE PREDICATE, AND ITS EXACT SCOPE. A signed-in viewer whose token is
+ * the block JWT: the case where an OAuth access token exists in principle — the
+ * host mints one only for a signed-in viewer, and only when the manifest asks —
+ * but this block does not hold it.
+ *
+ * Both halves are load-bearing and neither may be widened:
+ *
+ * - `viewer === null` — an anonymous viewer gets no OAuth token whatever the
+ *   manifest says, so naming the manifest would send them at the wrong fix
+ *   (theirs is `host.requestSignIn()`). It is also a frozen wire field.
+ * - `kind !== 'block'` — `kind` is optional, and a host predating it sends none.
+ *   An absent `kind` is not evidence of a block token, so it must read as "not
+ *   this failure" and behave exactly as it did before `kind` existed.
+ *
+ * It is read live, not captured: the host rotates the token, and an opt-in block
+ * on a host whose flag is flipped on gets an `oauth` token on the next refresh.
+ */
+const holdsBlockToken = (snapshot) => () => snapshot().viewer !== null && snapshot().token.kind === 'block';
+/** The fix, spelled once, so every surface names the same thing. */
+const OAUTH_OPT_IN = 'declare `auth: "oauth"` in block.manifest.json';
+/**
+ * Paths the block-scoped token was minted for. A refusal there is not about the
+ * token's KIND — app storage, for one, is refused to an OAuth token and served
+ * only to a block token — so the manifest advice must not be attached to it.
+ *
+ * This is the token's own namespace prefix, not a copy of the server's route
+ * table: the 35-odd `withBlockScope` routes are the server's to change, and a
+ * list of them here would be the thing that drifts.
+ *
+ * 🔴 It is therefore deliberately NARROWER than the surface the token is
+ * accepted on, and that is not a bug to be widened away. Measured on civitai
+ * `main` (02e057b3, 2026-09-24): of the 35 route files wrapping `withBlockScope`,
+ * exactly one — `src/pages/api/v1/models/[id].ts` — sits outside `blocks/`. The
+ * cost of the gap is that a refusal there carries the annotation too, which is
+ * affordable because the advice is CONDITIONAL ("if this path needs an OAuth
+ * token") and because that route can genuinely refuse a block token anyway: it
+ * binds `models:read:self` to the one model the block renders beside. The
+ * alternative — naming the exceptions here — is the second copy this comment
+ * refuses, with nothing in this repo able to notice it going stale.
+ */
+const BLOCK_NAMESPACE = /^\/*blocks\//;
+function createAppClient(session, options, holdsBlockTokenNow = () => false) {
     const http = (baseUrl) => createHttp({ session, baseUrl, fetch: options.fetch });
     // One instance for both site-hosted surfaces: `storage`'s routes live under
     // the same base URL, so a `siteUrl` override redirects them together.
-    const siteHttp = http(options.siteUrl ?? DEFAULT_SITE_URL);
+    // Wrapped once, so `BLOCK_NAMESPACE` is the single place that decides where the
+    // diagnosis applies. `storage` needs no exemption of its own: every one of its
+    // routes is `blocks/app-storage/*`, which that namespace already excludes, and
+    // `test/storage/seam.test.ts` pins its `BASE` there textually.
+    const siteHttp = explainApiRefusal(http(options.siteUrl ?? DEFAULT_SITE_URL), holdsBlockTokenNow);
     return {
         site: createSiteClient(siteHttp),
         storage: createStorageClient(siteHttp),
-        orchestration: createOrchestrationClient(http(options.orchestrationUrl ?? DEFAULT_ORCHESTRATION_URL)),
+        orchestration: createOrchestrationClient(refuseBlockToken(http(options.orchestrationUrl ?? DEFAULT_ORCHESTRATION_URL), holdsBlockTokenNow)),
         requestGrants: (scopes, opts) => session.requestGrants(scopes, opts),
         getToken: (opts) => session.getToken(opts),
     };
 }
+/**
+ * The orchestrator, which accepts a block-scoped token on no route at all. That
+ * makes this the one destination the SDK can judge without making the call, so
+ * it refuses eagerly — before any request — rather than letting a 401 stand in
+ * for a configuration problem.
+ */
+function refuseBlockToken(http, holdsBlockTokenNow) {
+    return (method, path, opts) => holdsBlockTokenNow()
+        ? Promise.reject(new CivitaiError('The orchestrator does not accept a block-scoped token, and this block holds one. ' +
+            `To run workflows as the viewer, ${OAUTH_OPT_IN} so the host mints an OAuth ` +
+            'access token; the block token reaches the `blocks/*` API routes and app storage only.'))
+        : http(method, path, opts);
+}
+/**
+ * `/api/v1`, where the SDK cannot know the destination: {@link SiteClient} is
+ * `get`/`post`/`request` over a base URL, so the route is the caller's string
+ * and a route the API gains needs no release here. Predicting it is therefore
+ * out of the question — but EXPLAINING a refusal is not, and that keeps the
+ * diagnosis the old eager guard existed for at the call that actually needed it.
+ *
+ * ⚠ It cannot catch every case, and does not pretend to: a PUBLIC route such as
+ * `images` ignores an unusable token and answers ANONYMOUSLY instead of
+ * refusing. Nothing observable at this seam distinguishes that from a successful
+ * authenticated read, so a block that must act as the viewer should prefer the
+ * `blocks/*` twin.
+ *
+ * 🔴 And the message must not name the surface either way. Which `/api/v1`
+ * routes accept a block-scoped token is a fact about the server, held in the
+ * server's repo; asserting it from here would be a claim this package has no way
+ * to check and no way to correct once published. So the message states the one
+ * thing that IS the token's own (`blocks/*`, its mint namespace), says plainly
+ * that the rest is not known here, and leaves the advice conditional.
+ */
+function explainApiRefusal(http, holdsBlockTokenNow) {
+    return async (method, path, opts) => {
+        try {
+            return await http(method, path, opts);
+        }
+        catch (error) {
+            if (error instanceof ApiError &&
+                (error.status === 401 || error.status === 403) &&
+                !BLOCK_NAMESPACE.test(path) &&
+                holdsBlockTokenNow()) {
+                // Appended to the error already thrown, rather than replacing it: a
+                // caller branches on `status` and reads `body` (`ApiError` is public and
+                // documented for exactly that), and re-wrapping would drop the stack
+                // that says which call failed. The server's own sentence stays first.
+                error.message =
+                    `${error.message} — and this block holds a block-scoped token. The API accepts it on ` +
+                        `the \`blocks/*\` routes it was minted for; which others also accept it is the ` +
+                        `server's to say and is not known here. If \`${path}\` needs an OAuth access token, ` +
+                        `${OAUTH_OPT_IN}.`;
+            }
+            throw error;
+        }
+    };
+}
 function ready(transport, timeoutMs, signal) {
     if (transport.snapshot.get().ready)
         return Promise.resolve();

package/dist/core/handshake.d.ts

@@ -63,18 +63,22 @@ export interface BlockSettings {
     publisherSettings: Record<string, unknown>;
     userSettings: Record<string, unknown>;
 }
+/** `block` is accepted only by the host; `oauth` also by the API and orchestrator. Older hosts send none. */
+export type TokenKind = 'block' | 'oauth';
 /** A token on the wire; `expiresAt` is ISO-8601 until the transport parses it. */
 export interface WrappedToken {
     raw: string;
     scopes: string[];
     expiresAt: string;
     buzzBudget?: number;
+    kind?: TokenKind;
 }
 export interface BlockToken {
     raw: string;
     scopes: string[];
     expiresAt: Date;
     buzzBudget?: number;
+    kind?: TokenKind;
 }
 /**
  * The host still sends `blockId` and `appId`; they are build-time identity a

package/dist/core/transport.js

@@ -33,5 +33,6 @@ export function tokenFromWrapped(wrapped) {
         scopes: wrapped.scopes,
         expiresAt: new Date(wrapped.expiresAt),
         buzzBudget: wrapped.buzzBudget,
+        kind: wrapped.kind,
     };
 }

package/dist/index.d.ts

@@ -21,4 +21,4 @@ export type { BridgeErrorCode, BridgeFailureCode } from './core/errors.js';
 export { getTransport } from './core/get-transport.js';
 export type { DetectOptions } from './core/get-transport.js';
 export type { BlockSnapshot, BlockTransport } from './core/transport.js';
-export type { BlockCheckpointInfo, BlockContext, BlockSettings, BlockToken, ColorDomain, ModelSlotContext, ModelSlotId, PageSlotContext, PageSlotId, ShowcaseImage, Theme, UnknownSlotContext, ViewerInfo, } from './core/handshake.js';
+export type { BlockCheckpointInfo, BlockContext, BlockSettings, BlockToken, ColorDomain, ModelSlotContext, ModelSlotId, PageSlotContext, PageSlotId, ShowcaseImage, Theme, TokenKind, UnknownSlotContext, ViewerInfo, } from './core/handshake.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "The Civitai SDK: an app holds a token and calls the Civitai API and the orchestrator; a block asks its host only to show host UI.",
   "license": "MIT",
   "type": "module",