@lastshotlabs/bunshot 0.0.27 → 0.1.0

package/dist/packages/bunshot-core/src/context/bunshotContext.d.ts

@@ -0,0 +1,232 @@
+import type { AuditLogProvider } from '../auditLog';
+import type { CacheAdapter, CacheStoreName, EmailTemplate, FingerprintBuilder, RateLimitAdapter, RouteAuthRegistry, UserResolver } from '../coreContracts';
+import type { ICronRegistryRepository } from '../cronRegistry';
+import type { DataEncryptionKey } from '../crypto';
+import type { BunshotEventBus } from '../eventBus';
+import type { IdempotencyAdapter } from '../idempotency';
+import type { BunshotPlugin } from '../plugin';
+import type { ISecretRepository } from '../secrets';
+import type { SigningConfig } from '../signing';
+import type { UploadRegistryRepository } from '../uploadRegistry';
+import type { RoomPersistenceConfig, WsMessageDefaults, WsMessageRepository } from '../wsMessages';
+import type { ResolvedStores } from './frameworkConfig';
+/**
+ * Resolved persistence repositories for the application instance.
+ * Created by `resolveFrameworkPersistence()` in createInfrastructure,
+ * wired into the BunshotContext by createApp().
+ */
+export interface ResolvedPersistence {
+    readonly uploadRegistry: UploadRegistryRepository;
+    readonly idempotency: IdempotencyAdapter;
+    readonly wsMessages: WsMessageRepository;
+    readonly auditLog: AuditLogProvider;
+    /** Persists BullMQ scheduler names across deployments for stale-scheduler cleanup. */
+    readonly cronRegistry: ICronRegistryRepository;
+    /** Configure a room for message persistence. */
+    configureRoom(endpoint: string, room: string, options: RoomPersistenceConfig): void;
+    /** Get resolved room config for an (endpoint, room) pair. Returns null if not configured. */
+    getRoomConfig(endpoint: string, room: string): {
+        maxCount: number;
+        ttlSeconds: number;
+    } | null;
+    /** Set default maxCount/ttlSeconds for rooms that don't specify their own. */
+    setDefaults(defaults: WsMessageDefaults): void;
+}
+/**
+ * Transport adapter interface for cross-instance WS message delivery.
+ * Mirrors WsTransportAdapter from the framework — defined here so the
+ * context type doesn't depend on framework internals.
+ */
+export interface WsTransportHandle {
+    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>;
+}
+/**
+ * Instance-scoped WebSocket runtime state.
+ *
+ * Populated by `createServer()` when `ws` config is present.
+ * Null when the server has no WebSocket endpoints.
+ */
+export interface WsState {
+    /** The Bun Server instance that owns the WebSocket upgrade. */
+    server: unknown | null;
+    /** Cross-instance pub/sub transport, or null for single-instance. */
+    transport: WsTransportHandle | null;
+    /** Unique instance ID for transport self-echo filtering. */
+    readonly instanceId: string;
+    /** Whether presence tracking is enabled on any endpoint. */
+    readonly presenceEnabled: boolean;
+    /** Room registry: wsEndpointKey → Set<socketId>. Shared reference to the live map. */
+    readonly roomRegistry: Map<string, Set<string>>;
+    /** Heartbeat socket registry: socketId → socket handle + timeout state. */
+    readonly heartbeatSockets: Map<string, {
+        ws: unknown;
+        endpoint: string;
+        timeoutAt: number;
+    }>;
+    /** Per-endpoint heartbeat configuration. */
+    readonly heartbeatEndpointConfigs: Map<string, {
+        intervalMs?: number;
+        timeoutMs?: number;
+    }>;
+    /** Active heartbeat timer handle, or null when disabled. */
+    heartbeatTimer: unknown | null;
+    /** Authenticated socket tracking for presence. */
+    readonly socketUsers: Map<string, string>;
+    /** Presence registry: wsEndpointKey(endpoint, room) → userId → Set<socketId>. */
+    readonly roomPresence: Map<string, Map<string, Set<string>>>;
+}
+export interface UploadRuntimeState {
+    readonly adapter: unknown | null;
+    readonly config: Readonly<Record<string, unknown>>;
+}
+export interface MetricsState {
+    readonly counters: Map<string, Map<string, {
+        labels: Record<string, string>;
+        value: number;
+    }>>;
+    readonly histograms: Map<string, {
+        boundaries: number[];
+        entries: Map<string, {
+            labels: Record<string, string>;
+            buckets: number[];
+            sum: number;
+            count: number;
+        }>;
+    }>;
+    readonly gaugeCallbacks: Map<string, () => Promise<{
+        labels: Record<string, string>;
+        value: number;
+    }[]>>;
+    queues: Map<string, any> | null;
+}
+/**
+ * The instance-scoped runtime state container for a Bunshot application.
+ *
+ * Created by `createApp()`, attached to the Hono app instance via WeakMap,
+ * and accessible from route handlers via `getContext(app)`.
+ *
+ * Replaces module-level singletons with instance-scoped state. Each
+ * `createApp()` invocation produces its own context — no shared globals,
+ * no cross-instance leakage.
+ */
+export interface BunshotContext {
+    /** The Hono app instance this context is attached to. */
+    readonly app: object;
+    /** Resolved and frozen application configuration. */
+    readonly config: BunshotResolvedConfig;
+    /** Redis client handle, or null when Redis is disabled. */
+    readonly redis: unknown | null;
+    /** Mongoose connection handles, or null when Mongo is disabled. */
+    readonly mongo: {
+        readonly auth: unknown | null;
+        readonly app: unknown | null;
+    } | null;
+    /** SQLite database path, or null when SQLite is not configured. */
+    readonly sqlite: string | null;
+    /** Resolved signing configuration, or null when not configured. */
+    readonly signing: Readonly<SigningConfig> | null;
+    /** Data encryption keys for field-level encryption. Empty array when not configured. */
+    readonly dataEncryptionKeys: readonly DataEncryptionKey[];
+    /**
+     * WebSocket runtime state, or null when the server has no WS endpoints.
+     *
+     * Set to null by `createApp()` — populated by `createServer()` after
+     * the Bun server and transport are initialized. Mutable so createServer
+     * can attach WS state after the context is created.
+     */
+    ws: WsState | null;
+    /**
+     * Resolved persistence repositories — upload registry, idempotency,
+     * WS message persistence, and audit log. Instance-scoped, no module-level state.
+     */
+    readonly persistence: ResolvedPersistence;
+    /**
+     * Plugin-scoped state map. Plugins store their resolved config or runtime
+     * state here during setupPost(). Keyed by plugin name (e.g. 'bunshot-auth').
+     *
+     * First step toward context-aware plugins — plugins register their resolved
+     * config here so it's instance-scoped rather than global.
+     */
+    readonly pluginState: Map<string, unknown>;
+    /**
+     * Registered plugins for this application instance.
+     * Replaces the appMeta WeakMap — instance-scoped, no module-level state.
+     */
+    readonly plugins: readonly BunshotPlugin[];
+    /**
+     * Event bus for cross-plugin communication.
+     * Replaces the appMeta WeakMap — instance-scoped, no module-level state.
+     */
+    readonly bus: BunshotEventBus;
+    /** Route auth registry for framework-owned routes. */
+    readonly routeAuth: RouteAuthRegistry | null;
+    /** User resolver used by framework WS/SSE and related helpers. */
+    readonly userResolver: UserResolver | null;
+    /** Rate limit adapter used by framework middleware. */
+    readonly rateLimitAdapter: RateLimitAdapter | null;
+    /** Fingerprint builder used by bot/rate limiting. */
+    readonly fingerprintBuilder: FingerprintBuilder | null;
+    /** Cache adapters registered for this app instance. */
+    readonly cacheAdapters: ReadonlyMap<CacheStoreName, CacheAdapter>;
+    /** Email templates registered by plugins for this app instance. */
+    readonly emailTemplates: ReadonlyMap<string, EmailTemplate>;
+    /** Trusted proxy configuration for IP extraction. */
+    readonly trustProxy: false | number;
+    /** Upload runtime state for the application instance. */
+    readonly upload: UploadRuntimeState | null;
+    /** Metrics runtime state for the application instance. */
+    readonly metrics: MetricsState;
+    /**
+     * Secret repository for resolving credentials at runtime.
+     * Resolved at startup before DB connections. Plugins and user code
+     * can call `ctx.secrets.get(key)` to resolve their own secrets.
+     */
+    readonly secrets: ISecretRepository;
+    /**
+     * Resolved startup secret snapshot.
+     * Contains framework secrets plus any app-specific schema entries resolved
+     * during bootstrap. Instance-owned and frozen.
+     */
+    readonly resolvedSecrets: Readonly<Record<string, string>>;
+    /**
+     * Clear all instance-owned in-memory state (stores, caches, registries).
+     * Used for test isolation — replaces the old global reset primitive.
+     */
+    clear(): Promise<void>;
+    /**
+     * Destroy the context — close database connections, stop timers, release resources.
+     * Called during graceful shutdown.
+     */
+    destroy(): Promise<void>;
+}
+/**
+ * The resolved configuration shape stored on the context.
+ * Uses `Record<string, unknown>` for now — will be refined as config
+ * types are consolidated during the full singleton migration.
+ */
+export interface BunshotResolvedConfig {
+    /** Application name. */
+    readonly appName: string;
+    /** Resolved store selections for sessions, OAuth state, cache, and auth. */
+    readonly resolvedStores: Readonly<ResolvedStores>;
+    /** CORS origins. */
+    readonly security: {
+        readonly cors: string | string[];
+    };
+    /** Signing configuration, or null when not configured. */
+    readonly signing: unknown;
+    /** Data encryption keys. */
+    readonly dataEncryptionKeys: readonly DataEncryptionKey[];
+    /** Redis handle when available. */
+    readonly redis: unknown | undefined;
+    /** Mongo connection handles when available. */
+    readonly mongo: {
+        readonly auth: unknown;
+        readonly app: unknown;
+    } | undefined;
+    /** Captcha configuration, or null. */
+    readonly captcha: unknown;
+}
+export type { BunshotFrameworkConfig } from './frameworkConfig';

