@statorjs/stator 2.1.0 → 2.3.0

package/src/server/config-compat.ts

@@ -0,0 +1,92 @@
+import type { LogLevel } from '../config.ts'
+import type { AppStore } from './app-store.ts'
+import type { Store } from './store.ts'
+
+/**
+ * The pre-nesting flat config keys. `createApp` shipped all of these at 2.1.0 (and
+ * `createDevApp` all but `ssePingMs`), so they stay ACCEPTED — typed and
+ * `@deprecated`, not removed — to keep those callers compiling and running:
+ * nesting the args would otherwise be a breaking change (a major). The removal is
+ * parked as a major-cutover (see ROADMAP surface hygiene). Nested values win when
+ * both a flat key and its nested home are present.
+ */
+export interface DeprecatedFlatConfig {
+  /** @deprecated use `persistence.session` */
+  store?: Store
+  /** @deprecated use `persistence.app` */
+  appStore?: AppStore
+  /** @deprecated use `sessions.ttlSeconds` */
+  sessionTtlSeconds?: number
+  /** @deprecated use `realtime.pingMs` */
+  ssePingMs?: number
+  /** @deprecated use `dev.inspector` */
+  inspector?: boolean
+}
+
+interface NestedReads {
+  persistence?: { session?: Store; app?: AppStore }
+  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. */
+export interface ResolvedAppConfig {
+  session?: Store
+  app?: AppStore
+  sessionTtlSeconds?: number
+  ssePingMs?: number
+  inspector?: boolean
+  logLevel?: LogLevel
+  trustedOrigins?: readonly string[]
+  sameSite?: 'Lax' | 'Strict'
+  origin?: string
+  host?: string
+  cors?: { origins: readonly string[]; credentials: boolean }
+}
+
+/**
+ * Resolve the nested config, falling back to the deprecated flat keys, and warn
+ * once (per app construction) if any flat key is in use. Nested wins. Exported for
+ * testing.
+ */
+export function resolveAppConfig(config: NestedReads & DeprecatedFlatConfig): ResolvedAppConfig {
+  const deprecated: string[] = []
+  if (config.store !== undefined) deprecated.push('store → persistence.session')
+  if (config.appStore !== undefined) deprecated.push('appStore → persistence.app')
+  if (config.sessionTtlSeconds !== undefined)
+    deprecated.push('sessionTtlSeconds → sessions.ttlSeconds')
+  if (config.ssePingMs !== undefined) deprecated.push('ssePingMs → realtime.pingMs')
+  if (config.inspector !== undefined) deprecated.push('inspector → dev.inspector')
+
+  if (deprecated.length > 0) {
+    console.warn(
+      'stator: these createApp/createDevApp options are deprecated and will be removed in a future major — move to the nested shape:\n' +
+        deprecated.map((d) => `  ${d}`).join('\n'),
+    )
+  }
+
+  return {
+    session: config.persistence?.session ?? config.store,
+    app: config.persistence?.app ?? config.appStore,
+    sessionTtlSeconds: config.sessions?.ttlSeconds ?? config.sessionTtlSeconds,
+    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,39 +1,78 @@
 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'
 import type { AppStore } from './app-store.ts'
-import { installGracefulShutdown } from './banner.ts'
+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 { buildHonoApp } from './http.ts'
-import { logger } from './logger.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 {
+export interface CreateAppConfig extends DeprecatedFlatConfig {
   machinesDir: string
   routesDir: string
   staticDir?: string
-  /** Persistence adapter for session-lifecycle machine state. Defaults to
-   *  InMemoryStore — fine for dev, V1 adapters swap in here. */
-  store?: Store
-  /** Persistence for `persist: true` app-lifecycle machines (no TTL, one
-   *  blob per machine). Defaults to in-memory (restart-wipe); pass
-   *  RedisAppStore for durable app state. */
-  appStore?: AppStore
-  /** Per-session TTL in seconds. Every set to any of the session's
-   *  machines refreshes this expiry. Defaults to 24h (86400). */
-  sessionTtlSeconds?: number
-  /** SSE heartbeat interval in ms (default 25s). Tests shorten it. */
-  ssePingMs?: number
+  /** Swappable persistence adapters, grouped by concern. Both optional —
+   *  default to in-memory (restart-wipe). Mirrors `StatorConfig.persistence`. */
+  persistence?: {
+    /** Session-lifecycle machine state. Defaults to InMemoryStore — fine for
+     *  dev, V1 adapters swap in here. */
+    session?: Store
+    /** App-lifecycle machine state for `persist: true` machines (no TTL, one
+     *  blob per machine). Defaults to in-memory (restart-wipe); pass
+     *  RedisAppStore for durable app state. */
+    app?: AppStore
+  }
+  /** Session policy. */
+  sessions?: {
+    /** 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?: {
+    /** SSE heartbeat interval in ms (default 25s). Tests shorten it. */
+    pingMs?: number
+  }
+  /** Dev-only tooling. */
+  dev?: {
+    /** Serve + inject the wire inspector toolbar (the dev server's on by
+     *  default; production opts in — demo sites want the wire visible). */
+    inspector?: boolean
+  }
+  /** Logging policy. */
+  logging?: {
+    /** Minimum level to emit. Default: `warn` in production, `info` in dev.
+     *  `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>
-  /** Serve + inject the wire inspector toolbar (the dev server's on by
-   *  default; production opts in — demo sites want the wire visible). */
-  inspector?: boolean
+  /** Path to the app's `middleware.ts` (if any). Loaded and validated; its
+   *  default export must be `defineMiddleware`/`dangerouslyDefineMiddleware`. */
+  middlewareFile?: string
 }
 
 export interface StatorApp {
@@ -50,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> {
@@ -57,11 +100,17 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
   const routesDir = resolve(config.routesDir)
   const staticDir = config.staticDir ? resolve(config.staticDir) : undefined
 
+  const resolved = resolveAppConfig(config)
+  // Level precedence: LOG_LEVEL env > config > the production default (createApp
+  // 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 persistence = config.store ?? new InMemoryStore()
-  const store = new MachineStore(defs, persistence, {
-    sessionTtlSeconds: config.sessionTtlSeconds,
-    appStore: config.appStore,
+  const sessionStore = resolved.session ?? new InMemoryStore()
+  const store = new MachineStore(defs, sessionStore, {
+    sessionTtlSeconds: resolved.sessionTtlSeconds,
+    appStore: resolved.app,
   })
   // Wire the effect scheduler BEFORE booting: a fresh app machine fires its
   // initial-state entry effect during boot, and that must have somewhere to go.
@@ -69,25 +118,35 @@ 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,
     store,
     staticDir,
-    headExtras: config.inspector
+    headExtras: inspector
       ? async (filePath) => {
           const base = (await config.headExtras?.(filePath)) ?? ''
           return `${base}\n<script src="/@stator/inspector.js" defer></script>`
         }
       : config.headExtras,
-    inspector: config.inspector,
-    ssePingMs: config.ssePingMs,
+    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 }, () => {
-          logger.info({ port, machines: defs.length, routes: routes.length }, 'listening')
+        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()
         })
         // Production is strict about its port (a collision is a deploy
@@ -110,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()
+  }
+}