@zintrust/core 0.1.19 → 0.1.21

package/src/middleware/ValidationMiddleware.d.ts

@@ -0,0 +1,25 @@
+import type { Middleware } from './MiddlewareStack';
+import type { ISchema, TypedSchema } from '../validation/Validator';
+type FieldSanitizers = Readonly<Record<string, (value: unknown) => unknown>>;
+export declare const ValidationMiddleware: Readonly<{
+    create(schema: ISchema): Middleware;
+    createBody<TSchema extends TypedSchema<unknown>>(schema: TSchema): Middleware;
+    createBodyWithSanitization<TSchema extends TypedSchema<unknown>>(schema: TSchema, sanitizers?: FieldSanitizers): Middleware;
+    createQuery<TSchema extends TypedSchema<unknown>>(schema: TSchema): Middleware;
+    createParams<TSchema extends TypedSchema<unknown>>(schema: TSchema): 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): 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,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAe,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAW/E,KAAK,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC;AAqG7E,eAAO,MAAM,oBAAoB;mBAChB,OAAO,GAAG,UAAU;eAwBxB,OAAO,SAAS,WAAW,CAAC,OAAO,CAAC,UAAU,OAAO,GAAG,UAAU;+BA0BlD,OAAO,SAAS,WAAW,CAAC,OAAO,CAAC,UACrD,OAAO,eACF,eAAe,GAC3B,UAAU;gBA6BD,OAAO,SAAS,WAAW,CAAC,OAAO,CAAC,UAAU,OAAO,GAAG,UAAU;iBAejE,OAAO,SAAS,WAAW,CAAC,OAAO,CAAC,UAAU,OAAO,GAAG,UAAU;IAe/E;;;;;;;;;;;OAWG;0CACmC,OAAO,SAAS,WAAW,CAAC,OAAO,CAAC,UAChE,OAAO,eACF,eAAe,GAC3B,UAAU;EAqCb,CAAC"}

package/src/middleware/ValidationMiddleware.js

