@zintrust/core 0.1.26 → 0.1.28

package/src/routes/common.ts

@@ -0,0 +1,50 @@
+/**
+ * Routing Common Utilities
+ * Shared helpers for static routes and content-type resolution.
+ */
+
+import { MIME_TYPES } from '@config/constants';
+import * as path from '@node-singletons/path';
+
+/**
+ * MIME types for static file serving.
+ */
+export const MIME_TYPES_MAP: Record<string, string> = {
+  '.html': MIME_TYPES.HTML,
+  '.js': MIME_TYPES.JS,
+  '.css': MIME_TYPES.CSS,
+  '.json': MIME_TYPES.JSON,
+  '.png': MIME_TYPES.PNG,
+  '.jpg': MIME_TYPES.JPG,
+  '.gif': MIME_TYPES.GIF,
+  '.svg': MIME_TYPES.SVG,
+  '.wav': MIME_TYPES.WAV,
+  '.mp4': MIME_TYPES.MP4,
+  '.woff': MIME_TYPES.WOFF,
+  '.ttf': MIME_TYPES.TTF,
+  '.eot': MIME_TYPES.EOT,
+  '.otf': MIME_TYPES.OTF,
+  '.wasm': MIME_TYPES.WASM,
+};
+
+export const tryDecodeURIComponent = (value: string): string => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+};
+
+/**
+ * Resolves a relative path against a base directory and ensures it stays within it.
+ * Returns undefined if the resolved path escapes the base.
+ */
+export const resolveSafePath = (baseDir: string, relativePath: string): string | undefined => {
+  const baseAbs = path.resolve(baseDir);
+  const candidate = path.resolve(baseDir, relativePath);
+
+  if (candidate === baseAbs) return candidate;
+  if (!candidate.startsWith(baseAbs + path.sep)) return undefined;
+
+  return candidate;
+};

package/src/routes/doc.ts

