@daloyjs/core 1.0.0-rc.2 → 1.0.0-rc.4

package/dist/pagination.js

@@ -28,6 +28,7 @@
  * @since 0.37.0
  */
 import { BadRequestError } from "./errors.js";
+import { safeJsonParseLimited } from "./security.js";
 import { isForbiddenObjectKey } from "./security.js";
 /**
  * Hard cap on the length of an encoded cursor string accepted by
@@ -91,7 +92,9 @@ export function decodeCursor(cursor) {
     }
     let parsed;
     try {
-        parsed = JSON.parse(json);
+        // Use limited parse for structural safety (wide/deep cursors).
+        // Cursors are length-capped at 4k so even default limits are very generous here.
+        parsed = safeJsonParseLimited(json, 1000, 20);
     }
     catch {
         throw new BadRequestError("Malformed pagination cursor.");

package/dist/response-cache.js

@@ -39,6 +39,7 @@
  * @module
  * @since 0.37.0
  */
+import { markSchemaValidatedResponse } from "./internal-response.js";
 /** Internal `ctx.state` key carrying the pending cache key between hooks. */
 const PENDING_STATE_KEY = "__responseCachePending";
 /**
@@ -183,7 +184,7 @@ function buildResponseFromCache(entry, outcome, statusHeaderName, isHead) {
     if (statusHeaderName)
         headers.set(statusHeaderName, outcome);
     const body = isHead || entry.body === "" ? null : base64ToBytes(entry.body);
-    return new Response(body, { status: entry.status, headers });
+    return markSchemaValidatedResponse(new Response(body, { status: entry.status, headers }));
 }
 function isPromiseLike(value) {
     return (value !== null &&

package/dist/safe-redirect.d.ts

@@ -31,7 +31,10 @@
  * ```ts
  * import { safeRedirect } from "@daloyjs/core";
  *
- * app.get("/login/callback", (ctx) => {
+ * app.get("/login/callback", {
+ *   acknowledgeNoResponseBodySchema: true,
+ *   responses: { 303: {} },
+ * }, (ctx) => {
  *   const next = new URL(ctx.request.url).searchParams.get("next") ?? "/";
  *   return safeRedirect(next, {
  *     allowedPaths: ["/", "/dashboard", "/account"],

package/dist/safe-redirect.js

@@ -31,7 +31,10 @@
  * ```ts
  * import { safeRedirect } from "@daloyjs/core";
  *
- * app.get("/login/callback", (ctx) => {
+ * app.get("/login/callback", {
+ *   acknowledgeNoResponseBodySchema: true,
+ *   responses: { 303: {} },
+ * }, (ctx) => {
  *   const next = new URL(ctx.request.url).searchParams.get("next") ?? "/";
  *   return safeRedirect(next, {
  *     allowedPaths: ["/", "/dashboard", "/account"],

package/dist/sbom.cdx.json

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:8448de36-3a72-553d-882f-b5b36bbd1426",
+  "serialNumber": "urn:uuid:6aa5f3fd-e017-5e4a-b206-49dc6d141768",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-07T09:24:36.816Z",
+    "timestamp": "2026-07-12T20:39:15.454Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "1.0.0-rc.2"
+        "version": "1.0.0-rc.4"
       }
     ],
     "authors": [
@@ -19,11 +19,11 @@
     ],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-rc.2",
+      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-rc.4",
       "name": "@daloyjs/core",
-      "version": "1.0.0-rc.2",
+      "version": "1.0.0-rc.4",
       "description": "DaloyJS is a runtime-portable, contract-first TypeScript web framework with built-in OpenAPI (Hey API), typed client generation, large-scale maintainability, and security-first defaults. Hono-grade portability, Elysia-grade DX, FastAPI-grade docs, Fastify-grade ops — distributed via pnpm.",
-      "purl": "pkg:npm/@daloyjs/core@1.0.0-rc.2",
+      "purl": "pkg:npm/@daloyjs/core@1.0.0-rc.4",
       "licenses": [
         {
           "license": {
@@ -46,9 +46,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-1.0.0-rc.2",
+        "tagId": "swidtag--daloyjs-core-1.0.0-rc.4",
         "name": "@daloyjs/core",
-        "version": "1.0.0-rc.2",
+        "version": "1.0.0-rc.4",
         "tagVersion": 0,
         "patch": false
       }
@@ -57,7 +57,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/@daloyjs/core@1.0.0-rc.2",
+      "ref": "pkg:npm/@daloyjs/core@1.0.0-rc.4",
       "dependsOn": []
     }
   ]

package/dist/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@daloyjs/core-1.0.0-rc.2",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-rc.2-8448de36-3a72-553d-882f-b5b36bbd1426",
+  "name": "@daloyjs/core-1.0.0-rc.4",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-rc.4-6aa5f3fd-e017-5e4a-b206-49dc6d141768",
   "creationInfo": {
-    "created": "2026-07-07T09:24:36.816Z",
+    "created": "2026-07-12T20:39:15.454Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package--daloyjs-core",
       "name": "@daloyjs/core",
-      "versionInfo": "1.0.0-rc.2",
+      "versionInfo": "1.0.0-rc.4",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/@daloyjs/core@1.0.0-rc.2"
+          "referenceLocator": "pkg:npm/@daloyjs/core@1.0.0-rc.4"
         }
       ]
     }

package/dist/security.d.ts

@@ -460,3 +460,24 @@ export declare function hasMongoOperatorKeys(value: unknown): boolean;
  * @since 0.35.0
  */
 export declare function assertNoMongoOperators(value: unknown): void;
