@c9up/ream 0.2.29 → 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,6 +24,7 @@
 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'
 
@@ -170,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 {
@@ -208,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
@@ -237,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. */
@@ -280,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
@@ -291,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) }] })
     }
   }
 
@@ -365,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] } }
     }
@@ -396,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.
@@ -436,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 ?? []
@@ -458,7 +491,7 @@ export class GraphQLEngine {
 
     // A token-authenticated request also needs the token to allow each one.
     if (permissions.length > 0) {
-      if (!holdsPermissions(ctx.auth, permissions)) {
+      if (!(await holdsPermissions(ctx.auth, permissions))) {
         return 'Insufficient permissions'
       }
     }
@@ -478,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 })) }
@@ -520,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
@@ -537,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/HttpContext.ts

@@ -55,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')`).
    *
@@ -405,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 {

package/src/http/RedirectBuilder.ts

@@ -32,6 +32,9 @@ function isTrustedRedirect(
   } catch {
     return false
   }
+  // Only a web URL is a redirect target: `javascript://app.test/%0aalert(1)`
+  // has the right host and is a script, not a page.
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false
   if (allowedHosts.includes(parsed.host)) return true
   // Upstream accepts any absolute URL when it knows no host to compare with;
   // refusing it is the safer reading of an attacker-controlled header.

package/src/http/Request.ts

@@ -478,7 +478,9 @@ export class Request extends Macroable {
   encryptedCookie(name: string, defaultValue?: string): string | null
   encryptedCookie(name: string, defaultValue?: string): string | null {
     const raw = this.plainCookie<string>(name, undefined, { encoded: false })
-    const value = raw === null || !this.#cookieSigner ? null : this.#cookieSigner.decrypt(raw)
+    // Decrypted for the purpose it was written under — its own name — so a
+    // value issued as another encrypted cookie is refused here.
+    const value = raw === null || !this.#cookieSigner ? null : this.#cookieSigner.decrypt(raw, name)
     return value ?? defaultValue ?? null
   }
 
@@ -757,7 +759,9 @@ export class Request extends Macroable {
       cookies: this.cookies(),
       hostname: this.hostname(),
       ip: this.ip(),
-      subdomains: this.subdomains(),
+      // What the route's domain captured (`ctx.subdomains`), as upstream
+      // serialises it — not the host's labels, which `subdomains()` returns.
+      subdomains: (this.ctx === undefined ? undefined : Reflect.get(this.ctx, 'subdomains')) ?? {},
     }
   }
 
@@ -1119,39 +1123,21 @@ export class Request extends Macroable {
     }
   }
 
+  /**
+   * The body is whatever the body parser decided it is, and `{}` when no
+   * parser claimed it. Nothing is parsed here: a JSON body is only JSON when
+   * its Content-Type says so. Reading any body as JSON let a foreign page
+   * drive a JSON route with a CORS simple request (no Content-Type, or
+   * `text/plain`), which a browser sends cross-site with the user's cookies
+   * and without a preflight.
+   */
   #ensureParsedBody(): void {
     if (this.#parsedBody !== undefined) return
     this.#assertBodyKept()
-    const raw = this.#raw.body
-    if (!raw || raw.length === 0) {
-      this.#parsedBody = {}
-      return
-    }
-    try {
-      const parsed: unknown = JSON.parse(raw)
-      this.#parsedBody = isPlainObject(parsed) ? parsed : { _body: parsed }
-    } catch {
-      this.#parsedBody = {}
-    }
+    this.#parsedBody = {}
   }
 }
 
