@zintrust/core 0.1.0

package/src/templates/project/basic/config/microservices.ts.tpl

@@ -0,0 +1,104 @@
+/**
+ * Microservices Configuration
+ * Microservices architecture and service discovery settings
+ * Sealed namespace for immutability
+ */
+
+import { Env } from '@config/env';
+
+const microservicesConfigObj = {
+  /**
+   * Enable microservices mode
+   */
+  enabled: Env.getBool('MICROSERVICES', false),
+
+  /**
+   * Enabled services (comma-separated)
+   */
+  services: Env.get('SERVICES', '')
+    .split(',')
+    .filter((s) => s.trim()),
+
+  /**
+   * Service discovery
+   */
+  discovery: {
+    type: Env.get('SERVICE_DISCOVERY_TYPE', 'filesystem') as 'filesystem' | 'consul' | 'etcd',
+    servicesPath: Env.get('SERVICES_PATH', 'services'),
+    refreshInterval: Env.getInt('SERVICE_DISCOVERY_REFRESH_INTERVAL', 30000),
+  },
+
+  /**
+   * Service Registry
+   */
+  registry: {
+    host: Env.get('SERVICE_REGISTRY_HOST', 'localhost'),
+    port: Env.getInt('SERVICE_REGISTRY_PORT', 8500),
+    deregisterCriticalServiceAfter: Env.get('SERVICE_DEREGISTER_CRITICAL_AFTER', '30s'),
+  },
+
+  /**
+   * Service Authentication
+   */
+  auth: {
+    strategy: Env.get('SERVICE_AUTH_STRATEGY', 'none') as 'api-key' | 'jwt' | 'none' | 'custom',
+    apiKey: Env.get('SERVICE_API_KEY'),
+    jwtSecret: Env.get('SERVICE_JWT_SECRET'),
+  },
+
+  /**
+   * Request Tracing
+   */
+  tracing: {
+    enabled: Env.getBool('MICROSERVICES_TRACING', false),
+    samplingRate: Env.getInt('MICROSERVICES_TRACING_RATE', 100) / 100,
+    exportInterval: Env.getInt('TRACING_EXPORT_INTERVAL', 10000),
+    jaegerEndpoint: Env.get('JAEGER_AGENT_HOST', 'localhost'),
+  },
+
+  /**
+   * Database Isolation
+   */
+  database: {
+    isolation: Env.get('DATABASE_ISOLATION', 'shared') as 'shared' | 'isolated',
+    schema: Env.get('DATABASE_SCHEMA_PREFIX', 'microservice'),
+  },
+
+  /**
+   * Service Health Check
+   */
+  healthCheck: {
+    enabled: Env.getBool('SERVICE_HEALTH_CHECK_ENABLED', true),
+    interval: Env.getInt('SERVICE_HEALTH_CHECK_INTERVAL', 30000),
+    timeout: Env.getInt('SERVICE_HEALTH_CHECK_TIMEOUT', 5000),
+    unhealthyThreshold: Env.getInt('SERVICE_UNHEALTHY_THRESHOLD', 3),
+    healthyThreshold: Env.getInt('SERVICE_HEALTHY_THRESHOLD', 2),
+  },
+
+  /**
+   * Service Communication
+   */
+  communication: {
+    timeout: Env.getInt('SERVICE_CALL_TIMEOUT', 30000),
+    retries: Env.getInt('SERVICE_CALL_RETRIES', 3),
+    retryDelay: Env.getInt('SERVICE_CALL_RETRY_DELAY', 1000),
+    circuitBreaker: {
+      enabled: Env.getBool('CIRCUIT_BREAKER_ENABLED', true),
+      threshold: Env.getInt('CIRCUIT_BREAKER_THRESHOLD', 5),
+      timeout: Env.getInt('CIRCUIT_BREAKER_TIMEOUT', 60000),
+    },
+  },
+
+  /**
+   * Service Mesh (Istio/Linkerd support)
+   */
+  mesh: {
+    enabled: Env.getBool('SERVICE_MESH_ENABLED', false),
+    type: Env.get('SERVICE_MESH_TYPE', 'istio') as 'istio' | 'linkerd',
+    namespace: Env.get('SERVICE_MESH_NAMESPACE', 'default'),
+  },
+} as const;
+
+export const microservicesConfig = Object.freeze(microservicesConfigObj);
+
+export type MicroservicesConfig = typeof microservicesConfig;

