@c9up/ream 0.2.27 → 0.2.29

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

@@ -9,8 +9,9 @@ const SWEEP_THRESHOLD = 1000
  * The sweep alone only removes EXPIRED entries, so within the TTL window
  * nothing bounded growth: anyone able to request a page could mint sessions
  * until the process ran out of memory, without ever logging in. Past the cap
- * the oldest sessions are dropped — a bounded store that forgets is strictly
- * better than an unbounded one that dies.
+ * the least recently used sessions are dropped (a write, an update or a
+ * touch moves a session to the back of the line) — a bounded store that
+ * forgets is strictly better than an unbounded one that dies.
  */
 const DEFAULT_MAX_ENTRIES = 10_000
 
@@ -57,6 +58,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
@@ -69,9 +79,14 @@ export class MemoryDriver implements SessionDriverWithTagging {
 
   async touch(sessionId: string, ttl: number): Promise<void> {
     const entry = this.#store.get(sessionId)
-    if (entry) {
-      entry.expiresAt = Date.now() + ttl * 1000
-    }
+    if (!entry || entry.expiresAt < Date.now()) return
+    // Re-inserted, not updated in place: eviction drops the head of the map,
+    // so a session in use has to move to the tail. Updated in place, a
+    // signed-in user who keeps browsing stayed first in line, and ten
+    // thousand anonymous requests evicted them.
+    entry.expiresAt = Date.now() + ttl * 1000
+    this.#store.delete(sessionId)
+    this.#store.set(sessionId, entry)
   }
 
   async tag(sessionId: string, userId: string | number): Promise<void> {

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
@@ -37,3 +54,34 @@ export class E_SESSION_TAGGING_NOT_SUPPORTED extends Exception {
     )
   }
 }
+
+/**
+ * A session config without a store (AdonisJS raises "Missing store" for the
+ * same config). There is no implicit fallback: the memory store is per
+ * process and bounded — a restart, a second replica or enough anonymous
+ * traffic signs every user out — so it is only used when it is chosen.
+ */
+export class E_SESSION_STORE_NOT_CONFIGURED extends Exception {
+  static override status = 500
+  static override code = 'E_SESSION_STORE_NOT_CONFIGURED'
+
+  constructor() {
+    super(
+      "No session store is configured. Set `store` in config/session.ts (redis, database, file or cookie), or `store: 'memory'` for sessions kept in this process only (tests, a single development instance).",
+      { status: 500, code: 'E_SESSION_STORE_NOT_CONFIGURED' },
+    )
+  }
+}
+
+/** `cookie.httpOnly: false` — the session id would be readable by any script on the page. */
+export class E_SESSION_COOKIE_NOT_HTTP_ONLY extends Exception {
+  static override status = 500
+  static override code = 'E_SESSION_COOKIE_NOT_HTTP_ONLY'
+
+  constructor() {
+    super(
+      'The session cookie must be httpOnly: a script able to read it turns any XSS into an account takeover. Remove `cookie.httpOnly: false` from the session config.',
+      { status: 500, code: 'E_SESSION_COOKIE_NOT_HTTP_ONLY' },
+    )
+  }
+}

package/src/session/templateTags.ts

@@ -1,3 +1,5 @@
+import { ReamError } from '../errors/ReamError.js'
+
 /**
  * The flash-message tags AdonisJS's session publishes to templates.
  *
@@ -122,3 +124,58 @@ export function registerSessionTemplateTags(engine: TemplateTagEngine): void {
     },
   })
 }
+
+/** Loads the template engine package. Swappable so a test needs no engine. */
+export type EnginePackageLoader = () => Promise<unknown>
+
+const loadInker: EnginePackageLoader = () => {
+  // Built rather than written inline: inker is an OPTIONAL peer, and a literal
+  // `import('@c9up/inker')` makes a bundler resolve it at build time for an
+  // application that never installed it. Computed, it only runs behind the
+  // `usingInker` flag.
+  const specifier = '@c9up/inker'
+  return import(/* @vite-ignore */ specifier)
+}
+
+function unusable(detail: string): ReamError {
+  return new ReamError(
+    'E_SESSION_TEMPLATE_ENGINE_UNUSABLE',
+    `The template engine is installed but the session tags cannot be registered: ${detail}`,
+    {
+      hint: '`@c9up/inker` must default-export its plugin registrar (`inker.use(plugin)`), whose plugins receive an engine with `registerTag()`.',
+    },
+  )
+}
+
+/**
+ * Publish the session tags into the template engine, the way AdonisJS's
+ * session does with Edge: through the engine package's MODULE SINGLETON
+ * (`inker.use(plugin)`), guarded by the host's `usingInker` flag — never by
+ * resolving a container binding. `use()` queues the plugin, and the engine
+ * runs it before its next render, whenever the engine was built.
+ *
+ * Returns whether the tags were handed over. A registrar or an engine of the
+ * wrong shape is an error, not a skip: a template using `@flashMessage`
+ * would otherwise render it as plain text with no warning.
+ */
+export async function installSessionTemplateTags(
+  usingInker: boolean,
+  load: EnginePackageLoader = loadInker,
+): Promise<boolean> {
+  if (!usingInker) return false
+  const module: unknown = await load()
+  const registrar =
+    typeof module === 'object' && module !== null ? Reflect.get(module, 'default') : undefined
+  const use = Reflect.get(Object(registrar), 'use')
+  if (typeof use !== 'function') throw unusable('its default export has no use()')
+  use.call(registrar, (engine: unknown) => {
+    const register = Reflect.get(Object(engine), 'registerTag')
+    if (typeof register !== 'function') throw unusable('the engine has no registerTag()')
+    registerSessionTemplateTags({
+      registerTag: (tag) => {
+        register.call(engine, tag)
+      },
+    })
+  })
+  return true
+}

