@zintrust/core 3.5.1 → 3.5.2

package/src/cache/drivers/KVRemoteDriver.js

@@ -0,0 +1,311 @@
+/**
+ * KV Remote Cache Driver
+ *
+ * Calls a ZinTrust Cloudflare Worker KV proxy over HTTPS.
+ */
+import { RemoteSignedJson } from '../../common/RemoteSignedJson.js';
+import { Env } from '../../config/env.js';
+import { Logger } from '../../config/logger.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { normalizeSigningCredentials } from '../../proxy/SigningService.js';
+const resolveSigningPrefix = (baseUrl) => {
+    try {
+        const parsed = new URL(baseUrl);
+        const path = parsed.pathname.endsWith('/') ? parsed.pathname.slice(0, -1) : parsed.pathname;
+        if (path === '' || path === '/')
+            return undefined;
+        return path;
+    }
+    catch {
+        return undefined;
+    }
+};
+const normalizeNamespace = (defaultNamespace) => defaultNamespace.trim() === '' ? undefined : defaultNamespace;
+const getSettings = () => ({
+    baseUrl: Env.get('KV_REMOTE_URL'),
+    keyId: Env.get('KV_REMOTE_KEY_ID'),
+    secret: Env.get('KV_REMOTE_SECRET', ''),
+    defaultNamespace: Env.get('KV_REMOTE_NAMESPACE'),
+    timeoutMs: Env.getInt('ZT_PROXY_TIMEOUT_MS', Env.REQUEST_TIMEOUT),
+});
+const getCloudflareCreds = () => ({
+    accountId: Env.get('KV_ACCOUNT_ID', Env.get('CLOUDFLARE_ACCOUNT_ID', '')).trim(),
+    apiToken: Env.get('KV_API_TOKEN', Env.get('CLOUDFLARE_API_TOKEN', '')).trim(),
+    namespaceId: Env.get('KV_NAMESPACE_ID', Env.get('CLOUDFLARE_KV_NAMESPACE_ID', '')).trim(),
+    namespaceTitle: Env.get('KV_NAMESPACE', '').trim(),
+});
+const hasCloudflareApiCreds = () => {
+    const creds = getCloudflareCreds();
+    return creds.accountId !== '' && creds.apiToken !== '';
+};
+const hasProxySigningCreds = (settings) => {
+    const normalized = normalizeSigningCredentials({
+        keyId: settings.keyId,
+        secret: settings.secret,
+    });
+    return normalized.keyId.trim() !== '' && normalized.secret.trim() !== '';
+};
+const buildCloudflareValueUrl = (creds, key, ttlSeconds) => {
+    const base = `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(creds.accountId)}/storage/kv/namespaces/${encodeURIComponent(creds.namespaceId)}/values/${encodeURIComponent(key)}`;
+    if (ttlSeconds === undefined)
+        return base;
+    const ttl = Math.max(60, Math.floor(ttlSeconds));
+    return ttl > 0 ? `${base}?expiration_ttl=${ttl}` : base;
+};
+const cfFetch = async (apiToken, url, init) => {
+    const headers = new Headers(init.headers);
+    headers.set('Authorization', `Bearer ${apiToken}`);
+    return fetch(url, { ...init, headers });
+};
+const parseJsonOrThrow = (text, message) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw ErrorFactory.createConnectionError(message, { body: text });
+    }
+};
+const listNamespacesPage = async (params) => {
+    const url = `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(params.accountId)}/storage/kv/namespaces?page=${params.page}&per_page=${params.perPage}`;
+    const res = await cfFetch(params.apiToken, url, { method: 'GET' });
+    const text = await res.text();
+    if (!res.ok) {
+        throw ErrorFactory.createConnectionError(`Cloudflare KV namespaces list failed (${res.status})`, {
+            status: res.status,
+            body: text,
+        });
+    }
+    const parsed = parseJsonOrThrow(text, 'Cloudflare KV namespaces list returned invalid JSON');
+    const namespaces = (parsed.result ?? [])
+        .map((ns) => ({
+        id: typeof ns.id === 'string' ? ns.id.trim() : '',
+        title: typeof ns.title === 'string' ? ns.title.trim() : '',
+    }))
+        .filter((ns) => ns.id !== '' && ns.title !== '');
+    const totalPages = Number(parsed.result_info?.total_pages ?? 1);
+    return {
+        namespaces,
+        totalPages: Number.isFinite(totalPages) && totalPages > 0 ? totalPages : 1,
+    };
+};
+const findNamespaceIdByTitle = (namespaces, title) => {
+    const found = namespaces.find((ns) => ns.title === title);
+    return found?.id ?? null;
+};
+const createRemoteSettings = (settings) => ({
+    baseUrl: settings.baseUrl,
+    keyId: settings.keyId,
+    secret: settings.secret,
+    timeoutMs: settings.timeoutMs,
+    signaturePathPrefixToStrip: resolveSigningPrefix(settings.baseUrl),
+    missingUrlMessage: 'KV remote proxy URL is missing (KV_REMOTE_URL)',
+    missingCredentialsMessage: `KV remote signing credentials are missing (${['KV_REMOTE', 'KEY_ID'].join('_')} / ${['KV_REMOTE', 'SECRET'].join('_')})`,
+    messages: {
+        unauthorized: 'KV remote proxy unauthorized',
+        forbidden: 'KV remote proxy forbidden',
+        rateLimited: 'KV remote proxy rate limited',
+        rejected: 'KV remote proxy rejected request',
+        error: 'KV remote proxy error',
+        timedOut: 'KV remote proxy request timed out',
+    },
+});
+const fetchAllNamespaces = async (params) => {
+    const first = await listNamespacesPage({
+        accountId: params.accountId,
+        apiToken: params.apiToken,
+        page: 1,
+        perPage: 100,
+    });
+    if (first.totalPages <= 1)
+        return first.namespaces;
+    const pages = Array.from({ length: first.totalPages - 1 }, (_v, idx) => idx + 2);
+    const rest = await Promise.all(pages.map(async (page) => listNamespacesPage({
+        accountId: params.accountId,
+        apiToken: params.apiToken,
+        page,
+        perPage: 100,
+    })));
+    return first.namespaces.concat(...rest.map((r) => r.namespaces));
+};
+const createCloudflareNamespaceIdResolver = () => {
+    let cachedNamespaceId = null;
+    let cachedNamespaceTitle = null;
+    let cachedAccountId = null;
+    return async () => {
+        const creds = getCloudflareCreds();
+        if (creds.namespaceId !== '')
+            return creds.namespaceId;
+        if (cachedNamespaceId !== null &&
+            cachedNamespaceTitle === creds.namespaceTitle &&
+            cachedAccountId === creds.accountId) {
+            return cachedNamespaceId;
+        }
+        if (creds.namespaceTitle === '') {
+            throw ErrorFactory.createConfigError('Cloudflare KV namespace id is missing (KV_NAMESPACE_ID) and no namespace title is provided (KV_NAMESPACE)');
+        }
+        const all = await fetchAllNamespaces({ accountId: creds.accountId, apiToken: creds.apiToken });
+        const match = findNamespaceIdByTitle(all, creds.namespaceTitle);
+        if (match === null) {
+            throw ErrorFactory.createConfigError('Cloudflare KV namespace not found', {
+                namespaceTitle: creds.namespaceTitle,
+            });
+        }
+        cachedNamespaceId = match;
+        cachedNamespaceTitle = creds.namespaceTitle;
+        cachedAccountId = creds.accountId;
+        return match;
+    };
+};
+const createCloudflareKvApiClient = (resolveNamespaceId) => {
+    const getJson = async (key) => {
+        const creds = getCloudflareCreds();
+        const namespaceId = await resolveNamespaceId();
+        const url = buildCloudflareValueUrl({ accountId: creds.accountId, namespaceId }, key);
+        const res = await cfFetch(creds.apiToken, url, { method: 'GET' });
+        if (res.status === 404)
+            return null;
+        const text = await res.text();
+        if (!res.ok) {
+            throw ErrorFactory.createConnectionError(`Cloudflare KV GET failed (${res.status})`, {
+                status: res.status,
+                body: text,
+            });
+        }
+        if (text.trim() === '')
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+    };
+    const putJson = async (key, value, ttlSeconds) => {
+        const creds = getCloudflareCreds();
+        const namespaceId = await resolveNamespaceId();
+        const url = buildCloudflareValueUrl({ accountId: creds.accountId, namespaceId }, key, ttlSeconds);
+        const body = JSON.stringify(value);
+        const res = await cfFetch(creds.apiToken, url, {
+            method: 'PUT',
+            headers: { 'content-type': 'application/json' },
+            body,
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw ErrorFactory.createConnectionError(`Cloudflare KV PUT failed (${res.status})`, {
+                status: res.status,
+                body: text,
+            });
+        }
+    };
+    const deleteKey = async (key) => {
+        const creds = getCloudflareCreds();
+        const namespaceId = await resolveNamespaceId();
+        const url = buildCloudflareValueUrl({ accountId: creds.accountId, namespaceId }, key);
+        const res = await cfFetch(creds.apiToken, url, { method: 'DELETE' });
+        const text = await res.text();
+        if (!res.ok && res.status !== 404) {
+            throw ErrorFactory.createConnectionError(`Cloudflare KV DELETE failed (${res.status})`, {
+                status: res.status,
+                body: text,
+            });
+        }
+    };
+    return { getJson, putJson, deleteKey };
+};
+const logKvRemoteProxyFallback = (operation, error) => {
+    Logger.warn(`KV remote proxy ${operation} failed; falling back to Cloudflare KV API`, Logger.withTraceSkipContext({
+        error: error instanceof Error ? error.message : String(error),
+    }));
+};
+const clearKvRemoteDriver = async () => {
+    Logger.warn('KV remote clear() is not implemented.');
+    await Promise.resolve();
+};
+const createKvRemoteHas = (getJson) => {
+    return async function has(key) {
+        if (!hasCloudflareApiCreds())
+            return (await this.get(key)) !== null;
+        const settings = getSettings();
+        if (!hasProxySigningCreds(settings))
+            return (await getJson(key)) !== null;
+        return (await this.get(key)) !== null;
+    };
+};
+const createKvRemoteDriver = () => {
+    const resolveNamespaceId = createCloudflareNamespaceIdResolver();
+    const cf = createCloudflareKvApiClient(resolveNamespaceId);
+    return {
+        async get(key) {
+            const settings = getSettings();
+            if (!hasProxySigningCreds(settings) && hasCloudflareApiCreds())
+                return cf.getJson(key);
+            try {
+                const remote = createRemoteSettings(settings);
+                const out = await RemoteSignedJson.request(remote, '/zin/kv/get', {
+                    namespace: normalizeNamespace(settings.defaultNamespace),
+                    key,
+                    type: 'json',
+                });
+                return out.value ?? null;
+            }
+            catch (error) {
+                if (!hasCloudflareApiCreds())
+                    throw error;
+                logKvRemoteProxyFallback('GET', error);
+                return cf.getJson(key);
+            }
+        },
+        async set(key, value, ttl) {
+            const settings = getSettings();
+            if (!hasProxySigningCreds(settings) && hasCloudflareApiCreds()) {
+                await cf.putJson(key, value, ttl);
+                return;
+            }
+            try {
+                const remote = createRemoteSettings(settings);
+                await RemoteSignedJson.request(remote, '/zin/kv/put', {
+                    namespace: normalizeNamespace(settings.defaultNamespace),
+                    key,
+                    value,
+                    ttlSeconds: ttl,
+                });
+            }
+            catch (error) {
+                if (!hasCloudflareApiCreds())
+                    throw error;
+                logKvRemoteProxyFallback('PUT', error);
+                await cf.putJson(key, value, ttl);
+            }
+        },
+        async delete(key) {
+            const settings = getSettings();
+            if (!hasProxySigningCreds(settings) && hasCloudflareApiCreds()) {
+                await cf.deleteKey(key);
+                return;
+            }
+            try {
+                const remote = createRemoteSettings(settings);
+                await RemoteSignedJson.request(remote, '/zin/kv/delete', {
+                    namespace: normalizeNamespace(settings.defaultNamespace),
+                    key,
+                });
+            }
+            catch (error) {
+                if (!hasCloudflareApiCreds())
+                    throw error;
+                logKvRemoteProxyFallback('DELETE', error);
+                await cf.deleteKey(key);
+            }
+        },
+        clear: clearKvRemoteDriver,
+        has: createKvRemoteHas(cf.getJson),
+        getRedisClient() {
+            throw ErrorFactory.createConfigError('getRedisClient() is only supported by Redis cache driver, not KV remote driver');
+        },
+    };
+};
+export const KVRemoteDriver = Object.freeze({
+    create: createKvRemoteDriver,
+});
+export default KVRemoteDriver;

package/src/cache/drivers/MemoryDriver.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Memory Cache Driver
+ * Simple in-memory storage for local development
+ */
+import type { CacheDriver } from '../CacheDriver.js';
+/**
+ * MemoryDriver namespace - sealed for immutability
+ */
+export declare const MemoryDriver: Readonly<{
+    create: () => CacheDriver;
+}>;
+//# sourceMappingURL=MemoryDriver.d.ts.map

package/src/cache/drivers/MemoryDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryDriver.d.ts","sourceRoot":"","sources":["../../../../src/cache/drivers/MemoryDriver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA8FtD;;GAEG;AACH,eAAO,MAAM,YAAY;kBA9EN,WAAW;EAgF5B,CAAC"}

package/src/cache/drivers/MemoryDriver.js

@@ -0,0 +1,83 @@
+/**
+ * Memory Cache Driver
+ * Simple in-memory storage for local development
+ */
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+function isUnrefableTimer(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'unref' in value &&
+        typeof value.unref === 'function');
+}
+/**
+ * Memory Cache Driver
+ * Simple in-memory storage for local development
+ * Refactored to Functional Object pattern
+ */
+const create = () => {
+    const storage = new Map();
+    // Background cleanup interval (runs every 60 seconds)
+    const cleanupInterval = setInterval(() => {
+        const now = Date.now();
+        for (const [key, item] of storage.entries()) {
+            if (item.expires !== null && item.expires < now) {
+                storage.delete(key);
+            }
+        }
+    }, 60_000); // 60 seconds
+    // Unref so it doesn't keep process alive (Node.js only)
+    if (isUnrefableTimer(cleanupInterval)) {
+        cleanupInterval.unref();
+    }
+    return {
+        async get(key) {
+            await Promise.resolve();
+            const item = storage.get(key);
+            if (item === undefined)
+                return null;
+            if (item.expires !== null && item.expires < Date.now()) {
+                storage.delete(key);
+                return null;
+            }
+            return item.value;
+        },
+        async set(key, value, ttl) {
+            const expires = ttl === undefined ? null : Date.now() + ttl * 1000;
+            storage.set(key, { value, expires });
+            await Promise.resolve();
+        },
+        async delete(key) {
+            storage.delete(key);
+            await Promise.resolve();
+        },
+        async clear() {
+            storage.clear();
+            await Promise.resolve();
+        },
+        async has(key) {
+            await Promise.resolve();
+            const item = storage.get(key);
+            if (item === undefined)
+                return false;
+            if (item.expires !== null && item.expires < Date.now()) {
+                storage.delete(key);
+                return false;
+            }
+            return true;
+        },
+        async dispose() {
+            clearInterval(cleanupInterval);
+            storage.clear();
+            await Promise.resolve();
+        },
+        getRedisClient() {
+            throw ErrorFactory.createConfigError('getRedisClient() is only supported by Redis cache driver, not memory driver');
+        },
+    };
+};
+/**
+ * MemoryDriver namespace - sealed for immutability
+ */
+export const MemoryDriver = Object.freeze({
+    create,
+});

