@seed-ship/mcp-ui-solid 5.5.0 → 5.6.0

package/src/services/telemetry.ts

@@ -0,0 +1,149 @@
+/**
+ * UI telemetry sink (B.5 — v5.6.0)
+ *
+ * Minimal OpenTelemetry-like Provider that lets a consumer (e.g. deposium
+ * `/admin/ui-telemetry`) collect lifecycle + error + action events from
+ * mcp-ui components without imposing any API change on apps that don't use
+ * it. Spec'd in `MCP-UI-AUDIT-2026-04-26.md` §M.6.
+ *
+ * Three hard rules:
+ *   1. Provider is OPTIONAL. When absent, `useTelemetry()` returns `null`
+ *      and dispatch sites no-op. Existing apps see zero behavior change.
+ *   2. Sink is FAIL-OPEN. A `sink()` throw or rejected promise is caught
+ *      silently — telemetry never crashes the renderer.
+ *   3. Events carry NO payload data. Only meta (type + id + counts + timing)
+ *      to avoid PII / data leaks in centralized logs.
+ */
+
+import type { ComponentType } from '../types'
+
+interface TelemetryEventBase {
+  /** Component instance id (from `UIComponent.id` or auto-generated). */
+  id: string
+  /** ComponentType, e.g. 'chart' / 'metric' / 'iframe'. */
+  componentType: ComponentType
+  /** Wall-clock timestamp (ms epoch) for cross-stack correlation. */
+  ts: number
+}
+
+/**
+ * Discriminated union of all telemetry events emitted by mcp-ui.
+ * See §M.6.2 for field semantics + privacy rules.
+ */
+export type TelemetryEvent =
+  | ({ type: 'component:mounted' } & TelemetryEventBase)
+  | ({ type: 'component:rendered'; durationMs: number } & TelemetryEventBase)
+  | ({ type: 'component:unmounted' } & TelemetryEventBase)
+  | ({
+      type: 'validation:failed'
+      errorCount: number
+      firstErrorCode: string | null
+    } & TelemetryEventBase)
+  | ({ type: 'render:error'; errorMessage: string } & TelemetryEventBase)
+  | ({ type: 'action:dispatched'; actionName: string } & TelemetryEventBase)
+
+/**
+ * Consumer-supplied sink. Receives a batch of events (always an array,
+ * even for `bufferMs: 0` — single-element array in that case). Errors
+ * and rejected promises are caught silently by the dispatcher.
+ */
+export interface TelemetrySink {
+  (events: TelemetryEvent[]): void | Promise<void>
+}
+
+export interface TelemetryOptions {
+  /** Per-event base sampling rate, 0..1, default 1.0 (all events). */
+  sampleRate?: number
+  /** Buffer events and flush after N ms (default 100). 0 = no buffer. */
+  bufferMs?: number
+  /** Max buffered events before forced flush (default 50). */
+  bufferMax?: number
+  /** Per-event-type override on sampling (high-volume types can be lower). */
+  sampleByType?: Partial<Record<TelemetryEvent['type'], number>>
+}
+
+/**
+ * Dispatcher returned by `createTelemetryDispatcher`. Used internally by
+ * the Provider, exposed only so tests can drive it without React/Solid.
+ */
+export interface TelemetryDispatcher {
+  /**
+   * Push an event. Sampling + buffering applied transparently. Never throws.
+   */
+  dispatch(event: TelemetryEvent): void
+  /**
+   * Force-flush the buffer. Useful on tab-hidden / unload, or for tests.
+   * Never throws.
+   */
+  flush(): void
+}
+
+const DEFAULT_BUFFER_MS = 100
+const DEFAULT_BUFFER_MAX = 50
+
+function shouldSample(
+  eventType: TelemetryEvent['type'],
+  options: TelemetryOptions | undefined
+): boolean {
+  const perTypeRate = options?.sampleByType?.[eventType]
+  const rate = perTypeRate !== undefined ? perTypeRate : (options?.sampleRate ?? 1.0)
+  if (rate >= 1) return true
+  if (rate <= 0) return false
+  return Math.random() < rate
+}
+
+/**
+ * Create a telemetry dispatcher. Pure function, no Solid context — exists
+ * separately from the Provider so it can be unit-tested in isolation.
+ */
+export function createTelemetryDispatcher(
+  sink: TelemetrySink,
+  options?: TelemetryOptions
+): TelemetryDispatcher {
+  const buffer: TelemetryEvent[] = []
+  const bufferMs = options?.bufferMs ?? DEFAULT_BUFFER_MS
+  const bufferMax = options?.bufferMax ?? DEFAULT_BUFFER_MAX
+  let flushTimer: ReturnType<typeof setTimeout> | undefined
+
+  function deliver(batch: TelemetryEvent[]): void {
+    try {
+      const result = sink(batch)
+      // Promise rejections are silenced too (fail-open, §M.6.1).
+      if (result && typeof (result as Promise<void>).then === 'function') {
+        ;(result as Promise<void>).catch(() => {
+          /* silent */
+        })
+      }
+    } catch {
+      /* silent */
+    }
+  }
+
+  function flush(): void {
+    if (flushTimer !== undefined) {
+      clearTimeout(flushTimer)
+      flushTimer = undefined
+    }
+    if (buffer.length === 0) return
+    const batch = buffer.splice(0, buffer.length)
+    deliver(batch)
+  }
+
+  function dispatch(event: TelemetryEvent): void {
+    if (!shouldSample(event.type, options)) return
+    buffer.push(event)
+    if (buffer.length >= bufferMax) {
+      flush()
+      return
+    }
+    if (bufferMs <= 0) {
+      flush()
+      return
+    }
+    if (flushTimer === undefined) {
+      flushTimer = setTimeout(flush, bufferMs)
+    }
+  }
+
+  return { dispatch, flush }
+}