+/**
+ * Like {@link safeJsonParse}, but additionally enforces structural limits
+ * (total object keys across the tree and maximum nesting depth) to defend
+ * against wide-object / hash-flood and deep-nesting DoS payloads that stay
+ * under the byte cap.
+ *
+ * The limits are checked with a single pre-parse text scan
+ * ({@link assertJsonTextStructure}), so an oversized structure is rejected
+ * *before* it is parsed or allocated. On success the text is handed to
+ * {@link safeJsonParse}, which applies the same prototype-pollution stripping
+ * as every other body parser — so the security posture is identical, only the
+ * structural bounds are added.
+ *
+ * @param text - JSON text. Empty string returns `undefined`.
+ * @param maxKeys - Maximum total object keys (0 or negative = unlimited).
+ * @param maxDepth - Maximum nesting depth (0 or negative = unlimited).
+ * @returns Parsed value (with dangerous keys stripped).
+ * @throws {BadRequestError} on invalid JSON or when limits are exceeded.
+ * @since 1.0.0
+ */
+export declare function safeJsonParseLimited(text: string, maxKeys?: number, maxDepth?: number): unknown;

package/dist/security.js

@@ -876,3 +876,92 @@ export function assertNoMongoOperators(value) {
         throw new BadRequestError("Operator-prefixed key rejected");
     }
 }
+/**
+ * Enforces structural limits by scanning raw JSON *text* in a single
+ * allocation-free pass, before the value is parsed — so a wide-object or
+ * deep-nesting bomb is rejected without ever being materialized into memory.
+ *
+ * Object keys are counted via `:` delimiters that sit outside string literals:
+ * every JSON object member is `"key": value`, and array elements carry no
+ * colon, so the number of structural colons equals the total object-key count
+ * across the whole tree. Nesting depth tracks the running `{`/`[` … `}`/`]`
+ * balance, again ignoring characters inside strings. Both checks short-circuit
+ * the instant a limit is exceeded, giving bounded-time rejection.
+ *
+ * This mirrors the accounting of the older recursive object walk but costs one
+ * tight character loop instead of a second full traversal of the parsed graph,
+ * keeping the common (small-body) path close to a bare `JSON.parse`.
+ *
+ * @param text - The raw JSON text (already known to be non-empty).
+ * @param maxKeys - Maximum total object keys (`<= 0` disables the key check).
+ * @param maxDepth - Maximum nesting depth (`<= 0` disables the depth check).
+ * @throws {BadRequestError} When the key or depth limit is exceeded.
+ * @internal
+ */
+function assertJsonTextStructure(text, maxKeys, maxDepth) {
+    let depth = 0;
+    let keyCount = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (c === 0x5c /* \ */)
+                escaped = true;
+            else if (c === 0x22 /* " */)
+                inString = false;
+            continue;
+        }
+        switch (c) {
+            case 0x22 /* " */:
+                inString = true;
+                break;
+            case 0x7b /* { */:
+            case 0x5b /* [ */:
+                depth++;
+                if (maxDepth > 0 && depth > maxDepth) {
+                    throw new BadRequestError("JSON exceeds maximum nesting depth");
+                }
+                break;
+            case 0x7d /* } */:
+            case 0x5d /* ] */:
+                depth--;
+                break;
+            case 0x3a /* : */:
+                if (maxKeys > 0 && ++keyCount > maxKeys) {
+                    throw new BadRequestError("JSON exceeds maximum key count");
+                }
+                break;
+        }
+    }
+}
+/**
+ * Like {@link safeJsonParse}, but additionally enforces structural limits
+ * (total object keys across the tree and maximum nesting depth) to defend
+ * against wide-object / hash-flood and deep-nesting DoS payloads that stay
+ * under the byte cap.
+ *
+ * The limits are checked with a single pre-parse text scan
+ * ({@link assertJsonTextStructure}), so an oversized structure is rejected
+ * *before* it is parsed or allocated. On success the text is handed to
+ * {@link safeJsonParse}, which applies the same prototype-pollution stripping
+ * as every other body parser — so the security posture is identical, only the
+ * structural bounds are added.
+ *
+ * @param text - JSON text. Empty string returns `undefined`.
+ * @param maxKeys - Maximum total object keys (0 or negative = unlimited).
+ * @param maxDepth - Maximum nesting depth (0 or negative = unlimited).
+ * @returns Parsed value (with dangerous keys stripped).
+ * @throws {BadRequestError} on invalid JSON or when limits are exceeded.
+ * @since 1.0.0
+ */
+export function safeJsonParseLimited(text, maxKeys = 10_000, maxDepth = 50) {
+    if (text.length === 0)
+        return undefined;
+    if (maxKeys > 0 || maxDepth > 0) {
+        assertJsonTextStructure(text, maxKeys, maxDepth);
+    }
+    return safeJsonParse(text);
+}

