@lastshotlabs/bunshot 0.0.20 → 0.0.25

package/dist/middleware/identify.js

@@ -1,9 +1,21 @@
 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 { getTrackLastActive, getSigningConfig } from "../lib/appConfig";
+import { getClientIp } from "../lib/clientIp";
+import { sha256 } from "../lib/crypto";
+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);
@@ -22,13 +34,49 @@ export const identify = async (c, next) => {
                 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}`);
-                        });
+                    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 fingerprint for sessionId=${sessionId}`);
+                            });
+                            c.set("authUserId", payload.sub);
+                            c.set("sessionId", sessionId);
+                        }
+                        else if (storedFp === current) {
+                            c.set("authUserId", payload.sub);
+                            c.set("sessionId", sessionId);
+                        }
+                        else {
+                            log(`[identify] fingerprint mismatch for sessionId=${sessionId} onMismatch=${onMismatch}`);
+                            if (onMismatch === "reject") {
+                                return c.json({ error: "Unauthorized", code: "FINGERPRINT_MISMATCH" }, 401);
+                            }
+                            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")) {
+                        log(`[identify] authUserId=${payload.sub} sessionId=${sessionId}`);
+                        if (getTrackLastActive()) {
+                            updateSessionLastActive(sessionId).catch(() => {
+                                log(`[identify] failed to update lastActiveAt for sessionId=${sessionId}`);
+                            });
+                        }
                     }
                 }
                 else {

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,99 @@
+import { getSigningConfig, getSigningSecret } from "../lib/appConfig";
+import { hmacVerify } from "../lib/signing";
+import { HEADER_SIGNATURE, HEADER_TIMESTAMP } from "../lib/constants";
+/**
+ * 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)) {
+        return c.json({ error: "Unauthorized", code: "EXPIRED_TIMESTAMP" }, 401);
+    }
+    // Auto-detect Unix seconds (< 1e10) vs milliseconds
+    const tsMs = tsNum < 1e10 ? tsNum * 1000 : tsNum;
+    if (Math.abs(Date.now() - tsMs) > tolerance) {
+        return c.json({ error: "Unauthorized", code: "EXPIRED_TIMESTAMP" }, 401);
+    }
+    // --- Signature header ---
+    const sig = c.req.header(sigHeader);
+    if (!sig) {
+        return c.json({ error: "Unauthorized", code: "INVALID_SIGNATURE" }, 401);
+    }
+    // --- Secret resolution ---
+    const secret = getSigningSecret();
+    if (!secret) {
+        return c.json({ error: "Internal Server Error", code: "SIGNING_SECRET_MISSING" }, 500);
+    }
+    // --- 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) {
+        return c.json({ error: "Unauthorized", code: "INVALID_SIGNATURE" }, 401);
+    }
+    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,36 @@
+import { getAuthAdapter } from "../lib/authAdapter";
+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) {
+        return c.json({ error: "MFA setup required", code: "MFA_SETUP_REQUIRED" }, 403);
+    }
+    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/upload.d.ts

@@ -0,0 +1,5 @@
+import type { MiddlewareHandler } from "hono";
+import type { AppEnv } from "../lib/context";
+import type { UploadOpts } from "../lib/upload";
+export type UploadMiddlewareOptions = UploadOpts;
+export declare const handleUpload: (opts?: UploadMiddlewareOptions) => MiddlewareHandler<AppEnv>;

package/dist/middleware/upload.js

@@ -0,0 +1,27 @@
+import { parseUpload, getUploadConfig } from "../lib/upload";
+export const handleUpload = (opts) => {
+    return async (c, next) => {
+        const config = getUploadConfig();
+        const merged = { ...config, ...opts };
+        const maxFileSize = merged.maxFileSize ?? 10 * 1024 * 1024;
+        const maxFiles = merged.maxFiles ?? 10;
+        // Content-Length pre-check to avoid Bun killing the connection
+        const contentLength = Number(c.req.header("content-length") ?? 0);
+        if (contentLength > 0 && contentLength > maxFileSize * maxFiles) {
+            return c.json({ error: `Request body too large. Maximum is ${maxFileSize * maxFiles} bytes` }, 413);
+        }
+        let results;
+        try {
+            results = await parseUpload(c, opts);
+        }
+        catch (err) {
+            if (err?.status === 400)
+                return c.json({ error: err.message }, 400);
+            if (err?.status === 413)
+                return c.json({ error: err.message }, 413);
+            throw err;
+        }
+        c.set("uploadResults", results);
+        await next();
+    };
+};

package/dist/middleware/webhookAuth.d.ts

@@ -0,0 +1,30 @@
+import type { MiddlewareHandler, Context } from "hono";
+import type { AppEnv } from "../lib/context";
+export interface WebhookTimestampOptions {
+    /** Header name containing the Unix timestamp (seconds or ms). */
+    header: string;
+    /**
+     * Allowed age of the timestamp in milliseconds.
+     * Values below 1e10 in the header are treated as Unix seconds and auto-converted.
+     */
+    tolerance: number;
+}
+export interface WebhookAuthOptions {
+    /**
+     * Shared HMAC secret. Pass a function for dynamic resolution
+     * (e.g. per-tenant secret lookup). If the function throws, a 500 is returned.
+     */
+    secret: string | ((c: Context<AppEnv>) => string | Promise<string>);
+    /** Header that carries the signature. Default: `"x-webhook-signature"`. */
+    header?: string;
+    /** HMAC algorithm. Default: `"sha256"`. */
+    algorithm?: "sha256" | "sha512" | "sha1";
+    /**
+     * Strip this prefix from the signature header value before comparing.
+     * e.g. `"sha256="` for GitHub-style `X-Hub-Signature-256: sha256=<hex>`.
+     */
+    prefix?: string;
+    /** Optional replay-protection via a timestamp header. */
+    timestamp?: WebhookTimestampOptions;
+}
+export declare const webhookAuth: (options: WebhookAuthOptions) => MiddlewareHandler<AppEnv>;

