@invisibleloop/pulse 0.20.37 → 0.20.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.20.37",
+  "version": "0.20.38",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",
@@ -61,7 +61,7 @@
   "scripts": {
     "dev": "node --watch src/cli/dev.js",
     "build": "node scripts/build.js",
-    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/cli/validate.test.js && node src/cli/diagnose.test.js && node src/cli/check-bundles.test.js && node src/cli/review.test.js && node src/cli/process-utils.test.js && node src/cli/stamp.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js && node scripts/css-purge.test.js && node src/mcp/mcp.test.js",
+    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/cli/validate.test.js && node src/cli/diagnose.test.js && node src/cli/check-bundles.test.js && node src/cli/review.test.js && node src/cli/process-utils.test.js && node src/cli/stamp.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js && node scripts/css-purge.test.js && node src/mcp/mcp.test.js && node src/mcp/guards.test.js",
     "typecheck": "tsc --noEmit",
     "docs": "node --watch src/cli/dev.js --root ../../docs --port 4000",
     "docs:start": "node ../../docs/server.js"

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.20.37
+0.20.38

package/src/mcp/guards.js

@@ -0,0 +1,94 @@
+/**
+ * Input guards for MCP tools.
+ *
+ * The MCP server runs locally, but its tool arguments are chosen by an AI agent
+ * that may have read untrusted content (a fetched page, a pasted brief). These
+ * helpers keep a steered tool call inside the project and off internal networks.
+ */
+
+import fs   from 'fs'
+import path from 'path'
+import net  from 'net'
+import dns  from 'dns/promises'
+
+/**
+ * Resolve a caller-supplied file path and require it to live inside `root`.
+ * Relative paths resolve against `root`. Symlinks are followed before the check
+ * so a link inside the project cannot point outside it.
+ *
+ * @returns {string} absolute path inside root
+ * @throws  {Error}  when the path escapes root
+ */
+export function resolveInRoot(root, file) {
+  const rootReal = fs.realpathSync(root)
+  const abs      = path.resolve(root, file)
+
+  // realpath the deepest existing ancestor so not-yet-created files are still checked
+  let probe = abs
+  while (!fs.existsSync(probe)) {
+    const parent = path.dirname(probe)
+    if (parent === probe) break
+    probe = parent
+  }
+  const real = path.join(fs.realpathSync(probe), path.relative(probe, abs))
+
+  const rel = path.relative(rootReal, real)
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(`path must be inside the project (${root}): ${file}`)
+  }
+  return abs
+}
+
+/** True for http(s) URLs that point at this machine (localhost / 127.0.0.0/8 / ::1). */
+export function isLoopbackUrl(rawUrl) {
+  let u
+  try { u = new URL(rawUrl) } catch { return false }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return false
+  const host = u.hostname.replace(/^\[|\]$/g, '').toLowerCase()
+  return host === 'localhost' || host.endsWith('.localhost') || host === '::1' || /^127\./.test(host)
+}
+
+/** True when an IP literal is loopback, private, link-local, CGNAT, multicast or otherwise non-public. */
+export function isPrivateAddress(ip) {
+  if (net.isIPv4(ip)) {
+    const [a, b] = ip.split('.').map(Number)
+    return a === 0 || a === 10 || a === 127 ||
+      (a === 100 && b >= 64 && b <= 127) ||
+      (a === 169 && b === 254) ||
+      (a === 172 && b >= 16 && b <= 31) ||
+      (a === 192 && b === 168) ||
+      a >= 224
+  }
+  if (net.isIPv6(ip)) {
+    const v = ip.toLowerCase()
+    const mapped = v.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)
+    if (mapped) return isPrivateAddress(mapped[1])
+    return v === '::' || v === '::1' ||
+      /^f[cd]/.test(v) ||            // fc00::/7 unique local
+      /^fe[89ab]/.test(v) ||         // fe80::/10 link-local
+      /^ff/.test(v)                  // multicast
+  }
+  return true // not an IP — treat as unsafe
+}
+
+/**
+ * Require a URL to be http(s) and resolve only to public addresses.
+ * Call before every request, including each redirect hop.
+ *
+ * @throws {Error} when the URL is not http(s) or resolves to a non-public address
+ */
+export async function assertPublicUrl(rawUrl) {
+  const u = rawUrl instanceof URL ? rawUrl : new URL(rawUrl)
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    throw new Error(`only http(s) URLs are allowed (got ${u.protocol})`)
+  }
+  const host = u.hostname.replace(/^\[|\]$/g, '')
+  if (net.isIP(host)) {
+    if (isPrivateAddress(host)) throw new Error(`${host} is not a public address`)
+    return
+  }
+  const addrs = await dns.lookup(host, { all: true })
+  if (!addrs.length || addrs.some(a => isPrivateAddress(a.address))) {
+    throw new Error(`${host} resolves to a non-public address`)
+  }
+}

