@zintrust/core 0.4.15 → 0.4.17

package/src/profiling/types.ts

@@ -0,0 +1,86 @@
+/**
+ * Profiling Type Definitions
+ * Shared interfaces for query logging, N+1 detection, and memory profiling
+ */
+
+export const PROFILING_TYPES_MODULE = Object.freeze('ProfilingTypes');
+
+/**
+ * Log entry for a single database query execution
+ */
+export interface QueryLogEntry {
+  sql: string;
+  params: unknown[];
+  duration: number;
+  timestamp: Date;
+  context: string;
+  executionCount?: number;
+}
+
+/**
+ * Detected N+1 query pattern
+ */
+export interface N1Pattern {
+  table: string;
+  queryCount: number;
+  query: string;
+  severity: 'warning' | 'critical';
+}
+
+/**
+ * Memory snapshot at a point in time
+ */
+export interface MemorySnapshot {
+  heapUsed: number;
+  heapTotal: number;
+  external: number;
+  rss: number;
+  timestamp: Date;
+}
+
+/**
+ * Memory delta between two snapshots
+ */
+export interface MemoryDelta {
+  heapUsed: number;
+  heapTotal: number;
+  external: number;
+  rss: number;
+}
+
+/**
+ * N1Detector analyzes query logs to identify N+1 patterns
+ * Groups identical queries and flags those executed 5+ times as critical
+ */
+export interface IN1Detector {
+  /**
+   * Extract table name from SQL query
+   */
+  extractTableFromSQL(sql: string): string;
+
+  /**
+   * Detect N+1 patterns in query log
+   */
+  detect(queryLog: QueryLogEntry[]): N1Pattern[];
+
+  /**
+   * Get severity level based on repetition count
+   */
+  getSeverity(count: number): 'warning' | 'critical';
+
+  /**
+   * Generate human-readable summary of N+1 patterns
+   */
+  generateSummary(patterns: N1Pattern[]): string;
+}
+
+/**
+ * Complete profile report for a request
+ */
+export interface ProfileReport {
+  duration: number;
+  queriesExecuted: number;
+  n1Patterns: N1Pattern[];
+  memoryDelta: MemoryDelta;
+  timestamp: Date;
+}

package/src/proxy/ErrorHandler.ts

@@ -0,0 +1,13 @@
+export type ProxyErrorResponse = Readonly<{
+  status: number;
+  body: { code: string; message: string };
+}>;
+
+const toProxyError = (status: number, code: string, message: string): ProxyErrorResponse => ({
+  status,
+  body: { code, message },
+});
+
+export const ErrorHandler = Object.freeze({
+  toProxyError,
+});

package/src/proxy/PoolManager.ts

@@ -0,0 +1,31 @@
+export type PoolFactory<T> = () => T;
+export type PoolDisposer<T> = (pool: T) => Promise<void> | void;
+
+export type PoolManager<T> = Readonly<{
+  get: () => T;
+  dispose: () => Promise<void>;
+}>;
+
+export const createPoolManager = <T>(
+  create: PoolFactory<T>,
+  dispose: PoolDisposer<T>
+): PoolManager<T> => {
+  let pool: T | null = null;
+
+  const get = (): T => {
+    pool ??= create();
+    return pool;
+  };
+
+  const disposePool = async (): Promise<void> => {
+    if (pool === null) return;
+    const current = pool;
+    pool = null;
+    await Promise.resolve(dispose(current));
+  };
+
+  return Object.freeze({
+    get,
+    dispose: disposePool,
+  });
+};

package/src/proxy/ProxyBackend.ts

@@ -0,0 +1,19 @@
+export type ProxyRequest = Readonly<{
+  method: string;
+  path: string;
+  headers: Record<string, string | undefined>;
+  body: string;
+}>;
+
+export type ProxyResponse = Readonly<{
+  status: number;
+  body: unknown;
+  headers?: Record<string, string>;
+}>;
+
+export type ProxyBackend = Readonly<{
+  name: string;
+  handle: (request: ProxyRequest) => Promise<ProxyResponse>;
+  health: () => Promise<ProxyResponse>;
+  shutdown?: () => Promise<void>;
+}>;

package/src/proxy/ProxyConfig.ts

@@ -0,0 +1,12 @@
+export type ProxySigningConfig = Readonly<{
+  keyId: string;
+  secret: string;
+  require: boolean;
+  windowMs: number;
+}>;
+
+export type ProxyServerConfig = Readonly<{
+  host: string;
+  port: number;
+  maxBodyBytes: number;
+}>;

package/src/proxy/ProxyRegistry.ts

