@statorjs/stator 1.1.1 → 1.2.0

package/README.md

@@ -96,7 +96,7 @@ const [counter] = Stator.reads([Counter])
 </html>
 ```
 
-Run with `tsx server.ts`. See the repo's `apps/example` for the full wiring
+Run with `tsx server.ts`. See the repo's `examples/desksmith` for the full wiring
 (type sync, production build, deploy).
 
 ## License

package/package.json

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

package/src/server/api-route.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto'
 import type { Context } from 'hono'
 import { setCookie } from 'hono/cookie'
 import { scheduleSessionEffects } from './effects.ts'
@@ -13,7 +14,7 @@ import type {
   Directive,
   RouteRequest,
 } from './routing.ts'
-import { getOrCreateSessionId } from './session.ts'
+import { getOrCreateSessionId, setSessionCookie } from './session.ts'
 import { withSessionLock } from './session-lock.ts'
 import { SessionRuntime } from './session-runtime.ts'
 import { fanOut } from './sse.ts'
@@ -42,6 +43,7 @@ export async function runApiRoute(
   params?: Record<string, string>,
 ): Promise<Response> {
   const { sessionId } = getOrCreateSessionId(c)
+  let rotation: { clear: boolean } | null = null
   const request = params
     ? { ...buildRouteRequest(c, discovered.paramNames), params }
     : buildRouteRequest(c, discovered.paramNames)
@@ -63,6 +65,12 @@ export async function runApiRoute(
           // The target machine is addressed by its def; read the name off it.
           const dispatchedTouched = runtime.processEvent(machine.name, event)
           for (const name of dispatchedTouched) touched.add(name)
+          // Same honesty as client dispatch: a guard-dropped event commits
+          // nothing, and handlers (login flows especially) need to know.
+          return { committed: dispatchedTouched.size > 0 }
+        },
+        rotateSession: (opts) => {
+          rotation = { clear: opts?.clear === true }
         },
       }
 
@@ -78,9 +86,32 @@ export async function runApiRoute(
         await runtime.persistTouched(touched)
         await fanOut(touched, { sessionId })
       }
+
+      // Session rotation (fixation defense). Order matters: the runtime has
+      // already persisted under the OLD id and fan-out has reached the old
+      // id's connections (about to be navigated away) — now the whole
+      // session moves (or, for logout, dies) and the response carries the
+      // 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
+      }
       // Effects queued by dispatched events run after this callback returns
       // (never under the session lock); see server/effects.ts.
-      scheduleSessionEffects(runtime, store, sessionId)
+      scheduleSessionEffects(runtime, store, effectsSessionId)
 
       // Escape hatch: handler returned a real Response. Pass through.
       if (result instanceof Response) return result

package/src/server/app-dispatch.ts

@@ -18,7 +18,7 @@ export async function dispatchToApp<D extends AnyMachineDef>(
   store: MachineStore,
   machine: D,
   event: EventOf<D>,
-): Promise<void> {
+): Promise<{ committed: boolean }> {
   const name = machine.name
   const handle = store.appInstance(name)
   if (!handle) {
@@ -46,6 +46,10 @@ export async function dispatchToApp<D extends AnyMachineDef>(
       await store.persistAppMachine(touchedName)
     }
     await fanOut(touched)
+    // Same contract as client and API-route dispatch: did the TARGET machine
+    // actually commit a transition? Webhook receivers use this to tell a
+    // processed event from a guard-dropped duplicate.
+    return { committed: touched.has(name) }
   } finally {
     runtime.dispose()
   }

package/src/server/cached-store.ts

@@ -99,6 +99,20 @@ export class CachedStore implements Store {
     await this.backing.deleteSession(sid)
   }
 
+  async renameSession(oldSid: string, newSid: string): Promise<void> {
+    // Drop (don't move) cache entries — the next read repopulates from the
+    // backing under the new id. Simpler than key surgery, and rotation is
+    // rare (login/logout).
+    const prefix = `${oldSid}:`
+    for (const k of [...this.cache.keys()]) {
+      if (k.startsWith(prefix)) this.cache.delete(k)
+    }
+    if (!this.backing.renameSession) {
+      throw new Error('stator: CachedStore backing store does not support renameSession')
+    }
+    await this.backing.renameSession(oldSid, newSid)
+  }
+
   /** Insert / refresh an entry at LRU-end and evict oldest if over capacity. */
   private populate(key: string, snapshot: unknown, ttlMs: number): void {
     this.cache.delete(key)

package/src/server/redis-store.ts

@@ -69,6 +69,14 @@ export class RedisStore implements Store {
     await this.client.del(this.key(sid))
   }
 
+  async renameSession(oldSid: string, newSid: string): Promise<void> {
+    // RENAME is atomic and carries the hash's TTL; it throws when the source
+    // is missing (an empty session has nothing to move — fine).
+    if ((await this.client.exists(this.key(oldSid))) === 1) {
+      await this.client.rename(this.key(oldSid), this.key(newSid))
+    }
+  }
+
   /** Close the connection. Call on graceful shutdown. */
   async close(): Promise<void> {
     await this.client.quit()

package/src/server/routing.ts

@@ -136,7 +136,18 @@ export interface ApiRouteHelpers {
    *  Processes the event under the dispatch context, persists touched machines,
    *  fires cross-machine subscriptions. The machine must be in the route's
    *  loaded graph (its `reads`, transitively). */
-  dispatch: <D extends AnyMachineDef>(machine: D, event: EventOf<D>) => Promise<void>
+  dispatch: <D extends AnyMachineDef>(
+    machine: D,
+    event: EventOf<D>,
+  ) => Promise<{ committed: boolean }>
+  /** Rotate the session id — the fixation defense for privilege changes.
+   *  Call on login (state moves to a fresh id; the old id becomes worthless
+   *  to anyone who captured it) and on logout with `{ clear: true }` (the
+   *  old session's state is DELETED and the browser starts anonymous).
+   *  Applied after the handler returns: state persists under the new id and
+   *  the response carries the new cookie. Requires a store with
+   *  `renameSession` (all built-in stores have it). */
+  rotateSession: (opts?: { clear?: boolean }) => void
 }
 
 export interface ApiRouteDefinition {

package/src/server/session.ts

@@ -12,6 +12,17 @@ function shouldUseSecureCookie(): boolean {
   return process.env.NODE_ENV === 'production'
 }
 
+/** 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',
+    path: '/',
+    secure: shouldUseSecureCookie(),
+  })
+}
+
 export function getOrCreateSessionId(c: Context): {
   sessionId: string
   isNew: boolean
@@ -19,11 +30,6 @@ export function getOrCreateSessionId(c: Context): {
   const existing = getCookie(c, SESSION_COOKIE)
   if (existing) return { sessionId: existing, isNew: false }
   const sessionId = randomUUID()
-  setCookie(c, SESSION_COOKIE, sessionId, {
-    httpOnly: true,
-    sameSite: 'Lax',
-    path: '/',
-    secure: shouldUseSecureCookie(),
-  })
+  setSessionCookie(c, sessionId)
   return { sessionId, isNew: true }
 }

package/src/server/store.ts

@@ -29,6 +29,10 @@ export interface Store {
   ): Promise<void>
   has(sessionId: string, machineName: string): Promise<boolean>
   deleteSession(sessionId: string): Promise<void>
+  /** Move EVERY machine snapshot from one session id to another (used by
+   *  session rotation on privilege change). Optional for custom adapters;
+   *  rotation fails loudly when the configured store lacks it. */
+  renameSession?(oldSessionId: string, newSessionId: string): Promise<void>
 }
 
 /**
@@ -92,4 +96,16 @@ export class InMemoryStore implements Store {
   async deleteSession(sid: string): Promise<void> {
     this.dropSession(sid)
   }
+
+  async renameSession(oldSid: string, newSid: string): Promise<void> {
+    if (this.isExpired(oldSid)) {
+      this.dropSession(oldSid)
+      return
+    }
+    const session = this.data.get(oldSid)
+    const expiry = this.expiryAt.get(oldSid)
+    this.dropSession(oldSid)
+    if (session) this.data.set(newSid, session)
+    if (expiry !== undefined) this.expiryAt.set(newSid, expiry)
+  }
 }