@c9up/ream 0.1.31 → 0.1.33

package/src/security/CookieSigner.ts

@@ -1,43 +1,134 @@
 /**
  * Cookie signing and encryption.
  * Uses Rust NAPI via crypto facade when available.
+ *
+ * NAMED DEVIATION — the wire format is NOT AdonisJS's.
+ *
+ * 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.
+ *
+ * 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.
  */
 
 import { createCipheriv, createDecipheriv, createHmac, randomBytes } from 'node:crypto'
 import { hmacSign, hmacVerify } from './crypto.js'
 
+/** Raised when no APP_KEY is configured (AdonisJS `E_MISSING_APP_KEY`). */
+export class E_MISSING_APP_KEY extends Error {
+  readonly code = 'E_MISSING_APP_KEY' as const
+  constructor() {
+    super('Missing APP_KEY. Set it in your environment before encrypting anything.')
+    this.name = 'E_MISSING_APP_KEY'
+  }
+}
+
+/** Raised when the APP_KEY is too short to be worth having. */
+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.')
+    this.name = 'E_INSECURE_APP_KEY'
+  }
+}
+
+/** The envelope carried inside an encrypted or signed value. */
+interface Envelope {
+  /** The payload. */
+  m: string
+  /** Epoch-ms expiry, when one was given. */
+  e?: number
+  /** The purpose it was sealed for, when one was given. */
+  p?: string
+}
+
 export class CookieSigner {
   #secret: string
   #keyBuffer: Buffer
 
   constructor(secret: string) {
+    // Validated as AdonisJS does: an absent or trivially short key is a
+    // 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()
     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())
   }
 
