@c9up/ream 0.2.8 → 0.2.10

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.
     //

package/src/testing/ApiResponse.ts

@@ -270,7 +270,7 @@ const responseGetters = new Map<string, (this: ApiResponse, res: ApiResponse) =>
  * `headers()`, `text()` — and `body()` returns the content-type-parsed body,
  * exactly like helix. `json()` is kept as an additive convenience.
  */
-// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: the merged interface (StatusAssertions) types the status-shortcut asserts attached to the prototype from STATUS_ASSERTIONS — the same generated-method pattern as EonSchema/Macroable (AdonisJS parity); every member is implemented, so the merge is safe.
+// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: the StatusAssertions interface below types the status shortcuts attached to the prototype from STATUS_ASSERTIONS — every member is implemented, so the merge is safe.
 export class ApiResponse {
   readonly #raw: TestResponse
   readonly #method: string
@@ -659,7 +659,6 @@ export type StatusAssertions<T> = {
 }
 
 // Merge the generated status-shortcut methods into the ApiResponse type.
-// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: the merged interface (StatusAssertions) types the status-shortcut asserts attached to the prototype from STATUS_ASSERTIONS — the same generated-method pattern as EonSchema/Macroable (AdonisJS parity); every member is implemented, so the merge is safe.
 export interface ApiResponse extends StatusAssertions<ApiResponse> {}
 
 /** Apply registered macros/getters onto a freshly built response. */

package/src/testing/RequestBuilder.ts

@@ -174,7 +174,7 @@ const requestSerializers = new Map<
   (data: unknown) => { body: Buffer; contentType: string }
 >()
 
-// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: the merged interface (StatusAssertions) types the status-shortcut asserts attached from STATUS_ASSERTIONS at load — the same generated-method pattern as EonSchema/Macroable (AdonisJS parity); every member is implemented, so the merge is safe.
+// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: the StatusAssertions interface below types the status shortcuts attached from STATUS_ASSERTIONS at load — every member is implemented, so the merge is safe.
 export class RequestBuilder {
   #sender: HttpSender
   #method: HttpMethod
@@ -761,7 +761,6 @@ export class RequestBuilder {
 }
 
 /** The status-shortcut assertions (lazy) are typed onto the builder. */
-// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: the merged interface (StatusAssertions) types the status-shortcut asserts attached from STATUS_ASSERTIONS at load — the same generated-method pattern as EonSchema/Macroable (AdonisJS parity); every member is implemented, so the merge is safe.
 export interface RequestBuilder extends StatusAssertions<RequestBuilder> {}
 
 // Attach the lazy status-shortcut assertions from the shared map so the builder

package/src/utils/Macroable.ts

@@ -27,6 +27,7 @@ export type MacroFn = (...args: unknown[]) => unknown
 /** A getter implementation — declare `this` in your callback to type the receiver. */
 export type GetterFn = () => unknown
 
+// biome-ignore lint/complexity/noStaticOnlyClass: eight classes extend this one to inherit macro()/getter(); it is a base class, not a namespace.
 export class Macroable {
   /**
    * Attach a method to every instance of THIS class (AdonisJS `macro`).