@daloyjs/core 1.0.0-rc.0 → 1.0.0-rc.2

package/dist/jwk.js

@@ -235,7 +235,7 @@ export function jwk(opts) {
         });
         return cachedVerifier;
     }
-    return {
+    const authHooks = {
         async beforeHandle(ctx) {
             const header = ctx.request.headers.get("authorization") ?? "";
             const match = /^Bearer\s+(.+)$/i.exec(header);
@@ -268,6 +268,11 @@ export function jwk(opts) {
             return undefined;
         },
     };
+    // Same global symbol as middleware's AUTH_HOOK_MARKER (stamped inline to keep
+    // the middleware module out of jwk's bundle): lets the route-auth boot guard
+    // recognize that a route declaring `auth:` is actually enforced here.
+    authHooks[Symbol.for("daloyjs.auth.hook")] = true;
+    return authHooks;
 }
 function extractScopes(payload) {
     // RFC 8693 / OAuth2: `scope` is a space-delimited string; some IdPs emit

package/dist/mcp.d.ts

@@ -39,9 +39,16 @@ export type McpJsonObject = {
 };
 /**
  * JSON Schema fragment advertised to MCP clients for a tool or prompt
- * argument object. DaloyJS does not bundle a schema validator here, so the
- * schema is documentation and client-side guidance. Validate sensitive inputs
- * inside your handler before touching databases, files, or remote services.
+ * argument object.
+ *
+ * For a tool's `inputSchema`, DaloyJS enforces the commonly-used,
+ * security-relevant subset of JSON Schema server-side (see
+ * {@link validateMcpInput}) BEFORE the tool handler runs, rejecting a
+ * `tools/call` whose arguments violate it with JSON-RPC `-32602`. Keywords
+ * outside that subset (`pattern`, `format`, `$ref`,
+ * `anyOf`/`oneOf`/`allOf`, …) are advertised to clients but NOT enforced —
+ * validate any constraint expressed only through those keywords inside your
+ * handler before touching databases, files, or remote services.
  *
  * @since 1.0.0
  */
@@ -195,8 +202,11 @@ export interface McpToolAnnotations {
  * Handler for a single MCP tool.
  *
  * @typeParam TArgs - Type expected in `params.arguments` for this tool.
- * @param args - Tool arguments supplied by the MCP client. They are typed for
- *   developer experience but are still untrusted JSON at runtime.
+ * @param args - Tool arguments supplied by the MCP client. They have already
+ *   been validated against this tool's `inputSchema` (enforced subset — see
+ *   {@link validateMcpInput}) and had prototype-pollution keys stripped, so the
+ *   declared shape holds at runtime. Constraints expressed only through
+ *   unsupported schema keywords (e.g. `pattern`) remain the handler's job.
  * @param ctx - Request metadata and the original HTTP request.
  * @returns Text shorthand or a full {@link McpToolResult}.
  * @throws {McpToolError} for caller-correctable failures that should be
@@ -209,9 +219,11 @@ export type McpToolHandler<TArgs extends Record<string, unknown> = Record<string
  * Definition of a callable MCP tool.
  *
  * Tools are model-controlled in MCP: clients may let the language model decide
- * when to call them. Treat every tool as a public API operation and enforce
- * authentication, authorization, rate limits, and validation before side
- * effects.
+ * when to call them. Treat every tool as a public API operation. DaloyJS
+ * enforces the tool's `inputSchema` (enforced subset — see
+ * {@link validateMcpInput}) before the handler runs; you remain responsible for
+ * authentication, authorization, rate limits, and any validation beyond that
+ * subset before side effects.
  *
  * @typeParam TArgs - Type expected by this tool's handler.
  * @since 1.0.0
@@ -492,6 +504,31 @@ export interface McpHandlerOptions {
  * @since 1.0.0
  */
 export type McpHandler = (request: Request) => Promise<Response>;
+/**
+ * Minimal, dependency-free JSON Schema validator for MCP tool arguments.
+ *
+ * DaloyJS core bundles no third-party schema library, so this implements the
+ * commonly-used, security-relevant subset of JSON Schema — enough to reject the
+ * untrusted `tools/call` argument shapes that matter before a tool handler
+ * runs: wrong `type` (including `integer`), missing `required` properties,
+ * unexpected keys under `additionalProperties: false`, `enum`/`const`
+ * violations, and basic string/number/array bounds (`minLength`/`maxLength`,
+ * `minimum`/`maximum`, `minItems`/`maxItems`). Nested `properties`, `items`,
+ * and object-form `additionalProperties` are validated recursively.
+ *
+ * Keywords outside this subset (`pattern`, `format`, `$ref`,
+ * `anyOf`/`oneOf`/`allOf`, etc.) are intentionally NOT enforced — notably
+ * `pattern` is skipped so a developer-authored regex can never become a ReDoS
+ * sink against attacker-controlled input. Handlers must still validate any
+ * constraint expressed only through those keywords.
+ *
+ * @param schema - The tool's advertised `inputSchema`.
+ * @param value - The untrusted `params.arguments` value from the client.
+ * @returns A list of human-readable validation errors; empty when the value
+ *   satisfies the enforced subset of the schema.
+ * @since 1.0.0
+ */
+export declare function validateMcpInput(schema: McpJsonSchema, value: unknown): string[];
 /**
  * Create a dependency-free MCP Streamable HTTP endpoint handler.
  *
@@ -544,6 +581,25 @@ export type McpHandler = (request: Request) => Promise<Response>;
  * @since 1.0.0
  */
 export declare function createMcpHandler(options: McpHandlerOptions): McpHandler;
+/**
+ * Options for {@link mcpRoutes}.
+ *
+ * @since 1.0.0
+ */
+export interface McpRoutesOptions {
+    /**
+     * Set `true` to intentionally expose the MCP endpoint WITHOUT authentication,
+     * opting the `POST` transport out of the App's production route-auth boot
+     * guard. Only do this for a genuinely public MCP server — MCP tools are
+     * model-controlled and can trigger side effects, so an unauthenticated
+     * endpoint is a high-impact default. When left `false` (the default), a
+     * production `secureDefaults` App refuses to boot unless an authentication
+     * hook covers the MCP route.
+     *
+     * @defaultValue false
+     */
+    public?: boolean;
+}
 /**
  * Build the Daloy route definitions for a Streamable HTTP MCP endpoint.
  *
@@ -552,8 +608,16 @@ export declare function createMcpHandler(options: McpHandlerOptions): McpHandler
  * its public contract and auth policy, while the MCP server can use its own
  * bearer token, rate limit, network allowlist, and tool set.
  *
+ * By default the `POST` transport route is stamped so that a production
+ * `secureDefaults` App **refuses to boot** unless an authentication hook covers
+ * it — MCP tools are model-controlled and side-effecting. Cover the route with
+ * an auth middleware (e.g. `app.use(bearerAuth({ ... }))`), or pass
+ * `{ public: true }` to intentionally expose a public MCP server.
+ *
  * @param path - Public MCP endpoint path, usually `"/mcp"`.
  * @param handler - Handler returned by {@link createMcpHandler}.
+ * @param options - See {@link McpRoutesOptions}; pass `{ public: true }` to opt
+ *   out of the auth boot guard.
  * @returns Route definitions for `POST`, `GET`, and `OPTIONS` on the same
  *   path. `POST` is the actual MCP transport; `GET` gives a human-readable
  *   405 hint because this helper does not open server-initiated SSE streams;
@@ -564,11 +628,18 @@ export declare function createMcpHandler(options: McpHandlerOptions): McpHandler
  * const app = new App();
  * const mcp = createMcpHandler({ serverInfo, tools });
  *
+ * // Authenticated MCP server (satisfies the production boot guard):
+ * app.use(bearerAuth({ validate: (t) => timingSafeEqual(t, process.env.MCP_TOKEN!) }));
  * for (const route of mcpRoutes("/mcp", mcp)) {
  *   app.route(route);
  * }
+ *
+ * // ...or an intentionally public MCP server:
+ * for (const route of mcpRoutes("/mcp", mcp, { public: true })) {
+ *   app.route(route);
+ * }
  * ```
  *
  * @since 1.0.0
  */
-export declare function mcpRoutes(path: PathString, handler: McpHandler): RouteDefinition<PathString, "GET" | "POST" | "OPTIONS">[];
+export declare function mcpRoutes(path: PathString, handler: McpHandler, options?: McpRoutesOptions): RouteDefinition<PathString, "GET" | "POST" | "OPTIONS">[];

package/dist/mcp.js

@@ -1,3 +1,4 @@
+import { safeJsonParse } from "./security.js";
 /**
  * Latest MCP protocol version DaloyJS negotiates by default.
  *
@@ -125,6 +126,165 @@ function asRecord(value) {
         ? value
         : {};
 }
+/** Hard cap on reported validation errors so a hostile payload can't inflate the response. */
+const MAX_MCP_VALIDATION_ERRORS = 20;
+/** Recursion-depth cap so a deeply-nested payload can't exhaust the stack. */
+const MAX_MCP_SCHEMA_DEPTH = 64;
+/** Narrow an arbitrary JSON value to a schema object (`{}`), excluding arrays/null. */
+function isSchemaObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/** Report the JSON type of a value using JSON Schema's type names. */
+function jsonTypeOf(v) {
+    if (v === null)
+        return "null";
+    if (Array.isArray(v))
+        return "array";
+    return typeof v;
+}
+/** Test a value against a single JSON Schema `type` keyword. */
+function matchesJsonType(type, value) {
+    switch (type) {
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "string":
+            return typeof value === "string";
+        case "boolean":
+            return typeof value === "boolean";
+        case "null":
+            return value === null;
+        case "object":
+            return value !== null && typeof value === "object" && !Array.isArray(value);
+        case "array":
+            return Array.isArray(value);
+        default:
+            // Unknown type keyword — do not reject; treat as unconstrained.
+            return true;
+    }
+}
+/** Structural equality for `enum`/`const` comparison (sufficient for JSON scalars/objects). */
+function deepEqualJson(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/** Recursive worker for {@link validateMcpInput}. Pushes human-readable errors into `errors`. */
+function validateSchemaNode(schema, value, path, errors, depth) {
+    if (errors.length >= MAX_MCP_VALIDATION_ERRORS)
+        return;
+    if (depth > MAX_MCP_SCHEMA_DEPTH) {
+        errors.push(`${path}: exceeds maximum validation depth`);
+        return;
+    }
+    // type (string or array-of-strings). A type mismatch stops deeper,
+    // type-dependent checks for this node to avoid a cascade of noise.
+    const typeKw = schema.type;
+    if (typeof typeKw === "string") {
+        if (!matchesJsonType(typeKw, value)) {
+            errors.push(`${path}: expected ${typeKw}, got ${jsonTypeOf(value)}`);
+            return;
+        }
+    }
+    else if (Array.isArray(typeKw)) {
+        const types = typeKw.filter((t) => typeof t === "string");
+        if (types.length > 0 && !types.some((t) => matchesJsonType(t, value))) {
+            errors.push(`${path}: expected one of [${types.join(", ")}], got ${jsonTypeOf(value)}`);
+            return;
+        }
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.some((e) => deepEqualJson(e, value))) {
+        errors.push(`${path}: value is not one of the allowed enum values`);
+    }
+    if ("const" in schema && !deepEqualJson(schema.const, value)) {
+        errors.push(`${path}: value does not equal the required constant`);
+    }
+    if (typeof value === "string") {
+        if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+            errors.push(`${path}: string shorter than minLength ${schema.minLength}`);
+        }
+        if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
+            errors.push(`${path}: string longer than maxLength ${schema.maxLength}`);
+        }
+    }
+    if (typeof value === "number") {
+        if (typeof schema.minimum === "number" && value < schema.minimum) {
+            errors.push(`${path}: number below minimum ${schema.minimum}`);
+        }
+        if (typeof schema.maximum === "number" && value > schema.maximum) {
+            errors.push(`${path}: number above maximum ${schema.maximum}`);
+        }
+    }
+    if (Array.isArray(value)) {
+        if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+            errors.push(`${path}: array has fewer than minItems ${schema.minItems}`);
+        }
+        if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+            errors.push(`${path}: array has more than maxItems ${schema.maxItems}`);
+        }
+        if (isSchemaObject(schema.items)) {
+            for (let i = 0; i < value.length; i++) {
+                validateSchemaNode(schema.items, value[i], `${path}[${i}]`, errors, depth + 1);
+                if (errors.length >= MAX_MCP_VALIDATION_ERRORS)
+                    return;
+            }
+        }
+    }
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        const obj = value;
+        const props = isSchemaObject(schema.properties) ? schema.properties : undefined;
+        if (Array.isArray(schema.required)) {
+            for (const req of schema.required) {
+                if (typeof req === "string" && !Object.prototype.hasOwnProperty.call(obj, req)) {
+                    errors.push(`${path}.${req}: required property is missing`);
+                }
+            }
+        }
+        const addl = schema.additionalProperties;
+        for (const key of Object.keys(obj)) {
+            const sub = props && isSchemaObject(props[key]) ? props[key] : undefined;
+            if (sub) {
+                validateSchemaNode(sub, obj[key], `${path}.${key}`, errors, depth + 1);
+            }
+            else if (addl === false) {
+                errors.push(`${path}.${key}: unexpected property (additionalProperties is false)`);
+            }
+            else if (isSchemaObject(addl)) {
+                validateSchemaNode(addl, obj[key], `${path}.${key}`, errors, depth + 1);
+            }
+            if (errors.length >= MAX_MCP_VALIDATION_ERRORS)
+                return;
+        }
+    }
+}
+/**
+ * Minimal, dependency-free JSON Schema validator for MCP tool arguments.
+ *
+ * DaloyJS core bundles no third-party schema library, so this implements the
+ * commonly-used, security-relevant subset of JSON Schema — enough to reject the
+ * untrusted `tools/call` argument shapes that matter before a tool handler
+ * runs: wrong `type` (including `integer`), missing `required` properties,
+ * unexpected keys under `additionalProperties: false`, `enum`/`const`
+ * violations, and basic string/number/array bounds (`minLength`/`maxLength`,
+ * `minimum`/`maximum`, `minItems`/`maxItems`). Nested `properties`, `items`,
+ * and object-form `additionalProperties` are validated recursively.
+ *
+ * Keywords outside this subset (`pattern`, `format`, `$ref`,
+ * `anyOf`/`oneOf`/`allOf`, etc.) are intentionally NOT enforced — notably
+ * `pattern` is skipped so a developer-authored regex can never become a ReDoS
+ * sink against attacker-controlled input. Handlers must still validate any
+ * constraint expressed only through those keywords.
+ *
+ * @param schema - The tool's advertised `inputSchema`.
+ * @param value - The untrusted `params.arguments` value from the client.
+ * @returns A list of human-readable validation errors; empty when the value
+ *   satisfies the enforced subset of the schema.
+ * @since 1.0.0
+ */
+export function validateMcpInput(schema, value) {
+    const errors = [];
+    validateSchemaNode(schema, value, "arguments", errors, 0);
+    return errors;
+}
 function publicTool(tool) {
     const { handler: _handler, ...rest } = tool;
     return rest;
@@ -382,8 +542,18 @@ export function createMcpHandler(options) {
                 if (!tool) {
                     return rpcError(id, INVALID_PARAMS, `Unknown tool: ${name || "<missing>"}`, undefined, 200, headers);
                 }
+                // Enforce the tool's advertised inputSchema on the untrusted client
+                // arguments BEFORE the handler runs, so a handler is never handed a
+                // payload that violates its own contract (wrong types, missing required
+                // fields, unexpected keys). Protocol-level validation failures map to
+                // JSON-RPC -32602 (Invalid params).
+                const rawArgs = params.arguments === undefined ? {} : params.arguments;
+                const validationErrors = validateMcpInput(tool.inputSchema, rawArgs);
+                if (validationErrors.length > 0) {
+                    return rpcError(id, INVALID_PARAMS, `Invalid arguments for tool "${name}": ${validationErrors[0]}`, { validationErrors }, 200, headers);
+                }
                 try {
-                    const result = await tool.handler(asRecord(params.arguments), ctx);
+                    const result = await tool.handler(asRecord(rawArgs), ctx);
                     return rpcResult(id, normalizeToolResult(result), headers);
                 }
                 catch (error) {
@@ -523,7 +693,11 @@ export function createMcpHandler(options) {
         }
         let message;
         try {
-            message = JSON.parse(raw);
+            // `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);
         }
         catch {
             return rpcError(null, PARSE_ERROR, "Invalid JSON in request body.", undefined, 400, headers);
@@ -565,8 +739,16 @@ export function createMcpHandler(options) {
  * its public contract and auth policy, while the MCP server can use its own
  * bearer token, rate limit, network allowlist, and tool set.
  *
+ * By default the `POST` transport route is stamped so that a production
+ * `secureDefaults` App **refuses to boot** unless an authentication hook covers
+ * it — MCP tools are model-controlled and side-effecting. Cover the route with
+ * an auth middleware (e.g. `app.use(bearerAuth({ ... }))`), or pass
+ * `{ public: true }` to intentionally expose a public MCP server.
+ *
  * @param path - Public MCP endpoint path, usually `"/mcp"`.
  * @param handler - Handler returned by {@link createMcpHandler}.
+ * @param options - See {@link McpRoutesOptions}; pass `{ public: true }` to opt
+ *   out of the auth boot guard.
  * @returns Route definitions for `POST`, `GET`, and `OPTIONS` on the same
  *   path. `POST` is the actual MCP transport; `GET` gives a human-readable
  *   405 hint because this helper does not open server-initiated SSE streams;
@@ -577,14 +759,21 @@ export function createMcpHandler(options) {
  * const app = new App();
  * const mcp = createMcpHandler({ serverInfo, tools });
  *
+ * // Authenticated MCP server (satisfies the production boot guard):
+ * app.use(bearerAuth({ validate: (t) => timingSafeEqual(t, process.env.MCP_TOKEN!) }));
  * for (const route of mcpRoutes("/mcp", mcp)) {
  *   app.route(route);
  * }
+ *
+ * // ...or an intentionally public MCP server:
+ * for (const route of mcpRoutes("/mcp", mcp, { public: true })) {
+ *   app.route(route);
+ * }
  * ```
  *
  * @since 1.0.0
  */
-export function mcpRoutes(path, handler) {
+export function mcpRoutes(path, handler, options = {}) {
     const responses = {
         200: { description: "MCP JSON-RPC response", body: MCP_JSON_RESPONSE_SCHEMA },
         202: { description: "MCP notification accepted", body: MCP_JSON_RESPONSE_SCHEMA },
@@ -594,7 +783,7 @@ export function mcpRoutes(path, handler) {
         405: { description: "Unsupported MCP transport method" },
         413: { description: "MCP request body too large" },
     };
-    return [
+    const routes = [
         {
             method: "POST",
             path,
@@ -620,4 +809,17 @@ export function mcpRoutes(path, handler) {
             handler: ({ request }) => handler(request),
         },
     ];
+    // Unless explicitly public, stamp the POST transport (the route that executes
+    // tools/call) with the global-registry marker the App boot guard reads. GET
+    // (405 hint) and OPTIONS (preflight) are not marked: preflight must stay
+    // credential-free. Uses the same string as app.ts's MCP_ROUTE_MARKER; kept as
+    // a bare Symbol.for so the App core never imports this module.
+    if (options.public !== true) {
+        for (const route of routes) {
+            if (route.method === "POST") {
+                route[Symbol.for("daloyjs.mcp.route")] = true;
+            }
+        }
+    }
+    return routes;
 }

package/dist/middleware.d.ts

@@ -314,6 +314,44 @@ export declare const CORS_WILDCARD_ORIGIN_MARKER: unique symbol;
  * @since 0.17.0
  */
 export declare const CSRF_HOOK_MARKER: unique symbol;
+/**
+ * Marker stamped on a {@link Hooks} bundle that authenticates the request —
+ * i.e. rejects callers without valid credentials. Built-in auth middlewares
+ * (`bearerAuth`, `basicAuth`, `jwk`, `httpSignatureAuth`, `clientCertAuth`)
+ * stamp it so the framework's route-auth boot guard can confirm that any route
+ * declaring an `auth:` requirement is actually enforced by a hook rather than
+ * being silently public (a `security` entry in the OpenAPI doc with no runtime
+ * check). Wrap a custom authentication hook with {@link markAuthHook} to opt it
+ * into the same guard.
+ *
+ * @since 1.0.0
+ */
+export declare const AUTH_HOOK_MARKER: unique symbol;
+/**
+ * Mark a custom {@link Hooks} bundle as performing request authentication.
+ *
+ * Use this when you authenticate with your own hook (not one of the built-in
+ * auth middlewares) but still declare `auth:` on the protected routes: it
+ * stamps {@link AUTH_HOOK_MARKER} so the production route-auth boot guard treats
+ * those routes as enforced. It is also the correct escape hatch when
+ * authentication is performed by an upstream gateway/mesh and the in-app hook
+ * is intentionally a pass-through.
+ *
+ * @param hooks - The hook bundle to mark (mutated in place and returned).
+ * @returns The same `hooks` object, now stamped as an auth hook.
+ *
+ * @example
+ * ```ts
+ * app.use(markAuthHook({
+ *   async beforeHandle(ctx) {
+ *     if (!(await myVerify(ctx.request))) throw new UnauthorizedError();
+ *   },
+ * }));
+ * ```
+ *
+ * @since 1.0.0
+ */
+export declare function markAuthHook(hooks: Hooks): Hooks;
 /** Predicate stamped on a CORS `Hooks` object that returns `true` for allowed origins. */
 export type CorsOriginAllow = (origin: string) => boolean;
 /** Options for {@link cors}. */

package/dist/middleware.js

@@ -447,6 +447,47 @@ export const CORS_WILDCARD_ORIGIN_MARKER = Symbol.for("daloyjs.middleware.cors.w
  * @since 0.17.0
  */
 export const CSRF_HOOK_MARKER = Symbol.for("daloyjs.middleware.csrf");
+/**
+ * Marker stamped on a {@link Hooks} bundle that authenticates the request —
+ * i.e. rejects callers without valid credentials. Built-in auth middlewares
+ * (`bearerAuth`, `basicAuth`, `jwk`, `httpSignatureAuth`, `clientCertAuth`)
+ * stamp it so the framework's route-auth boot guard can confirm that any route
+ * declaring an `auth:` requirement is actually enforced by a hook rather than
+ * being silently public (a `security` entry in the OpenAPI doc with no runtime
+ * check). Wrap a custom authentication hook with {@link markAuthHook} to opt it
+ * into the same guard.
+ *
+ * @since 1.0.0
+ */
+export const AUTH_HOOK_MARKER = Symbol.for("daloyjs.auth.hook");
+/**
+ * Mark a custom {@link Hooks} bundle as performing request authentication.
+ *
+ * Use this when you authenticate with your own hook (not one of the built-in
+ * auth middlewares) but still declare `auth:` on the protected routes: it
+ * stamps {@link AUTH_HOOK_MARKER} so the production route-auth boot guard treats
+ * those routes as enforced. It is also the correct escape hatch when
+ * authentication is performed by an upstream gateway/mesh and the in-app hook
+ * is intentionally a pass-through.
+ *
+ * @param hooks - The hook bundle to mark (mutated in place and returned).
+ * @returns The same `hooks` object, now stamped as an auth hook.
+ *
+ * @example
+ * ```ts
+ * app.use(markAuthHook({
+ *   async beforeHandle(ctx) {
+ *     if (!(await myVerify(ctx.request))) throw new UnauthorizedError();
+ *   },
+ * }));
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function markAuthHook(hooks) {
+    hooks[AUTH_HOOK_MARKER] = true;
+    return hooks;
+}
 /**
  * Cross-Origin Resource Sharing (CORS) middleware. Handles both preflight
  * (`OPTIONS`) and actual requests, attaching the correct
@@ -838,7 +879,7 @@ export function bearerAuth(opts) {
     if (/["\r\n\0]/.test(realm)) {
         throw new Error("bearerAuth(): realm must not contain quotes, CR, LF, or NUL bytes.");
     }
-    return {
+    return markAuthHook({
         async beforeHandle(ctx) {
             const h = ctx.request.headers.get("authorization") ?? "";
             const m = /^Bearer\s+(.+)$/i.exec(h);
@@ -866,7 +907,7 @@ export function bearerAuth(opts) {
             }
             return undefined;
         },
-    };
+    });
 }
 const CSRF_STATE_TOKEN = "csrfToken";
 const CSRF_STATE_ISSUED = "__csrfIssued";
@@ -1115,7 +1156,7 @@ export function basicAuth(opts) {
     if (!Number.isInteger(maxBytes) || maxBytes < 1) {
         throw new Error("basicAuth(): maxCredentialBytes must be a positive integer.");
     }
-    return {
+    return markAuthHook({
         async beforeHandle(ctx) {
             const header = ctx.request.headers.get("authorization") ?? "";
             const match = BASIC_AUTH_TOKEN_RE.exec(header);
@@ -1134,7 +1175,7 @@ export function basicAuth(opts) {
             }
             return undefined;
         },
-    };
+    });
 }
 // ---------- requireScopes ----------
 /**

package/dist/mtls.js

@@ -347,7 +347,7 @@ export function clientCertAuth(opts = {}) {
                 return certFromHeaders(ctx.request, headerConfig);
             return undefined;
         });
-    return {
+    const authHooks = {
         async beforeHandle(ctx) {
             const cert = resolve(ctx);
             if (!cert) {
@@ -386,6 +386,11 @@ export function clientCertAuth(opts = {}) {
             return undefined;
         },
     };
+    // Same global symbol as middleware's AUTH_HOOK_MARKER (stamped inline to keep
+    // the middleware module out of this bundle): lets the route-auth boot guard
+    // recognize that a route declaring `auth:` is actually enforced here.
+    authHooks[Symbol.for("daloyjs.auth.hook")] = true;
+    return authHooks;
 }
 function assertHeaderConfig(cfg) {
     if (cfg.format === "xfcc")

package/dist/sbom.cdx.json

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:e297e402-67fc-54e1-a292-02441ebb5d71",
+  "serialNumber": "urn:uuid:8448de36-3a72-553d-882f-b5b36bbd1426",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-03T11:51:00.910Z",
+    "timestamp": "2026-07-07T09:24:36.816Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "1.0.0-rc.0"
+        "version": "1.0.0-rc.2"
       }
     ],
     "authors": [
@@ -19,11 +19,11 @@
     ],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-rc.0",
+      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-rc.2",
       "name": "@daloyjs/core",
-      "version": "1.0.0-rc.0",
+      "version": "1.0.0-rc.2",
       "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-rc.0",
+      "purl": "pkg:npm/@daloyjs/core@1.0.0-rc.2",
       "licenses": [
         {
           "license": {
@@ -46,9 +46,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-1.0.0-rc.0",
+        "tagId": "swidtag--daloyjs-core-1.0.0-rc.2",
         "name": "@daloyjs/core",
-        "version": "1.0.0-rc.0",
+        "version": "1.0.0-rc.2",
         "tagVersion": 0,
         "patch": false
       }
@@ -57,7 +57,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/@daloyjs/core@1.0.0-rc.0",
+      "ref": "pkg:npm/@daloyjs/core@1.0.0-rc.2",
       "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-rc.0",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-rc.0-e297e402-67fc-54e1-a292-02441ebb5d71",
+  "name": "@daloyjs/core-1.0.0-rc.2",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-rc.2-8448de36-3a72-553d-882f-b5b36bbd1426",
   "creationInfo": {
-    "created": "2026-07-03T11:51:00.910Z",
+    "created": "2026-07-07T09:24:36.816Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package--daloyjs-core",
       "name": "@daloyjs/core",
-      "versionInfo": "1.0.0-rc.0",
+      "versionInfo": "1.0.0-rc.2",
       "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-rc.0"
+          "referenceLocator": "pkg:npm/@daloyjs/core@1.0.0-rc.2"
         }
       ]
     }