@c9up/ream 0.1.3

package/src/scheduler/locks/MemoryLockBackend.ts

@@ -0,0 +1,85 @@
+/**
+ * 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.
+ *
+ * Expiry is evaluated **lazily** at `acquire` time — no background
+ * timer, no `setInterval`. This preserves Story 28.1's
+ * Rust-ticker-only philosophy: the only timers in the scheduler live
+ * in the Rust Tokio runtime.
+ *
+ * An opportunistic sweep runs at most once per `acquire` call to
+ * cap unbounded growth: when the map exceeds `SWEEP_THRESHOLD`
+ * entries, expired entries are pruned in O(N) without blocking
+ * the normal path.
+ *
+ * @implements Story 28.3
+ */
+
+import { ReamError } from '../../errors/ReamError.js'
+import 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>()
+
+  async acquire(name: string, ttlMs: number): Promise<boolean> {
+    assertValidTtl(ttlMs)
+    const now = Date.now()
+
+    // Opportunistic sweep: when the map grows past the threshold,
+    // drop expired entries. Bounded by the current map size, runs at
+    // most once per acquire, never schedules async work.
+    if (this.#locks.size >= SWEEP_THRESHOLD) {
+      for (const [key, expiry] of this.#locks) {
+        if (expiry <= now) this.#locks.delete(key)
+      }
+    }
+
+    const existing = this.#locks.get(name)
+    if (existing !== undefined && existing > now) {
+      return false
+    }
+    this.#locks.set(name, now + ttlMs)
+    return true
+  }
+
+  async release(name: string): Promise<void> {
+    this.#locks.delete(name)
+  }
+
+  /**
+   * @internal Test-only helper: force an entry into the map with an
+   * arbitrary expiry. Used to simulate a crashed holder whose lock
+   * has already expired without advancing `Date.now()`. Not part of
+   * the public {@link LockBackend} contract — never call from
+   * production code.
+   */
+  __setExpiryForTesting(name: string, expiryMs: number): void {
+    this.#locks.set(name, expiryMs)
+  }
+
+  /** @internal Test-only helper — return the current map size. */
+  __sizeForTesting(): number {
+    return this.#locks.size
+  }
+}
+
+export default MemoryLockBackend

package/src/scheduler/observability/ErrorReporter.ts

@@ -0,0 +1,13 @@
+/**
+ * Callback invoked when a scheduled task throws. Typically bridges
+ * to `ErrorBoundary.serviceError` — but the scheduler does not
+ * import `ErrorBoundary` directly; the user wires the adapter
+ * per the "agnostic per package" rule.
+ *
+ * The scheduler wraps the call in its own `try/catch`, so an
+ * `ErrorReporter` that itself throws cannot crash the Rust ticker.
+ *
+ * @implements Story 28.4
+ */
+
+export type ErrorReporter = (err: unknown, context: { taskName: string }) => void

package/src/scheduler/observability/ScheduleEvent.ts

@@ -0,0 +1,61 @@
+/**
+ * Discriminated union of events emitted by the scheduler's task
+ * invocation wrapper.
+ *
+ * All payloads are JSON-serializable so downstream sinks (the event bus,
+ * structured logs, metrics backends) can forward them without
+ * touching live `Error` instances.
+ *
+ * @implements Story 28.4
+ */
+
+export interface ScheduleTaskStartedEvent {
+  type: 'schedule.task.started'
+  taskName: string
+  /** ms-epoch instant the Rust ticker chose for this fire. */
+  scheduledForMs: number
+  /** ms-epoch at which the JS wrapper began running the user callback. */
+  startedAtMs: number
+}
+
+export interface ScheduleTaskCompletedEvent {
+  type: 'schedule.task.completed'
+  taskName: string
+  /** Wall-clock milliseconds spent running the callback. */
+  durationMs: number
+}
+
+export interface ScheduleTaskFailedEvent {
+  type: 'schedule.task.failed'
+  taskName: string
+  /** Plain-object projection of the thrown error (no live `Error`). */
+  error: { name: string; message: string; stack?: string }
+  /** Wall-clock milliseconds until the throw. */
+  durationMs: number
+}
+
+export interface ScheduleTaskSkippedEvent {
+  type: 'schedule.task.skipped'
+  taskName: string
+  /** Reason this tick did not execute the task body.
+   *  - `'locked'` — distributed-lock backend reported the slot as
+   *    already held by another instance.
+   *  - `'acquire-failed'` — the lock backend itself threw/rejected
+   *    (e.g. Redis connection drop); the scheduler treats the tick
+   *    as skipped for observability rather than silently dropping.
+   *  - `'already-running'` — an in-process invocation of the same
+   *    task is already in flight (ticker + concurrent `runTaskNow`,
+   *    or two simultaneous `runTaskNow` calls). The duplicate is
+   *    dropped to prevent double-execution of non-idempotent tasks.
+   *
+   *  Left open for future reasons (e.g. `'paused'`). Consumers that
+   *  branch on `reason` should handle unknown values defensively
+   *  (log + treat as skip) so adding a new variant is non-breaking. */
+  reason: 'locked' | 'acquire-failed' | 'already-running'
+}
+
+export type ScheduleEvent =
+  | ScheduleTaskStartedEvent
+  | ScheduleTaskCompletedEvent
+  | ScheduleTaskFailedEvent
+  | ScheduleTaskSkippedEvent

