@daloyjs/core 1.0.0-beta.3 → 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.3`). 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/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);

package/dist/sbom.cdx.json

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:6e9958fe-26f1-5084-94ea-5ff9bfb68412",
+  "serialNumber": "urn:uuid:609085f8-6098-51c0-9dce-7717eb9fb590",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-24T05:34:04.875Z",
+    "timestamp": "2026-06-26T13:41:51.513Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "1.0.0-beta.3"
+        "version": "1.0.0-beta.4"
       }
     ],
     "authors": [
@@ -19,11 +19,11 @@
     ],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-beta.3",
+      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-beta.4",
       "name": "@daloyjs/core",
-      "version": "1.0.0-beta.3",
+      "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.3",
+      "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.3",
+        "tagId": "swidtag--daloyjs-core-1.0.0-beta.4",
         "name": "@daloyjs/core",
-        "version": "1.0.0-beta.3",
+        "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.3",
+      "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.3",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-beta.3-6e9958fe-26f1-5084-94ea-5ff9bfb68412",
+  "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-24T05:34:04.875Z",
+    "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.3",
+      "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.3"
+          "referenceLocator": "pkg:npm/@daloyjs/core@1.0.0-beta.4"
         }
       ]
     }

package/dist/types.d.ts

@@ -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.3",
+  "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": {