package/src/templates/project/basic/config/queue.ts.tpl

@@ -0,0 +1,134 @@
+/**
+ * Queue Configuration
+ * Background job and message queue settings
+ * Sealed namespace for immutability
+ */
+
+import { Env } from '@config/env';
+
+type QueueDriverName = 'sync' | 'database' | 'redis' | 'rabbitmq' | 'sqs';
+
+type SyncQueueDriverConfig = {
+  driver: 'sync';
+};
+
+type DatabaseQueueDriverConfig = {
+  driver: 'database';
+  table: string;
+  connection: string;
+};
+
+type RedisQueueDriverConfig = {
+  driver: 'redis';
+  host: string;
+  port: number;
+  password?: string;
+  database: number;
+};
+
+type RabbitMqQueueDriverConfig = {
+  driver: 'rabbitmq';
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+  vhost: string;
+};
+
+type SqsQueueDriverConfig = {
+  driver: 'sqs';
+  key?: string;
+  secret?: string;
+  region: string;
+  queueUrl?: string;
+};
+
+type QueueDriversConfig = {
+  sync: SyncQueueDriverConfig;
+  database: DatabaseQueueDriverConfig;
+  redis: RedisQueueDriverConfig;
+  rabbitmq: RabbitMqQueueDriverConfig;
+  sqs: SqsQueueDriverConfig;
+};
+
+type QueueConfigWithDrivers = {
+  default: QueueDriverName;
+  drivers: QueueDriversConfig;
+};
+
+const getQueueDriver = (config: QueueConfigWithDrivers): QueueDriversConfig[QueueDriverName] => {
+  const driverName = config.default;
+  return config.drivers[driverName];
+};
+
+const queueConfigObj = {
+  /**
+   * Default queue driver
+   */
+  default: Env.get('QUEUE_DRIVER', 'sync') as QueueDriverName,
+
+  /**
+   * Queue drivers
+   */
+  drivers: {
+    sync: {
+      driver: 'sync' as const,
+    },
+    database: {
+      driver: 'database' as const,
+      table: Env.get('QUEUE_TABLE', 'jobs'),
+      connection: Env.get('QUEUE_DB_CONNECTION', 'default'),
+    },
+    redis: {
+      driver: 'redis' as const,
+      host: Env.get('REDIS_HOST', 'localhost'),
+      port: Env.getInt('REDIS_PORT', 6379),
+      password: Env.get('REDIS_PASSWORD'),
+      database: Env.getInt('REDIS_QUEUE_DB', 1),
+    },
+    rabbitmq: {
+      driver: 'rabbitmq' as const,
+      host: Env.get('RABBITMQ_HOST', 'localhost'),
+      port: Env.getInt('RABBITMQ_PORT', 5672),
+      username: Env.get('RABBITMQ_USER', 'guest'),
+      password: Env.get('RABBITMQ_PASSWORD', 'guest'),
+      vhost: Env.get('RABBITMQ_VHOST', '/'),
+    },
+    sqs: {
+      driver: 'sqs' as const,
+      key: Env.get('AWS_ACCESS_KEY_ID'),
+      secret: Env.get('AWS_SECRET_ACCESS_KEY'),
+      region: Env.AWS_REGION,
+      queueUrl: Env.get('AWS_SQS_QUEUE_URL'),
+    },
+  } satisfies QueueDriversConfig,
+
+  /**
+   * Get queue driver config
+   */
+  getDriver(): QueueDriversConfig[QueueDriverName] {
+    return getQueueDriver(this);
+  },
+
+  /**
+   * Failed jobs table
+   */
+  failed: {
+    database: Env.get('FAILED_JOBS_DB_CONNECTION', 'default'),
+    table: Env.get('FAILED_JOBS_TABLE', 'failed_jobs'),
+  },
+
+  /**
+   * Job processing
+   */
+  processing: {
+    timeout: Env.getInt('QUEUE_JOB_TIMEOUT', 60),
+    retries: Env.getInt('QUEUE_JOB_RETRIES', 3),
+    backoff: Env.getInt('QUEUE_JOB_BACKOFF', 0),
+    workers: Env.getInt('QUEUE_WORKERS', 1),
+  },
+};
+
+export const queueConfig = Object.freeze(queueConfigObj);
+
+export type QueueConfig = typeof queueConfig;