@@ -0,0 +1,251 @@
+import { Env } from '../config/env.js';
+import { Logger } from '../config/logger.js';
+import { Xss } from '../security/Xss.js';
+import { Validator } from '../validation/Validator.js';
+const toRecord = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return {};
+    if (Array.isArray(value))
+        return {};
+    return value;
+};
+const applyFieldSanitizers = (input, sanitizers) => {
+    if (sanitizers === undefined)
+        return input;
+    if (typeof input !== 'object' || input === null)
+        return input;
+    if (Array.isArray(input))
+        return input;
+    const record = input;
+    let changed = false;
+    const out = { ...record };
+    for (const [field, sanitizer] of Object.entries(sanitizers)) {
+        if (Object.prototype.hasOwnProperty.call(out, field) === false)
+            continue;
+        const before = out[field];
+        const after = sanitizer(before);
+        if (after !== before) {
+            out[field] = after;
+            changed = true;
+        }
+    }
+    return changed ? out : record;
+};
+const shouldLogValidationBody = () => {
+    if (Env.NODE_ENV === 'production')
+        return false;
+    return Env.getBool('ZIN_DEBUG_VALIDATION_BODY', false);
+};
+const safeCall = (fn) => {
+    try {
+        return fn?.();
+    }
+    catch {
+        return undefined;
+    }
+};
+const getContentType = (req) => {
+    const fromGetHeader = safeCall(() => req.getHeader?.('content-type'));
+    if (fromGetHeader !== undefined)
+        return fromGetHeader;
+    const fromHeaders = safeCall(() => req.getHeaders?.()['content-type']);
+    if (fromHeaders !== undefined)
+        return fromHeaders;
+    return req.headers?.['content-type'];
+};
+const logValidationBodyInput = (req, stage) => {
+    if (!shouldLogValidationBody())
+        return;
+    Logger.debug('[Validation] body input:', {
+        stage,
+        method: safeCall(() => req.getMethod()),
+        path: safeCall(() => req.getPath()),
+        contentType: getContentType(req),
+        rawBody: safeCall(() => (typeof req.getBody === 'function' ? req.getBody() : undefined)),
+        bodyRecord: req.body,
+    });
+};
+const toBodyRecord = (value) => toRecord(value);
+const getBodyForValidation = (req) => {
+    const bodyRecord = toBodyRecord(req.body);
+    if (Object.keys(bodyRecord).length > 0)
+        return bodyRecord;
+    const raw = safeCall(() => req.getBody?.());
+    return toBodyRecord(raw);
+};
+const handleValidationError = (res, error) => {
+    // Temporary: log validation error details to help debugging failing requests.
+    // Remove this detailed debug logging once the issue is investigated.
+    Logger.warn('Validation failed');
+    try {
+        const err = error;
+        if (typeof err?.toObject === 'function') {
+            // Prefer structured debug output when available
+            try {
+                Logger.debug('[Validation] errors:', err.toObject());
+            }
+            catch {
+                // best-effort: fall back to direct log
+                Logger.debug('[Validation] errors (toObject threw):', err);
+            }
+            res.setStatus(422).json({ errors: err.toObject() });
+            return;
+        }
+        // Fallback: log raw error
+        Logger.debug('[Validation] error:', err);
+        res.setStatus(400).json({ error: 'Invalid request body' });
+    }
+    catch (error_) {
+        // Ensure we don't throw while handling validation errors
+        Logger.debug('[Validation] failed to log error details:', error_);
+        res.setStatus(400).json({ error: 'Invalid request body' });
+    }
+};
+export const ValidationMiddleware = Object.freeze({
+    create(schema) {
+        return async (req, res, next) => {
+            const method = req.getMethod();
+            if (method === 'GET' || method === 'DELETE') {
+                await next();
+                return;
+            }
+            try {
+                logValidationBodyInput(req, 'create:before-validate');
+                const bodyForValidation = getBodyForValidation(req);
+                if (Object.keys(bodyForValidation).length > 0 && Object.keys(req.body ?? {}).length === 0) {
+                    safeCall(() => req.setBody?.(bodyForValidation));
+                }
+                Validator.validate(bodyForValidation, schema);
+                req.validated.body = bodyForValidation;
+                await next();
+            }
+            catch (error) {
+                handleValidationError(res, error);
+            }
+        };
+    },
+    createBody(schema) {
+        return async (req, res, next) => {
+            const method = req.getMethod();
+            if (method === 'GET' || method === 'DELETE') {
+                await next();
+                return;
+            }
+            try {
+                logValidationBodyInput(req, 'createBody:before-validate');
+                const bodyForValidation = getBodyForValidation(req);
+                if (Object.keys(bodyForValidation).length > 0 && Object.keys(req.body ?? {}).length === 0) {
+                    safeCall(() => req.setBody?.(bodyForValidation));
+                }
+                Validator.validate(bodyForValidation, schema);
+                req.validated.body = bodyForValidation;
+                await next();
+            }
+            catch (error) {
+                handleValidationError(res, error);
+            }
+        };
+    },
+    createBodyWithSanitization(schema, sanitizers) {
+        return async (req, res, next) => {
+            const method = req.getMethod();
+            if (method === 'GET' || method === 'DELETE') {
+                await next();
+                return;
+            }
+            try {
+                const rawBody = req.getBody();
+                const xssSanitized = Xss.sanitize(rawBody ?? {});
+                const fieldSanitized = applyFieldSanitizers(xssSanitized, sanitizers);
+                const bodyForValidation = toBodyRecord(fieldSanitized);
+                safeCall(() => req.setBody?.(bodyForValidation));
+                logValidationBodyInput(req, 'createBodyWithSanitization:before-validate');
+                Validator.validate(bodyForValidation, schema);
+                req.validated.body = bodyForValidation;
+                await next();
+            }
+            catch (error) {
+                handleValidationError(res, error);
+            }
+        };
+    },
+    createQuery(schema) {
+        return async (req, res, next) => {
+            try {
+                const query = toRecord(req.getQuery());
+                Validator.validate(query, schema);
+                req.validated.query = query;
+                await next();
+            }
+            catch (error) {
+                handleValidationError(res, error);
+            }
+        };
+    },
+    createParams(schema) {
+        return async (req, res, next) => {
+            try {
+                const params = toRecord(req.getParams());
+                Validator.validate(params, schema);
+                req.validated.params = params;
+                await next();
+            }
+            catch (error) {
+                handleValidationError(res, error);
+            }
+        };
+    },
+    /**
+     * 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(schema, sanitizers) {
+        return async (req, res, next) => {
+            const method = req.getMethod();
+            if (method === 'GET' || method === 'DELETE') {
+                await next();
+                return;
+            }
+            try {
+                const rawBody = req.getBody();
+                const xssSanitized = Xss.sanitize(rawBody ?? {});
+                const fieldSanitized = applyFieldSanitizers(xssSanitized, sanitizers);
+                const bodyForValidation = toBodyRecord(fieldSanitized);
+                safeCall(() => req.setBody?.(bodyForValidation));
+                logValidationBodyInput(req, 'createBodyWithBulletproofSanitization:before-validate');
+                Validator.validate(bodyForValidation, schema);
+                req.validated.body = bodyForValidation;
+                await next();
+            }
+            catch (error) {
+                // Handle SanitizerError by converting to validation error format
+                if (isSanitizerError(error)) {
+                    res.setStatus(422).json({
+                        errors: {
+                            sanitization: [error.message],
+                        },
+                    });
+                    return;
+                }
+                handleValidationError(res, error);
+            }
+        };
+    },
+});
+/**
+ * Check if error is a SanitizerError
+ */
+function isSanitizerError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'name' in error &&
+        error.name === 'SanitizerError');
+}

