@nifrajs/core 3.5.0 → 4.0.2

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 &&

package/src/internal/route-program.ts

@@ -8,24 +8,27 @@
  */
 
 import type { StandardSchemaV1 } from "../schema/standard.ts"
+import { pathnameOf } from "../server/http.ts"
 import type { Registry } from "../server/registry.ts"
 import {
   CONTEXT_SET,
   EMPTY_RESPONSE_CONTROLS,
   isResponseResult,
   type ResponseResult,
+  status,
 } from "../server/runtime-core.ts"
 import type { CtxSet, MaybePromise, RawContext, RequestSource, Server } from "../server/server.ts"
 import type {
   InternalHandler,
   RawAfterHandle,
+  RawAuthStage,
   RawBeforeHandle,
   RawDerive,
   RawErrorHandler,
   RouteEntry,
 } from "./route-execution.ts"
 
-export type ProgramValidationKind = "headers" | "params" | "body" | "query"
+export type ProgramValidationKind = "headers" | "cookies" | "params" | "body" | "query"
 
 export type RouteProgramStage =
   | { readonly kind: ProgramValidationKind; readonly schema: StandardSchemaV1 }
@@ -37,6 +40,11 @@ export type RouteProgramStage =
 /** The complete registration-time lifecycle, in semantic execution order. */
 export interface RouteProgram {
   readonly stages: readonly RouteProgramStage[]
+  readonly validationOrder: "validate-before-auth" | "auth-before-validation"
+  readonly authBeforeValidation: boolean
+  readonly authStages: readonly RawAuthStage[]
+  /** Protected route fast lane: auth plus validation/handler, with no general lifecycle hooks. */
+  readonly authFastLane: boolean
   readonly validationStages: readonly Extract<RouteProgramStage, { kind: ProgramValidationKind }>[]
   readonly derives: readonly RawDerive[]
   readonly beforeHandle: readonly RawBeforeHandle[]
@@ -54,6 +62,7 @@ export interface RouteProgramInput {
   readonly schema: RouteEntry["schema"]
   readonly handler: InternalHandler
   readonly derives: readonly RawDerive[]
+  readonly authStages?: readonly RawAuthStage[]
   readonly beforeHandle: readonly RawBeforeHandle[]
   readonly afterHandle: readonly RawAfterHandle[]
   readonly onError: readonly RawErrorHandler[]
@@ -69,25 +78,18 @@ export function compileRouteProgram(input: RouteProgramInput): RouteProgram {
   const stages: RouteProgramStage[] = []
   const validationStages: Extract<RouteProgramStage, { kind: ProgramValidationKind }>[] = []
   const schema = input.schema
-  if (schema?.headers !== undefined) {
-    const stage = { kind: "headers", schema: schema.headers } as const
-    stages.push(stage)
-    validationStages.push(stage)
-  }
-  if (schema?.params !== undefined) {
-    const stage = { kind: "params", schema: schema.params } as const
-    stages.push(stage)
-    validationStages.push(stage)
-  }
-  if (schema?.body !== undefined) {
-    const stage = { kind: "body", schema: schema.body } as const
-    stages.push(stage)
-    validationStages.push(stage)
-  }
-  if (schema?.query !== undefined) {
-    const stage = { kind: "query", schema: schema.query } as const
-    stages.push(stage)
-    validationStages.push(stage)
+  const authStages = input.authStages ?? []
+  const authBeforeValidation =
+    authStages.length > 0
+      ? schema?.validationOrder !== "validate-before-auth"
+      : schema?.validationOrder === "auth-before-validation"
+  for (const kind of ["headers", "cookies", "params", "body", "query"] as const) {
+    const validator = schema?.[kind]
+    if (validator !== undefined) {
+      const stage = { kind, schema: validator }
+      stages.push(stage)
+      validationStages.push(stage)
+    }
   }
   for (const derive of input.derives) stages.push({ kind: "derive", run: derive })
   for (const before of input.beforeHandle) stages.push({ kind: "before", run: before })
@@ -96,6 +98,14 @@ export function compileRouteProgram(input: RouteProgramInput): RouteProgram {
 
   return Object.freeze({
     stages: Object.freeze(stages),
+    validationOrder: authBeforeValidation ? "auth-before-validation" : "validate-before-auth",
+    authBeforeValidation,
+    authStages: Object.freeze([...authStages]),
+    authFastLane:
+      authStages.length > 0 &&
+      input.derives.length === 0 &&
+      input.beforeHandle.length === 0 &&
+      input.afterHandle.length === 0,
     validationStages: Object.freeze(validationStages),
     derives: Object.freeze([...input.derives]),
     beforeHandle: Object.freeze([...input.beforeHandle]),
@@ -146,8 +156,395 @@ function isEarly(value: unknown): value is Response | ResponseResult {
   return value instanceof Response || isResponseResult(value)
 }
 
+function authHeadersOf(source: RequestSource): import("../server/auth.ts").AuthHeaders {
+  return Object.freeze({
+    get: (name: string) => source.headers.get(name),
+    has: (name: string) => source.headers.has(name),
+    forEach: (callback: (value: string, name: string) => void) => {
+      source.headers.forEach(callback)
+    },
+  })
+}
+
+function authenticationInputOf(
+  source: RequestSource,
+  ctx: RawContext,
+): import("../server/auth.ts").AuthenticationInput<unknown> {
+  return Object.freeze({
+    method: source.method,
+    pathname: pathnameOf(source.url),
+    headers: authHeadersOf(source),
+    params: Object.freeze({ ...ctx.params }),
+    env: ctx.env,
+    clientIp: ctx.clientIp,
+    signal: ctx.signal,
+  })
+}
+
+function defaultAuthenticationResponse(
+  reason: import("../server/auth.ts").AuthenticationFailureReason | undefined,
+): ResponseResult {
+  if (reason === "forbidden") return status(403, { ok: false, error: "forbidden" })
+  if (reason === "unavailable") return status(503, { ok: false, error: "auth_unavailable" })
+  return status(401, { ok: false, error: "unauthorized" })
+}
+
+function validAuthenticationFailureReason(
+  value: unknown,
+): value is import("../server/auth.ts").AuthenticationFailureReason | undefined {
+  return (
+    value === undefined ||
+    value === "unauthenticated" ||
+    value === "forbidden" ||
+    value === "unavailable"
+  )
+}
+
+function runAuthenticationStages<T>(
+  host: RouteProgramRuntime,
+  entry: RouteEntry,
+  program: RouteProgram,
+  source: RequestSource,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
+  start = 0,
+  validationComplete = false,
+): ProgramResult<T> {
+  if (start >= program.authStages.length) {
+    if (program.authFastLane) {
+      const validationIndex = validationComplete ? program.validationStages.length : 0
+      return runFastAuthenticatedProgram(
+        host,
+        entry,
+        program,
+        source,
+        ctx,
+        finalize,
+        wrapResponse,
+        validationIndex,
+      )
+    }
+    return validationComplete
+      ? runSync(
+          host,
+          entry,
+          program,
+          source,
+          ctx,
+          finalize,
+          wrapResponse,
+          program.validationStages.length,
+          undefined,
+        )
+      : runValidatedProgram(host, entry, program, source, ctx, finalize, wrapResponse)
+  }
+  const input = authenticationInputOf(source, ctx)
+  const stage = program.authStages[start]!
+  let outcome: MaybePromise<import("../server/auth.ts").AuthenticationResult<unknown>>
+  try {
+    outcome = stage.run(input)
+  } catch {
+    return finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx))
+  }
+  if (outcome instanceof Promise) {
+    return outcome.then(
+      (settled) =>
+        finishAuthentication(
+          host,
+          entry,
+          program,
+          source,
+          ctx,
+          finalize,
+          wrapResponse,
+          settled,
+          start + 1,
+          validationComplete,
+        ),
+      () => finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx)),
+    )
+  }
+  return finishAuthentication(
+    host,
+    entry,
+    program,
+    source,
+    ctx,
+    finalize,
+    wrapResponse,
+    outcome,
+    start + 1,
+    validationComplete,
+  )
+}
+
+function finishAuthentication<T>(
+  host: RouteProgramRuntime,
+  entry: RouteEntry,
+  program: RouteProgram,
+  source: RequestSource,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
+  result: import("../server/auth.ts").AuthenticationResult<unknown>,
+  next: number,
+  validationComplete = false,
+): ProgramResult<T> {
+  if (
+    result === null ||
+    typeof result !== "object" ||
+    (result.kind !== "authenticated" && result.kind !== "rejected")
+  ) {
+    return finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx))
+  }
+  if (result.kind === "rejected") {
+    if (!validAuthenticationFailureReason(result.reason)) {
+      return finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx))
+    }
+    if (
+      result.response !== undefined &&
+      !(result.response instanceof Response) &&
+      !isResponseResult(result.response)
+    ) {
+      return finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx))
+    }
+    const response = result.response ?? defaultAuthenticationResponse(result.reason)
+    return finalize(response, responseSet(ctx))
+  }
+  if (result.principal === null || result.principal === undefined) {
+    return finalize(defaultAuthenticationResponse("unavailable"), responseSet(ctx))
+  }
+  Object.defineProperty(ctx, "principal", {
+    value: result.principal,
+    enumerable: true,
+    configurable: true,
+    writable: false,
+  })
+  return runAuthenticationStages(
+    host,
+    entry,
+    program,
+    source,
+    ctx,
+    finalize,
+    wrapResponse,
+    next,
+    validationComplete,
+  )
+}
+
+/** Validate first only when a route explicitly opts out of the protected auth-first default. */
+function runFastAuthenticatedProgram<T>(
+  host: RouteProgramRuntime,
+  entry: RouteEntry,
+  program: RouteProgram,
+  source: RequestSource,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
+  validationIndex: number,
+): ProgramResult<T> {
+  for (let i = validationIndex; i < program.validationStages.length; i++) {
+    const stage = program.validationStages[i]!
+    const outcome =
+      stage.kind === "body"
+        ? host.readProgramBody(entry, source, ctx)
+        : host.validateProgramStage(entry, stage, source, ctx)
+    if (outcome instanceof Promise) {
+      return continueFastAuthenticatedProgram(
+        host,
+        entry,
+        program,
+        source,
+        ctx,
+        finalize,
+        wrapResponse,
+        i + 1,
+        outcome,
+      )
+    }
+    if (outcome !== undefined) return wrapResponse(outcome)
+  }
+  return runFastAuthenticatedHandler(host, entry, program, ctx, finalize, wrapResponse)
+}
+
+async function continueFastAuthenticatedProgram<T>(
+  host: RouteProgramRuntime,
+  entry: RouteEntry,
+  program: RouteProgram,
+  source: RequestSource,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
+  validationIndex: number,
+  pending: Promise<unknown>,
+): Promise<T> {
+  try {
+    const settled = await pending
+    if (settled !== undefined) return wrapResponse(settled as Response | ResponseResult)
+    return await runFastAuthenticatedProgram(
+      host,
+      entry,
+      program,
+      source,
+      ctx,
+      finalize,
+      wrapResponse,
+      validationIndex,
+    )
+  } catch (error) {
+    return await host.handleProgramError(entry, error, ctx, finalize, wrapResponse)
+  }
+}
+
+function runFastAuthenticatedHandler<T>(
+  host: RouteProgramRuntime,
+  entry: RouteEntry,
+  program: RouteProgram,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
+): ProgramResult<T> {
+  let result: unknown
+  try {
+    result = program.handler(ctx)
+  } catch (error) {
+    return host.handleProgramError(entry, error, ctx, finalize, wrapResponse)
+  }
+  if (result instanceof Promise) {
+    return result.then(
+      (value) => host.finishProgramResult(entry, ctx, value, finalize, wrapResponse),
+      (error) => host.handleProgramError(entry, error, ctx, finalize, wrapResponse),
+    )
+  }
+  return host.finishProgramResult(entry, ctx, result, finalize, wrapResponse)
+}
+
+function runValidationBeforeAuthentication<T>(
+  host: RouteProgramRuntime,
+  entry: RouteEntry,
+  program: RouteProgram,
+  source: RequestSource,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
+  validationIndex = 0,
+): ProgramResult<T> {
+  for (let i = validationIndex; i < program.validationStages.length; i++) {
+    const stage = program.validationStages[i]!
+    const outcome =
+      stage.kind === "body"
+        ? host.readProgramBody(entry, source, ctx)
+        : host.validateProgramStage(entry, stage, source, ctx)
+    if (outcome instanceof Promise) {
+      return continueValidationBeforeAuthentication(
+        host,
+        entry,
+        program,
+        source,
+        ctx,
+        finalize,
+        wrapResponse,
+        i + 1,
+        outcome,
+      )
+    }
+    if (outcome !== undefined) return wrapResponse(outcome)
+  }
+  return runAuthenticationStages(host, entry, program, source, ctx, finalize, wrapResponse, 0, true)
+}
+
+async function continueValidationBeforeAuthentication<T>(
+  host: RouteProgramRuntime,
+  entry: RouteEntry,
+  program: RouteProgram,
+  source: RequestSource,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
+  validationIndex: number,
+  pending: Promise<unknown>,
+): Promise<T> {
+  try {
+    const settled = await pending
+    if (settled !== undefined) return wrapResponse(settled as Response | ResponseResult)
+    return await runValidationBeforeAuthentication(
+      host,
+      entry,
+      program,
+      source,
+      ctx,
+      finalize,
+      wrapResponse,
+      validationIndex,
+    )
+  } catch (error) {
+    return await host.handleProgramError(entry, error, ctx, finalize, wrapResponse)
+  }
+}
+
+function runValidatedProgram<T>(
+  host: RouteProgramRuntime,
+  entry: RouteEntry,
+  program: RouteProgram,
+  source: RequestSource,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
+): ProgramResult<T> {
+  if (program.hasDecorations) Object.assign(ctx, program.decorations)
+  return runSync(host, entry, program, source, ctx, finalize, wrapResponse, 0, undefined)
+}
+
 type ProgramResult<T> = MaybePromise<T>
 
