@daloyjs/core 0.16.0 → 0.29.0

package/dist/middleware.js

@@ -4,6 +4,7 @@
  * All middlewares return `Hooks` objects so they compose with `app.use(...)`,
  * groups, and per-route hooks identically.
  */
+import { assertCookieAttributes, readRequestCookie, serializeCookie } from "./cookie.js";
 import { TooManyRequestsError, ForbiddenError } from "./errors.js";
 import { randomId, sanitizeHeaderName, timingSafeEqual } from "./security.js";
 /**
@@ -83,12 +84,36 @@ function buildCspHeader(opt, nonce) {
             entries["trusted-types"] = trustedTypes.policies.slice();
         }
     }
+    if (opt.reportTo) {
+        entries["report-to"] = [opt.reportTo];
+    }
     const parts = [];
     for (const [directiveName, sources] of Object.entries(entries)) {
         parts.push(`${directiveName} ${sources.join(" ")}`);
     }
     return parts.join("; ");
 }
+function cspSourceListHasValues(directiveValue) {
+    return Array.isArray(directiveValue)
+        ? directiveValue.some((source) => source.trim().length > 0)
+        : directiveValue.split(/\s+/).some((source) => source.length > 0);
+}
+function cspStringHasFrameAncestors(csp) {
+    return csp.split(";").some((directivePart) => {
+        const tokens = directivePart.trim().split(/\s+/).filter(Boolean);
+        const directiveName = tokens[0];
+        return directiveName?.toLowerCase() === "frame-ancestors" && tokens.length > 1;
+    });
+}
+function cspOptionsHaveFrameAncestors(csp) {
+    for (const [directiveName, directiveValue] of Object.entries(csp.directives)) {
+        if (directiveName.toLowerCase() === "frame-ancestors" &&
+            cspSourceListHasValues(directiveValue)) {
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * Apply a Helmet-equivalent baseline of secure response headers:
  * `Content-Security-Policy`, `Strict-Transport-Security`, `X-Frame-Options`,
@@ -126,7 +151,53 @@ function buildCspHeader(opt, nonce) {
 export const SECURE_HEADERS_MARKER = Symbol.for("daloyjs.middleware.secureHeaders");
 export function secureHeaders(opts = {}) {
     const headers = {};
-    const cspOpt = opts.contentSecurityPolicy ?? "default-src 'self'; frame-ancestors 'none'";
+    let cspOpt = opts.contentSecurityPolicy ?? "default-src 'self'; frame-ancestors 'none'";
+    // Wave 8 — refuse to construct when the developer disabled BOTH framing
+    // defenses simultaneously (no X-Frame-Options AND no frame-ancestors
+    // directive in CSP). A response with neither defense can be embedded in
+    // an `<iframe>` from any origin, which re-opens the clickjacking surface
+    // the helper is meant to close. The dual-knob "I disabled both" case is
+    // the documented footgun this guard catches.
+    const frameOptionExplicitlyDisabled = opts.frameOptions === false;
+    if (frameOptionExplicitlyDisabled) {
+        let cspProvidesFrameAncestors = false;
+        if (typeof cspOpt === "string") {
+            cspProvidesFrameAncestors = cspStringHasFrameAncestors(cspOpt);
+        }
+        else if (cspOpt !== false && typeof cspOpt === "object") {
+            cspProvidesFrameAncestors = cspOptionsHaveFrameAncestors(cspOpt);
+        }
+        if (!cspProvidesFrameAncestors) {
+            throw new Error("secureHeaders(): refusing to construct with both frameOptions: false " +
+                "AND no CSP frame-ancestors directive — that disables every clickjacking " +
+                "defense the helper provides. Set frameOptions: 'DENY' / 'SAMEORIGIN', " +
+                "or add a `frame-ancestors` directive to contentSecurityPolicy.");
+        }
+    }
+    // If `reportTo` is provided at the top level but CSP is still a string,
+    // promote it into a directives object so we can append `report-to <group>`.
+    if (opts.reportTo && typeof cspOpt === "string") {
+        const directives = {};
+        for (const part of cspOpt.split(";")) {
+            const trimmed = part.trim();
+            if (!trimmed)
+                continue;
+            const spaceIndex = trimmed.indexOf(" ");
+            if (spaceIndex === -1) {
+                directives[trimmed] = "";
+            }
+            else {
+                directives[trimmed.slice(0, spaceIndex)] = trimmed.slice(spaceIndex + 1);
+            }
+        }
+        cspOpt = { directives, reportTo: opts.reportTo };
+    }
+    else if (opts.reportTo &&
+        cspOpt !== false &&
+        typeof cspOpt === "object" &&
+        !cspOpt.reportTo) {
+        cspOpt = { ...cspOpt, reportTo: opts.reportTo };
+    }
     const cspIsDynamic = cspOpt !== false && typeof cspOpt === "object";
     if (cspOpt !== false && typeof cspOpt === "string") {
         headers["content-security-policy"] = cspOpt;
@@ -159,6 +230,24 @@ export function secureHeaders(opts = {}) {
         headers["x-content-type-options"] = "nosniff";
     if (opts.xssProtection ?? false)
         headers["x-xss-protection"] = "0"; // modern guidance
+    // Wave 4 leftover: Reporting API endpoints.
+    if (opts.reportingEndpoints) {
+        const entries = Object.entries(opts.reportingEndpoints);
+        if (entries.length > 0) {
+            // Modern: structured header field — quoted URL per group.
+            headers["reporting-endpoints"] = entries
+                .map(([group, url]) => `${group}="${url}"`)
+                .join(", ");
+            // Legacy: Report-To JSON for older Chromium versions.
+            headers["report-to"] = entries
+                .map(([group, url]) => JSON.stringify({
+                group,
+                max_age: 10886400,
+                endpoints: [{ url }],
+            }))
+                .join(", ");
+        }
+    }
     const hooks = {
         beforeHandle(ctx) {
             if (cspIsDynamic && cspOpt.nonce) {
@@ -212,6 +301,30 @@ export const CORS_HOOK_MARKER = Symbol.for("daloyjs.middleware.cors");
  * @since 0.16.0
  */
 export const CORS_ORIGIN_ALLOW_MARKER = Symbol.for("daloyjs.middleware.cors.originAllow");
