@statorjs/stator 2.2.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "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",
@@ -95,7 +95,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "2.2.0"
+    "@statorjs/stator": "2.4.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/build/build.ts

@@ -82,6 +82,11 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
     if (await exists(src)) await cp(src, join(outDir, d), { recursive: true })
   }
 
+  // A root-level middleware.ts is a single file, not a source dir — copy it too
+  // (raw TS, run under tsx/native in prod like the rest of the server).
+  const middlewareSrc = join(root, 'middleware.ts')
+  if (await exists(middlewareSrc)) await cp(middlewareSrc, join(outDir, 'middleware.ts'))
+
   // Compile every .stator into a sibling .stator.ts; collect CSS and islands.
   const statorFiles = await walk(outDir, (f) => f.endsWith('.stator'))
   let css = ''

package/src/cli/commands/dev.ts

@@ -16,6 +16,9 @@ export async function run(ctx: CliContext): Promise<void> {
     persistence: config.persistence,
     sessions: config.sessions,
     dev: config.dev,
+    trustedOrigins: config.trustedOrigins,
+    origin: config.origin,
+    cors: config.cors,
   })
   await app.listen(resolvePort(ctx.portFlag, config.port))
 }

package/src/cli/commands/start.ts

@@ -23,7 +23,12 @@ export async function run(ctx: CliContext): Promise<void> {
     persistence: config.persistence,
     sessions: config.sessions,
     realtime: config.realtime,
+    trustedOrigins: config.trustedOrigins,
+    origin: config.origin,
+    host: config.host,
+    cors: config.cors,
     headExtras: await loadProductionHead(dist),
+    middlewareFile: resolve(dist, 'middleware.ts'),
   })
 
   await app.listen(resolvePort(ctx.portFlag, config.port))

package/src/cli/run.ts

@@ -59,6 +59,12 @@ const ctx: CliContext = {
   rest: positionals.slice(1),
 }
 
