@statorjs/stator 2.1.0 → 2.3.0

package/src/server/dev.ts

@@ -6,11 +6,13 @@ import { getRequestListener } from '@hono/node-server'
 import type { Hono } from 'hono'
 import { createServer as createViteServer, type ViteDevServer } from 'vite'
 import { compile } from '../compiler/index.ts'
+import type { LogLevel } from '../config.ts'
 import type { AnyMachineDef, EventOf } from '../engine/index.ts'
 import { machineStub, stator } from '../vite/index.ts'
 import type { AppStore } from './app-store.ts'
 import { findFreePort, installGracefulShutdown, printDevBanner } from './banner.ts'
-import { logger } from './logger.ts'
+import { resolveAppConfig } from './config-compat.ts'
+import { logger, setLogLevel } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
 import { isStatorQueryRoute } from './routing.ts'
@@ -39,11 +41,49 @@ export interface DevAppConfig {
   machinesDir: string
   routesDir: string
   staticDir?: string
+  /** Swappable persistence adapters, grouped by concern. Both optional —
+   *  default to in-memory. Mirrors `StatorConfig.persistence`. */
+  persistence?: {
+    /** Session-lifecycle machine state. Defaults to InMemoryStore. */
+    session?: Store
+    /** App-lifecycle machine state for `persist: true` machines. Defaults to
+     *  in-memory. */
+    app?: AppStore
+  }
+  /** Session policy. */
+  sessions?: {
+    /** Per-session TTL in seconds. Defaults to 24h (86400). */
+    ttlSeconds?: number
+    /** Session cookie policy. `cookie.sameSite: 'Strict'` opts into the
+     *  controlled CSRF posture. */
+    cookie?: { sameSite?: 'Lax' | 'Strict' }
+  }
+  /** Dev-only tooling. */
+  dev?: {
+    /** Auto-inject the dev inspector toolbar. On by default; set false to disable. */
+    inspector?: boolean
+  }
+  /** Logging policy. */
+  logging?: {
+    /** Minimum level to emit. Default: `info` in dev. `LOG_LEVEL` env wins. */
+    level?: LogLevel
+  }
+  /** Origins allowed to make cross-site writes despite the CSRF guard (exact or
+   *  wildcard-subdomain). Mirrors `StatorConfig.trustedOrigins`. */
+  trustedOrigins?: readonly string[]
+  /** Canonical app URL, exposed via `stator(c).origin`. */
+  origin?: string
+  /** Cross-origin READ policy (CORS); `origins` defaults to `trustedOrigins`. */
+  cors?: { origins?: string[]; credentials?: boolean }
+  // Deprecated flat keys — accepted (typed) so 2.1.0 callers don't break; nested
+  // wins. `createDevApp` never shipped `ssePingMs`, so it's not accepted here.
+  /** @deprecated use `persistence.session` */
   store?: Store
-  /** Persistence for `persist: true` app machines. Defaults to in-memory. */
+  /** @deprecated use `persistence.app` */
   appStore?: AppStore
+  /** @deprecated use `sessions.ttlSeconds` */
   sessionTtlSeconds?: number
-  /** Auto-inject the dev inspector toolbar. On by default; set false to disable. */
+  /** @deprecated use `dev.inspector` */
   inspector?: boolean
 }
 
@@ -60,6 +100,9 @@ export interface DevApp {
     machine: D,
     event: EventOf<D>,
   ): Promise<{ committed: boolean }>
+  /** Break-glass: the current raw Hono app (a getter — the dev server rebuilds
+   *  it on edits, so mount inside the pipeline, not post-hoc). */
+  readonly hono: Hono
   listen: (port: number) => Promise<void>
   close: () => Promise<void>
 }
@@ -92,7 +135,17 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
   const root = resolve(config.root)
   const machinesDir = resolve(config.machinesDir)
   const routesDir = resolve(config.routesDir)
