@zintrust/core 0.4.17 → 0.4.19

package/src/middleware/RateLimiter.js

@@ -0,0 +1,276 @@
+/**
+ * Rate Limiter Middleware
+ * Token bucket implementation for request rate limiting
+ * Zero-dependency implementation
+ */
+import { Cache } from '../cache/Cache.js';
+import { Env } from '../config/env.js';
+import { Logger } from '../config/logger.js';
+import { respondWithMiddlewareFailure, } from './MiddlewareFailureResponder.js';
+const createMemoryStore = () => {
+    const entries = new Map();
+    let nextCleanupAt = Date.now() + 60_000;
+    const cleanupExpired = (now) => {
+        if (now < nextCleanupAt)
+            return;
+        for (const [k, state] of entries.entries()) {
+            if (now > state.resetTime)
+                entries.delete(k);
+        }
+        nextCleanupAt = now + 60_000;
+    };
+    return Object.freeze({
+        async get(key) {
+            await Promise.resolve();
+            const now = Date.now();
+            cleanupExpired(now);
+            const state = entries.get(key);
+            if (!state)
+                return null;
+            if (now > state.resetTime) {
+                entries.delete(key);
+                return null;
+            }
+            return { ...state };
+        },
+        async set(key, value) {
+            await Promise.resolve();
+            const now = Date.now();
+            cleanupExpired(now);
+            entries.set(key, { ...value });
+        },
+        async delete(key) {
+            await Promise.resolve();
+            entries.delete(key);
+        },
+    });
+};
+const createCacheStore = (storeName) => {
+    const store = Cache.store(storeName);
+    return Object.freeze({
+        async get(key) {
+            return store.get(key);
+        },
+        async set(key, value, ttlSeconds) {
+            await store.set(key, value, ttlSeconds);
+        },
+        async delete(key) {
+            await store.delete(key);
+        },
+    });
+};
+const normalizeStoreName = (name) => {
+    const raw = String(name ?? '')
+        .trim()
+        .toLowerCase();
+    if (raw === 'redis')
+        return 'redis';
+    if (raw === 'kv')
+        return 'kv';
+    if (raw === 'db' || raw === 'database' || raw === 'mongo' || raw === 'mongodb')
+        return 'db';
+    return 'memory';
+};
+const resolveStore = (name) => {
+    const selected = normalizeStoreName((name ?? Env.RATE_LIMIT_STORE) || Env.RATE_LIMIT_DRIVER || 'memory');
+    if (selected === 'redis')
+        return { storeName: 'redis', store: createCacheStore('redis') };
+    if (selected === 'kv')
+        return { storeName: 'kv', store: createCacheStore('kv') };
+    if (selected === 'db')
+        return { storeName: 'db', store: createCacheStore('mongodb') };
+    return { storeName: 'memory', store: createMemoryStore() };
+};
+let serviceStoreSelection = normalizeStoreName(Env.RATE_LIMIT_STORE || Env.RATE_LIMIT_DRIVER || 'memory');
+let serviceStore = resolveStore(serviceStoreSelection).store;
+const prefixKey = (purpose, key) => {
+    const prefix = Env.RATE_LIMIT_KEY_PREFIX.trim();
+    return `${prefix}${purpose}:${key}`;
+};
+const consume = async (params) => {
+    const now = Date.now();
+    const ttlSeconds = Math.max(1, Math.ceil(params.windowMs / 1000));
+    const existing = await params.store.get(params.key);
+    const state = existing === null || now > existing.resetTime
+        ? { count: 0, resetTime: now + params.windowMs }
+        : existing;
+    const nextCount = state.count + 1;
+    const nextState = { count: nextCount, resetTime: state.resetTime };
+    await params.store.set(params.key, nextState, ttlSeconds);
+    return {
+        count: nextCount,
+        resetTime: nextState.resetTime,
+        allowed: nextCount <= params.max,
+    };
+};
+const resolveRemoteAddress = (candidate) => {
+    if (candidate === null || candidate === undefined)
+        return undefined;
+    if (typeof candidate !== 'object')
+        return undefined;
+    const record = candidate;
+    const ip = record['remoteAddress'];
+    return typeof ip === 'string' && ip.length > 0 ? ip : undefined;
+};
+const resolveRemoteAddressFromRaw = (raw) => {
+    if (raw === null || raw === undefined)
+        return undefined;
+    if (typeof raw !== 'object')
+        return undefined;
+    const rawRecord = raw;
+    return (resolveRemoteAddress(rawRecord['socket']) ??
+        resolveRemoteAddress(rawRecord['connection']) ??
+        resolveRemoteAddress(raw));
+};
+const DEFAULT_OPTIONS = {
+    windowMs: 60 * 1000, // 1 minute
+    max: 100, // 100 requests per minute
+    message: 'Too many requests, please try again later.',
+    statusCode: 429,
+    headers: true,
+    keyGenerator: (req) => {
+        const forwardedFor = req.getHeader('x-forwarded-for');
+        const forwardedForIp = typeof forwardedFor === 'string' && forwardedFor.length > 0
+            ? forwardedFor.split(',')[0]?.trim()
+            : undefined;
+        const raw = req.getRaw();
+        const rawIp = resolveRemoteAddressFromRaw(raw);
+        return forwardedForIp ?? rawIp ?? 'unknown';
+    },
+};
+export const RateLimiter = Object.freeze({
+    /**
+     * Configure the store used by the programmatic API (attempt/tooManyAttempts/till/clear).
+     * Defaults to 'memory'.
+     */
+    configure(config) {
+        serviceStoreSelection = normalizeStoreName(config?.store);
+        serviceStore = resolveStore(serviceStoreSelection).store;
+    },
+    /**
+     * Attempt to perform an action.
+     *
+     * Returns true if allowed (and records the hit), false if rate limited.
+     */
+    async attempt(key, maxAttempts, decaySeconds) {
+        const windowMs = Math.max(1, Math.floor(decaySeconds * 1000));
+        const namespacedKey = prefixKey('service', key);
+        const out = await consume({
+            store: serviceStore,
+            key: namespacedKey,
+            max: maxAttempts,
+            windowMs,
+        });
+        return out.allowed;
+    },
+    /**
+     * Check if the key is currently rate limited.
+     */
+    async tooManyAttempts(key, maxAttempts) {
+        const now = Date.now();
+        const namespacedKey = prefixKey('service', key);
+        const state = await serviceStore.get(namespacedKey);
+        if (!state || now > state.resetTime)
+            return false;
+        return state.count >= maxAttempts;
+    },
+    /**
+     * Seconds until the key is available again.
+     * Returns 0 if not rate limited.
+     */
+    async till(key) {
+        const now = Date.now();
+        const namespacedKey = prefixKey('service', key);
+        const state = await serviceStore.get(namespacedKey);
+        if (!state || now > state.resetTime)
+            return 0;
+        return Math.max(0, Math.ceil((state.resetTime - now) / 1000));
+    },
+    /**
+     * Clear rate limit state for a key.
+     */
+    async clear(key) {
+        const namespacedKey = prefixKey('service', key);
+        await serviceStore.delete(namespacedKey);
+    },
+    /**
+     * Create rate limiter middleware
+     */
+    create(options = DEFAULT_OPTIONS) {
+        const config = { ...DEFAULT_OPTIONS, ...options };
+        const { storeName, store } = resolveStore(config.store);
+        const useMemoryInstanceStore = storeName === 'memory';
+        // Middleware store is per-instance (matches prior behavior).
+        const clients = new Map();
+        // Cleanup to prevent unbounded growth.
+        // Done lazily (on requests) to avoid background timers in serverless/test environments.
+        let nextCleanupAt = Date.now() + config.windowMs;
+        const cleanupExpiredClients = (now) => {
+            if (now < nextCleanupAt)
+                return;
+            for (const [k, state] of clients.entries()) {
+                if (now > state.resetTime) {
+                    clients.delete(k);
+                }
+            }
+            nextCleanupAt = now + config.windowMs;
+        };
+        const getOrInitClient = (key, now) => {
+            let client = clients.get(key);
+            if (!client || now > client.resetTime) {
+                client = { count: 0, resetTime: now + config.windowMs };
+                clients.set(key, client);
+            }
+            return client;
+        };
+        return async (req, res, next) => {
+            const key = config.keyGenerator ? config.keyGenerator(req) : 'unknown';
+            const now = Date.now();
+            let count;
+            let resetAt;
+            if (useMemoryInstanceStore) {
+                cleanupExpiredClients(now);
+                const client = getOrInitClient(key, now);
+                client.count++;
+                count = client.count;
+                resetAt = client.resetTime;
+            }
+            else {
+                // Include limiter config to avoid collisions between different middleware instances.
+                const middlewareKey = prefixKey('middleware', `${config.max}:${config.windowMs}:${key}`);
+                const out = await consume({
+                    store,
+                    key: middlewareKey,
+                    max: config.max,
+                    windowMs: config.windowMs,
+                });
+                count = out.count;
+                resetAt = out.resetTime;
+            }
+            const remaining = Math.max(0, config.max - count);
+            const resetTime = Math.ceil((resetAt - now) / 1000);
+            // Set headers
+            if (config.headers ?? false) {
+                res.setHeader('X-RateLimit-Limit', config.max.toString());
+                res.setHeader('X-RateLimit-Remaining', remaining.toString());
+                res.setHeader('X-RateLimit-Reset', resetTime.toString());
+            }
+            // Check limit
+            if (count > config.max) {
+                Logger.warn(`Rate limit exceeded for IP: ${key}`);
+                await respondWithMiddlewareFailure(req, res, config.onFailure, {
+                    middleware: 'rateLimit',
+                    reason: 'rate_limit_exceeded',
+                    statusCode: config.statusCode ?? 429,
+                    message: config.message ?? 'Too many requests',
+                    body: {
+                        error: 'Too Many Requests',
+                        message: config.message,
+                    },
+                });
+                return;
+            }
+            await next();
+        };
+    },
+});

