@zintrust/core 0.1.0

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

@@ -0,0 +1,164 @@
+# ============================================================================
+# Zintrust Framework - Environment Configuration
+# Generated from src/config/env.ts - All available configuration keys
+# ============================================================================
+
+# ============================================================================
+# APPLICATION
+# ============================================================================
+
+# Environment: development | staging | production
+NODE_ENV=development
+
+# Server Configuration
+HOST=127.0.0.1
+APP_PORT=7777
+APP_NAME={{projectName}}
+APP_KEY=
+
+
+# ============================================================================
+# LOGGING
+# ============================================================================
+
+# Log Level: debug | info | warn | error
+LOG_LEVEL=debug
+DISABLE_LOGGING=true
+LOG_CHANNEL=file
+
+
+# ============================================================================
+# DATABASE
+# ============================================================================
+
+# Database Connection Driver
+# Options: sqlite | postgresql | mysql | sqlserver | d1
+DB_CONNECTION=sqlite
+
+# SQLite Configuration
+DB_PATH=./storage/db.sqlite
+
+# PostgreSQL Configuration
+DB_HOST=localhost
+DB_PORT=5432
+DB_DATABASE=zintrust
+DB_USERNAME=postgres
+DB_PASSWORD=
+DB_READ_HOSTS=
+
+# ============================================================================
+# CLOUDFLARE
+# ============================================================================
+
+D1_DATABASE_ID=
+KV_NAMESPACE_ID=
+
+# ============================================================================
+# CACHE
+# ============================================================================
+
+# Cache Driver: memory | redis | memcached
+CACHE_DRIVER=memory
+
+# Redis Configuration
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+
+# MongoDB Cache Configuration
+MONGO_URI=
+MONGO_DB=zintrust_cache
+
+# ============================================================================
+# AWS
+# ============================================================================
+
+AWS_REGION=us-east-1
+AWS_LAMBDA_FUNCTION_NAME=
+AWS_LAMBDA_FUNCTION_VERSION=
+AWS_EXECUTION_ENV=
+LAMBDA_TASK_ROOT=
+
+# ============================================================================
+# MICROSERVICES
+# ============================================================================
+
+MICROSERVICES=
+SERVICES=
+MICROSERVICES_TRACING=false
+MICROSERVICES_TRACING_RATE=1.0
+DATABASE_ISOLATION=shared
+SERVICE_API_KEY=
+SERVICE_JWT_SECRET=
+
+# ============================================================================
+# SECURITY
+# ============================================================================
+
+DEBUG=false
+ENABLE_MICROSERVICES=false
+TOKEN_TTL=3600000
+TOKEN_LENGTH=32
+
+# JWT Secret for authentication
+JWT_SECRET=
+
+# Session Configuration
+SESSION_DRIVER=cookie
+SESSION_LIFETIME=7200
+
+# CORS Configuration
+CORS_ORIGINS=http://localhost:3000,http://localhost:5173
+
+# ============================================================================
+# DEPLOYMENT
+# ============================================================================
+
+ENVIRONMENT=development
+REQUEST_TIMEOUT=30000
+MAX_BODY_SIZE=10485760
+
+
+# ============================================================================
+# EXTERNAL SERVICES & CREDENTIALS
+# ============================================================================
+
+SONAR_ORGANIZATION="zintrust"
+SONAR_PROJECT_ID="ZinTrust_ZinTrust"
+SONAR_HOST_URL="https://sonarcloud.io"
+SONAR_TOKEN=
+
+# Cloudflare Workspace-Specific Credentials
+CLOUDFLARE_API_TOKEN=
+CLOUDFLARE_ACCOUNT_ID=""
+
+CODECOV_TOKEN=
+
+# Security Scanning
+SNYK_TOKEN=
+
+# Email (SendGrid)
+SENDGRID_API_KEY=
+
+# Payments (Stripe)
+STRIPE_SECRET_KEY=
+STRIPE_PUBLIC_KEY=
+
+# Cloud Storage (AWS S3)
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_BUCKET=
+
+# ============================================================================
+# DEVELOPMENT
+# ============================================================================
+
+# Database Synchronization (auto-migrate on startup)
+DB_SYNCHRONIZE=true
+
+# Database Logging
+DB_LOGGING=false
+
+# Raw SQL Query Support (development only)
+# WARNING: Only enable in development. Bypasses QueryBuilder safety.
+USE_RAW_QRY=false

