@iskra-bun/web-kit 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @iskra-bun/web-kit
 
+## 0.2.0
+
+### Minor Changes
+
+- **Breaking:** public class renames for naming consistency with the `Driver`/`Feature` conventions:
+
+    - `WebServer` → `WebDriver` (same `{ port, routes }` options).
+    - `HealthFeature` → `HealthCheckFeature`.
+
+    Update imports accordingly: `import { WebDriver } from '@iskra-bun/web-kit'`. See the "Upgrading to 0.2" guide for the full migration. (Pre-1.0, but bumped as a minor to signal the break.)
+
+### Patch Changes
+
+- f9654df: `DbDriver` and `DbFeature` now accept an optional schema generic (`DbDriver<TSchema>` / `DbFeature<TSchema>`), so `.db` is a typed Drizzle database instead of `any` — opt-in callers get typed relational queries and autocomplete. The generic defaults preserve existing behavior, so no call site needs changes; consumers that relied on `any` may need to add a type argument or annotation.
+- f9654df: Internal refactor: the email, storage, and auth features now delegate to the new standalone `@iskra-bun/mailer-kit`, `@iskra-bun/storage-kit`, and `@iskra-bun/auth-kit` packages instead of bundling their own copies. The public API (`EmailFeature`, `StorageFeature`, `AuthFeature`, and the types/adapters they re-export) is unchanged. The now-transitive `nodemailer`, `@sendgrid/mail`, and `@aws-sdk/*` direct dependencies were dropped. Note: `MockEmailAdapter` no longer prints a `console.log` line on send (it is now silent).
+- Security fixes for the web server:
+
+    - The health endpoint no longer leaks internal details by default: `includeDetails` defaults to `false`, failing feature/custom/db checks return only `{ status: 'error' }`, and the raw error is logged server-side only instead of being returned in the response.
+    - API keys are no longer used verbatim as cache keys — the cache key is now a SHA-256 hash of the key, so raw secrets are kept out of the cache layer.
+    - The CSRF kill-switch (`disableCSRFCheck`) is ignored in production: it is only forwarded when `NODE_ENV !== 'production'`, so CSRF protection cannot be accidentally disabled in a production deployment.
+
+- f9654df: Security and correctness fixes:
+
+    - API key ids are now random and no longer expose a prefix of the secret key.
+    - CSRF tokens are HMAC-signed (signed double-submit cookie) and compared in constant time; forged, tampered, and unsigned tokens are rejected.
+    - `/health/ready` now runs readiness checks registered via `addReadinessCheck()` and returns 503 when any fails, instead of always reporting ready.
+
+- Updated dependencies [f9654df]
+- Updated dependencies
+- Updated dependencies [f9654df]
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies [f9654df]
+- Updated dependencies [f9654df]
+- Updated dependencies [f9654df]
+- Updated dependencies
+    - @iskra-bun/auth-kit@0.1.0
+    - @iskra-bun/core@0.1.1
+    - @iskra-bun/mailer-kit@0.1.0
+    - @iskra-bun/storage-kit@0.1.0
+
 ## 0.1.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -4,9 +4,17 @@ import { Driver, App, IskraError, ErrorCode } from '@iskra-bun/core';
 export { ErrorCode, ErrorCodes } from '@iskra-bun/core';
 import { z } from 'zod';
 import { HTTPException } from 'hono/http-exception';
-import { Auth as Auth$1 } from 'better-auth';
+import * as _iskra_bun_storage_kit from '@iskra-bun/storage-kit';
+import { BaseStorageAdapter, StorageConfig } from '@iskra-bun/storage-kit';
+export { BaseStorageAdapter, LocalStorageAdapter, StorageConfig, StorageFile } from '@iskra-bun/storage-kit';
+import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import { MySql2Database } from 'drizzle-orm/mysql2';
+import { BunSQLiteDatabase } from 'drizzle-orm/bun-sqlite';
+import { User, createBetterAuth, Auth } from '@iskra-bun/auth-kit';
 import * as hono_utils_types from 'hono/utils/types';
 import { ErrorObject } from 'ajv';
