@zintrust/core 0.1.26 → 0.1.28

package/src/config/queue.ts

@@ -0,0 +1,205 @@
+/**
+ * Queue Configuration
+ * Background job and message queue settings
+ * Sealed namespace for immutability
+ */
+
+import { Env } from '@config/env';
+
+import type { QueueConfigWithDrivers, QueueDriverName, QueueDriversConfig } from '@config/type';
+import { StartupConfigFile, StartupConfigFileRegistry } from '@runtime/StartupConfigFileRegistry';
+
+export type QueueConfigOverrides = Partial<{
+  default: QueueDriverName;
+  drivers: Partial<QueueDriversConfig>;
+  failed: { database: string; table: string };
+  processing: { timeout: number; retries: number; backoff: number; workers: number };
+  monitor: {
+    enabled: boolean;
+    basePath: string;
+    middleware: ReadonlyArray<string>;
+    autoRefresh: boolean;
+    refreshIntervalMs: number;
+  };
+}>;
+
+const getQueueDriver = (config: QueueConfigWithDrivers): QueueDriversConfig[QueueDriverName] => {
+  const driverName = config.default;
+  return config.drivers[driverName];
+};
+
+/**
+ * Helper: Create base driver configurations from environment
+ */
+export const createBaseDrivers = (): QueueDriversConfig => ({
+  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'),
+  },
+});
+
+/**
+ * Helper: Create monitor configuration from environment
+ */
+const createBaseMonitor = (): {
+  enabled: boolean;
+  basePath: string;
+  middleware: ReadonlyArray<string>;
+  autoRefresh: boolean;
+  refreshIntervalMs: number;
+} => ({
+  enabled: Env.getBool('QUEUE_MONITOR_ENABLED', true),
+  basePath: Env.get('QUEUE_MONITOR_BASE_PATH', '/queue-monitor'),
+  middleware: Env.get('QUEUE_MONITOR_MIDDLEWARE', '')
+    .split(',')
+    .map((m: string) => m.trim())
+    .filter((m: string | string[]) => m.length > 0) as ReadonlyArray<string>,
+  autoRefresh: Env.getBool('QUEUE_MONITOR_AUTO_REFRESH', true),
+  refreshIntervalMs: Env.getInt('QUEUE_MONITOR_REFRESH_MS', 5000),
+});
+
+const createQueueConfig = (): {
+  default: QueueDriverName;
+  drivers: QueueDriversConfig;
+  getDriver: (this: QueueConfigWithDrivers) => QueueDriversConfig[QueueDriverName];
+  failed: { database: string; table: string };
+  processing: { timeout: number; retries: number; backoff: number; workers: number };
+  monitor: {
+    enabled: boolean;
+    basePath: string;
+    middleware: ReadonlyArray<string>;
+    autoRefresh: boolean;
+    refreshIntervalMs: number;
+  };
+} => {
+  const overrides: QueueConfigOverrides =
+    StartupConfigFileRegistry.get<QueueConfigOverrides>(StartupConfigFile.Queue) ?? {};
+
+  const baseDefault = Env.get('QUEUE_DRIVER', 'sync') as QueueDriverName;
+  const baseDrivers = createBaseDrivers();
+
+  const baseFailed = {
+    database: Env.get('FAILED_JOBS_DB_CONNECTION', 'default'),
+    table: Env.get('FAILED_JOBS_TABLE', 'failed_jobs'),
+  };
+
+  const baseProcessing = {
+    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),
+  };
+
+  const baseMonitor = createBaseMonitor();
+
+  const mergedDrivers = {
+    ...baseDrivers,
+    ...overrides.drivers,
+  } satisfies QueueDriversConfig;
+
+  const queueConfigObj = {
+    /**
+     * Default queue driver
+     */
+    default: overrides.default ?? baseDefault,
+
+    /**
+     * Queue drivers
+     */
+    drivers: mergedDrivers,
+
+    /**
+     * Get queue driver config
+     */
+    getDriver(): QueueDriversConfig[QueueDriverName] {
+      return getQueueDriver(this);
+    },
+
+    /**
+     * Failed jobs table
+     */
+    failed: {
+      ...baseFailed,
+      ...overrides.failed,
+    },
+
+    /**
+     * Job processing
+     */
+    processing: {
+      ...baseProcessing,
+      ...overrides.processing,
+    },
+
+    /**
+     * Queue Monitor settings
+     */
+    monitor: {
+      ...baseMonitor,
+      ...overrides.monitor,
+    },
+  };
+
+  return Object.freeze(queueConfigObj);
+};
+
+export type QueueConfig = ReturnType<typeof createQueueConfig>;
+
+let cached: QueueConfig | null = null;
+const proxyTarget: QueueConfig = {} as QueueConfig;
+
+const ensureQueueConfig = (): QueueConfig => {
+  if (cached) return cached;
+  cached = createQueueConfig();
+
+  try {
+    Object.defineProperties(
+      proxyTarget as unknown as object,
+      Object.getOwnPropertyDescriptors(cached)
+    );
+  } catch {
+    // best-effort
+  }
+
+  return cached;
+};
+
+export const queueConfig: QueueConfig = new Proxy(proxyTarget, {
+  get(_target, prop: keyof QueueConfig) {
+    return ensureQueueConfig()[prop];
+  },
+  ownKeys() {
+    ensureQueueConfig();
+    return Reflect.ownKeys(proxyTarget as unknown as object);
+  },
+  getOwnPropertyDescriptor(_target, prop) {
+    ensureQueueConfig();
+    return Object.getOwnPropertyDescriptor(proxyTarget as unknown as object, prop);
+  },
+});