package/src/templates/project/basic/README.md.tpl

@@ -0,0 +1,13 @@
+# {{projectName}}
+
+Starter Task API built with Zintrust.
+
+## Run
+
+```bash
+npm install
+zin s
+```
+
+- Health: http://localhost:{{port}}/health
+- Tasks:  http://localhost:{{port}}/api/tasks

package/src/templates/project/basic/app/Controllers/UserController.ts.tpl

@@ -0,0 +1,155 @@
+/**
+ * User Controller
+ * Example controller demonstrating request handling
+ */
+
+import { User } from '@app/Models/User';
+import { Logger } from '@config/logger';
+import { type IRequest, type IResponse } from '@zintrust/core';
+
+/**
+ * User Controller Interface
+ */
+export interface IUserController {
+  index(req: IRequest, res: IResponse): Promise<void>;
+  show(req: IRequest, res: IResponse): Promise<void>;
+  create(req: IRequest, res: IResponse): Promise<void>;
+  store(req: IRequest, res: IResponse): Promise<void>;
+  edit(req: IRequest, res: IResponse): Promise<void>;
+  update(req: IRequest, res: IResponse): Promise<void>;
+  destroy(req: IRequest, res: IResponse): Promise<void>;
+}
+
+/**
+ * User Controller Methods
+ */
+const userControllerMethods: IUserController = {
+  /**
+   * List all users
+   * GET /users
+   */
+  async index(_req: IRequest, res: IResponse): Promise<void> {
+    try {
+      const users = await User.all();
+      res.json({ data: users });
+    } catch (error) {
+      Logger.error('Error fetching users:', error);
+      res.status(500).json({ error: 'Failed to fetch users' });
+    }
+  },
+
+  /**
+   * Show a specific user
+   * GET /users/:id
+   */
+  async show(req: IRequest, res: IResponse): Promise<void> {
+    try {
+      const id = req.params['id'];
+      const user = await User.find(id);
+      if (user === null) {
+        res.status(404).json({ error: 'User not found' });
+        return;
+      }
+      res.json({ data: user });
+    } catch (error) {
+      Logger.error('Error fetching user:', error);
+      res.status(500).json({ error: 'Failed to fetch user' });
+    }
+  },
+
+  /**
+   * Show create form
+   * GET /users/create
+   */
+  async create(_req: IRequest, res: IResponse): Promise<void> {
+    res.json({ form: 'Create User Form' });
+  },
+
+  /**
+   * Store a new user
+   * POST /users
+   */
+  async store(req: IRequest, res: IResponse): Promise<void> {
+    try {
+      const body = req.body;
+      if (typeof body['name'] !== 'string' || !body['name']) {
+        res.status(422).json({ error: 'Name is required' });
+        return;
+      }
+      const user = User.create(body);
+      res.status(201).json({ message: 'User created', user });
+    } catch (error) {
+      Logger.error('Error creating user:', error);
+      res.status(500).json({ error: 'Failed to create user' });
+    }
+  },
+
+  /**
+   * Show edit form
+   * GET /users/:id/edit
+   */
+  async edit(_req: IRequest, res: IResponse): Promise<void> {
+    try {
+      res.json({ form: 'Edit User Form' });
+    } catch (error) {
+      Logger.error('Error loading edit form:', error);
+      res.status(500).json({ error: 'Failed to load edit form' });
+    }
+  },
+
+  /**
+   * Update a user
+   * PUT /users/:id
+   */
+  async update(req: IRequest, res: IResponse): Promise<void> {
+    try {
+      const id = req.params['id'];
+      const user = await User.find(id);
+      if (user === null) {
+        res.status(404).json({ error: 'User not found' });
+        return;
+      }
+      const body = req.body;
+      user.fill(body);
+      await user.save();
+      res.json({ message: 'User updated', user });
+    } catch (error) {
+      Logger.error('Error updating user:', error);
+      res.status(500).json({ error: 'Failed to update user' });
+    }
+  },
+
+  /**
+   * Delete a user
+   * DELETE /users/:id
+   */
+  async destroy(req: IRequest, res: IResponse): Promise<void> {
+    try {
+      const id = req.params['id'];
+      const user = await User.find(id);
+      if (user === null) {
+        res.status(404).json({ error: 'User not found' });
+        return;
+      }
+      await user.delete();
+      res.json({ message: 'User deleted' });
+    } catch (error) {
+      Logger.error('Error deleting user:', error);
+      res.status(500).json({ error: 'Failed to delete user' });
+    }
+  },
+};
+
+/**
+ * User Controller Factory
+ */
+export const UserController = {
+  /**
+   * Create a new user controller instance
+   */
+  create(): IUserController {
+    return userControllerMethods;
+  },
+};
+
+export default UserController;