package/src/cache/drivers/MongoDriver.d.ts

@@ -0,0 +1,17 @@
+/**
+ * MongoDB Cache Driver
+ * Uses MongoDB Atlas Data API (HTTPS) for zero-dependency integration
+ */
+import type { CacheDriver } from '../CacheDriver.js';
+/**
+ * MongoDB Cache Driver
+ * Uses MongoDB Atlas Data API (HTTPS) for zero-dependency integration
+ * Sealed namespace for immutability
+ */
+export declare const MongoDriver: Readonly<{
+    /**
+     * Create a new MongoDB driver instance
+     */
+    create(): CacheDriver;
+}>;
+//# sourceMappingURL=MongoDriver.d.ts.map

package/src/cache/drivers/MongoDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MongoDriver.d.ts","sourceRoot":"","sources":["../../../../src/cache/drivers/MongoDriver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAKtD;;;;GAIG;AACH,eAAO,MAAM,WAAW;IACtB;;OAEG;cACO,WAAW;EAkFrB,CAAC"}

package/src/cache/drivers/MongoDriver.js

@@ -0,0 +1,83 @@
+/**
+ * MongoDB Cache Driver
+ * Uses MongoDB Atlas Data API (HTTPS) for zero-dependency integration
+ */
+import { Env } from '../../config/env.js';
+import { Logger } from '../../config/logger.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+/**
+ * MongoDB Cache Driver
+ * Uses MongoDB Atlas Data API (HTTPS) for zero-dependency integration
+ * Sealed namespace for immutability
+ */
+export const MongoDriver = Object.freeze({
+    /**
+     * Create a new MongoDB driver instance
+     */
+    create() {
+        const uri = Env.MONGO_URI;
+        const db = Env.MONGO_DB;
+        const collection = 'cache';
+        const request = async (action, body) => {
+            if (uri === '') {
+                Logger.warn('MONGO_URI not configured. MongoDB Cache request ignored.');
+                return null;
+            }
+            try {
+                const response = await fetch(`${uri}/action/${action}`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Access-Control-Request-Headers': '*',
+                    },
+                    body: JSON.stringify({
+                        dataSource: 'Cluster0',
+                        database: db,
+                        collection: collection,
+                        ...body,
+                    }),
+                });
+                return await response.json();
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                ErrorFactory.createTryCatchError(`MongoDB Cache Error: ${message}`);
+                return null;
+            }
+        };
+        return {
+            async get(key) {
+                const result = (await request('findOne', { filter: { _id: key } }));
+                if (result?.document === undefined || result.document === null)
+                    return null;
+                const doc = result.document;
+                if (doc.expires !== null && doc.expires < Date.now()) {
+                    await this.delete(key);
+                    return null;
+                }
+                return doc.value;
+            },
+            async set(key, value, ttl) {
+                const expires = ttl === undefined ? null : Date.now() + ttl * 1000;
+                await request('updateOne', {
+                    filter: { _id: key },
+                    update: { $set: { value, expires } },
+                    upsert: true,
+                });
+            },
+            async delete(key) {
+                await request('deleteOne', { filter: { _id: key } });
+            },
+            async clear() {
+                await request('deleteMany', { filter: {} });
+            },
+            async has(key) {
+                const result = (await request('findOne', { filter: { _id: key } }));
+                return result?.document !== undefined && result.document !== null;
+            },
+            getRedisClient() {
+                throw ErrorFactory.createConfigError('getRedisClient() is only supported by Redis cache driver, not MongoDB driver');
+            },
+        };
+    },
+});

package/src/cache/drivers/RedisDriver.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Redis Cache Driver
+ * Zero-dependency implementation using Node.js native net module
+ */
+import type { CacheDriver } from '../CacheDriver.js';
+/**
+ * RedisDriver namespace - sealed for immutability
+ */
+export declare const RedisDriver: Readonly<{
+    create: () => CacheDriver;
+}>;
+//# sourceMappingURL=RedisDriver.d.ts.map

package/src/cache/drivers/RedisDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisDriver.d.ts","sourceRoot":"","sources":["../../../../src/cache/drivers/RedisDriver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAsdtD;;GAEG;AACH,eAAO,MAAM,WAAW;kBAbL,WAAW;EAe5B,CAAC"}