@goodandready/dsh-image-gen 0.10.30 → 0.10.32

package/lib/fallback-router.js

@@ -0,0 +1,163 @@
+// fallback-router.js — Smart Provider Fallback Chain for image generation (#282).
+// Automatically cascades across configured providers on 429, 5xx, timeouts,
+// quota depletion, and network issues without failing the user's turn.
+
+import { formatErrorMessage } from './provider-utils.js'
+
+/**
+ * Checks if an error is strictly a prompt-level safety or client syntax violation
+ * that cannot be fixed by switching to a different provider.
+ *
+ * @param {Error|any} error
+ * @returns {boolean} true if fatal prompt/content violation, false if provider-level retryable
+ */
+export function isFatalPromptError(error) {
+  const msg = (error?.message || String(error || '')).toLowerCase()
+  return (
+    msg.includes('content policy') ||
+    msg.includes('safety system') ||
+    msg.includes('nsfw') ||
+    msg.includes('moderation') ||
+    msg.includes('prompt is required') ||
+    msg.includes('empty prompt') ||
+    msg.includes('invalid_prompt') ||
+    msg.includes('unsupported image format')
+  )
+}
+
+/**
+ * Checks whether an error is retryable by switching to another provider.
+ * Covers 429 (rate limit), 5xx (server error), timeout, payment/quota depletion, and network dropouts.
+ *
+ * @param {Error|any} error
+ * @returns {boolean}
+ */
+export function isRetryableProviderError(error) {
+  if (isFatalPromptError(error)) return false
+  const msg = (error?.message || String(error || '')).toLowerCase()
+  return (
+    msg.includes('429') ||
+    msg.includes('rate limit') ||
+    msg.includes('too many requests') ||
+    msg.includes('500') ||
+    msg.includes('502') ||
+    msg.includes('503') ||
+    msg.includes('504') ||
+    msg.includes('bad gateway') ||
+    msg.includes('service unavailable') ||
+    msg.includes('gateway timeout') ||
+    msg.includes('timeout') ||
+    msg.includes('timed out') ||
+    msg.includes('aborted') ||
+    msg.includes('402') ||
+    msg.includes('payment required') ||
+    msg.includes('insufficient_quota') ||
+    msg.includes('insufficient credits') ||
+    msg.includes('exceeded your current quota') ||
+    msg.includes('balance is insufficient') ||
+    msg.includes('quota') ||
+    msg.includes('credit') ||
+    msg.includes('unauthorized') ||
+    msg.includes('401') ||
+    msg.includes('invalid api key') ||
+    msg.includes('econnrefused') ||
+    msg.includes('enotfound') ||
+    msg.includes('fetch failed') ||
+    msg.includes('network')
+  )
+}
+
+/**
+ * Resolves the candidate evaluation order:
+ * Primary provider first, followed by explicit fallbackProviders, then remaining known providers.
+ *
+ * @param {string} primary
+ * @param {string[]} [configuredFallbacks=[]]
+ * @param {string[]} [allProviders=[]]
+ * @returns {string[]}
+ */
+export function resolveFallbackChain(primary, configuredFallbacks = [], allProviders = []) {
+  const chain = [primary]
+  if (Array.isArray(configuredFallbacks)) {
+    for (const p of configuredFallbacks) {
+      if (typeof p === 'string' && p.trim() && !chain.includes(p.trim())) {
+        chain.push(p.trim())
+      }
+    }
+  }
+  if (Array.isArray(allProviders)) {
+    for (const p of allProviders) {
+      if (typeof p === 'string' && p.trim() && !chain.includes(p.trim())) {
+        chain.push(p.trim())
+      }
+    }
+  }
+  return chain
+}
+
+/**
+ * Executes image generation across a cascade of providers with full attempt diagnostics.
+ *
+ * @param {Record<string, (seed: number, prompt: string) => Promise<any>>} generators
+ * @param {string[]} chain Ordered list of providers to try
+ * @param {number} seed
+ * @param {string} prompt
+ * @param {object} [options]
+ * @returns {Promise<any>} Produced image with attached _fallback metadata
+ */
+export async function executeWithFallback(generators, chain, seed, prompt, options = {}) {
+  const attempts = []
+  const primaryProvider = chain[0] || 'unknown'
+  const logger = options.logger || null
+
+  for (let i = 0; i < chain.length; i++) {
+    const providerKey = chain[i]
+    const generator = generators[providerKey]
+    if (typeof generator !== 'function') {
+      continue
+    }
+
+    const startTime = Date.now()
+    try {
+      const produced = await generator(seed, prompt)
+      if (produced) {
+        const isFallback = providerKey !== primaryProvider
+        produced._fallback = {
+          triggered: isFallback,
+          primaryProvider,
+          providerUsed: providerKey,
+          attempts: [
+            ...attempts,
+            { provider: providerKey, durationMs: Date.now() - startTime, success: true },
+          ],
+        }
+        if (isFallback && logger && typeof logger.info === 'function') {
+          logger.info(`[dsh-image-gen] Fallback triggered: ${primaryProvider} -> ${providerKey}`)
+        }
+        return produced
+      }
+    } catch (err) {
+      const durationMs = Date.now() - startTime
+      const formatted = formatErrorMessage(err, providerKey)
+      attempts.push({
+        provider: providerKey,
+        error: formatted,
+        durationMs,
+        success: false,
+      })
+
+      if (isFatalPromptError(err)) {
+        throw new Error(`Content or policy error on ${providerKey} (not cascading): ${formatted}`)
+      }
+
+      if (logger && typeof logger.warn === 'function') {
+        logger.warn(`[dsh-image-gen] Provider ${providerKey} failed: ${formatted}. Trying next candidate...`)
+      }
+    }
+  }
+
+  const failureSummary = attempts
+    .map((a) => `${a.provider} (${a.durationMs}ms): ${a.error}`)
+    .join('; ')
+  throw new Error(`Image generation cascade failed on all ${attempts.length} attempted providers: ${failureSummary}`)
+}

