@civitai/app-sdk 0.51.1 → 0.51.2

package/README.md

@@ -134,7 +134,7 @@ interface BlockInitPayload {
 
 | Export | What |
 |---|---|
-| `BLOCK_SCOPES` / `BLOCK_SCOPE_PATTERN` | The 15 known block scope strings (the authoritative enum the canonical schema validates `scopes` against) + the `domain:verb:target` format-helper regex. A scope is valid only if it's a member of `BLOCK_SCOPES`, matching the [canonical schema](https://civitai.com/schemas/app-block/v1.json). |
+| `BLOCK_SCOPES` / `BLOCK_SCOPE_PATTERN` | Every known block scope string (the authoritative enum the canonical schema validates `scopes` against) + the `domain:verb:target` format-helper regex. Read the current set from `BLOCK_SCOPES` itself — scopes are added and retired, so no count is quoted here. A scope is valid only if it's a member of `BLOCK_SCOPES`, matching the [canonical schema](https://civitai.com/schemas/app-block/v1.json). |
 | `isMessage(data, type)` | Discriminator-only message narrowing (see above). |
 | `isModelSlotContext(ctx)` / `isPageSlotContext(ctx)` | Runtime narrowing for the `slotId`-discriminated `BlockContext` union. Real checks on a value that crossed a `postMessage` boundary — they verify every field they assert, not just `slotId`. |
 | `isSignedIn(viewer)` | **The sign-in gate.** `isSignedIn(useBlockContext().viewer)` — do not open-code it as `viewer !== null` or `viewer?.signedIn === true`. Which of those is correct has already changed once with the host contract, and this is the one place it is decided. It reads neither `viewer.id` nor `viewer.username` (both `@deprecated`), so nothing written through it changes when those are removed. Need the identity rather than the presence? `useViewer()` — scope-gated and audited per call. |

package/dist/blocks/browsingLevel.d.ts

@@ -3,9 +3,12 @@
  *
  * The host (civitai/civitai) projects an authoritative `maxBrowsingLevel`
  * BITMASK into `BLOCK_INIT` — the max NSFW levels the surrounding color-domain
- * allows (computed server-side from `domainBrowsingCeiling(color)`). A block
- * reads it via `useDomainMaturity()` to decide whether to surface mature
- * affordances.
+ * allows (computed server-side from `domainBrowsingCeiling(color)`) — and,
+ * alongside it, the viewer-narrowed `effectiveBrowsingLevel`. A block decides
+ * whether to surface mature affordances from the PAIR, via
+ * {@link effectiveBrowsingCeiling}; `@civitai/blocks-react`'s
+ * `useDomainMaturity()` is the React wrapper over exactly that. The domain
+ * ceiling alone is not the answer — see {@link ColorDomain}.
  *
  * The per-level bit VALUES below mirror civitai/civitai's server `NsfwLevel`
  * enum. They are STABLE wire values (a level's bit never changes), so it is
@@ -44,7 +47,7 @@ export declare const SFW_LEVELS: number;
  */
 export declare const NSFW_LEVELS: number;
 /**
- * True when the domain's browsing-level ceiling permits NO NSFW content.
+ * True when the given browsing-level ceiling permits NO NSFW content.
  *
  * Derived purely from the BITMASK: SFW ⇔ the ceiling has no NSFW bits set.
  *
@@ -54,7 +57,17 @@ export declare const NSFW_LEVELS: number;
  * block must therefore treat "unknown" as SFW and hide mature affordances
  * until proven otherwise.
  *
- * @param maxBrowsingLevel the domain ceiling bitmask from `BLOCK_INIT`.
+ * ⚠ A NEGATIVE ceiling is none of those three and fails OPEN:
+ * `isSfwCeiling(-1)` is `false` and `isLevelAllowed(XXX, -1)` is `true`, because
+ * two's complement sets every bit. {@link effectiveBrowsingCeiling} guards a
+ * negative VIEWER level but not a negative DOMAIN ceiling, so the recipe does
+ * not neutralise it either. Stated rather than fixed: adding the guard is a
+ * behaviour change and belongs in its own release.
+ *
+ * @param maxBrowsingLevel the ceiling to test — WHICHEVER you pass. Named for
+ * the domain mask because that was the only ceiling when this shipped; when
+ * gating for a viewer pass {@link effectiveBrowsingCeiling}'s result instead,
+ * or this answers "is the DOMAIN SFW?" and not "may I show THIS viewer".
  * @example
  * isSfwCeiling(BrowsingLevel.PG | BrowsingLevel.PG13); // true  (green/blue)
  * isSfwCeiling(BrowsingLevel.PG | BrowsingLevel.X);     // false (mature)
@@ -62,14 +75,24 @@ export declare const NSFW_LEVELS: number;
  */
 export declare function isSfwCeiling(maxBrowsingLevel?: number | null): boolean;
 /**
- * True when a specific browsing `level` bit is permitted by the domain ceiling.
+ * True when a specific browsing `level` bit is permitted by the given ceiling.
  *
  * **Fail-closed.** A missing / null / non-finite ceiling permits ONLY SFW
  * levels (PG / PG13) — same fail-closed posture as {@link isSfwCeiling}. A
  * non-finite / non-positive `level` returns `false`.
  *
+ * ⚠ A NEGATIVE ceiling is none of those three and fails OPEN:
+ * `isSfwCeiling(-1)` is `false` and `isLevelAllowed(XXX, -1)` is `true`, because
+ * two's complement sets every bit. {@link effectiveBrowsingCeiling} guards a
+ * negative VIEWER level but not a negative DOMAIN ceiling, so the recipe does
+ * not neutralise it either. Stated rather than fixed: adding the guard is a
+ * behaviour change and belongs in its own release.
+ *
  * @param level a single `BrowsingLevel` bit (e.g. `BrowsingLevel.R`).
- * @param maxBrowsingLevel the domain ceiling bitmask from `BLOCK_INIT`.
+ * @param maxBrowsingLevel the ceiling to test — WHICHEVER you pass. Named for
+ * the domain mask because that was the only ceiling when this shipped; when
+ * gating for a viewer pass {@link effectiveBrowsingCeiling}'s result instead,
+ * or this answers what the DOMAIN permits and not what THIS viewer may see.
  * @example
  * isLevelAllowed(BrowsingLevel.R, BrowsingLevel.PG | BrowsingLevel.PG13); // false
  * isLevelAllowed(BrowsingLevel.PG13, undefined);                          // true
@@ -126,10 +149,28 @@ export declare function isLevelAllowed(level: number, maxBrowsingLevel?: number
  */
 export declare function effectiveBrowsingCeiling(maxBrowsingLevel?: number | null, effectiveBrowsingLevel?: number | null): number;
 /**
- * The color-domain a block is rendered inside, as projected by the host. The
- * SFW policy is NOT derived from this — use {@link isSfwCeiling} on the
- * accompanying `maxBrowsingLevel` mask instead. `null` / absent means the host
- * did not project a domain (treat as unknown ⇒ fail-closed SFW).
+ * The color-domain a block is rendered inside, as projected by the host.
+ * Informational ONLY — the SFW policy is server-side, and this string is not
+ * it. `null` / absent means the host did not project a domain (treat as
+ * unknown ⇒ fail-closed SFW).
+ *
+ * 🔴 Never gate on this string, and never on `maxBrowsingLevel` alone. Resolve
+ * the ceiling with {@link effectiveBrowsingCeiling}, then test it with
+ * {@link isSfwCeiling} or {@link isLevelAllowed}:
+ *
+ * ```ts
+ * const eff = effectiveBrowsingCeiling(maxBrowsingLevel, effectiveBrowsingLevel);
+ * // 🔴 OPPOSITE POLARITIES — do not copy these two lines as a uniform pair.
+ * if (isSfwCeiling(eff)) hideMatureAffordances();     // true = SFW  ⇒ HIDE
+ * if (isLevelAllowed(BrowsingLevel.R, eff)) showR();  // true = allowed ⇒ SHOW
+ * ```
+ *
+ * This docblock used to say *"use `isSfwCeiling` on the accompanying
+ * `maxBrowsingLevel` mask instead"*. The predicate was never the problem — both
+ * predicates take WHATEVER CEILING YOU PASS — the problem was passing the
+ * domain one, which is identical for every viewer on `civitai.red` including
+ * one whose own NSFW setting is off, so it cannot answer "may I show THIS
+ * viewer mature content".
  */
 export type ColorDomain = 'green' | 'blue' | 'red';
 //# sourceMappingURL=browsingLevel.d.ts.map

package/dist/blocks/browsingLevel.js

@@ -3,9 +3,12 @@
  *
  * The host (civitai/civitai) projects an authoritative `maxBrowsingLevel`
  * BITMASK into `BLOCK_INIT` — the max NSFW levels the surrounding color-domain
- * allows (computed server-side from `domainBrowsingCeiling(color)`). A block
- * reads it via `useDomainMaturity()` to decide whether to surface mature
- * affordances.
+ * allows (computed server-side from `domainBrowsingCeiling(color)`) — and,
+ * alongside it, the viewer-narrowed `effectiveBrowsingLevel`. A block decides
+ * whether to surface mature affordances from the PAIR, via
+ * {@link effectiveBrowsingCeiling}; `@civitai/blocks-react`'s
+ * `useDomainMaturity()` is the React wrapper over exactly that. The domain
+ * ceiling alone is not the answer — see {@link ColorDomain}.
  *
  * The per-level bit VALUES below mirror civitai/civitai's server `NsfwLevel`
  * enum. They are STABLE wire values (a level's bit never changes), so it is
@@ -42,7 +45,7 @@ export const SFW_LEVELS = BrowsingLevel.PG | BrowsingLevel.PG13;
  */
 export const NSFW_LEVELS = BrowsingLevel.R | BrowsingLevel.X | BrowsingLevel.XXX;
 /**
- * True when the domain's browsing-level ceiling permits NO NSFW content.
+ * True when the given browsing-level ceiling permits NO NSFW content.
  *
  * Derived purely from the BITMASK: SFW ⇔ the ceiling has no NSFW bits set.
  *
@@ -52,7 +55,17 @@ export const NSFW_LEVELS = BrowsingLevel.R | BrowsingLevel.X | BrowsingLevel.XXX
  * block must therefore treat "unknown" as SFW and hide mature affordances
  * until proven otherwise.
  *
- * @param maxBrowsingLevel the domain ceiling bitmask from `BLOCK_INIT`.
+ * ⚠ A NEGATIVE ceiling is none of those three and fails OPEN:
+ * `isSfwCeiling(-1)` is `false` and `isLevelAllowed(XXX, -1)` is `true`, because
+ * two's complement sets every bit. {@link effectiveBrowsingCeiling} guards a
+ * negative VIEWER level but not a negative DOMAIN ceiling, so the recipe does
+ * not neutralise it either. Stated rather than fixed: adding the guard is a
+ * behaviour change and belongs in its own release.
+ *
+ * @param maxBrowsingLevel the ceiling to test — WHICHEVER you pass. Named for
+ * the domain mask because that was the only ceiling when this shipped; when
+ * gating for a viewer pass {@link effectiveBrowsingCeiling}'s result instead,
+ * or this answers "is the DOMAIN SFW?" and not "may I show THIS viewer".
  * @example
  * isSfwCeiling(BrowsingLevel.PG | BrowsingLevel.PG13); // true  (green/blue)
  * isSfwCeiling(BrowsingLevel.PG | BrowsingLevel.X);     // false (mature)
@@ -65,14 +78,24 @@ export function isSfwCeiling(maxBrowsingLevel) {
     return (maxBrowsingLevel & NSFW_LEVELS) === 0;
 }
 /**
- * True when a specific browsing `level` bit is permitted by the domain ceiling.
+ * True when a specific browsing `level` bit is permitted by the given ceiling.
  *
  * **Fail-closed.** A missing / null / non-finite ceiling permits ONLY SFW
  * levels (PG / PG13) — same fail-closed posture as {@link isSfwCeiling}. A
  * non-finite / non-positive `level` returns `false`.
  *
+ * ⚠ A NEGATIVE ceiling is none of those three and fails OPEN:
+ * `isSfwCeiling(-1)` is `false` and `isLevelAllowed(XXX, -1)` is `true`, because
+ * two's complement sets every bit. {@link effectiveBrowsingCeiling} guards a
+ * negative VIEWER level but not a negative DOMAIN ceiling, so the recipe does
+ * not neutralise it either. Stated rather than fixed: adding the guard is a
+ * behaviour change and belongs in its own release.
+ *
  * @param level a single `BrowsingLevel` bit (e.g. `BrowsingLevel.R`).
- * @param maxBrowsingLevel the domain ceiling bitmask from `BLOCK_INIT`.
+ * @param maxBrowsingLevel the ceiling to test — WHICHEVER you pass. Named for
+ * the domain mask because that was the only ceiling when this shipped; when
+ * gating for a viewer pass {@link effectiveBrowsingCeiling}'s result instead,
+ * or this answers what the DOMAIN permits and not what THIS viewer may see.
  * @example
  * isLevelAllowed(BrowsingLevel.R, BrowsingLevel.PG | BrowsingLevel.PG13); // false
  * isLevelAllowed(BrowsingLevel.PG13, undefined);                          // true

package/dist/blocks/messages.d.ts

@@ -150,8 +150,21 @@ export interface BlockInitPayload {
     /**
      * The color-domain the block is rendered inside (`green` | `blue` | `red`),
      * or `null` when the host did not resolve one. Informational ONLY — the SFW
-     * policy is server-side; derive "is this SFW?" from {@link maxBrowsingLevel}
-     * (via `isSfwCeiling` / `useDomainMaturity`), never from this string.
+     * policy is server-side; never gate on this string. Resolve the ceiling
+     * first, then test it — in any runtime:
+     *
+     * ```ts
+     * const eff = effectiveBrowsingCeiling(maxBrowsingLevel, effectiveBrowsingLevel);
+     * // 🔴 OPPOSITE POLARITIES — do not copy these two lines as a uniform pair.
+     * if (isSfwCeiling(eff)) hideMatureAffordances();     // true = SFW  ⇒ HIDE
+     * if (isLevelAllowed(BrowsingLevel.R, eff)) showR();  // true = allowed ⇒ SHOW
+     * ```
+     *
+     * 🔴 `effectiveBrowsingCeiling` returns a BITMASK, not a boolean — an SFW
+     * ceiling is `3`, which is truthy, so branching on it directly shows mature
+     * content to a viewer who may not see it. It needs one of the two predicates
+     * above. In React, `@civitai/blocks-react`'s `useDomainMaturity()` returns
+     * `isSfw` / `isLevelAllowed` already composed this way.
      *
      * Sent by civitai/civitai PR #2670. A host that predates it omits this field
      * (reads `undefined`).
@@ -161,8 +174,9 @@ export interface BlockInitPayload {
      * Authoritative browsing-level BITMASK = the max NSFW levels the domain
      * allows, computed server-side from `domainBrowsingCeiling(color)` (green/
      * blue → SFW, red → all). Bits mirror the server `NsfwLevel` (see
-     * `browsingLevel.ts`). A block reads this to decide whether to surface mature
-     * affordances — `isSfwCeiling(maxBrowsingLevel)` is the canonical test.
+     * `browsingLevel.ts`). `isSfwCeiling(maxBrowsingLevel)` answers "is this
+     * DOMAIN SFW?" — not "may I show THIS viewer mature content"; for that, see
+     * the warning below and {@link effectiveBrowsingLevel}.
      *
      * Sent by civitai/civitai PR #2670. A host that predates it omits this field
      * (reads `undefined`); the SDK fail-closes to SFW when it is absent.
@@ -193,9 +207,13 @@ export interface BlockInitPayload {
      *      WIDER than the domain permits and is not permission for anything.
      *
      * ADDITIVE + OPTIONAL. A host that predates it omits the field, in which case
-     * `useDomainMaturity()` falls back to `maxBrowsingLevel` — i.e. exactly the
-     * behaviour that host already had. Read it through the hook rather than
-     * directly, so the fallback and the fail-closed defaults are applied for you.
+     * the ceiling falls back to {@link maxBrowsingLevel} — i.e. exactly the
+     * behaviour that host already had. Do not read this field directly: pass it
+     * through `effectiveBrowsingCeiling`, which applies that fallback and the
+     * fail-closed defaults for you. `@civitai/blocks-react`'s
+     * `useDomainMaturity()` is the React wrapper over the same thing — it is one
+     * way to get this right, not the only one, since this module is
+     * runtime-agnostic and two of the starters ship without React.
      */
     effectiveBrowsingLevel?: number;
 }

package/dist/blocks/scopes.d.ts

@@ -33,7 +33,7 @@ export type BlockScope = (typeof BLOCK_SCOPES)[BlockScopeKey];
  *
  * NOTE: this regex is **not** the authoritative validity contract. The
  * canonical manifest schema (https://civitai.com/schemas/app-block/v1.json)
- * validates `scopes` by MEMBERSHIP in a fixed enum — i.e. the 12 values in
+ * validates `scopes` by MEMBERSHIP in a fixed enum — i.e. exactly the values in
  * {@link BLOCK_SCOPES}. `defineBlock` therefore gates on membership in
  * `BLOCK_SCOPES`; this pattern is kept only as a FORMAT HEURISTIC to give a
  * pointed error message (e.g. distinguishing a malformed/PascalCase scope from

package/dist/blocks/scopes.js

@@ -55,7 +55,7 @@ export const BLOCK_SCOPES = {
  *
  * NOTE: this regex is **not** the authoritative validity contract. The
  * canonical manifest schema (https://civitai.com/schemas/app-block/v1.json)
- * validates `scopes` by MEMBERSHIP in a fixed enum — i.e. the 12 values in
+ * validates `scopes` by MEMBERSHIP in a fixed enum — i.e. exactly the values in
  * {@link BLOCK_SCOPES}. `defineBlock` therefore gates on membership in
  * `BLOCK_SCOPES`; this pattern is kept only as a FORMAT HEURISTIC to give a
  * pointed error message (e.g. distinguishing a malformed/PascalCase scope from

package/dist/safe-storage/index.d.ts

@@ -1,6 +1,12 @@
 /**
  * `@civitai/app-sdk/safe-storage` — survive an opaque-origin sandbox.
  *
+ * 🔴 `@civitai/sdk`'s `src/safe-storage/index.ts` is a deliberate independent
+ * COPY of this file (the successor must not depend on its predecessor). The two
+ * bodies are held byte-identical modulo comments by
+ * `tests/guards/safe-storage-copy-parity.test.mjs`, so a fix here goes red
+ * until it is applied there too.
+ *
  * Civitai Apps run in an iframe sandboxed as `allow-scripts allow-forms`,
  * deliberately WITHOUT `allow-same-origin`. The document therefore has an
  * **opaque origin**, and there is no origin to key web storage against, so the
@@ -54,8 +60,19 @@ export declare function createMemoryStorage(): Storage;
  * with an in-memory `Storage`, so third-party code that touches it unguarded
  * cannot throw.
  *
- * - **No-op where storage works.** A healthy `Storage` is never replaced, and
- *   its contents are never touched.
+ * - **No-op where storage works — but not a no-TOUCH.** A healthy `Storage` is
+ *   never replaced and its contents are unchanged, but it *is* written to:
+ *   classifying it means a real round trip, so each of `localStorage` and
+ *   `sessionStorage` gets `setItem('__civitai_app_sdk_storage_probe__', '1')`
+ *   immediately followed by `removeItem`. MEASURED against the built artifact
+ *   with instrumented healthy stores: exactly those four operations, the store
+ *   objects not replaced, contents identical before and after. Per the Web
+ *   Storage spec every one of those writes queues a `storage` event in the
+ *   *other* documents that share the store, so at a REAL origin a cross-tab
+ *   listener that does not filter by key sees spurious events (the two
+ *   `localStorage` writes are the ones another tab receives). At the opaque
+ *   origin this module exists for there is no other same-origin document, so
+ *   there is nothing to receive them.
  * - **No-op where storage is absent** (Node/SSR/workers). Nothing is invented.
  * - **Never loses readable data.** When the old store reads but refuses writes
  *   (full / disabled), its entries are copied into the fallback first, so the

package/dist/safe-storage/index.js

@@ -1,6 +1,12 @@
 /**
  * `@civitai/app-sdk/safe-storage` — survive an opaque-origin sandbox.
  *
+ * 🔴 `@civitai/sdk`'s `src/safe-storage/index.ts` is a deliberate independent
+ * COPY of this file (the successor must not depend on its predecessor). The two
+ * bodies are held byte-identical modulo comments by
+ * `tests/guards/safe-storage-copy-parity.test.mjs`, so a fix here goes red
+ * until it is applied there too.
+ *
  * Civitai Apps run in an iframe sandboxed as `allow-scripts allow-forms`,
  * deliberately WITHOUT `allow-same-origin`. The document therefore has an
  * **opaque origin**, and there is no origin to key web storage against, so the
@@ -272,8 +278,19 @@ function seedFrom(existing, into) {
  * with an in-memory `Storage`, so third-party code that touches it unguarded
  * cannot throw.
  *
- * - **No-op where storage works.** A healthy `Storage` is never replaced, and
- *   its contents are never touched.
+ * - **No-op where storage works — but not a no-TOUCH.** A healthy `Storage` is
+ *   never replaced and its contents are unchanged, but it *is* written to:
+ *   classifying it means a real round trip, so each of `localStorage` and
+ *   `sessionStorage` gets `setItem('__civitai_app_sdk_storage_probe__', '1')`
+ *   immediately followed by `removeItem`. MEASURED against the built artifact
+ *   with instrumented healthy stores: exactly those four operations, the store
+ *   objects not replaced, contents identical before and after. Per the Web
+ *   Storage spec every one of those writes queues a `storage` event in the
+ *   *other* documents that share the store, so at a REAL origin a cross-tab
+ *   listener that does not filter by key sees spurious events (the two
+ *   `localStorage` writes are the ones another tab receives). At the opaque
+ *   origin this module exists for there is no other same-origin document, so
+ *   there is nothing to receive them.
  * - **No-op where storage is absent** (Node/SSR/workers). Nothing is invented.
  * - **Never loses readable data.** When the old store reads but refuses writes
  *   (full / disabled), its entries are copied into the fallback first, so the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/app-sdk",
-  "version": "0.51.1",
+  "version": "0.51.2",
   "description": "OAuth + PKCE, encrypted-cookie sessions, scopes, and orchestrator helpers for building third-party Civitai apps.",
   "license": "MIT",
   "type": "module",

package/schemas/app-block/v1.json

@@ -72,7 +72,7 @@
     },
     "auth": {
       "type": "string",
-      "description": "Which credential the host hands the block: \"block-token\" (default when omitted) is the block-scoped JWT; \"oauth\" opts the block into a real OAuth access token for its own OauthClient, accepted unchanged by /api/v1, the orchestrator and the MCP.",
+      "description": "Which credential the host hands the block: \"block-token\" (default when omitted) is the block-scoped JWT; \"oauth\" asks for an opaque OAuth access token for the block's own OauthClient, which ordinary /api/v1 routes accept as a viewer bearer. Minting it is gated on a server flag that is not generally enabled, and also requires a signed-in viewer and a declared \"user:read:self\" scope; when any of those is unmet the host hands back a block JWT instead of failing, so branch on the token kind the host reports rather than on this field. An OAuth token is refused by the postMessage bridge procedures, which verify a block JWT only, and declaring \"oauth\" alongside any \"apps:storage:*\" scope is refused at submit time.",
       "enum": ["block-token", "oauth"]
     },
     "trustTier": {