@zintrust/core 0.1.1 → 0.1.3

package/src/config/logger.js

@@ -3,9 +3,124 @@
  * Sealed namespace pattern - all exports through Logger namespace
  * Replaces console.* calls throughout the codebase
  */
+import { appConfig } from './app';
 import { Env } from './env';
-const isDevelopment = Env.NODE_ENV === 'development' || Env.NODE_ENV === undefined;
-const isProduction = Env.NODE_ENV === 'production';
+const isDevelopment = () => appConfig.isDevelopment();
+const isProduction = () => appConfig.isProduction();
+const getLogFormat = () => Env.get('LOG_FORMAT', 'text');
+const isJsonFormat = (value) => value === 'json';
+const SENSITIVE_FIELDS = new Set([
+    'password',
+    'token',
+    'authorization',
+    'secret',
+    'apikey',
+    'api_key',
+    'jwt',
+    'bearer',
+]);
+const redactSensitiveData = (data) => {
+    const seen = new WeakSet();
+    const walk = (value) => {
+        if (Array.isArray(value)) {
+            if (seen.has(value))
+                return '[Circular]';
+            seen.add(value);
+            return value.map((v) => walk(v));
+        }
+        if (typeof value === 'object' && value !== null) {
+            const asObj = value;
+            if (seen.has(asObj))
+                return '[Circular]';
+            seen.add(asObj);
+            const out = {};
+            for (const [key, inner] of Object.entries(asObj)) {
+                if (SENSITIVE_FIELDS.has(key.toLowerCase())) {
+                    out[key] = '[REDACTED]';
+                }
+                else {
+                    out[key] = walk(inner);
+                }
+            }
+            return out;
+        }
+        return value;
+    };
+    return walk(data);
+};
+const safeStringify = (obj, indent = false) => {
+    const seen = new WeakSet();
+    return JSON.stringify(obj, (_key, value) => {
+        if (typeof value === 'object' && value !== null) {
+            const asObj = value;
+            if (seen.has(asObj))
+                return '[Circular]';
+            seen.add(asObj);
+        }
+        return value;
+    }, indent ? 2 : 0);
+};
+let fileWriterPromise;
+let fileWriter;
+const getFileWriter = () => {
+    if (fileWriter !== undefined)
+        return;
+    if (fileWriterPromise !== undefined)
+        return;
+    fileWriterPromise = import('./FileLogWriter')
+        .then((mod) => {
+        fileWriter = mod.FileLogWriter;
+        return mod;
+    })
+        .catch(() => {
+        fileWriterPromise = undefined;
+        return { FileLogWriter: { write: (_line) => undefined } };
+    });
+};
+const shouldLogToFile = () => {
+    // Prefer dynamic lookup so late-bound env (tests, some runtimes) is respected.
+    if (!Env.getBool('LOG_TO_FILE', false))
+        return false;
+    if (typeof process === 'undefined')
+        return false;
+    return true;
+};
+const buildFileLine = (params) => {
+    if (isJsonFormat(getLogFormat()))
+        return params.formatted;
+    let line = params.formatted;
+    if (typeof params.errorMessage === 'string' && params.errorMessage.length > 0) {
+        line = `${line} ${params.errorMessage}`;
+    }
+    else if (params.data !== undefined && params.data !== '') {
+        line = `${line} ${safeStringify(redactSensitiveData(params.data))}`;
+    }
+    return line;
+};
+const writeToFile = (line) => {
+    if (!shouldLogToFile())
+        return;
+    if (fileWriter !== undefined) {
+        fileWriter.write(line);
+        return;
+    }
+    getFileWriter();
+    fileWriterPromise?.then((mod) => mod.FileLogWriter.write(line));
+};
+const formatLogMessage = (params) => {
+    if (isJsonFormat(getLogFormat())) {
+        return safeStringify({
+            timestamp: new Date().toISOString(),
+            level: params.level,
+            message: params.message,
+            category: params.category,
+            data: redactSensitiveData(params.data),
+            error: params.errorMessage,
+        });
+    }
+    // text format
+    return `[${params.level.toUpperCase()}] ${params.message}`;
+};
 /**
  * Helper to extract error message from unknown error type
  */
