@zintrust/core 0.1.28 → 0.1.29

package/src/security/StartupSecretValidation.js

@@ -0,0 +1,139 @@
+/**
+ * Startup Secret Validation
+ *
+ * Validates critical secrets early at boot time so production misconfiguration
+ * fails fast and predictably.
+ */
+import { appConfig } from '../config/app.js';
+import { Env } from '../config/env.js';
+import { securityConfig } from '../config/security.js';
+import { startupConfig } from '../config/startup.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+const validateApiKeySecret = () => {
+    if (!securityConfig.apiKey.enabled)
+        return null;
+    const secret = (securityConfig.apiKey.secret ?? '').trim();
+    if (secret.length > 0)
+        return null;
+    return {
+        key: 'API_KEY_SECRET',
+        message: 'API_KEY_SECRET must be set when API key auth is enabled',
+    };
+};
+const validateJwtSecret = () => {
+    if (!securityConfig.jwt.enabled)
+        return null;
+    try {
+        const secret = securityConfig.jwt.secret.trim();
+        const appKey = (Env.APP_KEY ?? '').trim();
+        if (secret.length === 0) {
+            if (appKey.length > 0)
+                return null;
+            return {
+                key: 'JWT_SECRET',
+                message: 'JWT_SECRET must be set when JWT is enabled (or provide APP_KEY)',
+            };
+        }
+        return null;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return { key: 'JWT_SECRET', message };
+    }
+};
+const normalizeCipher = (raw) => {
+    const value = raw.trim().toLowerCase();
+    if (value === 'aes-256-cbc')
+        return 'aes-256-cbc';
+    if (value === 'aes-256-gcm')
+        return 'aes-256-gcm';
+    return null;
+};
+const parseBase64KeyBytes = (rawKey) => {
+    const base64 = rawKey.startsWith('base64:') ? rawKey.slice('base64:'.length) : rawKey;
+    const decoded = Buffer.from(base64, 'base64');
+    if (decoded.length === 0) {
+        return null;
+    }
+    return decoded.length;
+};
+const validateEncryptionInterop = () => {
+    const errors = [];
+    const cipherRaw = (Env.ENCRYPTION_CIPHER ?? '').trim();
+    if (cipherRaw.length === 0) {
+        errors.push({
+            key: 'ENCRYPTION_CIPHER',
+            message: 'ENCRYPTION_CIPHER must be set (supported: aes-256-cbc, aes-256-gcm)',
+        });
+        return errors;
+    }
+    const cipher = normalizeCipher(cipherRaw);
+    if (cipher === null) {
+        errors.push({
+            key: 'ENCRYPTION_CIPHER',
+            message: 'Unsupported ENCRYPTION_CIPHER (supported: aes-256-cbc, aes-256-gcm)',
+        });
+    }
+    const appKey = (Env.APP_KEY ?? '').trim();
+    if (appKey.length === 0) {
+        errors.push({ key: 'APP_KEY', message: 'APP_KEY must be set for encryption interoperability' });
+        return errors;
+    }
+    const bytes = parseBase64KeyBytes(appKey);
+    if (bytes === null) {
+        errors.push({
+            key: 'APP_KEY',
+            message: 'APP_KEY must be valid base64 (supports base64:... prefix)',
+        });
+        return errors;
+    }
+    // Current supported ciphers are aes-256-*, so require 32-byte keys.
+    if (bytes !== 32) {
+        errors.push({
+            key: 'APP_KEY',
+            message: `APP_KEY must decode to 32 bytes for ${cipherRaw}`,
+        });
+    }
+    const prev = (Env.APP_PREVIOUS_KEYS ?? '').trim();
+    if (prev.length > 0 && prev.startsWith('[')) {
+        try {
+            const parsed = JSON.parse(prev);
+            if (!Array.isArray(parsed) || !parsed.every((v) => typeof v === 'string')) {
+                errors.push({
+                    key: 'APP_PREVIOUS_KEYS',
+                    message: 'APP_PREVIOUS_KEYS JSON must be an array of strings',
+                });
+            }
+        }
+        catch {
+            errors.push({ key: 'APP_PREVIOUS_KEYS', message: 'APP_PREVIOUS_KEYS must be valid JSON' });
+        }
+    }
+    return errors;
+};
+export const StartupSecretValidation = Object.freeze({
+    validate() {
+        if (!startupConfig.validateSecrets)
+            return { valid: true, errors: [] };
+        if (!appConfig.isProduction())
+            return { valid: true, errors: [] };
+        const errors = [];
+        const jwtError = validateJwtSecret();
+        if (jwtError !== null)
+            errors.push(jwtError);
+        const apiKeyError = validateApiKeySecret();
+        if (apiKeyError !== null)
+            errors.push(apiKeyError);
+        errors.push(...validateEncryptionInterop());
+        return { valid: errors.length === 0, errors };
+    },
+    assertValid() {
+        const result = StartupSecretValidation.validate();
+        if (result.valid)
+            return;
+        throw ErrorFactory.createConfigError('Invalid startup secret configuration', {
+            errors: result.errors,
+        });
+    },
+});
+export default StartupSecretValidation;