package/lib/index.js

@@ -15,7 +15,7 @@
 import z from '@deepseek-ai/schemastery'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
-import { enforceSecurePermissions } from './security.js'
+import { enforceSecurePermissions, isTrustedLocalRequest } from './security.js'
 import { saveAndAttachResult } from './attachment-helper.js'
 import {
   historyFile,
@@ -264,6 +264,10 @@ export const Config = z.object({
     .boolean()
     .description('Content-addressed disk caching for identical generations (<50ms retrieval, zero API cost). On by default.')
     .default(true),
+  fallbackProviders: z
+    .array(z.string())
+    .description('Ordered list of fallback providers to cascade to if the primary encounters 429, 5xx, or quota limits.')
+    .default([]),
 })
 
 /** Keep a file stem safe for the filesystem. */
@@ -431,6 +435,11 @@ export function apply(ctx, config) {
         res.end(JSON.stringify({ error: 'GET only' }))
         return
       }
+      if (!isTrustedLocalRequest(req)) {
+        res.writeHead(403, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: 'forbidden' }))
+        return
+      }
       const query = new URL(req.url ?? '/', 'http://x').searchParams
       const id = query.get('id') ?? ''
       if (!/^sha256:[0-9a-f]{64}$/.test(id)) {
@@ -504,6 +513,11 @@ export function apply(ctx, config) {
         res.end(JSON.stringify({ error: 'GET only' }))
         return
       }
+      if (!isTrustedLocalRequest(req)) {
+        res.writeHead(403, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: 'forbidden' }))
+        return
+      }
       try {
         const u = new URL(req.url, 'http://localhost')
         const provider = u.searchParams.get('provider') || config.provider || 'fal'
@@ -533,12 +547,20 @@ export function apply(ctx, config) {
         res.end(JSON.stringify({ error: 'GET only' }))
         return
       }
+      if (!isTrustedLocalRequest(req)) {
+        res.writeHead(403, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: 'forbidden' }))
+        return
+      }
       const exists = (p) => existsSync(p)
       const entries = await readHistory()
