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

package/README.md

@@ -55,7 +55,7 @@ DaloyJS exists to be the framework you'd build if you took the best ideas from e
 | **Contract-first typed client, no codegen**                | [ts-rest](https://ts-rest.com/)                                       | Your route definition *is* the contract: an in-process typed client with zero codegen, plus OpenAPI 3.1 + a Hey API SDK for consumers that can't import your types. |
 | Opinionated **DI / module architecture** for large teams   | [NestJS](https://docs.nestjs.com/)                                    | Plugin encapsulation, `register()` prefixes, and `defineDependency()` typed-DI with per-request dedup — no decorators. |
 | Minimalist **async middleware cascade**                    | [Koa](https://koajs.com/)                                             | Koa-style `Context` on a web-standard core, with validation, OpenAPI, errors, and security headers in-box.            |
-| **Services + real-time** API framework                     | [FeathersJS](https://feathersjs.com/)                                 | First-party `app.ws()` with CSWSH refuse-to-boot guards, plus SSE / NDJSON streaming over explicit OpenAPI routes.    |
+| **Services + real-time** API framework                     | [FeathersJS](https://feathersjs.com/)                                 | First-party `app.ws()` with CSWSH refuse-to-boot guards, plus SSE / NDJSON streaming and raw `Response` passthrough (return a Vercel AI SDK stream straight from a handler) over explicit OpenAPI routes.    |
 | Battle-tested **Node middleware compatibility**            | [Express v5](https://expressjs.com/en/blog/2024-10-15-v5-release)     | Regex-free trie router, schema-validated routes, RFC 9457 problem+json, and refuse-to-boot guards on every runtime.   |
 | **Portable supply-chain hardening** for the apps you build | [pnpm](https://pnpm.io/motivation) defaults + a zero-runtime-dep core | Hardened `.npmrc`, source-verified lockfiles, zero runtime deps, CycloneDX + SPDX SBOM, and npm provenance attestations. |
 
@@ -507,7 +507,7 @@ The core only ever sees `Request → Response`. Adapters live at the edge.
 
 ## Status
 
-DaloyJS is now in the **`1.0.0` beta** (`1.0.0-beta.2`). The public API is feature-complete and stable for the 1.0 line; from `1.0.0` onward, breaking changes follow SemVer and deprecations get at least one minor cycle. Small adjustments are still possible before the `1.0.0` GA if beta feedback surfaces something. The framework is already in use for production trials.
+DaloyJS is now in the **`1.0.0` beta** (`1.0.0-beta.4`). The public API is feature-complete and stable for the 1.0 line; from `1.0.0` onward, breaking changes follow SemVer and deprecations get at least one minor cycle. Small adjustments are still possible before the `1.0.0` GA if beta feedback surfaces something. The framework is already in use for production trials.
 
 **Release quality bar.** Every release ships with **≥90% line + function coverage and ≥90% branch coverage**, strict TypeScript, OpenSSF Scorecard, CodeQL + Opengrep dual SAST, zizmor workflow linting, and npm provenance. Coverage was relaxed from a former 100% gate so complex security work isn't blocked chasing throwaway tests for unreachable defensive branches or tsx source-map phantoms; see [AGENTS.md](AGENTS.md) for the policy.
 

package/dist/adapters/node.js

@@ -296,7 +296,7 @@ function toWebRequest(req, trustProxy, bufferedBody) {
         : undefined;
     const proto = forwardedProto ??
         (req.socket.encrypted ? "https" : "http");
-    const url = `${proto}://${host}${req.url ?? "/"}`;
+    const url = `${proto}://${host}${normalizeRequestTarget(req.url)}`;
     // 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
@@ -348,6 +348,23 @@ function firstHeader(v) {
     const comma = raw.indexOf(",");
     return (comma === -1 ? raw : raw.slice(0, comma)).trim() || undefined;
 }
+function normalizeRequestTarget(target) {
+    const raw = target && target.length > 0 ? target : "/";
+    if (raw.charCodeAt(0) === 47 /* / */)
+        return raw;
+    if (raw.startsWith("http://") || raw.startsWith("https://")) {
+        try {
+            const url = new URL(raw);
+            return `${url.pathname}${url.search}`;
+        }
+        catch {
+            return "/";
+        }
+    }
+    if (raw.charCodeAt(0) === 63 /* ? */)
+        return `/${raw}`;
+    return `/${raw}`;
+}
 function sendWebResponse(res, out) {
     out.statusCode = res.status;
     res.headers.forEach((v, k) => out.setHeader(k, v));

package/dist/app.js

@@ -623,6 +623,42 @@ export class App {
      * a misconfigured surface.
      */
     assertSecureHookConfig(hooks) {
+        // Always-on correctness guard (independent of secureDefaults / environment).
+        // A hook bundle must be a single Hooks object. Passing an ARRAY — or any
+        // object carrying none of the recognized hook keys — is a silent no-op: the
+        // framework reads `.beforeHandle` / `.onSend` / ... off it, finds
+        // `undefined`, and applies NOTHING. A route that looks guarded
+        // (`hooks: [ipRestriction(...), bearerAuth(...)]`) would then ship wide open.
+        // TypeScript already rejects an array literal here; this catches JS callers,
+        // spreads, and `as`-casts, where the silent runtime skip is the dangerous part.
+        if (hooks !== null && typeof hooks === "object") {
+            const HOOK_KEYS = [
+                "onRequest",
+                "beforeHandle",
+                "afterHandle",
+                "onError",
+                "onSend",
+                "onResponse",
+            ];
+            const carriesAHook = HOOK_KEYS.some((k) => typeof hooks[k] === "function");
+            if (!carriesAHook) {
+                if (Array.isArray(hooks)) {
+                    throw new Error("Hooks must be a single Hooks object, not an array. To run multiple " +
+                        "hook bundles (e.g. ipRestriction + bearerAuth) on one route, compose " +
+                        "them with every(...) (all must pass) or some(...) (any may pass) from " +
+                        "@daloyjs/core. Passing an array silently applies NO hooks, leaving the " +
+                        "route unguarded.");
+                }
+                if (Object.keys(hooks).length > 0) {
+                    throw new Error("Hooks object carries none of the recognized hook keys (onRequest, " +
+                        "beforeHandle, afterHandle, onError, onSend, onResponse), so it would " +
+                        "silently apply no hooks. To compose multiple hook bundles use " +
+                        "every(...) / some(...) from @daloyjs/core.");
+                }
+                // An empty object `{}` carries no hook and makes no false promise of one;
+                // it is an explicit no-op, equivalent to omitting `hooks`, and is allowed.
+            }
+        }
         if (this.options.secureDefaults === false)
             return;
         const record = hooks;
@@ -2260,6 +2296,37 @@ export class App {
                 if (afterReturn !== undefined)
                     result = afterReturn;
             }
+            // Escape hatch: a handler (or an `afterHandle` transform) may return a
+            // raw web-standard `Response` — an AI SDK stream, a forwarded upstream
+            // response, or any pre-built body that no response schema can describe.
+            // It bypasses response-schema validation by design, but is finalized
+            // through the exact same path as every other response (and as the
+            // `beforeHandle` `Response` passthrough above), so no security control
+            // is skipped: `ctx.set` headers (secureHeaders / CORS) are copied on, the
+            // request id is added when absent, `onSend` / `onResponse` hooks run,
+            // fingerprint headers are stripped, and `HEAD` yields an empty body.
+            if (result instanceof Response) {
+                copyContextHeaders(ctx, result);
+                if (!result.headers.has("x-request-id")) {
+                    result.headers.set("x-request-id", requestId);
+                }
+                let finalizedRaw;
+                if (hasFinalizeHook) {
+                    const fin = finalizeResponse(result, ctx, allHooks, stripFingerprint);
+                    finalizedRaw = isPromiseLike(fin) ? await fin : fin;
+                }
+                else {
+                    finalizedRaw = finalizeFast(result, stripFingerprint);
+                }
+                if (method === "HEAD") {
+                    return new Response(null, {
+                        status: finalizedRaw.status,
+                        statusText: finalizedRaw.statusText,
+                        headers: finalizedRaw.headers,
+                    });
+                }
+                return finalizedRaw;
+            }
             const serializeResultRes = serializeResult(result, def, this.options.validateResponses ?? true);
             let response = isPromiseLike(serializeResultRes) ? await serializeResultRes : serializeResultRes;
             copyContextHeaders(ctx, response);
@@ -3265,7 +3332,7 @@ function serializeResult(result, def, validateResponses) {
         const treatAsJson = !explicitCt || explicitCt.includes("application/json");
         if (!explicitCt)
             headers.set("content-type", "application/json");
-        // RFC 8594 deprecation lifecycle headers. A route with an explicit
+        // Deprecation lifecycle headers. A route with an explicit RFC 8594
         // `sunset` date is implicitly deprecated. Never overwrite a value the
         // handler set deliberately.
         if (def.deprecated === true || def.sunset !== undefined) {

package/dist/docs.js

@@ -218,6 +218,7 @@ export function htmlResponse(html, opts = {}) {
                     connectOrigins: opts.connectOrigins,
                     scriptNonce: opts.scriptNonce,
                     allowInlineStyles: opts.allowInlineStyles,
+                    allowBlobWorkers: opts.allowBlobWorkers,
                 }),
             "x-content-type-options": "nosniff",
             "referrer-policy": "no-referrer",

package/dist/pagination.d.ts

@@ -15,8 +15,8 @@
  * - {@link buildLinkHeader} / {@link buildPageLinks} — assemble a Web-standard
  *   `Link` header, with CRLF / angle-bracket header-injection guards baked in.
  * - {@link paginationQuery} — a Standard Schema validator for the `cursor` +
- *   `limit` query parameters that both validates at runtime (clamping `limit`
- *   to a safe range) **and** advertises itself to the OpenAPI generator via a
+ *   `limit` query parameters that both validates runtime page-size bounds
+ *   **and** advertises itself to the OpenAPI generator via a
  *   `toJSONSchema()` method, so `request: { query: paginationQuery() }` wires
  *   the parameters into the contract with no extra code.
  *
@@ -157,12 +157,12 @@ export interface PaginationQueryOptions {
     defaultLimit?: number;
     /** Minimum accepted page size. Default: `1`. */
     minLimit?: number;
-    /** Maximum accepted page size (also caps over-large requests). Default: `100`. */
+    /** Maximum accepted page size. Over-large requests are rejected. Default: `100`. */
     maxLimit?: number;
 }
 /** Validated output of {@link paginationQuery}. */
 export interface PaginationParams {
-    /** The resolved page size, clamped to `[minLimit, maxLimit]`. */
+    /** The resolved page size after validation against `[minLimit, maxLimit]`. */
     limit: number;
     /** The opaque cursor, if the client supplied one. */
     cursor?: string;
@@ -180,11 +180,12 @@ export interface PaginationQuerySchema extends StandardSchemaV1<Record<string, u
  * Build a Standard Schema validator for cursor-pagination query parameters.
  *
  * Use it as a route's `request.query`. At runtime it parses and validates
- * `limit` (coerced from its string query value to an integer and clamped to
- * `[minLimit, maxLimit]`, defaulting to `defaultLimit` when absent) and passes
- * `cursor` through as an optional opaque string. Because it also exposes
- * `toJSONSchema()`, the same call wires both parameters into the generated
- * OpenAPI document and typed client — no duplicate parameter declarations.
+ * `limit` (coerced from its string query value to an integer, rejected when
+ * outside `[minLimit, maxLimit]`, and defaulting to `defaultLimit` when absent)
+ * and passes `cursor` through as an optional opaque string. Because it also
+ * exposes `toJSONSchema()`, the same call wires both parameters into the
+ * generated OpenAPI document and typed client — no duplicate parameter
+ * declarations.
  *
  * @example
  * ```ts

package/dist/pagination.js

@@ -15,8 +15,8 @@
  * - {@link buildLinkHeader} / {@link buildPageLinks} — assemble a Web-standard
  *   `Link` header, with CRLF / angle-bracket header-injection guards baked in.
  * - {@link paginationQuery} — a Standard Schema validator for the `cursor` +
- *   `limit` query parameters that both validates at runtime (clamping `limit`
- *   to a safe range) **and** advertises itself to the OpenAPI generator via a
+ *   `limit` query parameters that both validates runtime page-size bounds
+ *   **and** advertises itself to the OpenAPI generator via a
  *   `toJSONSchema()` method, so `request: { query: paginationQuery() }` wires
  *   the parameters into the contract with no extra code.
  *
@@ -190,11 +190,12 @@ export function buildPageLinks(opts) {
  * Build a Standard Schema validator for cursor-pagination query parameters.
  *
  * Use it as a route's `request.query`. At runtime it parses and validates
- * `limit` (coerced from its string query value to an integer and clamped to
- * `[minLimit, maxLimit]`, defaulting to `defaultLimit` when absent) and passes
- * `cursor` through as an optional opaque string. Because it also exposes
- * `toJSONSchema()`, the same call wires both parameters into the generated
- * OpenAPI document and typed client — no duplicate parameter declarations.
+ * `limit` (coerced from its string query value to an integer, rejected when
+ * outside `[minLimit, maxLimit]`, and defaulting to `defaultLimit` when absent)
+ * and passes `cursor` through as an optional opaque string. Because it also
+ * exposes `toJSONSchema()`, the same call wires both parameters into the
+ * generated OpenAPI document and typed client — no duplicate parameter
+ * declarations.
  *
  * @example
  * ```ts

package/dist/safe-redirect.d.ts

@@ -14,8 +14,11 @@
  * - Same-origin paths must start with `/` and must not start with `//`
  *   or `/\` (which browsers interpret as protocol-relative URLs that
  *   escape your origin).
- * - Backslashes, control characters, and `CR`/`LF` are rejected to
- *   stop response-splitting and homograph tricks.
+ * - Backslashes, encoded backslashes, control characters, and `CR`/`LF`
+ *   are rejected to stop response-splitting and homograph tricks.
+ *   Percent-encoded protocol-relative path prefixes such as `/%2f%2f`
+ *   are also refused so downstream decoders cannot turn a same-origin
+ *   `Location` into an origin-escaping redirect.
  * - Absolute URLs are only allowed when their `origin` exactly matches
  *   one of the entries in `allowedOrigins`.
  * - `javascript:`, `data:`, `vbscript:`, and `file:` schemes are always

package/dist/safe-redirect.js

@@ -14,8 +14,11 @@
  * - Same-origin paths must start with `/` and must not start with `//`
  *   or `/\` (which browsers interpret as protocol-relative URLs that
  *   escape your origin).
- * - Backslashes, control characters, and `CR`/`LF` are rejected to
- *   stop response-splitting and homograph tricks.
+ * - Backslashes, encoded backslashes, control characters, and `CR`/`LF`
+ *   are rejected to stop response-splitting and homograph tricks.
+ *   Percent-encoded protocol-relative path prefixes such as `/%2f%2f`
+ *   are also refused so downstream decoders cannot turn a same-origin
+ *   `Location` into an origin-escaping redirect.
  * - Absolute URLs are only allowed when their `origin` exactly matches
  *   one of the entries in `allowedOrigins`.
  * - `javascript:`, `data:`, `vbscript:`, and `file:` schemes are always
@@ -79,6 +82,11 @@ function classify(target, allowedPaths, allowedOrigins) {
     // `/\evil.com` is interpreted by some browsers as protocol-relative too.
     if (target.startsWith("/\\"))
         return { ok: false, reason: "backslash-path" };
+    if (hasEncodedBackslash(target))
+        return { ok: false, reason: "backslash-path" };
+    if (hasEncodedProtocolRelativePrefix(target)) {
+        return { ok: false, reason: "protocol-relative" };
+    }
     if (target.startsWith("/")) {
         // Same-origin path. Backslashes anywhere in the path can confuse
         // user agents and proxies — refuse them outright.
@@ -113,6 +121,26 @@ function classify(target, allowedPaths, allowedOrigins) {
     }
     return { ok: true, location: parsed.toString() };
 }
+function hasEncodedBackslash(value) {
+    return /%5c/i.test(value);
+}
+function hasEncodedProtocolRelativePrefix(value) {
+    let raw = value;
+    for (let i = 0; i < 3; i++) {
+        if (/^\/%2f/i.test(raw))
+            return true;
+        try {
+            const decoded = decodeURIComponent(raw);
+            if (decoded === raw)
+                return false;
+            raw = decoded;
+        }
+        catch {
+            return false;
+        }
+    }
+    return raw.startsWith("//");
+}
 /**
  * Build a redirect `Response` after validating the target against an
  * explicit allowlist. Throws {@link OpenRedirectBlockedError} when the

package/dist/sbom.cdx.json

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:086b2383-b351-57fb-bd98-0fbf04f2342b",
+  "serialNumber": "urn:uuid:609085f8-6098-51c0-9dce-7717eb9fb590",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-22T21:07:28.471Z",
+    "timestamp": "2026-06-26T13:41:51.513Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "1.0.0-beta.2"
+        "version": "1.0.0-beta.4"
       }
     ],
     "authors": [
@@ -19,11 +19,11 @@
     ],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-beta.2",
+      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-beta.4",
       "name": "@daloyjs/core",
-      "version": "1.0.0-beta.2",
+      "version": "1.0.0-beta.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-beta.2",
+      "purl": "pkg:npm/@daloyjs/core@1.0.0-beta.4",
       "licenses": [
         {
           "license": {
@@ -46,9 +46,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-1.0.0-beta.2",
+        "tagId": "swidtag--daloyjs-core-1.0.0-beta.4",
         "name": "@daloyjs/core",
-        "version": "1.0.0-beta.2",
+        "version": "1.0.0-beta.4",
         "tagVersion": 0,
         "patch": false
       }
@@ -57,7 +57,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/@daloyjs/core@1.0.0-beta.2",
+      "ref": "pkg:npm/@daloyjs/core@1.0.0-beta.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-beta.2",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-beta.2-086b2383-b351-57fb-bd98-0fbf04f2342b",
+  "name": "@daloyjs/core-1.0.0-beta.4",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-beta.4-609085f8-6098-51c0-9dce-7717eb9fb590",
   "creationInfo": {
-    "created": "2026-06-22T21:07:28.471Z",
+    "created": "2026-06-26T13:41:51.513Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package--daloyjs-core",
       "name": "@daloyjs/core",
-      "versionInfo": "1.0.0-beta.2",
+      "versionInfo": "1.0.0-beta.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-beta.2"
+          "referenceLocator": "pkg:npm/@daloyjs/core@1.0.0-beta.4"
         }
       ]
     }

package/dist/streaming.d.ts

@@ -28,9 +28,15 @@
  *
  * For NDJSON, each yielded value is JSON-encoded and terminated with `\n`.
  */
-/** A single SSE event. `data` may be a string or any JSON-serializable value. */
+/**
+ * A single SSE event or control frame.
+ *
+ * `data` may be a string or any JSON-serializable value. It is optional so
+ * callers can emit valid comment-only or retry-only SSE frames for keep-alive
+ * and reconnection control without sending an event payload.
+ */
 export interface SSEMessage {
-    data: unknown;
+    data?: unknown;
     event?: string;
     id?: string;
     /** Reconnection delay in milliseconds. */

package/dist/types.d.ts

@@ -327,8 +327,8 @@ export interface RouteDefinition<P extends PathString = PathString, M extends Ht
      *
      * - implicitly treats the route as {@link RouteDefinition.deprecated}
      *   (the OpenAPI operation is emitted with `deprecated: true`);
-     * - emits a `Deprecation: true` response header (RFC 8594 / the
-     *   `Deprecation` HTTP header field) on every response from the route; and
+     * - emits a `Deprecation: true` response header on every response from the
+     *   route; and
      * - emits a `Sunset: <IMF-fixdate>` response header normalized to an HTTP
      *   date so clients and gateways can schedule migration.
      *
@@ -422,7 +422,32 @@ export interface RouteDefinition<P extends PathString = PathString, M extends Ht
      */
     meta?: RouteMeta;
     hooks?: Hooks;
-    handler: (ctx: BaseContext<P, Req>) => HandlerReturn<Res> | Promise<HandlerReturn<Res>>;
+    /**
+     * The route handler. Receives the typed, validated {@link BaseContext} and
+     * returns either:
+     *
+     * - a structured result `{ status, body, headers? }` whose `body` is
+     *   validated against the route's response schema and typed end-to-end into
+     *   the OpenAPI document and generated client (the common case), or
+     * - a raw web-standard {@link Response} as an escape hatch for streaming,
+     *   proxying, or pre-built bodies (for example an AI SDK
+     *   `result.toUIMessageStreamResponse()`, or an upstream `fetch()` response
+     *   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,
+     * 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
+     * headers (`server`, `x-powered-by`) are stripped, and a `HEAD` request still
+     * yields an empty body. This mirrors the existing `beforeHandle` `Response`
+     * passthrough. Prefer the structured result whenever a schema can describe
+     * the payload; reach for `Response` only when it genuinely cannot.
+     *
+     * @since 0.1.0
+     */
+    handler: (ctx: BaseContext<P, Req>) => HandlerReturn<Res> | Response | Promise<HandlerReturn<Res> | Response>;
 }
 /**
  * One operation inside an OpenAPI Callback Object. Mirrors a route minus

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daloyjs/core",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.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": {