@zintrust/core 0.1.28 → 0.1.30

package/src/http/ValidationHelper.ts

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

@@ -1,108 +0,0 @@
-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

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

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