package/dist/tenancy.d.ts

@@ -48,7 +48,7 @@
  *
  * @since 0.42.0
  */
-import type { BaseContext, Hooks } from "./types.js";
+import type { BaseContext, Hooks, PreBodyContext } from "./types.js";
 /**
  * Resolves a raw (un-normalized) tenant id from a request, or a nullish value
  * when this strategy cannot determine one. Resolvers are tried in order and
@@ -249,4 +249,4 @@ export interface TenantScopeOptions {
  * @returns A key function suitable for `keyGenerator` / `scope`.
  * @since 0.42.0
  */
-export declare function tenantScope(opts?: TenantScopeOptions): (ctx: BaseContext<any, any>) => string;
+export declare function tenantScope(opts?: TenantScopeOptions): (ctx: BaseContext<any, any> | PreBodyContext<any>) => string;

package/dist/types.d.ts

@@ -103,7 +103,8 @@ export type InferRequest<R extends RequestSchemas | undefined, P extends string>
 /**
  * Describes a single HTTP response variant declared by a route.
  *
- * - `description` — surfaces in OpenAPI documentation. Required.
+ * - `description` — optional OpenAPI documentation; omitted values receive a
+ *   stable `HTTP <status> response` fallback.
  * - `body`        — Standard-Schema validator for the response body; when
  *   present, DaloyJS validates the handler's return value against it
  *   (controlled by `AppOptions.validateResponses`).
@@ -114,8 +115,8 @@ export type InferRequest<R extends RequestSchemas | undefined, P extends string>
  * @since 0.1.0
  */
 export interface ResponseSpec {
-    /** Human-readable description emitted into the OpenAPI response object. Required. */
-    description: string;
+    /** Human-readable OpenAPI description. Defaults to `HTTP <status> response`. */
+    description?: string;
     /** Response-body validator; handler return values are checked against it when `AppOptions.validateResponses` is on. */
     body?: StandardSchemaV1;
     /** Documented response headers keyed by header name; surfaced in the OpenAPI document. */
@@ -273,20 +274,53 @@ export interface BaseContext<P extends string, R extends RequestSchemas | undefi
         headers: Headers;
     };
 }
