@lastshotlabs/bunshot 0.0.25 → 0.0.28

package/dist/src/framework/lib/wsMessages.d.ts

@@ -0,0 +1,25 @@
+import type { RoomPersistenceConfig, StoredMessage, WsMessageDefaults } from '../../../packages/bunshot-core/src/index.js';
+export type { StoredMessage, WsMessageDefaults, RoomPersistenceConfig };
+export type WsMessageStore = 'redis' | 'mongo' | 'sqlite' | 'memory';
+/**
+ * Persist a message to a room. Returns null if room is not configured for persistence.
+ * On store errors, logs a warning and returns null (non-blocking).
+ */
+export declare const persistMessage: (endpoint: string, room: string, data: {
+    senderId?: string | null;
+    payload: unknown;
+}, app: object) => Promise<StoredMessage | null>;
+/**
+ * Get message history for a room.
+ * Cursor-based pagination using message `id` as cursor.
+ */
+export declare const getMessageHistory: (endpoint: string, room: string, opts: {
+    limit?: number;
+    before?: string;
+    after?: string;
+} | undefined, app: object) => Promise<StoredMessage[]>;
+/**
+ * Opt a room into message persistence.
+ * Delegates to persistence.configureRoom() on the context.
+ */
+export declare const configureRoom: (endpoint: string, room: string, options: RoomPersistenceConfig, app: object) => void;

package/dist/src/framework/lib/wsMessages.js

@@ -0,0 +1,45 @@
+import { getContext } from '../../../packages/bunshot-core/src/index.js';
+// ---------------------------------------------------------------------------
+// Public API — requires app context
+// ---------------------------------------------------------------------------
+/**
+ * Persist a message to a room. Returns null if room is not configured for persistence.
+ * On store errors, logs a warning and returns null (non-blocking).
+ */
+export const persistMessage = async (endpoint, room, data, app) => {
+    const ctx = getContext(app);
+    const persistence = ctx.persistence;
+    const config = persistence.getRoomConfig(endpoint, room);
+    if (!config)
+        return null;
+    const message = {
+        id: crypto.randomUUID(),
+        endpoint,
+        room,
+        senderId: data.senderId ?? null,
+        payload: data.payload,
+        createdAt: Date.now(),
+    };
+    try {
+        return await persistence.wsMessages.persist(message, config);
+    }
+    catch (err) {
+        console.warn(`[wsMessages] failed to persist message to ${endpoint}${room}:`, err);
+        return null;
+    }
+};
+/**
+ * Get message history for a room.
+ * Cursor-based pagination using message `id` as cursor.
+ */
+export const getMessageHistory = async (endpoint, room, opts, app) => {
+    return getContext(app).persistence.wsMessages.getHistory(endpoint, room, opts);
+};
+/**
+ * Opt a room into message persistence.
+ * Delegates to persistence.configureRoom() on the context.
+ */
+export const configureRoom = (endpoint, room, options, app) => {
+    const ctx = getContext(app);
+    ctx.persistence.configureRoom(endpoint, room, options);
+};

package/dist/src/framework/lib/wsNamespace.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Produces a collision-safe composite key for scoping rooms to an endpoint.
+ *
+ * Both endpoint and room are percent-encoded before joining with `:`.
+ * Since encodeURIComponent encodes `:` → `%3A`, the literal `:` separator
+ * can only come from this function — not from endpoint or room values.
+ *
+ * Examples:
+ *   wsEndpointKey("/chat", "general")     → "%2Fchat:general"
+ *   wsEndpointKey("/chat", "room:1")      → "%2Fchat:room%3A1"
+ *   wsEndpointKey("/a:b", "c")            → "%2Fa%3Ab:c"
+ *   wsEndpointKey("/notifications", "x")  → "%2Fnotifications:x"
+ *
+ * Used for: in-memory room maps, Redis channel names, Redis message keys.
+ * NOT used for: SQLite or MongoDB schemas (those store endpoint + room separately).
+ */
+export declare function wsEndpointKey(endpoint: string, room: string): string;

package/dist/src/framework/lib/wsNamespace.js