package/dist/packages/bunshot-core/src/context/bunshotContext.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/bunshot-core/src/context/contextAccess.d.ts

@@ -0,0 +1,3 @@
+import type { BunshotContext } from './bunshotContext';
+export type ContextCarrier = BunshotContext | object;
+export declare function resolveContext(input: ContextCarrier): BunshotContext;

package/dist/packages/bunshot-core/src/context/contextAccess.js

@@ -0,0 +1,16 @@
+import { getContext } from './contextStore';
+export function resolveContext(input) {
+    if (typeof input === 'object' &&
+        input !== null &&
+        ('config' in input ||
+            'persistence' in input ||
+            'routeAuth' in input ||
+            'userResolver' in input ||
+            'rateLimitAdapter' in input ||
+            'fingerprintBuilder' in input ||
+            'cacheAdapters' in input ||
+            'emailTemplates' in input)) {
+        return input;
+    }
+    return getContext(input);
+}

package/dist/packages/bunshot-core/src/context/contextStore.d.ts

@@ -0,0 +1,16 @@
+import type { BunshotContext } from './bunshotContext';
+/**
+ * Attach a BunshotContext to an app instance.
+ * Called once by `createApp()` after the context is fully assembled.
+ */
+export declare function attachContext(app: object, ctx: BunshotContext): void;
+/**
+ * Retrieve the BunshotContext for an app instance.
+ * Throws if no context is found — indicates `createApp()` was not called.
+ */
+export declare function getContext(app: object): BunshotContext;
+/**
+ * Retrieve the BunshotContext for an app instance, or null if not attached.
+ * Use when context availability is optional (e.g., standalone plugin setup).
+ */
+export declare function getContextOrNull(app: object): BunshotContext | null;

