@zintrust/core 0.1.27 → 0.1.28

package/src/exceptions/ZintrustError.ts

@@ -0,0 +1,290 @@
+/**
+ * Base Exception Factory for ZinTrust Framework
+ * Implemented as plain functions (no classes / no prototype-based constructors).
+ */
+
+import { Logger } from '@config/logger';
+
+export interface IZintrustError extends Error {
+  statusCode: number;
+  code: string;
+  details?: unknown;
+}
+
+type StackTraceConstructorOpt =
+  | ((...args: never[]) => unknown)
+  | (abstract new (...args: never[]) => unknown);
+
+export type ZintrustErrorInit = Readonly<{
+  statusCode?: number;
+  code?: string;
+  details?: unknown;
+  name?: string;
+  prototype?: object;
+  captureStackTraceCtor?: StackTraceConstructorOpt;
+}>;
+
+/**
+ * Plain initializer for ZinTrust framework errors.
+ */
+export function initZintrustError(target: Error, init: ZintrustErrorInit = {}): void {
+  const mutable = target as Error & {
+    statusCode?: number;
+    code?: string;
+    details?: unknown;
+  };
+
+  if (init.name !== undefined) {
+    target.name = init.name;
+  }
+
+  mutable.statusCode = init.statusCode ?? 500;
+  mutable.code = init.code ?? 'INTERNAL_ERROR';
+  if (init.details !== undefined) {
+    mutable.details = init.details;
+  }
+
+  if (init.prototype !== undefined) {
+    Object.setPrototypeOf(target, init.prototype);
+  }
+
+  if (Error?.captureStackTrace !== undefined) {
+    Error.captureStackTrace(target, (init.captureStackTraceCtor ?? initZintrustError) as never);
+  }
+}
+
+type TypedZintrustError<
+  TCode extends string,
+  TName extends string,
+  TStatus extends number,
+> = IZintrustError & {
+  readonly code: TCode;
+  name: TName;
+  readonly statusCode: TStatus;
+};
+
+function createTypedZintrustError<
+  TCode extends string,
+  TName extends string,
+  TStatus extends number,
+>(
+  message: string,
+  statusCode: TStatus,
+  code: TCode,
+  name: TName,
+  details?: unknown
+): TypedZintrustError<TCode, TName, TStatus> {
+  // Use `globalThis.Error` to avoid the project's `new Error(...)` restricted syntax selector.
+  const error = new globalThis.Error(message);
+  initZintrustError(error, {
+    statusCode,
+    code,
+    details,
+    name,
+    prototype: Error.prototype,
+    captureStackTraceCtor: createTypedZintrustError,
+  });
+  return error as TypedZintrustError<TCode, TName, TStatus>;
+}
+
+export type ZintrustError = TypedZintrustError<'INTERNAL_ERROR', 'ZintrustError', 500>;
+export type DatabaseError = TypedZintrustError<'DATABASE_ERROR', 'DatabaseError', 500>;
+export type WorkerError = TypedZintrustError<'WORKER_ERROR', 'WorkerError', 500>;
+export type ValidationError = TypedZintrustError<'VALIDATION_ERROR', 'ValidationError', 400>;
+export type NotFoundError = TypedZintrustError<'NOT_FOUND', 'NotFoundError', 404>;
+export type UnauthorizedError = TypedZintrustError<'UNAUTHORIZED', 'UnauthorizedError', 401>;
+export type ForbiddenError = TypedZintrustError<'FORBIDDEN', 'ForbiddenError', 403>;
+export type ConnectionError = TypedZintrustError<'CONNECTION_ERROR', 'ConnectionError', 500>;
+export type ConfigError = TypedZintrustError<'CONFIG_ERROR', 'ConfigError', 500>;
+export type GeneralError = TypedZintrustError<'GENERAL_ERROR', 'GeneralError', 500>;
+export type CliError = TypedZintrustError<'CLI_ERROR', 'CliError', 1>;
+export type SecurityError = TypedZintrustError<'SECURITY_ERROR', 'SecurityError', 401>;
+export type CatchError = TypedZintrustError<'TRY_CATCH_ERROR', 'CatchError', 500>;
+export type SanitizerError = TypedZintrustError<'SANITIZER_ERROR', 'SanitizerError', 400>;
+
+/**
+ * Plain error creators.
+ */
+export function ZintrustError(message: string, details?: unknown): ZintrustError {
+  return createTypedZintrustError(message, 500, 'INTERNAL_ERROR', 'ZintrustError', details);
+}
+
+export function createDatabaseError(message: string, details?: unknown): DatabaseError {
+  return createTypedZintrustError(message, 500, 'DATABASE_ERROR', 'DatabaseError', details);
+}
+
+export function createWorkerError(message: string, details?: unknown): WorkerError {
+  return createTypedZintrustError(message, 500, 'WORKER_ERROR', 'WorkerError', details);
+}
+
+export function createValidationError(message: string, details?: unknown): ValidationError {
+  return createTypedZintrustError(message, 400, 'VALIDATION_ERROR', 'ValidationError', details);
+}
+
+export function createNotFoundError(
+  message: string = 'Resource not found',
+  details?: unknown
+): NotFoundError {
+  return createTypedZintrustError(message, 404, 'NOT_FOUND', 'NotFoundError', details);
+}
+
+export function createUnauthorizedError(
+  message: string = 'Unauthorized',
+  details?: unknown
+): UnauthorizedError {
+  return createTypedZintrustError(message, 401, 'UNAUTHORIZED', 'UnauthorizedError', details);
+}
+
+export function createForbiddenError(
+  message: string = 'Forbidden',
+  details?: unknown
+): ForbiddenError {
+  return createTypedZintrustError(message, 403, 'FORBIDDEN', 'ForbiddenError', details);
+}
+
+export function createConnectionError(message: string, details?: unknown): ConnectionError {
+  return createTypedZintrustError(message, 500, 'CONNECTION_ERROR', 'ConnectionError', details);
+}
+
+export function createConfigError(message: string, details?: unknown): ConfigError {
+  return createTypedZintrustError(message, 500, 'CONFIG_ERROR', 'ConfigError', details);
+}
+
+export function createGeneralError(message: string, details?: unknown): GeneralError {
+  return createTypedZintrustError(message, 500, 'GENERAL_ERROR', 'GeneralError', details);
+}
+
+export function createCliError(message: string, details?: unknown): CliError {
+  return createTypedZintrustError(message, 1, 'CLI_ERROR', 'CliError', details);
+}
+
+export function createSecurityError(message: string, details?: unknown): SecurityError {
+  return createTypedZintrustError(message, 401, 'SECURITY_ERROR', 'SecurityError', details);
+}
+
+export function createTryCatchError(message: string, details?: unknown): CatchError {
+  Logger.error(message, details);
+  return createTypedZintrustError(message, 500, 'TRY_CATCH_ERROR', 'CatchError', details);
+}
+
+/**
+ * Truncate a string if it exceeds maximum length
+ */
+function truncateString(str: string, maxLen: number): string {
+  if (str.length <= maxLen) return str;
+  return `${str.slice(0, 16)}...${str.slice(-8)}`;
+}
+
+/**
+ * Redact sensitive values for error messages
+ */
+function redactValue(value: unknown): string {
+  if (value === null || value === undefined) return String(value);
+
+  const MAX_LEN = 48;
+
+  if (typeof value === 'string') {
+    return truncateString(value, MAX_LEN);
+  }
+
+  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+    return String(value);
+  }
+
+  if (typeof value === 'symbol') {
+    return 'Symbol';
+  }
+
+  if (typeof value === 'function') {
+    return 'Function';
+  }
+
+  // Avoid stringifying binary buffers (can leak secrets and/or blow up logs).
+  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value)) {
+    return `Buffer(len=${value.length})`;
+  }
+
+  if (value instanceof Uint8Array) {
+    return `Uint8Array(len=${value.length})`;
+  }
+
+  if (Array.isArray(value)) {
+    return `Array(len=${value.length})`;
+  }
+
+  if (typeof value === 'object') {
+    return 'Object';
+  }
+
+  return truncateString(String(value), MAX_LEN);
+}
+
+/**
+ * Create a sanitizer error with method name, reason, and redacted value
+ */
+export function createSanitizerError(
+  method: string,
+  reason: string,
+  value: unknown
+): SanitizerError {
+  const redacted = redactValue(value);
+  const message = `Sanitizer.${method}() failed: ${reason} (value: ${redacted})`;
+  return createTypedZintrustError(message, 400, 'SANITIZER_ERROR', 'SanitizerError', {
+    method,
+    reason,
+    redactedValue: redacted,
+  });
+}
+
+/**
+ * Backward compatibility Errors object.
+ */
+export const Errors = Object.freeze({
+  database: (message: string, details?: unknown): Error => createDatabaseError(message, details),
+  notFound: (message?: string, details?: unknown): Error =>
+    createNotFoundError(message ?? 'Resource not found', details),
+  validation: (message: string, details?: unknown): Error =>
+    createValidationError(message, details),
+  unauthorized: (message?: string, details?: unknown): Error =>
+    createUnauthorizedError(message ?? 'Unauthorized', details),
+  forbidden: (message?: string, details?: unknown): Error =>
+    createForbiddenError(message ?? 'Forbidden', details),
+  connection: (message: string, details?: unknown): Error =>
+    createConnectionError(message, details),
+  config: (message: string, details?: unknown): Error => createConfigError(message, details),
+  general: (message: string, details?: unknown): Error => createGeneralError(message, details),
+  cli: (message: string, details?: unknown): Error => createCliError(message, details),
+  security: (message: string, details?: unknown): Error => createSecurityError(message, details),
+  catchError: (message: string, details?: unknown): Error => createTryCatchError(message, details),
+  sanitizer: (method: string, reason: string, value: unknown): Error =>
+    createSanitizerError(method, reason, value),
+});
+
+/**
+ * Centralized ErrorFactory for creating standardized errors.
+ */
+export const ErrorFactory = Object.freeze({
+  createDatabaseError: (message: string, details?: unknown) =>
+    createDatabaseError(message, details),
+  createWorkerError: (message: string, details?: unknown) => createWorkerError(message, details),
+
+  createConnectionError: (message: string, details?: unknown) =>
+    createConnectionError(message, details),
+  createConfigError: (message: string, details?: unknown) => createConfigError(message, details),
+  createValidationError: (message: string, details?: unknown) =>
+    createValidationError(message, details),
+  createGeneralError: (message: string, details?: unknown) => createGeneralError(message, details),
+  createTryCatchError: (message: string, details?: unknown) =>
+    createTryCatchError(message, details),
+  createCliError: (message: string, details?: unknown) => createCliError(message, details),
+  createSecurityError: (message: string, details?: unknown) =>
+    createSecurityError(message, details),
+  createNotFoundError: (message?: string, details?: unknown) =>
+    createNotFoundError(message ?? 'Resource not found', details),
+  createUnauthorizedError: (message?: string, details?: unknown) =>
+    createUnauthorizedError(message ?? 'Unauthorized', details),
+  createSanitizerError: (method: string, reason: string, value: unknown) =>
+    createSanitizerError(method, reason, value),
+  createForbiddenError: (message?: string, details?: unknown) =>
+    createForbiddenError(message ?? 'Forbidden', details),
+});