package/src/services/validation.test.ts

@@ -6,7 +6,7 @@
  */
 
 import { describe, it, expect, vi } from 'vitest'
-import { validateComponent, validateChartComponent, getIframeSandbox } from './validation'
+import { validateComponent, validateChartComponent, getIframeSandbox, validateIframeDomain } from './validation'
 import type { UIComponent, ComponentType } from '../types'
 
 /** Helper to create a minimal valid UIComponent for testing */
@@ -22,13 +22,14 @@ function makeComponent(type: ComponentType, params: Record<string, any> = {}): U
 /** Types that have explicit validation cases in validateComponent */
 const VALIDATED_TYPES: ComponentType[] = [
   'chart', 'table', 'metric', 'text', 'iframe', 'image', 'link', 'action',
+  'artifact',
 ]
 
 /** Types that hit the default case (no specific validation) */
 const PASSTHROUGH_TYPES: ComponentType[] = [
   'code', 'map', 'form', 'modal', 'action-group',
   'image-gallery', 'video', 'grid', 'carousel',
-  'artifact', 'footer',
+  'footer',
 ]
 
 describe('validateComponent', () => {
@@ -47,7 +48,7 @@ describe('validateComponent', () => {
   describe('validated types still work', () => {
     it('validates a valid chart component', () => {
       const component = makeComponent('chart', {
-        chartType: 'bar',
+        type: 'bar',
         data: { labels: ['A'], datasets: [{ data: [1] }] },
       })
       const result = validateComponent(component)
@@ -327,3 +328,52 @@ describe('getIframeSandbox — tiered sandbox', () => {
     expect(sandbox).toContain('allow-same-origin')
   })
 })
+
+describe('validateIframeDomain — security regression (v5.5.1)', () => {
+  // Pre-v5.5.1 bug: the predicate was
+  //   `domain === allowed || domain.endsWith(`.${allowed}`) || allowed === 'localhost'`
+  // The third clause `allowed === 'localhost'` was checking the WHITELIST
+  // ENTRY (not the domain) — once 'localhost' appeared in DEFAULT_IFRAME_DOMAINS,
+  // every URL was accepted. These tests lock the fixed behavior in place.
+
+  it('REJECTS a non-whitelisted external domain (this used to silently pass)', () => {
+    const result = validateIframeDomain('https://evil.example.com/x')
+    expect(result.valid).toBe(false)
+    expect(result.errors?.[0]?.code).toBe('DOMAIN_NOT_WHITELISTED')
+  })
+
+  it('REJECTS a typo-squat that is NOT a subdomain of any whitelisted entry', () => {
+    // youtube-evil.com is not youtube.com nor a subdomain of it
+    const result = validateIframeDomain('https://youtube-evil.com/embed/x')
+    expect(result.valid).toBe(false)
+    expect(result.errors?.[0]?.code).toBe('DOMAIN_NOT_WHITELISTED')
+  })
+
+  it('still accepts a whitelisted domain (quickchart.io)', () => {
+    expect(validateIframeDomain('https://quickchart.io/chart?c={}').valid).toBe(true)
+  })
+
+  it('still accepts subdomains of whitelisted entries (player.vimeo.com)', () => {
+    expect(validateIframeDomain('https://player.vimeo.com/video/123').valid).toBe(true)
+  })
+
+  it('still accepts localhost (dev convenience)', () => {
+    expect(validateIframeDomain('http://localhost:3000/x').valid).toBe(true)
+  })
+
+  it('still accepts 127.0.0.1 (loopback equivalent of localhost)', () => {
+    expect(validateIframeDomain('http://127.0.0.1:8080/x').valid).toBe(true)
+  })
+
+  it('respects allow-all policy bypass', () => {
+    expect(validateIframeDomain('https://anything.com', { policy: 'allow-all' }).valid).toBe(true)
+  })
+
+  it('extend policy adds custom domains', () => {
+    const result = validateIframeDomain('https://my-internal-tool.corp.com/x', {
+      policy: 'extend',
+      customDomains: ['my-internal-tool.corp.com'],
+    })
+    expect(result.valid).toBe(true)
+  })
+})

package/src/services/validation.ts

@@ -22,6 +22,9 @@ import {
   ImageGalleryParamsSchema,
   ActionGroupParamsSchema,
   CodeComponentParamsSchema,
+  // v5.6.0 — added after spec@5.0.2 relaxations (deposium audit §M)
+  MapComponentParamsSchema,
+  FormComponentParamsSchema,
 } from '@seed-ship/mcp-ui-spec'
 import type {
   UIComponent,
@@ -47,7 +50,7 @@ const KNOWN_COMPONENT_TYPES: Set<string> = new Set<ComponentType>([
 ])
 
 /**
- * Spec-driven validation dispatch table (B.1 — v5.5.0).
+ * Spec-driven validation dispatch table (B.1 — v5.5.0, expanded in v5.6.0).
  *
  * For each ComponentType where we delegate shape validation to a Zod schema
  * from `@seed-ship/mcp-ui-spec`, this table maps:
@@ -56,13 +59,13 @@ const KNOWN_COMPONENT_TYPES: Set<string> = new Set<ComponentType>([
  *     pre-v5.5.0 `errors[].code` API contract — see MCP-UI-AUDIT-2026-04-26.md
  *     §I.3.a + §J.1)
  *
+ * **v5.6.0** : `map` and `form` joined the dispatch after spec@5.0.2 relaxed
+ * their schemas (LatLngPoint union for map.center, regex relax for
+ * field.name) per deposium audit §L answers. Closed B.1 to **14/17 types**.
+ *
  * Types deliberately omitted (kept on the imperative path):
  *   - `chart`, `table` — have rich imperative validators with their own
  *     codes (MISSING_DATA, DATA_LENGTH_MISMATCH, RESOURCE_LIMIT_EXCEEDED, …)
- *   - `form`           — spec FormFieldSchema has strict regex on field
- *     names that could reject LLM-generated payloads. Conservative.
- *   - `map`            — spec center is `tuple([number, number])`; production
- *     payloads use `{lat, lng}` objects. Avoid backward-compat regression.
  *   - `modal`          — all params are optional; nothing to enforce.
  *   - `grid`, `footer`, `composite` — pass-through, validated elsewhere.
  */
@@ -79,6 +82,9 @@ const SPEC_VALIDATORS: Partial<Record<ComponentType, { schema: ZodSchema; legacy
   'action-group': { schema: ActionGroupParamsSchema, legacyCode: 'EMPTY_ACTION_GROUP' },
   code: { schema: CodeComponentParamsSchema, legacyCode: 'INVALID_CODE' },
   artifact: { schema: ArtifactComponentParamsSchema, legacyCode: 'INVALID_ARTIFACT' },
+  // v5.6.0 additions
+  form: { schema: FormComponentParamsSchema, legacyCode: 'EMPTY_FORM' },
+  map: { schema: MapComponentParamsSchema, legacyCode: 'INVALID_MAP' },
 }
 
 /**
@@ -568,9 +574,17 @@ export function validateIframeDomain(
       effectiveWhitelist = [...DEFAULT_IFRAME_DOMAINS, ...options.customDomains]
     }
 
-    const isAllowed = effectiveWhitelist.some(
-      (allowed) => domain === allowed || domain.endsWith(`.${allowed}`) || allowed === 'localhost'
-    )
+    // SECURITY (v5.5.1) — pre-fix bug: predicate was `allowed === 'localhost'`
+    // which trivially returned true for every URL once the whitelist contained
+    // 'localhost' (an entry from DEFAULT_IFRAME_DOMAINS), making the entire
+    // domain whitelist inoperative. Fixed: only the URL's actual hostname
+    // being 'localhost' (or a 127.0.0.x loopback) bypasses the whitelist.
+    const isLoopback = domain === 'localhost' || /^127(\.\d{1,3}){3}$/.test(domain)
+    const isAllowed =
+      isLoopback ||
+      effectiveWhitelist.some(
+        (allowed) => allowed !== 'localhost' && (domain === allowed || domain.endsWith(`.${allowed}`))
+      )
 
     if (!isAllowed) {
       return {
@@ -669,35 +683,49 @@ export function validateComponent(
     errors.push(...(sizeResult.errors || []))
   }
 
-  // Type-specific validation (B.1 — v5.5.0).
+  // Type-specific validation (B.1 — v5.5.0, expanded v5.6.0).
   //
-  // 12 types delegate shape validation to Zod schemas in `mcp-ui-spec` via
-  // SPEC_VALIDATORS. The 5 remaining types stay imperative because they
-  // need cross-field consistency, resource limits, or backward-compat logic
-  // that pure Zod can't express without `.refine()` (see SPEC_VALIDATORS docstring).
+  // 14 types delegate shape validation to Zod schemas in `mcp-ui-spec` via
+  // SPEC_VALIDATORS. The 3 remaining types stay imperative because they
+  // need cross-field consistency, resource limits, or have nothing to validate
+  // (see SPEC_VALIDATORS docstring).
   const specValidator = SPEC_VALIDATORS[component.type]
   if (specValidator) {
     const result = specValidator.schema.safeParse(component.params)
     if (!result.success) {
       errors.push(...mapZodIssuesToErrors(result.error.issues, specValidator.legacyCode))
     }
-    // Iframe + video: chain the domain whitelist post-check ONLY when the
-    // shape parse succeeded (i.e. url is present and a string). Skipping the
-    // domain check when shape failed avoids cascading errors on the same field.
-    if (result.success && (component.type === 'iframe' || component.type === 'video')) {
-      const url = (component.params as { url?: string })?.url
-      if (typeof url === 'string') {
-        const domainResult = validateIframeDomain(url, {
-          policy: options?.iframePolicy,
-          customDomains: options?.customIframeDomains,
-        })
-        if (!domainResult.valid) {
-          errors.push(...(domainResult.errors || []))
+    // Post-spec chained checks. Skipped when the shape parse failed to avoid
+    // cascading errors on already-broken payloads.
+    if (result.success) {
+      // Iframe + video: domain whitelist
+      if (component.type === 'iframe' || component.type === 'video') {
+        const url = (component.params as { url?: string })?.url
+        if (typeof url === 'string') {
+          const domainResult = validateIframeDomain(url, {
+            policy: options?.iframePolicy,
+            customDomains: options?.customIframeDomains,
+          })
+          if (!domainResult.valid) {
+            errors.push(...(domainResult.errors || []))
+          }
+        }
+      }
+      // Map (v5.6.0): center OR markers required. Spec has both .optional()
+      // since auto-center from markers is supported, but we need ONE of them.
+      if (component.type === 'map') {
+        const mapParams = component.params as { center?: unknown; markers?: unknown[] }
+        if (!mapParams.center && (!Array.isArray(mapParams.markers) || mapParams.markers.length === 0)) {
+          errors.push({
+            path: 'params',
+            message: 'Map must have center or markers',
+            code: 'INVALID_MAP',
+          })
         }
       }
     }
   } else {
-    // Imperative path for chart/table/form/map/modal/grid/footer/composite.
+    // Imperative path for chart/table/modal/grid/footer/composite.
     switch (component.type) {
       case 'chart': {
         const chartResult = validateChartComponent(component.params as ChartComponentParams, limits)
@@ -715,24 +743,6 @@ export function validateComponent(
         break
       }
 
-      case 'form': {
-        const formParams = component.params as { fields?: unknown[] }
-        if (!Array.isArray(formParams.fields) || formParams.fields.length === 0) {
-          errors.push({ path: 'params.fields', message: 'Form must have non-empty fields array', code: 'EMPTY_FORM' })
-        }
-        break
-      }
-
-      case 'map': {
-        // Map can auto-detect center from markers, so center is not strictly required.
-        // Spec MapComponentParamsSchema would be too strict (tuple-only center) — kept imperative.
-        const mapParams = component.params as { center?: unknown; markers?: unknown[] }
-        if (!mapParams.center && (!Array.isArray(mapParams.markers) || mapParams.markers.length === 0)) {
-          errors.push({ path: 'params', message: 'Map must have center or markers', code: 'INVALID_MAP' })
-        }
-        break
-      }
-
       case 'modal':
         // Modal is valid with minimal params (title optional, content can be children).
         break