package/dist/packages/bunshot-core/src/context/contextStore.js

@@ -0,0 +1,31 @@
+const APP_CONTEXT_SYMBOL = Symbol.for('bunshot.context');
+/**
+ * Attach a BunshotContext to an app instance.
+ * Called once by `createApp()` after the context is fully assembled.
+ */
+export function attachContext(app, ctx) {
+    Object.defineProperty(app, APP_CONTEXT_SYMBOL, {
+        configurable: true,
+        enumerable: false,
+        writable: true,
+        value: ctx,
+    });
+}
+/**
+ * Retrieve the BunshotContext for an app instance.
+ * Throws if no context is found — indicates `createApp()` was not called.
+ */
+export function getContext(app) {
+    const ctx = app[APP_CONTEXT_SYMBOL];
+    if (!ctx)
+        throw new Error('BunshotContext not found — was createApp() called?');
+    return ctx;
+}
+/**
+ * Retrieve the BunshotContext for an app instance, or null if not attached.
+ * Use when context availability is optional (e.g., standalone plugin setup).
+ */
+export function getContextOrNull(app) {
+    return (app[APP_CONTEXT_SYMBOL] ??
+        null);
+}

package/dist/packages/bunshot-core/src/context/frameworkConfig.d.ts

@@ -0,0 +1,38 @@
+import type { CoreRegistrar } from '../coreContracts';
+import type { DataEncryptionKey } from '../crypto';
+import type { SigningConfig } from '../signing';
+import type { StoreType } from '../storeType';
+/**
+ * Resolved store selections — which backend each subsystem uses.
+ * Defined here (not in framework internals) so plugins can reference
+ * it without importing from the framework's private modules.
+ */
+export interface ResolvedStores {
+    sessions: StoreType;
+    oauthState: StoreType;
+    cache: StoreType;
+    authStore: StoreType;
+    sqlite: string | undefined;
+}
+/**
+ * Resolved framework configuration passed to plugin lifecycle hooks.
+ *
+ * Extracted from bunshotContext to break the bunshotContext ↔ plugin
+ * type cycle — this file has no dependency on either.
+ */
+export interface BunshotFrameworkConfig {
+    resolvedStores: ResolvedStores;
+    security: {
+        cors: string | string[];
+    };
+    signing: SigningConfig | null;
+    dataEncryptionKeys: DataEncryptionKey[];
+    redis: unknown | undefined;
+    mongo: {
+        auth: unknown | null;
+        app: unknown | null;
+    } | undefined;
+    captcha: unknown | null;
+    trustProxy: false | number;
+    registrar: CoreRegistrar;
+}