package/src/config/redis.ts

@@ -0,0 +1,84 @@
+import { Env } from '@config/env';
+import type { RedisBroadcastDriverConfig } from '@config/type';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import type { QueueMessage } from '@tools/queue/Queue';
+import { Queue } from '@tools/queue/Queue';
+
+export type QueueDriver = {
+  enqueue<T = unknown>(queue: string, payload: T): Promise<string>;
+  dequeue<T = unknown>(queue: string): Promise<QueueMessage<T> | undefined>;
+  ack(queue: string, id: string): Promise<void>;
+  length(queue: string): Promise<number>;
+  drain(queue: string): Promise<void>;
+};
+
+export type RedisPublishClient = {
+  connect?: () => Promise<void>;
+  publish(channel: string, message: string): Promise<number>;
+};
+
+export const buildRedisUrl = (config?: RedisBroadcastDriverConfig): string => {
+  // Otherwise build URL from individual settings (like cache driver)
+  const host = config?.host ?? Env.get('REDIS_HOST', 'localhost');
+  const port = config?.port ?? Env.getInt('REDIS_PORT', 6379);
+  const password = config?.password ?? Env.get('REDIS_PASSWORD');
+  const database = config?.database ?? Env.getInt('REDIS_QUEUE_DB', 1);
+  let redisUrl = `redis://`;
+  if (password) redisUrl += `:${password}@`;
+  redisUrl += `${host}:${port}`;
+  if (database > 0) redisUrl += `/${database}`;
+
+  return redisUrl;
+};
+
+export const getRedisUrl = (config?: RedisBroadcastDriverConfig): string | null => {
+  const fromEnv = Env.get('REDIS_URL', '');
+  const hasProcess = typeof process === 'object' && process !== null;
+  const fallback = hasProcess ? (process.env?.['REDIS_URL'] ?? '') : '';
+  const trimmed = fromEnv.trim();
+  const url = (trimmed.length > 0 ? fromEnv : String(fallback)).trim();
+
+  // If REDIS_URL exists, use it
+  if (url.length > 0) return url;
+
+  return buildRedisUrl(config);
+};
+
+export const ensureDriver = async <T = QueueDriver>(type?: 'queue' | 'publish'): Promise<T> => {
+  if (type === 'publish') {
+    // Return Redis publish client with publish() method from package
+    const mod = (await import('@zintrust/queue-redis')) as unknown as {
+      createRedisPublishClient?: () => Promise<RedisPublishClient>;
+    };
+
+    if (mod.createRedisPublishClient) {
+      return mod.createRedisPublishClient() as T;
+    }
+
+    throw ErrorFactory.createConfigError(
+      'Redis publish client is not available in queue-redis package'
+    );
+  }
+
+  // Return queue driver (current behavior)
+  try {
+    return Queue.get('redis') as T;
+  } catch {
+    try {
+      const mod = (await import('@zintrust/queue-redis')) as unknown as {
+        RedisQueue?: QueueDriver;
+      };
+
+      if (mod.RedisQueue !== undefined) {
+        Queue.register('redis', mod.RedisQueue);
+      }
+
+      return Queue.get('redis') as T;
+    } catch (error) {
+      throw ErrorFactory.createConfigError(
+        'Redis queue driver is not registered. Install queue:redis via zin plugin install.',
+        error as Error
+      );
+    }
+  }
+};

package/src/config/security.ts