package/src/functions/cloudflare.ts

@@ -0,0 +1,28 @@
+import { Logger } from '@config/logger';
+import type { IncomingMessage, ServerResponse } from '@node-singletons/http';
+import { CloudflareAdapter } from '@runtime/adapters/CloudflareAdapter';
+
+import { getKernel } from '@runtime/getKernel';
+
+export default {
+  async fetch(request: Request, _env: unknown, _ctx: unknown): Promise<Response> {
+    try {
+      // Make bindings available to framework code in Workers
+      (globalThis as unknown as { env?: unknown }).env = _env;
+
+      const kernel = await getKernel();
+
+      const adapter = CloudflareAdapter.create({
+        handler: async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+          await kernel.handle(req, res);
+        },
+      });
+
+      const platformResponse = await adapter.handle(request);
+      return adapter.formatResponse(platformResponse) as Response;
+    } catch (error) {
+      Logger.error('Cloudflare handler error:', error as Error);
+      return new Response('Internal Server Error', { status: 500 });
+    }
+  },
+};

package/src/functions/deno.ts

@@ -0,0 +1,25 @@
+import { Logger } from '@config/logger';
+import type { IncomingMessage, ServerResponse } from '@node-singletons/http';
+import { DenoAdapter } from '@runtime/adapters/DenoAdapter';
+
+import { getKernel } from '@runtime/getKernel';
+
+const deno = async (request: Request): Promise<Response> => {
+  try {
+    const kernel = await getKernel();
+
+    const adapter = DenoAdapter.create({
+      handler: async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+        await kernel.handle(req, res);
+      },
+    });
+
+    const platformResponse = await adapter.handle(request);
+    return adapter.formatResponse(platformResponse) as Response;
+  } catch (error) {
+    Logger.error('Deno handler error:', error as Error);
+    return new Response('Internal Server Error', { status: 500 });
+  }
+};
+
+export default deno;

