@lastshotlabs/bunshot 0.0.27 → 0.1.0

package/dist/src/framework/config/schema.js

@@ -0,0 +1,528 @@
+/**
+ * Zod schemas for full-depth config validation.
+ *
+ * These schemas validate the complete shape of CreateAppConfig and
+ * CreateServerConfig at startup — catching typos, wrong types, and structural
+ * errors at every nesting level. Type mismatches always throw.
+ * Unknown keys throw in production, warn in development.
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Validator for function-typed config fields. */
+const fnSchema = z.custom(v => typeof v === 'function', {
+    message: 'Expected a function',
+});
+// ---------------------------------------------------------------------------
+// Nested section schemas
+// ---------------------------------------------------------------------------
+// -- App --
+const appSectionSchema = z.object({
+    name: z.string().optional(),
+    version: z.string().optional(),
+});
+// -- Signing --
+const signingSchema = z.object({
+    secret: z.union([z.string(), z.array(z.string())]).optional(),
+    cookies: z.boolean().optional(),
+    cursors: z.boolean().optional(),
+    presignedUrls: z
+        .union([
+        z.boolean(),
+        z
+            .object({
+            defaultExpiry: z.number().optional(),
+        })
+            .passthrough(),
+    ])
+        .optional(),
+    requestSigning: z
+        .union([
+        z.boolean(),
+        z
+            .object({
+            tolerance: z.number().optional(),
+            header: z.string().optional(),
+            timestampHeader: z.string().optional(),
+        })
+            .passthrough(),
+    ])
+        .optional(),
+    idempotencyKeys: z.boolean().optional(),
+    sessionBinding: z
+        .union([
+        z.boolean(),
+        z
+            .object({
+            fields: z.array(z.enum(['ip', 'ua', 'accept-language'])).optional(),
+            onMismatch: z.enum(['unauthenticate', 'reject', 'log-only']).optional(),
+        })
+            .passthrough(),
+    ])
+        .optional(),
+});
+// -- Rate Limit --
+const rateLimitSchema = z.object({
+    windowMs: z.number().optional(),
+    max: z.number().optional(),
+    message: z.string().optional(),
+    standardHeaders: z.boolean().optional(),
+    keyGenerator: fnSchema.optional(),
+    skip: fnSchema.optional(),
+    handler: fnSchema.optional(),
+});
+// -- CORS --
+const corsObjectSchema = z.object({
+    origin: z.union([z.string(), z.array(z.string())]),
+    credentials: z.boolean().optional(),
+    allowHeaders: z.array(z.string()).optional(),
+    exposeHeaders: z.array(z.string()).optional(),
+    maxAge: z.number().optional(),
+});
+// -- Captcha --
+const captchaSchema = z.object({
+    provider: z.string(),
+    secretKey: z.string(),
+    minScore: z.number().optional(),
+    tokenField: z.string().optional(),
+    adaptive: z.boolean().optional(),
+    adaptiveThreshold: z.number().optional(),
+});
+// -- Bot Protection --
+const botProtectionSchema = z.object({
+    blockList: z.array(z.string()).optional(),
+    fingerprintRateLimit: z.boolean().optional(),
+});
+// -- Security --
+const securitySchema = z.object({
+    cors: z.union([z.string(), z.array(z.string()), corsObjectSchema.passthrough()]).optional(),
+    headers: z.union([z.boolean(), z.record(z.string(), z.unknown())]).optional(),
+    rateLimit: z.union([rateLimitSchema.passthrough(), z.literal(false)]).optional(),
+    botProtection: z.union([botProtectionSchema.passthrough(), z.literal(false)]).optional(),
+    trustProxy: z.union([z.literal(false), z.number()]).optional(),
+    signing: signingSchema.passthrough().optional(),
+    captcha: z.union([captchaSchema.passthrough(), z.literal(false)]).optional(),
+});
+// -- Db --
+const redisSchema = z.union([
+    z.boolean(),
+    z.string(),
+    z
+        .object({
+        url: z.string().optional(),
+        maxRetriesPerRequest: z.number().optional(),
+    })
+        .passthrough(),
+]);
+const dbSchema = z.object({
+    sqlite: z.string().optional(),
+    mongo: z.union([z.enum(['single', 'separate']), z.literal(false)]).optional(),
+    redis: redisSchema.optional(),
+    sessions: z.enum(['redis', 'mongo', 'sqlite', 'memory']).optional(),
+    oauthState: z.enum(['redis', 'mongo', 'sqlite', 'memory']).optional(),
+    cache: z.enum(['redis', 'mongo', 'sqlite', 'memory']).optional(),
+    auth: z.enum(['mongo', 'sqlite', 'memory']).optional(),
+});
+// -- Jobs --
+const jobsSchema = z.object({
+    statusEndpoint: z.boolean().optional(),
+    auth: z.union([z.enum(['userAuth', 'none']), z.array(z.unknown())]).optional(),
+    roles: z.array(z.string()).optional(),
+    allowedQueues: z.array(z.string()).optional(),
+    scopeToUser: z.boolean().optional(),
+    unsafePublic: z.boolean().optional(),
+});
+// -- Tenancy --
+const tenancySchema = z.object({
+    resolution: z.enum(['header', 'subdomain', 'path']),
+    headerName: z.string().optional(),
+    pathSegment: z.number().optional(),
+    onResolve: fnSchema.optional(),
+    cacheTtlMs: z.number().optional(),
+    cacheMaxSize: z.number().optional(),
+    exemptPaths: z.array(z.string()).optional(),
+    rejectionStatus: z.number().optional(),
+});
+// -- Logging --
+const loggingSchema = z.object({
+    enabled: z.boolean().optional(),
+    onLog: fnSchema.optional(),
+    level: z.enum(['debug', 'info', 'warn', 'error']).optional(),
+    excludePaths: z.array(z.union([z.string(), z.instanceof(RegExp)])).optional(),
+    excludeMethods: z.array(z.string()).optional(),
+});
+// -- Metrics --
+const metricsSchema = z.object({
+    enabled: z.boolean().optional(),
+    auth: z.union([z.enum(['userAuth', 'none']), z.array(z.unknown())]).optional(),
+    excludePaths: z.array(z.string()).optional(),
+    normalizePath: fnSchema.optional(),
+    queues: z.array(z.string()).optional(),
+    unsafePublic: z.boolean().optional(),
+});
+// -- Validation --
+const validationSchema = z.object({
+    formatError: fnSchema.optional(),
+});
+// -- Upload --
+const uploadPresignedSchema = z.object({
+    expirySeconds: z.number().optional(),
+    path: z.string().optional(),
+});
+const uploadSchema = z.object({
+    storage: z.any(),
+    maxFileSize: z.number().optional(),
+    maxFiles: z.number().optional(),
+    allowedMimeTypes: z.array(z.string()).optional(),
+    keyPrefix: z.string().optional(),
+    generateKey: fnSchema.optional(),
+    tenantScopedKeys: z.boolean().optional(),
+    presignedUrls: z.union([z.boolean(), uploadPresignedSchema.passthrough()]).optional(),
+    authorization: z
+        .object({
+        authorize: fnSchema.optional(),
+    })
+        .passthrough()
+        .optional(),
+    allowExternalKeys: z.boolean().optional(),
+});
+// -- Versioning --
+const versioningObjectSchema = z.object({
+    versions: z.array(z.string()),
+    sharedDir: z.string().optional(),
+    defaultVersion: z.string().optional(),
+});
+// -- ModelSchemas --
+const modelSchemasObjectSchema = z.object({
+    paths: z.union([z.string(), z.array(z.string())]).optional(),
+    registration: z.enum(['auto', 'explicit']).optional(),
+});
+// -- TLS --
+const tlsSchema = z.object({
+    key: z.any().optional(),
+    cert: z.any().optional(),
+    ca: z.any().optional(),
+    passphrase: z.string().optional(),
+    serverName: z.string().optional(),
+    dhParamsFile: z.string().optional(),
+    lowMemoryMode: z.boolean().optional(),
+    secureOptions: z.number().optional(),
+    rejectUnauthorized: z.boolean().optional(),
+    requestCert: z.boolean().optional(),
+});
+// -- WS Endpoint --
+const wsEndpointSchema = z.object({
+    upgrade: fnSchema.optional(),
+    on: z
+        .object({
+        open: fnSchema.optional(),
+        message: fnSchema.optional(),
+        close: fnSchema.optional(),
+        drain: fnSchema.optional(),
+    })
+        .passthrough()
+        .optional(),
+    onRoomSubscribe: fnSchema.optional(),
+    maxMessageSize: z.number().optional(),
+    heartbeat: z
+        .union([
+        z.boolean(),
+        z
+            .object({
+            intervalMs: z.number().optional(),
+            timeoutMs: z.number().optional(),
+        })
+            .passthrough(),
+    ])
+        .optional(),
+    presence: z
+        .union([
+        z.boolean(),
+        z
+            .object({
+            broadcastEvents: z.boolean().optional(),
+        })
+            .passthrough(),
+    ])
+        .optional(),
+    persistence: z
+        .object({
+        store: z.any().optional(),
+        defaults: z.any().optional(),
+    })
+        .passthrough()
+        .optional(),
+});
+// -- WS --
+const wsSchema = z.object({
+    endpoints: z.record(z.string(), wsEndpointSchema.passthrough()),
+    transport: z.any().optional(),
+    idleTimeout: z.number().optional(),
+    backpressureLimit: z.number().optional(),
+    closeOnBackpressureLimit: z.boolean().optional(),
+    perMessageDeflate: z.boolean().optional(),
+    publishToSelf: z.boolean().optional(),
+});
+// -- SSE Endpoint --
+const sseEndpointSchema = z.object({
+    events: z.array(z.string()),
+    upgrade: fnSchema.optional(),
+    filter: fnSchema.optional(),
+    heartbeat: z.union([z.number(), z.literal(false)]).optional(),
+});
+// -- SSE --
+const sseSchema = z.object({
+    endpoints: z.record(z.string(), sseEndpointSchema.passthrough()),
+});
+// ---------------------------------------------------------------------------
+// CreateAppConfig schema
+// ---------------------------------------------------------------------------
+export const appConfigSchema = z
+    .object({
+    routesDir: z.string(),
+    modelSchemas: z
+        .union([z.string(), z.array(z.string()), modelSchemasObjectSchema.passthrough()])
+        .optional(),
+    app: appSectionSchema.passthrough().optional(),
+    security: securitySchema.passthrough().optional(),
+    middleware: z.array(z.unknown()).optional(),
+    db: dbSchema.passthrough().optional(),
+    jobs: jobsSchema.passthrough().optional(),
+    tenancy: tenancySchema.passthrough().optional(),
+    logging: loggingSchema.passthrough().optional(),
+    metrics: metricsSchema.passthrough().optional(),
+    validation: validationSchema.passthrough().optional(),
+    upload: uploadSchema.passthrough().optional(),
+    versioning: z.union([versioningObjectSchema.passthrough(), z.array(z.string())]).optional(),
+    plugins: z.array(z.unknown()).optional(),
+    eventBus: z.unknown().optional(),
+    secrets: z.unknown().optional(),
+})
+    .passthrough();
+// ---------------------------------------------------------------------------
+// CreateServerConfig schema (extends app config)
+// ---------------------------------------------------------------------------
+export const serverConfigSchema = appConfigSchema
+    .extend({
+    port: z.number().optional(),
+    hostname: z.string().optional(),
+    unix: z.string().optional(),
+    tls: tlsSchema.passthrough().optional(),
+    workersDir: z.string().optional(),
+    enableWorkers: z.boolean().optional(),
+    ws: wsSchema.passthrough().optional(),
+    sse: sseSchema.passthrough().optional(),
+    maxRequestBodySize: z.number().optional(),
+})
+    .passthrough();
+// ---------------------------------------------------------------------------
+// Known key sets (for unknown-key detection at every level)
+// ---------------------------------------------------------------------------
+/**
+ * Map of section name → known keys for that section.
+ * Used to detect unknown/typo'd keys in nested config objects.
+ */
+const NESTED_KNOWN_KEYS = {
+    app: new Set(['name', 'version']),
+    security: new Set([
+        'cors',
+        'headers',
+        'rateLimit',
+        'botProtection',
+        'trustProxy',
+        'signing',
+        'captcha',
+    ]),
+    'security.cors': new Set(['origin', 'credentials', 'allowHeaders', 'exposeHeaders', 'maxAge']),
+    'security.rateLimit': new Set([
+        'windowMs',
+        'max',
+        'message',
+        'standardHeaders',
+        'keyGenerator',
+        'skip',
+        'handler',
+    ]),
+    'security.botProtection': new Set(['blockList', 'fingerprintRateLimit']),
+    'security.signing': new Set([
+        'secret',
+        'cookies',
+        'cursors',
+        'presignedUrls',
+        'requestSigning',
+        'idempotencyKeys',
+        'sessionBinding',
+    ]),
+    'security.signing.presignedUrls': new Set(['defaultExpiry']),
+    'security.signing.requestSigning': new Set(['tolerance', 'header', 'timestampHeader']),
+    'security.signing.sessionBinding': new Set(['fields', 'onMismatch']),
+    'security.captcha': new Set([
+        'provider',
+        'secretKey',
+        'minScore',
+        'tokenField',
+        'adaptive',
+        'adaptiveThreshold',
+    ]),
+    db: new Set(['sqlite', 'mongo', 'redis', 'sessions', 'oauthState', 'cache', 'auth']),
+    'db.redis': new Set(['url', 'maxRetriesPerRequest']),
+    jobs: new Set([
+        'statusEndpoint',
+        'auth',
+        'roles',
+        'allowedQueues',
+        'scopeToUser',
+        'unsafePublic',
+    ]),
+    tenancy: new Set([
+        'resolution',
+        'headerName',
+        'pathSegment',
+        'onResolve',
+        'cacheTtlMs',
+        'cacheMaxSize',
+        'exemptPaths',
+        'rejectionStatus',
+    ]),
+    logging: new Set(['enabled', 'onLog', 'level', 'excludePaths', 'excludeMethods']),
+    metrics: new Set(['enabled', 'auth', 'excludePaths', 'normalizePath', 'queues', 'unsafePublic']),
+    validation: new Set(['formatError']),
+    upload: new Set([
+        'storage',
+        'maxFileSize',
+        'maxFiles',
+        'allowedMimeTypes',
+        'keyPrefix',
+        'generateKey',
+        'tenantScopedKeys',
+        'presignedUrls',
+        'authorization',
+        'allowExternalKeys',
+    ]),
+    'upload.presignedUrls': new Set(['expirySeconds', 'path']),
+    versioning: new Set(['versions', 'sharedDir', 'defaultVersion']),
+    modelSchemas: new Set(['paths', 'registration']),
+    tls: new Set([
+        'key',
+        'cert',
+        'ca',
+        'passphrase',
+        'serverName',
+        'dhParamsFile',
+        'lowMemoryMode',
+        'secureOptions',
+        'rejectUnauthorized',
+        'requestCert',
+    ]),
+    ws: new Set([
+        'endpoints',
+        'transport',
+        'idleTimeout',
+        'backpressureLimit',
+        'closeOnBackpressureLimit',
+        'perMessageDeflate',
+        'publishToSelf',
+    ]),
+    sse: new Set(['endpoints']),
+};
+const APP_CONFIG_KEYS = new Set([
+    'routesDir',
+    'modelSchemas',
+    'app',
+    'security',
+    'middleware',
+    'db',
+    'jobs',
+    'tenancy',
+    'logging',
+    'metrics',
+    'validation',
+    'upload',
+    'versioning',
+    'plugins',
+    'eventBus',
+    'secrets',
+]);
+const SERVER_EXTRA_KEYS = new Set([
+    'port',
+    'hostname',
+    'unix',
+    'tls',
+    'workersDir',
+    'enableWorkers',
+    'ws',
+    'sse',
+    'maxRequestBodySize',
+]);
+const SERVER_CONFIG_KEYS = new Set([...APP_CONFIG_KEYS, ...SERVER_EXTRA_KEYS]);
+// Sections to skip for nested unknown-key checking (runtime objects, not config shapes)
+const SKIP_NESTED_CHECK = new Set(['middleware', 'plugins', 'eventBus']);
+/**
+ * Validate a CreateAppConfig at startup.
+ * - Throws on type mismatches or missing required fields.
+ * - Returns warnings for unknown keys at any depth.
+ */
+export function validateAppConfig(config) {
+    return validateConfig(config, appConfigSchema, APP_CONFIG_KEYS);
+}
+/**
+ * Validate a CreateServerConfig at startup.
+ * - Throws on type mismatches or missing required fields.
+ * - Returns warnings for unknown keys at any depth.
+ */
+export function validateServerConfig(config) {
+    return validateConfig(config, serverConfigSchema, SERVER_CONFIG_KEYS);
+}
+function validateConfig(config, schema, knownKeys) {
+    const result = schema.safeParse(config);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map(issue => {
+            const path = issue.path.join('.');
+            return path ? `  - ${path}: ${issue.message}` : `  - ${issue.message}`;
+        })
+            .join('\n');
+        throw new Error(`[bunshot] Invalid config:\n${issues}`);
+    }
+    // Detect unknown keys at top level and all nested levels
+    const warnings = [];
+    // Top-level unknown keys
+    for (const key of Object.keys(config)) {
+        if (!knownKeys.has(key)) {
+            warnings.push(`[bunshot] Unknown config key "${key}" — will be ignored. Check for typos.`);
+        }
+    }
+    // Nested unknown keys
+    collectNestedUnknownKeys(config, '', warnings);
+    // In production, unknown config keys are errors — fail fast, don't silently misconfigure.
+    if (warnings.length > 0 && process.env.NODE_ENV === 'production') {
+        throw new Error(`[bunshot] Config validation failed in production:\n${warnings.join('\n')}\n` +
+            `Fix the config keys above or remove them. Unknown keys are not allowed in production.`);
+    }
+    return { warnings };
+}
+/**
+ * Recursively walk nested config objects and warn about unknown keys.
+ * Uses NESTED_KNOWN_KEYS to determine which keys are valid at each path.
+ */
+function collectNestedUnknownKeys(obj, parentPath, warnings) {
+    for (const [key, value] of Object.entries(obj)) {
+        if (SKIP_NESTED_CHECK.has(key) && parentPath === '')
+            continue;
+        const currentPath = parentPath ? `${parentPath}.${key}` : key;
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            const knownKeys = NESTED_KNOWN_KEYS[currentPath];
+            if (knownKeys) {
+                const nested = value;
+                for (const nestedKey of Object.keys(nested)) {
+                    if (!knownKeys.has(nestedKey)) {
+                        warnings.push(`[bunshot] Unknown config key "${currentPath}.${nestedKey}" — will be ignored. Check for typos.`);
+                    }
+                }
+                // Recurse into known sub-sections
+                collectNestedUnknownKeys(nested, currentPath, warnings);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,76 @@
+import type { frameworkSecretSchema } from './secrets/frameworkSecretSchema';
+import type { SigningConfig } from '../lib/signingConfig';
+import type { Connection } from 'mongoose';
+import type { BunshotFrameworkConfig, CaptchaConfig, CoreRegistrar, DataEncryptionKey, ResolvedPersistence, ResolvedSecrets, ResolvedStores, StoreType } from '../../packages/bunshot-core/src/index.js';
+import type { DrizzlePostgresDb } from '@lastshotlabs/bunshot-postgres';
+export interface DbConfig {
+    sqlite?: string;
+    mongo?: 'single' | 'separate' | false;
+    redis?: boolean;
+    /** Postgres connection string. When set, postgres becomes the default store. */
+    postgres?: string;
+    sessions?: StoreType;
+    oauthState?: StoreType;
+    cache?: StoreType;
+    auth?: 'mongo' | 'sqlite' | 'memory' | 'postgres';
+}
+export type { ResolvedStores };
+/**
+ * The frameworkConfig object passed to all plugin phase methods.
+ * This is the shape plugins currently receive.
+ */
+export interface FrameworkConfig extends BunshotFrameworkConfig {
+    mongo: {
+        auth: Connection | null;
+        app: Connection | null;
+    } | undefined;
+    captcha: CaptchaConfig | null;
+    registrar: CoreRegistrar;
+}
+export interface InfrastructureResult {
+    /** The frameworkConfig object passed to plugin lifecycle methods. */
+    frameworkConfig: FrameworkConfig;
+    /** Resolved store selections. */
+    resolvedStores: ResolvedStores;
+    /** Whether Redis is connected and available. */
+    redisEnabled: boolean;
+    /** Mongo connection mode. */
+    mongoMode: 'single' | 'separate' | false;
+    /** Data encryption keys resolved from env. */
+    dataEncryptionKeys: DataEncryptionKey[];
+    /** Resolved CORS origins. */
+    corsOrigins: string | string[];
+    /** Resolved persistence repositories — upload registry, idempotency, WS messages, audit log. */
+    persistence: ResolvedPersistence;
+    /** SQLite database handle, or null when SQLite is disabled. */
+    sqliteDb: import('bun:sqlite').Database | null;
+    /** Redis client handle, or null when Redis is disabled. */
+    redis: import('ioredis').default | null;
+    /** Mongo connection handles, or null when Mongo is disabled. */
+    mongo: {
+        auth: Connection | null;
+        app: Connection | null;
+        mongoose: typeof import('mongoose');
+    } | null;
+    /** Postgres connection bundle, or null when Postgres is not configured. */
+    postgres: DrizzlePostgresDb | null;
+}
+export interface InfrastructureOptions {
+    db: DbConfig;
+    securitySigning?: SigningConfig | null;
+    cors?: string | string[];
+    captcha?: CaptchaConfig;
+    trustProxy?: false | number;
+    registrar: CoreRegistrar;
+    /** Resolved framework secrets from ISecretRepository. Credentials are passed to connect functions — no process.env fallback. */
+    secrets: ResolvedSecrets<typeof frameworkSecretSchema>;
+    /** TTL in seconds for upload registry entries. Default: 2592000 (30 days). */
+    uploadRegistryTtlSeconds?: number;
+    /** Retention in days for audit log entries. SQLite: prunes on write. MongoDB: sets expiresAt for the TTL index. Undefined = no automatic pruning. */
+    auditLogTtlDays?: number;
+}
+/**
+ * Connect databases, resolve store preferences, configure trust-proxy,
+ * and assemble the frameworkConfig object that plugins receive.
+ */
+export declare function createInfrastructure(options: InfrastructureOptions): Promise<InfrastructureResult>;