@zintrust/core 3.5.1 → 3.5.2

package/src/routes/error.ts

@@ -1,222 +0,0 @@
-/**
- * Error Routing
- * Centralizes 404/500 handling and HTML error page rendering.
- */
-
-import { appConfig } from '@config/app';
-import { HTTP_HEADERS, MIME_TYPES } from '@config/constants';
-import {
-  serveErrorPagesFileAsync,
-  serveZintrustSvgFile,
-  serveZintrustSvgFileAsync,
-} from '@core-routes/errorPages';
-import { getPublicRoot } from '@core-routes/publicRoot';
-import type { IRouter } from '@core-routes/Router';
-import { Router } from '@core-routes/Router';
-import { ErrorFactory } from '@exceptions/ZintrustError';
-import { ErrorPageRenderer } from '@http/error-pages/ErrorPageRenderer';
-import { ErrorResponse } from '@http/ErrorResponse';
-import type { IRequest } from '@http/Request';
-import type { IResponse } from '@http/Response';
-import type * as http from '@node-singletons/http';
-
-// Cache Set at module level to avoid repeated creation
-const REDACTED_HEADERS = new Set(['authorization', 'cookie', 'set-cookie', 'x-api-key']);
-
-const redactHeaders = (headers: Record<string, unknown>): Record<string, unknown> => {
-  const out: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(headers)) {
-    if (REDACTED_HEADERS.has(key.toLowerCase())) {
-      out[key] = '[redacted]';
-      continue;
-    }
-    out[key] = value;
-  }
-  return out;
-};
-
-const safeJsonStringify = (value: unknown): string => {
-  try {
-    return JSON.stringify(value, null, 2) ?? '';
-  } catch {
-    return '';
-  }
-};
-
-const trySendHtmlErrorPage = async (
-  request: IRequest,
-  response: IResponse,
-  input: {
-    statusCode: number;
-    errorName: string;
-    errorMessage: string;
-    stackPretty?: string;
-    stackRaw?: string;
-    requestPretty?: string;
-    requestRaw?: string;
-  }
-): Promise<boolean> => {
-  if (!ErrorPageRenderer.shouldSendHtml(request)) return false;
-
-  const publicRoot = getPublicRoot();
-  const html = await ErrorPageRenderer.renderHtmlAsync(publicRoot, {
-    statusCode: input.statusCode,
-    errorName: input.errorName,
-    errorMessage: input.errorMessage,
-    requestPath: request.getPath(),
-    stackPretty: input.stackPretty,
-    stackRaw: input.stackRaw,
-    requestPretty: input.requestPretty,
-    requestRaw: input.requestRaw,
-  });
-
-  if (html === undefined) return false;
-
-  response.html(html);
-  return true;
-};
-
-const handleNotFound = async (
-  request: IRequest,
-  response: IResponse,
-  requestId?: string
-): Promise<void> => {
-  const path = request.getPath();
-  if (path.startsWith('/error-pages/')) {
-    await serveErrorPagesFileAsync(path, response);
-    return;
-  }
-
-  if (path === '/zintrust.svg') {
-    if (!(await serveZintrustSvgFileAsync(response))) {
-      serveZintrustSvgFile(response);
-    }
-    return;
-  }
-
-  response.setStatus(404);
-
-  if (
-    await trySendHtmlErrorPage(request, response, {
-      statusCode: 404,
-      errorName: 'Not Found',
-      errorMessage: 'The page you requested could not be found.',
-    })
-  ) {
-    return;
-  }
-
-  response.json(ErrorResponse.notFound('Route', requestId));
-};
-
-const handleInternalServerErrorWithWrappers = async (
-  request: IRequest,
-  response: IResponse,
-  error: unknown,
-  requestId?: string
-): Promise<void> => {
-  response.setStatus(500);
-
-  const isDev = appConfig.isDevelopment();
-  const err =
-    error instanceof Error ? error : ErrorFactory.createGeneralError('Unknown error', error);
-
-  const errorName = isDev ? err.name || 'Error' : 'Internal Server Error';
-  const errorMessage = isDev
-    ? err.message || 'An error has occurred'
-    : 'Something went wrong while handling your request.';
-
-  const requestObj = isDev
-    ? {
-        method: request.getMethod(),
-        path: request.getPath(),
-        query: request.getQuery(),
-        headers: redactHeaders(request.getHeaders() as unknown as Record<string, unknown>),
-      }
-    : undefined;
-
-  const requestPretty =
-    requestObj === undefined
-      ? undefined
-      : `Request\n\nMethod: ${requestObj.method}\nPath: ${
-          requestObj.path
-        }\n\nHeaders:\n${safeJsonStringify(requestObj.headers)}\n\nQuery:\n${safeJsonStringify(
-          requestObj.query
-        )}`;
-
-  const requestRaw = requestObj === undefined ? undefined : safeJsonStringify(requestObj);
-
-  const stackPretty = isDev ? err.stack ?? '' : undefined;
-  const stackRaw = isDev
-    ? safeJsonStringify({ name: err.name, message: err.message, stack: err.stack })
-    : undefined;
-
-  if (
-    await trySendHtmlErrorPage(request, response, {
-      statusCode: 500,
-      errorName,
-      errorMessage,
-      stackPretty,
-      stackRaw,
-      requestPretty,
-      requestRaw,
-    })
-  ) {
-    return;
-  }
-
-  response.json(
-    ErrorResponse.internalServerError(
-      'Internal server error',
-      requestId,
-      isDev ? err.stack : undefined
-    )
-  );
-};
-
-const handleInternalServerErrorRaw = (res: http.ServerResponse): void => {
-  res.writeHead(500, { [HTTP_HEADERS.CONTENT_TYPE]: MIME_TYPES.JSON });
-  res.end(JSON.stringify(ErrorResponse.internalServerError('Internal server error')));
-};
-
-const handleForced404 = async (req: IRequest, res: IResponse): Promise<void> => {
-  await handleNotFound(req, res);
-};
-
-const handleForced500 = async (req: IRequest, res: IResponse): Promise<void> => {
-  const forced = ErrorFactory.createGeneralError('Forced 500 route', {
-    route: '/500',
-  });
-  await handleInternalServerErrorWithWrappers(req, res, forced);
-};
-
-/**
- * Debug routes to always render 404/500 responses.
- */
-export const registerErrorRoutes = (router: IRouter): void => {
-  Router.get(router, '/404', handleForced404);
-  Router.get(router, '/500', handleForced500);
-};
-
-type ErrorRoutingApi = {
-  getPublicRoot: () => string;
-  registerErrorRoutes: (router: IRouter) => void;
-  handleNotFound: (request: IRequest, response: IResponse, requestId?: string) => Promise<void>;
-  handleInternalServerErrorWithWrappers: (
-    request: IRequest,
-    response: IResponse,
-    error: unknown,
-    requestId?: string
-  ) => Promise<void>;
-  handleInternalServerErrorRaw: (res: http.ServerResponse) => void;
-};
-
-export const ErrorRouting: ErrorRoutingApi = Object.freeze({
-  getPublicRoot,
-  registerErrorRoutes,
-  handleNotFound,
-  handleInternalServerErrorWithWrappers,
-  handleInternalServerErrorRaw,
-});
-
-export default ErrorRouting;

