@zintrust/core 0.1.5 → 0.1.7

package/src/templates/adapters/PostgreSQLAdapter.ts.tpl

@@ -1,4 +1,3 @@
-// TEMPLATE_START
 /* eslint-disable @typescript-eslint/require-await */
 /**
  * PostgreSQL Database Adapter
@@ -102,5 +101,3 @@ export const PostgreSQLAdapter = Object.freeze({
 });
 
 export default PostgreSQLAdapter;
-
-// TEMPLATE_END

package/src/templates/adapters/SQLServerAdapter.ts.tpl

@@ -1,4 +1,3 @@
-// TEMPLATE_START
 /* eslint-disable @typescript-eslint/require-await */
 /**
  * SQL Server Database Adapter
@@ -97,4 +96,3 @@ export const SQLServerAdapter = Object.freeze({
 });
 
 export default SQLServerAdapter;
-// TEMPLATE_END

package/src/templates/adapters/SQLiteAdapter.ts.tpl

@@ -1,4 +1,3 @@
-// TEMPLATE_START
 /* eslint-disable @typescript-eslint/require-await */
 /**
  * SQLite Database Adapter
@@ -191,4 +190,3 @@ function createSQLiteAdapter(config: DatabaseConfig): IDatabaseAdapter {
 export const SQLiteAdapter = Object.freeze({
   create: createSQLiteAdapter,
 });
-// TEMPLATE_END

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

@@ -8,10 +8,18 @@
 # Environment: development | staging | production
 NODE_ENV=development
 
+# Application Name
+APP_NAME=Zintrust App
+
 # Server Configuration
 HOST=
 PORT=
 
+# Application Encryption Key (base64 required for production)
+# Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+# Used for: encryption, CSRF tokens, session tokens, API keys
+APP_KEY=
+
 # ============================================================================
 # DATABASE
 # ============================================================================
@@ -156,4 +164,3 @@ DB_SYNCHRONIZE=
 
 # Database Logging
 DB_LOGGING=
-

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

@@ -4,8 +4,9 @@
  */
 
 import { User } from '@app/Models/User';
-import { Logger } from '@config/logger';
-import { type IRequest, type IResponse } from '@zintrust/core';
+import { Logger } from '@zintrust/core';
+import { IRequest } from '@zintrust/core';
+import { IResponse } from '@zintrust/core';
 
 /**
  * User Controller Interface

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

@@ -4,8 +4,9 @@
  * Enables request profiling when ENABLE_PROFILER environment variable is set
  */
 
-import { Logger } from '@config/logger';
-import { type Middleware, RequestProfiler } from '@zintrust/core';
+import { Logger } from '@zintrust/core';
+import { Middleware } from '@zintrust/core';
+import { RequestProfiler } from '@zintrust/core';
 
 /**
  * ProfilerMiddleware wraps request execution with performance profiling

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

@@ -1,22 +1,16 @@
-import {
-  type CsrfTokenManagerType,
-  type ICsrfTokenManager,
-  type IJwtManager,
-  type JwtAlgorithm,
-  type JwtManagerType,
-  type IRequest,
-  type IResponse,
-  XssProtection,
-  type ISchema,
-  type SchemaType,
-  Validator,
-} from '@zintrust/core';
+import type { CsrfTokenManagerType, ICsrfTokenManager } from '@zintrust/core';
+import type { IJwtManager, JwtAlgorithm, JwtManagerType } from '@zintrust/core';
 /**
  * Example Middleware
  * Common middleware patterns for Zintrust
  */
 
-import { Logger } from '@config/logger';
+import { Logger } from '@zintrust/core';
+import { IRequest } from '@zintrust/core';
+import { IResponse } from '@zintrust/core';
+import { XssProtection } from '@zintrust/core';
+import type { ISchema, SchemaType } from '@zintrust/core';
+import { Validator } from '@zintrust/core';
 
 type JwtManagerInput = IJwtManager | JwtManagerType;
 type CsrfManagerInput = ICsrfTokenManager | CsrfTokenManagerType;