package/src/middleware/SanitizeBodyMiddleware.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Sanitize Body Middleware
+ * Applies recursive XSS sanitization (tag stripping + entity escaping) to JSON request bodies.
+ *
+ * This is a defense-in-depth layer that normalizes untrusted input early.
+ */
+import type { Middleware } from './MiddlewareStack';
+export declare const SanitizeBodyMiddleware: Readonly<{
+    create(): Middleware;
+}>;
+export default SanitizeBodyMiddleware;
+//# sourceMappingURL=SanitizeBodyMiddleware.d.ts.map

package/src/middleware/SanitizeBodyMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SanitizeBodyMiddleware.d.ts","sourceRoot":"","sources":["../../../src/middleware/SanitizeBodyMiddleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAG9D,eAAO,MAAM,sBAAsB;cACvB,UAAU;EAyBpB,CAAC;AAEH,eAAe,sBAAsB,CAAC"}

package/src/middleware/SanitizeBodyMiddleware.js

@@ -0,0 +1,31 @@
+/**
+ * Sanitize Body Middleware
+ * Applies recursive XSS sanitization (tag stripping + entity escaping) to JSON request bodies.
+ *
+ * This is a defense-in-depth layer that normalizes untrusted input early.
+ */
+import { Xss } from '../security/Xss.js';
+export const SanitizeBodyMiddleware = Object.freeze({
+    create() {
+        return async (req, _res, next) => {
+            const method = req.getMethod();
+            if (method === 'GET' || method === 'HEAD' || method === 'OPTIONS' || method === 'DELETE') {
+                await next();
+                return;
+            }
+            if (req.isJson() === false) {
+                await next();
+                return;
+            }
+            const rawBody = req.getBody();
+            if (rawBody === undefined || rawBody === null) {
+                await next();
+                return;
+            }
+            const sanitized = Xss.sanitize(rawBody);
+            req.setBody(sanitized);
+            await next();
+        };
+    },
+});
+export default SanitizeBodyMiddleware;