package/src/functions/lambda.ts

@@ -0,0 +1,30 @@
+import { Logger } from '@config/logger';
+import type { IncomingMessage, ServerResponse } from '@node-singletons/http';
+import { LambdaAdapter } from '@runtime/adapters/LambdaAdapter';
+
+import { getKernel } from '@runtime/getKernel';
+
+export const handler = async (event: unknown, context: unknown): Promise<unknown> => {
+  try {
+    const kernel = await getKernel();
+
+    const adapter = LambdaAdapter.create({
+      handler: async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+        await kernel.handle(req, res);
+      },
+    });
+
+    return await adapter.handle(event, context);
+  } catch (error) {
+    Logger.error('Lambda handler error:', error as Error);
+    return {
+      statusCode: 500,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        message: 'Internal Server Error',
+      }),
+    };
+  }
+};

package/src/health/RuntimeHealthProbes.ts

@@ -0,0 +1,75 @@
+/**
+ * Runtime Health Probes
+ *
+ * Lightweight dependency probes intended for readiness endpoints.
+ *
+ * NOTE: Startup probes are handled separately by StartupHealthChecks.
+ */
+
+import { Cloudflare } from '@config/cloudflare';
+import { Env } from '@config/env';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+const getCacheDriverName = (): string => {
+  return Env.get('CACHE_DRIVER', 'memory');
+};
+
+const withTimeout = async <T>(label: string, ms: number, fn: () => Promise<T>): Promise<T> => {
+  if (!Number.isFinite(ms) || ms <= 0) {
+    return fn();
+  }
+
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutId = globalThis.setTimeout(() => {
+      reject(ErrorFactory.createConfigError(`${label} timed out after ${ms}ms`, { label, ms }));
+    }, ms);
+
+    // Node: allow process to exit; other runtimes may not support unref()
+    if (typeof (timeoutId as unknown as { unref?: unknown }).unref === 'function') {
+      (timeoutId as unknown as { unref: () => void }).unref();
+    }
+  });
+
+  try {
+    return await Promise.race([fn(), timeoutPromise]);
+  } finally {
+    if (timeoutId !== undefined) {
+      clearTimeout(timeoutId);
+      timeoutId = undefined;
+    }
+  }
+};
+
+const pingKvCache = async (timeoutMs = 2000): Promise<number | null> => {
+  const driver = getCacheDriverName();
+  if (driver !== 'kv') return null;
+
+  const start = Date.now();
+
+  const kv = Cloudflare.getKVBinding('CACHE');
+  if (kv === null) {
+    throw ErrorFactory.createConfigError('KV binding "CACHE" not found');
+  }
+
+  const key = `__runtime_health__:kv:${Date.now()}`;
+
+  await withTimeout('runtime.cache.kv.ping', timeoutMs, async () => {
+    await kv.put(key, JSON.stringify({ ok: true }), { expirationTtl: 60 });
+    const value = (await kv.get(key, { type: 'json' })) as { ok?: boolean } | null;
+    if (value?.ok !== true) {
+      throw ErrorFactory.createConnectionError('KV probe failed: unexpected value');
+    }
+    await kv.delete(key);
+  });
+
+  return Date.now() - start;
+};
+
+export const RuntimeHealthProbes = Object.freeze({
+  getCacheDriverName,
+  pingKvCache,
+});
+
+export default RuntimeHealthProbes;