package/src/templates/project/basic/app/Middleware/ProfilerMiddleware.ts.tpl

@@ -0,0 +1,55 @@
+// @ts-nocheck - Example middleware - WIP
+/**
+ * Profiler Middleware
+ * Enables request profiling when ENABLE_PROFILER environment variable is set
+ */
+
+import { Logger } from '@config/logger';
+import { type Middleware, RequestProfiler } from '@zintrust/core';
+
+/**
+ * ProfilerMiddleware wraps request execution with performance profiling
+ * Enabled via ENABLE_PROFILER=true environment variable
+ * Attaches profiling report to response headers
+ */
+export const ProfilerMiddleware: Middleware = async (req, res, next) => {
+  const isEnabled = process.env.ENABLE_PROFILER === 'true';
+
+  if (!isEnabled) {
+    // Pass through without profiling
+    await next();
+    return;
+  }
+
+  const profiler = RequestProfiler.create();
+  const queryLogger = profiler.getQueryLogger();
+
+  // Set up query logging if database is available
+  const db = req.context.db;
+  if (db !== undefined && db !== null && typeof db.onAfterQuery === 'function') {
+    db.onAfterQuery((sql: string, params: unknown[], duration: number) => {
+      queryLogger.logQuery(sql, params, duration, 'middleware-profiling');
+    });
+  }
+
+  // Capture request execution
+  const profile = await profiler.captureRequest(async () => next());
+
+  // Attach profile to response
+  res.locals.profile = profile;
+
+  // Add profiling report to response header
+  try {
+    const report = profiler.generateReport(profile);
+    res.setHeader('X-Profiler-Report', Buffer.from(report).toString('base64'));
+    res.setHeader('X-Profiler-Queries', profile.queriesExecuted.toString());
+    res.setHeader('X-Profiler-Duration', profile.duration.toString());
+
+    if (profile.n1Patterns.length > 0) {
+      res.setHeader('X-Profiler-N1-Patterns', profile.n1Patterns.length.toString());
+    }
+  } catch (error) {
+    // Silently fail if header encoding fails
+    Logger.error('Failed to encode profiler report header:', error);
+  }
+};

package/src/templates/project/basic/app/Middleware/index.ts.tpl