package/src/middleware/SecurityMiddleware.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Security Middleware
+ * Implements standard security headers and CORS protection
+ * Zero-dependency implementation replacing helmet/cors
+ */
+import type { Middleware } from './MiddlewareStack';
+export interface SecurityOptions {
+    hsts?: {
+        maxAge?: number;
+        includeSubDomains?: boolean;
+        preload?: boolean;
+    };
+    frameguard?: {
+        action?: 'DENY' | 'SAMEORIGIN';
+    };
+    cors?: {
+        origin?: string;
+        methods?: string[];
+        allowedHeaders?: string[];
+        credentials?: boolean;
+        maxAge?: number;
+    };
+    csp?: {
+        directives?: Record<string, string[]>;
+    };
+}
+export declare const SecurityMiddleware: Readonly<{
+    /**
+     * Create security middleware with options
+     */
+    create(options?: SecurityOptions): Middleware;
+}>;
+//# sourceMappingURL=SecurityMiddleware.d.ts.map

package/src/middleware/SecurityMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SecurityMiddleware.d.ts","sourceRoot":"","sources":["../../../src/middleware/SecurityMiddleware.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,UAAU,CAAC,EAAE;QACX,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;KAChC,CAAC;IACF,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,GAAG,CAAC,EAAE;QACJ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;KACvC,CAAC;CACH;AA+FD,eAAO,MAAM,kBAAkB;IAC7B;;OAEG;qBACa,eAAe,GAAQ,UAAU;EAgBjD,CAAC"}

