@zintrust/core 0.4.17 → 0.4.18

package/src/common/AwsSigV4.ts

@@ -1,116 +0,0 @@
-import { createHash, createHmac } from '@node-singletons/crypto';
-
-export type AwsSigV4Credentials = {
-  accessKeyId: string;
-  secretAccessKey: string;
-  sessionToken?: string;
-};
-
-type CanonicalizedHeaders = {
-  canonicalHeaders: string;
-  signedHeaders: string;
-};
-
-export const AwsSigV4 = Object.freeze({
-  sha256Hex(data: string | Uint8Array): string {
-    return createHash('sha256').update(data).digest('hex');
-  },
-
-  hmacSha256(key: Uint8Array | string, data: string): Uint8Array {
-    return createHmac('sha256', key).update(data).digest();
-  },
-
-  toAmzDate(date: Date): { amzDate: string; dateStamp: string } {
-    const yyyy = String(date.getUTCFullYear());
-    const mm = String(date.getUTCMonth() + 1).padStart(2, '0');
-    const dd = String(date.getUTCDate()).padStart(2, '0');
-    const hh = String(date.getUTCHours()).padStart(2, '0');
-    const mi = String(date.getUTCMinutes()).padStart(2, '0');
-    const ss = String(date.getUTCSeconds()).padStart(2, '0');
-
-    const dateStamp = `${yyyy}${mm}${dd}`;
-    const amzDate = `${dateStamp}T${hh}${mi}${ss}Z`;
-    return { amzDate, dateStamp };
-  },
-
-  deriveSigningKey(params: {
-    secretAccessKey: string;
-    dateStamp: string;
-    region: string;
-    service: string;
-  }): Uint8Array {
-    const kDate = this.hmacSha256(`AWS4${params.secretAccessKey}`, params.dateStamp);
-    const kRegion = this.hmacSha256(kDate, params.region);
-    const kService = this.hmacSha256(kRegion, params.service);
-    return this.hmacSha256(kService, 'aws4_request');
-  },
-
-  canonicalizeHeaders(headers: Record<string, string>): CanonicalizedHeaders {
-    const sortedHeaderKeys = Object.keys(headers).sort((a, b) => a.localeCompare(b));
-
-    const canonicalHeaders = sortedHeaderKeys
-      .map((k) => `${k}:${String(headers[k]).trim().replaceAll(/\s+/g, ' ')}`)
-      .join('\n');
-
-    const signedHeaders = sortedHeaderKeys.join(';');
-
-    return { canonicalHeaders, signedHeaders };
-  },
-
-  buildAuthorization(params: {
-    method: string;
-    canonicalUri: string;
-    canonicalQueryString: string;
-    headers: Record<string, string>;
-    payloadHash: string;
-    region: string;
-    service: string;
-    amzDate: string;
-    dateStamp: string;
-    credentials: AwsSigV4Credentials;
-  }): { authorization: string; signedHeaders: string } {
-    const sessionToken = params.credentials.sessionToken;
-    if (
-      typeof sessionToken === 'string' &&
-      sessionToken.trim() !== '' &&
-      params.headers['x-amz-security-token'] === undefined
-    ) {
-      params.headers['x-amz-security-token'] = sessionToken;
-    }
-
-    const { canonicalHeaders, signedHeaders } = this.canonicalizeHeaders(params.headers);
-
-    const canonicalRequest = [
-      params.method,
-      params.canonicalUri,
-      params.canonicalQueryString,
-      `${canonicalHeaders}\n`,
-      signedHeaders,
-      params.payloadHash,
-    ].join('\n');
-
-    const algorithm = 'AWS4-HMAC-SHA256';
-    const credentialScope = `${params.dateStamp}/${params.region}/${params.service}/aws4_request`;
-    const stringToSign = [
-      algorithm,
-      params.amzDate,
-      credentialScope,
-      this.sha256Hex(canonicalRequest),
-    ].join('\n');
-
-    const signingKey = this.deriveSigningKey({
-      secretAccessKey: params.credentials.secretAccessKey,
-      dateStamp: params.dateStamp,
-      region: params.region,
-      service: params.service,
-    });
-
-    const signature = createHmac('sha256', signingKey).update(stringToSign).digest('hex');
-
-    const authorization =
-      `${algorithm} Credential=${params.credentials.accessKeyId}/${credentialScope}, ` +
-      `SignedHeaders=${signedHeaders}, Signature=${signature}`;
-
-    return { authorization, signedHeaders };
-  },
-});

