@nifrajs/core 1.7.0 → 1.9.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/context.ts

@@ -1,3 +1,4 @@
+import type { RequestBudget } from "@nifrajs/budget"
 import type { InferOutput, StandardIssue, StandardSchemaV1 } from "../schema/standard.ts"
 import type { CookieOptions } from "./cookies.ts"
 
@@ -133,6 +134,11 @@ export interface Context<Path extends string = string, S extends RouteSchema = R
    * timed-out request stops doing work instead of running on after the 503.
    */
   readonly signal: AbortSignal
+  /**
+   * Absolute request deadline plus monotonic remaining time. It shares {@link signal}; the server
+   * clamps an inbound deadline to local policy when `acceptInboundDeadlines` is enabled.
+   */
+  readonly budget: RequestBudget
   /**
    * Platform bindings from `app.fetch(request, { env })` — Workers `env` (KV/D1/secrets), etc.
    * `undefined` off-edge (Bun/Node/Deno). Declare the shape with `server<Env>()` to read it typed

package/src/server/registry.ts

@@ -78,14 +78,20 @@ export type OutputOf<H extends (...args: never[]) => unknown> = Exclude<
 /**
  * Merge a new route into the registry, combining methods that share a path.
  *
- * SCALING CEILING (measured, see many-routes.test-d.ts): each chained route call nests one alias
- * level (`AddRoute<AddRoute<...`), and TypeScript resolves the whole stack lazily in ONE
- * recursion on first demand — its instantiation-depth limit fires as TS2589 at ~95-100 calls on
- * a single server. Eager-flattening variants (mapped remap, `extends infer` force, phantom
- * constraint params) were all tried and either lower the ceiling or leave spurious diagnostics —
- * the lazy first-walk is not defeatable from library code. Past ~90 routes on one app, compose
- * instead: split into domain groups and `.merge()` them (each group resolves its own short
- * stack), or use contract-first `implement()` (a single object type — no accumulation at all).
+ * 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,