@iskra-bun/web-kit 0.1.0

package/src/features/api-key.ts

@@ -0,0 +1,243 @@
+import type { Feature, ApiKeyConfig, ApiKeyMetadata, ApiKeyValidationResult } from "../types";
+import type { Kernel } from "../kernel";
+import type { Context, Next } from "hono";
+import { HTTPException } from "hono/http-exception";
+
+// --- ApiKeyStore ---
+
+export class ApiKeyStore {
+    private staticKeysMap: Map<string, ApiKeyMetadata> = new Map();
+    private cache?: any;
+
+    constructor(private config: Required<ApiKeyConfig>, private kernel: Kernel) {
+        this.initializeStaticKeys();
+    }
+
+    private getCache() {
+        if (!this.cache && this.config.enableCache) {
+            const cacheFeature = this.kernel.getFeature<any>('cache');
+            if (cacheFeature) {
+                this.cache = cacheFeature.client;
+            }
+        }
+        return this.cache;
+    }
+
+    private initializeStaticKeys(): void {
+        if (!this.config.staticKeys || this.config.staticKeys.length === 0) {
+            return;
+        }
+
+        for (const staticKey of this.config.staticKeys) {
+            const metadata: ApiKeyMetadata = {
+                id: this.generateId(staticKey.key),
+                key: staticKey.key,
+                name: staticKey.name,
+                scopes: staticKey.scopes,
+                rateLimit: staticKey.rateLimit,
+                expiresAt: staticKey.expiresAt,
+                createdAt: new Date(),
+                metadata: staticKey.metadata,
+                lastUsedAt: undefined // Explicitly undefined initially
+            };
+
+            this.staticKeysMap.set(staticKey.key, metadata);
+        }
+        console.log(`✅ Loaded ${this.staticKeysMap.size} static API keys`);
+    }
+
+    private generateId(key: string): string {
+        return key.substring(0, 8);
+    }
+
+    private compareKeys(a: string, b: string): boolean {
+        if (a.length !== b.length) return false;
+        let result = 0;
+        for (let i = 0; i < a.length; i++) {
+            result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+        }
+        return result === 0;
+    }
+
+    private isExpired(expiresAt?: Date): boolean {
+        if (!expiresAt) return false;
+        return new Date() > expiresAt;
+    }
+
+    async validate(key: string): Promise<ApiKeyValidationResult> {
+        if (!key) return { isValid: false, error: "API key is required" };
+
+        const cache = this.getCache();
+        const cacheKey = `apikey:${key}`;
+
+        if (cache) {
+            try {
+                const cached = await cache.get(cacheKey);
+                if (cached) {
+                    const metadata = typeof cached === 'string' ? JSON.parse(cached) : cached;
+                    return { isValid: true, key: metadata };
+                }
+            } catch (err) {
+                // Cache error, ignore
+            }
+        }
+
+        // Check static keys
+        for (const [staticKey, metadata] of this.staticKeysMap) {
+            if (this.compareKeys(key, staticKey)) {
+                if (this.isExpired(metadata.expiresAt)) {
+                    return { isValid: false, error: "API key has expired" };
+                }
+                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);
+                    } catch {
+                        // ignore cache write failures — validation already succeeded
+                    }
+                }
+
+                return { isValid: true, key: metadata };
+            }
+        }
+
+        return { isValid: false, error: "Invalid API key" };
+    }
+
+    hasScopes(key: ApiKeyMetadata, requiredScopes: string[]): boolean {
+        if (!requiredScopes || requiredScopes.length === 0) return true;
+        if (!key.scopes || key.scopes.length === 0) return false;
+
+        for (const requiredScope of requiredScopes) {
+            const hasScope = key.scopes.some((scope) => {
+                if (scope.endsWith("*")) {
+                    const prefix = scope.slice(0, -1);
+                    return requiredScope.startsWith(prefix);
+                }
+                return scope === requiredScope;
+            });
+
+            if (!hasScope) return false;
+        }
+        return true;
+    }
+}
+
+// --- ApiKeyFeature ---
+
+declare module "hono" {
+    interface ContextVariableMap {
+        apiKey?: ApiKeyMetadata;
+        apiKeyScopes?: string[];
+        hasScope?: (scope: string) => boolean;
+        hasAnyScope?: (...scopes: string[]) => boolean;
+        hasAllScopes?: (...scopes: string[]) => boolean;
+    }
+}
+
+export class ApiKeyFeature implements Feature {
+    name = "apiKey";
+    private store?: ApiKeyStore;
+    private config: Required<ApiKeyConfig>;
+
+    constructor(config: ApiKeyConfig = {}) {
+        this.config = {
+            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,
+            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>;
+    }
+
+    async initialize(kernel: Kernel): Promise<void> {
+        this.store = new ApiKeyStore(this.config, kernel);
+        const app = kernel.getApp();
+
+        app.use("*", async (c: Context, next: Next) => {
+            if (this.shouldSkipPath(c.req.path)) {
+                await next();
+                return;
+            }
+
+            const apiKey = this.extractApiKey(c);
+            if (!apiKey) {
+                c.set("apiKey", undefined);
+                c.set("apiKeyScopes", undefined);
+                await next();
+                return;
+            }
+
+            const result = await this.store!.validate(apiKey);
+            if (!result.isValid) {
+                throw new HTTPException(401, { message: result.error || "Invalid API key" });
+            }
+
+            c.set("apiKey", result.key);
+            c.set("apiKeyScopes", result.key?.scopes || []);
+
+            c.set("hasScope", (scope: string) => this.store!.hasScopes(result.key!, [scope]));
+            c.set("hasAnyScope", (...scopes: string[]) => scopes.some(s => this.store!.hasScopes(result.key!, [s])));
+            c.set("hasAllScopes", (...scopes: string[]) => this.store!.hasScopes(result.key!, scopes));
+
+            await next();
+        });
+
+        console.log("✅ API Key feature initialized");
+    }
+
+    private shouldSkipPath(path: string): boolean {
+        if (!this.config.skipPaths?.length) return false;
+        return this.config.skipPaths.some(skip => {
+            if (skip.endsWith("*")) return path.startsWith(skip.slice(0, -1));
+            return path === skip;
+        });
+    }
+
+    private extractApiKey(c: Context): string | null {
+        for (const strategy of (this.config.extractStrategies || [])) {
+            let key: string | null = null;
+            switch (strategy) {
+                case "header":
+                    key = c.req.header(this.config.headerName) || null;
+                    break;
+                case "bearer": {
+                    const auth = c.req.header("Authorization");
+                    if (auth?.startsWith("Bearer ")) key = auth.substring(7);
+                    break;
+                }
+                case "query":
+                    key = c.req.query(this.config.queryParamName) || null;
+                    break;
+            }
+            if (key) return key;
+        }
+        return null;
+    }
+}
+
+export function requireApiKey() {
+    return async (c: Context, next: Next) => {
+        if (!c.get("apiKey")) throw new HTTPException(401, { message: "API key is required" });
+        await next();
+    };
+}
+
+export function requireScope(...scopes: string[]) {
+    return async (c: Context, next: Next) => {
+        const hasAll = c.get("hasAllScopes");
+        if (!c.get("apiKey")) throw new HTTPException(401, { message: "API key is required" });
+        if (!hasAll || !hasAll(...scopes)) throw new HTTPException(403, { message: "Insufficient scopes" });
+        await next();
+    };
+}

package/src/features/auth/better-auth-config.ts

@@ -0,0 +1,160 @@
+import { betterAuth, type Auth as BetterAuthInstance } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { genericOAuth } from "better-auth/plugins/generic-oauth";
+import { pgSchema, mysqlSchema, sqliteSchema } from "./schema";
+
+export interface BetterAuthConfigOptions {
+    db: any; // Drizzle instance
+    adapterType: "postgres" | "mysql" | "sqlite";
+    secret: string;
+    baseURL?: string;
+    basePath?: string;
+    trustedOrigins?: string[];
+    enableEmailPassword?: boolean;
+    disableCSRFCheck?: boolean;
+    // deno-lint-ignore no-explicit-any
+    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>;
+        };
+    };
+}
+
+export function createBetterAuth(options: BetterAuthConfigOptions): BetterAuthInstance {
+    const {
+        db,
+        adapterType,
+        secret,
+        baseURL = "http://localhost:3000",
+        basePath = "/api/auth",
+        trustedOrigins = [],
+        enableEmailPassword = true,
+        disableCSRFCheck = false,
+        socialProviders,
+        oidcConfig,
+    } = options;
+
+    const baseOrigin = new URL(baseURL).origin;
+    const allTrustedOrigins = trustedOrigins.includes(baseOrigin)
+        ? trustedOrigins
+        : [baseOrigin, ...trustedOrigins];
+
+    console.log("[BetterAuth Config] Creating Drizzle adapter...");
+
+    let schema;
+    let provider: "pg" | "mysql" | "sqlite";
+
+    switch (adapterType) {
+        case "postgres":
+            schema = pgSchema;
+            provider = "pg";
+            break;
+        case "mysql":
+            schema = mysqlSchema;
+            provider = "mysql";
+            break;
+        case "sqlite":
+            schema = sqliteSchema;
+            provider = "sqlite";
+            break;
+        default:
+            throw new Error(`Unsupported adapter type: ${adapterType}`);
+    }
+
+    const database = drizzleAdapter(db, {
+        provider,
+        schema
+    });
+
+    console.log("[BetterAuth Config] Initializing betterAuth with config:", {
+        baseURL,
+        basePath,
+        provider,
+        enableEmailPassword
+    });
+
+    const plugins = [];
+    if (oidcConfig) {
+        const authorizationUrl = oidcConfig.authorizationEndpoint ||
+            `${oidcConfig.issuer}/protocol/openid-connect/auth`;
+        const tokenUrl = oidcConfig.tokenEndpoint ||
+            `${oidcConfig.issuer}/protocol/openid-connect/token`;
+        const userInfoUrl = oidcConfig.userinfoEndpoint ||
+            `${oidcConfig.issuer}/protocol/openid-connect/userinfo`;
+
+        plugins.push(
+            genericOAuth({
+                config: [
+                    {
+                        providerId: oidcConfig.providerId || "oidc",
+                        clientId: oidcConfig.clientId,
+                        clientSecret: oidcConfig.clientSecret,
+                        authorizationUrl,
+                        tokenUrl,
+                        userInfoUrl,
+                        discoveryUrl: oidcConfig.discoveryEndpoint ||
+                            `${oidcConfig.issuer}/.well-known/openid-configuration`,
+                        scopes: oidcConfig.scopes || ["openid", "email", "profile"],
+                        pkce: oidcConfig.pkce !== undefined ? oidcConfig.pkce : false,
+                        mapProfileToUser: (profile: any) => {
+                            return {
+                                id: profile.sub || profile.id,
+                                email: profile.email,
+                                name: profile.name || profile.preferred_username,
+                                image: profile.picture || profile.image,
+                                emailVerified: profile.email_verified || false,
+                            };
+                        },
+                    },
+                ],
+            }),
+        );
+    }
+
+    return betterAuth({
+        database,
+        secret,
+        baseURL,
+        basePath,
+        trustedOrigins: allTrustedOrigins,
+        emailAndPassword: enableEmailPassword
+            ? {
+                enabled: true,
+                autoSignIn: true,
+            }
+            : undefined,
+        socialProviders: Object.keys(socialProviders || {}).length > 0 ? socialProviders : undefined,
+        plugins,
+        session: {
+            expiresIn: 60 * 60 * 24 * 7,
+            updateAge: 60 * 60 * 24,
+            cookieCache: {
+                enabled: true,
+                maxAge: 5 * 60,
+            },
+        },
+        advanced: {
+            disableCSRFCheck,
+            generateId: () => crypto.randomUUID().replace(/-/g, ""),
+        },
+    }) as unknown as BetterAuthInstance;
+}
+
+export type Auth = ReturnType<typeof createBetterAuth>;