@@ -16,33 +131,162 @@ const getErrorMessage = (error) => {
     if (error instanceof Error) {
         return error.message;
     }
-    return String(error);
+    if (typeof error === 'string')
+        return error;
+    if (typeof error === 'number' || typeof error === 'bigint')
+        return error.toString();
+    if (typeof error === 'boolean')
+        return error ? 'true' : 'false';
+    if (typeof error === 'symbol')
+        return error.toString();
+    if (typeof error === 'function')
+        return '[Function]';
+    try {
+        return safeStringify(error);
+    }
+    catch {
+        return '[Unserializable error]';
+    }
+};
+const emitCloudLogs = (event) => {
+    // Lazy-load to avoid cycles and avoid cost when disabled.
+    void (async () => {
+        try {
+            if (event.level === 'error' || event.level === 'fatal') {
+                const mod = await import('./logging/KvLogger');
+                void mod.KvLogger.enqueue(event);
+            }
+        }
+        catch {
+            // best-effort
+        }
+        try {
+            if (event.level === 'warn' || event.level === 'error' || event.level === 'fatal') {
+                const mod = await import('./logging/SlackLogger');
+                void mod.SlackLogger.enqueue(event);
+            }
+        }
+        catch {
+            // best-effort
+        }
+        try {
+            const mod = await import('./logging/HttpLogger');
+            void mod.HttpLogger.enqueue(event);
+        }
+        catch {
+            // best-effort
+        }
+    })();
 };
 // Private helper functions
 const logDebug = (message, data, category) => {
     String(category);
-    if (isDevelopment) {
-        console.debug(`[DEBUG] ${message}`, data ?? ''); // eslint-disable-line no-console
+    if (isDevelopment()) {
+        const timestamp = new Date().toISOString();
+        const out = formatLogMessage({ level: 'debug', message, data, category });
+        writeToFile(buildFileLine({ formatted: out, data }));
+        if (isJsonFormat(getLogFormat())) {
+            console.debug(out); // eslint-disable-line no-console
+            return;
+        }
+        console.debug(out, data ?? ''); // eslint-disable-line no-console
+        emitCloudLogs({
+            timestamp,
+            level: 'debug',
+            message,
+            category,
+            data: redactSensitiveData(data),
+        });
     }
 };
 const logInfo = (message, data, category) => {
     String(category);
-    console.log(`[INFO] ${message}`, data ?? ''); // eslint-disable-line no-console
+    const timestamp = new Date().toISOString();
+    const out = formatLogMessage({ level: 'info', message, data, category });
+    writeToFile(buildFileLine({ formatted: out, data }));
+    if (isJsonFormat(getLogFormat())) {
+        console.log(out); // eslint-disable-line no-console
+    }
+    else {
+        console.log(out, data ?? ''); // eslint-disable-line no-console
+    }
+    emitCloudLogs({
+        timestamp,
+        level: 'info',
+        message,
+        category,
+        data: redactSensitiveData(data),
+    });
 };
 const logWarn = (message, data, category) => {
     String(category);
-    console.warn(`[WARN] ${message}`, data ?? ''); // eslint-disable-line no-console
+    const timestamp = new Date().toISOString();
+    const out = formatLogMessage({ level: 'warn', message, data, category });
+    writeToFile(buildFileLine({ formatted: out, data }));
+    if (isJsonFormat(getLogFormat())) {
+        console.warn(out); // eslint-disable-line no-console
+    }
+    else {
+        console.warn(out, data ?? ''); // eslint-disable-line no-console
+    }
+    emitCloudLogs({
+        timestamp,
+        level: 'warn',
+        message,
+        category,
+        data: redactSensitiveData(data),
+    });
 };
 const logError = (message, error, category) => {
     const errorMessage = getErrorMessage(error);
     String(category);
-    console.error(`[ERROR] ${message}`, errorMessage); // eslint-disable-line no-console
+    const timestamp = new Date().toISOString();
+    const out = formatLogMessage({
+        level: 'error',
+        message,
+        category,
+        errorMessage,
+    });
+    writeToFile(buildFileLine({ formatted: out, errorMessage }));
+    if (isJsonFormat(getLogFormat())) {
+        console.error(out); // eslint-disable-line no-console
+    }
+    else {
+        console.error(out, errorMessage); // eslint-disable-line no-console
+    }
+    emitCloudLogs({
+        timestamp,
+        level: 'error',
+        message,
+        category,
+        error: errorMessage,
+    });
 };
 const logFatal = (message, error, category) => {
     const errorMessage = getErrorMessage(error);
     String(category);
-    console.error(`[FATAL] ${message}`, errorMessage); // eslint-disable-line no-console
-    if (isProduction && typeof process !== 'undefined') {
+    const timestamp = new Date().toISOString();
+    const out = formatLogMessage({
+        level: 'fatal',
+        message,
+        category,
+        errorMessage,
+    });
+    writeToFile(buildFileLine({ formatted: out, errorMessage }));
+    if (isJsonFormat(getLogFormat())) {
+        console.error(out); // eslint-disable-line no-console
+    }
+    else {
+        console.error(out, errorMessage); // eslint-disable-line no-console
+    }
+    emitCloudLogs({
+        timestamp,
+        level: 'fatal',
+        message,
+        category,
+        error: errorMessage,
+    });
+    if (isProduction() && typeof process !== 'undefined') {
         process.exit(1);
     }
 };
@@ -65,13 +309,28 @@ const createLoggerScope = (scope) => {
         },
     };
 };
