@civitai/blocks-react 0.61.1 → 0.62.0

package/dist/internal/mockHost.d.ts

@@ -599,18 +599,70 @@ export interface MockHostOptions {
      * {@link MockHost.setScenario}.
      */
     disallowedAccountTypes?: BuzzAccountType[];
+    /**
+     * The scopes the app's `block.manifest.json` DECLARES — the set the real
+     * host's token mint draws from.
+     *
+     * 🔴 **STORAGE IS GATED ON THIS, AND THE DEFAULT IS EMPTY.** A storage op whose
+     * scope is not in here is refused exactly as the server refuses it, because the
+     * server's test is presence in the block's approved scope set (see
+     * `BLOCK_SCOPES` in `@civitai/app-sdk`) and an undeclared scope is never
+     * approved. Omit this and every `APP_STORAGE_*` / `SHARED_*` call fails.
+     *
+     * That is a DELIBERATE BREAKING DEFAULT. Until this existed the mock host
+     * served storage unconditionally, so an app that forgot the scopes passed its
+     * whole suite and the dev harness and then failed every save in production —
+     * the one storage failure mode that actually ships was the only one the mock
+     * could not produce. A default of "permissive" would have left that true for
+     * every app that did not opt in, i.e. precisely the apps that did not know the
+     * scopes existed.
+     *
+     * Pass what your manifest declares — ideally by importing your own
+     * `block.manifest.json` as `manifest`, so the two cannot drift:
+     *
+     * ```ts
+     * createMockHost({ declaredScopes: manifest.scopes });
+     * ```
+     *
+     * ⚠️ The `import` line is described rather than shown ON PURPOSE, and please
+     * do not helpfully add it back. `tests/guards/blocks-react-entry-directory-names.test.mjs`
+     * extracts import specifiers with a raw regex over the whole file —
+     * `/\bfrom\s*['"]([^'"]+)['"]/g`, comments included — so a `from '…'` inside a
+     * doc comment is read as a real edge and resolved against THIS file's
+     * directory. A relative path to a consumer's manifest does not exist from
+     * here, and the guard fails with `unresolvable specifier`. Measured: it went
+     * red on all five `Starter (…)` matrix legs.
+     *
+     * A test that only exercises storage mechanics (quota, caps, row limits) and
+     * does not care about authorization should declare the storage scopes
+     * explicitly rather than reach for a permissive flag — there is none, on
+     * purpose.
+     *
+     * ⚠️ Scopes OTHER than storage are not read from here yet. `ai:write:budgeted`
+     * keeps its own `consentGranted` flag, because `buzzBudget` is conditional on
+     * it and `setScenario` can toggle it mid-session; giving one scope two sources
+     * of truth is how they drift.
+     */
+    declaredScopes?: string[];
     /**
      * STORAGE scenario: in-memory KV backend (seed / quota / failNext). See
      * {@link MockStorageScenario}. When omitted, the store starts EMPTY with the
-     * v0 defaults — `APP_STORAGE_*` is answered either way (the mock host always
-     * serves storage now).
+     * v0 defaults.
+     *
+     * ⚠️ This governs the BACKEND, not authorization. Storage is additionally
+     * gated on {@link MockHostOptions.declaredScopes}, which defaults to empty —
+     * so a scenario alone no longer makes storage answer. (It used to: this doc
+     * said `APP_STORAGE_*` was "answered either way", and that was the defect.)
      */
     storage?: MockStorageScenario;
     /**
      * SHARED scenario: in-memory, app-scoped, votable backend (seed / failNext).
-     * See {@link MockSharedScenario}. When omitted, the shared store starts EMPTY
-     * — the `SHARED_*` protocol is answered either way (the mock host always
-     * serves shared storage now).
+     * See {@link MockSharedScenario}. When omitted, the shared store starts EMPTY.
+     *
+     * ⚠️ As with {@link MockHostOptions.storage}, this governs the BACKEND and not
+     * authorization: `SHARED_*` is additionally gated on
+     * {@link MockHostOptions.declaredScopes} (`apps:storage:shared:read` /
+     * `:write`), which defaults to empty.
      */
     shared?: MockSharedScenario;
     /** Host theme delivered in `BLOCK_INIT` + context. Default `'dark'`. */

package/dist/internal/mockHost.js

@@ -39,6 +39,7 @@
  */
 import { APP_STORAGE_ERROR_REQUEST_FAILED, APP_STORAGE_ERROR_USER_QUOTA_EXCEEDED, APP_STORAGE_ERROR_USER_ROW_LIMIT, APP_STORAGE_ERROR_VALUE_TOO_LARGE, APP_STORAGE_MAX_BYTES, APP_STORAGE_MAX_ROWS, APP_STORAGE_MAX_VALUE_BYTES, BrowsingLevel, SFW_LEVELS, } from '@civitai/app-sdk/blocks';
 import { consentUnavailablePayload, isKnownBlockScope, resolveUngrantableConsentNotice, } from './consent.js';
+import { requiredStorageScope, storageResultType, storageScopeDeniedMessage, storageScopeDeniedPayload, } from './mockHostScopes.js';
 import { hostContextWithTheme } from '../transport/transport.js';
 import { isRoutableRequestId } from '../transport/requestId.js';
 /**
@@ -849,6 +850,19 @@ export function createMockHost(options = {}) {
          * precisely what `./consent.js`'s header warns about.
          */
         const extraGrantedScopes = new Set();
+        /**
+         * What the app's manifest DECLARES — the set the real host's token mint draws
+         * from, and the set the storage gate tests presence in.
+         *
+         * 🔴 Deliberately NOT defaulted to anything permissive. See
+         * {@link MockHostOptions.declaredScopes}: a permissive default would leave the
+         * pre-gate behaviour in place for every app that did not opt in, which is the
+         * population the gate exists for.
+         *
+         * This is a SNAPSHOT at install time, unlike `consentGranted`, which
+         * `setScenario` can toggle. A manifest does not change mid-session.
+         */
+        const declaredScopeSet = new Set(options.declaredScopes ?? []);
         /** Everything the CURRENT token carries. One reader, so the two cannot drift. */
         const currentScopes = () => [
             ...(consentGranted ? [BUDGETED_SCOPE] : []),
@@ -911,6 +925,30 @@ export function createMockHost(options = {}) {
                 const typed = msg;
                 options.onOutbound?.({ type: typed.type, payload: typed.payload });
                 const requestId = typed.payload?.requestId;
+                // ---- THE STORAGE SCOPE GATE — see ./mockHostScopes.ts ----
+                //
+                // The server's test is PRESENCE in the block's approved scope set, so an
+                // UNDECLARED scope is refused before the backend is ever consulted. That
+                // ordering is the point: it refuses even when the scenario, the quota and
+                // the row budget would all have allowed the op, because production does.
+                //
+                // 🔴 IT SITS AHEAD OF THE SWITCH SO ONE RULE COVERS EVERY SURFACE. The
+                // alternative — a check inside each of the 15 storage handlers — is the
+                // shape that regenerates the same omission at every new site: a storage
+                // message added later is governed the moment it joins the table in
+                // `mockHostScopes.ts`, rather than whenever someone remembers to copy a
+                // guard into its handler.
+                {
+                    const needed = requiredStorageScope(typed.type);
+                    if (needed !== null && !declaredScopeSet.has(needed)) {
+                        const error = storageScopeDeniedMessage(typed.type, needed);
+                        dispatchToBlock({
+                            type: storageResultType(typed.type),
+                            payload: storageScopeDeniedPayload(typed.type, requestId, error),
+                        });
+                        return;
+                    }
+                }
                 switch (typed.type) {
                     case 'REQUEST_TOKEN':
                         dispatchToBlock({

package/dist/internal/mockHostScopes.d.ts

@@ -0,0 +1,100 @@
+/**
+ * mockHostScopes.ts — the dev host's STORAGE SCOPE GATE.
+ *
+ * THE MOTIVATING FAILURE (2026-10-01). An app was built from the documented
+ * onboarding prompt, shipped `useAppStorage()` for every save, and declared only
+ * `ai:write:budgeted` in its manifest. It passed **198 unit tests, the dev
+ * harness, `civitai app validate`, and a full submit** — then every save in
+ * production failed:
+ *
+ *     "message": "storage set requires the apps:storage:write scope",
+ *     "code": -32003,
+ *     "data": { "code": "FORBIDDEN", "httpStatus": 403, "path": "apps.storage.set" }
+ *
+ * which the viewer saw as *"Saving failed for an unknown reason… try again"*.
+ *
+ * 🔴 THE REASON IT GOT THAT FAR IS THIS FILE'S ABSENCE. `createMockHost` served
+ * storage unconditionally — its own options doc said so in as many words
+ * ("`APP_STORAGE_*` is answered either way (the mock host always serves storage
+ * now)") — so the one failure mode that actually ships was the only storage
+ * failure mode the mock could not produce. It modelled the per-value cap, both
+ * per-viewer budgets, the row limit and an induced transport failure, and not
+ * the scope.
+ *
+ * So this is not a new feature so much as the missing arm of an existing
+ * simulation: the dev host already models `ai:write:budgeted` (it has a flag,
+ * a consent round-trip and an un-grantable case). Storage had nothing.
+ *
+ * ---
+ *
+ * WHAT THE SERVER ACTUALLY DOES, and what is inferred here.
+ *
+ * `BLOCK_SCOPES` in `@civitai/app-sdk` states the mechanism: the storage scopes
+ * "have no OAuth bit … the server gates them by presence in the block's
+ * APPROVED SCOPE SET, not a bitmask". Presence is therefore the whole test, and
+ * it is what {@link requiredStorageScope} models.
+ *
+ * 🔴 ONE ROW IS MEASURED; THE REST ARE INFERRED FROM THE SCOPE NAMES. The
+ * incident above is direct evidence for exactly one pair —
+ * `apps.storage.set` → `apps:storage:write` — because the server named both in
+ * its own refusal. Every other row below reads a `:read` scope onto a read op
+ * and a `:write` scope onto a write op, which is the only split the names admit
+ * but is still an inference about another service. Nothing in this repository
+ * can verify it: there is no op→scope table in `@civitai/app-sdk`, none in this
+ * package, and the server's own table is not vendored.
+ *
+ * The consequence matters because enforcement is ON by default: a row that is
+ * WRONG fails a CORRECT app's suite. If that happens, the row is the suspect —
+ * not the app. Fix the row and say what the server did instead.
+ *
+ * `SHARED_REPORT` is the row to doubt first. It is mapped to
+ * `apps:storage:shared:write` because `useSharedStorage().report()` files a row
+ * in the shared store, so it is a write by construction — but a server is also
+ * free to treat an abuse report as a moderation path outside the store's own
+ * gate, in which case this row over-gates and should be removed rather than
+ * weakened.
+ */
+/** Every message type this gate governs. Exported for the ledger test. */
+export declare function gatedStorageMessages(): string[];
+/**
+ * The scope `type` needs, or `null` when this gate does not govern it.
+ *
+ * `null` is the ordinary answer — the overwhelming majority of block→host
+ * messages are not storage.
+ */
+export declare function requiredStorageScope(type: string): string | null;
+/**
+ * The refusal text. Modelled on the server's own prose for the one case it was
+ * observed emitting: *"storage set requires the apps:storage:write scope"*.
+ *
+ * 🔴 DO NOT LET A BLOCK BRANCH ON THIS STRING, and do not render it to a viewer.
+ * `@civitai/app-sdk`'s `appStorageErrors.ts` is explicit that host refusal prose
+ * is "not localized, not written for an end user, and free to change", and that
+ * an authorization failure deliberately classifies as `null` through
+ * `classifyAppStorageError` — which is exactly what this message does, matching
+ * production rather than inventing a classification the real host does not send.
+ * That `null` arm is also why *"please try again"* is the wrong copy for it: a
+ * missing scope is a manifest defect and no number of retries fixes it.
+ */
+export declare function storageScopeDeniedMessage(type: string, scope: string): string;
+/**
+ * The reply payload that refuses `type`, type-correct for that reply's own
+ * contract.
+ *
+ * 🔴 EVERY STORAGE REPLY CARRIES `error?`, AND A NON-EMPTY `error` IS THE REJECT
+ * SIGNAL — `@civitai/app-sdk`'s messages module calls it "the
+ * `APP_STORAGE_GET_RESULT` value-or-error convention: consumers treat a
+ * non-empty `error` as the failure signal". So a refusal does not need a new
+ * wire field, a new constant, or an `@civitai/app-sdk` change — which also
+ * means it needs no peer-range bump, the hazard that once left 27 of 43 test
+ * files collecting zero tests in this very package.
+ *
+ * The DATA fields are still required by each reply's type, so each arm supplies
+ * an empty-but-valid one rather than omitting it: a reply that fails its own
+ * contract risks being dropped by the host-message validator, which would
+ * present as a HANG rather than a refusal.
+ */
+export declare function storageScopeDeniedPayload(type: string, requestId: string | undefined, error: string): Record<string, unknown>;
+/** The reply type for a block→host storage message. Uniform across the family. */
+export declare function storageResultType(type: string): string;
+//# sourceMappingURL=mockHostScopes.d.ts.map

package/dist/internal/mockHostScopes.js

@@ -0,0 +1,171 @@
+/**
+ * mockHostScopes.ts — the dev host's STORAGE SCOPE GATE.
+ *
+ * THE MOTIVATING FAILURE (2026-10-01). An app was built from the documented
+ * onboarding prompt, shipped `useAppStorage()` for every save, and declared only
+ * `ai:write:budgeted` in its manifest. It passed **198 unit tests, the dev
+ * harness, `civitai app validate`, and a full submit** — then every save in
+ * production failed:
+ *
+ *     "message": "storage set requires the apps:storage:write scope",
+ *     "code": -32003,
+ *     "data": { "code": "FORBIDDEN", "httpStatus": 403, "path": "apps.storage.set" }
+ *
+ * which the viewer saw as *"Saving failed for an unknown reason… try again"*.
+ *
+ * 🔴 THE REASON IT GOT THAT FAR IS THIS FILE'S ABSENCE. `createMockHost` served
+ * storage unconditionally — its own options doc said so in as many words
+ * ("`APP_STORAGE_*` is answered either way (the mock host always serves storage
+ * now)") — so the one failure mode that actually ships was the only storage
+ * failure mode the mock could not produce. It modelled the per-value cap, both
+ * per-viewer budgets, the row limit and an induced transport failure, and not
+ * the scope.
+ *
+ * So this is not a new feature so much as the missing arm of an existing
+ * simulation: the dev host already models `ai:write:budgeted` (it has a flag,
+ * a consent round-trip and an un-grantable case). Storage had nothing.
+ *
+ * ---
+ *
+ * WHAT THE SERVER ACTUALLY DOES, and what is inferred here.
+ *
+ * `BLOCK_SCOPES` in `@civitai/app-sdk` states the mechanism: the storage scopes
+ * "have no OAuth bit … the server gates them by presence in the block's
+ * APPROVED SCOPE SET, not a bitmask". Presence is therefore the whole test, and
+ * it is what {@link requiredStorageScope} models.
+ *
+ * 🔴 ONE ROW IS MEASURED; THE REST ARE INFERRED FROM THE SCOPE NAMES. The
+ * incident above is direct evidence for exactly one pair —
+ * `apps.storage.set` → `apps:storage:write` — because the server named both in
+ * its own refusal. Every other row below reads a `:read` scope onto a read op
+ * and a `:write` scope onto a write op, which is the only split the names admit
+ * but is still an inference about another service. Nothing in this repository
+ * can verify it: there is no op→scope table in `@civitai/app-sdk`, none in this
+ * package, and the server's own table is not vendored.
+ *
+ * The consequence matters because enforcement is ON by default: a row that is
+ * WRONG fails a CORRECT app's suite. If that happens, the row is the suspect —
+ * not the app. Fix the row and say what the server did instead.
+ *
+ * `SHARED_REPORT` is the row to doubt first. It is mapped to
+ * `apps:storage:shared:write` because `useSharedStorage().report()` files a row
+ * in the shared store, so it is a write by construction — but a server is also
+ * free to treat an abuse report as a moderation path outside the store's own
+ * gate, in which case this row over-gates and should be removed rather than
+ * weakened.
+ */
+import { BLOCK_SCOPES } from '@civitai/app-sdk/blocks';
+/**
+ * Block→host message type → the scope the server requires to answer it.
+ *
+ * Only storage surfaces appear here. The money path keeps its own flag
+ * (`consentGranted`) in `mockHost.ts`, deliberately: `buzzBudget` is conditional
+ * on it and `setScenario` can toggle it mid-session, so folding it in here would
+ * give one scope two sources of truth.
+ */
+const STORAGE_SCOPE_BY_MESSAGE = {
+    // Per-app, per-viewer KV store.
+    APP_STORAGE_GET: BLOCK_SCOPES.APPS_STORAGE_READ,
+    APP_STORAGE_LIST: BLOCK_SCOPES.APPS_STORAGE_READ,
+    APP_STORAGE_QUOTA: BLOCK_SCOPES.APPS_STORAGE_READ,
+    APP_STORAGE_SET: BLOCK_SCOPES.APPS_STORAGE_WRITE, // ← the MEASURED row
+    APP_STORAGE_DELETE: BLOCK_SCOPES.APPS_STORAGE_WRITE,
+    // Shared, cross-user store.
+    SHARED_LIST: BLOCK_SCOPES.APPS_STORAGE_SHARED_READ,
+    SHARED_GET: BLOCK_SCOPES.APPS_STORAGE_SHARED_READ,
+    SHARED_GET_COUNT: BLOCK_SCOPES.APPS_STORAGE_SHARED_READ,
+    SHARED_GET_COUNTS: BLOCK_SCOPES.APPS_STORAGE_SHARED_READ,
+    SHARED_APPEND: BLOCK_SCOPES.APPS_STORAGE_SHARED_WRITE,
+    SHARED_VOTE: BLOCK_SCOPES.APPS_STORAGE_SHARED_WRITE,
+    SHARED_UNVOTE: BLOCK_SCOPES.APPS_STORAGE_SHARED_WRITE,
+    SHARED_WITHDRAW: BLOCK_SCOPES.APPS_STORAGE_SHARED_WRITE,
+    SHARED_UPDATE: BLOCK_SCOPES.APPS_STORAGE_SHARED_WRITE,
+    SHARED_REPORT: BLOCK_SCOPES.APPS_STORAGE_SHARED_WRITE, // ← doubt this one first
+};
+/** Every message type this gate governs. Exported for the ledger test. */
+export function gatedStorageMessages() {
+    return Object.keys(STORAGE_SCOPE_BY_MESSAGE).sort();
+}
+/**
+ * The scope `type` needs, or `null` when this gate does not govern it.
+ *
+ * `null` is the ordinary answer — the overwhelming majority of block→host
+ * messages are not storage.
+ */
+export function requiredStorageScope(type) {
+    return STORAGE_SCOPE_BY_MESSAGE[type] ?? null;
+}
+/**
+ * The refusal text. Modelled on the server's own prose for the one case it was
+ * observed emitting: *"storage set requires the apps:storage:write scope"*.
+ *
+ * 🔴 DO NOT LET A BLOCK BRANCH ON THIS STRING, and do not render it to a viewer.
+ * `@civitai/app-sdk`'s `appStorageErrors.ts` is explicit that host refusal prose
+ * is "not localized, not written for an end user, and free to change", and that
+ * an authorization failure deliberately classifies as `null` through
+ * `classifyAppStorageError` — which is exactly what this message does, matching
+ * production rather than inventing a classification the real host does not send.
+ * That `null` arm is also why *"please try again"* is the wrong copy for it: a
+ * missing scope is a manifest defect and no number of retries fixes it.
+ */
+export function storageScopeDeniedMessage(type, scope) {
+    return `${verbFor(type)} requires the ${scope} scope`;
+}
+/**
+ * The server names the OPERATION, not the message type, in its refusal
+ * (`storage set …`, on path `apps.storage.set`). Mirror that so a developer
+ * grepping their logs for the production string finds the dev one too.
+ */
+function verbFor(type) {
+    const shared = type.startsWith('SHARED_');
+    const op = type
+        .replace(/^APP_STORAGE_/, '')
+        .replace(/^SHARED_/, '')
+        .toLowerCase()
+        .replace(/_/g, ' ');
+    return shared ? `shared storage ${op}` : `storage ${op}`;
+}
+/**
+ * The reply payload that refuses `type`, type-correct for that reply's own
+ * contract.
+ *
+ * 🔴 EVERY STORAGE REPLY CARRIES `error?`, AND A NON-EMPTY `error` IS THE REJECT
+ * SIGNAL — `@civitai/app-sdk`'s messages module calls it "the
+ * `APP_STORAGE_GET_RESULT` value-or-error convention: consumers treat a
+ * non-empty `error` as the failure signal". So a refusal does not need a new
+ * wire field, a new constant, or an `@civitai/app-sdk` change — which also
+ * means it needs no peer-range bump, the hazard that once left 27 of 43 test
+ * files collecting zero tests in this very package.
+ *
+ * The DATA fields are still required by each reply's type, so each arm supplies
+ * an empty-but-valid one rather than omitting it: a reply that fails its own
+ * contract risks being dropped by the host-message validator, which would
+ * present as a HANG rather than a refusal.
+ */
+export function storageScopeDeniedPayload(type, requestId, error) {
+    switch (type) {
+        // ---- reads: data field + error ----
+        case 'APP_STORAGE_GET':
+            return { requestId, value: null, error };
+        case 'APP_STORAGE_LIST':
+            return { requestId, keys: [], error };
+        case 'APP_STORAGE_QUOTA':
+            return { requestId, usedBytes: 0, rowCount: 0, limitBytes: 0, limitRows: 0, error };
+        case 'SHARED_LIST':
+            return { requestId, items: [], error };
+        case 'SHARED_GET':
+            return { requestId, item: null, error };
+        case 'SHARED_GET_COUNT':
+            return { requestId, count: 0, error };
+        case 'SHARED_GET_COUNTS':
+            return { requestId, counts: {}, error };
+        // ---- writes: ok:false + error ----
+        default:
+            return { requestId, ok: false, error };
+    }
+}
+/** The reply type for a block→host storage message. Uniform across the family. */
+export function storageResultType(type) {
+    return `${type}_RESULT`;
+}
+//# sourceMappingURL=mockHostScopes.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/blocks-react",
-  "version": "0.61.1",
+  "version": "0.62.0",
   "description": "React hooks and iframe transport for Civitai Apps. Pairs with @civitai/app-sdk/blocks.",
   "license": "MIT",
   "type": "module",