@@ -0,0 +1,139 @@
+/**
+ * Documentation Routes
+ * Serves static files from /doc/* paths with relaxed CSP headers.
+ */
+
+import { HTTP_HEADERS } from '@config/constants';
+import { MIME_TYPES_MAP, resolveSafePath, tryDecodeURIComponent } from '@core-routes/common';
+import { ErrorRouting } from '@core-routes/error';
+import { getPublicRootAsync } 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';
+
+export { MIME_TYPES_MAP } from '@core-routes/common';
+
+/**
+ * Find the package root directory
+ */
+// Backward-compatible re-exports
+export {
+  findPackageRoot,
+  findPackageRootAsync,
+  getFrameworkPublicRoots,
+  getFrameworkPublicRootsAsync,
+  getPublicRoot,
+  getPublicRootAsync,
+} from '@core-routes/publicRoot';
+
+const mapStaticPathAsync = async (urlPath: string): Promise<string | undefined> => {
+  const publicRoot = await getPublicRootAsync();
+  const normalize = (p: string): string => (p.startsWith('/') ? p.slice(1) : p);
+
+  if (urlPath === '/doc' || urlPath === '/doc/') return publicRoot;
+  if (urlPath.startsWith('/doc/')) {
+    const rawRelative = urlPath.slice('/doc/'.length);
+    const normalizedRelative = tryDecodeURIComponent(rawRelative).replaceAll('\\', '/');
+    return resolveSafePath(publicRoot, normalize(normalizedRelative));
+  }
+
+  const normalized = tryDecodeURIComponent(urlPath).replaceAll('\\', '/');
+  return resolveSafePath(publicRoot, normalize(normalized));
+};
+
+/**
+ * Set relaxed CSP headers for docs (allows external assets like Tailwind CDN, Google Fonts)
+ */
+export const setDocumentationCSPHeaders = (response: IResponse): void => {
+  response.setHeader(
+    HTTP_HEADERS.CONTENT_SECURITY_POLICY,
+    "default-src 'self'; " +
+      "script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdn.tailwindcss.com; " +
+      "script-src-elem 'self' 'unsafe-inline' https://cdn.tailwindcss.com; " +
+      "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; " +
+      "style-src-elem 'self' 'unsafe-inline' https://fonts.googleapis.com; " +
+      "img-src 'self' data: https:; " +
+      "font-src 'self' data: https://fonts.gstatic.com;"
+  );
+};
+
+/**
+ * Serve a documentation static file (async)
+ */
+export const serveDocumentationFileAsync = async (
+  urlPath: string,
+  response: IResponse
+): Promise<boolean> => {
+  let filePath = await mapStaticPathAsync(urlPath);
+
+  if (filePath === undefined) {
+    return false;
+  }
+
+  try {
+    try {
+      const stats = await fs.fsPromises.stat(filePath);
+      if (stats.isDirectory()) {
+        filePath = path.join(filePath, 'index.html');
+      }
+    } catch {
+      // ignore
+    }
+
+    const exists = async (p: string): Promise<boolean> => {
+      try {
+        await fs.fsPromises.access(p);
+        return true;
+      } catch {
+        return false;
+      }
+    };
+
+    if (!(await exists(filePath)) && !path.extname(filePath)) {
+      const htmlPath = `${filePath}.html`;
+      if (await exists(htmlPath)) {
+        filePath = htmlPath;
+      }
+    }
+
+    if (await exists(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('Content-Type', contentType);
+      response.send(content);
+      return true;
+    }
+  } catch (error) {
+    ErrorFactory.createTryCatchError(`Error serving documentation file ${filePath}`, error);
+  }
+
+  return false;
+};
+
+const handleDocRequest = async (req: IRequest, res: IResponse): Promise<void> => {
+  setDocumentationCSPHeaders(res);
+  const urlPath = req.getPath();
+  if (await serveDocumentationFileAsync(urlPath, res)) return;
+  ErrorRouting.handleNotFound(req, res);
+};
+
+export const registerDocRoutes = (router: IRouter): void => {
+  // Root docs entrypoints.
+  Router.get(router, '/doc', handleDocRequest);
+  Router.get(router, '/doc/', handleDocRequest);
+  // Greedy path match for nested assets like /doc/assets/app.js
+  Router.get(router, '/doc/:path*', handleDocRequest);
+};
+
+export default {
+  registerDocRoutes,
+  setDocumentationCSPHeaders,
+  serveDocumentationFileAsync,
+};

package/src/routes/error.ts

@@ -0,0 +1,185 @@
+/**
+ * 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 { 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 = (
+  request: IRequest,
+  response: IResponse,
+  input: {
+    statusCode: number;
+    errorName: string;
+    errorMessage: string;
+    stackPretty?: string;
+    stackRaw?: string;
+    requestPretty?: string;
+    requestRaw?: string;
+  }
+): boolean => {
+  if (!ErrorPageRenderer.shouldSendHtml(request)) return false;
+
+  const publicRoot = getPublicRoot();
+  const html = ErrorPageRenderer.renderHtml(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 = (request: IRequest, response: IResponse, requestId?: string): void => {
+  response.setStatus(404);
+
+  if (
+    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 = (
+  request: IRequest,
+  response: IResponse,
+  error: unknown,
+  requestId?: string
+): 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 (
+    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 = (req: IRequest, res: IResponse): void => {
+  handleNotFound(req, res);
+};
+
+const handleForced500 = (req: IRequest, res: IResponse): void => {
+  const forced = ErrorFactory.createGeneralError('Forced 500 route', {
+    route: '/500',
+  });
+  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);
+};
+
+export const ErrorRouting = Object.freeze({
+  getPublicRoot,
+  registerErrorRoutes,
+  handleNotFound,
+  handleInternalServerErrorWithWrappers,
+  handleInternalServerErrorRaw,
+});
+
+export default ErrorRouting;

package/src/routes/errorPages.ts

@@ -0,0 +1,125 @@
+/**
+ * Error Pages Static Assets
+ * Serves /error-pages/* assets (CSS/JS/SVG/etc) used by HTML error templates.
+ */
+
+import { HTTP_HEADERS, MIME_TYPES } from '@config/constants';
+import { MIME_TYPES_MAP, resolveSafePath, tryDecodeURIComponent } from '@core-routes/common';
+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 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';
+
+const servePublicRootFile = (
+  relativePath: string,
+  response: IResponse,
+  contentType: string
+): void => {
+  const publicRoot = getPublicRoot();
+  const filePath = path.join(publicRoot, relativePath);
+
+  try {
+    if (!fs.existsSync(filePath) || fs.statSync(filePath).isDirectory()) {
+      response.setStatus(404);
+      response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
+      response.send('Not Found');
+      return;
+    }
+
+    const content = fs.readFileSync(filePath);
+    response.setStatus(200);
+    response.setHeader(HTTP_HEADERS.CONTENT_TYPE, contentType);
+    response.send(content);
+    return;
+  } 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;
+  }
+};
+
+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 publicRoot = getPublicRoot();
+  const baseDir = path.join(publicRoot, 'error-pages');
+
+  const rawRelative = urlPath.slice('/error-pages/'.length);
+  const normalizedRelative = tryDecodeURIComponent(rawRelative).replaceAll('\\', '/');
+
+  const filePath = resolveSafePath(baseDir, normalizedRelative);
+  if (filePath === undefined) {
+    response.setStatus(404);
+    response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
+    response.send('Not Found');
+    return true;
+  }
+
+  try {
+    if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
+      response.setStatus(404);
+      response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
+      response.send('Not Found');
+      return true;
+    }
+
+    if (!fs.existsSync(filePath)) {
+      response.setStatus(404);
+      response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
+      response.send('Not Found');
+      return true;
+    }
+
+    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;
+  }
+};
+
+const handleErrorPagesRequest = (req: IRequest, res: IResponse): void => {
+  const urlPath = req.getPath();
+  if (serveErrorPagesFile(urlPath, res)) return;
+
+  res.setStatus(404);
+  res.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
+  res.send('Not Found');
+};
+
+const handleZintrustSvgRequest = (_req: IRequest, res: IResponse): void => {
+  servePublicRootFile('zintrust.svg', res, 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

@@ -0,0 +1,6 @@
+/**
+ * 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

@@ -0,0 +1,24 @@
+/**
+ * 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

@@ -0,0 +1,93 @@
+/**
+ * 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;