-  const inspectorOn = config.inspector ?? true
+  const resolved = resolveAppConfig(config)
+  // Level precedence: LOG_LEVEL env > config > dev default (info). Apply to this
+  // module's logger AND the Vite-loaded runtime instance — SSE/http/effects log
+  // through the latter — via setLogLevel, which also covers the scoped children.
+  const logLevel = process.env.LOG_LEVEL ?? resolved.logLevel ?? 'info'
+  setLogLevel(logLevel)
+  runtime.setLogLevel(logLevel)
+  // The session cookie is written by the Vite-loaded runtime, so configure that
+  // instance's SameSite (the native one would set a different module's global).
+  runtime.setSessionSameSite(resolved.sameSite ?? 'Lax')
+  const inspectorOn = resolved.inspector ?? true
 
   const resultCache = new Map<string, ReturnType<typeof compile>>()
   const compiledFor = async (file: string) => {
@@ -144,9 +197,9 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
   const rebuildStore = async (): Promise<void> => {
     const { defs } = await runtime.discoverMachines(machinesDir, loader)
     machineCount = defs.length
-    store = new runtime.MachineStore(defs, config.store ?? new runtime.InMemoryStore(), {
-      sessionTtlSeconds: config.sessionTtlSeconds,
-      appStore: config.appStore,
+    store = new runtime.MachineStore(defs, resolved.session ?? new runtime.InMemoryStore(), {
+      sessionTtlSeconds: resolved.sessionTtlSeconds,
+      appStore: resolved.app,
     })
     // Wire the effect scheduler before booting — a fresh app machine's
     // initial-state entry effect fires during boot and needs a live scheduler.
@@ -181,12 +234,20 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
     }
   }
   const rebuildServer = async (): Promise<void> => {
+    // Re-discover `middleware.ts` each rebuild so edits to it take effect. Loaded
+    // through the Vite runtime so its handlers share the runtime's instance.
+    const middleware = await runtime.discoverMiddleware(resolve(root, 'middleware.ts'), loader)
     app = await runtime.buildHonoApp({
       routes,
       store,
       staticDir: config.staticDir,
       headExtras,
       inspector: inspectorOn,
+      trustedOrigins: resolved.trustedOrigins,
+      sameSite: resolved.sameSite,
+      origin: resolved.origin,
+      cors: resolved.cors,
+      middleware,
     })
   }
 
@@ -229,6 +290,9 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
 
   return {
     fetch: (request) => app.fetch(request),
+    get hono() {
+      return app
+    },
     vite,
     // `store` is read at call time, not captured — a machine-edit rebuild
     // swaps it and the method follows.

package/src/server/http.ts

@@ -6,18 +6,19 @@ 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 { crossSiteGuard } from './csrf.ts'
 import { scheduleSessionEffects } from './effects.ts'
 import { record, replayFor } from './event-dedupe.ts'
 import { scopedLogger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
+import type { MiddlewareDefinition } from './middleware.ts'
 import { runQueryRoute } from './query-route.ts'
 import { initialSyncPatches, recompute } from './recompute.ts'
 import { renderRoute } from './render.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
 import { buildRouteRequest } from './route-request.ts'
 import { isStatorQueryRoute, type RouteDefinition } from './routing.ts'
-import { getOrCreateSessionId } from './session.ts'
+import { CLAIMS_KEY, getOrCreateSessionId, getSessionState } from './session.ts'
 import { withSessionLock } from './session-lock.ts'
 import { SessionRuntime } from './session-runtime.ts'
 import { fanOut, registerConnection, unregisterConnection } from './sse.ts'
@@ -37,6 +38,19 @@ export interface HttpConfig {
   inspector?: boolean
   /** SSE heartbeat interval in ms (default 25s). Tests shorten it. */
   ssePingMs?: number
+  /** Origins allowed to make cross-site writes despite the guard (exact or
+   *  wildcard-subdomain). Feeds the default `crossSiteGuard`. */
+  trustedOrigins?: readonly string[]
+  /** Session cookie `SameSite`. `Strict` flips the guard to allowlist-only for
+   *  same-site writes too. */
+  sameSite?: 'Lax' | 'Strict'
+  /** Canonical app origin, exposed to middleware via `stator(c).origin`. */
+  origin?: string
+  /** Resolved CORS read policy, exposed via `stator(c).cors`. */
+  cors?: { origins: readonly string[]; credentials: boolean }
+  /** The app's discovered `middleware.ts` definition (if any). `withDefaults`
+   *  controls whether the framework security stack is prepended. */
+  middleware?: MiddlewareDefinition
 }
 
 const eventSchema = z.object({
@@ -137,7 +151,9 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     const ms = Math.round(performance.now() - start)
     const status = c.res.status
     const isLive = c.req.path === '/__sse'
-    httpLog[status >= 500 ? 'error' : status >= 400 ? 'warn' : 'info'](
+    // Successful requests log at debug (one line per asset is prod noise); 4xx
+    // warns and 5xx errors stay visible at the default level.
+    httpLog[status >= 500 ? 'error' : status >= 400 ? 'warn' : 'debug'](
       {
         method: c.req.method,
         path: c.req.path,
@@ -149,6 +165,53 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     )
   })
 
+  // Context bridge — expose resolved config to every middleware (cors, app
+  // middleware) that follows, off `stator(c)`. Runs first. Also establishes the
+  // session once and eager-loads its claims (for a returning session), so the
+  // whole request shares one sid + claims snapshot; dirty claims persist at the
+  // end, to the current (possibly rotated) sid.
+  app.use('*', async (c, next) => {
+    c.set('stator', {
+      origin: config.origin,
+      trustedOrigins: config.trustedOrigins ?? [],
+      sameSite: config.sameSite ?? 'Lax',
+      cors: config.cors,
+    })
+    // Stash the store so middleware session ops (rotate/clear) can act now.
+    c.set('statorStore', config.store)
+    const { sessionId, isNew } = getOrCreateSessionId(c)
+    const session = getSessionState(c)
+    if (!isNew && session) {
+      session.claims = (await config.store.persistence.get(sessionId, CLAIMS_KEY)) ?? undefined
+    }
+    await next()
+    // Same session object (rotation mutates `.sid` in place), so persist to the
+    // current — possibly rotated — id.
+    if (session?.claimsDirty) {
+      await config.store.persistence.set(session.sid, CLAIMS_KEY, session.claims, {
+        ttlSeconds: config.store.sessionTtlSeconds,
+      })
+    }
+  })
+
+  // Security defaults (unless the app opted out via dangerouslyDefineMiddleware),
+  // then the app's own middleware — all ahead of route matching, so a guard here
+  // can't be missed by a route added later. crossSiteGuard runs before matching,
+  // so a cross-site write to an unknown path 403s (not a route-revealing 404).
+  const mw = config.middleware
+  if (mw?.withDefaults ?? true) {
+    app.use(
+      '*',
+      crossSiteGuard({
+        trustedOrigins: config.trustedOrigins,
+        strict: config.sameSite === 'Strict',
+      }),
+    )
+  }
+  for (const handler of mw?.handlers ?? []) {
+    app.use('*', handler)
+  }
+
   // Compile matchers for every route, in discovery's specificity order. Our own
   // matcher (not Hono's router) is the routing authority: GET/API dispatch and
   // SSE/POST resolution all go through `matchPath`, so rest params (`*name`) and
@@ -289,9 +352,6 @@ 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) {
@@ -339,6 +399,19 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
       return c.json({ error: `unknown machine "${body.machine}"` }, 404)
     }
 
+    // `serverOnly` events are server-generated — effect completions
+    // (`CHARGE_APPROVED`), `after:` timers, cross-machine internals — that no
+    // client legitimately sends. A client POST of one is forgery (e.g. faking a
+    // settled charge), so reject at the wire boundary with 403. The chart still
+    // handles the event when the engine/effects raise it internally: that path
+    // is `runtime.processEvent`, never `/__events`, so it's untouched. Enforced
+    // in dev and prod alike — the declaration is explicit, so there's no
+    // false-positive risk and no dev/prod divergence. Origin legitimacy only,
+    // not per-user authorization — guards still own that.
+    if (originDef.serverOnly.includes(body.event.type)) {
+      return c.json({ error: `event type "${body.event.type}" is server-only` }, 403)
+    }
+
     return withSessionLock(sessionId, async () => {
       // Idempotent replay: a duplicate POST (client retry after a lost
       // response) returns the original response body verbatim instead of
@@ -406,7 +479,6 @@ 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/index.ts

@@ -20,8 +20,13 @@ export type { AppStore } from './app-store.ts'
 export { InMemoryAppStore } from './app-store.ts'
 export type { CachedStoreOptions } from './cached-store.ts'
 export { CachedStore } from './cached-store.ts'
+export type { StatorContext } from './context.ts'
+export { stator } from './context.ts'
+export type { CorsOptions } from './cors.ts'
+export { cors } from './cors.ts'
 export type { CreateAppConfig, StatorApp } from './create-app.ts'
 export { createApp } from './create-app.ts'
+export { crossSiteGuard } from './csrf.ts'
 export type {
   ActionHelpers,
   DefineMachineConfig,
@@ -47,8 +52,15 @@ export type { HttpConfig } from './http.ts'
 export { buildHonoApp } from './http.ts'
 export type { InstanceHandle } from './instance-proxy.ts'
 export { createInstanceProxy, defForProxy } from './instance-proxy.ts'
-export { logger, scopedLogger } from './logger.ts'
+export { logger, scopedLogger, setLogLevel } from './logger.ts'
 export { MachineStore } from './machine-store.ts'
+export type { MiddlewareDefinition } from './middleware.ts'
+export {
+  dangerouslyDefineMiddleware,
+  defineMiddleware,
+  discoverMiddleware,
+  isMiddlewareDefinition,
+} from './middleware.ts'
 export { runQueryRoute } from './query-route.ts'
 export { recompute } from './recompute.ts'
 export { RedisAppStore, RedisStore } from './redis-store.ts'
@@ -106,7 +118,9 @@ export {
   isStatorQueryRoute,
   isStatorRoute,
 } from './routing.ts'
-export { getOrCreateSessionId, SESSION_COOKIE } from './session.ts'
+export type { SecurityHeadersOptions } from './security-headers.ts'
+export { securityHeaders } from './security-headers.ts'
+export { getOrCreateSessionId, SESSION_COOKIE, setSessionSameSite } from './session.ts'
 export { SessionRuntime } from './session-runtime.ts'
 export type { Connection } from './sse.ts'
 export {

package/src/server/logger.ts

@@ -3,8 +3,10 @@ import pino, { type Logger } from 'pino'
 
 /**
  * Framework logger. Pretty colored output in dev (auto-detected via
- * NODE_ENV), JSON in production for log aggregators. Level controlled by
- * LOG_LEVEL env (default 'info').
+ * NODE_ENV), JSON in production for log aggregators. Level defaults to `warn`
+ * in production (quiet — errors and warnings only) and `info` in dev; the
+ * `LOG_LEVEL` env overrides both, and `stator.config.ts`'s `logging.level`
+ * overrides the default when `LOG_LEVEL` is unset (applied at app construction).
  *
  * Application code can use this module-level logger or call `child()` for
  * scoped context. The framework uses scoped children for SSE events,
@@ -23,8 +25,8 @@ function hasPinoPretty(): boolean {
 }
 
 function buildLogger(): Logger {
-  const level = process.env.LOG_LEVEL ?? 'info'
   const isProd = process.env.NODE_ENV === 'production'
+  const level = process.env.LOG_LEVEL ?? (isProd ? 'warn' : 'info')
 
   if (isProd || !hasPinoPretty()) {
     return pino({ level })
@@ -46,7 +48,25 @@ function buildLogger(): Logger {
 
 export const logger: Logger = buildLogger()
 
+// Pino children capture the parent level at CREATION and do not follow later
+// changes to it. The framework's scoped loggers (http, sse, effect, …) are all
+// created at module load, so `logger.level = …` alone would never quiet them.
+// Track them and set the level on each explicitly in `setLogLevel`.
+const scopedChildren: Logger[] = []
+
 /** Child logger with a `scope` tag for filtering. */
 export function scopedLogger(scope: string): Logger {
-  return logger.child({ scope })
+  const child = logger.child({ scope })
+  scopedChildren.push(child)
+  return child
+}
+
+/**
+ * Set the level on the root logger AND every scoped child. Children created
+ * after this call inherit the new root level, so this is complete regardless of
+ * import order. Called once at app construction from the resolved config.
+ */
+export function setLogLevel(level: string): void {
+  logger.level = level
+  for (const child of scopedChildren) child.level = level
 }

package/src/server/machine-store.ts

@@ -6,6 +6,7 @@ import { abortEntryEffects, isEffectInFlight } from './effects.ts'
 import { createInstanceProxy, type InstanceHandle } from './instance-proxy.ts'
 import { scopedLogger } from './logger.ts'
 import { serverReadsResolver } from './reads-helpers.ts'
+import { RESERVED_KEY_PREFIX } from './session.ts'
 import type { Store } from './store.ts'
 import { APP_SCOPE, armAfterTimers, cancelAfterTimers } from './timers.ts'
 
@@ -87,6 +88,12 @@ export class MachineStore {
     this.sessionTtlSeconds = opts?.sessionTtlSeconds ?? 86400
     this.appStore = opts?.appStore ?? new InMemoryAppStore()
     for (const def of defs) {
+      if (def.name.startsWith(RESERVED_KEY_PREFIX)) {
+        throw new Error(
+          `stator: machine name "${def.name}" is reserved — the "${RESERVED_KEY_PREFIX}" ` +
+            `prefix is framework-only (it namespaces per-session storage keys like claims)`,
+        )
+      }
       if (this.defs.has(def.name)) {
         throw new Error(`stator: duplicate machine name "${def.name}"`)
       }

package/src/server/middleware.ts

@@ -0,0 +1,78 @@
+import { existsSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+import type { MiddlewareHandler } from 'hono'
+import type { ModuleLoader } from './discovery.ts'
+
+// A global-registry symbol so the brand survives the dev dual-instance: the app's
+// `middleware.ts` is loaded through Vite while the framework may check it from the
+// native module instance — `Symbol.for` resolves to the same symbol in both.
+const MIDDLEWARE_BRAND = Symbol.for('stator.middleware.definition')
+
+/**
+ * The value an app's `middleware.ts` exports (default) — an ordered list of
+ * Hono middleware plus whether the framework's security defaults are prepended.
+ * Opaque: build it with `defineMiddleware` / `dangerouslyDefineMiddleware`.
+ */
+export interface MiddlewareDefinition {
+  readonly [MIDDLEWARE_BRAND]: true
+  readonly handlers: readonly MiddlewareHandler[]
+  /** Prepend the framework's default security stack (`crossSiteGuard`, …)? */
+  readonly withDefaults: boolean
+}
+
+/** Type guard for a discovered `middleware.ts` default export. */
+export function isMiddlewareDefinition(value: unknown): value is MiddlewareDefinition {
+  return typeof value === 'object' && value !== null && MIDDLEWARE_BRAND in value
+}
+
+/**
+ * Define the app's HTTP middleware. The framework's security defaults
+ * (`crossSiteGuard`, …) run first, then these handlers, then the route — so a
+ * guard added here can't be missed by a route added later. Export the result as
+ * the default from `middleware.ts` at the app root.
+ *
+ * Handlers are plain Hono middleware and run in array order.
+ */
+export function defineMiddleware(handlers: readonly MiddlewareHandler[]): MiddlewareDefinition {
+  return { [MIDDLEWARE_BRAND]: true, handlers, withDefaults: true }
+}
+
+/**
+ * Like `defineMiddleware`, but WITHOUT the framework security defaults — these
+ * handlers are the entire stack. The `dangerously` name is the point: opting out
+ * of the defaults is a visible, greppable decision that says "this app owns its
+ * security." Re-add the exported primitives (`crossSiteGuard()`, …) as needed.
+ *
+ * This only skips the *security* defaults; framework request plumbing (sessions,
+ * dispatch routing, logging, static) is not middleware and is never bypassed.
+ */
+export function dangerouslyDefineMiddleware(
+  handlers: readonly MiddlewareHandler[],
+): MiddlewareDefinition {
+  return { [MIDDLEWARE_BRAND]: true, handlers, withDefaults: false }
+}
+
+const nativeLoader: ModuleLoader = (file) => import(/* @vite-ignore */ pathToFileURL(file).href)
+
+/**
+ * Load an app's `middleware.ts` (if present) and validate its default export.
+ * Returns `undefined` when there is no file — the framework then applies its
+ * security defaults with no user handlers (safe-by-default). `loader` is injected
+ * so dev can go through Vite; prod/native uses `import`. The single toolchain
+ * touch-point, kept swappable for the post-Vite pipeline.
+ */
+export async function discoverMiddleware(
+  file: string,
+  loader: ModuleLoader = nativeLoader,
+): Promise<MiddlewareDefinition | undefined> {
+  if (!existsSync(file)) return undefined
+  const mod = await loader(file)
+  const def = (mod as { default?: unknown }).default
+  if (!isMiddlewareDefinition(def)) {
+    throw new Error(
+      `${file} must \`export default defineMiddleware([...])\` ` +
+        `(or dangerouslyDefineMiddleware([...]))`,
+    )
+  }
+  return def
+}

package/src/server/origin-match.ts

@@ -0,0 +1,63 @@
+/**
+ * Match an incoming `Origin` against an allowlist of patterns — shared by the
+ * cross-site write guard (`trustedOrigins`) and `cors()`. Patterns are origins
+ * with a scheme, either exact (`https://app.example.com`) or wildcard-subdomain
+ * (`https://*.example.com`).
+ *
+ * Boundary-safe by construction: `https://*.example.com` matches `app.example.com`
+ * and `a.b.example.com` (any depth), and NEVER `example.com.evil.com` (suffix
+ * attack), `evilexample.com` (no label boundary), or the apex `example.com` (list
+ * it explicitly if wanted). Scheme must match; port matches when the pattern omits
+ * one, else must be equal. Malformed origins and patterns fail closed (no match).
+ */
+export function matchOrigin(
+  origin: string | undefined | null,
+  patterns: readonly string[],
+): boolean {
+  if (!origin) return false
+  let incoming: URL
+  try {
+    incoming = new URL(origin)
+  } catch {
+    return false
+  }
+  return patterns.some((pattern) => matchOne(incoming, pattern))
+}
+
+/** `scheme://*.rest` — `rest` may carry a `:port`, split off below. */
+const WILDCARD = /^([a-z][a-z0-9+.-]*):\/\/\*\.([^/]+)$/i
+
+function matchOne(incoming: URL, pattern: string): boolean {
+  const wild = WILDCARD.exec(pattern)
+  if (wild) {
+    const rawScheme = wild[1]
+    const rawRest = wild[2]
+    if (rawScheme === undefined || rawRest === undefined) return false
+    const scheme = rawScheme.toLowerCase()
+    let domain = rawRest.toLowerCase()
+    let port = ''
+    const colon = domain.lastIndexOf(':')
+    if (colon !== -1) {
+      port = domain.slice(colon + 1)
+      domain = domain.slice(0, colon)
+    }
+    if (incoming.protocol !== `${scheme}:`) return false
+    if (port && incoming.port !== port) return false
+    const host = incoming.hostname.toLowerCase()
+    // A non-empty subdomain label before `.domain` (any depth), on a label
+    // boundary — the leading dot is what defeats the suffix attack.
+    return host.length > domain.length + 1 && host.endsWith(`.${domain}`)
+  }
+
+  let pat: URL
+  try {
+    pat = new URL(pattern)
+  } catch {
+    return false
+  }
+  if (incoming.protocol !== pat.protocol) return false
+  if (incoming.hostname.toLowerCase() !== pat.hostname.toLowerCase()) return false
+  // A pattern with no explicit port matches any port; with one, it must be equal.
+  if (pat.port && incoming.port !== pat.port) return false
+  return true
+}

package/src/server/routing.ts

@@ -1,5 +1,6 @@
 import type { HtmlFragment } from '../template/types.ts'
 import type { WireEnvelope } from '../wire/index.ts'
+import type { CookieJar } from './cookies.ts'
 import type { AnyMachineDef, EventOf, ReadsMap } from './define-machine.ts'
 
 /** Machine context passed to a route's render function. Keyed by machine name. */
@@ -148,6 +149,19 @@ export interface ApiRouteHelpers {
    *  the response carries the new cookie. Requires a store with
    *  `renameSession` (all built-in stores have it). */
   rotateSession: (opts?: { clear?: boolean }) => void
+  /** Read this session's app-defined claims (identity/data). `undefined` if none. */
+  claims: <T = unknown>() => T | undefined
+  /** Replace this session's claims — persisted at request end. */
+  setClaims: (claims: unknown) => void
+  /** Drop this session's claims (keeps the session) — persisted at request end. */
+  clearClaims: () => void
+  /** Destroy this session — its state is deleted and the browser starts
+   *  anonymous. Sugar for `rotateSession({ clear: true })`; applied after the
+   *  handler returns. */
+  clearSession: () => void
+  /** Read/write app-owned cookies (e.g. a login `returnTo`). Distinct from the
+   *  framework-managed session cookie; writes take effect on this response. */
+  readonly cookies: CookieJar
 }
 
 export interface ApiRouteDefinition {

package/src/server/security-headers.ts

@@ -0,0 +1,32 @@
+import type { MiddlewareHandler } from 'hono'
+
+export interface SecurityHeadersOptions {
+  /** `X-Frame-Options`. Default `SAMEORIGIN`; `false` to omit. */
+  frameOptions?: 'DENY' | 'SAMEORIGIN' | false
+  /** `Referrer-Policy`. Default `strict-origin-when-cross-origin`; `false` to omit. */
+  referrerPolicy?: string | false
+  /** `Strict-Transport-Security` max-age in seconds (HSTS). Off by default —
+   *  only meaningful over HTTPS, and easy to lock yourself out with. */
+  hsts?: number | false
+  /** `Content-Security-Policy`. Off by default — CSP varies per app. */
+  contentSecurityPolicy?: string | false
+}
+
+/**
+ * Baseline security response headers — opt-in (not a default), matching SvelteKit
+ * and Stator's current stance of leaving HTTP hardening to the app/platform.
+ * `X-Content-Type-Options: nosniff` is always set; frame + referrer are on with
+ * safe defaults; HSTS and CSP are opt-in.
+ */
+export function securityHeaders(opts: SecurityHeadersOptions = {}): MiddlewareHandler {
+  const frame = opts.frameOptions ?? 'SAMEORIGIN'
+  const referrer = opts.referrerPolicy ?? 'strict-origin-when-cross-origin'
+  return async (c, next) => {
+    c.header('X-Content-Type-Options', 'nosniff')
+    if (frame) c.header('X-Frame-Options', frame)
+    if (referrer) c.header('Referrer-Policy', referrer)
+    if (opts.hsts) c.header('Strict-Transport-Security', `max-age=${opts.hsts}; includeSubDomains`)
+    if (opts.contentSecurityPolicy) c.header('Content-Security-Policy', opts.contentSecurityPolicy)
+    await next()
+  }
+}