-      const withThumbs = filterHistory(entries, exists).map((e) => ({
-        ...e,
-        thumbnailUrl: e.attachmentId ? `/dsh-image-gen/image?id=${encodeURIComponent(e.attachmentId)}` : '',
-      }))
+      const withThumbs = filterHistory(entries, exists).map((e) => {
+        const { path: _discardPath, ...safeEntry } = e
+        return {
+          ...safeEntry,
+          thumbnailUrl: e.attachmentId ? `/dsh-image-gen/image?id=${encodeURIComponent(e.attachmentId)}` : '',
+        }
+      })
       res.writeHead(200, { 'Content-Type': 'application/json' })
       res.end(JSON.stringify(withThumbs))
     },

package/lib/register-tools.js

@@ -11,6 +11,9 @@ import { registerSketchTools } from './tools/sketch.js'
 import { registerSpritesheetTools } from './tools/spritesheet.js'
 import { registerPatternTools } from './tools/pattern.js'
 import { registerResponsiveTools } from './tools/responsive.js'
+import { registerAnchorTools } from './tools/anchor.js'
+import { registerUiAssetTools } from './tools/ui-asset.js'
+import { registerStyleMatrixTools } from './tools/style-matrix.js'
 
 /**
  * Registers every image-gen tool on the host tools service.
@@ -29,4 +32,7 @@ export function registerAllTools(ctx, deps) {
   registerSpritesheetTools(ctx, deps)
   registerPatternTools(ctx, deps)
   registerResponsiveTools(ctx, deps)
+  registerAnchorTools(ctx, deps)
+  registerUiAssetTools(ctx, deps)
+  registerStyleMatrixTools(ctx, deps)
 }

package/lib/security.js

@@ -1,5 +1,6 @@
 // lib/security.js
 // Secure credential handling, 0600 file permissions, and token masking (#169)
+// Address validation and trusted request guards against DNS rebinding & cross-site leaks (Refs: GitHub #1, #280, #276, #277)
 
 import { chmodSync, existsSync } from 'node:fs'
 
@@ -67,3 +68,168 @@ export function enforceSecurePermissions(filePath) {
     return false
   }
 }
+
+/**
+ * Strict loopback address verification.
+ * Supports:
+ * - 'localhost' and RFC 6761 reserved '.localhost' TLD (e.g. 'sub.localhost')
+ * - IPv6 loopback '::1'
+ * - Strict IPv4 loopback 127.0.0.0/8 (anchored ^ and $, valid octets 0..255)
+ * - IPv6-mapped IPv4 loopback '::ffff:127.x.x.x'
+ *
+ * Explicitly rejects prefix-matched hostnames such as 127.0.0.1.evil.com.
+ */
+export function isLoopbackAddress(value) {
+  if (!value || typeof value !== 'string') return false
+  const address = value.trim().toLowerCase().replace(/^\[|\]$/g, '')
+  if (
+    address === 'localhost' ||
+    address === 'localhost.' ||
+    address === '::1' ||
+    address.endsWith('.localhost') ||
+    address.endsWith('.localhost.')
+  ) {
+    return true
+  }
+  const ipv4 = address.startsWith('::ffff:') ? address.slice(7) : address
+  const m = /^127\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(ipv4)
+  if (!m) return false
+  const o = [Number(m[1]), Number(m[2]), Number(m[3])]
+  return o.every((n) => n >= 0 && n <= 255)
+}
+
+/**
+ * Strict private LAN address verification.
+ * Supports:
+ * - 10.0.0.0/8 (10.0.0.0 - 10.255.255.255)
+ * - 172.16.0.0/12 (172.16.0.0 - 172.31.255.255)
+ * - 192.168.0.0/16 (192.168.0.0 - 192.168.255.255)
+ * - 169.254.0.0/16 (link-local)
+ * - IPv6-mapped IPv4 equivalents (::ffff:...)
+ * - IPv6 ULA (fc00::/7) and link-local (fe80::/10)
+ *
+ * Explicitly rejects prefix-matched hostnames such as 10.evil.com,
+ * 192.168.evil.com, 172.16.evil.com, 10.0.0.1.nip.io.
+ */
+export function isPrivateLanAddress(value) {
+  if (!value || typeof value !== 'string') return false
+  const address = value.trim().toLowerCase().replace(/^\[|\]$/g, '')
+  const ipv4 = address.startsWith('::ffff:') ? address.slice(7) : address
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(ipv4)
+  if (m) {
+    const o = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])]
+    if (o.some((n) => n < 0 || n > 255)) return false
+    if (o[0] === 10) return true
+    if (o[0] === 172 && o[1] >= 16 && o[1] <= 31) return true
+    if (o[0] === 192 && o[1] === 168) return true
+    if (o[0] === 169 && o[1] === 254) return true
+    return false
+  }
+
+  // IPv6 ULA (fc00::/7) or link-local (fe80::/10)
+  if (/^(fc|fd)[0-9a-f]{2}:/i.test(address) || /^fe80:/i.test(address)) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Safely extracts hostname without port or IPv6 brackets from Host header or authority string.
+ */
+export function extractHostName(hostHeader) {
+  if (!hostHeader || typeof hostHeader !== 'string') return ''
+  const trimmed = hostHeader.trim()
+  try {
+    const url = new URL(`http://${trimmed}`)
+    return url.hostname.replace(/^\[|\]$/g, '')
+  } catch {
+    return trimmed.replace(/^\[|\]$/g, '').split(':')[0] || ''
+  }
+}
+
+/**
+ * Helper to get header value in case-insensitive manner.
+ */
+function getHeader(req, name) {
+  if (!req?.headers) return undefined
+  const direct = req.headers[name]
+  if (direct !== undefined) return Array.isArray(direct) ? direct[0] : direct
+  const lower = req.headers[name.toLowerCase()]
+  return Array.isArray(lower) ? lower[0] : lower
+}
+
+/**
+ * Verifies that an incoming HTTP request originates from and targets a trusted local or private LAN authority.
+ * Guards against DNS rebinding, cross-site leaks, and unauthorized external probing.
+ *
+ * Rules:
+ * 1. Client remote address (if present on socket) must be loopback or private LAN.
+ * 2. Sec-Fetch-Site (if present) must NOT be 'cross-site'.
+ * 3. Host header must be present and its hostname must be loopback or private LAN.
+ * 4. Origin header (if present) must have valid http/https protocol, its hostname must be loopback/LAN,
+ *    and its host authority must match the request's Host header.
+ * 5. Referer header (if present) must have valid http/https protocol and its hostname must be loopback/LAN.
+ */
+export function isTrustedLocalRequest(req) {
+  if (!req) return false
+
+  const remote = req.socket?.remoteAddress
+  if (remote && !isLoopbackAddress(remote) && !isPrivateLanAddress(remote)) {
+    return false
+  }
+
+  const site = getHeader(req, 'sec-fetch-site')
+  if (site === 'cross-site') {
+    return false
+  }
+
+  const host = getHeader(req, 'host')
+  if (!host || typeof host !== 'string') {
+    return false
+  }
+  const hostName = extractHostName(host)
+  if (!isLoopbackAddress(hostName) && !isPrivateLanAddress(hostName)) {
+    return false
+  }
+
+  const origin = getHeader(req, 'origin')
+  if (origin !== undefined) {
+    if (typeof origin !== 'string' || origin === '' || origin === 'null') {
+      return false
+    }
+    try {
+      const url = new URL(origin)
+      if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        return false
+      }
+      const originHostName = url.hostname.replace(/^\[|\]$/g, '')
+      if (!isLoopbackAddress(originHostName) && !isPrivateLanAddress(originHostName)) {
+        return false
+      }
+      if (url.host.toLowerCase() !== host.toLowerCase()) {
+        return false
+      }
+    } catch {
+      return false
+    }
+  }
+
+  const referer = getHeader(req, 'referer')
+  if (referer !== undefined && typeof referer === 'string' && referer !== '') {
+    try {
+      const url = new URL(referer)
+      if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        return false
+      }
+      const refererHostName = url.hostname.replace(/^\[|\]$/g, '')
+      if (!isLoopbackAddress(refererHostName) && !isPrivateLanAddress(refererHostName)) {
+        return false
+      }
+    } catch {
+      return false
+    }
+  }
+
+  return true
+}