@@ -0,0 +1,170 @@
+/**
+ * Security Configuration
+ * JWT, CSRF, encryption and other security settings
+ * Sealed namespace for immutability
+ *
+ * APP_KEY: Primary encryption key for storage signing and app-level encryption.
+ *          Set automatically during project scaffolding.
+ *
+ * Security keys can be configured per domain:
+ * - APP_KEY: Default encryption key for all operations (auto-generated)
+ * - API_KEY_SECRET: Optional API key authentication (if API_KEY_ENABLED=true)
+ * - ENCRYPTION_CIPHER: Cipher for encrypted envelope interoperability
+ * - JWT_SECRET: JWT token signing key
+ *
+ * Developers can use a single APP_KEY or configure separate keys for different
+ * security domains (e.g., different keys for different microservices).
+ */
+
+import { appConfig } from '@config/app';
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+/**
+ * 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.');
+  if (appConfig.isProduction()) {
+    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') || Env.get('APP_KEY') || warnMissingSecret('JWT_SECRET')
+        : Env.get('JWT_SECRET') || Env.get('APP_KEY') || '';
+      return cachedJwtSecret;
+    },
+    algorithm: Env.get('JWT_ALGORITHM', 'HS256') as 'HS256' | 'HS512' | 'RS256',
+    expiresIn: Env.getInt('JWT_EXPIRES_IN', 60 * 60),
+    refreshExpiresIn: Env.get('JWT_REFRESH_EXPIRES_IN', '7d'),
+    issuer: Env.get('JWT_ISSUER', 'zintrust'),
+    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: {
+    // Required for framework-compatible encrypted payloads.
+    // Supported values: aes-256-cbc | aes-256-gcm (case-insensitive)
+    cipher: Env.get('ENCRYPTION_CIPHER', ''),
+
+    // Primary key used for encryption interoperability (framework-compatible envelopes).
+    // APP_KEY supports both `base64:...` and raw base64.
+    appKey: Env.get('APP_KEY', ''),
+    appPreviousKeys: Env.get('APP_PREVIOUS_KEYS', ''),
+
+    // Back-compat fields (not used by EncryptedEnvelope)
+    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', false),
+    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/config/startup.ts

@@ -0,0 +1,29 @@
+/**
+ * Startup Configuration
+ *
+ * Startup-only controls (evaluated during Application.boot()).
+ */
+
+import { Env } from '@config/env';
+
+export type StartupConfig = {
+  healthChecksEnabled: boolean;
+  validateSecrets: boolean;
+  requireEnv: boolean;
+  checkDatabase: boolean;
+  checkCache: boolean;
+  timeoutMs: number;
+  continueOnFailure: boolean;
+};
+
+export const startupConfig = Object.freeze({
+  healthChecksEnabled: Env.getBool('STARTUP_HEALTH_CHECKS', true),
+  validateSecrets: Env.getBool('STARTUP_VALIDATE_SECRETS', true),
+  requireEnv: Env.getBool('STARTUP_REQUIRE_ENV', false),
+  checkDatabase: Env.getBool('STARTUP_CHECK_DB', false),
+  checkCache: Env.getBool('STARTUP_CHECK_CACHE', false),
+  timeoutMs: Env.getInt('STARTUP_HEALTH_TIMEOUT_MS', 2500),
+  continueOnFailure: Env.getBool('STARTUP_CONTINUE_ON_FAILURE', false),
+} satisfies StartupConfig);
+
+export default startupConfig;

package/src/config/storage.ts

