@iskra-bun/web-kit 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@iskra-bun/web-kit",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "Servidor HTTP de Iskra basado en Hono, con Kernel y features (auth, cors, db, health, etc.).",
     "keywords": [
         "iskra",
@@ -49,7 +49,10 @@
     "dependencies": {
         "@hono/zod-openapi": "^1.2.0",
         "@hono/zod-validator": "^0.4.2",
-        "@iskra-bun/core": "0.1.0",
+        "@iskra-bun/core": "0.1.1",
+        "@iskra-bun/auth-kit": "0.1.0",
+        "@iskra-bun/mailer-kit": "0.1.0",
+        "@iskra-bun/storage-kit": "0.1.0",
         "better-auth": "^1.4.18",
         "drizzle-orm": "^0.45.1",
         "hono": "^4.6.14",
@@ -60,11 +63,7 @@
         "ajv-errors": "^3.0.0",
         "ajv-formats": "^3.0.1",
         "zod": "^3.24.1",
-        "@aws-sdk/client-s3": "^3.600.0",
-        "@aws-sdk/s3-request-presigner": "^3.600.0",
-        "@hono/otel": "^1.0.0",
-        "nodemailer": "^6.9.1",
-        "@sendgrid/mail": "^8.1.0"
+        "@hono/otel": "^1.0.0"
     },
     "devDependencies": {
         "@types/bun": "^1.3.5",

package/src/features/api-key.ts

@@ -2,6 +2,15 @@ import type { Feature, ApiKeyConfig, ApiKeyMetadata, ApiKeyValidationResult } fr
 import type { Kernel } from "../kernel";
 import type { Context, Next } from "hono";
 import { HTTPException } from "hono/http-exception";
+import { createHash } from "crypto";
+
+// Resolved config: scalar/array fields are always populated by the constructor
+// defaults, while the genuinely optional callbacks stay optional. This replaces
+// the previous `as unknown as Required<ApiKeyConfig>` cast, which masked shape
+// drift by pretending the callbacks were always present.
+type ResolvedApiKeyConfig =
+    Required<Omit<ApiKeyConfig, "vaultService" | "customExtractor" | "onError" | "onValidated">>
+    & Pick<ApiKeyConfig, "vaultService" | "customExtractor" | "onError" | "onValidated">;
 
 // --- ApiKeyStore ---
 
@@ -9,7 +18,7 @@ export class ApiKeyStore {
     private staticKeysMap: Map<string, ApiKeyMetadata> = new Map();
     private cache?: any;
 
-    constructor(private config: Required<ApiKeyConfig>, private kernel: Kernel) {
+    constructor(private config: ResolvedApiKeyConfig, private kernel: Kernel) {
         this.initializeStaticKeys();
     }
 
@@ -46,8 +55,11 @@ export class ApiKeyStore {
         console.log(`✅ Loaded ${this.staticKeysMap.size} static API keys`);
     }
 
-    private generateId(key: string): string {
-        return key.substring(0, 8);
+    private generateId(_key: string): string {
+        // Derive the id independently of the secret key material so it can never
+        // leak a usable prefix of the key. Lookup is keyed by the plaintext key
+        // (staticKeysMap / cache), never by id, so a random id is sufficient.
+        return crypto.randomUUID();
     }
 
     private compareKeys(a: string, b: string): boolean {
@@ -64,11 +76,18 @@ export class ApiKeyStore {
         return new Date() > expiresAt;
     }
 
+    private cacheKeyFor(key: string): string {
+        // Hash the key before using it as a cache key so the plaintext secret is
+        // never persisted (e.g. in Redis) where it could leak via cache dumps.
+        const hash = createHash("sha256").update(key).digest("hex");
+        return `apikey:${hash}`;
+    }
+
     async validate(key: string): Promise<ApiKeyValidationResult> {
         if (!key) return { isValid: false, error: "API key is required" };
 
         const cache = this.getCache();
-        const cacheKey = `apikey:${key}`;
+        const cacheKey = this.cacheKeyFor(key);
 
         if (cache) {
             try {
@@ -88,18 +107,20 @@ export class ApiKeyStore {
                 if (this.isExpired(metadata.expiresAt)) {
                     return { isValid: false, error: "API key has expired" };
                 }
-                metadata.lastUsedAt = new Date();
+                // Build a derived object instead of mutating the metadata held in
+                // staticKeysMap (immutability — the stored object must stay intact).
+                const usedMetadata: ApiKeyMetadata = { ...metadata, lastUsedAt: new Date() };
 
                 if (cache) {
                     const ttl = this.config.cacheTtl ? Math.floor(this.config.cacheTtl / 1000) : 300;
                     try {
-                        await cache.set(cacheKey, JSON.stringify(metadata), ttl);
+                        await cache.set(cacheKey, JSON.stringify(usedMetadata), ttl);
                     } catch {
                         // ignore cache write failures — validation already succeeded
                     }
                 }
 
-                return { isValid: true, key: metadata };
+                return { isValid: true, key: usedMetadata };
             }
         }
 
@@ -140,24 +161,27 @@ declare module "hono" {
 export class ApiKeyFeature implements Feature {
     name = "apiKey";
     private store?: ApiKeyStore;
-    private config: Required<ApiKeyConfig>;
+    private config: ResolvedApiKeyConfig;
 
     constructor(config: ApiKeyConfig = {}) {
-        this.config = {
+        // Explicit, fully-typed defaults object — every resolved field is assigned
+        // a concrete value so shape drift surfaces at compile time instead of
+        // being masked by an `as unknown as` cast.
+        const defaults: ResolvedApiKeyConfig = {
             staticKeys: config.staticKeys || [],
             headerName: config.headerName || "X-API-Key",
             queryParamName: config.queryParamName || "api_key",
             extractStrategies: config.extractStrategies || ["header", "bearer"],
-            // Defaults for other optional properties
-            vaultService: undefined,
-            customExtractor: undefined,
+            vaultService: config.vaultService,
+            customExtractor: config.customExtractor,
             enableCache: config.enableCache ?? true,
             cacheTtl: config.cacheTtl ?? 300000,
             requireScopes: config.requireScopes ?? false,
             skipPaths: config.skipPaths || [],
             onError: config.onError,
-            onValidated: config.onValidated
-        } as unknown as Required<ApiKeyConfig>;
+            onValidated: config.onValidated,
+        };
+        this.config = defaults;
     }
 
     async initialize(kernel: Kernel): Promise<void> {
@@ -183,6 +207,12 @@ export class ApiKeyFeature implements Feature {
                 throw new HTTPException(401, { message: result.error || "Invalid API key" });
             }
 
+            // When requireScopes is enabled, a validated key that carries no scope
+            // is treated as insufficiently privileged and rejected.
+            if (this.config.requireScopes && !(result.key?.scopes && result.key.scopes.length > 0)) {
+                throw new HTTPException(403, { message: "API key has no scopes" });
+            }
+
             c.set("apiKey", result.key);
             c.set("apiKeyScopes", result.key?.scopes || []);
 

package/src/features/auth/index.ts

@@ -1,11 +1,11 @@
 import type { AuthConfig, Feature, Kernel } from "../../types";
 import type { Context, Hono, Next } from "hono";
 import { HTTPException } from "hono/http-exception";
-import { type Auth, createBetterAuth } from "./better-auth-config";
+import { type Auth, createBetterAuth } from "@iskra-bun/auth-kit";
 import { z } from "@hono/zod-openapi";
 import type { DbFeature } from "../db";
 import type { OpenAPIFeature } from "../openapi";
-import type { User } from "./types";
+import type { User } from "@iskra-bun/auth-kit";
 
 declare module "hono" {
     interface ContextVariableMap {
@@ -52,8 +52,14 @@ export class AuthFeature implements Feature {
     private config: Required<Pick<AuthConfig, "secret" | "basePath">> & AuthConfig;
     private kernel?: Kernel;
     private authMode: "oidc" | "email";
+    private createAuth: typeof createBetterAuth;
 
-    constructor(config: AuthConfig) {
+    // The second parameter is an internal seam: it defaults to the real
+    // createBetterAuth and lets tests inject a fake without globally mocking the
+    // @iskra-bun/auth-kit module (bun's mock.module is process-global and cannot
+    // be restored, which would otherwise leak into auth-kit's own test suite).
+    constructor(config: AuthConfig, createAuth: typeof createBetterAuth = createBetterAuth) {
+        this.createAuth = createAuth;
         this.config = {
             ...config,
             basePath: config.basePath || "/api/sso",
@@ -81,7 +87,14 @@ export class AuthFeature implements Feature {
             throw new Error("DbFeature must expose 'adapter' type (postgres, mysql, sqlite)");
         }
 
-        this.auth = createBetterAuth({
+        // CSRF kill-switch is honored only outside production. Even if a config
+        // ships with disableCSRFCheck enabled, it is neutralized in prod so CSRF
+        // protection cannot be silently turned off in a deployed environment.
+        const disableCSRFCheck = process.env.NODE_ENV !== "production"
+            ? this.config.disableCSRFCheck === true
+            : false;
+
+        this.auth = this.createAuth({
             db,
             adapterType,
             secret: this.config.secret,
@@ -89,12 +102,17 @@ export class AuthFeature implements Feature {
             basePath: this.config.basePath,
             trustedOrigins: this.config.trustedOrigins,
             enableEmailPassword: true,
-            disableCSRFCheck: this.config.disableCSRFCheck,
+            disableCSRFCheck,
             socialProviders: this.config.socialProviders,
             oidcConfig: this.config.oidcConfig,
         });
 
         const app = kernel.getApp();
+
+        // Per-IP rate limiting on the auth routes by default, throttling
+        // credential-stuffing / brute-force against sign-in and sign-up.
+        app.use(`${this.config.basePath}/*`, this.authRateLimitMiddleware());
+
         app.use("*", async (c: Context, next: Next) => {
             try {
                 const session = await this.auth!.api.getSession({
@@ -106,7 +124,11 @@ export class AuthFeature implements Feature {
                     c.set("authUser", session.user);
                 }
             } catch (error) {
-                // Ignore session errors (just not logged in)
+                // A failed getSession means "not authenticated" — expected for
+                // anonymous requests. Surface unexpected detail at debug only;
+                // never block the request on a session read.
+                const logger = c.get("logger");
+                if (logger?.debug) logger.debug("Auth session read failed", { error });
             }
             await next();
         });
@@ -114,6 +136,31 @@ export class AuthFeature implements Feature {
         console.log("✅ Auth feature initialized (better-auth)");
     }
 
+    // ─── Auth-route rate limiting ────────────────────────────────────────────
+    private authRateLimitHits = new Map<string, { count: number; expiresAt: number }>();
+    private readonly authRateLimitWindowMs = 15 * 60 * 1000;
+    private readonly authRateLimitMax = 20;
+
+    private authRateLimitMiddleware() {
+        return async (c: Context, next: Next) => {
+            const ip = c.req.header("x-forwarded-for")
+                || c.req.header("x-real-ip")
+                || "unknown";
+            const now = Date.now();
+            const entry = this.authRateLimitHits.get(ip);
+
+            const next_entry = !entry || now > entry.expiresAt
+                ? { count: 1, expiresAt: now + this.authRateLimitWindowMs }
+                : { count: entry.count + 1, expiresAt: entry.expiresAt };
+            this.authRateLimitHits.set(ip, next_entry);
+
+            if (next_entry.count > this.authRateLimitMax) {
+                throw new HTTPException(429, { message: "Too many authentication attempts" });
+            }
+            await next();
+        };
+    }
+
     routes(app: Hono): void {
         if (!this.auth) {
             throw new Error("Auth not initialized");

package/src/features/csrf.ts

@@ -3,6 +3,7 @@ import type { Kernel } from "../kernel";
 import type { Context, Next } from "hono";
 import { HTTPException } from "hono/http-exception";
 import { getCookie, setCookie } from "hono/cookie";
+import { createHmac, timingSafeEqual, randomUUID } from "crypto";
 
 declare module "hono" {
     interface ContextVariableMap {
@@ -10,6 +11,41 @@ declare module "hono" {
     }
 }
 
+// ─── Signed Double-Submit Token ──────────────────────────────────────────────
+//
+// A CSRF token is `<random>.<hmac>` where the HMAC signs the random nonce under
+// the configured secret (OWASP signed double-submit cookie). Forging a token
+// requires the secret, and an attacker can neither read nor set the victim's
+// cookie cross-origin. The nonce is intentionally NOT bound to the session id:
+// anonymous flows mint a throwaway session id per request, so binding would
+// reject the first POST of every logged-out flow.
+
+function constantTimeEqual(a: string, b: string): boolean {
+    const aBuf = Buffer.from(a);
+    const bBuf = Buffer.from(b);
+    // timingSafeEqual throws on length mismatch; comparing lengths first keeps
+    // the call safe. The length check is not constant-time, but token length is
+    // not secret — the signature comparison below is what gates forgery.
+    if (aBuf.length !== bBuf.length) return false;
+    return timingSafeEqual(aBuf, bBuf);
+}
+
+function signCsrfToken(random: string, secret: string): string {
+    const signature = createHmac("sha256", secret)
+        .update(random)
+        .digest("base64url");
+    return `${random}.${signature}`;
+}
+
+function verifyCsrfToken(token: string, secret: string): boolean {
+    const lastDot = token.lastIndexOf(".");
+    if (lastDot === -1) return false;
+
+    const random = token.substring(0, lastDot);
+    const expected = signCsrfToken(random, secret);
+    return constantTimeEqual(token, expected);
+}
+
 export class CsrfFeature implements Feature {
     name = "csrf";
     private config: Required<CsrfConfig>;
@@ -44,7 +80,7 @@ export class CsrfFeature implements Feature {
         let token = getCookie(c, this.config.cookieName);
 
         if (!token) {
-            token = crypto.randomUUID().replace(/-/g, '');
+            token = signCsrfToken(randomUUID().replace(/-/g, ""), this.config.secret);
             setCookie(c, this.config.cookieName, token, {
                 httpOnly: this.config.cookieOptions.httpOnly,
                 secure: this.config.cookieOptions.secure,
@@ -70,17 +106,27 @@ export class CsrfFeature implements Feature {
     }
 
     private async validateToken(c: Context, expectedToken: string): Promise<boolean> {
+        // The cookie token itself must carry a valid signature under the secret.
+        // An unsigned or foreign token is rejected before any comparison, so a
+        // token minted elsewhere cannot pass double-submit.
+        if (!verifyCsrfToken(expectedToken, this.config.secret)) return false;
+
         const headerToken = c.req.header(this.config.headerName);
-        if (headerToken === expectedToken) return true;
+        if (headerToken && constantTimeEqual(headerToken, expectedToken)) return true;
 
         try {
             const contentType = c.req.header("content-type");
             if (contentType?.includes("application/x-www-form-urlencoded")) {
                 const body = await c.req.parseBody();
                 const bodyToken = body._csrf || body[this.config.cookieName];
-                if (String(bodyToken) === expectedToken) return true;
+                if (bodyToken && constantTimeEqual(String(bodyToken), expectedToken)) return true;
             }
-        } catch { /* ignored */ }
+        } catch (error) {
+            // A malformed/unparseable body just means no valid body token is
+            // present; fall through to rejection. Surface detail at debug only.
+            const logger = c.get("logger");
+            if (logger?.debug) logger.debug("CSRF body token parse failed", { error });
+        }
 
         return false;
     }

package/src/features/db.ts

@@ -1,23 +1,35 @@
 import type { Feature, DbConfig } from "../types";
 import type { Kernel } from "../kernel";
 import type { Context, Next } from "hono";
-import { drizzle } from 'drizzle-orm/postgres-js';
-import { drizzle as drizzleMysql } from 'drizzle-orm/mysql2';
-import { drizzle as drizzleBunSqlite } from 'drizzle-orm/bun-sqlite';
+import { drizzle, type PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import { drizzle as drizzleMysql, type MySql2Database } from 'drizzle-orm/mysql2';
+import { drizzle as drizzleBunSqlite, type BunSQLiteDatabase } from 'drizzle-orm/bun-sqlite';
 import postgres from 'postgres';
 import mysql from 'mysql2/promise';
 import { Database } from 'bun:sqlite';
 
+/**
+ * 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.
+ */
+export 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;
     }
 }
 
-export class DbFeature implements Feature {
+export class DbFeature<TSchema extends Record<string, unknown> = Record<string, never>> implements Feature {
     name = "db";
     private client: any;
-    public db: any;
+    public db!: WebKitDrizzleDb<TSchema>;
     public readonly adapter: string;
 
     constructor(private config: DbConfig) {
@@ -40,7 +52,7 @@ export class DbFeature implements Feature {
                         password: config.connection.password!
                     };
                     this.client = postgres(pgConfig as any);
-                    this.db = drizzle(this.client);
+                    this.db = drizzle<TSchema>(this.client);
                     break;
                 }
                 case 'mysql': {
@@ -53,13 +65,13 @@ export class DbFeature implements Feature {
                         password: config.connection.password!
                     };
                     this.client = await mysql.createConnection(mysqlConfig as any);
-                    this.db = drizzleMysql(this.client);
+                    this.db = drizzleMysql<TSchema>(this.client);
                     break;
                 }
                 case 'sqlite': {
                     const url = config.connection?.database || ':memory:';
                     this.client = new Database(url);
-                    this.db = drizzleBunSqlite(this.client);
+                    this.db = drizzleBunSqlite<TSchema>(this.client);
                     break;
                 }
                 default:
@@ -67,13 +79,16 @@ export class DbFeature implements Feature {
             }
             console.log('✅ DB connected successfully.');
         } catch (error) {
-            console.error('❌ Failed to connect to DB', error);
+            // Log only the message — the full error/config object can embed the
+            // connection string (host, user, password) and must not be logged.
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`❌ Failed to connect to DB: ${message}`);
             throw error;
         }
 
         const app = kernel.getApp();
         app.use("*", async (c: Context, next: Next) => {
-            c.set("db", this.db);
+            c.set("db", this.db as WebKitDrizzleDb);
             await next();
         });
     }

package/src/features/email/index.ts

@@ -1,61 +1,66 @@
 import type { Feature } from "../../types";
 import type { Kernel } from "../../kernel";
 import type { Context, Next } from "hono";
+import { createEmailAdapter } from "@iskra-bun/mailer-kit";
 
-export 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;
-}
+export type { EmailConfig, EmailMessage, TemplateData, EmailAdapter } from "@iskra-bun/mailer-kit";
+export { MockEmailAdapter } from "@iskra-bun/mailer-kit";
+
+import type { EmailConfig, EmailAdapter, EmailMessage, TemplateData } from "@iskra-bun/mailer-kit";
 
-export 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>;
+declare module "hono" {
+    interface ContextVariableMap {
+        email: EmailAdapter;
+    }
 }
 
-export interface TemplateData {
-    [key: string]: unknown;
+// ─── Header-injection guards ─────────────────────────────────────────────────
+//
+// An attacker who controls a recipient address or a header value can inject CR
+// or LF to smuggle extra SMTP headers (e.g. a hidden Bcc). Reject any address or
+// header that carries a CR/LF before the message reaches the underlying adapter.
+
+const CRLF = /[\r\n]/;
+
+function assertNoCrlf(value: string, label: string): void {
+    if (CRLF.test(value)) {
+        throw new Error(`Invalid ${label}: control characters (CR/LF) are not allowed`);
+    }
 }
 
-export interface EmailAdapter {
-    send(message: EmailMessage): Promise<{ messageId: string; success: boolean }>;
-    sendTemplate(templateName: string, to: string | string[], data: TemplateData): Promise<{ messageId: string; success: boolean }>;
+function assertRecipients(to: string | string[] | undefined, label: string): void {
+    if (to === undefined) return;
+    const recipients = Array.isArray(to) ? to : [to];
+    for (const recipient of recipients) assertNoCrlf(recipient, label);
 }
 
-class MockEmailAdapter implements EmailAdapter {
-    async send(message: EmailMessage) {
-        console.log("📧 [MOCK] Sent to", message.to, "Subject:", message.subject);
-        return { messageId: `mock-${Date.now()}`, success: true };
-    }
-    async sendTemplate(name: string, to: string | string[], data: TemplateData) {
-        return this.send({ to, subject: `Template: ${name}`, html: `Template ${name} with data: ${JSON.stringify(data)}` });
+function validateMessage(message: EmailMessage): void {
+    assertRecipients(message.to, "recipient");
+    assertRecipients(message.cc, "cc recipient");
+    assertRecipients(message.bcc, "bcc recipient");
+    if (message.replyTo !== undefined) assertNoCrlf(message.replyTo, "replyTo");
+    assertNoCrlf(message.subject, "subject");
+    if (message.headers) {
+        for (const [name, value] of Object.entries(message.headers)) {
+            assertNoCrlf(name, "header name");
+            assertNoCrlf(value, "header value");
+        }
     }
 }
 
-declare module "hono" {
-    interface ContextVariableMap {
-        email: EmailAdapter;
-    }
+// Wrap an adapter so every send is validated centrally before delegation. The
+// wrapper is a new object — it never mutates the underlying adapter.
+function withValidation(adapter: EmailAdapter): EmailAdapter {
+    return {
+        send: (message: EmailMessage) => {
+            validateMessage(message);
+            return adapter.send(message);
+        },
+        sendTemplate: (templateName: string, to: string | string[], data: TemplateData) => {
+            assertRecipients(to, "recipient");
+            return adapter.sendTemplate(templateName, to, data);
+        },
+    };
 }
 
 export class EmailFeature implements Feature {
@@ -65,33 +70,12 @@ export class EmailFeature implements Feature {
     constructor(private config: EmailConfig) { }
 
     async initialize(kernel: Kernel): Promise<void> {
-        this.adapter = await this.createAdapter(this.config);
+        this.adapter = withValidation(await createEmailAdapter(this.config));
         const app = kernel.getApp();
         app.use("*", async (c: Context, next: Next) => {
             if (this.adapter) c.set("email", this.adapter);
             await next();
         });
-        console.log(`✅ EmailFeature initialized (${this.config.provider})`);
-    }
-
-    private async createAdapter(config: EmailConfig): Promise<EmailAdapter> {
-        switch (config.provider) {
-            case "mock": return new MockEmailAdapter();
-            case "smtp": {
-                // Lazy load to avoid import issues if not installed/configured in all envs (though we added deps)
-                const { SmtpEmailAdapter } = await import("./providers/smtp");
-                return new SmtpEmailAdapter(config);
-            }
-            case "sendgrid": {
-                const { SendGridEmailAdapter } = await import("./providers/sendgrid");
-                return new SendGridEmailAdapter(config);
-            }
-            case "mailgun": {
-                const { MailgunEmailAdapter } = await import("./providers/mailgun");
-                return new MailgunEmailAdapter(config);
-            }
-            default: throw new Error(`Provider ${config.provider} not implemented`);
-        }
     }
 
     getAdapter(): EmailAdapter {
@@ -99,5 +83,3 @@ export class EmailFeature implements Feature {
         return this.adapter;
     }
 }
-
-export { MockEmailAdapter };