package/dist/packages/bunshot-core/src/context/frameworkConfig.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/bunshot-core/src/context/index.d.ts

@@ -0,0 +1,4 @@
+export type { BunshotContext, BunshotResolvedConfig, WsState, WsTransportHandle, UploadRuntimeState, ResolvedPersistence, } from './bunshotContext';
+export type { BunshotFrameworkConfig, ResolvedStores } from './frameworkConfig';
+export { attachContext, getContext, getContextOrNull } from './contextStore';
+export { resolveContext } from './contextAccess';

package/dist/packages/bunshot-core/src/context/index.js

@@ -0,0 +1,2 @@
+export { attachContext, getContext, getContextOrNull } from './contextStore';
+export { resolveContext } from './contextAccess';

package/dist/packages/bunshot-core/src/context.d.ts

@@ -0,0 +1,40 @@
+import { type Hook, OpenAPIHono } from '@hono/zod-openapi';
+import type { Context } from 'hono';
+import type { ZodIssue } from 'zod';
+import type { AuthVariables } from './authVariables';
+import type { BunshotContext } from './context/bunshotContext';
+import type { UploadResult } from './storageAdapter';
+export interface ValidationErrorDetail {
+    path: string;
+    message: string;
+}
+export interface DefaultValidationErrorBody {
+    error: string;
+    details: ValidationErrorDetail[];
+    requestId: string;
+}
+export type ValidationErrorFormatter = (issues: ZodIssue[], requestId: string) => unknown;
+export declare const defaultValidationErrorFormatter: ValidationErrorFormatter;
+export type AppVariables = {
+    requestId: string;
+    tenantId: string | null;
+    tenantConfig: Record<string, unknown> | null;
+    validationErrorFormatter: ValidationErrorFormatter;
+    uploadResults: UploadResult[] | null;
+    uploadBucket: string | undefined;
+    /** Instance-scoped BunshotContext, set by contextMiddleware on every request. */
+    bunshotCtx: BunshotContext;
+};
+export type AppEnv = {
+    Variables: AppVariables & AuthVariables;
+};
+export declare const defaultHook: Hook<any, AppEnv, any, any>;
+export declare const createRouter: () => OpenAPIHono<AppEnv, {}, "/">;
+/**
+ * Retrieve the BunshotContext from a Hono request context.
+ *
+ * Requires the context middleware to have run (mounted by `createApp()`).
+ * Throws if the context variable is not set — indicates the request is
+ * not flowing through a Bunshot-managed app.
+ */
+export declare function getBunshotCtx(c: Context<AppEnv>): BunshotContext;

