@zintrust/core 0.1.26 → 0.1.28

package/src/http/ValidationHelper.ts

@@ -0,0 +1,131 @@
+/**
+ * Validation Helper
+ * Utilities for working with validated request data
+ */
+
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import type { IRequest } from '@http/Request';
+
+type ValidatedShape = {
+  body?: unknown;
+  query?: unknown;
+  params?: unknown;
+  headers?: unknown;
+};
+
+const getValidated = (req: IRequest): ValidatedShape | undefined => {
+  return (req as unknown as { validated?: ValidatedShape }).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<T = Record<string, unknown>>(req: IRequest): T | undefined {
+  const validated = getValidated(req);
+  if (validated === undefined) return undefined;
+  if (validated.body === undefined) return undefined;
+  return validated.body as T;
+}
+
+/**
+ * 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: IRequest): boolean {
+  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<T = Record<string, unknown>>(req: IRequest): T {
+  const body = getValidatedBody<T>(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<T = Record<string, unknown>>(req: IRequest): T | undefined {
+  const validated = getValidated(req);
+  if (validated === undefined) return undefined;
+  if (validated.query === undefined) return undefined;
+  return validated.query as T;
+}
+
+/**
+ * Extract validated route parameters from request
+ * Returns the validated params if present, undefined otherwise
+ */
+export function getValidatedParams<T = Record<string, unknown>>(req: IRequest): T | undefined {
+  const validated = getValidated(req);
+  if (validated === undefined) return undefined;
+  if (validated.params === undefined) return undefined;
+  return validated.params as T;
+}
+
+/**
+ * Extract validated headers from request
+ * Returns the validated headers if present, undefined otherwise
+ */
+export function getValidatedHeaders<T = Record<string, unknown>>(req: IRequest): T | undefined {
+  const validated = getValidated(req);
+  if (validated === undefined) return undefined;
+  if (validated.headers === undefined) return undefined;
+  return validated.headers as T;
+}
+
+/**
+ * Validation Helper - Sealed namespace
+ */
+export const ValidationHelper = Object.freeze({
+  getValidatedBody,
+  hasValidatedBody,
+  requireValidatedBody,
+  getValidatedQuery,
+  getValidatedParams,
+  getValidatedHeaders,
+});
+
+export default ValidationHelper;

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

@@ -0,0 +1,108 @@
+import { MIME_TYPES } from '@/config/constants';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import type { IRequest } from '@http/Request';
+import * as fs from '@node-singletons/fs';
+import * as path from '@node-singletons/path';
+
+type ErrorTemplateName = '404' | '500';
+
+type RenderInput = {
+  statusCode: number;
+  errorName: string;
+  errorMessage: string;
+  requestPath: string;
+  stackPretty?: string;
+  stackRaw?: string;
+  requestPretty?: string;
+  requestRaw?: string;
+};
+
+const escapeHtml = (value: string): string => {
+  return value
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+};
+
+const getAcceptHeader = (request: IRequest): string => {
+  const accept = request.getHeader('accept');
+  if (typeof accept === 'string') return accept;
+  if (Array.isArray(accept)) return accept.join(',');
+  return '';
+};
+
+const prefersHtml = (request: IRequest): boolean => {
+  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(MIME_TYPES.HTML) || accept.includes(MIME_TYPES.XHTML);
+};
+
+const prefersJson = (request: IRequest): boolean => {
+  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(MIME_TYPES.TEXT) || accept.includes(MIME_TYPES.XHTML)) return false;
+
+  if (accept.includes(MIME_TYPES.JSON)) return true;
+
+  // Default to JSON when the client doesn't express a preference.
+  return accept === '' || accept.includes('*/*');
+};
+
+const interpolate = (template: string, data: RenderInput): string => {
+  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: string, templateName: ErrorTemplateName): string => {
+  return path.join(publicRoot, 'error-pages', `${templateName}.html`);
+};
+
+const safeReadTemplate = (filePath: string): string | undefined => {
+  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: number): ErrorTemplateName | undefined => {
+  if (statusCode === 404) return '404';
+  if (statusCode === 500) return '500';
+  return undefined;
+};
+
+export const ErrorPageRenderer = Object.freeze({
+  shouldSendHtml(request: IRequest): boolean {
+    return prefersHtml(request) && !prefersJson(request);
+  },
+
+  renderHtml(publicRoot: string, input: RenderInput): string | undefined {
+    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.ts

@@ -0,0 +1,294 @@
+/**
+ * Content Type Detection & Body Parsing Middleware
+ * Detects content-type and parses non-JSON request bodies
+ */
+
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+import type { IRequest } from '@http/Request';
+import type { IResponse } from '@http/Response';
+import { MultipartParser } from '@http/parsers/MultipartParser';
+import type { Middleware } from '@middleware/MiddlewareStack';
+
+type ReadBodyResult =
+  | { ok: true; bytes: Buffer; text: string }
+  | { ok: false; statusCode: 400 | 413; message: string };
+
+/**
+ * Get content-type from request headers
+ */
+const getContentType = (req: IRequest): string => {
+  const contentType = req.getHeader('content-type');
+  if (typeof contentType === 'string') return contentType.split(';')[0].toLowerCase().trim();
+  if (Array.isArray(contentType) && typeof contentType[0] === 'string') {
+    return contentType[0].split(';')[0].toLowerCase().trim();
+  }
+  return '';
+};
+
+const shouldReadRequestBody = (req: IRequest): boolean => {
+  const method = (req.getMethod?.() ?? 'GET').toUpperCase();
+  if (method === 'GET' || method === 'HEAD' || method === 'OPTIONS') return false;
+  return true;
+};
+
+const toBuffer = (chunk: unknown): Buffer => {
+  if (Buffer.isBuffer(chunk)) return chunk;
+  if (typeof chunk === 'string') return Buffer.from(chunk);
+  if (chunk instanceof Uint8Array) return Buffer.from(chunk);
+  if (chunk instanceof ArrayBuffer) return Buffer.from(new Uint8Array(chunk));
+  return Buffer.from(String(chunk));
+};
+
+const validateSize = (bytes: Buffer, maxBytes: number): ReadBodyResult | null => {
+  if (bytes.length > maxBytes) {
+    return { ok: false, statusCode: 413, message: 'Payload Too Large' };
+  }
+  return null;
+};
+
+const handleMockedStringBody = (body: string, maxBytes: number): ReadBodyResult | null => {
+  const bytes = Buffer.from(body);
+  const sizeError = validateSize(bytes, maxBytes);
+  if (sizeError) return sizeError;
+  return { ok: true, bytes, text: body };
+};
+
+const handleMockedBufferBody = (body: Buffer, maxBytes: number): ReadBodyResult | null => {
+  const sizeError = validateSize(body, maxBytes);
+  if (sizeError) return sizeError;
+  return { ok: true, bytes: body, text: body.toString('utf-8') };
+};
+
+const handleMockedObjectBody = (body: object, maxBytes: number): ReadBodyResult | null => {
+  try {
+    const text = JSON.stringify(body);
+    const bytes = Buffer.from(text, 'utf-8');
+    const sizeError = validateSize(bytes, maxBytes);
+    if (sizeError) return sizeError;
+    return { ok: true, bytes, text };
+  } catch {
+    return { ok: false, statusCode: 400, message: 'Invalid request body' };
+  }
+};
+
+const handleMockedBody = (mockedBody: unknown, maxBytes: number): ReadBodyResult | null => {
+  if (typeof mockedBody === 'string') {
+    return handleMockedStringBody(mockedBody, maxBytes);
+  }
+  if (Buffer.isBuffer(mockedBody)) {
+    return handleMockedBufferBody(mockedBody, maxBytes);
+  }
+  if (typeof mockedBody === 'object' && mockedBody !== null) {
+    return handleMockedObjectBody(mockedBody, maxBytes);
+  }
+  return null;
+};
+
+const readStreamBody = async (raw: unknown, maxBytes: number): Promise<ReadBodyResult> => {
+  const chunks: Buffer[] = [];
+  let totalSize = 0;
+
+  try {
+    for await (const chunk of raw as AsyncIterable<unknown>) {
+      const buf = toBuffer(chunk);
+      totalSize += buf.length;
+
+      if (totalSize > maxBytes) {
+        try {
+          (raw as { destroy?: () => void }).destroy?.();
+        } catch {
+          // best-effort
+        }
+        return { ok: false, statusCode: 413, message: 'Payload Too Large' };
+      }
+
+      chunks.push(buf);
+    }
+  } catch {
+    return { ok: false, statusCode: 400, message: 'Invalid request body' };
+  }
+
+  if (chunks.length === 0) return { ok: true, bytes: Buffer.from(''), text: '' };
+  const bytes = Buffer.concat(chunks);
+  return { ok: true, bytes, text: bytes.toString('utf-8') };
+};
+
+const readRawBody = async (req: IRequest, maxBytes: number): Promise<ReadBodyResult> => {
+  const raw = req.getRaw();
+
+  // Support tests/mocks that stuff a body directly on the raw request.
+  const mockedBody = (raw as unknown as { body?: unknown }).body;
+  const mockedResult = handleMockedBody(mockedBody, maxBytes);
+  if (mockedResult) {
+    return mockedResult;
+  }
+
+  // Read from actual stream
+  return readStreamBody(raw, maxBytes);
+};
+
+const convertExistingToRawResult = (
+  existingBytes: unknown,
+  existingText: unknown
+): ReadBodyResult => {
+  if (Buffer.isBuffer(existingBytes)) {
+    return { ok: true, bytes: existingBytes, text: existingBytes.toString('utf-8') };
+  }
+
+  if (typeof existingText === 'string') {
+    return { ok: true, bytes: Buffer.from(existingText, 'utf-8'), text: existingText };
+  }
+
+  // Should be unreachable (guarded by `hasExisting`), but keep a safe fallback.
+  return { ok: true, bytes: Buffer.from('', 'utf-8'), text: '' };
+};
+
+const parseJsonBody = (text: string, contentType: string, res: IResponse): unknown => {
+  try {
+    return text === '' ? null : (JSON.parse(text) as unknown);
+  } catch {
+    Logger.debug('[Body Parser] Invalid JSON body', {
+      contentType,
+      byteLength: Buffer.byteLength(text),
+      rawBodyPreview: text.slice(0, 256),
+    });
+    res.setStatus(400).json({ error: 'Invalid JSON body' });
+    return null;
+  }
+};
+
+const setRequestBody = (
+  req: IRequest,
+  rawResult: ReadBodyResult & { ok: true },
+  contentType: string
+): void => {
+  const isUrlEncoded = contentType.includes('application/x-www-form-urlencoded');
+  const isText = contentType.startsWith('text/') || contentType.includes('application/xml');
+
+  if (isUrlEncoded) {
+    req.setBody(parseUrlEncodedBody(rawResult.text));
+  } else if (isText) {
+    req.setBody(rawResult.text);
+  } else if (contentType !== '') {
+    req.setBody(rawResult.bytes);
+  }
+};
+
+const parseUrlEncodedBody = (text: string): Record<string, string | string[]> => {
+  const out: Record<string, string | string[]> = {};
+  const params = new URLSearchParams(text);
+  for (const [key, value] of params.entries()) {
+    const existing = out[key];
+    if (existing === undefined) {
+      out[key] = value;
+      continue;
+    }
+    if (Array.isArray(existing)) {
+      existing.push(value);
+      continue;
+    }
+    out[key] = [existing, value];
+  }
+  return out;
+};
+
+const processBodyParsing = async (
+  req: IRequest,
+  res: IResponse,
+  contentType: string,
+  maxBytes: number
+): Promise<boolean> => {
+  const rawResult: ReadBodyResult = await readRawBody(req, maxBytes);
+
+  if (rawResult.ok === false) {
+    res.setStatus(rawResult.statusCode).json({ error: rawResult.message });
+    return false;
+  }
+
+  // Store raw body for downstream consumers
+  req.context['rawBodyBytes'] = rawResult.bytes;
+  req.context['rawBodyText'] = rawResult.text;
+
+  // Parse and set body based on content type
+  try {
+    const isJson = contentType.includes('application/json');
+    if (isJson) {
+      const parsed = parseJsonBody(rawResult.text, contentType, res);
+      if (parsed === null && res.getStatus() === 400) {
+        return false; // JSON parsing failed, response already sent
+      }
+      req.setBody(parsed);
+    } else {
+      setRequestBody(req, rawResult, contentType);
+    }
+
+    if (Env.getBool('ZIN_DEBUG_BODY_PARSING', false)) {
+      Logger.debug('[Body Parser] Parsed request body', {
+        contentType,
+        byteLength: rawResult.bytes.length,
+        parsedType: typeof req.getBody?.(),
+      });
+    }
+  } catch (error) {
+    Logger.error('[Body Parser] Unexpected error during body parsing', error);
+  }
+
+  return true;
+};
+
+/**
+ * Body parsing middleware
+ * Automatically detects content-type and parses non-JSON bodies
+ */
+export const bodyParsingMiddleware: Middleware = async (
+  req: IRequest,
+  res: IResponse,
+  next: () => Promise<void>
+): Promise<void> => {
+  const contentType = getContentType(req);
+
+  // Early exit if body already set
+  const existingBody = req.getBody?.();
+  if (existingBody !== null && existingBody !== undefined) {
+    await next();
+    return;
+  }
+
+  // Early exit for multipart (handled by upload middleware)
+  if (MultipartParser.isMultipart(contentType)) {
+    await next();
+    return;
+  }
+
+  // Early exit for methods that don't have bodies
+  if (!shouldReadRequestBody(req)) {
+    await next();
+    return;
+  }
+
+  // Determine if we have existing raw body from adapter
+  const existingBytes = req.context['rawBodyBytes'];
+  const existingText = req.context['rawBodyText'];
+  const hasExisting = Buffer.isBuffer(existingBytes) || typeof existingText === 'string';
+
+  // Calculate size limit based on content type
+  const isJson = contentType.includes('application/json');
+  const maxJsonSize = Env.getInt('MAX_JSON_SIZE', 1024 * 1024);
+  const maxBytes = isJson ? maxJsonSize : Env.MAX_BODY_SIZE;
+
+  // Read or reuse raw body
+  if (hasExisting) {
+    const rawResult = convertExistingToRawResult(existingBytes, existingText);
+    if (rawResult.ok) {
+      req.context['rawBodyBytes'] = rawResult.bytes;
+      req.context['rawBodyText'] = rawResult.text;
+    }
+  } else {
+    await processBodyParsing(req, res, contentType, maxBytes);
+  }
+
+  await next();
+};
+
+export default bodyParsingMiddleware;

package/src/http/middleware/FileUploadMiddleware.ts

@@ -0,0 +1,91 @@
+/**
+ * File Upload Middleware
+ * Processes multipart/form-data requests and makes files available on request
+ */
+
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+import { MultipartParser } from '@http/parsers/MultipartParser';
+import { MultipartParserRegistry } from '@http/parsers/MultipartParserRegistry';
+import type { IRequest } from '@http/Request';
+import type { IResponse } from '@http/Response';
+import type { Middleware } from '@middleware/MiddlewareStack';
+
+/**
+ * Extract content-type header safely
+ */
+const getContentType = (req: IRequest): string => {
+  const contentType = req.getHeader('content-type');
+  if (typeof contentType === 'string') return contentType.toLowerCase().trim();
+  return '';
+};
+
+/**
+ * File upload middleware
+ * Automatically parses multipart/form-data and makes files available
+ */
+export const fileUploadMiddleware: Middleware = async (
+  req: IRequest,
+  res: IResponse,
+  next: () => Promise<void>
+): Promise<void> => {
+  const contentType = getContentType(req);
+
+  // Only process multipart/form-data requests
+  if (!MultipartParser.isMultipart(contentType)) {
+    await next();
+    return;
+  }
+
+  // Phase 4 default behavior: multipart requires external streaming parser.
+  const provider = MultipartParserRegistry.get();
+  if (provider === null) {
+    res.setStatus(415).json({
+      error: 'multipart/form-data not supported. Install @zintrust/storage to enable uploads.',
+    });
+    return;
+  }
+
+  try {
+    const maxFileSizeBytes = Env.getInt('MAX_FILE_SIZE', 50 * 1024 * 1024);
+    const maxFiles = Env.getInt('MAX_FILES', 20);
+    const maxFields = Env.getInt('MAX_FIELDS', 200);
+    const maxFieldSizeBytes = Env.getInt('MAX_FIELD_SIZE', 128 * 1024);
+
+    const parsed = await provider({
+      req: req.getRaw(),
+      contentType,
+      limits: {
+        maxFileSizeBytes,
+        maxFiles,
+        maxFields,
+        maxFieldSizeBytes,
+      },
+    });
+
+    const currentBody = req.getBody?.();
+    const updatedBody = typeof currentBody === 'object' && currentBody !== null ? currentBody : {};
+
+    // Merge fields directly into the request body for ergonomics.
+    // Files remain under __files for FileUpload helper compatibility.
+    req.setBody({
+      ...updatedBody,
+      ...parsed.fields,
+      __files: parsed.files,
+    });
+
+    if (Env.getBool('ZIN_DEBUG_FILE_UPLOAD', false)) {
+      Logger.debug('[File Upload] Successfully parsed multipart data', {
+        fieldsCount: Object.keys(parsed.fields).length,
+        filesCount: Object.keys(parsed.files).length,
+      });
+    }
+  } catch (error) {
+    Logger.error('[File Upload] Error parsing multipart data', error);
+    // Continue with unparsed body
+  }
+
+  await next();
+};
+
+export default fileUploadMiddleware;