@africode/core 5.0.0

package/core/server/csrf.js

@@ -0,0 +1,206 @@
+/**
+ * AfriCode CSRF Protection Middleware
+ *
+ * Double-submit cookie pattern for CSRF protection.
+ * Framework-level middleware — secure by default.
+ *
+ * How it works:
+ * 1. Server generates a random CSRF token and sets it as a cookie
+ * 2. Client reads the cookie and sends the token in a header (X-CSRF-Token)
+ * 3. Server compares cookie token with header token
+ * 4. If they match → request is from the legitimate client
+ * 5. If they don't match → request is cross-site (blocked)
+ *
+ * Why double-submit cookie:
+ * - No server-side session storage needed for the token
+ * - Works with stateless APIs
+ * - Compatible with single-page apps and server-rendered pages
+ *
+ * @module core/server/csrf
+ */
+
+import { CsrfError } from '../errors.js';
+import { emitSecurityViolation } from '../config.js';
+
+/**
+ * Generate a cryptographically secure CSRF token
+ * @returns {string} 32-byte hex token
+ */
+export function generateCsrfToken() {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Create the CSRF cookie header string
+ * @param {string} token - The CSRF token
+ * @param {Object} [opts] - Options
+ * @param {boolean} [opts.secure=false] - Set Secure flag (HTTPS only)
+ * @param {string} [opts.sameSite='Strict'] - SameSite policy
+ * @param {number} [opts.maxAge=86400] - Cookie max age in seconds (default: 24h)
+ * @returns {string} Set-Cookie header value
+ */
+export function createCsrfCookie(token, opts = {}) {
+  const { secure = false, sameSite = 'Strict', maxAge = 86400 } = opts;
+  return `csrf_token=${token}; Path=/; Max-Age=${maxAge}; SameSite=${sameSite}${secure ? '; Secure' : ''}`;
+}
+
+/**
+ * Extract the CSRF token from the request cookie
+ * @param {Request} request
+ * @returns {string|null}
+ */
+function getCsrfFromCookie(request) {
+  const cookieHeader = request.headers.get('Cookie');
+  if (!cookieHeader) {return null;}
+
+  const match = cookieHeader.match(/csrf_token=([^;]+)/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Extract the CSRF token from the request header
+ * @param {Request} request
+ * @returns {string|null}
+ */
+function getCsrfFromHeader(request) {
+  return request.headers.get('X-CSRF-Token') || null;
+}
+
+/**
+ * CSRF Protection Middleware
+ *
+ * Validates that the CSRF token in the cookie matches the one in the header.
+ * Only applies to state-changing methods (POST, PUT, PATCH, DELETE).
+ * GET, HEAD, OPTIONS are safe methods and are not checked.
+ *
+ * @param {Object} [config] - Configuration
+ * @param {string[]} [config.safeMethods=['GET', 'HEAD', 'OPTIONS']] - Methods that skip CSRF check
+ * @param {string[]} [config.excludePaths=[]] - Paths that skip CSRF check (e.g. public APIs)
+ * @param {string} [config.headerName='X-CSRF-Token'] - Header name for the token
+ * @param {string} [config.cookieName='csrf_token'] - Cookie name for the token
+ * @param {Function} [config.onFailure] - Custom failure handler (receives request, returns Response)
+ *
+ * @returns {Function} Middleware function: (request) => Response | null
+ *
+ * @example
+ * // In your server setup:
+ * const csrf = createCsrfMiddleware();
+ *
+ * // In your request handler:
+ * const csrfError = csrf(request);
+ * if (csrfError) return csrfError;
+ *
+ * @example
+ * // With configuration:
+ * const csrf = createCsrfMiddleware({
+ *   excludePaths: ['/api/webhooks'],
+ *   onFailure: (req) => new Response('Custom CSRF error', { status: 403 })
+ * });
+ */
+export function createCsrfMiddleware(config = {}) {
+  const {
+    safeMethods = ['GET', 'HEAD', 'OPTIONS'],
+    excludePaths = [],
+    headerName = 'X-CSRF-Token',
+    cookieName = 'csrf_token',
+    onFailure = null
+  } = config;
+
+  /**
+   * @param {Request} request
+   * @returns {Response|null} Returns Response if CSRF fails, null if passes
+   */
+  return function csrfMiddleware(request) {
+    const method = request.method.toUpperCase();
+
+    // Safe methods don't need CSRF protection
+    if (safeMethods.includes(method)) {
+      return null;
+    }
+
+    // Check excluded paths
+    const url = new URL(request.url);
+    if (excludePaths.some(path => url.pathname.startsWith(path))) {
+      return null;
+    }
+
+    // Get tokens
+    const cookieToken = getCsrfFromCookie(request);
+    const headerToken = request.headers.get(headerName);
+
+    // Both must exist
+    if (!cookieToken || !headerToken) {
+      const error = new CsrfError('missing');
+      emitSecurityViolation(error);
+      if (onFailure) {return onFailure(request);}
+      return error.toResponse();
+    }
+
+    // Constant-time comparison to prevent timing attacks
+    if (!timingSafeEqual(cookieToken, headerToken)) {
+      const error = new CsrfError('mismatch');
+      emitSecurityViolation(error);
+      if (onFailure) {return onFailure(request);}
+      return error.toResponse();
+    }
+
+    // CSRF check passed
+    return null;
+  };
+}
+
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ * Both strings must be the same length for timing safety.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) {return false;}
+
+  const encoder = new TextEncoder();
+  const bufA = encoder.encode(a);
+  const bufB = encoder.encode(b);
+
+  // Use constant-time XOR comparison
+  let result = 0;
+  for (let i = 0; i < bufA.length; i++) {
+    result |= bufA[i] ^ bufB[i];
+  }
+
+  return result === 0;
+}
+
+/**
+ * Helper to inject CSRF token into a page response.
+ * Sets the cookie and adds a meta tag for client-side access.
+ *
+ * @param {string} html - The HTML response body
+ * @param {string} token - The CSRF token
+ * @returns {{ html: string, cookie: string }} Modified HTML and cookie header
+ *
+ * @example
+ * const token = generateCsrfToken();
+ * const { html, cookie } = injectCsrfToken(pageHtml, token);
+ * return new Response(html, {
+ *   headers: {
+ *     'Content-Type': 'text/html',
+ *     'Set-Cookie': cookie
+ *   }
+ * });
+ */
+export function injectCsrfToken(html, token) {
+  const metaTag = `<meta name="csrf-token" content="${token}">`;
+  const modifiedHtml = html.replace('</head>', `  ${metaTag}\n</head>`);
+
+  return {
+    html: modifiedHtml,
+    cookie: createCsrfCookie(token)
+  };
+}
+
+export default { generateCsrfToken, createCsrfCookie, createCsrfMiddleware, injectCsrfToken };

package/core/server/db.js

@@ -0,0 +1,39 @@
+/**
+ * AfriCode Database Layer
+ * Zero-config SQLite integration powered by Bun
+ */
+
+import { Database } from "bun:sqlite";
+
+// Auto-create db file
+const db = new Database("africode.sqlite", { create: true });
+
+// Initialize Schema
+db.run(`
+  CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    email TEXT UNIQUE,
+    password_hash TEXT,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+  );
+`);
+
+db.run(`
+  CREATE TABLE IF NOT EXISTS sessions (
+    id TEXT PRIMARY KEY,
+    user_id INTEGER,
+    expires_at DATETIME,
+    FOREIGN KEY(user_id) REFERENCES users(id)
+  );
+`);
+
+export default db;
+
+// Helper query function
+export const query = {
+    getUserByEmail: (email) => db.query("SELECT * FROM users WHERE email = ?").get(email),
+    createUser: (email, hash) => db.run("INSERT INTO users (email, password_hash) VALUES (?, ?)", [email, hash]),
+    createSession: (sid, uid, exp) => db.run("INSERT INTO sessions (id, user_id, expires_at) VALUES (?, ?, ?)", [sid, uid, exp]),
+    getSession: (sid) => db.query("SELECT * FROM sessions WHERE id = ?").get(sid),
+    deleteSession: (sid) => db.run("DELETE FROM sessions WHERE id = ?", [sid])
+};

package/core/server/middleware.js

@@ -0,0 +1,324 @@
+/**
+ * AfriCode Middleware Pipeline
+ * 
+ * Chainable middleware system for cross-cutting concerns:
+ * - CORS handling
+ * - Request logging
+ * - Authentication checks
+ * - Rate limiting
+ * - Error handling
+ * 
+ * Usage:
+ * ```javascript
+ * const app = new MiddlewareApp();
+ * app.use(cors({ origin: 'https://example.com' }));
+ * app.use(logging());
+ * app.use(authRequired());
+ * app.listen(3000);
+ * ```
+ */
+
+export class MiddlewareApp {
+    constructor() {
+        this.middlewares = [];
+        this.errorHandlers = [];
+    }
+
+    /**
+     * Register a middleware function
+     * Middleware receives (request, response, next) and can:
+     * - Modify request/response
+     * - Call next() to continue
+     * - Return a response to short-circuit
+     */
+    use(middleware) {
+        if (typeof middleware !== 'function') {
+            throw new Error('Middleware must be a function');
+        }
+        this.middlewares.push(middleware);
+        return this; // Enable chaining
+    }
+
+    /**
+     * Register error handling middleware
+     */
+    onError(handler) {
+        if (typeof handler !== 'function') {
+            throw new Error('Error handler must be a function');
+        }
+        this.errorHandlers.push(handler);
+        return this;
+    }
+
+    /**
+     * Execute middleware chain
+     */
+    async executeMiddlewares(request, response) {
+        let index = 0;
+
+        const next = async () => {
+            if (index >= this.middlewares.length) {
+                return; // End of chain
+            }
+
+            const middleware = this.middlewares[index++];
+            try {
+                await middleware(request, response, next);
+            } catch (error) {
+                // Call error handlers
+                for (const handler of this.errorHandlers) {
+                    await handler(error, request, response);
+                }
+            }
+        };
+
+        await next();
+    }
+
+    /**
+     * Start HTTP server
+     */
+    listen(port = 3000, callback) {
+        const server = Bun.serve({
+            port,
+            fetch: async (request) => {
+                const response = new Response();
+                await this.executeMiddlewares(request, response);
+                return response;
+            }
+        });
+
+        console.log(`[Middleware] Server listening on port ${port}`);
+        if (callback) callback();
+        return server;
+    }
+}
+
+/**
+ * Built-in Middleware Functions
+ */
+
+/**
+ * CORS Middleware
+ * Handles Cross-Origin Resource Sharing
+ */
+export function cors(options = {}) {
+    const {
+        origin = '*',
+        methods = ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+        allowedHeaders = ['Content-Type', 'Authorization'],
+        credentials = false,
+        maxAge = 3600
+    } = options;
+
+    return async (request, response, next) => {
+        const requestOrigin = request.headers.get('origin');
+
+        // Check if origin is allowed
+        let allowOrigin = false;
+        if (origin === '*') {
+            allowOrigin = true;
+        } else if (Array.isArray(origin)) {
+            allowOrigin = origin.includes(requestOrigin);
+        } else if (typeof origin === 'function') {
+            allowOrigin = origin(requestOrigin);
+        } else {
+            allowOrigin = origin === requestOrigin;
+        }
+
+        if (allowOrigin) {
+            response.headers.set('Access-Control-Allow-Origin', requestOrigin || '*');
+            response.headers.set('Access-Control-Allow-Methods', methods.join(', '));
+            response.headers.set('Access-Control-Allow-Headers', allowedHeaders.join(', '));
+            response.headers.set('Access-Control-Max-Age', maxAge.toString());
+            
+            if (credentials) {
+                response.headers.set('Access-Control-Allow-Credentials', 'true');
+            }
+        }
+
+        // Handle preflight requests
+        if (request.method === 'OPTIONS') {
+            return new Response(null, { status: 204 });
+        }
+
+        await next();
+    };
+}
+
+/**
+ * Request Logging Middleware
+ */
+export function logging(options = {}) {
+    const {
+        format = 'combined',
+        logFn = console.log
+    } = options;
+
+    return async (request, response, next) => {
+        const startTime = Date.now();
+        const method = request.method;
+        const url = new URL(request.url);
+        const pathname = url.pathname;
+
+        await next();
+
+        const duration = Date.now() - startTime;
+        const ip = request.headers.get('x-forwarded-for') || '127.0.0.1';
+
+        if (format === 'json') {
+            logFn(JSON.stringify({
+                ip,
+                method,
+                pathname,
+                duration,
+                timestamp: new Date().toISOString()
+            }));
+        } else if (format === 'combined') {
+            logFn(`[${new Date().toISOString()}] ${ip} - ${method} ${pathname} - ${duration}ms`);
+        } else {
+            logFn(`[${new Date().toISOString()}] ${method} ${pathname} - ${duration}ms`);
+        }
+    };
+}
+
+/**
+ * Authentication Required Middleware
+ */
+export function authRequired() {
+    return async (request, response, next) => {
+        // Extract session from cookies
+        const cookieHeader = request.headers.get('Cookie');
+        if (!cookieHeader) {
+            return new Response(
+                JSON.stringify({ error: 'Unauthorized' }),
+                { status: 401, headers: { 'Content-Type': 'application/json' } }
+            );
+        }
+
+        const sessionMatch = cookieHeader.match(/session_id=([^;]+)/);
+        if (!sessionMatch) {
+            return new Response(
+                JSON.stringify({ error: 'Unauthorized' }),
+                { status: 401, headers: { 'Content-Type': 'application/json' } }
+            );
+        }
+
+        // Attach session ID to request for later use
+        request.sessionId = sessionMatch[1];
+
+        await next();
+    };
+}
+
+/**
+ * Rate Limiting Middleware
+ */
+export function rateLimit(options = {}) {
+    const {
+        maxRequests = 100,
+        windowMs = 60000, // 1 minute
+        keyGenerator = (request) => request.headers.get('x-forwarded-for') || '127.0.0.1'
+    } = options;
+
+    const store = new Map();
+
+    return async (request, response, next) => {
+        const key = keyGenerator(request);
+        const now = Date.now();
+        const record = store.get(key);
+
+        // Clean up old records
+        if (record && now - record.resetTime > windowMs) {
+            store.delete(key);
+        }
+
+        // Check if limit exceeded
+        const current = store.get(key) || { count: 0, resetTime: now };
+        if (current.count >= maxRequests) {
+            return new Response(
+                JSON.stringify({ error: 'Rate limit exceeded' }),
+                { status: 429, headers: { 'Content-Type': 'application/json' } }
+            );
+        }
+
+        current.count++;
+        store.set(key, current);
+
+        // Add rate limit headers
+        response.headers.set('X-RateLimit-Limit', maxRequests.toString());
+        response.headers.set('X-RateLimit-Remaining', (maxRequests - current.count).toString());
+        response.headers.set('X-RateLimit-Reset', (current.resetTime + windowMs).toString());
+
+        await next();
+    };
+}
+
+/**
+ * Error Handling Middleware
+ */
+export function errorHandler() {
+    return async (error, request, response) => {
+        console.error('[Error]', error);
+
+        const statusCode = error.status || 500;
+        const message = error.message || 'Internal Server Error';
+
+        response.status = statusCode;
+        response.headers.set('Content-Type', 'application/json');
+        
+        return new Response(
+            JSON.stringify({
+                error: message,
+                status: statusCode,
+                timestamp: new Date().toISOString()
+            }),
+            { status: statusCode, headers: { 'Content-Type': 'application/json' } }
+        );
+    };
+}
+
+/**
+ * Content Type Validation Middleware
+ */
+export function validateContentType(acceptedTypes = ['application/json']) {
+    return async (request, response, next) => {
+        if (request.method === 'POST' || request.method === 'PUT') {
+            const contentType = request.headers.get('Content-Type')?.split(';')[0];
+            if (!acceptedTypes.includes(contentType)) {
+                return new Response(
+                    JSON.stringify({ error: 'Unsupported Content-Type' }),
+                    { status: 415, headers: { 'Content-Type': 'application/json' } }
+                );
+            }
+        }
+        await next();
+    };
+}
+
+/**
+ * Security Headers Middleware
+ */
+export function securityHeaders() {
+    return async (request, response, next) => {
+        response.headers.set('X-Content-Type-Options', 'nosniff');
+        response.headers.set('X-Frame-Options', 'DENY');
+        response.headers.set('X-XSS-Protection', '1; mode=block');
+        response.headers.set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+        response.headers.set('Content-Security-Policy', "default-src 'self'");
+        response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
+
+        await next();
+    };
+}
+
+export default {
+    MiddlewareApp,
+    cors,
+    logging,
+    authRequired,
+    rateLimit,
+    errorHandler,
+    validateContentType,
+    securityHeaders
+};