package/dist/middleware/webhookAuth.js

@@ -0,0 +1,57 @@
+import { createHmac } from "crypto";
+import { timingSafeEqual } from "../lib/crypto";
+export const webhookAuth = (options) => async (c, next) => {
+    const algorithm = options.algorithm ?? "sha256";
+    const sigHeader = options.header ?? "x-webhook-signature";
+    // --- Optional timestamp replay protection ---
+    if (options.timestamp) {
+        const { header: tsHeader, tolerance } = options.timestamp;
+        const rawTs = c.req.header(tsHeader);
+        const tsNum = rawTs !== undefined ? parseInt(rawTs, 10) : NaN;
+        if (isNaN(tsNum)) {
+            return c.json({ error: "Unauthorized", code: "EXPIRED_TIMESTAMP" }, 401);
+        }
+        // Auto-detect Unix seconds (< 1e10) vs milliseconds
+        const tsMs = tsNum < 1e10 ? tsNum * 1000 : tsNum;
+        if (Math.abs(Date.now() - tsMs) > tolerance) {
+            return c.json({ error: "Unauthorized", code: "EXPIRED_TIMESTAMP" }, 401);
+        }
+    }
+    // --- Signature header ---
+    const rawSig = c.req.header(sigHeader);
+    if (!rawSig) {
+        return c.json({ error: "Unauthorized", code: "INVALID_SIGNATURE" }, 401);
+    }
+    const provided = options.prefix && rawSig.startsWith(options.prefix)
+        ? rawSig.slice(options.prefix.length)
+        : rawSig;
+    // --- Secret resolution ---
+    let secret;
+    if (typeof options.secret === "function") {
+        try {
+            secret = await options.secret(c);
+        }
+        catch {
+            return c.json({ error: "Internal Server Error", code: "WEBHOOK_SECRET_ERROR" }, 500);
+        }
+    }
+    else {
+        secret = options.secret;
+    }
+    // --- Body reading (Hono caches this — downstream c.req.json() still works) ---
+    const body = await c.req.text();
+    // --- HMAC computation & comparison ---
+    const computed = createHmac(algorithm, secret).update(body).digest("hex");
+    let valid;
+    try {
+        valid = timingSafeEqual(computed, provided);
+    }
+    catch {
+        // timingSafeEqual can throw if buffer byte lengths differ (e.g. multi-byte Unicode in sig)
+        valid = false;
+    }
+    if (!valid) {
+        return c.json({ error: "Unauthorized", code: "INVALID_SIGNATURE" }, 401);
+    }
+    await next();
+};