package/src/security/TokenRevocation.d.ts

@@ -0,0 +1,7 @@
+type AuthorizationHeader = string | string[] | undefined;
+export declare const TokenRevocation: Readonly<{
+    revoke(header: AuthorizationHeader): string | null;
+    isRevoked(token: string): boolean;
+}>;
+export default TokenRevocation;
+//# sourceMappingURL=TokenRevocation.d.ts.map

package/src/security/TokenRevocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TokenRevocation.d.ts","sourceRoot":"","sources":["../../../src/security/TokenRevocation.ts"],"names":[],"mappings":"AAGA,KAAK,mBAAmB,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;AAsCzD,eAAO,MAAM,eAAe;mBACX,mBAAmB,GAAG,MAAM,GAAG,IAAI;qBASjC,MAAM,GAAG,OAAO;EAUjC,CAAC;AAEH,eAAe,eAAe,CAAC"}

package/src/security/TokenRevocation.js

@@ -0,0 +1,57 @@
+import { securityConfig } from '../config/security.js';
+import { JwtManager } from './JwtManager.js';
+const revokedTokens = new Map();
+const defaultTtlMs = Math.max(securityConfig.jwt.expiresIn * 1000, 60_000);
+const getBearerToken = (header) => {
+    const value = Array.isArray(header) ? header[0] : header;
+    if (typeof value !== 'string')
+        return null;
+    const [scheme, token] = value.trim().split(' ');
+    if (scheme.toLowerCase() !== 'bearer')
+        return null;
+    if (typeof token !== 'string' || token.trim() === '')
+        return null;
+    return token;
+};
+const cleanupExpired = () => {
+    const now = Date.now();
+    for (const [token, expiresAt] of revokedTokens.entries()) {
+        if (expiresAt <= now) {
+            revokedTokens.delete(token);
+        }
+    }
+};
+const resolveExpiryMs = (token) => {
+    try {
+        const payload = JwtManager.create().decode(token);
+        if (typeof payload.exp === 'number' && Number.isFinite(payload.exp)) {
+            return payload.exp * 1000;
+        }
+    }
+    catch {
+        // ignore decode errors; fallback to default TTL
+    }
+    return Date.now() + defaultTtlMs;
+};
+export const TokenRevocation = Object.freeze({
+    revoke(header) {
+        const token = getBearerToken(header);
+        if (token === null)
+            return null;
+        cleanupExpired();
+        revokedTokens.set(token, resolveExpiryMs(token));
+        return token;
+    },
+    isRevoked(token) {
+        cleanupExpired();
+        const expiresAt = revokedTokens.get(token);
+        if (expiresAt === undefined)
+            return false;
+        if (expiresAt <= Date.now()) {
+            revokedTokens.delete(token);
+            return false;
+        }
+        return true;
+    },
+});
+export default TokenRevocation;

package/src/security/UrlValidator.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Security Utilities
+ * Mitigates SSRF (SonarQube S5144)
+ */
+export interface IUrlValidator {
+    validateUrl(url: string, allowedDomains?: string[]): void;
+}
+/**
+ * Validate URL for SSRF protection
+ * Ensures URL is either internal or matches allowed domains
+ */
+declare const validate: (url: string, allowedDomains?: string[]) => void;
+declare const validateUrl: (url: string, allowedDomains?: string[]) => void;
+/**
+ * UrlValidator handles URL validation for SSRF protection
+ * Sealed namespace for immutability
+ */
+export declare const UrlValidator: IUrlValidator;
+export { validate, validateUrl };
+//# sourceMappingURL=UrlValidator.d.ts.map

package/src/security/UrlValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UrlValidator.d.ts","sourceRoot":"","sources":["../../../src/security/UrlValidator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAC3D;AAED;;;GAGG;AACH,QAAA,MAAM,QAAQ,GAAI,KAAK,MAAM,EAAE,iBAAgB,MAAM,EAA+B,KAAG,IAyBtF,CAAC;AAEF,QAAA,MAAM,WAAW,GAAI,KAAK,MAAM,EAAE,iBAAiB,MAAM,EAAE,KAAG,IAE7D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,aAGzB,CAAC;AAGH,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC"}

package/src/security/UrlValidator.js