package/src/middleware/SecurityMiddleware.js

@@ -0,0 +1,106 @@
+/**
+ * Security Middleware
+ * Implements standard security headers and CORS protection
+ * Zero-dependency implementation replacing helmet/cors
+ */
+const DEFAULT_OPTIONS = {
+    hsts: {
+        maxAge: 15552000, // 180 days
+        includeSubDomains: true,
+        preload: false,
+    },
+    frameguard: {
+        action: 'SAMEORIGIN',
+    },
+    cors: {
+        origin: '*',
+        methods: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'],
+        allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With', 'X-CSRF-Token'],
+        credentials: true,
+        maxAge: 86400,
+    },
+};
+function applyHsts(res, hsts) {
+    if (!hsts)
+        return;
+    let headerValue = `max-age=${hsts.maxAge}`;
+    if (hsts.includeSubDomains ?? false)
+        headerValue += '; includeSubDomains';
+    if (hsts.preload ?? false)
+        headerValue += '; preload';
+    res.setHeader('Strict-Transport-Security', headerValue);
+}
+function applyFrameguard(res, frameguard) {
+    if (!frameguard)
+        return;
+    res.setHeader('X-Frame-Options', frameguard.action ?? 'SAMEORIGIN');
+}
+function applyNoSniff(res) {
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+}
+function applyReferrerPolicy(res) {
+    res.setHeader('Referrer-Policy', 'no-referrer');
+}
+function applyCsp(res, csp) {
+    if (!csp?.directives)
+        return;
+    const headerValue = Object.entries(csp.directives)
+        .map(([key, values]) => `${key} ${values.join(' ')}`)
+        .join('; ');
+    res.setHeader('Content-Security-Policy', headerValue);
+}
+function applyCors(req, res, cors) {
+    if (!cors)
+        return false;
+    const originHeader = req.getHeader('origin');
+    const origin = typeof originHeader === 'string' ? originHeader : undefined;
+    let allowedOrigin = cors.origin;
+    if (Array.isArray(cors.origin)) {
+        if (origin === undefined || !cors.origin.includes(origin)) {
+            allowedOrigin = undefined;
+        }
+        else {
+            allowedOrigin = origin;
+        }
+    }
+    if (allowedOrigin !== null && allowedOrigin !== undefined) {
+        res.setHeader('Access-Control-Allow-Origin', allowedOrigin ?? '*');
+    }
+    if (cors.methods) {
+        res.setHeader('Access-Control-Allow-Methods', cors.methods.join(', '));
+    }
+    if (cors.allowedHeaders) {
+        res.setHeader('Access-Control-Allow-Headers', cors.allowedHeaders.join(', '));
+    }
+    if (cors.credentials !== undefined) {
+        res.setHeader('Access-Control-Allow-Credentials', 'true');
+    }
+    if (cors.maxAge !== undefined) {
+        res.setHeader('Access-Control-Max-Age', cors.maxAge.toString());
+    }
+    // Handle Preflight
+    if (req.getMethod() === 'OPTIONS') {
+        res.setStatus(204);
+        return true;
+    }
+    return false;
+}
+export const SecurityMiddleware = Object.freeze({
+    /**
+     * Create security middleware with options
+     */
+    create(options = {}) {
+        const config = { ...DEFAULT_OPTIONS, ...options };
+        return async (req, res, next) => {
+            applyHsts(res, config.hsts);
+            applyFrameguard(res, config.frameguard);
+            applyNoSniff(res);
+            applyReferrerPolicy(res);
+            applyCsp(res, config.csp);
+            const preflightHandled = applyCors(req, res, config.cors);
+            if (preflightHandled)
+                return;
+            await next();
+        };
+    },
+});

package/src/middleware/SessionMiddleware.d.ts

@@ -0,0 +1,8 @@
+import type { Middleware } from './MiddlewareStack';
+import { type SessionManagerOptions } from '../session/SessionManager';
+export type SessionOptions = SessionManagerOptions;
+export declare const SessionMiddleware: Readonly<{
+    create(options?: SessionOptions): Middleware;
+}>;
+export default SessionMiddleware;
+//# sourceMappingURL=SessionMiddleware.d.ts.map

