@c9up/ream 0.2.1 → 0.2.3

package/src/env/Secret.ts

@@ -34,8 +34,34 @@ export class Secret<T> {
     return this.#keyword
   }
 
+  /**
+   * Redacted placeholder for implicit coercion.
+   *
+   * `valueOf` is what `+secret` and `secret == 'x'` reach for — without it,
+   * they fall back to the raw value and the secret leaks through arithmetic
+   * and loose comparison.
+   */
+  valueOf(): string {
+    return this.#keyword
+  }
+
+  /** Redacted placeholder for locale-aware string conversion. */
+  toLocaleString(): string {
+    return this.#keyword
+  }
+
   /** Release the underlying value — the one deliberate way to read the secret. */
   release(): T {
     return this.#value
   }
+
+  /**
+   * Transform the wrapped value, keeping it wrapped.
+   *
+   * The point is that the intermediate never escapes: `secret.map(v => v.trim())`
+   * hands back another Secret rather than a bare string that could be logged.
+   */
+  map<R>(transform: (value: T) => R): Secret<R> {
+    return new Secret(transform(this.#value), this.#keyword)
+  }
 }

package/src/errors/aggregate.ts

@@ -0,0 +1,36 @@
+/**
+ * The framework's exceptions, in one bag.
+ *
+ * AdonisJS exposes `import { errors } from '@adonisjs/core'` (and one bag per
+ * module) so an app can branch on `error instanceof errors.E_ROUTE_NOT_FOUND`
+ * without importing each class by name. The flat named exports stay — this is
+ * the shape a migrating app already writes.
+ */
+
+import { EnvValidationException } from '../env/Env.js'
+import {
+  E_FORBIDDEN,
+  E_HTTP_EXCEPTION,
+  E_HTTP_REQUEST_ABORTED,
+  E_ROUTE_NOT_FOUND,
+  E_ROW_NOT_FOUND,
+  E_UNAUTHORIZED,
+  E_VALIDATION_ERROR,
+} from '../http/Exception.js'
+import { E_INSECURE_APP_KEY, E_MISSING_APP_KEY } from '../security/CookieSigner.js'
+import { E_SESSION_NOT_READY, E_SESSION_TAGGING_NOT_SUPPORTED } from '../session/errors.js'
+
+export const errors = {
+  E_FORBIDDEN,
+  E_HTTP_EXCEPTION,
+  E_HTTP_REQUEST_ABORTED,
+  E_INSECURE_APP_KEY,
+  E_INVALID_ENV_VARIABLES: EnvValidationException,
+  E_MISSING_APP_KEY,
+  E_ROUTE_NOT_FOUND,
+  E_ROW_NOT_FOUND,
+  E_SESSION_NOT_READY,
+  E_SESSION_TAGGING_NOT_SUPPORTED,
+  E_UNAUTHORIZED,
+  E_VALIDATION_ERROR,
+} as const

package/src/events/Emitter.ts

@@ -590,17 +590,42 @@ export class Emitter {
  *   emitter.on(TaskDeclared, LogTaskEvent)
  */
 export class BaseEvent {
+  /**
+   * Subclasses declare their own payload parameters; this signature only has
+   * to be wide enough for `dispatch` to forward them (AdonisJS does the same).
+   */
+  constructor(..._args: unknown[]) {}
+
   static eventName?: string
-  private static _emitter: Emitter | undefined
+
+  /**
+   * The emitter events dispatch through. Public, as in AdonisJS: a test swaps
+   * it to capture dispatches without booting a provider.
+   */
+  static emitter: Emitter | undefined
 
   /** @internal Wire the emitter (called by EventsProvider). */
   static useEmitter(emitter: Emitter): void {
-    BaseEvent._emitter = emitter
+    BaseEvent.emitter = emitter
   }
 
   /** @internal Ownership-guarded reset — only clears if `emitter` is still the active one. */
   static resetEmitter(emitter: Emitter): void {
-    if (BaseEvent._emitter === emitter) BaseEvent._emitter = undefined
+    if (BaseEvent.emitter === emitter) BaseEvent.emitter = undefined
+  }
+
+  /**
+   * Construct and dispatch in one call — `OrderShipped.dispatch(order)`.
+   *
+   * The AdonisJS idiom, and the reason `emit()` alone is not enough: an event
+   * is almost always built only to be emitted, and naming the class twice to
+   * do it is what the static removes.
+   */
+  static async dispatch<T extends typeof BaseEvent>(
+    this: T,
+    ...args: ConstructorParameters<T>
+  ): Promise<void> {
+    await new this(...args).emit()
   }
 
   /**
@@ -608,9 +633,9 @@ export class BaseEvent {
    * No-op if no emitter is wired (test/standalone mode).
    */
   async emit(): Promise<void> {
-    if (!BaseEvent._emitter) return
+    if (!BaseEvent.emitter) return
     try {
-      await BaseEvent._emitter.dispatchEvent(this)
+      await BaseEvent.emitter.dispatchEvent(this)
     } catch (err) {
       process.stderr.write(`[events] dispatch error for ${this.constructor.name}: ${err}\n`)
     }

package/src/events/services/main.ts

@@ -9,6 +9,7 @@
  * Populated by `EventsProvider.boot()`.
  */
 
+import { createServiceProxy } from '../../services/createServiceProxy.js'
 import type { Emitter } from '../Emitter.js'
 
 let instance: Emitter | undefined
@@ -23,17 +24,10 @@ export function getEmitter(): Emitter | undefined {
   return instance
 }
 
-const emitter: Emitter = new Proxy({} as Emitter, {
-  get(_target, prop) {
-    if (!instance) {
-      throw new Error(
-        '[ream:events] Emitter singleton accessed before EventsProvider.boot() ran. ' +
-          'Check that `@c9up/ream/events/provider` is listed in your reamrc.ts providers.',
-      )
-    }
-    const value = Reflect.get(instance, prop, instance)
-    return typeof value === 'function' ? value.bind(instance) : value
-  },
-})
+const emitter: Emitter = createServiceProxy<Emitter>(
+  () => instance,
+  '[ream:events] Emitter singleton accessed before EventsProvider.boot() ran. ' +
+    'Check that `@c9up/ream/events/provider` is listed in your reamrc.ts providers.',
+)
 
 export default emitter

package/src/helpers/MessageBuilder.ts

@@ -0,0 +1,69 @@
+/**
+ * Wrap a value with an expiry and a purpose before it is signed or encrypted.
+ *
+ * The signature on a token proves it was issued by this application. It does
+ * NOT prove the token is still valid, nor that it was issued for the job it is
+ * being presented for — a signed password-reset token would otherwise pass as a
+ * signed email-verification token. Those two claims travel inside the payload,
+ * which is why they are added before signing rather than checked after.
+ *
+ * Ported from `@poppinss/utils`; `CookieSigner` and `SignedUrl` sign what this
+ * produces.
+ */
+
+import { milliseconds } from './duration.js'
+
+/** The envelope `build` emits and `verify` reads back. */
+interface Envelope {
+  message: unknown
+  purpose?: string
+  expiryDate?: string
+}
+
+export class MessageBuilder {
+  /**
+   * Serialise `message`, optionally stamped with an expiry and a purpose.
+   *
+   * @param expiresIn - a duration (`'2 hours'`) or a number of milliseconds.
+   */
+  build(message: unknown, expiresIn?: string | number, purpose?: string): string {
+    const envelope: Envelope = { message }
+    if (purpose !== undefined) envelope.purpose = purpose
+    if (expiresIn !== undefined) {
+      envelope.expiryDate = new Date(Date.now() + milliseconds.parse(expiresIn)).toISOString()
+    }
+    return JSON.stringify(envelope)
+  }
+
+  /**
+   * Read an envelope back, or `null` when it is malformed, expired, or was
+   * issued for a different purpose.
+   *
+   * Never throws: every failure is the same `null`, so a caller cannot
+   * accidentally tell "tampered" from "expired" and leak which it was.
+   */
+  verify<T = unknown>(payload: string, purpose?: string): T | null {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(payload)
+    } catch {
+      return null
+    }
+    if (parsed === null || typeof parsed !== 'object') return null
+    if (!('message' in parsed) || parsed.message === undefined) return null
+
+    const envelopePurpose = 'purpose' in parsed ? parsed.purpose : undefined
+    if (envelopePurpose !== purpose) return null
+
+    if ('expiryDate' in parsed && typeof parsed.expiryDate === 'string') {
+      const expiresAt = new Date(parsed.expiryDate)
+      // An unparseable date counts as expired: a token whose expiry cannot be
+      // read is a token whose expiry cannot be enforced.
+      if (Number.isNaN(expiresAt.getTime()) || expiresAt <= new Date()) return null
+    }
+
+    // The caller declares the shape it put in — the same contract as
+    // `session.get<T>()`, over a payload that is untyped by nature.
+    return parsed.message as T
+  }
+}

package/src/helpers/VerificationToken.ts

@@ -0,0 +1,93 @@
+/**
+ * The base class for opaque, single-use tokens — password resets, email
+ * verification, magic links.
+ *
+ * The shape it enforces is the point. The token handed to the user is
+ * `<identifier>.<secret>`, and only the SHA-256 of the secret is stored. A
+ * database leak therefore yields hashes, not usable tokens, and the identifier
+ * travels alongside so verification is one indexed lookup rather than a scan.
+ *
+ * Comparison goes through a constant-time equality: comparing hashes with `===`
+ * leaks their common prefix through timing, which is enough to forge one.
+ *
+ * Ported from `@adonisjs/core/helpers` — subclass it and add the persistence.
+ */
+
+import { createHash } from 'node:crypto'
+import { Secret } from '../env/Secret.js'
+import { base64 } from './base64.js'
+import { seconds } from './duration.js'
+import { safeEqual } from './safeEqual.js'
+import { random } from './string.js'
+
+export abstract class VerificationToken {
+  /** Row identifier, as stored. */
+  declare identifier: string | number | bigint
+  /** Who the token belongs to. */
+  declare tokenableId: string | number | bigint
+  /** SHA-256 of the secret — the only half that is persisted. */
+  declare hash: string
+  /** When the token stops being accepted. */
+  declare expiresAt: Date
+  /** The full token, present only on the instance that just created it. */
+  value?: Secret<string>
+
+  /**
+   * Split a presented token back into its identifier and secret.
+   *
+   * Returns `null` for anything malformed rather than throwing: the input is
+   * attacker-controlled, and every rejection should look the same.
+   */
+  static decode(value: string): { identifier: string; secret: Secret<string> } | null {
+    if (typeof value !== 'string' || value.length === 0) return null
+    const [identifier, ...rest] = value.split('.')
+    if (!identifier || rest.length === 0) return null
+    const decodedIdentifier = base64.urlDecode(identifier)
+    const decodedSecret = base64.urlDecode(rest.join('.'))
+    if (!decodedIdentifier || !decodedSecret) return null
+    return { identifier: decodedIdentifier, secret: new Secret(decodedSecret) }
+  }
+
+  /** A fresh secret and its hash. */
+  static seed(size: number): { secret: Secret<string>; hash: string } {
+    const secret = new Secret(random(size))
+    return {
+      secret,
+      hash: createHash('sha256').update(secret.release()).digest('hex'),
+    }
+  }
+
+  /** A seed plus the owner and an expiry, ready to be persisted. */
+  static createTransientToken(
+    userId: string | number | bigint,
+    size: number,
+    expiresIn: string | number,
+  ): {
+    userId: string | number | bigint
+    expiresAt: Date
+    secret: Secret<string>
+    hash: string
+  } {
+    const expiresAt = new Date()
+    expiresAt.setSeconds(expiresAt.getSeconds() + seconds.parse(expiresIn))
+    return { userId, expiresAt, ...VerificationToken.seed(size) }
+  }
+
+  /** Build the public `<identifier>.<secret>` value, after the row has an id. */
+  protected computeValue(secret: Secret<string>): void {
+    this.value = new Secret(
+      `${base64.urlEncode(String(this.identifier))}.${base64.urlEncode(secret.release())}`,
+    )
+  }
+
+  /** Whether the expiry has passed. */
+  isExpired(): boolean {
+    return this.expiresAt < new Date()
+  }
+
+  /** Whether `secret` hashes to the stored hash, compared in constant time. */
+  verify(secret: Secret<string>): boolean {
+    const candidate = createHash('sha256').update(secret.release()).digest('hex')
+    return safeEqual(this.hash, candidate)
+  }
+}

package/src/helpers/defineStaticProperty.ts

@@ -0,0 +1,51 @@
+/**
+ * Give a subclass its own copy of an inherited static property.
+ *
+ * A static declared on a base class is SHARED: every subclass mutating
+ * `Model.booted` or `Model.$columns` writes into the same object. This walks
+ * that back by defining an own property on the subclass, seeded either from a
+ * fresh value or from a copy of what it inherited.
+ *
+ * Ported from `@poppinss/utils` — the mechanism ORM-style base classes rely on.
+ */
+export function defineStaticProperty<T>(
+  target: object,
+  propertyName: string,
+  options: { initialValue: T; strategy: 'inherit' | 'define' | ((value: T) => T) },
+): void {
+  if (Object.hasOwn(target, propertyName)) return
+
+  const inherited: unknown = Reflect.get(target, propertyName)
+  const { strategy, initialValue } = options
+
+  const value =
+    strategy === 'define' || inherited === undefined
+      ? initialValue
+      : typeof strategy === 'function'
+        ? strategy(inherited as T)
+        : structuredCloneOrCopy(inherited)
+
+  Object.defineProperty(target, propertyName, {
+    value,
+    configurable: true,
+    enumerable: true,
+    writable: true,
+  })
+}
+
+/**
+ * A deep copy where one is possible, a shallow one otherwise.
+ *
+ * `structuredClone` throws on functions and class instances, which a static
+ * bag can legitimately hold — falling back keeps the inherit strategy usable
+ * instead of failing at class-definition time.
+ */
+function structuredCloneOrCopy(value: unknown): unknown {
+  try {
+    return structuredClone(value)
+  } catch {
+    if (Array.isArray(value)) return [...value]
+    if (value !== null && typeof value === 'object') return { ...value }
+    return value
+  }
+}

package/src/helpers/duration.ts

@@ -69,3 +69,78 @@ export function durationToSeconds(value: number | string, label: string): number
   }
   return Math.floor(milliseconds / SECOND)
 }
+
+/**
+ * Format a millisecond duration the way `@poppinss/string` does.
+ *
+ * Short form by default (`'2h'`), long form on request (`'2 hours'`).
+ */
+function formatMs(value: number, long: boolean): string {
+  const table: [number, string][] = long
+    ? [
+        [YEAR, 'year'],
+        [DAY, 'day'],
+        [HOUR, 'hour'],
+        [MINUTE, 'minute'],
+        [SECOND, 'second'],
+        [1, 'millisecond'],
+      ]
+    : [
+        [DAY, 'd'],
+        [HOUR, 'h'],
+        [MINUTE, 'm'],
+        [SECOND, 's'],
+        [1, 'ms'],
+      ]
+  const magnitude = Math.abs(value)
+  for (const [scale, label] of table) {
+    if (magnitude >= scale) {
+      const count = Math.round(value / scale)
+      return long ? `${count} ${label}${Math.abs(count) === 1 ? '' : 's'}` : `${count}${label}`
+    }
+  }
+  return long ? `${value} milliseconds` : `${value}ms`
+}
+
+/** The duration that could not be read, as one message shape for both objects. */
+function parseOrThrow(duration: string | number, unitLabel: string): number {
+  if (typeof duration === 'number') return duration
+  const parsed = parseDurationMs(duration)
+  if (parsed === undefined) {
+    throw new Error(
+      `Cannot read "${duration}" as ${unitLabel}. Use a number, or a duration such as '30m', '2 hours' or '7 days'.`,
+    )
+  }
+  return parsed
+}
+
+/**
+ * `string.milliseconds` — parse and format durations in milliseconds.
+ *
+ * A number passes through untouched, matching `@poppinss/string`.
+ */
+export const milliseconds = {
+  parse(duration: string | number): number {
+    return parseOrThrow(duration, 'milliseconds')
+  },
+  format(value: number, long = false): string {
+    return formatMs(value, long)
+  },
+}
+
+/**
+ * `string.seconds` — the same, in seconds.
+ *
+ * `parse` keeps the AdonisJS quirk its own `durationToSeconds` documents: a
+ * NUMBER is already seconds and passes through, while a unit-less STRING is
+ * milliseconds and gets scaled down.
+ */
+export const seconds = {
+  parse(duration: string | number): number {
+    if (typeof duration === 'number') return duration
+    return parseOrThrow(duration, 'seconds') / SECOND
+  },
+  format(value: number, long = false): string {
+    return formatMs(value * SECOND, long)
+  },
+}

package/src/helpers/fs.ts

@@ -0,0 +1,104 @@
+/**
+ * Recursive directory reads, as `fsReadAll` / `fsImportAll` in AdonisJS.
+ *
+ * What the framework itself uses to discover config files, preloads and
+ * commands, and what an app reaches for to load a directory of modules.
+ */
+
+import type { Dirent } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { join, relative, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+export interface ReadAllFilesOptions {
+  /** Keep only files this returns true for. Defaults to `.js`/`.ts` modules. */
+  filter?: (filePath: string, index: number) => boolean
+  /** Sort the collected paths. Defaults to a stable alphabetical order. */
+  sort?: (current: string, next: string) => number
+  /** Ignore directories whose name this returns true for. */
+  ignoreMissingRoot?: boolean
+  /** Return absolute paths instead of paths relative to the root. */
+  absolute?: boolean
+  /** Also descend into subdirectories. Defaults to true. */
+  recursive?: boolean
+}
+
+const DEFAULT_FILTER = (filePath: string): boolean =>
+  /\.(js|ts|mjs|cjs|mts|cts)$/.test(filePath) && !/\.d\.ts$/.test(filePath)
+
+/**
+ * Every file under `location`, relative to it and alphabetically sorted.
+ *
+ * A missing root throws unless `ignoreMissingRoot` is set — an app that
+ * declares no `config/` directory is legitimate, a typo in the path is not,
+ * and only the caller can tell them apart.
+ */
+export async function fsReadAll(
+  location: string | URL,
+  options: ReadAllFilesOptions = {},
+): Promise<string[]> {
+  const root = location instanceof URL ? location.pathname : location
+  const filter = options.filter ?? DEFAULT_FILTER
+  const recursive = options.recursive ?? true
+
+  let entries: Dirent[]
+  try {
+    entries = await readdir(root, { withFileTypes: true, recursive })
+  } catch (error) {
+    if (options.ignoreMissingRoot && isMissing(error)) return []
+    throw error
+  }
+
+  const files: string[] = []
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    // `parentPath` is where recursive readdir puts the containing directory.
+    const absolute = join(entry.parentPath ?? root, entry.name)
+    const value = options.absolute ? absolute : relative(root, absolute).split(sep).join('/')
+    files.push(value)
+  }
+
+  const kept = files.filter((file, index) => filter(file, index))
+  return options.sort ? kept.sort(options.sort) : kept.sort()
+}
+
+export interface ImportAllFilesOptions extends ReadAllFilesOptions {
+  /** Turn a file path into the key it lands under. Defaults to the path minus its extension. */
+  transformKeys?: (key: string) => string
+}
+
+/**
+ * Import every file under `location`, keyed by its path minus the extension.
+ *
+ * A module with a default export contributes that export; one without
+ * contributes its named exports as a plain object — the same rule the config
+ * loader follows, and for the same reason.
+ */
+export async function fsImportAll(
+  location: string | URL,
+  options: ImportAllFilesOptions = {},
+): Promise<Record<string, unknown>> {
+  const root = location instanceof URL ? location.pathname : location
+  const files = await fsReadAll(root, options)
+  const collected: Record<string, unknown> = {}
+
+  for (const file of files) {
+    const key = (options.transformKeys ?? stripExtension)(file)
+    const module: Record<string, unknown> = await import(pathToFileURL(join(root, file)).href)
+    collected[key] = 'default' in module ? module.default : { ...module }
+  }
+  return collected
+}
+
+function stripExtension(file: string): string {
+  return file.replace(/\.(js|ts|mjs|cjs|mts|cts)$/, '')
+}
+
+function isMissing(error: unknown): boolean {
+  return (
+    error !== null &&
+    typeof error === 'object' &&
+    'code' in error &&
+    (error.code === 'ENOENT' || error.code === 'ENOTDIR')
+  )
+}

package/src/helpers/index.ts

@@ -1,6 +1,14 @@
+export { Secret } from '../env/Secret.js'
 export { base64 } from './base64.js'
+export { defineStaticProperty } from './defineStaticProperty.js'
+export { milliseconds, seconds } from './duration.js'
+export type { ImportAllFilesOptions, ReadAllFilesOptions } from './fs.js'
+export { fsImportAll, fsReadAll } from './fs.js'
 export type * from './is.js'
 export { default as is } from './is.js'
+export { MessageBuilder } from './MessageBuilder.js'
 export { safeEqual } from './safeEqual.js'
+export { safeTiming } from './safeTiming.js'
 export { default as string } from './string.js'
 export type * from './types.js'
+export { VerificationToken } from './VerificationToken.js'

package/src/helpers/safeTiming.ts

@@ -0,0 +1,45 @@
+/**
+ * Run `callback`, never returning before `minimumMs` has elapsed.
+ *
+ * A login that answers in 3ms for an unknown address and 80ms for a known one
+ * tells an attacker which addresses exist, whatever the response body says.
+ * Holding every path to the same floor removes that signal.
+ *
+ * The callback can call `returnEarly()` to opt out — on a path where the timing
+ * carries nothing, waiting is pure latency.
+ */
+export async function safeTiming<T>(
+  minimumMs: number,
+  callback: (timing: { returnEarly(): void }) => Promise<T>,
+): Promise<T> {
+  const startedAt = performance.now()
+  let returnEarly = false
+
+  let result: T | undefined
+  let caught: unknown
+  let threw = false
+  try {
+    result = await callback({
+      returnEarly() {
+        returnEarly = true
+      },
+    })
+  } catch (error) {
+    caught = error
+    threw = true
+  }
+
+  // The floor applies to the failing path too: an error that comes back faster
+  // than a success is the same leak in the other direction.
+  if (!returnEarly) {
+    const remaining = minimumMs - (performance.now() - startedAt)
+    if (remaining > 0) {
+      await new Promise((resolve) => setTimeout(resolve, remaining))
+    }
+  }
+
+  if (threw) throw caught
+  // `result` is assigned whenever the callback returned, and we rethrew above
+  // when it did not.
+  return result as T
+}