+// Load .env before importing the command — so `stator.config.ts` (imported by
+// loadConfig inside the command) can read `process.env.*`. createApp/createDevApp
+// load it again for the direct-`server.ts` path; idempotent.
+const { loadDotenv } = await import('../server/env.ts')
+loadDotenv(ctx.root)
+
 // Dynamic import per command so `check` never loads the dev server's Vite, etc.
 const { run } = (await import(`./commands/${command}.ts`)) as {
   run: (ctx: CliContext) => Promise<void>

package/src/config.ts

@@ -23,6 +23,19 @@ export type LogLevel = 'silent' | 'fatal' | 'error' | 'warn' | 'info' | 'debug'
 export interface StatorConfig {
   /** Listen port for `dev`/`start`. Precedence: `--port` flag > `$PORT` > this > 3000. */
   port?: number
+  /** Listen host / bind address. Default: all interfaces. Containers behind a
+   *  proxy typically need `0.0.0.0`. */
+  host?: string
+  /** Canonical app URL (`https://example.com`) — for absolute-URL generation
+   *  (redirects, SSE reconnect, OG tags) and as a spoof-proof same-origin
+   *  anchor. Exposed to middleware via `stator(c).origin`. */
+  origin?: string
+  /** Signing secret for signed cookies (`cookies.setSigned`/`getSigned`) — the
+   *  sealed short-lived-state primitive (OAuth `state`/PKCE, a magic-link token,
+   *  a WebAuthn challenge). Falls back to `process.env.STATOR_SECRET`. Use a long
+   *  random string (≥32 chars); keep it out of source — set it in `.env.local` or
+   *  a platform secret. Absent → the signed-cookie methods throw. */
+  secret?: string
   /** The swappable persistence adapters, grouped by concern. Both optional —
    *  default to in-memory (restart-wipe). Neither is a machine-graph entry
    *  point (machines are file-discovered). */
@@ -39,6 +52,13 @@ export interface StatorConfig {
   sessions?: {
     /** Per-session idle TTL in seconds. Default: 86400 (24h). */
     ttlSeconds?: number
+    /** Session cookie policy. */
+    cookie?: {
+      /** `SameSite` attribute. Default `Lax` (allows same-site subdomains).
+       *  `Strict` withholds the cookie from every cross-site request and flips
+       *  the CSRF guard to allowlist-only — the controlled posture. */
+      sameSite?: 'Lax' | 'Strict'
+    }
     // cookieName?, rotation? — reserved policy siblings (not wired yet).
   }
   /** Realtime / push policy. Protocol-neutral so a future WS transport doesn't
@@ -53,6 +73,16 @@ export interface StatorConfig {
     /** Dev inspector toolbar (`dev` only). Default: on. */
     inspector?: boolean
   }
+  /** Origins allowed to make cross-site writes despite the CSRF guard — exact
+   *  (`https://app.example.com`) or wildcard-subdomain (`https://*.example.com`).
+   *  Same-origin and same-site writes are already allowed; this is for decoupled
+   *  frontends or partner domains. */
+  trustedOrigins?: string[]
+  /** Cross-origin READ policy (CORS) — governs which cross-origin sites may read
+   *  responses (distinct from `trustedOrigins`, which governs cross-site writes).
+   *  Opt in per route/app with the `cors()` middleware; `origins` defaults to
+   *  `trustedOrigins`. */
+  cors?: { origins?: string[]; credentials?: boolean }
   /** Logging policy. */
   logging?: {
     /** Minimum level to emit. Default: `warn` in production, `info` in dev.

package/src/engine/define-machine.ts

@@ -30,6 +30,13 @@ export interface DefineMachineConfig<
   /** Typed event surface. Pass `{} as MyEvents` — a phantom carrier the engine
    *  reads only for its type. Actions/guards then narrow per transition. */
   events?: E
+  /** Event types NO client may dispatch to `/__events` — effect completions
+   *  (`CHARGE_APPROVED`), timer/`after:` events, cross-machine internals: events
+   *  only the server/engine generates. A production `stator start` rejects a
+   *  client POST of one with 403 (dev does not enforce). Typed against the event
+   *  union, so a name that isn't a real event is a compile error. The chart still
+   *  handles them normally when the engine/effects raise them. */
+  serverOnly?: readonly E['type'][]
   emits?: EmitsConfig<C, E>
   context: C
   initial: NoInfer<S>
@@ -116,6 +123,7 @@ export function defineMachine<
     persist: config.persist ?? false,
     reads,
     subscribes: config.subscribes ?? [],
+    serverOnly: config.serverOnly ?? [],
     emits: normalizeEmits<C, E>(config.emits),
     selectors: (config.selectors ?? {}) as Sel,
     capabilities: computeCapabilities(reads),

package/src/engine/types.ts

@@ -243,6 +243,10 @@ export interface MachineDef<
   persist: boolean
   reads: AnyMachineDef[]
   subscribes: SubscribeEntry[]
+  /** Event types no client may dispatch to `/__events` (server-generated only:
+   *  effect completions, timers, cross-machine internals). Normalized to `[]`.
+   *  Enforced with a 403 in production; the chart handles them normally. */
+  serverOnly: readonly string[]
   /** Normalized: every declared emit, possibly with a payload selector. */
   emits: Record<string, EmitDeclaration<C, E>>
   selectors: Sel

package/src/server/api-route.ts

@@ -1,7 +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 { cookieJar } from './cookies.ts'
 import { scheduleSessionEffects } from './effects.ts'
 import { scopedLogger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
@@ -15,7 +15,7 @@ import type {
   Directive,
   RouteRequest,
 } from './routing.ts'
-import { getOrCreateSessionId, setSessionCookie } from './session.ts'
+import { getOrCreateSessionId, getSessionState, rotateSessionNow } from './session.ts'
 import { withSessionLock } from './session-lock.ts'
 import { SessionRuntime } from './session-runtime.ts'
 import { fanOut } from './sse.ts'
@@ -73,6 +73,25 @@ export async function runApiRoute(
         rotateSession: (opts) => {
           rotation = { clear: opts?.clear === true }
         },
+        clearSession: () => {
+          rotation = { clear: true }
+        },
+        claims: <T = unknown>() => getSessionState(c)?.claims as T | undefined,
+        setClaims: (claims) => {
+          const s = getSessionState(c)
+          if (s) {
+            s.claims = claims
+            s.claimsDirty = true
+          }
+        },
+        clearClaims: () => {
+          const s = getSessionState(c)
+          if (s) {
+            s.claims = undefined
+            s.claimsDirty = true
+          }
+        },
+        cookies: cookieJar(c),
       }
 
       let result: Response | ApiRouteEnvelope
@@ -101,20 +120,11 @@ export async function runApiRoute(
       // new cookie. Effect completions must chase the NEW id.
       let effectsSessionId = sessionId
       if (rotation !== null) {
-        const newSessionId = randomUUID()
-        if ((rotation as { clear: boolean }).clear) {
-          await store.persistence.deleteSession(sessionId)
-        } else {
-          if (!store.persistence.renameSession) {
-            throw new Error(
-              'stator: rotateSession requires a store with renameSession — ' +
-                'the configured custom store does not implement it.',
-            )
-          }
-          await store.persistence.renameSession(sessionId, newSessionId)
-        }
-        setSessionCookie(c, newSessionId)
-        effectsSessionId = newSessionId
+        // Apply the deferred rotation now the handler has returned. The helper
+        // moves (or, on clear, deletes) the session, sets the new cookie, and
+        // updates the shared session state so the bridge persists claims to the
+        // new id. Effect completions must chase the NEW id.
+        effectsSessionId = await rotateSessionNow(c, store, rotation)
       }
       // Effects queued by dispatched events run after this callback returns
       // (never under the session lock); see server/effects.ts.
@@ -201,8 +211,10 @@ function synthesizeResponse(
       // 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 })
+    // No actionable directive for a no-JS client. Send a minimal 204 — via
+    // c.body so any cookies set this request (session rotation, the cookie jar)
+    // survive; a bare `new Response` would drop c's accumulated Set-Cookie.
+    return c.body(null, 204)
   }
 
   // JSON / client-runtime path.

package/src/server/config-compat.ts

@@ -25,10 +25,15 @@ export interface DeprecatedFlatConfig {
 
 interface NestedReads {
   persistence?: { session?: Store; app?: AppStore }
-  sessions?: { ttlSeconds?: number }
+  sessions?: { ttlSeconds?: number; cookie?: { sameSite?: 'Lax' | 'Strict' } }
   realtime?: { pingMs?: number }
   dev?: { inspector?: boolean }
   logging?: { level?: LogLevel }
+  trustedOrigins?: readonly string[]
+  origin?: string
+  host?: string
+  secret?: string
+  cors?: { origins?: readonly string[]; credentials?: boolean }
 }
 
 /** The flat internal values `createApp`/`createDevApp` actually consume. */
@@ -39,6 +44,13 @@ export interface ResolvedAppConfig {
   ssePingMs?: number
   inspector?: boolean
   logLevel?: LogLevel
+  trustedOrigins?: readonly string[]
+  sameSite?: 'Lax' | 'Strict'
+  origin?: string
+  host?: string
+  /** Signed-cookie signing key. `config.secret` ?? `STATOR_SECRET`. */
+  secret?: string
+  cors?: { origins: readonly string[]; credentials: boolean }
 }
 
 /**
@@ -69,5 +81,17 @@ export function resolveAppConfig(config: NestedReads & DeprecatedFlatConfig): Re
     ssePingMs: config.realtime?.pingMs ?? config.ssePingMs,
     inspector: config.dev?.inspector ?? config.inspector,
     logLevel: config.logging?.level,
+    trustedOrigins: config.trustedOrigins,
+    sameSite: config.sessions?.cookie?.sameSite,
+    origin: config.origin,
+    host: config.host,
+    // The signing key: explicit config wins, else the env (loadable via .env).
+    secret: config.secret ?? process.env.STATOR_SECRET,
+    cors: config.cors
+      ? {
+          origins: config.cors.origins ?? config.trustedOrigins ?? [],
+          credentials: config.cors.credentials ?? false,
+        }
+      : undefined,
   }
 }

package/src/server/context.ts

@@ -0,0 +1,103 @@
+import type { Context } from 'hono'
+import { type CookieJar, cookieJar } from './cookies.ts'
+import { getSessionState, rotateSessionNow } from './session.ts'
+import type { Store } from './store.ts'
+
+/**
+ * The resolved config data `buildHonoApp` stashes on the context (early), for
+ * the security defaults, `cors()`, and app middleware to read.
+ */
+interface StatorConfigData {
+  readonly origin?: string
+  readonly trustedOrigins: readonly string[]
+  readonly sameSite: 'Lax' | 'Strict'
+  readonly cors?: { readonly origins: readonly string[]; readonly credentials: boolean }
+}
+
+// Type `c.get('stator')` / `c.set('stator', …)` — the stored config data, plus
+// the store the bridge stashes so middleware session ops can rotate/clear now.
+declare module 'hono' {
+  interface ContextVariableMap {
+    stator: StatorConfigData
+    statorStore: { persistence: Store }
+    /** Signed-cookie signing key, stashed by the bridge when configured. */
+    statorSecret: string
+  }
+}
+
+/**
+ * What `stator(c)` returns — resolved config *plus* per-request session ops.
+ * Read it in middleware; handlers get the same ops on their `ctx`.
+ */
+export interface StatorContext {
+  readonly origin?: string
+  readonly trustedOrigins: readonly string[]
+  readonly sameSite: 'Lax' | 'Strict'
+  readonly cors?: { readonly origins: readonly string[]; readonly credentials: boolean }
+
+  /** The established session id for this request. */
+  readonly sid: string
+  /** 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
+  /** Rotate the session id *now* (fixation defense on privilege change): state
+   *  moves to a fresh id, the response carries the new cookie. Immediate because
+   *  middleware runs upstream of the handler pipeline. */
+  rotateSession(opts?: { clear?: boolean }): Promise<void>
+  /** Destroy this session *now* — its state is deleted and the browser starts
+   *  anonymous. Sugar for `rotateSession({ clear: true })`. */
+  clearSession(): Promise<void>
+  /** Read/write app-owned cookies (e.g. a login `returnTo`). Distinct from the
+   *  framework-managed session cookie. */
+  readonly cookies: CookieJar
+}
+
+const DEFAULT: StatorConfigData = { trustedOrigins: [], sameSite: 'Lax' }
+
+/**
+ * Read Stator's request context — resolved config + session ops. Safe outside the
+ * framework pipeline (inert config defaults, empty session) if the bridge/session
+ * setup never ran.
+ */
+export function stator(c: Context): StatorContext {
+  const cfg = c.get('stator') ?? DEFAULT
+  const session = getSessionState(c)
+  return {
+    origin: cfg.origin,
+    trustedOrigins: cfg.trustedOrigins,
+    sameSite: cfg.sameSite,
+    cors: cfg.cors,
+    get sid() {
+      return session?.sid ?? ''
+    },
+    claims<T = unknown>(): T | undefined {
+      return session?.claims as T | undefined
+    },
+    setClaims(claims: unknown): void {
+      if (session) {
+        session.claims = claims
+        session.claimsDirty = true
+      }
+    },
+    clearClaims(): void {
+      if (session) {
+        session.claims = undefined
+        session.claimsDirty = true
+      }
+    },
+    async rotateSession(opts?: { clear?: boolean }): Promise<void> {
+      const store = c.get('statorStore')
+      if (!store) return // inert outside the framework pipeline
+      await rotateSessionNow(c, store, opts)
+    },
+    async clearSession(): Promise<void> {
+      const store = c.get('statorStore')
+      if (!store) return
+      await rotateSessionNow(c, store, { clear: true })
+    },
+    cookies: cookieJar(c),
+  }
+}

package/src/server/cookies.ts

@@ -0,0 +1,69 @@
+import type { Context } from 'hono'
+import { deleteCookie, getCookie, getSignedCookie, setCookie, setSignedCookie } from 'hono/cookie'
+import type { RouteCookieOptions } from './routing.ts'
+
+/**
+ * A focused read/write cookie surface for app-owned cookies (a login
+ * `returnTo`, a consent flag, a theme). Thin over `hono/cookie` — no jar state,
+ * writes append `Set-Cookie` on the response immediately.
+ *
+ * `get` reads the *inbound* request cookie: a `set` this request is not visible
+ * to a later `get` in the same request (standard cookie semantics). The session
+ * cookie (`stator_sid`) is framework-managed — use the session ops, not this.
+ */
+export interface CookieJar {
+  /** The inbound value of `name`, or `undefined` if absent. */
+  get(name: string): string | undefined
+  /** Write a cookie on the response. Defaults are hono's (not HttpOnly/Secure);
+   *  pass options for auth-shaped cookies. */
+  set(name: string, value: string, options?: RouteCookieOptions): void
+  /** Expire a cookie. `path`/`domain` must match how it was set. Works for
+   *  signed cookies too — deletion needs no signature. */
+  delete(name: string, options?: Pick<RouteCookieOptions, 'path' | 'domain'>): void
+  /** Read a signed cookie, verifying its signature against the app secret.
+   *  `undefined` if absent OR the signature is invalid (tampered, or signed
+   *  with a since-rotated secret) — an untrustworthy value is treated as absent.
+   *  Throws if no secret is configured. The sealed short-lived-state read
+   *  (OAuth `state`/PKCE, a magic-link token, a WebAuthn challenge). */
+  getSigned(name: string): Promise<string | undefined>
+  /** Write a signed cookie — the value is tamper-evident, not encrypted (still
+   *  readable by the client, so don't put secrets *in* it; put a nonce it can't
+   *  forge). Throws if no secret is configured. */
+  setSigned(name: string, value: string, options?: RouteCookieOptions): Promise<void>
+}
+
+/** Read the configured signing secret, or throw a fix-it error. */
+function requireSecret(c: Context): string {
+  const secret = c.get('statorSecret')
+  if (!secret) {
+    throw new Error(
+      'stator: signed cookies require a secret — set `secret` in stator.config.ts ' +
+        'or `STATOR_SECRET` in the environment (e.g. .env.local).',
+    )
+  }
+  return secret
+}
+
+/** Build the cookie jar bound to a request context. Shared by `stator(c)`
+ *  (middleware) and the API-route handler `ctx`, so both read/write cookies
+ *  the same way. */
+export function cookieJar(c: Context): CookieJar {
+  return {
+    get: (name) => getCookie(c, name),
+    set: (name, value, options) => {
+      setCookie(c, name, value, options as never)
+    },
+    delete: (name, options) => {
+      deleteCookie(c, name, options as never)
+    },
+    getSigned: async (name) => {
+      // hono returns `false` for a present-but-invalid signature; collapse it to
+      // undefined so callers never trust (or even see) a tampered value.
+      const value = await getSignedCookie(c, requireSecret(c), name)
+      return value === false ? undefined : value
+    },
+    setSigned: async (name, value, options) => {
+      await setSignedCookie(c, name, value, requireSecret(c), options as never)
+    },
+  }
+}

package/src/server/cors.ts

@@ -0,0 +1,48 @@
+import type { MiddlewareHandler } from 'hono'
+import { stator } from './context.ts'
+import { matchOrigin } from './origin-match.ts'
+
+export interface CorsOptions {
+  /** Allowed origins (exact or wildcard-subdomain). Defaults to the app's
+   *  `cors.origins`, which itself defaults to `trustedOrigins`. */
+  origins?: readonly string[]
+  /** Send `Access-Control-Allow-Credentials: true` (needed to read a response
+   *  with cookies). Defaults to the app's `cors.credentials`. */
+  credentials?: boolean
+  /** Methods advertised on preflight. Default: GET/POST/PUT/PATCH/DELETE/OPTIONS. */
+  methods?: readonly string[]
+  /** Request headers advertised on preflight. Default: reflects the request's. */
+  headers?: readonly string[]
+}
+
+const DEFAULT_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'] as const
+
+/**
+ * CORS middleware — governs which cross-origin sites may READ responses (distinct
+ * from `crossSiteGuard`, which governs cross-site WRITES). Opt-in, not a default.
+ * Reflects the request `Origin` when it matches the allowlist — never `*`, so
+ * credentialed (cookie-bearing) reads work — and answers preflight with 204.
+ * Wildcards go through the shared boundary-safe matcher.
+ */
+export function cors(opts: CorsOptions = {}): MiddlewareHandler {
+  return async (c, next) => {
+    const ctx = stator(c)
+    const origins = opts.origins ?? ctx.cors?.origins ?? ctx.trustedOrigins
+    const credentials = opts.credentials ?? ctx.cors?.credentials ?? false
+    const reqOrigin = c.req.header('origin')
+
+    if (reqOrigin && matchOrigin(reqOrigin, origins)) {
+      c.header('Access-Control-Allow-Origin', reqOrigin)
+      c.header('Vary', 'Origin')
+      if (credentials) c.header('Access-Control-Allow-Credentials', 'true')
+    }
+
+    if (c.req.method === 'OPTIONS') {
+      c.header('Access-Control-Allow-Methods', (opts.methods ?? DEFAULT_METHODS).join(', '))
+      const reqHeaders = opts.headers?.join(', ') ?? c.req.header('access-control-request-headers')
+      if (reqHeaders) c.header('Access-Control-Allow-Headers', reqHeaders)
+      return c.body(null, 204)
+    }
+    await next()
+  }
+}

package/src/server/create-app.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path'
 import { serve } from '@hono/node-server'
+import type { Hono } from 'hono'
 import type { LogLevel } from '../config.ts'
 import type { AnyMachineDef, EventOf } from '../engine/index.ts'
 import { dispatchToApp } from './app-dispatch.ts'
@@ -8,10 +9,13 @@ import { installGracefulShutdown, printStartupNotice } from './banner.ts'
 import { type DeprecatedFlatConfig, resolveAppConfig } from './config-compat.ts'
 import { discoverMachines } from './discovery.ts'
 import { wireAppEffects } from './effects.ts'
+import { loadDotenv } from './env.ts'
 import { buildHonoApp } from './http.ts'
 import { logger, setLogLevel } from './logger.ts'
 import { MachineStore } from './machine-store.ts'
+import { discoverMiddleware } from './middleware.ts'
 import { discoverRoutes } from './route-discovery.ts'
+import { setSessionSameSite } from './session.ts'
 import { InMemoryStore, type Store } from './store.ts'
 
 export interface CreateAppConfig extends DeprecatedFlatConfig {
@@ -34,6 +38,9 @@ export interface CreateAppConfig extends DeprecatedFlatConfig {
     /** Per-session TTL in seconds. Every set to any of the session's machines
      *  refreshes this expiry. Defaults to 24h (86400). */
     ttlSeconds?: number
+    /** Session cookie policy. `cookie.sameSite: 'Strict'` opts into the
+     *  controlled CSRF posture. */
+    cookie?: { sameSite?: 'Lax' | 'Strict' }
   }
   /** Realtime / push policy. */
   realtime?: {
@@ -52,9 +59,24 @@ export interface CreateAppConfig extends DeprecatedFlatConfig {
      *  `LOG_LEVEL` env takes precedence over this. */
     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
+  /** Listen host / bind address (used by `listen`). Default: all interfaces. */
+  host?: string
+  /** Cross-origin READ policy (CORS); `origins` defaults to `trustedOrigins`. */
+  cors?: { origins?: string[]; credentials?: boolean }
   /** Extra `<head>` HTML per GET route. A production build uses this to link the
    *  prebuilt `components.css`; ignored if omitted. */
   headExtras?: (filePath: string) => string | Promise<string>
+  /** Path to the app's `middleware.ts` (if any). Loaded and validated; its
+   *  default export must be `defineMiddleware`/`dangerouslyDefineMiddleware`. */
+  middlewareFile?: string
 }
 
 export interface StatorApp {
@@ -71,9 +93,16 @@ export interface StatorApp {
     machine: D,
     event: EventOf<D>,
   ): Promise<{ committed: boolean }>
+  /** Break-glass: the raw Hono app. The unsupported paved-road exit — for
+   *  sub-app mounts / protocol upgrades the framework surface doesn't cover.
+   *  Mutate before `listen`. */
+  hono: Hono
 }
 
 export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
+  // Load .env before anything reads process.env (LOG_LEVEL below, app secrets).
+  // No-op if the CLI already loaded it; covers the direct `server.ts` entry.
+  loadDotenv()
   const machinesDir = resolve(config.machinesDir)
   const routesDir = resolve(config.routesDir)
   const staticDir = config.staticDir ? resolve(config.staticDir) : undefined
@@ -83,6 +112,7 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
   // is the production entry point, so it defaults quiet). setLogLevel also covers
   // the scoped children (http/sse/…), which a bare `logger.level =` would miss.
   setLogLevel(process.env.LOG_LEVEL ?? resolved.logLevel ?? 'warn')
+  setSessionSameSite(resolved.sameSite ?? 'Lax')
   const { defs } = await discoverMachines(machinesDir)
   const sessionStore = resolved.session ?? new InMemoryStore()
   const store = new MachineStore(defs, sessionStore, {
@@ -95,6 +125,9 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
   await store.bootAppMachines()
 
   const routes = await discoverRoutes(routesDir)
+  const middleware = config.middlewareFile
+    ? await discoverMiddleware(config.middlewareFile)
+    : undefined
   const inspector = resolved.inspector
   const app = await buildHonoApp({
     routes,
@@ -108,12 +141,18 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
       : config.headExtras,
     inspector,
     ssePingMs: resolved.ssePingMs,
+    trustedOrigins: resolved.trustedOrigins,
+    sameSite: resolved.sameSite,
+    origin: resolved.origin,
+    secret: resolved.secret,
+    cors: resolved.cors,
+    middleware,
   })
 
   return {
     listen(port: number): Promise<void> {
       return new Promise((resolveFn) => {
-        const server = serve({ fetch: app.fetch, port }, () => {
+        const server = serve({ fetch: app.fetch, port, hostname: resolved.host }, () => {
           // Always-on (level-independent) so `warn` prod still confirms boot.
           printStartupNotice({ port, machines: defs.length, routes: routes.length })
           resolveFn()
@@ -138,5 +177,6 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
     fetch: (request: Request) => app.fetch(request),
     store,
     dispatchToApp: (machine, event) => dispatchToApp(store, machine, event),
+    hono: app,
   }
 }