@zintrust/core 0.1.28 → 0.1.30

package/src/config/SecretsManager.js

@@ -0,0 +1,355 @@
+/**
+ * Unified Secrets Management Layer
+ * Abstracts secrets retrieval across different cloud platforms
+ * Supports: AWS Secrets Manager, Parameter Store, Cloudflare KV, Deno env
+ */
+import { Env } from './env.js';
+import { Logger } from './logger.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+let instance;
+function pruneCache(cache, maxEntries) {
+    if (cache.size <= maxEntries)
+        return;
+    const now = Date.now();
+    for (const [key, entry] of cache.entries()) {
+        if (entry.expiresAt <= now)
+            cache.delete(key);
+    }
+    // If still large, drop oldest entries (Map preserves insertion order)
+    while (cache.size > maxEntries) {
+        const next = cache.keys().next();
+        if (next.done === true)
+            break;
+        cache.delete(next.value);
+    }
+}
+/**
+ * Get secret value from appropriate backend
+ */
+async function runGetSecret(config, cache, key, options) {
+    // Check cache first
+    const cached = cache.get(key);
+    if (cached !== undefined && cached.expiresAt > Date.now()) {
+        return cached.value;
+    }
+    // Opportunistic cleanup if cache has grown
+    pruneCache(cache, 500);
+    let value;
+    switch (config.platform) {
+        case 'aws':
+            value = await getFromAWSSecretsManager(key);
+            break;
+        case 'cloudflare':
+            value = await getFromCloudflareKV(config, key);
+            break;
+        case 'deno':
+            value = await getFromDenoEnv(key);
+            break;
+        case 'local':
+        default:
+            value = await getFromEnv(key);
+    }
+    // Cache the value
+    const ttl = options?.cacheTtl ?? 3600000; // 1 hour default
+    cache.set(key, {
+        value,
+        expiresAt: Date.now() + ttl,
+    });
+    pruneCache(cache, 500);
+    return value;
+}
+/**
+ * Set secret value
+ */
+async function runSetSecret(config, cache, key, value, options) {
+    switch (config.platform) {
+        case 'aws':
+            await setInAWSSecretsManager(key, value, options);
+            break;
+        case 'cloudflare':
+            await setInCloudflareKV(config, key, value, options);
+            break;
+        case 'deno':
+            throw ErrorFactory.createConfigError('Cannot set secrets in Deno environment');
+        case 'local':
+        default:
+            throw ErrorFactory.createConfigError('Cannot set secrets in local environment');
+    }
+    // Invalidate cache
+    cache.delete(key);
+}
+/**
+ * Delete secret
+ */
+async function runDeleteSecret(config, cache, key) {
+    switch (config.platform) {
+        case 'aws':
+            await deleteFromAWSSecretsManager(key);
+            break;
+        case 'cloudflare':
+            await deleteFromCloudflareKV(config, key);
+            break;
+        case 'deno':
+        case 'local':
+        default:
+            throw ErrorFactory.createConfigError('Cannot delete secrets in this environment');
+    }
+    // Invalidate cache
+    cache.delete(key);
+}
+/**
+ * SecretsManager implementation
+ * Refactored to Functional Object pattern
+ */
+const SecretsManagerImpl = {
+    /**
+     * Create a new secrets manager instance
+     */
+    create(config) {
+        const cache = new Map();
+        return {
+            /**
+             * Get secret value from appropriate backend
+             */
+            async getSecret(key, options) {
+                return runGetSecret(config, cache, key, options);
+            },
+            /**
+             * Set secret value
+             */
+            async setSecret(key, value, options) {
+                return runSetSecret(config, cache, key, value, options);
+            },
+            /**
+             * Delete secret
+             */
+            async deleteSecret(key) {
+                return runDeleteSecret(config, cache, key);
+            },
+            /**
+             * Rotate secret (trigger new secret generation)
+             */
+            // eslint-disable-next-line @typescript-eslint/require-await
+            async rotateSecret(_key) {
+                if (config.platform === 'aws') {
+                    // AWS Secrets Manager supports automatic rotation
+                    throw ErrorFactory.createConfigError('Secret rotation not implemented');
+                }
+                throw ErrorFactory.createConfigError('Secret rotation not supported on this platform');
+            },
+            /**
+             * Get all secrets matching pattern
+             */
+            async listSecrets(pattern) {
+                switch (config.platform) {
+                    case 'aws':
+                        return listFromAWSSecretsManager(pattern);
+                    case 'cloudflare':
+                        return listFromCloudflareKV(config, pattern);
+                    case 'deno':
+                    case 'local':
+                    default:
+                        return [];
+                }
+            },
+            /**
+             * Clear cache (useful after rotation)
+             */
+            clearCache(key) {
+                if (key === undefined) {
+                    cache.clear();
+                }
+                else {
+                    cache.delete(key);
+                }
+            },
+        };
+    },
+};
+/**
+ * AWS Secrets Manager integration
+ */
+// eslint-disable-next-line @typescript-eslint/require-await
+async function getFromAWSSecretsManager(key) {
+    try {
+        Logger.debug(`[AWS] Getting secret: ${key}`);
+        throw ErrorFactory.createConfigError('AWS SDK not available in core - use wrapper module');
+    }
+    catch (error) {
+        throw ErrorFactory.createTryCatchError(`Failed to retrieve secret from AWS: ${error.message}`, error);
+    }
+}
+// eslint-disable-next-line @typescript-eslint/require-await
+async function setInAWSSecretsManager(key, _value, _options) {
+    Logger.info(`[AWS] Setting secret: ${key}`);
+    throw ErrorFactory.createConfigError('AWS SDK not available in core - use wrapper module');
+}
+// eslint-disable-next-line @typescript-eslint/require-await
+async function deleteFromAWSSecretsManager(key) {
+    Logger.info(`[AWS] Deleting secret: ${key}`);
+    throw ErrorFactory.createConfigError('AWS SDK not available in core - use wrapper module');
+}
+// eslint-disable-next-line @typescript-eslint/require-await
+async function listFromAWSSecretsManager(pattern) {
+    Logger.info(`[AWS] Listing secrets with pattern: ${pattern ?? '*'}`);
+    return [];
+}
+/**
+ * Cloudflare KV integration
+ */
+async function getFromCloudflareKV(config, key) {
+    if (config.kv === undefined) {
+        throw ErrorFactory.createConfigError('Cloudflare KV namespace not configured');
+    }
+    const value = await config.kv.get(key);
+    if (value === null || value === '') {
+        throw ErrorFactory.createNotFoundError(`Secret not found: ${key}`, { key });
+    }
+    return value;
+}
+async function setInCloudflareKV(config, key, value, options) {
+    if (config.kv === undefined) {
+        throw ErrorFactory.createConfigError('Cloudflare KV namespace not configured');
+    }
+    const ttl = options?.expirationTtl;
+    await config.kv.put(key, value, { expirationTtl: ttl });
+}
+async function deleteFromCloudflareKV(config, key) {
+    if (config.kv === undefined) {
+        throw ErrorFactory.createConfigError('Cloudflare KV namespace not configured');
+    }
+    await config.kv.delete(key);
+}
+async function listFromCloudflareKV(config, pattern) {
+    if (config.kv === undefined) {
+        throw ErrorFactory.createConfigError('Cloudflare KV namespace not configured');
+    }
+    const result = await config.kv.list({ prefix: pattern });
+    return result.keys.map((k) => k.name);
+}
+/**
+ * Deno environment integration
+ */
+// eslint-disable-next-line @typescript-eslint/require-await
+async function getFromDenoEnv(key) {
+    const value = globalThis['Deno']?.env?.get?.(key);
+    if (value === undefined || value === null || value === '') {
+        throw ErrorFactory.createNotFoundError(`Secret not found: ${key}`, { key });
+    }
+    return value;
+}
+/**
+ * Local environment variables (Node.js)
+ */
+// eslint-disable-next-line @typescript-eslint/require-await
+async function getFromEnv(key) {
+    const value = Env.get(key, '');
+    if (value === undefined || value === null || value === '') {
+        throw ErrorFactory.createNotFoundError(`Secret not found: ${key}`, { key });
+    }
+    return value;
+}
+/**
+ * SecretsManager - Unified interface for retrieving secrets
+ * Sealed namespace for immutability
+ */
+export const SecretsManager = Object.freeze({
+    /**
+     * Get or create singleton instance
+     */
+    getInstance(config) {
+        if (instance === undefined && config !== undefined) {
+            instance = SecretsManagerImpl.create(config);
+        }
+        if (instance === undefined) {
+            throw ErrorFactory.createConfigError('SecretsManager not initialized. Call getInstance(config) first.');
+        }
+        return instance;
+    },
+    /**
+     * Get secret value from appropriate backend
+     */
+    async getSecret(key, options) {
+        return this.getInstance().getSecret(key, options);
+    },
+    /**
+     * Set secret value
+     */
+    async setSecret(key, value, options) {
+        return this.getInstance().setSecret(key, value, options);
+    },
+    /**
+     * Delete secret
+     */
+    async deleteSecret(key) {
+        return this.getInstance().deleteSecret(key);
+    },
+    /**
+     * Rotate secret (trigger new secret generation)
+     */
+    async rotateSecret(key) {
+        return this.getInstance().rotateSecret(key);
+    },
+    /**
+     * Get all secrets matching pattern
+     */
+    async listSecrets(pattern) {
+        return this.getInstance().listSecrets(pattern);
+    },
+    /**
+     * Clear cache (useful after rotation)
+     */
+    clearCache(key) {
+        this.getInstance().clearCache(key);
+    },
+});
+/**
+ * Predefined secret keys
+ * Sealed namespace for immutability
+ */
+export const SECRETS = Object.freeze({
+    // Database credentials
+    DB_USERNAME: 'db/username',
+    // Secret identifier only (not a credential value)
+    DB_PASSWORD: 'db/password', // NOSONAR (typescript:S2068) - secret key name, not hardcoded password
+    DB_HOST: 'db/host',
+    DB_PORT: 'db/port',
+    DB_DATABASE: 'db/database',
+    // API keys
+    JWT_SECRET: 'jwt/secret',
+    JWT_REFRESH_SECRET: 'jwt/refresh-secret',
+    // Encryption
+    ENCRYPTION_KEY: 'encryption/key',
+    ENCRYPTION_IV: 'encryption/iv',
+    // Third-party APIs
+    STRIPE_API_KEY: 'stripe/api-key',
+    STRIPE_WEBHOOK_SECRET: 'stripe/webhook-secret',
+    SENDGRID_API_KEY: 'sendgrid/api-key',
+    GITHUB_TOKEN: 'github/token',
+    // Session/CSRF
+    SESSION_SECRET: 'session/secret',
+    CSRF_SECRET: 'csrf/secret',
+});
+/**
+ * Helper to get database credentials using secrets manager
+ */
+export async function getDatabaseCredentials() {
+    const manager = SecretsManager.getInstance();
+    return {
+        username: await manager.getSecret(SECRETS.DB_USERNAME),
+        password: await manager.getSecret(SECRETS.DB_PASSWORD),
+        host: await manager.getSecret(SECRETS.DB_HOST),
+        port: Number.parseInt(await manager.getSecret(SECRETS.DB_PORT), 10),
+        database: await manager.getSecret(SECRETS.DB_DATABASE),
+    };
+}
+/**
+ * Helper to get JWT secrets
+ */
+export async function getJwtSecrets() {
+    const manager = SecretsManager.getInstance();
+    return {
+        secret: await manager.getSecret(SECRETS.JWT_SECRET),
+        refreshSecret: await manager.getSecret(SECRETS.JWT_REFRESH_SECRET),
+    };
+}

