@statorjs/stator 2.3.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.3.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.3.0"
+    "@statorjs/stator": "2.4.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

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

@@ -30,6 +30,12 @@ export interface StatorConfig {
    *  (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). */

package/src/server/config-compat.ts

@@ -32,6 +32,7 @@ interface NestedReads {
   trustedOrigins?: readonly string[]
   origin?: string
   host?: string
+  secret?: string
   cors?: { origins?: readonly string[]; credentials?: boolean }
 }
 
@@ -47,6 +48,8 @@ export interface ResolvedAppConfig {
   sameSite?: 'Lax' | 'Strict'
   origin?: string
   host?: string
+  /** Signed-cookie signing key. `config.secret` ?? `STATOR_SECRET`. */
+  secret?: string
   cors?: { origins: readonly string[]; credentials: boolean }
 }
 
@@ -82,6 +85,8 @@ export function resolveAppConfig(config: NestedReads & DeprecatedFlatConfig): Re
     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 ?? [],

package/src/server/context.ts

@@ -20,6 +20,8 @@ declare module 'hono' {
   interface ContextVariableMap {
     stator: StatorConfigData
     statorStore: { persistence: Store }
+    /** Signed-cookie signing key, stashed by the bridge when configured. */
+    statorSecret: string
   }
 }
 

package/src/server/cookies.ts

@@ -1,5 +1,5 @@
 import type { Context } from 'hono'
-import { deleteCookie, getCookie, setCookie } from 'hono/cookie'
+import { deleteCookie, getCookie, getSignedCookie, setCookie, setSignedCookie } from 'hono/cookie'
 import type { RouteCookieOptions } from './routing.ts'
 
 /**
@@ -17,8 +17,31 @@ export interface CookieJar {
   /** 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. */
+  /** 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)`
@@ -33,5 +56,14 @@ export function cookieJar(c: Context): CookieJar {
     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/create-app.ts

@@ -9,6 +9,7 @@ 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'
@@ -63,6 +64,9 @@ export interface CreateAppConfig extends DeprecatedFlatConfig {
   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`. */
@@ -96,6 +100,9 @@ export interface StatorApp {
 }
 
 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
@@ -137,6 +144,7 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
     trustedOrigins: resolved.trustedOrigins,
     sameSite: resolved.sameSite,
     origin: resolved.origin,
+    secret: resolved.secret,
     cors: resolved.cors,
     middleware,
   })

package/src/server/dev.ts

@@ -12,6 +12,7 @@ import { machineStub, stator } from '../vite/index.ts'
 import type { AppStore } from './app-store.ts'
 import { findFreePort, installGracefulShutdown, printDevBanner } from './banner.ts'
 import { resolveAppConfig } from './config-compat.ts'
+import { loadDotenv } from './env.ts'
 import { logger, setLogLevel } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
@@ -73,6 +74,9 @@ export interface DevAppConfig {
   trustedOrigins?: readonly string[]
   /** Canonical app URL, exposed via `stator(c).origin`. */
   origin?: string
+  /** Signed-cookie signing key. Falls back to `STATOR_SECRET`. Mirrors
+   *  `StatorConfig.secret`. */
+  secret?: string
   /** Cross-origin READ policy (CORS); `origins` defaults to `trustedOrigins`. */
   cors?: { origins?: string[]; credentials?: boolean }
   // Deprecated flat keys — accepted (typed) so 2.1.0 callers don't break; nested
@@ -108,6 +112,9 @@ export interface DevApp {
 }
 
 export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
+  // Load .env before anything reads process.env. No-op if the CLI already
+  // loaded it; covers a direct `createDevApp` call (a hand-written dev entry).
+  loadDotenv(resolve(config.root))
   // Vite's HMR websocket defaults to 24678 for EVERY dev server — two
   // stator apps side by side would fight over it (the loser's live reload
   // silently dies). Probe a free one instead.
@@ -246,6 +253,7 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
       trustedOrigins: resolved.trustedOrigins,
       sameSite: resolved.sameSite,
       origin: resolved.origin,
+      secret: resolved.secret,
       cors: resolved.cors,
       middleware,
     })

package/src/server/env.ts

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

package/src/server/http.ts

@@ -46,6 +46,9 @@ export interface HttpConfig {
   sameSite?: 'Lax' | 'Strict'
   /** Canonical app origin, exposed to middleware via `stator(c).origin`. */
   origin?: string
+  /** Signed-cookie signing key (`config.secret` ?? `STATOR_SECRET`). Stashed on
+   *  the request context so `cookies.setSigned`/`getSigned` can reach it. */
+  secret?: string
   /** Resolved CORS read policy, exposed via `stator(c).cors`. */
   cors?: { origins: readonly string[]; credentials: boolean }
   /** The app's discovered `middleware.ts` definition (if any). `withDefaults`
@@ -179,6 +182,8 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     })
     // Stash the store so middleware session ops (rotate/clear) can act now.
     c.set('statorStore', config.store)
+    // Stash the signing key so the cookie jar's signed methods can reach it.
+    if (config.secret !== undefined) c.set('statorSecret', config.secret)
     const { sessionId, isNew } = getOrCreateSessionId(c)
     const session = getSessionState(c)
     if (!isNew && session) {