@lastshotlabs/bunshot 0.0.21 → 0.0.27

package/dist/app.d.ts

@@ -1,10 +1,13 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { MiddlewareHandler } from "hono";
-import type { AppEnv } from "./lib/context";
-import type { PrimaryField, EmailVerificationConfig, PasswordResetConfig, PasswordPolicyConfig, RefreshTokenConfig, MfaConfig, MfaEmailOtpConfig, MfaWebAuthnConfig } from "./lib/appConfig";
+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, JwtConfig, BreachedPasswordConfig, StepUpConfig, M2MConfig, OidcConfig, SamlConfig, ScimConfig } from "./lib/appConfig";
+import type { CaptchaConfig } from "./lib/captcha";
 import type { AuthAdapter } from "./lib/authAdapter";
 import type { OAuthProviderConfig } from "./lib/oauth";
 type StoreType = "redis" | "mongo" | "sqlite" | "memory";
+export type { BreachedPasswordConfig } from "./lib/appConfig";
 export interface DbConfig {
     /**
      * Absolute path to the SQLite database file.
@@ -116,6 +119,22 @@ export interface AuthRateLimitConfig {
      * Use "redis" for multi-instance deployments so limits are shared across servers.
      */
     store?: "memory" | "redis";
+    /** Credential stuffing detection. Tracks distinct accounts per IP and IPs per account. */
+    credentialStuffing?: {
+        maxAccountsPerIp?: {
+            count: number;
+            windowMs: number;
+        };
+        maxIpsPerAccount?: {
+            count: number;
+            windowMs: number;
+        };
+        onDetected?: (signal: {
+            type: "ip" | "account";
+            key: string;
+            count: number;
+        }) => void;
+    };
 }
 export interface AuthConfig {
     /** Set false to skip mounting /auth/* routes. Defaults to true */
@@ -172,6 +191,49 @@ export interface AuthConfig {
      * OAuth logins skip MFA (the OAuth provider is treated as the second factor).
      */
     mfa?: MfaConfig;
+    /**
+     * JWT claims configuration. When set, `iss`, `aud`, and `iat` are included in all tokens.
+     * Tokens with a non-matching issuer or audience will fail verification.
+     *
+     * - **`iss`** (issuer) and **`aud`** (audience) are validated on every token verification when
+     *   configured. A token issued for a different issuer or intended for a different audience is
+     *   rejected outright.
+     * - **`iat`** (issued-at) is always included in tokens once this config is set. Use it to detect
+     *   token reuse or implement absolute expiry windows independent of `exp`.
+     *
+     * Recommended for fintech and multi-service deployments where tokens from one service should
+     * never be accepted by another.
+     * Use `algorithm: "RS256"` to enable OIDC mode.
+     */
+    jwt?: JwtConfig;
+    /**
+     * When true, suspension status is checked on every authenticated request (via identify middleware).
+     * This adds one adapter call per request. Default: false.
+     * Suspension is always enforced at login time regardless of this setting.
+     */
+    checkSuspensionOnIdentify?: boolean;
+    /**
+     * Breached password detection using the HaveIBeenPwned k-Anonymity API.
+     * Checks passwords at registration and reset. No full hash leaves the server.
+     */
+    breachedPasswordCheck?: BreachedPasswordConfig;
+    /**
+     * Step-up MFA configuration. When set, the requireStepUp() middleware and
+     * POST /auth/step-up endpoint are available. Requires auth.mfa to be configured.
+     */
+    stepUp?: StepUpConfig;
+    /** M2M client credentials configuration. Enables POST /oauth/token with client_credentials grant. */
+    m2m?: M2MConfig;
+    /**
+     * OIDC discovery and RS256 JWT signing configuration.
+     * When set, mounts /.well-known/openid-configuration and /.well-known/jwks.json.
+     * Auto-generates an RSA-2048 key pair on startup if signingKey is not provided.
+     */
+    oidc?: OidcConfig;
+    /** SAML 2.0 SSO configuration. Enables /auth/saml/* routes. Requires samlify peer dependency. */
+    saml?: SamlConfig;
+    /** SCIM 2.0 user provisioning. Enables /scim/v2/* endpoints with its own bearer token. */
+    scim?: ScimConfig;
 }
 export interface AccountDeletionConfig {
     /** Called before deletion. Throw to abort (e.g., active subscription check). */
@@ -204,7 +266,8 @@ export interface AuthSessionPolicyConfig {
      */
     trackLastActive?: boolean;
 }
-export type { PrimaryField, EmailVerificationConfig, PasswordResetConfig, RefreshTokenConfig, MfaConfig, MfaEmailOtpConfig, MfaWebAuthnConfig };
+export type { PrimaryField, EmailVerificationConfig, PasswordResetConfig, RefreshTokenConfig, MfaConfig, MfaEmailOtpConfig, MfaWebAuthnConfig, SigningConfig, JwtConfig, StepUpConfig, OidcConfig, SamlConfig, ScimConfig };
+export type { CaptchaConfig, CaptchaProvider } from "./lib/captcha";
 export interface BotProtectionConfig {
     /**
      * List of IPv4 CIDRs (e.g. "198.51.100.0/24"), IPv4 addresses, or IPv6 addresses to block outright.
@@ -267,6 +330,16 @@ export interface SecurityConfig {
      * 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;
+    /**
+     * Global CAPTCHA configuration. When set, use requireCaptcha() middleware on specific routes,
+     * or enable adaptive mode to auto-require CAPTCHA after rate limit thresholds.
+     */
+    captcha?: CaptchaConfig;
 }
 export interface ModelSchemasConfig {
     /**
@@ -309,6 +382,12 @@ export interface JobsConfig {
     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 TenantConfig {
     [key: string]: unknown;
@@ -331,6 +410,101 @@ export interface TenancyConfig {
     /** 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[];
+    /**
+     * 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 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;
+    /**
+     * 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 interface CreateAppConfig {
     /** Absolute path to the service's routes directory (use import.meta.dir + "/routes") */
     routesDir: string;
@@ -355,5 +529,31 @@ export interface CreateAppConfig {
     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;
+    /**
+     * Security event streaming (SIEM integration). When set, auth and security events
+     * are emitted to the provided onEvent callback. Non-blocking — errors are swallowed.
+     * Use include/exclude to filter event types.
+     */
+    securityEvents?: import("./lib/securityEvents").SecurityEventConfig;
 }
 export declare const createApp: (config: CreateAppConfig) => Promise<OpenAPIHono<AppEnv>>;