@@ -0,0 +1,20 @@
+export type ProxyRegistration = Readonly<{
+  name: string;
+  description: string;
+}>;
+
+const registry = new Map<string, ProxyRegistration>();
+
+const register = (proxy: ProxyRegistration): void => {
+  registry.set(proxy.name, proxy);
+};
+
+const get = (name: string): ProxyRegistration | undefined => registry.get(name);
+
+const list = (): ProxyRegistration[] => Array.from(registry.values());
+
+export const ProxyRegistry = Object.freeze({
+  register,
+  get,
+  list,
+});

package/src/proxy/ProxyRequestParsing.ts

@@ -0,0 +1,21 @@
+import { ErrorHandler } from '@proxy/ErrorHandler';
+import type { ProxyResponse } from '@proxy/ProxyBackend';
+import { RequestValidator } from '@proxy/RequestValidator';
+
+export const validateProxyRequest = (request: { method: string }): ProxyResponse | null => {
+  const methodError = RequestValidator.requirePost(request.method);
+  if (methodError) {
+    return ErrorHandler.toProxyError(405, methodError.code, methodError.message);
+  }
+  return null;
+};
+
+export const parseJsonBody = (
+  body: string
+): { ok: true; value: Record<string, unknown> } | ProxyResponse => {
+  const parsed = RequestValidator.parseJson(body);
+  if (!parsed.ok) {
+    return ErrorHandler.toProxyError(400, parsed.error.code, parsed.error.message);
+  }
+  return { ok: true, value: parsed.value };
+};

package/src/proxy/ProxyServer.ts