package/src/migrations/MigrationDiscovery.d.ts

@@ -0,0 +1,5 @@
+export declare const MigrationDiscovery: Readonly<{
+    resolveDir(projectRoot: string, dir: string): string;
+    listMigrationFiles(dir: string, extension: string): string[];
+}>;
+//# sourceMappingURL=MigrationDiscovery.d.ts.map

package/src/migrations/MigrationDiscovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MigrationDiscovery.d.ts","sourceRoot":"","sources":["../../../src/migrations/MigrationDiscovery.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,kBAAkB;4BACL,MAAM,OAAO,MAAM,GAAG,MAAM;4BAI5B,MAAM,aAAa,MAAM,GAAG,MAAM,EAAE;EAQ5D,CAAC"}

package/src/migrations/MigrationDiscovery.js

@@ -0,0 +1,16 @@
+import fs from '../node-singletons/fs.js';
+import * as path from '../node-singletons/path.js';
+export const MigrationDiscovery = Object.freeze({
+    resolveDir(projectRoot, dir) {
+        return path.resolve(projectRoot, dir);
+    },
+    listMigrationFiles(dir, extension) {
+        if (!fs.existsSync(dir))
+            return [];
+        const files = fs.readdirSync(dir);
+        return files
+            .filter((f) => f.endsWith(extension) && !f.startsWith('index.'))
+            .sort((a, b) => a.localeCompare(b))
+            .map((f) => path.join(dir, f));
+    },
+});

package/src/migrations/MigrationLoader.d.ts

@@ -0,0 +1,5 @@
+import type { LoadedMigration } from '../migrations/types';
+export declare const MigrationLoader: Readonly<{
+    load(filePath: string): Promise<LoadedMigration>;
+}>;
+//# sourceMappingURL=MigrationLoader.d.ts.map

package/src/migrations/MigrationLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MigrationLoader.d.ts","sourceRoot":"","sources":["../../../src/migrations/MigrationLoader.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAqC,MAAM,oBAAoB,CAAC;AAwB7F,eAAO,MAAM,eAAe;mBACL,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;EA4BtD,CAAC"}

package/src/migrations/MigrationLoader.js

@@ -0,0 +1,43 @@
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import * as path from '../node-singletons/path.js';
+import { pathToFileURL } from 'node:url';
+function isFunction(value) {
+    return typeof value === 'function';
+}
+function normalizeHandler(fn, label) {
+    if (!isFunction(fn)) {
+        throw ErrorFactory.createValidationError(`Invalid migration export: expected function for ${label}`);
+    }
+    return async (db) => {
+        // Support both (db) => Promise<void> and () => Promise<void>.
+        if (fn.length <= 0) {
+            await Promise.resolve(fn());
+            return;
+        }
+        await Promise.resolve(fn(db));
+    };
+}
+export const MigrationLoader = Object.freeze({
+    async load(filePath) {
+        const url = pathToFileURL(filePath).href;
+        const raw = (await import(url));
+        // Some tooling/transpilation paths wrap exports under `default`.
+        // Prefer direct named exports, but fall back to default export if present.
+        const mod = (raw ?? {});
+        const fallback = (mod.default ?? {});
+        const up = mod.migration?.up ?? mod.up ?? fallback.migration?.up ?? fallback.up;
+        const down = mod.migration?.down ?? mod.down ?? fallback.migration?.down ?? fallback.down;
+        if (up === undefined) {
+            throw ErrorFactory.createValidationError(`Migration '${filePath}' is missing an 'up' export`);
+        }
+        if (down === undefined) {
+            throw ErrorFactory.createValidationError(`Migration '${filePath}' is missing a 'down' export`);
+        }
+        return {
+            name: path.basename(filePath, path.extname(filePath)),
+            filePath,
+            up: normalizeHandler(up, 'up'),
+            down: normalizeHandler(down, 'down'),
+        };
+    },
+});

