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

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/dist/waf.js

@@ -161,6 +161,75 @@ function safeDecode(value) {
         return value;
     }
 }
+/**
+ * Maximum percent-decode passes applied when expanding inspection variants.
+ *
+ * One pass matches what most HTTP stacks hand the handler. A second pass
+ * catches classic double-encoding WAF evasions (`%2527` → `%27` → `'`). A
+ * third is omitted on purpose: deeper recursive decoding inflates false
+ * positives on legitimately percent-bearing text and is not how frameworks
+ * deliver query/path values.
+ */
+const MAX_DECODE_PASSES = 2;
+/**
+ * Expand a single inbound string into the variants the WAF should scan.
+ *
+ * Includes the raw value, up to {@link MAX_DECODE_PASSES} percent-decodes,
+ * a `+`→space form (URLSearchParams parity), and a SQL-comment-stripped
+ * form so comment-split keywords (e.g. OR wrapped in block comments) score
+ * the same as the whitespace-separated form.
+ *
+ * Scanning variants is pure defense-in-depth: the handler still receives
+ * whatever the framework's single-decode path produced. Each variant is
+ * truncated to `maxValueLength` and deduplicated so hostile inputs cannot
+ * explode the scan set.
+ *
+ * @param value - Raw or already-decoded string from path/query/header/body.
+ * @param maxValueLength - Cap applied to every variant before scanning.
+ * @returns Deduplicated inspection variants in stable insertion order.
+ */
+function inspectionVariants(value, maxValueLength) {
+    const seen = new Set();
+    const out = [];
+    const push = (v) => {
+        const truncated = v.length > maxValueLength ? v.slice(0, maxValueLength) : v;
+        if (!seen.has(truncated)) {
+            seen.add(truncated);
+            out.push(truncated);
+        }
+    };
+    let current = value;
+    push(current);
+    for (let i = 0; i < MAX_DECODE_PASSES; i++) {
+        const decoded = safeDecode(current);
+        if (decoded === current)
+            break;
+        push(decoded);
+        current = decoded;
+    }
+    // Snapshot before secondary transforms so we only expand the decode chain.
+    const decodedChain = out.slice();
+    for (const v of decodedChain) {
+        if (v.includes("+"))
+            push(v.replace(/\+/g, " "));
+        if (v.includes("/*"))
+            push(v.replace(/\/\*[\s\S]*?\*\//g, " "));
+    }
+    return out;
+}
+/**
+ * Scan every inspection variant of `value` for the active rule set.
+ *
+ * @see inspectionVariants
+ */
+function scanValueVariants(value, location, rules, scored, maxValueLength) {
+    for (const variant of inspectionVariants(value, maxValueLength)) {
+        scanValue(variant, location, rules, scored);
+        // Early exit once every rule has already fired — no further variants needed.
+        if (scored.size === rules.length)
+            return;
+    }
+}
 /**
  * Collect up to `maxNodes` string values from a parsed body value (object /
  * array / scalar), each truncated to `maxValueLength`. Depth and node count are
@@ -268,37 +337,29 @@ export function waf(opts = {}) {
             const scored = new Map();
             const url = new URL(ctx.request.url);
             if (inspectPath) {
-                scanValue(safeDecode(url.pathname), "path", rules, scored);
+                // Path is scanned across raw + up to two decode passes so double-
+                // encoded traversal / injection tokens in path segments still score.
+                scanValueVariants(url.pathname, "path", rules, scored, maxValueLength);
             }
             if (inspectQuery && url.search.length > 1) {
-                // Scan both the raw query string and a best-effort decoded form so an
-                // encoded payload (`%27%20OR%201=1`) is caught after normalization.
-                // This is a SINGLE decode on purpose: the framework's request path also
-                // decodes the query exactly once, so the WAF sees the same bytes the
-                // handler will. Recursive decoding is deliberately avoided — it would
-                // false-positive on values that legitimately contain percent-encoded
-                // text, and a double-encoded payload stays inert (`%3Cscript%3E`) all
-                // the way to the handler. See red-team-attacks-6 "DOCUMENTED LIMITATION".
+                // Scan the raw query, bounded multi-decode variants, and each
+                // URLSearchParams key/value. Multi-decode (max 2) closes classic
+                // double-encoding WAF evasions (`%2527` → `%27` → `'`) without open-
+                // ended recursive decoding. URLSearchParams also turns `+` into
+                // space; inspectionVariants covers that form so `1+OR+1=1` scores
+                // the same as `1 OR 1=1` (parser-differential defense).
                 const raw = url.search.slice(1);
-                scanValue(raw, "query", rules, scored);
-                const decoded = safeDecode(raw);
-                if (decoded !== raw)
-                    scanValue(decoded, "query", rules, scored);
-                // Additionally inspect each key/value the way the app's OWN query parser
-                // (`URLSearchParams`) decodes them: notably `+` becomes a space, which a
-                // plain `decodeURIComponent` does NOT do. Without this, `1+OR+1=1` slipped
-                // past the WAF while the handler still received `1 OR 1=1` (a parser
-                // differential — the WAF must inspect the bytes the app actually parses).
+                scanValueVariants(raw, "query", rules, scored, maxValueLength);
                 for (const [k, v] of url.searchParams) {
-                    scanValue(k, "query", rules, scored);
-                    scanValue(v, "query", rules, scored);
+                    scanValueVariants(k, "query", rules, scored, maxValueLength);
+                    scanValueVariants(v, "query", rules, scored, maxValueLength);
                 }
             }
             if (headerAllowlist.length > 0) {
                 for (const name of headerAllowlist) {
                     const value = ctx.request.headers.get(name);
                     if (value)
-                        scanValue(value, "header", rules, scored);
+                        scanValueVariants(value, "header", rules, scored, maxValueLength);
                 }
             }
             if (inspectBody && ctx.body !== undefined && ctx.body !== null) {
@@ -316,14 +377,13 @@ export function waf(opts = {}) {
                     });
                 }
                 if (typeof ctx.body === "string") {
-                    scanValue(ctx.body.length > maxValueLength
-                        ? ctx.body.slice(0, maxValueLength)
-                        : ctx.body, "body", rules, scored);
+                    scanValueVariants(ctx.body, "body", rules, scored, maxValueLength);
                 }
                 else if (typeof ctx.body === "object") {
                     const strings = collectBodyStrings(ctx.body, maxBodyNodes, maxValueLength);
-                    for (const value of strings)
-                        scanValue(value, "body", rules, scored);
+                    for (const value of strings) {
+                        scanValueVariants(value, "body", rules, scored, maxValueLength);
+                    }
                 }
             }
             if (scored.size === 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daloyjs/core",
-  "version": "1.0.0-rc.3",
+  "version": "1.0.0-rc.5",
   "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"
@@ -232,12 +236,12 @@
     }
   },
   "devDependencies": {
-    "@hey-api/openapi-ts": "^0.99.0",
+    "@hey-api/openapi-ts": "0.0.0-next-20260711024907",
     "@types/node": "^26.0.1",
     "fast-check": "^4.8.0",
     "prettier": "^3.8.3",
     "tsx": "^4.22.3",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "zod": "^4.4.3"
   },
   "scripts": {
@@ -245,7 +249,10 @@
     "dev": "tsc -w -p tsconfig.json",
     "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:serverless": "pnpm build && 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",
+    "bench:ablation": "pnpm build && node --import tsx bench/ablation.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",