+import { EmailAdapter, EmailConfig } from '@iskra-bun/mailer-kit';
+export { EmailAdapter, EmailConfig, EmailMessage, MockEmailAdapter, TemplateData } from '@iskra-bun/mailer-kit';
 export { OpenAPIHono, createRoute, z } from '@hono/zod-openapi';
 
 /**
@@ -140,6 +148,9 @@ interface HealthCheckConfig {
             details?: any;
         }>;
     };
+    readinessChecks?: {
+        [name: string]: () => Promise<boolean>;
+    };
 }
 interface RequestIdConfig {
     headerName?: string;
@@ -336,6 +347,7 @@ declare class WebDriver implements Driver {
     private runningServer;
     constructor(options?: WebServerOptions);
     init(app: App): void;
+    private setupSecurityHeaders;
     private setupOpenApi;
     private setupRoutes;
     start(): void;
@@ -363,7 +375,9 @@ declare class HealthCheckFeature implements Feature {
     name: string;
     private kernel?;
     private config;
+    private readinessChecks;
     constructor(config?: HealthCheckConfig);
+    addReadinessCheck(name: string, check: () => Promise<boolean>): void;
     initialize(kernel: Kernel): Promise<void>;
     private handleHealthCheck;
     private checkFeatureHealth;
@@ -397,78 +411,6 @@ declare class RequestIdFeature implements Feature {
     private defaultGenerator;
 }
 
-interface StorageConfig {
-    adapter: "local" | "minio" | "s3";
-    basePath?: string;
-    connection?: {
-        endpoint?: string;
-        accessKey?: string;
-        secretKey?: string;
-        bucket?: string;
-        region?: string;
-        useSSL?: boolean;
-    };
-}
-interface StorageFile {
-    name: string;
-    path: string;
-    size: number;
-    mimeType?: string;
-    lastModified?: Date;
-    url?: string;
-}
-interface PutOptions {
-    contentType?: string;
-    metadata?: Record<string, string>;
-    public?: boolean;
-}
-interface StorageAdapter {
-    connect(): Promise<void>;
-    disconnect(): Promise<void>;
-    put(path: string, data: Uint8Array | Buffer | ReadableStream, options?: PutOptions): Promise<StorageFile>;
-    get(path: string): Promise<Uint8Array | null>;
-    delete(path: string): Promise<void>;
-    exists(path: string): Promise<boolean>;
-    list(prefix?: string): Promise<StorageFile[]>;
-    url(path: string, expiresIn?: number): Promise<string>;
-    copy(from: string, to: string): Promise<void>;
-    move(from: string, to: string): Promise<void>;
-    isDirectory(path: string): Promise<boolean>;
-}
-declare abstract class BaseStorageAdapter implements StorageAdapter {
-    protected connected: boolean;
-    abstract connect(): Promise<void>;
-    abstract disconnect(): Promise<void>;
-    abstract put(path: string, data: Uint8Array | Buffer | ReadableStream, options?: PutOptions): Promise<StorageFile>;
-    abstract get(path: string): Promise<Uint8Array | null>;
-    abstract delete(path: string): Promise<void>;
-    abstract exists(path: string): Promise<boolean>;
-    abstract list(prefix?: string): Promise<StorageFile[]>;
-    abstract url(path: string, expiresIn?: number): Promise<string>;
-    abstract isDirectory(path: string): Promise<boolean>;
-    isConnected(): boolean;
-    protected ensureConnected(): void;
-    copy(from: string, to: string): Promise<void>;
-    move(from: string, to: string): Promise<void>;
-    protected generateFileName(originalName: string): string;
-    protected sanitizePath(path: string): string;
-    protected getMimeType(filename: string): string;
-}
-
-declare class LocalStorageAdapter extends BaseStorageAdapter {
-    private basePath;
-    constructor(config: StorageConfig);
-    connect(): Promise<void>;
-    disconnect(): Promise<void>;
-    put(filePath: string, data: Uint8Array | Buffer, options?: PutOptions): Promise<StorageFile>;
-    get(filePath: string): Promise<Uint8Array | null>;
-    delete(filePath: string): Promise<void>;
-    exists(filePath: string): Promise<boolean>;
-    isDirectory(filePath: string): Promise<boolean>;
-    list(prefix?: string): Promise<StorageFile[]>;
-    url(filePath: string, _expiresIn?: number): Promise<string>;
-}
-
 declare module "hono" {
     interface ContextVariableMap {
         storage: BaseStorageAdapter;
@@ -484,16 +426,24 @@ declare class StorageFeature implements Feature {
     getAdapter(): BaseStorageAdapter | undefined;
 }
 
+/**
+ * The Drizzle database handle a {@link DbFeature} exposes, parameterized by the
+ * caller's schema. A union of the supported dialect databases — all share the
+ * same `TSchema extends Record<string, unknown> = Record<string, never>`
+ * parameter, so passing a schema types `db.query.*` for opt-in callers while the
+ * default `Record<string, never>` reproduces the historical untyped behavior.
+ */
+type WebKitDrizzleDb<TSchema extends Record<string, unknown> = Record<string, never>> = PostgresJsDatabase<TSchema> | MySql2Database<TSchema> | BunSQLiteDatabase<TSchema>;
 declare module "hono" {
     interface ContextVariableMap {
-        db: any;
+        db: WebKitDrizzleDb;
     }
 }