package/src/templates/project/basic/app/Models/Post.ts.tpl

@@ -2,8 +2,9 @@
  * Example Post Model
  */
 
+import { IRelationship } from '@zintrust/core';
 import { User } from '@app/Models/User';
-import { type IModel, Model, type ModelConfig, type IRelationship } from '@zintrust/core';
+import { IModel, Model, ModelConfig } from '@zintrust/core';
 
 export const PostConfig: ModelConfig = {
   table: 'posts',

package/src/templates/project/basic/app/Models/User.ts.tpl

@@ -3,7 +3,7 @@
  */
 
 import { Post } from '@app/Models/Post';
-import { type IModel, Model } from '@zintrust/core';
+import { IModel, Model } from '@zintrust/core';
 
 /**
  * User Model Definition

package/src/templates/project/basic/app/Toolkit/Broadcast/sendBroadcast.ts.tpl

@@ -1,4 +1,4 @@
-import { Broadcast } from '@broadcast/Broadcast';
+import { Broadcast } from '@zintrust/core';
 
 export async function sendBroadcast(channel: string, event: string, data: unknown): Promise<void> {
   await Broadcast.send(channel, event, data);

package/src/templates/project/basic/app/Toolkit/Mail/sendWelcomeEmail.ts.tpl

@@ -1,4 +1,4 @@
-import { Mail } from '@mail/Mail';
+import { Mail } from '@zintrust/core';
 
 export async function sendWelcomeEmail(
   to: string,

package/src/templates/project/basic/app/Toolkit/Notification/sendSlackNotification.ts.tpl

@@ -1,4 +1,4 @@
-import { sendSlackWebhook } from '@notification/drivers/Slack';
+import { sendSlackWebhook } from '@zintrust/core';
 
 export async function sendSlackNotification(
   webhookUrl: string,

package/src/templates/project/basic/app/Toolkit/Notification/sendSms.ts.tpl

@@ -1,4 +1,4 @@
-import { sendSms } from '@notification/drivers/Twilio';
+import { sendSms } from '@zintrust/core';
 
 export async function sendSmsNotification(
   accountSid: string,

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

@@ -1,12 +1,10 @@
 /**
  * FileLogWriter (Node.js only)
- *
- * Provides best-effort file logging with daily + size-based rotation.
- * This module imports Node built-ins and should be loaded only in Node environments.
+ * Re-exports core FileLogWriter for optional use
  */
 
 import { ensureDirSafe } from '@zintrust/core';
-import { Env } from '@config/env';
+import { Env } from '@zintrust/core';
 import * as fs from '@node-singletons/fs';
 import * as path from '@node-singletons/path';
 

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

@@ -5,39 +5,16 @@
  */
 
 import { Logger } from '@config/logger';
+import type {
+  GetSecretOptions,
+  SecretConfig,
+  SecretsManagerInstance,
+  SetSecretOptions,
+} from '@config/type';
 import { ErrorFactory } from '@zintrust/core';
 
-export interface CloudflareKV {
-  get(key: string): Promise<string | null>;
-  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
-  delete(key: string): Promise<void>;
-  list(options?: { prefix?: string }): Promise<{ keys: { name: string }[] }>;
-}
-
-export interface SecretConfig {
-  platform: 'aws' | 'cloudflare' | 'deno' | 'local';
-  region?: string;
-  kv?: CloudflareKV; // Cloudflare KV namespace
-}
-
-export interface SecretValue {
-  key: string;
-  value: string;
-  expiresAt?: number;
-  rotationEnabled?: boolean;
-}
-
 let instance: SecretsManagerInstance | undefined;
 
-interface SecretsManagerInstance {
-  getSecret(key: string, options?: GetSecretOptions): Promise<string>;
-  setSecret(key: string, value: string, options?: SetSecretOptions): Promise<void>;
-  deleteSecret(key: string): Promise<void>;
-  rotateSecret(key: string): Promise<void>;
-  listSecrets(pattern?: string): Promise<string[]>;
-  clearCache(key?: string): void;
-}
-
 function pruneCache(
   cache: Map<string, { value: string; expiresAt: number }>,
   maxEntries: number
@@ -433,16 +410,6 @@ export const SECRETS = Object.freeze({
   CSRF_SECRET: 'csrf/secret',
 } as const);
 
-export interface GetSecretOptions {
-  cacheTtl?: number; // Cache time-to-live in milliseconds
-  throwIfMissing?: boolean;
-}
-
-export interface SetSecretOptions {
-  expirationTtl?: number; // Expiration time-to-live in seconds
-  metadata?: Record<string, unknown>;
-}
-
 /**
  * Helper to get database credentials using secrets manager
  */

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

@@ -1,17 +1,7 @@
 import { appConfig } from '@config/app';
+import type { StartupConfigValidationError, StartupConfigValidationResult } from '@config/type';
 import { ErrorFactory } from '@zintrust/core';
 
-export type StartupConfigValidationError = {
-  key: string;
-  value: unknown;
-  message: string;
-};
-
-export type StartupConfigValidationResult = {
-  valid: boolean;
-  errors: StartupConfigValidationError[];
-};
-
 const isSensitiveKey = (key: string): boolean => {
   const normalized = key.toLowerCase();
   return (
@@ -93,47 +83,174 @@ const getEnvString = (key: string, defaultValue: string): string => {
   return env[key] ?? defaultValue;
 };
 
+const getEnvOptionalString = (key: string): string | undefined => {
+  const proc = getProcessLike();
+  const env = proc?.env ?? {};
+  const value = env[key];
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed === '' ? undefined : trimmed;
+};
+
+const getEnvBoolLoose = (key: string, defaultValue: boolean): boolean => {
+  const raw = getEnvOptionalString(key);
+  if (raw === undefined) return defaultValue;
+  const normalized = raw.toLowerCase();
+  return normalized === 'true' || normalized === '1' || normalized === 'yes' || normalized === 'on';
+};
+
 const getEnvInt = (key: string, defaultValue: number): number => {
   const raw = getEnvString(key, String(defaultValue));
   return Number.parseInt(raw, 10);
 };
 
-export const StartupConfigValidator = Object.freeze({
-  validate(): StartupConfigValidationResult {
-    const errors: StartupConfigValidationError[] = [];
+type RequireEnvStringOptions = {
+  aliases?: readonly string[];
+  requiredMessage?: string;
+  minLength?: number;
+  minLengthMessage?: string;
+};
+
+const requireEnvString = (
+  errors: StartupConfigValidationError[],
+  key: string,
+  options: RequireEnvStringOptions = {}
+): string | undefined => {
+  const value =
+    getEnvOptionalString(key) ??
+    (options.aliases ?? []).reduce<string | undefined>((found, alias) => {
+      if (found !== undefined) return found;
+      return getEnvOptionalString(alias);
+    }, undefined);
+
+  if (value === undefined) {
+    pushError(errors, key, value, options.requiredMessage ?? `${key} is required`);
+    return undefined;
+  }
+
+  if (options.minLength !== undefined && value.length < options.minLength) {
+    pushError(
+      errors,
+      key,
+      value,
+      options.minLengthMessage ?? `${key} must be at least ${options.minLength} characters`
+    );
+  }
+
+  return value;
+};
+
+const validateSqliteDbFileRequired = (
+  errors: StartupConfigValidationError[],
+  dbConnection: string | undefined
+): void => {
+  // sqlite convenience: accept DB_DATABASE or DB_PATH
+  if ((dbConnection ?? '').toLowerCase() !== 'sqlite') return;
+
+  const dbFile = getEnvOptionalString('DB_DATABASE') ?? getEnvOptionalString('DB_PATH');
+  if (dbFile === undefined) {
+    pushError(errors, 'DB_DATABASE', dbFile, 'DB_DATABASE (or DB_PATH) is required for sqlite');
+  }
+};
+
+const validateStrictRequiredEnv = (errors: StartupConfigValidationError[]): void => {
+  const requireEnv = getEnvBoolLoose('STARTUP_REQUIRE_ENV', false);
+  if (!requireEnv) return;
+
+  requireEnvString(errors, 'NODE_ENV');
+  requireEnvString(errors, 'APP_NAME');
+  requireEnvString(errors, 'HOST');
+
+  const portRaw = requireEnvString(errors, 'PORT', {
+    aliases: ['APP_PORT'],
+    requiredMessage: 'PORT (or APP_PORT) is required',
+  });
+  if (portRaw !== undefined) {
+    const port = Number.parseInt(portRaw, 10);
+    validateIntRange(errors, 'PORT', port, 1, 65535);
+  }
+
+  const dbConnection = requireEnvString(errors, 'DB_CONNECTION');
+
+  requireEnvString(errors, 'APP_KEY', { minLength: 16 });
+  requireEnvString(errors, 'LOG_LEVEL');
+  requireEnvString(errors, 'LOG_CHANNEL');
 
-    const nodeEnv = getEnvString('NODE_ENV', 'development');
-    validateEnum(errors, 'NODE_ENV', nodeEnv, ['development', 'production', 'testing', 'test']);
+  validateSqliteDbFileRequired(errors, dbConnection);
+};
+
+const validateNodeEnv = (errors: StartupConfigValidationError[]): void => {
+  const nodeEnv = getEnvString('NODE_ENV', 'development');
+  validateEnum(errors, 'NODE_ENV', nodeEnv, ['development', 'production', 'testing', 'test']);
+};
+
+const validatePort = (errors: StartupConfigValidationError[]): void => {
+  // Port can be provided as PORT or APP_PORT. In non-strict mode we keep defaults.
+  const portFromPort = getEnvOptionalString('PORT');
+  const portFromAppPort = getEnvOptionalString('APP_PORT');
+  const portRaw = portFromPort ?? portFromAppPort;
 
+  if (portRaw === undefined) {
     const appPort = getEnvInt('APP_PORT', 3000);
     validateIntRange(errors, 'APP_PORT', appPort, 1, 65535);
+    return;
+  }
+
+  const parsed = Number.parseInt(portRaw, 10);
+  const key = portFromPort === undefined ? 'APP_PORT' : 'PORT';
+  validateIntRange(errors, key, parsed, 1, 65535);
+};
+
+const validateLogging = (errors: StartupConfigValidationError[]): void => {
+  const logFormat = getEnvString('LOG_FORMAT', 'text');
+  validateEnum(errors, 'LOG_FORMAT', logFormat, ['text', 'json']);
+
+  const logLevel = getEnvString('LOG_LEVEL', 'debug');
+  validateEnum(errors, 'LOG_LEVEL', logLevel, ['debug', 'info', 'warn', 'error']);
+
+  // Optional (but validated when provided): LOG_CHANNEL (starter apps often use this)
+  const logChannel = getEnvOptionalString('LOG_CHANNEL');
+  if (logChannel !== undefined) {
+    validateEnum(errors, 'LOG_CHANNEL', logChannel, ['console', 'file', 'all']);
+  }
+};
+
+const validateRotationAndTimeout = (errors: StartupConfigValidationError[]): void => {
+  const logRotationSize = getEnvInt('LOG_ROTATION_SIZE', 10485760);
+  validatePositiveInt(errors, 'LOG_ROTATION_SIZE', logRotationSize);
 
-    const logFormat = getEnvString('LOG_FORMAT', 'text');
-    validateEnum(errors, 'LOG_FORMAT', logFormat, ['text', 'json']);
+  const logRotationDays = getEnvInt('LOG_ROTATION_DAYS', 7);
+  validatePositiveInt(errors, 'LOG_ROTATION_DAYS', logRotationDays);
 
-    const logLevel = getEnvString('LOG_LEVEL', 'debug');
-    validateEnum(errors, 'LOG_LEVEL', logLevel, ['debug', 'info', 'warn', 'error']);
+  const startupHealthTimeoutMs = getEnvInt('STARTUP_HEALTH_TIMEOUT_MS', 2500);
+  validatePositiveInt(errors, 'STARTUP_HEALTH_TIMEOUT_MS', startupHealthTimeoutMs);
+};
+
+const validateProductionAppKey = (errors: StartupConfigValidationError[]): void => {
+  if (!appConfig.isProduction()) return;
 
-    const logRotationSize = getEnvInt('LOG_ROTATION_SIZE', 10485760);
-    validatePositiveInt(errors, 'LOG_ROTATION_SIZE', logRotationSize);
+  const appKey = getEnvString('APP_KEY', '');
+  if (appKey.trim().length < 16) {
+    pushError(
+      errors,
+      'APP_KEY',
+      appKey,
+      'APP_KEY must be set and at least 16 characters in production'
+    );
+  }
+};
 
-    const logRotationDays = getEnvInt('LOG_ROTATION_DAYS', 7);
-    validatePositiveInt(errors, 'LOG_ROTATION_DAYS', logRotationDays);
+export const StartupConfigValidator = Object.freeze({
+  validate(): StartupConfigValidationResult {
+    const errors: StartupConfigValidationError[] = [];
 
-    const startupHealthTimeoutMs = getEnvInt('STARTUP_HEALTH_TIMEOUT_MS', 2500);
-    validatePositiveInt(errors, 'STARTUP_HEALTH_TIMEOUT_MS', startupHealthTimeoutMs);
+    validateStrictRequiredEnv(errors);
 
-    if (appConfig.isProduction()) {
-      const appKey = getEnvString('APP_KEY', '');
-      if (appKey.trim().length < 16) {
-        pushError(
-          errors,
-          'APP_KEY',
-          appKey,
-          'APP_KEY must be set and at least 16 characters in production'
-        );
-      }
-    }
+    validateNodeEnv(errors);
+    validatePort(errors);
+    validateLogging(errors);
+    validateRotationAndTimeout(errors);
+    validateProductionAppKey(errors);
 
     return { valid: errors.length === 0, errors };
   },

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

@@ -5,11 +5,7 @@
  */
 
 import { Env } from '@config/env';
-
-type ProcessLike = { env?: Record<string, string | undefined> };
-
-type Environment = 'development' | 'dev' | 'production' | 'prod' | 'pro' | 'testing' | 'test';
-type StartMode = 'development' | 'production' | 'testing';
+import type { Environment, ProcessLike, StartMode } from '@config/type';
 
 const getProcessLike = (): ProcessLike | undefined => {
   return typeof process === 'undefined' ? undefined : (process as unknown as ProcessLike);

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

@@ -6,42 +6,12 @@
  */
 
 import { Env } from '@config/env';
-
-export type KnownBroadcastDriverName = 'inmemory' | 'pusher' | 'redis' | 'redishttps';
-
-export type InMemoryBroadcastDriverConfig = {
-  driver: 'inmemory';
-};
-
-export type PusherBroadcastDriverConfig = {
-  driver: 'pusher';
-  appId: string;
-  key: string;
-  secret: string;
-  cluster: string;
-  useTLS: boolean;
-};
-
-export type RedisBroadcastDriverConfig = {
-  driver: 'redis';
-  host: string;
-  port: number;
-  password: string;
-  channelPrefix: string;
-};
-
-export type RedisHttpsBroadcastDriverConfig = {
-  driver: 'redishttps';
-  endpoint: string;
-  token: string;
-  channelPrefix: string;
-};
-
-export type KnownBroadcastDriverConfig =
-  | InMemoryBroadcastDriverConfig
-  | PusherBroadcastDriverConfig
-  | RedisBroadcastDriverConfig
-  | RedisHttpsBroadcastDriverConfig;
+import {
+  KnownBroadcastDriverConfig,
+  PusherBroadcastDriverConfig,
+  RedisBroadcastDriverConfig,
+  RedisHttpsBroadcastDriverConfig,
+} from '@config/type';
 
 const normalizeDriverName = (value: string): string => value.trim().toLowerCase();
 

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

@@ -5,48 +5,7 @@
  */
 
 import { Env } from '@config/env';
-
-type MemoryCacheDriverConfig = {
-  driver: 'memory';
-  ttl: number;
-};
-
-type RedisCacheDriverConfig = {
-  driver: 'redis';
-  host: string;
-  port: number;
-  ttl: number;
-};
-
-type MongoCacheDriverConfig = {
-  driver: 'mongodb';
-  uri: string;
-  db: string;
-  ttl: number;
-};
-
-type KvCacheDriverConfig = {
-  driver: 'kv';
-  ttl: number;
-};
-
-type CacheDriverConfig =
-  | MemoryCacheDriverConfig
-  | RedisCacheDriverConfig
-  | MongoCacheDriverConfig
-  | KvCacheDriverConfig;
-
-type CacheDrivers = {
-  memory: MemoryCacheDriverConfig;
-  redis: RedisCacheDriverConfig;
-  mongodb: MongoCacheDriverConfig;
-  kv: KvCacheDriverConfig;
-};
-
-type CacheConfigInput = {
-  default: string;
-  drivers: CacheDrivers;
-};
+import { CacheConfigInput, CacheDriverConfig, CacheDrivers } from '@config/type';
 
 const getCacheDriver = (config: CacheConfigInput): CacheDriverConfig => {
   const defaultDriver = config.default;

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

@@ -5,23 +5,9 @@
  * This keeps runtime-specific globals out of adapters/drivers.
  */
 
+import { KVNamespace, WorkersEnv } from '@config/type';
 import type { DatabaseConfig, ID1Database } from '@zintrust/core';
 
-export type WorkersEnv = Record<string, unknown>;
-
-type KVNamespace = {
-  get(
-    key: string,
-    options?: { type: 'text' | 'json' | 'arrayBuffer' | 'stream' }
-  ): Promise<unknown>;
-  put(
-    key: string,
-    value: string | ReadableStream | ArrayBuffer | FormData,
-    options?: { expiration?: number; expirationTtl?: number; metadata?: unknown }
-  ): Promise<void>;
-  delete(key: string): Promise<void>;
-};
-
 const getWorkersEnv = (): WorkersEnv | null => {
   const env = (globalThis as unknown as { env?: unknown }).env;
   if (env === undefined || env === null) return null;

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

@@ -5,57 +5,11 @@
  */
 
 import { Env } from '@config/env';
-
-type SqliteConnectionConfig = {
-  driver: 'sqlite';
-  database: string;
-  migrations: string;
-};
-
-type PostgresqlConnectionConfig = {
-  driver: 'postgresql';
-  host: string;
-  port: number;
-  database: string;
-  username: string;
-  password: string;
-  ssl: boolean;
-  pooling: {
-    enabled: boolean;
-    min: number;
-    max: number;
-    idleTimeout: number;
-    connectionTimeout: number;
-  };
-};
-
-type MysqlConnectionConfig = {
-  driver: 'mysql';
-  host: string;
-  port: number;
-  database: string;
-  username: string;
-  password: string;
-  pooling: {
-    enabled: boolean;
-    min: number;
-    max: number;
-  };
-};
-
-type DatabaseConnections = {
-  sqlite: SqliteConnectionConfig;
-  postgresql: PostgresqlConnectionConfig;
-  mysql: MysqlConnectionConfig;
-};
-
-type DatabaseConnectionName = keyof DatabaseConnections;
-type DatabaseConnectionConfig = DatabaseConnections[DatabaseConnectionName];
-
-type DatabaseConfigShape = {
-  default: DatabaseConnectionName;
-  connections: DatabaseConnections;
-};
+import {
+  DatabaseConfigShape,
+  DatabaseConnectionConfig,
+  DatabaseConnectionName,
+} from '@config/type';
 
 const isDatabaseConnectionName = (value: string): value is DatabaseConnectionName => {
   return value === 'sqlite' || value === 'postgresql' || value === 'mysql';