@statorjs/stator 1.2.0 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Server-canonical web framework: business logic in composable state machines, UI as a thin renderer binding machine outputs to DOM positions. Ships TypeScript source (Vite/tsx-native by design).",
   "license": "MIT",
   "type": "module",
@@ -88,7 +88,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "1.2.0"
+    "@statorjs/stator": "1.2.1"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/client/use.ts

@@ -85,7 +85,10 @@ export function use<D extends MachineDef>(
         context: { ...(def.context as object), ...eager },
       }
     : undefined
-  const actor = createActor(def as AnyMachineDef, { snapshot })
+  // Client islands honor framework-internal events (`@set` for two-way
+  // `bind:value`); the actor lives in the browser and only its own compiled
+  // bind code sends them. Server actors deliberately do NOT (see createActor).
+  const actor = createActor(def as AnyMachineDef, { snapshot, internalEvents: true })
 
   // Register with the element under construction so its lifecycle owns the actor.
   const bucket = collectors[collectors.length - 1]

package/src/engine/actor.ts

@@ -57,6 +57,12 @@ export interface CreateActorOptions<C> {
    *  effect locally on a microtask and sends its completion event to itself —
    *  the client-plane (and unit-test) behavior. */
   onEffect?: (invocation: EffectInvocation) => void
+  /** Honor framework-internal events (currently `@set`, which powers two-way
+   *  `bind:value`). Enabled ONLY for client-island actors, whose `@set` events
+   *  originate from their own compiled bind code. Server actors leave this off:
+   *  they take events straight from the untrusted wire (`/__events`), where a
+   *  `@set` would be an arbitrary-context-write that bypasses every guard. */
+  internalEvents?: boolean
 }
 
 /** Unique per-invocation effect id — usable as an idempotency key, so it must
@@ -125,9 +131,13 @@ export function createActor<C extends object, E extends EventObject, S extends s
     },
 
     send(event: E) {
-      // Built-in `@set`: assign one context key. Powers two-way `bind:value`
-      // (DOM → state) without a per-field transition. Available in every state.
-      if ((event as { type: string }).type === '@set') {
+      // Framework-internal `@set`: assign one context key. Powers two-way
+      // `bind:value` (DOM → state) on client islands without a per-field
+      // transition. Honored ONLY when the host opted in (`internalEvents`) —
+      // server actors never do, so a wire-delivered `@set` falls through to
+      // ordinary (unhandled) resolution and mutates nothing. Without this gate
+      // `@set` is a guard-bypassing arbitrary-context write over `/__events`.
+      if (opts.internalEvents && (event as { type: string }).type === '@set') {
         const e = event as unknown as { key: string; value: unknown }
         context = { ...context, [e.key]: e.value }
         commits += 1

package/src/server/api-route.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto'
 import type { Context } from 'hono'
 import { setCookie } from 'hono/cookie'
+import { safeNavigationUrl } from '../wire/safe-url.ts'
 import { scheduleSessionEffects } from './effects.ts'
 import { scopedLogger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
@@ -124,6 +125,21 @@ export async function runApiRoute(
   })
 }
 
+/** The Referer header is attacker-controllable, so redirecting back to it is an
+ *  open-redirect vector. Return a same-origin relative path (pathname+search)
+ *  when the referer matches this request's origin, else '/'. */
+function sameOriginReferer(request: RouteRequest): string {
+  const ref = request.headers.get('referer')
+  if (!ref) return '/'
+  try {
+    const refUrl = new URL(ref)
+    if (refUrl.origin !== new URL(request.url).origin) return '/'
+    return `${refUrl.pathname}${refUrl.search}`
+  } catch {
+    return '/'
+  }
+}
+
 /**
  * Content-negotiated response synthesis from a directives envelope.
  *
@@ -146,12 +162,14 @@ function synthesizeResponse(
       (d): d is Extract<Directive, { type: 'navigate' }> => d.type === 'navigate',
     )
     if (navigate) {
-      return c.redirect(navigate.to, 303)
+      // Never emit a javascript:/vbscript:/data: Location — coerce to '/'.
+      return c.redirect(safeNavigationUrl(navigate.to), 303)
     }
     const reload = envelope.directives?.find((d) => d.type === 'reload')
     if (reload) {
-      const ref = request.headers.get('referer') ?? '/'
-      return c.redirect(ref, 303)
+      // The Referer is attacker-controllable; only bounce back to it when it's
+      // same-origin, else fall back to '/' (no open redirect).
+      return c.redirect(sameOriginReferer(request), 303)
     }
     // No actionable directive for a no-JS client. Send a minimal 204.
     return new Response(null, { status: 204 })

package/src/server/csrf.ts

@@ -0,0 +1,31 @@
+import type { Context } from 'hono'
+
+/**
+ * CSRF signal check for state-changing requests. The session cookie
+ * (`stator_sid`) is `SameSite=Lax`, which already withholds itself from most
+ * cross-site POSTs — this is defense-in-depth using the browser-supplied
+ * request metadata (`Sec-Fetch-Site`, falling back to `Origin`).
+ *
+ * Only browser-originated cross-origin writes are rejected. Requests with no
+ * such signal (server-to-server API/webhook callers, the test harness) pass —
+ * they carry no ambient cookie authority a forgery could abuse, and the header
+ * is browser-only, so a real browser can never suppress it.
+ *
+ * Note the primary vector blocked is `cross-site`. `same-site` (sibling
+ * subdomain) is allowed so legitimate multi-subdomain deployments keep working;
+ * harden with `SameSite=Strict` / an app-level check if subdomains are
+ * untrusted.
+ */
+export function isBlockedCrossSite(c: Context): boolean {
+  const site = c.req.header('sec-fetch-site')
+  if (site) return site === 'cross-site'
+  const origin = c.req.header('origin')
+  if (origin) {
+    try {
+      return new URL(origin).host !== new URL(c.req.url).host
+    } catch {
+      return true
+    }
+  }
+  return false
+}

