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

package/dist/jwk.d.ts

@@ -1,5 +1,5 @@
 import { type JwtAlgorithm } from "./jwt.js";
-import type { BaseContext, Hooks } from "./types.js";
+import type { Hooks, PreBodyContext } from "./types.js";
 /** Asymmetric algorithms accepted by {@link jwk}. */
 export type JwkAlgorithm = Exclude<JwtAlgorithm, "HS256" | "HS384" | "HS512">;
 /** Minimal JWKS document shape (RFC 7517 §5). */
@@ -12,8 +12,12 @@ export interface JwkSet {
  * `https://` URL (fetched with TTL caching), or a custom async resolver.
  */
 export type JwkSource = JwkSet | string | (() => JwkSet | Promise<JwkSet>);
-/** Per-request payload-revalidation hook. */
-export type JwkVerifyHook = (payload: Record<string, unknown>, ctx: BaseContext<any, any>) => boolean | void | Promise<boolean | void>;
+/**
+ * Per-request payload-revalidation hook run before request-body I/O.
+ * The supplied {@link PreBodyContext} exposes raw headers/query/params and an
+ * always-`undefined` body.
+ */
+export type JwkVerifyHook = (payload: Record<string, unknown>, ctx: PreBodyContext<any>) => boolean | void | Promise<boolean | void>;
 /**
  * Options for {@link jwk}: the JWKS source and asymmetric algorithm allowlist
  * are required; issuer / audience / clock-skew checks, JWKS fetch caching,
@@ -61,10 +65,10 @@ export interface JwkOptions {
      */
     fetch?: typeof fetch;
     /**
-    * Optional per-request revalidation hook. Returning `false` rejects the
-    * request with `403`; returning `true` or `undefined` accepts. Use for
-    * revocation lists / token-version counters / "user changed password since
-    * this JWT was issued".
+     * Optional per-request revalidation hook. Returning `false` rejects the
+     * request with `403`; returning `true` or `undefined` accepts. Use for
+     * revocation lists / token-version counters / "user changed password since
+     * this JWT was issued". Runs before request-body I/O.
      *
      * @since 0.22.0
      */

package/dist/jwk.js

@@ -30,9 +30,15 @@
 import { ForbiddenError } from "./errors.js";
 import { createJwtVerifier, JwtError, } from "./jwt.js";
 const ALLOWED_JWK_ALGS = new Set([
-    "RS256", "RS384", "RS512",
-    "PS256", "PS384", "PS512",
-    "ES256", "ES384", "ES512",
+    "RS256",
+    "RS384",
+    "RS512",
+    "PS256",
+    "PS384",
+    "PS512",
+    "ES256",
+    "ES384",
+    "ES512",
     "EdDSA",
 ]);
 function unauthorized(realm, errorCode, description) {
@@ -59,9 +65,7 @@ function sanitizeAuthParam(value) {
     return value.replace(/[\u0000-\u001f\u007f"\\]/g, "");
 }
 function isJwkSet(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        Array.isArray(value.keys));
+    return (typeof value === "object" && value !== null && Array.isArray(value.keys));
 }
 function findJwkByKid(jwks, kid) {
     for (const k of jwks.keys) {
@@ -236,7 +240,7 @@ export function jwk(opts) {
         return cachedVerifier;
     }
     const authHooks = {
-        async beforeHandle(ctx) {
+        async preBody(ctx) {
             const header = ctx.request.headers.get("authorization") ?? "";
             const match = /^Bearer\s+(.+)$/i.exec(header);
             if (!match) {

package/dist/logger.d.ts

@@ -133,4 +133,49 @@ export declare function createLogger(opts?: ConsoleLoggerOptions): Logger;
  * @since 0.1.0
  */
 export declare const noopLogger: Logger;
+/**
+ * Query parameter names whose values are redacted when a request URL is
+ * bound into a log record. Case-insensitive. Covers OAuth redirect params,
+ * API keys in query strings, signed-URL tokens, session identifiers, and the
+ * exact-named parameters of AWS SigV4 / GCS V4 presigned URLs (the `x-amz-*`
+ * and `x-goog-*` families are additionally matched by prefix — see
+ * {@link SENSITIVE_URL_QUERY_KEY_PREFIXES}).
+ *
+ * @since 1.0.0
+ */
+export declare const SENSITIVE_URL_QUERY_KEYS: readonly string[];
+/**
+ * Case-insensitive query-key prefixes whose values are always redacted in a
+ * logged URL. Covers the full AWS SigV4 (`X-Amz-*`) and GCS V4 (`X-Goog-*`)
+ * presigned-URL parameter families so a signature never leaks even if a
+ * provider adds a new signed parameter name. Redacting the non-secret members
+ * of the bundle (`X-Amz-Date`, `X-Amz-Expires`, …) is harmless in a log line.
+ *
+ * @since 1.0.0
+ */
+export declare const SENSITIVE_URL_QUERY_KEY_PREFIXES: readonly string[];
+/**
+ * Produce a log-safe form of a request URL.
+ *
+ * Keeps scheme, host, and path for operability. Redacts values of
+ * {@link SENSITIVE_URL_QUERY_KEYS} / {@link SENSITIVE_URL_QUERY_KEY_PREFIXES}
+ * (and JWT-like / credential-like query values) so OAuth `?code=`,
+ * `?access_token=`, and presigned-URL signatures (`?X-Amz-Signature=`,
+ * `?X-Goog-Signature=`) never land in durable error logs under the field name
+ * `url` (which the structured redactor does not rename-match).
+ *
+ * Malformed URLs fall back to the path-only prefix before `?` / `#`.
+ *
+ * This runs once per request on the logging path, so it fast-paths the common
+ * case: a URL with no query, no fragment, and no userinfo (`@`) delimiter is
+ * already log-safe and is returned verbatim without the WHATWG URL parse (about
+ * an order of magnitude cheaper). The `@` guard preserves userinfo stripping
+ * for the rare inputs that carry credentials in the authority — `request.url`
+ * itself never does, but this is a public utility.
+ *
+ * @param url - Absolute or relative request URL (typically `request.url`).
+ * @returns A string safe to attach as a logger binding.
+ * @since 1.0.0
+ */
+export declare function sanitizeUrlForLog(url: string): string;
 export {};

package/dist/logger.js

@@ -34,6 +34,17 @@ export const DEFAULT_REDACT_KEYS = Object.freeze([
     "refresh_token",
     "id_token",
     "client_secret",
+    // A structured field literally named `private_key` is always a secret and
+    // has a negligible false-positive rate as a log-field name (mirrors the
+    // existing `client_secret`). The broader OAuth/session query-string names
+    // (`code`, `state`, `id`, `key`, `sid`, `session`, `signature`, `sig`,
+    // `auth`, …) are DELIBERATELY NOT here: those are extremely common,
+    // non-secret structured field names (record ids, sort keys, UI state) and
+    // redacting them at every depth would corrupt normal operational logs.
+    // Secrets that ride in a *URL query string* are handled instead by
+    // {@link sanitizeUrlForLog} / {@link SENSITIVE_URL_QUERY_KEYS}, which only
+    // applies to the `url` field where the query context makes them sensitive.
+    "private_key",
     // AI / LLM provider credential headers and body fields. Added in response
     // to the LiteLLM 2026 "AI blast radius" incident class (Snyk 2026,
     // CVE-2026-42208 + CVE-2026-33634) — an AI gateway that brokers prompts
@@ -265,3 +276,129 @@ export const noopLogger = {
         return noopLogger;
     },
 };
+/**
+ * Query parameter names whose values are redacted when a request URL is
+ * bound into a log record. Case-insensitive. Covers OAuth redirect params,
+ * API keys in query strings, signed-URL tokens, session identifiers, and the
+ * exact-named parameters of AWS SigV4 / GCS V4 presigned URLs (the `x-amz-*`
+ * and `x-goog-*` families are additionally matched by prefix — see
+ * {@link SENSITIVE_URL_QUERY_KEY_PREFIXES}).
+ *
+ * @since 1.0.0
+ */
+export const SENSITIVE_URL_QUERY_KEYS = Object.freeze([
+    "authorization",
+    "access_token",
+    "refresh_token",
+    "id_token",
+    "token",
+    "api_key",
+    "apikey",
+    "api-key",
+    "key",
+    "password",
+    "passwd",
+    "secret",
+    "client_secret",
+    "code",
+    "state",
+    "session_state",
+    "session",
+    "sid",
+    "signature",
+    "sig",
+    "auth",
+    "private_key",
+    "x-api-key",
+    // AWS SigV4 presigned URL parameters. `X-Amz-Signature` is the secret; the
+    // credential (embeds the access-key id) and session token are equally
+    // sensitive. Also covered by the `x-amz-` prefix below.
+    "x-amz-signature",
+    "x-amz-credential",
+    "x-amz-security-token",
+    // Google Cloud Storage V4 signed URL parameters. Also covered by `x-goog-`.
+    "x-goog-signature",
+    "x-goog-credential",
+    "googleaccessid",
+]);
+/**
+ * Case-insensitive query-key prefixes whose values are always redacted in a
+ * logged URL. Covers the full AWS SigV4 (`X-Amz-*`) and GCS V4 (`X-Goog-*`)
+ * presigned-URL parameter families so a signature never leaks even if a
+ * provider adds a new signed parameter name. Redacting the non-secret members
+ * of the bundle (`X-Amz-Date`, `X-Amz-Expires`, …) is harmless in a log line.
+ *
+ * @since 1.0.0
+ */
+export const SENSITIVE_URL_QUERY_KEY_PREFIXES = Object.freeze([
+    "x-amz-",
+    "x-goog-",
+]);
+const SENSITIVE_URL_QUERY_KEY_SET = new Set(SENSITIVE_URL_QUERY_KEYS.map((k) => k.toLowerCase()));
+/**
+ * Whether a URL query-parameter name is treated as secret-bearing when a
+ * request URL is bound into a log record. True when the lower-cased name is in
+ * {@link SENSITIVE_URL_QUERY_KEYS} or starts with a
+ * {@link SENSITIVE_URL_QUERY_KEY_PREFIXES} entry.
+ *
+ * @param lowerKey - Already-lower-cased query-parameter name.
+ * @returns `true` if the value should be redacted.
+ */
+function isSensitiveUrlQueryKey(lowerKey) {
+    if (SENSITIVE_URL_QUERY_KEY_SET.has(lowerKey))
+        return true;
+    for (const prefix of SENSITIVE_URL_QUERY_KEY_PREFIXES) {
+        if (lowerKey.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * Produce a log-safe form of a request URL.
+ *
+ * Keeps scheme, host, and path for operability. Redacts values of
+ * {@link SENSITIVE_URL_QUERY_KEYS} / {@link SENSITIVE_URL_QUERY_KEY_PREFIXES}
+ * (and JWT-like / credential-like query values) so OAuth `?code=`,
+ * `?access_token=`, and presigned-URL signatures (`?X-Amz-Signature=`,
+ * `?X-Goog-Signature=`) never land in durable error logs under the field name
+ * `url` (which the structured redactor does not rename-match).
+ *
+ * Malformed URLs fall back to the path-only prefix before `?` / `#`.
+ *
+ * This runs once per request on the logging path, so it fast-paths the common
+ * case: a URL with no query, no fragment, and no userinfo (`@`) delimiter is
+ * already log-safe and is returned verbatim without the WHATWG URL parse (about
+ * an order of magnitude cheaper). The `@` guard preserves userinfo stripping
+ * for the rare inputs that carry credentials in the authority — `request.url`
+ * itself never does, but this is a public utility.
+ *
+ * @param url - Absolute or relative request URL (typically `request.url`).
+ * @returns A string safe to attach as a logger binding.
+ * @since 1.0.0
+ */
+export function sanitizeUrlForLog(url) {
+    if (url.indexOf("?") === -1 &&
+        url.indexOf("#") === -1 &&
+        url.indexOf("@") === -1) {
+        return url;
+    }
+    try {
+        const parsed = new URL(url);
+        if (parsed.search === "" && parsed.hash === "") {
+            return `${parsed.origin}${parsed.pathname}`;
+        }
+        const safe = new URL(parsed.origin + parsed.pathname);
+        for (const [key, value] of parsed.searchParams) {
+            const lower = key.toLowerCase();
+            const sensitiveKey = isSensitiveUrlQueryKey(lower);
+            const sensitiveValue = JWT_LIKE_RE.test(value) || CREDENTIAL_LIKE_RE.test(value);
+            CREDENTIAL_LIKE_RE.lastIndex = 0;
+            safe.searchParams.append(key, sensitiveKey || sensitiveValue ? "[REDACTED]" : value);
+        }
+        return safe.toString();
+    }
+    catch {
+        const cut = url.search(/[?#]/);
+        return cut === -1 ? url : url.slice(0, cut);
+    }
+}

package/dist/mcp.js

@@ -1,4 +1,4 @@
-import { safeJsonParse } from "./security.js";
+import { safeJsonParseLimited } from "./security.js";
 /**
  * Latest MCP protocol version DaloyJS negotiates by default.
  *
@@ -355,10 +355,16 @@ function compileUriTemplate(template) {
 const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
 /**
  * Streamable HTTP DNS-rebinding defense: decide whether a browser `Origin`
- * may talk to this MCP endpoint. Same-origin and loopback origins are always
- * allowed; anything else must be explicitly allowlisted.
+ * may talk to this MCP endpoint.
+ *
+ * Loopback origins (`localhost` / `127.0.0.1` / `[::1]` / `*.localhost`) are
+ * allowed for local development. Every non-loopback origin must appear in
+ * the configured allowlist. We deliberately do **not** treat
+ * `Origin.host === request Host` as sufficient: under DNS rebinding both
+ * can be the attacker hostname resolving to the target IP, which would
+ * silently bypass an implicit same-origin check.
  */
-function isAllowedOrigin(origin, request, allowlist) {
+function isAllowedOrigin(origin, _request, allowlist) {
     const normalized = origin.toLowerCase();
     if (allowlist.has(normalized))
         return true;
@@ -374,12 +380,7 @@ function isAllowedOrigin(origin, request, allowlist) {
     const hostname = parsed.hostname;
     if (LOOPBACK_HOSTNAMES.has(hostname) || hostname.endsWith(".localhost"))
         return true;
-    try {
-        return parsed.host === new URL(request.url).host;
-    }
-    catch {
-        return false;
-    }
+    return false;
 }
 /**
  * Create a dependency-free MCP Streamable HTTP endpoint handler.
@@ -693,11 +694,10 @@ export function createMcpHandler(options) {
         }
         let message;
         try {
-            // `safeJsonParse` strips `__proto__` / `constructor` / `prototype` keys so
-            // an untrusted MCP client cannot smuggle prototype-pollution-shaped keys
-            // into a tool handler's arguments — matching the REST body parsers'
-            // secure-by-default posture (see `safeJsonParse` in security.ts).
-            message = safeJsonParse(raw);
+            // Use the limited parser (proto stripping + key/depth bounds) so an
+            // untrusted MCP client cannot DoS us with wide or deeply-nested JSON-RPC
+            // payloads, even within the MCP body cap. Matches the REST body parsers.
+            message = safeJsonParseLimited(raw);
         }
         catch {
             return rpcError(null, PARSE_ERROR, "Invalid JSON in request body.", undefined, 400, headers);
@@ -789,6 +789,10 @@ export function mcpRoutes(path, handler, options = {}) {
             path,
             operationId: "mcpPost",
             summary: "MCP Streamable HTTP endpoint",
+            // The transport handler owns JSON-RPC serialization and may also emit
+            // empty/streaming responses, so its web-standard Response is
+            // intentionally opaque to Daloy's response serializer.
+            acknowledgeNoResponseBodySchema: true,
             responses,
             handler: ({ request }) => handler(request),
         },
@@ -797,6 +801,7 @@ export function mcpRoutes(path, handler, options = {}) {
             path,
             operationId: "mcpGet",
             summary: "MCP Streamable HTTP discovery hint",
+            acknowledgeNoResponseBodySchema: true,
             responses,
             handler: ({ request }) => handler(request),
         },
@@ -805,6 +810,7 @@ export function mcpRoutes(path, handler, options = {}) {
             path,
             operationId: "mcpOptions",
             summary: "MCP Streamable HTTP preflight",
+            acknowledgeNoResponseBodySchema: true,
             responses,
             handler: ({ request }) => handler(request),
         },

package/dist/middleware.d.ts

@@ -4,7 +4,7 @@
  * All middlewares return `Hooks` objects so they compose with `app.use(...)`,
  * groups, and per-route hooks identically.
  */
-import type { Hooks, BaseContext } from "./types.js";
+import type { Hooks, BaseContext, PreBodyContext } from "./types.js";
 import { timingSafeEqual } from "./security.js";
 /** Options for {@link requestId}. */
 export interface RequestIdOptions {
@@ -327,6 +327,23 @@ export declare const CSRF_HOOK_MARKER: unique symbol;
  * @since 1.0.0
  */
 export declare const AUTH_HOOK_MARKER: unique symbol;
+/**
+ * Internal list of request-budget hooks that must run when a later `preBody`
+ * guard rejects. This preserves registration order for `rateLimit()` before
+ * authentication without moving body-aware middleware ahead of validation.
+ *
+ * @internal
+ */
+export declare const EARLY_REJECTION_HOOK_MARKER: unique symbol;
+/**
+ * Compose `preBody` hooks while honoring request-budget hooks registered
+ * before the guard that rejects. Used internally by App and hook combinators.
+ *
+ * @param layers - Hook layers in registration order.
+ * @returns A composed `preBody` hook, or `undefined` when no layer has one.
+ * @internal
+ */
+export declare function _mergePreBodyWithEarlyRejections(layers: Hooks[]): NonNullable<Hooks["preBody"]> | undefined;
 /**
  * Mark a custom {@link Hooks} bundle as performing request authentication.
  *
@@ -343,7 +360,7 @@ export declare const AUTH_HOOK_MARKER: unique symbol;
  * @example
  * ```ts
  * app.use(markAuthHook({
- *   async beforeHandle(ctx) {
+ *   async preBody(ctx) {
  *     if (!(await myVerify(ctx.request))) throw new UnauthorizedError();
  *   },
  * }));
@@ -426,14 +443,27 @@ export interface RateLimitStore {
         resetMs: number;
     }>;
 }
+/**
+ * Context accepted by rate-limit key generators. It is validated on the
+ * ordinary path, but may be a pre-body context when a limiter registered
+ * before authentication counts an early credential rejection.
+ *
+ * @since 1.0.0
+ */
+export type RateLimitContext = PreBodyContext<any> | BaseContext<any, any>;
 /** Options for {@link rateLimit}. */
 export interface RateLimitOptions {
     /** Rolling-window width in milliseconds (e.g. `60_000` for one minute). */
     windowMs: number;
     /** Maximum allowed requests per `windowMs` per key. */
     max: number;
-    /** Derive the bucket key from `ctx`. Default returns `"global"`. */
-    keyGenerator?: (ctx: BaseContext<any, any>) => string;
+    /**
+     * Derive the bucket key from `ctx`. Default returns `"global"`. When the
+     * limiter precedes `preBody` authentication, it also receives failed
+     * attempts before body I/O; rely only on the raw request and state populated
+     * by earlier `preBody` hooks.
+     */
+    keyGenerator?: (ctx: RateLimitContext) => string;
     /** Custom backend (default: shared in-memory store). */
     store?: RateLimitStore;
     /**
@@ -483,6 +513,11 @@ export declare function _resetSharedRateLimitStoresForTests(): void;
  * `X-Forwarded-For` / `X-Real-IP` when behind a trusted proxy, or supply a
  * custom `keyGenerator` (e.g. derive from the authenticated user id).
  *
+ * Registration order remains security-significant: a limiter placed before a
+ * `preBody` auth hook counts rejected credentials and can replace the later
+ * `401` with `429`, without consuming the request body. On ordinary accepted
+ * requests it retains the validated `beforeHandle` timing.
+ *
  * @example
  * ```ts
  * import { rateLimit } from "@daloyjs/core";
@@ -508,7 +543,7 @@ export interface LoginThrottleOptions {
     /** Shared bucket id. Default: `"login"`. */
     groupId?: string;
     /** Derive the caller key. Defaults to trusted proxy headers only when enabled. */
-    keyGenerator?: (ctx: BaseContext<any, any>) => string;
+    keyGenerator?: (ctx: RateLimitContext) => string;
     /** Shared store for the hard limit. Uses rateLimit()'s in-memory group bucket by default. */
     store?: RateLimitStore;
     /** Trust x-forwarded-for / x-real-ip when deriving the default key. Default: false. */
@@ -530,6 +565,8 @@ export interface LoginThrottleOptions {
  * Mount the same `loginThrottle()` instance (or multiple instances with the
  * same `groupId`) across related routes so an attacker cannot bypass the limit
  * by rotating between password, OTP, and reset endpoints.
+ * When registered before `preBody` authentication it counts and progressively
+ * delays rejected credentials without consuming a declared request body.
  *
  * @param opts - Throttle tuning (see {@link LoginThrottleOptions}); every field has a safe default.
  * @returns A {@link Hooks} bundle ready for `app.use(...)` or per-route `hooks`.
@@ -588,7 +625,7 @@ export declare function timing(headerName?: string): Hooks;
  *
  * @since 0.22.0
  */
-export type BearerAuthVerifyHook<TCredentials = string> = (credentials: TCredentials, ctx: BaseContext<any, any>) => boolean | void | Promise<boolean | void>;
+export type BearerAuthVerifyHook<TCredentials = string> = (credentials: TCredentials, ctx: PreBodyContext<any>) => boolean | void | Promise<boolean | void>;
 /** Options for {@link bearerAuth}. */
 export interface BearerAuthOptions {
     /** Cheap, stateless token check (signature / format). */
@@ -616,6 +653,8 @@ export interface BearerAuthOptions {
  * optional `verify` hook is the integration point for revocation
  * lists, token-version counters, and other per-request invalidation checks
  * that `validate` cannot answer statelessly.
+ * Both checks run before request-body I/O; `verify` receives a
+ * {@link PreBodyContext} whose `body` is always `undefined`.
  *
  * @example
  * ```ts
@@ -757,13 +796,15 @@ export interface BasicAuthOptions {
      * after the framework has stamped `ctx.state.user`. Use this to decorate
      * `ctx.state` with extra fields (typed via `AppState`) so handlers do not
      * re-parse the `Authorization` header in every route.
+     * Runs before request-body I/O with a {@link PreBodyContext}; `ctx.body` is
+     * always `undefined`.
      *
      * @since 0.22.0
      */
     onAuthSuccess?: (creds: {
         username: string;
         password: string;
-    }, ctx: BaseContext<any, any>) => void | Promise<void>;
+    }, ctx: PreBodyContext<any>) => void | Promise<void>;
 }
 /**
  * HTTP Basic Authentication middleware (RFC 7617).