package/src/mcp/guards.test.js

@@ -0,0 +1,90 @@
+/**
+ * MCP input guard tests — run with: node src/mcp/guards.test.js
+ */
+
+import fs     from 'node:fs'
+import os     from 'node:os'
+import path   from 'node:path'
+import assert from 'node:assert/strict'
+import { resolveInRoot, isLoopbackUrl, isPrivateAddress, assertPublicUrl } from './guards.js'
+
+let passed = 0
+let failed = 0
+
+async function test(label, fn) {
+  try { await fn(); console.log(`  ✓ ${label}`); passed++ }
+  catch (e) { console.log(`  ✗ ${label}\n      ${e.message}`); failed++ }
+}
+
+const base    = fs.mkdtempSync(path.join(os.tmpdir(), 'pulse-guards-'))
+const root    = path.join(base, 'project')
+const outside = path.join(base, 'outside')
+fs.mkdirSync(path.join(root, 'src', 'pages'), { recursive: true })
+fs.mkdirSync(outside)
+fs.writeFileSync(path.join(root, 'src', 'pages', 'a.js'), '')
+fs.writeFileSync(path.join(outside, 'secret.js'), '')
+fs.symlinkSync(outside, path.join(root, 'link'))
+
+console.log('\nresolveInRoot\n')
+
+await test('accepts absolute and relative paths inside the project', () => {
+  assert.equal(resolveInRoot(root, path.join(root, 'src/pages/a.js')), path.join(root, 'src/pages/a.js'))
+  assert.equal(resolveInRoot(root, 'src/pages/a.js'), path.join(root, 'src/pages/a.js'))
+})
+await test('accepts a not-yet-created file inside the project', () => {
+  assert.doesNotThrow(() => resolveInRoot(root, 'src/pages/new.js'))
+})
+await test('rejects absolute paths outside the project', () => {
+  assert.throws(() => resolveInRoot(root, path.join(outside, 'secret.js')), /inside the project/)
+})
+await test('rejects ../ traversal', () => {
+  assert.throws(() => resolveInRoot(root, '../outside/secret.js'), /inside the project/)
+  assert.throws(() => resolveInRoot(root, 'src/../../outside/secret.js'), /inside the project/)
+})
+await test('rejects a symlink inside the project that points outside it', () => {
+  assert.throws(() => resolveInRoot(root, 'link/secret.js'), /inside the project/)
+})
+await test('rejects a sibling directory sharing the root name prefix', () => {
+  fs.mkdirSync(root + '-evil')
+  assert.throws(() => resolveInRoot(root, root + '-evil/x.js'), /inside the project/)
+})
+
+console.log('\nisLoopbackUrl\n')
+
+await test('allows localhost, 127.x and ::1', () => {
+  for (const u of ['http://localhost:3000/', 'http://127.0.0.1:3000/x', 'http://[::1]:3000/', 'http://app.localhost/'])
+    assert.equal(isLoopbackUrl(u), true, u)
+})
+await test('rejects remote hosts, lookalikes and non-http schemes', () => {
+  for (const u of ['http://example.com/', 'http://localhost.evil.com/', 'http://169.254.169.254/', 'file:///etc/passwd', 'ftp://localhost/', 'nonsense'])
+    assert.equal(isLoopbackUrl(u), false, u)
+})
+
+console.log('\nisPrivateAddress / assertPublicUrl\n')
+
+await test('flags loopback, private, link-local, CGNAT and metadata addresses', () => {
+  for (const ip of ['127.0.0.1', '10.0.0.5', '172.16.0.1', '172.31.255.255', '192.168.1.1', '169.254.169.254', '100.64.0.1', '0.0.0.0', '::1', '::', 'fd00::1', 'fe80::1', '::ffff:10.0.0.1'])
+    assert.equal(isPrivateAddress(ip), true, ip)
+})
+await test('allows public addresses', () => {
+  for (const ip of ['8.8.8.8', '1.1.1.1', '172.32.0.1', '2606:4700:4700::1111'])
+    assert.equal(isPrivateAddress(ip), false, ip)
+})
+await test('assertPublicUrl rejects internal IP literals and non-http schemes', async () => {
+  await assert.rejects(assertPublicUrl('http://169.254.169.254/latest/meta-data/'), /not a public address/)
+  await assert.rejects(assertPublicUrl('http://127.0.0.1:3000/'), /not a public address/)
+  await assert.rejects(assertPublicUrl('http://[::1]/'), /not a public address/)
+  await assert.rejects(assertPublicUrl('file:///etc/passwd'), /only http/)
+})
+await test('assertPublicUrl rejects hostnames that resolve to loopback', async () => {
+  await assert.rejects(assertPublicUrl('http://localhost:3000/'), /non-public/)
+})
+await test('assertPublicUrl accepts a public IP literal', async () => {
+  await assertPublicUrl('https://1.1.1.1/')
+})
+
+fs.rmSync(base, { recursive: true, force: true })
+fs.rmSync(root + '-evil', { recursive: true, force: true })
+
+console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)
+if (failed > 0) process.exit(1)

