@nifrajs/core 3.3.0 → 4.0.0

package/src/index.ts

@@ -16,14 +16,25 @@
  * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and
  * `check:publish` asserts it equals `@nifrajs/core`'s package version.
  */
-export const VERSION = "3.3.0" as const
+export const VERSION = "4.0.0" as const
 
 export type Version = typeof VERSION
 
 export { FrameworkError, RouteConfigError, type RouteConfigErrorCode } from "./errors.ts"
 export { FRAMEWORK_NAME, type FrameworkName } from "./internal/brand.ts"
 export { isSameOriginRequest } from "./internal/same-origin.ts"
-export { METHODS, type Method, Router, type RouterMatch } from "./router/router.ts"
+export {
+  ROUTE_PATTERN_OVERLAP_MAX_STATES,
+  RoutePatternOverlapLimitError,
+  routePatternOverlap,
+} from "./router/overlap.ts"
+export {
+  METHODS,
+  type Method,
+  type RouteMethod,
+  Router,
+  type RouterMatch,
+} from "./router/router.ts"
 export type {
   InferInput,
   InferOutput,
@@ -33,11 +44,24 @@ export type {
   StandardTypes,
   ValidationOutcome,
 } from "./schema/standard.ts"
+export {
+  type AuthenticationFailure,
+  type AuthenticationFailureReason,
+  type AuthenticationInput,
+  type AuthenticationResult,
+  type AuthenticationStage,
+  type AuthenticationSuccess,
+  type AuthHeaders,
+  type AuthMaybePromise,
+  authenticated,
+  rejected,
+} from "./server/auth.ts"
 export type {
   Context,
   Params,
   Platform,
   Prettify,
+  RequestPath,
   ResponseControls,
   RouteSchema,
 } from "./server/context.ts"
@@ -45,6 +69,7 @@ export {
   type CookieOptions,
   type CookieSecret,
   cookieNamePrefix,
+  hasDuplicateCookie,
   parseCookies,
   serializeCookie,
   signValue,
@@ -82,7 +107,15 @@ export {
   toVercelHandler,
   type VercelHandler,
 } from "./server/platform-adapters.ts"
-export type { Registry, ResponseMapFor, RouteInfo, RouteInfoFor } from "./server/registry.ts"
+export type {
+  JoinRoutePath,
+  PrefixRegistry,
+  Registry,
+  ResponseMapFor,
+  RouteInfo,
+  RouteInfoFor,
+} from "./server/registry.ts"
+export { replacedRequestOf } from "./server/request-lineage.ts"
 export {
   type PlainRender,
   type ResponseResult,
@@ -101,13 +134,18 @@ export {
   defineRouterPlugin,
   type Handler,
   type IdentityPlugin,
+  type ListenTlsOptions,
   type McpPromptDescriptor,
   type McpResourceDescriptor,
   type Middleware,
+  type MountableApp,
+  type MountFetchOptions,
+  type MountOptions,
   type NifraFeatureVersion,
   type NifraPlugin,
   type NodeRequestContext,
   type NodeRequestHook,
+  type NodeResponseBodyHook,
   type NodeResponseContext,
   type NodeResponseHook,
   type NodeServeOutcome,

package/src/internal/code-unit-order.ts

@@ -0,0 +1,8 @@
+/**
+ * Code-unit order, the same on every runtime and in every locale. `localeCompare` answers by the
+ * runtime's locale and ICU data, so an artifact that is hashed, signed, or committed sorts with this
+ * instead: its bytes must not depend on the machine that built it.
+ */
+export function codeUnitOrder(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0
+}

package/src/internal/durable-saga-protocol.ts

@@ -22,6 +22,8 @@ function transitionSaga(
 ): SagaRecord | undefined {
   if (
     input.record.version !== input.version + 1 ||
+    // A record filed under another saga's key could never load again, and scans would act on its id.
+    input.record.sagaId !== input.sagaId ||
     (current !== undefined &&
       (current.sagaId !== input.sagaId || current.version !== input.version))
   ) {

package/src/internal/route-catalog.ts

@@ -16,7 +16,7 @@
  * registration.
  */
 import type { CompiledRoutePattern } from "../router/pattern.ts"
-import { type Method, Router, type RouterMatch } from "../router/router.ts"
+import { Router, type RouterMatch } from "../router/router.ts"
 import type { RouteDescriptor } from "../server/server-types.ts"
 import type { AssuranceDeclaration } from "./route-assurance.ts"
 import type { RouteEntry } from "./route-execution.ts"
@@ -24,7 +24,7 @@ import type { RouteEntry } from "./route-execution.ts"
 /** One canonical runtime route fact. The catalog owns matching, reflection, assurance, tool metadata,
  * replay, and native compilation input so batch registration has one commit point. */
 export interface CatalogRoute {
-  readonly method: Method
+  readonly method: string
   readonly path: string
   readonly pattern: CompiledRoutePattern
   readonly entry: RouteEntry
@@ -33,10 +33,10 @@ export interface CatalogRoute {
 }
 
 /**
- * Runtime route catalog. Single-route registration mutates directly; multi-route registration replays
- * the existing catalog plus the candidate batch into a staged router, then swaps the complete state only
- * after every route validates. Failed `implement()`/`merge()` batches therefore leave matching and
- * reflection unchanged.
+ * Runtime route catalog. Single-route registration mutates directly. A batch adds its routes the same
+ * way and, if one is rejected, restores the catalog to what it was before the batch. A failed
+ * `implement()`/`merge()` batch therefore leaves matching and reflection unchanged, and a batch that
+ * validates costs what its routes cost one by one.
  *
  * Coverage note: this file reports 90% functions with every method exercised. `bun test --coverage`
  * (1.3.14) counts one synthetic function per class that it never marks hit - a one-method class with a
@@ -58,18 +58,19 @@ export class RouteCatalog {
   }
 
   addBatch(routes: readonly CatalogRoute[]): void {
-    if (routes.length === 0) return
-    const nextRecords = this.records.concat(routes)
-    const nextDescriptors = this.descriptors.concat(routes.map(({ descriptor }) => descriptor))
-    const nextAssurancePresent =
-      this.assurancePresent || routes.some((route) => route.assurance.length > 0)
-    const staged = new Router<RouteEntry>()
-    for (const route of this.records) staged.add(route.method, route.pattern, route.entry)
-    for (const route of routes) staged.add(route.method, route.pattern, route.entry)
-    this.matcher = staged
-    this.records = nextRecords
-    this.descriptors = nextDescriptors
-    this.assurancePresent = nextAssurancePresent
+    const kept = this.records.length
+    const assurancePresent = this.assurancePresent
+    try {
+      for (const route of routes) this.add(route)
+    } catch (error) {
+      // The rejected route may have left nodes in the trie, so the matcher is not patched: it is
+      // rebuilt from the routes that were there before the batch. They validated once already.
+      this.records.length = this.descriptors.length = kept
+      this.assurancePresent = assurancePresent
+      this.matcher = new Router<RouteEntry>()
+      for (const route of this.records) this.matcher.add(route.method, route.pattern, route.entry)
+      throw error
+    }
   }
 
   find(method: string, path: string): RouterMatch<RouteEntry> {

package/src/internal/route-compiler.ts

@@ -13,13 +13,14 @@
 import type { EffectLifecycleObserver } from "../effect-lifecycle.ts"
 import { RouteConfigError } from "../errors.ts"
 import { type CompiledRoutePattern, compileRoutePattern } from "../router/pattern.ts"
-import type { Method } from "../router/router.ts"
-import type { StandardSchemaV1 } from "../schema/standard.ts"
 import { assertByteLimit } from "../server/body.ts"
 import type { RouteSchema } from "../server/context.ts"
 import type { IdempotencyRuntime, ResolvedIdempotency } from "../server/idempotency-lane.ts"
 import type { EffectLedgerRuntime, ResolvedEffectLedger } from "../server/ledger-lane.ts"
-import type { ResponseContractRuntime } from "../server/response-contract-lane.ts"
+import type {
+  ResponseContractDefinition,
+  ResponseContractRuntime,
+} from "../server/response-contract-lane.ts"
 import {
   CAPABILITY_GUARD,
   type CapabilityUseEvent,
@@ -37,6 +38,7 @@ import {
 import type {
   RawAfterHandle,
   RawAround,
+  RawAuthStage,
   RawBeforeHandle,
   RawDerive,
   RawErrorHandler,
@@ -55,6 +57,7 @@ export interface RouteCompilerContext {
   readonly idempotencyRuntime: IdempotencyRuntime | undefined
   readonly responseContractRuntime: ResponseContractRuntime | undefined
   readonly derives: readonly RawDerive[]
+  readonly authStages: readonly RawAuthStage[]
   readonly beforeHandleHooks: readonly RawBeforeHandle[]
   readonly afterHandleHooks: readonly RawAfterHandle[]
   readonly onErrorHooks: readonly RawErrorHandler[]
@@ -72,16 +75,18 @@ export interface CompiledRouteOptions {
   readonly idempotent: ResolvedIdempotency | undefined
   readonly ledgered: ResolvedEffectLedger | undefined
   readonly responseContract:
-    | { readonly runtime: ResponseContractRuntime; readonly schema: StandardSchemaV1 }
+    | { readonly runtime: ResponseContractRuntime; readonly definition: ResponseContractDefinition }
     | undefined
   readonly lanes: RouteLaneSelection
   readonly routeAssurance: readonly AssuranceDeclaration[]
+  readonly authStages: readonly RawAuthStage[]
+  readonly authenticated: boolean
 }
 
 /** Resolve all registration-time policy and lane facts for one route. */
 export function compileRouteOptions(
   context: RouteCompilerContext,
-  method: Method,
+  method: string,
   path: string,
   schema: RouteSchema | undefined,
   handler: (context: never) => unknown,
@@ -91,6 +96,25 @@ export function compileRouteOptions(
   const invalidBodyLimit = (message: string): never => {
     throw new RouteConfigError("INVALID_BODY_LIMIT", `route ${method} ${path}: ${message}`)
   }
+  if (schema?.wire !== undefined && schema.wire !== "raw") {
+    throw new RouteConfigError("INVALID_WIRE", `route ${method} ${path}: wire must be "raw"`)
+  }
+  if (schema?.wire === "raw" && schema.body !== undefined) {
+    throw new RouteConfigError(
+      "INVALID_WIRE",
+      `route ${method} ${path}: wire: "raw" cannot be combined with a body schema`,
+    )
+  }
+  if (
+    schema?.validationOrder !== undefined &&
+    schema.validationOrder !== "validate-before-auth" &&
+    schema.validationOrder !== "auth-before-validation"
+  ) {
+    throw new RouteConfigError(
+      "INVALID_VALIDATION_ORDER",
+      `route ${method} ${path}: validationOrder is invalid`,
+    )
+  }
   if (schema?.bodyLimitReason !== undefined && schema.bodyLimit !== "unlimited") {
     invalidBodyLimit('bodyLimitReason is only valid with bodyLimit: "unlimited"')
   }
@@ -124,11 +148,13 @@ export function compileRouteOptions(
     )
   }
 
-  const authenticated = assuranceEvidenceFor(
-    [...context.activeAssurance, ...handlerAssurance, ...context.globalAssurance],
-    method,
-    path,
-  ).some((evidence) => evidence.id === NIFRA_ASSURANCE_IDS.AUTHENTICATED)
+  const authenticated =
+    context.authStages.length > 0 ||
+    assuranceEvidenceFor(
+      [...context.activeAssurance, ...handlerAssurance, ...context.globalAssurance],
+      method,
+      path,
+    ).some((evidence) => evidence.id === NIFRA_ASSURANCE_IDS.AUTHENTICATED)
   const routeDecorations: Record<PropertyKey, unknown> = { ...context.decorations }
   if (capabilities.length > 0) {
     routeDecorations[CAPABILITY_GUARD] = createCapabilityGuard(
@@ -155,12 +181,20 @@ export function compileRouteOptions(
     context.maxBodyBytes,
   )
   const ledgered = context.effectLedgerRuntime?.resolve(capabilities, method, path)
+  const responseDefinition =
+    schema?.response !== undefined || schema?.errors !== undefined
+      ? {
+          ...(schema.response === undefined ? {} : { response: schema.response }),
+          ...(schema.errors === undefined ? {} : { errors: schema.errors }),
+        }
+      : undefined
   const contracted =
-    context.responseContractRuntime !== undefined && schema?.response !== undefined
-      ? { runtime: context.responseContractRuntime, schema: schema.response }
+    context.responseContractRuntime !== undefined && responseDefinition !== undefined
+      ? { runtime: context.responseContractRuntime, definition: responseDefinition }
       : undefined
   const lanes = selectRouteLanes({
     schema,
+    hasAuth: context.authStages.length > 0,
     hasIdempotency: idempotent !== undefined,
     hasLedger: ledgered !== undefined,
     hasResponseContract: contracted !== undefined,
@@ -174,7 +208,7 @@ export function compileRouteOptions(
   })
 
   const routeAssurance: AssuranceDeclaration[] = [...context.activeAssurance, ...handlerAssurance]
-  if (contracted?.runtime.mode === "enforce" && schema?.response !== undefined) {
+  if (contracted?.runtime.mode === "enforce") {
     routeAssurance.push(
       Object.freeze({
         id: NIFRA_ASSURANCE_IDS.RESPONSE_CONTRACT,
@@ -217,6 +251,19 @@ export function compileRouteOptions(
       }),
     )
   }
+  if (context.authStages.length > 0) {
+    // `authenticate()` is an actual runtime enforcement stage, not a route assertion. Publish its
+    // proof directly so a core-authenticated route cannot accidentally become assurance
+    // classification-only when it is not using an integration plugin such as better-auth.
+    routeAssurance.push(
+      Object.freeze({
+        id: NIFRA_ASSURANCE_IDS.AUTHENTICATED,
+        source: "nifra.authenticate",
+        scope: "plugin",
+        provenance: "runtime" as const,
+      }),
+    )
+  }
 
   return {
     pattern,
@@ -230,5 +277,7 @@ export function compileRouteOptions(
     responseContract: contracted,
     lanes,
     routeAssurance: Object.freeze(routeAssurance),
+    authStages: Object.freeze([...context.authStages]),
+    authenticated,
   }
 }

package/src/internal/route-execution.ts

@@ -18,7 +18,7 @@
  */
 import type { RequestBudget } from "../budget.ts"
 import type { RequestLedger } from "../ledger.ts"
-import type { StandardSchemaV1 } from "../schema/standard.ts"
+import type { AuthenticationStage } from "../server/auth.ts"
 import { UNLIMITED_BODY_BYTES } from "../server/body.ts"
 import type { Platform, RouteSchema } from "../server/context.ts"
 import type { ResolvedIdempotency } from "../server/idempotency-lane.ts"
@@ -26,7 +26,10 @@ import type { EffectLedgerRuntime, ResolvedEffectLedger } from "../server/ledger
 import type { ProtoPoisoning } from "../server/proto-guard.ts"
 import type { Registry } from "../server/registry.ts"
 import { RequestContext } from "../server/request-context.ts"
-import type { ResponseContractRuntime } from "../server/response-contract-lane.ts"
+import type {
+  ResponseContractDefinition,
+  ResponseContractRuntime,
+} from "../server/response-contract-lane.ts"
 import type { HandlerResult, ResponseResult } from "../server/runtime-core.ts"
 import type { CtxSet, MaybePromise, RawContext, RequestSource, Server } from "../server/server.ts"
 import type { RouteProgram } from "./route-program.ts"
@@ -35,6 +38,8 @@ export type InternalHandler = (ctx: RawContext) => MaybePromise<HandlerResult>
 
 /** A `derive` computes per-request context extensions; stored path-erased. */
 export type RawDerive = (ctx: RawContext) => MaybePromise<object>
+/** A route-scoped authentication provider, stored path-erased after registration. */
+export type RawAuthStage = AuthenticationStage<unknown, unknown>
 export type RawBeforeHandle = (ctx: RawContext) => MaybePromise<unknown>
 export type RawAfterHandle = (result: unknown, ctx: RawContext) => MaybePromise<unknown>
 export type RawErrorHandler = (error: unknown, ctx: RawContext) => MaybePromise<unknown>
@@ -311,10 +316,15 @@ export interface RouteEntry {
    * at registration; `undefined` = not checked (the default, and the only state in which the route can
    * still take the fused/native lanes). */
   readonly responseContract:
-    | { readonly runtime: ResponseContractRuntime; readonly schema: StandardSchemaV1 }
+    | {
+        readonly runtime: ResponseContractRuntime
+        readonly definition: ResponseContractDefinition
+      }
     | undefined
   /** Per-request context extensions captured at registration (order-scoped). */
   readonly derives: ReadonlyArray<RawDerive>
+  /** Dedicated auth stages run before validation; ordinary derives keep their existing order. */
+  readonly authStages: ReadonlyArray<RawAuthStage>
   /** Static context extensions captured at registration. */
   readonly decorations: Record<PropertyKey, unknown>
   /** Whether {@link decorations} has any keys - precomputed so the hot path skips a no-op

package/src/internal/route-lanes.ts

@@ -31,6 +31,7 @@ export interface RouteLaneSelection {
 
 export function selectRouteLanes(options: {
   readonly schema: RouteSchema | undefined
+  readonly hasAuth?: boolean
   readonly hasIdempotency: boolean
   readonly hasLedger: boolean
   readonly hasResponseContract: boolean
@@ -56,9 +57,15 @@ export function selectRouteLanes(options: {
     defaultOnValidationError,
   } = options
 
+  const authBeforeValidation =
+    options.hasAuth === true || schema?.validationOrder === "auth-before-validation"
+  // No fused lane validates params, headers, or cookies: any of those schemas keeps the stage runner.
+  const plain =
+    schema?.params === undefined && schema?.headers === undefined && schema?.cookies === undefined
+
   const bare =
-    schema?.params === undefined &&
-    schema?.headers === undefined &&
+    !authBeforeValidation &&
+    plain &&
     schema?.body === undefined &&
     schema?.query === undefined &&
     !hasIdempotency &&
@@ -76,11 +83,11 @@ export function selectRouteLanes(options: {
   // exactly `validationError(issues)`, so any recovery semantics keep the generic lane.
   const fusedQuery =
     !bare &&
+    !authBeforeValidation &&
     !hasResponseContract &&
     schema?.query !== undefined &&
     schema.body === undefined &&
-    schema.params === undefined &&
-    schema.headers === undefined &&
+    plain &&
     schema.onValidationError === undefined &&
     !defaultOnValidationError &&
     !hasIdempotency &&
@@ -92,11 +99,11 @@ export function selectRouteLanes(options: {
     around === 0
 
   const bodyOnly =
+    !authBeforeValidation &&
     !hasResponseContract &&
     schema?.body !== undefined &&
     schema.query === undefined &&
-    schema.params === undefined &&
-    schema.headers === undefined &&
+    plain &&
     derives === 0 &&
     beforeHandle === 0 &&
     afterHandle === 0 &&
@@ -104,6 +111,7 @@ export function selectRouteLanes(options: {
 
   const fusedBody =
     !bare &&
+    !authBeforeValidation &&
     bodyOnly &&
     schema.onValidationError === undefined &&
     !defaultOnValidationError &&
@@ -111,28 +119,29 @@ export function selectRouteLanes(options: {
     !hasLedger &&
     around === 0
 
-  const lane: RouteExecutionLane = bare
-    ? "bare"
-    : bodyOnly
-      ? "body"
-      : !hasResponseContract &&
-          schema?.body === undefined &&
-          schema?.query !== undefined &&
-          schema.params === undefined &&
-          schema.headers === undefined &&
-          derives === 0 &&
-          beforeHandle === 0 &&
-          afterHandle === 0 &&
-          onError === 0
-        ? "query"
-        : "lifecycle"
+  const lane: RouteExecutionLane = authBeforeValidation
+    ? "lifecycle"
+    : bare
+      ? "bare"
+      : bodyOnly
+        ? "body"
+        : !hasResponseContract &&
+            schema?.body === undefined &&
+            schema?.query !== undefined &&
+            plain &&
+            derives === 0 &&
+            beforeHandle === 0 &&
+            afterHandle === 0 &&
+            onError === 0
+          ? "query"
+          : "lifecycle"
 
   // Lifecycle routes with no params schema are the common middleware shape: derive/before plus an
   // optional query or body schema. Select their complete validation stage at registration so the
   // request path never re-checks params/body presence. Parameter-schema routes retain the generic
   // lifecycle runner until their more involved recovery matrix is selected explicitly.
   const lifecycleLane: LifecycleExecutionLane =
-    lane !== "lifecycle" || schema?.params !== undefined || schema?.headers !== undefined
+    lane !== "lifecycle" || !plain
       ? undefined
       : schema?.body !== undefined
         ? schema.query !== undefined
@@ -145,21 +154,21 @@ export function selectRouteLanes(options: {
   // The realistic middleware shape is commonly exactly one synchronous-or-async derive followed by
   // one before hook. Keep the generic runner for every route that can observe decorations, after hooks,
   // error hooks, or response contracts; this lane only removes the two per-request hook-loop dispatches
-  // and preserves the same async continuations and error handling. A params or headers schema routes
-  // back to the generic lane because the fused builder has no `params` / `headers` validation step
+  // and preserves the same async continuations and error handling. A params, headers, or cookies schema
+  // routes back to the generic lane because the fused builder has no validation step for them
   // baked in - adding them would be more code than it saves. A `body` schema is the same story
   // because the fused derive-before / derive-before-after builders don't parse the body: routes with a
   // body schema are routed to the `body-derive-before` / `body-derive-before-after` lane below.
   const lifecycleHookLane =
     lane === "lifecycle" &&
+    !authBeforeValidation &&
     !hasResponseContract &&
     !hasDecorations &&
     !hasIdempotency &&
     !hasLedger &&
     schema?.onValidationError === undefined &&
     !defaultOnValidationError &&
-    schema?.params === undefined &&
-    schema?.headers === undefined &&
+    plain &&
     schema?.body === undefined &&
     derives === 1 &&
     beforeHandle === 1 &&
@@ -177,10 +186,10 @@ export function selectRouteLanes(options: {
   // win `fusedBody` already gives for the no-hooks body shape.
   const fusedBodyLifecycle =
     lane === "lifecycle" &&
+    !authBeforeValidation &&
     schema?.body !== undefined &&
     schema?.query === undefined &&
-    schema?.params === undefined &&
-    schema?.headers === undefined &&
+    plain &&
     schema?.onValidationError === undefined &&
     !defaultOnValidationError &&
     !hasResponseContract &&