package/src/scheduler/observability/ScheduleEventSink.ts

@@ -0,0 +1,21 @@
+/**
+ * Destination for scheduler task-invocation events.
+ *
+ * This interface is intentionally minimal so users can adapt to any
+ * event bus (the bus, a raw `EventEmitter`, a structured logger). The
+ * scheduler does NOT import the event bus directly — writing the
+ * bridge is the user's responsibility per the project's "agnostic
+ * per package" rule.
+ *
+ * The scheduler treats `emit` as fire-and-forget: it does not await
+ * the return value, and any sync throw is caught at the call site so
+ * a buggy adapter cannot crash the Rust ticker.
+ *
+ * @implements Story 28.4
+ */
+
+import type { ScheduleEvent } from './ScheduleEvent.js'
+
+export interface ScheduleEventSink {
+  emit(event: ScheduleEvent): void | Promise<void>
+}

package/src/scheduler/observability/StatsTracker.ts

@@ -0,0 +1,134 @@
+/**
+ * Per-task run statistics. Populated by the scheduler's invocation
+ * wrapper and surfaced via `Scheduler.getStats(taskName)`.
+ *
+ * `nextRunMs` is NOT tracked here — it is read live from the Rust
+ * NAPI layer every time `Scheduler.getStats` is called. This tracker
+ * only owns counters that accumulate over time.
+ *
+ * @implements Story 28.4
+ */
+
+export interface TaskStats {
+  /** ms-epoch of the most recent fire that the wrapper STARTED (lock-skipped fires do not update this). `null` if never started. */
+  lastRunMs: number | null
+  /** ms-epoch of the next scheduled fire as reported by the Rust core. `null` when the task is unknown or the core returns null. */
+  nextRunMs: number | null
+  /** Total terminal invocations: completed + failed + skipped. */
+  runCount: number
+  /** Completed (callback resolved without throwing). */
+  successCount: number
+  /** Failed (callback threw / rejected). */
+  errorCount: number
+  /** Skipped (lock backend reported the task already held by another instance). */
+  skippedCount: number
+  /**
+   * Rolling average wall-clock duration over completed + failed
+   * runs (skipped runs have no duration and are excluded). `0`
+   * until at least one duration has been recorded.
+   */
+  avgDurationMs: number
+}
+
+interface InternalStats {
+  lastRunMs: number | null
+  runCount: number
+  successCount: number
+  errorCount: number
+  skippedCount: number
+  totalDurationMs: number
+  durationRunCount: number
+}
+
+function zeroInternal(): InternalStats {
+  return {
+    lastRunMs: null,
+    runCount: 0,
+    successCount: 0,
+    errorCount: 0,
+    skippedCount: 0,
+    totalDurationMs: 0,
+    durationRunCount: 0,
+  }
+}
+
+/**
+ * O(1) in-memory counter map — one entry per task name seen. Never
+ * grows beyond the number of distinct task names the scheduler has
+ * seen; no per-run history retained.
+ */
+export class StatsTracker {
+  #stats = new Map<string, InternalStats>()
+
+  #ensure(name: string): InternalStats {
+    let s = this.#stats.get(name)
+    if (!s) {
+      s = zeroInternal()
+      this.#stats.set(name, s)
+    }
+    return s
+  }
+
+  recordStarted(name: string, startedAtMs: number): void {
+    this.#ensure(name).lastRunMs = startedAtMs
+  }
+
+  recordCompleted(name: string, durationMs: number): void {
+    const s = this.#ensure(name)
+    s.runCount++
+    s.successCount++
+    // Guard against non-finite durations — a caller bug passing NaN or
+    // Infinity would permanently poison the rolling average. Still
+    // count the run; only skip the duration accumulation.
+    if (Number.isFinite(durationMs)) {
+      s.totalDurationMs += durationMs
+      s.durationRunCount++
+    }
+  }
+
+  recordFailed(name: string, durationMs: number): void {
+    const s = this.#ensure(name)
+    s.runCount++
+    s.errorCount++
+    if (Number.isFinite(durationMs)) {
+      s.totalDurationMs += durationMs
+      s.durationRunCount++
+    }
+  }
+
+  recordSkipped(name: string): void {
+    const s = this.#ensure(name)
+    s.runCount++
+    s.skippedCount++
+  }
+
+  /**
+   * Return a defensive snapshot. Unknown tasks yield a zeroed
+   * snapshot with `null` timestamps. `nextRunMs` is always `null`
+   * here — the caller (`Scheduler.getStats`) overlays the live
+   * value from the NAPI layer.
+   */
+  get(name: string): TaskStats {
+    const s = this.#stats.get(name)
+    if (!s) {
+      return {
+        lastRunMs: null,
+        nextRunMs: null,
+        runCount: 0,
+        successCount: 0,
+        errorCount: 0,
+        skippedCount: 0,
+        avgDurationMs: 0,
+      }
+    }
+    return {
+      lastRunMs: s.lastRunMs,
+      nextRunMs: null,
+      runCount: s.runCount,
+      successCount: s.successCount,
+      errorCount: s.errorCount,
+      skippedCount: s.skippedCount,
+      avgDurationMs: s.durationRunCount > 0 ? s.totalDurationMs / s.durationRunCount : 0,
+    }
+  }
+}