package/src/server/http.ts

@@ -1,11 +1,12 @@
 import { readFile } from 'node:fs/promises'
-import { dirname, extname, resolve } from 'node:path'
+import { dirname, extname, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { build } from 'esbuild'
 import { type Context, Hono } from 'hono'
 import { streamSSE } from 'hono/streaming'
 import { z } from 'zod'
 import { applyRenderedEffects, runApiRoute } from './api-route.ts'
+import { isBlockedCrossSite } from './csrf.ts'
 import { scheduleSessionEffects } from './effects.ts'
 import { scopedLogger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
@@ -161,12 +162,20 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
   }
 
   if (config.staticDir) {
-    const staticDir = config.staticDir
+    const staticDir = resolve(config.staticDir)
     app.get('/static/*', async (c) => {
       const rel = c.req.path.replace(/^\/static\//, '')
-      if (rel.includes('..')) return c.text('forbidden', 403)
+      // Containment check: resolve, then require the result to stay under
+      // staticDir. This defeats `..` traversal AND absolute-path escapes —
+      // `/static//etc/passwd` yields rel `/etc/passwd`, which `resolve` would
+      // otherwise honor verbatim (discarding staticDir) and serve. A lexical
+      // `..` check alone misses the absolute-path case.
+      const full = resolve(staticDir, rel)
+      if (full !== staticDir && !full.startsWith(staticDir + sep)) {
+        return c.text('forbidden', 403)
+      }
       try {
-        const buf = await readFile(resolve(staticDir, rel))
+        const buf = await readFile(full)
         c.header('Content-Type', contentTypeFor(rel))
         return c.body(buf)
       } catch {
@@ -260,6 +269,9 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
   })
 
   app.post('/__events', async (c) => {
+    if (isBlockedCrossSite(c)) {
+      return c.json({ error: 'cross-site request blocked' }, 403)
+    }
     const { sessionId } = getOrCreateSessionId(c)
     const routeKey = c.req.header('X-Stator-Route')
     if (!routeKey) {
@@ -287,6 +299,16 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
       return c.json({ error: 'invalid event payload', detail: String(e) }, 400)
     }
 
+    // Reserved `@`-prefixed events (e.g. the engine's built-in `@set`) are
+    // framework-internal and only ever originate in-browser for client-island
+    // binds. They must never reach a server machine from the wire, where `@set`
+    // would be a guard-bypassing arbitrary-context write. Server actors also
+    // ignore them (createActor without `internalEvents`); this is the clean
+    // 400 at the boundary rather than a silent no-op.
+    if (body.event.type.startsWith('@')) {
+      return c.json({ error: `event type "${body.event.type}" is reserved` }, 400)
+    }
+
     const originDef = config.store.getDef(body.machine)
     if (!originDef) {
       return c.json({ error: `unknown machine "${body.machine}"` }, 404)
@@ -339,6 +361,7 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
       const matched = matchPath(matchers, c.req.path)
       const apiRoute = matched?.route[method]
       if (!matched || !apiRoute) return next()
+      if (isBlockedCrossSite(c)) return c.text('cross-site request blocked', 403)
       return runApiRoute(c, matched.route, apiRoute, config.store, matched.params)
     })
   }

package/src/server/recompute.ts

@@ -1,6 +1,7 @@
 import { renderBranchBody } from '../template/conditional.ts'
 import { coerceKeys, renderKeyedItem, renderListBody } from '../template/each.ts'
 import type { Patch } from '../wire/index.ts'
+import { isUrlAttribute, safeAttrUrl } from '../wire/safe-url.ts'
 import {
   keyedScopePrefix,
   keyToken,
@@ -68,7 +69,7 @@ export function recompute(
             target: { kind: 'element', id: binding.parentId },
             op: 'attr',
             name: binding.attrName,
-            value: attrWireValue(newValue),
+            value: sanitizeAttrWire(binding.attrName, attrWireValue(newValue)),
           },
           sourceSlot: slotId,
         })
@@ -285,3 +286,12 @@ function attrWireValue(v: unknown): string | null {
   if (v === true) return ''
   return stringify(v)
 }
+
+/** Mirror of html.ts `sanitizeAttrValue` for the live-update path: strip a
+ *  javascript:/vbscript: value from a url-bearing attribute patch so a binding
+ *  that was safe at first render can't turn dangerous via a diff. Null
+ *  (attribute-absent) passes through. */
+function sanitizeAttrWire(attrName: string, value: string | null): string | null {
+  if (value === null) return null
+  return isUrlAttribute(attrName) ? safeAttrUrl(value) : value
+}

package/src/server/session-lock.ts

@@ -11,11 +11,52 @@
  *
  * GETs are read-only and do not acquire the lock.
  */
+import { scopedLogger } from './logger.ts'
+
+const lockLog = scopedLogger('session-lock')
 const sessionLocks = new Map<string, Promise<unknown>>()
 
+/** A single mutation that neither resolves nor rejects (a hung store I/O, a
+ *  wedged effect) would otherwise pin the session's whole promise chain
+ *  forever — every later mutation queues behind it with no recovery. This cap
+ *  converts a hang into a rejection so the chain drains. The abandoned work may
+ *  still complete in the background, so the timeout is generous (a real
+ *  mutation is milliseconds); it's a wedge backstop, not a deadline. */
+const LOCK_TIMEOUT_MS = 30_000
+
+function withTimeout<T>(sid: string, fn: () => Promise<T>): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    let done = false
+    const timer = setTimeout(() => {
+      if (done) return
+      done = true
+      lockLog.error({ sid, ms: LOCK_TIMEOUT_MS }, 'session lock timed out — mutation abandoned')
+      reject(new Error(`stator: session "${sid}" lock held > ${LOCK_TIMEOUT_MS}ms — abandoned`))
+    }, LOCK_TIMEOUT_MS)
+    ;(timer as unknown as { unref?: () => void }).unref?.()
+    Promise.resolve()
+      .then(fn)
+      .then(
+        (v) => {
+          if (done) return
+          done = true
+          clearTimeout(timer)
+          resolve(v)
+        },
+        (e) => {
+          if (done) return
+          done = true
+          clearTimeout(timer)
+          reject(e)
+        },
+      )
+  })
+}
+
 export function withSessionLock<T>(sid: string, fn: () => Promise<T>): Promise<T> {
   const prev = sessionLocks.get(sid) ?? Promise.resolve()
-  const next = prev.then(fn, fn)
+  const run = () => withTimeout(sid, fn)
+  const next = prev.then(run, run)
   const settled = next.then(
     () => undefined,
     () => undefined,

package/src/template/directives/list-attr.ts

@@ -119,11 +119,24 @@ function walkStyle(spec: StyleListSpec, out: string[]): void {
     for (const [prop, raw] of Object.entries(spec)) {
       const value = evalRead(raw)
       if (value == null || value === '') continue
-      out.push(`${prop}: ${value}`)
+      // A single property's value must not carry `;` — a `read()`-sourced value
+      // like `red; position: fixed; …` would otherwise inject extra
+      // declarations (overlay / `url()` exfil). Cut at the first `;`.
+      const safe = cssValue(String(value))
+      if (safe === '') continue
+      out.push(`${prop}: ${safe}`)
     }
   }
 }
 
+/** One declaration's value: everything up to the first `;` (the declaration
+ *  separator), trimmed. Blocks reactive CSS-value injection while leaving legit
+ *  values — including `url(...)` — intact. */
+function cssValue(v: string): string {
+  const semi = v.indexOf(';')
+  return (semi === -1 ? v : v.slice(0, semi)).trim()
+}
+
 /**
  * Register one attr-binding per unique machine the spec depends on. Each
  * binding's selector ignores its arg and recomputes the entire attribute

package/src/template/html.ts

@@ -3,6 +3,7 @@ import {
   registerBinding,
   requireCurrentRenderState,
 } from '../server/render-context.ts'
+import { isUrlAttribute, safeAttrUrl } from '../wire/safe-url.ts'
 import { escapeAttribute, escapeText, HtmlBuilder, type ValuePosition } from './parser.ts'
 import { createHtmlFragment, type HtmlFragment, isHtmlFragment } from './types.ts'
 
@@ -43,6 +44,14 @@ export function html(strings: TemplateStringsArray, ...values: unknown[]): HtmlF
   return createHtmlFragment(builder.toString())
 }
 
+/** URL-scheme guard for attribute interpolation: on url-bearing attributes
+ *  (href/src/…), strip a javascript:/vbscript: value; other attributes pass
+ *  through unchanged. Mirrored on the live-update path (server/recompute.ts) so
+ *  a value that's safe at first render can't turn dangerous via a patch. */
+function sanitizeAttrValue(attrName: string, value: string): string {
+  return isUrlAttribute(attrName) ? safeAttrUrl(value) : value
+}
+
 function processValue(builder: HtmlBuilder, state: RenderState, value: unknown): void {
   const pos = builder.positionForValue()
   if (pos.kind === 'invalid') {
@@ -101,7 +110,7 @@ function processValue(builder: HtmlBuilder, state: RenderState, value: unknown):
     return
   }
   if (pos.kind === 'attr-value') {
-    builder.pushRaw(escapeAttribute(stringifyValue(value)))
+    builder.pushRaw(escapeAttribute(sanitizeAttrValue(pos.attrName, stringifyValue(value))))
     return
   }
   throw new Error(`stator: cannot interpolate a plain value at ${pos.kind} position`)
@@ -164,7 +173,7 @@ function handleRead(
     if (r.value === false || r.value === null || r.value === undefined) {
       builder.omitCurrentAttribute()
     } else if (r.value !== true) {
-      builder.pushRaw(escapeAttribute(stringifyValue(r.value)))
+      builder.pushRaw(escapeAttribute(sanitizeAttrValue(pos.attrName, stringifyValue(r.value))))
     }
     return
   }

package/src/template/parser.ts

@@ -336,6 +336,7 @@ export function escapeAttribute(s: string): string {
   return s
     .replace(/&/g, '&')
     .replace(/"/g, '"')
+    .replace(/'/g, ''')
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')
 }

package/src/wire/apply.ts

@@ -9,6 +9,7 @@
  * path applied it.
  */
 import type { Directive, Patch } from './index.ts'
+import { isSafeNavigationUrl } from './safe-url.ts'
 
 function emit(name: string, detail: unknown): void {
   window.dispatchEvent(new CustomEvent(name, { detail }))
@@ -66,15 +67,29 @@ export function applyDirectives(directives: Directive[]): void {
     emit('stator:directive-applied', { directive, timestamp: Date.now() })
     switch (directive.type) {
       case 'navigate':
+        // Reject javascript:/vbscript:/data: targets — a navigation directive
+        // must not be an in-page script sink or off-document jump.
+        if (!isSafeNavigationUrl(directive.to)) {
+          console.error('stator: refusing unsafe navigate target', directive.to)
+          return
+        }
         location.href = directive.to
         return // stop processing further directives; we're leaving
       case 'reload':
         location.reload()
         return
       case 'push-url':
+        if (!isSafeNavigationUrl(directive.to)) {
+          console.error('stator: refusing unsafe push-url target', directive.to)
+          break
+        }
         history.pushState({}, '', directive.to)
         break
       case 'replace-url':
+        if (!isSafeNavigationUrl(directive.to)) {
+          console.error('stator: refusing unsafe replace-url target', directive.to)
+          break
+        }
         history.replaceState({}, '', directive.to)
         break
       case 'focus': {

package/src/wire/safe-url.ts

@@ -0,0 +1,67 @@
+/**
+ * URL-scheme safety — shared by the client directive applier (`wire/apply.ts`)
+ * and the server render/redirect paths (`template/html.ts`,
+ * `server/recompute.ts`, `server/api-route.ts`). One implementation so the two
+ * planes can't drift on what counts as a dangerous URL.
+ *
+ * The framework does no URL-scheme validation otherwise, so a user-controlled
+ * `href`/`src` or navigation target can carry `javascript:` (script execution)
+ * or an off-site/`data:` document. These helpers reject the never-legitimate
+ * schemes while leaving ordinary relative and `http(s)`/`mailto:`/`tel:` URLs —
+ * and, for attributes, `data:` images — untouched.
+ */
+
+/** Normalize for the scheme check ONLY (we still render the original value).
+ *  Browsers ignore leading control chars/whitespace and strip TAB/LF/CR from
+ *  within a scheme, so `\x01java\tscript:` must be caught. The `^` anchor in
+ *  the callers means removing interior whitespace can't create a false match on
+ *  a legitimate `http(s)` URL. Strips ASCII space/controls (<= 0x20) and C1
+ *  controls (0x7f–0x9f) without embedding a control-char regex literal. */
+function stripForSchemeCheck(url: string): string {
+  let out = ''
+  for (let i = 0; i < url.length; i++) {
+    const code = url.charCodeAt(i)
+    if (code > 0x20 && !(code >= 0x7f && code <= 0x9f)) out += url[i]
+  }
+  return out
+}
+
+/** Script-executing schemes — never legitimate in any attribute or navigation. */
+const SCRIPT_SCHEME = /^(?:javascript|vbscript):/i
+/** Adds `data:` — dangerous as a navigation target (renders as a document),
+ *  but allowed in resource attributes like `img src` (data-URI images). */
+const NAV_SCHEME = /^(?:javascript|vbscript|data):/i
+
+/** Safe as a navigation target (`location.href`, an HTTP redirect)? */
+export function isSafeNavigationUrl(url: string): boolean {
+  return !NAV_SCHEME.test(stripForSchemeCheck(url))
+}
+
+/** Coerce a navigation target: dangerous-scheme URLs collapse to `fallback`. */
+export function safeNavigationUrl(url: string, fallback = '/'): string {
+  return isSafeNavigationUrl(url) ? url : fallback
+}
+
+/** Attribute names whose values are fetched/navigated as URLs. */
+const URL_ATTRS = new Set([
+  'href',
+  'src',
+  'action',
+  'formaction',
+  'xlink:href',
+  'poster',
+  'background',
+  'cite',
+  'ping',
+])
+
+export function isUrlAttribute(name: string): boolean {
+  return URL_ATTRS.has(name.toLowerCase())
+}
+
+/** Sanitize a URL attribute value: strip an ever-illegitimate script scheme
+ *  (`javascript:`/`vbscript:`) to an empty value; leave everything else
+ *  (relative, http(s), mailto, tel, and `data:` images) intact. */
+export function safeAttrUrl(value: string): string {
+  return SCRIPT_SCHEME.test(stripForSchemeCheck(value)) ? '' : value
+}