@zintrust/core 0.4.15 → 0.4.17

package/src/cache/CacheDriver.ts

@@ -0,0 +1,39 @@
+/**
+ * Cache Driver Interface
+ * Defines contract for different cache implementations
+ */
+
+export interface CacheDriver {
+  /**
+   * Get an item from the cache
+   */
+  get<T>(key: string): Promise<T | null>;
+
+  /**
+   * Store an item in the cache
+   */
+  set<T>(key: string, value: T, ttl?: number): Promise<void>;
+
+  /**
+   * Remove an item from the cache
+   */
+  delete(key: string): Promise<void>;
+
+  /**
+   * Clear all items from the cache
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Check if an item exists in the cache
+   */
+  has(key: string): Promise<boolean>;
+
+  /**
+   * Dispose of resources (optional cleanup method)
+   */
+  dispose?(): Promise<void>;
+}
+
+// Runtime marker to make this type-only module coverable in V8 coverage.
+export const CACHE_DRIVER_INTERFACE = 'CacheDriver';

package/src/cache/CacheDriverRegistry.ts

@@ -0,0 +1,29 @@
+import type { CacheDriver } from '@cache/CacheDriver';
+import type { CacheDriverConfig } from '@config/type';
+
+export type CacheDriverFactory = (config: CacheDriverConfig) => CacheDriver;
+
+const registry = new Map<CacheDriverConfig['driver'], CacheDriverFactory>();
+
+function register(driver: CacheDriverConfig['driver'], factory: CacheDriverFactory): void {
+  registry.set(driver, factory);
+}
+
+function get(driver: CacheDriverConfig['driver']): CacheDriverFactory | undefined {
+  return registry.get(driver);
+}
+
+function has(driver: CacheDriverConfig['driver']): boolean {
+  return registry.has(driver);
+}
+
+function list(): Array<CacheDriverConfig['driver']> {
+  return Array.from(registry.keys());
+}
+
+export const CacheDriverRegistry = Object.freeze({
+  register,
+  get,
+  has,
+  list,
+});

package/src/cache/CacheRuntimeRegistration.ts

@@ -0,0 +1,24 @@
+import type { CacheConfig } from '@config/cache';
+
+import { CacheDriverRegistry } from '@cache/CacheDriverRegistry';
+import { KVDriver } from '@cache/drivers/KVDriver';
+import { KVRemoteDriver } from '@cache/drivers/KVRemoteDriver';
+import { MemoryDriver } from '@cache/drivers/MemoryDriver';
+import { MongoDriver } from '@cache/drivers/MongoDriver';
+import { RedisDriver } from '@cache/drivers/RedisDriver';
+
+/**
+ * Register cache drivers from runtime config.
+ *
+ * This follows the framework's config-driven availability pattern:
+ * - Built-in driver factories are registered so config entries can reference them.
+ * - Named cache stores are still resolved from `cacheConfig.drivers[storeName]`.
+ * - Unknown store names throw when explicitly selected via `cacheConfig.getDriver(name)`.
+ */
+export function registerCachesFromRuntimeConfig(_config: CacheConfig): void {
+  CacheDriverRegistry.register('memory', () => MemoryDriver.create());
+  CacheDriverRegistry.register('redis', () => RedisDriver.create());
+  CacheDriverRegistry.register('mongodb', () => MongoDriver.create());
+  CacheDriverRegistry.register('kv', () => KVDriver.create());
+  CacheDriverRegistry.register('kv-remote', () => KVRemoteDriver.create());
+}

package/src/cache/drivers/KVDriver.ts

@@ -0,0 +1,63 @@
+/**
+ * Cloudflare KV Cache Driver
+ * Interfaces with the native KV binding in Cloudflare Workers
+ */
+
+import type { CacheDriver } from '@cache/CacheDriver';
+import { Cloudflare } from '@config/cloudflare';
+import { Logger } from '@config/logger';
+
+/**
+ * Create a new KV driver instance
+ */
+const create = (): CacheDriver => {
+  // In Cloudflare Workers, the KV namespace is usually bound to a variable in the environment
+  const kv = Cloudflare.getKVBinding('CACHE');
+
+  return {
+    async get<T>(key: string): Promise<T | null> {
+      if (kv === null) return null;
+      const value = await kv.get(key, { type: 'json' });
+      return (value as T | null) ?? null;
+    },
+
+    async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+      if (kv === null) {
+        Logger.warn('KV binding "CACHE" not found. Cache set ignored.');
+        return;
+      }
+
+      const options: { expirationTtl?: number } = {};
+      if (ttl !== undefined) {
+        // KV expirationTtl must be at least 60 seconds
+        options.expirationTtl = Math.max(60, ttl);
+      }
+
+      await kv.put(key, JSON.stringify(value), options);
+    },
+
+    async delete(key: string): Promise<void> {
+      if (kv === null) return;
+      await kv.delete(key);
+    },
+
+    async clear(): Promise<void> {
+      // KV doesn't support clearing all keys easily without listing and deleting
+      Logger.warn('KV clear() is not implemented due to Cloudflare KV limitations.');
+      await Promise.resolve();
+    },
+
+    async has(key: string): Promise<boolean> {
+      if (kv === null) return false;
+      const value = await kv.get(key);
+      return value !== null;
+    },
+  };
+};
+
+/**
+ * KVDriver namespace - sealed for immutability
+ */
+export const KVDriver = Object.freeze({
+  create,
+});