package/src/config/StartupConfigValidator.d.ts

@@ -0,0 +1,7 @@
+import type { StartupConfigValidationResult } from './type';
+export declare const StartupConfigValidator: Readonly<{
+    validate(): StartupConfigValidationResult;
+    assertValid(): void;
+}>;
+export default StartupConfigValidator;
+//# sourceMappingURL=StartupConfigValidator.d.ts.map

package/src/config/StartupConfigValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StartupConfigValidator.d.ts","sourceRoot":"","sources":["../../../src/config/StartupConfigValidator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAgC,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAiPhG,eAAO,MAAM,sBAAsB;gBACrB,6BAA6B;mBAc1B,IAAI;EAQnB,CAAC;AAEH,eAAe,sBAAsB,CAAC"}

package/src/config/StartupConfigValidator.js

@@ -0,0 +1,179 @@
+import { appConfig } from './app.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+const isSensitiveKey = (key) => {
+    const normalized = key.toLowerCase();
+    return (normalized.includes('password') ||
+        normalized.includes('secret') ||
+        normalized.includes('token') ||
+        normalized.includes('key') ||
+        normalized.includes('authorization'));
+};
+const redactValue = (key, value) => {
+    return isSensitiveKey(key) ? '<redacted>' : value;
+};
+const pushError = (errors, key, value, message) => {
+    errors.push({ key, value: redactValue(key, value), message });
+};
+const validateEnum = (errors, key, value, allowed) => {
+    if (!allowed.includes(value)) {
+        pushError(errors, key, value, `${key} must be one of: ${allowed.join(', ')}`);
+    }
+};
+const validateIntRange = (errors, key, value, min, max) => {
+    if (Number.isNaN(value)) {
+        pushError(errors, key, value, `${key} must be a valid integer`);
+        return;
+    }
+    if (value < min || value > max) {
+        pushError(errors, key, value, `${key} must be between ${min} and ${max}`);
+    }
+};
+const validatePositiveInt = (errors, key, value) => {
+    if (Number.isNaN(value)) {
+        pushError(errors, key, value, `${key} must be a valid integer`);
+        return;
+    }
+    if (value <= 0) {
+        pushError(errors, key, value, `${key} must be greater than 0`);
+    }
+};
+const getProcessLike = () => {
+    return typeof process === 'undefined' ? undefined : process;
+};
+const getEnvString = (key, defaultValue) => {
+    const proc = getProcessLike();
+    const env = proc?.env ?? {};
+    return env[key] ?? defaultValue;
+};
+const getEnvOptionalString = (key) => {
+    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, defaultValue) => {
+    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, defaultValue) => {
+    const raw = getEnvString(key, String(defaultValue));
+    return Number.parseInt(raw, 10);
+};
+const requireEnvString = (errors, key, options = {}) => {
+    const value = getEnvOptionalString(key) ??
+        (options.aliases ?? []).reduce((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, dbConnection) => {
+    // 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) => {
+    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');
+    validateSqliteDbFileRequired(errors, dbConnection);
+};
+const validateNodeEnv = (errors) => {
+    const nodeEnv = getEnvString('NODE_ENV', 'development');
+    validateEnum(errors, 'NODE_ENV', nodeEnv, ['development', 'production', 'testing', 'test']);
+};
+const validatePort = (errors) => {
+    // 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) => {
+    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) => {
+    const logRotationSize = getEnvInt('LOG_ROTATION_SIZE', 10485760);
+    validatePositiveInt(errors, 'LOG_ROTATION_SIZE', logRotationSize);
+    const logRotationDays = getEnvInt('LOG_ROTATION_DAYS', 7);
+    validatePositiveInt(errors, 'LOG_ROTATION_DAYS', logRotationDays);
+    const startupHealthTimeoutMs = getEnvInt('STARTUP_HEALTH_TIMEOUT_MS', 2500);
+    validatePositiveInt(errors, 'STARTUP_HEALTH_TIMEOUT_MS', startupHealthTimeoutMs);
+};
+const validateProductionAppKey = (errors) => {
+    if (!appConfig.isProduction())
+        return;
+    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');
+    }
+};
+export const StartupConfigValidator = Object.freeze({
+    validate() {
+        const errors = [];
+        validateStrictRequiredEnv(errors);
+        validateNodeEnv(errors);
+        validatePort(errors);
+        validateLogging(errors);
+        validateRotationAndTimeout(errors);
+        validateProductionAppKey(errors);
+        return { valid: errors.length === 0, errors };
+    },
+    assertValid() {
+        const result = StartupConfigValidator.validate();
+        if (result.valid)
+            return;
+        throw ErrorFactory.createConfigError('Invalid startup configuration', {
+            errors: result.errors,
+        });
+    },
+});
+export default StartupConfigValidator;

package/src/config/app.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Application Configuration
+ * Core application settings
+ * Sealed namespace for immutability
+ */
+import type { StartMode } from './type';
+declare const getSafeEnv: () => NodeJS.ProcessEnv;
+export declare const appConfig: Readonly<{
+    /**
+     * Application name
+     */
+    readonly name: string;
+    /**
+     * Application prefix
+     */
+    readonly prefix: string;
+    /**
+     * Application environment
+     */
+    readonly environment: StartMode;
+    /**
+     * Application port
+     */
+    readonly port: number;
+    /**
+     * Application host
+     */
+    readonly host: string;
+    /**
+     * Is development environment
+     */
+    readonly isDevelopment: () => boolean;
+    /**
+     * Is production environment
+     */
+    readonly isProduction: () => boolean;
+    /**
+     * Is testing environment
+     */
+    readonly isTesting: () => boolean;
+    /**
+     * Application debug mode
+     */
+    readonly debug: boolean;
+    /**
+     * Application timezone
+     */
+    readonly timezone: string;
+    /**
+     * Request timeout (milliseconds)
+     */
+    readonly requestTimeout: number;
+    /**
+     * Max request body size
+     */
+    readonly maxBodySize: number;
+    readonly getSafeEnv: () => NodeJS.ProcessEnv;
+    readonly detectRuntime: () => string;
+}>;
+export { getSafeEnv };
+export type AppConfig = typeof appConfig;
+//# sourceMappingURL=app.d.ts.map

package/src/config/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/config/app.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,cAAc,CAAC;AAoI3D,QAAA,MAAM,UAAU,QAAO,MAAM,CAAC,UAA2B,CAAC;AAsF1D,eAAO,MAAM,SAAS;IAtEpB;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;kCACc,OAAO;IAIxB;;OAEG;iCACa,OAAO;IAIvB;;OAEG;8BACU,OAAO;IAIpB;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;+BA/EkB,MAAM,CAAC,UAAU;kCAhDd,MAAM;EAsIoB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC"}