@lastshotlabs/bunshot 0.0.25 → 0.0.28

package/dist/app.d.ts

@@ -1,456 +0,0 @@
-import { OpenAPIHono } from "@hono/zod-openapi";
-import type { MiddlewareHandler } from "hono";
-import type { AppEnv, ValidationErrorFormatter } from "./lib/context";
-import type { RequestLogEntry, LogLevel } from "./middleware/requestLogger";
-import type { PrimaryField, EmailVerificationConfig, PasswordResetConfig, PasswordPolicyConfig, RefreshTokenConfig, MfaConfig, MfaEmailOtpConfig, MfaWebAuthnConfig, SigningConfig } from "./lib/appConfig";
-import type { AuthAdapter } from "./lib/authAdapter";
-import type { OAuthProviderConfig } from "./lib/oauth";
-type StoreType = "redis" | "mongo" | "sqlite" | "memory";
-export interface DbConfig {
-    /**
-     * Absolute path to the SQLite database file.
-     * Required when any store is "sqlite".
-     * Example: import.meta.dir + "/../data.db"
-     */
-    sqlite?: string;
-    /**
-     * MongoDB auto-connect mode.
-     * - "single" (default): calls connectMongo() — auth and app share one server (MONGO_* env vars)
-     * - "separate": calls connectAuthMongo() + connectAppMongo() — auth on MONGO_AUTH_* server, app on MONGO_* server
-     * - false: skip auto-connect (call connectMongo / connectAuthMongo / connectAppMongo yourself)
-     */
-    mongo?: "single" | "separate" | false;
-    /**
-     * Auto-connect Redis before starting. Defaults to true.
-     * Set false to skip (e.g. when using sqlite or memory stores only).
-     */
-    redis?: boolean;
-    /**
-     * Where to store JWT sessions. Default: "redis".
-     * Sessions are stored on appConnection (not authConnection) so they are isolated per-app
-     * in "separate" mongo mode.
-     */
-    sessions?: StoreType;
-    /**
-     * Where to store OAuth state (PKCE code verifier, link user ID). Default: follows `sessions`.
-     */
-    oauthState?: StoreType;
-    /**
-     * Global default store for cacheResponse middleware. Default: "redis".
-     * Can be overridden per-route via cacheResponse({ store: "..." }).
-     */
-    cache?: StoreType;
-    /**
-     * Which built-in auth adapter to use for /auth/* routes.
-     * - "mongo" (default when mongo is enabled): Mongoose adapter (requires connectMongo)
-     * - "sqlite": bun:sqlite adapter (requires sqlite path)
-     * - "memory": in-memory Maps (ephemeral, great for tests)
-     * When `mongo: false`, defaults to the same store as `sessions`.
-     * Ignored when `auth.adapter` is explicitly passed in CreateAppConfig.
-     */
-    auth?: "mongo" | "sqlite" | "memory";
-}
-export interface AppMeta {
-    /** App name shown in the root endpoint and OpenAPI docs title. Defaults to "Bun Core API" */
-    name?: string;
-    /** Version shown in OpenAPI docs. Defaults to "1.0.0" */
-    version?: string;
-}
-export interface OAuthConfig {
-    /** OAuth provider credentials. Configured providers get automatic /auth/{provider} routes. */
-    providers?: OAuthProviderConfig;
-    /** Where to redirect after a successful OAuth login. Defaults to "/" */
-    postRedirect?: string;
-    /** Allowlist of redirect URLs. If set, the postRedirect URL is validated against this list.
-     *  Relative paths (e.g., "/") are always allowed. Only absolute URLs are validated. */
-    allowedRedirectUrls?: string[];
-}
-export interface AuthRateLimitConfig {
-    /** Max login failures per window before the account is locked. Default: 10 per 15 min. */
-    login?: {
-        windowMs?: number;
-        max?: number;
-    };
-    /** Max registration attempts per IP per window. Default: 5 per hour. */
-    register?: {
-        windowMs?: number;
-        max?: number;
-    };
-    /** Max email verification attempts per IP per window. Default: 10 per 15 min. */
-    verifyEmail?: {
-        windowMs?: number;
-        max?: number;
-    };
-    /** Max resend-verification attempts per user per window. Default: 3 per hour. */
-    resendVerification?: {
-        windowMs?: number;
-        max?: number;
-    };
-    /** Max forgot-password requests per IP per window. Default: 5 per 15 min. */
-    forgotPassword?: {
-        windowMs?: number;
-        max?: number;
-    };
-    /** Max reset-password attempts per IP per window. Default: 10 per 15 min. */
-    resetPassword?: {
-        windowMs?: number;
-        max?: number;
-    };
-    /** Max account deletion attempts per user per window. Default: 3 per hour. */
-    deleteAccount?: {
-        windowMs?: number;
-        max?: number;
-    };
-    /** Max MFA verification attempts per IP per window. Default: 10 per 15 min. */
-    mfaVerify?: {
-        windowMs?: number;
-        max?: number;
-    };
-    /** Max MFA email OTP resend attempts per IP per window. Default: 5 per minute. */
-    mfaResend?: {
-        windowMs?: number;
-        max?: number;
-    };
-    /**
-     * Store backend for auth rate limit counters.
-     * Defaults to "redis" when Redis is enabled, otherwise "memory".
-     * Use "redis" for multi-instance deployments so limits are shared across servers.
-     */
-    store?: "memory" | "redis";
-}
-export interface AuthConfig {
-    /** Set false to skip mounting /auth/* routes. Defaults to true */
-    enabled?: boolean;
-    /**
-     * Custom auth adapter for the built-in /auth/* routes.
-     * Use this for fully custom backends (e.g. Postgres).
-     * For built-in backends prefer `db.auth: "mongo" | "sqlite" | "memory"`.
-     * When both are set, this takes precedence.
-     */
-    adapter?: AuthAdapter;
-    /** Valid roles for this app (e.g. ["admin", "editor", "user"]). Used by requireRole middleware. */
-    roles?: string[];
-    /** Role automatically assigned to new users on registration. Must be one of roles. */
-    defaultRole?: string;
-    /** OAuth provider and redirect configuration */
-    oauth?: OAuthConfig;
-    /**
-     * The primary identifier field used for registration and login.
-     * Defaults to "email". Use "username" or "phone" for apps that identify users differently.
-     * Email verification is only available when primaryField is "email".
-     */
-    primaryField?: PrimaryField;
-    /**
-     * Email verification configuration. Only active when primaryField is "email".
-     * Provide an onSend callback to send the verification email via any provider (Resend, SendGrid, etc.).
-     */
-    emailVerification?: EmailVerificationConfig;
-    /**
-     * Password reset configuration. Only active when primaryField is "email".
-     * Provide an onSend callback to send the reset email via any provider (Resend, SendGrid, etc.).
-     * Mounts POST /auth/forgot-password and POST /auth/reset-password.
-     */
-    passwordReset?: PasswordResetConfig;
-    /** Password strength policy for registration and reset-password.
-     *  Login is intentionally lenient (min 1) so users under older policies can still sign in.
-     *  Defaults: minLength=8, requireLetter=true, requireDigit=true, requireSpecial=false. */
-    passwordPolicy?: PasswordPolicyConfig;
-    /** Rate limit configuration for built-in auth endpoints. */
-    rateLimit?: AuthRateLimitConfig;
-    /** Session concurrency and metadata persistence policy. */
-    sessionPolicy?: AuthSessionPolicyConfig;
-    /** Account deletion configuration. Enables DELETE /auth/me when the adapter supports deleteUser. */
-    accountDeletion?: AccountDeletionConfig;
-    /**
-     * Refresh token configuration. When set, login/register return short-lived access tokens
-     * (default 15 min) alongside long-lived refresh tokens (default 30 days). Mounts POST /auth/refresh.
-     * When not configured, the existing 7-day JWT behavior is unchanged.
-     */
-    refreshTokens?: RefreshTokenConfig;
-    /**
-     * MFA/TOTP configuration. When set, enables MFA setup/verify/disable routes under /auth/mfa/*.
-     * Login returns { mfaRequired: true, mfaToken } when MFA is enabled for the user.
-     * OAuth logins skip MFA (the OAuth provider is treated as the second factor).
-     */
-    mfa?: MfaConfig;
-}
-export interface AccountDeletionConfig {
-    /** Called before deletion. Throw to abort (e.g., active subscription check). */
-    onBeforeDelete?: (userId: string) => Promise<void>;
-    /** Called after auth data is deleted. Runs at execution time — query current state, not a snapshot. */
-    onAfterDelete?: (userId: string) => Promise<void>;
-    /** When true, deletion is queued as a BullMQ job instead of running synchronously. Requires Redis + BullMQ. */
-    queued?: boolean;
-    /** Grace period in seconds before queued deletion executes. Default: 0 (immediate). */
-    gracePeriod?: number;
-    /** Called when deletion is scheduled (queued + gracePeriod > 0). Use to send a confirmation/cancel email. */
-    onDeletionScheduled?: (userId: string, email: string, cancelToken: string) => Promise<void>;
-}
-export interface AuthSessionPolicyConfig {
-    /** Max simultaneous active sessions per user. Oldest is evicted when exceeded. Default: 6. */
-    maxSessions?: number;
-    /**
-     * Retain session metadata (IP, user-agent, timestamps) after a session expires or is deleted.
-     * Enables future novel-device/location detection. Default: true.
-     */
-    persistSessionMetadata?: boolean;
-    /**
-     * Include inactive (expired/deleted) sessions in GET /auth/sessions.
-     * Only meaningful when persistSessionMetadata is true. Default: false.
-     */
-    includeInactiveSessions?: boolean;
-    /**
-     * Update lastActiveAt on every authenticated request.
-     * Adds one DB write per auth'd request. Default: false.
-     */
-    trackLastActive?: boolean;
-}
-export type { PrimaryField, EmailVerificationConfig, PasswordResetConfig, RefreshTokenConfig, MfaConfig, MfaEmailOtpConfig, MfaWebAuthnConfig, SigningConfig };
-export interface BotProtectionConfig {
-    /**
-     * List of IPv4 CIDRs (e.g. "198.51.100.0/24"), IPv4 addresses, or IPv6 addresses to block outright.
-     * Matched requests receive a 403 before any other processing.
-     * Example: ["198.51.100.0/24", "203.0.113.42"]
-     */
-    blockList?: string[];
-    /**
-     * Also rate-limit by HTTP fingerprint (User-Agent, Accept-*, Connection, browser header presence)
-     * in addition to IP. Bots that rotate IPs but use the same HTTP client share a bucket.
-     * Uses the same store as auth rate limiting (Redis or memory).
-     * Default: false
-     */
-    fingerprintRateLimit?: boolean;
-}
-export interface CsrfConfig {
-    /** Enable CSRF protection for cookie-authenticated state-changing requests. */
-    enabled: boolean;
-    /** Paths exempt from CSRF checks (in addition to built-in OAuth callback exemptions). Uses prefix matching when path ends with "*". */
-    exemptPaths?: string[];
-    /** Also validate Origin header against CORS origins. Default: true. */
-    checkOrigin?: boolean;
-}
-export interface SecurityConfig {
-    /** CORS origins. Defaults to "*" */
-    cors?: string | string[];
-    /** Additional security headers to set via Hono's secureHeaders middleware.
-     *  Pass a Content-Security-Policy, Permissions-Policy, etc. */
-    headers?: {
-        contentSecurityPolicy?: string;
-        permissionsPolicy?: string;
-    };
-    /** Global rate limit. Defaults to 100 req / 60s */
-    rateLimit?: {
-        windowMs: number;
-        max: number;
-    };
-    /**
-     * Bearer auth check. Set false to disable entirely.
-     * Pass an object with bypass paths (merged with built-in defaults: /docs, /health, /openapi.json, etc.).
-     * Defaults to enabled with no extra bypass paths.
-     */
-    bearerAuth?: boolean | {
-        bypass?: string[];
-    };
-    /**
-     * Bot protection: CIDR blocklist and fingerprint-based rate limiting.
-     * Runs before IP rate limiting so blocked IPs are rejected immediately.
-     */
-    botProtection?: BotProtectionConfig;
-    /**
-     * Trusted proxy configuration for IP extraction.
-     * - `false` (default): use socket-level IP only, ignore X-Forwarded-For entirely.
-     * - A number N: trust N proxy hops — take the Nth-from-right IP in the X-Forwarded-For chain.
-     */
-    trustProxy?: false | number;
-    /**
-     * CSRF protection for cookie-based auth. Opt-in.
-     * Uses signed double-submit cookie pattern with HMAC-SHA256.
-     * Only validates when the auth cookie is present on state-changing requests.
-     */
-    csrf?: CsrfConfig;
-    /**
-     * Unified HMAC signing for cookies, cursors, presigned URLs, request signing,
-     * idempotency key hashing, and session binding. All features are opt-in.
-     */
-    signing?: SigningConfig;
-}
-export interface ModelSchemasConfig {
-    /**
-     * One or more absolute directory paths or glob patterns containing shared Zod schemas.
-     * All matching .ts files are imported before routes so schemas are registered first.
-     * Optional when registration is "explicit" — in that case your registerSchema /
-     * registerSchemas calls run at the time each schema file is imported by a route.
-     * Examples:
-     *   import.meta.dir + "/schemas"
-     *   [import.meta.dir + "/schemas", import.meta.dir + "/models"]
-     *   import.meta.dir + "/models/**\/*.schema.ts"
-     */
-    paths?: string | string[];
-    /**
-     * How schemas found in the files are registered in `components/schemas`.
-     * - "auto" (default): exported Zod schemas are registered automatically. The export
-     *   name is used as the schema name, with a trailing "Schema" suffix stripped
-     *   (e.g. `LedgerItemSchema` → `"LedgerItem"`). Schemas already registered via
-     *   `registerSchema` or `registerSchemas` inside the file are never overwritten.
-     * - "explicit": files are imported but registration is entirely up to the user —
-     *   call `registerSchema` or `registerSchemas` inside each file.
-     */
-    registration?: "auto" | "explicit";
-}
-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" | import("hono").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;
-}
-export interface TenantConfig {
-    [key: string]: unknown;
-}
-export interface TenancyConfig {
-    /** How tenant is identified. */
-    resolution: "header" | "subdomain" | "path";
-    /** Header name when resolution is "header". Default: "x-tenant-id". */
-    headerName?: string;
-    /** Path segment index when resolution is "path". Default: 0. */
-    pathSegment?: number;
-    /** Callback to validate/load tenant. Return null to reject. */
-    onResolve?: (tenantId: string) => Promise<TenantConfig | null>;
-    /** TTL in ms for caching onResolve results (LRU cache). Default: 60_000. Set 0 to disable. */
-    cacheTtlMs?: number;
-    /** Max entries in tenant resolution cache. Default: 500. */
-    cacheMaxSize?: number;
-    /** Paths that skip tenant resolution. Uses startsWith matching. Default: ["/health", "/docs", "/openapi.json"]. */
-    exemptPaths?: string[];
-    /** HTTP status when onResolve returns null. Default: 403. */
-    rejectionStatus?: 403 | 404;
-}
-export interface LoggingConfig {
-    /** Enable structured request logging. Default: true. When false, no logger is registered at all. */
-    enabled?: boolean;
-    /** Custom log handler. Default: `console.log(JSON.stringify(entry))`. */
-    onLog?: (entry: RequestLogEntry) => void | Promise<void>;
-    /** Minimum log level to emit. Entries below this level are dropped. */
-    level?: LogLevel;
-    /**
-     * Paths to exclude from logging. Strings use **prefix matching**.
-     * Default: `["/health", "/docs", "/openapi.json"]`.
-     */
-    excludePaths?: (string | RegExp)[];
-    /** HTTP methods to exclude from logging (e.g. `["OPTIONS"]`). */
-    excludeMethods?: string[];
-}
-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[];
-}
-export interface ValidationConfig {
-    /** Custom formatter for Zod validation errors. Receives issues + requestId, returns the JSON body. */
-    formatError?: ValidationErrorFormatter;
-}
-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 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;
-}
-export interface CreateAppConfig {
-    /** Absolute path to the service's routes directory (use import.meta.dir + "/routes") */
-    routesDir: string;
-    /**
-     * Shared Zod schema sources. Files are imported before route discovery so schemas
-     * are registered before any route references them.
-     * Accepts a directory path, an array of paths/globs, or a full ModelSchemasConfig object.
-     * Shorthand string/array defaults to registration: "auto".
-     */
-    modelSchemas?: string | string[] | ModelSchemasConfig;
-    /** App name and version for the root endpoint and OpenAPI docs */
-    app?: AppMeta;
-    /** Auth, roles, and OAuth configuration */
-    auth?: AuthConfig;
-    /** Security: CORS, rate limiting, bearer auth */
-    security?: SecurityConfig;
-    /** Extra middleware injected after identify, before route matching */
-    middleware?: MiddlewareHandler<AppEnv>[];
-    /** Database connection and store routing configuration */
-    db?: DbConfig;
-    /** Job status endpoint configuration. Requires BullMQ + Redis. */
-    jobs?: JobsConfig;
-    /** Multi-tenancy configuration. When set, tenant middleware resolves tenant on each request. */
-    tenancy?: TenancyConfig;
-    /**
-     * Groups feature configuration. When set, the groups lib is available.
-     * Set managementRoutes to mount built-in CRUD routes for groups and memberships.
-     */
-    groups?: import("./routes/groups").GroupsConfig;
-    /** Structured request logging configuration. Replaces Hono's built-in text logger. */
-    logging?: LoggingConfig;
-    /** Prometheus-compatible /metrics endpoint. Opt-in. */
-    metrics?: MetricsConfig;
-    /** Zod validation error formatting configuration. */
-    validation?: ValidationConfig;
-    /** File upload configuration. When set, registers storage adapter and upload settings. */
-    upload?: UploadConfig;
-    /**
-     * API versioning configuration. When set, routes are discovered per-version from
-     * subdirectories of `routesDir` (e.g. `routes/v1/`, `routes/v2/`). Each version
-     * gets its own OpenAPI spec at `/{version}/openapi.json` and Scalar docs at
-     * `/{version}/docs`. Root `/docs` becomes a version selector.
-     */
-    versioning?: VersioningConfig;
-}
-export declare const createApp: (config: CreateAppConfig) => Promise<OpenAPIHono<AppEnv>>;