package/src/health/StartupHealthChecks.ts

@@ -0,0 +1,156 @@
+/**
+ * Startup Health Checks
+ *
+ * Lightweight boot-time checks that validate the runtime environment before
+ * the server starts accepting requests.
+ */
+
+import { generateUuid } from '@/common/utility';
+import { Cache } from '@cache/Cache';
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+import { startupConfig } from '@config/startup';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { Database } from '@orm/Database';
+import type { DatabaseConfig } from '@orm/DatabaseAdapter';
+import { QueryBuilder } from '@orm/QueryBuilder';
+import { StartupSecretValidation } from '@security/StartupSecretValidation';
+
+export type StartupHealthCheck = {
+  name: string;
+  ok: boolean;
+  durationMs?: number;
+  details?: unknown;
+};
+
+export type StartupHealthReport = {
+  ok: boolean;
+  checks: StartupHealthCheck[];
+};
+
+export const StartupHealthChecks = Object.freeze({
+  async run(): Promise<StartupHealthReport> {
+    if (!startupConfig.healthChecksEnabled) {
+      return { ok: true, checks: [{ name: 'startup.healthChecks', ok: true }] };
+    }
+
+    const checks: StartupHealthCheck[] = [];
+
+    const secrets = StartupSecretValidation.validate();
+    checks.push({
+      name: 'startup.secrets',
+      ok: secrets.valid,
+      details: secrets.valid ? undefined : { errors: secrets.errors },
+    });
+
+    if (startupConfig.checkDatabase === true) {
+      // Minimal config derived from Env. For Workers D1, the adapter will resolve the binding via Cloudflare helpers.
+      const driver = (Env.DB_CONNECTION || 'sqlite') as DatabaseConfig['driver'];
+      const readHosts =
+        Env.DB_READ_HOSTS.trim().length > 0 ? Env.DB_READ_HOSTS.split(',') : undefined;
+
+      const config: DatabaseConfig = {
+        driver,
+        database: Env.DB_DATABASE,
+        host: Env.DB_HOST,
+        port: Env.DB_PORT,
+        username: Env.DB_USERNAME,
+        password: Env.DB_PASSWORD,
+        readHosts,
+      };
+
+      checks.push(await StartupHealthChecks.checkDatabase(config));
+    }
+
+    if (startupConfig.checkCache === true) {
+      checks.push(await StartupHealthChecks.checkCache());
+    }
+
+    return { ok: checks.every((c) => c.ok), checks };
+  },
+
+  async assertHealthy(): Promise<StartupHealthReport> {
+    const report = await StartupHealthChecks.run();
+    if (report.ok) return report;
+
+    if (startupConfig.continueOnFailure === true) {
+      Logger.warn('Startup health checks failed but continuing due to configuration', { report });
+      return report;
+    }
+
+    throw ErrorFactory.createConfigError('Startup health checks failed', { report });
+  },
+
+  async checkDatabase(config: DatabaseConfig): Promise<StartupHealthCheck> {
+    const startedAt = Date.now();
+
+    try {
+      await StartupHealthChecks.withTimeout('startup.database.connect', async () => {
+        const db = Database.create(config);
+        await db.connect();
+        try {
+          await QueryBuilder.ping(db);
+        } finally {
+          await db.disconnect();
+        }
+      });
+
+      return { name: 'startup.database', ok: true, durationMs: Date.now() - startedAt };
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      return {
+        name: 'startup.database',
+        ok: false,
+        durationMs: Date.now() - startedAt,
+        details: { message },
+      };
+    }
+  },
+
+  async checkCache(): Promise<StartupHealthCheck> {
+    const startedAt = Date.now();
+    const key = `__startup_health__:${generateUuid()}`;
+
+    try {
+      await StartupHealthChecks.withTimeout('startup.cache.probe', async () => {
+        await Cache.set(key, { ok: true }, 60);
+        const value = await Cache.get<{ ok: boolean }>(key);
+        await Cache.delete(key);
+
+        if (value?.ok !== true) {
+          throw ErrorFactory.createConfigError('Cache probe failed', { key });
+        }
+      });
+
+      return { name: 'startup.cache', ok: true, durationMs: Date.now() - startedAt };
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      return {
+        name: 'startup.cache',
+        ok: false,
+        durationMs: Date.now() - startedAt,
+        details: { message },
+      };
+    }
+  },
+
+  async withTimeout(name: string, fn: () => Promise<void>): Promise<void> {
+    const timeoutMs = Math.max(1, Number(startupConfig.timeoutMs));
+
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      timeoutId = globalThis.setTimeout(() => {
+        reject(ErrorFactory.createConfigError(`Startup check timed out: ${name}`, { timeoutMs }));
+      }, timeoutMs);
+    });
+
+    try {
+      await Promise.race([fn(), timeoutPromise]);
+    } finally {
+      if (timeoutId !== undefined) globalThis.clearTimeout(timeoutId);
+    }
+  },
+});
+
+export default StartupHealthChecks;