+/**
+ * Marker stamped on the `Hooks` object returned by {@link cors} when the
+ * configured `origin` permits the wildcard `"*"`. Used by the Wave 3
+ * boot-time refuse-to-boot guard: a wildcard CORS origin in production is
+ * almost always a misconfiguration, so `App` constructed with
+ * `secureDefaults: true` (the 0.16+ default) and resolved to
+ * `production` throws at `app.use(cors({ origin: "*" }))` time rather than
+ * silently exposing every state-changing endpoint cross-origin.
+ *
+ * @since 0.17.0
+ */
+export const CORS_WILDCARD_ORIGIN_MARKER = Symbol.for("daloyjs.middleware.cors.wildcardOrigin");
+/**
+ * Marker stamped on the `Hooks` object returned by {@link csrf}. Used by
+ * the Wave 3 boot-time refuse-to-boot guard: when `session()` is registered
+ * on a `secureDefaults: true` App that also exposes any state-changing
+ * route, the framework requires a matching `csrf()` hook somewhere in the
+ * hook chain so an attacker cannot forge a cross-site request that mutates
+ * the authenticated session. Third-party CSRF helpers can opt into the
+ * guard by stamping the same marker on their returned hooks.
+ *
+ * @since 0.17.0
+ */
+export const CSRF_HOOK_MARKER = Symbol.for("daloyjs.middleware.csrf");
 /**
  * Cross-Origin Resource Sharing (CORS) middleware. Handles both preflight
  * (`OPTIONS`) and actual requests, attaching the correct
@@ -301,8 +414,28 @@ export function cors(opts) {
     };
     hooks[CORS_HOOK_MARKER] = true;
     hooks[CORS_ORIGIN_ALLOW_MARKER] = (origin) => allow(origin) !== null;
+    const hasWildcard = opts.origin === "*" ||
+        (Array.isArray(opts.origin) && opts.origin.includes("*"));
+    if (hasWildcard) {
+        hooks[CORS_WILDCARD_ORIGIN_MARKER] = true;
+    }
     return hooks;
 }
+/**
+ * Shared in-memory store registry for {@link RateLimitOptions.groupId}. Two
+ * `rateLimit({ groupId: "auth" })` calls receive the same bucket map so the
+ * limit is enforced across every route the same `groupId` is mounted on.
+ *
+ * Exposed only for tests; not part of the documented public API.
+ *
+ * @internal
+ */
+const SHARED_RATE_LIMIT_STORES = new Map();
+const SHARED_LOGIN_THROTTLE_BUCKETS = new Map();
+export function _resetSharedRateLimitStoresForTests() {
+    SHARED_RATE_LIMIT_STORES.clear();
+    SHARED_LOGIN_THROTTLE_BUCKETS.clear();
+}
 class MemoryStore {
     buckets = new Map();
     async hit(key, windowMs) {
@@ -356,7 +489,22 @@ class MemoryStore {
  * @since 0.1.0
  */
 export function rateLimit(opts) {
-    const store = opts.store ?? new MemoryStore();
+    let store;
+    if (opts.store) {
+        store = opts.store;
+    }
+    else if (opts.groupId) {
+        let shared = SHARED_RATE_LIMIT_STORES.get(opts.groupId);
+        if (!shared) {
+            shared = new MemoryStore();
+            SHARED_RATE_LIMIT_STORES.set(opts.groupId, shared);
+        }
+        store = shared;
+    }
+    else {
+        store = new MemoryStore();
+    }
+    const groupPrefix = opts.groupId ? `${opts.groupId}:` : "";
     const keyOf = opts.keyGenerator ??
         ((ctx) => {
             if (opts.trustProxyHeaders) {
@@ -368,7 +516,7 @@ export function rateLimit(opts) {
         });
     return {
         async beforeHandle(ctx) {
-            const key = keyOf(ctx);
+            const key = `${groupPrefix}${keyOf(ctx)}`;
             const { count, resetMs } = await store.hit(key, opts.windowMs);
             const remaining = Math.max(0, opts.max - count);
             ctx.set.headers.set("x-ratelimit-limit", String(opts.max));
@@ -382,6 +530,94 @@ export function rateLimit(opts) {
         },
     };
 }
+function assertNonNegativeInteger(name, value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`loginThrottle(): ${name} must be a non-negative integer.`);
+    }
+}
+function assertPositiveInteger(name, value) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`loginThrottle(): ${name} must be a positive integer.`);
+    }
+}
+function defaultLoginThrottleKey(trustProxyHeaders) {
+    return (ctx) => {
+        if (trustProxyHeaders) {
+            const forwardedFor = ctx.request.headers.get("x-forwarded-for");
+            const firstForwarded = forwardedFor ? forwardedFor.split(",")[0].trim() : "";
+            return firstForwarded || ctx.request.headers.get("x-real-ip") || "global";
+        }
+        return "global";
+    };
+}
+function wait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Login throttle preset for `/login`, `/login/otp`, password reset, and
+ * adjacent credential-entry routes. It combines a shared `rateLimit({ groupId })`
+ * bucket with a small progressive slowdown before the hard 429 kicks in.
+ *
+ * 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.
+ *
+ * @since 0.23.0
+ */
+export function loginThrottle(opts = {}) {
+    const windowMs = opts.windowMs ?? 15 * 60_000;
+    const max = opts.max ?? 5;
+    const delayAfter = opts.delayAfter ?? 2;
+    const delayMs = opts.delayMs ?? 250;
+    const maxDelayMs = opts.maxDelayMs ?? 2_000;
+    assertPositiveInteger("windowMs", windowMs);
+    assertPositiveInteger("max", max);
+    assertNonNegativeInteger("delayAfter", delayAfter);
+    assertNonNegativeInteger("delayMs", delayMs);
+    assertNonNegativeInteger("maxDelayMs", maxDelayMs);
+    const groupId = opts.groupId ?? "login";
+    const keyGenerator = opts.keyGenerator ?? defaultLoginThrottleKey(opts.trustProxyHeaders);
+    const limiter = rateLimit({
+        windowMs,
+        max,
+        groupId,
+        keyGenerator,
+        ...(opts.store ? { store: opts.store } : {}),
+        ...(opts.trustProxyHeaders !== undefined
+            ? { trustProxyHeaders: opts.trustProxyHeaders }
+            : {}),
+        ...(opts.retryAfter !== undefined ? { retryAfter: opts.retryAfter } : {}),
+    });
+    let slowdownBuckets = SHARED_LOGIN_THROTTLE_BUCKETS.get(groupId);
+    if (!slowdownBuckets) {
+        slowdownBuckets = new Map();
+        SHARED_LOGIN_THROTTLE_BUCKETS.set(groupId, slowdownBuckets);
+    }
+    return {
+        async beforeHandle(ctx) {
+            const now = Date.now();
+            const key = `${groupId}:${keyGenerator(ctx)}`;
+            let bucket = slowdownBuckets.get(key);
+            if (!bucket || bucket.resetMs <= now) {
+                bucket = { count: 0, resetMs: now + windowMs };
+                slowdownBuckets.set(key, bucket);
+            }
+            bucket.count += 1;
+            if (slowdownBuckets.size > 10_000) {
+                for (const [bucketKey, value] of slowdownBuckets) {
+                    if (value.resetMs <= now)
+                        slowdownBuckets.delete(bucketKey);
+                }
+            }
+            if (bucket.count > delayAfter && delayMs > 0 && maxDelayMs > 0) {
+                const delay = Math.min(maxDelayMs, (bucket.count - delayAfter) * delayMs);
+                if (delay > 0)
+                    await wait(delay);
+            }
+            return limiter.beforeHandle?.(ctx);
+        },
+    };
+}
 // ---------- Timing ----------
 /**
  * Stamp a `Server-Timing` header (or your chosen header) on every response
@@ -413,14 +649,17 @@ export function timing(headerName = "server-timing") {
         },
     };
 }
-// ---------- Bearer auth helper ----------
 /**
  * Minimal Bearer-token authentication middleware. Rejects requests with no
  * `Authorization: Bearer ...` header with `401` (and a `WWW-Authenticate`
- * challenge), and requests whose token fails `validate(token)` with `403`.
+ * challenge), and requests whose token fails `validate(token)` (or the
+ * optional per-request `verify(token, ctx)` revalidation hook) with `403`.
  *
  * The `validate` callback is the integration point with whatever JWT
- * verifier, opaque-token introspector, or in-memory test stub you use.
+ * verifier, opaque-token introspector, or in-memory test stub you use. The
+ * optional `verify` hook (Wave 5) is the integration point for revocation
+ * lists, token-version counters, and other per-request invalidation checks
+ * that `validate` cannot answer statelessly.
  *
  * @example
  * ```ts
@@ -432,14 +671,23 @@ export function timing(headerName = "server-timing") {
  *   validate: async (token) => {
  *     try { await jwtVerify(token, jwks); return true; } catch { return false; }
  *   },
+ *   verify: async (token, _ctx) => !(await revoked.has(hash(token))),
  * }));
  * ```
  *
- * @param opts - Token validator and optional `WWW-Authenticate` realm.
+ * @param opts - Token validator, optional revalidation hook, and realm.
  * @returns A {@link Hooks} bundle ready for `app.use(...)`.
  * @since 0.1.0
  */
 export function bearerAuth(opts) {
+    const options = opts;
+    if (!options || typeof options.validate !== "function") {
+        throw new Error("bearerAuth(): validate must be a function.");
+    }
+    const realm = options.realm ?? "api";
+    if (/["\r\n\0]/.test(realm)) {
+        throw new Error("bearerAuth(): realm must not contain quotes, CR, LF, or NUL bytes.");
+    }
     return {
         async beforeHandle(ctx) {
             const h = ctx.request.headers.get("authorization") ?? "";
@@ -453,20 +701,25 @@ export function bearerAuth(opts) {
                     status: 401,
                     headers: {
                         "content-type": "application/problem+json",
-                        "www-authenticate": `Bearer realm="${opts.realm ?? "api"}"`,
+                        "www-authenticate": `Bearer realm="${realm}"`,
+                        "cache-control": "no-store",
                     },
                 });
             }
-            const ok = await opts.validate(m[1]);
+            const ok = await options.validate(m[1]);
             if (!ok)
                 throw new ForbiddenError("Invalid token");
+            if (options.verify) {
+                const verified = await options.verify(m[1], ctx);
+                if (verified === false)
+                    throw new ForbiddenError("Token revoked");
+            }
             return undefined;
         },
     };
 }
 const CSRF_STATE_TOKEN = "csrfToken";
 const CSRF_STATE_ISSUED = "__csrfIssued";
