@nifrajs/core 2.14.1 → 3.2.0

package/src/server/cookies.ts

@@ -202,11 +202,25 @@ const toBase64Url = (buf: ArrayBuffer): string => {
   return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
 }
 
+const BASE64URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+const BASE64URL_RE = /^[A-Za-z0-9_-]+$/
+
 // Returns `Uint8Array<ArrayBuffer>` (not the generic `Uint8Array<ArrayBufferLike>`) so it satisfies
-// WebCrypto's `BufferSource` parameter under TS 5.7+'s typed-array generics.
+// WebCrypto's `BufferSource` parameter under TS 5.7+'s typed-array generics. Reject non-canonical
+// encodings: base64 decoders otherwise accept alternate final characters whose unused padding bits
+// decode to the same bytes, which lets a visibly changed signed cookie verify as if it were original.
 const fromBase64Url = (s: string): Uint8Array<ArrayBuffer> | null => {
+  if (s.length === 0 || s.length % 4 === 1 || !BASE64URL_RE.test(s)) return null
+  const remainder = s.length % 4
+  const last = BASE64URL_ALPHABET.indexOf(s[s.length - 1]!)
+  // Two or three base64 characters leave four or two unused low bits respectively. The encoder above
+  // always emits those bits as zero; accepting anything else creates a second spelling of the same
+  // byte sequence.
+  if ((remainder === 2 && (last & 0x0f) !== 0) || (remainder === 3 && (last & 0x03) !== 0))
+    return null
   try {
-    const bin = atob(s.replace(/-/g, "+").replace(/_/g, "/"))
+    const padded = s + "=".repeat((4 - remainder) % 4)
+    const bin = atob(padded.replace(/-/g, "+").replace(/_/g, "/"))
     const bytes = new Uint8Array(bin.length)
     for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i)
     return bytes

package/src/server/header-case.ts

@@ -1,3 +1,5 @@
+import { NODE_BRIDGE_MARKER_KEYS } from "./bridge-markers.ts"
+
 /**
  * The all-lowercase header-name proof: one answer, computed once per request, read by everyone who
  * would otherwise re-derive it.
@@ -23,7 +25,7 @@
  * Declared with `Symbol.for` so the `@nifrajs/node` adapter can read it by key rather than importing
  * across the package boundary - the same cross-package convention as the body and result marks.
  */
-const LOWERCASE_HEADER_KEYS = Symbol.for("nifra.headers.lowercase")
+const LOWERCASE_HEADER_KEYS = Symbol.for(NODE_BRIDGE_MARKER_KEYS.lowercaseHeaderKeys)
 
 /** True when the name contains an ASCII `A`-`Z`, i.e. is not already the wire spelling. */
 export function hasUpperAscii(name: string): boolean {

package/src/server/http.ts

@@ -1,8 +1,37 @@
 /**
- * Dependency-free HTTP helpers shared by the kernel and the opt-in request lanes (idempotency,
- * effect-ledger). Kept in a leaf module so a lane can reuse them without importing the server, and so
- * the server can reuse them without pulling a lane's feature code into the base bundle.
+ * HTTP helpers shared by the kernel and the opt-in request lanes (idempotency, effect-ledger). Kept
+ * in a leaf module (runtime-core aside, itself a leaf) so a lane can reuse them without importing the
+ * server, and so the server can reuse them without pulling a lane's feature code into the base bundle.
  */
+import { type ResponseResult, status as statusResult } from "./runtime-core.ts"
+
+/**
+ * Is `value` a destination that stays on this origin?
+ *
+ * True only for an absolute path: one leading `/`, never `//` (protocol-relative → another origin),
+ * and free of any character a URL parser turns into an origin escape. A leading `/` alone is not
+ * enough: under a special scheme `\` parses as `/`, and tab/CR/LF are STRIPPED before parsing, so
+ * `/\evil.example` and `/<TAB>/evil.example` both resolve to the external host `evil.example` while
+ * passing a `//` test. Rejecting CR/LF here also keeps a validated destination out of the
+ * response-splitting sink it usually flows into.
+ *
+ * One implementation, because every caller is the same open-redirect gate: `redirect()` in
+ * `@nifrajs/web`, the `redirectTo` of the `@nifrajs/auth` and `@nifrajs/better-auth` guards. Three
+ * copies of a security predicate is three chances for one of them to be hardened alone.
+ *
+ * It answers about a PATH, not a URL: an absolute `https://this.host/x` is false even for the
+ * current origin, because the whole point is that the value never got to name a host.
+ */
+export function isSameOriginPath(value: string): boolean {
+  if (!value.startsWith("/") || value.startsWith("//")) return false
+  // Scanned by character code rather than matched by regex: no control characters have to be written
+  // into a pattern, and the check is a single pass over a short string.
+  for (let i = 1; i < value.length; i++) {
+    const code = value.charCodeAt(i)
+    if (code === 0x5c /* \ */ || code <= 0x1f || code === 0x7f) return false
+  }
+  return true
+}
 
 /** A uniform JSON error envelope: `{ ok: false, error }` at the given status. */
 export function jsonError(
@@ -16,6 +45,27 @@ export function jsonError(
   )
 }
 
+/**
+ * The same envelope as {@link jsonError}, as plain data rather than a built `Response`.
+ *
+ * This is what the framework's own renders - 404, 405, 422, the body caps, the timeouts, 500 - answer
+ * with wherever the value flows into a lane's response wrapper, so an error costs what a handler's
+ * plain return costs. Building the `Response` was measured as the dominant cost of answering early
+ * (see `PlainRender`), and on the Node lane an error `Response` is worse still: it is untagged, so
+ * the adapter cannot recognize its body and drains it through a Web stream, which is also why an
+ * error answered chunked while an ordinary return carries a `content-length`.
+ *
+ * `jsonError` stays for the callers that genuinely need a `Response` object (mount bridges, the
+ * lanes' own typed returns).
+ */
+export function plainError(
+  status: number,
+  error: string,
+  headers?: Record<string, string>,
+): ResponseResult {
+  return statusResult(status, { ok: false, error }, headers !== undefined ? { headers } : undefined)
+}
+
 export interface UrlParts {
   readonly pathname: string
   readonly search: string

package/src/server/install.ts

@@ -6,6 +6,7 @@
  *   - the seam stays off the server's public typed surface (symbol-keyed methods are not part of it).
  * Both sides reference the SAME registered symbol, so no module has to import the other.
  */
+import { NODE_BRIDGE_MARKER_KEYS } from "./bridge-markers.ts"
 
 /** @internal Install the idempotency runtime on a server (called by the `idempotency()` plugin). */
 export const INSTALL_IDEMPOTENCY: unique symbol = Symbol.for("@nifrajs/core/install-idempotency")
@@ -31,3 +32,16 @@ export const INSTALL_WS: unique symbol = Symbol.for("@nifrajs/core/install-ws")
 export const INSTALL_RESPONSE_CONTRACT: unique symbol = Symbol.for(
   "@nifrajs/core/install-response-contract",
 )
+
+/** @internal Install the response-observer adapters on a server. */
+export const INSTALL_RESPONSE_OBSERVER: unique symbol = Symbol.for(
+  "@nifrajs/core/install-response-observer",
+)
+
+/** @internal Resolve a native mount for an adapter that can keep the request on its own stream lane. */
+export const RESOLVE_NODE_MOUNT: unique symbol = Symbol.for(
+  NODE_BRIDGE_MARKER_KEYS.resolveNodeMount,
+)
+
+/** @internal Marker on a mounted handler that knows how to serve a native Node request/response. */
+export const NODE_NATIVE_MOUNT: unique symbol = Symbol.for("@nifrajs/core/node-native-mount")

package/src/server/node-outcome-hook.ts

@@ -3,6 +3,7 @@
 import type { Platform } from "./context.ts"
 import { hasLowercaseHeaderKeysMark, hasUpperAscii } from "./header-case.ts"
 import type { NodeServeOutcome } from "./node-outcome.ts"
+import type { ResponseResult } from "./runtime-core.ts"
 import type { CtxSet, MaybePromise } from "./server.ts"
 
 /**
@@ -309,7 +310,7 @@ export interface NodeOutcomeRuntime {
   toOutcome(result: unknown, set: CtxSet): NodeServeOutcome
   /** Materialize a buffered outcome for a Web response hook without losing its direct-write marker. */
   toResponse(outcome: NodeServeOutcome): Response
-  fromResponse(response: Response): NodeServeOutcome
+  fromResponse(response: Response | ResponseResult): NodeServeOutcome
   timeout(): NodeServeOutcome
   /** The `Content-Type` this runtime's json render writes implicitly. The native hook walk
    * materializes it into the hook-visible header record so a body hook's content-type checks see

package/src/server/node-outcome.ts

@@ -11,7 +11,14 @@ import {
   rememberMutableHeaders,
   taggedResponseBody,
 } from "./respond.ts"
-import { type HandlerResult, isResponseResult } from "./runtime-core.ts"
+import {
+  EMPTY_RESPONSE_CONTROLS,
+  type HandlerResult,
+  isResponseResult,
+  type PlainRender,
+  plainRenderHeaders,
+  type ResponseResult,
+} from "./runtime-core.ts"
 import type { CtxSet } from "./server.ts"
 import {
   mergeStaticHeaderRecord,
@@ -58,6 +65,8 @@ export type NodeServeOutcome =
  */
 export function toNodeOutcome(result: HandlerResult, set: CtxSet): NodeServeOutcome {
   if (isResponseResult(result)) {
+    const plain = result.plain
+    if (plain !== undefined) return plainNodeOutcome(plain, set)
     const body = result.toNodeBody?.()
     if (body !== undefined) {
       return {
@@ -85,6 +94,24 @@ export function toNodeOutcome(result: HandlerResult, set: CtxSet): NodeServeOutc
   }
 }
 
+/**
+ * A `status(...)` (or any other {@link PlainRender} carrier) on the node lane: the same `kind: "json"`
+ * outcome a handler's plain return produces, so an early exit is written to the socket by the same
+ * direct writer, with a `content-length`, and never builds a `Response`.
+ */
+export function plainNodeOutcome(plain: PlainRender, set: CtxSet): NodeServeOutcome {
+  return {
+    kind: "json",
+    status: plain.status,
+    headers: plainRenderHeaders(plain, set),
+    cookies: set._cookies,
+    body:
+      plain.body === undefined || isBodylessStatus(plain.status)
+        ? null
+        : JSON.stringify(plain.body),
+  }
+}
+
 /**
  * Materialize a buffered node outcome only when a Web `onResponse` hook needs to see a real
  * `Response`. The marker lets an in-place hook (`response.headers.set(...); return response`) go back
@@ -162,8 +189,22 @@ export function withStaticNodeHeaders(
   return { ...outcome, headers }
 }
 
-export function nodeOutcomeFromResponse(response: Response): NodeServeOutcome {
-  response = normalizeBodylessResponse(response)
+/**
+ * The node lane's `wrapResponse`: what an early exit built OUTSIDE the handler's finalizer renders as
+ * - an `onRequest` hook's `Response`, a mount's, and every framework error render.
+ *
+ * A plain-data carrier ({@link plainError}, `status(...)`) takes the same `kind: "json"` lane a
+ * handler's plain return takes: no `Response` built, and none drained. `EMPTY_RESPONSE_CONTROLS`
+ * rather than the request's `c.set` on purpose - these renders happen where no context exists (before
+ * routing, or after it was abandoned), which is exactly why they are wrapped rather than finalized.
+ */
+export function nodeOutcomeFromResponse(result: Response | ResponseResult): NodeServeOutcome {
+  if (!(result instanceof Response)) {
+    const plain = result.plain
+    if (plain !== undefined) return plainNodeOutcome(plain, EMPTY_RESPONSE_CONTROLS)
+    return nodeOutcomeFromResponse(result.toResponse())
+  }
+  const response = normalizeBodylessResponse(result)
   const body = nodeResponseBody(response)
   return body === undefined
     ? { kind: "response", response }

package/src/server/plugin.ts

@@ -23,7 +23,9 @@ export type NifraPlugin<In extends AnyServer = AnyServer, Out extends AnyServer
  * server type it receives, preserving the caller's typed registry and context across `.use()` while
  * still allowing the plugin to register runtime hooks or handlers.
  */
-export type IdentityPlugin = (<S extends AnyServer>(app: S) => S) & {
+export type IdentityPlugin<AddedHookOutput = never> = (<R extends Registry, Ctx, HookOutput>(
+  app: Server<R, Ctx, HookOutput>,
+) => Server<R, Ctx, HookOutput | AddedHookOutput>) & {
   readonly pluginName?: string
 }
 
@@ -142,11 +144,15 @@ export function definePlugin(
  * const api = server().get("/a", h).use(audit).get("/b", h) // /a AND /b stay typed
  * ```
  */
-export function defineIdentityPlugin(
+export function defineIdentityPlugin<AddedHookOutput = never>(
   name: string,
-  apply: <S extends AnyServer>(app: S) => S,
-): IdentityPlugin {
-  return Object.assign(apply, { pluginName: name }) as IdentityPlugin
+  // The runtime identity plugin may install lifecycle hooks whose richer type is intentionally not
+  // threaded through this legacy identity seam. Accept the resulting server here so existing
+  // middleware remains source-compatible; direct typed hooks and future typed middleware can use the
+  // concrete Server return type without forcing every identity plugin to become response-aware.
+  apply: <S extends AnyServer>(app: S) => S | AnyServer,
+): IdentityPlugin<AddedHookOutput> {
+  return Object.assign(apply, { pluginName: name }) as IdentityPlugin<AddedHookOutput>
 }
 
 /**

package/src/server/query.ts

@@ -4,7 +4,8 @@
  * and the byte-capped HTML-form reader. Split out of the server kernel so the file stays one domain.
  */
 import { readBoundedBytes } from "./body.ts"
-import { jsonError, urlPartsOf } from "./http.ts"
+import { plainError, urlPartsOf } from "./http.ts"
+import type { ResponseResult } from "./runtime-core.ts"
 import type { RequestSource } from "./server.ts"
 
 // The query string ("?a=1", or "" when absent) - for lazily building `c.query` only when read.
@@ -123,16 +124,21 @@ const FORM_DECODER = new TextDecoder()
  * Read an HTML-form body (urlencoded) into the plain object a body schema validates - same byte
  * cap as the JSON path (a lying/absent Content-Length can't force an oversized buffer), same
  * repeated-key -> `string[]` promotion as query parsing, same `__proto__` guard.
+ *
+ * A rejection is a `ResponseResult`, not a built `Response`, matching the JSON reader: the cap is a
+ * framework render, and answering one on the plain lane costs what a handler's plain return costs
+ * (see `plainError`). The distinction is observable on the Node adapter - a `Response` there is
+ * untagged, so its body drains through a Web stream and the answer goes out chunked.
  */
 export async function readBoundedForm(
   req: RequestSource,
   maxBytes: number,
-): Promise<Record<string, QueryValue> | Response> {
+): Promise<Record<string, QueryValue> | ResponseResult> {
   const read = await readBoundedBytes(req, maxBytes)
   if (!read.ok) {
     return read.status === 413
-      ? jsonError(413, "payload_too_large")
-      : jsonError(400, "invalid_content_length")
+      ? plainError(413, "payload_too_large")
+      : plainError(400, "invalid_content_length")
   }
   const out: Record<string, QueryValue> = Object.create(null) as Record<string, QueryValue>
   // URLSearchParams owns the format's quirks (`+` as space, percent-decoding, empty keys);

package/src/server/registry.ts

@@ -1,6 +1,7 @@
 import type { BinaryResponse, RawResponse } from "../binary.ts"
 import type { InferInput, InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
 import type { Params, RouteSchema } from "./context.ts"
+import type { StatusResponse } from "./runtime-core.ts"
 
 /**
  * One route's input/output shape as the **client** will consume it. `query`/`body`
@@ -17,6 +18,8 @@ export interface RouteInfo {
   readonly query: unknown
   readonly body: unknown
   readonly output: unknown
+  /** The complete inferred/declared status-keyed response map. */
+  readonly responses?: unknown
   /** The route's declared error bodies as a status-keyed record (from `schema.errors`, e.g.
    * `{ 404: NotFound }`); `unknown` when the route declares none. The typed client turns this into
    * a status-discriminated failure union. */
@@ -48,22 +51,73 @@ type RegistryQuery<S extends RouteSchema> = S extends { query: infer Q extends S
   ? InferInput<Q>
   : never
 
-/** The client-visible output: the declared `response` contract when present (so the client sees the
- * contract, not the handler's incidental return), otherwise the inferred handler output. */
-type RegistryOutput<S extends RouteSchema, Output> = S extends {
+type StatusCodeOf<Output> =
+  Output extends StatusResponse<infer Code, unknown> ? (number extends Code ? never : Code) : never
+
+type StatusBodyAt<Output, Code extends number> =
+  Output extends StatusResponse<infer Actual, infer Body>
+    ? Code extends Actual
+      ? Body
+      : never
+    : never
+
+type IsSuccessCode<Code extends number> = `${Code}` extends `2${string}` ? true : false
+
+type EmptyResponseMap = NonNullable<unknown>
+
+type StatusBodies<Output, Codes extends number = StatusCodeOf<Output>> = [Codes] extends [never]
+  ? EmptyResponseMap
+  : { [Code in Codes]: StatusBodyAt<Output, Code> }
+
+/** A dynamic status code cannot be classified as success or failure; expose an opaque success arm
+ * rather than guessing a status or body schema. Explicit route schemas still override this fallback. */
+type DynamicStatusResponses<Output> =
+  Output extends StatusResponse<infer Code, unknown>
+    ? number extends Code
+      ? { 200: unknown }
+      : EmptyResponseMap
+    : EmptyResponseMap
+
+type InferredResponses<Output> = (Exclude<
+  Output,
+  StatusResponse<number, unknown> | Response
+> extends never
+  ? EmptyResponseMap
+  : { 200: Exclude<Output, StatusResponse<number, unknown> | Response> }) &
+  StatusBodies<Output> &
+  DynamicStatusResponses<Output>
+
+type ExplicitResponses<S extends RouteSchema> = (S extends {
   response: infer R extends StandardSchemaV1
 }
-  ? InferOutput<R>
-  : Output
-
-/** A route's declared error-response body types as a STATUS-KEYED record (`schema.errors` →
- * `{ 404: NotFound, 409: Conflict }`), so the typed client can discriminate the failure body by
- * `status`, not just surface a union. `unknown` when the route declares no `errors`. */
-type RegistryErrors<S extends RouteSchema> = S extends {
-  errors: infer E extends Record<number, StandardSchemaV1>
+  ? { 200: InferOutput<R> }
+  : EmptyResponseMap) &
+  (S extends { errors: infer E extends Record<number, StandardSchemaV1> }
+    ? { [K in keyof E]: E[K] extends StandardSchemaV1 ? InferOutput<E[K]> : never }
+    : EmptyResponseMap)
+
+type MergeResponseMaps<Inferred, Explicit> = Omit<Inferred, keyof Explicit> & Explicit
+
+type ResponseMap<S extends RouteSchema, Output> = MergeResponseMaps<
+  InferredResponses<Output>,
+  ExplicitResponses<S>
+>
+
+/** Public type seam for build-time consumers that need the complete route response map. */
+export type ResponseMapFor<S extends RouteSchema, Output> = ResponseMap<S, Output>
+
+type ResponseErrors<M> = {
+  [K in keyof M as K extends number ? (IsSuccessCode<K> extends true ? never : K) : never]: M[K]
 }
-  ? { [K in keyof E]: E[K] extends StandardSchemaV1 ? InferOutput<E[K]> : never }
-  : unknown
+
+type ResponseSuccessBodies<M> = {
+  [K in keyof M]: K extends number ? (IsSuccessCode<K> extends true ? M[K] : never) : never
+}[keyof M]
+
+type NonEmptyOrUnknown<M> = keyof M extends never ? unknown : M
+
+/** The client-visible output is the union of all inferred/declared 2xx bodies. */
+type RegistryOutput<S extends RouteSchema, Output> = ResponseSuccessBodies<ResponseMap<S, Output>>
 
 /** The SSE event payload type from a route's `sse` schema; `never` for ordinary routes. */
 type RegistrySse<S extends RouteSchema> = S extends { sse: infer E extends StandardSchemaV1 }
@@ -71,12 +125,13 @@ type RegistrySse<S extends RouteSchema> = S extends { sse: infer E extends Stand
   : never
 
 /** Build a {@link RouteInfo} from a route's path, schema, and handler output type. */
-export type RouteInfoFor<Path extends string, S extends RouteSchema, Output> = {
+export type RouteInfoFor<Path extends string, S extends RouteSchema, Output, HookOutput = never> = {
   readonly params: Params<Path>
   readonly query: RegistryQuery<S>
   readonly body: RegistryBody<S>
-  readonly output: RegistryOutput<S, Output>
-  readonly errors: RegistryErrors<S>
+  readonly output: RegistryOutput<S, Output | HookOutput>
+  readonly responses?: ResponseMapFor<S, Output | HookOutput>
+  readonly errors: NonEmptyOrUnknown<ResponseErrors<ResponseMapFor<S, Output | HookOutput>>>
   readonly sse: RegistrySse<S>
 }