@c9up/ream 0.2.27 → 0.2.29

package/src/http-client/index.ts

@@ -0,0 +1,21 @@
+/**
+ * `@c9up/ream/http-client` — outbound HTTP with an SSRF guard, and its test fake.
+ */
+
+export { isPublicAddress } from './addresses.js'
+export {
+  FakeHttpClient,
+  type FakeMatcher,
+  type FakeResponse,
+  fakeHttp,
+  type RecordedRequest,
+} from './fake.js'
+export {
+  HttpClient,
+  HttpClientError,
+  type HttpClientFailure,
+  type HttpClientOptions,
+  type HttpRequestOptions,
+  HttpResponse,
+  type OutgoingRequest,
+} from './HttpClient.js'

package/src/index.ts

@@ -91,6 +91,7 @@ export type {
 export { RedisDriver as SessionRedisDriver } from './session/drivers/RedisDriver.js'
 export {
   E_SESSION_NOT_READY,
+  E_SESSION_STORE_NOT_CONDITIONAL,
   E_SESSION_TAGGING_NOT_SUPPORTED,
 } from './session/errors.js'
 export type { ValuePath } from './session/ReadOnlyValuesStore.js'
@@ -218,8 +219,13 @@ export { createHttpKernel } from './HttpKernel.js'
 
 // ─── Server ─────────────────────────────────────────────────
 
+export type { NativeGrpcCall, NativeGrpcHandler } from './server/nativeGrpc.js'
 export type {
   ErrorHandlerClass,
+  GrpcCall,
+  GrpcHandler,
+  GrpcLimits,
+  GrpcReply,
   LazyImport,
   MiddlewareClass,
   MiddlewareEntry,
@@ -281,7 +287,9 @@ export type {
 export {
   type Codemods,
   createCodemods,
+  type EnvValidationNode,
   type GeneratedStub,
+  type PreloadEnvironment,
   type StubState,
 } from './Codemods.js'
 export {
@@ -405,4 +413,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.2.27'
+export const VERSION = '0.2.29'

package/src/middleware/Pipeline.ts

@@ -15,6 +15,7 @@ import { debugHttp } from '../debug.js'
 import { ReamError } from '../errors/ReamError.js'
 import { E_FORBIDDEN, E_UNAUTHORIZED, E_VALIDATION_ERROR } from '../http/Exception.js'
 import type { HttpContext } from '../http/HttpContext.js'
+import { holdsPermissions } from '../http/permissions.js'
 
 export type MiddlewareFunction = (
   ctx: HttpContext,
@@ -96,7 +97,10 @@ export async function runValidator(
     }
   }
 
-  throw new TypeError(
+  // A dedicated code, not a TypeError: callers tell this configuration
+  // mistake apart from a TypeError raised by a bug inside a rule.
+  throw new ReamError(
+    'E_VALIDATOR_UNUSABLE',
     'Route validator exposes none of validateResultAsync(), validateResult() or validate().',
   )
 }
@@ -239,9 +243,9 @@ function createGuardMiddleware(
       }
     }
 
+    // A token-authenticated request also needs the token to allow each one.
     if (permissions && permissions.length > 0) {
-      const userPerms = ctx.auth.permissions ?? ctx.auth.user?.permissions ?? []
-      if (!permissions.every((p) => userPerms.includes(p))) {
+      if (!holdsPermissions(ctx.auth, permissions)) {
         throw new E_FORBIDDEN('Insufficient permissions', permissions)
       }
     }

package/src/native/generated.ts

@@ -23,6 +23,53 @@ export interface NapiResponse {
   streamId?: string
 }
 
+/**
+ * One gRPC call, handed to the JS handler registered with `onGrpc`.
+ *
+ * The message crosses as BYTES — never through the `String` (base64 for
+ * binary) body of the HTTP path.
+ */
+
+export interface NapiGrpcCall {
+  /**
+   * This call, in the ids `onGrpcCancel` reports. Increasing, in the order
+   * the calls reach JavaScript.
+   */
+  id: number
+  /** `/package.Service/Method`. */
+  path: string
+  /**
+   * Request metadata: the request headers, every value of a repeated one
+   * in order, names lowercased.
+   */
+  metadata: Record<string, Array<string>>
+  /** The request message, still encoded. */
+  message: Uint8Array
+  /** Resolved client IP, by the same trusted-proxy rules as `request.ip`. */
+  ip: string
+}
+
+/**
+ * What the gRPC handler answers: a reply `message`, or a status `code`
+ * (with its `details`) instead of one.
+ */
+
+export interface NapiGrpcReply {
+  message?: Uint8Array
+  code?: number
+  details?: string
+}
+
+/**
+ * Message size bounds of the gRPC calls, in bytes; `-1` for none. Omitted:
+ * 4 MiB received, no bound sent.
+ */
+
+export interface NapiGrpcLimits {
+  maxReceiveMessageLength?: number
+  maxSendMessageLength?: number
+}
+
 /**
  * Configuration for the wire-level shield filter. Mirrors the Rust
  * `ShieldConfig` shape; the JS layer constructs it from `ShieldMiddleware`
@@ -45,6 +92,45 @@ export interface NapiRateLimitConfig {
   windowSecs: number
 }
 
+/**
+ * The limit of one body parser and the content types it claims. `limit` is
+ * in bytes; an omitted field keeps the default.
+ */
+
+export interface NapiBodyLimit {
+  limit?: number
+  types?: Array<string>
+}
+
+/**
+ * Request-body limits per content type, the body parser's sections. Each
+ * omitted section keeps the `@adonisjs/bodyparser` default: json, form and
+ * raw (`text/*`) 1 MB, multipart 20 MB. A content type no section claims
+ * gets the raw limit.
+ */
+
+export interface NapiBodyLimits {
+  json?: NapiBodyLimit
+  form?: NapiBodyLimit
+  raw?: NapiBodyLimit
+  multipart?: NapiBodyLimit
+}
+
+/**
+ * Timeouts (milliseconds) and the connection cap, named after the Node
+ * `http.Server` settings an Adonis app configures. `0` disables a bound;
+ * an omitted field keeps the default: `headersTimeout` 60 000,
+ * `requestTimeout` 300 000, `keepAliveTimeout` 5 000, `maxConnections`
+ * 10 000.
+ */
+
+export interface NapiConnectionConfig {
+  headersTimeout?: number
+  requestTimeout?: number
+  keepAliveTimeout?: number
+  maxConnections?: number
+}
+
 /**
  * NAPI-exposed event bus.
  * Uses shared Tokio runtime (no per-instance runtime).
@@ -96,11 +182,45 @@ export declare class HyperServer {
    */
   onRequest(callback: (request: Record<string, unknown>) => Promise<NapiResponse>): void
   /**
-   * Configure the trusted-proxy CIDR list used by `request.ip` resolution.
-   * Must be called BEFORE `listen()`. Empty list = legacy permissive mode
-   * (any peer can populate `X-Forwarded-For`).
+   * Register the gRPC handler. From `listen()` on, `application/grpc`
+   * requests on this port are gRPC calls handed to it; without it they stay
+   * HTTP requests. Must be called BEFORE `listen()`.
+   *
+   * A rejected promise is answered `INTERNAL`, with nothing of the error
+   * sent to the client. `limits` bounds the request and reply messages;
+   * a request is read, and refused, before the handler is called.
+   */
+  onGrpc(
+    callback: (arg: NapiGrpcCall) => Promise<NapiGrpcReply>,
+    limits?: NapiGrpcLimits | undefined | null,
+  ): void
+  /**
+   * Register the function told, with its `id`, about a gRPC call the
+   * client gave up on — a reset stream or a closed connection — before the
+   * handler answered. A cancel can reach JavaScript before its call does.
+   */
+  onGrpcCancel(callback: (arg: number) => void): void
+  /**
+   * Configure the trusted proxies used by `request.ip` / `request.ips`
+   * resolution. Must be called BEFORE `listen()`. Entries are addresses,
+   * CIDR ranges (IPv4 or IPv6), IPv4 netmask ranges, the named ranges
+   * `loopback` / `linklocal` / `uniquelocal`, or `"*"` (trust every hop).
+   * Empty list (the default) = `X-Forwarded-For` ignored, the socket peer
+   * is the client. Throws on an entry that is none of these.
    */
   configureTrustedProxies(cidrs: Array<string>): void
+  /**
+   * Configure the request-body limits, applied while the body is read:
+   * nothing past a limit is kept, and the request reaches JS without its
+   * body and with `bodyTooLarge` set, for the body parser to answer 413
+   * once the route is known. Must be called BEFORE `listen()`.
+   */
+  configureBodyLimits(config: NapiBodyLimits): void
+  /**
+   * Configure the header / body / keep-alive timeouts and the connection
+   * cap. Must be called BEFORE `listen()`.
+   */
+  configureConnections(config: NapiConnectionConfig): void
   /**
    * Install (or replace) the wire-level rate limiter. Pass `None` to
    * disable. Must be called BEFORE `listen()`.

package/src/rpc/RpcProvider.ts

@@ -39,6 +39,12 @@ export interface RpcConfig {
    * it as public and never populates `ctx.auth` (every guarded method 401s).
    */
   guards?: string[]
+  /**
+   * Media types the endpoint accepts a request body under; any other is
+   * answered 415. Default: `application/json`, `application/json-rpc`,
+   * `application/jsonrequest`.
+   */
+  contentTypes?: string[]
 }
 
 export class RpcProvider extends Provider {
@@ -47,7 +53,10 @@ export class RpcProvider extends Provider {
 
   constructor(app: AppContext, options: RpcProviderOptions = {}) {
     super(app)
-    this.rpc = options.router ?? new RpcRouter()
+    // Config is loaded before providers are constructed.
+    this.rpc =
+      options.router ??
+      new RpcRouter({ contentTypes: app.config.get<RpcConfig>('rpc')?.contentTypes })
   }
 
   override register(): void {

package/src/rpc/RpcRouter.ts

@@ -5,7 +5,7 @@
  *
  * Usage:
  *   rpc.method('task.validate', handler).guard('jwt').role('cs_member')
- *   rpc.namespace('task', TaskController)  // every public method, DI-resolved per call
+ *   rpc.namespace('task', TaskController, ['show', 'update'])  // listed methods, DI-resolved per call
  *   rpc.group({ guard: 'jwt' }, (r) => { r.method('user.find', handler) })
  *
  * @implements MISS-27
@@ -15,11 +15,14 @@ import {
   buildSuccess,
   isNotification,
   isRpcShapedError,
+  type JsonRpcId,
   parseRequest as parseRpcRequest,
   buildError as rpcError,
 } from '@c9up/comet'
 import { currentNodeEnv } from '../env/nodeEnv.js'
+import { isReamError, ReamError } from '../errors/ReamError.js'
 import type { HttpContext } from '../http/HttpContext.js'
+import { holdsPermissions } from '../http/permissions.js'
 import type { MiddlewareRegistry, RuntimeValidator } from '../middleware/Pipeline.js'
 import { composeMiddleware, runValidator } from '../middleware/Pipeline.js'
 
@@ -79,17 +82,58 @@ export class RpcMethodBuilder {
 }
 
 /**
- * Unwrap the `{ _body: [...] }` envelope `request.body()` puts around a
- * top-level JSON array (it only treats plain objects as the body verbatim). A
- * JSON-RPC batch arrives this way; a single request is a plain object and is
- * returned unchanged.
+ * A -32603 whose detail reaches the caller only outside production: an
+ * internal failure's message is where hosts, credentials and queries end up.
  */
-function unwrapBatchBody(value: unknown): unknown {
-  if (typeof value === 'object' && value !== null && '_body' in value) {
-    const inner = value._body
-    if (Array.isArray(inner)) return inner
+function internalError(detail: string, id: JsonRpcId) {
+  return rpcError(-32603, currentNodeEnv() !== 'production' ? detail : 'Internal error', id)
+}
+
+/** The public method names of a controller instance type. */
+export type ControllerMethodName<T> = {
+  [K in keyof T]: T[K] extends (...args: never[]) => unknown ? K : never
+}[keyof T] &
+  string
+
+/**
+ * Whether `name` is a plain method of the controller's own class chain.
+ * The walk stops before `Object.prototype` and reads descriptors, so
+ * neither `toString` nor a getter (whose read would run code) qualifies.
+ */
+function isControllerMethod(proto: unknown, name: unknown): boolean {
+  if (typeof name !== 'string' || name === '' || name === 'constructor') return false
+  let current: unknown = proto
+  while (typeof current === 'object' && current !== null && current !== Object.prototype) {
+    const descriptor = Object.getOwnPropertyDescriptor(current, name)
+    if (descriptor) return typeof descriptor.value === 'function'
+    current = Object.getPrototypeOf(current)
   }
-  return value
+  return false
+}
+
+/**
+ * The JSON media types JSON-RPC over HTTP is sent with. None of them is a
+ * CORS-safelisted request type, so a foreign page cannot send one without a
+ * preflight.
+ */
+const DEFAULT_CONTENT_TYPES = [
+  'application/json',
+  'application/json-rpc',
+  'application/jsonrequest',
+]
+
+/** `Application/JSON; charset=utf-8` → `application/json`. */
+function mediaType(contentType: string | undefined): string {
+  return (contentType?.split(';')[0] ?? '').trim().toLowerCase()
+}
+
+export interface RpcRouterOptions {
+  /**
+   * Media types `handle()` accepts a request body under; anything else is
+   * answered 415 before the body is read. Default: `application/json`,
+   * `application/json-rpc`, `application/jsonrequest`.
+   */
+  contentTypes?: readonly string[]
 }
 
 /**
@@ -113,9 +157,9 @@ function checkRpcAuthorization(
       return { code: -32003, message: 'Insufficient role' }
     }
   }
+  // A token-authenticated call also needs the token to allow each permission.
   if (def.permissions.length > 0) {
-    const userPerms = ctx.auth?.permissions ?? ctx.auth?.user?.permissions ?? []
-    if (!def.permissions.every((p: string) => userPerms.includes(p))) {
+    if (!holdsPermissions(ctx.auth, def.permissions)) {
       return { code: -32003, message: 'Insufficient permissions' }
     }
   }
@@ -126,6 +170,13 @@ export class RpcRouter {
   #methods: Map<string, RpcMethodDefinition> = new Map()
   #groupConfig: { guards: string[]; roles: string[]; middleware: string[] } | null = null
   #container?: RpcContainer
+  readonly #contentTypes: ReadonlySet<string>
+
+  constructor(options: RpcRouterOptions = {}) {
+    this.#contentTypes = new Set(
+      (options.contentTypes ?? DEFAULT_CONTENT_TYPES).map((type) => mediaType(type)),
+    )
+  }
 
   /**
    * Set the IoC container used to resolve `namespace()` controllers — mirrors
@@ -137,8 +188,23 @@ export class RpcRouter {
     this.#container = container
   }
 
-  /** Register an RPC method. */
+  /**
+   * Register an RPC method. JSON-RPC 2.0 §4 reserves names starting with
+   * `rpc.` for the protocol itself, so they are refused here, as an empty
+   * name is.
+   */
   method(name: string, handler: RpcHandler): RpcMethodBuilder {
+    if (typeof name !== 'string' || name === '') {
+      throw new ReamError(
+        'E_RPC_INVALID_METHOD_NAME',
+        'An RPC method name must be a non-empty string',
+      )
+    }
+    if (name.startsWith('rpc.')) {
+      throw new ReamError('E_RPC_RESERVED_METHOD_NAME', `'${name}' is a reserved RPC method name`, {
+        hint: 'JSON-RPC 2.0 reserves names starting with "rpc." for rpc-internal methods; pick another prefix.',
+      })
+    }
     const def: RpcMethodDefinition = {
       name,
       handler,
@@ -152,24 +218,28 @@ export class RpcRouter {
   }
 
   /**
-   * Register methods from a controller — auto-registers all public methods.
+   * Register the listed methods of a controller as `<prefix>.<method>`.
    *
-   * The parameter used to demand
-   * `new (...args: unknown[]) => Record<string, (...args: unknown[]) => unknown>`,
-   * which NO real controller satisfies: a class with any non-method property
-   * fails the `Record`, and a method declared `bump(): number` fails the
-   * `unknown[]` parameters, which are compared contravariantly. So the
-   * documented call — `rpc.namespace('task', TaskController)` — did not
-   * typecheck, and nothing noticed because the tests were outside `tsc`.
-   *
-   * Any class, then. The body already checks that what it found is callable
-   * and names the method when it is not.
+   * The list is explicit, like a route binding one `[Controller, 'method']`
+   * pair: TypeScript `private`/`protected` vanish at runtime, so a namespace
+   * that published "every method on the prototype" made helpers the author
+   * never meant to expose remotely callable. The type admits only public
+   * method names; the runtime check refuses a name with no plain method
+   * behind it (a getter, `constructor`, anything from `Object.prototype`).
    */
-  namespace(prefix: string, controller: abstract new (...args: never[]) => object): void {
-    const proto = controller.prototype
-    const methods = Object.getOwnPropertyNames(proto).filter(
-      (m) => m !== 'constructor' && typeof proto[m] === 'function',
-    )
+  namespace<T extends object>(
+    prefix: string,
+    controller: abstract new (...args: never[]) => T,
+    methods: ReadonlyArray<ControllerMethodName<T>>,
+  ): void {
+    for (const methodName of methods) {
+      if (!isControllerMethod(controller.prototype, methodName)) {
+        throw new ReamError(
+          'E_RPC_UNKNOWN_CONTROLLER_METHOD',
+          `${controller.name} has no method '${String(methodName)}' to expose as an RPC method`,
+        )
+      }
+    }
     for (const methodName of methods) {
       this.method(`${prefix}.${methodName}`, async (ctx, params) => {
         // Resolve through the container on every call (fresh DI per request,
@@ -212,10 +282,26 @@ export class RpcRouter {
 
   /** Handle an incoming JSON-RPC request. */
   async handle(ctx: HttpContext): Promise<void> {
-    // `request.body()` wraps a top-level JSON array — a JSON-RPC batch — as its
-    // non-object envelope `{ _body: [...] }`. Unwrap it so batch detection works;
-    // a single request is a plain object and passes through untouched.
-    const body = unwrapBatchBody(ctx.request.body())
+    // 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 victim's cookies and
+    // no preflight. Refused before the body is read, as JSON-RPC servers
+    // answer 415 to anything but JSON.
+    if (!this.#contentTypes.has(mediaType(ctx.request.header('content-type')))) {
+      ctx.response.status(415).send('')
+      return
+    }
+
+    // Parsed here, not through `request.body()`, which turns malformed JSON
+    // into `{}` — and §5.1 answers invalid JSON with -32700, not -32600.
+    // `raw()` stays outside the try: its 413 is not a parse error.
+    const raw = ctx.request.raw()
+    let body: unknown
+    try {
+      body = JSON.parse(raw)
+    } catch {
+      ctx.response.status(200).json(rpcError(-32700, 'Parse error', null))
+      return
+    }
 
     // Batch support (max 50 to prevent DoS)
     if (Array.isArray(body)) {
@@ -310,8 +396,7 @@ export class RpcRouter {
       if (def.validator) {
         const token = `validator:${def.validator}`
         if (!this.#container?.has(token)) {
-          return rpcError(
-            -32603,
+          return internalError(
             `Validator '${def.validator}' is not registered (bind container.singleton('${token}', () => schema)).`,
             id,
           )
@@ -324,9 +409,11 @@ export class RpcRouter {
         try {
           outcome = await runValidator(validator, params)
         } catch (err) {
-          return rpcError(
-            -32603,
-            err instanceof TypeError
+          // Caught here rather than below so a validator's error is never
+          // honoured as a domain error: a rule hitting the database throws
+          // whatever the driver throws.
+          return internalError(
+            isReamError(err, 'E_VALIDATOR_UNUSABLE')
               ? `Validator '${def.validator}' exposes no usable validate method.`
               : `Validator '${def.validator}' failed: ${err instanceof Error ? err.message : String(err)}`,
             id,
@@ -346,10 +433,7 @@ export class RpcRouter {
         const message = typeof err.message === 'string' ? err.message : 'RPC error'
         return rpcError(err.code, message, id, err.data)
       }
-      // Otherwise don't leak internal error details to the caller.
-      const isDev = currentNodeEnv() !== 'production'
-      const message = isDev && err instanceof Error ? err.message : 'Internal error'
-      return rpcError(-32603, message, id)
+      return internalError(err instanceof Error ? err.message : 'Internal error', id)
     }
   }
 

package/src/scheduler/locks/RedisLockBackend.ts

@@ -67,12 +67,20 @@ export class RedisLockBackend implements LockBackend {
     this.#prefix = options.prefix ?? 'ream:schedule:lock:'
   }
 
-  /** The client, resolved once and kept. */
+  /**
+   * The client, resolved once and kept. Only a success is kept: a lookup
+   * that fails (the connection is not registered yet at boot, Redis is
+   * briefly down) is forgotten so the next task retries it, instead of
+   * every lock failing with the same error until the process restarts.
+   */
   #client(): Promise<LockRedisClient> {
     if (!this.#resolved) {
-      this.#resolved = Promise.resolve(
-        typeof this.#source === 'function' ? this.#source() : this.#source,
-      )
+      const source = this.#source
+      const pending = (async () => (typeof source === 'function' ? source() : source))()
+      this.#resolved = pending
+      pending.catch(() => {
+        if (this.#resolved === pending) this.#resolved = undefined
+      })
     }
     return this.#resolved
   }

package/src/security/CookieSigner.ts

@@ -23,6 +23,11 @@
 import { createCipheriv, createDecipheriv, createHmac, randomBytes } from 'node:crypto'
 import { hmacSign, hmacVerify } from './crypto.js'
 
+/** The 96-bit nonce GCM is specified for. */
+const GCM_IV_BYTES = 12
+/** The full 128-bit authentication tag — never a truncated one. */
+const GCM_TAG_BYTES = 16
+
 /** Raised when no APP_KEY is configured (AdonisJS `E_MISSING_APP_KEY`). */
 export class E_MISSING_APP_KEY extends Error {
   readonly code = 'E_MISSING_APP_KEY' as const
@@ -217,8 +222,10 @@ export class CookieSigner {
   }
 
   encrypt(value: unknown, expiresIn?: number, purpose?: string): string {
-    const iv = randomBytes(12)
-    const cipher = createCipheriv('aes-256-gcm', this.#keyBuffer, iv)
+    const iv = randomBytes(GCM_IV_BYTES)
+    const cipher = createCipheriv('aes-256-gcm', this.#keyBuffer, iv, {
+      authTagLength: GCM_TAG_BYTES,
+    })
     const sealed = this.#seal(value, expiresIn, purpose)
     const encrypted = Buffer.concat([cipher.update(sealed, 'utf8'), cipher.final()])
     const tag = cipher.getAuthTag()
@@ -242,7 +249,14 @@ export class CookieSigner {
       const iv = Buffer.from(ivPart, 'base64url')
       const data = Buffer.from(dataPart, 'base64url')
       const tag = Buffer.from(tagPart, 'base64url')
-      const decipher = createDecipheriv('aes-256-gcm', this.#keyBuffer, iv)
+      // GCM verifies only as many tag bytes as it is handed: a client that
+      // trims the tag to 4 bytes would cut forgery cost from 2^128 to 2^32
+      // guesses. Only what `encrypt` produces is accepted — a 12-byte IV and
+      // the full 16-byte tag — and the decipher is pinned to that length too.
+      if (iv.length !== GCM_IV_BYTES || tag.length !== GCM_TAG_BYTES) return null
+      const decipher = createDecipheriv('aes-256-gcm', this.#keyBuffer, iv, {
+        authTagLength: GCM_TAG_BYTES,
+      })
       decipher.setAuthTag(tag)
       const raw = Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8')
       return this.#open(raw, purpose) as T | null

package/src/security/SignedUrl.ts

@@ -43,7 +43,12 @@ export class SignedUrl {
     if (!providedSig) return false
     const expires = url.searchParams.get('expires')
     if (expires && Math.floor(Date.now() / 1000) > parseInt(expires, 10)) return false
-    if (purpose && url.searchParams.get('purpose') !== purpose) return false
+    // Exact match both ways: a URL minted for `password-reset` must not pass a
+    // check that names no purpose (or another one), and a purpose-less URL
+    // must not pass a check that names one. An empty purpose is no purpose,
+    // as in `make`.
+    const signedPurpose = url.searchParams.get('purpose') || undefined
+    if (signedPurpose !== (purpose || undefined)) return false
 
     url.searchParams.delete('signature')
     const expectedSig = hmacSign(url.pathname + url.search, this.#secret)