@c9up/ream 0.2.28 → 0.2.30

package/src/events/Emitter.ts

@@ -96,6 +96,8 @@ export class Emitter {
   #fakedEvents?: Set<BufferedEventName>
   /** Wildcard subscriptions, so `offAny(listener)` can find its Rust handle. */
   readonly #anySubscriptions = new Map<(eventName: string, data: unknown) => void, Set<number>>()
+  /** Observers told of every emission as it happens — see {@link tap}. */
+  readonly #taps = new Set<(event: string, data: unknown) => void>()
 
   constructor(bus: EventBus, resolver?: EmitterResolver) {
     this.#bus = bus
@@ -227,6 +229,34 @@ export class Emitter {
 
   // ─── Emit ─────────────────────────────────────────────────
 
+  /**
+   * Watch every emission — string and class-based — as it happens.
+   *
+   * Development tooling: the profiler's events panel. `onAny` is not enough for
+   * it, because a wildcard subscription goes through the native bus and is
+   * called later, outside the request that emitted. A tap runs synchronously,
+   * in the emitting code's own async context, before any listener.
+   *
+   * It observes and nothing more: it sees a faked event too, it cannot change
+   * or cancel the emission, and a tap that throws is ignored.
+   */
+  tap(observer: (event: string, data: unknown) => void): UnsubscribeFunction {
+    this.#taps.add(observer)
+    return () => {
+      this.#taps.delete(observer)
+    }
+  }
+
+  #notifyTaps(event: string, data: unknown): void {
+    for (const observer of this.#taps) {
+      try {
+        observer(event, data)
+      } catch {
+        // Observation must never break the emission it watches.
+      }
+    }
+  }
+
   /**
    * Run an event's listeners, in parallel or one after another.
    *
@@ -235,10 +265,9 @@ export class Emitter {
    * event it does not own.
    */
   async #dispatchListeners(event: string, data: unknown, serial: boolean): Promise<void> {
-    const listeners = [
-      ...(this.#stringListeners.get(event) ?? []),
-      ...this.#wildcardListenersFor(event),
-    ]
+    // `onAny` listeners are not here: they subscribe through the native bus,
+    // which delivers every matching event to them on its own.
+    const listeners = this.#stringListeners.get(event) ?? []
     if (listeners.length === 0) return
     const run = async (fn: ListenerFn): Promise<void> => {
       try {
@@ -254,17 +283,13 @@ export class Emitter {
     await Promise.all(listeners.map(run))
   }
 
-  /** Listeners registered through `onAny` whose pattern matches `event`. */
-  #wildcardListenersFor(_event: string): ListenerFn[] {
-    return []
-  }
-
   /**
    * Emit and run the listeners ONE AT A TIME (AdonisJS `emitSerial`).
    *
    * Use it when order matters — a listener that seeds what the next one reads.
    */
   async emitSerial(event: string, data: unknown): Promise<void> {
+    this.#notifyTaps(event, data)
     if (this.#capture(event, data)) return
     await this.#dispatchListeners(event, data, true)
     this.#publishToBus(event, data)
@@ -282,6 +307,7 @@ export class Emitter {
    * rejects is reported through `emitError`, never left unhandled.
    */
   async emit(event: string, data: unknown): Promise<void> {
+    this.#notifyTaps(event, data)
     if (this.#capture(event, data)) return
     await this.#dispatchListeners(event, data, false)
     this.#publishToBus(event, data)
@@ -331,11 +357,12 @@ export class Emitter {
    */
   async dispatchEvent<T extends object>(event: T): Promise<void> {
     const EventClass = event.constructor as EventConstructor<T>
+    const name = (EventClass as { eventName?: string }).eventName ?? classToEventName(EventClass)
+    this.#notifyTaps(name, event)
     // Faked by the class, as AdonisJS does — `fake([TaskDeclared])` catches
     // `new TaskDeclared(...).emit()`.
     if (this.#capture(EventClass, event)) return
     const listeners = this.#classListeners.get(EventClass) ?? []
-    const name = (EventClass as { eventName?: string }).eventName ?? classToEventName(EventClass)
 
     // Per-listener error isolation — mirrors the string `emit()` contract.
     // A side-effect listener that throws (SMTP down, etc.) MUST NOT abort

package/src/events/helix/helpers.ts

@@ -15,6 +15,16 @@ export interface CollectedEvent {
   [key: string]: unknown
 }
 
+function isCollectedEvent(value: unknown): value is CollectedEvent {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'name' in value &&
+    typeof value.name === 'string' &&
+    'data' in value
+  )
+}
+
 export interface CollectResult {
   events: CollectedEvent[]
   subId: number
@@ -34,15 +44,17 @@ interface BusLike {
 export function collect(bus: BusLike, pattern: string): CollectResult {
   const events: CollectedEvent[] = []
   const subId = bus.subscribe(pattern, (eventJson: string) => {
+    const unreadable: CollectedEvent = {
+      _raw: eventJson,
+      _parseError: true,
+      name: '',
+      data: undefined,
+    }
     try {
-      events.push(JSON.parse(eventJson) as CollectedEvent)
+      const parsed: unknown = JSON.parse(eventJson)
+      events.push(isCollectedEvent(parsed) ? parsed : unreadable)
     } catch {
-      events.push({
-        _raw: eventJson,
-        _parseError: true,
-        name: '',
-        data: undefined,
-      } as CollectedEvent)
+      events.push(unreadable)
     }
   })
   return { events, subId }
@@ -233,20 +245,13 @@ function partialMatch(actual: unknown, expected: unknown): boolean {
 
   if (Array.isArray(expected)) {
     if (!Array.isArray(actual)) return false
-    return expected.every(
-      (item, i) => i < (actual as unknown[]).length && partialMatch((actual as unknown[])[i], item),
-    )
+    const items: unknown[] = actual
+    return expected.every((item, i) => i < items.length && partialMatch(items[i], item))
   }
 
-  for (const key of Object.keys(expected as object)) {
-    if (!(key in (actual as object))) return false
-    if (
-      !partialMatch(
-        (actual as Record<string, unknown>)[key],
-        (expected as Record<string, unknown>)[key],
-      )
-    )
-      return false
+  for (const key of Object.keys(expected)) {
+    if (!(key in actual)) return false
+    if (!partialMatch(Reflect.get(actual, key), Reflect.get(expected, key))) return false
   }
   return true
 }

package/src/graphql/GraphQLEngine.ts

@@ -24,7 +24,9 @@
 import * as fs from 'node:fs'
 import { currentNodeEnv } from '../env/nodeEnv.js'
 import { loadNapi } from '../helpers/napi-loader.js'
+import { Exception } from '../http/Exception.js'
 import type { HttpContext } from '../http/HttpContext.js'
+import { holdsPermissions } from '../http/permissions.js'
 
 /** Rust parser output (the `ream-graphql` crate via the `index` NAPI binary). */
 interface RustParsedField {
@@ -169,6 +171,14 @@ export interface GraphQLConfig {
    * (default: 1000).
    */
   maxComplexity?: number
+  /**
+   * Echo the message of any error a resolver throws to the client. Default:
+   * only when NODE_ENV is development. Otherwise only a deliberate
+   * `Exception`, a client error (status below 500) or an error flagged
+   * `expose: true` keeps its message; anything else reads "Internal server
+   * error", and the real error goes to `ctx.logger`.
+   */
+  debug?: boolean
 }
 
 export interface ResolverOptions {
@@ -207,6 +217,7 @@ export class GraphQLEngine {
   #container?: { make<T>(target: abstract new (...args: never[]) => T): Promise<T> }
   readonly path: string
   #playground: boolean
+  readonly #debug: boolean
   #maxQueryBytes: number
   #maxDepth: number
   #maxComplexity: number
@@ -236,6 +247,7 @@ export class GraphQLEngine {
     this.#maxQueryBytes = config.maxQueryBytes ?? 100_000
     this.#maxDepth = config.maxDepth ?? 12
     this.#maxComplexity = config.maxComplexity ?? 1000
+    this.#debug = config.debug ?? currentNodeEnv() === 'development'
   }
 
   /** Set IoC container for resolver instantiation. */
@@ -279,8 +291,19 @@ export class GraphQLEngine {
       return
     }
 
-    const rawBody = ctx.request.body()
-    const body = parseGraphQLBody(rawBody)
+    // Only a JSON body is a GraphQL request. A form post, a text/plain body or
+    // one with no Content-Type is a CORS simple request: a foreign page sends
+    // it with the user's cookies and no preflight, so a mutation would run
+    // cross-site. Refused before the body is read.
+    const mediaType = (ctx.request.header('content-type')?.split(';')[0] ?? '').trim().toLowerCase()
+    if (mediaType !== 'application/json') {
+      ctx.response.status(415).json({ errors: [{ message: 'Unsupported Media Type' }] })
+      return
+    }
+
+    // Read from the raw body rather than `request.body()`, so the endpoint
+    // works whether or not the body parser runs in front of it.
+    const body = parseGraphQLBody(parseJson(ctx.request.raw()))
     if (!body) {
       ctx.response.status(400).json({ errors: [{ message: 'Missing or invalid query' }] })
       return
@@ -290,11 +313,7 @@ export class GraphQLEngine {
       const result = await this.#execute(body, ctx)
       ctx.response.status(200).json(result)
     } catch (err) {
-      const message =
-        currentNodeEnv() !== 'production' && err instanceof Error
-          ? err.message
-          : 'Internal server error'
-      ctx.response.status(500).json({ errors: [{ message }] })
+      ctx.response.status(500).json({ errors: [{ message: this.#publicMessage(err, ctx) }] })
     }
   }
 
@@ -364,7 +383,7 @@ export class GraphQLEngine {
       }
     }
 
-    const guardError = this.#enforceGuards(entry.options, ctx)
+    const guardError = await this.#enforceGuards(entry.options, ctx)
     if (guardError) {
       return { ok: false, error: { message: guardError, path: [field.name] } }
     }
@@ -395,11 +414,26 @@ export class GraphQLEngine {
       // ask for. Empty selection (scalar field) returns the value as-is.
       return { ok: true, value: pruneToSelection(result, field.selection) }
     } catch (err) {
-      const msg = err instanceof Error ? err.message : 'Resolver error'
-      return { ok: false, error: { message: msg, path: [field.name] } }
+      return { ok: false, error: { message: this.#publicMessage(err, ctx), path: [field.name] } }
     }
   }
 
+  /**
+   * The message a client may see for a thrown error — the rule the HTTP
+   * exception handler applies. A driver or library error carries internal
+   * hosts, credentials and stored values in its text, so outside debug it is
+   * collapsed, and the original is logged for the operator instead.
+   */
+  #publicMessage(err: unknown, ctx: HttpContext): string {
+    const message = err instanceof Error ? err.message : String(err)
+    if (this.#debug || isPublicError(err)) return message
+    ctx.logger.error('GraphQL resolver failed', {
+      message,
+      stack: err instanceof Error ? err.stack : undefined,
+    })
+    return 'Internal server error'
+  }
+
   /**
    * Build the resolver argument bag: `$variable` references resolve against
    * `request.variables`, then any unreferenced variables are merged in.
@@ -435,7 +469,7 @@ export class GraphQLEngine {
   }
 
   /** Enforce guard/role/permission on a resolver. */
-  #enforceGuards(options: ResolverOptions, ctx: HttpContext): string | null {
+  async #enforceGuards(options: ResolverOptions, ctx: HttpContext): Promise<string | null> {
     const guards = [...(options.guards ?? []), ...(options.guard ? [options.guard] : [])]
     const roles = [...(options.roles ?? []), ...(options.role ? [options.role] : [])]
     const permissions = options.permissions ?? []
@@ -455,9 +489,9 @@ export class GraphQLEngine {
       }
     }
 
+    // A token-authenticated request also needs the token to allow each one.
     if (permissions.length > 0) {
-      const userPerms = ctx.auth?.permissions ?? ctx.auth?.user?.permissions ?? []
-      if (!permissions.every((p) => userPerms.includes(p))) {
+      if (!(await holdsPermissions(ctx.auth, permissions))) {
         return 'Insufficient permissions'
       }
     }
@@ -477,7 +511,10 @@ export class GraphQLEngine {
     // Full-Rust: the spec-compliant `ream-graphql` parser (graphql-parser
     // crate) rejects invalid queries before any resolver runs. No TS fallback —
     // ream ships the native binary, so when Rust exists the engine is Rust.
-    const raw = JSON.parse(graphqlNative().graphqlParse(query)) as RustParseResult
+    const raw: unknown = JSON.parse(graphqlNative().graphqlParse(query))
+    if (!isRustParseResult(raw)) {
+      return { typeName: 'Query', fields: [], errors: [{ message: 'Unreadable parse result' }] }
+    }
     const typeName = OPERATION_TYPE[raw.operation_type] ?? 'Query'
     if (raw.errors.length > 0) {
       return { typeName, fields: [], errors: raw.errors.map((message) => ({ message })) }
@@ -519,6 +556,22 @@ function isVariablesRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
+/** A deliberate `Exception`, a client error, or an error flagged `expose: true`. */
+function isPublicError(err: unknown): boolean {
+  if (err instanceof Exception) return true
+  if (err === null || typeof err !== 'object') return false
+  if ('expose' in err && err.expose === true) return true
+  return 'status' in err && typeof err.status === 'number' && err.status < 500
+}
+
+function parseJson(raw: string): unknown {
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return undefined
+  }
+}
+
 function parseGraphQLBody(body: unknown): GraphQLRequest | null {
   if (!body || typeof body !== 'object' || Array.isArray(body)) return null
   // After typeof check, body is a non-null non-array object; index via 'in' narrowing
@@ -536,6 +589,30 @@ function parseGraphQLBody(body: unknown): GraphQLRequest | null {
   return { query: q, variables, operationName }
 }
 
+/** The shape the native parser answers with, checked rather than assumed. */
+function isRustParseResult(value: unknown): value is RustParseResult {
+  if (!isRecord(value)) return false
+  return (
+    typeof value.operation_type === 'string' &&
+    (value.operation_name === null || typeof value.operation_name === 'string') &&
+    Array.isArray(value.errors) &&
+    value.errors.every((error) => typeof error === 'string') &&
+    Array.isArray(value.fields) &&
+    value.fields.every(isRustParsedField)
+  )
+}
+
+function isRustParsedField(value: unknown): value is RustParsedField {
+  if (!isRecord(value)) return false
+  return (
+    typeof value.name === 'string' &&
+    (value.alias === null || typeof value.alias === 'string') &&
+    isRecord(value.args) &&
+    Array.isArray(value.sub_fields) &&
+    value.sub_fields.every(isRustParsedField)
+  )
+}
+
 function isRecord(v: unknown): v is Record<string, unknown> {
   return typeof v === 'object' && v !== null && !Array.isArray(v)
 }

package/src/helpers/MessageBuilder.ts

@@ -7,8 +7,10 @@
  * 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.
+ * Ported from `@poppinss/utils`, as a helper for application code. Ream's own
+ * signers do not use it: `CookieSigner` seals its values in a compact envelope
+ * of its own (`{ m, e, p }`, an epoch-millisecond expiry), and `SignedUrl`
+ * carries the expiry and the purpose as query parameters.
  */
 
 import { milliseconds } from './duration.js'

package/src/helpers/errors.ts

@@ -0,0 +1,16 @@
+/**
+ * A caught value as the `NodeJS.ErrnoException` an error callback takes.
+ *
+ * `catch` binds `unknown`: an `Error` already is one (every field it adds is
+ * optional), and anything else thrown is wrapped, so a callback never reads
+ * `.code` or `.message` off a string.
+ */
+export function toErrnoException(error: unknown): NodeJS.ErrnoException {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+/** The `code` of a caught system error (`ENOENT`, `MODULE_NOT_FOUND`…), if any. */
+export function errorCode(error: unknown): string | undefined {
+  if (typeof error !== 'object' || error === null || !('code' in error)) return undefined
+  return typeof error.code === 'string' ? error.code : undefined
+}

package/src/helpers/napi-loader.ts

@@ -12,6 +12,7 @@ import { dirname, join } from 'node:path'
 import { arch, platform } from 'node:process'
 import { fileURLToPath } from 'node:url'
 import { ReamError } from '../errors/ReamError.js'
+import { errorCode } from './errors.js'
 
 /**
  * Platform triple suffix (matches napi-rs naming).
@@ -88,14 +89,14 @@ export function loadNapi<T>(options: LoadNapiOptions): T {
     try {
       return req(path) as T
     } catch (e) {
-      const code = (e as NodeJS.ErrnoException | undefined)?.code
+      const code = errorCode(e)
       if (code === 'MODULE_NOT_FOUND') continue
       // Any other error (SyntaxError, ABI mismatch, permissions,
       // corrupt binary) means the file exists but cannot load. Surface
       // the real cause rather than a generic "not found".
       throw new ReamError(
         `${errorCodePrefix}_NAPI_LOAD_FAILED`,
-        `${binaryName} NAPI binary exists at '${path}' but failed to load: ${(e as Error).message}`,
+        `${binaryName} NAPI binary exists at '${path}' but failed to load: ${e instanceof Error ? e.message : String(e)}`,
         {
           hint: 'Check that the binary was built for the current platform and Node ABI. Rebuild with `pnpm --filter @c9up/ream build:rust`.',
         },

package/src/http/Exception.ts

@@ -259,6 +259,12 @@ export type HttpError = {
   report?: (error: unknown, ctx: HttpContext) => Promise<void> | void
   /** A hint appended to the message, when the exception carries one. */
   help?: string
+  /**
+   * Set by a thrown value that is not an {@link Exception} but whose message is
+   * written for clients (the `http-errors` convention). Shown outside debug
+   * mode even on a 5xx.
+   */
+  expose?: boolean
 }
 
 /** Renders an HTML error page for a status (AdonisJS `StatusPageRenderer`). */
@@ -352,13 +358,22 @@ export class ExceptionHandler extends Macroable {
    * The message a client is allowed to see.
    *
    * DEVIATION (named): outside debug mode ream only echoes the message of a
-   * deliberate `Exception`; anything else collapses to a generic line. AdonisJS
+   * deliberate `Exception`, of a client error (status below 500, which a
+   * package raises on purpose: 401, 403, 413…), or of an error flagged
+   * `expose: true`; anything else collapses to a generic line. AdonisJS
    * echoes `error.message` whatever was thrown, which leaks the text of driver
    * and library errors to the client.
+   *
+   * A `code` is NOT a reason to show the message: Node system errors
+   * (`ECONNREFUSED`, `ENOENT`) and database drivers (`23505`) carry one, and
+   * their messages hold internal hosts, file paths, constraint names and
+   * stored values. The error itself is left untouched for reporting.
    */
   protected publicMessage(error: HttpError, ctx: HttpContext): string {
     if (this.isDebuggingEnabled(ctx)) return error.message
-    if (error.code !== 'E_UNKNOWN') return error.message
+    if (error instanceof Exception || error.status < 500 || error.expose === true) {
+      return error.message
+    }
     return 'An internal error occurred'
   }
 

package/src/http/HttpContext.ts

@@ -33,7 +33,14 @@ export interface AuthState {
     id: string
     email?: string
     roles?: string[]
+    /** The user's own permissions — never widened by a token's abilities. */
     permissions?: string[]
+    /**
+     * Set by a token guard (AdonisJS `user.currentAccessToken`): the token this
+     * request authenticated with. Its abilities restrict the user's
+     * permissions on every `.permission()` gate; they never add to them.
+     */
+    currentAccessToken?: AccessTokenAbilities
     [key: string]: unknown
   }
   roles?: string[]
@@ -48,6 +55,16 @@ export interface AuthState {
   check?(): Promise<boolean>
   authenticateUsing?(guards?: string[], options?: { loginRoute?: string }): Promise<void>
   getUserOrFail?(): AuthState['user']
+  /**
+   * Whether the authenticated user holds every permission in `permissions`,
+   * as the auth layer resolves them (warden's authenticator asks its rights
+   * resolver and narrows by the current access token). When present, the
+   * `.permission()` gates trust this answer instead of the payload's
+   * `permissions`, which can be stale or incomplete. `scope` is the auth
+   * layer's own notion (warden: `'global'` or a tenant); the gates pass none,
+   * so the layer's default applies.
+   */
+  hasAllPermissions?(permissions: readonly string[], scope?: unknown): Promise<boolean>
   /**
    * The guard behind `name` (AdonisJS `auth.use('web')`).
    *
@@ -65,6 +82,11 @@ export interface AuthState {
   readonly authenticatedViaGuard?: string
 }
 
+/** What a permission gate needs from an access token: whether it allows an ability. */
+export interface AccessTokenAbilities {
+  allows(ability: string): boolean
+}
+
 /**
  * Per-request authorization entry point — populated by an authorization
  * middleware (e.g. `@c9up/warden`'s Bouncer initializer). A structural
@@ -393,10 +415,16 @@ export class HttpContext extends Macroable {
     this.request.setSignedUrl(signedUrl)
   }
 
-  /** Subdomains of the request host (AdonisJS `ctx.subdomains`). */
-  get subdomains(): string[] {
-    return this.request.subdomains()
-  }
+  /**
+   * The values the matched route's domain captured from the host:
+   * `{ tenant: 'acme' }` for a route on `:tenant.app.test` reached through
+   * `acme.app.test`. Empty when the route has no parameterised domain. Set by
+   * the HTTP kernel from the route match, as upstream's router does.
+   *
+   * BREAKING — this used to be the host's labels (`['api']`); that is
+   * `ctx.request.subdomains()`, and stays there.
+   */
+  subdomains: Record<string, string> = {}
 
   /** Stable identifier for the matched route (`METHOD-pattern`) — AdonisJS `ctx.routeKey`. */
   get routeKey(): string {
@@ -440,8 +468,9 @@ export class HttpContext extends Macroable {
     this.response.setRedirectFactory(
       () =>
         new RedirectBuilder(this.response, {
-          requestUrl: this.request.url(),
+          requestUrl: this.request.url(true),
           requestReferer: this.request.header('referer'),
+          requestAuthority: this.request.authority() ?? undefined,
           routeUrlResolver: this.#routeUrlResolver,
         }),
     )