package/src/middleware/SessionMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionMiddleware.d.ts","sourceRoot":"","sources":["../../../src/middleware/SessionMiddleware.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAkB,KAAK,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAErF,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC;AAEnD,eAAO,MAAM,iBAAiB;qBACZ,cAAc,GAAQ,UAAU;EAehD,CAAC;AAEH,eAAe,iBAAiB,CAAC"}

package/src/middleware/SessionMiddleware.js

@@ -0,0 +1,15 @@
+import { SessionManager } from '../session/SessionManager.js';
+export const SessionMiddleware = Object.freeze({
+    create(options = {}) {
+        const manager = SessionManager.create(options);
+        return async (req, res, next) => {
+            const sessionId = await manager.ensureSessionId(req, res);
+            // Keep both request state + context aligned.
+            req.sessionId = sessionId;
+            req.context['sessionId'] = sessionId;
+            res.locals['sessionId'] = sessionId;
+            await next();
+        };
+    },
+});
+export default SessionMiddleware;

package/src/middleware/ValidationMiddleware.d.ts

@@ -0,0 +1,30 @@
+import { type MiddlewareFailureResponder } from './MiddlewareFailureResponder';
+import type { Middleware } from './MiddlewareStack';
+import type { ISchema, TypedSchema } from '../validation/Validator';
+type ValidationMiddlewareOptions = Readonly<{
+    onFailure?: MiddlewareFailureResponder;
+    middlewareKey?: string;
+}>;
+type FieldSanitizers = Readonly<Record<string, (value: unknown) => unknown>>;
+export declare const ValidationMiddleware: Readonly<{
+    create(schema: ISchema, options?: ValidationMiddlewareOptions): Middleware;
+    createBody<TSchema extends TypedSchema<unknown>>(schema: TSchema, options?: ValidationMiddlewareOptions): Middleware;
+    createBodyWithSanitization<TSchema extends TypedSchema<unknown>>(schema: TSchema, sanitizers?: FieldSanitizers, options?: ValidationMiddlewareOptions): Middleware;
+    createQuery<TSchema extends TypedSchema<unknown>>(schema: TSchema, options?: ValidationMiddlewareOptions): Middleware;
+    createParams<TSchema extends TypedSchema<unknown>>(schema: TSchema, options?: ValidationMiddlewareOptions): Middleware;
+    /**
+     * Create body validation middleware with bulletproof sanitization error handling.
+     * Automatically converts SanitizerError to 422 validation response.
+     * Recommended for authentication, user management, and financial operations.
+     *
+     * Use this when controllers apply Sanitizer methods with bulletproof=true (default).
+     * The middleware will catch SanitizerError and convert to proper validation error response.
+     *
+     * @param schema - Validation schema
+     * @param sanitizers - Optional field sanitizers to apply before validation
+     * @returns Middleware with bulletproof error handling
+     */
+    createBodyWithBulletproofSanitization<TSchema extends TypedSchema<unknown>>(schema: TSchema, sanitizers?: FieldSanitizers, options?: ValidationMiddlewareOptions): Middleware;
+}>;
+export {};
+//# sourceMappingURL=ValidationMiddleware.d.ts.map

package/src/middleware/ValidationMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValidationMiddleware.d.ts","sourceRoot":"","sources":["../../../src/middleware/ValidationMiddleware.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAe,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAI/E,KAAK,2BAA2B,GAAG,QAAQ,CAAC;IAC1C,SAAS,CAAC,EAAE,0BAA0B,CAAC;IACvC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC,CAAC;AAQH,KAAK,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC;AA+H7E,eAAO,MAAM,oBAAoB;mBAChB,OAAO,YAAW,2BAA2B,GAAQ,UAAU;eAwBnE,OAAO,SAAS,WAAW,CAAC,OAAO,CAAC,UACrC,OAAO,YACN,2BAA2B,GACnC,UAAU;+BA0Bc,OAAO,SAAS,WAAW,CAAC,OAAO,CAAC,UACrD,OAAO,eACF,eAAe,YACnB,2BAA2B,GACnC,UAAU;gBA6BD,OAAO,SAAS,WAAW,CAAC,OAAO,CAAC,UACtC,OAAO,YACN,2BAA2B,GACnC,UAAU;iBAeA,OAAO,SAAS,WAAW,CAAC,OAAO,CAAC,UACvC,OAAO,YACN,2BAA2B,GACnC,UAAU;IAeb;;;;;;;;;;;OAWG;0CACmC,OAAO,SAAS,WAAW,CAAC,OAAO,CAAC,UAChE,OAAO,eACF,eAAe,YACnB,2BAA2B,GACnC,UAAU;EA4Cb,CAAC"}