package/src/security/CookieSigner.ts

@@ -0,0 +1,54 @@
+/**
+ * Cookie signing and encryption.
+ * Uses Rust NAPI via crypto facade when available.
+ */
+
+import { createCipheriv, createDecipheriv, createHmac, randomBytes } from 'node:crypto'
+import { hmacSign, hmacVerify } from './crypto.js'
+
+export class CookieSigner {
+  #secret: string
+  #keyBuffer: Buffer
+
+  constructor(secret: string) {
+    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}`
+  }
+
+  unsign(signed: string): string | null {
+    const lastDot = signed.lastIndexOf('.')
+    if (lastDot === -1) return null
+    const value = signed.slice(0, lastDot)
+    const sig = signed.slice(lastDot + 1)
+    return hmacVerify(value, sig, this.#secret) ? value : null
+  }
+
+  encrypt(value: 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 tag = cipher.getAuthTag()
+    return `${iv.toString('base64url')}.${encrypted.toString('base64url')}.${tag.toString('base64url')}`
+  }
+
+  decrypt(encrypted: string): string | null {
+    const parts = encrypted.split('.')
+    if (parts.length !== 3) return null
+    try {
+      const iv = Buffer.from(parts[0], 'base64url')
+      const data = Buffer.from(parts[1], 'base64url')
+      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')
+    } catch {
+      return null
+    }
+  }
+}

package/src/security/SignedUrl.ts

@@ -0,0 +1,71 @@
+/**
+ * Signed URLs — HMAC-SHA256 with expiration.
+ * Uses Rust NAPI via crypto facade when available.
+ */
+
+import { constantTimeEq, hmacSign } from './crypto.js'
+
+export interface SignedUrlConfig {
+  secret: string
+}
+
+export class SignedUrl {
+  #secret: string
+
+  constructor(config: SignedUrlConfig) {
+    this.#secret = config.secret
+  }
+
+  make(path: string, options?: { expiresIn?: string | number; purpose?: string }): string {
+    const url = new URL(path, 'http://localhost')
+    // Audit 2026-05-22: `expiresIn !== undefined` instead of truthy check.
+    // `expiresIn: 0` previously fell through the falsy branch and produced
+    // an URL with no `expires` param — a never-expiring signed URL when the
+    // caller explicitly asked for "expires immediately". The new check
+    // honours 0 (and any other numeric input) by stamping the expires param;
+    // verify() then rejects it as soon as the wall clock advances.
+    if (options?.expiresIn !== undefined) {
+      url.searchParams.set(
+        'expires',
+        String(Math.floor(Date.now() / 1000) + parseExpiry(options.expiresIn)),
+      )
+    }
+    if (options?.purpose) {
+      url.searchParams.set('purpose', options.purpose)
+    }
+    url.searchParams.set('signature', hmacSign(url.pathname + url.search, this.#secret))
+    return url.pathname + url.search
+  }
+
+  verify(urlString: string, purpose?: string): boolean {
+    const url = new URL(urlString, 'http://localhost')
+    const providedSig = url.searchParams.get('signature')
+    if (!providedSig) return false
+    const expires = url.searchParams.get('expires')
+    if (expires && Math.floor(Date.now() / 1000) > parseInt(expires, 10)) return false
+    if (purpose && url.searchParams.get('purpose') !== purpose) return false
+
+    url.searchParams.delete('signature')
+    const expectedSig = hmacSign(url.pathname + url.search, this.#secret)
+    return constantTimeEq(providedSig, expectedSig)
+  }
+}
+
+function parseExpiry(value: string | number): number {
+  if (typeof value === 'number') return value
+  const match = value.match(/^(\d+)(s|m|h|d)$/)
+  if (!match) return 3600
+  const num = parseInt(match[1], 10)
+  switch (match[2]) {
+    case 's':
+      return num
+    case 'm':
+      return num * 60
+    case 'h':
+      return num * 3600
+    case 'd':
+      return num * 86400
+    default:
+      return 3600
+  }
+}

package/src/security/crypto.ts

@@ -0,0 +1,98 @@
+/**
+ * Crypto facade — resolves Rust NAPI bindings at load time.
+ * If the binary isn't available, falls back to Node.js crypto.
+ *
+ * Usage:
+ *   import { hmacSign, hmacVerify, randomHex, constantTimeEq } from './crypto.js'
+ */
+
+import { createHmac, randomBytes as nodeRandomBytes, timingSafeEqual } from 'node:crypto'
+
+interface NapiCrypto {
+  hmacSign(data: string, secret: string): string
+  hmacVerify(data: string, signature: string, secret: string): boolean
+  randomBytesBase64(len: number): string
+  randomHex(len: number): string
+  constantTimeEq(a: string, b: string): boolean
+}
+
+let napi: NapiCrypto | null = null
+
+try {
+  // Optional pre-install path: a NAPI loader may set `globalThis.__reamNapi`
+  // before this module loads. We validate the shape rather than declare a
+  // global `var`, so the loader contract stays runtime-only.
+  const preinstalled = readPreinstalledNapi()
+  if (preinstalled) napi = preinstalled
+} catch {
+  /* binary not available */
+}
+
+/** @internal Set the NAPI bindings (called once by the NAPI loader). */
+export function setNapi(bindings: NapiCrypto): void {
+  napi = bindings
+}
+
+/** Check if Rust NAPI crypto is available. */
+export function hasNativeCrypto(): boolean {
+  return napi !== null
+}
+
+// ─── Exports ────────────────────────────────────────────────
+
+export function hmacSign(data: string, secret: string): string {
+  if (napi) return napi.hmacSign(data, secret)
+  return createHmac('sha256', secret).update(data).digest('base64url')
+}
+
+export function hmacVerify(data: string, signature: string, secret: string): boolean {
+  if (napi) return napi.hmacVerify(data, signature, secret)
+  const expected = createHmac('sha256', secret).update(data).digest('base64url')
+  const a = Buffer.from(signature)
+  const b = Buffer.from(expected)
+  if (a.length !== b.length) return false
+  return timingSafeEqual(a, b)
+}
+
+export function randomBytesBase64(len: number): string {
+  if (napi) return napi.randomBytesBase64(len)
+  return nodeRandomBytes(len).toString('base64url')
+}
+
+export function randomHex(len: number): string {
+  if (napi) return napi.randomHex(len)
+  return nodeRandomBytes(len).toString('hex')
+}
+
+export function constantTimeEq(a: string, b: string): boolean {
+  if (napi) return napi.constantTimeEq(a, b)
+  const bufA = Buffer.from(a)
+  const bufB = Buffer.from(b)
+  if (bufA.length !== bufB.length) return false
+  return timingSafeEqual(bufA, bufB)
+}
+
+function readPreinstalledNapi(): NapiCrypto | null {
+  // `globalThis` is typed without an index signature, so we go through Reflect
+  // and validate the shape downstream — no global `var` declaration needed.
+  const candidate: unknown = Reflect.get(globalThis, '__reamNapi')
+  return isNapiCrypto(candidate) ? candidate : null
+}
+
+function isNapiCrypto(value: unknown): value is NapiCrypto {
+  if (typeof value !== 'object' || value === null) return false
+  return (
+    hasFn(value, 'hmacSign') &&
+    hasFn(value, 'hmacVerify') &&
+    hasFn(value, 'randomBytesBase64') &&
+    hasFn(value, 'randomHex') &&
+    hasFn(value, 'constantTimeEq')
+  )
+}
+
+function hasFn<K extends string>(
+  value: object,
+  key: K,
+): value is Record<K, (...args: unknown[]) => unknown> {
+  return key in value && typeof Reflect.get(value, key) === 'function'
+}

package/src/server/HyperServer.ts

@@ -0,0 +1,121 @@
+import type { HttpKernelRequest, HttpKernelResponse } from '../HttpKernel.js'
+import { loadNapi } from '../helpers/napi-loader.js'
+
+/**
+ * Wire-level shield configuration handed off to the Rust filter at boot.
+ * Each flag toggles one rule on/off; they all default to true on the Rust
+ * side, so omitting `configureShield()` entirely leaves the server with no
+ * filter installed.
+ */
+export interface RustShieldConfig {
+  pathTraversal: boolean
+  paramPollution: boolean
+}
+
+export interface RustRateLimitConfig {
+  max: number
+  windowSecs: number
+}
+
+export interface HyperServerLike {
+  onRequest(callback: (request: HttpKernelRequest) => Promise<HttpKernelResponse>): void
+  configureShield(config: RustShieldConfig): void
+  configureTrustedProxies(cidrs: string[]): void
+  configureRateLimit(config: RustRateLimitConfig | null): void
+  listen(): Promise<void>
+  port(): Promise<number>
+  close(): Promise<void>
+  /**
+   * Reserve a streaming-response slot. The handler must call this and
+   * pass the returned id back inside `HttpKernelResponse.streamId`
+   * BEFORE returning, so the hyper-side response builder can feed the
+   * body from the matching registry entry.
+   */
+  registerStream(streamId: string): Promise<boolean>
+  /**
+   * Push a UTF-8 chunk onto a registered stream. Returns `false` once
+   * the client has disconnected — callers stop pushing.
+   */
+  writeStream(streamId: string, chunk: string): Promise<boolean>
+  /**
+   * End a stream from the server side. Idempotent.
+   */
+  closeStream(streamId: string): Promise<boolean>
+  /**
+   * Install a one-shot callback fired the moment the matching stream
+   * receiver is dropped — i.e. the client disconnected OR
+   * `closeStream` was called. Used by the JS SDK to drop bookkeeping
+   * for subscriptions and SSE viewers.
+   */
+  onStreamDisconnect(streamId: string, callback: () => void): void
+}
+
+interface NativeModule {
+  HyperServer: new (port: number) => HyperServerLike
+}
+
+let native: NativeModule | undefined
+
+function loadNative(): NativeModule {
+  if (native) return native
+  native = loadNapi<NativeModule>({
+    binaryName: 'index',
+    callerMetaUrl: import.meta.url,
+    errorCodePrefix: 'HYPER_SERVER',
+  })
+  return native
+}
+
+/** HyperServer — Rust-powered HTTP server. */
+export class HyperServer implements HyperServerLike {
+  #inner: HyperServerLike
+
+  constructor(port: number) {
+    const mod = loadNative()
+    this.#inner = new mod.HyperServer(port)
+  }
+
+  onRequest(callback: (request: HttpKernelRequest) => Promise<HttpKernelResponse>): void {
+    this.#inner.onRequest(callback)
+  }
+
+  configureShield(config: RustShieldConfig): void {
+    this.#inner.configureShield(config)
+  }
+
+  configureTrustedProxies(cidrs: string[]): void {
+    this.#inner.configureTrustedProxies(cidrs)
+  }
+
+  configureRateLimit(config: RustRateLimitConfig | null): void {
+    this.#inner.configureRateLimit(config)
+  }
+
+  listen(): Promise<void> {
+    return this.#inner.listen()
+  }
+
+  port(): Promise<number> {
+    return this.#inner.port()
+  }
+
+  close(): Promise<void> {
+    return this.#inner.close()
+  }
+
+  registerStream(streamId: string): Promise<boolean> {
+    return this.#inner.registerStream(streamId)
+  }
+
+  writeStream(streamId: string, chunk: string): Promise<boolean> {
+    return this.#inner.writeStream(streamId, chunk)
+  }
+
+  closeStream(streamId: string): Promise<boolean> {
+    return this.#inner.closeStream(streamId)
+  }
+
+  onStreamDisconnect(streamId: string, callback: () => void): void {
+    this.#inner.onStreamDisconnect(streamId, callback)
+  }
+}