package/src/common/ExternalServiceUtils.ts

@@ -1,157 +0,0 @@
-/**
- * Shared Utilities for External Service Drivers
- * Common patterns for API calls, environment variable reading, and error handling
- */
-
-import { Env } from '@config/env';
-import { ErrorFactory } from '@exceptions/ZintrustError';
-
-/**
- * Environment variable reader with fallback support
- * Handles both Env.get() and process.env for maximum compatibility
- */
-export const readEnvString = (key: string, fallback = ''): string => {
-  const anyEnv = Env as { get?: (k: string, d?: string) => string; [key: string]: unknown };
-  const fromEnv = typeof anyEnv.get === 'function' ? anyEnv.get(key, '') : '';
-  if (typeof fromEnv === 'string' && fromEnv.trim() !== '') {
-    return fromEnv;
-  }
-  const getEnv = anyEnv[key];
-  if (typeof getEnv === 'string' && getEnv.trim() !== '') {
-    return getEnv;
-  }
-  if (typeof process !== 'undefined') {
-    const raw = process.env?.[key];
-    if (typeof raw === 'string') return raw;
-  }
-  return fallback;
-};
-
-/**
- * Validate required parameters for external service calls
- */
-export const validateRequiredParams = (
-  params: Record<string, unknown>,
-  required: string[]
-): void => {
-  for (const param of required) {
-    const value = params[param];
-    if (
-      value === null ||
-      value === undefined ||
-      (typeof value === 'string' && value.length === 0)
-    ) {
-      throw ErrorFactory.createValidationError(`${param} is required`);
-    }
-  }
-};
-
-/**
- * Create standardized API error response
- */
-export const createApiError = (message: string, service: string): Error => {
-  return ErrorFactory.createValidationError(`${service} API error: ${message}`);
-};
-
-/**
- * Common fetch wrapper with error handling
- */
-export const safeFetch = async (url: string, options: RequestInit): Promise<Response> => {
-  try {
-    const response = await globalThis.fetch(url, options);
-
-    if (!response.ok) {
-      throw ErrorFactory.createValidationError(`HTTP ${response.status}: ${response.statusText}`);
-    }
-
-    return response;
-  } catch (error) {
-    throw ErrorFactory.createValidationError(
-      error instanceof Error ? error.message : 'Unknown fetch error'
-    );
-  }
-};
-
-/**
- * Standard API response builder
- */
-export const buildApiResponse = <T>(
-  success: boolean,
-  data?: T,
-  error?: string
-): { success: boolean; data?: T; error?: string } => {
-  const response: { success: boolean; data?: T; error?: string } = { success };
-
-  if (data !== undefined) {
-    response.data = data;
-  }
-
-  if (error !== undefined) {
-    response.error = error;
-  }
-
-  return response;
-};
-
-/**
- * Health check utilities
- */
-export const HealthUtils = {
-  /**
-   * Get process uptime safely
-   */
-  getUptime(): number {
-    return typeof process !== 'undefined' && typeof process.uptime === 'function'
-      ? process.uptime()
-      : 0;
-  },
-
-  /**
-   * Get current timestamp
-   */
-  getTimestamp(): string {
-    return new Date().toISOString();
-  },
-
-  /**
-   * Check if in production
-   */
-  isProduction(environment: string): boolean {
-    return environment === 'production';
-  },
-
-  /**
-   * Build health response
-   */
-  buildHealthResponse(
-    status: 'healthy' | 'unhealthy' | 'alive' | 'ready' | 'not_ready',
-    environment: string,
-    extra?: Record<string, unknown>
-  ) {
-    const base = {
-      status,
-      timestamp: HealthUtils.getTimestamp(),
-      environment,
-      ...extra,
-    };
-
-    return base;
-  },
-
-  /**
-   * Build error health response
-   */
-  buildErrorResponse(
-    status: 'unhealthy' | 'not_ready',
-    environment: string,
-    error: Error,
-    extra?: Record<string, unknown>
-  ) {
-    const isProd = HealthUtils.isProduction(environment);
-
-    return HealthUtils.buildHealthResponse(status, environment, {
-      error: isProd ? 'Service unavailable' : error.message,
-      ...extra,
-    });
-  },
-};

package/src/common/HealthRoutes.ts