package/src/http/Controller.ts

@@ -0,0 +1,64 @@
+/**
+ * Base Controller
+ * All controllers extend this class
+ */
+
+import type { IRequest } from '@http/Request';
+import type { IResponse } from '@http/Response';
+
+export interface IController {
+  json(res: IResponse, data: unknown, statusCode?: number): void;
+  error(res: IResponse, message: string, statusCode?: number): void;
+  redirect(res: IResponse, url: string, statusCode?: number): void;
+  param(req: IRequest, name: string): string | undefined;
+  query(req: IRequest, name: string): string | string[] | undefined;
+  body(req: IRequest): unknown;
+}
+
+/**
+ * Base Controller
+ * Sealed namespace for immutability
+ */
+export const Controller: IController = Object.freeze({
+  /**
+   * Send JSON response
+   */
+  json(res: IResponse, data: unknown, statusCode: number = 200): void {
+    res.setStatus(statusCode).json(data);
+  },
+
+  /**
+   * Send error response
+   */
+  error(res: IResponse, message: string, statusCode: number = 400): void {
+    res.setStatus(statusCode).json({ error: message });
+  },
+
+  /**
+   * Redirect response
+   */
+  redirect(res: IResponse, url: string, statusCode: number = 302): void {
+    res.redirect(url, statusCode);
+  },
+
+  /**
+   * Get route parameter
+   */
+  param(req: IRequest, name: string): string | undefined {
+    return req.getParam(name);
+  },
+
+  /**
+   * Get query parameter
+   */
+  query(req: IRequest, name: string): string | string[] | undefined {
+    return req.getQueryParam(name);
+  },
+
+  /**
+   * Get request body
+   */
+  body(req: IRequest): unknown {
+    return req.getBody();
+  },
+});