+/** Opt-in sensitive-route lane: run authentication/policy hooks before parsing untrusted input. */
+async function runAuthBeforeValidation<T>(
+  host: RouteProgramRuntime,
+  entry: RouteEntry,
+  program: RouteProgram,
+  source: RequestSource,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
+): Promise<T> {
+  try {
+    if (program.hasDecorations) Object.assign(ctx, program.decorations)
+
+    for (const derive of program.derives) {
+      const result = derive(ctx)
+      const settled = result instanceof Promise ? await result : result
+      if (isEarly(settled)) return finalize(settled, responseSet(ctx))
+      Object.assign(ctx, settled)
+    }
+
+    for (const before of program.beforeHandle) {
+      const result = before(ctx)
+      const settled = result instanceof Promise ? await result : result
+      if (settled !== undefined) return finalize(settled, responseSet(ctx))
+    }
+
+    for (const stage of program.validationStages) {
+      const result =
+        stage.kind === "body"
+          ? await host.readProgramBody(entry, source, ctx)
+          : host.validateProgramStage(entry, stage, source, ctx)
+      const settled = result instanceof Promise ? await result : result
+      if (settled !== undefined) return wrapResponse(settled)
+    }
+
+    let result = await program.handler(ctx)
+    for (const after of program.afterHandle) {
+      const transformed = after(result, ctx)
+      result = transformed instanceof Promise ? await transformed : transformed
+    }
+    return await host.finishProgramResult(entry, ctx, result, finalize, wrapResponse)
+  } catch (error) {
+    return await host.handleProgramError(entry, error, ctx, finalize, wrapResponse)
+  }
+}
+
 type PendingPhase =
   | { readonly kind: "validation"; readonly next: number }
   | { readonly kind: "derive"; readonly next: number }
@@ -167,6 +564,23 @@ export function executeRouteProgram<T, R extends Registry, Ctx>(
 ): ProgramResult<T> {
   const host = runtime as unknown as RouteProgramRuntime
   try {
+    if (program.authStages.length > 0) {
+      if (program.hasDecorations) Object.assign(ctx, program.decorations)
+      return program.authBeforeValidation
+        ? runAuthenticationStages(host, entry, program, source, ctx, finalize, wrapResponse)
+        : runValidationBeforeAuthentication(
+            host,
+            entry,
+            program,
+            source,
+            ctx,
+            finalize,
+            wrapResponse,
+          )
+    }
+    if (program.validationOrder === "auth-before-validation") {
+      return runAuthBeforeValidation(host, entry, program, source, ctx, finalize, wrapResponse)
+    }
     if (program.hasDecorations) Object.assign(ctx, program.decorations)
     return runSync(host, entry, program, source, ctx, finalize, wrapResponse, 0, undefined)
   } catch (error) {