@lastshotlabs/bunshot 0.0.27 → 0.0.28

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

@@ -1,12 +1,12 @@
-import { parseUpload, getUploadConfig } from "../lib/upload";
+import { getUploadConfig, parseUpload } from '../lib/upload';
 export const handleUpload = (opts) => {
     return async (c, next) => {
-        const config = getUploadConfig();
+        const config = getUploadConfig(c.get('bunshotCtx'));
         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);
+        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);
         }
@@ -21,7 +21,7 @@ export const handleUpload = (opts) => {
                 return c.json({ error: err.message }, 413);
             throw err;
         }
-        c.set("uploadResults", results);
+        c.set('uploadResults', results);
         await next();
     };
 };

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

@@ -1,5 +1,5 @@
-import type { MiddlewareHandler, Context } from "hono";
-import type { AppEnv } from "../lib/context";
+import type { Context, MiddlewareHandler } from 'hono';
+import type { AppEnv } from '../../../packages/bunshot-core/src/index.js';
 export interface WebhookTimestampOptions {
     /** Header name containing the Unix timestamp (seconds or ms). */
     header: string;
@@ -18,7 +18,7 @@ export interface WebhookAuthOptions {
     /** Header that carries the signature. Default: `"x-webhook-signature"`. */
     header?: string;
     /** HMAC algorithm. Default: `"sha256"`. */
-    algorithm?: "sha256" | "sha512";
+    algorithm?: 'sha256' | 'sha512';
     /**
      * Strip this prefix from the signature header value before comparing.
      * e.g. `"sha256="` for GitHub-style `X-Hub-Signature-256: sha256=<hex>`.

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

@@ -1,39 +1,38 @@
-import { createHmac } from "crypto";
-import { timingSafeEqual } from "../lib/crypto";
-import { HttpError } from "../lib/HttpError";
+import { createHmac } from 'crypto';
+import { HttpError, timingSafeEqual } from '../../../packages/bunshot-core/src/index.js';
 export const webhookAuth = (options) => async (c, next) => {
-    const algorithm = options.algorithm ?? "sha256";
-    const sigHeader = options.header ?? "x-webhook-signature";
+    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)) {
-            throw new HttpError(401, "Unauthorized", "EXPIRED_TIMESTAMP");
+            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");
+            throw new HttpError(401, 'Unauthorized', 'EXPIRED_TIMESTAMP');
         }
     }
     // --- Signature header ---
     const rawSig = c.req.header(sigHeader);
     if (!rawSig) {
-        throw new HttpError(401, "Unauthorized", "INVALID_SIGNATURE");
+        throw new HttpError(401, 'Unauthorized', 'INVALID_SIGNATURE');
     }
     const provided = options.prefix && rawSig.startsWith(options.prefix)
         ? rawSig.slice(options.prefix.length)
         : rawSig;
     // --- Secret resolution ---
     let secret;
-    if (typeof options.secret === "function") {
+    if (typeof options.secret === 'function') {
         try {
             secret = await options.secret(c);
         }
         catch {
-            throw new HttpError(500, "Internal Server Error", "WEBHOOK_SECRET_ERROR");
+            throw new HttpError(500, 'Internal Server Error', 'WEBHOOK_SECRET_ERROR');
         }
     }
     else {
@@ -42,7 +41,7 @@ export const webhookAuth = (options) => async (c, next) => {
     // --- 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");
+    const computed = createHmac(algorithm, secret).update(body).digest('hex');
     let valid;
     try {
         valid = timingSafeEqual(computed, provided);
@@ -52,7 +51,7 @@ export const webhookAuth = (options) => async (c, next) => {
         valid = false;
     }
     if (!valid) {
-        throw new HttpError(401, "Unauthorized", "INVALID_SIGNATURE");
+        throw new HttpError(401, 'Unauthorized', 'INVALID_SIGNATURE');
     }
     await next();
 };

package/dist/src/framework/models/AuditLog.d.ts

@@ -0,0 +1,21 @@
+import type { Connection, Document, Model } from 'mongoose';
+interface IAuditLog {
+    id: string;
+    userId: string | null;
+    sessionId: string | null;
+    tenantId: string | null;
+    method: string;
+    path: string;
+    status: number;
+    ip: string | null;
+    userAgent: string | null;
+    action?: string;
+    resource?: string;
+    resourceId?: string;
+    meta?: Record<string, unknown>;
+    createdAt: Date;
+    expiresAt?: Date;
+}
+type AuditLogDocument = IAuditLog & Document;
+export declare function getAuditLogModel(conn: Connection): Model<AuditLogDocument>;
+export {};

package/dist/src/framework/models/AuditLog.js

@@ -0,0 +1,31 @@
+import { getMongooseModule } from '../../lib/mongo';
+export function getAuditLogModel(conn) {
+    if (conn.models['AuditLog']) {
+        return conn.models['AuditLog'];
+    }
+    const mg = getMongooseModule();
+    const { Schema } = mg;
+    const schema = new Schema({
+        id: { type: String, required: true, unique: true },
+        userId: { type: String, default: null },
+        sessionId: { type: String, default: null },
+        tenantId: { type: String, default: null },
+        method: { type: String, required: true },
+        path: { type: String, required: true },
+        status: { type: Number, required: true },
+        ip: { type: String, default: null },
+        userAgent: { type: String, default: null },
+        action: { type: String },
+        resource: { type: String },
+        resourceId: { type: String },
+        meta: { type: Schema.Types.Mixed },
+        expiresAt: { type: Date, index: { expireAfterSeconds: 0 } },
+    }, {
+        collection: 'audit_logs',
+        timestamps: { createdAt: 'createdAt', updatedAt: false },
+    });
+    schema.index({ userId: 1, createdAt: 1 });
+    schema.index({ tenantId: 1, createdAt: 1 });
+    schema.index({ path: 1 });
+    return conn.model('AuditLog', schema);
+}

package/dist/src/framework/mountMiddleware.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Middleware mounting — extracted from createApp().
+ *
+ * Handles the framework middleware stack: request ID, validation formatter,
+ * metrics collection, request logging, secure headers, CORS, bot protection,
+ * rate limiting, and tenant resolution.
+ */
+import type { MetricsState } from './lib/metrics';
+import type { LogLevel, RequestLogEntry } from './middleware/requestLogger';
+import type { OpenAPIHono } from '@hono/zod-openapi';
+import type { MiddlewareHandler } from 'hono';
+import type { AppEnv, ValidationErrorFormatter } from '../../packages/bunshot-core/src/index.js';
+export interface SecurityConfig {
+    cors?: string | string[];
+    headers?: {
+        contentSecurityPolicy?: string;
+        permissionsPolicy?: string;
+    };
+    rateLimit?: {
+        windowMs: number;
+        max: number;
+    };
+    botProtection?: {
+        blockList?: string[];
+        fingerprintRateLimit?: boolean;
+    };
+    trustProxy?: false | number;
+    signing?: unknown;
+    captcha?: unknown;
+}
+export interface LoggingConfig {
+    enabled?: boolean;
+    onLog?: (entry: RequestLogEntry) => void | Promise<void>;
+    level?: LogLevel;
+    excludePaths?: (string | RegExp)[];
+    excludeMethods?: string[];
+}
+export interface MetricsConfig {
+    enabled?: boolean;
+    auth?: 'userAuth' | 'none' | MiddlewareHandler<AppEnv>[];
+    excludePaths?: (string | RegExp)[];
+    normalizePath?: (path: string) => string;
+    queues?: string[];
+    unsafePublic?: boolean;
+}
+export interface TenancyConfig {
+    resolution: 'header' | 'subdomain' | 'path';
+    headerName?: string;
+    pathSegment?: number;
+    onResolve?: (tenantId: string) => Promise<Record<string, unknown> | null>;
+    cacheTtlMs?: number;
+    cacheMaxSize?: number;
+    exemptPaths?: string[];
+    rejectionStatus?: 403 | 404;
+}
+export interface MountMiddlewareConfig {
+    security: SecurityConfig;
+    logging?: LoggingConfig;
+    metrics?: MetricsConfig;
+    metricsState?: MetricsState;
+    tenancy?: TenancyConfig;
+    validation?: {
+        formatError?: ValidationErrorFormatter;
+    };
+    middleware?: MiddlewareHandler<AppEnv>[];
+}
+/**
+ * Mount all framework middleware on the Hono app in the correct order.
+ *
+ * Order:
+ * 1. Request ID
+ * 2. Validation error formatter (context variable)
+ * 3. Metrics collection (if enabled)
+ * 4. Request logging (if enabled)
+ * 5. Secure headers
+ * 6. Custom security headers
+ * 7. CORS
+ * 8. Bot protection (if configured)
+ * 9. Rate limiting
+ *
+ * Plugin middleware and tenant resolution are mounted separately
+ * (after this function returns) to maintain correct ordering.
+ */
+export declare function mountFrameworkMiddleware(app: OpenAPIHono<AppEnv>, config: MountMiddlewareConfig): Promise<void>;
+/**
+ * Mount tenant resolution middleware. Called after plugin middleware phase
+ * so tenant context is available in routes but plugins can set up auth first.
+ */
+export declare function mountTenantMiddleware(app: OpenAPIHono<AppEnv>, tenancy: TenancyConfig, carrier?: {
+    cache: import('./middleware/tenant').TenantResolutionCache | null;
+}): Promise<void>;

package/dist/src/framework/mountMiddleware.js

@@ -0,0 +1,128 @@
+import { rateLimit } from './middleware/rateLimit';
+import { requestId } from './middleware/requestId';
+import { requestLogger } from './middleware/requestLogger';
+import { cors } from 'hono/cors';
+import { secureHeaders } from 'hono/secure-headers';
+import { HEADER_CSRF_TOKEN, HEADER_REFRESH_TOKEN, HEADER_REQUEST_ID, HEADER_USER_TOKEN, defaultValidationErrorFormatter, } from '../../packages/bunshot-core/src/index.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Mount all framework middleware on the Hono app in the correct order.
+ *
+ * Order:
+ * 1. Request ID
+ * 2. Validation error formatter (context variable)
+ * 3. Metrics collection (if enabled)
+ * 4. Request logging (if enabled)
+ * 5. Secure headers
+ * 6. Custom security headers
+ * 7. CORS
+ * 8. Bot protection (if configured)
+ * 9. Rate limiting
+ *
+ * Plugin middleware and tenant resolution are mounted separately
+ * (after this function returns) to maintain correct ordering.
+ */
+export async function mountFrameworkMiddleware(app, config) {
+    const { security: securityConfig = {} } = config;
+    app.use(requestId);
+    // Set the validation error formatter on context so defaultHook and onError both pick it up
+    const validationFormatter = config.validation?.formatError ?? defaultValidationErrorFormatter;
+    app.use('*', async (c, next) => {
+        c.set('validationErrorFormatter', validationFormatter);
+        await next();
+    });
+    // Metrics collection middleware (before requestLogger so it captures all requests)
+    if (config.metrics?.enabled) {
+        const metricsAuth = config.metrics.auth ?? 'none';
+        if (metricsAuth === 'none' && !config.metrics.unsafePublic) {
+            if (process.env.NODE_ENV === 'production') {
+                throw new Error('[security] metrics.auth is required in production. Set metrics.auth or explicitly set unsafePublic: true with auth: "none".');
+            }
+            console.warn('[security] /metrics is enabled without auth. Configure metrics.auth for production.');
+        }
+        const { metricsCollector } = await import('./middleware/metrics');
+        app.use(metricsCollector({
+            state: config.metricsState ??
+                (() => {
+                    throw new Error('metricsState is required when metrics are enabled');
+                })(),
+            excludePaths: config.metrics.excludePaths,
+            normalizePath: config.metrics.normalizePath,
+        }));
+    }
+    // Request logging
+    const loggingConfig = config.logging ?? {};
+    if (loggingConfig.enabled !== false) {
+        app.use(requestLogger({
+            onLog: loggingConfig.onLog,
+            level: loggingConfig.level,
+            excludePaths: loggingConfig.excludePaths,
+            excludeMethods: loggingConfig.excludeMethods,
+        }));
+    }
+    // Secure headers
+    const headerOpts = {};
+    if (securityConfig.headers?.contentSecurityPolicy) {
+        headerOpts['Content-Security-Policy'] = securityConfig.headers.contentSecurityPolicy;
+    }
+    if (securityConfig.headers?.permissionsPolicy) {
+        headerOpts['Permissions-Policy'] = securityConfig.headers.permissionsPolicy;
+    }
+    app.use(secureHeaders());
+    if (Object.keys(headerOpts).length > 0) {
+        app.use(async (c, next) => {
+            await next();
+            for (const [k, v] of Object.entries(headerOpts)) {
+                c.res.headers.set(k, v);
+            }
+        });
+    }
+    // CORS
+    const corsOrigins = securityConfig.cors ?? '*';
+    if (corsOrigins === '*' && process.env.NODE_ENV === 'production') {
+        console.warn('[security] CORS is set to wildcard (*) in production. Configure security.cors with specific origins to restrict cross-origin access.');
+    }
+    const corsAllowHeaders = [
+        'Content-Type',
+        'Authorization',
+        HEADER_USER_TOKEN,
+        HEADER_REFRESH_TOKEN,
+        HEADER_CSRF_TOKEN,
+    ];
+    app.use(cors({
+        origin: corsOrigins,
+        allowHeaders: corsAllowHeaders,
+        exposeHeaders: ['x-cache', HEADER_REQUEST_ID],
+        credentials: true,
+    }));
+    // Bot protection
+    const botCfg = securityConfig.botProtection ?? {};
+    if ((botCfg.blockList?.length ?? 0) > 0) {
+        const { botProtection } = await import('./middleware/botProtection');
+        app.use(botProtection({ blockList: botCfg.blockList }));
+    }
+    // Rate limiting
+    const rlConfig = securityConfig.rateLimit ?? { windowMs: 60_000, max: 100 };
+    app.use(rateLimit({ ...rlConfig, fingerprintLimit: botCfg.fingerprintRateLimit ?? false }));
+}
+/**
+ * Mount tenant resolution middleware. Called after plugin middleware phase
+ * so tenant context is available in routes but plugins can set up auth first.
+ */
+export async function mountTenantMiddleware(app, tenancy, carrier) {
+    if (!tenancy.onResolve) {
+        if (process.env.NODE_ENV === 'production') {
+            throw new Error('[security] Tenancy is configured without an onResolve callback. ' +
+                'In production, onResolve is required to validate tenant IDs and prevent cross-tenant access. ' +
+                'Provide tenancy.onResolve or remove the tenancy config.');
+        }
+        else {
+            console.warn('[security] Tenancy is configured without an onResolve callback — ' +
+                'tenant IDs will be trusted without validation. This is unsafe in production.');
+        }
+    }
+    const { createTenantMiddleware } = await import('./middleware/tenant');
+    app.use(createTenantMiddleware(tenancy, carrier));
+}

package/dist/src/framework/mountOptionalEndpoints.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Optional endpoint mounting — extracted from createApp().
+ *
+ * Mounts the jobs status endpoint, /metrics endpoint, and upload presigned-URL
+ * endpoint when each is enabled in the app config.
+ */
+import type { MetricsState } from './lib/metrics';
+import type { OpenAPIHono } from '@hono/zod-openapi';
+import type { MiddlewareHandler } from 'hono';
+import type { AppEnv } from '../../packages/bunshot-core/src/index.js';
+export interface JobsConfig {
+    /** Enable the job status endpoint. Default: false. */
+    statusEndpoint?: boolean;
+    /**
+     * Auth protection for job endpoints.
+     * - `"userAuth"` — requires authenticated user session (cookie/token).
+     * - `"none"` — no auth (not recommended for production).
+     * - `MiddlewareHandler[]` — custom middleware stack (e.g., `[userAuth, requireRole("admin")]`).
+     *
+     * Default: `"none"`. You must explicitly configure auth.
+     */
+    auth?: 'userAuth' | 'none' | MiddlewareHandler<AppEnv>[];
+    /** Required roles for accessing job endpoints. Only works when auth includes userAuth. */
+    roles?: string[];
+    /** Whitelist of queue names exposed. Default: [] (nothing exposed). */
+    allowedQueues?: string[];
+    /** When using userAuth, restrict job visibility to the user who created it. Default: false. */
+    scopeToUser?: boolean;
+    /**
+     * Explicitly acknowledge that jobs endpoint is public in production.
+     * Set to true only when auth is "none" and you understand the risk.
+     * Without this, createApp throws in production when auth is "none".
+     */
+    unsafePublic?: boolean;
+}
+export interface MetricsConfig {
+    /** Enable the /metrics endpoint. Default: false (must be explicitly enabled). */
+    enabled?: boolean;
+    /**
+     * Auth protection for the /metrics endpoint.
+     * - `"userAuth"` — requires authenticated user session.
+     * - `"none"` — no auth (default — logs a production warning).
+     * - `MiddlewareHandler[]` — custom middleware stack.
+     */
+    auth?: 'userAuth' | 'none' | MiddlewareHandler<AppEnv>[];
+    /** Paths to exclude from metrics collection. Strings use prefix matching. */
+    excludePaths?: (string | RegExp)[];
+    /** Custom path normalizer to prevent high-cardinality labels. */
+    normalizePath?: (path: string) => string;
+    /** BullMQ queue names to report depth gauges for. */
+    queues?: string[];
+    /**
+     * Explicitly acknowledge that metrics endpoint is public in production.
+     * Set to true only when auth is "none" and you understand the risk.
+     * Without this, createApp throws in production when auth is "none".
+     */
+    unsafePublic?: boolean;
+}
+export interface PresignedUrlConfig {
+    expirySeconds?: number;
+    path?: string;
+}
+export interface UploadConfig {
+    storage: import('./lib/storageAdapter').StorageAdapter;
+    maxFileSize?: number;
+    maxFiles?: number;
+    allowedMimeTypes?: string[];
+    keyPrefix?: string;
+    generateKey?: (file: File, ctx: {
+        userId?: string;
+        tenantId?: string;
+    }) => string;
+    tenantScopedKeys?: boolean;
+    presignedUrls?: boolean | PresignedUrlConfig;
+    /**
+     * TTL in seconds for upload registry entries across all backends.
+     * Default: 2592000 (30 days).
+     */
+    registryTtlSeconds?: number;
+    /**
+     * Authorization callback for upload read/delete operations.
+     * Called when registry ownership check fails or key is not in registry.
+     */
+    authorization?: {
+        authorize?: (input: {
+            action: 'read' | 'delete';
+            key: string;
+            userId?: string;
+            tenantId?: string;
+        }) => boolean | Promise<boolean>;
+    };
+    /**
+     * Allow operations on keys not in the upload registry.
+     * When false (default), operations on unknown keys return 404.
+     * When true, requires an authorize callback — denies if absent.
+     */
+    allowExternalKeys?: boolean;
+}
+export declare function mountOptionalEndpoints(app: OpenAPIHono<AppEnv>, coreRoutesDir: string, jobs: JobsConfig | undefined, metrics: MetricsConfig | undefined, upload: UploadConfig | undefined, metricsState: MetricsState, resolvedSecrets: {
+    redisHost?: string;
+    redisUser?: string;
+    redisPassword?: string;
+}): Promise<void>;

package/dist/src/framework/mountOptionalEndpoints.js

@@ -0,0 +1,47 @@
+import { createQueueFactory } from '../lib/queue';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+export async function mountOptionalEndpoints(app, coreRoutesDir, jobs, metrics, upload, metricsState, resolvedSecrets) {
+    const needsQueueFactory = !!jobs?.statusEndpoint || !!metrics?.queues?.length;
+    const queueFactory = needsQueueFactory
+        ? (() => {
+            if (!resolvedSecrets.redisHost) {
+                throw new Error('[queue] Jobs/metrics queue helpers require REDIS_HOST via the Bunshot secret bundle at startup.');
+            }
+            return createQueueFactory({
+                host: resolvedSecrets.redisHost,
+                user: resolvedSecrets.redisUser,
+                password: resolvedSecrets.redisPassword,
+            });
+        })()
+        : undefined;
+    if (jobs?.statusEndpoint) {
+        const jobsAuth = jobs.auth ?? 'none';
+        if (jobsAuth === 'none' && !jobs.unsafePublic) {
+            if (process.env.NODE_ENV === 'production') {
+                throw new Error('[security] jobs.auth is required in production. Set jobs.auth or explicitly set unsafePublic: true with auth: "none".');
+            }
+            console.warn('[security] /jobs is enabled without auth. Configure jobs.auth for production.');
+        }
+        const { createJobsRouter } = await import(`${coreRoutesDir}/jobs`);
+        app.route('/', createJobsRouter(jobs, queueFactory));
+    }
+    if (metrics?.enabled) {
+        const { createMetricsRouter } = await import(`${coreRoutesDir}/metrics`);
+        app.route('/', createMetricsRouter({
+            auth: metrics.auth,
+            queues: metrics.queues,
+            unsafePublic: metrics.unsafePublic,
+        }, metricsState, queueFactory));
+    }
+    if (upload?.presignedUrls) {
+        const { createUploadsRouter } = await import(`${coreRoutesDir}/uploads`);
+        const presignConfig = upload.presignedUrls === true ? {} : upload.presignedUrls;
+        app.route('/', createUploadsRouter({
+            ...presignConfig,
+            authorization: upload.authorization,
+            allowExternalKeys: upload.allowExternalKeys,
+        }));
+    }
+}

package/dist/src/framework/mountRoutes.d.ts

@@ -0,0 +1,21 @@
+import { OpenAPIHono } from '@hono/zod-openapi';
+import type { AppEnv } from '../../packages/bunshot-core/src/index.js';
+export interface VersioningConfig {
+    /**
+     * Version identifiers in ascending order, e.g. `["v1", "v2"]`.
+     * Each version needs a matching subdirectory under `routesDir` (e.g. `routes/v1/`).
+     */
+    versions: string[];
+    /**
+     * Subdirectory name for routes shared across all versions. Shared route schemas
+     * receive unprefixed names since they are version-agnostic. Default: `"shared"`.
+     * Set `false` to disable shared route discovery.
+     */
+    sharedDir?: string | false;
+    /**
+     * Which version `/docs` and `/openapi.json` redirect to.
+     * Defaults to the last version in the array (i.e. the latest).
+     */
+    defaultVersion?: string;
+}
+export declare function mountRoutes(app: OpenAPIHono<AppEnv>, routesDir: string, versioning: VersioningConfig | string[] | undefined, appName: string, openApiVersion: string): Promise<void>;