@linxin666/dsh-pet 0.2.2 → 0.2.4

package/src/routes.ts

@@ -9,15 +9,16 @@
  * @module @linxin666/dsh-pet/routes
  */
 
-import { existsSync } from 'node:fs'
+import { existsSync, realpathSync, statSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { join, sep } from 'node:path'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import type { PetService } from './service.ts'
 import type { PetInteraction } from './affinity.ts'
-import { petEntryView, type PetEntry, type PetRegistry } from './registry.ts'
+import { DECORATION_ASSET_PREFIX, petEntryView, petPackageRoot, type PetEntry, type PetRegistry } from './registry.ts'
 import { isLoopbackRequest } from './loopback.ts'
+import { dshHome } from './dsh-home.ts'
 
 /** Browser-facing base path of the pet API. */
 export const PET_API_PREFIX = '/api/pet'
@@ -29,6 +30,53 @@ const MANIFEST_FILE = 'pet.json'
 const PREVIEW_DIR = 'previews'
 const PREVIEW_PATTERN = /^[A-Za-z0-9._-]+$/
 
+/**
+ * Per-class size ceilings for served pet assets, in bytes (pet-center M2 P3,
+ * issue #623). Constants are tested directly; makePetRoutes accepts an
+ * override so tests can exercise the 413 path with tiny caps.
+ */
+export const PET_ASSET_CAPS = {
+  /** pet.json manifest. */
+  manifest: 64 * 1024,
+  /** Atlas, preview and Live2D texture imagery. */
+  image: 20 * 1024 * 1024,
+  /** Live2D model closure files (.moc3, motion/physics/expression JSON; M3). */
+  model: 32 * 1024 * 1024,
+} as const
+
+/** Size-cap profile the asset route enforces (test seam). */
+export interface PetAssetCaps {
+  manifest: number
+  image: number
+  model: number
+}
+
+/** Imagery extensions classify into the image cap; everything else served from a closure is model-class. */
+const IMAGE_EXTENSIONS: ReadonlySet<string> = new Set(['.webp', '.png', '.gif', '.jpg', '.jpeg'])
+
+/** Lowercased file extension ('' when none). */
+function extensionOf(file: string): string {
+  const dot = file.lastIndexOf('.')
+  return dot < 0 ? '' : file.slice(dot).toLowerCase()
+}
+
+/**
+ * realpath containment: resolve both sides and require the candidate to stay
+ * inside the base directory. A pet directory (or an atlas/preview inside it)
+ * that is a symlink escaping its root is rejected, never followed.
+ */
+export function containedRealpath(base: string, candidate: string): string | undefined {
+  try {
+    const realBase = realpathSync(base)
+    const realCandidate = realpathSync(candidate)
+    return realCandidate === realBase || realCandidate.startsWith(realBase + sep)
+      ? realCandidate
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
 const MIME_BY_EXT: Readonly<Record<string, string>> = {
   '.webp': 'image/webp',
   '.png': 'image/png',
@@ -145,10 +193,14 @@ function dirAliases(registry: PetRegistry): Map<string, PetEntry> {
 /**
  * The one asset handler behind the '/pet' prefix. Resolves the pet by id (or
  * legacy directory alias), then serves exactly the files a manifest declares:
- * pet.json, the declared spritesheet path, and optional 'previews/<name>'
- * media. Composed pets without a manifest file get a synthesized pet.json.
+ * pet.json, the entry's servable set (the sprite2d atlas, or the live2d
+ * model3.json plus its reference closure — pet-center M3), and optional
+ * 'previews/<name>' media. The servable match is an exact string comparison
+ * against scan-time normalized paths, so crafted '..' or '.' segments never
+ * match; containedRealpath stays as the second layer. Composed pets without
+ * a manifest file get a synthesized pet.json.
  */
-function assetHandler(registry: PetRegistry): WebRoute['handler'] {
+function assetHandler(registry: PetRegistry, caps: PetAssetCaps): WebRoute['handler'] {
   const aliases = dirAliases(registry)
   return (req: IncomingMessage, res: ServerResponse): void => {
     if (!guard(req, res)) return
@@ -204,14 +256,14 @@ function assetHandler(registry: PetRegistry): WebRoute['handler'] {
       const manifestFile = join(entry.dir, MANIFEST_FILE)
       file = existsSync(manifestFile) ? manifestFile : undefined
       if (file === undefined) synthesized = true
-    } else if (rest.length > 0 && rel === entry.spritesheetPath) {
-      file = join(entry.dir, entry.spritesheetPath)
+    } else if (rest.length > 0 && entry.servable.includes(rel)) {
+      file = join(entry.dir, rel)
     } else if (rest.length === 2 && rest[0] === PREVIEW_DIR && PREVIEW_PATTERN.test(rest[1]!)) {
       const preview = join(entry.dir, PREVIEW_DIR, rest[1]!)
       file = existsSync(preview) ? preview : undefined
     }
     if (synthesized) {
-      const body = Buffer.from(JSON.stringify(petEntryView(entry), null, 2), 'utf8')
+      const body = Buffer.from(JSON.stringify(petEntryView(entry, registry.globalVoice), null, 2), 'utf8')
       res.writeHead(200, {
         'content-type': 'application/json; charset=utf-8',
         'content-length': String(body.byteLength),
@@ -229,12 +281,258 @@ function assetHandler(registry: PetRegistry): WebRoute['handler'] {
       res.end()
       return
     }
-    const resolved = file
+    // realpath containment: a symlink escaping the pet directory is refused.
+    const resolved = containedRealpath(entry.dir, file)
+    if (resolved === undefined) {
+      res.writeHead(403)
+      res.end()
+      return
+    }
+    // Enforce the size ceiling before the file is read into memory.
+    const cap = rest.length === 1 && rest[0] === MANIFEST_FILE
+      ? caps.manifest
+      : IMAGE_EXTENSIONS.has(extensionOf(rel)) ? caps.image : caps.model
+    try {
+      if (statSync(resolved).size > cap) {
+        res.writeHead(413)
+        res.end()
+        return
+      }
+    } catch {
+      res.writeHead(404)
+      res.end()
+      return
+    }
+    readFile(resolved).then((body) => {
+      res.writeHead(200, {
+        'content-type': mimeFor(resolved),
+        'content-length': String(body.byteLength),
+        'cache-control': 'no-cache',
+      })
+      if (req.method === 'HEAD') {
+        res.end()
+        return
+      }
+      res.end(body)
+    }, () => {
+      res.writeHead(404)
+      res.end()
+    })
+  }
+}
+
+/** Browser-facing base path of the plugin runtime files (pet-center M3). */
+export const PET_RUNTIME_PREFIX = PET_API_PREFIX + '/runtime'
+
+/**
+ * The runtime files the route may serve, by exact name (no slashes, no
+ * user-controlled path segments, so traversal is structurally impossible):
+ * the user-supplied Cubism Core from the pet runtime directory (the plugin
+ * never bundles or downloads it — issue #623 M1 §0) and the plugin-shipped
+ * MIT vendor bundle from the package lib directory.
+ */
+const RUNTIME_FILES: Readonly<Record<string, { root: 'runtimeDir' | 'vendorDir' }>> = {
+  'live2dcubismcore.min.js': { root: 'runtimeDir' },
+  'live2d-vendor.js': { root: 'vendorDir' },
+  'live2d-vendor.js.map': { root: 'vendorDir' },
+}
+
+/** Size ceiling for one runtime file (the Cubism Core is ~200 KB today). */
+export const PET_RUNTIME_CAP = 16 * 1024 * 1024
+
+/** Runtime file roots (test seam; defaults resolve from the environment). */
+export interface PetRuntimeRoots {
+  /** User-supplied runtime directory (defaults to '$DSH_HOME/pets/.runtime'). */
+  runtimeDir?: string
+  /** Plugin vendor bundle directory (defaults to the package 'lib'). */
+  vendorDir?: string
+}
+
+/**
+ * The runtime handler behind '/api/pet/runtime/<name>'. A missing file
+ * answers 404 with a JSON marker the client renderer turns into install
+ * guidance (the Cubism Core is user-supplied, so its absence is a normal
+ * state, not an error).
+ */
+function runtimeHandler(roots: { runtimeDir: string; vendorDir: string }): WebRoute['handler'] {
+  return (req: IncomingMessage, res: ServerResponse): void => {
+    if (!guard(req, res)) return
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.writeHead(405)
+      res.end()
+      return
+    }
+    let pathname: string
+    try {
+      pathname = new URL(req.url ?? '/', 'http://pet.local').pathname
+    } catch {
+      res.writeHead(400)
+      res.end()
+      return
+    }
+    const rest = pathname.slice(PET_RUNTIME_PREFIX.length).replace(/^\/+/, '')
+    let name: string
+    try {
+      name = decodeURIComponent(rest)
+    } catch {
+      res.writeHead(400)
+      res.end()
+      return
+    }
+    const spec = RUNTIME_FILES[name]
+    // Exact-name allow-list: anything with a path separator never matches.
+    if (spec === undefined) {
+      res.writeHead(404)
+      res.end()
+      return
+    }
+    const base = spec.root === 'runtimeDir' ? roots.runtimeDir : roots.vendorDir
+    const file = join(base, name)
+    if (!existsSync(file)) {
+      json(res, 404, { ok: false, error: 'runtime-file-missing', file: name })
+      return
+    }
+    const resolved = containedRealpath(base, file)
+    if (resolved === undefined) {
+      res.writeHead(403)
+      res.end()
+      return
+    }
+    try {
+      if (statSync(resolved).size > PET_RUNTIME_CAP) {
+        res.writeHead(413)
+        res.end()
+        return
+      }
+    } catch {
+      res.writeHead(404)
+      res.end()
+      return
+    }
+    readFile(resolved).then((body) => {
+      res.writeHead(200, {
+        'content-type': name.endsWith('.map') ? 'application/json' : 'application/javascript; charset=utf-8',
+        'content-length': String(body.byteLength),
+        'cache-control': 'no-cache',
+      })
+      if (req.method === 'HEAD') {
+        res.end()
+        return
+      }
+      res.end(body)
+    }, () => {
+      res.writeHead(404)
+      res.end()
+    })
+  }
+}
+
+/**
+ * The decoration asset handler behind '/api/pet/decoration/<id>/<file>'
+ * (pet-center M5, #567). Serves exactly the files a decoration descriptor
+ * declares — decoration.json and the PNG/WebP strip — by exact allow-list
+ * match, with realpath containment and the same size ceilings as pet
+ * assets. Crafted '..' or '.' segments never match the normalized closure.
+ */
+function decorationHandler(registry: PetRegistry, caps: PetAssetCaps): WebRoute['handler'] {
+  return (req: IncomingMessage, res: ServerResponse): void => {
+    if (!guard(req, res)) return
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.writeHead(405)
+      res.end()
+      return
+    }
+    let pathname: string
+    try {
+      pathname = new URL(req.url ?? '/', 'http://pet.local').pathname
+    } catch {
+      res.writeHead(400)
+      res.end()
+      return
+    }
+    const segments = pathname.split('/').filter(segment => segment !== '')
+    const prefixSegments = DECORATION_ASSET_PREFIX.split('/').filter(segment => segment !== '')
+    if (segments.length < prefixSegments.length + 2) {
+      res.writeHead(404)
+      res.end()
+      return
+    }
+    for (let i = 0; i < prefixSegments.length; i += 1) {
+      if (segments[i] !== prefixSegments[i]) {
+        res.writeHead(404)
+        res.end()
+        return
+      }
+    }
+    let id: string
+    try {
+      id = decodeURIComponent(segments[prefixSegments.length])
+    } catch {
+      res.writeHead(400)
+      res.end()
+      return
+    }
+    const entry = registry.decorationById?.(id)
+    if (entry === undefined) {
+      res.writeHead(404)
+      res.end()
+      return
+    }
+    const rest: string[] = []
+    for (const segment of segments.slice(prefixSegments.length + 1)) {
+      let decoded: string
+      try {
+        decoded = decodeURIComponent(segment)
+      } catch {
+        res.writeHead(400)
+        res.end()
+        return
+      }
+      rest.push(decoded)
+    }
+    const rel = rest.join('/')
+    if (!entry.servable.includes(rel)) {
+      res.writeHead(404)
+      res.end()
+      return
+    }
+    const file = join(entry.dir, rel)
+    const resolved = containedRealpath(entry.dir, file)
+    if (resolved === undefined) {
+      res.writeHead(403)
+      res.end()
+      return
+    }
+    const cap = rel === 'decoration.json' ? caps.manifest : caps.image
+    let stat: ReturnType<typeof statSync>
+    try {
+      stat = statSync(resolved)
+      if (stat.size > cap) {
+        res.writeHead(413)
+        res.end()
+        return
+      }
+    } catch {
+      res.writeHead(404)
+      res.end()
+      return
+    }
+    // Weak ETag from size + mtime: 'no-cache' forces revalidation, and the
+    // validator lets repeat requests settle as 304 — the ornament remounts
+    // on whisper and display-session flips, and without a validator each
+    // remount would re-download the full strip body.
+    const etag = '"' + stat.size.toString(16) + '-' + Math.round(stat.mtimeMs).toString(16) + '"'
+    if (req.headers['if-none-match'] === etag) {
+      res.writeHead(304, { etag, 'cache-control': 'no-cache' })
+      res.end()
+      return
+    }
     readFile(resolved).then((body) => {
       res.writeHead(200, {
         'content-type': mimeFor(resolved),
         'content-length': String(body.byteLength),
         'cache-control': 'no-cache',
+        etag,
       })
       if (req.method === 'HEAD') {
         res.end()
@@ -248,12 +546,13 @@ function assetHandler(registry: PetRegistry): WebRoute['handler'] {
   }
 }
 
-/** Build the full route family (API + assets) for one service. */
-export function makePetRoutes(deps: { service: PetService }): WebRoute[] {
+/** Build the full route family (API + assets + runtime) for one service. */
+export function makePetRoutes(deps: { service: PetService; assetCaps?: PetAssetCaps } & PetRuntimeRoots): WebRoute[] {
   const { service } = deps
   const apiRoutes: WebRoute[] = [
     getRoute(PET_API_PREFIX + '/state', () => service.state()),
     getRoute(PET_API_PREFIX + '/pets', () => service.pets()),
+    getRoute(PET_API_PREFIX + '/diagnostics', () => service.diagnostics()),
     postRoute(PET_API_PREFIX + '/interact', (body) => {
       const kind = body.kind as PetInteraction | undefined
       if (kind !== 'pet' && kind !== 'feed') return Promise.reject(new Error('invalid-kind'))
@@ -285,10 +584,25 @@ export function makePetRoutes(deps: { service: PetService }): WebRoute[] {
   const assetRoute: WebRoute = {
     kind: 'prefix',
     path: PET_ASSET_PREFIX,
-    handler: assetHandler(service.registrySnapshot()),
+    handler: assetHandler(service.registrySnapshot(), deps.assetCaps ?? PET_ASSET_CAPS),
+  }
+
+  const runtimeRoute: WebRoute = {
+    kind: 'prefix',
+    path: PET_RUNTIME_PREFIX,
+    handler: runtimeHandler({
+      runtimeDir: deps.runtimeDir ?? join(dshHome(), 'pets', '.runtime'),
+      vendorDir: deps.vendorDir ?? join(petPackageRoot(import.meta.url), 'lib'),
+    }),
+  }
+
+  const decorationRoute: WebRoute = {
+    kind: 'prefix',
+    path: DECORATION_ASSET_PREFIX,
+    handler: decorationHandler(service.registrySnapshot(), deps.assetCaps ?? PET_ASSET_CAPS),
   }
 
-  return [...apiRoutes, assetRoute]
+  return [...apiRoutes, assetRoute, runtimeRoute, decorationRoute]
 }
 
 // Re-exported for the package surface (the registry owns the definition now).

package/src/service.ts

@@ -36,14 +36,19 @@ import {
   type PetDisplayConfig,
 } from './persist.ts'
 import {
+  DEFAULT_DECORATION_ID,
+  decorationView,
   loadPetRegistry,
   petEntryView,
   petPackageRoot,
   type PetDefinition,
   type PetManifest,
   type PetRegistry,
+  type PetRegistryDiagnostic,
 } from './registry.ts'
-import { WHISPER_TTL_MS } from './chatter.ts'
+import { WHISPER_TTL_MS, type VoicePackOverrides, type VoicePoolsProvider } from './chatter.ts'
+import { mergeVoicePacks } from './voice-pack.ts'
+import type { DecorationView } from './contracts/status-decoration.ts'
 import {
   defaultPetStateConfig,
   PetStateMachine,
@@ -64,6 +69,8 @@ export interface PetConfig {
   persistDir?: string
   /** Master switch for the plugin (browser half + host routes). */
   enabled?: boolean
+  /** Status-decoration master switch (pet-center M5, #567); defaults to on. */
+  decorationEnabled?: boolean
   /** Prebuilt registry (tests); defaults to scanning the package + user dirs. */
   registry?: PetRegistry
   /** Extra manifest entries composed by the embedding application. */
@@ -90,6 +97,11 @@ export interface PetSettingsSection {
   bottom: number
   /** Master switch for the plugin (browser half + host routes). */
   enabled?: boolean
+  /**
+   * Status-decoration master switch (pet-center M5, #567). Defaults to on;
+   * the settings surface mirrors this field and can turn it off.
+   */
+  decorationEnabled?: boolean
 }
 
 /** Settings namespace of the pet capability. Spelled here rather than imported: the browser half spells the same value. */
@@ -158,6 +170,12 @@ export interface PetStateView {
    * rendered by the client as a distinct whisper bubble.
    */
   whisper?: string
+  /**
+   * The active status decoration (pet-center M5, #567), when the master
+   * switch is on and the default decoration entry exists. Absent means the
+   * browser half renders no ornament.
+   */
+  decoration?: DecorationView
 }
 
 /** Result of `pet.interact`. */
@@ -199,9 +217,17 @@ export class PetService extends Service {
   private readonly registry: PetRegistry
   private readonly persistDir: string
   private enabled: boolean
+  /** Status-decoration master switch (M5, #567); mirrored from settings. */
+  private decorationEnabled: boolean
   private disposeActivity: (() => void) | undefined
   /** Session whose most recent meaningful event currently drives the global pet. */
   private displaySession: Session | undefined
+  /**
+   * Effective voice-pack overrides for the currently selected pet (M4,
+   * #677). Cached per pet id; the registry is an immutable snapshot, so the
+   * global pack and each entry's pack cannot change behind the cache.
+   */
+  private voiceCache: { petId: string; overrides: VoicePackOverrides } | undefined
   /**
    * Per-session activity, most recent last (Map insertion order). Bounded by
    * MAX_SESSION_BUBBLES so a burst of sessions cannot grow it without bound;
@@ -236,10 +262,28 @@ export class PetService extends Service {
     this.stateConfig = { ...defaultPetStateConfig, ...(config.state ?? {}) }
     this.machine = new PetStateMachine(this.stateConfig)
     this.enabled = config.enabled ?? true
+    this.decorationEnabled = config.decorationEnabled ?? true
 
     this.syncActivity()
   }
 
+  /**
+   * The draw-time voice-pool provider handed to every projection runtime.
+   * It re-resolves when the selected pet changes, so live engines re-voice
+   * on the next draw without being rebuilt (M4, #677).
+   */
+  private voicePools(): VoicePoolsProvider {
+    return () => {
+      const entry = this.activeEntry()
+      if (this.voiceCache !== undefined && this.voiceCache.petId === entry.id) {
+        return this.voiceCache.overrides
+      }
+      const overrides = mergeVoicePacks(this.registry.globalVoice, entry.voice)?.overrides ?? {}
+      this.voiceCache = { petId: entry.id, overrides }
+      return overrides
+    }
+  }
+
   /** Whether the pet service consumes session activity while enabled. */
   isEnabled(): boolean {
     return this.enabled
@@ -257,7 +301,7 @@ export class PetService extends Service {
 
   /** RPC: the registry entries the browser half renders and selects from. */
   async pets(): Promise<PetDefinition[]> {
-    return this.registry.entries.map(petEntryView)
+    return this.registry.entries.map(entry => petEntryView(entry, this.registry.globalVoice))
   }
 
   /** The loaded registry (the asset routes serve its entries). */
@@ -265,6 +309,21 @@ export class PetService extends Service {
     return this.registry
   }
 
+  /** RPC: structured registry diagnostics (pet-center M2, issue #623). */
+  async diagnostics(): Promise<{ diagnostics: PetRegistryDiagnostic[] }> {
+    return { diagnostics: this.registry.diagnostics }
+  }
+
+  /**
+   * The active status decoration view (M5, #567): the default 'whale' entry
+   * (user directories override built-ins by id), gated by the master switch.
+   */
+  private activeDecoration(): DecorationView | undefined {
+    if (!this.decorationEnabled) return undefined
+    const entry = this.registry.decorationById?.(DEFAULT_DECORATION_ID)
+    return entry === undefined ? undefined : decorationView(entry)
+  }
+
   /** The selected pet's registry entry. */
   activeEntry(): NonNullable<PetRegistry['entries'][number]> {
     return this.registry.byId(this.selectedPetId()) ?? this.registry.defaultEntry()
@@ -364,7 +423,7 @@ export class PetService extends Service {
     let activity = this.sessionActivity.get(session)
     if (activity === undefined) {
       activity = {
-        runtime: emptyProjectionRuntime(),
+        runtime: emptyProjectionRuntime(this.voicePools()),
         machine: new PetStateMachine(this.stateConfig),
       }
       this.sessionActivity.set(session, activity)
@@ -443,6 +502,7 @@ export class PetService extends Service {
    * @param section - the resolved settings section.
    */
   applySettingsSection(section: PetSettingsSection): void {
+    this.decorationEnabled = section.decorationEnabled ?? true
     const selected = typeof section.petId === 'string' ? this.registry.byId(section.petId) : undefined
     if (selected !== undefined) {
       this.ledger.setPetId(selected.id)
@@ -518,6 +578,7 @@ export class PetService extends Service {
     const freshWhisper = whisper !== undefined && Date.now() - whisper.at < WHISPER_TTL_MS
       ? whisper.text
       : undefined
+    const decoration = this.activeDecoration()
     // Read-only: the ledger settles on economic events only, never on a read,
     // so polling the state cannot trigger pet.json writes.
     return {
@@ -527,6 +588,7 @@ export class PetService extends Service {
       sessionActive: snapshot.sessionActive,
       sessions,
       ...(freshWhisper === undefined ? {} : { whisper: freshWhisper }),
+      ...(decoration === undefined ? {} : { decoration }),
       affinity: this.ledger.affinityView(Date.now()),
       display: { ...this.ledger.snapshot.display },
       pet: {