package/src/routes/errorPages.ts

@@ -1,319 +0,0 @@
-/**
- * Error Pages Static Assets
- * Serves /error-pages/* assets (CSS/JS/SVG/etc) used by HTML error templates.
- */
-
-import { Cloudflare } from '@config/cloudflare';
-import { HTTP_HEADERS, MIME_TYPES } from '@config/constants';
-import { MIME_TYPES_MAP, resolveSafePath, tryDecodeURIComponent } from '@core-routes/common';
-import { getFrameworkPublicRoots } from '@core-routes/publicRoot';
-import type { IRouter } from '@core-routes/Router';
-import { Router } from '@core-routes/Router';
-import { ErrorFactory } from '@exceptions/ZintrustError';
-import type { IRequest } from '@http/Request';
-import type { IResponse } from '@http/Response';
-import * as fs from '@node-singletons/fs';
-import * as path from '@node-singletons/path';
-
-let cachedCandidateRoots: { cwd: string; roots: string[] } | null = null;
-
-const getCandidatePublicRoots = (): string[] => {
-  const cwd = process.cwd();
-  if (cachedCandidateRoots !== null && cachedCandidateRoots.cwd === cwd) {
-    return cachedCandidateRoots.roots;
-  }
-
-  const roots = [path.join(cwd, 'public'), ...getFrameworkPublicRoots()];
-  const unique = new Set(roots.map((root) => root.trim()).filter((root) => root !== ''));
-  const resolved = [...unique];
-  cachedCandidateRoots = { cwd, roots: resolved };
-  return resolved;
-};
-
-const pathExistsAsync = async (candidate: string): Promise<boolean> => {
-  try {
-    await fs.fsPromises.access(candidate);
-    return true;
-  } catch {
-    return false;
-  }
-};
-
-const isFileAsync = async (candidate: string): Promise<boolean> => {
-  try {
-    const stats = await fs.fsPromises.stat(candidate);
-    return stats.isFile();
-  } catch {
-    return false;
-  }
-};
-
-const findFirstExistingFileAsync = async (candidates: string[]): Promise<string | undefined> => {
-  const results = await Promise.all(
-    candidates.map(async (candidate) => ({
-      candidate,
-      isFile: await isFileAsync(candidate),
-    }))
-  );
-
-  return results.find((result) => result.isFile)?.candidate;
-};
-
-const resolveErrorPageFilePathAsync = async (
-  candidateRoots: string[],
-  normalizedRelative: string
-): Promise<string | undefined> => {
-  const checks = await Promise.all(
-    candidateRoots.map(async (root) => {
-      const baseDir = path.join(root, 'error-pages');
-      const filePath = resolveSafePath(baseDir, normalizedRelative);
-      if (filePath === undefined) return undefined;
-
-      try {
-        const stats = await fs.fsPromises.stat(filePath);
-        if (stats.isDirectory()) return undefined;
-        return filePath;
-      } catch {
-        return undefined;
-      }
-    })
-  );
-
-  return checks.find((filePath) => typeof filePath === 'string');
-};
-
-const servePublicRootFileAsync = async (
-  relativePath: string,
-  response: IResponse,
-  contentType: string
-): Promise<boolean> => {
-  const candidateRoots = getCandidatePublicRoots();
-  const candidates = candidateRoots.map((root) => path.join(root, relativePath));
-  const filePath = await findFirstExistingFileAsync(candidates);
-
-  try {
-    if (filePath === undefined || filePath === null) {
-      response.setStatus(404);
-      response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
-      response.send('Not Found');
-      return false;
-    }
-
-    const content = await fs.fsPromises.readFile(filePath);
-    response.setStatus(200);
-    response.setHeader(HTTP_HEADERS.CONTENT_TYPE, contentType);
-    response.send(content);
-    return true;
-  } catch (error) {
-    ErrorFactory.createTryCatchError(`Error serving public file ${filePath}`, error);
-    response.setStatus(500);
-    response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
-    response.send('Internal Server Error');
-    return false;
-  }
-};
-
-const findFirstExistingFile = (candidates: string[]): string | undefined => {
-  for (const candidate of candidates) {
-    try {
-      if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate;
-    } catch {
-      // ignore and continue
-    }
-  }
-  return undefined;
-};
-
-const servePublicRootFile = (
-  relativePath: string,
-  response: IResponse,
-  contentType: string
-): boolean => {
-  const candidateRoots = getCandidatePublicRoots();
-  const candidates = candidateRoots.map((root) => path.join(root, relativePath));
-  const filePath = findFirstExistingFile(candidates);
-
-  try {
-    if (filePath === undefined || filePath === null) {
-      response.setStatus(404);
-      response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
-      response.send('Not Found');
-      return false;
-    }
-
-    const content = fs.readFileSync(filePath);
-    response.setStatus(200);
-    response.setHeader(HTTP_HEADERS.CONTENT_TYPE, contentType);
-    response.send(content);
-    return true;
-  } catch (error) {
-    ErrorFactory.createTryCatchError(`Error serving public file ${filePath}`, error);
-    response.setStatus(500);
-    response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
-    response.send('Internal Server Error');
-    return false;
-  }
-};
-
-const serveAssetsFileAsync = async (urlPath: string, response: IResponse): Promise<boolean> => {
-  const assets = Cloudflare.getAssetsBinding();
-  if (!assets) return false;
-
-  try {
-    const url = new URL(urlPath, 'https://assets.local');
-    const res = await assets.fetch(url.toString());
-    const contentType = res.headers.get(HTTP_HEADERS.CONTENT_TYPE) ?? MIME_TYPES.TEXT;
-    const body = Buffer.from(await res.arrayBuffer());
-
-    response.setStatus(res.status);
-    response.setHeader(HTTP_HEADERS.CONTENT_TYPE, contentType);
-    response.send(body);
-    return true;
-  } catch (error) {
-    ErrorFactory.createTryCatchError(`Error serving asset ${urlPath}`, error);
-    response.setStatus(500);
-    response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
-    response.send('Internal Server Error');
-    return true;
-  }
-};
-
-export const serveErrorPagesFile = (urlPath: string, response: IResponse): boolean => {
-  if (urlPath === '/error-pages' || urlPath === '/error-pages/') {
-    response.setStatus(404);
-    response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
-    response.send('Not Found');
-    return true;
-  }
-
-  if (!urlPath.startsWith('/error-pages/')) return false;
-
-  const candidateRoots = getCandidatePublicRoots();
-
-  const rawRelative = urlPath.slice('/error-pages/'.length);
-  const normalizedRelative = tryDecodeURIComponent(rawRelative).replaceAll('\\', '/');
-
-  for (const root of candidateRoots) {
-    const baseDir = path.join(root, 'error-pages');
-    const filePath = resolveSafePath(baseDir, normalizedRelative);
-    if (filePath === undefined) continue;
-
-    try {
-      if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
-        continue;
-      }
-
-      if (!fs.existsSync(filePath)) {
-        continue;
-      }
-
-      const ext = path.extname(filePath).toLowerCase();
-      const contentType = MIME_TYPES_MAP[ext] || 'application/octet-stream';
-      const content = fs.readFileSync(filePath);
-
-      response.setStatus(200);
-      response.setHeader(HTTP_HEADERS.CONTENT_TYPE, contentType);
-      response.send(content);
-      return true;
-    } catch (error) {
-      ErrorFactory.createTryCatchError(`Error serving error-pages file ${filePath}`, error);
-      response.setStatus(500);
-      response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
-      response.send('Internal Server Error');
-      return true;
-    }
-  }
-
-  response.setStatus(404);
-  response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
-  response.send('Not Found');
-  return true;
-};
-
-export const serveErrorPagesFileAsync = async (
-  urlPath: string,
-  response: IResponse
-): Promise<boolean> => {
-  if (urlPath === '/error-pages' || urlPath === '/error-pages/') {
-    response.setStatus(404);
-    response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
-    response.send('Not Found');
-    return true;
-  }
-
-  if (!urlPath.startsWith('/error-pages/')) return false;
-
-  if (Cloudflare.getWorkersEnv() !== null) {
-    return serveAssetsFileAsync(urlPath, response);
-  }
-
-  const candidateRoots = getCandidatePublicRoots();
-
-  const rawRelative = urlPath.slice('/error-pages/'.length);
-  const normalizedRelative = tryDecodeURIComponent(rawRelative).replaceAll('\\', '/');
-
-  const filePath = await resolveErrorPageFilePathAsync(candidateRoots, normalizedRelative);
-
-  try {
-    if (filePath !== undefined && (await pathExistsAsync(filePath))) {
-      const ext = path.extname(filePath).toLowerCase();
-      const contentType = MIME_TYPES_MAP[ext] || 'application/octet-stream';
-      const content = await fs.fsPromises.readFile(filePath);
-
-      response.setStatus(200);
-      response.setHeader(HTTP_HEADERS.CONTENT_TYPE, contentType);
-      response.send(content);
-      return true;
-    }
-  } catch (error) {
-    ErrorFactory.createTryCatchError(`Error serving error-pages file ${filePath}`, error);
-    response.setStatus(500);
-    response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
-    response.send('Internal Server Error');
-    return true;
-  }
-
-  response.setStatus(404);
-  response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
-  response.send('Not Found');
-  return true;
-};
-
-const handleErrorPagesRequest = async (req: IRequest, res: IResponse): Promise<void> => {
-  const urlPath = req.getPath();
-  if (await serveErrorPagesFileAsync(urlPath, res)) return;
-
-  res.setStatus(404);
-  res.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
-  res.send('Not Found');
-};
-
-const handleZintrustSvgRequest = async (_req: IRequest, res: IResponse): Promise<void> => {
-  if (Cloudflare.getWorkersEnv() !== null) {
-    await serveAssetsFileAsync('/zintrust.svg', res);
-    return;
-  }
-  await servePublicRootFileAsync('zintrust.svg', res, MIME_TYPES.SVG);
-};
-
-export const serveZintrustSvgFile = (response: IResponse): boolean => {
-  return servePublicRootFile('zintrust.svg', response, MIME_TYPES.SVG);
-};
-
-export const serveZintrustSvgFileAsync = async (response: IResponse): Promise<boolean> => {
-  if (Cloudflare.getWorkersEnv() !== null) {
-    return serveAssetsFileAsync('/zintrust.svg', response);
-  }
-  return servePublicRootFileAsync('zintrust.svg', response, MIME_TYPES.SVG);
-};
-
-export const registerErrorPagesRoutes = (router: IRouter): void => {
-  Router.get(router, '/error-pages', handleErrorPagesRequest);
-  Router.get(router, '/error-pages/', handleErrorPagesRequest);
-  Router.get(router, '/error-pages/:path*', handleErrorPagesRequest);
-
-  // Used by the HTML error templates (logo in footer).
-  Router.get(router, '/zintrust.svg', handleZintrustSvgRequest);
-};
-
-export default { registerErrorPagesRoutes, serveErrorPagesFile };