+/**
+ * Minimal request context exposed before request-body I/O or schema
+ * validation. It is intended for cheap perimeter decisions such as bearer,
+ * API-key, mTLS, and header-only JWT authentication.
+ *
+ * Path, query, and header values are raw at this phase, and `body` is always
+ * `undefined`. Middleware that requires validated input or body bytes belongs
+ * in {@link Hooks.beforeHandle}.
+ *
+ * @typeParam P - Literal route path used to infer raw path-parameter names.
+ * @since 1.0.0
+ */
+export interface PreBodyContext<P extends string = string> {
+    /** Original web-standard Request. Its body stream has not been consumed by DaloyJS. */
+    request: Request;
+    /** Raw router path parameters. */
+    params: PathParams<P>;
+    /** Raw query-string values, materialized lazily. */
+    query: Record<string, string | string[] | undefined>;
+    /** Raw request headers, materialized lazily. */
+    headers: Record<string, string | undefined>;
+    /** Always `undefined`; request-body I/O has not started. */
+    body: undefined;
+    /** Mutable per-request state shared with later hooks and the handler. */
+    state: AppState & Record<string, unknown>;
+    /** Response headers/status available to a short-circuiting perimeter hook. */
+    set: {
+        status?: number;
+        headers: Headers;
+    };
+}
 /**
  * Lifecycle hooks fired around request handling. Hooks compose pipeline-style
  * — the global hooks (`AppOptions.hooks`) run first, then group hooks added
  * with `app.use()`, then per-route hooks. Returning a `Response` from
- * `beforeHandle` or `onSend` short-circuits/replaces the response.
+ * `preBody`, `beforeHandle`, or `onSend` short-circuits/replaces the response.
  *
  * Ordering for a successful request:
  *   1. `onRequest`     — before any context is built (raw `Request`).
- *   2. `beforeHandle`  — with the built context; may short-circuit.
- *   3. *handler runs*
- *   4. `afterHandle`   — may transform the handler return value.
- *   5. *response is serialized + validated*
- *   6. `onSend`        — may mutate or replace the outgoing `Response`.
- *   7. `onResponse`    — fire-and-forget observer (cannot change anything).
+ *   2. `preBody`       — after routing, before body I/O or validation.
+ *   3. *request schemas are validated and the body is read when declared*
+ *   4. `beforeHandle`  — with the validated context; may short-circuit.
+ *   5. *handler runs*
+ *   6. `afterHandle`   — may transform the handler return value.
+ *   7. *response is serialized + validated*
+ *   8. `onSend`        — may mutate or replace the outgoing `Response`.
+ *   9. `onResponse`    — fire-and-forget observer (cannot change anything).
  *
  * `onError` runs on the error path before serialization.
  *
@@ -295,7 +329,9 @@ export interface BaseContext<P extends string, R extends RequestSchemas | undefi
 export interface Hooks {
     /** Runs first, before validation or context building. Receives the raw web-standard `Request`. */
     onRequest?: (req: Request) => void | Promise<void>;
-    /** Runs with the validated {@link BaseContext} before the handler. Returning a `Response` short-circuits the handler entirely (useful for auth guards). */
+    /** Runs after route matching but before request-body I/O or schema validation. Use for cheap header/certificate auth; `ctx.body` is always undefined. A successful raw `Response` requires the route's `acknowledgeNoResponseBodySchema` flag; `4xx`/`5xx` denials do not. */
+    preBody?: (ctx: PreBodyContext<any>) => void | Response | Promise<void | Response>;
+    /** Runs with the validated {@link BaseContext} before the handler. Returning a `Response` short-circuits the handler entirely. Successful raw responses require the route's `acknowledgeNoResponseBodySchema` flag; `4xx`/`5xx` auth denials do not. */
     beforeHandle?: (ctx: BaseContext<any, any>) => void | Response | Promise<void | Response>;
     /** Runs after the handler with its raw return value. Return a non-`undefined` value to replace the result before serialization and response-schema validation. */
     afterHandle?: (ctx: BaseContext<any, any>, result: unknown) => void | unknown | Promise<void | unknown>;
@@ -358,16 +394,22 @@ export interface RouteDefinition<P extends PathString = PathString, M extends Ht
     /** Optional per-route API version label. Informational metadata only; not emitted into the OpenAPI document. */
     version?: string;
     /**
-     * Acknowledge that this route's `2xx` responses intentionally carry no
-     * response body schema — an opaque, framework-controlled, or non-JSON body
-     * (a raw `Response`, an HTML page, a spec document, a proxied payload).
+     * Acknowledge that this route's output intentionally is not protected by a
+     * response body schema — either because its `2xx` response declares no body
+     * schema or because it returns an opaque, framework-controlled raw
+     * `Response` (an HTML page, stream, spec document, or proxied payload).
      *
      * Setting this suppresses the `security.response.bodySchemaMissing` boot
      * warning and the `audit.response.bodySchema` `daloy doctor` finding for
-     * this route only. It documents intent; it does not add protection —
-     * response field-level stripping (OWASP API3) still does not run for a
-     * `2xx` response without a body schema, so never set this on a route whose
-     * handler builds JSON from domain objects.
+     * this route only. It also explicitly authorizes a handler or `afterHandle`
+     * hook to return a raw `Response`, or a `preBody` / `beforeHandle` hook to
+     * short-circuit with a successful (`2xx`/`3xx`) raw `Response`. DaloyJS fails
+     * closed with a `500` when those cases lack this acknowledgement. Ordinary
+     * `4xx`/`5xx` hook denials and errors remain available without opting out of
+     * response validation. This flag documents intent; it does not add
+     * protection — response field-level stripping (OWASP API3) does not run for
+     * an opaque body, so never set this on a route whose handler builds JSON from
+     * domain objects.
      */
     acknowledgeNoResponseBodySchema?: boolean;
     /**
@@ -489,8 +531,11 @@ export interface RouteDefinition<P extends PathString = PathString, M extends Ht
      *   forwarded verbatim).
      *
      * A returned `Response` **bypasses response-schema validation and the
-     * typed-client body type by design** — there is no schema that can describe
-     * an opaque stream. It is still finalized exactly like every other response,
+     * typed-client body type by design** and therefore requires
+     * `acknowledgeNoResponseBodySchema: true` on the route. Without that explicit
+     * acknowledgement, DaloyJS refuses the response with a `500` instead of
+     * silently weakening the contract. An acknowledged raw response is still
+     * finalized exactly like every other response,
      * so no security control is skipped: headers set via `ctx.set` (including
      * `secureHeaders()` and CORS) are copied onto it, `x-request-id` is added
      * when absent, any `onSend` / `onResponse` hooks run, server-fingerprint
@@ -503,6 +548,26 @@ export interface RouteDefinition<P extends PathString = PathString, M extends Ht
      */
     handler: (ctx: BaseContext<P, Req>) => HandlerReturn<Res> | Response | Promise<HandlerReturn<Res> | Response>;
 }
