@iskra-bun/web-kit 0.1.0

package/src/features/json-schema-validation.ts

@@ -0,0 +1,186 @@
+import type { Feature } from "../types";
+import type { Kernel } from "../kernel";
+import type { Context, Next, Hono, Handler } from "hono";
+import Ajv from "ajv";
+import addErrors from "ajv-errors";
+import addFormats from "ajv-formats";
+import type { ErrorObject } from "ajv";
+import { ErrorCodes, errorResponse } from "../responses";
+
+// ─── Module Augmentation ────────────────────────────────────────────────────
+
+declare module "hono" {
+    interface Hono {
+        getJsonValidated(path: string, schema: JsonValidationSchema, handler: Handler, options?: JsonValidationOptions): Hono;
+        postJsonValidated(path: string, schema: JsonValidationSchema, handler: Handler, options?: JsonValidationOptions): Hono;
+        putJsonValidated(path: string, schema: JsonValidationSchema, handler: Handler, options?: JsonValidationOptions): Hono;
+        deleteJsonValidated(path: string, schema: JsonValidationSchema, handler: Handler, options?: JsonValidationOptions): Hono;
+    }
+}
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface JsonValidationSchema {
+    params?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: Record<string, unknown>;
+}
+
+export interface JsonValidationOptions {
+    logErrors?: boolean;
+    status?: number;
+    allErrors?: boolean;
+    coerceTypes?: boolean;
+}
+
+export interface FormattedValidationErrors {
+    fields: Record<string, string[]>;
+    errors: string[];
+}
+
+// ─── Ajv Instance Factory ───────────────────────────────────────────────────
+
+function createAjvInstance(options: JsonValidationOptions = {}): Ajv {
+    const ajv = new Ajv({
+        allErrors: options.allErrors ?? true,
+        coerceTypes: options.coerceTypes ?? true,
+        verbose: true,
+        $data: true,
+    });
+    addFormats(ajv);
+    addErrors(ajv);
+    return ajv;
+}
+
+// ─── Error Formatter ────────────────────────────────────────────────────────
+
+function formatAjvErrors(errors: ErrorObject[] | null | undefined): FormattedValidationErrors {
+    const result: FormattedValidationErrors = { fields: {}, errors: [] };
+    if (!errors) return result;
+
+    for (const err of errors) {
+        let fieldPath: string;
+
+        if (err.instancePath) {
+            fieldPath = err.instancePath.replace(/^\//, "").replace(/\//g, ".");
+        } else if (err.params && "missingProperty" in err.params) {
+            fieldPath = err.params.missingProperty as string;
+        } else {
+            fieldPath = "_root";
+        }
+
+        const message = err.message || "Invalid value";
+
+        if (!result.fields[fieldPath]) {
+            result.fields[fieldPath] = [];
+        }
+
+        if (!result.fields[fieldPath].includes(message)) {
+            result.fields[fieldPath].push(message);
+        }
+
+        const formatted = fieldPath === "_root" ? message : `${fieldPath}: ${message}`;
+        if (!result.errors.includes(formatted)) {
+            result.errors.push(formatted);
+        }
+    }
+
+    return result;
+}
+
+// ─── Validation Middleware ───────────────────────────────────────────────────
+
+export function createJsonSchemaValidationMiddleware(
+    schema: JsonValidationSchema,
+    options: JsonValidationOptions = {},
+) {
+    const { logErrors = true, status = 400 } = options;
+    const ajv = createAjvInstance(options);
+
+    const validators = {
+        params: schema.params ? ajv.compile(schema.params) : null,
+        query: schema.query ? ajv.compile(schema.query) : null,
+        body: schema.body ? ajv.compile(schema.body) : null,
+    };
+
+    return async (c: Context, next: Next) => {
+        try {
+            const validated: Record<string, any> = {};
+
+            if (validators.params) {
+                const data = { ...c.req.param() };
+                const valid = validators.params(data);
+                if (!valid) {
+                    const details = formatAjvErrors(validators.params.errors);
+                    return c.json(errorResponse("Invalid route params", ErrorCodes.VALIDATION_ERROR, details), status as any);
+                }
+                validated.params = data;
+            }
+
+            if (validators.query) {
+                const data = { ...c.req.query() };
+                const valid = validators.query(data);
+                if (!valid) {
+                    const details = formatAjvErrors(validators.query.errors);
+                    return c.json(errorResponse("Invalid query params", ErrorCodes.VALIDATION_ERROR, details), status as any);
+                }
+                validated.query = data;
+            }
+
+            if (validators.body) {
+                let data: unknown = {};
+                const contentType = c.req.header("content-type") || "";
+                if (contentType.includes("application/json")) {
+                    data = await c.req.json().catch(() => ({}));
+                } else if (contentType.includes("application/x-www-form-urlencoded") || contentType.includes("multipart/form-data")) {
+                    data = await c.req.parseBody();
+                }
+
+                const valid = validators.body(data);
+                if (!valid) {
+                    const details = formatAjvErrors(validators.body.errors);
+                    return c.json(errorResponse("Invalid body", ErrorCodes.VALIDATION_ERROR, details), status as any);
+                }
+                validated.body = data;
+            }
+
+            (c as any).valid = () => validated;
+            await next();
+        } catch (err) {
+            if (logErrors) console.error("JSON Schema validation error:", err);
+            return c.json(errorResponse("Validation middleware failed", ErrorCodes.INTERNAL_ERROR), 500);
+        }
+    };
+}
+
+// ─── Hono Extension ─────────────────────────────────────────────────────────
+
+function extendHonoWithJsonSchemaValidation(app: Hono) {
+    const methods = ["get", "post", "put", "delete"] as const;
+    for (const method of methods) {
+        (app as any)[`${method}JsonValidated`] = function (
+            path: string,
+            schema: JsonValidationSchema,
+            handler: Handler,
+            options?: JsonValidationOptions,
+        ) {
+            const middleware = createJsonSchemaValidationMiddleware(schema, options);
+            (this as any)[method](path, middleware, handler);
+            return this;
+        };
+    }
+}
+
+// ─── Feature Class ──────────────────────────────────────────────────────────
+
+export class JsonSchemaValidationFeature implements Feature {
+    name = "json-schema-validation";
+
+    async initialize(kernel: Kernel): Promise<void> {
+        const app = kernel.getApp();
+        extendHonoWithJsonSchemaValidation(app);
+        console.log("✅ JSON Schema validation feature initialized");
+    }
+}
+
+export { formatAjvErrors };

package/src/features/logger.ts

@@ -0,0 +1,70 @@
+import type { Feature, LoggerConfig } from "../types";
+import type { Kernel } from "../kernel";
+import type { Context, Next } from "hono";
+
+declare module "hono" {
+    interface ContextVariableMap {
+        logger: any;
+    }
+}
+
+// Simple Logger implementation to avoid heavy dependency unless necessary
+class SimpleLogger {
+    constructor(private config: LoggerConfig) { }
+
+    info(message: string, ...args: any[]) {
+        if (this.shouldLog("info")) console.log(`[INFO] ${message}`, ...args);
+    }
+    error(message: string, ...args: any[]) {
+        if (this.shouldLog("error")) console.error(`[ERROR] ${message}`, ...args);
+    }
+    warn(message: string, ...args: any[]) {
+        if (this.shouldLog("warn")) console.warn(`[WARN] ${message}`, ...args);
+    }
+    debug(message: string, ...args: any[]) {
+        if (this.shouldLog("debug")) console.debug(`[DEBUG] ${message}`, ...args);
+    }
+
+    private shouldLog(level: string) {
+        // Basic level check (can be improved)
+        return true;
+    }
+}
+
+export class LoggerFeature implements Feature {
+    name = "logger";
+
+    private config: LoggerConfig;
+    private logger: SimpleLogger;
+
+    constructor(config: LoggerConfig = {}) {
+        this.config = config;
+        this.logger = new SimpleLogger(config);
+    }
+
+    async initialize(kernel: Kernel): Promise<void> {
+        const app = kernel.getApp();
+
+        app.use("*", async (c: Context, next: Next) => {
+            c.set("logger", this.logger);
+            await next();
+        });
+
+        if (this.config.logRequests) {
+            app.use("*", async (c: Context, next: Next) => {
+                const start = Date.now();
+                const requestId = c.get("requestId");
+                this.logger.info(`Incoming request ${c.req.method} ${c.req.path}`, { requestId });
+
+                await next();
+
+                const duration = Date.now() - start;
+                if (this.config.logResponses) {
+                    this.logger.info(`Request completed ${c.res.status} ${duration}ms`, { requestId });
+                }
+            });
+        }
+
+        console.log("✅ Logger feature initialized");
+    }
+}

package/src/features/openapi.ts

@@ -0,0 +1,107 @@
+import type { Feature, OpenAPIConfig } from "../types";
+import type { Kernel } from "../kernel";
+import type { Context, Handler, Hono } from "hono";
+import { OpenAPIHono, createRoute, z } from "@hono/zod-openapi";
+import { ErrorCodes, errorResponse } from "../responses";
+
+export class OpenAPIFeature implements Feature {
+    name = "openapi";
+    private app?: OpenAPIHono;
+    private config: OpenAPIConfig;
+    private kernel?: Kernel;
+    private autoGeneratedRoutes: Array<{ path: string; method: string; tags: string[]; summary: string }> = [];
+    private queuedRoutes: Array<{ route: any; handler: Handler }> = [];
+
+    constructor(config: OpenAPIConfig) {
+        this.config = config;
+    }
+
+    async initialize(kernel: Kernel): Promise<void> {
+        this.kernel = kernel;
+        this.app = new OpenAPIHono({
+            defaultHook: (result: any, c: Context) => {
+                if (!result.success) {
+                    return c.json(errorResponse("Validation Error", ErrorCodes.VALIDATION_ERROR, result.error.flatten()), 400);
+                }
+            }
+        });
+
+        this.processQueuedRoutes();
+        console.log("✅ OpenAPIFeature initialized");
+    }
+
+    addRoute(route: any, handler: Handler) {
+        if (!this.app) {
+            this.queuedRoutes.push({ route, handler });
+            return;
+        }
+        this.app.openapi(createRoute(route), handler);
+        this.autoGeneratedRoutes.push({
+            path: route.path,
+            method: route.method.toUpperCase(),
+            tags: route.tags || [],
+            summary: route.summary || ""
+        });
+    }
+
+    private processQueuedRoutes() {
+        if (!this.app) return;
+        for (const { route, handler } of this.queuedRoutes) {
+            this.addRoute(route, handler);
+        }
+        this.queuedRoutes = [];
+    }
+
+    routes(app: Hono) {
+        if (this.app) {
+            app.route("/", this.app);
+        }
+
+        app.get("/openapi.json", (c: Context) => {
+            if (!this.app) return c.json({ error: "OpenAPI not initialized" }, 500);
+
+            const spec = this.app.getOpenAPIDocument({
+                openapi: "3.1.0",
+                info: {
+                    title: this.config.title,
+                    version: this.config.version,
+                    description: this.config.description || "API Documentation",
+                    contact: this.config.contact,
+                    license: this.config.license
+                },
+                servers: this.config.servers || [{ url: "http://localhost:8000", description: "Dev Server" }],
+                tags: this.config.tags || [],
+                externalDocs: this.config.externalDocs,
+                security: this.config.security
+            });
+
+            if (this.config.securitySchemes) {
+                if (!spec.components) spec.components = {};
+                spec.components.securitySchemes = this.config.securitySchemes;
+            }
+
+            return c.json(spec);
+        });
+
+        app.get("/docs", (c) => c.html(this.generateScalarHTML()));
+    }
+
+    private generateScalarHTML(): string {
+        return `
+<!DOCTYPE html>
+<html>
+<head>
+    <title>${this.config.title} - API Documentation</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style>body { margin: 0; padding: 0; }</style>
+</head>
+<body>
+    <script id="api-reference" data-url="/openapi.json" data-configuration='{"theme":"purple","layout":"modern","showSidebar":true}'></script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference@latest"></script>
+</body>
+</html>`.trim();
+    }
+}
+
+export { createRoute, OpenAPIHono, z };

package/src/features/permissions.ts

@@ -0,0 +1,128 @@
+import type { Feature, PermissionsConfig, Role } from "../types";
+import type { Kernel } from "../kernel";
+import type { Context, Next } from "hono";
+import { HTTPException } from "hono/http-exception";
+
+declare module "hono" {
+    interface ContextVariableMap {
+        userPermissions: string[];
+        checkPermission: (permission: string) => boolean;
+        hasRole: (role: string) => boolean;
+        hasAnyRole: (...roles: string[]) => boolean;
+        hasAllRoles: (...roles: string[]) => boolean;
+    }
+}
+
+const DEFAULT_ROLES: Record<string, Role> = {
+    admin: { name: "admin", permissions: ["*"], description: "Full access" },
+    user: { name: "user", permissions: ["read:own", "write:own"], description: "User access" },
+    guest: { name: "guest", permissions: ["read:public"], description: "Guest access" }
+};
+
+export class PermissionsFeature implements Feature {
+    name = "permissions";
+    dependencies = ["auth"];
+    private config: Required<PermissionsConfig>;
+    private roles: Map<string, Role> = new Map();
+
+    constructor(config: PermissionsConfig = {}) {
+        this.config = {
+            loadPermissions: config.loadPermissions || (async () => ["read:own"]),
+            loadRoles: config.loadRoles || (async () => ["user"]),
+            anonymousPermissions: config.anonymousPermissions || ["read:public"],
+            enableRBAC: config.enableRBAC ?? true,
+            cachePermissions: config.cachePermissions ?? true,
+            cacheTTL: config.cacheTTL || 3600
+        };
+        Object.values(DEFAULT_ROLES).forEach(r => this.roles.set(r.name, r));
+    }
+
+    async initialize(kernel: Kernel): Promise<void> {
+        const app = kernel.getApp();
+        app.use("*", async (c: Context, next: Next) => {
+            await this.permissionsMiddleware(c, next, kernel);
+        });
+        console.log("✅ Permissions feature initialized");
+    }
+
+    private async permissionsMiddleware(c: Context, next: Next, _kernel: Kernel) {
+        const user = c.get("user") || (c.get("session") as any)?.user;
+        const userId = user?.id;
+
+        let permissions: string[] = [];
+        let roles: string[] = [];
+
+        if (userId) {
+            if (this.config.cachePermissions) {
+                const cache = c.get("cache");
+                if (cache) {
+                    const cached = await cache.get(`permissions:${userId}`);
+                    if (cached) {
+                        permissions = cached.permissions || [];
+                        roles = cached.roles || [];
+                    }
+                }
+            }
+
+            if (permissions.length === 0) {
+                permissions = await this.config.loadPermissions(userId);
+                if (this.config.enableRBAC) {
+                    roles = await this.config.loadRoles(userId);
+                    for (const rName of roles) {
+                        const r = this.roles.get(rName);
+                        if (r) permissions.push(...r.permissions);
+                    }
+                }
+
+                if (this.config.cachePermissions) {
+                    const cache = c.get("cache");
+                    if (cache) {
+                        // Assume cache set exists and supports object storage (json stringify maybe required depending on cache impl)
+                        // Simple cache might require string
+                        await cache.set(`permissions:${userId}`, { permissions, roles }, this.config.cacheTTL);
+                    }
+                }
+            }
+        } else {
+            permissions = this.config.anonymousPermissions;
+        }
+
+        permissions = [...new Set(permissions)];
+
+        c.set("userPermissions", permissions);
+        c.set("checkPermission", (p: string) => this.checkPermission(permissions, p));
+        c.set("hasRole", (r: string) => roles.includes(r));
+        c.set("hasAnyRole", (...rs: string[]) => rs.some(r => roles.includes(r)));
+        c.set("hasAllRoles", (...rs: string[]) => rs.every(r => roles.includes(r)));
+
+        await next();
+    }
+
+    private checkPermission(userPerms: string[], required: string): boolean {
+        if (userPerms.includes("*")) return true;
+        if (userPerms.includes(required)) return true;
+
+        const parts = required.split(":");
+        for (let i = parts.length - 1; i > 0; i--) {
+            const pattern = parts.slice(0, i).join(":") + ":*";
+            if (userPerms.includes(pattern)) return true;
+        }
+        return false;
+    }
+}
+
+export function requirePermission(permission: string) {
+    return async (c: Context, next: Next) => {
+        const check = c.get("checkPermission");
+        if (!check || !check(permission)) throw new HTTPException(403, { message: `Missing permission: ${permission}` });
+        await next();
+    };
+}
+
+export function requireRole(role: string) {
+    return async (c: Context, next: Next) => {
+        const check = c.get("hasRole");
+        if (!check || !check(role)) throw new HTTPException(403, { message: `Missing role: ${role}` });
+        await next();
+    };
+}

package/src/features/rate-limit.ts

@@ -0,0 +1,173 @@
+import type { Feature, RateLimitConfig } from "../types";
+import type { Kernel } from "../kernel";
+import type { Context, Next } from "hono";
+import { HTTPException } from "hono/http-exception";
+
+interface RateLimitStore {
+    get(key: string): Promise<number | null>;
+    set(key: string, value: number, ttl: number): Promise<void>;
+    increment(key: string, ttl: number): Promise<number>;
+}
+
+class MemoryStore implements RateLimitStore {
+    private store = new Map<string, { count: number; expiresAt: number }>();
+
+    async get(key: string): Promise<number | null> {
+        const entry = this.store.get(key);
+        if (!entry) return null;
+        if (Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return null;
+        }
+        return entry.count;
+    }
+
+    async set(key: string, value: number, ttl: number): Promise<void> {
+        this.store.set(key, { count: value, expiresAt: Date.now() + ttl });
+    }
+
+    async increment(key: string, ttl: number): Promise<number> {
+        const entry = this.store.get(key);
+        if (!entry || Date.now() > entry.expiresAt) {
+            this.store.set(key, { count: 1, expiresAt: Date.now() + ttl });
+            return 1;
+        }
+        entry.count++;
+        return entry.count;
+    }
+
+    cleanup(): void {
+        const now = Date.now();
+        for (const [key, entry] of this.store.entries()) {
+            if (now > entry.expiresAt) this.store.delete(key);
+        }
+    }
+}
+
+class CacheStoreWrapper implements RateLimitStore {
+    constructor(private cache: any) { }
+
+    async get(key: string): Promise<number | null> {
+        return await this.cache.get(key);
+    }
+
+    async set(key: string, value: number, ttl: number): Promise<void> {
+        await this.cache.set(key, value, ttl / 1000); // Cache feature expects seconds typically if using Redis, but check implementation
+    }
+
+    async increment(key: string, ttl: number): Promise<number> {
+        const ttlSeconds = Math.ceil(ttl / 1000);
+        const current = await this.cache.get(key);
+        if (current === null) {
+            await this.cache.set(key, 1, ttlSeconds);
+            return 1;
+        }
+        // Use atomic increment if available (Redis INCR)
+        if (this.cache.increment) return await this.cache.increment(key);
+
+        // Fallback: increment and re-set with TTL
+        const newVal = Number(current) + 1;
+        await this.cache.set(key, newVal, ttlSeconds);
+        return newVal;
+    }
+}
+
+export class RateLimitFeature implements Feature {
+    name = "rate-limit";
+    private config: Required<Omit<RateLimitConfig, "keyGenerator" | "skip" | "handler">> & {
+        keyGenerator?: RateLimitConfig["keyGenerator"];
+        skip?: RateLimitConfig["skip"];
+        handler?: RateLimitConfig["handler"];
+    };
+    private store?: RateLimitStore;
+    private cleanupInterval?: ReturnType<typeof setInterval>;
+
+    constructor(config: RateLimitConfig = {}) {
+        this.config = {
+            windowMs: config.windowMs || 15 * 60 * 1000,
+            max: config.max || 100,
+            standardHeaders: config.standardHeaders ?? true,
+            store: config.store || "memory",
+            keyGenerator: config.keyGenerator,
+            skip: config.skip,
+            handler: config.handler
+        };
+    }
+
+    async initialize(kernel: Kernel): Promise<void> {
+        if (this.config.store === "cache") {
+            const cacheFeature = kernel.getFeature("cache") as any;
+            if (cacheFeature?.client) {
+                this.store = new CacheStoreWrapper(cacheFeature.client);
+            } else {
+                console.warn("⚠️ Cache feature not available for rate-limit, falling back to memory store");
+                const mem = new MemoryStore();
+                this.store = mem;
+                this.cleanupInterval = setInterval(() => mem.cleanup(), 300000);
+            }
+        }
+
+        if (this.config.store === "memory") {
+            const mem = new MemoryStore();
+            this.store = mem;
+            this.cleanupInterval = setInterval(() => mem.cleanup(), 300000);
+        }
+
+        const app = kernel.getApp();
+        app.use("*", async (c: Context, next: Next) => {
+            await this.middleware(c, next);
+        });
+        console.log("✅ Rate limit feature initialized");
+    }
+
+    private async middleware(c: Context, next: Next) {
+        if (this.config.skip && this.config.skip(c)) {
+            await next();
+            return;
+        }
+
+        let store = this.store;
+        if (!store && this.config.store === "cache") {
+            const cache = c.get("cache");
+            if (cache) {
+                store = new CacheStoreWrapper(cache);
+            } else {
+                if (!this.store) {
+                    this.store = new MemoryStore(); // Fallback
+                    this.cleanupInterval = setInterval(() => (this.store as MemoryStore).cleanup(), 300000);
+                }
+                store = this.store;
+            }
+        }
+
+        if (!store) {
+            await next();
+            return;
+        }
+
+        const key = this.config.keyGenerator ? this.config.keyGenerator(c) : this.defaultKeyGenerator(c);
+        const rlKey = `rate_limit:${key}`;
+        const count = await store.increment(rlKey, this.config.windowMs);
+
+        if (count > this.config.max) {
+            if (this.config.handler) return this.config.handler(c);
+            throw new HTTPException(429, { message: "Too many requests" });
+        }
+
+        if (this.config.standardHeaders) {
+            c.header("X-RateLimit-Limit", String(this.config.max));
+            c.header("X-RateLimit-Remaining", String(Math.max(0, this.config.max - count)));
+            c.header("X-RateLimit-Reset", String(Math.ceil((Date.now() + this.config.windowMs) / 1000)));
+        }
+
+        await next();
+    }
+
+    private defaultKeyGenerator(c: Context): string {
+        return c.req.header("x-forwarded-for") || c.req.header("x-real-ip") || "unknown";
+    }
+
+    async shutdown() {
+        if (this.cleanupInterval) clearInterval(this.cleanupInterval);
+    }
+}