@zintrust/core 0.1.0

package/src/scripts/TemplateSync.js

@@ -0,0 +1,234 @@
+/**
+ * Template Sync Script
+ * Synchronizes base framework files to .tpl templates when checksums change
+ * Runs during npm run build
+ */
+import { TemplateRegistry } from '../templates/TemplateRegistry.js';
+import { Logger } from '../config/logger';
+import { ErrorFactory } from '../exceptions/ZintrustError';
+import * as crypto from '../node-singletons/crypto';
+import fs from '../node-singletons/fs';
+import { fileURLToPath } from '../node-singletons/url';
+import * as path from 'node:path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT_DIR = path.resolve(__dirname, '../../');
+/**
+ * Calculate SHA1 hash of file content
+ */
+function hashFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        return crypto.createHash('sha1').update(content).digest('hex'); // NOSONAR;
+    }
+    catch (error) {
+        Logger.error(`Error reading file ${filePath}`, error);
+        throw ErrorFactory.createTryCatchError(`Failed to read file: ${filePath}`, error);
+    }
+}
+/**
+ * Extract content between TEMPLATE_START and TEMPLATE_END markers
+ */
+function extractTemplateContent(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const startMarker = '// TEMPLATE_START';
+        const endMarker = '// TEMPLATE_END';
+        const startIdx = content.indexOf(startMarker);
+        const endIdx = content.indexOf(endMarker);
+        if (startIdx === -1 || endIdx === -1) {
+            Logger.warn(`Template markers not found in ${filePath}`);
+            return content;
+        }
+        // Extract from after START marker to before END marker (inclusive of END comment)
+        return content.substring(startIdx, endIdx + endMarker.length);
+    }
+    catch (error) {
+        Logger.error(`Error extracting template from ${filePath}`, error);
+        throw ErrorFactory.createTryCatchError(`Failed to extract template from: ${filePath}`, error);
+    }
+}
+/**
+ * Ensure directory exists, create if needed
+ */
+function ensureDir(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+const shouldSkipEntry = (name) => {
+    return (name === 'node_modules' ||
+        name === 'dist' ||
+        name === 'coverage' ||
+        name === '.git' ||
+        name === '.DS_Store');
+};
+const listFilesRecursive = (baseDirAbs) => {
+    const out = [];
+    const walk = (dirAbs) => {
+        const entries = fs.readdirSync(dirAbs, { withFileTypes: true });
+        for (const entry of entries) {
+            if (shouldSkipEntry(entry.name))
+                continue;
+            const abs = path.join(dirAbs, entry.name);
+            if (entry.isDirectory()) {
+                walk(abs);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            out.push({ absPath: abs, relPath: path.relative(baseDirAbs, abs) });
+        }
+    };
+    walk(baseDirAbs);
+    return out;
+};
+const syncProjectTemplateDir = (params) => {
+    const baseDirAbs = path.join(ROOT_DIR, params.baseDirRel);
+    const templateDirAbs = path.join(ROOT_DIR, params.templateDirRel);
+    if (!fs.existsSync(baseDirAbs)) {
+        Logger.warn(`⚠️  Base directory not found: ${params.baseDirRel}`);
+        return { updated: 0, skipped: 0, total: 0 };
+    }
+    const files = listFilesRecursive(baseDirAbs);
+    let updated = 0;
+    let skipped = 0;
+    for (const file of files) {
+        const baseKey = `${params.baseDirRel}/${file.relPath}`;
+        const currentHash = hashFile(file.absPath);
+        const storedHash = params.checksums[baseKey];
+        const outRel = `${file.relPath}.tpl`;
+        const outAbs = path.join(templateDirAbs, outRel);
+        if (currentHash === storedHash && fs.existsSync(outAbs)) {
+            skipped++;
+            continue;
+        }
+        const raw = fs.readFileSync(file.absPath, 'utf8');
+        const transformed = typeof params.transformContent === 'function'
+            ? params.transformContent(file.relPath, raw)
+            : raw;
+        ensureDir(path.dirname(outAbs));
+        fs.writeFileSync(outAbs, transformed, 'utf8');
+        params.checksums[baseKey] = currentHash;
+        updated++;
+    }
+    if (files.length > 0) {
+        Logger.info(`✓ ${params.description} (updated: ${updated}, skipped: ${skipped}, total: ${files.length})`);
+    }
+    return { updated, skipped, total: files.length };
+};
+/**
+ * Load existing checksums from JSON file
+ */
+function loadChecksums() {
+    const checksumPath = path.join(ROOT_DIR, '.template-checksums.json');
+    if (fs.existsSync(checksumPath)) {
+        try {
+            const content = fs.readFileSync(checksumPath, 'utf8');
+            return JSON.parse(content);
+        }
+        catch (error) {
+            Logger.error('Could not parse .template-checksums.json, starting fresh', error);
+            return {};
+        }
+    }
+    return {};
+}
+/**
+ * Save checksums to JSON file
+ */
+function saveChecksums(checksums) {
+    const checksumPath = path.join(ROOT_DIR, '.template-checksums.json');
+    fs.writeFileSync(checksumPath, JSON.stringify(checksums, null, 2));
+}
+/**
+ * Main sync function
+ */
+// eslint-disable-next-line @typescript-eslint/require-await
+async function syncTemplates() {
+    Logger.info('🔄 Syncing templates...\n');
+    const checksums = loadChecksums();
+    const mappings = TemplateRegistry.getMappings();
+    let updated = 0;
+    let skipped = 0;
+    for (const mapping of mappings) {
+        const basePath = path.join(ROOT_DIR, mapping.basePath);
+        const templatePath = path.join(ROOT_DIR, mapping.templatePath);
+        // Check if base file exists
+        if (!fs.existsSync(basePath)) {
+            Logger.warn(`⚠️  Base file not found: ${mapping.basePath}`);
+            continue;
+        }
+        // Calculate current hash
+        const currentHash = hashFile(basePath);
+        const storedHash = checksums[mapping.basePath];
+        // Check if update is needed
+        if (currentHash === storedHash && fs.existsSync(templatePath)) {
+            Logger.info(`✓ ${mapping.description} (in sync)`);
+            skipped++;
+            continue;
+        }
+        // Extract and write template
+        try {
+            const templateContent = extractTemplateContent(basePath);
+            ensureDir(path.dirname(templatePath));
+            fs.writeFileSync(templatePath, templateContent, 'utf8');
+            // Update checksum
+            checksums[mapping.basePath] = currentHash;
+            Logger.info(`✓ Updated: ${mapping.description}`);
+            updated++;
+        }
+        catch (error) {
+            Logger.error(`❌ Failed to sync ${mapping.basePath}:`, error);
+            process.exit(1);
+        }
+    }
+    // Sync starter project templates (basic) from base framework folders.
+    // Spec: app/* -> app/*, src/config/* -> config/*, src/database/* -> database/*, routes/* -> routes/*
+    // plus .env (generated from .env.example with sensitive values blanked).
+    Logger.info('');
+    Logger.info('🔄 Syncing starter project templates (basic)...');
+    const projectRoot = 'src/templates/project/basic';
+    const s1 = syncProjectTemplateDir({
+        checksums,
+        baseDirRel: 'app',
+        templateDirRel: `${projectRoot}/app`,
+        description: 'Starter project app/*',
+    });
+    const s2 = syncProjectTemplateDir({
+        checksums,
+        baseDirRel: 'src/config',
+        templateDirRel: `${projectRoot}/config`,
+        description: 'Starter project config/* (from src/config/*)',
+    });
+    const s3 = syncProjectTemplateDir({
+        checksums,
+        baseDirRel: 'src/database',
+        templateDirRel: `${projectRoot}/database`,
+        description: 'Starter project database/* (from src/database/*)',
+    });
+    const s4 = syncProjectTemplateDir({
+        checksums,
+        baseDirRel: 'routes',
+        templateDirRel: `${projectRoot}/routes`,
+        description: 'Starter project routes/*',
+    });
+    const s5 = { updated: 0, skipped: 0 };
+    updated += s1.updated + s2.updated + s3.updated + s4.updated + s5.updated;
+    skipped += s1.skipped + s2.skipped + s3.skipped + s4.skipped + s5.skipped;
+    // Save updated checksums
+    saveChecksums(checksums);
+    // Summary
+    Logger.info(`\n📦 Template sync complete`);
+    Logger.info(`   Updated: ${updated}`);
+    Logger.info(`   Skipped: ${skipped}`);
+    Logger.info(`   Total: ${mappings.length + s1.total + s2.total + s3.total + s4.total}\n`);
+}
+// Run sync
+try {
+    await syncTemplates();
+}
+catch (error) {
+    Logger.error('Template sync failed', error);
+    process.exit(1);
+}

package/src/security/CsrfTokenManager.d.ts

@@ -0,0 +1,28 @@
+/**
+ * CSRF Token Manager
+ * Generate, validate, and bind CSRF tokens to sessions
+ */
+export interface CsrfTokenData {
+    token: string;
+    sessionId: string;
+    createdAt: Date;
+    expiresAt: Date;
+}
+export interface ICsrfTokenManager {
+    generateToken(sessionId: string): string;
+    validateToken(sessionId: string, token: string): boolean;
+    invalidateToken(sessionId: string): void;
+    getTokenData(sessionId: string): CsrfTokenData | null;
+    refreshToken(sessionId: string): string | null;
+    cleanup(): number;
+    clear(): void;
+    getTokenCount(): number;
+}
+export interface CsrfTokenManagerType {
+    create(): ICsrfTokenManager;
+}
+/**
+ * CsrfTokenManager namespace - sealed for immutability
+ */
+export declare const CsrfTokenManager: CsrfTokenManagerType;
+//# sourceMappingURL=CsrfTokenManager.d.ts.map

package/src/security/CsrfTokenManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CsrfTokenManager.d.ts","sourceRoot":"","sources":["../../../src/security/CsrfTokenManager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACzC,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACzD,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAAC;IACtD,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC/C,OAAO,IAAI,MAAM,CAAC;IAClB,KAAK,IAAI,IAAI,CAAC;IACd,aAAa,IAAI,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,IAAI,iBAAiB,CAAC;CAC7B;AAoED;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,oBAE7B,CAAC"}

package/src/security/CsrfTokenManager.js

@@ -0,0 +1,78 @@
+/**
+ * CSRF Token Manager
+ * Generate, validate, and bind CSRF tokens to sessions
+ */
+import { Env } from '../config/env';
+import { randomBytes } from 'node:crypto';
+/**
+ * Create a new CSRF token manager instance
+ */
+const create = () => {
+    const tokens = new Map();
+    const tokenLength = Env.TOKEN_LENGTH; // 256 bits
+    const tokenTtl = Env.TOKEN_TTL; // 1 hour in milliseconds
+    return {
+        generateToken(sessionId) {
+            tokens.delete(sessionId);
+            const token = randomBytes(tokenLength).toString('hex');
+            const now = new Date();
+            const expiresAt = new Date(now.getTime() + tokenTtl);
+            const tokenData = { token, sessionId, createdAt: now, expiresAt };
+            tokens.set(sessionId, tokenData);
+            return token;
+        },
+        validateToken(sessionId, token) {
+            const tokenData = tokens.get(sessionId);
+            if (!tokenData)
+                return false;
+            const isValid = tokenData.token === token;
+            const isExpired = new Date() > tokenData.expiresAt;
+            if (isExpired) {
+                tokens.delete(sessionId);
+                return false;
+            }
+            return isValid;
+        },
+        invalidateToken(sessionId) {
+            tokens.delete(sessionId);
+        },
+        getTokenData(sessionId) {
+            return tokens.get(sessionId) ?? null;
+        },
+        refreshToken(sessionId) {
+            const tokenData = tokens.get(sessionId);
+            if (!tokenData)
+                return null;
+            const isExpired = new Date() > tokenData.expiresAt;
+            if (isExpired) {
+                tokens.delete(sessionId);
+                return null;
+            }
+            tokenData.expiresAt = new Date(Date.now() + tokenTtl);
+            return tokenData.token;
+        },
+        cleanup() {
+            let removed = 0;
+            const now = new Date();
+            for (const [sessionId, tokenData] of tokens.entries()) {
+                if (now > tokenData.expiresAt) {
+                    tokens.delete(sessionId);
+                    removed++;
+                }
+            }
+            return removed;
+        },
+        clear() {
+            tokens.clear();
+        },
+        getTokenCount() {
+            return tokens.size;
+        },
+    };
+};
+/**
+ * CsrfTokenManager namespace - sealed for immutability
+ */
+export const CsrfTokenManager = Object.freeze({
+    create,
+});

package/src/security/Encryptor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Encryptor
+ * Password hashing with dual support: PBKDF2 (default) and optional bcrypt
+ */
+/**
+ * Hash algorithm selector
+ */
+export type HashAlgorithm = 'pbkdf2' | 'bcrypt';
+export interface IEncryptor {
+    hash(password: string): Promise<string>;
+    verify(password: string, hash: string): Promise<boolean>;
+    getAlgorithm(): HashAlgorithm;
+}
+export declare const Encryptor: IEncryptor;
+//# sourceMappingURL=Encryptor.d.ts.map

package/src/security/Encryptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Encryptor.d.ts","sourceRoot":"","sources":["../../../src/security/Encryptor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,CAAC;AA2HhD,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,YAAY,IAAI,aAAa,CAAC;CAC/B;AAuCD,eAAO,MAAM,SAAS,EAAE,UAItB,CAAC"}

package/src/security/Encryptor.js

@@ -0,0 +1,142 @@
+/**
+ * Encryptor
+ * Password hashing with dual support: PBKDF2 (default) and optional bcrypt
+ */
+import { Logger } from '../config/logger';
+import { ErrorFactory } from '../exceptions/ZintrustError';
+import { pbkdf2Sync, randomBytes } from 'node:crypto';
+function isBcryptModule(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    return typeof record['hash'] === 'function' && typeof record['compare'] === 'function';
+}
+let algorithm = 'pbkdf2';
+let bcrypt;
+let loadingPromise;
+async function loadBcrypt() {
+    try {
+        const imported = await import('bcrypt');
+        const module = imported;
+        const candidate = module.default ?? module;
+        if (!isBcryptModule(candidate)) {
+            throw ErrorFactory.createConfigError('Invalid bcrypt module shape');
+        }
+        bcrypt = candidate;
+        algorithm = 'bcrypt';
+    }
+    catch (error) {
+        Logger.error('bcrypt not installed, falling back to PBKDF2', error);
+        ErrorFactory.createSecurityError('bcrypt not installed, falling back to PBKDF2', error);
+        // bcrypt not installed, will use PBKDF2
+        algorithm = 'pbkdf2';
+    }
+}
+async function ensureLoaded() {
+    if (bcrypt !== undefined)
+        return;
+    if (loadingPromise !== undefined)
+        return loadingPromise;
+    loadingPromise = loadBcrypt();
+    return loadingPromise;
+}
+/**
+ * Timing-safe string comparison
+ */
+function timingSafeEquals(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= (a.codePointAt(i) ?? 0) ^ (b.codePointAt(i) ?? 0);
+    }
+    return result === 0;
+}
+/**
+ * Hash with PBKDF2 (default)
+ */
+function hashPbkdf2(password) {
+    const iterations = 600000; // OWASP recommended for SHA-256
+    const salt = randomBytes(32).toString('hex');
+    const keyLength = 64;
+    const digest = 'sha256';
+    const hash = pbkdf2Sync(password, salt, iterations, keyLength, digest).toString('hex');
+    // Format: algorithm$iterations$salt$hash
+    return `pbkdf2$${iterations}$${salt}$${hash}`;
+}
+/**
+ * Verify PBKDF2 hash
+ */
+function verifyPbkdf2(password, passwordHash) {
+    const parts = passwordHash.split('$');
+    const iterationsStr = parts[1];
+    const salt = parts[2];
+    const storedHash = parts[3];
+    if (iterationsStr === undefined || salt === undefined || storedHash === undefined) {
+        return false;
+    }
+    try {
+        const iterations = Number.parseInt(iterationsStr, 10);
+        const keyLength = 64;
+        const digest = 'sha256';
+        const computed = pbkdf2Sync(password, salt, iterations, keyLength, digest).toString('hex');
+        return timingSafeEquals(computed, storedHash);
+    }
+    catch (error) {
+        Logger.error('PBKDF2 verification failed', error);
+        ErrorFactory.createSecurityError('PBKDF2 verification failed', error);
+        return false;
+    }
+}
+/**
+ * Hash with bcrypt
+ */
+async function hashBcrypt(bcryptModule, password) {
+    const rounds = 12;
+    return bcryptModule.hash(password, rounds);
+}
+/**
+ * Verify bcrypt hash
+ */
+async function verifyBcrypt(bcryptModule, password, passwordHash) {
+    return bcryptModule.compare(password, passwordHash);
+}
+/**
+ * Encryptor handles password hashing and verification
+ * Refactored to Functional Object pattern
+ */
+const hash = async (password) => {
+    await ensureLoaded();
+    if (algorithm === 'bcrypt' && bcrypt !== undefined) {
+        return hashBcrypt(bcrypt, password);
+    }
+    return hashPbkdf2(password);
+};
+/**
+ * Verify password against hash
+ */
+const verify = async (password, passwordHash) => {
+    await ensureLoaded();
+    // Detect hash format
+    if (passwordHash.startsWith('$2')) {
+        // bcrypt hash format
+        if (bcrypt !== undefined) {
+            return verifyBcrypt(bcrypt, password, passwordHash);
+        }
+        throw ErrorFactory.createConfigError('bcrypt not available to verify hash');
+    }
+    // PBKDF2 hash format (algorithm$iterations$salt$hash)
+    return verifyPbkdf2(password, passwordHash);
+};
+/**
+ * Get current algorithm
+ */
+const getAlgorithm = () => {
+    return algorithm;
+};
+export const Encryptor = Object.freeze({
+    hash,
+    verify,
+    getAlgorithm,
+});

package/src/security/JwtManager.d.ts

@@ -0,0 +1,41 @@
+/**
+ * JWT Manager
+ * JSON Web Token generation, verification, and claims management
+ * Uses native Node.js crypto module (zero external dependencies)
+ */
+export type JwtAlgorithm = 'HS256' | 'HS512' | 'RS256';
+export interface JwtPayload {
+    sub?: string;
+    iss?: string;
+    aud?: string;
+    exp?: number;
+    iat?: number;
+    nbf?: number;
+    jti?: string;
+    [key: string]: unknown;
+}
+export interface JwtOptions {
+    algorithm?: JwtAlgorithm;
+    expiresIn?: number;
+    issuer?: string;
+    audience?: string;
+    subject?: string;
+    jwtId?: string;
+}
+export interface IJwtManager {
+    setHmacSecret(secret: string): void;
+    setRsaKeys(privateKey: string, publicKey: string): void;
+    sign(payload: JwtPayload, options?: JwtOptions): string;
+    verify(token: string, algorithm?: JwtAlgorithm): JwtPayload;
+    decode(token: string): JwtPayload;
+    signRsa(message: string): string;
+    generateJwtId(): string;
+}
+export interface JwtManagerType {
+    create(): IJwtManager;
+}
+/**
+ * JwtManager namespace - sealed for immutability
+ */
+export declare const JwtManager: JwtManagerType;
+//# sourceMappingURL=JwtManager.d.ts.map

package/src/security/JwtManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JwtManager.d.ts","sourceRoot":"","sources":["../../../src/security/JwtManager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAEvD,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACxD,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IACxD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IAC5D,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC;IAClC,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,aAAa,IAAI,MAAM,CAAC;CACzB;AAQD,MAAM,WAAW,cAAc;IAC7B,MAAM,IAAI,WAAW,CAAC;CACvB;AAsCD;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,cAEvB,CAAC"}