@c9up/ream 0.1.33 → 0.2.0

package/src/session/Session.ts

@@ -13,7 +13,16 @@
 import type { SessionRedisClientSource } from './drivers/RedisDriver.js'
 
 export interface SessionDriver {
-  read(sessionId: string): Promise<Record<string, unknown>>
+  /**
+   * The stored session, or `null` when the store has no entry for this id
+   * (AdonisJS `SessionStoreContract.read`).
+   *
+   * `null` and `{}` mean different things: the first is "no session here",
+   * the second "a session that happens to be empty". Without the difference a
+   * cookie whose server-side row has expired looked like a live session, and
+   * `commit()` touched a row that was not there.
+   */
+  read(sessionId: string): Promise<Record<string, unknown> | null>
   write(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<void>
   destroy(sessionId: string): Promise<void>
   touch(sessionId: string, ttl: number): Promise<void>
@@ -51,6 +60,14 @@ export function supportsTagging(driver: SessionDriver): driver is SessionDriverW
   )
 }
 
+/**
+ * The session key the flash bag travels in.
+ *
+ * One constant rather than three literals: the read, the delete and the write
+ * below all have to agree, and they had to agree by hand.
+ */
+const FLASH_KEY = '__flash'
+
 /** Where `flashAll` / `flashOnly` / `flashExcept` put the request input. */
 const FLASH_INPUT_KEY = 'input'
 
@@ -175,9 +192,9 @@ export class Session {
    */
   #hydrate(data: Record<string, unknown>): void {
     this.#data = { ...data }
-    const flash = data.__flash
+    const flash = data[FLASH_KEY]
     this.#previousFlash = isPlainRecord(flash) ? { ...flash } : {}
-    delete this.#data.__flash
+    delete this.#data[FLASH_KEY]
   }
 
   /** Current session id. Mutated by `regenerate()`. */
