@c9up/ream 0.2.9 → 0.2.11

package/src/scheduler/ScheduleProvider.ts

@@ -24,8 +24,9 @@ import { getServiceRegistry } from '../decorators/Service.js'
 import { ReamError } from '../errors/ReamError.js'
 import type { AppContext } from '../Provider.js'
 import { Provider } from '../Provider.js'
+import type { SchedulerConfig } from './config.js'
 import { getScheduleMetadata } from './Schedule.js'
-import { Scheduler } from './Scheduler.js'
+import { Scheduler, type SchedulerOptions } from './Scheduler.js'
 
 export interface ScheduleProviderOptions {
   /**
@@ -40,12 +41,14 @@ let activeProvider: ScheduleProvider | undefined
 
 export class ScheduleProvider extends Provider {
   readonly scheduler: Scheduler
-  #booted = false
+  /** Task names already registered, so a second pass adds only what is new. */
+  readonly #known = new Set<string>()
   #registered = false
 
   constructor(app: AppContext, options: ScheduleProviderOptions = {}) {
     super(app)
-    this.scheduler = options.scheduler ?? new Scheduler()
+    this.scheduler =
+      options.scheduler ?? new Scheduler(schedulerOptionsFrom(app.config.get('scheduler')))
   }
 
   /**
@@ -82,8 +85,44 @@ export class ScheduleProvider extends Provider {
     this.#registered = true
   }
 
+  /**
+   * Discovery runs at START, not at boot, and that is the whole point.
+   *
+   * `app/modules/**` is auto-loaded during the start phase — after every
+   * provider has booted. A `@Service()` carrying `@Schedule` there, which is
+   * where one naturally lives, was therefore registered into the service
+   * registry AFTER this had already read it. The task was never registered,
+   * and nothing said so: no error, no warning, the application started
+   * normally and the task simply never fired.
+   *
+   * Reading the registry once the modules are in place is what fixes it. A
+   * service declared anywhere earlier — a provider, a preload — is in the
+   * registry by then too, so nothing is lost by waiting.
+   */
   override async boot(): Promise<void> {
-    if (this.#booted) return
+    // Anything already in the registry — declared by a provider, or imported
+    // by one. The rest is caught at start().
+    this.#discover()
+  }
+
+  override async start(): Promise<void> {
+    this.#discover()
+    if (activeProvider !== undefined && activeProvider !== this) {
+      // A previous app's scheduler is still running — stop it before this one
+      // starts, otherwise every @Schedule task fires twice per tick.
+      activeProvider.scheduler.stop()
+    }
+    activeProvider = this
+    this.scheduler.start()
+  }
+
+  /**
+   * Walk the service registry and register every `@Schedule` it declares.
+   *
+   * Idempotent: a second call registers nothing twice, so an application that
+   * restarts its Ignitor does not end up firing everything in duplicate.
+   */
+  #discover(): void {
     const registry = getServiceRegistry()
     const registered: string[] = []
 
@@ -118,6 +157,8 @@ export class ScheduleProvider extends Provider {
           }
 
           const taskName = `${target.name}.${methodName}`
+          // Registered on an earlier pass: skip rather than fire it twice.
+          if (this.#known.has(taskName)) continue
           try {
             this.scheduler.register(taskName, cronExpr, async () => {
               // Resolve from the container on every fire so transient
@@ -133,6 +174,7 @@ export class ScheduleProvider extends Provider {
               await (method as (...args: unknown[]) => unknown).call(instance)
             })
             registered.push(taskName)
+            this.#known.add(taskName)
           } catch (cause) {
             const inner = cause as ReamError & { message?: string; hint?: string }
             throw new ReamError(
@@ -146,7 +188,6 @@ export class ScheduleProvider extends Provider {
           }
         }
       }
-      this.#booted = true
     } catch (err) {
       // Roll back any partial registrations so a retry does not hit
       // DUPLICATE_TASK and the scheduler is never half-initialized.
@@ -162,16 +203,6 @@ export class ScheduleProvider extends Provider {
     }
   }
 
-  override async start(): Promise<void> {
-    if (activeProvider !== undefined && activeProvider !== this) {
-      // A previous app's scheduler is still running — stop it before this one starts,
-      // otherwise every @Schedule task fires twice per tick.
-      activeProvider.scheduler.stop()
-    }
-    activeProvider = this
-    this.scheduler.start()
-  }
-
   override async shutdown(): Promise<void> {
     if (activeProvider === this) activeProvider = undefined
     this.scheduler.stop()
@@ -180,3 +211,22 @@ export class ScheduleProvider extends Provider {
 
 // Default export so reamrc's provider loader can `() => import('@c9up/ream/<feature>/provider')` (resolves to { default }), matching events/rpc. Named export above stays.
 export default ScheduleProvider
+
+/**
+ * Turn `config/scheduler.ts` into the options the `Scheduler` takes.
+ *
+ * The lock is built here rather than in the config file because that file is
+ * read before the application boots — a Redis connection named in it does not
+ * exist yet, so the helpers hand back a factory and this calls it.
+ */
+function schedulerOptionsFrom(config: SchedulerConfig | undefined): SchedulerOptions {
+  if (config === undefined) return {}
+  const options: SchedulerOptions = {}
+  if (config.lock !== undefined) {
+    options.lockBackend = typeof config.lock === 'function' ? config.lock() : config.lock
+  }
+  if (config.defaultLockTtlMs !== undefined) {
+    options.defaultLockTtlMs = config.defaultLockTtlMs
+  }
+  return options
+}

package/src/scheduler/config.ts

@@ -0,0 +1,34 @@
+/**
+ * Author-time config for `config/scheduler.ts`.
+ *
+ *   import { defineConfig, locks } from '@c9up/ream/scheduler/config'
+ *
+ *   export default defineConfig({
+ *     lock: locks.redis({ connection: 'main' }),
+ *   })
+ */
+
+import type { LockBackend } from './locks/LockBackend.js'
+import type { LockBackendFactory } from './locks/locks.js'
+
+export interface SchedulerConfig {
+  /**
+   * The lock consulted before a task fires, so that only one instance runs
+   * it. Takes a backend, or a factory answering one — which is what the
+   * `locks.*` helpers return, so a config file can name a Redis lock before
+   * the connection exists.
+   *
+   * Left out, the scheduler locks nothing: every instance runs every task.
+   * Correct on one instance, and a duplicate run per replica past that.
+   */
+  lock?: LockBackend | LockBackendFactory
+  /** How long a lease is held before it expires on its own. Default 60 000. */
+  defaultLockTtlMs?: number
+}
+
+export function defineConfig(config: SchedulerConfig): SchedulerConfig {
+  return config
+}
+
+export type { LockBackend } from './locks/LockBackend.js'
+export { type LockBackendFactory, locks } from './locks/locks.js'

package/src/scheduler/index.ts

@@ -1,5 +1,13 @@
+export type { SchedulerConfig } from './config.js'
+export { defineConfig as defineSchedulerConfig } from './config.js'
 export type { LockBackend } from './locks/LockBackend.js'
+export { type LockBackendFactory, locks } from './locks/locks.js'
 export { MemoryLockBackend } from './locks/MemoryLockBackend.js'
+export {
+  type LockRedisClient,
+  type LockRedisResolver,
+  RedisLockBackend,
+} from './locks/RedisLockBackend.js'
 export type { ErrorReporter } from './observability/ErrorReporter.js'
 export type {
   ScheduleEvent,

package/src/scheduler/locks/LockBackend.ts

@@ -3,13 +3,18 @@
  *
  * The scheduler consults a `LockBackend` immediately before firing a
  * registered task so that in multi-instance deployments only one
- * instance runs a given task on each tick. Redis, database
- * advisory-lock, and other backends live in user-land — this module
- * ships only the interface and a single-process `MemoryLockBackend`.
+ * instance runs a given task on each tick.
+ *
+ * Two backends ship with it: `MemoryLockBackend`, correct while the
+ * application runs in one process, and `RedisLockBackend`, which is
+ * what a second replica needs — see `locks` for the factories a
+ * config file names.
  *
  * @implements Story 28.3
  */
 
+import { ReamError } from '../../errors/ReamError.js'
+
 export interface LockBackend {
   /**
    * Attempt to acquire an exclusive lock on `name` for up to `ttlMs`
@@ -36,3 +41,21 @@ export interface LockBackend {
    */
   release(name: string): Promise<void>
 }
+
+/**
+ * Reject a TTL that cannot bound anything. A zero or negative lease
+ * expires the instant it is taken, so every instance would acquire the
+ * same lock and run the same task — the exact outcome locking exists to
+ * prevent, arriving silently.
+ */
+export function assertValidTtl(ttlMs: number): void {
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+    throw new ReamError(
+      'SCHEDULE_INVALID_LOCK_TTL',
+      `Lock TTL must be a finite positive number, got ${ttlMs}`,
+      {
+        hint: 'Use a millisecond value greater than zero (typical range 1_000 - 600_000).',
+      },
+    )
+  }
+}

package/src/scheduler/locks/MemoryLockBackend.ts

@@ -1,11 +1,10 @@
 /**
  * Default single-process lock backend backed by a `Map`.
  *
- * Correct for apps that run in a single Node.js process. For
- * horizontally-scaled deployments, implement `LockBackend` against a
- * shared store (Redis `SET NX PX`, Postgres advisory locks, etc.) —
- * those drivers live in user-land per the project's "agnostic per
- * package" rule.
+ * Correct for apps that run in a single Node.js process, and only
+ * those: two processes each keep their own map, so both acquire the
+ * same name and both run the task. Reach for `RedisLockBackend` the
+ * moment a second replica exists.
  *
  * Expiry is evaluated **lazily** at `acquire` time — no background
  * timer, no `setInterval`. This preserves Story 28.1's
@@ -20,23 +19,10 @@
  * @implements Story 28.3
  */
 
-import { ReamError } from '../../errors/ReamError.js'
-import type { LockBackend } from './LockBackend.js'
+import { assertValidTtl, type LockBackend } from './LockBackend.js'
 
 const SWEEP_THRESHOLD = 256
 
-function assertValidTtl(ttlMs: number): void {
-  if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
-    throw new ReamError(
-      'SCHEDULE_INVALID_LOCK_TTL',
-      `Lock TTL must be a finite positive number, got ${ttlMs}`,
-      {
-        hint: 'Use a millisecond value greater than zero (typical range 1_000 – 600_000).',
-      },
-    )
-  }
-}
-
 export class MemoryLockBackend implements LockBackend {
   #locks = new Map<string, number>()
 

package/src/scheduler/locks/RedisLockBackend.ts

@@ -0,0 +1,114 @@
+/**
+ * Redis lock backend — the one a second replica needs.
+ *
+ * Without a shared lock, every instance of an application runs every
+ * scheduled task on every tick: a nightly invoice run goes out N times,
+ * a reminder email arrives N times, and nothing in the logs says so.
+ * `MemoryLockBackend` does not close that gap — each process keeps its
+ * own map — and the scheduler locks nothing at all by default.
+ *
+ * No import of a Redis package. The client is taken structurally — `set`
+ * and `eval` — so this works against a `@c9up/quasar` connection without
+ * ream depending on quasar, which is an optional peer.
+ */
+
+import { randomUUID } from 'node:crypto'
+import { assertValidTtl, type LockBackend } from './LockBackend.js'
+
+/** The commands this issues. Any client answering them will do. */
+export interface LockRedisClient {
+  /** `SET key value PX <ttl> NX` — answers null when the key already exists. */
+  set(key: string, value: string, ...args: unknown[]): Promise<unknown>
+  /** `EVAL script numKeys ...` — used for the compare-and-delete release. */
+  eval(script: string, numKeys: number, ...args: unknown[]): Promise<unknown>
+}
+
+/**
+ * How the backend gets its client: the client itself, or something that
+ * answers with one.
+ *
+ * The resolver form is what a config file needs. `config/scheduler.ts` is
+ * read before the application boots, so the connection does not exist yet
+ * and cannot be awaited there — a function defers the lookup to the first
+ * task that fires.
+ */
+export type LockRedisResolver = LockRedisClient | (() => LockRedisClient | Promise<LockRedisClient>)
+
+export interface RedisLockBackendOptions {
+  /** Key prefix. Default `"ream:schedule:lock:"`. */
+  prefix?: string
+}
+
+/**
+ * Release only a lease we still hold.
+ *
+ * A plain `DEL` is the classic way to break this: a task that outlives its
+ * TTL loses the lock, another instance acquires it and starts running, and
+ * the first one then deletes THAT instance's lease on its way out — leaving
+ * the name free while a task is still running under it. Comparing the token
+ * before deleting makes the release a no-op once the lease is no longer ours.
+ */
+const RELEASE = `
+if redis.call('get', KEYS[1]) == ARGV[1] then
+  return redis.call('del', KEYS[1])
+end
+return 0
+`
+
+export class RedisLockBackend implements LockBackend {
+  readonly #source: LockRedisResolver
+  readonly #prefix: string
+  #resolved: Promise<LockRedisClient> | undefined
+  /** Our token per held name, so a release can prove the lease is ours. */
+  readonly #tokens = new Map<string, string>()
+
+  constructor(client: LockRedisResolver, options: RedisLockBackendOptions = {}) {
+    this.#source = client
+    this.#prefix = options.prefix ?? 'ream:schedule:lock:'
+  }
+
+  /** The client, resolved once and kept. */
+  #client(): Promise<LockRedisClient> {
+    if (!this.#resolved) {
+      this.#resolved = Promise.resolve(
+        typeof this.#source === 'function' ? this.#source() : this.#source,
+      )
+    }
+    return this.#resolved
+  }
+
+  #key(name: string): string {
+    return `${this.#prefix}${name}`
+  }
+
+  /**
+   * `SET key token PX ttl NX` — one round trip, atomic on the server, which
+   * is what makes the decision the same for every instance asking at once.
+   *
+   * The TTL is what recovers the lock after a crash: an instance that dies
+   * holding it never releases, and the lease simply expires.
+   */
+  async acquire(name: string, ttlMs: number): Promise<boolean> {
+    assertValidTtl(ttlMs)
+    const client = await this.#client()
+    const token = randomUUID()
+    // Redis takes an integer number of milliseconds; a fractional TTL is a
+    // protocol error, not a rounding detail.
+    const result = await client.set(this.#key(name), token, 'PX', Math.ceil(ttlMs), 'NX')
+    if (result === null || result === undefined) return false
+    this.#tokens.set(name, token)
+    return true
+  }
+
+  /**
+   * Idempotent, as the contract requires: releasing a name this instance
+   * never acquired — or one whose lease has since expired — does nothing.
+   */
+  async release(name: string): Promise<void> {
+    const token = this.#tokens.get(name)
+    if (token === undefined) return
+    this.#tokens.delete(name)
+    const client = await this.#client()
+    await client.eval(RELEASE, 1, this.#key(name), token)
+  }
+}

package/src/scheduler/locks/locks.ts

@@ -0,0 +1,49 @@
+/**
+ * The lock backends a scheduler config names.
+ *
+ *   // config/scheduler.ts
+ *   import { defineConfig, locks } from '@c9up/ream'
+ *
+ *   export default defineConfig({
+ *     lock: locks.redis({ connection: 'main' }),
+ *   })
+ *
+ * Without a lock the scheduler runs every task on every instance, which is
+ * correct while there is one, and duplicates every run once there are two.
+ *
+ * Factories are lazy: the backend is built when the scheduler is, so naming
+ * a Redis lock in a config that runs single-instance costs nothing until it
+ * is selected.
+ */
+
+import type { LockBackend } from './LockBackend.js'
+import { MemoryLockBackend } from './MemoryLockBackend.js'
+import { quasarConnection } from './quasar.js'
+import { type LockRedisResolver, RedisLockBackend } from './RedisLockBackend.js'
+
+/** A lock backend, built on first use. */
+export type LockBackendFactory = () => LockBackend
+
+export const locks = {
+  /**
+   * In this process's memory. Two processes each keep their own, so this
+   * bounds nothing across replicas — it is for a single-process deployment
+   * and for tests.
+   */
+  memory(): LockBackendFactory {
+    return () => new MemoryLockBackend()
+  },
+
+  /**
+   * Redis. `connection` takes a client, a function answering one, or the
+   * NAME of a `@c9up/quasar` connection — the last of which is resolved at
+   * runtime without ream importing quasar, which stays an optional peer.
+   */
+  redis(options: { connection: LockRedisResolver | string; prefix?: string }): LockBackendFactory {
+    const client: LockRedisResolver =
+      typeof options.connection === 'string'
+        ? quasarConnection(options.connection)
+        : options.connection
+    return () => new RedisLockBackend(client, { prefix: options.prefix })
+  },
+}

package/src/scheduler/locks/quasar.ts

@@ -0,0 +1,67 @@
+/**
+ * Resolving a Redis connection by name, from `@c9up/quasar`.
+ *
+ * Ream does not depend on quasar: it is an optional peer, and this module
+ * never imports it statically. The specifier is built at runtime so the
+ * TypeScript build stays free of it too — a hard type import would make
+ * ream unbuildable for anyone scheduling on a single instance.
+ *
+ * Same bridge the session store uses, for the same reason.
+ */
+
+import type { LockRedisClient } from './RedisLockBackend.js'
+
+/** The slice of quasar's manager this needs: a connection, by name. */
+interface ConnectionSource {
+  connection(name?: string): unknown
+}
+
+function isConnectionSource(value: unknown): value is ConnectionSource {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof Reflect.get(value, 'connection') === 'function'
+  )
+}
+
+/**
+ * The commands the backend issues, checked before use: a connection missing
+ * one would fail on the first task that fires, far from the cause.
+ */
+function isLockRedisClient(value: unknown): value is LockRedisClient {
+  if (typeof value !== 'object' || value === null) return false
+  return ['set', 'eval'].every((name) => typeof Reflect.get(value, name) === 'function')
+}
+
+/**
+ * A resolver for `locks.redis({ connection })` — quasar is loaded when the
+ * first task fires, not while the config file is read.
+ */
+export function quasarConnection(name?: string): () => Promise<LockRedisClient> {
+  return async () => {
+    const specifier = '@c9up/quasar/services/main'
+    let loaded: unknown
+    try {
+      loaded = await import(/* @vite-ignore */ specifier)
+    } catch (cause) {
+      throw new Error(
+        `Ream: the scheduler lock asks for the '${name ?? 'default'}' quasar connection, but @c9up/quasar is not installed.\n` +
+          '  pnpm add @c9up/quasar',
+        { cause },
+      )
+    }
+
+    const manager = isConnectionSource(loaded) ? loaded : Reflect.get(Object(loaded), 'default')
+    if (!isConnectionSource(manager)) {
+      throw new Error('Ream: @c9up/quasar/services/main did not expose a connection() manager')
+    }
+
+    const connection = manager.connection(name)
+    if (!isLockRedisClient(connection)) {
+      throw new Error(
+        `Ream: quasar connection '${name ?? 'default'}' does not carry the commands a scheduler lock needs`,
+      )
+    }
+    return connection
+  }
+}

package/src/security/CookieSigner.ts

@@ -2,19 +2,22 @@
  * Cookie signing and encryption.
  * Uses Rust NAPI via crypto facade when available.
  *
- * NAMED DEVIATION — the wire format is NOT AdonisJS's.
+ * The cipher is `aes-256-gcm`, where authentication is part of the cipher
+ * rather than a second primitive bolted on: encrypt-then-MAC assembled by hand
+ * is a well-known source of subtle breaks.
  *
- * AdonisJS encrypts with `aes-256-cbc` and appends its own HMAC
- * (`base64url(payload).base64url(iv).hmac`). Ream uses `aes-256-gcm`, where
- * authentication is part of the cipher rather than a second primitive bolted on
- * — encrypt-then-MAC assembled by hand is a well-known source of subtle breaks,
- * and there is no reason to reproduce it.
+ * That is upstream's own current choice, not a divergence from it — v7 ships
+ * AES-256-GCM, ChaCha20-Poly1305 and AES-SIV as first-class drivers, and its
+ * documented example configures `aes256gcm` as the default. The CBC + HMAC
+ * construction lives on there under the name `legacy`, described in its own
+ * source as maintaining compatibility with the OLD v6 format.
  *
- * The consequence, stated plainly: a cookie encrypted by an AdonisJS app cannot
- * be decrypted here. Migrating an app invalidates the encrypted cookies already
- * in users' browsers — they are signed out once, at deploy. Everything the app
- * CALLS (`encrypt` / `decrypt` / `sign` / `unsign`, with purpose and expiry)
- * behaves the same.
+ * The consequence, stated plainly: a cookie encrypted by a v6-era application
+ * cannot be decrypted here — those users are signed out once, at deploy. The
+ * same is true of upstream v7 unless the legacy driver is configured. Should
+ * that migration path ever be wanted, the answer is the one taken there: an
+ * additional, explicitly named legacy reader — never a downgrade of the
+ * default.
  */
 
 import { createCipheriv, createDecipheriv, createHmac, randomBytes } from 'node:crypto'
@@ -29,15 +32,29 @@ export class E_MISSING_APP_KEY extends Error {
   }
 }
 
-/** Raised when the APP_KEY is too short to be worth having. */
+/** Raised when the APP_KEY is too short, or is a value everyone already has. */
 export class E_INSECURE_APP_KEY extends Error {
   readonly code = 'E_INSECURE_APP_KEY' as const
-  constructor() {
-    super('APP_KEY is too short — it must be at least 16 characters.')
+  constructor(reason = 'it must be at least 16 characters') {
+    super(`APP_KEY is not usable — ${reason}.`)
     this.name = 'E_INSECURE_APP_KEY'
   }
 }
 
+/**
+ * Keys that appear in scaffolding, documentation and tutorials.
+ *
+ * A key anyone can read is not a secret: with it, cookies, sessions, CSRF
+ * tokens and signed URLs can all be forged. Refusing them costs a developer
+ * one `ream generate:key` and costs an attacker everything.
+ */
+const PUBLICLY_KNOWN_KEYS = new Set([
+  'change-me-to-a-unique-32+-byte-secret!!',
+  'change-me',
+  'your-app-key-here',
+  'secret',
+])
+
 /** The envelope carried inside an encrypted or signed value. */
 interface Envelope {
   /**
@@ -61,6 +78,11 @@ export class CookieSigner {
     // configuration error, not something to discover at decrypt time.
     if (typeof secret !== 'string' || secret.length === 0) throw new E_MISSING_APP_KEY()
     if (secret.length < 16) throw new E_INSECURE_APP_KEY()
+    if (PUBLICLY_KNOWN_KEYS.has(secret.trim().toLowerCase())) {
+      throw new E_INSECURE_APP_KEY(
+        'it is a placeholder from the scaffolding, which everyone can read. Run `ream generate:key`',
+      )
+    }
     this.#secret = secret
     // Derive a 32-byte key for AES-256-GCM via HKDF-like derivation
     this.#keyBuffer = Buffer.from(createHmac('sha256', secret).update('cookie-key').digest())

package/src/services/encryption.ts

@@ -14,8 +14,18 @@ import { createServiceProxy } from './createServiceProxy.js'
 
 let instance: CookieSigner | undefined
 
-/** @internal Set the signer (called by Ignitor once APP_KEY is validated). */
-export function setEncryption(signer: CookieSigner): void {
+/**
+ * @internal Set the signer, or clear it with `undefined`.
+ *
+ * Called by the Ignitor for EVERY boot, key or no key. Leaving a previous
+ * application's signer in place when this one has none is the dangerous
+ * reading: `import encryption from '.../services/encryption'` would answer
+ * with a key this application never configured, and sign its cookies with it.
+ * Last boot owns the locator — the same rule as `setApp` / `setRouter` /
+ * `setServer` beside it. A process running two applications at once should
+ * resolve `'encryption'` from its own container, which is per-application.
+ */
+export function setEncryption(signer: CookieSigner | undefined): void {
   instance = signer
 }
 

package/src/session/Session.ts

@@ -78,16 +78,17 @@ const INTENDED_URL_KEY = '__intended_url'
 
 export interface SessionConfig {
   /**
-   * Which store to use. AdonisJS names this key `store`; `driver` is ream's
-   * older spelling and both are accepted, so a migrated `config/session.ts`
-   * runs with its imports rewritten and nothing else.
+   * Which store to use — a key of {@link stores}, or a driver name on its own.
+   * Read from the environment in the generated config, so a deployment picks
+   * its backend without editing a file.
    */
-  driver?: string
-  /** AdonisJS spelling of {@link driver}. */
   store?: string
+  /** Ream's older spelling of {@link store}. Both are accepted; `store` wins. */
+  driver?: string
   /**
-   * Named stores, AdonisJS-style: `{ store: 'redis', stores: { redis: … } }`.
-   * The selected entry supplies the driver name and its options.
+   * The stores this application can use, by name:
+   * `{ store: 'redis', stores: { redis: … } }`. The selected entry supplies the
+   * driver name and its options.
    */
   stores?: Record<string, { driver: string } & Record<string, unknown>>
   /** `file` driver only — the directory session files are written to. */

package/src/session/SessionMiddleware.ts

@@ -6,6 +6,7 @@
  */
 
 import { randomBytes } from 'node:crypto'
+import { currentNodeEnv } from '../env/nodeEnv.js'
 import { durationToSeconds } from '../helpers/duration.js'
 import type { HttpContext } from '../http/HttpContext.js'
 import { CookieDriver } from './drivers/CookieDriver.js'
@@ -104,7 +105,9 @@ export default class SessionMiddleware {
     const cookieName = this.#config.cookieName
     const maxAge = this.#config.maxAge
     const rolling = this.#config.rolling
-    const isProduction = process.env.NODE_ENV === 'production'
+    // Normalised: `NODE_ENV=prod` reaching here as "not production" ships
+    // the session cookie without Secure, over plain HTTP.
+    const isProduction = currentNodeEnv() === 'production'
 
     // Read the session cookie — pre-parsed by the Rust HyperServer.
     //