-// Sealed namespace with all logger functionality
+// Expose log cleanup API and sealed namespace with all logger functionality
+export const cleanLogsOnce = async () => {
+    if (!shouldLogToFile())
+        return [];
+    try {
+        const mod = await import('./FileLogWriter');
+        const deleted = mod.cleanOnce();
+        logInfo('Log cleanup executed', { deletedCount: deleted.length });
+        return deleted;
+    }
+    catch (err) {
+        logError('Log cleanup failed', err);
+        return [];
+    }
+};
 export const Logger = Object.freeze({
     debug: logDebug,
     info: logInfo,
     warn: logWarn,
     error: logError,
     fatal: logFatal,
+    cleanLogsOnce,
     scope: createLoggerScope,
 });
 export default Logger;

package/src/config/logging/HttpLogger.d.ts

@@ -0,0 +1,23 @@
+/**
+ * HTTP Endpoint Logger
+ * Sends logs to an external HTTP logging service.
+ *
+ * Enabled via env:
+ *  - HTTP_LOG_ENABLED (default: false)
+ *  - HTTP_LOG_ENDPOINT_URL
+ *  - HTTP_LOG_BATCH_SIZE (default: 50)
+ *  - HTTP_LOG_AUTH_TOKEN (optional)
+ */
+export type HttpLogEvent = {
+    timestamp: string;
+    level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+    message: string;
+    category?: string;
+    data?: unknown;
+    error?: string;
+};
+export declare const HttpLogger: Readonly<{
+    enqueue(event: HttpLogEvent): Promise<void>;
+}>;
+export default HttpLogger;
+//# sourceMappingURL=HttpLogger.d.ts.map

package/src/config/logging/HttpLogger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpLogger.d.ts","sourceRoot":"","sources":["../../../../src/config/logging/HttpLogger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAkFF,eAAO,MAAM,UAAU;mBACA,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;EAYjD,CAAC;AAEH,eAAe,UAAU,CAAC"}

package/src/config/logging/HttpLogger.js

