@c9up/ream 0.2.26 → 0.2.28

package/src/session/drivers/CookieDriver.ts

@@ -5,23 +5,33 @@ import type { SessionDriver } from '../Session.js'
  * Cookie session driver — stores session data in an encrypted cookie (AES-256-GCM).
  * Stateless on the server. Limited by cookie size (~4KB).
  * Requires a secret for encryption.
+ *
+ * Sealed for the cookie's name, as upstream seals every encrypted cookie, so a
+ * value encrypted for another cookie under the same key cannot be presented as
+ * the session. And sealed with its expiry — the named deviation: upstream
+ * leaves expiry to the browser's `maxAge`, which a copied cookie does not
+ * obey, so a session lifted from a browser stayed valid for as long as the key
+ * did. Here a value older than the session's lifetime opens as nothing.
  */
 export class CookieDriver implements SessionDriver {
   #signer: CookieSigner
+  readonly #purpose: string
+  readonly stateless = true
 
-  constructor(secret: string) {
+  constructor(secret: string, cookieName = 'ream_session') {
     if (!secret) {
       throw new Error(
         'CookieDriver requires a secret for session encryption. Set session.secret in your config.',
       )
     }
     this.#signer = new CookieSigner(secret)
+    this.#purpose = cookieName
   }
 
   async read(sessionId: string): Promise<Record<string, unknown> | null> {
     if (!sessionId) return null
-    const decrypted = this.#signer.decrypt(sessionId)
-    if (!decrypted) return null
+    const decrypted = this.#signer.decrypt(sessionId, this.#purpose)
+    if (typeof decrypted !== 'string') return null
     try {
       return JSON.parse(decrypted)
     } catch {
@@ -33,6 +43,11 @@ export class CookieDriver implements SessionDriver {
     // Cookie driver writes via the response cookie — handled by middleware
   }
 
+  async update(_sessionId: string, _data: Record<string, unknown>, _ttl: number): Promise<boolean> {
+    // Cookie driver writes via the response cookie — handled by middleware
+    return true
+  }
+
   async destroy(_sessionId: string): Promise<void> {
     // Cookie deletion handled by middleware setting maxAge=0
   }
@@ -41,8 +56,8 @@ export class CookieDriver implements SessionDriver {
     // Cookie renewal handled by middleware
   }
 
-  /** Encode session data for cookie storage (encrypted). */
-  encode(data: Record<string, unknown>): string {
-    return this.#signer.encrypt(JSON.stringify(data))
+  /** Encode session data for cookie storage (encrypted), valid for `ttl` seconds. */
+  encode(data: Record<string, unknown>, ttl: number): string {
+    return this.#signer.encrypt(JSON.stringify(data), ttl * 1000, this.#purpose)
   }
 }

package/src/session/drivers/DatabaseDriver.ts

@@ -143,6 +143,16 @@ export class DatabaseDriver implements SessionDriverWithTagging {
     }
   }
 
+  /** One UPDATE: a row deleted or expired meanwhile matches nothing. */
+  async update(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<boolean> {
+    const now = Date.now()
+    const updated = await this.#db.execute(
+      `UPDATE ${this.#table} SET data = ?, expires_at = ? WHERE id = ? AND expires_at >= ?`,
+      [JSON.stringify(data), now + ttl * 1000, sessionId, now],
+    )
+    return updated.rowsAffected > 0
+  }
+
   async destroy(sessionId: string): Promise<void> {
     await this.#db.execute(`DELETE FROM ${this.#table} WHERE id = ?`, [sessionId])
   }

package/src/session/drivers/FileDriver.ts

@@ -16,6 +16,18 @@ export interface FileDriverOptions {
   location: string
 }
 
+/** How long a writer waits for a session's lock before giving up. */
+const LOCK_WAIT_MS = 2000
+/**
+ * A lock older than this was left by a process that died holding it. Every
+ * operation under the lock is one small file read or write, far below it.
+ */
+const LOCK_STALE_MS = 10_000
+
+function hasCode(error: unknown, code: string): boolean {
+  return error instanceof Error && Reflect.get(error, 'code') === code
+}
+
 export class FileDriver implements SessionDriver {
   readonly #location: string
 
@@ -37,6 +49,17 @@ export class FileDriver implements SessionDriver {
   }
 
   async read(sessionId: string): Promise<Record<string, unknown> | null> {
+    return this.#read(sessionId, () => this.destroy(sessionId))
+  }
+
+  /**
+   * Read, dropping an expired file through `drop`: `destroy()` from outside,
+   * a bare removal from inside the lock, which is already held there.
+   */
+  async #read(
+    sessionId: string,
+    drop: () => Promise<void>,
+  ): Promise<Record<string, unknown> | null> {
     let raw: string
     try {
       raw = await fs.promises.readFile(this.#pathFor(sessionId), 'utf8')
@@ -48,7 +71,7 @@ export class FileDriver implements SessionDriver {
       if (typeof parsed !== 'object' || parsed === null) return null
       const entry = parsed as { expiresAt?: number; data?: Record<string, unknown> }
       if (typeof entry.expiresAt === 'number' && entry.expiresAt < Date.now()) {
-        await this.destroy(sessionId)
+        await drop()
         return null
       }
       return entry.data ?? {}
@@ -60,6 +83,43 @@ export class FileDriver implements SessionDriver {
   }
 
   async write(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<void> {
+    await this.#locked(sessionId, () => this.#replace(sessionId, data, ttl))
+  }
+
+  /**
+   * Written only while the file is still there. A filesystem has no
+   * conditional write, so every change to a session's file — this, `write`,
+   * `destroy` and `touch` — runs under that session's lock: a `destroy` from a
+   * logout cannot land between the check and the write, in this process or in
+   * another one sharing the directory.
+   */
+  async update(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<boolean> {
+    return this.#locked(sessionId, async () => {
+      if ((await this.#read(sessionId, () => this.#remove(sessionId))) === null) return false
+      await this.#replace(sessionId, data, ttl)
+      return true
+    })
+  }
+
+  async destroy(sessionId: string): Promise<void> {
+    await this.#locked(sessionId, () => this.#remove(sessionId))
+  }
+
+  async #remove(sessionId: string): Promise<void> {
+    await fs.promises.rm(this.#pathFor(sessionId), { force: true })
+  }
+
+  async touch(sessionId: string, ttl: number): Promise<void> {
+    await this.#locked(sessionId, async () => {
+      const data = await this.#read(sessionId, () => this.#remove(sessionId))
+      // Nothing stored: there is no expiry to slide, and writing here would
+      // create the very session that was not there.
+      if (data === null || Object.keys(data).length === 0) return
+      await this.#replace(sessionId, data, ttl)
+    })
+  }
+
+  async #replace(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<void> {
     const file = this.#pathFor(sessionId)
     const payload = JSON.stringify({ expiresAt: Date.now() + ttl * 1000, data })
     // Written to a temporary neighbour then renamed: a crash mid-write would
@@ -70,15 +130,35 @@ export class FileDriver implements SessionDriver {
     await fs.promises.rename(temp, file)
   }
 
-  async destroy(sessionId: string): Promise<void> {
-    await fs.promises.rm(this.#pathFor(sessionId), { force: true })
-  }
-
-  async touch(sessionId: string, ttl: number): Promise<void> {
-    const data = await this.read(sessionId)
-    // Nothing stored: there is no expiry to slide, and writing here would
-    // create the very session that was not there.
-    if (data === null || Object.keys(data).length === 0) return
-    await this.write(sessionId, data, ttl)
+  /**
+   * Run `fn` holding the session's lock: a directory beside its file, which
+   * `mkdir` creates atomically or refuses — the one exclusive primitive every
+   * filesystem gives, across processes too.
+   */
+  async #locked<T>(sessionId: string, fn: () => Promise<T>): Promise<T> {
+    const lock = `${this.#pathFor(sessionId)}.lock`
+    const deadline = Date.now() + LOCK_WAIT_MS
+    for (;;) {
+      try {
+        await fs.promises.mkdir(lock)
+        break
+      } catch (error) {
+        if (!hasCode(error, 'EEXIST')) throw error
+        const held = await fs.promises.stat(lock).catch(() => null)
+        if (held !== null && Date.now() - held.mtimeMs > LOCK_STALE_MS) {
+          await fs.promises.rm(lock, { recursive: true, force: true })
+          continue
+        }
+        if (Date.now() > deadline) {
+          throw new Error(`Session file is locked: ${lock}`)
+        }
+        await new Promise((resolve) => setTimeout(resolve, 5))
+      }
+    }
+    try {
+      return await fn()
+    } finally {
+      await fs.promises.rmdir(lock).catch(() => {})
+    }
   }
 }

package/src/session/drivers/MemoryDriver.ts

@@ -57,6 +57,15 @@ export class MemoryDriver implements SessionDriverWithTagging {
     }
   }
 
+  /** Atomic by construction: nothing else runs between the check and the set. */
+  async update(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<boolean> {
+    const entry = this.#store.get(sessionId)
+    if (!entry || entry.expiresAt < Date.now()) return false
+    this.#store.delete(sessionId)
+    this.#store.set(sessionId, { data, expiresAt: Date.now() + ttl * 1000 })
+    return true
+  }
+
   async destroy(sessionId: string): Promise<void> {
     this.#store.delete(sessionId)
     // Drop the tags too: a destroyed session left in the index would be

package/src/session/drivers/RedisDriver.ts

@@ -142,6 +142,13 @@ export class RedisDriver implements SessionDriverWithTagging {
     await client.set(this.#key(sessionId), JSON.stringify(data), 'EX', ttl)
   }
 
+  /** `XX` makes the existence check and the write one command. */
+  async update(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<boolean> {
+    const client = await this.#client()
+    const reply = await client.set(this.#key(sessionId), JSON.stringify(data), 'EX', ttl, 'XX')
+    return reply !== null
+  }
+
   async destroy(sessionId: string): Promise<void> {
     const client = await this.#client()
     await client.del(this.#key(sessionId))

package/src/session/errors.ts

@@ -25,6 +25,23 @@ export class E_SESSION_NOT_READY extends Exception {
   }
 }
 
+/**
+ * A store with no `update()`: it cannot write a session back only while its
+ * entry still exists, so a request running across a logout could sign the
+ * user in again. Refused when the store is attached, not at the first race.
+ */
+export class E_SESSION_STORE_NOT_CONDITIONAL extends Exception {
+  static override status = 500
+  static override code = 'E_SESSION_STORE_NOT_CONDITIONAL'
+
+  constructor() {
+    super(
+      'This session store has no update(): it must write a session only over an entry that still exists, in one step. See "Writing a session store".',
+      { status: 500, code: 'E_SESSION_STORE_NOT_CONDITIONAL' },
+    )
+  }
+}
+
 /** The configured store cannot tag sessions (cookie and file stores cannot). */
 export class E_SESSION_TAGGING_NOT_SUPPORTED extends Exception {
   static override status = 500