@@ -0,0 +1,41 @@
+/**
+ * Security Utilities
+ * Mitigates SSRF (SonarQube S5144)
+ */
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+/**
+ * Validate URL for SSRF protection
+ * Ensures URL is either internal or matches allowed domains
+ */
+const validate = (url, allowedDomains = ['localhost', '127.0.0.1']) => {
+    try {
+        const parsedUrl = new URL(url);
+        const hostname = parsedUrl.hostname;
+        // In a real microservices environment, we would check against a service registry
+        // For now, we allow localhost and any domain in the allowed list
+        const isAllowed = allowedDomains.some((domain) => hostname === domain || hostname.endsWith(`.${domain}`));
+        if (!isAllowed) {
+            throw ErrorFactory.createValidationError(`URL hostname '${hostname}' is not allowed (SSRF Protection)`, { hostname });
+        }
+    }
+    catch (error) {
+        const maybeZinError = error;
+        if (maybeZinError.code === 'VALIDATION_ERROR') {
+            throw error;
+        }
+        throw ErrorFactory.createValidationError(`Invalid URL: ${url}`, { cause: error });
+    }
+};
+const validateUrl = (url, allowedDomains) => {
+    return validate(url, allowedDomains);
+};
+/**
+ * UrlValidator handles URL validation for SSRF protection
+ * Sealed namespace for immutability
+ */
+export const UrlValidator = Object.freeze({
+    validate,
+    validateUrl,
+});
+// Re-export for backward compatibility
+export { validate, validateUrl };

package/src/security/Xss.d.ts

@@ -0,0 +1,14 @@
+/**
+ * XSS Sanitizer
+ * Recursive, zero-dependency input sanitization utility.
+ *
+ * This is intentionally conservative:
+ * - Strings: strip tags, then escape HTML entities.
+ * - Arrays/Objects: sanitize recursively.
+ */
+export interface IXss {
+    sanitize(input: unknown): unknown;
+}
+export declare const Xss: IXss;
+export default Xss;
+//# sourceMappingURL=Xss.d.ts.map

package/src/security/Xss.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Xss.d.ts","sourceRoot":"","sources":["../../../src/security/Xss.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAwDH,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;CACnC;AAED,eAAO,MAAM,GAAG,EAAE,IAIhB,CAAC;AAEH,eAAe,GAAG,CAAC"}

package/src/security/Xss.js

@@ -0,0 +1,57 @@
+/**
+ * XSS Sanitizer
+ * Recursive, zero-dependency input sanitization utility.
+ *
+ * This is intentionally conservative:
+ * - Strings: strip tags, then escape HTML entities.
+ * - Arrays/Objects: sanitize recursively.
+ */
+import { XssProtection } from './XssProtection.js';
+const stripTags = (value) => {
+    // Remove all HTML tags in linear time (no regex backtracking / ReDoS risk).
+    let out = '';
+    let inTag = false;
+    for (const element of value) {
+        const ch = element;
+        if (ch === '<') {
+            inTag = true;
+            continue;
+        }
+        if (inTag) {
+            if (ch === '>')
+                inTag = false;
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+};
+const sanitizeRecursive = (input, seen) => {
+    if (typeof input === 'string') {
+        return XssProtection.escape(stripTags(input));
+    }
+    if (Array.isArray(input)) {
+        if (seen.has(input))
+            return input;
+        seen.add(input);
+        return input.map((item) => sanitizeRecursive(item, seen));
+    }
+    if (typeof input === 'object' && input !== null) {
+        const obj = input;
+        if (seen.has(obj))
+            return input;
+        seen.add(obj);
+        const out = {};
+        for (const [key, value] of Object.entries(obj)) {
+            out[key] = sanitizeRecursive(value, seen);
+        }
+        return out;
+    }
+    return input;
+};
+export const Xss = Object.freeze({
+    sanitize(input) {
+        return sanitizeRecursive(input, new WeakSet());
+    },
+});
+export default Xss;

package/src/security/XssProtection.d.ts

@@ -0,0 +1,24 @@
+/**
+ * XSS Protection Utilities
+ * HTML escaping and sanitization (pure TypeScript, zero dependencies)
+ * Sealed namespace pattern - all exports through XssProtection namespace
+ */
+/**
+ * Escape JSON for safe embedding in HTML
+ */
+export declare const escapeJson: (obj: unknown) => string;
+export interface IXssProtection {
+    escape(text: string): string;
+    sanitize(html: string): string;
+    encodeUri(uri: string): string;
+    encodeHref(href: string): string;
+    isSafeUrl(url: string): boolean;
+    escapeJson(obj: unknown): string;
+}
+/**
+ * XSS Protection Utilities
+ * HTML escaping and sanitization (pure TypeScript, zero dependencies)
+ * Sealed namespace with protection methods
+ */
+export declare const XssProtection: IXssProtection;
+//# sourceMappingURL=XssProtection.d.ts.map

package/src/security/XssProtection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XssProtection.d.ts","sourceRoot":"","sources":["../../../src/security/XssProtection.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0WH;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,OAAO,KAAG,MAGzC,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC;CAClC;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,cAO1B,CAAC"}