package/src/templates/project/basic/config/security.ts.tpl

@@ -0,0 +1,149 @@
+/**
+ * Security Configuration
+ * JWT, CSRF, encryption and other security settings
+ * Sealed namespace for immutability
+ */
+
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@zintrust/core';
+
+/**
+ * Helper to warn about missing secrets
+ */
+function warnMissingSecret(secretName: string): string {
+  Logger.error(`❌ CRITICAL: ${secretName} environment variable is not set!`);
+  Logger.error('⚠️  Application may not function correctly. Set this in production immediately.');
+
+  const nodeEnv = Env.get('NODE_ENV', 'development');
+  if (nodeEnv === 'production') {
+    throw ErrorFactory.createConfigError(`Missing required secret: ${secretName}`, { secretName });
+  }
+
+  // In non-production environments, allow the app/CLI to start while still warning loudly.
+  // This is intentionally predictable for local development and test tooling.
+  return 'dev-unsafe-jwt-secret';
+}
+
+let cachedJwtSecret: string | undefined;
+
+const securityConfigObj = {
+  /**
+   * JWT Configuration
+   */
+  jwt: {
+    enabled: Env.getBool('JWT_ENABLED', true),
+    get secret(): string {
+      if (cachedJwtSecret !== undefined) return cachedJwtSecret;
+      const isEnabled = Env.getBool('JWT_ENABLED', true);
+      cachedJwtSecret = isEnabled
+        ? Env.get('JWT_SECRET') || warnMissingSecret('JWT_SECRET')
+        : Env.get('JWT_SECRET') || '';
+      return cachedJwtSecret;
+    },
+    algorithm: Env.get('JWT_ALGORITHM', 'HS256') as 'HS256' | 'HS512' | 'RS256',
+    expiresIn: Env.get('JWT_EXPIRES_IN', '1h'),
+    refreshExpiresIn: Env.get('JWT_REFRESH_EXPIRES_IN', '7d'),
+    issuer: Env.get('JWT_ISSUER', '@zintrust/core'),
+    audience: Env.get('JWT_AUDIENCE', 'zintrust-api'),
+  },
+
+  /**
+   * CSRF Protection
+   */
+  csrf: {
+    enabled: Env.getBool('CSRF_ENABLED', true),
+    headerName: Env.get('CSRF_HEADER_NAME', 'x-csrf-token'),
+    tokenName: Env.get('CSRF_TOKEN_NAME', '_csrf'),
+    cookieName: Env.get('CSRF_COOKIE_NAME', 'XSRF-TOKEN'),
+    cookieHttpOnly: Env.getBool('CSRF_COOKIE_HTTP_ONLY', true),
+    cookieSecure: Env.getBool('CSRF_COOKIE_SECURE', true),
+    cookieSameSite: Env.get('CSRF_COOKIE_SAME_SITE', 'strict') as 'strict' | 'lax' | 'none',
+  },
+
+  /**
+   * Encryption
+   */
+  encryption: {
+    algorithm: Env.get('ENCRYPTION_ALGORITHM', 'aes-256-cbc'),
+    key: Env.get('ENCRYPTION_KEY', 'your-encryption-key'),
+  },
+
+  /**
+   * API Key Authentication
+   */
+  apiKey: {
+    enabled: Env.getBool('API_KEY_ENABLED', true),
+    headerName: Env.get('API_KEY_HEADER', 'x-api-key'),
+    secret: Env.get('API_KEY_SECRET'),
+  },
+
+  /**
+   * CORS Configuration
+   */
+  cors: {
+    enabled: Env.getBool('CORS_ENABLED', true),
+    origins: Env.get('CORS_ORIGINS', '*').split(','),
+    methods: Env.get('CORS_METHODS', 'GET,POST,PUT,PATCH,DELETE').split(','),
+    allowedHeaders: Env.get('CORS_ALLOWED_HEADERS', 'Content-Type,Authorization').split(','),
+    exposedHeaders: Env.get('CORS_EXPOSED_HEADERS', '').split(','),
+    credentials: Env.getBool('CORS_CREDENTIALS', false),
+    maxAge: Env.getInt('CORS_MAX_AGE', 86400),
+  },
+
+  /**
+   * Rate Limiting
+   */
+  rateLimit: {
+    enabled: Env.getBool('RATE_LIMIT_ENABLED', true),
+    windowMs: Env.getInt('RATE_LIMIT_WINDOW_MS', 900000), // 15 minutes
+    maxRequests: Env.getInt('RATE_LIMIT_MAX_REQUESTS', 100),
+    message: Env.get('RATE_LIMIT_MESSAGE', 'Too many requests, please try again later'),
+  },
+
+  /**
+   * XSS Protection
+   */
+  xss: {
+    enabled: Env.getBool('XSS_ENABLED', true),
+    reportUri: Env.get('XSS_REPORT_URI'),
+  },
+
+  /**
+   * Helmet Security Headers
+   */
+  helmet: {
+    enabled: Env.getBool('HELMET_ENABLED', true),
+    contentSecurityPolicy: Env.getBool('CSP_ENABLED', true),
+    hsts: {
+      enabled: Env.getBool('HSTS_ENABLED', true),
+      maxAge: Env.getInt('HSTS_MAX_AGE', 31536000),
+      includeSubDomains: Env.getBool('HSTS_INCLUDE_SUBDOMAINS', true),
+    },
+  },
+
+  /**
+   * Session Configuration
+   */
+  session: {
+    name: Env.get('SESSION_NAME', 'zintrust_session'),
+    secret: Env.get('SESSION_SECRET', 'your-session-secret'),
+    expiresIn: Env.getInt('SESSION_EXPIRES_IN', 1800000), // 30 minutes
+    secure: Env.getBool('SESSION_SECURE', true),
+    httpOnly: Env.getBool('SESSION_HTTP_ONLY', true),
+    sameSite: Env.get('SESSION_SAME_SITE', 'strict') as 'strict' | 'lax' | 'none',
+  },
+
+  /**
+   * Password settings
+   */
+  password: {
+    minLength: Env.getInt('PASSWORD_MIN_LENGTH', 8),
+    requireUppercase: Env.getBool('PASSWORD_REQUIRE_UPPERCASE', true),
+    requireNumbers: Env.getBool('PASSWORD_REQUIRE_NUMBERS', true),
+    requireSpecialChars: Env.getBool('PASSWORD_REQUIRE_SPECIAL_CHARS', true),
+    bcryptRounds: Env.getInt('BCRYPT_ROUNDS', 10),
+  },
+} as const;
+
+export const securityConfig = Object.freeze(securityConfigObj);

