@statorjs/stator 2.2.0 → 2.4.0

package/src/server/csrf.ts

@@ -1,4 +1,5 @@
-import type { Context } from 'hono'
+import type { Context, MiddlewareHandler } from 'hono'
+import { matchOrigin } from './origin-match.ts'
 
 /**
  * CSRF signal check for state-changing requests. The session cookie
@@ -11,21 +12,64 @@ import type { Context } from 'hono'
  * 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.
+ * `trustedOrigins` is an allowlist (exact or wildcard-subdomain — see
+ * `matchOrigin`) of origins permitted despite being cross-site, for a decoupled
+ * frontend or partner domain that legitimately writes. `same-site` (sibling
+ * subdomain) is allowed by default; under `strict` (the `SameSite=Strict`
+ * posture) a same-site write must match `trustedOrigins`, exactly like a
+ * cross-site one — the allowlist becomes the whole gate.
  */
-export function isBlockedCrossSite(c: Context): boolean {
-  const site = c.req.header('sec-fetch-site')
-  if (site) return site === 'cross-site'
+export function isBlockedCrossSite(
+  c: Context,
+  trustedOrigins: readonly string[] = [],
+  strict = false,
+): boolean {
   const origin = c.req.header('origin')
+  const site = c.req.header('sec-fetch-site')
+
+  if (site) {
+    if (site === 'same-origin' || site === 'none') return false
+    // same-site is allowed by default; under strict it must be allowlisted.
+    if (site === 'same-site') return strict ? !matchOrigin(origin, trustedOrigins) : false
+    // cross-site: allowed only if allowlisted.
+    return !matchOrigin(origin, trustedOrigins)
+  }
+
+  // No Sec-Fetch-Site (older browsers): fall back to an Origin host comparison.
   if (origin) {
+    let sameHost: boolean
     try {
-      return new URL(origin).host !== new URL(c.req.url).host
+      sameHost = new URL(origin).host === new URL(c.req.url).host
     } catch {
       return true
     }
+    if (sameHost) return false
+    return !matchOrigin(origin, trustedOrigins)
   }
+
+  // No browser signal at all — server-to-server / webhook / test harness.
   return false
 }
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+/**
+ * The framework's default cross-site write guard, as composable middleware. It
+ * rejects state-changing (non-safe-method) requests that `isBlockedCrossSite`
+ * flags — before route matching, so a cross-site write to an unknown path 403s
+ * rather than revealing its existence with a 404. Reads its `trustedOrigins`
+ * allowlist from options; exported so an app on `dangerouslyDefineMiddleware`
+ * can re-add it.
+ */
+export function crossSiteGuard(
+  opts: { trustedOrigins?: readonly string[]; strict?: boolean } = {},
+): MiddlewareHandler {
+  const trusted = opts.trustedOrigins ?? []
+  const strict = opts.strict ?? false
+  return async (c, next) => {
+    if (!SAFE_METHODS.has(c.req.method) && isBlockedCrossSite(c, trusted, strict)) {
+      return c.json({ error: 'cross-site request blocked' }, 403)
+    }
+    await next()
+  }
+}

package/src/server/dev.ts

@@ -12,6 +12,7 @@ import { machineStub, stator } from '../vite/index.ts'
 import type { AppStore } from './app-store.ts'
 import { findFreePort, installGracefulShutdown, printDevBanner } from './banner.ts'
 import { resolveAppConfig } from './config-compat.ts'
+import { loadDotenv } from './env.ts'
 import { logger, setLogLevel } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
@@ -54,6 +55,9 @@ export interface DevAppConfig {
   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?: {
@@ -65,6 +69,16 @@ export interface DevAppConfig {
     /** 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
+  /** Signed-cookie signing key. Falls back to `STATOR_SECRET`. Mirrors
+   *  `StatorConfig.secret`. */
+  secret?: 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` */
@@ -90,11 +104,17 @@ 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>
 }
 
 export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
+  // Load .env before anything reads process.env. No-op if the CLI already
+  // loaded it; covers a direct `createDevApp` call (a hand-written dev entry).
+  loadDotenv(resolve(config.root))
   // Vite's HMR websocket defaults to 24678 for EVERY dev server — two
   // stator apps side by side would fight over it (the loser's live reload
   // silently dies). Probe a free one instead.
@@ -129,6 +149,9 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
   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>>()
@@ -218,12 +241,21 @@ 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,
+      secret: resolved.secret,
+      cors: resolved.cors,
+      middleware,
     })
   }
 
@@ -266,6 +298,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/env.ts

@@ -0,0 +1,27 @@
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+/**
+ * Load `.env` files into `process.env` — the home for server config/secrets
+ * that's uniform across dev and prod (unlike Vite's transform-time
+ * `import.meta.env`, absent in prod). Precedence, highest first:
+ *
+ *   real shell env  >  .env.local  >  .env
+ *
+ * `process.loadEnvFile` (native, Node ≥20.12 — no dependency) never overrides
+ * an already-set key, so real env always wins, and `.env.local` is loaded
+ * *before* `.env`: the earlier load claims a key the later one can't reclaim.
+ * Absent files are skipped. Idempotent-safe — a second call adds nothing new,
+ * so the CLI (which loads before importing `stator.config.ts`) and
+ * `createApp`/`createDevApp` (which load for the direct `server.ts` path) can
+ * both call it without conflict.
+ *
+ * `.env.local` is for machine-local secrets and belongs in `.gitignore`; `.env`
+ * holds committed defaults.
+ */
+export function loadDotenv(root: string = process.cwd()): void {
+  for (const name of ['.env.local', '.env']) {
+    const path = resolve(root, name)
+    if (existsSync(path)) process.loadEnvFile(path)
+  }
+}

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,22 @@ 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
+  /** Signed-cookie signing key (`config.secret` ?? `STATOR_SECRET`). Stashed on
+   *  the request context so `cookies.setSigned`/`getSigned` can reach it. */
+  secret?: 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({
@@ -151,6 +168,55 @@ 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)
+    // Stash the signing key so the cookie jar's signed methods can reach it.
+    if (config.secret !== undefined) c.set('statorSecret', config.secret)
+    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
@@ -291,9 +357,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) {
@@ -341,6 +404,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
@@ -408,7 +484,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,
@@ -49,6 +54,13 @@ export type { InstanceHandle } from './instance-proxy.ts'
 export { createInstanceProxy, defForProxy } from './instance-proxy.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/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()
+  }
+}