package/src/cache/drivers/KVRemoteDriver.ts

@@ -0,0 +1,400 @@
+/**
+ * KV Remote Cache Driver
+ *
+ * Calls a ZinTrust Cloudflare Worker KV proxy over HTTPS.
+ */
+
+import type { CacheDriver } from '@cache/CacheDriver';
+import { RemoteSignedJson, type RemoteSignedJsonSettings } from '@common/RemoteSignedJson';
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+type KvValueType = 'text' | 'json' | 'arrayBuffer';
+
+type KvGetResponse = { value: unknown };
+type KvPutResponse = { ok: true };
+type KvDeleteResponse = { ok: true };
+
+type KvRemoteSettings = {
+  baseUrl: string;
+  keyId: string;
+  secret: string;
+  defaultNamespace: string;
+  timeoutMs: number;
+};
+
+type CloudflareKvCreds = {
+  accountId: string;
+  apiToken: string;
+  namespaceId: string;
+  namespaceTitle: string;
+};
+
+type CloudflareNamespacesResponse = {
+  success?: boolean;
+  result?: Array<{ id?: string; title?: string }>;
+  result_info?: { page?: number; total_pages?: number };
+  errors?: unknown;
+};
+
+const resolveSigningPrefix = (baseUrl: string): string | undefined => {
+  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: string): string | undefined =>
+  defaultNamespace.trim() === '' ? undefined : defaultNamespace;
+
+const getSettings = (): KvRemoteSettings => ({
+  baseUrl: Env.get('KV_REMOTE_URL'),
+  keyId: Env.get('KV_REMOTE_KEY_ID'),
+  secret: Env.get('KV_REMOTE_SECRET', Env.APP_KEY),
+  defaultNamespace: Env.get('KV_REMOTE_NAMESPACE'),
+  timeoutMs: Env.getInt('ZT_PROXY_TIMEOUT_MS', Env.REQUEST_TIMEOUT),
+});
+
+const getCloudflareCreds = (): CloudflareKvCreds => ({
+  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 = (): boolean => {
+  const creds = getCloudflareCreds();
+  return creds.accountId !== '' && creds.apiToken !== '';
+};
+
+const hasProxySigningCreds = (settings: KvRemoteSettings): boolean =>
+  settings.keyId.trim() !== '' && settings.secret.trim() !== '';
+
+const buildCloudflareValueUrl = (
+  creds: { accountId: string; namespaceId: string },
+  key: string,
+  ttlSeconds?: number
+): string => {
+  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: string, url: string, init: RequestInit): Promise<Response> => {
+  const headers = new Headers(init.headers);
+  headers.set('Authorization', `Bearer ${apiToken}`);
+  return fetch(url, { ...init, headers });
+};
+
+const parseJsonOrThrow = <T>(text: string, message: string): T => {
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    throw ErrorFactory.createConnectionError(message, { body: text });
+  }
+};
+
+const listNamespacesPage = async (params: {
+  accountId: string;
+  apiToken: string;
+  page: number;
+  perPage: number;
+}): Promise<{ namespaces: Array<{ id: string; title: string }>; totalPages: number }> => {
+  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<CloudflareNamespacesResponse>(
+    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: Array<{ id: string; title: string }>,
+  title: string
+): string | null => {
+  const found = namespaces.find((ns) => ns.title === title);
+  return found?.id ?? null;
+};
+
+const createRemoteSettings = (settings: KvRemoteSettings): RemoteSignedJsonSettings => ({
+  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 / KV_REMOTE_SECRET)',
+  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: {
+  accountId: string;
+  apiToken: string;
+}): Promise<Array<{ id: string; title: string }>> => {
+  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 = (): (() => Promise<string>) => {
+  let cachedNamespaceId: string | null = null;
+  let cachedNamespaceTitle: string | null = null;
+  let cachedAccountId: string | null = null;
+
+  return async (): Promise<string> => {
+    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: () => Promise<string>
+): {
+  getJson: <T>(key: string) => Promise<T | null>;
+  putJson: (key: string, value: unknown, ttlSeconds?: number) => Promise<void>;
+  deleteKey: (key: string) => Promise<void>;
+} => {
+  const getJson = async <T>(key: string): Promise<T | null> => {
+    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) as T;
+    } catch {
+      return null;
+    }
+  };
+
+  const putJson = async (key: string, value: unknown, ttlSeconds?: number): Promise<void> => {
+    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: string): Promise<void> => {
+    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 createKvRemoteDriver = (): CacheDriver => {
+  const resolveNamespaceId = createCloudflareNamespaceIdResolver();
+  const cf = createCloudflareKvApiClient(resolveNamespaceId);
+
+  return {
+    async get<T>(key: string): Promise<T | null> {
+      const settings = getSettings();
+      if (!hasProxySigningCreds(settings) && hasCloudflareApiCreds()) return cf.getJson<T>(key);
+
+      try {
+        const remote = createRemoteSettings(settings);
+        const out = await RemoteSignedJson.request<KvGetResponse>(remote, '/zin/kv/get', {
+          namespace: normalizeNamespace(settings.defaultNamespace),
+          key,
+          type: 'json' satisfies KvValueType,
+        });
+        return (out.value as T | null) ?? null;
+      } catch (error) {
+        if (!hasCloudflareApiCreds()) throw error;
+        Logger.warn('KV remote proxy GET failed; falling back to Cloudflare KV API', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return cf.getJson<T>(key);
+      }
+    },
+
+    async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+      const settings = getSettings();
+      if (!hasProxySigningCreds(settings) && hasCloudflareApiCreds()) {
+        await cf.putJson(key, value, ttl);
+        return;
+      }
+
+      try {
+        const remote = createRemoteSettings(settings);
+        await RemoteSignedJson.request<KvPutResponse>(remote, '/zin/kv/put', {
+          namespace: normalizeNamespace(settings.defaultNamespace),
+          key,
+          value,
+          ttlSeconds: ttl,
+        });
+      } catch (error) {
+        if (!hasCloudflareApiCreds()) throw error;
+        Logger.warn('KV remote proxy PUT failed; falling back to Cloudflare KV API', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        await cf.putJson(key, value, ttl);
+      }
+    },
+
+    async delete(key: string): Promise<void> {
+      const settings = getSettings();
+      if (!hasProxySigningCreds(settings) && hasCloudflareApiCreds()) {
+        await cf.deleteKey(key);
+        return;
+      }
+
+      try {
+        const remote = createRemoteSettings(settings);
+        await RemoteSignedJson.request<KvDeleteResponse>(remote, '/zin/kv/delete', {
+          namespace: normalizeNamespace(settings.defaultNamespace),
+          key,
+        });
+      } catch (error) {
+        if (!hasCloudflareApiCreds()) throw error;
+        Logger.warn('KV remote proxy DELETE failed; falling back to Cloudflare KV API', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        await cf.deleteKey(key);
+      }
+    },
+
+    async clear(): Promise<void> {
+      Logger.warn('KV remote clear() is not implemented.');
+      await Promise.resolve();
+    },
+
+    async has(key: string): Promise<boolean> {
+      if (!hasCloudflareApiCreds()) return (await this.get(key)) !== null;
+      const settings = getSettings();
+      if (!hasProxySigningCreds(settings)) return (await cf.getJson<unknown>(key)) !== null;
+      return (await this.get(key)) !== null;
+    },
+  };
+};
+
+export const KVRemoteDriver = Object.freeze({
+  create: createKvRemoteDriver,
+});
+
+export default KVRemoteDriver;

package/src/cache/drivers/MemoryDriver.ts

@@ -0,0 +1,98 @@
+/**
+ * Memory Cache Driver
+ * Simple in-memory storage for local development
+ */
+
+import type { CacheDriver } from '@cache/CacheDriver';
+
+type UnrefableTimer = { unref: () => void };
+
+function isUnrefableTimer(value: unknown): value is UnrefableTimer {
+  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 = (): CacheDriver => {
+  const storage = new Map<string, { value: unknown; expires: number | null }>();
+
+  // 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<T>(key: string): Promise<T | null> {
+      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 as T;
+    },
+
+    async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+      const expires = ttl === undefined ? null : Date.now() + ttl * 1000;
+      storage.set(key, { value, expires });
+      await Promise.resolve();
+    },
+
+    async delete(key: string): Promise<void> {
+      storage.delete(key);
+      await Promise.resolve();
+    },
+
+    async clear(): Promise<void> {
+      storage.clear();
+      await Promise.resolve();
+    },
+
+    async has(key: string): Promise<boolean> {
+      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(): Promise<void> {
+      clearInterval(cleanupInterval);
+      storage.clear();
+      await Promise.resolve();
+    },
+  };
+};
+
+/**
+ * MemoryDriver namespace - sealed for immutability
+ */
+export const MemoryDriver = Object.freeze({
+  create,
+});