package/src/templates/project/basic/config/storage.ts.tpl

@@ -0,0 +1,136 @@
+/**
+ * Storage Configuration
+ * File storage and cloud storage settings
+ * Sealed namespace for immutability
+ */
+
+import { Env } from '@config/env';
+
+type EnvGetValue = ReturnType<typeof Env.get>;
+type EnvGetBoolValue = ReturnType<typeof Env.getBool>;
+
+type LocalStorageDriverConfig = {
+  driver: 'local';
+  root: EnvGetValue;
+  url: EnvGetValue;
+  visibility: EnvGetValue;
+};
+
+type S3StorageDriverConfig = {
+  driver: 's3';
+  key: EnvGetValue;
+  secret: EnvGetValue;
+  region: typeof Env.AWS_REGION;
+  bucket: EnvGetValue;
+  url: EnvGetValue;
+  endpoint: EnvGetValue;
+  usePathStyleUrl: EnvGetBoolValue;
+};
+
+type GcsStorageDriverConfig = {
+  driver: 'gcs';
+  projectId: EnvGetValue;
+  keyFile: EnvGetValue;
+  bucket: EnvGetValue;
+  url: EnvGetValue;
+};
+
+type StorageDrivers = {
+  local: LocalStorageDriverConfig;
+  s3: S3StorageDriverConfig;
+  gcs: GcsStorageDriverConfig;
+};
+
+type StorageDriverName = keyof StorageDrivers;
+type StorageDriverConfig = StorageDrivers[StorageDriverName];
+
+type StorageConfigRuntime = {
+  default: string;
+  drivers: StorageDrivers;
+};
+
+const isStorageDriverName = (value: string, drivers: StorageDrivers): value is StorageDriverName => {
+  return value in drivers;
+};
+
+const getStorageDriver = (config: StorageConfigRuntime): StorageDriverConfig => {
+  const driverName = config.default;
+
+  if (isStorageDriverName(driverName, config.drivers)) {
+    return config.drivers[driverName];
+  }
+
+  return config.drivers.local;
+};
+
+const storageConfigObj = {
+  /**
+   * Default storage driver
+   */
+  default: Env.get('STORAGE_DRIVER', 'local'),
+
+  /**
+   * Storage drivers configuration
+   */
+  drivers: {
+    local: {
+      driver: 'local' as const,
+      root: Env.get('STORAGE_PATH', 'storage'),
+      url: Env.get('STORAGE_URL', '/storage'),
+      visibility: Env.get('STORAGE_VISIBILITY', 'private'),
+    },
+    s3: {
+      driver: 's3' as const,
+      key: Env.get('AWS_ACCESS_KEY_ID'),
+      secret: Env.get('AWS_SECRET_ACCESS_KEY'),
+      region: Env.AWS_REGION,
+      bucket: Env.get('AWS_S3_BUCKET'),
+      url: Env.get('AWS_S3_URL'),
+      endpoint: Env.get('AWS_S3_ENDPOINT'),
+      usePathStyleUrl: Env.getBool('AWS_S3_USE_PATH_STYLE_URL', false),
+    },
+    gcs: {
+      driver: 'gcs' as const,
+      projectId: Env.get('GCS_PROJECT_ID'),
+      keyFile: Env.get('GCS_KEY_FILE'),
+      bucket: Env.get('GCS_BUCKET'),
+      url: Env.get('GCS_URL'),
+    },
+  },
+
+  /**
+   * Get storage driver config
+   */
+  getDriver(this: StorageConfigRuntime): StorageDriverConfig {
+    return getStorageDriver(this);
+  },
+
+  /**
+   * Temporary file settings
+   */
+  temp: {
+    path: Env.get('TEMP_PATH', 'storage/temp'),
+    maxAge: Env.getInt('TEMP_FILE_MAX_AGE', 86400), // 24 hours
+  },
+
+  /**
+   * Uploads settings
+   */
+  uploads: {
+    maxSize: Env.get('MAX_UPLOAD_SIZE', '100mb'),
+    allowedMimes: Env.get('ALLOWED_UPLOAD_MIMES', 'jpg,jpeg,png,pdf,doc,docx'),
+    path: Env.get('UPLOADS_PATH', 'storage/uploads'),
+  },
+
+  /**
+   * Backups settings
+   */
+  backups: {
+    path: Env.get('BACKUPS_PATH', 'storage/backups'),
+    driver: Env.get('BACKUP_DRIVER', 's3'),
+  },
+};
+
+export const storageConfig = Object.freeze(storageConfigObj);
+
+export type StorageConfig = typeof storageConfig;

