@invisibleloop/pulse 0.20.52 → 0.20.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.20.52",
+  "version": "0.20.53",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",
@@ -76,7 +76,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/cli/feedback.test.js && node src/cli/update.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",
+    "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/cli/feedback.test.js && node src/cli/update.test.js && node src/cli/dev-host.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.52
+0.20.53

package/src/agent/guide-server.md

@@ -371,6 +371,19 @@ export default {
 }
 ```
 
+## Production behind a proxy — pin the public origin
+
+By default Pulse builds `<link rel="canonical">`, `sitemap.xml` and `robots.txt` from the request's `Host`, `X-Forwarded-Host` and `X-Forwarded-Proto` headers. Anyone can send those headers, and a CDN that ignores `Vary` will cache the result for everyone — one forged request can point every visitor's canonical URL at another domain. For a real deployment, pin the origin:
+
+```js
+// pulse.config.js
+export default {
+  origin: 'https://example.com',   // canonical + sitemap + robots use this; headers are ignored
+}
+```
+
+It must be an absolute http(s) URL (a bad value fails at startup). `sitemap: { origin }` still wins for the sitemap if you set both. Also set `host: '127.0.0.1'` in `pulse.config.js` if a reverse proxy on the same machine is the only thing that should reach the server. `pulse dev` already listens on `127.0.0.1`; use `pulse dev --host 0.0.0.0` for phone testing or a container.
+
 ## Health check endpoint
 
 Pulse exposes a built-in health check at `/healthz` by default. It responds **before** `onRequest`, static files, and route matching — so load balancers always get a response.

package/src/cli/dev.js

@@ -21,6 +21,7 @@ import * as log         from './logger.js'
 const args     = process.argv.slice(2)
 const rootArg  = args.indexOf('--root')
 const portArg  = args.indexOf('--port')
+const hostArg  = args.indexOf('--host')
 
 const ROOT = rootArg !== -1
   ? path.resolve(args[rootArg + 1])
@@ -295,6 +296,10 @@ const reloadScript = (nonce) => `<script nonce="${nonce}">
 
 const { updateSpecs, updateStore } = await createServer(specs, {
   port:      PORT,
+  // Loopback by default: the dev server has dev-only endpoints and stack-trace error
+  // pages, and should not be reachable from the LAN. `--host 0.0.0.0` (or `host` in
+  // pulse.config.js) opts in — e.g. for testing on a phone, or inside a container.
+  host:      (hostArg !== -1 && args[hostArg + 1]) || _config.host || '127.0.0.1',
   stream:    true,
   staticDir: fs.existsSync(PUBLIC_DIR) ? PUBLIC_DIR : null,
   manifest:  {},        // never use a build manifest in dev — always serve source files
@@ -305,7 +310,7 @@ const { updateSpecs, updateStore } = await createServer(specs, {
   ...(_config.csp ? { csp: _config.csp } : {}),
   // Server options forwarded verbatim from pulse.config.js so dev behaves like
   // production — keep in sync with start.js PASSTHROUGH_OPTIONS
-  ...(['redirects', 'sitemap', 'robots', 'secret', 'live', 'trailingSlash', 'fetcherTimeout', 'maxBody'].reduce(
+  ...(['redirects', 'sitemap', 'robots', 'secret', 'live', 'trailingSlash', 'fetcherTimeout', 'maxBody', 'origin'].reduce(
     (acc, k) => (_config[k] !== undefined ? { ...acc, [k]: _config[k] } : acc), {})),
 
   onRequest(req, res) {

package/src/cli/start.js

@@ -48,7 +48,7 @@ let csp          = null
 let passthrough  = {}
 
 // Server options forwarded verbatim from pulse.config.js — keep in sync with dev.js
-const PASSTHROUGH_OPTIONS = ['redirects', 'sitemap', 'robots', 'secret', 'live', 'trailingSlash', 'fetcherTimeout', 'maxBody']
+const PASSTHROUGH_OPTIONS = ['redirects', 'sitemap', 'robots', 'secret', 'live', 'trailingSlash', 'fetcherTimeout', 'maxBody', 'origin', 'host']
 
 const configPath = path.join(ROOT, 'pulse.config.js')
 if (fs.existsSync(configPath)) {

package/src/server/index.js

@@ -614,6 +614,11 @@ export async function createServer(entries, options = {}) {
     staticDir     = null,
     manifest      = null,          // path to manifest.json or plain object
     trailingSlash = 'remove',      // 'remove' | 'add' | 'allow'
+    origin: pinOrigin = null,      // pin the public origin, e.g. 'https://example.com': used for
+                                   // <link rel="canonical">, sitemap.xml and robots.txt INSTEAD of the
+                                   // Host / X-Forwarded-* headers, which a client (or a CDN that ignores
+                                   // Vary) can forge. Recommended in production.
+    host: listenHost = null,       // interface to listen on (default: all). `pulse dev` uses 127.0.0.1.
     extraBody     = '',            // extra HTML injected before </body> on every page
     dev           = false,         // dev mode — show detailed error pages
     store         = null,          // global store definition (pulse.store.js default export)
@@ -653,6 +658,17 @@ export async function createServer(entries, options = {}) {
     quiet          = false,        // suppress request logging
   } = options
 
+  // A pinned origin must be a bare http(s) origin; normalise it ("https://example.com/x" -> "https://example.com").
+  let pinnedOrigin = null
+  if (pinOrigin != null) {
+    let u = null
+    try { u = new URL(String(pinOrigin)) } catch { /* rejected below */ }
+    if (!u || (u.protocol !== 'http:' && u.protocol !== 'https:')) {
+      throw new Error(`createServer: origin must be an absolute http(s) URL such as "https://example.com" (got ${JSON.stringify(pinOrigin)})`)
+    }
+    pinnedOrigin = u.origin
+  }
+
   // Resolve URL entries → spec objects, auto-setting hydrate where needed
   const specs = await resolveSpecEntries(entries, root)
 
@@ -794,7 +810,7 @@ export async function createServer(entries, options = {}) {
   // Sitemap — track the live spec list (updated on hot reload) and surface a
   // startup hint for dynamic routes that can't be enumerated automatically.
   const sitemapEnabled = !!sitemap
-  const sitemapOrigin  = (typeof sitemap === 'object' && sitemap?.origin) ? String(sitemap.origin).replace(/\/$/, '') : null
+  const sitemapOrigin  = ((typeof sitemap === 'object' && sitemap?.origin) ? String(sitemap.origin).replace(/\/$/, '') : null) || pinnedOrigin
   let   allSpecs       = specs
   if (sitemapEnabled && !quiet) {
     const unenumerated = specs.filter(s =>
@@ -1157,7 +1173,7 @@ export async function createServer(entries, options = {}) {
       const canonicalPath = trailingSlash === 'add' && pathname !== '/'
         ? (pathname.endsWith('/') ? pathname : pathname + '/')
         : (pathname !== '/' && pathname.endsWith('/') ? pathname.slice(0, -1) : pathname)
-      const canonicalBase = `${proto}://${host}${canonicalPath}`
+      const canonicalBase = pinnedOrigin ? `${pinnedOrigin}${canonicalPath}` : `${proto}://${host}${canonicalPath}`
 
       // Raw content spec (RSS, sitemap, JSON API, webhooks) — bypass HTML pipeline
       if (spec.contentType) {
@@ -1261,7 +1277,7 @@ export async function createServer(entries, options = {}) {
   process.on('SIGTERM', shutdown)
   process.on('SIGINT',  shutdown)
 
-  server.listen(port, () => {
+  const onListening = () => {
     import('../cli/logger.js').then(({ banner }) => {
       banner({
         url:       `http://localhost:${port}`,
@@ -1272,7 +1288,9 @@ export async function createServer(entries, options = {}) {
     }).catch(() => {
       console.log(`⚡ Pulse running at http://localhost:${port}`)
     })
-  })
+  }
+  if (listenHost) server.listen(port, listenHost, onListening)
+  else            server.listen(port, onListening)
 
   return {
     server,

package/types/server.d.ts

@@ -36,6 +36,21 @@ export interface ServerOptions {
    */
   trailingSlash?: 'remove' | 'add' | 'allow'
 
+  /**
+   * Pin the site's public origin, e.g. `'https://example.com'`. Used for `<link rel="canonical">`,
+   * `sitemap.xml` and `robots.txt` INSTEAD of the `Host` / `X-Forwarded-Host` / `X-Forwarded-Proto`
+   * headers, which a client — or a CDN that ignores `Vary` — can forge to poison those URLs.
+   * Recommended in production. An explicit `sitemap.origin` still takes precedence for the sitemap.
+   * Must be an absolute http(s) URL; anything after the origin is dropped.
+   */
+  origin?: string
+
+  /**
+   * Network interface to listen on. Default: all interfaces (what a server behind a proxy or in
+   * a container needs). `pulse dev` passes `'127.0.0.1'` unless told otherwise.
+   */
+  host?: string
+
   /** Maximum request body size in bytes. Default 1 MB. Requests exceeding this receive a 413. */
   maxBody?: number