@daloyjs/core 1.0.0-rc.3 → 1.0.0-rc.5

package/dist/adapters/lambda.js

@@ -1,17 +1,56 @@
+import { setConnInfo } from "../conn-info.js";
 const TEXT_TYPE_RE = /^(text\/|application\/(json|xml|javascript|x-www-form-urlencoded|.*\+json|.*\+xml))/i;
 /**
  * Wrap an {@link App} as a Lambda/Netlify handler accepting either v1.0 or v2.0 event payloads.
  *
+ * A malformed event (e.g. a `Host`/path combination that cannot form a valid
+ * URL) is answered with a clean `400` problem+json instead of throwing out of
+ * the handler, which API Gateway would otherwise surface as an opaque `502`.
+ *
  * @param app - The DaloyJS {@link App} that serves each translated request.
  * @returns A {@link LambdaHandler} that converts the event to a `Request`, calls {@link App.fetch}, and emits the matching v1.0/v2.0 response shape.
  */
 export function toLambdaHandler(app) {
     return async (event) => {
-        const request = eventToRequest(event);
+        let request;
+        try {
+            request = eventToRequest(event);
+        }
+        catch {
+            return responseToLambda(badRequestResponse(), isV2Event(event));
+        }
         const response = await app.fetch(request);
         return responseToLambda(response, isV2Event(event));
     };
 }
