@c9up/ream 0.1.3

package/src/http/Response.ts

@@ -0,0 +1,351 @@
+/**
+ * Response — accumulates HTTP response state with a fluent API.
+ *
+ * Wraps the same { status, headers, body } wire format expected by the NAPI layer.
+ * Provides AdonisJS-compatible methods: json(), send(), status(), header(), etc.
+ *
+ * @implements FR21
+ */
+
+import type { RedirectBuilder } from './RedirectBuilder.js'
+import {
+  openSseStream,
+  type SseStream,
+  type SseStreamOptions,
+  type StreamBackend,
+} from './SseStream.js'
+
+/**
+ * Reject CR / LF / NUL bytes in header names or values. Without this guard
+ * an attacker controlling part of a header (e.g. a redirect URL parameter
+ * echoed into `Location`) could splice extra response headers — the classic
+ * CRLF injection / response-splitting attack (CWE-113).
+ */
+function assertNoCRLF(name: string, value: string): void {
+  if (/[\r\n\0]/.test(name) || /[\r\n\0]/.test(value)) {
+    throw new Error(
+      `CRLF / NUL byte in header '${name}' is not allowed (response-splitting protection).`,
+    )
+  }
+}
+
+export class Response {
+  #status = 200
+  #headers: Record<string, string> = {}
+  #cookies: string[] = []
+  #body = ''
+  #finished = false
+  #redirectBuilderFactory?: () => RedirectBuilder
+  #streamBackend?: StreamBackend
+  #streamId?: string
+
+  /**
+   * CSP nonce for this request (AdonisJS idiom: `response.nonce`). Seeded by
+   * the `@c9up/blackhole` middleware when the CSP uses `@nonce`; `undefined`
+   * otherwise. Also published to `ctx.store` as `cspNonce` for templating.
+   */
+  nonce?: string
+
+  // ─── Status ───────────────────────────────────────────────
+
+  /** Set the HTTP status code. Chainable. */
+  status(code: number): this {
+    this.#status = code
+    return this
+  }
+
+  /** Set status only if not already set (still 200). */
+  safeStatus(code: number): this {
+    if (this.#status === 200) {
+      this.#status = code
+    }
+    return this
+  }
+
+  // ─── Headers ──────────────────────────────────────────────
+
+  /** Set a response header. Chainable. */
+  header(key: string, value: string): this {
+    assertNoCRLF(key, value)
+    this.#headers[key.toLowerCase()] = value
+    return this
+  }
+
+  /** Append to a response header (for multi-value like Set-Cookie). */
+  append(key: string, value: string): this {
+    assertNoCRLF(key, value)
+    const k = key.toLowerCase()
+    if (k === 'set-cookie') {
+      // Set-Cookie must NOT be comma-joined — each cookie is its own
+      // header line, or browsers/proxies mis-parse the lot. Route into
+      // the same `#cookies` channel `cookie()` uses; `getHeaders()`
+      // emits them newline-separated for the serializer.
+      this.#cookies.push(value)
+      return this
+    }
+    const existing = this.#headers[k]
+    this.#headers[k] = existing ? `${existing}, ${value}` : value
+    return this
+  }
+
+  /** Remove a response header. */
+  removeHeader(key: string): this {
+    delete this.#headers[key.toLowerCase()]
+    return this
+  }
+
+  /** Set the Content-Type header. Chainable. */
+  type(contentType: string): this {
+    // Same CRLF/NUL guard as header() — `type(userValue)` must not be a
+    // response-splitting hole just because it writes a fixed header key.
+    assertNoCRLF('content-type', contentType)
+    this.#headers['content-type'] = contentType
+    return this
+  }
+
+  // ─── Body ─────────────────────────────────────────────────
+
+  /** Send a JSON response. Sets content-type and stringifies. */
+  json(data: unknown): void {
+    this.#headers['content-type'] = 'application/json'
+    this.#body = JSON.stringify(data)
+    this.#finished = true
+  }
+
+  /** Send a response body. Auto-detects content type if not set. */
+  send(data: unknown): void {
+    if (typeof data === 'string') {
+      if (!this.#headers['content-type']) {
+        this.#headers['content-type'] = 'text/html; charset=utf-8'
+      }
+      this.#body = data
+    } else if (Buffer.isBuffer(data)) {
+      // Without this branch a Buffer would hit the `typeof === 'object'`
+      // path and be JSON-stringified into `{"type":"Buffer","data":[...]}`
+      // — every binary asset (PNG, PDF, ...) would arrive corrupted.
+      this.sendBuffer(data)
+      return
+    } else if (typeof data === 'object' && data !== null) {
+      this.#headers['content-type'] = 'application/json'
+      this.#body = JSON.stringify(data)
+    } else if (data !== undefined && data !== null) {
+      if (!this.#headers['content-type']) {
+        this.#headers['content-type'] = 'text/plain'
+      }
+      this.#body = String(data)
+    }
+    this.#finished = true
+  }
+
+  /**
+   * Send a binary body as-is. Encodes to base64 across the NAPI bridge
+   * with the `x-ream-body-encoding: base64` marker so the Rust HTTP
+   * layer decodes it before writing to the socket. The marker header is
+   * stripped server-side and never leaks to the client.
+   *
+   * Use this for any non-UTF-8 payload (images, PDFs, archives, etc.) —
+   * `send()` auto-routes Buffers here, but call directly when intent is
+   * unambiguous.
+   */
+  sendBuffer(buffer: Buffer): void {
+    if (!this.#headers['content-type']) {
+      this.#headers['content-type'] = 'application/octet-stream'
+    }
+    this.#headers['x-ream-body-encoding'] = 'base64'
+    this.#body = buffer.toString('base64')
+    this.#finished = true
+  }
+
+  /** Send 204 No Content. */
+  noContent(): void {
+    this.#status = 204
+    this.#body = ''
+    this.#finished = true
+  }
+
+  // ─── Redirect ─────────────────────────────────────────────
+
+  /** Get a redirect builder. */
+  redirect(): RedirectBuilder {
+    if (this.#redirectBuilderFactory) {
+      return this.#redirectBuilderFactory()
+    }
+    throw new Error(
+      'redirect() requires an HttpContext. Response was created outside a request handler.',
+    )
+  }
+
+  /** @internal Set the redirect builder factory (injected by HttpContext). */
+  setRedirectFactory(factory: () => RedirectBuilder): void {
+    this.#redirectBuilderFactory = factory
+  }
+
+  /** @internal Wire the SSE backend (HyperServer NAPI). Injected by HttpKernel. */
+  setStreamBackend(backend: StreamBackend): void {
+    this.#streamBackend = backend
+  }
+
+  // ─── Streaming (SSE) ──────────────────────────────────────
+
+  /**
+   * Open a Server-Sent Events stream. The returned `SseStream` lets the
+   * handler push named events for as long as the client stays
+   * connected. Headers are pre-set to the SSE wire format; the host
+   * router serializes the response with the reserved stream id so the
+   * Rust HyperServer keeps the connection open.
+   *
+   *   const sse = await ctx.response.sse()
+   *   sse.send('connected', { uid: caller.id })
+   *   onTaskAssigned((evt) => sse.send('task.assigned', evt))
+   *
+   * Throws `STREAMING_UNSUPPORTED` if the underlying HyperServer host
+   * does not implement the streaming NAPI (e.g. a mock server in unit
+   * tests). The host capability is opt-in: implement
+   * `registerStream`/`writeStream`/`closeStream`/`onStreamDisconnect`
+   * to participate.
+   */
+  async sse(options?: SseStreamOptions): Promise<SseStream> {
+    if (!this.#streamBackend) {
+      throw new Error(
+        '[ream] response.sse() requires a streaming-capable HyperServer host. ' +
+          'The current server has no stream backend wired.',
+      )
+    }
+    // SSE wire format + safety defaults. The buffered body string stays
+    // empty — every chunk goes through the registry instead.
+    this.#headers['content-type'] = 'text/event-stream'
+    if (!this.#headers['cache-control']) {
+      this.#headers['cache-control'] = 'no-cache, no-transform'
+    }
+    if (!this.#headers['x-accel-buffering']) {
+      this.#headers['x-accel-buffering'] = 'no'
+    }
+    const stream = await openSseStream(this.#streamBackend, options)
+    this.#streamId = stream.id
+    // Mark the response as "finished" so middleware that bails when
+    // `isFinished()` is true (the standard short-circuit) doesn't
+    // re-touch the body or headers after the SSE pipe has been set up.
+    this.#finished = true
+    return stream
+  }
+
+  // ─── Cookies ──────────────────────────────────────────────
+
+  /** Set a response cookie. */
+  cookie(
+    name: string,
+    value: string,
+    options?: {
+      maxAge?: number
+      path?: string
+      httpOnly?: boolean
+      secure?: boolean
+      sameSite?: 'lax' | 'strict' | 'none'
+    },
+  ): this {
+    // SameSite=None cookies REQUIRE the Secure attribute — modern browsers
+    // (Chrome 80+, Firefox, Safari) silently reject the cookie otherwise, so
+    // a missing Secure here turns OAuth callbacks / iframe sessions into a
+    // "works in dev (localhost relaxes Secure), breaks in prod" foot-gun.
+    if (options?.sameSite === 'none' && !options.secure) {
+      throw new Error(
+        `Cookie '${name}': SameSite=None requires Secure: true (browsers reject SameSite=None cookies without Secure).`,
+      )
+    }
+    const parts = [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`]
+    // `maxAge: 0` is the RFC 6265 "delete-now" signal used by logout
+    // flows. A truthiness check would skip it and leave the cookie
+    // alive for the session — explicit `!== undefined` covers both
+    // 0 and negative values that browsers also treat as immediate
+    // expiry.
+    if (options?.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`)
+    if (options?.path) {
+      // `Path` is concatenated raw (encodeURIComponent would mangle the `/`
+      // separators a path legitimately contains), so it needs the same
+      // CRLF/NUL guard as header()/append() — otherwise a controlled path
+      // injects into the `\n`-joined Set-Cookie header (response-splitting).
+      assertNoCRLF(`Set-Cookie path for '${name}'`, options.path)
+      parts.push(`Path=${options.path}`)
+    }
+    if (options?.httpOnly !== false) parts.push('HttpOnly')
+    if (options?.secure) parts.push('Secure')
+    if (options?.sameSite) parts.push(`SameSite=${options.sameSite}`)
+    this.#cookies.push(parts.join('; '))
+    return this
+  }
+
+  // ─── Internals (used by HttpKernel for NAPI serialization) ─
+
+  /** @internal Get the accumulated status code. */
+  getStatus(): number {
+    return this.#status
+  }
+
+  /** @internal Get all accumulated headers (Set-Cookie as separate entries joined by newline). */
+  getHeaders(): Record<string, string> {
+    const headers = { ...this.#headers }
+    if (this.#cookies.length > 0) {
+      // Multiple Set-Cookie headers must be separate — we join with \n for the serializer
+      headers['set-cookie'] = this.#cookies.join('\n')
+    }
+    return headers
+  }
+
+  /**
+   * Read a single accumulated response header by name (case-insensitive).
+   * Returns `undefined` when not set — used by middleware that conditionally
+   * inspects the outgoing content-type before sanitisation.
+   */
+  getHeader(name: string): string | undefined {
+    return this.#headers[name.toLowerCase()]
+  }
+
+  /** @internal Get the accumulated body string. */
+  getBody(): string {
+    return this.#body
+  }
+
+  /** @internal Check if response has been finalized. */
+  isFinished(): boolean {
+    return this.#finished
+  }
+
+  /** @internal Set body directly (used by redirect, exception handler). */
+  setBody(body: string): void {
+    this.#body = body
+    this.#finished = true
+  }
+
+  /**
+   * @internal Streaming-response handle, set by `sse()`. The host
+   * router forwards this id to the Rust HyperServer so the connection
+   * stays open and chunks flow from the JS-side writer.
+   */
+  getStreamId(): string | undefined {
+    return this.#streamId
+  }
+
+  /**
+   * @internal Tear down a stream the handler opened via `sse()` but
+   * then abandoned by throwing. Closes the backend registry slot and
+   * clears the stream id + finished flag so the kernel's error path
+   * serializes a normal buffered error response instead of emitting
+   * `streamId` alongside an error body (which would leave the
+   * HyperServer feeding a dead/empty stream forever). Best-effort: a
+   * closeStream failure is swallowed — the slot's TTL/disconnect will
+   * reclaim it.
+   */
+  async abortStream(): Promise<void> {
+    const id = this.#streamId
+    if (id === undefined) return
+    this.#streamId = undefined
+    this.#finished = false
+    if (this.#streamBackend) {
+      try {
+        await this.#streamBackend.closeStream(id)
+      } catch {
+        // benign — registry TTL / client disconnect reclaims the slot.
+      }
+    }
+  }
+}

package/src/http/SseStream.ts

@@ -0,0 +1,250 @@
+/**
+ * Server-Sent Events writer — owns one logical SSE stream and pushes
+ * encoded events through the underlying `StreamBackend` (a thin
+ * abstraction over the HyperServer NAPI `registerStream` / `writeStream`
+ * / `closeStream` trio).
+ *
+ * Lifecycle:
+ *
+ *   1. `ctx.response.sse()` returns a ready-to-use writer. Internally it
+ *      asks the backend to reserve a stream id and stamps the response
+ *      with the right `Content-Type` + caching headers so the host
+ *      router knows to switch into streaming mode.
+ *   2. The handler calls `writer.send(event, data)` / `writer.comment(...)`
+ *      to push frames. Each call returns a boolean — `false` once the
+ *      client has disconnected, so callers can bail out of long loops
+ *      without polling.
+ *   3. The handler RETURNS the Response from the route — buffered body is
+ *      empty, but `response.getStreamId()` is set, so Ream tells the
+ *      Rust HyperServer to keep the connection open and feed the body
+ *      from the stream registry.
+ *   4. Background tasks keep pushing through `writer.send(...)` until
+ *      either the client leaves (`onClose` callback fires) or the
+ *      server calls `writer.end()`.
+ *
+ * The encoding follows the SSE wire format (RFC chez WHATWG):
+ *
+ *     event: <name>\n
+ *     data: <stringified payload>\n
+ *     id: <optional event id>\n
+ *     \n
+ *
+ * Multi-line payloads are split on `\n` and each line is prefixed with
+ * `data: ` so the consumer browser reassembles them with newlines.
+ */
+
+/** Minimal backend the writer needs — the HyperServer NAPI fits exactly. */
+export interface StreamBackend {
+  registerStream(streamId: string): Promise<boolean>
+  writeStream(streamId: string, chunk: string): Promise<boolean>
+  closeStream(streamId: string): Promise<boolean>
+  onStreamDisconnect(streamId: string, callback: () => void): void
+}
+
+export interface SseStreamOptions {
+  /** Keep-alive ping interval (ms). Defaults to 30s. Set to 0 to disable. */
+  pingInterval?: number
+  /** Initial `retry: <ms>` directive sent before any event. Defaults to 5_000. */
+  retry?: number
+}
+
+const DEFAULT_PING_INTERVAL = 30_000
+const DEFAULT_RETRY = 5_000
+
+/** Cryptographic-quality stream id — 16 random bytes, hex-encoded. */
+function generateStreamId(): string {
+  const bytes = new Uint8Array(16)
+  // `crypto.getRandomValues` is the WHATWG primitive available on every
+  // supported Node version (>=22). Avoids pulling in `node:crypto` for
+  // a 32-char hex string.
+  globalThis.crypto.getRandomValues(bytes)
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')
+}
+
+/** Active SSE writer returned by `response.sse()`. */
+export class SseStream {
+  readonly id: string
+  #backend: StreamBackend
+  #open = true
+  #closeFired = false
+  #pingTimer: ReturnType<typeof setInterval> | null = null
+  #closeListeners: Array<() => void> = []
+
+  constructor(id: string, backend: StreamBackend, options?: SseStreamOptions) {
+    this.id = id
+    this.#backend = backend
+
+    // The backend disconnect signal and a server-side end() can BOTH
+    // fire (e.g. server end() followed by the client-drop signal). The
+    // shared #fireClose() guards idempotency so user cleanups run once.
+    backend.onStreamDisconnect(id, () => {
+      this.#open = false
+      this.#stopPing()
+      this.#fireClose()
+    })
+
+    const ping = options?.pingInterval ?? DEFAULT_PING_INTERVAL
+    if (ping > 0) {
+      this.#pingTimer = setInterval(() => {
+        if (!this.#open) return
+        // Comment frames keep the connection alive without firing a
+        // JS event on the client. `writeStream` returns false once the
+        // client has disconnected (per the NAPI contract); if we see
+        // that while still "open" the disconnect signal was missed —
+        // e.g. the client dropped in the window between registerStream
+        // and the constructor wiring onStreamDisconnect. Self-heal:
+        // stop the timer and run close listeners once, so a dropped-
+        // at-open stream can't leave an orphaned keepalive ticking
+        // against a dead registry slot.
+        void this.#backend.writeStream(this.id, ':keepalive\n\n').then((ok) => {
+          if (!ok && this.#open) {
+            this.#open = false
+            this.#stopPing()
+            this.#fireClose()
+          }
+        })
+      }, ping)
+      // The keepalive must not pin the Node event loop — letting the
+      // process exit on its own when nothing else is keeping it busy
+      // matches Adonis Transmit's behavior.
+      if (typeof this.#pingTimer === 'object' && 'unref' in this.#pingTimer) {
+        ;(this.#pingTimer as { unref: () => void }).unref()
+      }
+    }
+  }
+
+  /** True until the client disconnects or the server calls `end()`. */
+  isOpen(): boolean {
+    return this.#open
+  }
+
+  /**
+   * Send a named SSE event. `data` is JSON-stringified unless it is
+   * already a string. Returns `false` if the stream is closed.
+   *
+   * `eventId` is optional — set it when you want browsers to send
+   * `Last-Event-ID` on reconnection. Useful for resumable streams.
+   */
+  async send(event: string, data: unknown, eventId?: string): Promise<boolean> {
+    if (!this.#open) return false
+    const payload = typeof data === 'string' ? data : JSON.stringify(data)
+    return this.#backend.writeStream(this.id, encodeFrame(event, payload, eventId))
+  }
+
+  /**
+   * Send a comment frame (`:text\n\n`) — useful for keep-alives and
+   * for human-readable inline debug. Comments are NOT delivered to
+   * `EventSource.onmessage`; the browser silently consumes them.
+   */
+  async comment(text: string): Promise<boolean> {
+    if (!this.#open) return false
+    // Strip newlines so a malicious comment cannot inject `\n\n` and
+    // close a frame early.
+    const sanitized = text.replace(/[\r\n]+/g, ' ')
+    return this.#backend.writeStream(this.id, `:${sanitized}\n\n`)
+  }
+
+  /** Register a callback fired once the underlying connection drops. */
+  onClose(callback: () => void): void {
+    if (!this.#open) {
+      // Already closed — run the callback synchronously so behavior
+      // matches the standard observer pattern.
+      try {
+        callback()
+      } catch {
+        // Swallow — same isolation as the normal listener loop.
+      }
+      return
+    }
+    this.#closeListeners.push(callback)
+  }
+
+  /**
+   * End the stream from the server side. Idempotent. The matching
+   * NAPI receiver finishes its work and hyper closes the body.
+   */
+  async end(): Promise<void> {
+    if (!this.#open) return
+    this.#open = false
+    this.#stopPing()
+    await this.#backend.closeStream(this.id)
+    this.#fireClose()
+  }
+
+  #stopPing(): void {
+    if (this.#pingTimer !== null) {
+      clearInterval(this.#pingTimer)
+      this.#pingTimer = null
+    }
+  }
+
+  /**
+   * Run every close listener exactly once. Both end() (server-side) and
+   * the backend disconnect signal funnel through here; the #closeFired
+   * latch stops user cleanups from being replayed when both fire.
+   */
+  #fireClose(): void {
+    if (this.#closeFired) return
+    this.#closeFired = true
+    for (const cb of this.#closeListeners) {
+      try {
+        cb()
+      } catch {
+        // Listener errors are isolated — one bad cleanup callback
+        // mustn't take down the rest.
+      }
+    }
+  }
+}
+
+/**
+ * Open a new SSE stream against the given backend. Returns once the
+ * registry slot is reserved — safe to call `send()` immediately, even
+ * before the handler has returned (frames buffer in the bounded mpsc
+ * inside Rust).
+ *
+ * The `retry: <ms>` directive is sent as the first thing on the wire
+ * (a comment frame would be invisible to the client; the retry hint
+ * needs to land before any real event so browsers know how long to
+ * wait before reconnecting if the connection drops).
+ */
+export async function openSseStream(
+  backend: StreamBackend,
+  options?: SseStreamOptions,
+): Promise<SseStream> {
+  const id = generateStreamId()
+  const registered = await backend.registerStream(id)
+  if (!registered) {
+    // Hex collision is astronomically improbable, but surfacing it
+    // cleanly beats a silent stream-id mismatch (the response builder
+    // would then 500 with E_STREAM_UNKNOWN, which is far less helpful).
+    throw new Error(`[ream] failed to reserve SSE stream id ${id} — collision in the registry`)
+  }
+  // First frame: the recommended retry hint. Conforms to the EventSource
+  // reconnection backoff spec; falling through with the default 5s.
+  await backend.writeStream(id, `retry: ${options?.retry ?? DEFAULT_RETRY}\n\n`)
+  return new SseStream(id, backend, options)
+}
+
+/** Encode a single SSE event in the wire format. */
+function encodeFrame(event: string, data: string, eventId?: string): string {
+  // `event:` line first if we have a name (a frame without `event:` is
+  // delivered as a generic `message` event by the browser — both forms
+  // are valid).
+  const lines: string[] = []
+  // `event:` and `id:` are single-line tokens — strip CR/LF so a
+  // caller-supplied event name or id can't splice extra SSE frames
+  // (the same injection `comment()` guards against). `data` is safe:
+  // it's split on `\n` and each line re-prefixed, so newlines there
+  // stay inside one logical event.
+  if (event) lines.push(`event: ${event.replace(/[\r\n]+/g, ' ')}`)
+  // Multi-line data is allowed by SSE but each line must repeat the
+  // `data: ` prefix. Splitting on `\n` keeps the browser's
+  // reassembly intact (it joins back with `\n`).
+  for (const line of data.split('\n')) {
+    lines.push(`data: ${line}`)
+  }
+  if (eventId) lines.push(`id: ${eventId.replace(/[\r\n]+/g, ' ')}`)
+  // Trailing blank line terminates the event.
+  return `${lines.join('\n')}\n\n`
+}

package/src/http/urlDecode.ts

@@ -0,0 +1,18 @@
+/**
+ * Safe URL decoding helpers for untrusted request inputs.
+ */
+
+/** Decode URI component and keep raw value on malformed escapes. */
+export function safeDecodeURIComponent(value: string): string {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}
+
+/** Decode x-www-form-urlencoded component (`+` => space) safely. */
+export function safeDecodeFormComponent(value: string): string {
+  const normalized = value.replace(/\+/g, ' ')
+  return safeDecodeURIComponent(normalized)
+}