package/dist/packages/bunshot-core/src/context.js

@@ -0,0 +1,35 @@
+import { OpenAPIHono } from '@hono/zod-openapi';
+export const defaultValidationErrorFormatter = (issues, requestId) => {
+    const error = issues.map(i => i.message).join(', ');
+    const details = issues.map(i => ({
+        path: i.path.join('.'),
+        message: i.message,
+    }));
+    return { error, details, requestId };
+};
+export const defaultHook = (result, c) => {
+    if (!result.success) {
+        const requestId = c.get('requestId') ?? 'unknown';
+        const formatter = c.get('validationErrorFormatter') ?? defaultValidationErrorFormatter;
+        try {
+            return c.json(formatter(result.error.issues, requestId), 400);
+        }
+        catch {
+            return c.json(defaultValidationErrorFormatter(result.error.issues, requestId), 400);
+        }
+    }
+};
+export const createRouter = () => new OpenAPIHono({ defaultHook });
+/**
+ * Retrieve the BunshotContext from a Hono request context.
+ *
+ * Requires the context middleware to have run (mounted by `createApp()`).
+ * Throws if the context variable is not set — indicates the request is
+ * not flowing through a Bunshot-managed app.
+ */
+export function getBunshotCtx(c) {
+    const ctx = c.get('bunshotCtx');
+    if (!ctx)
+        throw new Error('BunshotContext not available — is this a Bunshot-managed app?');
+    return ctx;
+}

package/dist/packages/bunshot-core/src/coreContracts.d.ts

@@ -0,0 +1,47 @@
+import type { MiddlewareHandler } from 'hono';
+export interface RouteAuthRegistry {
+    userAuth: MiddlewareHandler<any>;
+    requireRole(...roles: string[]): MiddlewareHandler<any>;
+}
+export interface UserResolver {
+    resolveUserId(req: Request): Promise<string | null>;
+}
+export interface RateLimitAdapter {
+    trackAttempt(key: string, opts: {
+        windowMs: number;
+        max: number;
+    }): Promise<boolean>;
+}
+export interface FingerprintBuilder {
+    buildFingerprint(req: Request): Promise<string>;
+}
+export interface CacheAdapter {
+    readonly name: string;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    del(key: string): Promise<void>;
+    delPattern(pattern: string): Promise<void>;
+    isReady(): boolean;
+}
+export type CacheStoreName = 'redis' | 'mongo' | 'sqlite' | 'memory' | 'postgres';
+export interface EmailTemplate {
+    subject: string;
+    html: string;
+    text?: string;
+}
+export interface CoreRegistrarSnapshot {
+    readonly routeAuth: RouteAuthRegistry | null;
+    readonly userResolver: UserResolver | null;
+    readonly rateLimitAdapter: RateLimitAdapter | null;
+    readonly fingerprintBuilder: FingerprintBuilder | null;
+    readonly cacheAdapters: ReadonlyMap<CacheStoreName, CacheAdapter>;
+    readonly emailTemplates: ReadonlyMap<string, EmailTemplate>;
+}
+export interface CoreRegistrar {
+    setRouteAuth(registry: RouteAuthRegistry): void;
+    setUserResolver(resolver: UserResolver): void;
+    setRateLimitAdapter(adapter: RateLimitAdapter): void;
+    setFingerprintBuilder(builder: FingerprintBuilder): void;
+    addCacheAdapter(store: CacheStoreName, adapter: CacheAdapter): void;
+    addEmailTemplates(templates: Record<string, EmailTemplate>): void;
+}