package/src/templates/project/basic/database/migrations/index.ts.tpl

@@ -0,0 +1,2 @@
+// Placeholder for migrations
+export {};

package/src/templates/project/basic/package.json.tpl

@@ -0,0 +1,22 @@
+{
+  "name": "{{projectName}}",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "zin s",
+    "build": "tsc && tsc-alias",
+    "start": "zin s --mode production --no-watch",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zintrust/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.21.0",
+    "tsc-alias": "^1.8.16",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  }
+}

package/src/templates/project/basic/routes/api.ts.tpl

@@ -0,0 +1,135 @@
+/**
+ * Example Routes
+ * Demonstrates routing patterns
+ */
+
+import { UserController } from '@app/Controllers/UserController';
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+import { useDatabase, type IRouter, Router } from '@zintrust/core';
+
+export function registerRoutes(router: IRouter): void {
+  const userController = UserController.create();
+  registerPublicRoutes(router);
+  registerApiV1Routes(router, userController);
+  registerAdminRoutes(router);
+}
+
+/**
+ * Register public routes
+ */
+function registerPublicRoutes(router: IRouter): void {
+  Router.get(router, '/', async (_req, res) => {
+    res.json({
+      framework: 'Zintrust Framework',
+      app_name: Env.APP_NAME,
+      version: '0.1.0',
+      env: Env.NODE_ENV ?? 'development',
+      database: Env.DB_CONNECTION ?? 'sqlite',
+    });
+  });
+
+  Router.get(router, '/health', async (_req, res) => {
+    try {
+      const db = useDatabase();
+      await db.query('SELECT 1');
+
+      const uptime =
+        typeof process !== 'undefined' && typeof process.uptime === 'function'
+          ? process.uptime()
+          : 0;
+
+      res.json({
+        status: 'healthy',
+        timestamp: new Date().toISOString(),
+        uptime,
+        database: 'connected',
+        environment: Env.NODE_ENV ?? 'development',
+      });
+    } catch (error) {
+      Logger.error('Health check failed:', error);
+
+      const isProd =
+        typeof process !== 'undefined' &&
+        typeof process.env === 'object' &&
+        process.env !== null &&
+        process.env['NODE_ENV'] === 'production';
+
+      res.setStatus(503).json({
+        status: 'unhealthy',
+        timestamp: new Date().toISOString(),
+        database: 'disconnected',
+        error: isProd ? 'Service unavailable' : (error as Error).message,
+      });
+    }
+  });
+}
+
+/**
+ * Register API V1 routes
+ */
+function registerApiV1Routes(
+  router: IRouter,
+  userController: ReturnType<typeof UserController.create>
+): void {
+  Router.group(router, '/api/v1', (r) => {
+    // Auth routes
+    Router.post(r, '/auth/login', async (_req, res) => {
+      res.json({ message: 'Login endpoint' });
+    });
+
+    Router.post(r, '/auth/register', async (_req, res) => {
+      res.json({ message: 'Register endpoint' });
+    });
+
+    // Protected routes (middleware is not modeled in Router.ts yet)
+    const pr = r;
+
+    // User resource (REST-ish)
+    Router.resource(pr, '/users', {
+      index: userController.index,
+      store: userController.store,
+      show: userController.show,
+      update: userController.update,
+      destroy: userController.destroy,
+    });
+
+    // If the controller exposes create/edit, wire them explicitly.
+    Router.get(pr, '/users/create', userController.create);
+    Router.get(pr, '/users/:id/edit', userController.edit);
+
+    // Custom user routes
+    Router.get(pr, '/profile', async (_req, res) => {
+      res.json({ message: 'Get user profile' });
+    });
+
+    Router.put(pr, '/profile', async (_req, res) => {
+      res.json({ message: 'Update user profile' });
+    });
+
+    // Posts resource
+    Router.get(r, '/posts', async (_req, res) => {
+      res.json({ data: [] });
+    });
+
+    Router.get(r, '/posts/:id', async (req, res) => {
+      const id = req.getParam('id');
+      res.json({ data: { id } });
+    });
+  });
+}
+
+/**
+ * Register admin routes
+ */
+function registerAdminRoutes(router: IRouter): void {
+  Router.group(router, '/admin', (r) => {
+    Router.get(r, '/dashboard', async (_req, res) => {
+      res.json({ message: 'Admin dashboard' });
+    });
+
+    Router.get(r, '/users', async (_req, res) => {
+      res.json({ data: [] });
+    });
+  });
+}