@civitai/sdk 0.2.0 → 0.3.0

package/BREAKING.md

@@ -15,14 +15,120 @@ messages have no destination yet.
 |---|---|---|
 | `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` | Takes one `imageId`, not a list |
+| `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_*` | — | No v1 route |
-| `GET_BUZZ_BALANCE`, `GET_BUZZ_ACCOUNTS`, `GET_BUZZ_TRANSACTIONS` | — | No v1 route |
-| `CREATE_POST_FROM_APP`, `PUBLISH_GENERATION_OUTPUTS` | — | No v1 route; both also showed a host confirmation per post, which an API call does not |
-| `SET_COLLECTION_FOLLOW` | — | No v1 route |
+| `SHARED_*` | `GET\|POST /api/v1/blocks/shared-storage/*` | **Route exists** — nine 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 |
+| `PUBLISH_GENERATION_OUTPUTS` | `app.host.publishGenerationOutputs` | Same reasoning: it raises host UI, so it stays on the bridge — **carried** rather than replaced |
+| `SET_COLLECTION_FOLLOW` | `POST /api/v1/blocks/collections/{id}/follow` | **Route exists** (scope `collections:write:self`). This row previously said "No v1 route"; that was wrong |
 | `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
+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
+capability rather than a migration gap.
+
+## 🔴 Before you call ANY block REST route: the scope-binding trap
+
+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.
+
+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`.
+
+**Workaround — pass a param the handler ignores:**
+
+```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.
+
+## Shared storage
+
+Nine 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 |
+|---|---|---|
+| `GET` | `/list` | `…shared:read` |
+| `GET` | `/item` | `…shared:read` |
+| `GET` | `/counts` | `…shared:read` |
+| `GET` | `/top` | `…shared:read` |
+| `POST` | `/append` · `/update` · `/vote` · `/unvote` · `/withdraw` · `/report` · `/increment` | `…shared:write` |
+
+### Who may read, and who may write
+
+These rules are enforced server-side and are **not** new policy — the REST routes call the same functions the
+bridge already called, so behaviour is identical on both transports.
+
+- **Anonymous viewers MAY read** — by design. `list`, `item`, `counts` and `top` skip the subject check
+  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.
+- **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.
+- **Tenancy is structural, not checked.** Every query interpolates a schema name derived from the **verified
+  token**, never from client input. An app cannot address another app's shared storage because it cannot name it.
+- **Rate limits are per-operation and per-namespace**, so one operation cannot starve another — browsing a feed
+  cannot exhaust a viewer's ability to delete their own rows.
+
+### 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.
+
+## 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
+already enforced.
+
+🔴 **Misses are reported by omission.** An id you may not see and an id that does not exist are both simply
+absent from `items`. That is deliberate: distinguishing them would leak whether a hidden image exists, which is
+the same non-disclosure `BlockGatedImage` already makes when it collapses its gated verdict. Do not infer
+deletion from absence.
+
+## Post creation stays on the bridge
+
+`CREATE_POST_FROM_APP` and `PUBLISH_GENERATION_OUTPUTS` are **not** getting a plain REST equivalent, and this is
+a decision rather than a backlog item.
+
+The host confirmation is not a dialog an app could reproduce. The server returns a preview; the write echoes
+`confirmedImageCount` **from that server preview**; and the host refuses the write on mismatch. A bare
+`POST /posts` would let a block draw its own confirmation inside an iframe at an opaque origin, with nothing
+binding what the viewer was shown to what gets written. Moving it would remove a consent control, not relocate
+one.
+
+If a REST surface is ever needed, the defensible shape is a route returning a short-lived server-signed publish
+intent that host chrome redeems after showing the preview — so the host stays in the loop by construction.
+
+`PUBLISH_GENERATION_OUTPUTS` is on `app.host` for exactly that reason: staying on the bridge is the decision,
+and `app.host` is where a bridge message lives. Its own version of the binding is the index — the block names a
+workflow and positions in it, and the host resolves the urls from the workflow it has verified the block owns,
+so there is no url for a frame to supply. `CREATE_POST_FROM_APP` is not carried; nothing in the fleet calls it
+that `publishGenerationOutputs` does not already serve.
+
 ## What a direct orchestrator call loses
 
 Submitting through the host went through civitai's own `blocks.submitWorkflow`,
@@ -38,12 +144,35 @@ which added controls a direct call does not get:
 ## Host UI still carried
 
 On `app.host`: `requestSignIn`, `download` (was `SAVE_IMAGE`),
-`openResourcePicker`, `openBuzzPurchase`, `resize`, `reportError`, `navigate`
-and `onVisibilityChange`. Consent is `app.requestGrants` (was `requestConsent`).
+`openResourcePicker`, `openBuzzPurchase`, `openImageUpload`,
+`publishGenerationOutputs`, `resize`, `reportError`, `navigate` and
+`onVisibilityChange`. Consent is `app.requestGrants` (was `requestConsent`).
+
+`publishGenerationOutputs` keeps `usePublishGenerationOutputs`'s wire exactly —
+`workflowId` plus `imageIndexes`, never a url — and drops one field. `title`
+reached the host's validator and was then discarded before the mutation, so
+sending it was a no-op end to end; a field that does nothing is not worth a
+version commitment. Two client-side refusals are new, and both are for
+something the host does silently: a missing `workflowId` is DROPPED with no
+reply at all, which without a client deadline is a hang; and an `imageIndexes`
+the host cannot read is STRIPPED, and a stripped `imageIndexes` means publish
+every output.
+
+`openImageUpload` differs in shape from `useImageUpload`, twice:
+
+- **There is one display mode, the asynchronous one.** The hook also had a
+  blocking variant whose return looked moderated; here a public upload always
+  resolves a `PendingImage` and the verdict comes from its `scan()`, so no
+  caller ends up holding an image that looks cleared without having asked. A
+  host predating `asyncScan` replies with a moderated image instead, and that
+  is read as the verdict it already is — `scan()` answers rather than waiting
+  on a push no such host will send.
+- **`scan()` has no deadline of its own.** The hook gave up after ten minutes
+  and called that a retryable error. Client deadlines left with all the others
+  (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),
-`OPEN_IMAGE_UPLOAD` (image-only; the site's upload takes media).
+`resourceType: 'Checkpoint'`), `SET_USER_CHECKPOINT` (inert on a page).
 
 ## Behaviour
 
@@ -61,9 +190,40 @@ 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
    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.
-2. Let a browser send `Authorization` to `/api/v1` from the app's registered
-   origins; the public routes answer with a wildcard that does not cover it.
+
+   🔴 **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.
+
+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
+   list, because a `*` wildcard does not cover it. Note `/api/v1/blocks/*` was never affected; it has carried
+   its own origin-allowlisted CORS since May.
+
 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.
+
+   ⚠ **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
+   arrival. What is missing is OAuth `TokenScope` enforcement on the *general* `/api/v1` surface: it is applied
+   by a tRPC middleware only, and the REST wrappers resolve a bearer token's scope onto the request and then
+   never read it back. Five routes check a scope by hand; everything else does not.
+
 And the orchestrator has to check that a workflow belongs to the caller before
 reading, changing or deleting it, which it does not today.
+
+⚠ **Sequencing note for anyone porting generation:** the `blocks.*` bridge path applies host-side checks that a
+direct orchestrator call does not. Porting an app's generation calls off the bridge is therefore not a
+transport-only change, and should be sequenced after the item above rather than before it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Civitai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -11,16 +11,20 @@ import { initialize } from '@civitai/sdk';
 const app = await initialize();
 
 const picked = await app.host.openResourcePicker({ resourceType: 'Checkpoint' });
-if (!picked) return;
-
-const { air } = await app.site.get<{ air: string }>(`model-versions/mini/${picked.versionId}`);
-
-if (!(await app.requestGrants(['ai:write:budgeted']))) return;
-
-const submitted = await app.orchestration.submitWorkflow({
-  steps: [{ $type: 'textToImage', input: { model: air, prompt: 'A lighthouse at dusk' } }],
-});
-const workflow = await app.orchestration.waitForWorkflow(submitted.id!);
+if (picked && (await app.requestGrants(['ai:write:budgeted']))) {
+  const { air } = await app.site.get<{ air: string }>(`model-versions/mini/${picked.versionId}`);
+
+  const submitted = await app.orchestration.submitWorkflow({
+    steps: [
+      {
+        $type: 'textToImage',
+        input: { model: air, prompt: 'A lighthouse at dusk', cfgScale: 7, seed: 1234 },
+      },
+    ],
+  });
+  const workflow = await app.orchestration.waitForWorkflow(submitted.id!);
+  render(workflow);
+}
 ```
 
 An app calls the Civitai API and the orchestrator as the viewer, with a token.
@@ -92,6 +96,50 @@ const images = await app.site.get('images', { query: { limit: 20, username: 'civ
 A `401` is retried once with a fresh token. Any other failure is an `ApiError`
 carrying `status`, the parsed `body`, and the server's own message.
 
+## App storage
+
+`app.storage` is the viewer's own key/value store, scoped to this app and this
+block instance. It needs the block token the host mints — an app holding an
+OAuth access token has no per-viewer app storage — and an anonymous viewer is
+refused, so gate on `app.viewer` rather than reading an empty page as "nothing
+stored".
+
+```ts
+await app.storage.set('draft:latest', { prompt, steps: 30 });
+const draft = await app.storage.get<Draft>('draft:latest'); // null when unset
+const { keys, nextCursor } = await app.storage.list({ prefix: 'draft:' });
+const quota = await app.storage.getQuota();
+```
+
+Three properties the surface is built around:
+
+- **Every failure rejects.** Nothing here resolves to mean "not written", and
+  nothing resolves to mean "could not read". A malformed success throws a
+  `CivitaiError`; a refusal is an `ApiError` carrying `status`. A caller that
+  must not act on a partial view branches on the rejection, never on an empty
+  result.
+- **`nextCursor` is present exactly when there may be more rows**, and is passed
+  through untouched. Its absence is your proof a scan completed. Page it
+  yourself, with a bound — the client adds no iterator, because the truncation
+  policy is the caller's to choose.
+- **`set`'s `sizeBytes` is the wire unit; `getQuota`'s `usedBytes` is the stored
+  unit.** They are not a fixed multiple — measured, a numeric-heavy value stores
+  up to 44.4x its wire size — so summing `sizeBytes` under-counts your quota.
+  `getQuota()` is the authority, and it reports neither the key-length cap nor
+  the per-value cap.
+
+A write refused for size or quota arrives as `413`, whichever ceiling fired — the
+server names which one only in prose, so test the status, not the message:
+
+```ts
+try {
+  await app.storage.set('draft:latest', huge);
+} catch (error) {
+  if (error instanceof ApiError && error.status === 413) askTheUserToFreeSpace();
+  else throw error;
+}
+```
+
 ## The orchestrator
 
 Steps are typed by `$type`: `input` is checked against that step's own input,
@@ -144,12 +192,103 @@ wider scope — and refuses without one.
 | `download({ url, filename })` | Saves to the viewer's device — a sandboxed frame cannot |
 | `openResourcePicker({ resourceType })` | civitai's own picker; resolves the one pick, or `null` |
 | `openBuzzPurchase({ suggestedAmount })` | The purchase flow; resolves `{ purchased }` |
+| `openImageUpload()` | The upload modal; resolves a `PendingImage`, or `null` |
+| `openImageUpload({ purpose: 'generationSource' })` | The same modal for a private img2img source; resolves `{ url, width, height }` |
+| `publishGenerationOutputs({ workflowId, imageIndexes })` | Publishes your own workflow's outputs, behind the host's confirmation; resolves the new image ids |
 
 Host failures reject with a `BridgeError` carrying a `code` (`forbidden`,
 `unauthenticated`, `rate-limited`, …). Timeouts are the host's to set; pass a
 `signal` to cancel. `ApiError` and `BridgeError` both extend `CivitaiError`, so
 one `catch` can tell a refusal from a bug.
 
+### Uploading an image
+
+The host owns the upload: it opens its own modal, takes the file through the
+viewer's session and hands back what it stored. The frame never sees the bytes.
+
+A **public** image is moderated *after* it is stored, so `openImageUpload()`
+resolves as soon as the image exists and the verdict comes from `scan()`:
+
+```ts
+const app = await initialize();
+
+const image = await app.host.openImageUpload();
+if (image) {
+  showTheAuthorTheirOwnPreview(image.url);
+
+  const verdict = await image.scan({ signal: AbortSignal.timeout(600_000) });
+  if (verdict.status === 'scanned') publish(verdict.image);
+  else if (verdict.status === 'blocked') tellThemWhy(verdict.reason);
+  else offerToTryAgain(verdict.message);
+}
+```
+
+🔴 `scanned` is the only verdict that clears the image for anyone but its
+author. `blocked` is the host refusing it; `error` is the host not answering —
+neither is a pass, so branch on `scanned`, never on "not blocked". `scan()`
+waits as long as the host takes and this package imposes no deadline of its
+own, which is why the snippet passes a signal.
+
+A **generation source** is private and unscanned here — the orchestrator scans
+it when the workflow runs — so it needs no verdict, and comes back as a url and
+the image's real dimensions. A step takes the two separately: `sourceImage` is
+the url, and the dimensions are the step's own:
+
+```ts
+const app = await initialize();
+
+const source = await app.host.openImageUpload({ purpose: 'generationSource' });
+if (source) {
+  await app.orchestration.submitWorkflow({
+    steps: [
+      {
+        $type: 'textToImage',
+        input: {
+          model: 'urn:air:sdxl:checkpoint:civitai:101055@128078',
+          prompt: 'the same lighthouse, at dawn',
+          cfgScale: 7,
+          seed: 1234,
+          sourceImage: source.url,
+          width: source.width,
+          height: source.height,
+        },
+      },
+    ],
+  });
+}
+```
+
+### Publishing a generation
+
+Outputs of a workflow your app ran can become public images, and the host asks
+the viewer first. Needs `ai:write:budgeted` — an app trusted to spend their
+Buzz on a generation is trusted to publish what it produced.
+
+```ts
+const app = await initialize();
+
+const imageIds = await app.host.publishGenerationOutputs(
+  { workflowId, imageIndexes: [0, 2] },
+  { signal: AbortSignal.timeout(600_000) },
+);
+```
+
+🔴 **Outputs are named by index, never by url.** The host re-derives that this
+viewer and this app own the workflow and resolves the urls itself — a frame at
+an opaque origin naming its own blob to publish would be a different feature
+entirely. Omit `imageIndexes` to publish every output; an unusable list is
+refused here rather than sent, because the host reads one it cannot parse as
+*publish everything*.
+
+The host holds its confirmation in front of a person, so this waits as long as
+they take and nothing here cuts it short — pass a `signal`, as above, for the
+bound your app wants. A viewer who declines rejects the call.
+
+⚠ Publishing is best-effort per image: an output that fails is skipped rather
+than failing the call, so `imageIds` can be **shorter** than what you selected
+and nothing says which index dropped. Compare lengths; do not pair ids to
+indexes.
+
 ## Parent origins
 
 Messages are accepted only from an allowlisted parent origin. The allowlist is
@@ -167,6 +306,24 @@ entry.
 `@civitai/sdk/testing` has `createFakeTransport()`: pass it as
 `initialize({ transport })` and script the host's answers.
 
+There is no published fake for app storage, on purpose. The seam is `fetch`, so
+pass your own `fetch` to `initialize({ token, fetch })` and the client's URLs,
+bodies, statuses and date revival are all real — which a fake replacing the
+`storage` client would not be. Two things to get right in one you write:
+
+- **Make the page size small** (2 or 3, not the server's 50). A page that holds
+  every fixture is exactly how a caller that never forwards `cursor` passes a
+  whole green suite.
+- **Put `updatedAt` on the wire as an ISO string**, as `res.json()` does. Hand
+  the client a `Date` and its revival becomes unobservable, since
+  `new Date(aDate)` is a `Date`.
+
+This SDK's own suite keeps one at
+[`test/support/fake-app-storage.ts`](./test/support/fake-app-storage.ts); it is
+not exported, because four of the five fleet apps that store per-viewer state
+need knobs it does not have (injected latency, prefix-targeted refusals, quota
+overrides, a cursor it ignores, a read that never settles). Copy it if it helps.
+
 ## Checks
 
 - `npm run api` regenerates [`api/public-api.md`](./api/public-api.md) from the

package/dist/app/index.d.ts

@@ -4,9 +4,19 @@ import { type Host } from '../host/index.js';
 import { type OrchestrationClient } from '../orchestration/index.js';
 import { type GrantOptions, type Scope, type TokenOptions, type TokenSessionOptions } from '../session/index.js';
 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. */
     readonly site: SiteClient;