@@ -0,0 +1,133 @@
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import {
+  createServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from '@node-singletons/http';
+import type { ProxyBackend, ProxyRequest, ProxyResponse } from '@proxy/ProxyBackend';
+
+export type ProxyServerOptions = Readonly<{
+  host: string;
+  port: number;
+  maxBodyBytes: number;
+  backend: ProxyBackend;
+  verify?: (
+    req: IncomingMessage,
+    body: string
+  ) => Promise<{ ok: true } | { ok: false; status: number; message: string }>;
+}>;
+
+const readBody = async (req: IncomingMessage, maxBodyBytes: number): Promise<string> => {
+  const chunks: Buffer[] = [];
+  let size = 0;
+
+  for await (const chunk of req) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : (Buffer.from(chunk) as Buffer<ArrayBufferLike>);
+    size += buffer.length;
+    if (size > maxBodyBytes) {
+      throw ErrorFactory.createValidationError('Body too large');
+    }
+    chunks.push(buffer);
+  }
+
+  return Buffer.concat(chunks).toString('utf8');
+};
+
+const respond = (res: ServerResponse, response: ProxyResponse): void => {
+  res.writeHead(response.status, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Cache-Control': 'no-store',
+    ...response.headers,
+  });
+  res.end(JSON.stringify(response.body));
+};
+
+const toProxyRequest = (req: IncomingMessage, body: string): ProxyRequest => {
+  const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+  const headers: Record<string, string | undefined> = {};
+  for (const [key, value] of Object.entries(req.headers)) {
+    headers[key.toLowerCase()] = Array.isArray(value) ? value.join(',') : value;
+  }
+
+  return {
+    method: req.method ?? 'POST',
+    path: url.pathname,
+    headers,
+    body,
+  };
+};
+
+export const createProxyServer = (
+  options: ProxyServerOptions
+): Readonly<{
+  start: () => Promise<void>;
+  stop: () => Promise<void>;
+  server: Server;
+}> => {
+  const server: Server = createServer(async (req, res) => {
+    try {
+      const body = await readBody(req, options.maxBodyBytes);
+
+      const rawUrl = req.url ?? '';
+      if (
+        rawUrl.startsWith('/containerstarthealthcheck') ||
+        rawUrl.startsWith('containerstarthealthcheck')
+      ) {
+        respond(res, {
+          status: 200,
+          body: { status: 'ok' },
+        });
+        return;
+      }
+
+      if ((req.url ?? '').startsWith('/health')) {
+        const response = await options.backend.health();
+        respond(res, response);
+        return;
+      }
+
+      if (options.verify) {
+        const verified = await options.verify(req, body);
+        if (!verified.ok) {
+          respond(res, {
+            status: verified.status,
+            body: { code: 'UNAUTHORIZED', message: verified.message },
+          });
+          return;
+        }
+      }
+
+      const request = toProxyRequest(req, body);
+      const response = await options.backend.handle(request);
+      respond(res, response);
+    } catch (error) {
+      respond(res, {
+        status: 500,
+        body: { code: 'PROXY_ERROR', message: String(error) },
+      });
+    }
+  });
+
+  const start = async (): Promise<void> =>
+    new Promise((resolve) => {
+      server.listen(options.port, options.host, () => resolve());
+    });
+
+  const stop = async (): Promise<void> =>
+    new Promise((resolve, reject) => {
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+
+  return Object.freeze({
+    start,
+    stop,
+    server,
+  });
+};

package/src/proxy/ProxyServerUtils.ts

@@ -0,0 +1,91 @@
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+import type { IncomingMessage } from '@node-singletons/http';
+import type { ProxySigningConfig } from '@proxy/ProxyConfig';
+import { resolveProxySigningConfig } from '@proxy/ProxySigningConfigResolver';
+import { extractSigningHeaders, verifyProxySignatureIfNeeded } from '@proxy/ProxySigningRequest';
+
+export type BaseProxyConfig = {
+  host: string;
+  port: number;
+  maxBodyBytes: number;
+};
+
+export type BaseProxyOverrides = Partial<{
+  host: string;
+  port: number;
+  maxBodyBytes: number;
+  requireSigning: boolean;
+  keyId: string;
+  secret: string;
+  signingWindowMs: number;
+}>;
+
+export const resolveBaseConfig = (
+  overrides: BaseProxyOverrides,
+  prefix: string,
+  defaults?: { host?: string; port?: number; maxBodyBytes?: number }
+): BaseProxyConfig => {
+  const host =
+    overrides.host ?? Env.get(`${prefix}_PROXY_HOST`, Env.HOST ?? defaults?.host ?? '127.0.0.1');
+  const port =
+    overrides.port ?? Env.getInt(`${prefix}_PROXY_PORT`, Env.PORT ?? defaults?.port ?? 3000);
+  const maxBodyBytes =
+    overrides.maxBodyBytes ??
+    Env.getInt(`${prefix}_PROXY_MAX_BODY_BYTES`, Env.MAX_BODY_SIZE ?? defaults?.maxBodyBytes ?? 0);
+
+  return { host, port, maxBodyBytes };
+};
+
+export const resolveBaseSigningConfig = (
+  overrides: BaseProxyOverrides,
+  prefix: string
+): {
+  keyId: string;
+  secret: string;
+  requireSigning: boolean;
+  signingWindowMs: number;
+} =>
+  resolveProxySigningConfig(overrides, {
+    keyIdEnvVar: `${prefix}_PROXY_KEY_ID`,
+    secretEnvVar: `${prefix}_PROXY_SECRET`,
+    requireEnvVar: `${prefix}_PROXY_REQUIRE_SIGNING`,
+    windowEnvVar: `${prefix}_PROXY_SIGNING_WINDOW_MS`,
+  });
+
+export const verifyRequestSignature = async (
+  req: IncomingMessage,
+  body: string,
+  config: { signing: ProxySigningConfig },
+  serviceName: string
+): Promise<{ ok: boolean; error?: { status: number; message: string } }> => {
+  const headers = extractSigningHeaders(req);
+
+  const hasAnySigningHeader = Object.values(headers).some(
+    (value) => typeof value === 'string' && value.trim() !== ''
+  );
+
+  Logger.debug(`[${serviceName}] Verifying request signature`, {
+    path: req.url ?? '',
+    method: req.method ?? 'POST',
+    requireSigning: config.signing.require,
+    hasAnySigningHeader,
+    configuredKeyId: config.signing.keyId,
+    hasConfiguredSecret: config.signing.secret.trim() !== '',
+    bodyBytes: body.length,
+  });
+
+  const verified = await verifyProxySignatureIfNeeded(req, body, config.signing);
+  if (!verified.ok) {
+    const error = verified.error ?? { status: 401, message: 'Unauthorized' };
+    Logger.warn(`[${serviceName}] Signature verification failed`, {
+      path: req.url ?? '',
+      method: req.method ?? 'POST',
+      status: error.status,
+      message: error.message,
+    });
+    return { ok: false, error };
+  }
+
+  return { ok: true };
+};

package/src/proxy/ProxySigningConfigResolver.ts

@@ -0,0 +1,57 @@
+import { Env } from '@config/env';
+import { normalizeSigningCredentials } from '@proxy/SigningService';
+
+type SigningOverrideLike = Partial<{
+  requireSigning: boolean;
+  keyId: string;
+  secret: string;
+  signingWindowMs: number;
+}>;
+
+type ResolveSigningConfigOptions = {
+  keyIdEnvVar: string;
+  secretEnvVar: string;
+  requireEnvVar: string;
+  windowEnvVar: string;
+  defaultRequire?: boolean;
+  defaultWindowMs?: number;
+};
+
+export const resolveProxySigningConfig = (
+  overrides: SigningOverrideLike | undefined,
+  options: ResolveSigningConfigOptions
+): {
+  keyId: string;
+  secret: string;
+  requireSigning: boolean;
+  signingWindowMs: number;
+} => {
+  const normalizedOverrides = overrides ?? {};
+  const appName = Env.get('APP_NAME', Env.APP_NAME ?? 'ZinTrust');
+  const appKey = Env.get('APP_KEY', Env.APP_KEY ?? '');
+
+  const envKeyId = Env.get(options.keyIdEnvVar, appName);
+  const envSecret = Env.get(options.secretEnvVar, appKey);
+
+  const keyIdRaw = normalizedOverrides.keyId ?? (envKeyId.trim() === '' ? appName : envKeyId);
+  const secretRaw = normalizedOverrides.secret ?? (envSecret.trim() === '' ? appKey : envSecret);
+  const secret = secretRaw.trim() === '' ? appKey : secretRaw;
+
+  const creds = normalizeSigningCredentials({ keyId: keyIdRaw, secret });
+
+  const requireSigning =
+    normalizedOverrides.requireSigning ??
+    Env.getBool(options.requireEnvVar, options.defaultRequire ?? true);
+  const signingWindowMs =
+    normalizedOverrides.signingWindowMs ??
+    Env.getInt(options.windowEnvVar, options.defaultWindowMs ?? 60000);
+
+  return {
+    keyId: creds.keyId,
+    secret: creds.secret,
+    requireSigning,
+    signingWindowMs,
+  };
+};
+
+export default resolveProxySigningConfig;

package/src/proxy/ProxySigningRequest.ts

@@ -0,0 +1,45 @@
+import type { IncomingMessage } from '@node-singletons/http';
+import type { ProxySigningConfig } from '@proxy/ProxyConfig';
+import { SigningService } from '@proxy/SigningService';
+
+export const normalizeHeaderValue = (value: string | string[] | undefined): string | undefined => {
+  if (Array.isArray(value)) return value.join(',');
+  return value;
+};
+
+export const extractSigningHeaders = (
+  req: IncomingMessage
+): Record<string, string | undefined> => ({
+  'x-zt-key-id': normalizeHeaderValue(req.headers['x-zt-key-id']),
+  'x-zt-timestamp': normalizeHeaderValue(req.headers['x-zt-timestamp']),
+  'x-zt-nonce': normalizeHeaderValue(req.headers['x-zt-nonce']),
+  'x-zt-body-sha256': normalizeHeaderValue(req.headers['x-zt-body-sha256']),
+  'x-zt-signature': normalizeHeaderValue(req.headers['x-zt-signature']),
+});
+
+export const verifyProxySignatureIfNeeded = async (
+  req: IncomingMessage,
+  body: string,
+  signing: ProxySigningConfig
+): Promise<{ ok: boolean; error?: { status: number; message: string } }> => {
+  const headers = extractSigningHeaders(req);
+
+  if (!SigningService.shouldVerify(signing, headers)) {
+    return { ok: true };
+  }
+
+  const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+  const verified = await SigningService.verify({
+    method: req.method ?? 'POST',
+    url,
+    body,
+    headers,
+    signing,
+  });
+
+  if (!verified.ok) {
+    return { ok: false, error: { status: verified.status, message: verified.message } };
+  }
+
+  return { ok: true };
+};

package/src/proxy/RequestValidator.ts

@@ -0,0 +1,33 @@
+import { isObject } from '@helper/index';
+
+export type ValidationError = Readonly<{ code: string; message: string }>;
+
+const isRecord = (value: unknown): value is Record<string, unknown> => isObject(value);
+
+const parseJson = (
+  body: string
+): { ok: true; value: Record<string, unknown> } | { ok: false; error: ValidationError } => {
+  if (body.trim() === '') {
+    return { ok: false, error: { code: 'VALIDATION_ERROR', message: 'Body is required' } };
+  }
+
+  try {
+    const parsed = JSON.parse(body) as unknown;
+    if (!isRecord(parsed)) {
+      return { ok: false, error: { code: 'VALIDATION_ERROR', message: 'Body must be an object' } };
+    }
+    return { ok: true, value: parsed };
+  } catch (error) {
+    return { ok: false, error: { code: 'INVALID_JSON', message: String(error) } };
+  }
+};
+
+const requirePost = (method: string | undefined): ValidationError | null => {
+  if (method === 'POST') return null;
+  return { code: 'METHOD_NOT_ALLOWED', message: 'POST only' };
+};
+
+export const RequestValidator = Object.freeze({
+  parseJson,
+  requirePost,
+});