@zintrust/core 0.1.18 → 0.1.20

package/src/http/RequestContext.js

@@ -1,4 +1,4 @@
-import { generateUuid } from '../common/uuid.js';
+import { generateUuid } from '../common/utility.js';
 const createFallbackStorage = () => {
     let store;
     return {
@@ -30,6 +30,52 @@ const getHeaderString = (req, name) => {
     const value = req.getHeader(name);
     return typeof value === 'string' ? value : undefined;
 };
+const extractTraceIdFromTraceparent = (traceparent) => {
+    if (typeof traceparent !== 'string')
+        return undefined;
+    const trimmed = traceparent.trim();
+    if (trimmed === '')
+        return undefined;
+    // W3C traceparent: version-traceid-spanid-flags
+    // Example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+    const parts = trimmed.split('-');
+    if (parts.length !== 4)
+        return undefined;
+    const traceId = parts[1] ?? '';
+    if (/^[0-9a-f]{32}$/i.test(traceId) === false)
+        return undefined;
+    // Disallow all-zero traceId
+    if (/^0{32}$/i.test(traceId))
+        return undefined;
+    return traceId.toLowerCase();
+};
+const getTraceIdFromMicroserviceTraceContext = (req) => {
+    const anyReq = req;
+    const trace = anyReq.context?.['trace'];
+    if (typeof trace !== 'object' || trace === null)
+        return undefined;
+    const traceId = trace.traceId;
+    return typeof traceId === 'string' && traceId.trim() !== '' ? traceId : undefined;
+};
+const getOptionalContextString = (req, key) => {
+    const anyReq = req;
+    const value = anyReq.context?.[key];
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number')
+        return String(value);
+    return undefined;
+};
+const setContextField = (req, field, value) => {
+    req.context ??= {};
+    if (typeof value === 'string' && value.trim() !== '') {
+        req.context[field] = value;
+    }
+    const ctx = RequestContext.get(req);
+    if (ctx) {
+        ctx[field] = value;
+    }
+};
 const STORAGE_PROMISE = resolveStorage();
 export const RequestContext = Object.freeze({
     async run(context, callback) {
@@ -44,14 +90,29 @@ export const RequestContext = Object.freeze({
         req.context ??= {};
         const requestIdFromHeader = getHeaderString(req, 'x-request-id');
         const requestId = requestIdFromHeader ?? generateUuid();
+        const traceId = extractTraceIdFromTraceparent(getHeaderString(req, 'traceparent')) ??
+            getHeaderString(req, 'x-trace-id') ??
+            getTraceIdFromMicroserviceTraceContext(req) ??
+            getOptionalContextString(req, 'traceId');
+        const userId = getOptionalContextString(req, 'userId');
+        const tenantId = getOptionalContextString(req, 'tenantId');
         const ctx = {
             requestId,
+            traceId,
+            userId,
+            tenantId,
             startTime: Date.now(),
             method: req.getMethod(),
             path: req.getPath(),
             userAgent: getHeaderString(req, 'user-agent'),
         };
         req.context['requestId'] = requestId;
+        if (traceId !== undefined)
+            req.context['traceId'] = traceId;
+        if (userId !== undefined)
+            req.context['userId'] = userId;
+        if (tenantId !== undefined)
+            req.context['tenantId'] = tenantId;
         req.context['requestContext'] = ctx;
         return ctx;
     },
@@ -59,6 +120,12 @@ export const RequestContext = Object.freeze({
         req.context ??= {};
         req.context['requestContext'] = context;
         req.context['requestId'] = context.requestId;
+        if (context.traceId !== undefined)
+            req.context['traceId'] = context.traceId;
+        if (context.userId !== undefined)
+            req.context['userId'] = context.userId;
+        if (context.tenantId !== undefined)
+            req.context['tenantId'] = context.tenantId;
     },
     get(req) {
         const anyReq = req;
@@ -73,5 +140,14 @@ export const RequestContext = Object.freeze({
             duration,
         };
     },
+    setUserId(req, userId) {
+        setContextField(req, 'userId', userId);
+    },
+    setTenantId(req, tenantId) {
+        setContextField(req, 'tenantId', tenantId);
+    },
+    setTraceId(req, traceId) {
+        setContextField(req, 'traceId', traceId);
+    },
 });
 export default RequestContext;

package/src/http/Response.d.ts

@@ -2,7 +2,7 @@
  * Response - HTTP Response wrapper
  * Wraps Node.js ServerResponse with additional utilities
  */
-import * as http from '../node-singletons/http';
+import type * as http from '../node-singletons/http';
 export interface IResponse {
     status(code: number): IResponse;
     setStatus(code: number): IResponse;

package/src/http/Response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Response.d.ts","sourceRoot":"","sources":["../../../src/http/Response.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAE9C,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,SAAS,IAAI,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IAC7D,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IACvD,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjD,MAAM,IAAI,IAAI,CAAC,cAAc,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ;IACnB;;OAEG;gBACS,IAAI,CAAC,cAAc,GAAG,SAAS;EA0D3C,CAAC;AAEH,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"Response.d.ts","sourceRoot":"","sources":["../../../src/http/Response.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAEnD,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,SAAS,IAAI,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IAC7D,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IACvD,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjD,MAAM,IAAI,IAAI,CAAC,cAAc,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ;IACnB;;OAEG;gBACS,IAAI,CAAC,cAAc,GAAG,SAAS;EA0D3C,CAAC;AAEH,eAAe,QAAQ,CAAC"}

package/src/http/ValidationHelper.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Validation Helper
+ * Utilities for working with validated request data
+ */
+import type { IRequest } from './Request';
+/**
+ * Extract validated body from request
+ * Returns the validated body if present, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const body = getValidatedBody(req);
+ * if (!body) {
+ *   Logger.error('Validation middleware not configured');
+ *   return res.setStatus(500).json({ error: 'Internal server error' });
+ * }
+ * const email = getString(body['email']);
+ * ```
+ */
+export declare function getValidatedBody<T = Record<string, unknown>>(req: IRequest): T | undefined;
+/**
+ * Check if request has a validated body
+ * Type guard for validated body existence
+ *
+ * @example
+ * ```typescript
+ * if (!hasValidatedBody(req)) {
+ *   Logger.error('Validation middleware not configured');
+ *   return res.setStatus(500).json({ error: 'Internal server error' });
+ * }
+ * const body = getValidatedBody(req)!; // Safe to use non-null assertion
+ * ```
+ */
+export declare function hasValidatedBody(req: IRequest): boolean;
+/**
+ * Extract validated body or throw error
+ * Throws if validation middleware is not properly configured
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const body = requireValidatedBody(req);
+ *   const email = getString(body['email']);
+ * } catch (error) {
+ *   Logger.error('Validation middleware error', error);
+ *   return res.setStatus(500).json({ error: 'Internal server error' });
+ * }
+ * ```
+ */
+export declare function requireValidatedBody<T = Record<string, unknown>>(req: IRequest): T;
+/**
+ * Extract validated query parameters from request
+ * Returns the validated query if present, undefined otherwise
+ */
+export declare function getValidatedQuery<T = Record<string, unknown>>(req: IRequest): T | undefined;
+/**
+ * Extract validated route parameters from request
+ * Returns the validated params if present, undefined otherwise
+ */
+export declare function getValidatedParams<T = Record<string, unknown>>(req: IRequest): T | undefined;
+/**
+ * Extract validated headers from request
+ * Returns the validated headers if present, undefined otherwise
+ */
+export declare function getValidatedHeaders<T = Record<string, unknown>>(req: IRequest): T | undefined;
+/**
+ * Validation Helper - Sealed namespace
+ */
+export declare const ValidationHelper: Readonly<{
+    getValidatedBody: typeof getValidatedBody;
+    hasValidatedBody: typeof hasValidatedBody;
+    requireValidatedBody: typeof requireValidatedBody;
+    getValidatedQuery: typeof getValidatedQuery;
+    getValidatedParams: typeof getValidatedParams;
+    getValidatedHeaders: typeof getValidatedHeaders;
+}>;
+export default ValidationHelper;
+//# sourceMappingURL=ValidationHelper.d.ts.map

package/src/http/ValidationHelper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValidationHelper.d.ts","sourceRoot":"","sources":["../../../src/http/ValidationHelper.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAa9C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,GAAG,SAAS,CAK1F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAKvD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,CAQlF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,GAAG,SAAS,CAK3F;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,GAAG,SAAS,CAK5F;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,GAAG,SAAS,CAK7F;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;EAO3B,CAAC;AAEH,eAAe,gBAAgB,CAAC"}

package/src/http/ValidationHelper.js

@@ -0,0 +1,121 @@
+/**
+ * Validation Helper
+ * Utilities for working with validated request data
+ */
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+const getValidated = (req) => {
+    return req.validated;
+};
+/**
+ * Extract validated body from request
+ * Returns the validated body if present, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const body = getValidatedBody(req);
+ * if (!body) {
+ *   Logger.error('Validation middleware not configured');
+ *   return res.setStatus(500).json({ error: 'Internal server error' });
+ * }
+ * const email = getString(body['email']);
+ * ```
+ */
+export function getValidatedBody(req) {
+    const validated = getValidated(req);
+    if (validated === undefined)
+        return undefined;
+    if (validated.body === undefined)
+        return undefined;
+    return validated.body;
+}
+/**
+ * Check if request has a validated body
+ * Type guard for validated body existence
+ *
+ * @example
+ * ```typescript
+ * if (!hasValidatedBody(req)) {
+ *   Logger.error('Validation middleware not configured');
+ *   return res.setStatus(500).json({ error: 'Internal server error' });
+ * }
+ * const body = getValidatedBody(req)!; // Safe to use non-null assertion
+ * ```
+ */
+export function hasValidatedBody(req) {
+    const validated = getValidated(req);
+    if (validated === undefined)
+        return false;
+    if (validated.body === undefined)
+        return false;
+    return true;
+}
+/**
+ * Extract validated body or throw error
+ * Throws if validation middleware is not properly configured
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const body = requireValidatedBody(req);
+ *   const email = getString(body['email']);
+ * } catch (error) {
+ *   Logger.error('Validation middleware error', error);
+ *   return res.setStatus(500).json({ error: 'Internal server error' });
+ * }
+ * ```
+ */
+export function requireValidatedBody(req) {
+    const body = getValidatedBody(req);
+    if (body === undefined) {
+        throw ErrorFactory.createValidationError('Validation middleware did not populate req.validated.body');
+    }
+    return body;
+}
+/**
+ * Extract validated query parameters from request
+ * Returns the validated query if present, undefined otherwise
+ */
+export function getValidatedQuery(req) {
+    const validated = getValidated(req);
+    if (validated === undefined)
+        return undefined;
+    if (validated.query === undefined)
+        return undefined;
+    return validated.query;
+}
+/**
+ * Extract validated route parameters from request
+ * Returns the validated params if present, undefined otherwise
+ */
+export function getValidatedParams(req) {
+    const validated = getValidated(req);
+    if (validated === undefined)
+        return undefined;
+    if (validated.params === undefined)
+        return undefined;
+    return validated.params;
+}
+/**
+ * Extract validated headers from request
+ * Returns the validated headers if present, undefined otherwise
+ */
+export function getValidatedHeaders(req) {
+    const validated = getValidated(req);
+    if (validated === undefined)
+        return undefined;
+    if (validated.headers === undefined)
+        return undefined;
+    return validated.headers;
+}
+/**
+ * Validation Helper - Sealed namespace
+ */
+export const ValidationHelper = Object.freeze({
+    getValidatedBody,
+    hasValidatedBody,
+    requireValidatedBody,
+    getValidatedQuery,
+    getValidatedParams,
+    getValidatedHeaders,
+});
+export default ValidationHelper;

package/src/http/error-pages/ErrorPageRenderer.d.ts

@@ -0,0 +1,17 @@
+import type { IRequest } from '../Request';
+type RenderInput = {
+    statusCode: number;
+    errorName: string;
+    errorMessage: string;
+    requestPath: string;
+    stackPretty?: string;
+    stackRaw?: string;
+    requestPretty?: string;
+    requestRaw?: string;
+};
+export declare const ErrorPageRenderer: Readonly<{
+    shouldSendHtml(request: IRequest): boolean;
+    renderHtml(publicRoot: string, input: RenderInput): string | undefined;
+}>;
+export {};
+//# sourceMappingURL=ErrorPageRenderer.d.ts.map

package/src/http/error-pages/ErrorPageRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorPageRenderer.d.ts","sourceRoot":"","sources":["../../../../src/http/error-pages/ErrorPageRenderer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAM9C,KAAK,WAAW,GAAG;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AA2EF,eAAO,MAAM,iBAAiB;4BACJ,QAAQ,GAAG,OAAO;2BAInB,MAAM,SAAS,WAAW,GAAG,MAAM,GAAG,SAAS;EAUtE,CAAC"}

package/src/http/error-pages/ErrorPageRenderer.js

@@ -0,0 +1,88 @@
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import * as fs from '../../node-singletons/fs.js';
+import * as path from '../../node-singletons/path.js';
+const escapeHtml = (value) => {
+    return value
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;');
+};
+const getAcceptHeader = (request) => {
+    const accept = request.getHeader('accept');
+    if (typeof accept === 'string')
+        return accept;
+    if (Array.isArray(accept))
+        return accept.join(',');
+    return '';
+};
+const prefersHtml = (request) => {
+    if (request.getPath().startsWith('/api'))
+        return false;
+    const accept = getAcceptHeader(request).toLowerCase();
+    if (accept === '')
+        return false;
+    // Browser Accept values almost always include one of these.
+    return accept.includes('text/html') || accept.includes('application/xhtml+xml');
+};
+const prefersJson = (request) => {
+    if (request.getPath().startsWith('/api'))
+        return true;
+    const accept = getAcceptHeader(request).toLowerCase();
+    // If the client explicitly accepts HTML, treat it as an HTML preference.
+    if (accept.includes('text/html') || accept.includes('application/xhtml+xml'))
+        return false;
+    if (accept.includes('application/json'))
+        return true;
+    // Default to JSON when the client doesn't express a preference.
+    return accept === '' || accept.includes('*/*');
+};
+const interpolate = (template, data) => {
+    return template
+        .replaceAll('{{statusCode}}', escapeHtml(String(data.statusCode)))
+        .replaceAll('{{errorName}}', escapeHtml(data.errorName))
+        .replaceAll('{{errorMessage}}', escapeHtml(data.errorMessage))
+        .replaceAll('{{requestPath}}', escapeHtml(data.requestPath))
+        .replaceAll('{{stackPretty}}', escapeHtml(data.stackPretty ?? ''))
+        .replaceAll('{{stackRaw}}', escapeHtml(data.stackRaw ?? ''))
+        .replaceAll('{{requestPretty}}', escapeHtml(data.requestPretty ?? ''))
+        .replaceAll('{{requestRaw}}', escapeHtml(data.requestRaw ?? ''));
+};
+const resolveTemplatePath = (publicRoot, templateName) => {
+    return path.join(publicRoot, 'error-pages', `${templateName}.html`);
+};
+const safeReadTemplate = (filePath) => {
+    try {
+        if (!fs.existsSync(filePath))
+            return undefined;
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return typeof content === 'string' && content.length > 0 ? content : undefined;
+    }
+    catch (error) {
+        ErrorFactory.createTryCatchError(`Failed to read error page template: ${filePath}`, error);
+        return undefined;
+    }
+};
+const toTemplateName = (statusCode) => {
+    if (statusCode === 404)
+        return '404';
+    if (statusCode === 500)
+        return '500';
+    return undefined;
+};
+export const ErrorPageRenderer = Object.freeze({
+    shouldSendHtml(request) {
+        return prefersHtml(request) && !prefersJson(request);
+    },
+    renderHtml(publicRoot, input) {
+        const templateName = toTemplateName(input.statusCode);
+        if (templateName === undefined)
+            return undefined;
+        const templatePath = resolveTemplatePath(publicRoot, templateName);
+        const template = safeReadTemplate(templatePath);
+        if (template === undefined)
+            return undefined;
+        return interpolate(template, input);
+    },
+});

package/src/http/middleware/BodyParsingMiddleware.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Content Type Detection & Body Parsing Middleware
+ * Detects content-type and parses non-JSON request bodies
+ */
+import type { Middleware } from '../../middleware/MiddlewareStack';
+/**
+ * Body parsing middleware
+ * Automatically detects content-type and parses non-JSON bodies
+ */
+export declare const bodyParsingMiddleware: Middleware;
+export default bodyParsingMiddleware;
+//# sourceMappingURL=BodyParsingMiddleware.d.ts.map

package/src/http/middleware/BodyParsingMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BodyParsingMiddleware.d.ts","sourceRoot":"","sources":["../../../../src/http/middleware/BodyParsingMiddleware.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAqO9D;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,UAgDnC,CAAC;AAEF,eAAe,qBAAqB,CAAC"}