@@ -1,194 +0,0 @@
-/**
- * Shared Health Route Handlers
- * Extracted to eliminate duplication between CoreRoutes.ts and routes/health.ts
- */
-
-import { appConfig } from '@/config/app';
-import { RuntimeHealthProbes } from '@/health/RuntimeHealthProbes';
-import type { IRequest } from '@/http/Request';
-import type { IResponse } from '@/http/Response';
-import { HealthUtils } from '@common/ExternalServiceUtils';
-import { databaseConfig } from '@config/database';
-import { Env } from '@config/env';
-import { Logger } from '@config/logger';
-import type { IRouter } from '@core-routes/Router';
-import { Router } from '@core-routes/Router';
-import { useDatabase } from '@orm/Database';
-import { QueryBuilder } from '@orm/QueryBuilder';
-
-const isMissingDefaultDatabase = (error: unknown): boolean => {
-  if (typeof error !== 'object' || error === null) return false;
-  const maybe = error as { name?: string; code?: string; message?: string };
-  if (maybe.name !== 'ConfigError' || maybe.code !== 'CONFIG_ERROR') return false;
-  return typeof maybe.message === 'string'
-    ? maybe.message.includes("Database connection 'default' is not registered")
-    : false;
-};
-
-const ensureDefaultDatabase = async (): Promise<ReturnType<typeof useDatabase> | null> => {
-  try {
-    return useDatabase();
-  } catch (error) {
-    if (!isMissingDefaultDatabase(error)) throw error;
-
-    try {
-      const mod = await import('@orm/DatabaseRuntimeRegistration');
-      mod.registerDatabasesFromRuntimeConfig?.(databaseConfig);
-      return useDatabase();
-    } catch (innerError) {
-      Logger.warn('Database registration failed; skipping health DB check', innerError as Error);
-      return null;
-    }
-  }
-};
-
-/**
- * Health check endpoint handler
- */
-async function handleHealthRoute(_req: IRequest, res: IResponse): Promise<void> {
-  const environment = Env.NODE_ENV ?? 'development';
-
-  try {
-    const db = await ensureDefaultDatabase();
-    if (db === null) {
-      const uptime = HealthUtils.getUptime();
-      res.json(
-        HealthUtils.buildHealthResponse('healthy', environment, {
-          uptime,
-          database: 'unconfigured',
-        })
-      );
-      return;
-    }
-    const maybeIsConnected = (db as unknown as { isConnected?: unknown }).isConnected;
-    const maybeConnect = (db as unknown as { connect?: unknown }).connect;
-    if (typeof maybeIsConnected === 'function' && maybeIsConnected.call(db) === false) {
-      if (typeof maybeConnect === 'function') {
-        await maybeConnect.call(db);
-      }
-    }
-    await QueryBuilder.ping(db);
-
-    const uptime = HealthUtils.getUptime();
-
-    res.json(
-      HealthUtils.buildHealthResponse('healthy', environment, {
-        uptime,
-        database: 'connected',
-      })
-    );
-  } catch (error) {
-    Logger.error('Health check failed:', error);
-
-    res.setStatus(503).json(
-      HealthUtils.buildErrorResponse('unhealthy', environment, error as Error, {
-        database: 'disconnected',
-      })
-    );
-  }
-}
-
-/**
- * Liveness probe endpoint handler
- */
-function handleHealthLiveRoute(_req: IRequest, res: IResponse): void {
-  const uptime = HealthUtils.getUptime();
-
-  res.json(
-    HealthUtils.buildHealthResponse('alive', Env.NODE_ENV ?? 'development', {
-      uptime,
-    })
-  );
-}
-
-/**
- * Readiness probe endpoint handler
- */
-async function handleHealthReadyRoute(_req: IRequest, res: IResponse): Promise<void> {
-  const startTime = Date.now();
-  const environment = appConfig.environment;
-
-  let databaseResponseTime: number | null = null;
-  let cacheResponseTime: number | null = null;
-
-  try {
-    const db = await ensureDefaultDatabase();
-    if (db === null) {
-      res.json(
-        HealthUtils.buildHealthResponse('ready', environment, {
-          dependencies: {
-            database: {
-              status: 'unconfigured',
-              responseTime: 0,
-            },
-          },
-        })
-      );
-      return;
-    }
-    const maybeIsConnected = (db as unknown as { isConnected?: unknown }).isConnected;
-    const maybeConnect = (db as unknown as { connect?: unknown }).connect;
-    if (typeof maybeIsConnected === 'function' && maybeIsConnected.call(db) === false) {
-      if (typeof maybeConnect === 'function') {
-        await maybeConnect.call(db);
-      }
-    }
-    await QueryBuilder.ping(db);
-
-    databaseResponseTime = Date.now() - startTime;
-
-    cacheResponseTime = await RuntimeHealthProbes.pingKvCache(2000);
-
-    res.json(
-      HealthUtils.buildHealthResponse('ready', environment, {
-        dependencies: {
-          database: {
-            status: 'ready',
-            responseTime: databaseResponseTime,
-          },
-          ...(cacheResponseTime === null
-            ? {}
-            : {
-                cache: {
-                  status: 'ready',
-                  responseTime: cacheResponseTime,
-                },
-              }),
-        },
-      })
-    );
-  } catch (error) {
-    Logger.error('Readiness check failed:', error);
-
-    const responseTime = Date.now() - startTime;
-
-    const dependencies: Record<string, unknown> = {
-      database: {
-        status: databaseResponseTime === null ? 'unavailable' : 'ready',
-        responseTime: databaseResponseTime ?? responseTime,
-      },
-    };
-
-    if (RuntimeHealthProbes.getCacheDriverName() === 'kv') {
-      dependencies['cache'] = {
-        status: 'unavailable',
-        responseTime: cacheResponseTime ?? responseTime,
-      };
-    }
-
-    res.setStatus(503).json(
-      HealthUtils.buildErrorResponse('not_ready', environment, error as Error, {
-        dependencies,
-      })
-    );
-  }
-}
-
-/**
- * Register all health routes
- */
-export const registerHealthRoutes = (router: IRouter): void => {
-  Router.get(router, '/health', handleHealthRoute);
-  Router.get(router, '/health/live', handleHealthLiveRoute);
-  Router.get(router, '/health/ready', handleHealthReadyRoute);
-};

