@nifrajs/core 3.3.0 → 4.0.0

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) {

package/src/ledger.ts

@@ -145,7 +145,7 @@ const ERROR_CODE = /^[a-z][a-z0-9_.-]{0,63}$/
 const DIGEST_HEX = /^[0-9a-f]{64}$/
 
 function printableToken(value: string, maxLength: number): boolean {
-  if (value.length === 0 || value.length > maxLength) return false
+  if (typeof value !== "string" || value.length === 0 || value.length > maxLength) return false
   for (let index = 0; index < value.length; index++) {
     const code = value.charCodeAt(index)
     if (code < 33 || code > 126) return false
@@ -153,6 +153,9 @@ function printableToken(value: string, maxLength: number): boolean {
   return true
 }
 
+// `RegExp.test` stringifies its argument, so a check on a token's shape must first check it is a string.
+const validDigest = (value: string): boolean => typeof value === "string" && DIGEST_HEX.test(value)
+
 function validateCost(cost: EffectCost): EffectCost {
   if (Object(cost) !== cost || Array.isArray(cost)) {
     throw new TypeError("effect ledger: invalid cost")
@@ -181,7 +184,7 @@ export function normalizeEffectMetadata(input: EffectMetadata): EffectMetadata {
   if (input.target !== undefined && !printableToken(input.target, TARGET_MAX_LENGTH)) {
     throw new TypeError("effect ledger: invalid target")
   }
-  if (input.digest !== undefined && !DIGEST_HEX.test(input.digest)) {
+  if (input.digest !== undefined && !validDigest(input.digest)) {
     throw new TypeError("effect ledger: invalid digest")
   }
   return Object.freeze({
@@ -236,7 +239,7 @@ class BoundedRequestLedger implements RequestLedger {
   append(input: EffectEntryInput): EffectEntry {
     if (this.sealResult !== undefined) throw new EffectLedgerSealedError()
     if (this.items.length >= this.maxEntries) throw new EffectLedgerOverflowError(this.maxEntries)
-    if (!validCapabilityId(input.capability)) {
+    if (typeof input.capability !== "string" || !validCapabilityId(input.capability)) {
       throw new TypeError(`effect ledger: invalid capability ${JSON.stringify(input.capability)}`)
     }
     const phase = input.phase ?? "intent"
@@ -249,10 +252,13 @@ class BoundedRequestLedger implements RequestLedger {
     if (input.target !== undefined && !printableToken(input.target, TARGET_MAX_LENGTH)) {
       throw new TypeError("effect ledger: invalid target")
     }
-    if (input.digest !== undefined && !DIGEST_HEX.test(input.digest)) {
+    if (input.digest !== undefined && !validDigest(input.digest)) {
       throw new TypeError("effect ledger: invalid digest")
     }
-    if (input.error !== undefined && !ERROR_CODE.test(input.error.code)) {
+    if (
+      input.error !== undefined &&
+      (typeof input.error?.code !== "string" || !ERROR_CODE.test(input.error.code))
+    ) {
       throw new TypeError("effect ledger: error code must be a bounded lowercase token")
     }
     // Only the known token fields are copied - a stray `payload`-like property never survives append.