@@ -0,0 +1,304 @@
+import {
+  type CsrfTokenManagerType,
+  type ICsrfTokenManager,
+  type IJwtManager,
+  type JwtAlgorithm,
+  type JwtManagerType,
+  type IRequest,
+  type IResponse,
+  XssProtection,
+  type ISchema,
+  type SchemaType,
+  Validator,
+} from '@zintrust/core';
+/**
+ * Example Middleware
+ * Common middleware patterns for Zintrust
+ */
+
+import { Logger } from '@config/logger';
+
+type JwtManagerInput = IJwtManager | JwtManagerType;
+type CsrfManagerInput = ICsrfTokenManager | CsrfTokenManagerType;
+
+const resolveJwtManager = (jwtManager: JwtManagerInput): IJwtManager =>
+  'verify' in jwtManager ? jwtManager : jwtManager.create();
+
+const resolveCsrfManager = (csrfManager: CsrfManagerInput): ICsrfTokenManager =>
+  'validateToken' in csrfManager ? csrfManager : csrfManager.create();
+
+type ValidationSchema = ISchema | SchemaType;
+
+const resolveSchema = (schema: ValidationSchema): ISchema =>
+  'getRules' in schema ? schema : schema.create();
+
+/**
+ * Authentication Middleware
+ * Verify user is authenticated
+ */
+export const authMiddleware = async (
+  req: IRequest,
+  res: IResponse,
+  next: () => Promise<void>
+): Promise<void> => {
+  const token = req.getHeader('authorization');
+
+  if (token === undefined || token === '') {
+    res.setStatus(401).json({ error: 'Unauthorized' });
+    return;
+  }
+
+  await next();
+};
+
+/**
+ * CORS Middleware
+ * Handle CORS headers
+ */
+export const corsMiddleware = async (
+  req: IRequest,
+  res: IResponse,
+  next: () => Promise<void>
+): Promise<void> => {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+
+  if (req.getMethod() === 'OPTIONS') {
+    res.setStatus(200).send('');
+    return;
+  }
+
+  await next();
+};
+
+/**
+ * JSON Request Middleware
+ * Parse JSON request bodies
+ */
+export const jsonMiddleware = async (
+  req: IRequest,
+  res: IResponse,
+  next: () => Promise<void>
+): Promise<void> => {
+  if (req.getMethod() === 'GET' || req.getMethod() === 'DELETE') {
+    await next();
+    return;
+  }
+
+  if (req.isJson() === false) {
+    res.setStatus(415).json({ error: 'Content-Type must be application/json' });
+    return;
+  }
+
+  await next();
+};
+
+/**
+ * Logging Middleware
+ * Log all requests
+ */
+export const loggingMiddleware = async (
+  req: IRequest,
+  res: IResponse,
+  next: () => Promise<void>
+): Promise<void> => {
+  const startTime = Date.now();
+  const method = req.getMethod();
+  const path = req.getPath();
+
+  Logger.info(`→ ${method} ${path}`);
+
+  await next();
+
+  const duration = Date.now() - startTime;
+  const status = res.getStatus();
+  Logger.info(`← ${status} ${method} ${path} (${duration}ms)`);
+};
+
+/**
+ * Rate Limiting Middleware
+ * Simple in-memory rate limiting
+ */
+const requestCounts = new Map<string, number[]>();
+
+export const rateLimitMiddleware = async (
+  req: IRequest,
+  res: IResponse,
+  next: () => Promise<void>
+): Promise<void> => {
+  const ip = req.getRaw().socket.remoteAddress ?? 'unknown';
+  const now = Date.now();
+  const windowMs = 60 * 1000; // 1 minute
+  const maxRequests = 100;
+
+  if (requestCounts.has(ip) === false) {
+    requestCounts.set(ip, []);
+  }
+
+  const requests = requestCounts.get(ip) ?? [];
+  const recentRequests = requests.filter((time) => now - time < windowMs);
+
+  if (recentRequests.length >= maxRequests) {
+    res.setStatus(429).json({ error: 'Too many requests' });
+    return;
+  }
+
+  recentRequests.push(now);
+  requestCounts.set(ip, recentRequests);
+
+  await next();
+};
+
+/**
+ * Trailing Slash Middleware
+ * Redirect URLs with trailing slashes
+ */
+export const trailingSlashMiddleware = async (
+  req: IRequest,
+  res: IResponse,
+  next: () => Promise<void>
+): Promise<void> => {
+  const path = req.getPath();
+
+  if (path.length > 1 && path.endsWith('/') === true) {
+    const withoutSlash = path.slice(0, -1);
+    res.redirect(withoutSlash, 301);
+    return;
+  }
+
+  await next();
+};
+
+/**
+ * JWT Authentication Middleware
+ * Verify JWT token and extract claims
+ */
+export const jwtMiddleware = (jwtManager: JwtManagerInput, algorithm: JwtAlgorithm = 'HS256') => {
+  return async (req: IRequest, res: IResponse, next: () => Promise<void>): Promise<void> => {
+    const authHeader = req.getHeader('authorization');
+
+    if (authHeader === undefined || authHeader === '') {
+      res.setStatus(401).json({ error: 'Missing authorization header' });
+      return;
+    }
+
+    const authHeaderStr = Array.isArray(authHeader) ? authHeader[0] : authHeader;
+    const [scheme, token] = authHeaderStr.split(' ');
+
+    if (scheme !== 'Bearer' || token === undefined || token === '') {
+      res.setStatus(401).json({ error: 'Invalid authorization header format' });
+      return;
+    }
+
+    try {
+      const payload = resolveJwtManager(jwtManager).verify(token, algorithm);
+      // Store in request context (TypeScript allows dynamic properties)
+      req.user = payload;
+      await next();
+    } catch (error) {
+      Logger.error('JWT verification failed:', error);
+      res.setStatus(401).json({ error: 'Invalid or expired token' });
+    }
+  };
+};
+
+/**
+ * CSRF Protection Middleware
+ * Validate CSRF tokens for state-changing requests
+ */
+export const csrfMiddleware = (csrfManager: CsrfManagerInput) => {
+  return async (req: IRequest, res: IResponse, next: () => Promise<void>): Promise<void> => {
+    const method = req.getMethod();
+
+    // Only validate on state-changing requests
+    if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(method) === false) {
+      await next();
+      return;
+    }
+
+    const sessionId = req.sessionId ?? req.getHeader('x-session-id');
+
+    if (sessionId === undefined || sessionId === '') {
+      res.setStatus(400).json({ error: 'Missing session ID' });
+      return;
+    }
+
+    const csrfToken = req.getHeader('x-csrf-token');
+
+    if (csrfToken === undefined || csrfToken === '') {
+      res.setStatus(403).json({ error: 'Missing CSRF token' });
+      return;
+    }
+
+    const isValid = resolveCsrfManager(csrfManager).validateToken(
+      String(sessionId),
+      String(csrfToken)
+    );
+
+    if (isValid === false) {
+      res.setStatus(403).json({ error: 'Invalid or expired CSRF token' });
+      return;
+    }
+
+    await next();
+  };
+};
+
+/**
+ * Input Validation Middleware
+ * Validate request body against schema
+ */
+export const validationMiddleware = (schema: SchemaType) => {
+  return async (req: IRequest, res: IResponse, next: () => Promise<void>): Promise<void> => {
+    if (req.getMethod() === 'GET' || req.getMethod() === 'DELETE') {
+      await next();
+      return;
+    }
+
+    try {
+      const body = req.body ?? {};
+      Validator.validate(body, resolveSchema(schema));
+      await next();
+    } catch (error: unknown) {
+      Logger.error('Validation error:', error);
+      const newError = error as Error & { toObject?: () => Record<string, unknown> };
+      if (
+        error !== undefined &&
+        'toObject' in newError &&
+        typeof newError.toObject === 'function'
+      ) {
+        res.setStatus(422).json({ errors: newError.toObject() });
+      } else {
+        res.setStatus(400).json({ error: 'Invalid request body' });
+      }
+    }
+  };
+};
+
+/**
+ * XSS Protection Middleware
+ * Sanitize and escape user input
+ */
+export const xssProtectionMiddleware = async (
+  req: IRequest,
+  res: IResponse,
+  next: () => Promise<void>
+): Promise<void> => {
+  // Add XSS protection headers
+  res.setHeader('X-Content-Type-Options', 'nosniff');
+  res.setHeader('X-Frame-Options', 'DENY');
+  res.setHeader('X-XSS-Protection', '1; mode=block');
+
+  // Sanitize request body if present
+  const body = req.body;
+  if (body !== undefined && body !== null && typeof body === 'object') {
+    for (const [key, value] of Object.entries(body)) {
+      if (typeof value === 'string') {
+        body[key] = XssProtection.escape(value);
+      }
+    }
+  }
+
+  await next();
+};