docs(furni): spec — server-authoritative furni names/descriptions from JSON + live

Design for sourcing furni display names from furnidata JSON (DB keeps technical data), with a live delta-broadcast pipeline (emulator file-watch -> renderer patch -> client refresh) and a security hardening section. Cross-repo reference copy.

docs/superpowers/specs/2026-06-04-furni-names-from-json-server-design.md

@@ -0,0 +1,264 @@
+# Furni names from JSON (server-authoritative) — Design
+
+- **Date:** 2026-06-04
+- **Status:** Draft for review
+- **Scope:** Cross-repo — Arcturus (emulator), Nitro_Render_V3 (renderer), Nitro-V3 (client)
+- **Out of scope:** furni-editor feature/packets, NitroV3-Housekeeping (CMS), server-side multi-language, description rendering in the infostand.
+
+## 1. Problem & motivation
+
+Today a furni's display name lives in **two independent places** that drift apart:
+
+- **DB** — `items_base.public_name` (`Item.fullName`), used by the emulator.
+- **furnidata JSON** — used by the client (the client already resolves all visible furni
+  names/descriptions from furnidata, keyed by classname).
+
+This forces admins to maintain names twice and causes mismatches. We want **one source of
+truth**: the **furnidata JSON owns display names & descriptions**, the **DB owns technical
+data**. Editing furnidata should reflect everywhere — server-pronounced strings and every
+connected client — **live**, with no DB edit and no restart.
+
+This is a single, unified refactor whose payoff is admin furni management: one place to edit,
+consistent everywhere.
+
+## 2. Source-of-truth contract
+
+| Concern | Owner | Storage | Read by |
+|---|---|---|---|
+| `classname` (`item_name` / `Item.name`) | **DB** | `items_base.item_name` | join key → furnidata **and** `.nitro` asset; `isPet/isBot`; wired `wf_` fallback |
+| technical data (dimensions, `stateCount`, flags, interaction, effects) | **DB** | `items_base.*` | emulator simulation |
+| **display name** | **JSON** | furnidata (per classname) | emulator (`getDisplayName`) + client (furnidata, unchanged) |
+| **description** | **JSON** | furnidata (per classname) | client only (catalog) — **no server consumer** |
+
+Invariants:
+
+1. The **bridge is `classname`**, not a numeric id. `Item.name` ↔ furnidata `classname`.
+2. `public_name` (`Item.fullName`) is **NOT removed**: it remains (a) the fallback when a
+   classname is missing from furnidata, and (b) the technical token for wired furni
+   (`Item.java:107-116` reads `fullName.startsWith("wf_")`). No schema migration. No DROP.
+3. There is **no `description` column** in `items_base`; description is JSON-only and has no
+   server consumer → the emulator gets **no** `getDescription()`.
+4. **One furnidata artifact** is shared truth: the file the emulator indexes must be the same
+   furnidata the client loads (deploy invariant, §7).
+5. Server emits names in the **base locale** of the furnidata file. Player-facing multi-language
+   stays a client localization-layer concern (unchanged).
+
+## 3. Architecture — two independent pieces
+
+The refactor is two pieces that share only the furnidata file and one new packet. They do not
+depend on each other.
+
+- **Piece 1 — Server-authoritative names.** The emulator's pronounced names come from furnidata.
+- **Piece 2 — Liveness via delta.** When the furnidata file changes, connected clients (and the
+  server index) update without reconnecting, via a minimal delta broadcast.
+
+## 4. Piece 1 — Emulator (server-authoritative names)
+
+### 4.1 `FurnidataReader` (new, package `com.eu.habbo.habbohotel.items`)
+
+A neutral, shared reader extracted so the editor is **not touched**. Responsibilities:
+
+- Resolve the furnidata source reusing the **same already-configured** path as the editor:
+  `furni.editor.renderer.config.path` → `furnidata.url` → `furni.editor.asset.base.path`
+  (see `FurniDataManager.resolveSource()` for the exact resolution we mirror). Default to those
+  values so admins configure **once**.
+- Support both layouts the editor already supports: **single file** (`FurnitureData.json`) and
+  **split-tier directory** (`core/custom/seasonal`, `manifest.json5`, JSON5 with comments;
+  later tiers override earlier). Reuse the JSON5 strip logic (extract to the shared reader).
+- Parse `roomitemtypes` (floor) and `wallitemtypes` (wall) → return a flat list of
+  `FurnidataEntry { int id, String classname, FurnitureType type, String name, String description }`.
+
+**Security requirements on the reader (furnidata is untrusted input):**
+
+- **Path-traversal guard.** When resolving split-tier manifest entries
+  (`tiers[]`, `files[]`) via `dir.resolve(name)`, normalize the result and **reject any path that
+  escapes the configured base dir** (absolute paths, `..`). The existing `FurniDataManager` lacks
+  this guard — the shared reader MUST add it (do not propagate the gap).
+- **Size cap.** Refuse to load a furnidata file/dir above a configurable max (default e.g. 64 MB)
+  to bound parse cost.
+- **Sanitization at the boundary.** Every `name`/`description` is sanitized on load:
+  truncate to **256 chars**, strip control characters and newlines, and **neutralize `%` tokens**
+  (so they cannot inject into `String.replace` placeholder chains, server- or wired-side).
+  Normal text/emoji/non-latin scripts pass through.
+- **Fail-safe.** Any IO/parse error is caught and logged; the provider keeps the **last-good
+  index** (or empty on first load) and never throws — boot must not crash on a bad furnidata.
+
+### 4.2 `FurnitureTextProvider` (new, package `items`)
+
+- Holds `volatile Map<String /*classname lowercase*/, FurniText {int id, String name, String description}>`.
+- `reindex()`: read via `FurnidataReader` → build a new immutable map → compute delta vs the
+  previous map (§5) → atomically swap the reference → return the delta.
+- Initialized in `GameEnvironment.load` near `ItemManager`. Resolution is **lazy**, so boot order
+  is not critical and `Item` objects do not depend on the provider at load time.
+- Toggle `items.furnidata.names.enabled` (default `true`). When `false`, `getDisplayName()`
+  returns the DB value (instant rollback, no recompile).
+
+### 4.3 `Item.getDisplayName()`
+
+```
+String getDisplayName():
+    if !enabled: return fullName
+    FurniText t = FurnitureTextProvider.get(this.name /* classname, lowercased */)
+    return (t != null && t.name not blank) ? t.name : this.fullName   // never null
+```
+
+No `getDescription()` on the server (no consumer).
+
+### 4.4 Swap list (exhaustive — verified)
+
+Replace `item.getFullName()` → `item.getDisplayName()` at exactly these 6 sites:
+
+| Site | Context |
+|---|---|
+| `CatalogBuyItemAsGiftEvent.java:251` | LTD daily-total alert (gift) |
+| `CatalogBuyItemAsGiftEvent.java:262` | LTD daily-item alert (gift) |
+| `CatalogManager.java:1057` | LTD daily-total alert (buy) |
+| `CatalogManager.java:1063` | LTD daily-item alert (buy) |
+| `WiredTextPlaceholderUtil.java:282` | wired `%furni.name%` (keep existing `getName()` ultimate fallback) |
+| `WatchAndEarnRewardComposer.java:21` | `appendString(...)` — sends name in a packet |
+
+**Do NOT change** (technical, use `item_name`/classname): `PresentItemOpenedComposer:24`,
+`GiftCommand:72`, `SendGift:82`, `SellItemEvent:37,45`, `CloseDiceEvent:34`, `isPet/isBot`, and the
+wired `wf_` fallback in `Item.load`. The catalog offer/page serialization sends **no** display
+name (`CatalogItem` serializes `catalog_name` + sprite only) — confirmed, nothing to change there.
+
+## 5. Piece 2 — Liveness via delta
+
+### 5.1 Server: file watcher + diff + broadcast
+
+- A `WatchService` watches the resolved furnidata location on a **single, serialized watcher
+  thread** (so reindex never races itself). For the **split-tier** layout, register the base dir
+  and each tier dir. **Debounce** (~750 ms) to coalesce burst writes, plus a **minimum interval
+  between broadcasts** (e.g. ≥5 s) to cap amplification.
+- On settle → `FurnitureTextProvider.reindex()` → diff old vs new **by classname**:
+  - **added** (new classname) and **changed** (name **or** description differs) → included.
+  - **removed** classnames → **ignored** (rare; resolved on client reconnect).
+- Broadcast decision (anti-DoS):
+  - delta empty → no broadcast.
+  - delta size ≤ **cap** (e.g. 500 entries) → broadcast `FurnitureDataReload` in **delta mode**.
+  - delta size > cap (mass replace) → broadcast in **reload-hint mode** (compact signal; clients
+    re-load furnidata at next opportunity) instead of a giant per-client payload.
+- The broadcast is triggered **only** by the file watcher — there is **no client-initiated reload
+  path**. This is a security property to preserve (clients cannot induce reindex/broadcast).
+
+### 5.2 Wire contract — new packet `FurnitureDataReload`
+
+- **Composer (Arcturus):** `FurnitureDataReloadComposer`, new dedicated header id (pick a free id;
+  document on both sides). Two modes:
+  ```
+  int   mode           // 0 = delta, 1 = reload-hint
+  // mode == 0 (delta):
+  int   count          // bounded by the server cap; the client MUST also bound it on read
+  count × {
+    string type        // "S" (floor) | "I" (wall)
+    int    id           // furnidata numeric id (for localization-key + FurnitureData lookup)
+    string classname
+    string name         // already sanitized server-side
+    string description
+  }
+  // mode == 1 (reload-hint): no further fields (optionally an int revision for cache-busting)
+  ```
+- **Parser/Event (renderer):** `FurnitureDataReloadEvent` + `FurnitureDataReloadParser` reading the
+  same shape. The parser **bounds `count`** (reject/clamp absurd values) and tolerates truncation
+  (`bytesAvailable` pattern) so a malformed/MITM payload cannot allocate unbounded memory.
+  Registered in `SessionDataManager.init()` via
+  `GetCommunication().registerMessageEvent(new FurnitureDataReloadEvent(...))` (same pattern as the
+  existing `FurniDataUpdatedEvent` registration, but a **distinct** handler).
+
+### 5.3 Renderer: separate patch path (no editor reuse)
+
+- New method, e.g. `SessionDataManager.applyFurnidataDelta(entries)` — **distinct** from the
+  editor's `applyLiveFurnitureNameUpdate(...)` (`SessionDataManager.ts:84`), which we leave intact.
+- **Delta mode (0):** for each entry, patch the corresponding `FurnitureData` (floor/wall, by `id`)
+  — update `_localizedName` and `_description` — and re-register the localization keys
+  `roomItem.name/desc.{id}` / `wallItem.name/desc.{id}` (mirrors `FurnitureDataLoader:105-110`).
+- **Reload-hint mode (1):** re-run the furnidata load (`FurnitureDataLoader`, re-fetching
+  `furnidata.url` with cache-bust) — the appropriate response to a mass change.
+- In both modes, after the batch dispatch the window event **once**:
+  `window.dispatchEvent(new CustomEvent('nitro-localization-updated'))`.
+
+### 5.4 Client: zero changes
+
+All three furni surfaces already subscribe to `nitro-localization-updated` and re-derive:
+
+- catalog — `useCatalog.ts:919`
+- inventory — `useInventoryFurni.ts:137` (→ `refreshGroupItemsLocalization`)
+- infostand — `useAvatarInfoWidget.ts:425` (→ `getFurniInfo`, which reads `furnitureData.name`)
+
+No Nitro-V3 edits are required for Piece 2.
+
+## 6. Admin-facing outcome
+
+Edit one place — the **furnidata JSON** — and display names update **live** across:
+server-pronounced strings (catalog LTD alerts, wired `%furni.name%`, Watch&Earn), and every
+connected client's catalog, inventory, and furni infostand. No DB edit, no restart, no double
+maintenance.
+
+## 7. Constraints, risks, invariants
+
+1. **Locale no-clobber.** If per-locale furni text override files are in use (they override
+   `roomItem.name.{id}` after furnidata load), a live delta that re-registers base names would
+   revert overridden ids to base. Mitigation options for the plan: re-apply active overrides after
+   the delta, or skip the localization-key patch for ids with an active override (still patch the
+   `FurnitureData` object). For single-furnidata setups (typical retro) there is no override and no
+   issue. **Document the limitation.**
+2. **Deploy invariant.** `furni.editor.asset.base.path`/`furnidata.url` (what the emulator watches)
+   and the furnidata the client loaded must be the **same artifact**, else the server delta
+   references entries the client doesn't have.
+3. **`public_name` fallback.** Wired `wf_` items absent from furnidata would show the raw `wf_…`
+   token as their display name (internal/invisible furni — acceptable).
+4. **Split-layout watcher.** The watcher must register all tier dirs; missing a tier dir means live
+   updates from that tier are not detected (resolved on reconnect).
+5. **Performance.** `getDisplayName()` is a single `HashMap` lookup on cold paths (catalog alerts,
+   wired text, Watch&Earn) — negligible.
+
+## 8. Security
+
+With this refactor the **furnidata becomes a security-relevant input**: its strings now flow into
+server output (catalog LTD alerts, wired `%furni.name%`, the Watch&Earn packet) and into a
+broadcast to every connected client. Regular players cannot influence names (names are admin-owned,
+keyed by classname); the threat is **untrusted furnidata content** (third-party furni packs,
+imports, a compromised editor/supply chain). Controls:
+
+1. **Boundary sanitization** (see §4.1): cap 256 chars, strip control/newline, **neutralize `%`**.
+   Neutralizing `%` at load makes every `String.replace("%itemname%", name)` /
+   `%furni.name%` site injection-safe; as defense-in-depth, substitute the (untrusted) furni name
+   **last** in any placeholder chain.
+2. **Path-traversal guard** in the shared reader (§4.1) — reject manifest paths escaping the base
+   dir. Closes a gap the current editor reader does not cover.
+3. **DoS / amplification controls** (§5.1): single serialized watcher thread, debounce + minimum
+   broadcast interval, delta-size cap with **reload-hint fallback** for mass changes, furnidata
+   file-size cap.
+4. **Fail-safe loading** (§4.1): bad/corrupt furnidata never crashes boot; last-good index is kept;
+   `getDisplayName()` falls back to `public_name`.
+5. **Robust client parser** (§5.2): bound `count`, tolerate truncation — a malformed/MITM
+   `FurnitureDataReload` cannot allocate unbounded memory client-side.
+6. **No client-triggered reload** (§5.1): only the file watcher broadcasts. Do not add any
+   client→server reload request. Preserve this property.
+7. **Minimal disclosure**: the delta carries **only** `name`/`description` (already public via
+   furnidata) — never other fields from the server-side file.
+8. **Concurrency**: `volatile` index reference + atomic swap + single reindex thread → no torn reads.
+
+## 9. Testing
+
+- **Emulator (JUnit):** `FurnidataReader` parses single-file and split-tier (JSON5, tier override);
+  `FurnitureTextProvider` lookup by lowercased classname, **fallback to `public_name`** when absent,
+  atomic reindex; `reindex()` diff produces correct added/changed delta and ignores removals;
+  `Item.getDisplayName()` honors the enable toggle.
+- **Renderer (Vitest):** `FurnitureDataReloadParser` reads the payload shape; `applyFurnidataDelta`
+  patches floor/wall `FurnitureData` by id, re-registers localization keys, dispatches
+  `nitro-localization-updated` once.
+- **Client (Vitest):** existing subscribers (`useCatalog`, `useInventoryFurni`, `useAvatarInfoWidget`)
+  refresh on `nitro-localization-updated` (regression guard; no new code).
+- **Manual acceptance:** edit a furni name in furnidata → live update in catalog + inventory +
+  infostand without refresh; a wired `%furni.name%` sign and a Watch&Earn reward show the new name.
+- **Security tests:** reader rejects a split-tier manifest with `../` traversal; a name containing
+  `%limit%`/`%user.name%` does not inject into catalog alerts or wired text (`%` neutralized);
+  oversized furnidata is refused; corrupt furnidata keeps last-good index and does not crash;
+  a mass change emits a reload-hint (not a giant delta); the client parser clamps an absurd `count`.
+
+## 10. Open questions
+
+- Free header id for `FurnitureDataReload` (assign during implementation; document both sides).
+- Whether any retro on this stack actually ships per-locale furni override files (governs whether
+  constraint §7.1 is live or moot).