@statorjs/stator 2.2.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.2.0",
+  "version": "2.3.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.3.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/config.ts

@@ -23,6 +23,13 @@ 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
   /** 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 +46,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 +67,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,14 @@ 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
+  cors?: { origins?: readonly string[]; credentials?: boolean }
 }
 
 /** The flat internal values `createApp`/`createDevApp` actually consume. */
@@ -39,6 +43,11 @@ export interface ResolvedAppConfig {
   ssePingMs?: number
   inspector?: boolean
   logLevel?: LogLevel
+  trustedOrigins?: readonly string[]
+  sameSite?: 'Lax' | 'Strict'
+  origin?: string
+  host?: string
+  cors?: { origins: readonly string[]; credentials: boolean }
 }
 
 /**
@@ -69,5 +78,15 @@ 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,
+    cors: config.cors
+      ? {
+          origins: config.cors.origins ?? config.trustedOrigins ?? [],
+          credentials: config.cors.credentials ?? false,
+        }
+      : undefined,
   }
 }

package/src/server/context.ts

@@ -0,0 +1,101 @@
+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 }
+  }
+}
+
+/**
+ * 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,37 @@
+import type { Context } from 'hono'
+import { deleteCookie, getCookie, setCookie } 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. */
+  delete(name: string, options?: Pick<RouteCookieOptions, 'path' | 'domain'>): void
+}
+
+/** 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)
+    },
+  }
+}

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'
@@ -11,7 +12,9 @@ import { wireAppEffects } from './effects.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 +37,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 +58,21 @@ 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
+  /** 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,6 +89,10 @@ 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> {
@@ -83,6 +105,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 +118,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 +134,17 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
       : config.headExtras,
     inspector,
     ssePingMs: resolved.ssePingMs,
+    trustedOrigins: resolved.trustedOrigins,
+    sameSite: resolved.sameSite,
+    origin: resolved.origin,
+    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 +169,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,
   }
 }

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

@@ -54,6 +54,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 +68,13 @@ 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
+  /** 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,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>
 }
@@ -129,6 +142,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 +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,
     })
   }
 
@@ -266,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({
@@ -151,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
@@ -291,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) {
@@ -341,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
@@ -408,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,
@@ -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()
+  }
+}

package/src/server/session.ts

@@ -1,9 +1,39 @@
 import { randomUUID } from 'node:crypto'
 import type { Context } from 'hono'
 import { getCookie, setCookie } from 'hono/cookie'
+import type { Store } from './store.ts'
 
 export const SESSION_COOKIE = 'stator_sid'
 
+/** Reserved storage-key prefix — framework-only. Machine names may not use it,
+ *  so per-session framework keys (like claims) can't collide with a machine. */
+export const RESERVED_KEY_PREFIX = '__'
+/** Session-claims storage key (a reserved pseudo-machine name in the Store). */
+export const CLAIMS_KEY = '__claims'
+
+/** Per-request session state — established once and shared across middleware and
+ *  handlers so they see one `sid` (and one claims snapshot), instead of each
+ *  calling `getOrCreateSessionId` and risking two ids on a first request. */
+export interface SessionState {
+  sid: string
+  isNew: boolean
+  /** App-defined claims; `undefined` until loaded (returning sessions) or set. */
+  claims: unknown
+  /** Set when claims changed this request and must persist at request end. */
+  claimsDirty: boolean
+}
+
+declare module 'hono' {
+  interface ContextVariableMap {
+    statorSession: SessionState
+  }
+}
+
+/** The established session state for this request, if any. */
+export function getSessionState(c: Context): SessionState | undefined {
+  return c.get('statorSession')
+}
+
 /** Secure cookie flag — set when running behind HTTPS. Enabled by
  *  NODE_ENV=production; can be overridden via STATOR_SECURE_COOKIE. */
 function shouldUseSecureCookie(): boolean {
@@ -12,12 +42,24 @@ function shouldUseSecureCookie(): boolean {
   return process.env.NODE_ENV === 'production'
 }
 
+/** The session cookie's `SameSite`. `Lax` (default) allows same-site sibling
+ *  subdomains; `Strict` withholds the cookie from every cross-site request (the
+ *  controlled posture — paired with the guard's allowlist-only same-site branch).
+ *  Set once at app construction; every `createApp` re-sets it, so it can't leak
+ *  across apps in one process. */
+let cookieSameSite: 'Lax' | 'Strict' = 'Lax'
+
+/** Configure the session cookie's `SameSite`. Called at app construction. */
+export function setSessionSameSite(value: 'Lax' | 'Strict'): void {
+  cookieSameSite = value
+}
+
 /** Write the session cookie — shared by session creation and rotation so
  *  the flags can never drift apart. */
 export function setSessionCookie(c: Context, sessionId: string): void {
   setCookie(c, SESSION_COOKIE, sessionId, {
     httpOnly: true,
-    sameSite: 'Lax',
+    sameSite: cookieSameSite,
     path: '/',
     secure: shouldUseSecureCookie(),
   })
@@ -27,9 +69,58 @@ export function getOrCreateSessionId(c: Context): {
   sessionId: string
   isNew: boolean
 } {
-  const existing = getCookie(c, SESSION_COOKIE)
-  if (existing) return { sessionId: existing, isNew: false }
-  const sessionId = randomUUID()
-  setSessionCookie(c, sessionId)
-  return { sessionId, isNew: true }
+  // Idempotent per request: the first caller (middleware or handler) establishes
+  // the session; everyone after reads the same one. Closes the double-create bug.
+  const established = c.get('statorSession')
+  if (established) return { sessionId: established.sid, isNew: established.isNew }
+
+  const cookieSid = getCookie(c, SESSION_COOKIE)
+  const sessionId = cookieSid ?? randomUUID()
+  const isNew = cookieSid === undefined
+  if (isNew) setSessionCookie(c, sessionId)
+
+  c.set('statorSession', { sid: sessionId, isNew, claims: undefined, claimsDirty: false })
+  return { sessionId, isNew }
+}
+
+/**
+ * Rotate (or, with `clear`, destroy) the current session *right now* and update
+ * the shared session state + cookie. The immediate counterpart to a handler's
+ * deferred `rotateSession`/`clearSession` — used from middleware, which runs
+ * upstream of the machine pipeline and has no "after the handler" seam.
+ *
+ * Rotate: state moves to a fresh id (fixation defense on privilege change);
+ * any claims set this request follow to the new id at persist time. Clear: the
+ * old session's state is DELETED and the browser starts anonymous. Returns the
+ * new session id.
+ */
+export async function rotateSessionNow(
+  c: Context,
+  store: { persistence: Pick<Store, 'deleteSession' | 'renameSession'> },
+  opts?: { clear?: boolean },
+): Promise<string> {
+  const { sessionId } = getOrCreateSessionId(c)
+  const clear = opts?.clear === true
+  const newSessionId = randomUUID()
+  if (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)
+  const session = getSessionState(c)
+  if (session) {
+    session.sid = newSessionId
+    if (clear) {
+      session.claims = undefined
+      session.claimsDirty = false
+    }
+  }
+  return newSessionId
 }