@c9up/ream 0.2.27 → 0.2.29

package/src/server/Server.ts

@@ -6,6 +6,7 @@
  * - server.errorHandler(() => import('#exceptions/handler')) — custom exception handler
  */
 
+import { ReamError } from '../errors/ReamError.js'
 import type { ExceptionHandler } from '../http/Exception.js'
 import type { HttpContext } from '../http/HttpContext.js'
 import type { MiddlewareFunction } from '../middleware/Pipeline.js'
@@ -32,28 +33,83 @@ export type MiddlewareClassConstructor = new (...args: never[]) => MiddlewareCla
 /** What server.use() and router.use() accept: lazy imports or direct functions. */
 export type MiddlewareEntry = LazyImport<MiddlewareClassConstructor> | MiddlewareFunction
 
+/** One unary gRPC call, as the native server hands it over. */
+export interface GrpcCall {
+  /** `/package.Service/Method`, as it arrived. */
+  path: string
+  /**
+   * Request metadata: the request headers, every value of a repeated one in
+   * order, names lowercased. Never the client's trailers.
+   */
+  metadata: Record<string, string[]>
+  /** The request message, still encoded. */
+  message: Uint8Array
+  /** Resolved client IP, by the same trusted-proxy rules as `request.ip()`. */
+  ip: string
+  /**
+   * Aborted when the client gives up on the call — resets its stream or
+   * closes the connection — before the handler answered.
+   */
+  signal: AbortSignal
+}
+
+/** A reply message, still encoded — or a gRPC status code instead of one. */
+export type GrpcReply = { message: Uint8Array } | { code: number; details: string }
+
+export type GrpcHandler = (call: GrpcCall) => Promise<GrpcReply>
+
+/**
+ * Message size bounds of the gRPC calls, in bytes; `-1` for none. A request
+ * past its bound is refused, `RESOURCE_EXHAUSTED`, before it is read; a reply
+ * past its bound is answered `RESOURCE_EXHAUSTED` instead.
+ */
+export interface GrpcLimits {
+  /** Default 4 MiB. */
+  maxReceiveMessageLength?: number
+  /** Default `-1`: no bound. */
+  maxSendMessageLength?: number
+}
+
+function checkGrpcLimit(name: string, value: number | undefined): void {
+  if (value === undefined || value === -1 || (Number.isSafeInteger(value) && value >= 0)) return
+  throw new ReamError(
+    'E_SERVER_GRPC_INVALID_LIMIT',
+    `${name} must be a whole number of bytes, or -1 for no limit — got ${value}.`,
+  )
+}
+
 export class Server {
   #router: Router
   #serverMiddleware: MiddlewareFunction[] = []
   #errorHandlerImporter?: LazyImport<ErrorHandlerClass>
   #resolvedErrorHandler?: ExceptionHandler
   #trustedProxies: string[] = []
+  #grpcHandler?: GrpcHandler
+  #grpcLimits: GrpcLimits = {}
 
   constructor(router: Router) {
     this.#router = router
   }
 
   /**
-   * Configure the trusted-proxy CIDR list. The Rust HyperServer uses it to
-   * pre-resolve `request.ip` once per request — JS reads the field, no CIDR
-   * matching in TS.
+   * Configure the trusted proxies. The Rust HyperServer uses them to
+   * pre-resolve `request.ip()` / `request.ips()` once per request — JS reads
+   * the fields, no CIDR matching in TS.
    *
-   * Empty list (default, 2026-05+) is **strict fail-closed**: `X-Forwarded-For`
-   * and `X-Real-IP` are ignored entirely; only the socket peer is used.
-   * Apps deployed behind a reverse proxy must list the proxy's CIDR
-   * (`'10.0.0.0/8'`, `'192.0.2.0/24'`, etc.) or pass the `'*'` sentinel
-   * for permissive mode (accepts spoofing as the explicit trade-off when
-   * proxy CIDRs can't be enumerated).
+   * The chain is the socket peer, then the `X-Forwarded-For` entries read
+   * right to left; it stops at the first hop that is not a trusted proxy, and
+   * its last entry is the client IP. Proxies append what they saw, so the
+   * left-most entry — the one a client writes itself — is only reached when
+   * every hop after it is trusted. `X-Real-IP` is never read.
+   *
+   * Entries: addresses or CIDR ranges, IPv4 or IPv6 (`'10.0.0.0/8'`,
+   * `'fd00::/8'`), IPv4 netmasks (`'10.0.0.0/255.0.0.0'`), the named ranges
+   * `'loopback'`, `'linklocal'`, `'uniquelocal'`, or `'*'` to trust every hop
+   * (the left-most entry wins — any client can choose its IP). An entry that is
+   * none of these makes the server refuse to start.
+   *
+   * Empty list (default) is **strict fail-closed**: `X-Forwarded-For` is
+   * ignored and only the socket peer is used.
    */
   trustedProxies(cidrs: string[]): this {
     this.#trustedProxies = [...cidrs]
@@ -65,6 +121,44 @@ export class Server {
     return this.#trustedProxies
   }
 
+  /**
+   * Serve gRPC on the HTTP port. Once a handler is set, a request whose
+   * content-type is `application/grpc*` is a gRPC call handed to it — ahead
+   * of the router and the middleware, which never see it. The native server
+   * still applies its rate limiter and security filter first. Without a
+   * handler such a request stays an ordinary HTTP request.
+   *
+   * No AdonisJS counterpart: it serves on Node's `http.Server`, where gRPC
+   * would attach a library of its own. Here the native server owns the
+   * socket, so the gRPC branch is part of it, and this is how a package
+   * reaches it — `@c9up/neutrino` registers its dispatcher here.
+   *
+   * One handler per server: a second one throws. Two packages both serving
+   * gRPC is a conflict to resolve, not to settle by load order.
+   */
+  grpc(handler: GrpcHandler, limits: GrpcLimits = {}): this {
+    if (this.#grpcHandler) {
+      throw new ReamError('E_SERVER_GRPC_ALREADY_SET', 'A gRPC handler is already registered.', {
+        hint: 'Only one package can serve gRPC on the HTTP port.',
+      })
+    }
+    checkGrpcLimit('maxReceiveMessageLength', limits.maxReceiveMessageLength)
+    checkGrpcLimit('maxSendMessageLength', limits.maxSendMessageLength)
+    this.#grpcHandler = handler
+    this.#grpcLimits = { ...limits }
+    return this
+  }
+
+  /** The message bounds given with the gRPC handler (consumed by Ignitor at boot). */
+  getGrpcLimits(): GrpcLimits {
+    return { ...this.#grpcLimits }
+  }
+
+  /** The gRPC handler, if one is set (consumed by Ignitor at boot). */
+  getGrpcHandler(): GrpcHandler | undefined {
+    return this.#grpcHandler
+  }
+
   /**
    * Register global server middleware.
    * Accepts lazy imports of middleware classes (AdonisJS pattern):

package/src/server/nativeGrpc.ts

@@ -0,0 +1,59 @@
+/**
+ * The gRPC handler as the native server calls it.
+ *
+ * The native server numbers each call and, separately, reports the numbers
+ * of the calls a client gave up on — a reset stream or a closed connection —
+ * before the handler answered. This turns those reports into the `signal` of
+ * each {@link GrpcCall}, so that a handler can stop the work it started.
+ *
+ * Calls reach JavaScript in increasing id order, but a cancel travels on its
+ * own queue and can arrive before its call: one for an id not seen yet is
+ * kept until that call arrives; one for an id already seen and finished is
+ * dropped.
+ */
+
+import type { GrpcCall, GrpcHandler, GrpcReply } from './Server.js'
+
+/** A call as the native server hands it over: numbered, without a signal. */
+export interface NativeGrpcCall extends Omit<GrpcCall, 'signal'> {
+  id: number
+}
+
+export type NativeGrpcHandler = (call: NativeGrpcCall) => Promise<GrpcReply>
+
+export interface CancellableGrpc {
+  /** Give to the native server's `onGrpc`. */
+  onCall: NativeGrpcHandler
+  /** Give to the native server's `onGrpcCancel`. */
+  onCancel: (id: number) => void
+}
+
+export function cancellableGrpc(handler: GrpcHandler): CancellableGrpc {
+  const running = new Map<number, AbortController>()
+  // Cancels that arrived before their call.
+  const early = new Set<number>()
+  let lastSeen = 0
+
+  return {
+    async onCall({ id, ...call }) {
+      lastSeen = Math.max(lastSeen, id)
+      const controller = new AbortController()
+      for (const cancelled of early) {
+        if (cancelled > id) continue
+        early.delete(cancelled)
+        if (cancelled === id) controller.abort()
+      }
+      running.set(id, controller)
+      try {
+        return await handler({ ...call, signal: controller.signal })
+      } finally {
+        running.delete(id)
+      }
+    },
+    onCancel(id) {
+      const controller = running.get(id)
+      if (controller !== undefined) controller.abort()
+      else if (id > lastSeen) early.add(id)
+    },
+  }
+}

package/src/server/nativeLimits.ts

@@ -0,0 +1,94 @@
+/**
+ * The limits the native server applies at the socket, read from the
+ * application's configuration.
+ *
+ * - Body limits come from `config/bodyparser.ts`: the native server enforces
+ *   each section's `limit` WHILE reading the body, so nothing past it is ever
+ *   buffered. The request still reaches routing, without its body and marked
+ *   `bodyTooLarge`; reading the body then throws the 413 the body parser
+ *   raises. The body parser keeps its own check; the two read one config.
+ * - Timeouts and the connection cap come from `config/app.ts` → `http`, where
+ *   an AdonisJS app sets `headersTimeout`, `requestTimeout` and
+ *   `keepAliveTimeout` for Node's server. `maxConnections` has no AdonisJS
+ *   option (Node's `server.maxConnections` is left unbounded there); it is a
+ *   deliberate DoS bound, and past it new clients wait in the listen backlog.
+ *
+ * Why the body limits are applied natively at all (NAPI constraint): the
+ * native server hands JS a request whose body is already read, where AdonisJS
+ * leaves the body in Node's stream until the parser pulls it. Without a limit
+ * at the read, every body is buffered before any JS-side limit can apply.
+ */
+
+import type { BodyParserConfig } from '../bodyparser/BodyParserMiddleware.js'
+import { parseSize } from '../bodyparser/parseSize.js'
+import { ReamError } from '../errors/ReamError.js'
+
+/** One body-parser section as the native server takes it (bytes). */
+export interface NativeBodyLimit {
+  limit?: number
+  types?: string[]
+}
+
+/** Body limits per body-parser section; an omitted section keeps its default. */
+export interface NativeBodyLimits {
+  json?: NativeBodyLimit
+  form?: NativeBodyLimit
+  raw?: NativeBodyLimit
+  multipart?: NativeBodyLimit
+}
+
+/** Timeouts in milliseconds (`0` disables one) and the connection cap (`0` = unbounded). */
+export interface NativeConnectionConfig {
+  headersTimeout?: number
+  requestTimeout?: number
+  keepAliveTimeout?: number
+  maxConnections?: number
+}
+
+const SECTIONS = ['json', 'form', 'raw', 'multipart'] as const
+
+/** Translate `config/bodyparser.ts` into the native server's body limits. */
+export function nativeBodyLimits(config: BodyParserConfig): NativeBodyLimits {
+  const limits: NativeBodyLimits = {}
+  for (const section of SECTIONS) {
+    const given = config[section]
+    if (!given) continue
+    const native: NativeBodyLimit = {}
+    if (given.limit !== undefined) native.limit = parseSize(given.limit)
+    if (given.types !== undefined) native.types = [...given.types]
+    limits[section] = native
+  }
+  return limits
+}
+
+const CONNECTION_KEYS = [
+  'headersTimeout',
+  'requestTimeout',
+  'keepAliveTimeout',
+  'maxConnections',
+] as const
+
+const MAX_U32 = 2 ** 32 - 1
+
+/**
+ * Pick the connection settings out of the `http` block of `config/app.ts`.
+ * Throws on a value that is not a whole number of milliseconds (or
+ * connections) the native server can hold, rather than letting it wrap.
+ */
+export function nativeConnectionConfig(http: unknown): NativeConnectionConfig {
+  const config: NativeConnectionConfig = {}
+  if (typeof http !== 'object' || http === null) return config
+  for (const key of CONNECTION_KEYS) {
+    const value: unknown = Reflect.get(http, key)
+    if (value === undefined) continue
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > MAX_U32) {
+      throw new ReamError(
+        'E_IGNITOR_INVALID_HTTP_CONFIG',
+        `\`http.${key}\` must be a whole number between 0 and ${MAX_U32}, received ${String(value)}.`,
+        { hint: 'Timeouts are in milliseconds; 0 disables the bound.' },
+      )
+    }
+    config[key] = value
+  }
+  return config
+}

package/src/session/Session.ts

@@ -10,8 +10,13 @@
  * Backed by pluggable drivers (cookie, memory, redis).
  */
 
+import type { CookieOptions } from '../http/Response.js'
 import type { SessionRedisClientSource } from './drivers/RedisDriver.js'
-import { E_SESSION_NOT_READY, E_SESSION_TAGGING_NOT_SUPPORTED } from './errors.js'
+import {
+  E_SESSION_NOT_READY,
+  E_SESSION_STORE_NOT_CONDITIONAL,
+  E_SESSION_TAGGING_NOT_SUPPORTED,
+} from './errors.js'
 import { ReadOnlyValuesStore } from './ReadOnlyValuesStore.js'
 
 export interface SessionDriver {
@@ -26,8 +31,27 @@ export interface SessionDriver {
    */
   read(sessionId: string): Promise<Record<string, unknown> | null>
   write(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<void>
+  /**
+   * Write only over an entry that is still there, in one step; `false` when it
+   * is gone, and nothing written.
+   *
+   * What `commit()` uses for a session that existed when the request came in.
+   * A request still running when the same session was logged out, rotated or
+   * destroyed everywhere would otherwise write its stale copy back — the user
+   * id included — and undo the logout. Upstream writes unconditionally and has
+   * that race; this is the named deviation that closes it.
+   *
+   * Required, and checked when the store is attached: a read followed by a
+   * write leaves the race open between the two calls.
+   */
+  update(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<boolean>
   destroy(sessionId: string): Promise<void>
   touch(sessionId: string, ttl: number): Promise<void>
+  /**
+   * The session lives with the client, not here: nothing on the server can
+   * delete a copy of it. Only the cookie store sets it.
+   */
+  readonly stateless?: boolean
 }
 
 /** One session belonging to a tagged user (AdonisJS `TaggedSession`). */
@@ -131,8 +155,23 @@ export interface SessionConfig {
   client?: SessionRedisClientSource
   /** `redis` driver only — key prefix. Defaults to `ream:session:`. */
   prefix?: string
+  /**
+   * Attributes of the session cookie, for every store. Defaults:
+   * `{ path: '/', httpOnly: true, sameSite: 'lax' }`, and `secure` on when
+   * `NODE_ENV` is production. Its lifetime comes from {@link age} and
+   * {@link clearWithBrowser}, not from here. `httpOnly: false` is refused: a
+   * script able to read the session cookie is what turns an XSS into an
+   * account takeover.
+   */
+  cookie?: SessionCookieOptions
 }
 
+/** The session cookie attributes an application may set. */
+export type SessionCookieOptions = Pick<
+  CookieOptions,
+  'path' | 'httpOnly' | 'secure' | 'sameSite' | 'domain' | 'partitioned' | 'priority'
+>
+
 /**
  * Generate a fresh session ID. Format mirrors AdonisJS / express-session —
  * 32 bytes of base64url entropy (~256 bits). Defined here so `regenerate()`
@@ -179,6 +218,8 @@ export class Session {
   #ttl = 0
   /** Whether {@link initiate} already ran, so a second call is a no-op. */
   #initiated = false
+  /** The entry vanished while this request ran — see {@link wasLost}. */
+  #lost = false
 
   constructor(sessionId: string, data: Record<string, unknown> = {}) {
     this.#sessionId = sessionId
@@ -228,6 +269,15 @@ export class Session {
     return this.#regenerated
   }
 
+  /**
+   * @internal — the stored entry was gone by the time {@link commit} ran: it
+   * was logged out, rotated or destroyed by another request meanwhile. Nothing
+   * was written, and the middleware must not hand the browser this id again.
+   */
+  wasLost(): boolean {
+    return this.#lost
+  }
+
   /** @internal — the id captured at request arrival; used to destroy the old driver entry post-regenerate. */
   originalSessionId(): string {
     return this.#originalSessionId
@@ -554,6 +604,11 @@ export class Session {
    * {@link initiate} / {@link commit} then have nothing to do.
    */
   setStore(driver: SessionDriver, options: { fresh: boolean; ttl: number }): void {
+    // A store written in JavaScript, or against the older contract, reaches
+    // here without the method the type requires.
+    if (typeof Reflect.get(driver, 'update') !== 'function') {
+      throw new E_SESSION_STORE_NOT_CONDITIONAL()
+    }
     this.#driver = driver
     this.#fresh = options.fresh
     this.#ttl = options.ttl
@@ -600,12 +655,27 @@ export class Session {
       return
     }
     if (this.#dirty) {
-      await driver.write(this.#sessionId, this.toJSON(), this.#ttl)
+      if (this.#fresh) {
+        await driver.write(this.#sessionId, this.toJSON(), this.#ttl)
+        return
+      }
+      this.#lost = !(await driver.update(this.#sessionId, this.toJSON(), this.#ttl))
       return
     }
     if (!this.#fresh) await driver.touch(this.#sessionId, this.#ttl)
   }
 
+  /**
+   * Whether ending this session on the server ends every copy of it.
+   *
+   * False under the cookie store, where the session travels with the client:
+   * a logout replaces the cookie in one browser and cannot reach a copy. What
+   * an auth guard reads to refuse signing in on a store it cannot revoke.
+   */
+  get revocable(): boolean {
+    return this.#driver !== undefined && this.#driver.stateless !== true
+  }
+
   /**
    * Whether the store behind this session can tag sessions with a user
    * (AdonisJS `supportsTagging`). False under the cookie and file drivers.

package/src/session/SessionMiddleware.ts

@@ -10,15 +10,17 @@ import { readModuleConfig } from '../config/moduleConfig.js'
 import { currentNodeEnv } from '../env/nodeEnv.js'
 import { durationToSeconds } from '../helpers/duration.js'
 import type { HttpContext } from '../http/HttpContext.js'
+import type { CookieOptions } from '../http/Response.js'
 import type { SessionConfigInput } from './config.js'
 import { CookieDriver } from './drivers/CookieDriver.js'
 import { DatabaseDriver, type SessionDbConnection } from './drivers/DatabaseDriver.js'
 import { FileDriver } from './drivers/FileDriver.js'
 import { MemoryDriver } from './drivers/MemoryDriver.js'
 import { RedisDriver } from './drivers/RedisDriver.js'
+import { E_SESSION_COOKIE_NOT_HTTP_ONLY, E_SESSION_STORE_NOT_CONFIGURED } from './errors.js'
 import { quasarConnection } from './quasar.js'
 import { ReadOnlyValuesStore, type ValuePath } from './ReadOnlyValuesStore.js'
-import type { SessionDriver } from './Session.js'
+import type { SessionCookieOptions, SessionDriver } from './Session.js'
 import { Session } from './Session.js'
 
 interface ResolvedSessionConfig {
@@ -27,6 +29,7 @@ interface ResolvedSessionConfig {
   maxAge: number
   clearWithBrowser: boolean
   rolling: boolean
+  cookie: SessionCookieOptions
 }
 
 /** Duck-typed check for a connection the database store can drive. */
@@ -61,8 +64,15 @@ export default class SessionMiddleware {
     // `{ store: 'redis', stores: { redis: { driver: 'redis' } } }` works.
     const selected = config?.store ?? config?.driver
     const named = selected ? config?.stores?.[selected] : undefined
+    // No implicit store, in any environment — AdonisJS' session config
+    // refuses one without `store` too. The memory store lives in one process
+    // and is bounded: a restart, a second replica, or enough anonymous
+    // requests signs every user out, so it is used only when it is chosen
+    // (`store: 'memory'`).
+    if (!selected) throw new E_SESSION_STORE_NOT_CONFIGURED()
+    if (config?.cookie?.httpOnly === false) throw new E_SESSION_COOKIE_NOT_HTTP_ONLY()
     this.#config = {
-      driver: named?.driver ?? selected ?? 'memory',
+      driver: named?.driver ?? selected,
       cookieName: config?.cookieName ?? 'ream_session',
       // `age` is the AdonisJS key and accepts a duration string.
       maxAge:
@@ -71,6 +81,7 @@ export default class SessionMiddleware {
           : (config?.maxAge ?? 7200),
       clearWithBrowser: config?.clearWithBrowser ?? false,
       rolling: config?.rolling ?? false,
+      cookie: { ...config?.cookie },
     }
 
     if (this.#config.driver === 'cookie') {
@@ -79,7 +90,7 @@ export default class SessionMiddleware {
           'Cookie session driver requires a secret. Set session.secret in your config.',
         )
       }
-      this.#cookieDriver = new CookieDriver(config.secret)
+      this.#cookieDriver = new CookieDriver(config.secret, this.#config.cookieName)
       this.#driver = this.#cookieDriver
     } else if (this.#config.driver === 'memory') {
       this.#driver = new MemoryDriver()
@@ -136,6 +147,9 @@ export default class SessionMiddleware {
 
     // Cookie driver: the cookie value IS the session data (encrypted)
     if (this.#cookieDriver) {
+      // When the data this request carries was last vouched for. See the
+      // re-emission below.
+      const readAt = Date.now()
       const data = await this.#driver.read(sessionId ?? '')
       sessionId = sessionId ?? generateSessionId()
       // `null` means the cookie carried nothing readable — an empty session,
@@ -162,8 +176,20 @@ export default class SessionMiddleware {
       // the cookie maxAge window slides forward (active users don't time out
       // mid-session). Caller opts in via SessionConfig.rolling.
       const shouldEmit = session.isDirty() || (rolling && hadIncomingCookie)
-      if (shouldEmit) {
-        const encoded = this.#cookieDriver.encode(session.toJSON())
+      // The re-emitted cookie lives `maxAge` from when this request READ the
+      // session, not from its response. Counted from the response, a request
+      // that outlasted a logout re-issued the signed-in data with a full new
+      // lifetime — past the window a revocation is kept for, after which the
+      // sign-in it carried was accepted again. Counted from the read, no cookie
+      // carrying a sign-in outlives the logout by more than `maxAge`. A session
+      // regenerated during the request (a login) is new data, so it counts from
+      // now; so does a session that came in with no cookie.
+      const issuedAt = hadIncomingCookie && !session.wasRegenerated() ? readAt : Date.now()
+      const remaining = issuedAt + maxAge * 1000 - Date.now()
+      // Expired while the request ran: nothing to hand back, and the browser
+      // keeps whatever cookie it was given since.
+      if (shouldEmit && remaining > 0) {
+        const encoded = this.#cookieDriver.encode(session.toJSON(), remaining / 1000)
         if (encoded.length > 4096) {
           process.stderr.write(
             `[session] Cookie session exceeds 4096 bytes (${encoded.length}). ` +
@@ -174,11 +200,8 @@ export default class SessionMiddleware {
           // Already encrypted by the cookie driver; packing it again would
           // only make the cookie bigger and change nothing.
           encode: false,
-          maxAge: this.#config.clearWithBrowser ? undefined : maxAge,
-          path: '/',
-          httpOnly: true,
-          sameSite: 'lax',
-          secure: isProduction,
+          ...this.#cookieAttributes(isProduction),
+          maxAge: this.#config.clearWithBrowser ? undefined : Math.ceil(remaining / 1000),
         })
       }
       return
@@ -216,6 +239,10 @@ export default class SessionMiddleware {
     // no server-side row (touch() is a no-op without a backing entry),
     // defeats HTTP caching, and leaks a Set-Cookie to CDNs. This mirrors
     // the cookie-driver path above (which already omits `isNew`).
+    // A session logged out or rotated by another request while this one ran
+    // was not written back (see `Session.wasLost`); handing the browser its id
+    // again would only point it at nothing, over the cookie it got since.
+    if (session.wasLost()) return
     if (session.isDirty() || regenerated || (rolling && hadIncomingCookie)) {
       // SIGNED, as AdonisJS signs it (`response.cookie(cookieName, id, …)`).
       // The id is 192 bits of entropy, so it was never guessable — what the
@@ -223,14 +250,26 @@ export default class SessionMiddleware {
       // 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, {
+        ...this.#cookieAttributes(isProduction),
         maxAge: this.#config.clearWithBrowser ? undefined : maxAge,
-        path: '/',
-        httpOnly: true,
-        sameSite: 'lax',
-        secure: isProduction,
       })
     }
   }
+
+  /**
+   * The session cookie's attributes: the configured `cookie` over the
+   * defaults. `secure` follows the environment unless the config sets it.
+   */
+  #cookieAttributes(isProduction: boolean): CookieOptions {
+    const configured = this.#config.cookie
+    return {
+      path: '/',
+      sameSite: 'lax',
+      ...configured,
+      httpOnly: true,
+      secure: configured.secure ?? isProduction,
+    }
+  }
 }
 
 function generateSessionId(): string {

package/src/session/config.ts

@@ -13,6 +13,7 @@
  *   })
  */
 
+import { E_SESSION_STORE_NOT_CONFIGURED } from './errors.js'
 import type { SessionConfig } from './Session.js'
 
 /** What a session config file may declare. */
@@ -24,6 +25,12 @@ export type SessionConfigInput = SessionConfig & {
   secret?: string
 }
 
+/**
+ * Validate and return a session config. A config without `store` (or its
+ * older spelling `driver`) is refused here, at load time, as AdonisJS'
+ * `defineConfig` refuses it: there is no implicit store.
+ */
 export function defineConfig(config: SessionConfigInput): SessionConfigInput {
+  if (!config.store && !config.driver) throw new E_SESSION_STORE_NOT_CONFIGURED()
   return config
 }

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])
   }