@@ -0,0 +1,19 @@
+/**
+ * Produces a collision-safe composite key for scoping rooms to an endpoint.
+ *
+ * Both endpoint and room are percent-encoded before joining with `:`.
+ * Since encodeURIComponent encodes `:` → `%3A`, the literal `:` separator
+ * can only come from this function — not from endpoint or room values.
+ *
+ * Examples:
+ *   wsEndpointKey("/chat", "general")     → "%2Fchat:general"
+ *   wsEndpointKey("/chat", "room:1")      → "%2Fchat:room%3A1"
+ *   wsEndpointKey("/a:b", "c")            → "%2Fa%3Ab:c"
+ *   wsEndpointKey("/notifications", "x")  → "%2Fnotifications:x"
+ *
+ * Used for: in-memory room maps, Redis channel names, Redis message keys.
+ * NOT used for: SQLite or MongoDB schemas (those store endpoint + room separately).
+ */
+export function wsEndpointKey(endpoint, room) {
+    return `${encodeURIComponent(endpoint)}:${encodeURIComponent(room)}`;
+}

package/dist/src/framework/lib/wsPresence.d.ts

@@ -0,0 +1,17 @@
+import type { WsState } from '../../../packages/bunshot-core/src/index.js';
+export declare const trackSocket: (state: WsState, socketId: string, userId: string | null) => void;
+export declare const untrackSocket: (state: WsState, socketId: string) => void;
+export declare const addPresence: (state: WsState, socketId: string, endpoint: string, room: string) => {
+    userId: string;
+    isNewUser: boolean;
+} | null;
+export declare const removePresence: (state: WsState, socketId: string, endpoint: string, room: string) => {
+    userId: string;
+    isLastSocket: boolean;
+} | null;
+export declare const cleanupPresence: (state: WsState, socketId: string, endpoint: string, rooms: Set<string>) => Array<{
+    room: string;
+    userId: string;
+}>;
+export declare const getRoomPresence: (state: WsState, endpoint: string, room: string) => string[];
+export declare const getUserPresence: (state: WsState, userId: string) => string[];

package/dist/src/framework/lib/wsPresence.js

@@ -0,0 +1,84 @@
+import { wsEndpointKey } from './wsNamespace';
+export const trackSocket = (state, socketId, userId) => {
+    if (!userId)
+        return;
+    state.socketUsers.set(socketId, userId);
+};
+export const untrackSocket = (state, socketId) => {
+    state.socketUsers.delete(socketId);
+};
+export const addPresence = (state, socketId, endpoint, room) => {
+    const userId = state.socketUsers.get(socketId);
+    if (!userId)
+        return null;
+    const key = wsEndpointKey(endpoint, room);
+    if (!state.roomPresence.has(key))
+        state.roomPresence.set(key, new Map());
+    const roomMap = state.roomPresence.get(key);
+    const isNewUser = !roomMap.has(userId) || roomMap.get(userId).size === 0;
+    if (!roomMap.has(userId))
+        roomMap.set(userId, new Set());
+    roomMap.get(userId).add(socketId);
+    return { userId, isNewUser };
+};
+export const removePresence = (state, socketId, endpoint, room) => {
+    const userId = state.socketUsers.get(socketId);
+    if (!userId)
+        return null;
+    const key = wsEndpointKey(endpoint, room);
+    const roomMap = state.roomPresence.get(key);
+    if (!roomMap)
+        return null;
+    const sockets = roomMap.get(userId);
+    if (!sockets)
+        return null;
+    sockets.delete(socketId);
+    const isLastSocket = sockets.size === 0;
+    if (isLastSocket) {
+        roomMap.delete(userId);
+        if (roomMap.size === 0)
+            state.roomPresence.delete(key);
+    }
+    return { userId, isLastSocket };
+};
+export const cleanupPresence = (state, socketId, endpoint, rooms) => {
+    const userId = state.socketUsers.get(socketId);
+    if (!userId)
+        return [];
+    const departed = [];
+    for (const room of rooms) {
+        const key = wsEndpointKey(endpoint, room);
+        const roomMap = state.roomPresence.get(key);
+        if (!roomMap)
+            continue;
+        const sockets = roomMap.get(userId);
+        if (!sockets)
+            continue;
+        sockets.delete(socketId);
+        if (sockets.size === 0) {
+            roomMap.delete(userId);
+            if (roomMap.size === 0)
+                state.roomPresence.delete(key);
+            departed.push({ room, userId });
+        }
+    }
+    return departed;
+};
+export const getRoomPresence = (state, endpoint, room) => {
+    const roomMap = state.roomPresence.get(wsEndpointKey(endpoint, room));
+    if (!roomMap)
+        return [];
+    return [...roomMap.keys()];
+};
+export const getUserPresence = (state, userId) => {
+    const rooms = [];
+    for (const [key, roomMap] of state.roomPresence) {
+        const sockets = roomMap.get(userId);
+        if (sockets && sockets.size > 0) {
+            const colonIdx = key.indexOf(':');
+            if (colonIdx !== -1)
+                rooms.push(decodeURIComponent(key.slice(colonIdx + 1)));
+        }
+    }
+    return rooms;
+};

