@c9up/ream 0.2.27 → 0.2.29

package/src/codemods/source.ts

@@ -0,0 +1,303 @@
+/**
+ * Just enough of a TypeScript scanner for the configure codemods: find a
+ * call or an object/array literal in CODE (never inside a string, a template
+ * or a comment), split a literal into its top-level entries, and append to
+ * one. Upstream does this with a full AST; ream ships no compiler, and the
+ * files these codemods edit (`start/env.ts`, `reamrc.ts`) are object and
+ * array literals.
+ *
+ * Not handled: regular-expression literals (a quote inside one reads as the
+ * start of a string). Neither file has a reason to contain one.
+ */
+
+const CLOSERS: Record<string, string> = { '{': '}', '[': ']', '(': ')' }
+
+function isIdentifierChar(char: string | undefined): boolean {
+  return char !== undefined && /[A-Za-z0-9_$]/.test(char)
+}
+
+/**
+ * The index just past the string, template or comment starting at `i`, or
+ * `i` itself when none starts there. An unterminated one runs to the end.
+ */
+function skipNonCode(src: string, i: number): number {
+  const char = src[i]
+  const next = src[i + 1]
+  if (char === '/' && next === '/') {
+    const end = src.indexOf('\n', i)
+    return end === -1 ? src.length : end
+  }
+  if (char === '/' && next === '*') {
+    const end = src.indexOf('*/', i + 2)
+    return end === -1 ? src.length : end + 2
+  }
+  if (char === "'" || char === '"') {
+    let j = i + 1
+    while (j < src.length && src[j] !== char && src[j] !== '\n') {
+      j += src[j] === '\\' ? 2 : 1
+    }
+    return j + 1
+  }
+  if (char === '`') {
+    let j = i + 1
+    while (j < src.length && src[j] !== '`') {
+      if (src[j] === '\\') {
+        j += 2
+      } else if (src[j] === '$' && src[j + 1] === '{') {
+        const close = matchClose(src, j + 1)
+        j = close === -1 ? src.length : close + 1
+      } else {
+        j += 1
+      }
+    }
+    return j + 1
+  }
+  return i
+}
+
+/** Whether the string, template or block comment starting at `i` is closed. */
+function isTerminated(src: string, i: number): boolean {
+  const char = src[i]
+  if (char === '/') return src.indexOf('*/', i + 2) !== -1
+  const end = skipNonCode(src, i)
+  return end <= src.length && end - 1 > i && src[end - 1] === char
+}
+
+/** Index of the bracket closing the one at `open`, or -1. */
+export function matchClose(src: string, open: number): number {
+  const first = CLOSERS[src[open] ?? '']
+  if (first === undefined) return -1
+  const stack = [first]
+  let i = open + 1
+  while (i < src.length) {
+    const skipped = skipNonCode(src, i)
+    if (skipped !== i) {
+      i = skipped
+      continue
+    }
+    const char = src[i] ?? ''
+    const closer = CLOSERS[char]
+    if (closer !== undefined) {
+      stack.push(closer)
+    } else if (char === stack[stack.length - 1]) {
+      stack.pop()
+      if (stack.length === 0) return i
+    } else if (char === '}' || char === ']' || char === ')') {
+      return -1
+    }
+    i += 1
+  }
+  return -1
+}
+
+/** First code character at or after `i` (before `end`), skipping whitespace and comments. */
+function firstCode(src: string, i: number, end: number): number {
+  let j = i
+  while (j < end) {
+    const char = src[j] ?? ''
+    if (/\s/.test(char)) {
+      j += 1
+      continue
+    }
+    if (char === '/' && (src[j + 1] === '/' || src[j + 1] === '*')) {
+      j = skipNonCode(src, j)
+      continue
+    }
+    return j
+  }
+  return end
+}
+
+/** One top-level entry of a literal: the text between two commas. */
+export interface Segment {
+  start: number
+  end: number
+  /** First code character, or `end` when the entry is only trivia. */
+  codeStart: number
+  /** Just past the last code character (comments and whitespace excluded). */
+  codeEnd: number
+}
+
+/** Split `src[start, end)` on its top-level commas. */
+export function segments(src: string, start: number, end: number): Segment[] {
+  const out: Segment[] = []
+  let segmentStart = start
+  let codeEnd = start
+  let depth = 0
+  let i = start
+  const close = (at: number) => {
+    const codeStart = firstCode(src, segmentStart, at)
+    out.push({ start: segmentStart, end: at, codeStart, codeEnd: Math.max(codeEnd, codeStart) })
+  }
+  while (i < end) {
+    const char = src[i] ?? ''
+    if (char === '/' && (src[i + 1] === '/' || src[i + 1] === '*')) {
+      i = skipNonCode(src, i)
+      continue
+    }
+    const skipped = skipNonCode(src, i)
+    if (skipped !== i) {
+      i = skipped
+      codeEnd = i
+      continue
+    }
+    if (char === ',' && depth === 0) {
+      close(i)
+      segmentStart = i + 1
+      codeEnd = i + 1
+      i += 1
+      continue
+    }
+    if (CLOSERS[char] !== undefined) depth += 1
+    else if (char === '}' || char === ']' || char === ')') depth -= 1
+    if (!/\s/.test(char)) codeEnd = i + 1
+    i += 1
+  }
+  close(end)
+  return out
+}
+
+/**
+ * Whether `code` is one complete expression that cannot reach outside the
+ * slot it is written into: brackets balanced and never closing past where
+ * they opened, strings and comments terminated, no top-level comma.
+ */
+export function isSingleExpression(code: string): boolean {
+  if (code.trim() === '') return false
+  let depth = 0
+  let i = 0
+  while (i < code.length) {
+    const skipped = skipNonCode(code, i)
+    if (skipped !== i) {
+      // A line comment would swallow the comma written after the value.
+      const lineComment = code[i] === '/' && code[i + 1] === '/'
+      if (lineComment || !isTerminated(code, i)) return false
+      i = skipped
+      continue
+    }
+    const char = code[i] ?? ''
+    if (CLOSERS[char] !== undefined) depth += 1
+    else if (char === '}' || char === ']' || char === ')') {
+      depth -= 1
+      if (depth < 0) return false
+    } else if (char === ',' && depth === 0) return false
+    i += 1
+  }
+  return depth === 0
+}
+
+/**
+ * Index of the `(` of the first call to `callee` in code, or -1. A mention
+ * inside a string or a comment, or as the tail of a longer name
+ * (`MyEnv.create`), does not count.
+ */
+export function findCall(src: string, callee: string): number {
+  let i = 0
+  while (i < src.length) {
+    const skipped = skipNonCode(src, i)
+    if (skipped !== i) {
+      i = skipped
+      continue
+    }
+    const before = src[i - 1]
+    if (src.startsWith(callee, i) && !isIdentifierChar(before) && before !== '.') {
+      const paren = firstCode(src, i + callee.length, src.length)
+      if (src[paren] === '(') return paren
+    }
+    i += 1
+  }
+  return -1
+}
+
+/** Index of the `{` after the first `export default` in code, or -1. */
+export function findExportDefaultObject(src: string): number {
+  let i = 0
+  while (i < src.length) {
+    const skipped = skipNonCode(src, i)
+    if (skipped !== i) {
+      i = skipped
+      continue
+    }
+    if (src.startsWith('export', i) && !isIdentifierChar(src[i - 1])) {
+      const word = firstCode(src, i + 'export'.length, src.length)
+      if (src.startsWith('default', word) && !isIdentifierChar(src[word + 'default'.length])) {
+        const brace = firstCode(src, word + 'default'.length, src.length)
+        return src[brace] === '{' ? brace : -1
+      }
+    }
+    i += 1
+  }
+  return -1
+}
+
+/** A `key: value` entry of an object literal. */
+export interface Property {
+  key: string
+  valueStart: number
+  valueEnd: number
+}
+
+/** The `key: value` entries of the object literal opening at `open`. */
+export function properties(src: string, open: number, close: number): Property[] {
+  const out: Property[] = []
+  for (const segment of segments(src, open + 1, close)) {
+    if (segment.codeStart >= segment.end) continue
+    const text = src.slice(segment.codeStart, segment.end)
+    const match = /^(?:([A-Za-z_$][\w$]*)|'([^'\\\n]*)'|"([^"\\\n]*)")\s*:/.exec(text)
+    if (match === null) continue
+    const key = match[1] ?? match[2] ?? match[3] ?? ''
+    const valueStart = firstCode(src, segment.codeStart + match[0].length, segment.end)
+    out.push({ key, valueStart, valueEnd: segment.codeEnd })
+  }
+  return out
+}
+
+/** Leading whitespace of the line holding `index`. */
+function lineIndent(src: string, index: number): string {
+  const lineStart = src.lastIndexOf('\n', index - 1) + 1
+  return /^[ \t]*/.exec(src.slice(lineStart))?.[0] ?? ''
+}
+
+/**
+ * Append entries to the literal `src[open..close]` and return the new text.
+ *
+ * `build` receives the indentation of the existing entries (or one level
+ * deeper than the closing bracket when there are none) and returns the lines
+ * to add, each already ending with its comma. `blankLine` separates the new
+ * entries from existing ones. A missing comma after the last existing entry
+ * is added.
+ */
+export function appendToLiteral(
+  src: string,
+  open: number,
+  close: number,
+  eol: string,
+  build: (indent: string) => string[],
+  blankLine = false,
+): string {
+  const all = segments(src, open + 1, close)
+  const entries = all.filter((s) => s.codeStart < s.end)
+  const first = entries[0]
+  const closeIndent = lineIndent(src, close)
+  const firstOnOwnLine =
+    first !== undefined &&
+    /^[ \t]*$/.test(src.slice(src.lastIndexOf('\n', first.codeStart - 1) + 1, first.codeStart))
+  const indent =
+    first !== undefined && firstOnOwnLine ? lineIndent(src, first.codeStart) : `${closeIndent}  `
+  const lines = build(indent)
+  const separator = blankLine && entries.length > 0 ? eol : ''
+
+  const closeLineStart = src.lastIndexOf('\n', close - 1) + 1
+  const closeOnOwnLine = /^[ \t]*$/.test(src.slice(closeLineStart, close))
+  let out = closeOnOwnLine
+    ? `${src.slice(0, closeLineStart)}${separator}${lines.join(eol)}${eol}${src.slice(closeLineStart)}`
+    : `${src.slice(0, close)}${eol}${separator}${lines.join(eol)}${eol}${closeIndent}${src.slice(close)}`
+
+  // The comma goes in last, as it sits before every insertion point above.
+  // No comma after the last entry when it is also the last segment.
+  const last = entries[entries.length - 1]
+  if (last !== undefined && all[all.length - 1] === last) {
+    out = `${out.slice(0, last.codeEnd)},${out.slice(last.codeEnd)}`
+  }
+  return out
+}