package/src/migrations/MigrationLock.d.ts

@@ -0,0 +1,4 @@
+export declare const MigrationLock: Readonly<{
+    acquire(lockFile: string): () => void;
+}>;
+//# sourceMappingURL=MigrationLock.d.ts.map

package/src/migrations/MigrationLock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MigrationLock.d.ts","sourceRoot":"","sources":["../../../src/migrations/MigrationLock.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,aAAa;sBACN,MAAM,GAAG,MAAM,IAAI;EAgCrC,CAAC"}

package/src/migrations/MigrationLock.js

@@ -0,0 +1,33 @@
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import fs from '../node-singletons/fs.js';
+import * as path from '../node-singletons/path.js';
+function nowIso() {
+    return new Date().toISOString();
+}
+export const MigrationLock = Object.freeze({
+    acquire(lockFile) {
+        fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+        try {
+            const fd = fs.openSync(lockFile, 'wx');
+            fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, createdAt: nowIso() }, null, 2), 'utf8');
+            fs.closeSync(fd);
+            return () => {
+                try {
+                    fs.unlinkSync(lockFile);
+                }
+                catch {
+                    // ignore
+                }
+            };
+        }
+        catch (error) {
+            if (typeof error === 'object' && error !== null && 'code' in error) {
+                const code = error.code;
+                if (code === 'EEXIST') {
+                    throw ErrorFactory.createCliError(`Migration lock already exists at ${lockFile}. Another migrate may be running.`);
+                }
+            }
+            throw ErrorFactory.createTryCatchError('Failed to acquire migration lock', { cause: error });
+        }
+    },
+});

package/src/migrations/Migrator.d.ts

@@ -0,0 +1,23 @@
+export type { LoadedMigration, MigrationHandler, MigrationModule, MigrationRecord, MigrationRecordStatus, MigrationScope, MigratorOptions, MigratorStatusRow, } from '../migrations/types';
+export declare const Migrator: Readonly<{
+    create: (options: import("../migrations/types").MigratorOptions) => {
+        status(): Promise<import("../migrations/types").MigratorStatusRow[]>;
+        migrate(): Promise<{
+            applied: number;
+            pending: number;
+            appliedNames: string[];
+        }>;
+        rollbackLastBatch(steps: number): Promise<{
+            rolledBack: number;
+        }>;
+        resetAll(): Promise<{
+            rolledBack: number;
+        }>;
+        fresh(): Promise<{
+            applied: number;
+            pending: number;
+            appliedNames: string[];
+        }>;
+    };
+}>;
+//# sourceMappingURL=Migrator.d.ts.map

package/src/migrations/Migrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Migrator.d.ts","sourceRoot":"","sources":["../../../src/migrations/Migrator.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;EAEnB,CAAC"}

package/src/migrations/Migrator.js

@@ -0,0 +1,4 @@
+import { MigratorFactory } from '../migrations/MigratorFactory.js';
+export const Migrator = Object.freeze({
+    create: MigratorFactory.create,
+});

package/src/migrations/MigratorFactory.d.ts

@@ -0,0 +1,25 @@
+import type { MigratorOptions, MigratorStatusRow } from '../migrations/types';
+type MigratorApi = {
+    status(): Promise<MigratorStatusRow[]>;
+    migrate(): Promise<{
+        applied: number;
+        pending: number;
+        appliedNames: string[];
+    }>;
+    rollbackLastBatch(steps: number): Promise<{
+        rolledBack: number;
+    }>;
+    resetAll(): Promise<{
+        rolledBack: number;
+    }>;
+    fresh(): Promise<{
+        applied: number;
+        pending: number;
+        appliedNames: string[];
+    }>;
+};
+export declare const MigratorFactory: Readonly<{
+    create(options: MigratorOptions): MigratorApi;
+}>;
+export {};
+//# sourceMappingURL=MigratorFactory.d.ts.map

package/src/migrations/MigratorFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MigratorFactory.d.ts","sourceRoot":"","sources":["../../../src/migrations/MigratorFactory.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAIV,eAAe,EACf,iBAAiB,EAClB,MAAM,oBAAoB,CAAC;AAU5B,KAAK,WAAW,GAAG;IACjB,MAAM,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACvC,OAAO,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACjF,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClE,QAAQ,IAAI,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5C,KAAK,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CAChF,CAAC;AA8aF,eAAO,MAAM,eAAe;oBACV,eAAe,GAAG,WAAW;EAW7C,CAAC"}