package/dist/src/framework/lib/wsTransport.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pluggable transport for cross-instance WebSocket message delivery.
+ *
+ * `publish()` is called on every room broadcast — the transport fans out
+ * the message to other server instances (e.g. via Redis pub/sub).
+ *
+ * `connect()` is called once at server startup. The `onMessage` callback
+ * should be invoked when a message arrives from another instance —
+ * it will be delivered to local sockets via Bun's native `server.publish()`.
+ *
+ * `disconnect()` is called on graceful shutdown.
+ */
+export interface WsTransportAdapter {
+    /**
+     * Fan out a message to other instances.
+     * Called on every `publish()` in ws.ts — must be non-blocking.
+     * Errors are caught and logged by the caller; they never break local delivery.
+     * @param origin — unique ID of the publishing instance (for self-echo filtering)
+     */
+    publish(endpoint: string, room: string, message: string, origin: string): Promise<void>;
+    /**
+     * Connect to the transport backend.
+     * @param onMessage — call this when a message arrives from the transport.
+     *   Includes `origin` so the caller can skip self-echo.
+     */
+    connect(onMessage: (endpoint: string, room: string, message: string, origin: string) => void): Promise<void>;
+    /** Disconnect from the transport backend. Called on SIGTERM/SIGINT. */
+    disconnect(): Promise<void>;
+}
+/**
+ * Default no-op transport. Single-instance — all messages go through
+ * Bun's native `server.publish()` only. No cross-instance delivery.
+ */
+export declare class InMemoryTransport implements WsTransportAdapter {
+    publish(_endpoint: string, _room: string, _message: string, _origin: string): Promise<void>;
+    connect(_onMessage: (endpoint: string, room: string, message: string, origin: string) => void): Promise<void>;
+    disconnect(): Promise<void>;
+}

package/dist/src/framework/lib/wsTransport.js

@@ -0,0 +1,9 @@
+/**
+ * Default no-op transport. Single-instance — all messages go through
+ * Bun's native `server.publish()` only. No cross-instance delivery.
+ */
+export class InMemoryTransport {
+    async publish(_endpoint, _room, _message, _origin) { }
+    async connect(_onMessage) { }
+    async disconnect() { }
+}

package/dist/{lib → src/framework/lib}/zodToMongoose.d.ts