-const CSRF_COOKIE_NAME_RE = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
 function generateCsrfToken() {
     const cryptoApi = globalThis.crypto;
     if (cryptoApi?.getRandomValues) {
@@ -478,69 +731,16 @@ function generateCsrfToken() {
         return cryptoApi.randomUUID().replace(/-/g, "");
     throw new Error("csrf(): WebCrypto is required for the default token generator. Pass a custom generator to csrf({ generator }).");
 }
-function validateCookieSegment(kind, value) {
-    if (/[;\r\n\0]/.test(value))
-        throw new Error(`csrf(): cookieOptions.${kind} contains an invalid character.`);
-}
-function validateCsrfCookieOptions(cookieName, opts) {
-    if (!CSRF_COOKIE_NAME_RE.test(cookieName))
-        throw new Error("csrf(): cookieName is not a valid cookie name.");
-    if (opts.sameSite !== "Strict" && opts.sameSite !== "Lax" && opts.sameSite !== "None") {
-        throw new Error('csrf(): cookieOptions.sameSite must be "Strict", "Lax", or "None".');
-    }
-    if (!opts.path.startsWith("/"))
-        throw new Error('csrf(): cookieOptions.path must start with "/".');
-    validateCookieSegment("path", opts.path);
-    if (opts.domain)
-        validateCookieSegment("domain", opts.domain);
-    if (!Number.isInteger(opts.maxAgeSeconds) || opts.maxAgeSeconds < 0) {
-        throw new Error("csrf(): cookieOptions.maxAgeSeconds must be a non-negative integer.");
-    }
-    if (cookieName.startsWith("__Host-")) {
-        if (!opts.secure || opts.path !== "/" || opts.domain) {
-            throw new Error('csrf(): "__Host-" cookie names require secure: true, path: "/", and no domain. ' +
-                "Pass an explicit cookieName or relax cookieOptions to use a non-prefixed cookie.");
-        }
-    }
-    if (opts.sameSite === "None" && !opts.secure) {
-        throw new Error('csrf(): cookieOptions.sameSite: "None" requires secure: true.');
-    }
-}
-function parseCookieValue(header, name) {
-    if (!header)
-        return null;
-    const parts = header.split(";");
-    for (let i = 0; i < parts.length; i++) {
-        const part = parts[i];
-        const eq = part.indexOf("=");
-        if (eq < 0)
-            continue;
-        const k = part.slice(0, eq).trim();
-        if (k === name) {
-            const v = part.slice(eq + 1).trim();
-            try {
-                return decodeURIComponent(v);
-            }
-            catch {
-                return v;
-            }
-        }
-    }
-    return null;
-}
-function buildCsrfSetCookie(name, value, opts) {
-    let s = `${name}=${encodeURIComponent(value)}`;
-    s += `; Path=${opts.path}`;
-    s += `; SameSite=${opts.sameSite}`;
-    if (opts.secure)
-        s += "; Secure";
-    if (opts.domain)
-        s += `; Domain=${opts.domain}`;
-    if (opts.maxAgeSeconds > 0)
-        s += `; Max-Age=${opts.maxAgeSeconds}`;
-    if (opts.partitioned)
-        s += "; Partitioned";
-    return s;
+function csrfCookieAttributes(opts) {
+    return {
+        sameSite: opts.sameSite,
+        secure: opts.secure,
+        path: opts.path,
+        domain: opts.domain || undefined,
+        maxAgeSeconds: opts.maxAgeSeconds,
+        partitioned: opts.partitioned,
+        httpOnly: false,
+    };
 }
 /**
  * CSRF protection middleware.
@@ -627,9 +827,14 @@ export function csrf(opts = {}) {
         maxAgeSeconds: cookieOverrides.maxAgeSeconds ?? 0,
         partitioned: cookieOverrides.partitioned ?? false,
     };
-    if (wantsDoubleSubmit)
-        validateCsrfCookieOptions(cookieName, cookieOpts);
-    return {
+    if (wantsDoubleSubmit) {
+        assertCookieAttributes({
+            scope: "csrf()",
+            name: cookieName,
+            attributes: csrfCookieAttributes(cookieOpts),
+        });
+    }
+    const hooks = {
         beforeHandle(ctx) {
             const method = ctx.request.method.toUpperCase();
             const isSafe = ignore.has(method);
@@ -638,7 +843,7 @@ export function csrf(opts = {}) {
             }
             if (!wantsDoubleSubmit)
                 return undefined;
-            const existing = parseCookieValue(ctx.request.headers.get("cookie"), cookieName);
+            const existing = readRequestCookie(ctx.request.headers.get("cookie"), cookieName);
             if (isSafe) {
                 if (existing) {
                     ctx.state[CSRF_STATE_TOKEN] = existing;
@@ -665,10 +870,12 @@ export function csrf(opts = {}) {
             const issued = ctx.state[CSRF_STATE_ISSUED];
             if (!issued)
                 return undefined;
-            res.headers.append("set-cookie", buildCsrfSetCookie(cookieName, issued, cookieOpts));
+            res.headers.append("set-cookie", serializeCookie(cookieName, issued, csrfCookieAttributes(cookieOpts)));
             return undefined;
         },
     };
+    hooks[CSRF_HOOK_MARKER] = true;
+    return hooks;
 }
 const BASIC_AUTH_TOKEN_RE = /^Basic\s+([A-Za-z0-9+/=]+)$/i;
 function decodeBasic(token) {
@@ -707,6 +914,7 @@ function basicAuthChallenge(realm) {
         headers: {
             "content-type": "application/problem+json",
             "www-authenticate": `Basic realm="${realm}", charset="UTF-8"`,
+            "cache-control": "no-store",
         },
     });
 }
@@ -766,9 +974,122 @@ export function basicAuth(opts) {
                 return basicAuthChallenge(realm);
             ctx.state.user =
                 typeof result === "object" ? result : { username: creds.user };
+            if (options.onAuthSuccess) {
+                await options.onAuthSuccess({ username: creds.user, password: creds.pass }, ctx);
+            }
             return undefined;
         },
     };
 }
+// ---------- requireScopes (Wave 5 leftover) ----------
+/**
+ * Marker stamped on the per-request `state` bag so multiple `requireScopes()`
+ * hooks in the same chain aggregate their required scopes into one combined
+ * `WWW-Authenticate: Bearer scope="..."` challenge instead of each emitting a
+ * separate `401` with only its own scopes.
+ *
+ * @since 0.21.0
+ */
+export const REQUIRE_SCOPES_AGGREGATE_KEY = "__daloyRequiredScopes";
+export const REQUIRE_SCOPES_HOOK_MARKER = Symbol.for("daloyjs.middleware.requireScopes");
+function validateScopeList(scopes) {
+    if (!Array.isArray(scopes) || scopes.length === 0) {
+        throw new Error("requireScopes(): scopes must be a non-empty array of strings.");
+    }
+    const seen = new Set();
+    const out = [];
+    for (const s of scopes) {
+        if (typeof s !== "string" || s.length === 0) {
+            throw new Error("requireScopes(): every scope must be a non-empty string.");
+        }
+        // RFC 6749 §3.3: scope values must not contain double-quote, backslash, or
+        // control characters; rejecting them at construction time means the
+        // WWW-Authenticate challenge cannot be malformed by user input.
+        if (/["\\\x00-\x1F\x7F]/.test(s)) {
+            throw new Error(`requireScopes(): scope "${s}" contains an illegal character.`);
+        }
+        if (!seen.has(s)) {
+            seen.add(s);
+            out.push(s);
+        }
+    }
+    return out;
+}
+function readUserScopes(user) {
+    if (!user || typeof user !== "object")
+        return null;
+    const raw = user.scopes;
+    if (!Array.isArray(raw))
+        return null;
+    const set = new Set();
+    for (const s of raw)
+        if (typeof s === "string" && s.length > 0)
+            set.add(s);
+    return set;
+}
+/**
+ * Declarative scope-check middleware for OAuth2-style bearer credentials.
+ * Reads the typed `ctx.state.user.scopes` written by the upstream auth
+ * helper (`bearerAuth`, `jwt`, …) and refuses the request with `401` (no
+ * credentials) or `403` (valid credentials but insufficient scopes).
+ *
+ * Multiple `requireScopes()` hooks in the same chain aggregate their required
+ * scopes into one combined `WWW-Authenticate: Bearer scope="a b c"` challenge
+ * via {@link REQUIRE_SCOPES_AGGREGATE_KEY} on `ctx.state`.
+ *
+ * @example
+ * ```ts
+ * app.route({
+ *   method: "POST",
+ *   path: "/items",
+ *   hooks: { ...bearerAuth({ validate }), ...requireScopes(["items:write"]) },
+ *   responses: { 200: { description: "ok" } },
+ *   handler: () => ({ status: 200 as const, body: { ok: true } }),
+ * });
+ * ```
+ *
+ * @since 0.21.0
+ */
+export function requireScopes(scopes) {
+    const required = validateScopeList(scopes);
+    const hooks = {
+        beforeHandle(ctx) {
+            const state = ctx.state;
+            const prior = state[REQUIRE_SCOPES_AGGREGATE_KEY];
+            const aggregate = Array.isArray(prior) ? [...prior] : [];
+            for (const s of required)
+                if (!aggregate.includes(s))
+                    aggregate.push(s);
+            state[REQUIRE_SCOPES_AGGREGATE_KEY] = aggregate;
+            const user = state.user;
+            if (user === undefined || user === null) {
+                const challenge = `Bearer scope="${aggregate.join(" ")}", error="insufficient_scope"`;
+                return new Response(JSON.stringify({
+                    type: "https://daloyjs.dev/errors/unauthorized",
+                    title: "Unauthorized",
+                    status: 401,
+                    detail: `Missing credentials. Required scopes: ${aggregate.join(", ")}.`,
+                }), {
+                    status: 401,
+                    headers: {
+                        "content-type": "application/problem+json",
+                        "www-authenticate": challenge,
+                        "cache-control": "no-store",
+                    },
+                });
+            }
+            const owned = readUserScopes(user);
+            const missing = owned === null
+                ? aggregate.slice()
+                : aggregate.filter((s) => !owned.has(s));
+            if (missing.length > 0) {
+                throw new ForbiddenError(`Missing required scope(s): ${missing.join(", ")}.`);
+            }
+            return undefined;
+        },
+    };
+    hooks[REQUIRE_SCOPES_HOOK_MARKER] = required;
+    return hooks;
+}
 export { timingSafeEqual };
 //# sourceMappingURL=middleware.js.map