+/**
+ * Wrap an {@link App} as an AWS Lambda response-streaming handler.
+ *
+ * The returned handler is decorated with the managed Node.js runtime's
+ * `awslambda.streamifyResponse()` helper, attaches status/headers with
+ * `HttpResponseStream.from()`, and pumps the web-standard response body while
+ * honoring writable-stream backpressure. The function throws during startup
+ * outside an AWS Lambda Node.js runtime so an accidentally buffered or broken
+ * deployment cannot start silently.
+ *
+ * @param app - The DaloyJS {@link App} that serves each translated request.
+ * @returns A response-streaming Lambda handler for Function URLs, API Gateway streaming proxy integrations, or `InvokeWithResponseStream`.
+ * @throws {Error} If the AWS Lambda response-streaming globals are unavailable.
+ */
+export function toLambdaStreamHandler(app) {
+    const runtime = lambdaStreamingRuntime();
+    return runtime.streamifyResponse(async (event, rawStream) => {
+        let request;
+        try {
+            request = eventToRequest(event);
+        }
+        catch {
+            await streamLambdaResponse(badRequestResponse(), rawStream, runtime);
+            return;
+        }
+        await streamLambdaResponse(await app.fetch(request), rawStream, runtime);
+    });
+}
 function eventToRequest(event) {
     const headers = new Headers();
     for (const [k, v] of Object.entries(event.headers ?? {})) {
@@ -28,35 +67,37 @@ function eventToRequest(event) {
     }
     if ("cookies" in event && event.cookies?.length)
         headers.set("cookie", event.cookies.join("; "));
-    const method = isV2Event(event) ? event.requestContext?.http?.method ?? "GET" : event.httpMethod ?? "GET";
+    const method = isV2Event(event)
+        ? (event.requestContext?.http?.method ?? "GET")
+        : (event.httpMethod ?? "GET");
     const rawPath = isV2Event(event)
-        ? event.rawPath ?? event.requestContext?.http?.path ?? "/"
-        : event.path ?? event.requestContext?.path ?? "/";
+        ? (event.rawPath ?? event.requestContext?.http?.path ?? "/")
+        : (event.path ?? event.requestContext?.path ?? "/");
     const host = headers.get("host") ?? event.requestContext?.domainName ?? "localhost";
     const proto = headers.get("x-forwarded-proto") ?? "https";
-    const rawQueryString = isV2Event(event) ? event.rawQueryString ?? "" : queryStringForV1(event);
+    const rawQueryString = isV2Event(event) ? (event.rawQueryString ?? "") : queryStringForV1(event);
     const qs = rawQueryString ? `?${rawQueryString}` : "";
     const path = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
     const url = `${proto}://${host}${path}${qs}`;
     const init = { method, headers };
     if (method !== "GET" && method !== "HEAD" && event.body != null) {
-        init.body = event.isBase64Encoded
-            ? base64ToBytes(event.body)
-            : event.body;
+        init.body = event.isBase64Encoded ? base64ToBytes(event.body) : event.body;
+    }
+    const request = new Request(url, init);
+    // Fulfil the conn-info contract with the caller address API Gateway saw
+    // (v2: `requestContext.http.sourceIp`, v1: `requestContext.identity.sourceIp`),
+    // so `getConnInfo` / `resolveClientIp` work on Lambda. API Gateway and
+    // Function URLs only serve TLS.
+    const sourceIp = isV2Event(event)
+        ? event.requestContext?.http?.sourceIp
+        : event.requestContext?.identity?.sourceIp;
+    if (sourceIp) {
+        setConnInfo(request, { remoteAddress: sourceIp, tls: true });
     }
-    return new Request(url, init);
+    return request;
 }
 async function responseToLambda(res, useV2Response) {
-    const headers = {};
-    const getSetCookie = res.headers.getSetCookie;
-    const cookies = typeof getSetCookie === "function"
-        ? getSetCookie.call(res.headers)
-        : cookieFallback(res.headers);
-    res.headers.forEach((value, key) => {
-        if (key.toLowerCase() === "set-cookie")
-            return;
-        headers[key] = value;
-    });
+    const { headers, cookies } = responseHeaders(res);
     const contentType = res.headers.get("content-type") ?? "";
     const isText = TEXT_TYPE_RE.test(contentType);
     let body = "";
@@ -87,7 +128,10 @@ async function responseToLambda(res, useV2Response) {
 }
 function isV2Event(event) {
     const requestContext = event.requestContext;
-    return event.version === "2.0" || "rawPath" in event || "rawQueryString" in event || !!requestContext?.http;
+    return (event.version === "2.0" ||
+        "rawPath" in event ||
+        "rawQueryString" in event ||
+        !!requestContext?.http);
 }
 function queryStringForV1(event) {
     const values = new URLSearchParams();
@@ -107,6 +151,78 @@ function cookieFallback(headers) {
     const cookie = headers.get("set-cookie");
     return cookie ? [cookie] : [];
 }
+function responseHeaders(res) {
+    const headers = {};
+    const getSetCookie = res.headers.getSetCookie;
+    const cookies = typeof getSetCookie === "function"
+        ? getSetCookie.call(res.headers)
+        : cookieFallback(res.headers);
+    res.headers.forEach((value, key) => {
+        if (key.toLowerCase() !== "set-cookie")
+            headers[key] = value;
+    });
+    return { headers, cookies };
+}
+function badRequestResponse() {
+    return Response.json({
+        type: "https://daloyjs.dev/errors/bad-request",
+        title: "Bad Request",
+        status: 400,
+    }, { status: 400, headers: { "content-type": "application/problem+json" } });
+}
+function lambdaStreamingRuntime() {
+    const runtime = globalThis
+        .awslambda;
+    if (!runtime ||
+        typeof runtime.streamifyResponse !== "function" ||
+        typeof runtime.HttpResponseStream?.from !== "function") {
+        throw new Error("AWS Lambda response streaming runtime not detected; toLambdaStreamHandler requires the managed Node.js awslambda globals");
+    }
+    return runtime;
+}
+async function streamLambdaResponse(response, rawStream, runtime) {
+    const { headers, cookies } = responseHeaders(response);
+    const metadata = { statusCode: response.status, headers };
+    if (cookies.length)
+        metadata.multiValueHeaders = { "set-cookie": cookies };
+    const responseStream = runtime.HttpResponseStream.from(rawStream, metadata);
+    if (response.body) {
+        const reader = response.body.getReader();
+        try {
+            for (;;) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                if (!responseStream.write(chunk.value))
+                    await waitForDrain(responseStream);
+            }
+        }
+        catch (error) {
+            await reader.cancel(error).catch(() => undefined);
+            throw error;
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    responseStream.end();
+    if (responseStream.finished)
+        await responseStream.finished();
+}
+function waitForDrain(stream) {
+    return new Promise((resolve, reject) => {
+        const onDrain = () => {
+            stream.off?.("error", onError);
+            resolve();
+        };
+        const onError = (error) => {
+            stream.off?.("drain", onDrain);
+            reject(error);
+        };
+        stream.once("drain", onDrain);
+        stream.once("error", onError);
+    });
+}
 function base64ToBytes(b64) {
     const binary = atob(b64);
     const bytes = new Uint8Array(binary.length);

package/dist/adapters/node.d.ts

@@ -76,7 +76,14 @@ export interface NodeServerOptions {
 export interface NodeServerHandle {
     /** The underlying `node:http` `Server` instance, for advanced wiring (extra listeners, address introspection). */
     server: Server;
-    /** Port the server was asked to listen on ({@link NodeServerOptions.port}, default `3000`). */
+    /**
+     * Bound TCP port once the server emits `listening`.
+     *
+     * Before the listener is ready, this is the requested
+     * {@link NodeServerOptions.port} (default `3000`). In particular, callers
+     * using `port: 0` must await the server's `listening` event before reading
+     * this property to receive the OS-assigned ephemeral port.
+     */
     port: number;
     /** Graceful shutdown: drains {@link App.shutdown} hooks, destroys WebSocket sockets, then closes the server. Idempotent. */
     close(): Promise<void>;

package/dist/adapters/node.js

@@ -4,8 +4,10 @@
  */
 import { createServer, } from "node:http";
 import { Readable } from "node:stream";
-import { DALOY_RAW_BODY, DALOY_RAW_STREAM, DALOY_REQUEST_RAW_BODY, DALOY_LIGHT_RESPONSE_OK, } from "../app.js";
+import { DALOY_RAW_BODY, DALOY_RAW_STREAM, DALOY_REQUEST_RAW_BODY, DALOY_LIGHT_RESPONSE_OK, DALOY_REQUEST_ABORT, } from "../app.js";
+import { BadRequestError } from "../errors.js";
 import { setClientCertificate, normalizePeerCertificate, } from "../mtls.js";
+import { setConnInfo } from "../conn-info.js";
 import { FrameSink, encodeFrame, encodeClosePayload, encodeSendPayload, validateUpgrade, validateSelectedSubprotocol, checkWebSocketOrigin, WS_OPCODE, WS_CLOSE_CODE, WS_READY_STATE, WS_MAX_CONTROL_PAYLOAD, WebSocketProtocolError, WebSocketPayloadTooLargeError, } from "../websocket.js";
 /**
  * Start a Node.js HTTP (and optional WebSocket) server bound to the given {@link App}.
@@ -85,11 +87,23 @@ export function serve(app, opts = {}) {
         server.on("upgrade", (req, socket, head) => {
             wsSockets.add(socket);
             socket.on("close", () => wsSockets.delete(socket));
-            void handleUpgrade(app, req, socket, head, trustProxy);
+            // Safety net: a rejection here would otherwise be unhandled and, under
+            // the production crash-on-unhandledRejection posture, kill the process
+            // from a single malformed upgrade request.
+            handleUpgrade(app, req, socket, head, trustProxy).catch((err) => {
+                app.log.error({ err }, "WebSocket upgrade failed");
+                try {
+                    writeUpgradeError(socket, 400, "Bad Request");
+                }
+                catch {
+                    /* socket already closed */
+                }
+                socket.destroy();
+            });
         });
     }
-    const port = opts.port ?? 3000;
-    server.listen(port, opts.hostname ?? "0.0.0.0");
+    const requestedPort = opts.port ?? 3000;
+    server.listen(requestedPort, opts.hostname ?? "0.0.0.0");
     // Kill idle keep-alive sockets immediately when draining begins.
     // In-flight requests keep their socket because Node's
     // `closeIdleConnections()` is a no-op for sockets with an in-flight request.
@@ -115,7 +129,16 @@ export function serve(app, opts = {}) {
         process.once("SIGTERM", () => onSignal("SIGTERM"));
         process.once("SIGINT", () => onSignal("SIGINT"));
     }
-    return { server, port, close };
+    return {
+        server,
+        get port() {
+            const address = server.address();
+            return address !== null && typeof address === "object"
+                ? address.port
+                : requestedPort;
+        },
+        close,
+    };
 }
 /**
  * Default pre-buffer ceiling for the Node adapter. 256 KiB is a compromise:
@@ -135,6 +158,14 @@ function dispatchToApp(app, req, res, trustProxy, bufferedBody) {
         writeAdapterError(res, e);
         return;
     }
+    // Fulfil the conn-info contract: the immediate TCP peer, so
+    // `getConnInfo` / `resolveClientIp` / `behindProxy` and WAF client-IP
+    // attribution work on Node. Never derived from spoofable headers.
+    setConnInfo(request, {
+        remoteAddress: req.socket.remoteAddress,
+        remotePort: req.socket.remotePort,
+        tls: req.socket.encrypted === true,
+    });
     attachClientCertificate(req, request);
     const responseOrPromise = app.fetch(request);
     if (responseOrPromise instanceof Promise) {
@@ -279,12 +310,15 @@ function writeMethodRefused(res) {
 }
 function writeAdapterError(res, e) {
     if (!res.headersSent) {
-        res.statusCode = 500;
+        const clientError = e instanceof BadRequestError;
+        res.statusCode = clientError ? 400 : 500;
         res.setHeader("content-type", "application/problem+json");
         res.end(JSON.stringify({
-            type: "https://daloyjs.dev/errors/internal",
-            title: "Internal Server Error",
-            status: 500,
+            type: clientError
+                ? "https://daloyjs.dev/errors/bad-request"
+                : "https://daloyjs.dev/errors/internal",
+            title: clientError ? "Bad Request" : "Internal Server Error",
+            status: clientError ? 400 : 500,
         }));
     }
     else {
@@ -307,9 +341,11 @@ function writeAdapterError(res, e) {
  * - `instanceof Request` holds (prototype chain is re-rooted onto
  *   `Request.prototype`), and every WHATWG method/getter is overridden here,
  *   so nothing hits undici's brand-checked prototype accessors.
- * - `signal` is an inert per-instance `AbortSignal`. This matches the real
- *   adapter behaviour today: the Node adapter never wires socket aborts into
- *   the request signal, so the signal never fires in either implementation.
+ * - `signal` is a lazily-created per-instance `AbortSignal`. The framework
+ *   aborts it (via the {@link DALOY_REQUEST_ABORT} hook) when the request
+ *   exceeds `requestTimeoutMs`, so a handler that forwards `ctx.request.signal`
+ *   to downstream `fetch`/DB calls sees them cancel on timeout. It is still NOT
+ *   wired to client socket-disconnect — that teardown never fires the signal.
  * - Passing this object directly to `fetch()` is not supported (undici
  *   brand-checks its input) — forward with `request.clone()` instead, which
  *   returns a real `Request`. This mirrors @hono/node-server's shim.
@@ -327,7 +363,7 @@ class LightRequest {
     #headers;
     #bodyBytes;
     #real;
-    #signal;
+    #controller;
     constructor(url, method, headers, bodyBytes) {
         this.#url = url;
         this.#method = method;
@@ -355,10 +391,22 @@ class LightRequest {
         return this.#headers;
     }
     get signal() {
-        // Inert, lazily created: the Node adapter has never wired socket
-        // teardown into the request signal, so a never-firing signal is
-        // behaviourally identical to the one a real `Request` would carry.
-        return (this.#signal ??= new AbortController().signal);
+        // Lazily created so only handlers that actually read `signal` pay for the
+        // controller. The framework aborts it via the DALOY_REQUEST_ABORT hook
+        // below when the request exceeds `requestTimeoutMs`; client
+        // socket-disconnect is not wired into it.
+        return (this.#controller ??= new AbortController()).signal;
+    }
+    /**
+     * Framework abort hook ({@link DALOY_REQUEST_ABORT}). Invoked by the core on
+     * request timeout so `ctx.request.signal` fires for cooperative teardown.
+     * A no-op when no handler ever read `signal` — there is no controller to
+     * abort and nothing observing it.
+     *
+     * @param reason - Abort reason surfaced on `signal.reason` (a `TimeoutError`).
+     */
+    [DALOY_REQUEST_ABORT](reason) {
+        this.#controller?.abort(reason);
     }
     get body() {
         return this.#materialize().body;
@@ -506,6 +554,13 @@ function toWebRequest(req, trustProxy, bufferedBody) {
     const proto = forwardedProto ??
         (req.socket.encrypted ? "https" : "http");
     const url = `${proto}://${host}${normalizeRequestTarget(req.url)}`;
+    // Reject malformed Host / request-target combinations at the adapter
+    // boundary instead of letting the invalid URL propagate as a 500 later.
+    // URL.canParse applies WHATWG validation without allocating and immediately
+    // discarding a URL object on every request.
+    if (!URL.canParse(url)) {
+        throw new BadRequestError("Invalid request target or Host header");
+    }
     // Build headers from `rawHeaders` (a flat [k0,v0,k1,v1,...] array) instead
     // of the parsed `req.headers` object. This matches @hono/node-server's
     // `newHeadersFromIncoming`: one `new Headers([[k,v],...])` constructor
@@ -578,7 +633,21 @@ function normalizeRequestTarget(target) {
 }
 function sendWebResponse(res, out) {
     out.statusCode = res.status;
-    res.headers.forEach((v, k) => out.setHeader(k, v));
+    // `Headers.forEach` yields each `Set-Cookie` as a separate callback while
+    // `ServerResponse.setHeader` overwrites repeated keys — copying naively
+    // keeps only the LAST cookie (e.g. dropping the session cookie when
+    // `csrf()` also sets its token cookie). Collect them via `getSetCookie()`
+    // and set the array once so every cookie reaches the wire.
+    let hasSetCookie = false;
+    res.headers.forEach((v, k) => {
+        if (k === "set-cookie") {
+            hasSetCookie = true;
+            return;
+        }
+        out.setHeader(k, v);
+    });
+    if (hasSetCookie)
+        out.setHeader("set-cookie", res.headers.getSetCookie());
     // Fast-path: response was produced by serializeResult and carries the raw
     // body bytes via the DALOY_RAW_BODY Symbol. Skip arrayBuffer() and the
     // reader-loop microtask churn entirely for buffer-backed responses.
@@ -661,7 +730,18 @@ async function handleUpgrade(app, req, socket, head, trustProxy) {
         : undefined;
     const proto = forwardedProto ??
         (req.socket.encrypted ? "https" : "http");
-    const url = new URL(`${proto}://${host}${req.url ?? "/"}`);
+    // A malformed `Host` header (e.g. containing a space) reaches this point:
+    // Node's HTTP parser accepts it and fires `upgrade`, but WHATWG URL
+    // parsing throws. Reject it as the client error it is instead of letting
+    // the throw escape the adapter.
+    let url;
+    try {
+        url = new URL(`${proto}://${host}${req.url ?? "/"}`);
+    }
+    catch {
+        writeUpgradeError(socket, 400, "Bad Request");
+        return;
+    }
     const match = app.webSocketRoutes.find(url.pathname);
     if (!match) {
         writeUpgradeError(socket, 404, "Not Found");
@@ -682,6 +762,11 @@ async function handleUpgrade(app, req, socket, head, trustProxy) {
         method: "GET",
         headers,
     });
+    setConnInfo(request, {
+        remoteAddress: req.socket.remoteAddress,
+        remotePort: req.socket.remotePort,
+        tls: req.socket.encrypted === true,
+    });
     const ctx = {
         request,
         params: match.params,

package/dist/app.d.ts

@@ -78,7 +78,12 @@ export interface AppOptions {
     bodyLimitBytes?: number;
     /** Reject requests whose Content-Type isn't in this allowlist (when a body schema is declared). */
     allowedContentTypes?: string[];
-    /** Per-request timeout in ms (handler + hooks). Default: 30000. Set 0 to disable. */
+    /**
+     * Per-request timeout in ms (handler + hooks). Default: 30000. Set 0 to
+     * disable. On timeout the framework aborts `ctx.request.signal` (cooperative
+     * cancellation of downstream I/O) and responds `408`; see
+     * {@link RequestTimeoutError}. It does not forcibly stop CPU-bound work.
+     */
     requestTimeoutMs?: number;
     /**
      * Maximum number of distinct request header fields accepted before the
@@ -93,6 +98,29 @@ export interface AppOptions {
      * @since 0.38.0
      */
     maxHeaderCount?: number;
+    /**
+     * Maximum number of keys (summed across every object in the tree) permitted
+     * when parsing a JSON request body. This bounds "hash-flood" / wide-object
+     * attacks that easily fit inside `bodyLimitBytes` (e.g. 40 000 tiny keys).
+     * Applies to top-level objects and all nested objects. Set to 0 to disable.
+     * Default: 10 000.
+     *
+     * Exposed in `getSecurityPosture()` and audited by `daloy doctor`.
+     *
+     * @since 1.0.0
+     */
+    jsonMaxKeys?: number;
+    /**
+     * Maximum nesting depth permitted for JSON request bodies (objects and arrays).
+     * Prevents deeply-nested structures that can consume excessive CPU/memory
+     * during schema validation or handler processing. Set to 0 to disable.
+     * Default: 50.
+     *
+     * Exposed in `getSecurityPosture()` and audited by `daloy doctor`.
+     *
+     * @since 1.0.0
+     */
+    jsonMaxDepth?: number;
     /**
      * Per-request limits applied when parsing `multipart/form-data` bodies.
      * These run in addition to `bodyLimitBytes`. Use them to cap the size of
@@ -516,7 +544,7 @@ export interface PluginExtension {
     /** Unique extension name. Referenced by `before` / `after` on siblings. */
     name: string;
     /** Lifecycle event the handler attaches to. */
-    event: "onRequest" | "beforeHandle" | "afterHandle" | "onSend" | "onError";
+    event: "onRequest" | "preBody" | "beforeHandle" | "afterHandle" | "onSend" | "onError";
     /** Hook handler. The shape mirrors the matching {@link Hooks} entry. */
     handler: (...args: any[]) => any;
     /** Extension names this one must run before. */
@@ -748,6 +776,23 @@ export declare const DALOY_RAW_BODY: unique symbol;
  * so first-party adapters can opt in; not part of the userland API surface.
  */
 export declare const DALOY_REQUEST_RAW_BODY: unique symbol;
+/**
+ * Internal Symbol an adapter sets (on its request shim) to expose the request's
+ * abort hook: a `(reason: unknown) => void` that aborts the `AbortController`
+ * backing `request.signal`. The core invokes it when a request exceeds
+ * {@link AppOptions.requestTimeoutMs} so a handler that forwarded
+ * `ctx.request.signal` to downstream I/O (`fetch`, a DB driver) sees those
+ * calls cancel — cooperative teardown, since single-threaded JS cannot preempt
+ * a running handler.
+ *
+ * The hook is invoked as a method on the request (`this` stays bound to the
+ * shim) so it can reach the shim's private controller. Absent on runtimes
+ * whose `Request.signal` is managed by the platform (Bun / Deno / Workers) and
+ * on direct `app.fetch()` callers, where {@link abortRequest} is a safe no-op
+ * and the timeout still resolves as a `408`. Module-public so first-party
+ * adapters can opt in; not part of the userland API surface.
+ */
+export declare const DALOY_REQUEST_ABORT: unique symbol;
 /**
  * Internal Symbol set by handlers/serializers to attach a raw stream
  * (Node `Readable` or Web `ReadableStream`) to a `Response`. The Node
@@ -828,6 +873,18 @@ export declare const DALOY_LIGHT_RESPONSE_OK: unique symbol;
  * @typeParam R - The route definition being registered.
  */
 type AppendRoute<Routes extends readonly RouteDefinition<any, any, any, any>[], R extends RouteDefinition<any, any, any, any>> = readonly RouteDefinition<any, any, any, any>[] extends Routes ? readonly [R] : readonly [...Routes, R];
+/** Append a literal tuple of route contracts to an App's accumulated routes. */
+type AppendRoutes<Routes extends readonly RouteDefinition<any, any, any, any>[], Added extends readonly RouteDefinition<any, any, any, any>[]> = readonly RouteDefinition<any, any, any, any>[] extends Routes ? Added : readonly [...Routes, ...Added];
+type PascalWords<S extends string> = S extends `${infer Head}-${infer Tail}` ? `${PascalWords<Head>}${PascalWords<Tail>}` : S extends `${infer Head}_${infer Tail}` ? `${Capitalize<Head>}${PascalWords<Tail>}` : Capitalize<S>;
+type OperationSegment<S extends string> = S extends `:${infer Param}` ? `By${PascalWords<Param>}` : PascalWords<S>;
+type OperationPathTail<P extends string> = P extends `${infer Segment}/${infer Rest}` ? `${OperationSegment<Segment>}${OperationPathTail<Rest>}` : OperationSegment<P>;
+type AutoOperationId<M extends HttpMethod, P extends PathString> = `${Lowercase<M>}${P extends "/" ? "Root" : P extends `/${infer Tail}` ? OperationPathTail<Tail> : never}`;
+type ShorthandOptions<P extends PathString, M extends HttpMethod, Req extends RequestSchemas | undefined, Res extends ResponsesMap, Op extends string | undefined> = Omit<RouteDefinition<P, M, Req, Res>, "method" | "path" | "operationId" | "handler"> & {
+    operationId?: Op;
+};
+type ShorthandRoute<P extends PathString, M extends HttpMethod, Req extends RequestSchemas | undefined, Res extends ResponsesMap, Op extends string | undefined> = RouteDefinition<P, M, Req, Res> & {
+    operationId: Op extends string ? Op : AutoOperationId<M, P>;
+};
 /**
  * The DaloyJS application: a contract-first router plus a web-standard
  * `fetch(Request): Promise<Response>` handler that runs unchanged on Node,
@@ -1007,6 +1064,8 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
         bodyLimitBytes: number;
         requestTimeoutMs: number;
         maxHeaderCount: number;
+        jsonMaxKeys: number;
+        jsonMaxDepth: number;
         stripServerHeaders: boolean;
         production: boolean;
     };
@@ -1204,6 +1263,74 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
     }): App<AppendRoute<Routes, RouteDefinition<P, M, Req, Res> & {
         operationId: Op;
     }>>;
+    /**
+     * Register a literal tuple of independently defined route contracts.
+     *
+     * Unlike repeated statements against an already-declared `App` variable,
+     * this method returns an App whose route tuple includes every supplied
+     * contract. That preserves the exact no-codegen client surface across route
+     * files and feature modules.
+     *
+     * @param definitions - Readonly literal tuple of route definitions.
+     * @returns This App instance widened with every supplied route contract.
+     * @since 1.0.0
+     */
+    registerRoutes<const Added extends readonly RouteDefinition<any, any, any, any>[]>(definitions: Added): App<AppendRoutes<Routes, Added>>;
+    /**
+     * Register a contract-backed `GET` route with validation and typed responses.
+     * @param path - Literal route path.
+     * @param options - Route schemas, responses, metadata, hooks, and security.
+     * @param handler - Handler contextually typed from the contract options.
+     * @returns This App widened with the registered route.
+     * @since 1.0.0
+     */
+    get<const P extends PathString, Req extends RequestSchemas | undefined, Res extends ResponsesMap, const Op extends string | undefined = undefined>(path: P, options: ShorthandOptions<P, "GET", Req, Res, Op>, handler: RouteDefinition<P, "GET", Req, Res>["handler"]): App<AppendRoute<Routes, ShorthandRoute<P, "GET", Req, Res, Op>>>;
+    /**
+     * Register a contract-backed `POST` route with validation and typed responses.
+     * @param path - Literal route path.
+     * @param options - Route schemas, responses, metadata, hooks, and security.
+     * @param handler - Handler contextually typed from the contract options.
+     * @returns This App widened with the registered route.
+     * @since 1.0.0
+     */
+    post<const P extends PathString, Req extends RequestSchemas | undefined, Res extends ResponsesMap, const Op extends string | undefined = undefined>(path: P, options: ShorthandOptions<P, "POST", Req, Res, Op>, handler: RouteDefinition<P, "POST", Req, Res>["handler"]): App<AppendRoute<Routes, ShorthandRoute<P, "POST", Req, Res, Op>>>;
+    /**
+     * Register a contract-backed `PUT` route with validation and typed responses.
+     * @param path - Literal route path.
+     * @param options - Route schemas, responses, metadata, hooks, and security.
+     * @param handler - Handler contextually typed from the contract options.
+     * @returns This App widened with the registered route.
+     * @since 1.0.0
+     */
+    put<const P extends PathString, Req extends RequestSchemas | undefined, Res extends ResponsesMap, const Op extends string | undefined = undefined>(path: P, options: ShorthandOptions<P, "PUT", Req, Res, Op>, handler: RouteDefinition<P, "PUT", Req, Res>["handler"]): App<AppendRoute<Routes, ShorthandRoute<P, "PUT", Req, Res, Op>>>;
+    /**
+     * Register a contract-backed `PATCH` route with validation and typed responses.
+     * @param path - Literal route path.
+     * @param options - Route schemas, responses, metadata, hooks, and security.
+     * @param handler - Handler contextually typed from the contract options.
+     * @returns This App widened with the registered route.
+     * @since 1.0.0
+     */
+    patch<const P extends PathString, Req extends RequestSchemas | undefined, Res extends ResponsesMap, const Op extends string | undefined = undefined>(path: P, options: ShorthandOptions<P, "PATCH", Req, Res, Op>, handler: RouteDefinition<P, "PATCH", Req, Res>["handler"]): App<AppendRoute<Routes, ShorthandRoute<P, "PATCH", Req, Res, Op>>>;
+    /**
+     * Register a contract-backed `DELETE` route with typed response statuses.
+     * @param path - Literal route path.
+     * @param options - Route schemas, responses, metadata, hooks, and security.
+     * @param handler - Handler contextually typed from the contract options.
+     * @returns This App widened with the registered route.
+     * @since 1.0.0
+     */
+    delete<const P extends PathString, Req extends RequestSchemas | undefined, Res extends ResponsesMap, const Op extends string | undefined = undefined>(path: P, options: ShorthandOptions<P, "DELETE", Req, Res, Op>, handler: RouteDefinition<P, "DELETE", Req, Res>["handler"]): App<AppendRoute<Routes, ShorthandRoute<P, "DELETE", Req, Res, Op>>>;
+    /**
+     * Register an explicit contract-backed `HEAD` route.
+     * @param path - Literal route path.
+     * @param options - Route schemas, responses, metadata, hooks, and security.
+     * @param handler - Handler contextually typed from the contract options.
+     * @returns This App widened with the registered route.
+     * @since 1.0.0
+     */
+    head<const P extends PathString, Req extends RequestSchemas | undefined, Res extends ResponsesMap, const Op extends string | undefined = undefined>(path: P, options: ShorthandOptions<P, "HEAD", Req, Res, Op>, handler: RouteDefinition<P, "HEAD", Req, Res>["handler"]): App<AppendRoute<Routes, ShorthandRoute<P, "HEAD", Req, Res, Op>>>;
+    private addHttpShorthand;
     /**
      * Register a WebSocket route. The handler runs when an HTTP client sends an
      * `Upgrade: websocket` request to `path`; the adapter performs the RFC 6455
@@ -1582,8 +1709,8 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      * "draining" signal); then the app waits up to `timeoutMs` for in-flight
      * requests to settle; finally, {@link App.onClose} cleanups run.
      *
-     * Both Node and Bun adapters call this automatically on `SIGINT` / `SIGTERM`.
-     * Call it manually from custom runtimes or integration tests.
+     * The Node, Bun, and Deno adapters call this automatically on `SIGINT` /
+     * `SIGTERM`. Call it manually from custom runtimes or integration tests.
      *
      * @param timeoutMs - Maximum time (ms) to wait for inflight requests. Default: `10_000`.
      * @param reason - Optional human-readable reason forwarded to listeners.
@@ -1671,11 +1798,4 @@ export declare function findRoutesMissingResponseBodySchema(routes: readonly Pic
  * @since 0.3.0
  */
 export declare function createApp(options?: AppOptions): App;
-/**
- * Test helper: clear the cached package.json read so each test starts
- * from a fresh lookup. Not part of the public API.
- *
- * @internal
- */
-export declare function _resetPackageJsonCacheForTests(): void;
 export {};