-declare class DbFeature implements Feature {
+declare class DbFeature<TSchema extends Record<string, unknown> = Record<string, never>> implements Feature {
     private config;
     name: string;
     private client;
-    db: any;
+    db: WebKitDrizzleDb<TSchema>;
     readonly adapter: string;
     constructor(config: DbConfig);
     initialize(kernel: Kernel): Promise<void>;
@@ -541,55 +491,6 @@ declare class SessionFeature implements Feature {
     shutdown(): Promise<void>;
 }
 
-interface BetterAuthConfigOptions {
-    db: any;
-    adapterType: "postgres" | "mysql" | "sqlite";
-    secret: string;
-    baseURL?: string;
-    basePath?: string;
-    trustedOrigins?: string[];
-    enableEmailPassword?: boolean;
-    disableCSRFCheck?: boolean;
-    socialProviders?: Record<string, any>;
-    oidcConfig?: {
-        clientId: string;
-        clientSecret: string;
-        issuer: string;
-        providerId?: string;
-        authorizationEndpoint?: string;
-        tokenEndpoint?: string;
-        userinfoEndpoint?: string;
-        jwksEndpoint?: string;
-        discoveryEndpoint?: string;
-        scopes?: string[];
-        pkce?: boolean;
-        mapping?: {
-            id?: string;
-            email?: string;
-            emailVerified?: string;
-            name?: string;
-            image?: string;
-            extraFields?: Record<string, string>;
-        };
-    };
-}
-declare function createBetterAuth(options: BetterAuthConfigOptions): Auth$1;
-type Auth = ReturnType<typeof createBetterAuth>;
-
-/**
- * Auth feature types and interfaces
- */
-interface User {
-    id: string;
-    email: string;
-    emailVerified: boolean;
-    name?: string | null;
-    image?: string | null;
-    createdAt: Date;
-    updatedAt: Date;
-    [key: string]: any;
-}
-
 declare module "hono" {
     interface ContextVariableMap {
         user: User | null;
@@ -603,8 +504,13 @@ declare class AuthFeature implements Feature {
     private config;
     private kernel?;
     private authMode;
-    constructor(config: AuthConfig);
+    private createAuth;
+    constructor(config: AuthConfig, createAuth?: typeof createBetterAuth);
     initialize(kernel: Kernel): Promise<void>;
+    private authRateLimitHits;
+    private readonly authRateLimitWindowMs;
+    private readonly authRateLimitMax;
+    private authRateLimitMiddleware;
     routes(app: Hono): void;
     getAuth(): Auth | undefined;
 }
@@ -644,17 +550,19 @@ declare class PermissionsFeature implements Feature {
 declare function requirePermission(permission: string): (c: Context, next: Next) => Promise<void>;
 declare function requireRole(role: string): (c: Context, next: Next) => Promise<void>;
 
+type ResolvedApiKeyConfig = Required<Omit<ApiKeyConfig, "vaultService" | "customExtractor" | "onError" | "onValidated">> & Pick<ApiKeyConfig, "vaultService" | "customExtractor" | "onError" | "onValidated">;
 declare class ApiKeyStore {
     private config;
     private kernel;
     private staticKeysMap;
     private cache?;
-    constructor(config: Required<ApiKeyConfig>, kernel: Kernel);
+    constructor(config: ResolvedApiKeyConfig, kernel: Kernel);
     private getCache;
     private initializeStaticKeys;
     private generateId;
     private compareKeys;
     private isExpired;
+    private cacheKeyFor;
     validate(key: string): Promise<ApiKeyValidationResult>;
     hasScopes(key: ApiKeyMetadata, requiredScopes: string[]): boolean;
 }
@@ -787,10 +695,11 @@ declare class UploadHelper {
     private basePath;
     constructor(storage: BaseStorageAdapter, projectName: string);
     getBasePath(): string;
+    private safeBasename;
     private buildPath;
     upload(filename: string, data: Uint8Array | string, subfolder?: string, options?: UploadOptions): Promise<UploadResult>;
     uploadFromRequest(request: Request, fieldName: string, subfolder?: string, options?: UploadOptions): Promise<UploadResult>;
-    list(subfolder?: string): Promise<StorageFile[]>;
+    list(subfolder?: string): Promise<_iskra_bun_storage_kit.StorageFile[]>;
     get(filename: string, subfolder?: string): Promise<Uint8Array<ArrayBufferLike> | null>;
     delete(filename: string, subfolder?: string): Promise<void>;
     getUrl(filename: string, subfolder?: string, expiresIn?: number): Promise<string>;
@@ -829,68 +738,6 @@ declare class OtelTracingFeature implements Feature {
     initialize(kernel: Kernel): Promise<void>;
 }
 
-interface EmailConfig {
-    provider: "smtp" | "sendgrid" | "mock" | "mailgun" | "ses";
-    smtp?: {
-        host: string;
-        port: number;
-        username: string;
-        password: string;
-        secure?: boolean;
-    };
-    apiKey?: string;
-    apiSecret?: string;
-    region?: string;
-    domain?: string;
-    baseUrl?: string;
-    from?: {
-        name?: string;
-        email: string;
-    };
-    templateDir?: string;
-}
-interface EmailMessage {
-    to: string | string[];
-    from?: {
-        name?: string;
-        email: string;
-    };
-    subject: string;
-    text?: string;
-    html?: string;
-    cc?: string | string[];
-    bcc?: string | string[];
-    replyTo?: string;
-    attachments?: Array<{
-        filename: string;
-        content: Uint8Array | string;
-        contentType?: string;
-    }>;
-    headers?: Record<string, string>;
-}
-interface TemplateData {
-    [key: string]: unknown;
-}
-interface EmailAdapter {
-    send(message: EmailMessage): Promise<{
-        messageId: string;
-        success: boolean;
-    }>;
-    sendTemplate(templateName: string, to: string | string[], data: TemplateData): Promise<{
-        messageId: string;
-        success: boolean;
-    }>;
-}
-declare class MockEmailAdapter implements EmailAdapter {
-    send(message: EmailMessage): Promise<{
-        messageId: string;
-        success: boolean;
-    }>;
-    sendTemplate(name: string, to: string | string[], data: TemplateData): Promise<{
-        messageId: string;
-        success: boolean;
-    }>;
-}
 declare module "hono" {
     interface ContextVariableMap {
         email: EmailAdapter;
@@ -902,7 +749,6 @@ declare class EmailFeature implements Feature {
     private adapter?;
     constructor(config: EmailConfig);
     initialize(kernel: Kernel): Promise<void>;
-    private createAdapter;
     getAdapter(): EmailAdapter;
 }
 
@@ -963,4 +809,4 @@ declare class ConflictError extends HttpError {
     });
 }
 
-export { type ApiKeyConfig, ApiKeyFeature, type ApiKeyMetadata, ApiKeyStore, type ApiKeyValidationResult, type ApiResponse, type AuthConfig, AuthError, AuthFeature, BaseStorageAdapter, type CacheAdapter, type CacheConfig, CacheFeature, ConflictError, type CorsConfig, CorsFeature, type CsrfConfig, CsrfFeature, type DbConfig, DbFeature, type EmailAdapter, type EmailConfig, EmailFeature, type EmailMessage, type ErrorHandlerConfig, ErrorHandlerFeature, type ErrorResponse, type Feature, ForbiddenError, type FormattedValidationErrors, type HealthCheckConfig, HealthCheckFeature, HttpError, JsonSchemaValidationFeature, type JsonValidationOptions, type JsonValidationSchema, Kernel, type KernelConfig, LocalStorageAdapter, type LoggerConfig, LoggerFeature, MockEmailAdapter, NotFoundError, type OpenAPIConfig, OpenAPIFeature, type OtelTracingConfig, OtelTracingFeature, type PermissionsConfig, PermissionsFeature, type RateLimitConfig, RateLimitFeature, type RequestIdConfig, RequestIdFeature, type Role, type RouteOptions, type SecurityHeadersConfig, type SessionConfig, SessionFeature, type Sink, type StorageConfig, StorageFeature, type StorageFile, type SuccessResponse, type TemplateData, type UploadConfig, UploadFeature, ValidationError, ValidationFeature, type ValidationOptions, type ValidationSchema, type WebContext, WebDriver, WebPlugin, type WebPluginConfig, type WebServerOptions, createHttpError, createJsonSchemaValidationMiddleware, createRouter, createValidationMiddleware, errorResponse, formatAjvErrors, requireApiKey, requireAuth, requireCsrf, requirePermission, requireRole, requireScope, successResponse };
+export { type ApiKeyConfig, ApiKeyFeature, type ApiKeyMetadata, ApiKeyStore, type ApiKeyValidationResult, type ApiResponse, type AuthConfig, AuthError, AuthFeature, type CacheAdapter, type CacheConfig, CacheFeature, ConflictError, type CorsConfig, CorsFeature, type CsrfConfig, CsrfFeature, type DbConfig, DbFeature, EmailFeature, type ErrorHandlerConfig, ErrorHandlerFeature, type ErrorResponse, type Feature, ForbiddenError, type FormattedValidationErrors, type HealthCheckConfig, HealthCheckFeature, HttpError, JsonSchemaValidationFeature, type JsonValidationOptions, type JsonValidationSchema, Kernel, type KernelConfig, type LoggerConfig, LoggerFeature, NotFoundError, type OpenAPIConfig, OpenAPIFeature, type OtelTracingConfig, OtelTracingFeature, type PermissionsConfig, PermissionsFeature, type RateLimitConfig, RateLimitFeature, type RequestIdConfig, RequestIdFeature, type Role, type RouteOptions, type SecurityHeadersConfig, type SessionConfig, SessionFeature, type Sink, StorageFeature, type SuccessResponse, type UploadConfig, UploadFeature, ValidationError, ValidationFeature, type ValidationOptions, type ValidationSchema, type WebContext, WebDriver, type WebKitDrizzleDb, WebPlugin, type WebPluginConfig, type WebServerOptions, createHttpError, createJsonSchemaValidationMiddleware, createRouter, createValidationMiddleware, errorResponse, formatAjvErrors, requireApiKey, requireAuth, requireCsrf, requirePermission, requireRole, requireScope, successResponse };