@@ -437,7 +454,7 @@ export class Session {
   toJSON(): Record<string, unknown> {
     const result = { ...this.#data }
     if (Object.keys(this.#flashData).length > 0) {
-      result.__flash = this.#flashData
+      result[FLASH_KEY] = this.#flashData
     }
     return result
   }
@@ -472,6 +489,51 @@ export class Session {
    * has no read-only session mode, and reporting `true` would tell a caller
    * its writes were dropped when they were not.
    */
+  /**
+   * The options this session was seated with (AdonisJS `config`).
+   *
+   * What `setStore` was told: whether the session is fresh, and how long it
+   * lives. Read-only — changing it after the fact would not move the entry
+   * already written.
+   */
+  get config(): { fresh: boolean; ttl: number } {
+    return { fresh: this.#fresh, ttl: this.#ttl }
+  }
+
+  /**
+   * The key the flash bag is stored under inside the session (AdonisJS
+   * `flashKey`).
+   *
+   * Exposed so a store that has to reason about the payload — a migration, a
+   * debug screen — does not have to hardcode the string.
+   */
+  get flashKey(): string {
+    return FLASH_KEY
+  }
+
+  /**
+   * What has been flashed for the NEXT request (AdonisJS
+   * `responseFlashMessages`).
+   *
+   * A copy: flashing goes through `flash()`, which is where the value checks
+   * live. `flashMessages` is the other half — what the PREVIOUS request left
+   * for this one.
+   */
+  get responseFlashMessages(): Record<string, unknown> {
+    return { ...this.#flashData }
+  }
+
+  /**
+   * Whether `regenerate()` ran this request (AdonisJS `hasRegeneratedSession`).
+   *
+   * The id changed, so anything holding the old one — a cookie already
+   * written, an external store keyed by session id — is stale. It was tracked
+   * internally and never exposed, so only this class could act on it.
+   */
+  get hasRegeneratedSession(): boolean {
+    return this.#regenerated
+  }
+
   get readonly(): boolean {
     return false
   }
@@ -496,7 +558,11 @@ export class Session {
   async initiate(): Promise<void> {
     if (this.#initiated || this.#driver === undefined) return
     this.#initiated = true
-    this.#hydrate(await this.#driver.read(this.#sessionId))
+    const stored = await this.#driver.read(this.#sessionId)
+    // The store is the authority on existence: a cookie can outlive the row it
+    // points at, and that session is fresh however old its id is.
+    if (stored === null) this.#fresh = true
+    this.#hydrate(stored ?? {})
   }
 
   /**

package/src/session/SessionMiddleware.ts

@@ -106,17 +106,25 @@ export default class SessionMiddleware {
     const rolling = this.#config.rolling
     const isProduction = process.env.NODE_ENV === 'production'
 
-    // Read session ID from cookie — pre-parsed by the Rust HyperServer.
-    let sessionId = ctx.request.plainCookie<string>(cookieName, undefined, {
-      encoded: false,
-    })
+    // Read the session cookie — pre-parsed by the Rust HyperServer.
+    //
+    // The COOKIE driver's value is its own AEAD ciphertext, so it is read raw
+    // and the driver authenticates it. The server-side drivers store a bare id,
+    // which is SIGNED on the way out (see the write below): `request.cookie()`
+    // verifies the HMAC and returns null when it does not hold, so a planted or
+    // foreign id is refused here instead of reaching the store.
+    let sessionId = this.#cookieDriver
+      ? ctx.request.plainCookie<string>(cookieName, undefined, { encoded: false })
+      : ctx.request.cookie(cookieName)
     const hadIncomingCookie = sessionId !== null
 
     // Cookie driver: the cookie value IS the session data (encrypted)
     if (this.#cookieDriver) {
       const data = await this.#driver.read(sessionId ?? '')
       sessionId = sessionId ?? generateSessionId()
-      const session = new Session(sessionId, data)
+      // `null` means the cookie carried nothing readable — an empty session,
+      // not an absent one, since for this driver the cookie IS the store.
+      const session = new Session(sessionId, data ?? {})
       // No store to commit to: the cookie written below IS the storage, so the
       // session is seated without one and `commit()` has nothing to do.
       session.setStore(this.#driver, { fresh: !hadIncomingCookie, ttl: maxAge })
@@ -193,10 +201,12 @@ export default class SessionMiddleware {
     // defeats HTTP caching, and leaks a Set-Cookie to CDNs. This mirrors
     // the cookie-driver path above (which already omits `isNew`).
     if (session.isDirty() || regenerated || (rolling && hadIncomingCookie)) {
-      ctx.response.plainCookie(cookieName, session.sessionId, {
-        // An opaque id — packing it would invalidate every session cookie
-        // already in a browser for no gain.
-        encode: false,
+      // SIGNED, as AdonisJS signs it (`response.cookie(cookieName, id, …)`).
+      // The id is 192 bits of entropy, so it was never guessable — what the
+      // signature buys is that a cookie the app did not issue is rejected on
+      // read, before any store lookup, and that an id from another deployment
+      // (a different APP_KEY) cannot be presented here.
+      ctx.response.cookie(cookieName, session.sessionId, {
         maxAge: this.#config.clearWithBrowser ? undefined : maxAge,
         path: '/',
         httpOnly: true,

package/src/session/drivers/CookieDriver.ts

@@ -18,14 +18,14 @@ export class CookieDriver implements SessionDriver {
     this.signer = new CookieSigner(secret)
   }
 
-  async read(sessionId: string): Promise<Record<string, unknown>> {
-    if (!sessionId) return {}
+  async read(sessionId: string): Promise<Record<string, unknown> | null> {
+    if (!sessionId) return null
     const decrypted = this.signer.decrypt(sessionId)
-    if (!decrypted) return {}
+    if (!decrypted) return null
     try {
       return JSON.parse(decrypted)
     } catch {
-      return {}
+      return null
     }
   }
 

package/src/session/drivers/DatabaseDriver.ts

@@ -70,16 +70,16 @@ export class DatabaseDriver implements SessionDriverWithTagging {
     this.#table = table
   }
 
-  async read(sessionId: string): Promise<Record<string, unknown>> {
+  async read(sessionId: string): Promise<Record<string, unknown> | null> {
     const rows = await this.#db.query<{ data: string; expires_at: number | string }>(
       `SELECT data, expires_at FROM ${this.#table} WHERE id = ?`,
       [sessionId],
     )
     const row = rows[0]
-    if (!row) return {}
+    if (!row) return null
     if (Number(row.expires_at) < Date.now()) {
       await this.destroy(sessionId)
-      return {}
+      return null
     }
     return parseData(row.data)
   }

package/src/session/drivers/FileDriver.ts

@@ -36,26 +36,26 @@ export class FileDriver implements SessionDriver {
     return path.join(this.#location, `${name}.json`)
   }
 
-  async read(sessionId: string): Promise<Record<string, unknown>> {
+  async read(sessionId: string): Promise<Record<string, unknown> | null> {
     let raw: string
     try {
       raw = await fs.promises.readFile(this.#pathFor(sessionId), 'utf8')
     } catch {
-      return {}
+      return null
     }
     try {
       const parsed: unknown = JSON.parse(raw)
-      if (typeof parsed !== 'object' || parsed === null) return {}
+      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)
-        return {}
+        return null
       }
       return entry.data ?? {}
     } catch {
       // A truncated or hand-edited file is a session we cannot trust; treat it
       // as absent rather than handing a half-parsed object to the app.
-      return {}
+      return null
     }
   }
 
@@ -76,7 +76,9 @@ export class FileDriver implements SessionDriver {
 
   async touch(sessionId: string, ttl: number): Promise<void> {
     const data = await this.read(sessionId)
-    if (Object.keys(data).length === 0) return
+    // 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)
   }
 }

package/src/session/drivers/MemoryDriver.ts

@@ -29,11 +29,11 @@ export class MemoryDriver implements SessionDriverWithTagging {
     this.#maxEntries = Math.max(1, options.maxEntries ?? DEFAULT_MAX_ENTRIES)
   }
 
-  async read(sessionId: string): Promise<Record<string, unknown>> {
+  async read(sessionId: string): Promise<Record<string, unknown> | null> {
     const entry = this.#store.get(sessionId)
     if (!entry || entry.expiresAt < Date.now()) {
       this.#store.delete(sessionId)
-      return {}
+      return null
     }
     return { ...entry.data }
   }

package/src/session/drivers/RedisDriver.ts

@@ -114,16 +114,16 @@ export class RedisDriver implements SessionDriverWithTagging {
    * A corrupt value would otherwise 500 every request carrying that cookie,
    * with no way for the visitor to recover — a new session is the safe answer.
    */
-  async read(sessionId: string): Promise<Record<string, unknown>> {
+  async read(sessionId: string): Promise<Record<string, unknown> | null> {
     const client = await this.#client()
     const raw = await client.get(this.#key(sessionId))
-    if (raw === null) return {}
+    if (raw === null) return null
 
     try {
       const parsed: unknown = JSON.parse(raw)
-      return isPlainRecord(parsed) ? parsed : {}
+      return isPlainRecord(parsed) ? parsed : null
     } catch {
-      return {}
+      return null
     }
   }
 
@@ -169,7 +169,14 @@ export class RedisDriver implements SessionDriverWithTagging {
         stale.push(id)
         continue
       }
-      sessions.push({ id, data: await this.read(id) })
+      // The EXISTS check above already established the key is there; a null
+      // here means it expired in the gap, and that device is no longer active.
+      const data = await this.read(id)
+      if (data === null) {
+        stale.push(id)
+        continue
+      }
+      sessions.push({ id, data })
     }
     if (stale.length > 0) await client.srem(key, ...stale)
     return sessions

package/tsconfig.app.json

@@ -1,21 +1,21 @@
 {
   "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./tsconfig.base.json",
   "compilerOptions": {
-    "strict": true,
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
     "lib": ["ES2023"],
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-    "skipLibCheck": true,
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
-    "resolveJsonModule": true,
-    "isolatedModules": true,
     "declaration": false,
     "sourceMap": true,
-    "outDir": "./dist"
+    "types": ["node"],
+    // `${configDir}` resolves against the config that EXTENDS this one, not
+    // against this file. Without it every path here pointed inside
+    // `node_modules/@c9up/ream`: an app's build output landed in ream's own
+    // dist, and its node_modules was never excluded.
+    "outDir": "${configDir}/dist"
   },
-  "exclude": ["node_modules", "dist", "build"]
+  "include": ["${configDir}/**/*"],
+  "exclude": [
+    "${configDir}/node_modules",
+    "${configDir}/dist",
+    "${configDir}/build"
+  ]
 }

package/tsconfig.base.json

@@ -0,0 +1,19 @@
+{
+  // Shared by tsconfig.app / tsconfig.package / tsconfig.client. Emit options
+  // (declaration, sourceMap, outDir) belong to the leaf that knows what it is
+  // building — a base that decides them makes every leaf fight it.
+  "compilerOptions": {
+    "strict": true,
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "exclude": ["node_modules", "dist"]
+}

package/tsconfig.client.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    // Browser code is bundled, so resolution follows the bundler rather than
+    // Node, and the DOM libs replace the Node types.
+    "moduleResolution": "Bundler",
+    "module": "ESNext",
+    "lib": ["DOM", "DOM.Iterable", "ES2023"],
+    "types": [],
+    "noEmit": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["${configDir}/**/*"],
+  "exclude": ["${configDir}/node_modules", "${configDir}/dist"]
+}

package/tsconfig.package.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    // A package ships its types, and keeps the doc-comments that document them.
+    "declaration": true,
+    "declarationMap": true,
+    "removeComments": false,
+    "sourceMap": true,
+    "types": ["node"],
+    "outDir": "${configDir}/dist"
+  },
+  "include": ["${configDir}/src/**/*"],
+  "exclude": ["${configDir}/node_modules", "${configDir}/dist"]
+}