@c9up/ream 0.1.24 → 0.1.26

package/src/http/Response.ts

@@ -7,6 +7,13 @@
  * @implements FR21
  */
 
+import { readFileSync } from 'node:fs'
+import { basename } from 'node:path'
+import etag from 'etag'
+import { contentType } from 'mime-types'
+import type { CookieSigner } from '../security/CookieSigner.js'
+import { Macroable } from '../utils/Macroable.js'
+import { E_HTTP_REQUEST_ABORTED } from './Exception.js'
 import type { RedirectBuilder } from './RedirectBuilder.js'
 import {
   openSseStream,
@@ -29,7 +36,33 @@ function assertNoCRLF(name: string, value: string): void {
   }
 }
 
-export class Response {
+/**
+ * JSON.stringify with AdonisJS-parity safety: `BigInt` values are emitted as
+ * strings (native `JSON.stringify` throws on them) and circular references are
+ * dropped instead of throwing — so `response.json()` / an object `send()` never
+ * blows up on a payload the raw serializer can't handle.
+ */
+function safeStringify(value: unknown): string {
+  const seen = new WeakSet<object>()
+  return JSON.stringify(value, (_key, val) => {
+    if (typeof val === 'bigint') return val.toString()
+    if (typeof val === 'object' && val !== null) {
+      if (seen.has(val)) return undefined
+      seen.add(val)
+    }
+    return val
+  })
+}
+
+export interface CookieOptions {
+  maxAge?: number
+  path?: string
+  httpOnly?: boolean
+  secure?: boolean
+  sameSite?: 'lax' | 'strict' | 'none'
+}
+
+export class Response extends Macroable {
   #status = 200
   #headers: Record<string, string> = {}
   #cookies: string[] = []
@@ -38,6 +71,8 @@ export class Response {
   #redirectBuilderFactory?: () => RedirectBuilder
   #streamBackend?: StreamBackend
   #streamId?: string
+  #request?: { method(): string; header(key: string): string | undefined }
+  #cookieSigner?: CookieSigner
 
   /**
    * CSP nonce for this request (AdonisJS idiom: `response.nonce`). Seeded by
@@ -94,12 +129,54 @@ export class Response {
     return this
   }
 
-  /** Set the Content-Type header. Chainable. */
-  type(contentType: string): this {
-    // Same CRLF/NUL guard as header() — `type(userValue)` must not be a
+  /**
+   * Set a header only if it has not been set yet (AdonisJS `safeHeader`) —
+   * the idiom for defaulting a header from middleware without clobbering a
+   * value a downstream handler already chose.
+   */
+  safeHeader(key: string, value: string): this {
+    if (!this.getHeader(key)) this.header(key, value)
+    return this
+  }
+
+  /** Append field(s) to the `Vary` header, de-duplicated (AdonisJS parity). */
+  vary(field: string | string[]): this {
+    const fields = Array.isArray(field) ? field : [field]
+    const current = this.getHeader('vary')
+    const existing = current
+      ? current
+          .split(',')
+          .map((f) => f.trim())
+          .filter(Boolean)
+      : []
+    for (const f of fields) if (!existing.includes(f)) existing.push(f)
+    this.header('Vary', existing.join(', '))
+    return this
+  }
+
+  /** Set the `Location` header without issuing a redirect (AdonisJS parity). */
+  location(url: string): this {
+    this.header('Location', url)
+    return this
+  }
+
+  /**
+   * Set the Content-Type header. Chainable. AdonisJS parity
+   * (`response.type(type, charset?)`): `type` may be a full MIME type OR a file
+   * extension — `type('txt')` → `text/plain; charset=utf-8`, `type('json')` →
+   * `application/json; charset=utf-8` — resolved via `mime-types` exactly like
+   * Adonis. An optional `charset` is appended before resolution.
+   */
+  type(type: string, charset?: string): this {
+    const input = charset ? `${type}; charset=${charset}` : type
+    // `contentType()` returns `false` for an unrecognised value — fall back to
+    // the raw input rather than writing `content-type: false`.
+    const resolved = contentType(input)
+    const value = resolved === false ? input : resolved
+    // Same CRLF/NUL guard as header() — a resolved type must never be a
     // response-splitting hole just because it writes a fixed header key.
-    assertNoCRLF('content-type', contentType)
-    this.#headers['content-type'] = contentType
+    assertNoCRLF('content-type', value)
+    this.#headers['content-type'] = value
     return this
   }
 
@@ -108,7 +185,28 @@ export class Response {
   /** 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.#body = safeStringify(data)
+    this.#finished = true
+  }
+
+  /**
+   * Send a JSONP response (AdonisJS parity) — wraps the JSON body in a
+   * `callbackName(...)` call served as `text/javascript`. The callback name is
+   * sanitised to identifier-safe characters and U+2028 / U+2029 are escaped
+   * (valid in JSON, but break JS), so neither the callback nor the payload can
+   * inject script.
+   */
+  jsonp(body: unknown, callbackName = 'callback'): void {
+    // Sanitise the callback name to identifier-safe characters — the JSONP XSS
+    // guard (an attacker-controlled callback must not inject script).
+    const safeCallback = callbackName.replace(/[^\w$.]/g, '')
+    // Escape U+2028 / U+2029 — valid inside JSON strings but line terminators in
+    // JS, so they'd break the wrapped payload in a <script> context (Adonis parity).
+    const json = safeStringify(body).replace(/[\u2028\u2029]/g, (c) =>
+      c === '\u2028' ? '\\u2028' : '\\u2029',
+    )
+    this.#headers['content-type'] = 'text/javascript; charset=utf-8'
+    this.#body = `/**/ typeof ${safeCallback} === 'function' && ${safeCallback}(${json});`
     this.#finished = true
   }
 
@@ -116,7 +214,12 @@ export class Response {
   send(data: unknown): void {
     if (typeof data === 'string') {
       if (!this.#headers['content-type']) {
-        this.#headers['content-type'] = 'text/html; charset=utf-8'
+        // AdonisJS parity: an HTML-looking string (opens with `<`) is served as
+        // `text/html`; a plain string as `text/plain` — not everything forced to
+        // HTML (which mislabels plain text and JSON/CSV/robots.txt bodies).
+        this.#headers['content-type'] = data.trimStart().startsWith('<')
+          ? 'text/html; charset=utf-8'
+          : 'text/plain; charset=utf-8'
       }
       this.#body = data
     } else if (Buffer.isBuffer(data)) {
@@ -127,7 +230,7 @@ export class Response {
       return
     } else if (typeof data === 'object' && data !== null) {
       this.#headers['content-type'] = 'application/json'
-      this.#body = JSON.stringify(data)
+      this.#body = safeStringify(data)
     } else if (data !== undefined && data !== null) {
       if (!this.#headers['content-type']) {
         this.#headers['content-type'] = 'text/plain'
@@ -163,6 +266,254 @@ export class Response {
     this.#finished = true
   }
 
+  // ─── Descriptive status methods (AdonisJS parity) ────────
+  // Each sets the status then sends the (optional) body — mirrors
+  // `@adonisjs/http-server` Response (e.g. `response.notFound(body)`).
+
+  /** 100 Continue. */
+  continue(): void {
+    this.status(100)
+  }
+
+  /** 101 Switching Protocols. */
+  switchingProtocols(): void {
+    this.status(101)
+  }
+
+  /** 200 ok. */
+  ok(body?: unknown): void {
+    this.status(200)
+    this.send(body)
+  }
+
+  /** 201 created. */
+  created(body?: unknown): void {
+    this.status(201)
+    this.send(body)
+  }
+
+  /** 202 accepted. */
+  accepted(body?: unknown): void {
+    this.status(202)
+    this.send(body)
+  }
+
+  /** 203 nonAuthoritativeInformation. */
+  nonAuthoritativeInformation(body?: unknown): void {
+    this.status(203)
+    this.send(body)
+  }
+
+  /** 205 resetContent. */
+  resetContent(body?: unknown): void {
+    this.status(205)
+    this.send(body)
+  }
+
+  /** 206 partialContent. */
+  partialContent(body?: unknown): void {
+    this.status(206)
+    this.send(body)
+  }
+
+  /** 300 multipleChoices. */
+  multipleChoices(body?: unknown): void {
+    this.status(300)
+    this.send(body)
+  }
+
+  /** 301 movedPermanently. */
+  movedPermanently(body?: unknown): void {
+    this.status(301)
+    this.send(body)
+  }
+
+  /** 302 movedTemporarily. */
+  movedTemporarily(body?: unknown): void {
+    this.status(302)
+    this.send(body)
+  }
+
+  /** 303 seeOther. */
+  seeOther(body?: unknown): void {
+    this.status(303)
+    this.send(body)
+  }
+
+  /** 304 notModified. */
+  notModified(body?: unknown): void {
+    this.status(304)
+    this.send(body)
+  }
+
+  /** 305 useProxy. */
+  useProxy(body?: unknown): void {
+    this.status(305)
+    this.send(body)
+  }
+
+  /** 307 temporaryRedirect. */
+  temporaryRedirect(body?: unknown): void {
+    this.status(307)
+    this.send(body)
+  }
+
+  /** 400 badRequest. */
+  badRequest(body?: unknown): void {
+    this.status(400)
+    this.send(body)
+  }
+
+  /** 401 unauthorized. */
+  unauthorized(body?: unknown): void {
+    this.status(401)
+    this.send(body)
+  }
+
+  /** 402 paymentRequired. */
+  paymentRequired(body?: unknown): void {
+    this.status(402)
+    this.send(body)
+  }
+
+  /** 403 forbidden. */
+  forbidden(body?: unknown): void {
+    this.status(403)
+    this.send(body)
+  }
+
+  /** 404 notFound. */
+  notFound(body?: unknown): void {
+    this.status(404)
+    this.send(body)
+  }
+
+  /** 405 methodNotAllowed. */
+  methodNotAllowed(body?: unknown): void {
+    this.status(405)
+    this.send(body)
+  }
+
+  /** 406 notAcceptable. */
+  notAcceptable(body?: unknown): void {
+    this.status(406)
+    this.send(body)
+  }
+
+  /** 407 proxyAuthenticationRequired. */
+  proxyAuthenticationRequired(body?: unknown): void {
+    this.status(407)
+    this.send(body)
+  }
+
+  /** 408 requestTimeout. */
+  requestTimeout(body?: unknown): void {
+    this.status(408)
+    this.send(body)
+  }
+
+  /** 409 conflict. */
+  conflict(body?: unknown): void {
+    this.status(409)
+    this.send(body)
+  }
+
+  /** 410 gone. */
+  gone(body?: unknown): void {
+    this.status(410)
+    this.send(body)
+  }
+
+  /** 411 lengthRequired. */
+  lengthRequired(body?: unknown): void {
+    this.status(411)
+    this.send(body)
+  }
+
+  /** 412 preconditionFailed. */
+  preconditionFailed(body?: unknown): void {
+    this.status(412)
+    this.send(body)
+  }
+
+  /** 413 requestEntityTooLarge. */
+  requestEntityTooLarge(body?: unknown): void {
+    this.status(413)
+    this.send(body)
+  }
+
+  /** 414 requestUriTooLong. */
+  requestUriTooLong(body?: unknown): void {
+    this.status(414)
+    this.send(body)
+  }
+
+  /** 415 unsupportedMediaType. */
+  unsupportedMediaType(body?: unknown): void {
+    this.status(415)
+    this.send(body)
+  }
+
+  /** 416 requestedRangeNotSatisfiable. */
+  requestedRangeNotSatisfiable(body?: unknown): void {
+    this.status(416)
+    this.send(body)
+  }
+
+  /** 417 expectationFailed. */
+  expectationFailed(body?: unknown): void {
+    this.status(417)
+    this.send(body)
+  }
+
+  /** 422 unprocessableEntity. */
+  unprocessableEntity(body?: unknown): void {
+    this.status(422)
+    this.send(body)
+  }
+
+  /** 429 tooManyRequests. */
+  tooManyRequests(body?: unknown): void {
+    this.status(429)
+    this.send(body)
+  }
+
+  /** 500 internalServerError. */
+  internalServerError(body?: unknown): void {
+    this.status(500)
+    this.send(body)
+  }
+
+  /** 501 notImplemented. */
+  notImplemented(body?: unknown): void {
+    this.status(501)
+    this.send(body)
+  }
+
+  /** 502 badGateway. */
+  badGateway(body?: unknown): void {
+    this.status(502)
+    this.send(body)
+  }
+
+  /** 503 serviceUnavailable. */
+  serviceUnavailable(body?: unknown): void {
+    this.status(503)
+    this.send(body)
+  }
+
+  /** 504 gatewayTimeout. */
+  gatewayTimeout(body?: unknown): void {
+    this.status(504)
+    this.send(body)
+  }
+
+  /** 505 httpVersionNotSupported. */
+  httpVersionNotSupported(body?: unknown): void {
+    this.status(505)
+    this.send(body)
+  }
+
   // ─── Redirect ─────────────────────────────────────────────
 
   /** Get a redirect builder. */
@@ -176,6 +527,103 @@ export class Response {
   }
 
   /** @internal Set the redirect builder factory (injected by HttpContext). */
+  /** Give the response access to the request (wired by HttpContext) — used by `fresh()`. */
+  setRequest(request: { method(): string; header(key: string): string | undefined }): void {
+    this.#request = request
+  }
+
+  /** Inject the APP_KEY-backed cookie signer — wired by HttpContext. */
+  setCookieSigner(signer: CookieSigner): void {
+    this.#cookieSigner = signer
+  }
+
+  /** Set a strong (or weak) `ETag` for the given body (AdonisJS parity, `etag` pkg). */
+  setEtag(body: string | Buffer, weak = false): this {
+    this.header('Etag', etag(body, { weak }))
+    return this
+  }
+
+  /**
+   * Whether the client's cached copy is still fresh (AdonisJS `fresh`) — a
+   * cacheable method (GET/HEAD) with a 2xx/304 status whose `If-None-Match`
+   * matches this response's `ETag`. Lets a handler answer `304 Not Modified`.
+   */
+  fresh(): boolean {
+    const method = this.#request?.method()
+    if (method && method !== 'GET' && method !== 'HEAD') return false
+    const status = this.#status
+    if (!((status >= 200 && status < 300) || status === 304)) return false
+    const noneMatch = this.#request?.header('if-none-match')
+    const currentEtag = this.getHeader('etag')
+    if (!noneMatch || !currentEtag) return false
+    if (noneMatch.trim() === '*') return true
+    return noneMatch.split(',').some((tag) => {
+      const t = tag.trim()
+      return t === currentEtag || t === `W/${currentEtag}` || `W/${t}` === currentEtag
+    })
+  }
+
+  /**
+   * Abort the request with a body + status (AdonisJS parity) — throws
+   * `E_HTTP_REQUEST_ABORTED`, which the exception handler renders (a string body
+   * verbatim, anything else as JSON).
+   */
+  abort(body: unknown, status = 400): never {
+    throw new E_HTTP_REQUEST_ABORTED(body, status)
+  }
+
+  /** Abort only when `condition` is truthy (AdonisJS `abortIf`). */
+  abortIf(
+    condition: unknown,
+    body: unknown,
+    status = 400,
+  ): asserts condition is undefined | null | false {
+    if (condition) this.abort(body, status)
+  }
+
+  /**
+   * Send a file to the client (AdonisJS `download`) — reads the file, infers the
+   * content-type from its extension, and sends it as a binary body. On a read
+   * error, `errorCallback` may map it to `[message, status?]`, else a 404.
+   */
+  download(
+    filePath: string,
+    generateEtag = false,
+    errorCallback?: (error: NodeJS.ErrnoException) => [string, number?],
+  ): void {
+    let content: Buffer
+    try {
+      content = readFileSync(filePath)
+    } catch (error) {
+      if (errorCallback) {
+        const [message, status] = errorCallback(error as NodeJS.ErrnoException)
+        this.status(status ?? 404).send(message)
+        return
+      }
+      this.status(404).send('Not Found')
+      return
+    }
+    const ct = contentType(basename(filePath))
+    if (ct) this.#headers['content-type'] = ct
+    if (generateEtag) this.setEtag(content)
+    this.sendBuffer(content)
+  }
+
+  /**
+   * Force a file download with a `Content-Disposition` header (AdonisJS
+   * `attachment`). Defaults the filename to the file's basename.
+   */
+  attachment(
+    filePath: string,
+    name?: string,
+    disposition = 'attachment',
+    generateEtag = false,
+  ): void {
+    const filename = name ?? basename(filePath)
+    this.header('Content-Disposition', `${disposition}; filename="${filename}"`)
+    this.download(filePath, generateEtag)
+  }
+
   setRedirectFactory(factory: () => RedirectBuilder): void {
     this.#redirectBuilderFactory = factory
   }
@@ -231,18 +679,41 @@ export class Response {
 
   // ─── Cookies ──────────────────────────────────────────────
 
-  /** Set a response cookie. */
-  cookie(
-    name: string,
-    value: string,
-    options?: {
-      maxAge?: number
-      path?: string
-      httpOnly?: boolean
-      secure?: boolean
-      sameSite?: 'lax' | 'strict' | 'none'
-    },
-  ): this {
+  /**
+   * Set a SIGNED response cookie (AdonisJS default). The value is HMAC-signed
+   * with the app's `APP_KEY` (via the injected signer) so tampering is detected
+   * on read; `request.cookie()` verifies + unwraps it. Falls back to a plain
+   * cookie when no APP_KEY / encryption service is configured.
+   */
+  cookie(name: string, value: string, options?: CookieOptions): this {
+    const signed = this.#cookieSigner ? this.#cookieSigner.sign(value) : value
+    return this.#writeCookie(name, signed, options)
+  }
+
+  /**
+   * Set an UNSIGNED response cookie (AdonisJS `plainCookie`) — sent as-is. Use
+   * for values you already protect (encrypted session ids, CSRF tokens) or that
+   * a client-side script must read.
+   */
+  plainCookie(name: string, value: string, options?: CookieOptions): this {
+    return this.#writeCookie(name, value, options)
+  }
+
+  /**
+   * Set an ENCRYPTED response cookie (AdonisJS `encryptedCookie`) — AES-256-GCM
+   * encrypted with `APP_KEY`, unreadable + tamper-proof on the client. Requires
+   * a configured encryption service (APP_KEY).
+   */
+  encryptedCookie(name: string, value: string, options?: CookieOptions): this {
+    if (!this.#cookieSigner) {
+      throw new Error(
+        'encryptedCookie() requires APP_KEY — set it so the encryption service is registered.',
+      )
+    }
+    return this.#writeCookie(name, this.#cookieSigner.encrypt(value), options)
+  }
+
+  #writeCookie(name: string, value: string, options?: CookieOptions): 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
@@ -253,17 +724,12 @@ export class Response {
       )
     }
     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.
+    // `maxAge: 0` is the RFC 6265 "delete-now" signal used by logout flows. A
+    // truthiness check would skip it; explicit `!== undefined` covers 0 too.
     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).
+      // `Path` is concatenated raw (encodeURIComponent would mangle `/`), so it
+      // needs the same CRLF/NUL guard as header() (response-splitting).
       assertNoCRLF(`Set-Cookie path for '${name}'`, options.path)
       parts.push(`Path=${options.path}`)
     }
@@ -274,6 +740,14 @@ export class Response {
     return this
   }
 
+  /**
+   * Expire a cookie immediately (AdonisJS `clearCookie`) — re-sends it with
+   * `Max-Age=0`, the RFC 6265 delete-now signal that `cookie()` honours.
+   */
+  clearCookie(name: string, options?: { path?: string }): this {
+    return this.plainCookie(name, '', { ...options, maxAge: 0 })
+  }
+
   // ─── Internals (used by HttpKernel for NAPI serialization) ─
 
   /** @internal Get the accumulated status code. */

package/src/index.ts

@@ -9,14 +9,17 @@ import 'reflect-metadata'
 // ─── Core ───────────────────────────────────────────────────
 
 export { Application } from './Application.js'
-export { ConfigStore, defineModuleConfig, env } from './ConfigLoader.js'
+export { ConfigStore, configProvider, defineModuleConfig, env } from './ConfigLoader.js'
 export { Container } from './container/Container.js'
 export type { Binding, ServiceFactory, ServiceScope, ServiceToken } from './container/types.js'
 export { Env, EnvValidationException } from './env/Env.js'
 export { loadEnvFiles } from './env/loadEnvFiles.js'
+export { Secret } from './env/Secret.js'
 export {
   EnvVarError,
+  type OptionalCondition,
   type RequiredNode,
+  type SchemaFnOptions,
   type SchemaNode,
   type StringOptions,
 } from './env/schema.js'
@@ -24,6 +27,7 @@ export {
 // ─── HTTP (new — AdonisJS-compatible) ───────────────────────
 
 export {
+  createError,
   E_FORBIDDEN,
   E_HTTP_EXCEPTION,
   E_ROUTE_NOT_FOUND,
@@ -31,7 +35,12 @@ export {
   E_UNAUTHORIZED,
   E_VALIDATION_ERROR,
   Exception,
+  type ExceptionClass,
+  type ExceptionConstructor,
   ExceptionHandler,
+  InvalidArgumentsException,
+  RuntimeException,
+  type StatusPageRenderer,
 } from './http/Exception.js'
 export type { Authorizer, AuthState, RouteInfo } from './http/HttpContext.js'
 export { HttpContext } from './http/HttpContext.js'
@@ -39,6 +48,7 @@ export { RedirectBuilder } from './http/RedirectBuilder.js'
 export type { RawRequest } from './http/Request.js'
 export { Request } from './http/Request.js'
 export { Response } from './http/Response.js'
+export { type GetterFn, Macroable, type MacroFn } from './utils/Macroable.js'
 
 // ─── Session ────────────────────────────────────────────────
 
@@ -116,7 +126,6 @@ export { SignedUrl } from './security/SignedUrl.js'
 
 // ─── Decorators ─────────────────────────────────────────────
 
-export { createLazyProxy, getLazyParams, Lazy } from './decorators/Lazy.js'
 export {
   clearServiceRegistry,
   getServiceMetadata,

package/src/middleware/Pipeline.ts

@@ -138,7 +138,7 @@ function createGuardMiddleware(
   return async (ctx, next) => {
     const needsAuth =
       guards.length > 0 || (roles && roles.length > 0) || (permissions && permissions.length > 0)
-    if (needsAuth && !ctx.auth.authenticated) {
+    if (needsAuth && !ctx.auth.isAuthenticated) {
       throw new E_UNAUTHORIZED()
     }
 

package/src/openapi/OpenApiProvider.ts

@@ -47,8 +47,8 @@ export class OpenApiProvider extends Provider {
     const config = this.app.config.get<OpenApiDocsConfig>('openapi') ?? {}
     if (config.enabled === false) return
 
-    const generator = this.#override ?? this.#buildGenerator(config)
-    const server = this.app.container.make<Server>('server')
+    const generator = this.#override ?? (await this.#buildGenerator(config))
+    const server = await this.app.container.make<Server>('server')
     const middleware = new OpenApiMiddleware({
       specPath: config.specPath,
       docsPath: config.docsPath,
@@ -57,8 +57,8 @@ export class OpenApiProvider extends Provider {
     server.use([(ctx, next) => middleware.handle(ctx, next)])
   }
 
-  #buildGenerator(config: OpenApiDocsConfig): OpenApiGenerator {
-    const router = this.app.container.make<Router>('router')
+  async #buildGenerator(config: OpenApiDocsConfig): Promise<OpenApiGenerator> {
+    const router = await this.app.container.make<Router>('router')
     return new OpenApiGenerator(router, {
       title: config.title ?? 'API',
       version: config.version ?? '1.0.0',