package/lib/style-matrix-helpers.js

@@ -0,0 +1,85 @@
+// style-matrix-helpers.js — Helpers for generate_style_matrix tool (#286).
+
+export const DEFAULT_MATRIX_STYLES = [
+  'editorial_photo',
+  'flat_vector',
+  'clay_3d',
+  'cyberpunk',
+]
+
+export const MATRIX_PRESET_PROMPTS = {
+  editorial_photo: 'editorial magazine photograph, 35mm film, soft diffused cinematic lighting, award-winning shot, ultra-detailed',
+  flat_vector: 'minimal flat vector art, clean sharp lines, bold solid colors, geometric modern graphic illustration',
+  clay_3d: 'charming 3D claymation plasticine sculpt, handcrafted clay texture, stop-motion animation aesthetic, miniature depth of field',
+  cyberpunk: 'gritty cyberpunk scene, neon reflections, rain-slicked chrome, dark synthwave palette, high-tech dystopian atmosphere',
+  cinematic: 'cinematic still frame, 70mm Panavision anamorphic lens, dramatic moody lighting, atmospheric haze',
+  anime: 'vibrant modern anime keyframe, Makoto Shinkai aesthetic, luminous skies, crisp cel shading',
+  isometric_3d: 'isometric 3D diorama render, Blender 3D, orthographic perspective, cute stylized textures',
+  analog_film: 'vintage 1970s Kodachrome analog film print, authentic grain, faded warm tones, nostalgic vignette',
+}
+
+/**
+ * Normalizes input styles into exactly 4 distinct style strings.
+ *
+ * @param {string[]|undefined} inputStyles
+ * @returns {string[]}
+ */
+export function normalizeMatrixStyles(inputStyles) {
+  const result = []
+  if (Array.isArray(inputStyles)) {
+    for (const s of inputStyles) {
+      if (typeof s === 'string' && s.trim()) {
+        const clean = s.trim().toLowerCase()
+        if (!result.includes(clean)) result.push(clean)
+      }
+      if (result.length === 4) break
+    }
+  }
+
+  // Backfill up to 4 using defaults
+  for (const def of DEFAULT_MATRIX_STYLES) {
+    if (result.length >= 4) break
+    if (!result.includes(def)) result.push(def)
+  }
+
+  return result.slice(0, 4)
+}
+
+/**
+ * Builds the full prompt for a matrix quadrant cell.
+ *
+ * @param {string} basePrompt
+ * @param {string} styleName
+ * @returns {string}
+ */
+export function buildMatrixCellPrompt(basePrompt, styleName) {
+  const cleanBase = String(basePrompt || '').trim()
+  const presetDirective = MATRIX_PRESET_PROMPTS[styleName] || (styleName + ' style, aesthetic rendering')
+  return cleanBase + ', ' + presetDirective
+}
+
+/**
+ * Formats a 2x2 markdown presentation grid for chat models.
+ *
+ * @param {object} params
+ * @param {string} params.basePrompt
+ * @param {boolean} params.blindMode
+ * @param {Array<{id: string, style: string, path: string, url: string, seed: number}>} params.cells
+ * @returns {string}
+ */
+export function formatMatrixMarkdown({ basePrompt, blindMode, cells }) {
+  const lines = [
+    '### Style Matrix (2×2 Benchmark): "' + basePrompt + '"',
+    blindMode ? '_Blind Comparison Mode: styles masked until evaluated_' : '',
+    '',
+    '| Cell | Style Preset | Seed | Path |',
+    '| :---: | :--- | :---: | :--- |',
+  ]
+
+  for (const c of cells) {
+    const styleLabel = blindMode ? ('Option ' + c.id) : ('**' + c.style + '**')
+    lines.push('| **' + c.id + '** | ' + styleLabel + ' | `' + c.seed + '` | `' + c.path + '` |')
+  }
+
+  return lines.filter(Boolean).join('\n')
+}

