@daloyjs/core 0.38.0 → 0.38.1

package/README.md

@@ -15,6 +15,7 @@
 [![Publish](https://github.com/daloyjs/daloy/actions/workflows/release.yml/badge.svg)](https://github.com/daloyjs/daloy/actions/workflows/release.yml)
 [![Zizmor](https://github.com/daloyjs/daloy/actions/workflows/zizmor.yml/badge.svg?branch=main)](https://github.com/daloyjs/daloy/actions/workflows/zizmor.yml)
 [![GitHub last commit](https://img.shields.io/github/last-commit/daloyjs/daloy)](https://github.com/daloyjs/daloy/commits/main)
+[![npm version](https://img.shields.io/npm/v/@daloyjs/core)](https://www.npmjs.com/package/@daloyjs/core)
 [![JSR](https://jsr.io/badges/@daloyjs/daloy)](https://jsr.io/@daloyjs/daloy)
 [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13058/badge)](https://www.bestpractices.dev/projects/13058)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/daloyjs/daloy/badge)](https://securityscorecards.dev/viewer/?uri=github.com/daloyjs/daloy)
@@ -38,6 +39,7 @@ DaloyJS exists to be the framework you'd build if you took the best ideas from e
 | Mature **Swagger / docs / ops** in Node                    | [Fastify](https://fastify.dev/docs/latest/Reference/)                 | Encapsulated plugins, structured logger, graceful shutdown, request ids, and lifecycle hooks — all first-party.       |
 | Modern **TS-first DX**, Bun acceptable                     | [Elysia](https://elysiajs.com/at-glance.html)                         | End-to-end typed handlers, typed context, and a typed in-process client — no codegen step required.                   |
 | Best-in-class **typed client codegen** for any consumer    | [Hey API](https://heyapi.dev/openapi-ts/get-started)                  | One `pnpm gen` command emits a fully-typed fetch SDK from your live OpenAPI spec.                                     |
+| **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.    |
@@ -61,6 +63,7 @@ Each existing stack is excellent at one thing and forces tradeoffs everywhere el
 - Fastify has the best Node ops story but is Node-only and validation/types/docs are not unified.
 - FastAPI has the best docs ergonomics — but it's Python.
 - Hey API gives you the best typed client — but you still need a server that produces a clean spec.
+- ts-rest gives lovely end-to-end types from a shared contract — but it rides on top of another server (Express/Fastify/Nest/Next), its safety is TypeScript-only, and OpenAPI and security are bring-your-own.
 - npm leaves supply-chain protection up to you.
 
 DaloyJS combines the wins:
@@ -339,6 +342,33 @@ deployment.
 
 ---
 
+## Authentication, OAuth2 & OpenID Connect
+
+DaloyJS is a **resource server** (and a toolkit for building a relying party),
+**not** an identity provider. Like Hono, Express, Fastify, or ASP.NET Core, it
+*verifies* and *enforces* tokens on each request — it does **not** ship a login
+UI, a user database, or an OAuth2 authorization server. It is **not** an
+"IdentityServer": it cannot, on its own, do what Duende IdentityServer,
+Keycloak, or Auth0 do (run login pages, manage clients/consent, mint tokens).
+
+To add login you bring an **OpenID Connect provider**. It does not have to be
+Auth0/Okta/Clerk specifically — any standards-compliant IdP works, including
+managed (Auth0, Okta, Clerk, Microsoft Entra ID, AWS Cognito) and **self-hosted
+open source** (Keycloak, Zitadel, Ory, Authentik, Logto, SuperTokens, Dex).
+Don't build your own authorization server — verify tokens from a vetted one.
+
+- **API as a resource server (default):** verify JWTs with `jwk()` against the
+  provider's JWKS (asymmetric-only algorithm allowlist, `issuer`/`audience`
+  enforced), then authorize per route with `requireScopes()`.
+- **Browser app:** use the back-end-for-frontend (BFF) pattern — run the
+  authorization-code + PKCE flow server-side, keep tokens in a `session()`
+  cookie (never in JavaScript), and protect mutations with `csrf()`.
+
+Read [Auth architecture: where DaloyJS fits in OAuth2 & OpenID Connect](https://daloyjs.dev/docs/auth/architecture)
+for the full picture, plus the per-provider guides under [`/docs/auth`](https://daloyjs.dev/docs/auth).
+
+---
+
 ## Performance
 
 ```text
@@ -429,6 +459,7 @@ The core only ever sees `Request → Response`. Adapters live at the edge.
 - Hono — portable web-standard router: <https://hono.dev/docs/>
 - Elysia — TS-first DX & typed context: <https://elysiajs.com/at-glance.html>
 - Fastify — production Node web framework: <https://fastify.dev/docs/latest/Reference/>
+- ts-rest — contract-first, RPC-like client/server over REST: <https://ts-rest.com/>
 - pnpm — strict, secure, content-addressable package manager: <https://pnpm.io/motivation>
 - Standard Schema — universal validator interface: <https://github.com/standard-schema/standard-schema>
 - RFC 9457 — Problem Details for HTTP APIs: <https://www.rfc-editor.org/rfc/rfc9457>

package/dist/app.js

@@ -351,7 +351,8 @@ export class App {
                 "If you really need this in production, also pass " +
                 "acknowledgeInsecureDefaults: true to confirm. Prefer per-feature opt-outs " +
                 "(secureHeaders: false, corsCrossOriginGuard: false, crashOnUnhandledRejection: false, " +
-                "trustProxy: false, csrf: \"off\") instead.");
+                "trustProxy: false, csrf: \"off\") instead. " +
+                "See https://daloyjs.dev/docs/security/secure-defaults-enforcement.");
         }
         if (!insecureDefaultsLoggedThisProcess) {
             insecureDefaultsLoggedThisProcess = true;
@@ -666,8 +667,11 @@ export class App {
             return;
         const err = new Error(`session() is registered in the hook chain for a state-changing route ` +
             `(${stateChanging.method} ${stateChanging.path}) but no csrf() hook is installed. ` +
+            `Without CSRF protection a browser can be tricked into making authenticated ` +
+            `state-changing requests cross-site. ` +
             `Register csrf() via app.use(csrf({ strategy: "fetch-metadata", allowedOrigins: [...] })), ` +
-            `or pass app({ csrf: "off" }) to acknowledge that this app is not browser-facing.`);
+            `or pass app({ csrf: "off" }) to acknowledge that this app is not browser-facing. ` +
+            `See https://daloyjs.dev/docs/security/boot-guards.`);
         this.bootGuard.error = err;
         throw err;
     }
@@ -717,9 +721,12 @@ export class App {
             this.log.warn({ event: "trust-proxy.unconfigured", header: found }, `Request carried ${found} but app({ trustProxy }) is unset; refusing to honour spoofable proxy headers.`);
         }
         throw new InternalError(`Refusing to dispatch request: ${found} header is present but app({ trustProxy }) is unconfigured. ` +
+            `Honouring a spoofable forwarded header would let a client forge its source IP for the rate ` +
+            `limiter, audit log, and request-id propagation. ` +
             `Pass app({ trustProxy: true }) when running behind a trusted reverse proxy, ` +
             `or app({ trustProxy: false }) to ignore forwarded headers, ` +
-            `or app({ secureDefaults: false }) to disable this guard.`);
+            `or app({ secureDefaults: false }) to disable this guard. ` +
+            `See https://daloyjs.dev/docs/security/boot-guards.`);
     }
     /**
      * Resolve the {@link AppOptions.docs} option and, when enabled, register

package/dist/jwt.js

@@ -236,7 +236,10 @@ export function createJwtSigner(opts) {
     }
     const { alg } = opts;
     if (alg === "none") {
-        throw new JwtError("alg_none_refused", 'jwt(): alg "none" is refused.');
+        throw new JwtError("alg_none_refused", 'jwt(): alg "none" is refused — it disables signature verification, so anyone could forge a ' +
+            'token by setting the header alg to "none" (the classic JWT signature-stripping / algorithm-' +
+            "confusion attack). Choose a real signing algorithm such as HS256 (shared secret) or " +
+            "RS256 / ES256 (key pair). See https://daloyjs.dev/docs/security/secure-defaults-enforcement.");
     }
     if (!ALL_ALGS.has(alg)) {
         throw new JwtError("invalid_alg", `jwt(): unknown algorithm "${String(alg)}". Allowed: ${[...ALL_ALGS].sort().join(", ")}.`);
@@ -335,7 +338,10 @@ export function createJwtVerifier(opts) {
     const allow = new Set();
     for (const alg of opts.algorithms) {
         if (alg === "none") {
-            throw new JwtError("alg_none_refused", 'jwt(): alg "none" cannot appear in the allowlist.');
+            throw new JwtError("alg_none_refused", 'jwt(): alg "none" cannot appear in the algorithms allowlist — it disables signature ' +
+                "verification and would let any caller forge a token. Remove it and list only real " +
+                "algorithms such as HS256, RS256, or ES256. " +
+                "See https://daloyjs.dev/docs/security/secure-defaults-enforcement.");
         }
         if (!ALL_ALGS.has(alg)) {
             throw new JwtError("invalid_alg", `jwt(): unknown algorithm "${String(alg)}" in allowlist.`);

package/dist/sbom.cdx.json

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:c230d67e-08ae-5162-959c-66cbbb24366a",
+  "serialNumber": "urn:uuid:51e4c48d-6a2e-5180-8452-1c9b9a5987d9",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-10T11:58:42.238Z",
+    "timestamp": "2026-06-11T09:54:26.041Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "0.38.0"
+        "version": "0.38.1"
       }
     ],
     "authors": [
@@ -19,11 +19,11 @@
     ],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/@daloyjs/core@0.38.0",
+      "bom-ref": "pkg:npm/@daloyjs/core@0.38.1",
       "name": "@daloyjs/core",
-      "version": "0.38.0",
+      "version": "0.38.1",
       "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@0.38.0",
+      "purl": "pkg:npm/@daloyjs/core@0.38.1",
       "licenses": [
         {
           "license": {
@@ -46,9 +46,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-0.38.0",
+        "tagId": "swidtag--daloyjs-core-0.38.1",
         "name": "@daloyjs/core",
-        "version": "0.38.0",
+        "version": "0.38.1",
         "tagVersion": 0,
         "patch": false
       }
@@ -57,7 +57,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/@daloyjs/core@0.38.0",
+      "ref": "pkg:npm/@daloyjs/core@0.38.1",
       "dependsOn": []
     }
   ]

package/dist/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@daloyjs/core-0.38.0",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-0.38.0-c230d67e-08ae-5162-959c-66cbbb24366a",
+  "name": "@daloyjs/core-0.38.1",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-0.38.1-51e4c48d-6a2e-5180-8452-1c9b9a5987d9",
   "creationInfo": {
-    "created": "2026-06-10T11:58:42.238Z",
+    "created": "2026-06-11T09:54:26.041Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package--daloyjs-core",
       "name": "@daloyjs/core",
-      "versionInfo": "0.38.0",
+      "versionInfo": "0.38.1",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/@daloyjs/core@0.38.0"
+          "referenceLocator": "pkg:npm/@daloyjs/core@0.38.1"
         }
       ]
     }

package/dist/session.js

@@ -57,7 +57,10 @@ function bytesToBase64Url(bytes) {
 }
 function makeSigner(secret) {
     if (typeof secret !== "string" || secret.length < 16) {
-        throw new Error("session(): each secret must be a string of at least 16 characters.");
+        throw new Error("session(): each secret must be a string of at least 16 characters — it is the HMAC key " +
+            "that signs every session cookie, so a short or guessable value lets an attacker forge sessions. " +
+            "Generate one with `openssl rand -base64 32` and load it from an env var or secret manager " +
+            "(never hard-code or commit it). See https://daloyjs.dev/docs/security/session.");
     }
     let keyPromise = null;
     const getKey = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daloyjs/core",
-  "version": "0.38.0",
+  "version": "0.38.1",
   "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": {