@@ -1,4 +1,4 @@
-import type { Schema as SchemaType } from "mongoose";
+import type { Schema as SchemaType } from 'mongoose';
 type ZodSchema = any;
 export type ZodToMongooseRefConfig = {
     /** DB field name (e.g., "account") */

package/dist/{lib → src/framework/lib}/zodToMongoose.js

@@ -1,19 +1,19 @@
-import { mongoose } from "./mongo";
+import { getMongooseModule } from '../../lib/mongo';
 /** Unwrap nullable, optional, and default wrappers to get the core Zod type */
 function unwrap(zodType) {
     let t = zodType;
     let required = true;
     while (true) {
         const defType = t._zod?.def?.type;
-        if (defType === "nullable") {
+        if (defType === 'nullable') {
             t = t._zod.def.innerType;
             required = false;
         }
-        else if (defType === "optional") {
+        else if (defType === 'optional') {
             t = t._zod.def.innerType;
             required = false;
         }
-        else if (defType === "default") {
+        else if (defType === 'default') {
             t = t._zod.def.innerType;
             required = false;
         }
@@ -24,21 +24,21 @@ function unwrap(zodType) {
 }
 /** Lazily access the Mongoose Schema class (avoids top-level require of mongoose) */
 function getSchema() {
-    return mongoose.Schema;
+    return getMongooseModule().Schema;
 }
 /** Convert a single Zod type to a Mongoose field definition */
 function toMongooseField(zodType) {
     const { core, required } = unwrap(zodType);
     const defType = core._zod?.def?.type;
-    if (defType === "string")
+    if (defType === 'string')
         return { type: String, required };
-    if (defType === "number")
+    if (defType === 'number')
         return { type: Number, required };
-    if (defType === "boolean")
+    if (defType === 'boolean')
         return { type: Boolean, required };
-    if (defType === "date")
+    if (defType === 'date')
         return { type: Date, required };
-    if (defType === "enum")
+    if (defType === 'enum')
         return { type: String, enum: core.options, required };
     return { type: getSchema().Types.Mixed, required };
 }
@@ -64,7 +64,7 @@ export function zodToMongoose(zodSchema, config = {}) {
     const shape = zodSchema.shape;
     const fields = {};
     for (const [apiField, zodType] of Object.entries(shape)) {
-        if (apiField === "id")
+        if (apiField === 'id')
             continue;
         if (config.refs?.[apiField]) {
             const { dbField, ref } = config.refs[apiField];

package/dist/{middleware → src/framework/middleware}/auditLog.d.ts

@@ -1,7 +1,8 @@
-import type { MiddlewareHandler, Context } from "hono";
-import type { AppEnv } from "../lib/context";
-import type { AuditLogEntry, AuditLogOptions } from "../lib/auditLog";
+import type { AuditLogOptions } from '../lib/auditLog';
+import type { Context, MiddlewareHandler } from 'hono';
+import type { AppEnv, AuditLogEntry, AuditLogProvider } from '../../../packages/bunshot-core/src/index.js';
 export interface AuditLogMiddlewareOptions extends AuditLogOptions {
+    provider?: AuditLogProvider;
     exclude?: {
         /** Skip logging for requests with these HTTP methods (e.g. `["GET", "HEAD"]`). */
         methods?: string[];

package/dist/src/framework/middleware/auditLog.js

@@ -0,0 +1,42 @@
+import { createAuditLogProvider } from '../lib/auditLog';
+import { getClientIp } from '../../../packages/bunshot-core/src/index.js';
+export const auditLog = (options) => {
+    const provider = options.provider ?? createAuditLogProvider(options);
+    return async (c, next) => {
+        await next();
+        // Exclusion checks run after next() intentionally — c.res.status is only available
+        // after the route handler runs. The route still executes; we're only skipping the log write.
+        if (options.exclude?.methods?.includes(c.req.method))
+            return;
+        // Note: if exclude.paths grows large, regex evaluation on every request adds up.
+        // For high-traffic exclusions, prefer string matching over regex.
+        const path = c.req.path;
+        if (options.exclude?.paths?.some(p => (typeof p === 'string' ? p === path : p.test(path))))
+            return;
+        let entry = {
+            id: crypto.randomUUID(),
+            requestId: c.get('requestId') ?? undefined,
+            userId: c.get('authUserId') ?? null,
+            sessionId: c.get('sessionId') ?? null,
+            tenantId: c.get('tenantId') ?? null,
+            method: c.req.method,
+            path,
+            status: c.res.status,
+            ip: getClientIp(c),
+            userAgent: c.req.header('user-agent') ?? null,
+            createdAt: new Date().toISOString(),
+        };
+        if (options.onEntry) {
+            try {
+                entry = await options.onEntry(entry, c);
+            }
+            catch (err) {
+                console.error('[auditLog] onEntry hook threw:', err);
+            }
+        }
+        // Fire-and-forget — never block the response; logAuditEntry also swallows errors internally
+        provider.logEntry(entry).catch((err) => {
+            console.error('[auditLog] write failed:', err);
+        });
+    };
+};

package/dist/{middleware → src/framework/middleware}/botProtection.d.ts

@@ -1,4 +1,4 @@
-import type { MiddlewareHandler } from "hono";
+import type { MiddlewareHandler } from 'hono';
 export interface BotProtectionOptions {
     /**
      * List of IPv4 CIDRs (e.g. "198.51.100.0/24"), IPv4 exact addresses,
@@ -6,4 +6,4 @@ export interface BotProtectionOptions {
      */
     blockList?: string[];
 }
-export declare const botProtection: ({ blockList, }: BotProtectionOptions) => MiddlewareHandler;
+export declare const botProtection: ({ blockList }: BotProtectionOptions) => MiddlewareHandler;

package/dist/{middleware → src/framework/middleware}/botProtection.js

@@ -1,14 +1,13 @@
-import { getClientIp } from "../lib/clientIp";
+import { getClientIp } from '../../../packages/bunshot-core/src/index.js';
 // ---------------------------------------------------------------------------
 // CIDR helpers (IPv4 only; IPv6 exact-match supported)
 // ---------------------------------------------------------------------------
 function ipv4ToUint32(ip) {
-    const parts = ip.split(".").map(Number);
-    return (((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>>
-        0);
+    const parts = ip.split('.').map(Number);
+    return ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0;
 }
 function cidrMatchesIpv4(cidr, ip) {
-    const slash = cidr.indexOf("/");
+    const slash = cidr.indexOf('/');
     const network = slash === -1 ? cidr : cidr.slice(0, slash);
     const prefixLen = slash === -1 ? 32 : parseInt(cidr.slice(slash + 1), 10);
     const mask = prefixLen === 0 ? 0 : (~0 << (32 - prefixLen)) >>> 0;
@@ -17,7 +16,7 @@ function cidrMatchesIpv4(cidr, ip) {
 const IPV4_RE = /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}/;
 function normalizeIp(ip) {
     // Strip IPv4-mapped IPv6 prefix (::ffff:1.2.3.4)
-    if (ip.startsWith("::ffff:"))
+    if (ip.startsWith('::ffff:'))
         return ip.slice(7);
     return ip;
 }
@@ -37,13 +36,13 @@ function isBlocked(ip, blockList) {
     }
     return false;
 }
-export const botProtection = ({ blockList = [], }) => {
+export const botProtection = ({ blockList = [] }) => {
     if (blockList.length === 0)
         return (_c, next) => next();
     return async (c, next) => {
         const ip = getClientIp(c);
-        if (ip !== "unknown" && isBlocked(ip, blockList)) {
-            return c.json({ error: "Forbidden" }, 403);
+        if (ip !== 'unknown' && isBlocked(ip, blockList)) {
+            return c.json({ error: 'Forbidden' }, 403);
         }
         await next();
     };

package/dist/src/framework/middleware/cacheResponse.d.ts

@@ -0,0 +1,35 @@
+import type { MiddlewareHandler } from 'hono';
+import type { Connection } from 'mongoose';
+import type { AppEnv } from '../../../packages/bunshot-core/src/index.js';
+import type { CacheStoreName } from '../../../packages/bunshot-core/src/index.js';
+interface CacheDoc {
+    key: string;
+    value: string;
+    expiresAt?: Date;
+}
+/**
+ * Get or create the Mongoose CacheEntry model on the given connection.
+ * Accepts connection and mongoose module as parameters — no module-level state.
+ */
+export declare function getCacheModel(conn?: Connection): import('mongoose').Model<CacheDoc>;
+type CacheStore = CacheStoreName;
+/**
+ * Delete a cached entry by exact key across ALL cache backends.
+ *
+ * Requires an app reference so cache invalidation uses the correct instance-owned adapters.
+ */
+export declare const bustCache: (key: string, app: object) => Promise<void>;
+/**
+ * Delete cached entries matching a glob pattern across ALL cache backends.
+ *
+ * Same defense-in-depth rationale as `bustCache` — see comment above.
+ */
+export declare const bustCachePattern: (pattern: string, app: object) => Promise<void>;
+type KeyFn = (c: Parameters<MiddlewareHandler<any>>[0]) => string;
+interface CacheOptions {
+    ttl?: number;
+    key: string | KeyFn;
+    store?: CacheStore;
+}
+export declare const cacheResponse: ({ ttl, key, store: storeOverride, }: CacheOptions) => MiddlewareHandler<AppEnv>;
+export {};

package/dist/src/framework/middleware/cacheResponse.js

@@ -0,0 +1,126 @@
+import { getMongooseModule } from '../../lib/mongo';
+import { getBunshotCtx, getCacheAdapter, getCacheAdapterOrNull } from '../../../packages/bunshot-core/src/index.js';
+/**
+ * Get or create the Mongoose CacheEntry model on the given connection.
+ * Accepts connection and mongoose module as parameters — no module-level state.
+ */
+export function getCacheModel(conn) {
+    // When called without args (from registerBoundaryAdapters), the model
+    // must already be registered on the connection from a prior call.
+    // This is a lazy model that gets created on first use with a connection.
+    if (!conn) {
+        // Fallback: the model must have been registered already on some connection.
+        // This path is only hit from registerBoundaryAdapters where appConnection is passed
+        // through the closure. We need to accept the connection as parameter.
+        throw new Error('getCacheModel requires a connection parameter');
+    }
+    if (conn.models['CacheEntry'])
+        return conn.models['CacheEntry'];
+    const mg = getMongooseModule();
+    const { Schema } = mg;
+    const cacheSchema = new Schema({
+        key: { type: String, required: true, unique: true },
+        value: { type: String, required: true },
+        expiresAt: { type: Date, index: { expireAfterSeconds: 0 } },
+    }, { collection: 'cache_entries' });
+    return conn.model('CacheEntry', cacheSchema);
+}
+async function storeGet(ctx, store, cacheKey) {
+    const adapter = getCacheAdapter(ctx, store);
+    if (!adapter.isReady()) {
+        throw new Error(`cacheResponse: store "${store}" is not ready.`);
+    }
+    return adapter.get(cacheKey);
+}
+async function storeSet(ctx, store, cacheKey, value, ttl) {
+    const adapter = getCacheAdapter(ctx, store);
+    if (!adapter.isReady()) {
+        throw new Error(`cacheResponse: store "${store}" is not ready.`);
+    }
+    await adapter.set(cacheKey, value, ttl);
+}
+async function storeDel(app, store, cacheKey) {
+    const adapter = getCacheAdapterOrNull(app, store);
+    if (!adapter?.isReady())
+        return;
+    await adapter.del(cacheKey);
+}
+async function storeDelPattern(app, store, fullPattern) {
+    const adapter = getCacheAdapterOrNull(app, store);
+    if (!adapter?.isReady())
+        return;
+    await adapter.delPattern(fullPattern);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Delete a cached entry by exact key across ALL cache backends.
+ *
+ * Requires an app reference so cache invalidation uses the correct instance-owned adapters.
+ */
+export const bustCache = async (key, app) => {
+    const { getContext } = await import('../../../packages/bunshot-core/src/index.js');
+    const ctx = getContext(app);
+    const appName = ctx.config.appName;
+    const cacheKey = `cache:${appName}:${key}`;
+    const stores = [...ctx.cacheAdapters.keys()];
+    await Promise.all(stores.map(store => storeDel(app, store, cacheKey)));
+};
+/**
+ * Delete cached entries matching a glob pattern across ALL cache backends.
+ *
+ * Same defense-in-depth rationale as `bustCache` — see comment above.
+ */
+export const bustCachePattern = async (pattern, app) => {
+    const { getContext } = await import('../../../packages/bunshot-core/src/index.js');
+    const ctx = getContext(app);
+    const appName = ctx.config.appName;
+    const fullPattern = `cache:${appName}:${pattern}`;
+    const stores = [...ctx.cacheAdapters.keys()];
+    await Promise.all(stores.map(store => storeDelPattern(app, store, fullPattern)));
+};
+/** Headers that must never be cached — storing these can cause session fixation or auth bypass. */
+const UNCACHEABLE_HEADERS = new Set([
+    'set-cookie',
+    'www-authenticate',
+    'authorization',
+    'x-csrf-token',
+    'proxy-authenticate',
+]);
+export const cacheResponse = ({ ttl, key, store: storeOverride, }) => {
+    return async (c, next) => {
+        const ctx = getBunshotCtx(c);
+        const store = storeOverride ?? ctx.config.resolvedStores.cache ?? 'redis';
+        const appName = ctx.config.appName;
+        const rawKey = typeof key === 'function' ? key(c) : key;
+        // Per-tenant namespacing: prevents two tenants caching the same key from colliding
+        const tenantId = c.get('tenantId');
+        const tenantSegment = tenantId ? `${tenantId}:` : '';
+        const cacheKey = `cache:${appName}:${tenantSegment}${rawKey}`;
+        const cached = await storeGet(ctx, store, cacheKey);
+        if (cached) {
+            const { status, headers, body } = JSON.parse(cached);
+            return new Response(body, {
+                status,
+                headers: { ...headers, 'x-cache': 'HIT' },
+            });
+        }
+        await next();
+        const res = c.res;
+        if (res.status >= 200 && res.status < 300) {
+            const body = await res.text();
+            const headers = {};
+            res.headers.forEach((value, name) => {
+                if (!UNCACHEABLE_HEADERS.has(name.toLowerCase())) {
+                    headers[name] = value;
+                }
+            });
+            await storeSet(ctx, store, cacheKey, JSON.stringify({ status: res.status, headers, body }), ttl);
+            c.res = new Response(body, {
+                status: res.status,
+                headers: { ...headers, 'x-cache': 'MISS' },
+            });
+        }
+    };
+};

package/dist/src/framework/middleware/captcha.d.ts

@@ -0,0 +1,9 @@
+import type { MiddlewareHandler } from 'hono';
+import type { AppEnv, CaptchaConfig } from '../../../packages/bunshot-core/src/index.js';
+/**
+ * Middleware factory that verifies a CAPTCHA token from the request body.
+ *
+ * @example
+ * router.post("/contact", requireCaptcha({ provider: "turnstile", secretKey: "..." }), handler);
+ */
+export declare const requireCaptcha: (config?: CaptchaConfig) => MiddlewareHandler<AppEnv>;

package/dist/src/framework/middleware/captcha.js

@@ -0,0 +1,37 @@
+import { verifyCaptcha } from '../lib/captcha';
+import { HttpError, getContextOrNull } from '../../../packages/bunshot-core/src/index.js';
+import { getClientIp } from '../../../packages/bunshot-core/src/index.js';
+/**
+ * Middleware factory that verifies a CAPTCHA token from the request body.
+ *
+ * @example
+ * router.post("/contact", requireCaptcha({ provider: "turnstile", secretKey: "..." }), handler);
+ */
+export const requireCaptcha = (config) => async (c, next) => {
+    // Get effective config: param takes precedence, then context config
+    const app = c.get('bunshotCtx')?.app;
+    const ctx = app ? getContextOrNull(app) : null;
+    const effectiveConfig = config ?? ctx?.config?.captcha ?? undefined;
+    if (!effectiveConfig) {
+        await next();
+        return;
+    }
+    const tokenField = effectiveConfig.tokenField ?? 'captcha-token';
+    let body;
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        body = {};
+    }
+    const token = body[tokenField];
+    if (!token) {
+        throw new HttpError(400, 'CAPTCHA token is required', 'CAPTCHA_MISSING');
+    }
+    const ip = getClientIp(c) ?? undefined;
+    const result = await verifyCaptcha(token, effectiveConfig, ip);
+    if (!result.success) {
+        throw new HttpError(400, 'CAPTCHA verification failed', 'CAPTCHA_FAILED');
+    }
+    await next();
+};

package/dist/{middleware → src/framework/middleware}/errorHandler.d.ts

@@ -1,2 +1,2 @@
-import type { Middleware } from ".";
+import type { Middleware } from '.';
 export declare const errorHandler: Middleware;