+    /**
+     * The viewer's own per-app key/value store.
+     *
+     * 🔴 Requires the block token the host mints: an app that authenticated with
+     * an OAuth access token has no per-viewer app storage, and every call here is
+     * refused. An anonymous viewer is refused too — gate on `viewer` rather than
+     * reading an empty result as "nothing stored".
+     */
+    readonly storage: StorageClient;
     /** The orchestrator's workflows, as the viewer. */
     readonly orchestration: OrchestrationClient;
     /** Asks for more scopes. `false` when they cannot be granted — a refusal is an answer. */

package/dist/app/index.js

@@ -5,6 +5,7 @@ import { 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';
+import { createStorageClient } from '../storage/index.js';
 /** Long enough for a slow host page; short enough that a block opened on its own says so. */
 const DEFAULT_INIT_TIMEOUT_MS = 10_000;
 export async function initialize(options = {}) {
@@ -33,8 +34,12 @@ export async function initialize(options = {}) {
 }
 function createAppClient(session, options) {
     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);
     return {
-        site: createSiteClient(http(options.siteUrl ?? DEFAULT_SITE_URL)),
+        site: createSiteClient(siteHttp),
+        storage: createStorageClient(siteHttp),
         orchestration: createOrchestrationClient(http(options.orchestrationUrl ?? DEFAULT_ORCHESTRATION_URL)),
         requestGrants: (scopes, opts) => session.requestGrants(scopes, opts),
         getToken: (opts) => session.getToken(opts),

package/dist/core/transports/iframe-transport.js

@@ -27,7 +27,9 @@ function fromLegacyReply(reply) {
  */
 const LEGACY_REPLIES = {
     OPEN_BUZZ_PURCHASE: 'BUZZ_PURCHASE_RESULT',
+    OPEN_IMAGE_UPLOAD: 'IMAGE_UPLOAD_RESULT',
     OPEN_RESOURCE_PICKER: 'RESOURCE_PICKER_RESULT',
+    PUBLISH_GENERATION_OUTPUTS: 'PUBLISH_RESULT',
     REQUEST_TOKEN: 'TOKEN_REFRESH_RESPONSE',
     SAVE_IMAGE: 'SAVE_IMAGE_RESULT',
 };

package/dist/host/index.d.ts

@@ -1,10 +1,28 @@
 import { type BlockTransport } from '../core/transport.js';
 import type { Session } from '../session/index.js';
-import type { DownloadRequest, PickedResource, ResourcePickerType } from './protocol.js';
-export type { ConsentRefusal, DownloadRequest, PickedResource, ResourcePickerType, } from './protocol.js';
+import type { DownloadRequest, ImageScanResult, PickedResource, ResourcePickerType, SourceImage } from './protocol.js';
+export type { ConsentRefusal, DownloadRequest, ImageScanResult, PickedResource, ResourcePickerType, SourceImage, UploadedImage, } from './protocol.js';
 export interface HostCallOptions {
     signal?: AbortSignal;
 }
+/**
+ * An upload the host has stored but not yet finished moderating. The image
+ * exists and its author can see it; nobody else may until `scan()` answers.
+ */
+export interface PendingImage {
+    imageId: number;
+    /** The author's own preview. Not for any other viewer until `scan()` says `scanned`. */
+    url: string;
+    /**
+     * The host's verdict on this upload. Resolves once the host reaches one and
+     * returns the same answer to every later call, so it is safe to re-read.
+     *
+     * 🔴 It waits as long as the host takes — the host is what bounds the scan,
+     * and this package sets no deadline of its own. Pass a `signal` if your app
+     * needs one; aborting gives up on the verdict, it does not decide it.
+     */
+    scan(opts?: HostCallOptions): Promise<ImageScanResult>;
+}
 /** Asking the host page to show its own UI. Data goes over the API, not here. */
 export interface Host {
     /** Resizes the frame, clamped to the manifest's bounds. */
@@ -41,6 +59,48 @@ export interface Host {
     }, opts?: HostCallOptions): Promise<{
         purchased: boolean;
     }>;
+    /**
+     * civitai's own upload modal. The bytes go through the host's session, never
+     * through the frame, and `null` means the viewer closed it without uploading.
+     *
+     * `purpose: 'generationSource'` uploads a PRIVATE img2img source: unscanned
+     * here, scanned by the orchestrator when the workflow runs.
+     */
+    openImageUpload(args: {
+        purpose: 'generationSource';
+    }, opts?: HostCallOptions): Promise<SourceImage | null>;
+    /**
+     * A PUBLIC image. The host stores it and moderates it afterwards, so this
+     * resolves with a {@link PendingImage} — the image, plus the `scan()` that
+     * answers whether anyone but its author may see it.
+     */
+    openImageUpload(args?: {
+        purpose?: 'display';
+    }, opts?: HostCallOptions): Promise<PendingImage | null>;
+    /**
+     * Publishes outputs of ONE of this app's own workflows as public images, and
+     * resolves with the ids of the rows the host created. Needs
+     * `ai:write:budgeted`: an app trusted to spend the viewer's Buzz on a
+     * generation is trusted to publish what that generation produced.
+     *
+     * 🔴 Outputs are named by INDEX into the workflow, never by url. The host
+     * re-derives that this viewer and this app own `workflowId`, then resolves
+     * the urls itself — which is the whole guarantee, because a frame at an
+     * opaque origin naming its own blob to publish would be a different feature.
+     *
+     * The host shows the viewer a confirmation first and answers only when they
+     * act, so this waits on a person. Nothing here bounds that wait; pass a
+     * `signal` for the bound your app wants.
+     *
+     * ⚠ Publishing is best-effort per image. An output that fails to publish is
+     * skipped rather than failing the call, so `imageIds` can be SHORTER than
+     * the selection and nothing says which index dropped. Compare lengths rather
+     * than pairing ids to indexes.
+     */
+    publishGenerationOutputs(args: {
+        workflowId: string;
+        imageIndexes?: number[];
+    }, opts?: HostCallOptions): Promise<number[]>;
 }
 export declare function createHost(transport: BlockTransport): Host;
 /** The token the host minted for this block, kept current as the host rotates it. */

package/dist/host/index.js

@@ -1,3 +1,4 @@
+import { BridgeError } from '../core/errors.js';
 import { createCaller, createListener, createNotifier } from '../core/messaging.js';
 import { tokenFromWrapped } from '../core/transport.js';
 const call = createCaller();
@@ -44,7 +45,202 @@ export function createHost(transport) {
             const { purchased } = await call('OPEN_BUZZ_PURCHASE', args, { ...opts, transport });
             return { purchased };
         },
+        async publishGenerationOutputs(args, opts = {}) {
+            const { imageIds } = await call('PUBLISH_GENERATION_OUTPUTS', publishParams(args), {
+                ...opts,
+                transport,
+            });
+            // The host spells "no failure" as `error: ''`, which the transport reads
+            // as a success — so a reply carrying neither the ids nor a message gets
+            // this far, and returning it would resolve `undefined` from a promise
+            // that says `number[]`. A caller reading that as "nothing published"
+            // would be guessing: images may well have been.
+            if (!Array.isArray(imageIds) || !imageIds.every((id) => typeof id === 'number')) {
+                throw new BridgeError('malformed', 'PUBLISH_GENERATION_OUTPUTS', 'PUBLISH_GENERATION_OUTPUTS reply carried no image ids. Whether anything ' +
+                    'was published is unknown; read the workflow back rather than assuming.');
+            }
+            return imageIds;
+        },
+        // Cast scoped to this one member: the interface overloads it so each
+        // `purpose` names its own return, which one implementation signature cannot
+        // express. Every other member here is still checked against `Host`.
+        openImageUpload: ((args = {}, opts = {}) => args.purpose === 'generationSource'
+            ? openSourceUpload(transport, opts)
+            : openDisplayUpload(transport, opts)),
+    };
+}
+/**
+ * Everything that goes on the `PUBLISH_GENERATION_OUTPUTS` wire, built field by
+ * field.
+ *
+ * 🔴 NAMED FIELDS, NEVER A SPREAD. The message's guarantee is that a block
+ * cannot say WHICH bytes to publish — it names a workflow it owns and indexes
+ * into it, and the host resolves the urls. Spreading the caller's object here
+ * would put whatever else it carries on the wire, so the one line that makes
+ * `url` unreachable is the two assignments below being the only ones.
+ *
+ * The two refusals are hangs and escalations the host cannot save us from:
+ *
+ * - A missing `workflowId` is DROPPED by the host with no reply at all, and
+ *   nothing in this package bounds a request, so the call would simply never
+ *   settle.
+ * - An `imageIndexes` the host cannot read — empty, or holding anything that is
+ *   not a whole index — is stripped, and a stripped `imageIndexes` means
+ *   PUBLISH EVERY OUTPUT. "Publish these two" quietly becoming "publish all
+ *   twenty" is not a failure a viewer can take back.
+ */
+function publishParams(args) {
+    const { workflowId, imageIndexes } = args;
+    if (typeof workflowId !== 'string' || workflowId === '') {
+        throw new BridgeError('invalid', 'PUBLISH_GENERATION_OUTPUTS', 'publishGenerationOutputs needs the workflowId of a workflow this app ran.');
+    }
+    if (imageIndexes === undefined)
+        return { workflowId };
+    if (!Array.isArray(imageIndexes) ||
+        imageIndexes.length === 0 ||
+        !imageIndexes.every((index) => Number.isInteger(index) && index >= 0)) {
+        throw new BridgeError('invalid', 'PUBLISH_GENERATION_OUTPUTS', 'imageIndexes must be a non-empty list of output indexes. The host reads an ' +
+            'unusable list as "publish every output", so this refuses rather than publish ' +
+            'more than you asked for.');
+    }
+    return { workflowId, imageIndexes: [...imageIndexes] };
+}
+async function openSourceUpload(transport, opts) {
+    const { selected } = await call('OPEN_IMAGE_UPLOAD', { purpose: 'generationSource' }, { ...opts, transport });
+    return asSourceImage(selected);
+}
+/**
+ * The public-image upload. Two things make it more than one `call`:
+ *
+ * The verdict is a PUSH the host sends on its own schedule, so the listener has
+ * to be attached BEFORE the request goes out — a scan that finishes quickly can
+ * land before the reply is read, and a verdict nobody heard is a verdict lost.
+ *
+ * And a host that does not know `asyncScan` answers the OLD way: it blocks its
+ * modal on the scan and replies with a moderated image. That reply is a verdict
+ * already reached, so it is stored as one; a caller written against `scan()`
+ * gets its answer rather than waiting on a push no such host will ever send.
+ */
+function openDisplayUpload(transport, opts) {
+    let verdict;
+    let imageId;
+    /** Verdicts that arrived before the reply named our `imageId`, keyed by theirs. */
+    const early = new Map();
+    const waiters = new Set();
+    const settle = (result) => {
+        verdict = result;
+        off();
+        for (const waiter of [...waiters])
+            waiter(result);
+        waiters.clear();
+    };
+    const off = on(transport, 'IMAGE_SCAN_RESOLVED', (push) => {
+        if (verdict !== undefined)
+            return; // the host emits once; honour the first
+        if (typeof push?.imageId !== 'number')
+            return;
+        if (imageId === undefined)
+            early.set(push.imageId, asScanResult(push.result));
+        else if (push.imageId === imageId)
+            settle(asScanResult(push.result));
+    });
+    const handle = (id, url) => {
+        imageId = id;
+        const buffered = early.get(id);
+        if (buffered !== undefined && verdict === undefined)
+            settle(buffered);
+        return {
+            imageId: id,
+            url,
+            scan: ({ signal } = {}) => new Promise((resolve, reject) => {
+                if (verdict !== undefined)
+                    return resolve(verdict);
+                if (signal?.aborted)
+                    return reject(signal.reason);
+                const deliver = (result) => {
+                    signal?.removeEventListener('abort', onAbort);
+                    resolve(result);
+                };
+                const onAbort = () => {
+                    waiters.delete(deliver);
+                    reject(signal.reason);
+                };
+                waiters.add(deliver);
+                signal?.addEventListener('abort', onAbort, { once: true });
+            }),
+        };
     };
+    return (async () => {
+        let selected;
+        try {
+            ({ selected } = await call('OPEN_IMAGE_UPLOAD', { asyncScan: true }, { ...opts, transport }));
+        }
+        catch (error) {
+            off();
+            throw error;
+        }
+        const pending = asPendingUpload(selected);
+        if (pending)
+            return handle(pending.imageId, pending.url);
+        // A host that ignored `asyncScan` and scanned before replying.
+        const moderated = asUploadedImage(selected);
+        if (moderated) {
+            const image = handle(moderated.imageId, moderated.url);
+            if (verdict === undefined)
+                settle({ status: 'scanned', image: moderated });
+            return image;
+        }
+        // Dismissed, or a reply this flow cannot read as an image. Never invent a
+        // handle: its `scan()` would have nothing to answer with.
+        off();
+        return null;
+    })();
+}
+function asSourceImage(value) {
+    const v = value;
+    return typeof v?.url === 'string' && typeof v.width === 'number' && typeof v.height === 'number'
+        ? { url: v.url, width: v.width, height: v.height }
+        : null;
+}
+function asPendingUpload(value) {
+    const v = value;
+    return v?.status === 'pending' && typeof v.imageId === 'number' && typeof v.url === 'string'
+        ? { imageId: v.imageId, url: v.url }
+        : null;
+}
+function asUploadedImage(value) {
+    const v = value;
+    return typeof v?.imageId === 'number' &&
+        typeof v.url === 'string' &&
+        typeof v.nsfwLevel === 'number' &&
+        typeof v.contentRating === 'string'
+        ? {
+            imageId: v.imageId,
+            url: v.url,
+            nsfwLevel: v.nsfwLevel,
+            contentRating: v.contentRating,
+        }
+        : null;
+}
+/**
+ * 🔴 The only way into {@link ImageScanResult}, and it fails CLOSED in both
+ * directions: `blocked` is kept exactly as the host sent it, and nothing
+ * becomes `scanned` without a readable image to back the claim. A verdict this
+ * cannot read is an `error` — which is not a pass — rather than dropped, since
+ * a dropped verdict leaves `scan()` waiting on a push the host has already sent.
+ */
+function asScanResult(value) {
+    const v = value;
+    if (v?.status === 'blocked') {
+        return { status: 'blocked', ...(typeof v.reason === 'string' ? { reason: v.reason } : {}) };
+    }
+    if (v?.status === 'scanned') {
+        const image = asUploadedImage(v.image);
+        return image
+            ? { status: 'scanned', image }
+            : { status: 'error', message: 'the host reported a scan with no image' };
+    }
+    return { status: 'error', ...(typeof v?.message === 'string' ? { message: v.message } : {}) };
 }
 /** The token the host minted for this block, kept current as the host rotates it. */
 export function createHostSession(transport) {

package/dist/host/protocol.d.ts

@@ -21,6 +21,50 @@ export interface DownloadRequest {
 }
 /** Why consent can never be granted in this environment. */
 export type ConsentRefusal = 'ungrantable';
+/**
+ * An uploaded image the host has finished moderating. `nsfwLevel` and
+ * `contentRating` are the host's verdict, so a block renders by them rather
+ * than judging the image itself.
+ */
+export interface UploadedImage {
+    imageId: number;
+    /** The host's browsing-level bitmask for this image. */
+    nsfwLevel: number;
+    contentRating: 'g' | 'pg' | 'pg13' | 'r' | 'x';
+    url: string;
+}
+/**
+ * A private img2img source. The host stores it UNSCANNED — the orchestrator
+ * scans it when the workflow runs — so it carries no moderation verdict and
+ * belongs in a generation step, not on a surface other viewers can see.
+ *
+ * A step takes the url and the dimensions separately: `sourceImage` is the url,
+ * and `width`/`height` are the step's own.
+ */
+export interface SourceImage {
+    url: string;
+    width: number;
+    height: number;
+}
+/**
+ * The host's moderation verdict on an upload, reached after the upload itself
+ * has already resolved.
+ *
+ * 🔴 `scanned` is the ONLY value that clears an image for a surface other
+ * viewers can see. `blocked` is the host refusing it, and `error` is the host
+ * declining to answer — neither is a pass, and a caller that reads "not
+ * blocked" as clean has inverted the guarantee.
+ */
+export type ImageScanResult = {
+    status: 'scanned';
+    image: UploadedImage;
+} | {
+    status: 'blocked';
+    reason?: string;
+} | {
+    status: 'error';
+    message?: string;
+};
 export type HostRequests = {
     SAVE_IMAGE: {
         params: DownloadRequest;
@@ -46,6 +90,50 @@ export type HostRequests = {
             newBalance?: number;
         };
     };
+    /**
+     * The host's own upload modal; the frame never handles the bytes.
+     *
+     * `purpose` is sent ONLY for `'generationSource'`. The host normalises an
+     * absent — or unrecognised — purpose to `'display'`, so omitting it keeps the
+     * display call byte-identical to the wire hosts have answered all along.
+     *
+     * `asyncScan` makes the host resolve on persist and stream the verdict as an
+     * `IMAGE_SCAN_RESOLVED` push. The host ignores it for `'generationSource'`,
+     * which has no scan at all.
+     */
+    OPEN_IMAGE_UPLOAD: {
+        params: {
+            purpose?: 'generationSource';
+            asyncScan?: true;
+        };
+        result: {
+            selected?: UploadedImage | SourceImage | {
+                status: 'pending';
+                imageId: number;
+                url: string;
+            };
+        };
+    };
+    /**
+     * Publish outputs of ONE of this app's own workflows as scanned public
+     * images, behind the host's own confirmation.
+     *
+     * 🔴 `imageIndexes` INDEX the workflow's outputs, and there is no url on this
+     * message — there must never be one. The host re-derives ownership of
+     * `workflowId` from the token and resolves the orchestrator urls itself,
+     * which is what stops a frame at an opaque origin from naming an arbitrary
+     * blob to publish. A shape that accepted a url would be a different, weaker
+     * feature wearing this one's name.
+     */
+    PUBLISH_GENERATION_OUTPUTS: {
+        params: {
+            workflowId: string;
+            imageIndexes?: number[];
+        };
+        result: {
+            imageIds: number[];
+        };
+    };
     REQUEST_TOKEN: {
         params: {
             blockInstanceId: string;
@@ -83,4 +171,17 @@ export type HostPushes = {
         reason: ConsentRefusal;
         scopes: string[];
     };
+    /**
+     * The verdict on an `asyncScan` upload, once per upload the host accepted.
+     * It arrives long after that upload's own reply, which is why it is a push.
+     *
+     * `requestId` echoes the `OPEN_IMAGE_UPLOAD` it belongs to, but the transport
+     * owns request ids and hands none out, so this client correlates on
+     * `imageId` — the id it was given in the reply.
+     */
+    IMAGE_SCAN_RESOLVED: {
+        requestId: string;
+        imageId: number;
+        result: ImageScanResult;
+    };
 };

package/dist/index.d.ts

@@ -9,10 +9,11 @@ export type { SignIn, SignInOptions } from './sign-in/index.js';
 export { SCOPES } from './session/index.js';
 export type { GrantOptions, Scope, TokenOptions, TokenSource } from './session/index.js';
 export type { SiteClient } from './site/index.js';
+export type { StorageCallOptions, StorageClient, StorageKeyEntry, StorageListQuery, StorageListResult, StorageQuota, } from './storage/index.js';
 export { isTerminal } from './orchestration/index.js';
 export type { OrchestrationClient, Step, StepTemplate, WaitOptions, Workflow, WorkflowPage, WorkflowQuery, WorkflowStatus, WorkflowTemplate, } from './orchestration/index.js';
 export { createHost } from './host/index.js';
-export type { ConsentRefusal, DownloadRequest, Host, HostCallOptions, PickedResource, ResourcePickerType, } from './host/index.js';
+export type { ConsentRefusal, DownloadRequest, Host, HostCallOptions, ImageScanResult, PendingImage, PickedResource, ResourcePickerType, SourceImage, UploadedImage, } from './host/index.js';
 export { ApiError } from './http/index.js';
 export type { Query, QueryValue, RequestOptions } from './http/index.js';
 export { BridgeError, CivitaiError } from './core/errors.js';

package/dist/storage/index.d.ts

@@ -0,0 +1,91 @@
+import type { Http } from '../http/index.js';
+export interface StorageCallOptions {
+    signal?: AbortSignal;
+}
+/** One row of a key listing. Values are not returned — `get(key)` fetches them. */
+export interface StorageKeyEntry {
+    key: string;
+    /**
+     * When this key was last written. The wire carries an ISO string; it is
+     * revived here, once, so a caller can do date arithmetic without knowing the
+     * transport.
+     */
+    updatedAt: Date;
+}
+export interface StorageListResult {
+    keys: StorageKeyEntry[];
+    /**
+     * 🔴 PRESENT EXACTLY WHEN THERE MAY BE MORE ROWS, and passed through
+     * untouched. The server sets it iff the page it returned was full. A caller
+     * uses its ABSENCE as proof a scan completed, and for one caller that is a
+     * money decision. Never default it, never normalise it, never re-derive it
+     * from `keys.length`.
+     */
+    nextCursor?: string;
+}
+export interface StorageListQuery {
+    /** Narrows to keys starting with this. Escaped server-side against LIKE wildcards. */
+    prefix?: string;
+    /** The server bounds this and applies its own default; this client sends none. */
+    limit?: number;
+    /** An opaque `nextCursor` from a previous page. */
+    cursor?: string;
+}
+export interface StorageQuota {
+    /**
+     * 🔴 THE STORED UNIT — Postgres `octet_length(value::text)` over JSONB, the
+     * unit both ceilings are enforced in, and the authority for "how close am I
+     * to my cap". It is NOT {@link StorageClient.set}'s `sizeBytes`: measured, a
+     * numeric-heavy payload stores up to 44.4x its wire size.
+     */
+    usedBytes: number;
+    rowCount: number;
+    /** Render this, never a compiled-in figure — the ceiling can move. */
+    limitBytes: number;
+    /** Usually the BINDING one: many small rows exhaust this long before bytes. */
+    limitRows: number;
+}
+/**
+ * The viewer's own per-(app, block instance) key/value store.
+ *
+ * 🔴 Requires the block token the host mints. An app that authenticated with an
+ * OAuth access token instead has no per-viewer app storage — every call is
+ * refused.
+ *
+ * 🔴 EVERY FAILURE REJECTS. There is no path here that resolves to mean "not
+ * written", and none that resolves to mean "could not read". A caller that must
+ * not act on a partial view branches on the rejection, never on an empty result.
+ */
+export interface StorageClient {
+    /** The value, or `null` when the key is unset. Rejects on any refusal. */
+    get<T = unknown>(key: string, opts?: StorageCallOptions): Promise<T | null>;
+    /**
+     * Upsert one key. Resolves only when the write landed.
+     *
+     * `sizeBytes` is the WIRE unit — the byte length of the serialised value — so
+     * it predicts the per-value cap and nothing else. 🔴 Do not sum it to track
+     * quota; call {@link StorageClient.getQuota}. See {@link StorageQuota.usedBytes}.
+     *
+     * A value of `undefined` is stored as `null`: it does not survive JSON, and
+     * the server writes `null` for an absent value rather than refusing.
+     */
+    set<T = unknown>(key: string, value: T, opts?: StorageCallOptions): Promise<{
+        ok: true;
+        sizeBytes: number;
+    }>;
+    /** Idempotent. `deleted: false` means the key was already absent — a success. */
+    delete(key: string, opts?: StorageCallOptions): Promise<{
+        ok: true;
+        deleted: boolean;
+    }>;
+    /** One page of keys, ordered by key ascending. Values are not returned. */
+    list(query?: StorageListQuery, opts?: StorageCallOptions): Promise<StorageListResult>;
+    /**
+     * This viewer's usage against this viewer's caps, in the stored unit.
+     *
+     * It reports neither the key-length cap nor the per-value cap, so a write
+     * that fits the numbers here can still be refused.
+     */
+    getQuota(opts?: StorageCallOptions): Promise<StorageQuota>;
+}
+export declare function createStorageClient(http: Http): StorageClient;

package/dist/storage/index.js

@@ -0,0 +1,68 @@
+import { CivitaiError } from '../core/errors.js';
+/** Where the five routes live under the site base URL. */
+const BASE = 'blocks/app-storage';
+export function createStorageClient(http) {
+    const post = (op, body, signal) => http('POST', `${BASE}/${op}`, { body, signal });
+    return {
+        async get(key, { signal } = {}) {
+            const res = await post('get', { key }, signal);
+            // 🔴 NO `res?.value ?? null`. `null` is this method's word for "the key is
+            // unset" — a real answer a caller acts on, including one that decides
+            // whether to spend. A reply that never carried `value` is not that answer.
+            if (res == null || typeof res !== 'object' || !('value' in res)) {
+                throw new CivitaiError('app-storage get: reply carried no `value`');
+            }
+            return (res.value ?? null);
+        },
+        async set(key, value, { signal } = {}) {
+            const res = await post('set', { key, value }, signal);
+            // Asserted, not cast: the declared `number` is a promise this client makes
+            // to a caller that renders it, and a cast would make it a lie we cannot see.
+            if (typeof res?.sizeBytes !== 'number') {
+                throw new CivitaiError('app-storage set: reply carried no `sizeBytes`');
+            }
+            return { ok: true, sizeBytes: res.sizeBytes };
+        },
+        async delete(key, { signal } = {}) {
+            const res = await post('delete', { key }, signal);
+            if (typeof res?.deleted !== 'boolean') {
+                throw new CivitaiError('app-storage delete: reply carried no `deleted` flag');
+            }
+            return { ok: true, deleted: res.deleted };
+        },
+        async list(query = {}, { signal } = {}) {
+            const res = await post('list', 
+            // Named rather than spread: each of the three is a field a mutation can
+            // drop on its own, and `JSON.stringify` omits the ones left undefined,
+            // so the server's own default applies instead of a second copy here.
+            { prefix: query.prefix, limit: query.limit, cursor: query.cursor }, signal);
+            // 🔴 NO `?? []`. A malformed 200 must throw, never answer "no keys": a
+            // caller stands its double-spend backstop down on a scan that completed,
+            // and a manufactured empty page is indistinguishable from one.
+            if (!Array.isArray(res?.keys)) {
+                throw new CivitaiError('app-storage list: reply carried no `keys` array');
+            }
+            return {
+                keys: res.keys.map(toEntry),
+                // 🔴 Passed through. Not defaulted, not normalised, not re-derived.
+                nextCursor: res.nextCursor,
+            };
+        },
+        getQuota: ({ signal } = {}) => post('quota', {}, signal),
+    };
+}
+function toEntry(row) {
+    const r = (row ?? {});
+    const raw = r.updatedAt;
+    // `new Date(null)` is the epoch, not an Invalid Date, so the NaN check below
+    // cannot be the only gate — a null timestamp would sort and compare silently
+    // wrong forever.
+    if (typeof r.key !== 'string' || !(typeof raw === 'string' || raw instanceof Date)) {
+        throw new CivitaiError('app-storage list: malformed key entry');
+    }
+    const at = new Date(raw);
+    if (Number.isNaN(at.getTime())) {
+        throw new CivitaiError('app-storage list: malformed key entry');
+    }
+    return { key: r.key, updatedAt: at };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/sdk",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -22,19 +22,6 @@
     "README.md",
     "dist"
   ],
-  "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
-    "api": "node scripts/api-report.mjs",
-    "api:check": "node scripts/api-report.mjs --check",
-    "check:layering": "node scripts/check-layering.mjs",
-    "check:parity": "node scripts/check-host-parity.mjs",
-    "gen:steps": "node scripts/gen-step-types.mjs",
-    "check:steps": "node scripts/gen-step-types.mjs --check",
-    "snapshot:host": "node scripts/snapshot-host-messages.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json && tsc -p tsconfig.examples.json",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "engines": {
     "node": ">=20"
   },
@@ -64,5 +51,18 @@
   },
   "dependencies": {
     "@civitai/orchestration-client": "0.2.0-beta.101"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "api": "node scripts/api-report.mjs",
+    "api:check": "node scripts/api-report.mjs --check",
+    "check:layering": "node scripts/check-layering.mjs",
+    "check:parity": "node scripts/check-host-parity.mjs",
+    "gen:steps": "node scripts/gen-step-types.mjs",
+    "check:steps": "node scripts/gen-step-types.mjs --check",
+    "snapshot:host": "node scripts/snapshot-host-messages.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json && tsc -p tsconfig.examples.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}