@zintrust/core 0.1.19 → 0.1.20

package/src/routing/Router.d.ts

@@ -1,13 +1,21 @@
-import { IRequest } from '../http/Request';
-import { IResponse } from '../http/Response';
+import type { IRequest } from '../http/Request';
+import type { IResponse } from '../http/Response';
+import { type RouteMeta, type RouteMetaInput } from './RouteRegistry';
 /**
  * Router - HTTP Routing Engine
  * Matches incoming requests to route handlers
  */
 export type RouteHandler = (req: IRequest, res: IResponse) => Promise<void> | void;
+export type RouteOptions<MiddlewareName extends string = string> = {
+    middleware?: ReadonlyArray<MiddlewareName>;
+    meta?: RouteMetaInput;
+};
 export interface RouteMatch {
     handler: RouteHandler;
     params: Record<string, string>;
+    middleware?: string[];
+    meta?: RouteMeta;
+    routePath?: string;
 }
 export interface Route {
     method: string;
@@ -15,6 +23,8 @@ export interface Route {
     pattern: RegExp;
     handler: RouteHandler;
     paramNames: string[];
+    middleware?: string[];
+    meta?: RouteMeta;
 }
 export type RouteGroupCallback = (router: IRouter) => void;
 export interface ResourceController {
@@ -24,6 +34,13 @@ export interface ResourceController {
     update?: RouteHandler;
     destroy?: RouteHandler;
 }
+export type ResourceOptions<MiddlewareName extends string = string> = RouteOptions<MiddlewareName> & {
+    index?: RouteOptions<MiddlewareName>;
+    show?: RouteOptions<MiddlewareName>;
+    store?: RouteOptions<MiddlewareName>;
+    update?: RouteOptions<MiddlewareName>;
+    destroy?: RouteOptions<MiddlewareName>;
+};
 export type IRouter = {
     routes: Route[];
     prefix: string;
@@ -38,13 +55,13 @@ export declare const Router: Readonly<{
     createRouter: () => IRouter;
     scopeRouter: (router: IRouter, prefix: string) => IRouter;
     group: (router: IRouter, prefix: string, callback: RouteGroupCallback) => void;
-    resource: (router: IRouter, path: string, controller: ResourceController) => void;
-    get: (router: IRouter, path: string, handler: RouteHandler) => void;
-    post: (router: IRouter, path: string, handler: RouteHandler) => void;
-    put: (router: IRouter, path: string, handler: RouteHandler) => void;
-    patch: (router: IRouter, path: string, handler: RouteHandler) => void;
-    del: (router: IRouter, path: string, handler: RouteHandler) => void;
-    any: (router: IRouter, path: string, handler: RouteHandler) => void;
+    resource: <M extends string = string>(router: IRouter, path: string, controller: ResourceController, options?: ResourceOptions<M>) => void;
+    get: <M extends string = string>(router: IRouter, path: string, handler: RouteHandler, options?: RouteOptions<M>) => void;
+    post: <M extends string = string>(router: IRouter, path: string, handler: RouteHandler, options?: RouteOptions<M>) => void;
+    put: <M extends string = string>(router: IRouter, path: string, handler: RouteHandler, options?: RouteOptions<M>) => void;
+    patch: <M extends string = string>(router: IRouter, path: string, handler: RouteHandler, options?: RouteOptions<M>) => void;
+    del: <M extends string = string>(router: IRouter, path: string, handler: RouteHandler, options?: RouteOptions<M>) => void;
+    any: <M extends string = string>(router: IRouter, path: string, handler: RouteHandler, options?: RouteOptions<M>) => void;
     match: (router: IRouter, method: string, path: string) => RouteMatch | null;
     getRoutes: (router: IRouter) => Route[];
 }>;

package/src/routing/Router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Router.d.ts","sourceRoot":"","sources":["../../../src/routing/Router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;GAGG;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEnF,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;AAE3D,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,MAAM,OAAO,GAAG;IACpB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;CAClC,CAAC;AAEF,eAAO,MAAM,YAAY,QAAO,OAI9B,CAAC;AAoMH;;;GAGG;AACH,eAAO,MAAM,MAAM;wBA5Ma,OAAO;0BA8IV,OAAO,UAAU,MAAM,KAAG,OAAO;oBAMvC,OAAO,UAAU,MAAM,YAAY,kBAAkB,KAAG,IAAI;uBAIzD,OAAO,QAAQ,MAAM,cAAc,kBAAkB,KAAG,IAAI;kBAgBjE,OAAO,QAAQ,MAAM,WAAW,YAAY,KAAG,IAAI;mBAIlD,OAAO,QAAQ,MAAM,WAAW,YAAY,KAAG,IAAI;kBAIpD,OAAO,QAAQ,MAAM,WAAW,YAAY,KAAG,IAAI;oBAIjD,OAAO,QAAQ,MAAM,WAAW,YAAY,KAAG,IAAI;kBAIrD,OAAO,QAAQ,MAAM,WAAW,YAAY,KAAG,IAAI;kBAInD,OAAO,QAAQ,MAAM,WAAW,YAAY,KAAG,IAAI;oBAOjD,OAAO,UAAU,MAAM,QAAQ,MAAM,KAAG,UAAU,GAAG,IAAI;wBAGrD,OAAO,KAAG,KAAK,EAAE;EAmB1C,CAAC;AAEH,eAAe,MAAM,CAAC"}
+{"version":3,"file":"Router.d.ts","sourceRoot":"","sources":["../../../src/routing/Router.ts"],"names":[],"mappings":"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"}

package/src/routing/Router.js

@@ -1,3 +1,4 @@
+import { RouteRegistry, normalizeRouteMeta, } from './RouteRegistry.js';
 export const createRouter = () => ({
     routes: [],
     prefix: '',
@@ -13,9 +14,13 @@ export const createRouter = () => ({
  */
 const pathToRegex = (path) => {
     const paramNames = [];
-    let regexPath = path.replaceAll(/:([a-zA-Z_]\w*)/g, (_, paramName) => {
+    // Supports:
+    // - :id     => single path segment (no slashes)
+    // - :path*  => greedy match (may include slashes)
+    let regexPath = path.replaceAll(/:([a-zA-Z_]\w*)(\*)?/g, (_full, paramName, star) => {
         paramNames.push(paramName);
-        return '([^/]+)';
+        const isGreedy = star === '*';
+        return isGreedy ? '(.+)' : '([^/]+)';
     });
     regexPath = `^${regexPath}$`;
     const pattern = new RegExp(regexPath);
@@ -24,7 +29,7 @@ const pathToRegex = (path) => {
 /**
  * Register a route
  */
-const registerRoute = (router, method, path, handler) => {
+const registerRoute = (router, method, path, handler, options) => {
     const { pattern, paramNames } = pathToRegex(path);
     const route = {
         method,
@@ -32,8 +37,16 @@ const registerRoute = (router, method, path, handler) => {
         pattern,
         handler,
         paramNames,
+        middleware: Array.isArray(options?.middleware) ? options?.middleware : undefined,
+        meta: normalizeRouteMeta(options?.meta),
     };
     router.routes.push(route);
+    RouteRegistry.record({
+        method,
+        path,
+        middleware: route.middleware,
+        meta: route.meta,
+    });
     // Index by method for faster lookup
     if (!router.routeIndex.has(method)) {
         router.routeIndex.set(method, []);
@@ -54,6 +67,9 @@ const getRouteMatch = (route, path) => {
     return {
         handler: route.handler,
         params,
+        middleware: route.middleware,
+        meta: route.meta,
+        routePath: route.path,
     };
 };
 /**
@@ -131,41 +147,69 @@ const scopeRouter = (router, prefix) => ({
 const group = (router, prefix, callback) => {
     callback(scopeRouter(router, prefix));
 };
-const resource = (router, path, controller) => {
-    const base = joinPaths(router.prefix, path);
+function buildResourcePaths(prefix, path) {
+    const base = joinPaths(prefix, path);
     const withId = `${base.endsWith('/') ? base.slice(0, -1) : base}/:id`;
-    if (controller.index)
-        registerRoute(router, 'GET', base, controller.index);
-    if (controller.store)
-        registerRoute(router, 'POST', base, controller.store);
-    if (controller.show)
-        registerRoute(router, 'GET', withId, controller.show);
-    if (controller.update) {
-        registerRoute(router, 'PUT', withId, controller.update);
-        registerRoute(router, 'PATCH', withId, controller.update);
-    }
-    if (controller.destroy)
-        registerRoute(router, 'DELETE', withId, controller.destroy);
-};
-const get = (router, path, handler) => {
-    registerRoute(router, 'GET', joinPaths(router.prefix, path), handler);
-};
-const post = (router, path, handler) => {
-    registerRoute(router, 'POST', joinPaths(router.prefix, path), handler);
-};
-const put = (router, path, handler) => {
-    registerRoute(router, 'PUT', joinPaths(router.prefix, path), handler);
-};
-const patch = (router, path, handler) => {
-    registerRoute(router, 'PATCH', joinPaths(router.prefix, path), handler);
-};
-const del = (router, path, handler) => {
-    registerRoute(router, 'DELETE', joinPaths(router.prefix, path), handler);
-};
-const any = (router, path, handler) => {
+    return { base, withId };
+}
+function resolveResourceDefaultOptions(options) {
+    return options?.middleware ? { middleware: options.middleware } : undefined;
+}
+function registerResourceIndex(router, base, controller, options, defaultOptions) {
+    if (!controller.index)
+        return;
+    registerRoute(router, 'GET', base, controller.index, options?.index ?? defaultOptions);
+}
+function registerResourceStore(router, base, controller, options, defaultOptions) {
+    if (!controller.store)
+        return;
+    registerRoute(router, 'POST', base, controller.store, options?.store ?? defaultOptions);
+}
+function registerResourceShow(router, withId, controller, options, defaultOptions) {
+    if (!controller.show)
+        return;
+    registerRoute(router, 'GET', withId, controller.show, options?.show ?? defaultOptions);
+}
+function registerResourceUpdate(router, withId, controller, options, defaultOptions) {
+    if (!controller.update)
+        return;
+    const updateOptions = options?.update ?? defaultOptions;
+    registerRoute(router, 'PUT', withId, controller.update, updateOptions);
+    registerRoute(router, 'PATCH', withId, controller.update, updateOptions);
+}
+function registerResourceDestroy(router, withId, controller, options, defaultOptions) {
+    if (!controller.destroy)
+        return;
+    registerRoute(router, 'DELETE', withId, controller.destroy, options?.destroy ?? defaultOptions);
+}
+const resource = (router, path, controller, options) => {
+    const { base, withId } = buildResourcePaths(router.prefix, path);
+    const defaultOptions = resolveResourceDefaultOptions(options);
+    registerResourceIndex(router, base, controller, options, defaultOptions);
+    registerResourceStore(router, base, controller, options, defaultOptions);
+    registerResourceShow(router, withId, controller, options, defaultOptions);
+    registerResourceUpdate(router, withId, controller, options, defaultOptions);
+    registerResourceDestroy(router, withId, controller, options, defaultOptions);
+};
+const get = (router, path, handler, options) => {
+    registerRoute(router, 'GET', joinPaths(router.prefix, path), handler, options);
+};
+const post = (router, path, handler, options) => {
+    registerRoute(router, 'POST', joinPaths(router.prefix, path), handler, options);
+};
+const put = (router, path, handler, options) => {
+    registerRoute(router, 'PUT', joinPaths(router.prefix, path), handler, options);
+};
+const patch = (router, path, handler, options) => {
+    registerRoute(router, 'PATCH', joinPaths(router.prefix, path), handler, options);
+};
+const del = (router, path, handler, options) => {
+    registerRoute(router, 'DELETE', joinPaths(router.prefix, path), handler, options);
+};
+const any = (router, path, handler, options) => {
     const fullPath = joinPaths(router.prefix, path);
     ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].forEach((method) => {
-        registerRoute(router, method, fullPath, handler);
+        registerRoute(router, method, fullPath, handler, options);
     });
 };
 const match = (router, method, path) => matchRoute(router, method, path);

package/src/routing/common.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Routing Common Utilities
+ * Shared helpers for static routes and content-type resolution.
+ */
+/**
+ * MIME types for static file serving.
+ */
+export declare const MIME_TYPES_MAP: Record<string, string>;
+export declare const tryDecodeURIComponent: (value: string) => string;
+/**
+ * Resolves a relative path against a base directory and ensures it stays within it.
+ * Returns undefined if the resolved path escapes the base.
+ */
+export declare const resolveSafePath: (baseDir: string, relativePath: string) => string | undefined;
+//# sourceMappingURL=common.d.ts.map

package/src/routing/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/routing/common.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAgBjD,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,OAAO,MAAM,KAAG,MAMrD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,EAAE,cAAc,MAAM,KAAG,MAAM,GAAG,SAQhF,CAAC"}

package/src/routing/common.js

@@ -0,0 +1,47 @@
+/**
+ * Routing Common Utilities
+ * Shared helpers for static routes and content-type resolution.
+ */
+import { MIME_TYPES } from '../config/constants.js';
+import * as path from '../node-singletons/path.js';
+/**
+ * MIME types for static file serving.
+ */
+export const MIME_TYPES_MAP = {
+    '.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) => {
+    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, relativePath) => {
+    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/routing/doc.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Documentation Routes
+ * Serves static files from /doc/* paths with relaxed CSP headers.
+ */
+import type { IResponse } from '../http/Response';
+import type { IRouter } from './Router';
+export { MIME_TYPES_MAP } from './common';
+/**
+ * Find the package root directory
+ */
+export { findPackageRoot, getFrameworkPublicRoots, getPublicRoot } from './publicRoot';
+/**
+ * Set relaxed CSP headers for docs (allows external assets like Tailwind CDN, Google Fonts)
+ */
+export declare const setDocumentationCSPHeaders: (response: IResponse) => void;
+/**
+ * Serve a documentation static file
+ * Returns true if file was served, false if not found
+ */
+export declare const serveDocumentationFile: (urlPath: string, response: IResponse) => boolean;
+export declare const registerDocRoutes: (router: IRouter) => void;
+declare const _default: {
+    registerDocRoutes: (router: IRouter) => void;
+    setDocumentationCSPHeaders: (response: IResponse) => void;
+    serveDocumentationFile: (urlPath: string, response: IResponse) => boolean;
+};
+export default _default;
+//# sourceMappingURL=doc.d.ts.map

package/src/routing/doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../../src/routing/doc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAMhD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAG/C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAoB9F;;GAEG;AACH,eAAO,MAAM,0BAA0B,GAAI,UAAU,SAAS,KAAG,IAWhE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GAAI,SAAS,MAAM,EAAE,UAAU,SAAS,KAAG,OAkC7E,CAAC;AASF,eAAO,MAAM,iBAAiB,GAAI,QAAQ,OAAO,KAAG,IAMnD,CAAC;;gCANwC,OAAO,KAAG,IAAI;2CA5DH,SAAS,KAAG,IAAI;sCAiBrB,MAAM,YAAY,SAAS,KAAG,OAAO;;AAmDrF,wBAAyF"}

package/src/routing/doc.js

@@ -0,0 +1,95 @@
+/**
+ * Documentation Routes
+ * Serves static files from /doc/* paths with relaxed CSP headers.
+ */
+import { HTTP_HEADERS } from '../config/constants.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import * as fs from '../node-singletons/fs.js';
+import * as path from '../node-singletons/path.js';
+import { MIME_TYPES_MAP, resolveSafePath, tryDecodeURIComponent } from './common.js';
+import { ErrorRouting } from './error.js';
+import { getPublicRoot } from './publicRoot.js';
+import { Router } from './Router.js';
+export { MIME_TYPES_MAP } from './common.js';
+/**
+ * Find the package root directory
+ */
+// Backward-compatible re-exports
+export { findPackageRoot, getFrameworkPublicRoots, getPublicRoot } from './publicRoot.js';
+/**
+ * Map URL path to physical file path for /doc routes
+ */
+const mapStaticPath = (urlPath) => {
+    const publicRoot = getPublicRoot();
+    const normalize = (p) => (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) => {
+    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
+ * Returns true if file was served, false if not found
+ */
+export const serveDocumentationFile = (urlPath, response) => {
+    let filePath = mapStaticPath(urlPath);
+    if (filePath === undefined) {
+        return false;
+    }
+    try {
+        if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
+            filePath = path.join(filePath, 'index.html');
+        }
+        if (!fs.existsSync(filePath) && !path.extname(filePath)) {
+            const htmlPath = `${filePath}.html`;
+            if (fs.existsSync(htmlPath)) {
+                filePath = htmlPath;
+            }
+        }
+        if (fs.existsSync(filePath)) {
+            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('Content-Type', contentType);
+            response.send(content);
+            return true;
+        }
+    }
+    catch (error) {
+        ErrorFactory.createTryCatchError(`Error serving documentation file ${filePath}`, error);
+    }
+    return false;
+};
+const handleDocRequest = (req, res) => {
+    setDocumentationCSPHeaders(res);
+    const urlPath = req.getPath();
+    if (serveDocumentationFile(urlPath, res))
+        return;
+    ErrorRouting.handleNotFound(req, res);
+};
+export const registerDocRoutes = (router) => {
+    // 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, serveDocumentationFile };

package/src/routing/error.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Error Routing
+ * Centralizes 404/500 handling and HTML error page rendering.
+ */
+import type { IRequest } from '../http/Request';
+import type { IResponse } from '../http/Response';
+import type * as http from '../node-singletons/http';
+import type { IRouter } from './Router';
+/**
+ * Debug routes to always render 404/500 responses.
+ */
+export declare const registerErrorRoutes: (router: IRouter) => void;
+export declare const ErrorRouting: Readonly<{
+    getPublicRoot: () => string;
+    registerErrorRoutes: (router: IRouter) => void;
+    handleNotFound: (request: IRequest, response: IResponse, requestId?: string) => void;
+    handleInternalServerErrorWithWrappers: (request: IRequest, response: IResponse, error: unknown, requestId?: string) => void;
+    handleInternalServerErrorRaw: (res: http.ServerResponse) => void;
+}>;
+export default ErrorRouting;
+//# sourceMappingURL=error.d.ts.map

package/src/routing/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../src/routing/error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAEnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAwJ/C;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,OAAO,KAAG,IAGrD,CAAC;AAEF,eAAO,MAAM,YAAY;;kCALmB,OAAO,KAAG,IAAI;8BAlGzB,QAAQ,YAAY,SAAS,cAAc,MAAM,KAAG,IAAI;qDAiB9E,QAAQ,YACP,SAAS,SACZ,OAAO,cACF,MAAM,KACjB,IAAI;wCA0DoC,IAAI,CAAC,cAAc,KAAG,IAAI;EA8BnE,CAAC;AAEH,eAAe,YAAY,CAAC"}

package/src/routing/error.js

@@ -0,0 +1,126 @@
+/**
+ * Error Routing
+ * Centralizes 404/500 handling and HTML error page rendering.
+ */
+import { appConfig } from '../config/app.js';
+import { HTTP_HEADERS, MIME_TYPES } from '../config/constants.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { ErrorPageRenderer } from '../http/error-pages/ErrorPageRenderer.js';
+import { ErrorResponse } from '../http/ErrorResponse.js';
+import { getPublicRoot } from './publicRoot.js';
+import { Router } from './Router.js';
+const redactHeaders = (headers) => {
+    const redacted = new Set(['authorization', 'cookie', 'set-cookie', 'x-api-key']);
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (redacted.has(key.toLowerCase())) {
+            out[key] = '[redacted]';
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+};
+const safeJsonStringify = (value) => {
+    try {
+        return JSON.stringify(value, null, 2) ?? '';
+    }
+    catch {
+        return '';
+    }
+};
+const trySendHtmlErrorPage = (request, response, input) => {
+    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, response, requestId) => {
+    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, response, error, requestId) => {
+    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()),
+        }
+        : 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) => {
+    res.writeHead(500, { [HTTP_HEADERS.CONTENT_TYPE]: MIME_TYPES.JSON });
+    res.end(JSON.stringify(ErrorResponse.internalServerError('Internal server error')));
+};
+const handleForced404 = (req, res) => {
+    handleNotFound(req, res);
+};
+const handleForced500 = (req, res) => {
+    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) => {
+    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/routing/errorPages.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Error Pages Static Assets
+ * Serves /error-pages/* assets (CSS/JS/SVG/etc) used by HTML error templates.
+ */
+import type { IResponse } from '../http/Response';
+import type { IRouter } from './Router';
+export declare const serveErrorPagesFile: (urlPath: string, response: IResponse) => boolean;
+export declare const registerErrorPagesRoutes: (router: IRouter) => void;
+declare const _default: {
+    registerErrorPagesRoutes: (router: IRouter) => void;
+    serveErrorPagesFile: (urlPath: string, response: IResponse) => boolean;
+};
+export default _default;
+//# sourceMappingURL=errorPages.d.ts.map

package/src/routing/errorPages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorPages.d.ts","sourceRoot":"","sources":["../../../src/routing/errorPages.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAKhD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAiC/C,eAAO,MAAM,mBAAmB,GAAI,SAAS,MAAM,EAAE,UAAU,SAAS,KAAG,OAsD1E,CAAC;AAeF,eAAO,MAAM,wBAAwB,GAAI,QAAQ,OAAO,KAAG,IAO1D,CAAC;;uCAP+C,OAAO,KAAG,IAAI;mCArElB,MAAM,YAAY,SAAS,KAAG,OAAO;;AA8ElF,wBAAiE"}