package/lib/tools/anchor.js

@@ -0,0 +1,129 @@
+// anchor.js — set_style_anchor tool (#283).
+// Manages persistent visual style & character reference anchors in session context.
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import {
+  setSessionAnchor,
+  getSessionAnchor,
+  clearSessionAnchor,
+  normalizeAnchorStrength,
+} from '../anchor-helpers.js'
+import { toLosslessJson } from '../providers.js'
+
+export function registerAnchorTools(ctx, deps) {
+  const { live, resolveSource } = deps
+
+  ctx.effect(() => {
+    ctx.tools.register(
+      defineTool({
+        name: 'set_style_anchor',
+        description:
+          'Set or clear a persistent visual anchor (character identity or artstyle) for this session. '
+          + 'Subsequent image generations automatically adhere to this reference to maintain visual continuity.',
+        parameters: {
+          image: {
+            type: 'string',
+            description: 'URL, local file path, or attachment id (sha256:...) to use as the visual anchor. Required unless clear is true.',
+          },
+          label: {
+            type: 'string',
+            description: 'Human-readable descriptor, e.g. "Protagonist Alex" or "Dark Synthwave 3D".',
+          },
+          mode: {
+            type: 'string',
+            enum: ['style', 'character'],
+            description: 'Anchor mode: "character" preserves facial/physical identity; "style" preserves artistic rendering, lighting, and palette. Default: style.',
+          },
+          strength: {
+            type: 'number',
+            description: 'Reference influence strength between 0.1 and 1.0 (default 0.65).',
+          },
+          clear: {
+            type: 'boolean',
+            description: 'When true, clears the active anchor for this session instead of setting a new one.',
+          },
+        },
+        output: {
+          schema: {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+              ok: { type: 'boolean' },
+              action: { type: 'string' },
+              anchor: {
+                type: 'object',
+                additionalProperties: true,
+                properties: {
+                  image: { type: 'string' },
+                  label: { type: 'string' },
+                  mode: { type: 'string' },
+                  strength: { type: 'number' },
+                  updatedAt: { type: 'string' },
+                },
+              },
+              summary: { type: 'string' },
+            },
+          },
+          render(args, value) {
+            return [{ type: 'text', text: value.summary || 'Style anchor updated.' }]
+          },
+        },
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+          const cfg = live ? live() : {}
+          if (cfg.enabled === false) {
+            throw new Error('Image generation plugin is disabled in settings.')
+          }
+
+          const sessionId = exec?.agent?.session?.id || exec?.agent?.session?.header?.id || 'session'
+
+          if (args.clear) {
+            const existed = clearSessionAnchor(sessionId)
+            const summary = existed
+              ? 'Active visual style anchor was cleared for this session.'
+              : 'No active visual style anchor was set for this session.'
+            return toLosslessJson({
+              ok: true,
+              action: 'cleared',
+              summary,
+            })
+          }
+
+          if (!args.image || typeof args.image !== 'string' || !args.image.trim()) {
+            throw new Error('Parameter "image" (URL, file path, or sha256 attachment ID) is required to set an anchor.')
+          }
+
+          const imageRef = args.image.trim()
+          const mode = args.mode === 'character' ? 'character' : 'style'
+          const strength = normalizeAnchorStrength(args.strength)
+          const label = args.label ? String(args.label).trim() : (mode === 'character' ? 'Character Anchor' : 'Style Anchor')
+
+          // Validate source readability if it is a local path or attachment
+          if (resolveSource && (imageRef.startsWith('sha256:') || !imageRef.startsWith('http'))) {
+            try {
+              await resolveSource(ctx, exec, imageRef)
+            } catch (err) {
+              // Best effort check; non-blocking if remote URL or future attachment
+            }
+          }
+
+          const anchor = setSessionAnchor(sessionId, {
+            image: imageRef,
+            label,
+            mode,
+            strength,
+          })
+
+          const summary = `Visual anchor "${label}" (${mode} mode, strength: ${strength}) is now active for this session. Subsequent generations will align with this reference.`
+
+          return toLosslessJson({
+            ok: true,
+            action: 'set',
+            anchor,
+            summary,
+          })
+        },
+      }),
+    )
+  }, 'dsh-image-gen: tool set_style_anchor')
+}