-  sign(value: string): string {
-    const sig = hmacSign(value, this.#secret)
-    return `${value}.${sig}`
+  /**
+   * Wrap a payload with its expiry and purpose.
+   *
+   * `purpose` is what stops a value sealed for one use being replayed into
+   * another — a password-reset token presented as a session cookie fails here
+   * rather than being honoured.
+   */
+  #seal(value: string, expiresIn?: number, purpose?: string): string {
+    const envelope: Envelope = { m: value }
+    if (expiresIn !== undefined) envelope.e = Date.now() + expiresIn
+    if (purpose !== undefined) envelope.p = purpose
+    return JSON.stringify(envelope)
   }
 
-  unsign(signed: string): string | null {
+  /** Unwrap a sealed payload, refusing an expired one or the wrong purpose. */
+  #open(raw: string, purpose?: string): string | null {
+    let envelope: Envelope
+    try {
+      const parsed: unknown = JSON.parse(raw)
+      if (typeof parsed !== 'object' || parsed === null) return null
+      envelope = parsed as Envelope
+    } catch {
+      // Not an envelope — a value sealed before this format existed.
+      return raw
+    }
+    if (typeof envelope.m !== 'string') return raw
+    if (envelope.e !== undefined && envelope.e < Date.now()) return null
+    if ((envelope.p ?? undefined) !== purpose) return null
+    return envelope.m
+  }
+
+  /**
+   * Sign a value (AdonisJS `Encryption.verifier.sign`).
+   *
+   * `expiresIn` is in milliseconds; `purpose` scopes the signature so it cannot
+   * be replayed somewhere else.
+   */
+  sign(value: string, expiresIn?: number, purpose?: string): string {
+    const sealed = Buffer.from(this.#seal(value, expiresIn, purpose)).toString('base64url')
+    const sig = hmacSign(sealed, this.#secret)
+    return `${sealed}.${sig}`
+  }
+
+  /** Verify and unwrap, returning null when tampered, expired, or mis-purposed. */
+  unsign(signed: string, purpose?: string): string | null {
     const lastDot = signed.lastIndexOf('.')
     if (lastDot === -1) return null
-    const value = signed.slice(0, lastDot)
+    const sealed = signed.slice(0, lastDot)
     const sig = signed.slice(lastDot + 1)
-    return hmacVerify(value, sig, this.#secret) ? value : null
+    if (!hmacVerify(sealed, sig, this.#secret)) return null
+    try {
+      return this.#open(Buffer.from(sealed, 'base64url').toString('utf8'), purpose)
+    } catch {
+      return null
+    }
   }
 
-  encrypt(value: string): string {
+  encrypt(value: string, expiresIn?: number, purpose?: string): string {
     const iv = randomBytes(12)
     const cipher = createCipheriv('aes-256-gcm', this.#keyBuffer, iv)
-    const encrypted = Buffer.concat([cipher.update(value, 'utf8'), cipher.final()])
+    const sealed = this.#seal(value, expiresIn, purpose)
+    const encrypted = Buffer.concat([cipher.update(sealed, 'utf8'), cipher.final()])
     const tag = cipher.getAuthTag()
     return `${iv.toString('base64url')}.${encrypted.toString('base64url')}.${tag.toString('base64url')}`
   }
 
-  decrypt(encrypted: string): string | null {
+  decrypt(encrypted: string, purpose?: string): string | null {
     const parts = encrypted.split('.')
     if (parts.length !== 3) return null
     try {
@@ -46,7 +137,8 @@ export class CookieSigner {
       const tag = Buffer.from(parts[2], 'base64url')
       const decipher = createDecipheriv('aes-256-gcm', this.#keyBuffer, iv)
       decipher.setAuthTag(tag)
-      return Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8')
+      const raw = Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8')
+      return this.#open(raw, purpose)
     } catch {
       return null
     }

package/src/server/Server.ts

@@ -23,11 +23,11 @@ export interface MiddlewareClass {
 /** Lazy import returning a module with a default export. */
 export type LazyImport<T> = () => Promise<{ default: T }>
 
-// biome-ignore lint/suspicious/noExplicitAny: contravariance — same as ControllerAction
-export type ErrorHandlerClass = new (...args: any[]) => ExceptionHandler
+// `never[]` accepts every constructor shape: parameters are contravariant, so a
+// rest of `never` is assignable from any concrete list. No `any` needed.
+export type ErrorHandlerClass = new (...args: never[]) => ExceptionHandler
 
-// biome-ignore lint/suspicious/noExplicitAny: contravariance — middleware class constructors
-type MiddlewareClassConstructor = new (...args: any[]) => MiddlewareClass
+export type MiddlewareClassConstructor = new (...args: never[]) => MiddlewareClass
 
 /** What server.use() and router.use() accept: lazy imports or direct functions. */
 export type MiddlewareEntry = LazyImport<MiddlewareClassConstructor> | MiddlewareFunction
@@ -130,6 +130,18 @@ export function resolveMiddlewareEntry(entry: MiddlewareEntry): MiddlewareFuncti
   return async (ctx: HttpContext, next: () => Promise<void>) => {
     if (!cachedClass) {
       const mod = await lazyImport()
+      if (mod === null || typeof mod !== 'object' || !('default' in mod)) {
+        // The zero-arity ambiguity, reported where it can be acted on: a bound
+        // or rest-args middleware lands here because it declares no parameters
+        // and was read as an import factory.
+        throw new Error(
+          '[E_MIDDLEWARE_ENTRY] A middleware entry with no declared parameters was treated as a lazy import, ' +
+            'but it did not resolve to a module with a default export. ' +
+            'If this is an inline middleware (e.g. `handle.bind(this)` or `(...args) => …`), register it on the ' +
+            'route or group — `router.get(...).use(fn)` — rather than in `router.use([...])`, which takes ' +
+            'imports of middleware classes, as AdonisJS does.',
+        )
+      }
       cachedClass = mod.default
     }
     const instance = ctx.containerResolver
@@ -169,18 +181,26 @@ export function resolveParametrizedMiddlewareEntry(
   }
 }
 
-/** Check if an entry is a direct middleware function (not a lazy import). */
+/**
+ * Whether an entry is a middleware to run, rather than a module to import.
+ *
+ * The two are separated by WHERE they are registered, exactly as in AdonisJS:
+ * `router.use([...])` takes imports of middleware classes (its own `use()`
+ * runs `moduleImporter(one, 'handle')` over every entry), while an inline
+ * function goes on a route or group. So this only has to cope with the entries
+ * that reach it, and a zero-arity function is an import factory.
+ *
+ * A middleware that lost its parameters — `handle.bind(this)`, `(...args) =>`
+ * — still lands here looking like a factory, which is why the resolver below
+ * raises a named error instead of failing somewhere deeper.
+ */
 function isMiddlewareFunction(entry: MiddlewareEntry): entry is MiddlewareFunction {
-  // A lazy import factory returns a promise (dynamic import). Middleware functions don't.
-  // We check: if calling it with no args returns a thenable, it's a lazy import.
-  // Better heuristic: lazy imports are () => import(...) which have .length === 0
-  // and middleware functions have .length >= 2 (ctx, next).
-  // Edge case: arrow with defaults has length 1. But lazy import() always has length 0.
   if (typeof entry !== 'function') return false
-  // Functions with 2+ params are definitely middleware
-  if (entry.length >= 2) return true
-  // Functions with 0 params are likely lazy imports
-  if (entry.length === 0) return false
-  // 1 param is ambiguous — treat as middleware (ctx only, no next)
-  return true
+  // A declared parameter means a middleware: `(ctx)`, `(ctx, next)`.
+  if (entry.length > 0) return true
+  // Zero declared parameters: an import factory. `router.use()` only takes
+  // those, so this is not a guess about which kind an entry is — a closure
+  // that reaches here was registered in the wrong place, and the resolver
+  // says so rather than running it as a module.
+  return false
 }

package/src/session/ReadOnlyValuesStore.ts

@@ -0,0 +1,52 @@
+/**
+ * A read-only bag of values addressed by key or key PATH, shared with templates.
+ *
+ * This is the shape AdonisJS shares as `session` and `flashMessages`, and the
+ * shape its `@error` / `@errors` / `@inputError` tags read — `has(['errorsBag',
+ * field])` and `get('inputErrorsBag', {})`. A migrated template relies on it, so
+ * the path semantics have to match: a dotted string and an array address the
+ * same nested value.
+ */
+
+/** A key, a dotted key path, or the same path already split. */
+export type ValuePath = string | readonly string[]
+
+function segments(path: ValuePath): string[] {
+  return Array.isArray(path) ? [...path] : String(path).split('.')
+}
+
+export class ReadOnlyValuesStore {
+  readonly #values: Record<string, unknown>
+
+  constructor(values: Record<string, unknown> | null) {
+    this.#values = values ?? {}
+  }
+
+  /** True when the bag holds nothing — `@if(flashMessages.isEmpty)`. */
+  get isEmpty(): boolean {
+    return Object.keys(this.#values).length === 0
+  }
+
+  /** Every value, as a shallow copy so a template cannot mutate the store. */
+  all(): Record<string, unknown> {
+    return { ...this.#values }
+  }
+
+  /** The value at `path`, or `defaultValue` when any segment is missing. */
+  get(path: ValuePath, defaultValue?: unknown): unknown {
+    let current: unknown = this.#values
+    for (const key of segments(path)) {
+      if (current === null || typeof current !== 'object') return defaultValue
+      // `Reflect.get` rather than indexing: a flashed key named `__proto__`
+      // must read an OWN property, never walk the prototype chain.
+      if (!Object.hasOwn(current, key)) return defaultValue
+      current = Reflect.get(current, key)
+    }
+    return current === undefined ? defaultValue : current
+  }
+
+  /** Whether `path` resolves to something other than `undefined`. */
+  has(path: ValuePath): boolean {
+    return this.get(path) !== undefined
+  }
+}