package/src/graphql/GraphQLEngine.ts

@@ -25,6 +25,7 @@ import * as fs from 'node:fs'
 import { currentNodeEnv } from '../env/nodeEnv.js'
 import { loadNapi } from '../helpers/napi-loader.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 {
@@ -455,9 +456,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 (!holdsPermissions(ctx.auth, permissions)) {
         return 'Insufficient permissions'
       }
     }

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[]
@@ -65,6 +72,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
@@ -440,8 +452,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,
         }),
     )

package/src/http/RedirectBuilder.ts

@@ -13,30 +13,36 @@ import type { Response } from './Response.js'
 
 export type RouteUrlResolver = (name: string, params?: Record<string, string>) => string
 
-function isSameOriginOrRelative(
-  referer: string,
-  requestUrl?: string,
-  allowedHosts: readonly string[] = [],
+/**
+ * AdonisJS `isValidRedirectUrl`: a relative path, or an absolute URL whose host
+ * is the request authority or an allowed host.
+ */
+function isTrustedRedirect(
+  url: string,
+  authority: string | undefined,
+  allowedHosts: readonly string[],
 ): boolean {
   // A relative path is trusted only when it starts with a single "/" and has no
   // backslash: browsers normalise "\" to "/", so "/\evil.com" would become the
   // protocol-relative "//evil.com" that a lone `!startsWith("//")` check misses.
-  if (referer.startsWith('/') && !referer.startsWith('//') && !referer.includes('\\')) return true
-  let ref: URL
-  try {
-    ref = new URL(referer)
-  } catch {
-    return false
-  }
-  // An explicitly allowed host is trusted whatever the request's own origin is
-  // — that is what the list is for (AdonisJS `allowedHosts`).
-  if (allowedHosts.includes(ref.host)) return true
-  if (!requestUrl) return false
+  if (url.startsWith('/') && !url.startsWith('//') && !url.includes('\\')) return true
+  let parsed: URL
   try {
-    return ref.origin === new URL(requestUrl).origin
+    parsed = new URL(url)
   } catch {
     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.
+  return authority !== undefined && parsed.host === authority
+}
+
+/** The query string of a path or URL, without the "?". */
+function searchOf(url: string | undefined): string {
+  if (url === undefined) return ''
+  const index = url.indexOf('?')
+  return index === -1 ? '' : url.slice(index + 1)
 }
 
 /** The slice of the session the intended-URL methods use. */
@@ -60,6 +66,7 @@ export class RedirectBuilder {
   #forwardQs = false
   #requestUrl?: string
   #requestReferer?: string
+  #requestAuthority?: string
   #routeUrlResolver?: RouteUrlResolver
   #session?: IntendedUrlStore
   #isAjax = false
@@ -68,8 +75,14 @@ export class RedirectBuilder {
   constructor(
     response: Response,
     options?: {
+      /** The request path with its query string. */
       requestUrl?: string
       requestReferer?: string
+      /**
+       * The request authority (`:authority` or `Host`, never X-Forwarded-Host)
+       * an absolute redirect target must match.
+       */
+      requestAuthority?: string
       routeUrlResolver?: RouteUrlResolver
       /** The request session, for the intended-URL methods. */
       session?: IntendedUrlStore
@@ -82,6 +95,7 @@ export class RedirectBuilder {
     this.#response = response
     this.#requestUrl = options?.requestUrl
     this.#requestReferer = options?.requestReferer
+    this.#requestAuthority = options?.requestAuthority
     this.#routeUrlResolver = options?.routeUrlResolver
     this.#session = options?.session
     this.#isAjax = options?.isAjax ?? false
@@ -135,13 +149,9 @@ export class RedirectBuilder {
 
   #safeIntended<T extends string | null>(intended: string | null, fallback: T): string | T {
     if (!intended) return fallback
-    if (this.#requestUrl && !isSameOriginOrRelative(intended, this.#requestUrl)) {
-      return fallback
-    }
-    // A protocol-relative `//evil.com` is absolute to a browser even though it
-    // looks relative — reject it whether or not a request URL is known.
-    if (intended.startsWith('//')) return fallback
-    return intended
+    return isTrustedRedirect(intended, this.#requestAuthority, this.allowedHosts)
+      ? intended
+      : fallback
   }
 
   /** Set redirect status code. */
@@ -191,7 +201,12 @@ export class RedirectBuilder {
 
   /** Redirect to an absolute or relative path. */
   toPath(path: string): void {
-    const url = this.#appendQs(path)
+    this.#send(path, searchOf(this.#requestUrl))
+  }
+
+  /** Redirect with `withQs()` forwarding `forwardedSearch` (a query string without "?"). */
+  #send(path: string, forwardedSearch: string): void {
+    const url = this.#appendQs(path, forwardedSearch)
     this.#response.status(this.#status)
     this.#response.header('location', url)
     this.#response.setBody('')
@@ -207,12 +222,13 @@ export class RedirectBuilder {
   }
 
   /**
-   * Redirect back to the previous page (Referer header).
-   * Only trusts same-origin or relative referers — external URLs fall back
-   * to `fallback` to prevent open redirect attacks.
+   * Redirect back to the previous page (AdonisJS `back`): the path of
+   * {@link getPreviousUrl}, so the redirect never leaves the site; `withQs()`
+   * forwards the previous page's query string, not the current request's.
    */
   back(fallback = '/'): void {
-    this.toPath(this.getPreviousUrl(fallback))
+    const previous = new URL(this.getPreviousUrl(fallback), 'http://localhost')
+    this.#send(previous.pathname, previous.search.slice(1))
   }
 
   /**
@@ -225,7 +241,7 @@ export class RedirectBuilder {
    */
   getPreviousUrl(fallback = '/'): string {
     const referer = this.#requestReferer
-    if (referer && isSameOriginOrRelative(referer, this.#requestUrl, this.allowedHosts)) {
+    if (referer && isTrustedRedirect(referer, this.#requestAuthority, this.allowedHosts)) {
       return referer
     }
     return fallback
@@ -236,15 +252,10 @@ export class RedirectBuilder {
    * uses, so `withQs()` plus `withQs('page', 2)` overrides an inbound `page`
    * rather than being overridden by it.
    */
-  #appendQs(path: string): string {
+  #appendQs(path: string, forwardedSearch: string): string {
     const params = new URLSearchParams()
-    if (this.#forwardQs && this.#requestUrl) {
-      const qsIdx = this.#requestUrl.indexOf('?')
-      if (qsIdx !== -1) {
-        for (const [key, value] of new URLSearchParams(this.#requestUrl.slice(qsIdx + 1))) {
-          params.append(key, value)
-        }
-      }
+    if (this.#forwardQs) {
+      for (const [key, value] of new URLSearchParams(forwardedSearch)) params.append(key, value)
     }
     for (const [key, value] of Object.entries(this.#qs)) {
       if (value === undefined || value === null) continue