package/src/storage/StaticMiddleware.ts

@@ -150,8 +150,11 @@ export class StaticMiddleware {
     const reqPath = ctx.request.path()
 
     // A dotfile under `deny` is answered, not passed on: falling through would
-    // leak its existence through whatever the router answers next.
-    if (this.#dotFiles === 'deny' && this.#hasDotSegment(reqPath)) {
+    // leak its existence through whatever the router answers next. The check
+    // runs on the DECODED path — the name that would be opened — or `/%2eenv`
+    // reaches `.env`. A path that does not decode is checked raw; it is never
+    // served anyway.
+    if (this.#dotFiles === 'deny' && this.#hasDotSegment(decodePath(reqPath) ?? reqPath)) {
       ctx.response.status(403).send('Forbidden')
       return
     }
@@ -335,25 +338,21 @@ export class StaticMiddleware {
       reqPath = reqPath.slice(this.#prefix.length) || '/'
     }
 
-    if (this.#dotFiles === 'ignore' && this.#hasDotSegment(reqPath)) return null
-
-    // The candidates, in upstream's order: the path itself, then the path with
-    // each fallback extension, then the index files for a directory request.
-    //
-    // Percent-decoding happens BEFORE resolution on purpose: `%2e%2e%2f` is
-    // `../` and has to be normalised away by `path.resolve` like any other
-    // traversal, not carried through as an opaque segment. `decodeURIComponent`
-    // THROWS on a malformed sequence (a lone `%`), which would otherwise become
-    // a 500 on a request anyone can send.
-    let decoded: string
-    try {
-      decoded = decodeURIComponent(reqPath)
-    } catch {
-      return null
-    }
+    // Percent-decoding happens BEFORE any check and BEFORE resolution on
+    // purpose: the dot-file policy has to see the name that will be opened
+    // (`%2eenv` is `.env`), and `%2e%2e%2f` is `../`, which has to be
+    // normalised away by `path.resolve` like any other traversal, not carried
+    // through as an opaque segment. A malformed sequence (a lone `%`) is not
+    // servable.
+    const decoded = decodePath(reqPath)
+    if (decoded === null) return null
     // A NUL truncates the path in the syscall layer of some runtimes; Node
     // rejects it, but refusing here keeps the decision in one place.
     if (decoded.includes('\0')) return null
+    if (this.#dotFiles !== 'allow' && this.#hasDotSegment(decoded)) return null
+
+    // The candidates, in upstream's order: the path itself, then the path with
+    // each fallback extension, then the index files for a directory request.
     const relative = decoded.replace(/^\/+/, '')
     const candidates: string[] = []
     if (relative !== '') {
@@ -367,6 +366,8 @@ export class StaticMiddleware {
     }
 
     for (const candidate of candidates) {
+      // A configured index or extension can itself name a dot file.
+      if (this.#dotFiles !== 'allow' && this.#hasDotSegment(candidate)) continue
       const opened = await this.#openInRoot(candidate)
       if (opened) return opened
     }
@@ -426,6 +427,15 @@ export class StaticMiddleware {
   }
 }
 
+/** `decodeURIComponent` that answers `null` instead of throwing on a malformed sequence. */
+function decodePath(reqPath: string): string | null {
+  try {
+    return decodeURIComponent(reqPath)
+  } catch {
+    return null
+  }
+}
+
 /**
  * Static config with the defaults filled in — `@adonisjs/static`'s
  * `defineConfig`, value for value.