package/src/features/auth/index.ts

@@ -0,0 +1,229 @@
+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 { z } from "@hono/zod-openapi";
+import type { DbFeature } from "../db";
+import type { OpenAPIFeature } from "../openapi";
+import type { User } from "./types";
+
+declare module "hono" {
+    interface ContextVariableMap {
+        user: User | null;
+        authUser: User | null;
+    }
+}
+
+// ─── OpenAPI Schemas ─────────────────────────────────────────────────────────
+
+const SignInSchema = z.object({
+    email: z.string().email(),
+    password: z.string().min(1),
+});
+
+const SignUpSchema = z.object({
+    email: z.string().email(),
+    password: z.string().min(8),
+    name: z.string().optional(),
+});
+
+const AuthSuccessSchema = z.object({
+    token: z.string().optional(),
+    user: z.object({
+        id: z.string(),
+        email: z.string(),
+        name: z.string().optional(),
+    }).optional(),
+    session: z.any().optional(),
+});
+
+const SessionResponseSchema = z.object({
+    session: z.any().nullable(),
+    user: z.any().nullable(),
+});
+
+// ─── Auth Feature ────────────────────────────────────────────────────────────
+
+export class AuthFeature implements Feature {
+    name = "auth";
+    dependencies = ["db"];
+
+    private auth: Auth | undefined;
+    private config: Required<Pick<AuthConfig, "secret" | "basePath">> & AuthConfig;
+    private kernel?: Kernel;
+    private authMode: "oidc" | "email";
+
+    constructor(config: AuthConfig) {
+        this.config = {
+            ...config,
+            basePath: config.basePath || "/api/sso",
+            baseURL: config.baseURL || "http://localhost:3000",
+        };
+
+        if (config.authMode === "oidc" || config.authMode === "email") {
+            this.authMode = config.authMode;
+        } else {
+            this.authMode = config.oidcConfig ? "oidc" : "email";
+        }
+    }
+
+    async initialize(kernel: Kernel): Promise<void> {
+        this.kernel = kernel;
+        const dbFeature = kernel.getFeature("db") as unknown as DbFeature;
+        if (!dbFeature) {
+            throw new Error("AuthFeature requires DbFeature");
+        }
+
+        const db = dbFeature.db;
+        const adapterType = dbFeature.adapter as "postgres" | "mysql" | "sqlite";
+
+        if (!adapterType) {
+            throw new Error("DbFeature must expose 'adapter' type (postgres, mysql, sqlite)");
+        }
+
+        this.auth = createBetterAuth({
+            db,
+            adapterType,
+            secret: this.config.secret,
+            baseURL: this.config.baseURL,
+            basePath: this.config.basePath,
+            trustedOrigins: this.config.trustedOrigins,
+            enableEmailPassword: true,
+            disableCSRFCheck: this.config.disableCSRFCheck,
+            socialProviders: this.config.socialProviders,
+            oidcConfig: this.config.oidcConfig,
+        });
+
+        const app = kernel.getApp();
+        app.use("*", async (c: Context, next: Next) => {
+            try {
+                const session = await this.auth!.api.getSession({
+                    headers: c.req.raw.headers,
+                });
+
+                if (session && session.user) {
+                    c.set("user", session.user);
+                    c.set("authUser", session.user);
+                }
+            } catch (error) {
+                // Ignore session errors (just not logged in)
+            }
+            await next();
+        });
+
+        console.log("✅ Auth feature initialized (better-auth)");
+    }
+
+    routes(app: Hono): void {
+        if (!this.auth) {
+            throw new Error("Auth not initialized");
+        }
+
+        const base = this.config.basePath!;
+        const openapi = this.kernel?.getFeature("openapi") as OpenAPIFeature | undefined;
+
+        // Register explicit OpenAPI-documented routes
+        if (openapi) {
+            openapi.addRoute(
+                {
+                    method: "post",
+                    path: `${base}/sign-in/email`,
+                    tags: ["Auth"],
+                    summary: "Sign in with email and password",
+                    request: {
+                        body: {
+                            content: { "application/json": { schema: SignInSchema } },
+                        },
+                    },
+                    responses: {
+                        200: {
+                            description: "Sign in successful",
+                            content: { "application/json": { schema: AuthSuccessSchema } },
+                        },
+                        401: { description: "Invalid credentials" },
+                    },
+                },
+                (c: any) => this.auth!.handler(c.req.raw),
+            );
+
+            openapi.addRoute(
+                {
+                    method: "post",
+                    path: `${base}/sign-up/email`,
+                    tags: ["Auth"],
+                    summary: "Create a new account",
+                    request: {
+                        body: {
+                            content: { "application/json": { schema: SignUpSchema } },
+                        },
+                    },
+                    responses: {
+                        200: {
+                            description: "Account created",
+                            content: { "application/json": { schema: AuthSuccessSchema } },
+                        },
+                        400: { description: "Validation error" },
+                    },
+                },
+                (c: any) => this.auth!.handler(c.req.raw),
+            );
+
+            openapi.addRoute(
+                {
+                    method: "post",
+                    path: `${base}/sign-out`,
+                    tags: ["Auth"],
+                    summary: "Sign out",
+                    responses: {
+                        200: { description: "Signed out" },
+                    },
+                },
+                (c: any) => this.auth!.handler(c.req.raw),
+            );
+
+            openapi.addRoute(
+                {
+                    method: "get",
+                    path: `${base}/get-session`,
+                    tags: ["Auth"],
+                    summary: "Get current session",
+                    responses: {
+                        200: {
+                            description: "Current session",
+                            content: { "application/json": { schema: SessionResponseSchema } },
+                        },
+                    },
+                },
+                (c: any) => this.auth!.handler(c.req.raw),
+            );
+        }
+
+        // Catch-all for all other auth routes (OAuth callbacks, etc.)
+        app.on(["POST", "GET"], `${base}/*`, (c) => {
+            return this.auth!.handler(c.req.raw);
+        });
+    }
+
+    getAuth(): Auth | undefined {
+        return this.auth;
+    }
+}
+
+export function requireAuth(kernel: Kernel) {
+    return async (c: Context, next: Next) => {
+        const authFeature = kernel.getFeature("auth") as AuthFeature;
+        if (!authFeature) throw new HTTPException(500, { message: "Auth not initialized" });
+
+        const auth = authFeature.getAuth();
+        if (!auth) throw new HTTPException(500, { message: "Auth not ready" });
+
+        const session = await auth.api.getSession({ headers: c.req.raw.headers });
+        if (!session || !session.user) {
+            throw new HTTPException(401, { message: "Unauthorized" });
+        }
+
+        c.set("user", session.user);
+        c.set("authUser", session.user);
+        await next();
+    };
+}