package/src/common/RemoteSignedJson.ts

@@ -1,189 +0,0 @@
-import { ErrorFactory } from '@exceptions/ZintrustError';
-import { isObject } from '@helper/index';
-import { normalizeSigningCredentials } from '@proxy/SigningService';
-import { SignedRequest } from '@security/SignedRequest';
-
-export type RemoteSignedJsonSettings = {
-  baseUrl: string;
-  keyId: string;
-  secret: string;
-  timeoutMs: number;
-  signaturePathPrefixToStrip?: string;
-
-  missingUrlMessage: string;
-  missingCredentialsMessage: string;
-
-  messages: {
-    unauthorized: string;
-    forbidden: string;
-    rateLimited: string;
-    rejected: string;
-    error: string;
-    timedOut: string;
-  };
-};
-
-const joinUrl = (baseUrl: string, path: string): URL => {
-  const u = new URL(baseUrl);
-  const basePath = u.pathname.endsWith('/') ? u.pathname.slice(0, -1) : u.pathname;
-  const next = path.startsWith('/') ? path : `/${path}`;
-  u.pathname = `${basePath}${next}`;
-  u.search = '';
-  return u;
-};
-
-const asJson = async (resp: Response): Promise<unknown> => {
-  const text = await resp.text();
-  if (text.trim() === '') return null;
-  try {
-    return JSON.parse(text) as unknown;
-  } catch {
-    return { message: text };
-  }
-};
-
-const isRecord = (value: unknown): value is Record<string, unknown> => isObject(value);
-
-const describeProxyError = (details: unknown): string => {
-  // Expected Worker proxy error shape: { status: number, body: { code: string, message: string } }
-  if (!isRecord(details)) return '';
-  const body = details['body'];
-  if (!isRecord(body)) return '';
-  const code = typeof body['code'] === 'string' ? body['code'] : '';
-  const message = typeof body['message'] === 'string' ? body['message'] : '';
-  if (code === '' && message === '') return '';
-  if (code !== '' && message !== '') return `${code}: ${message}`;
-  return code === '' ? message : code;
-};
-
-const normalizeSettings = (settings: RemoteSignedJsonSettings): RemoteSignedJsonSettings => {
-  const creds = normalizeSigningCredentials({
-    keyId: settings.keyId,
-    secret: settings.secret,
-  });
-  return { ...settings, keyId: creds.keyId, secret: creds.secret };
-};
-
-const requireConfigured = (settings: RemoteSignedJsonSettings): void => {
-  if (settings.baseUrl.trim() === '') {
-    throw ErrorFactory.createConfigError(settings.missingUrlMessage);
-  }
-  if (settings.keyId.trim() === '' || settings.secret.trim() === '') {
-    throw ErrorFactory.createConfigError(settings.missingCredentialsMessage);
-  }
-};
-
-const getNativeTimeoutSignal = (timeoutMs: number): AbortSignal | undefined => {
-  if (timeoutMs <= 0) return undefined;
-  const timeout = (AbortSignal as unknown as { timeout?: (ms: number) => AbortSignal }).timeout;
-  return typeof timeout === 'function' ? timeout(timeoutMs) : undefined;
-};
-
-const buildSigningUrl = (url: URL, settings: RemoteSignedJsonSettings): URL => {
-  const rawPrefix = settings.signaturePathPrefixToStrip?.trim() ?? '';
-  if (rawPrefix === '' || rawPrefix === '/') {
-    return new URL(url.toString());
-  }
-
-  const normalizedPrefix = rawPrefix.startsWith('/') ? rawPrefix : `/${rawPrefix}`;
-  const signingUrl = new URL(url.toString());
-
-  if (signingUrl.pathname === normalizedPrefix) {
-    signingUrl.pathname = '/';
-    return signingUrl;
-  }
-
-  if (signingUrl.pathname.startsWith(`${normalizedPrefix}/`)) {
-    signingUrl.pathname = signingUrl.pathname.slice(normalizedPrefix.length);
-  }
-
-  return signingUrl;
-};
-
-const throwForNonOkResponse = async (
-  resp: Response,
-  settings: RemoteSignedJsonSettings
-): Promise<never> => {
-  const details = await asJson(resp);
-
-  switch (resp.status) {
-    case 401:
-      throw ErrorFactory.createUnauthorizedError(settings.messages.unauthorized, details);
-    case 403:
-      throw ErrorFactory.createForbiddenError(settings.messages.forbidden, details);
-    case 429:
-      throw ErrorFactory.createSecurityError(settings.messages.rateLimited, details);
-    default: {
-      if (resp.status >= 400 && resp.status < 500) {
-        throw ErrorFactory.createValidationError(settings.messages.rejected, details);
-      }
-
-      const extra = describeProxyError(details);
-      const msg = extra === '' ? settings.messages.error : `${settings.messages.error} (${extra})`;
-      throw ErrorFactory.createConnectionError(msg, {
-        status: resp.status,
-        details,
-      });
-    }
-  }
-};
-
-const rethrowRequestError = (error: unknown, settings: RemoteSignedJsonSettings): never => {
-  if (error instanceof Error && error.name === 'AbortError') {
-    throw ErrorFactory.createConnectionError(settings.messages.timedOut, {
-      timeoutMs: settings.timeoutMs,
-    });
-  }
-  throw error;
-};
-
-export const RemoteSignedJson = Object.freeze({
-  async request<T>(
-    settings: RemoteSignedJsonSettings,
-    path: string,
-    payload: Record<string, unknown>
-  ): Promise<T> {
-    const normalized = normalizeSettings(settings);
-    requireConfigured(normalized);
-
-    const url = joinUrl(normalized.baseUrl, path);
-    const signingUrl = buildSigningUrl(url, normalized);
-    const body = JSON.stringify(payload);
-    const signed = await SignedRequest.createHeaders({
-      method: 'POST',
-      url: signingUrl,
-      body,
-      keyId: normalized.keyId,
-      secret: normalized.secret,
-    });
-
-    const nativeSignal = getNativeTimeoutSignal(normalized.timeoutMs);
-    if (nativeSignal === undefined && normalized.timeoutMs > 0) {
-      throw ErrorFactory.createConfigError(
-        'RemoteSignedJson timeout requires AbortSignal.timeout() support in this runtime',
-        { timeoutMs: normalized.timeoutMs }
-      );
-    }
-
-    try {
-      const resp = await fetch(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', ...signed },
-        body,
-        signal: nativeSignal,
-      });
-
-      if (!resp.ok) {
-        await throwForNonOkResponse(resp, normalized);
-      }
-
-      return (await asJson(resp)) as T;
-    } catch (error: unknown) {
-      return rethrowRequestError(error, normalized);
-    } finally {
-      // No timer cleanup needed: uses AbortSignal.timeout() when available.
-    }
-  },
-});
-
-export default RemoteSignedJson;