@lastshotlabs/bunshot 0.0.21 → 0.0.27

package/dist/middleware/identify.js

@@ -1,34 +1,107 @@
 import { getCookie } from "hono/cookie";
 import { verifyToken } from "../lib/jwt";
-import { getSession, updateSessionLastActive } from "../lib/session";
+import { getSession, updateSessionLastActive, getSessionFingerprint, setSessionFingerprint } from "../lib/session";
 import { COOKIE_TOKEN, HEADER_USER_TOKEN } from "../lib/constants";
-import { log } from "../lib/logger";
-import { getTrackLastActive } from "../lib/appConfig";
+import { log, authTrace } from "../lib/logger";
+import { getTrackLastActive, getSigningConfig, getCheckSuspensionOnIdentify } from "../lib/appConfig";
+import { getSuspended } from "../lib/suspension";
+import { getClientIp } from "../lib/clientIp";
+import { sha256, timingSafeEqual } from "../lib/crypto";
+import { HttpError } from "../lib/HttpError";
+function computeFingerprint(c, fields) {
+    const parts = fields.map((f) => {
+        if (f === "ip")
+            return getClientIp(c) ?? "";
+        if (f === "ua")
+            return c.req.header("user-agent") ?? "";
+        return c.req.header("accept-language") ?? "";
+    });
+    return sha256(parts.join(":"));
+}
 export const identify = async (c, next) => {
     c.set("authUserId", null);
     c.set("roles", null);
     c.set("sessionId", null);
+    c.set("authClientId", null);
+    c.set("tokenPayload", null);
     // cookie for browsers, x-user-token header for non-browser clients
     const token = getCookie(c, COOKIE_TOKEN) ?? c.req.header(HEADER_USER_TOKEN) ?? null;
     log(`[identify] token=${token ? "present" : "absent"}`);
     if (token) {
         try {
             const payload = await verifyToken(token);
+            c.set("tokenPayload", payload);
             const sessionId = payload.sid;
             if (!sessionId) {
-                log("[identify] token missing sid claim — unauthenticated");
+                // Check for M2M token (scope present, no sid)
+                if (payload.scope && payload.sub) {
+                    c.set("authClientId", payload.sub);
+                    log(`[identify] M2M token for clientId=${payload.sub}`);
+                }
+                else {
+                    log("[identify] token missing sid claim — unauthenticated");
+                }
             }
             else {
                 const stored = await getSession(sessionId);
-                log(`[identify] token for authUserId=${payload.sub} verified, checking session...`);
-                if (stored === token) {
-                    c.set("authUserId", payload.sub);
-                    c.set("sessionId", sessionId);
-                    log(`[identify] authUserId=${payload.sub} sessionId=${sessionId}`);
-                    if (getTrackLastActive()) {
-                        updateSessionLastActive(sessionId).catch(() => {
-                            log(`[identify] failed to update lastActiveAt for sessionId=${sessionId}`);
-                        });
+                log("[identify] token verified, checking session...");
+                authTrace(`[identify] authUserId=${payload.sub}`);
+                if (timingSafeEqual(stored ?? "", token)) {
+                    const signingCfg = getSigningConfig();
+                    const bindingCfg = signingCfg?.sessionBinding;
+                    if (bindingCfg) {
+                        const bindingOpts = typeof bindingCfg === "object" ? bindingCfg : {};
+                        const fields = bindingOpts.fields ?? ["ip", "ua"];
+                        const onMismatch = bindingOpts.onMismatch ?? "unauthenticate";
+                        const current = computeFingerprint(c, fields);
+                        const storedFp = await getSessionFingerprint(sessionId);
+                        if (storedFp === null) {
+                            // First authenticated request — store the fingerprint
+                            setSessionFingerprint(sessionId, current).catch(() => {
+                                log("[identify] failed to store session fingerprint");
+                            });
+                            c.set("authUserId", payload.sub);
+                            c.set("sessionId", sessionId);
+                        }
+                        else if (timingSafeEqual(storedFp, current)) {
+                            c.set("authUserId", payload.sub);
+                            c.set("sessionId", sessionId);
+                        }
+                        else {
+                            log(`[identify] fingerprint mismatch, onMismatch=${onMismatch}`);
+                            authTrace(`[identify] sessionId=${sessionId}`);
+                            if (onMismatch === "reject") {
+                                throw new HttpError(401, "Unauthorized", "FINGERPRINT_MISMATCH");
+                            }
+                            else if (onMismatch === "log-only") {
+                                c.set("authUserId", payload.sub);
+                                c.set("sessionId", sessionId);
+                            }
+                            // onMismatch === "unauthenticate" — leave authUserId null (already null)
+                        }
+                    }
+                    else {
+                        c.set("authUserId", payload.sub);
+                        c.set("sessionId", sessionId);
+                    }
+                    if (c.get("authUserId")) {
+                        if (getCheckSuspensionOnIdentify()) {
+                            const suspensionStatus = await getSuspended(payload.sub).catch(() => ({ suspended: false }));
+                            if (suspensionStatus.suspended) {
+                                c.set("authUserId", null);
+                                c.set("sessionId", null);
+                                c.set("roles", null);
+                                log(`[identify] userId=${payload.sub} is suspended — unauthenticated`);
+                            }
+                        }
+                    }
+                    if (c.get("authUserId")) {
+                        authTrace(`[identify] authUserId=${payload.sub} sessionId=${sessionId}`);
+                        if (getTrackLastActive()) {
+                            updateSessionLastActive(sessionId).catch(() => {
+                                log("[identify] failed to update session lastActiveAt");
+                            });
+                        }
                     }
                 }
                 else {
@@ -36,7 +109,9 @@ export const identify = async (c, next) => {
                 }
             }
         }
-        catch {
+        catch (err) {
+            if (err instanceof HttpError)
+                throw err;
             log("[identify] invalid token — unauthenticated");
         }
     }

package/dist/middleware/metrics.d.ts

@@ -0,0 +1,9 @@
+import type { MiddlewareHandler } from "hono";
+import type { AppEnv } from "../lib/context";
+export interface MetricsMiddlewareOptions {
+    /** Paths to exclude from metrics collection. Strings use prefix matching. */
+    excludePaths?: (string | RegExp)[];
+    /** Custom path normalizer to prevent cardinality explosion. */
+    normalizePath?: (path: string) => string;
+}
+export declare const metricsCollector: (options?: MetricsMiddlewareOptions) => MiddlewareHandler<AppEnv>;

package/dist/middleware/metrics.js

@@ -0,0 +1,26 @@
+import { incrementCounter, observeHistogram, defaultNormalizePath } from "../lib/metrics";
+const DEFAULT_EXCLUDE = ["/metrics", "/health", "/docs", "/openapi.json"];
+export const metricsCollector = (options = {}) => {
+    const { excludePaths = DEFAULT_EXCLUDE, normalizePath = defaultNormalizePath, } = options;
+    return async (c, next) => {
+        const rawPath = c.req.path;
+        const excluded = excludePaths.some(p => typeof p === "string" ? rawPath.startsWith(p) : p.test(rawPath));
+        if (excluded)
+            return next();
+        const start = performance.now();
+        await next();
+        const duration = (performance.now() - start) / 1000; // seconds
+        const method = c.req.method;
+        const path = normalizePath(rawPath);
+        const status = String(c.res.status);
+        const tenantId = c.get("tenantId") ?? undefined;
+        const labels = { method, path, status };
+        const durationLabels = { method, path };
+        if (tenantId) {
+            labels.tenant = tenantId;
+            durationLabels.tenant = tenantId;
+        }
+        incrementCounter("http_requests_total", labels);
+        observeHistogram("http_request_duration_seconds", durationLabels, duration);
+    };
+};

package/dist/middleware/requestId.d.ts

@@ -0,0 +1,3 @@
+import type { MiddlewareHandler } from "hono";
+import type { AppEnv } from "../lib/context";
+export declare const requestId: MiddlewareHandler<AppEnv>;

package/dist/middleware/requestId.js

@@ -0,0 +1,7 @@
+import { HEADER_REQUEST_ID } from "../lib/constants";
+export const requestId = async (c, next) => {
+    const id = c.req.header(HEADER_REQUEST_ID) ?? crypto.randomUUID();
+    c.set("requestId", id);
+    await next();
+    c.res.headers.set(HEADER_REQUEST_ID, id);
+};

package/dist/middleware/requestLogger.d.ts

@@ -0,0 +1,38 @@
+import type { MiddlewareHandler } from "hono";
+import type { AppEnv } from "../lib/context";
+export type LogLevel = "info" | "warn" | "error";
+export interface RequestLogEntry {
+    level: LogLevel;
+    time: number;
+    msg: string;
+    requestId: string;
+    method: string;
+    path: string;
+    statusCode: number;
+    responseTime: number;
+    ip: string;
+    userAgent: string | null;
+    userId: string | null;
+    sessionId: string | null;
+    tenantId: string | null;
+    err?: {
+        message: string;
+        stack?: string;
+    };
+}
+export interface RequestLoggerOptions {
+    /** Custom log handler. Default: `console.log(JSON.stringify(entry))`. */
+    onLog?: (entry: RequestLogEntry) => void | Promise<void>;
+    /** Minimum level to emit. Entries below this level are dropped. */
+    level?: LogLevel;
+    /**
+     * Paths to exclude from logging. Strings use **prefix matching**
+     * (`"/health"` matches `/health`, `/health/live`, `/health/ready`).
+     * RegExp entries use `.test()`.
+     * Default: `["/health", "/docs", "/openapi.json"]`.
+     */
+    excludePaths?: (string | RegExp)[];
+    /** HTTP methods to exclude from logging (e.g. `["OPTIONS"]`). */
+    excludeMethods?: string[];
+}
+export declare const requestLogger: (options?: RequestLoggerOptions) => MiddlewareHandler<AppEnv>;

package/dist/middleware/requestLogger.js

@@ -0,0 +1,68 @@
+import { getClientIp } from "../lib/clientIp";
+const LEVEL_ORDER = { info: 0, warn: 1, error: 2 };
+function statusToLevel(status) {
+    if (status >= 500)
+        return "error";
+    if (status >= 400)
+        return "warn";
+    return "info";
+}
+const DEFAULT_EXCLUDE_PATHS = ["/health", "/docs", "/openapi.json", "/metrics"];
+export const requestLogger = (options = {}) => {
+    const { onLog = (entry) => console.log(JSON.stringify(entry)), level: minLevel, excludePaths = DEFAULT_EXCLUDE_PATHS, excludeMethods, } = options;
+    return async (c, next) => {
+        const method = c.req.method;
+        if (excludeMethods?.includes(method)) {
+            return next();
+        }
+        const path = c.req.path;
+        const excluded = excludePaths.some(p => typeof p === "string" ? path.startsWith(p) : p.test(path));
+        if (excluded) {
+            return next();
+        }
+        const start = performance.now();
+        let error;
+        try {
+            await next();
+        }
+        catch (e) {
+            error = e;
+        }
+        const statusCode = error ? 500 : c.res.status;
+        const level = statusToLevel(statusCode);
+        if (minLevel && LEVEL_ORDER[level] < LEVEL_ORDER[minLevel]) {
+            if (error)
+                throw error;
+            return;
+        }
+        const entry = {
+            level,
+            time: Date.now(),
+            msg: `${method} ${path} ${error ? "ERROR" : statusCode}`,
+            requestId: c.get("requestId") ?? "unknown",
+            method,
+            path,
+            statusCode,
+            responseTime: Math.round((performance.now() - start) * 100) / 100,
+            ip: getClientIp(c),
+            userAgent: c.req.header("user-agent") ?? null,
+            userId: c.get("authUserId") ?? null,
+            sessionId: c.get("sessionId") ?? null,
+            tenantId: c.get("tenantId") ?? null,
+        };
+        if (error) {
+            entry.err = {
+                message: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack : undefined,
+            };
+        }
+        try {
+            onLog(entry);
+        }
+        catch {
+            // onLog error isolation — never affect the response
+        }
+        if (error)
+            throw error;
+    };
+};

package/dist/middleware/requestSigning.d.ts

@@ -0,0 +1,20 @@
+import type { MiddlewareHandler } from "hono";
+import type { AppEnv } from "../lib/context";
+export interface RequestSigningOptions {
+    /** Allowed age of the timestamp in milliseconds. Default: 300_000 (5 min). */
+    tolerance?: number;
+    /** Header carrying the HMAC signature. Default: "x-signature". */
+    header?: string;
+    /** Header carrying the Unix timestamp (seconds or ms). Default: "x-timestamp". */
+    timestampHeader?: string;
+}
+/**
+ * Middleware that verifies the client has HMAC-signed the canonical request.
+ *
+ * Canonical string:
+ *   METHOD\nPATH\nCANONICAL_QUERY\nTIMESTAMP\nBODY
+ *
+ * When `signing.requestSigning` is false (or not configured), the middleware
+ * is a no-op pass-through.
+ */
+export declare const requireSignedRequest: (opts?: RequestSigningOptions) => MiddlewareHandler<AppEnv>;

package/dist/middleware/requestSigning.js

@@ -0,0 +1,100 @@
+import { getSigningConfig, getSigningSecret } from "../lib/appConfig";
+import { hmacVerify } from "../lib/signing";
+import { HEADER_SIGNATURE, HEADER_TIMESTAMP } from "../lib/constants";
+import { HttpError } from "../lib/HttpError";
+/**
+ * Canonicalize the query string for signing.
+ *
+ * - Sort params by key, then by value for repeated keys
+ * - Normalize percent-encoding: decode then re-encode via encodeURIComponent
+ *   so that %20 and + both canonicalize to %20 (most common source of
+ *   signature mismatches between clients)
+ * - Returns "" when there are no query params (not omitted — omitting the
+ *   query line would allow ?foo=1 and ?foo=2 to share a valid signature)
+ */
+function canonicalizeQuery(search) {
+    // Remove leading "?"
+    const qs = search.startsWith("?") ? search.slice(1) : search;
+    if (!qs)
+        return "";
+    const pairs = [];
+    for (const part of qs.split("&")) {
+        if (!part)
+            continue;
+        const eqIdx = part.indexOf("=");
+        const rawKey = eqIdx === -1 ? part : part.slice(0, eqIdx);
+        const rawVal = eqIdx === -1 ? "" : part.slice(eqIdx + 1);
+        // Normalize encoding: decode then re-encode
+        const key = encodeURIComponent(decodeURIComponent(rawKey.replace(/\+/g, " ")));
+        const val = encodeURIComponent(decodeURIComponent(rawVal.replace(/\+/g, " ")));
+        pairs.push([key, val]);
+    }
+    // Sort by key, then by value for repeated keys
+    pairs.sort((a, b) => {
+        if (a[0] !== b[0])
+            return a[0] < b[0] ? -1 : 1;
+        return a[1] < b[1] ? -1 : 1;
+    });
+    return pairs.map(([k, v]) => `${k}=${v}`).join("&");
+}
+/**
+ * Middleware that verifies the client has HMAC-signed the canonical request.
+ *
+ * Canonical string:
+ *   METHOD\nPATH\nCANONICAL_QUERY\nTIMESTAMP\nBODY
+ *
+ * When `signing.requestSigning` is false (or not configured), the middleware
+ * is a no-op pass-through.
+ */
+export const requireSignedRequest = (opts) => async (c, next) => {
+    const cfg = getSigningConfig();
+    // No-op when request signing is not enabled
+    if (!cfg?.requestSigning) {
+        await next();
+        return;
+    }
+    const signingOpts = typeof cfg.requestSigning === "object" ? cfg.requestSigning : {};
+    const tolerance = opts?.tolerance ?? signingOpts.tolerance ?? 300_000;
+    const sigHeader = opts?.header ?? signingOpts.header ?? HEADER_SIGNATURE;
+    const tsHeader = opts?.timestampHeader ?? signingOpts.timestampHeader ?? HEADER_TIMESTAMP;
+    // --- Timestamp validation (replay protection) ---
+    const rawTs = c.req.header(tsHeader);
+    const tsNum = rawTs !== undefined ? parseInt(rawTs, 10) : NaN;
+    if (isNaN(tsNum)) {
+        throw new HttpError(401, "Unauthorized", "EXPIRED_TIMESTAMP");
+    }
+    // Auto-detect Unix seconds (< 1e10) vs milliseconds
+    const tsMs = tsNum < 1e10 ? tsNum * 1000 : tsNum;
+    if (Math.abs(Date.now() - tsMs) > tolerance) {
+        throw new HttpError(401, "Unauthorized", "EXPIRED_TIMESTAMP");
+    }
+    // --- Signature header ---
+    const sig = c.req.header(sigHeader);
+    if (!sig) {
+        throw new HttpError(401, "Unauthorized", "INVALID_SIGNATURE");
+    }
+    // --- Secret resolution ---
+    const secret = getSigningSecret();
+    if (!secret) {
+        throw new HttpError(500, "Internal Server Error", "SIGNING_SECRET_MISSING");
+    }
+    // --- Build canonical string ---
+    const method = c.req.method.toUpperCase();
+    const url = new URL(c.req.url);
+    const path = url.pathname;
+    const query = canonicalizeQuery(url.search);
+    const body = await c.req.text();
+    const canonical = `${method}\n${path}\n${query}\n${rawTs}\n${body}`;
+    // --- HMAC verification ---
+    let valid;
+    try {
+        valid = hmacVerify(canonical, sig, secret);
+    }
+    catch {
+        valid = false;
+    }
+    if (!valid) {
+        throw new HttpError(401, "Unauthorized", "INVALID_SIGNATURE");
+    }
+    await next();
+};

package/dist/middleware/requireMfaSetup.d.ts

@@ -0,0 +1,16 @@
+import type { MiddlewareHandler } from "hono";
+import type { AppEnv } from "../lib/context";
+/**
+ * Middleware that blocks authenticated users who have not completed MFA setup.
+ *
+ * When `auth.mfa.required` is `true`, this middleware is applied globally by
+ * `createApp`. It can also be applied per-route for finer control:
+ *
+ * @example
+ * import { requireMfaSetup } from "@lastshotlabs/bunshot";
+ * router.use("/dashboard", userAuth, requireMfaSetup);
+ *
+ * Exempt paths: `/auth/*`, `/health`, `/docs`, `/openapi.json`, and the root `/`.
+ * Unauthenticated requests pass through — use `userAuth` to block those.
+ */
+export declare const requireMfaSetup: MiddlewareHandler<AppEnv>;

package/dist/middleware/requireMfaSetup.js

@@ -0,0 +1,37 @@
+import { getAuthAdapter } from "../lib/authAdapter";
+import { HttpError } from "../lib/HttpError";
+const EXEMPT_PREFIXES = ["/auth/", "/health", "/docs", "/openapi.json"];
+/**
+ * Middleware that blocks authenticated users who have not completed MFA setup.
+ *
+ * When `auth.mfa.required` is `true`, this middleware is applied globally by
+ * `createApp`. It can also be applied per-route for finer control:
+ *
+ * @example
+ * import { requireMfaSetup } from "@lastshotlabs/bunshot";
+ * router.use("/dashboard", userAuth, requireMfaSetup);
+ *
+ * Exempt paths: `/auth/*`, `/health`, `/docs`, `/openapi.json`, and the root `/`.
+ * Unauthenticated requests pass through — use `userAuth` to block those.
+ */
+export const requireMfaSetup = async (c, next) => {
+    const path = c.req.path;
+    // Exempt paths — auth routes (including MFA setup), health, docs, root
+    if (path === "/" || EXEMPT_PREFIXES.some((p) => path.startsWith(p))) {
+        return next();
+    }
+    // Only applies to authenticated users — unauthenticated requests pass through
+    const userId = c.get("authUserId");
+    if (!userId) {
+        return next();
+    }
+    const adapter = getAuthAdapter();
+    if (!adapter.isMfaEnabled) {
+        return next();
+    }
+    const enabled = await adapter.isMfaEnabled(userId);
+    if (!enabled) {
+        throw new HttpError(403, "MFA setup required", "MFA_SETUP_REQUIRED");
+    }
+    return next();
+};

package/dist/middleware/requireRole.d.ts

@@ -4,10 +4,11 @@ import type { AppEnv } from "../lib/context";
  * Middleware factory that enforces role-based access.
  * Requires `identify` to have run first (authUserId must be set).
  *
- * When tenant context exists (`tenantId` set on context), checks tenant-scoped roles.
- * Falls back to app-wide roles when no tenant context is present.
+ * Effective roles = direct roles ∪ group baseline roles ∪ per-membership roles.
  *
- * The adapter must implement `getRoles` (and `getTenantRoles` for tenant-scoped checks).
+ * When tenant context exists (`tenantId` set on context), checks tenant-scoped
+ * direct roles + tenant-scoped group roles.
+ * When no tenant context is present, checks app-wide direct roles + app-wide group roles.
  *
  * @example
  * // Allow any authenticated user with the "admin" role
@@ -21,6 +22,11 @@ export declare const requireRole: ((...roles: string[]) => MiddlewareHandler<App
      * Always checks app-wide roles regardless of tenant context.
      * Use for super-admin gates that should ignore tenant scoping.
      *
+     * SCOPE CONTRACT: only app-wide direct roles + app-wide group roles count here.
+     * Tenant-scoped roles and tenant-scoped group roles are NEVER considered.
+     * A user who is "admin" only in a tenant-scoped group is NOT a global admin —
+     * they must be assigned the role app-wide.
+     *
      * @example
      * app.get("/super-admin", userAuth, requireRole.global("superadmin"), handler)
      */

package/dist/middleware/requireRole.js

@@ -1,12 +1,13 @@
-import { getAuthAdapter } from "../lib/authAdapter";
+import { getEffectiveRoles } from "../lib/groups";
 /**
  * Middleware factory that enforces role-based access.
  * Requires `identify` to have run first (authUserId must be set).
  *
- * When tenant context exists (`tenantId` set on context), checks tenant-scoped roles.
- * Falls back to app-wide roles when no tenant context is present.
+ * Effective roles = direct roles ∪ group baseline roles ∪ per-membership roles.
  *
- * The adapter must implement `getRoles` (and `getTenantRoles` for tenant-scoped checks).
+ * When tenant context exists (`tenantId` set on context), checks tenant-scoped
+ * direct roles + tenant-scoped group roles.
+ * When no tenant context is present, checks app-wide direct roles + app-wide group roles.
  *
  * @example
  * // Allow any authenticated user with the "admin" role
@@ -20,28 +21,10 @@ export const requireRole = Object.assign((...roles) => async (c, next) => {
     if (!userId) {
         return c.json({ error: "Unauthorized" }, 401);
     }
-    const adapter = getAuthAdapter();
-    const tenantId = c.get("tenantId");
-    // When tenant context exists and adapter supports tenant roles, check tenant-scoped roles
-    if (tenantId && adapter.getTenantRoles) {
-        const tenantRoles = await adapter.getTenantRoles(userId, tenantId);
-        const hasRole = roles.some((role) => tenantRoles.includes(role));
-        if (!hasRole) {
-            return c.json({ error: "Forbidden" }, 403);
-        }
-        return next();
-    }
-    // Fall back to app-wide roles
-    let userRoles = c.get("roles");
-    if (userRoles === null) {
-        if (!adapter.getRoles) {
-            throw new Error("requireRole used but auth adapter does not implement getRoles");
-        }
-        userRoles = await adapter.getRoles(userId);
-        c.set("roles", userRoles);
-    }
-    const hasRole = roles.some((role) => userRoles.includes(role));
-    if (!hasRole) {
+    const tenantId = c.get("tenantId") ?? null;
+    const effective = await getEffectiveRoles(userId, tenantId);
+    c.set("roles", effective);
+    if (!roles.some((r) => effective.includes(r))) {
         return c.json({ error: "Forbidden" }, 403);
     }
     await next();
@@ -50,6 +33,11 @@ export const requireRole = Object.assign((...roles) => async (c, next) => {
      * Always checks app-wide roles regardless of tenant context.
      * Use for super-admin gates that should ignore tenant scoping.
      *
+     * SCOPE CONTRACT: only app-wide direct roles + app-wide group roles count here.
+     * Tenant-scoped roles and tenant-scoped group roles are NEVER considered.
+     * A user who is "admin" only in a tenant-scoped group is NOT a global admin —
+     * they must be assigned the role app-wide.
+     *
      * @example
      * app.get("/super-admin", userAuth, requireRole.global("superadmin"), handler)
      */
@@ -58,17 +46,16 @@ export const requireRole = Object.assign((...roles) => async (c, next) => {
         if (!userId) {
             return c.json({ error: "Unauthorized" }, 401);
         }
-        let userRoles = c.get("roles");
-        if (userRoles === null) {
-            const adapter = getAuthAdapter();
-            if (!adapter.getRoles) {
-                throw new Error("requireRole.global used but auth adapter does not implement getRoles");
-            }
-            userRoles = await adapter.getRoles(userId);
-            c.set("roles", userRoles);
+        // In development, log when tenant context is present but intentionally ignored.
+        // console.info is used deliberately: console.debug is suppressed by default in most
+        // runtimes, so info gives reliably visible output during development without being
+        // noisy in production (this branch never executes there).
+        if (process.env.NODE_ENV !== "production" && c.get("tenantId")) {
+            console.info("[requireRole.global] tenant context present but intentionally ignored — checking app-wide roles only");
         }
-        const hasRole = roles.some((role) => userRoles.includes(role));
-        if (!hasRole) {
+        const effective = await getEffectiveRoles(userId, null);
+        c.set("roles", effective);
+        if (!roles.some((r) => effective.includes(r))) {
             return c.json({ error: "Forbidden" }, 403);
         }
         await next();

package/dist/middleware/requireScope.d.ts

@@ -0,0 +1,10 @@
+import type { MiddlewareHandler } from "hono";
+import type { AppEnv } from "../lib/context";
+/**
+ * Middleware that requires the JWT to contain all specified scopes.
+ * Reads scope from `tokenPayload.scope` (set by identify middleware).
+ *
+ * @example
+ * router.get("/data", requireScope("read:data"), handler);
+ */
+export declare const requireScope: (...requiredScopes: string[]) => MiddlewareHandler<AppEnv>;

package/dist/middleware/requireScope.js

@@ -0,0 +1,25 @@
+import { HttpError } from "../lib/HttpError";
+/**
+ * Middleware that requires the JWT to contain all specified scopes.
+ * Reads scope from `tokenPayload.scope` (set by identify middleware).
+ *
+ * @example
+ * router.get("/data", requireScope("read:data"), handler);
+ */
+export const requireScope = (...requiredScopes) => async (c, next) => {
+    const payload = c.get("tokenPayload");
+    if (!payload) {
+        throw new HttpError(401, "Authentication required");
+    }
+    const scope = payload.scope;
+    if (!scope) {
+        throw new HttpError(403, "Insufficient scope", "INSUFFICIENT_SCOPE");
+    }
+    const grantedScopes = scope.split(" ");
+    for (const required of requiredScopes) {
+        if (!grantedScopes.includes(required)) {
+            throw new HttpError(403, "Insufficient scope", "INSUFFICIENT_SCOPE");
+        }
+    }
+    await next();
+};

package/dist/middleware/requireStepUp.d.ts

@@ -0,0 +1,18 @@
+import type { MiddlewareHandler } from "hono";
+import type { AppEnv } from "../lib/context";
+export interface StepUpOptions {
+    /** Max age in seconds since last MFA verification. Default: 300 (5 min). */
+    maxAge?: number;
+}
+/**
+ * Middleware that requires the user to have recently completed step-up MFA.
+ *
+ * Attach to sensitive routes that require fresh MFA verification:
+ * ```
+ * router.post("/transfer", userAuth, requireStepUp(), transferHandler);
+ * ```
+ *
+ * The user completes step-up via POST /auth/step-up.
+ * After successful step-up, mfaVerifiedAt is stored in their session.
+ */
+export declare const requireStepUp: (opts?: StepUpOptions) => MiddlewareHandler<AppEnv>;