@@ -0,0 +1,93 @@
+/**
+ * HTTP Endpoint Logger
+ * Sends logs to an external HTTP logging service.
+ *
+ * Enabled via env:
+ *  - HTTP_LOG_ENABLED (default: false)
+ *  - HTTP_LOG_ENDPOINT_URL
+ *  - HTTP_LOG_BATCH_SIZE (default: 50)
+ *  - HTTP_LOG_AUTH_TOKEN (optional)
+ */
+import { delay } from '../../common/index';
+import { Env } from '../env';
+import { ErrorFactory } from '../../exceptions/ZintrustError';
+import { HttpClient } from '../../tools/http/Http';
+const isEnabled = () => Env.getBool('HTTP_LOG_ENABLED', false);
+let buffer = [];
+let flushPromise;
+const postBatch = async (events) => {
+    const endpoint = Env.get('HTTP_LOG_ENDPOINT_URL').trim();
+    if (endpoint.length === 0) {
+        throw ErrorFactory.createConfigError('HTTP_LOG_ENDPOINT_URL is required when HTTP logging is enabled');
+    }
+    const token = Env.get('HTTP_LOG_AUTH_TOKEN').trim();
+    const builder = HttpClient.post(endpoint, {
+        sentAt: new Date().toISOString(),
+        count: events.length,
+        events,
+    });
+    if (token.length > 0) {
+        builder.withAuth(token, 'Bearer');
+    }
+    await builder.send();
+};
+const flushNow = async () => {
+    const toSend = buffer;
+    buffer = [];
+    if (!isEnabled())
+        return;
+    if (toSend.length === 0)
+        return;
+    const maxRetries = 3;
+    const attemptPost = async (attempt) => {
+        try {
+            await postBatch(toSend);
+        }
+        catch {
+            if (attempt >= maxRetries)
+                return;
+            const backoffMs = 100 * 2 ** attempt;
+            await delay(backoffMs);
+            await attemptPost(attempt + 1);
+        }
+    };
+    await attemptPost(0);
+};
+const scheduleFlush = async () => {
+    if (flushPromise !== undefined)
+        return flushPromise;
+    const promise = new Promise((resolve) => {
+        const run = async () => {
+            try {
+                await flushNow();
+            }
+            finally {
+                resolve(undefined);
+            }
+        };
+        if (typeof globalThis.setTimeout !== 'function') {
+            void run();
+            return;
+        }
+        globalThis.setTimeout(() => {
+            void run();
+        }, 0);
+    });
+    flushPromise = promise.finally(() => {
+        flushPromise = undefined;
+    });
+    return flushPromise;
+};
+export const HttpLogger = Object.freeze({
+    async enqueue(event) {
+        if (!isEnabled())
+            return Promise.resolve(); // NOSONAR
+        buffer.push(event);
+        const batchSize = Math.max(1, Env.getInt('HTTP_LOG_BATCH_SIZE', 50));
+        if (buffer.length >= batchSize) {
+            return scheduleFlush();
+        }
+        return scheduleFlush();
+    },
+});
+export default HttpLogger;

package/src/config/logging/KvLogger.d.ts

@@ -0,0 +1,22 @@
+/**
+ * KV Logger
+ * Writes batches of log events to a KV namespace (Cloudflare Workers compatible)
+ *
+ * Enabled via env:
+ *  - KV_LOG_ENABLED (default: false)
+ *  - KV_NAMESPACE (binding name; default: 'CACHE')
+ *  - KV_LOG_RETENTION_DAYS (default: 30)
+ */
+export type KvLogEvent = {
+    timestamp: string;
+    level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+    message: string;
+    category?: string;
+    data?: unknown;
+    error?: string;
+};
+export declare const KvLogger: Readonly<{
+    enqueue(event: KvLogEvent): Promise<void>;
+}>;
+export default KvLogger;
+//# sourceMappingURL=KvLogger.d.ts.map

package/src/config/logging/KvLogger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KvLogger.d.ts","sourceRoot":"","sources":["../../../../src/config/logging/KvLogger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AA2IF,eAAO,MAAM,QAAQ;mBACE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;EAkB/C,CAAC;AAEH,eAAe,QAAQ,CAAC"}

package/src/config/logging/KvLogger.js