package/src/mcp/server.js

@@ -36,9 +36,11 @@ import { z }                   from 'zod'
 import path                      from 'path'
 import fs                        from 'fs'
 import http                      from 'http'
+import https                     from 'https'
 import { spawn, spawnSync } from 'child_process'
 
 import { loadPages } from '../cli/discover.js'
+import { resolveInRoot, isLoopbackUrl, assertPublicUrl } from './guards.js'
 import { validateContent, validateFile, formatValidationResult } from '../cli/validate.js'
 import { readJournal, formatJournal, resolveEntries, formatResolveResult } from '../cli/diagnose.js'
 import { writeStamp, formatStampResult } from '../cli/stamp.js'
@@ -821,6 +823,9 @@ server.registerTool(
       return text('Error: provide only one of content or file, not both')
     }
 
+    if (file) {
+      try { file = resolveInRoot(ROOT, file) } catch (e) { return text(`Error: ${e.message}`) }
+    }
     const result = file ? await validateFile(file, ROOT) : await validateContent(content, ROOT)
     return text(formatValidationResult(result, { nextSteps: true }))
   }
@@ -1045,6 +1050,10 @@ The generated file uses @invisibleloop/pulse/testing (renderSync / render). Do N
     },
   },
   async ({ file }) => {
+    try { file = resolveInRoot(ROOT, file) } catch (e) { return text(`Error: ${e.message}`) }
+    if (!file.endsWith('.js') || file.endsWith('.test.js')) {
+      return text('Error: file must be a spec .js file (not a .test.js file)')
+    }
     if (!fs.existsSync(file)) {
       return text(`File not found: ${file}`)
     }
@@ -1207,6 +1216,9 @@ server.registerTool(
     inputSchema: { url: z.string().describe('Full URL, e.g. http://localhost:3000/about') },
   },
   ({ url }) => new Promise(resolve => {
+    if (!isLoopbackUrl(url) || !url.startsWith('http:')) {
+      return resolve(text('Error: pulse_fetch_page only fetches the local dev server (http://localhost:PORT/...)'))
+    }
     const req = http.get(url, { timeout: 10_000 }, res => {
       const chunks = []
       res.on('data', d => chunks.push(d))
@@ -1399,7 +1411,7 @@ any feature build.
 
     let source = content
     if (file) {
-      if (!path.isAbsolute(file)) file = path.resolve(process.cwd(), file)
+      try { file = resolveInRoot(ROOT, file) } catch (e) { return text(`Error: ${e.message}`) }
       if (!fs.existsSync(file)) return text(`File not found: ${file}`)
       source = fs.readFileSync(file, 'utf8')
     }
@@ -1575,12 +1587,15 @@ server.registerTool(
     const inSync       = installed === staticAsset
 
     // Fetch latest from npm registry
-    const req = http.get('http://registry.npmjs.org/@invisibleloop/pulse/latest', { timeout: 5000 }, res => {
+    const req = https.get('https://registry.npmjs.org/@invisibleloop/pulse/latest', { timeout: 5000 }, res => {
       const chunks = []
       res.on('data', d => chunks.push(d))
       res.on('end', () => {
         let latest = 'unknown'
-        try { latest = JSON.parse(Buffer.concat(chunks).toString()).version } catch { /* ignore */ }
+        try {
+          const v = JSON.parse(Buffer.concat(chunks).toString()).version
+          if (/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(v)) latest = v   // never echo an unvalidated string
+        } catch { /* ignore */ }
 
         const lines = [
           `Installed package : v${installed}`,
@@ -3351,9 +3366,11 @@ Call it with the external URLs you plan to use, before your first Lighthouse run
       let blocked = null
       try {
         for (let hop = 0; hop < MAX_HOPS; hop++) {
+          await assertPublicUrl(url)   // every hop: block internal/metadata addresses
           const res = await fetch(url, { method: 'HEAD', redirect: 'manual', signal: AbortSignal.timeout(5000) })
           if (res.status >= 300 && res.status < 400 && res.headers.get('location')) {
             url = new URL(res.headers.get('location'), url)
+            await assertPublicUrl(url)
             chain.push(url.origin)
             continue
           }
@@ -3362,6 +3379,7 @@ Call it with the external URLs you plan to use, before your first Lighthouse run
             const get = await fetch(url, { method: 'GET', redirect: 'manual', headers: { Range: 'bytes=0-0' }, signal: AbortSignal.timeout(5000) })
             if (get.status >= 300 && get.status < 400 && get.headers.get('location')) {
               url = new URL(get.headers.get('location'), url)
+              await assertPublicUrl(url)
               chain.push(url.origin)
               continue
             }
@@ -3413,6 +3431,7 @@ Run this immediately after writing a theme file — before production build and
     let source = css || ''
 
     if (!source && file) {
+      try { file = resolveInRoot(ROOT, file) } catch (e) { return text(`Error: ${e.message}`) }
       if (!fs.existsSync(file)) return text(`File not found: ${file}`)
       source = fs.readFileSync(file, 'utf8')
     }

package/src/runtime/ssr.js

@@ -148,7 +148,7 @@ export function renderToStream(spec, ctx = {}, nonce = '') {
       const mergedAllState = applyCtxExtras(mergeStoreKeys(spec, allServerState, ctx.store), ctx)
       if (spec.hydrate && Object.keys(mergedAllState).length > 0) {
         controller.enqueue(encode(
-          `<script nonce="${nonce}">window.__PULSE_SERVER__ = ${JSON.stringify(mergedAllState)};</script>`
+          `<script nonce="${nonce}">window.__PULSE_SERVER__ = ${safeJson(mergedAllState)};</script>`
         ))
       }
 
@@ -275,7 +275,7 @@ export function buildStoreScript(spec, storeState, nonce, livePath = '') {
   // mount() connects only when the page actually subscribes to store keys.
   const liveFlag = livePath ? `window.__PULSE_LIVE__='${livePath}';` : ''
   if (storeState && Object.keys(storeState).length > 0) {
-    return `<script nonce="${nonce}">window.__PULSE_NONCE__='${nonce}';${liveFlag}window.__PULSE_STORE__=${JSON.stringify(storeState)};window.__updatePulseStore__=function(s){window.__PULSE_STORE__=Object.assign(window.__PULSE_STORE__||{},s);};</script>`
+    return `<script nonce="${nonce}">window.__PULSE_NONCE__='${nonce}';${liveFlag}window.__PULSE_STORE__=${safeJson(storeState)};window.__updatePulseStore__=function(s){window.__PULSE_STORE__=Object.assign(window.__PULSE_STORE__||{},s);};</script>`
   }
   return `<script nonce="${nonce}">window.__PULSE_NONCE__='${nonce}';${liveFlag}</script>`
 }
@@ -373,7 +373,7 @@ export function wrapDocument({ content, spec = {}, serverState = {}, storeState
   const deferredStyleLinks = (meta.deferredStyles || []).length > 0
     ? `<script nonce="${nonce}">(function(){${
         (meta.deferredStyles || []).map(href =>
-          `var l=document.createElement('link');l.rel='stylesheet';l.href='${esc(href)}';document.head.appendChild(l);`
+          `var l=document.createElement('link');l.rel='stylesheet';l.href=${safeJson(href)};document.head.appendChild(l);`
         ).join('')
       }})();</script>`
     : ''
@@ -383,14 +383,14 @@ export function wrapDocument({ content, spec = {}, serverState = {}, storeState
     .join('\n  ')
 
   const schemaScript = meta.schema
-    ? `<script type="application/ld+json">${JSON.stringify(meta.schema)}</script>`
+    ? `<script type="application/ld+json">${safeJson(meta.schema)}</script>`
     : ''
 
   // Serialise server state into the page so the client runtime can read it
   // without making a second request. Only needed when the page is hydrated —
   // purely server-rendered pages have no JS to read it.
   const serverStateScript = spec.hydrate && Object.keys(serverState).length > 0
-    ? `<script nonce="${nonce}">window.__PULSE_SERVER__ = ${JSON.stringify(serverState)};</script>`
+    ? `<script nonce="${nonce}">window.__PULSE_SERVER__ = ${safeJson(serverState)};</script>`
     : ''
 
   const storeStateScript = buildStoreScript(spec, storeState, nonce, livePath)
@@ -677,6 +677,22 @@ function isBundle(hydratePath) {
   return typeof hydratePath === 'string' && hydratePath.startsWith('/dist/')
 }
 
+/**
+ * JSON.stringify for embedding inside an inline <script>. Plain JSON.stringify
+ * leaves `<`, `>` and `&` alone, so a value containing "</script>" (or "<!--")
+ * ends the script element early and the rest is parsed as HTML. Escaping those
+ * as \uXXXX keeps the output valid JS/JSON with the same parsed value. U+2028/9
+ * are escaped too (line terminators in JS string literals before ES2019).
+ */
+export function safeJson(value) {
+  return JSON.stringify(value)
+    ?.replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029')
+}
+
 /**
  * Escape HTML special characters for safe attribute insertion.
  */

package/src/runtime/ssr.test.js

@@ -3,7 +3,7 @@
  * run: node src/runtime/ssr.test.js
  */
 
-import { renderToString, renderToStream, renderToNavStream, wrapDocument, withTimeout } from './ssr.js'
+import { renderToString, renderToStream, renderToNavStream, wrapDocument, withTimeout, safeJson } from './ssr.js'
 
 // ---------------------------------------------------------------------------
 // Test runner
@@ -705,5 +705,46 @@ await test('stream.scope: meta arrives before slow deferred fetcher resolves', a
 
 // ---------------------------------------------------------------------------
 
+console.log('\nScript-context serialisation\n')
+
+const HOSTILE = '</script><img src=x onerror=alert(1)><!-- \u2028 & '
+
+await test('safeJson never emits < > & or line separators, and round-trips the value', () => {
+  const value = { a: HOSTILE, nested: [HOSTILE], n: 1 }
+  const out   = safeJson(value)
+  assert(!/[<>&\u2028\u2029]/.test(out), `unsafe character left in: ${out}`)
+  assert(JSON.stringify(JSON.parse(out)) === JSON.stringify(value), 'value changed in round trip')
+})
+
+await test('safeJson(undefined) stays undefined like JSON.stringify', () => {
+  assert(safeJson(undefined) === undefined)
+})
+
+await test('wrapDocument cannot be broken out of via server state, store state or schema', () => {
+  const { html } = wrapDocument({
+    content: '<p>x</p>',
+    spec: { hydrate: '/dist/x.boot-1.js', meta: { title: 't', schema: { name: HOSTILE } } },
+    serverState: { comment: HOSTILE },
+    storeState: { note: HOSTILE },
+    nonce: 'abc',
+  })
+  assert(!html.includes('</script><img'), 'script element was closed early by data')
+  assert(!html.includes('onerror=alert(1)><!--'), 'raw hostile payload reached the document')
+  const state = html.match(/window\.__PULSE_SERVER__ = (.*?);<\/script>/s)[1]
+  assert(JSON.stringify(JSON.parse(state)) === JSON.stringify({ comment: HOSTILE }), 'state changed in round trip')
+})
+
+await test('wrapDocument deferred style hrefs are emitted as safe JS strings', () => {
+  const { html } = wrapDocument({
+    content: '',
+    spec: { meta: { title: 't', deferredStyles: ["/a.css';alert(1);//", '/b\\'] } },
+    nonce: 'abc',
+  })
+  assert(html.includes(`l.href="/a.css';alert(1);//"`), 'href must be a JSON string literal')
+  assert(html.includes('l.href="/b\\\\"'), 'trailing backslash must be escaped')
+})
+
+// ---------------------------------------------------------------------------
+
 console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)
 if (failed > 0) process.exit(1)

package/src/server/index.js

@@ -21,7 +21,7 @@ import { createRequire } from 'module'
 
 const _require = createRequire(import.meta.url)
 export const version = _require('../../package.json').version
-import { renderToString, renderToStream, renderToNavStream, wrapDocument, resolveServerState, buildStoreScript, buildHydrateScript, buildStylePreconnects } from '../runtime/ssr.js'
+import { renderToString, renderToStream, renderToNavStream, wrapDocument, resolveServerState, buildStoreScript, buildHydrateScript, buildStylePreconnects, safeJson } from '../runtime/ssr.js'
 import { validateSpec } from '../spec/schema.js'
 import { validateStore, resolveStoreState } from '../store/index.js'
 
@@ -1422,7 +1422,7 @@ async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = f
           ).join('')
         }})();</script>`
       : '',
-    meta.schema ? `  <script type="application/ld+json">${JSON.stringify(meta.schema)}</script>` : '',
+    meta.schema ? `  <script type="application/ld+json">${safeJson(meta.schema)}</script>` : '',
   ].filter(Boolean).join('\n')
 
   const bodyAttr = [