package/dist/packages/bunshot-core/src/coreContracts.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/bunshot-core/src/coreRegistrar.d.ts

@@ -0,0 +1,6 @@
+import type { CoreRegistrar, CoreRegistrarSnapshot } from './coreContracts';
+export type { CoreRegistrar, CoreRegistrarSnapshot };
+export declare function createCoreRegistrar(): {
+    registrar: CoreRegistrar;
+    drain(): CoreRegistrarSnapshot;
+};

package/dist/packages/bunshot-core/src/coreRegistrar.js

@@ -0,0 +1,42 @@
+export function createCoreRegistrar() {
+    let routeAuth = null;
+    let userResolver = null;
+    let rateLimitAdapter = null;
+    let fingerprintBuilder = null;
+    const cacheAdapters = new Map();
+    const emailTemplates = new Map();
+    return {
+        registrar: {
+            setRouteAuth(registry) {
+                routeAuth = registry;
+            },
+            setUserResolver(resolver) {
+                userResolver = resolver;
+            },
+            setRateLimitAdapter(adapter) {
+                rateLimitAdapter = adapter;
+            },
+            setFingerprintBuilder(builder) {
+                fingerprintBuilder = builder;
+            },
+            addCacheAdapter(store, adapter) {
+                cacheAdapters.set(store, adapter);
+            },
+            addEmailTemplates(templates) {
+                for (const [key, template] of Object.entries(templates)) {
+                    emailTemplates.set(key, template);
+                }
+            },
+        },
+        drain() {
+            return {
+                routeAuth,
+                userResolver,
+                rateLimitAdapter,
+                fingerprintBuilder,
+                cacheAdapters: new Map(cacheAdapters),
+                emailTemplates: new Map(emailTemplates),
+            };
+        },
+    };
+}

package/dist/{lib → packages/bunshot-core/src}/createRoute.d.ts

@@ -1,27 +1,5 @@
-import type { RouteConfig } from "@hono/zod-openapi";
-import type { ZodType } from "zod";
-/**
- * Sets the active version prefix for schema name generation and creates a unique
- * Symbol token for interleaving detection. Call before importing a version's route files.
- */
-export declare function setVersionPrefix(version: string): void;
-/**
- * Clears the active version prefix and token. Call after each version's route files
- * have been fully imported.
- */
-export declare function clearVersionPrefix(): void;
-/** Returns the current version token for assertion after import. */
-export declare function getVersionToken(): symbol | null;
-/**
- * Drains and returns all tokens captured by createRoute() calls since the last drain.
- * Used by versioned route discovery to detect interleaving.
- */
-export declare function drainCapturedTokens(): (symbol | null)[];
-/**
- * Asserts that all tokens in the array match the expected token.
- * Throws a clear startup error if any mismatch is detected.
- */
-export declare function assertCapturedTokens(tokens: (symbol | null)[], expectedToken: symbol | null): void;
+import type { RouteConfig } from '@hono/zod-openapi';
+import type { ZodType } from 'zod';
 /**
  * Registers a Zod schema as a named entry in `components/schemas`.
  *
@@ -75,13 +53,9 @@ export declare const withSecurity: <T extends RouteConfig>(route: T, ...schemes:
  * OpenAPI components so they appear in `components/schemas` instead of being
  * inlined at every use site. Generated names follow the convention:
  *
- *   {Version}{Method}{PathSegments}Request — request body (when versioning is active)
- *   {Version}{Method}{PathSegments}{Status} — response body (when versioning is active)
+ *   {Method}{PathSegments}Request
+ *   {Method}{PathSegments}{Status}
  *
  * Schemas already named via `.openapi("Name")` are never overwritten.
- *
- * When `setVersionPrefix` has been called, the version prefix is prepended to all
- * generated schema names and the current version token is captured for interleaving
- * detection via `drainCapturedTokens()` / `assertCapturedTokens()`.
  */
 export declare const createRoute: <T extends RouteConfig>(config: T) => T;