@@ -0,0 +1,205 @@
+/**
+ * Storage Configuration
+ * File storage and cloud storage settings
+ * Sealed namespace for immutability
+ */
+
+import { Env } from '@config/env';
+import type { StorageConfigRuntime, StorageDriverConfig, StorageDrivers } from '@config/type';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { StartupConfigFile, StartupConfigFileRegistry } from '@runtime/StartupConfigFileRegistry';
+
+export type StorageConfigOverrides = Partial<{
+  default: string;
+  drivers: Partial<StorageDrivers> & Record<string, StorageDriverConfig>;
+  temp: { path: string; maxAge: number };
+  uploads: { maxSize: string; allowedMimes: string; path: string };
+  backups: { path: string; driver: string };
+}>;
+
+type StorageRuntimeConfig = StorageConfigRuntime & {
+  getDriver: (this: StorageConfigRuntime) => StorageDriverConfig;
+  getDriverConfig: (this: StorageConfigRuntime, name?: string) => StorageDriverConfig;
+  temp: { path: string; maxAge: number };
+  uploads: { maxSize: string; allowedMimes: string; path: string };
+  backups: { path: string; driver: string };
+};
+const hasOwn = <T extends object>(obj: T, key: PropertyKey): key is keyof T => {
+  return Object.hasOwn(obj, key);
+};
+
+const getStorageDriver = (config: StorageConfigRuntime, name?: string): StorageDriverConfig => {
+  const selected = String(name ?? config.default).trim();
+  const diskName = selected === 'default' ? String(config.default).trim() : selected;
+  const isExplicitSelection =
+    name !== undefined && String(name).trim().length > 0 && String(name).trim() !== 'default';
+
+  if (diskName !== '' && hasOwn(config.drivers, diskName)) {
+    const resolved = config.drivers[diskName];
+    if (resolved !== undefined) return resolved;
+  }
+
+  if (isExplicitSelection) {
+    throw ErrorFactory.createConfigError(`Storage disk not configured: ${diskName}`);
+  }
+
+  if (Object.keys(config.drivers ?? {}).length === 0) {
+    throw ErrorFactory.createConfigError('No storage disks are configured');
+  }
+
+  throw ErrorFactory.createConfigError(
+    `Storage default disk not configured: ${diskName || '<empty>'}`
+  );
+};
+
+const getDrivers = (): StorageDrivers => ({
+  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,
+    accessKeyId: Env.get('AWS_ACCESS_KEY_ID', ''),
+    secretAccessKey: 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),
+  },
+  r2: {
+    driver: 'r2' as const,
+    accessKeyId: Env.get('R2_ACCESS_KEY_ID', ''),
+    secretAccessKey: Env.get('R2_SECRET_ACCESS_KEY', ''),
+    region: Env.get('R2_REGION', ''),
+    bucket: Env.get('R2_BUCKET', ''),
+    endpoint: Env.get('R2_ENDPOINT', ''),
+    url: Env.get('R2_URL', ''),
+  },
+  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', ''),
+  },
+});
+
+const createStorageConfig = (): StorageRuntimeConfig => {
+  const overrides: StorageConfigOverrides =
+    StartupConfigFileRegistry.get<StorageConfigOverrides>(StartupConfigFile.Storage) ?? {};
+
+  const storageConfigObj: StorageRuntimeConfig = {
+    /**
+     * Default storage driver (dynamic; tests may mutate process.env)
+     */
+    get default(): string {
+      const base = Env.get('STORAGE_CONNECTION', Env.get('STORAGE_DRIVER', 'local'))
+        .trim()
+        .toLowerCase();
+      const selected = overrides.default ?? base;
+      return String(selected).trim().toLowerCase();
+    },
+
+    /**
+     * Storage drivers configuration (dynamic; tests may mutate process.env)
+     */
+    get drivers(): StorageDrivers {
+      return {
+        ...getDrivers(),
+        ...overrides.drivers,
+      } as StorageDrivers;
+    },
+
+    /**
+     * Get storage driver config
+     */
+    getDriver(this: StorageConfigRuntime): StorageDriverConfig {
+      return getStorageDriver(this);
+    },
+
+    /**
+     * Get a storage disk configuration by name.
+     *
+     * - When `name` is provided and not configured, this throws.
+     * - When `name` is omitted, it resolves the configured default with a backwards-compatible fallback.
+     * - Reserved name `default` aliases the configured default.
+     */
+    getDriverConfig(this: StorageConfigRuntime, name?: string): StorageDriverConfig {
+      return getStorageDriver(this, name);
+    },
+
+    /**
+     * Temporary file settings
+     */
+    get temp(): { path: string; maxAge: number } {
+      return {
+        path: Env.get('TEMP_PATH', 'storage/temp'),
+        maxAge: Env.getInt('TEMP_FILE_MAX_AGE', 86400), // 24 hours
+        ...overrides.temp,
+      };
+    },
+
+    /**
+     * Uploads settings
+     */
+    get uploads(): { maxSize: string; allowedMimes: string; path: string } {
+      return {
+        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'),
+        ...overrides.uploads,
+      };
+    },
+
+    /**
+     * Backups settings
+     */
+    get backups(): { path: string; driver: string } {
+      return {
+        path: Env.get('BACKUPS_PATH', 'storage/backups'),
+        driver: Env.get('BACKUP_DRIVER', 's3'),
+        ...overrides.backups,
+      };
+    },
+  };
+
+  return Object.freeze(storageConfigObj);
+};
+
+export type StorageConfig = ReturnType<typeof createStorageConfig>;
+
+let cached: StorageConfig | null = null;
+const proxyTarget: StorageConfig = {} as StorageConfig;
+
+const ensureStorageConfig = (): StorageConfig => {
+  if (cached) return cached;
+  cached = createStorageConfig();
+
+  try {
+    Object.defineProperties(
+      proxyTarget as unknown as object,
+      Object.getOwnPropertyDescriptors(cached)
+    );
+  } catch {
+    // best-effort
+  }
+
+  return cached;
+};
+
+export const storageConfig: StorageConfig = new Proxy(proxyTarget, {
+  get(_target, prop: keyof StorageConfig) {
+    return ensureStorageConfig()[prop];
+  },
+  ownKeys() {
+    ensureStorageConfig();
+    return Reflect.ownKeys(proxyTarget as unknown as object);
+  },
+  getOwnPropertyDescriptor(_target, prop) {
+    ensureStorageConfig();
+    return Object.getOwnPropertyDescriptor(proxyTarget as unknown as object, prop);
+  },
+});