@nifrajs/core 1.6.0 → 1.8.0

package/src/internal/route-assurance.ts

@@ -0,0 +1,166 @@
+import { METHODS, type Method } from "../router/router.ts"
+
+/** Where enforcement evidence follows Nifra's route-registration semantics. */
+export type AssuranceScope = "global" | "subsequent" | "plugin"
+
+/** Reflection-safe proof that a named enforcement module covered a route. */
+export interface AssuranceEvidence {
+  readonly id: string
+  readonly source: string
+}
+
+/** Metadata installed on a middleware/plugin by {@link withRouteAssurance}. */
+export interface AssuranceDeclaration extends AssuranceEvidence {
+  readonly scope: AssuranceScope
+  /** Restrict evidence to these HTTP methods. Omit for every method. */
+  readonly methods?: readonly Method[]
+  /** Restrict evidence to these absolute route globs. Omit for every path. */
+  readonly paths?: readonly string[]
+}
+
+const EVIDENCE_ID = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/
+const METHOD_SET: ReadonlySet<string> = new Set(METHODS)
+const declarations = new WeakMap<object, readonly AssuranceDeclaration[]>()
+
+export const NIFRA_ASSURANCE_IDS = Object.freeze({
+  AUTHENTICATED: "nifra.authenticated",
+  BODY_BOUNDED: "nifra.body-bounded",
+  CSRF: "nifra.csrf",
+  IDEMPOTENCY_KEY: "nifra.idempotency-key",
+  IP_RESTRICTED: "nifra.ip-restricted",
+  RATE_LIMITED: "nifra.rate-limited",
+  SECURITY_HEADERS: "nifra.security-headers",
+} as const)
+
+const escapeRegex = (value: string): string => value.replace(/[|\\{}()[\]^$+?.-]/g, "\\$&")
+
+/** Compile an absolute route glob. `*` is one segment; `**` is zero or more segments. */
+export function routeGlob(pattern: string): RegExp {
+  if (!pattern.startsWith("/") || pattern.includes("?") || pattern.includes("#")) {
+    throw new Error(
+      `route assurance: path glob must be an absolute path: ${JSON.stringify(pattern)}`,
+    )
+  }
+  if (pattern === "/") return /^\/$/
+  const segments = pattern.slice(1).split("/")
+  let source = "^"
+  for (const [index, segment] of segments.entries()) {
+    if (segment === "**") {
+      if (index !== segments.length - 1) {
+        throw new Error(
+          `route assurance: ** must be the final path segment: ${JSON.stringify(pattern)}`,
+        )
+      }
+      source += "(?:/.*)?"
+    } else if (segment === "*") {
+      source += "/[^/]+"
+    } else {
+      if (segment.includes("*")) {
+        throw new Error(
+          `route assurance: * must occupy a whole path segment: ${JSON.stringify(pattern)}`,
+        )
+      }
+      source += `/${escapeRegex(segment)}`
+    }
+  }
+  return new RegExp(`${source}$`)
+}
+
+function normalizeDeclaration(value: AssuranceDeclaration): AssuranceDeclaration {
+  if (!EVIDENCE_ID.test(value.id)) {
+    throw new Error(
+      `route assurance: invalid evidence id ${JSON.stringify(value.id)} (use lowercase dot/dash segments)`,
+    )
+  }
+  if (typeof value.source !== "string" || value.source.trim() === "") {
+    throw new Error("route assurance: evidence source must be a non-empty string")
+  }
+  if (value.scope !== "global" && value.scope !== "subsequent" && value.scope !== "plugin") {
+    throw new Error(`route assurance: invalid scope ${JSON.stringify(value.scope)}`)
+  }
+  const methods = value.methods?.map((method) => method.toUpperCase())
+  for (const method of methods ?? []) {
+    if (!METHOD_SET.has(method)) {
+      throw new Error(`route assurance: unsupported HTTP method ${JSON.stringify(method)}`)
+    }
+  }
+  const paths = value.paths?.map((path) => {
+    routeGlob(path)
+    return path
+  })
+  return Object.freeze({
+    id: value.id,
+    source: value.source.trim(),
+    scope: value.scope,
+    ...(methods !== undefined ? { methods: Object.freeze(methods as Method[]) } : {}),
+    ...(paths !== undefined ? { paths: Object.freeze(paths) } : {}),
+  })
+}
+
+/** Attach enforcement evidence to the middleware/plugin that installs it. */
+export function withRouteAssurance<T extends object>(
+  target: T,
+  declaration: AssuranceDeclaration | readonly AssuranceDeclaration[],
+): T {
+  const values = Array.isArray(declaration) ? declaration : [declaration]
+  if (values.length === 0) throw new Error("route assurance: at least one declaration is required")
+  const previous = declarations.get(target) ?? []
+  declarations.set(
+    target,
+    Object.freeze([...previous, ...values.map((value) => normalizeDeclaration(value))]),
+  )
+  return target
+}
+
+export function assuranceDeclarationsOf(value: object): readonly AssuranceDeclaration[] {
+  return declarations.get(value) ?? []
+}
+
+export function declarationApplies(
+  declaration: AssuranceDeclaration,
+  method: string,
+  path: string,
+): boolean {
+  if (declaration.methods !== undefined && !declaration.methods.includes(method as Method))
+    return false
+  return (
+    declaration.paths === undefined ||
+    declaration.paths.some((pattern) => routeGlob(pattern).test(path))
+  )
+}
+
+export function assuranceEvidenceFor(
+  declarationsToApply: readonly AssuranceDeclaration[],
+  method: string,
+  path: string,
+): readonly AssuranceEvidence[] {
+  const seen = new Set<string>()
+  const evidence: AssuranceEvidence[] = []
+  for (const declaration of declarationsToApply) {
+    if (!declarationApplies(declaration, method, path)) continue
+    const key = `${declaration.id}\n${declaration.source}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    evidence.push(Object.freeze({ id: declaration.id, source: declaration.source }))
+  }
+  return Object.freeze(evidence)
+}
+
+export function validEvidence(value: unknown): value is AssuranceEvidence {
+  if (typeof value !== "object" || value === null) return false
+  const candidate = value as Partial<AssuranceEvidence>
+  return (
+    typeof candidate.id === "string" &&
+    EVIDENCE_ID.test(candidate.id) &&
+    typeof candidate.source === "string" &&
+    candidate.source.trim() !== ""
+  )
+}
+
+export function validEvidenceId(value: string): boolean {
+  return EVIDENCE_ID.test(value)
+}
+
+export function validMethod(value: string): value is Method {
+  return METHOD_SET.has(value.toUpperCase())
+}

package/src/reflection.ts

@@ -7,6 +7,7 @@
  * recognizes Nifra/TypeBox carriers and raw JSON Schema without depending on a validator package.
  */
 
+import { type AssuranceEvidence, validEvidence } from "./internal/route-assurance.ts"
 import type { StandardSchemaV1 } from "./schema/standard.ts"
 import type { ToolAnnotations } from "./server/server.ts"
 
@@ -43,6 +44,7 @@ export interface ReflectedRoute {
   readonly method: string
   readonly path: string
   readonly schema?: ReflectedRouteSchema
+  readonly assurance?: readonly AssuranceEvidence[]
   readonly tool?: {
     readonly name: string
     readonly description: string
@@ -97,7 +99,7 @@ const normalizeJsonSchema = (value: unknown): JsonSchema | undefined => {
     // carrier (a JSON Schema object that also carries `~standard`, with no separate `.jsonSchema`) would
     // otherwise leak the marker into emitted OpenAPI / mock / form output.
     if (!("~standard" in record)) return record
-    const { ["~standard"]: _omitted, ...rest } = record
+    const { "~standard": _omitted, ...rest } = record
     return rest
   } catch {
     return undefined
@@ -174,6 +176,14 @@ const reflectedTool = (value: unknown): ReflectedRoute["tool"] => {
   }
 }
 
+const reflectedAssurance = (value: unknown): readonly AssuranceEvidence[] | undefined => {
+  if (!Array.isArray(value)) return undefined
+  const evidence = value
+    .filter(validEvidence)
+    .map((item) => Object.freeze({ id: item.id, source: item.source.trim() }))
+  return evidence.length > 0 ? Object.freeze(evidence) : undefined
+}
+
 /**
  * Safely enumerate and normalize route descriptors from an app or descriptor array. Invalid entries
  * are ignored; a missing/throwing `routes()` method yields an empty array.
@@ -185,10 +195,12 @@ export function reflectRoutes(source: unknown): readonly ReflectedRoute[] {
     if (typeof route?.method !== "string" || typeof route.path !== "string") continue
     const schema = reflectedRouteSchema(route.schema)
     const tool = reflectedTool(route.tool)
+    const assurance = reflectedAssurance(route.assurance)
     reflected.push({
       method: route.method.toUpperCase(),
       path: route.path,
       ...(schema !== undefined ? { schema } : {}),
+      ...(assurance !== undefined ? { assurance } : {}),
       ...(tool !== undefined ? { tool } : {}),
     })
   }

package/src/server/registry.ts

@@ -75,7 +75,24 @@ export type OutputOf<H extends (...args: never[]) => unknown> = Exclude<
   Response
 >
 
-/** Merge a new route into the registry, combining methods that share a path. */
+/**
+ * Merge a new route into the registry, combining methods that share a path.
+ *
+ * SCALING CEILING (measured — see many-routes.test-d.ts and the isolation study below): a single
+ * fluent chain hits TS2589 at ~95-100 routes. This intersection is NOT the cause — in isolation it
+ * accumulates 1000+ routes cleanly, and heavy per-route `Params<Path>`/schema inference alone
+ * reaches 600+. The wall is an INTERACTION unique to the fluent builder: each `.get(path, handler)`
+ * both (a) computes the handler's context type from the path (`c.params.id` inferred from `:id`)
+ * AND (b) returns `Server<AddRoute<growing-R, …>, Ctx>`. Neither alone strains the compiler; the
+ * PRODUCT — recomputing the handler context while re-threading the ever-larger registry at each of
+ * N steps — exhausts TypeScript's per-expression instantiation budget around N≈95. It is therefore
+ * O(N) and inherent to any builder that infers handler context AND accumulates a typed route
+ * registry (Elysia/tRPC/hono's typed clients cap the same way); it is not fixable by reshaping
+ * AddRoute. Past ~90 routes, use a path that DOESN'T form the product: split into domain groups and
+ * `.merge()` them (each group is a short chain; a merge is one `R & R2` intersection with no
+ * per-call context work), or contract-first `implement()` (the registry is one object type declared
+ * upfront — no grow-R-per-call, so no ceiling at all).
+ */
 export type AddRoute<
   R extends Registry,
   Method extends string,

package/src/server/server.ts

@@ -1,4 +1,11 @@
-import { FrameworkError } from "../errors.ts"
+import { FrameworkError, RouteConfigError } from "../errors.ts"
+import {
+  type AssuranceDeclaration,
+  type AssuranceEvidence,
+  assuranceDeclarationsOf,
+  assuranceEvidenceFor,
+  NIFRA_ASSURANCE_IDS,
+} from "../internal/route-assurance.ts"
 import { EMPTY_PARAMS, type Method, Router } from "../router/router.ts"
 import type {
   InferOutput,
@@ -289,6 +296,8 @@ export interface RouteDescriptor {
   readonly method: Method
   readonly path: string
   readonly schema: RouteSchema | undefined
+  /** Effective enforcement evidence, populated only during reflection/introspection. */
+  readonly assurance?: readonly AssuranceEvidence[]
   readonly tool?: {
     readonly name: string
     readonly description: string
@@ -1126,9 +1135,26 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   private readonly responseRequests: WeakMap<Request, Request>
   /** Names of plugins/middleware already applied via `use` — for idempotent dedupe. */
   private readonly appliedPlugins: Set<string>
+  /** Order-scoped evidence captured by routes registered after an assured plugin. */
+  private readonly activeAssurance: AssuranceDeclaration[]
+  /** App-wide evidence from global hooks; applies retroactively to every route. */
+  private readonly globalAssurance: AssuranceDeclaration[]
   /** App-declared MCP resources / prompts (via {@link resource} / {@link prompt}), read by `nifra mcp`. */
   private readonly mcpResourceList: McpResourceDescriptor[]
   private readonly mcpPromptList: McpPromptDescriptor[]
+  /**
+   * Every registered route's raw router entry + descriptor, in order — the replay source for
+   * {@link merge}. The entry already carries the chains captured at registration (derives,
+   * decorations, before/after/around/onError), so a merged route behaves exactly as it did on
+   * the server that defined it.
+   */
+  private readonly rawEntries: Array<{
+    readonly method: Method
+    readonly path: string
+    readonly entry: RouteEntry
+    readonly descriptor: RouteDescriptor
+    readonly assurance: readonly AssuranceDeclaration[]
+  }>
 
   constructor(options: ServerOptions = {}) {
     this.router = new Router<RouteEntry>()
@@ -1154,8 +1180,11 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     this.onResponseFinalizedHooks = []
     this.responseRequests = new WeakMap()
     this.appliedPlugins = new Set()
+    this.activeAssurance = []
+    this.globalAssurance = []
     this.mcpResourceList = []
     this.mcpPromptList = []
+    this.rawEntries = []
   }
 
   /** Add a per-request, computed context extension for subsequent routes. */
@@ -1250,12 +1279,32 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         if (this.appliedPlugins.has(name)) return this // idempotent: already applied
         this.appliedPlugins.add(name)
       }
-      return arg(this)
+      const evidence = assuranceDeclarationsOf(arg)
+      const pluginOnly = evidence.filter((item) => item.scope === "plugin")
+      this.globalAssurance.push(...evidence.filter((item) => item.scope === "global"))
+      this.activeAssurance.push(...evidence.filter((item) => item.scope === "subsequent"))
+      this.activeAssurance.push(...pluginOnly)
+      try {
+        return arg(this)
+      } finally {
+        // Remove only this plugin's temporary evidence. Nested assured plugins may deliberately leave
+        // subsequent evidence active, so truncating the whole array would lose real ordering semantics.
+        for (const item of pluginOnly) {
+          const index = this.activeAssurance.indexOf(item)
+          if (index !== -1) this.activeAssurance.splice(index, 1)
+        }
+      }
     }
     if (arg.name !== undefined) {
       if (this.appliedPlugins.has(arg.name)) return this
       this.appliedPlugins.add(arg.name)
     }
+    const evidence = assuranceDeclarationsOf(arg)
+    if (evidence.some((item) => item.scope === "plugin")) {
+      throw new Error('route assurance: scope "plugin" may only annotate a plugin function')
+    }
+    this.globalAssurance.push(...evidence.filter((item) => item.scope === "global"))
+    this.activeAssurance.push(...evidence.filter((item) => item.scope === "subsequent"))
     if (arg.onRequest !== undefined) this.onRequest(arg.onRequest)
     if (arg.around !== undefined) this.around(arg.around)
     if (arg.beforeHandle !== undefined) this.beforeHandle(arg.beforeHandle)
@@ -1583,7 +1632,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
             isContextlessNoArgArrow(handler),
           )
         : undefined
-    this.router.add(method, path, {
+    const entry: RouteEntry = {
       // (context: never) => unknown -> InternalHandler: the framework invokes it
       // with the concrete RawContext the typed handler expects, so this is sound.
       handler: handler as unknown as InternalHandler,
@@ -1616,8 +1665,68 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         this.beforeHandleHooks.length === 0 &&
         this.afterHandleHooks.length === 0 &&
         this.onErrorHooks.length === 0,
+    }
+    this.router.add(method, path, entry)
+    const descriptor: RouteDescriptor = { method, path, schema }
+    this.routeList.push(descriptor)
+    const routeAssurance: AssuranceDeclaration[] = [...this.activeAssurance]
+    if (schema?.body !== undefined) {
+      routeAssurance.push(
+        Object.freeze({
+          id: NIFRA_ASSURANCE_IDS.BODY_BOUNDED,
+          source: "route-schema",
+          scope: "plugin",
+        }),
+      )
+    }
+    this.rawEntries.push({
+      method,
+      path,
+      entry,
+      descriptor,
+      assurance: Object.freeze(routeAssurance),
     })
-    this.routeList.push({ method, path, schema })
+  }
+
+  /**
+   * Merge another server's routes into this one — the composition escape hatch for large apps.
+   *
+   * WHY: the fluent chain accumulates one type-alias level per route, and TypeScript resolves
+   * that stack in one recursion — a single chain hits TS2589 at ~95 routes. Groups keep every
+   * chain short: build each domain (`listings`, `agents`, …) as its own `server()` (its registry
+   * resolves independently), then `app.merge(listings).merge(agents)` — each merge adds ONE level
+   * regardless of group size. 300+ routes stay fully typed (see many-routes.test-d.ts). The
+   * other escape hatch is contract-first `implement()`, whose registry is a single object type.
+   *
+   * Semantics: merged routes keep the chains captured where they were DEFINED — the group's
+   * `derive`/`decorate`/`beforeHandle`/`afterHandle`/`onError`/`around` apply to its routes
+   * exactly as they did standalone, so a group wires its own plugins. The group's request-level
+   * hooks (`onRequest`/`onResponse`/`onResponseFinalized`) are appended to this server's. This
+   * server's route-scoped chains do NOT retroactively wrap merged routes (order-scoped, like
+   * routes registered before a `derive`). Fail closed: a path+method collision throws
+   * `RouteConfigError` at merge time, and a group with WebSocket routes is refused (register
+   * those on the parent).
+   */
+  merge<R2 extends Registry, Ctx2>(other: Server<R2, Ctx2>): Server<R & R2, Ctx> {
+    const source = other as unknown as Server<Registry, EmptyContext>
+    if (source.wsRouteCount > 0) {
+      throw new RouteConfigError(
+        "INVALID_PATH",
+        "merge() does not carry WebSocket routes — register .ws() routes on the parent server",
+      )
+    }
+    for (const { method, path, entry, descriptor, assurance } of source.rawEntries) {
+      this.router.add(method, path, entry) // throws RouteConfigError on a duplicate — fail closed
+      this.routeList.push(descriptor) // shared ref on purpose: carries later .tool() tagging
+      this.rawEntries.push({ method, path, entry, descriptor, assurance })
+    }
+    this.onRequestHooks.push(...source.onRequestHooks)
+    this.onResponseHooks.push(...source.onResponseHooks)
+    this.onResponseFinalizedHooks.push(...source.onResponseFinalizedHooks)
+    this.globalAssurance.push(...source.globalAssurance)
+    this.mcpResourceList.push(...source.mcpResourceList)
+    this.mcpPromptList.push(...source.mcpPromptList)
+    return this as unknown as Server<R & R2, Ctx>
   }
 
   /**
@@ -1626,7 +1735,14 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * longer holds the original patterns.
    */
   routes(): ReadonlyArray<RouteDescriptor> {
-    return this.routeList
+    if (this.activeAssurance.length === 0 && this.globalAssurance.length === 0) {
+      const anyRouteEvidence = this.rawEntries.some((entry) => entry.assurance.length > 0)
+      if (!anyRouteEvidence) return this.routeList
+    }
+    return this.rawEntries.map(({ method, path, descriptor, assurance }) => {
+      const effective = assuranceEvidenceFor([...assurance, ...this.globalAssurance], method, path)
+      return effective.length > 0 ? { ...descriptor, assurance: effective } : descriptor
+    })
   }
 
   /**