@zintrust/core 0.1.27 → 0.1.28

package/src/scripts/TemplateSync.ts

@@ -0,0 +1,489 @@
+/**
+ * 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 { ensureDir, esmDirname } from '@common/index';
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import * as crypto from '@node-singletons/crypto';
+import fs from '@node-singletons/fs';
+import * as path from '@node-singletons/path';
+import * as nodePath from 'node:path';
+
+const __dirname = esmDirname(import.meta.url);
+const ROOT_DIR = path.resolve(__dirname, '../../');
+
+interface ChecksumRecord {
+  [basePath: string]: string;
+}
+
+/**
+ * Calculate SHA1 hash of file content
+ */
+function hashFile(filePath: string): string {
+  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: string): string {
+  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);
+  }
+}
+
+type WalkFile = {
+  absPath: string;
+  relPath: string;
+};
+
+const shouldSkipEntry = (name: string): boolean => {
+  return (
+    name === 'node_modules' ||
+    name === 'dist' ||
+    name === 'coverage' ||
+    name === '.git' ||
+    name === '.DS_Store'
+  );
+};
+
+const listFilesRecursive = (baseDirAbs: string): WalkFile[] => {
+  const out: WalkFile[] = [];
+  const walk = (dirAbs: string): void => {
+    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: {
+  checksums: ChecksumRecord;
+  baseDirRel: string;
+  templateDirRel: string;
+  description: string;
+  transformContent?: (relPath: string, content: string) => string;
+  checksumSalt?: string;
+}): { updated: number; skipped: number; total: number } => {
+  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 checksumSaltPart =
+      typeof params.checksumSalt === 'string' && params.checksumSalt.length > 0
+        ? `|${params.checksumSalt}`
+        : '';
+    const baseKey = `${params.baseDirRel}/${file.relPath}${checksumSaltPart}`;
+    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 };
+};
+
+const rewriteStarterTemplateImports = (relPath: string, content: string): string => {
+  if (!relPath.endsWith('.ts') && !relPath.endsWith('.tsx') && !relPath.endsWith('.mts')) {
+    return content;
+  }
+
+  const rewriteConfigAlias = (aliasSuffix: string): string => {
+    const currentDir = nodePath.posix.dirname(relPath);
+    const from = currentDir === '.' ? '' : currentDir;
+    const target = aliasSuffix;
+    const relative = nodePath.posix.relative(from, target);
+    return relative.startsWith('.') ? relative : `./${relative}`;
+  };
+
+  // Starter templates should import framework APIs from the public package surface,
+  // not from internal path-alias modules that only exist in the framework repo.
+  return (
+    content
+      // Some templates are extracted from internal sources that use repo-relative imports.
+      // Normalize those to the public package surface.
+      .replaceAll("'../../../features'", "'@zintrust/core'")
+      .replaceAll('"../../../features"', '"@zintrust/core"')
+      .replaceAll("'../../../logger'", "'@zintrust/core'")
+      .replaceAll('"../../../logger"', '"@zintrust/core"')
+      .replaceAll("'../../logger'", "'@zintrust/core'")
+      .replaceAll('"../../logger"', '"@zintrust/core"')
+      .replaceAll("'../logger'", "'@zintrust/core'")
+      .replaceAll('"../logger"', '"@zintrust/core"')
+
+      .replaceAll("'@common/uuid'", "'@zintrust/core'")
+      .replaceAll('"@common/uuid"', '"@zintrust/core"')
+
+      // Starter templates should not rely on local config/env wrappers.
+      // Normalize Env imports to come from the public package surface.
+      .replaceAll("from '../env';", "from '@zintrust/core';")
+      .replaceAll('from "../env";', 'from "@zintrust/core";')
+      .replaceAll("from './env';", "from '@zintrust/core';")
+      .replaceAll('from "./env";', 'from "@zintrust/core";')
+
+      // Node-singletons are internal to this repo; starter templates should use Node built-ins.
+      .replaceAll("'@node-singletons/fs'", "'node:fs'")
+      .replaceAll('"@node-singletons/fs"', '"node:fs"')
+      .replaceAll("'@node-singletons/path'", "'node:path'")
+      .replaceAll('"@node-singletons/path"', '"node:path"')
+      .replaceAll("'@node-singletons/perf-hooks'", "'node:perf_hooks'")
+      .replaceAll('"@node-singletons/perf-hooks"', '"node:perf_hooks"')
+
+      // Starter project config/* should reference sibling config modules via relative imports.
+      .replaceAll(/(['"])@config\/([^'"]+)\1/g, (_m, quote: string, suffix: string) => {
+        const rewritten = rewriteConfigAlias(suffix);
+        return `${quote}${rewritten}${quote}`;
+      })
+
+      // Middleware imports are framework APIs; they must come from the public package.
+      .replaceAll(/(['"])@middleware\/[^'"]+\1/g, (_m, quote: string) => {
+        return `${quote}@zintrust/core${quote}`;
+      })
+
+      .replaceAll("'@routing/Router'", "'@zintrust/core'")
+      .replaceAll("'@orm/Database'", "'@zintrust/core'")
+      .replaceAll("'@orm/QueryBuilder'", "'@zintrust/core'")
+      .replaceAll("'@orm/DatabaseAdapter'", "'@zintrust/core'")
+      .replaceAll("'@exceptions/ZintrustError'", "'@zintrust/core'")
+      .replaceAll("'@common/index'", "'@zintrust/core'")
+      .replaceAll("'@httpClient/Http'", "'@zintrust/core'")
+      // Handle double-quoted module specifiers too
+      .replaceAll('"@routing/Router"', '"@zintrust/core"')
+      .replaceAll('"@orm/Database"', '"@zintrust/core"')
+      .replaceAll('"@orm/QueryBuilder"', '"@zintrust/core"')
+      .replaceAll('"@orm/DatabaseAdapter"', '"@zintrust/core"')
+      .replaceAll('"@exceptions/ZintrustError"', '"@zintrust/core"')
+      .replaceAll('"@common/index"', '"@zintrust/core"')
+      .replaceAll('"@httpClient/Http"', '"@zintrust/core"')
+  );
+};
+
+const rewriteRegistryTemplateImports = (relPath: string, content: string): string => {
+  if (!relPath.endsWith('.ts') && !relPath.endsWith('.tsx') && !relPath.endsWith('.mts')) {
+    return content;
+  }
+
+  // Registry templates (adapters/features) must only import from the public package surface.
+  // Unlike starter project templates, they should NEVER rewrite `@config/*` into relative imports.
+  return (
+    content
+      // Normalize internal aliases to public API
+      .replaceAll("'@config/logger'", "'@zintrust/core'")
+      .replaceAll('"@config/logger"', '"@zintrust/core"')
+      .replaceAll("'@config/features'", "'@zintrust/core'")
+      .replaceAll('"@config/features"', '"@zintrust/core"')
+      .replaceAll("'@exceptions/ZintrustError'", "'@zintrust/core'")
+      .replaceAll('"@exceptions/ZintrustError"', '"@zintrust/core"')
+      .replaceAll("'@orm/DatabaseAdapter'", "'@zintrust/core'")
+      .replaceAll('"@orm/DatabaseAdapter"', '"@zintrust/core"')
+      .replaceAll("'@orm/QueryBuilder'", "'@zintrust/core'")
+      .replaceAll('"@orm/QueryBuilder"', '"@zintrust/core"')
+      .replaceAll("'@orm/Database'", "'@zintrust/core'")
+      .replaceAll('"@orm/Database"', '"@zintrust/core"')
+      .replaceAll("'@common/uuid'", "'@zintrust/core'")
+      .replaceAll('"@common/uuid"', '"@zintrust/core"')
+      .replaceAll("'@common/index'", "'@zintrust/core'")
+      .replaceAll('"@common/index"', '"@zintrust/core"')
+
+      // Node-singletons are internal to this repo; templates should use Node built-ins.
+      .replaceAll("'@node-singletons/fs'", "'node:fs'")
+      .replaceAll('"@node-singletons/fs"', '"node:fs"')
+      .replaceAll("'@node-singletons/path'", "'node:path'")
+      .replaceAll('"@node-singletons/path"', '"node:path"')
+      .replaceAll("'@node-singletons/perf-hooks'", "'node:perf_hooks'")
+      .replaceAll('"@node-singletons/perf-hooks"', '"node:perf_hooks"')
+
+      // Defensive: if old templates already contain repo-relative imports, normalize them.
+      .replaceAll("'../../../features'", "'@zintrust/core'")
+      .replaceAll('"../../../features"', '"@zintrust/core"')
+      .replaceAll("'../../../logger'", "'@zintrust/core'")
+      .replaceAll('"../../../logger"', '"@zintrust/core"')
+      .replaceAll("'../../logger'", "'@zintrust/core'")
+      .replaceAll('"../../logger"', '"@zintrust/core"')
+      .replaceAll("'../logger'", "'@zintrust/core'")
+      .replaceAll('"../logger"', '"@zintrust/core"')
+  );
+};
+
+const syncRegistryMappings = (params: {
+  checksums: ChecksumRecord;
+  mappings: Array<{ basePath: string; templatePath: string; description: string }>;
+}): { updated: number; skipped: number } => {
+  let updated = 0;
+  let skipped = 0;
+
+  const checksumSalt = 'registry-imports-v3';
+
+  for (const mapping of params.mappings) {
+    const basePath = path.join(ROOT_DIR, mapping.basePath);
+    const templatePath = path.join(ROOT_DIR, mapping.templatePath);
+
+    if (!fs.existsSync(basePath)) {
+      Logger.warn(`⚠️  Base file not found: ${mapping.basePath}`);
+      continue;
+    }
+
+    const currentHash = hashFile(basePath);
+    const checksumKey = `${mapping.basePath}|${checksumSalt}`;
+    const storedHash = params.checksums[checksumKey];
+
+    if (currentHash === storedHash && fs.existsSync(templatePath)) {
+      Logger.info(`✓ ${mapping.description} (in sync)`);
+      skipped++;
+      continue;
+    }
+
+    try {
+      const rawTemplateContent = extractTemplateContent(basePath);
+      const templateContent = rewriteRegistryTemplateImports(mapping.basePath, rawTemplateContent);
+      ensureDir(path.dirname(templatePath));
+      fs.writeFileSync(templatePath, templateContent, 'utf8');
+      params.checksums[checksumKey] = currentHash;
+      Logger.info(`✓ Updated: ${mapping.description}`);
+      updated++;
+    } catch (error) {
+      Logger.error(`❌ Failed to sync ${mapping.basePath}:`, error);
+      process.exit(1);
+    }
+  }
+
+  return { updated, skipped };
+};
+
+const syncStarterEnvTemplate = (params: {
+  checksums: ChecksumRecord;
+  projectRoot: string;
+}): { updated: number; skipped: number; total: number } => {
+  const envExampleAbs = fs.existsSync(path.join(ROOT_DIR, '.env.example'))
+    ? path.join(ROOT_DIR, '.env.example')
+    : path.join(ROOT_DIR, '.env.example.generated');
+
+  const envTemplateAbs = path.join(ROOT_DIR, params.projectRoot, '.env.tpl');
+  const envChecksumKey = 'starter/.env';
+
+  if (!fs.existsSync(envExampleAbs)) {
+    Logger.warn('⚠️  .env.example not found; skipping starter .env template generation');
+    return { updated: 0, skipped: 0, total: 1 };
+  }
+
+  const currentHash = hashFile(envExampleAbs);
+  const storedHash = params.checksums[envChecksumKey];
+
+  if (currentHash === storedHash && fs.existsSync(envTemplateAbs)) {
+    return { updated: 0, skipped: 1, total: 1 };
+  }
+
+  const raw = fs.readFileSync(envExampleAbs, 'utf8');
+  const lines = raw.split(/\r?\n/);
+  const rendered =
+    lines
+      .map((line) => {
+        if (line.trim() === '' || line.startsWith('#')) return line;
+        const eq = line.indexOf('=');
+        if (eq === -1) return line;
+        const key = line.slice(0, eq).trim();
+        if (key === '') return line;
+        if (key === 'NODE_ENV') return 'NODE_ENV=development';
+        return `${key}=`;
+      })
+      .join('\n') + '\n';
+
+  ensureDir(path.dirname(envTemplateAbs));
+  fs.writeFileSync(envTemplateAbs, rendered, 'utf8');
+  params.checksums[envChecksumKey] = currentHash;
+  Logger.info('✓ Starter project .env (generated)');
+  return { updated: 1, skipped: 0, total: 1 };
+};
+
+const syncStarterProjectTemplates = (params: {
+  checksums: ChecksumRecord;
+  projectRoot: string;
+}): { updated: number; skipped: number; total: number } => {
+  const s1 = syncProjectTemplateDir({
+    checksums: params.checksums,
+    baseDirRel: 'app',
+    templateDirRel: `${params.projectRoot}/app`,
+    description: 'Starter project app/*',
+  });
+
+  // NOTE:
+  // `src/templates/project/basic/config/*` is intentionally hand-authored.
+  // It must stay declarative (core owns runtime/env logic), and should never be
+  // auto-generated from `src/config/*` (which would overwrite project-level overrides).
+
+  const s3 = syncProjectTemplateDir({
+    checksums: params.checksums,
+    baseDirRel: 'src/database',
+    templateDirRel: `${params.projectRoot}/database`,
+    description: 'Starter project database/* (from src/database/*)',
+    transformContent: rewriteStarterTemplateImports,
+    checksumSalt: 'starter-imports-v3',
+  });
+
+  const s4 = syncProjectTemplateDir({
+    checksums: params.checksums,
+    baseDirRel: 'routes',
+    templateDirRel: `${params.projectRoot}/routes`,
+    description: 'Starter project routes/*',
+    transformContent: rewriteStarterTemplateImports,
+    checksumSalt: 'starter-imports-v1',
+  });
+
+  const s5 = syncStarterEnvTemplate({
+    checksums: params.checksums,
+    projectRoot: params.projectRoot,
+  });
+
+  return {
+    updated: s1.updated + s3.updated + s4.updated + s5.updated,
+    skipped: s1.skipped + s3.skipped + s4.skipped + s5.skipped,
+    total: s1.total + s3.total + s4.total + s5.total,
+  };
+};
+
+/**
+ * Load existing checksums from JSON file
+ */
+function loadChecksums(): ChecksumRecord {
+  const checksumPath = path.join(ROOT_DIR, '.template-checksums.json');
+  if (fs.existsSync(checksumPath)) {
+    try {
+      const content = fs.readFileSync(checksumPath, 'utf8');
+      return <ChecksumRecord>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: ChecksumRecord): void {
+  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(): Promise<void> {
+  Logger.info('🔄 Syncing templates...\n');
+
+  const args = new Set(process.argv.slice(2));
+  const shouldSyncStarterTemplates = args.has('--dangerously-sync-starter-templates');
+
+  const checksums = loadChecksums();
+  const mappings = TemplateRegistry.getMappings();
+  const registry = syncRegistryMappings({ checksums, mappings });
+
+  let starter: { updated: number; skipped: number; total: number } = {
+    updated: 0,
+    skipped: 0,
+    total: 0,
+  };
+
+  // Sync starter project templates (basic) from base framework folders.
+  // This is intentionally opt-in to avoid overwriting hand-authored starter templates.
+  if (shouldSyncStarterTemplates) {
+    Logger.info('');
+    Logger.info('🔄 Syncing starter project templates (basic)...');
+
+    const projectRoot = 'src/templates/project/basic';
+    starter = syncStarterProjectTemplates({ checksums, projectRoot });
+  } else {
+    Logger.info('');
+    Logger.info(
+      '⏭️  Skipping starter project template sync (pass --dangerously-sync-starter-templates to enable)'
+    );
+  }
+
+  // Save updated checksums
+  saveChecksums(checksums);
+
+  // Summary
+  const updated = registry.updated + starter.updated;
+  const skipped = registry.skipped + starter.skipped;
+  Logger.info(`\n📦 Template sync complete`);
+  Logger.info(`   Updated: ${updated}`);
+  Logger.info(`   Skipped: ${skipped}`);
+  Logger.info(`   Total: ${mappings.length + starter.total}\n`);
+}
+
+// Run sync
+try {
+  await syncTemplates();
+} catch (error) {
+  Logger.error('Template sync failed', error);
+  process.exit(1);
+}

package/src/security/CsrfTokenManager.ts

@@ -0,0 +1,102 @@
+/**
+ * CSRF Token Manager
+ * Generate, validate, and bind CSRF tokens to sessions
+ */
+
+import { Env } from '@config/env';
+import { randomBytes } from '@node-singletons/crypto';
+
+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;
+}
+
+/**
+ * Create a new CSRF token manager instance
+ */
+const create = (): ICsrfTokenManager => {
+  const tokens: Map<string, CsrfTokenData> = new Map();
+  const tokenLength = Env.TOKEN_LENGTH; // 256 bits
+  const tokenTtl = Env.TOKEN_TTL; // 1 hour in milliseconds
+
+  return {
+    generateToken(sessionId: string): string {
+      tokens.delete(sessionId);
+      const token = randomBytes(tokenLength).toString('hex');
+      const now = new Date();
+      const expiresAt = new Date(now.getTime() + tokenTtl);
+      const tokenData: CsrfTokenData = { token, sessionId, createdAt: now, expiresAt };
+      tokens.set(sessionId, tokenData);
+      return token;
+    },
+    validateToken(sessionId: string, token: string): boolean {
+      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: string): void {
+      tokens.delete(sessionId);
+    },
+    getTokenData(sessionId: string): CsrfTokenData | null {
+      return tokens.get(sessionId) ?? null;
+    },
+    refreshToken(sessionId: string): string | null {
+      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(): number {
+      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(): void {
+      tokens.clear();
+    },
+    getTokenCount(): number {
+      return tokens.size;
+    },
+  };
+};
+
+/**
+ * CsrfTokenManager namespace - sealed for immutability
+ */
+export const CsrfTokenManager: CsrfTokenManagerType = Object.freeze({
+  create,
+});