@statorjs/stator 1.2.0 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "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.2"
   },
   "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/compiler/virtual-code.ts

@@ -18,6 +18,7 @@
  * load-bearing part.
  */
 
+import ts from 'typescript'
 import { analyzeScriptClasses } from './client-script.ts'
 import { componentPropsType, extractFrontmatterTypes } from './dts.ts'
 import { type ScannedRegions, scanRegions } from './split.ts'
@@ -131,24 +132,29 @@ export function toVirtualCode(source: string): VirtualCodeResult {
   }
 }
 
-/** Server component: frontmatter (module scope) + template as a JSX fragment, so
- *  template expressions see the frontmatter's bindings. */
+/** Server component: import/type/interface declarations hoist to module scope;
+ *  the executable frontmatter body + the template (a JSX fragment) live inside
+ *  the render function, so template expressions see the frontmatter's bindings.
+ *
+ *  The body is deliberately NOT at module scope: it runs as a synchronous
+ *  function body at runtime (compile.ts wraps it the same way), so modelling it
+ *  as one here is what makes top-level `await` / `return` the TS errors they
+ *  should be. Emitting the body at module scope (the previous shape) silently
+ *  made them legal in-editor while diverging from runtime semantics. */
 function buildServerTsx(regions: ScannedRegions): VirtualFile {
   const mappings: VirtualMapping[] = []
-  const userCode = (regions.frontmatter?.content ?? '') + regions.template.content
+  const fm = regions.frontmatter?.content ?? ''
+  const fmOffset = regions.frontmatter?.contentOffset ?? 0
+  const userCode = fm + regions.template.content
   let code =
     injectImports(TEMPLATE_GLOBALS, '@statorjs/stator/template', userCode) +
     AMBIENT_TYPE_IMPORTS +
     STATOR_AMBIENT
 
-  if (regions.frontmatter?.content.trim()) {
-    push(
-      mappings,
-      regions.frontmatter.contentOffset,
-      code.length,
-      regions.frontmatter.content.length,
-    )
-    code += `${regions.frontmatter.content}\n`
+  const { hoisted, body } = splitFrontmatter(fm, fmOffset)
+  for (const seg of hoisted) {
+    push(mappings, seg.sourceOffset, code.length, seg.text.length)
+    code += `${seg.text}\n`
   }
 
   // A leading <!doctype> is static HTML, not JSX — drop it from the shell (no
@@ -162,17 +168,18 @@ function buildServerTsx(regions: ScannedRegions): VirtualFile {
   }
 
   // `export default function` gives importers a default export (`import X from
-  // './x.stator'`) and puts the template in a scope that closes over the
-  // frontmatter bindings. The param is typed from `Stator.props<P>()` (same
-  // extraction as the .d.ts generator), so `<Component bad={...}/>` in OTHER
-  // .stator files is checked in-editor — TS validates value-based JSX against
-  // the component function's first parameter. Named prop types resolve
-  // because the frontmatter is emitted into this same module above.
-  const propsT = componentPropsType(
-    extractFrontmatterTypes(regions.frontmatter?.content ?? '').propsType,
-    regions.template.content,
-  )
-  code += `export default function (_props: ${propsT}) {\n  return (<>`
+  // './x.stator'`) and a scope that closes over the frontmatter body. The param
+  // is typed from `Stator.props<P>()` (same extraction as the .d.ts generator),
+  // so `<Component bad={...}/>` in OTHER .stator files is checked in-editor.
+  // Named prop types resolve because their type/interface decls hoisted above.
+  const propsT = componentPropsType(extractFrontmatterTypes(fm).propsType, regions.template.content)
+  code += `export default function (_props: ${propsT}) {\n`
+  for (const seg of body) {
+    code += '  '
+    push(mappings, seg.sourceOffset, code.length, seg.text.length)
+    code += `${seg.text}\n`
+  }
+  code += '  return (<>'
   push(mappings, tplOffset, code.length, tpl.length)
   code += tpl
   code += '</>);\n}\n'
@@ -180,6 +187,41 @@ function buildServerTsx(regions: ScannedRegions): VirtualFile {
   return { lang: 'tsx', code, mappings }
 }
 
+interface FmSegment {
+  sourceOffset: number
+  text: string
+}
+
+/**
+ * Split frontmatter into hoisted declarations (import/type/interface — must be
+ * module scope) and body statements (everything else — the render function).
+ * Mirrors the runtime classification in `compile.ts` `processFrontmatter`, so
+ * the editor models the same scoping. Each segment keeps its exact source range
+ * (`getStart`..`getText`) so the mapping stays a verbatim 1:1 run.
+ */
+function splitFrontmatter(
+  fm: string,
+  fmOffset: number,
+): { hoisted: FmSegment[]; body: FmSegment[] } {
+  const hoisted: FmSegment[] = []
+  const body: FmSegment[] = []
+  if (!fm.trim()) return { hoisted, body }
+  const sf = ts.createSourceFile('fm.ts', fm, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+  for (const stmt of sf.statements) {
+    const seg: FmSegment = { sourceOffset: fmOffset + stmt.getStart(sf), text: stmt.getText(sf) }
+    if (
+      ts.isImportDeclaration(stmt) ||
+      ts.isTypeAliasDeclaration(stmt) ||
+      ts.isInterfaceDeclaration(stmt)
+    ) {
+      hoisted.push(seg)
+    } else {
+      body.push(seg)
+    }
+  }
+  return { hoisted, body }
+}
+
 /** Client component: the `<script>` is the module. Emit it as TS so the class,
  *  `use()`/`machine()`, and imports get full intelligence. (Template-member
  *  resolution — `bind:text={theme.label}` → the class field — is a later phase.) */

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
+}