+/**
+ * Define a route contract outside an {@link "./app.js".App} while preserving
+ * its literal path, method, operation id, schemas, and contextually typed
+ * handler.
+ *
+ * Export contracts from route modules, collect them in a literal tuple, then
+ * register the tuple with {@link "./app.js".App.registerRoutes}. The returned
+ * App retains the complete tuple for the no-codegen typed client.
+ *
+ * @param definition - Complete route contract and handler.
+ * @returns The same definition object, unchanged at runtime.
+ * @since 1.0.0
+ */
+export declare function defineRoute<const P extends PathString, const M extends HttpMethod, Req extends RequestSchemas | undefined, Res extends ResponsesMap, const Op extends string | undefined = undefined>(definition: RouteDefinition<P, M, Req, Res> & {
+    operationId?: Op;
+}): RouteDefinition<P, M, Req, Res> & (Op extends string ? {
+    operationId: Op;
+} : {
+    operationId?: undefined;
+});
 /**
  * One operation inside an OpenAPI Callback Object. Mirrors a route minus
  * `path` (the URL is supplied at runtime via the expression key) and

package/dist/types.js

@@ -1 +1,16 @@
-export {};
+/**
+ * Define a route contract outside an {@link "./app.js".App} while preserving
+ * its literal path, method, operation id, schemas, and contextually typed
+ * handler.
+ *
+ * Export contracts from route modules, collect them in a literal tuple, then
+ * register the tuple with {@link "./app.js".App.registerRoutes}. The returned
+ * App retains the complete tuple for the no-codegen typed client.
+ *
+ * @param definition - Complete route contract and handler.
+ * @returns The same definition object, unchanged at runtime.
+ * @since 1.0.0
+ */
+export function defineRoute(definition) {
+    return definition;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daloyjs/core",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.4",
   "description": "DaloyJS is a runtime-portable, contract-first TypeScript web framework with built-in OpenAPI (Hey API), typed client generation, large-scale maintainability, and security-first defaults. Hono-grade portability, Elysia-grade DX, FastAPI-grade docs, Fastify-grade ops — distributed via pnpm.",
   "type": "module",
   "publishConfig": {
@@ -46,6 +46,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./app": {
+      "types": "./dist/app.d.ts",
+      "import": "./dist/app.js"
+    },
     "./node": {
       "types": "./dist/adapters/node.d.ts",
       "import": "./dist/adapters/node.js"
@@ -246,6 +250,8 @@
     "example": "node --import tsx examples/basic.ts",
     "bench": "node --import tsx bench/router.bench.ts",
     "bench:serverless": "node --import tsx bench/serverless-cold-path.bench.ts",
+    "bench:json": "node --import tsx bench/json-body.bench.ts",
+    "bench:json-e2e": "node --import tsx bench/json-body-e2e.bench.ts",
     "test": "node --import tsx --test tests/**/*.test.ts",
     "test:red-team": "node --import tsx --test tests/red-team-attacks.test.ts tests/red-team-attacks-2.test.ts tests/red-team-attacks-3.test.ts tests/red-team-attacks-4.test.ts tests/red-team-attacks-5.test.ts tests/red-team-attacks-6.test.ts tests/red-team-attacks-7.test.ts tests/red-team-attacks-8.test.ts tests/red-team-attacks-9.test.ts tests/red-team-attacks-10.test.ts",
     "red-team:live": "node --import tsx red-team-live/run.ts",