@@ -0,0 +1,143 @@
+/**
+ * KV Logger
+ * Writes batches of log events to a KV namespace (Cloudflare Workers compatible)
+ *
+ * Enabled via env:
+ *  - KV_LOG_ENABLED (default: false)
+ *  - KV_NAMESPACE (binding name; default: 'CACHE')
+ *  - KV_LOG_RETENTION_DAYS (default: 30)
+ */
+import { Cloudflare } from '../cloudflare';
+import { Env } from '../env';
+const getRetentionTtlSeconds = () => {
+    const days = Env.getInt('KV_LOG_RETENTION_DAYS', 30);
+    const safeDays = Number.isFinite(days) && days > 0 ? days : 30;
+    return safeDays * 24 * 60 * 60;
+};
+const getKvBindingName = () => {
+    const name = Env.get('KV_NAMESPACE', 'CACHE').trim();
+    return name.length > 0 ? name : 'CACHE';
+};
+const isEnabled = () => Env.getBool('KV_LOG_ENABLED', false);
+const safeRandom = () => {
+    try {
+        // Prefer crypto if available
+        const cryptoObj = globalThis.crypto;
+        if (cryptoObj?.getRandomValues) {
+            const bytes = new Uint8Array(8);
+            cryptoObj.getRandomValues(bytes);
+            return Array.from(bytes)
+                .map((b) => b.toString(16).padStart(2, '0'))
+                .join('');
+        }
+    }
+    catch {
+        // fall through
+    }
+    const generate = Math.random().toString(16).slice(2); // NOSONAR
+    const fallback = generate + Math.random().toString(16).slice(2); // NOSONAR this is not used for security
+    return fallback;
+};
+const buildKey = (timestampIso) => {
+    const date = timestampIso.slice(0, 10);
+    const hour = timestampIso.slice(11, 13);
+    return `logs:${date}:${hour}:${safeRandom()}`;
+};
+let buffer = [];
+let flushTimer;
+let flushPromise;
+const scheduleFlush = async () => {
+    if (flushPromise !== undefined)
+        return flushPromise;
+    // Fixed small batching window to reduce KV write volume.
+    const windowMs = 1000;
+    const promise = new Promise((resolve) => {
+        const run = async () => {
+            try {
+                await flushNow();
+            }
+            finally {
+                resolve(undefined);
+            }
+        };
+        if (typeof globalThis.setTimeout !== 'function') {
+            // microtask-ish
+            void run();
+            return;
+        }
+        flushTimer = globalThis.setTimeout(() => {
+            flushTimer = undefined;
+            void run();
+        }, windowMs);
+    });
+    flushPromise = promise.finally(() => {
+        flushPromise = undefined;
+    });
+    return flushPromise;
+};
+const getKv = () => {
+    const bindingName = getKvBindingName();
+    return Cloudflare.getKVBinding(bindingName);
+};
+const putBatch = async (kv, events) => {
+    if (events.length === 0)
+        return;
+    const timestamp = events.at(-1)?.timestamp ?? new Date().toISOString();
+    const key = buildKey(timestamp);
+    const payload = JSON.stringify({
+        version: 1,
+        createdAt: new Date().toISOString(),
+        count: events.length,
+        events,
+    });
+    const opts = { expirationTtl: getRetentionTtlSeconds() };
+    await kv.put(key, payload, opts);
+};
+const flushNow = async () => {
+    if (!isEnabled()) {
+        buffer = [];
+        return;
+    }
+    const kv = getKv();
+    if (kv === null) {
+        buffer = [];
+        return;
+    }
+    const toSend = buffer;
+    buffer = [];
+    try {
+        await putBatch(kv, toSend);
+    }
+    catch {
+        // Best-effort: never throw from logging.
+    }
+};
+const flushSoon = async () => {
+    if (flushPromise !== undefined)
+        return flushPromise;
+    flushPromise = Promise.resolve()
+        .then(async () => flushNow())
+        .finally(() => {
+        flushPromise = undefined;
+    });
+    return flushPromise;
+};
+export const KvLogger = Object.freeze({
+    async enqueue(event) {
+        if (!isEnabled())
+            return Promise.resolve();
+        buffer.push(event);
+        // Basic size guard: flush if it gets too large
+        const maxBatch = 100;
+        if (buffer.length >= maxBatch) {
+            // Cancel scheduled flush and flush immediately
+            if (flushTimer !== undefined) {
+                globalThis.clearTimeout(flushTimer);
+                flushTimer = undefined;
+            }
+            return flushSoon();
+        }
+        return scheduleFlush();
+    },
+});
+export default KvLogger;

package/src/config/logging/SlackLogger.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Slack Notification Logger
+ * Sends warn/error/fatal log events to a Slack incoming webhook.
+ *
+ * Enabled via env:
+ *  - SLACK_LOG_ENABLED (default: false)
+ *  - SLACK_LOG_WEBHOOK_URL
+ *  - SLACK_LOG_LEVELS (comma-separated; default: "warn,error,fatal")
+ *  - SLACK_LOG_BATCH_WINDOW_MS (default: 5000)
+ */
+export type SlackLogEvent = {
+    timestamp: string;
+    level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+    message: string;
+    category?: string;
+    data?: unknown;
+    error?: string;
+};
+export declare const SlackLogger: Readonly<{
+    enqueue(event: SlackLogEvent): Promise<void>;
+}>;
+export default SlackLogger;
+//# sourceMappingURL=SlackLogger.d.ts.map

package/src/config/logging/SlackLogger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SlackLogger.d.ts","sourceRoot":"","sources":["../../../../src/config/logging/SlackLogger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAoHF,eAAO,MAAM,WAAW;mBACD,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;EAclD,CAAC;AAEH,eAAe,WAAW,CAAC"}