package/src/routes/health.ts

@@ -1,6 +0,0 @@
-/**
- * Health Routes - Re-export from shared module
- * This file maintains backward compatibility while eliminating duplication
- */
-
-export { registerHealthRoutes } from '@common/HealthRoutes';

package/src/routes/metrics.ts

@@ -1,24 +0,0 @@
-/**
- * Metrics Routes
- *
- * Exposes Prometheus metrics when enabled.
- */
-
-import { PrometheusMetrics } from '@/observability/PrometheusMetrics';
-import { Env } from '@config/env';
-import { type IRouter, Router } from '@core-routes/Router';
-
-export function registerMetricsRoutes(router: IRouter): void {
-  if (Env.getBool('METRICS_ENABLED', false) === false) return;
-
-  const pathFromEnv = Env.get('METRICS_PATH', '/metrics').trim();
-  const path = pathFromEnv === '' ? '/metrics' : pathFromEnv;
-
-  Router.get(router, path, async (_req, res) => {
-    const { contentType, body } = await PrometheusMetrics.getMetricsText();
-    res.setHeader('Content-Type', contentType);
-    res.send(body);
-  });
-}
-
-export default registerMetricsRoutes;

package/src/routes/openapi.ts

@@ -1,93 +0,0 @@
-/**
- * OpenAPI Routes
- *
- * Serves a generated OpenAPI spec from the in-memory RouteRegistry.
- */
-
-import { OpenApiGenerator } from '@/openapi/OpenApiGenerator';
-import { Env } from '@config/env';
-import { type IRouter, Router } from '@core-routes/Router';
-import { RouteRegistry } from '@core-routes/RouteRegistry';
-
-const getServerUrl = (): string | undefined => {
-  const explicit = Env.BASE_URL;
-  if (explicit.trim() !== '') return explicit;
-
-  const host = Env.HOST;
-  const port = Env.PORT;
-  if (host.trim() === '' || Number.isNaN(port) || port <= 0) return undefined;
-
-  return `http://${host}:${port}`;
-};
-
-const getDocsHtml = (specUrl: string): string => `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>${Env.APP_NAME} API Docs</title>
-    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
-    <style>
-      html, body { margin: 0; padding: 0; }
-      #swagger-ui { box-sizing: border-box; }
-    </style>
-  </head>
-  <body>
-    <div id="swagger-ui"></div>
-    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
-    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"></script>
-    <script>
-      window.onload = function () {
-        window.ui = SwaggerUIBundle({
-          url: ${JSON.stringify(specUrl)},
-          dom_id: '#swagger-ui',
-          presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
-          layout: 'BaseLayout'
-        });
-      };
-    </script>
-  </body>
-</html>`;
-
-export function registerOpenApiRoutes(router: IRouter): void {
-  Router.get(
-    router,
-    '/openapi.json',
-    (_req, res) => {
-      // Convert readonly to mutable array for OpenApiGenerator
-      const routes = Array.from(RouteRegistry.list());
-      const doc = OpenApiGenerator.generate(routes, {
-        title: Env.APP_NAME,
-        version: Env.get('APP_VERSION', '0.0.0'),
-        serverUrl: getServerUrl(),
-        excludePaths: ['/openapi.json', '/docs'],
-      });
-
-      res.json(doc);
-    },
-    {
-      meta: {
-        summary: 'OpenAPI spec',
-        tags: ['Docs'],
-        responseStatus: 200,
-      },
-    }
-  );
-
-  Router.get(
-    router,
-    '/docs',
-    (_req, res) => {
-      res.html(getDocsHtml('/openapi.json'));
-    },
-    {
-      meta: {
-        summary: 'Swagger UI',
-        tags: ['Docs'],
-        responseStatus: 200,
-      },
-    }
-  );
-}
-
-export default registerOpenApiRoutes;