-/** Parse a query string (key=value&key2=value2) into an object. */
-/**
- * Test whether an IPv4 address is within a CIDR range. Bare IP entries
- * (`10.0.0.42`) are accepted as `/32`. IPv6 falls back to string equality
- * — a full v6 implementation isn't required by the current security tests.
- */
-/**
- * Type guard for plain JSON-decoded objects. Excludes `null` (which is
- * `typeof === 'object'`) and arrays so consumers can index by string key
- * without a separate runtime check.
- */
-function isPlainObject(value: unknown): value is Dict<unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-/** True for an IPv4 dotted-quad or a (bracketed) IPv6 literal — hosts with no subdomains. */
 /**
  * Headers whose VALUE is a credential. Listing them is useful; printing them
  * hands whoever reads the log a working key.

package/src/http/Response.ts

@@ -13,6 +13,7 @@ import { readFile, stat } from 'node:fs/promises'
 import { basename } from 'node:path'
 import { ReamError } from '../errors/ReamError.js'
 import { durationToSeconds } from '../helpers/duration.js'
+import { toErrnoException } from '../helpers/errors.js'
 import { etag, matchesIfNoneMatch } from './etag.js'
 import { contentType } from './mime.js'
 
@@ -848,7 +849,7 @@ export class Response extends Macroable {
       size = (await stat(filePath)).size
     } catch (error) {
       if (errorCallback) {
-        const [message, status] = errorCallback(error as NodeJS.ErrnoException)
+        const [message, status] = errorCallback(toErrnoException(error))
         this.status(status ?? 404).send(message)
         return
       }
@@ -1002,7 +1003,7 @@ export class Response extends Macroable {
       // The headers are already out, so there is no status left to change: end
       // the body and let the client see a short read. `errorCallback` is still
       // consulted for whatever logging it does.
-      errorCallback?.(err as NodeJS.ErrnoException)
+      errorCallback?.(toErrnoException(err))
     } finally {
       // Never rethrows: this runs detached, and an unhandled rejection here
       // would take the process down over one client's download.
@@ -1022,7 +1023,7 @@ export class Response extends Macroable {
       }
     } catch (err) {
       const [message, status] = errorCallback
-        ? errorCallback(err as NodeJS.ErrnoException)
+        ? errorCallback(toErrnoException(err))
         : ['Cannot process the request', 500]
       this.status(status ?? 500)
       this.send(message)
@@ -1133,7 +1134,9 @@ export class Response extends Macroable {
         'encryptedCookie() requires APP_KEY — set it so the encryption service is registered.',
       )
     }
-    return this.#writeCookie(name, this.#cookieSigner.encrypt(value), options)
+    // The cookie name is the purpose, as for a signed cookie: a value issued
+    // as one encrypted cookie cannot be replayed under another one's name.
+    return this.#writeCookie(name, this.#cookieSigner.encrypt(value, undefined, name), options)
   }
 
   #writeCookie(name: string, value: string, options?: CookieOptions): this {
@@ -1195,10 +1198,15 @@ export class Response extends Macroable {
 
   /**
    * Expire a cookie immediately (AdonisJS `clearCookie`) — re-sends it with
-   * `Max-Age=0`, the RFC 6265 delete-now signal that `cookie()` honours.
+   * `Max-Age=0` and an `Expires` in 1970, the RFC 6265 delete-now signals.
+   *
+   * A browser matches the cookie to replace on its name, domain and path, so
+   * a cookie written with a `domain` (or a `path`) is only cleared when the
+   * same ones are passed here; `secure` and `sameSite` are accepted so a
+   * `SameSite=None` cookie can be cleared at all.
    */
-  clearCookie(name: string, options?: { path?: string }): this {
-    return this.plainCookie(name, '', { ...options, maxAge: 0 })
+  clearCookie(name: string, options?: Omit<CookieOptions, 'maxAge' | 'expires'>): this {
+    return this.plainCookie(name, '', { ...options, maxAge: 0, expires: new Date(0) })
   }
 
   // ─── Internals (used by HttpKernel for NAPI serialization) ─

package/src/http/permissions.ts

@@ -9,23 +9,39 @@ import type { AuthState } from './HttpContext.js'
  * Whether the request's identity holds every permission in `required` — what
  * the route, RPC and GraphQL `.permission()` gates ask.
  *
- * The permissions are the user's own (top-level `auth.permissions`, or
- * `auth.user.permissions` where warden puts them). When the request was
- * authenticated with a token, each permission must ALSO be allowed by
- * `auth.user.currentAccessToken`: an intersection, never a union. A token
- * scope named like a permission grants nothing the user lacks, and a token
- * limited to `profile` does not carry every permission of its user. A token
- * whose `allows` cannot be called denies.
+ * When the auth state exposes `hasAllPermissions` (the auth layer resolves
+ * permissions itself, as warden does through its rights resolver), its
+ * answer decides: a permission granted only by the resolver passes, one left
+ * only in the payload does not. Anything but `true` denies, and an error from
+ * the resolver propagates rather than grants. Only an auth state without that
+ * method falls back to the payload: top-level `auth.permissions`, or
+ * `auth.user.permissions`.
+ *
+ * When the request was authenticated with a token, each permission must ALSO
+ * be allowed by `auth.user.currentAccessToken`: an intersection, never a
+ * union. A token scope named like a permission grants nothing the user
+ * lacks, and a token limited to `profile` does not carry every permission of
+ * its user. A token whose `allows` cannot be called denies.
  */
-export function holdsPermissions(
+export async function holdsPermissions(
   auth: AuthState | undefined,
   required: readonly string[],
-): boolean {
-  const granted = auth?.permissions ?? auth?.user?.permissions ?? []
+): Promise<boolean> {
+  if (!(await userHolds(auth, required))) return false
   const token = auth?.user?.currentAccessToken
-  return required.every((permission) => {
-    if (!granted.includes(permission)) return false
-    if (token === undefined || token === null) return true
-    return typeof token.allows === 'function' && token.allows(permission) === true
-  })
+  if (token === undefined || token === null) return true
+  return required.every(
+    (permission) => typeof token.allows === 'function' && token.allows(permission) === true,
+  )
+}
+
+async function userHolds(
+  auth: AuthState | undefined,
+  required: readonly string[],
+): Promise<boolean> {
+  if (typeof auth?.hasAllPermissions === 'function') {
+    return (await auth.hasAllPermissions(required)) === true
+  }
+  const granted = auth?.permissions ?? auth?.user?.permissions ?? []
+  return required.every((permission) => granted.includes(permission))
 }