@doclo/core 0.1.5

package/dist/runtime/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/runtime/crypto.ts"],"sourcesContent":["/**\n * Universal Crypto Adapter\n *\n * Provides crypto-secure random byte generation for both Node.js and Edge Runtime.\n * Uses Web Crypto API (available in both environments) for maximum compatibility.\n *\n * @module @doclo/core/runtime/crypto\n */\n\n/**\n * Generate crypto-secure random bytes\n *\n * Uses Web Crypto API which is available in:\n * - Node.js 18+ (globalThis.crypto)\n * - Browsers (window.crypto)\n * - Cloudflare Workers (crypto)\n * - Vercel Edge Functions (crypto)\n *\n * @param length - Number of random bytes to generate\n * @returns Uint8Array containing random bytes\n */\nexport function getRandomBytes(length: number): Uint8Array {\n  const bytes = new Uint8Array(length);\n\n  // Use Web Crypto API (available in all supported runtimes)\n  // Node.js 18+, Edge Runtime, and browsers all support globalThis.crypto\n  if (typeof globalThis !== 'undefined' && globalThis.crypto?.getRandomValues) {\n    globalThis.crypto.getRandomValues(bytes);\n    return bytes;\n  }\n\n  throw new Error(\n    'Web Crypto API not available. This SDK requires:\\n' +\n    '- Node.js 18.0.0 or later (has globalThis.crypto)\\n' +\n    '- Edge Runtime (Vercel, Cloudflare)\\n' +\n    '- Modern browsers'\n  );\n}\n\n/**\n * Convert Uint8Array to lowercase hex string\n *\n * @param bytes - Byte array to convert\n * @returns Hex string representation\n */\nexport function bytesToHex(bytes: Uint8Array): string {\n  return Array.from(bytes)\n    .map(b => b.toString(16).padStart(2, '0'))\n    .join('');\n}\n\n/**\n * Generate random hex string of specified byte length\n *\n * @param byteLength - Number of random bytes (hex string will be 2x this length)\n * @returns Lowercase hex string\n *\n * @example\n * ```typescript\n * const traceId = randomHex(16); // 32 hex characters\n * const spanId = randomHex(8);   // 16 hex characters\n * ```\n */\nexport function randomHex(byteLength: number): string {\n  const bytes = getRandomBytes(byteLength);\n  return bytesToHex(bytes);\n}\n\n/**\n * Generate a UUID v4 string\n *\n * Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx\n *\n * @returns UUID v4 string\n *\n * @example\n * ```typescript\n * const id = randomUUID(); // \"550e8400-e29b-41d4-a716-446655440000\"\n * ```\n */\nexport function randomUUID(): string {\n  // Try native crypto.randomUUID() first (Node 19+, all Edge runtimes)\n  if (typeof globalThis !== 'undefined' && globalThis.crypto?.randomUUID) {\n    return globalThis.crypto.randomUUID();\n  }\n\n  // Fallback: Manual UUID v4 generation\n  const bytes = getRandomBytes(16);\n\n  // Set version (4) and variant bits for UUID v4\n  bytes[6] = (bytes[6] & 0x0f) | 0x40; // Version 4\n  bytes[8] = (bytes[8] & 0x3f) | 0x80; // Variant 10\n\n  // Format as UUID string\n  const hex = bytesToHex(bytes);\n  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;\n}\n"],"mappings":";AAqBO,SAAS,eAAe,QAA4B;AACzD,QAAM,QAAQ,IAAI,WAAW,MAAM;AAInC,MAAI,OAAO,eAAe,eAAe,WAAW,QAAQ,iBAAiB;AAC3E,eAAW,OAAO,gBAAgB,KAAK;AACvC,WAAO;AAAA,EACT;AAEA,QAAM,IAAI;AAAA,IACR;AAAA,EAIF;AACF;AAQO,SAAS,WAAW,OAA2B;AACpD,SAAO,MAAM,KAAK,KAAK,EACpB,IAAI,OAAK,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC,EACxC,KAAK,EAAE;AACZ;AAcO,SAAS,UAAU,YAA4B;AACpD,QAAM,QAAQ,eAAe,UAAU;AACvC,SAAO,WAAW,KAAK;AACzB;AAcO,SAAS,aAAqB;AAEnC,MAAI,OAAO,eAAe,eAAe,WAAW,QAAQ,YAAY;AACtE,WAAO,WAAW,OAAO,WAAW;AAAA,EACtC;AAGA,QAAM,QAAQ,eAAe,EAAE;AAG/B,QAAM,CAAC,IAAK,MAAM,CAAC,IAAI,KAAQ;AAC/B,QAAM,CAAC,IAAK,MAAM,CAAC,IAAI,KAAQ;AAG/B,QAAM,MAAM,WAAW,KAAK;AAC5B,SAAO,GAAG,IAAI,MAAM,GAAG,CAAC,CAAC,IAAI,IAAI,MAAM,GAAG,EAAE,CAAC,IAAI,IAAI,MAAM,IAAI,EAAE,CAAC,IAAI,IAAI,MAAM,IAAI,EAAE,CAAC,IAAI,IAAI,MAAM,IAAI,EAAE,CAAC;AAC9G;","names":[]}

package/dist/runtime/env.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Universal Environment Configuration
+ *
+ * Provides environment variable access for both Node.js and Edge Runtime.
+ * Supports multiple patterns:
+ * - Node.js: process.env
+ * - Vercel Edge Functions: process.env (available)
+ * - Cloudflare Workers: env bindings (passed as config)
+ *
+ * @module @doclo/core/runtime/env
+ */
+/**
+ * Runtime environment configuration
+ *
+ * Can be set explicitly or will fall back to process.env when available.
+ */
+interface RuntimeEnv {
+    /**
+     * Node environment (development, production, test)
+     */
+    NODE_ENV?: string;
+    /**
+     * Debug flag for validation messages
+     */
+    DEBUG_VALIDATION?: string;
+    /**
+     * Skip flow validation (use with caution!)
+     */
+    DOCLO_SKIP_VALIDATION?: string;
+    /**
+     * Endpoint for security event logging
+     */
+    SECURITY_LOG_ENDPOINT?: string;
+    /**
+     * Additional environment variables
+     */
+    [key: string]: string | undefined;
+}
+/**
+ * Set global runtime environment configuration
+ *
+ * Use this to configure environment variables in Edge Runtime environments
+ * where process.env is not available (like Cloudflare Workers).
+ *
+ * @param env - Environment configuration object
+ */
+declare function setRuntimeEnv(env: RuntimeEnv): void;
+/**
+ * Get global runtime environment configuration
+ *
+ * @returns Current runtime environment config or null
+ */
+declare function getRuntimeEnv(): RuntimeEnv | null;
+/**
+ * Clear global runtime environment configuration (for testing)
+ */
+declare function clearRuntimeEnv(): void;
+/**
+ * Get environment variable value
+ *
+ * Priority:
+ * 1. Explicitly set runtime env (via setRuntimeEnv)
+ * 2. process.env (Node.js, Vercel Edge)
+ * 3. undefined
+ *
+ * @param key - Environment variable name
+ * @param defaultValue - Optional default value if not found
+ * @returns Environment variable value or undefined
+ *
+ * @example
+ * ```typescript
+ * const nodeEnv = getEnv('NODE_ENV', 'development');
+ * const isProduction = nodeEnv === 'production';
+ *
+ * const skipValidation = getEnv('DOCLO_SKIP_VALIDATION') === 'true';
+ * ```
+ */
+declare function getEnv(key: string, defaultValue?: string): string | undefined;
+/**
+ * Check if running in production mode
+ *
+ * @returns True if NODE_ENV is 'production'
+ */
+declare function isProduction(): boolean;
+/**
+ * Check if running in development mode
+ *
+ * @returns True if NODE_ENV is 'development'
+ */
+declare function isDevelopment(): boolean;
+/**
+ * Check if running in test mode
+ *
+ * @returns True if NODE_ENV is 'test'
+ */
+declare function isTest(): boolean;
+/**
+ * Check if debug validation is enabled
+ *
+ * @returns True if DEBUG_VALIDATION is set to any truthy value
+ */
+declare function isDebugValidation(): boolean;
+/**
+ * Check if validation should be skipped
+ *
+ * CAUTION: Only use in trusted environments!
+ *
+ * @returns True if DOCLO_SKIP_VALIDATION is 'true'
+ */
+declare function shouldSkipValidation(): boolean;
+/**
+ * Detect current runtime environment
+ *
+ * @returns Runtime type: 'node', 'edge-vercel', 'workerd' (Cloudflare), 'browser', or 'unknown'
+ */
+declare function detectRuntime(): 'node' | 'edge-vercel' | 'workerd' | 'browser' | 'unknown';
+/**
+ * Check if running in an Edge Runtime environment
+ *
+ * @returns True if running in Vercel Edge or Cloudflare Workers
+ */
+declare function isEdgeRuntime(): boolean;
+/**
+ * Check if running in Node.js
+ *
+ * @returns True if running in Node.js
+ */
+declare function isNodeRuntime(): boolean;
+
+export { type RuntimeEnv, clearRuntimeEnv, detectRuntime, getEnv, getRuntimeEnv, isDebugValidation, isDevelopment, isEdgeRuntime, isNodeRuntime, isProduction, isTest, setRuntimeEnv, shouldSkipValidation };

package/dist/runtime/env.js

@@ -0,0 +1,76 @@
+// src/runtime/env.ts
+var globalRuntimeEnv = null;
+function setRuntimeEnv(env) {
+  globalRuntimeEnv = env;
+}
+function getRuntimeEnv() {
+  return globalRuntimeEnv;
+}
+function clearRuntimeEnv() {
+  globalRuntimeEnv = null;
+}
+function getEnv(key, defaultValue) {
+  if (globalRuntimeEnv && key in globalRuntimeEnv) {
+    return globalRuntimeEnv[key];
+  }
+  if (typeof process !== "undefined" && process.env) {
+    const value = process.env[key];
+    if (value !== void 0) {
+      return value;
+    }
+  }
+  return defaultValue;
+}
+function isProduction() {
+  return getEnv("NODE_ENV") === "production";
+}
+function isDevelopment() {
+  return getEnv("NODE_ENV") === "development";
+}
+function isTest() {
+  return getEnv("NODE_ENV") === "test";
+}
+function isDebugValidation() {
+  const debug = getEnv("DEBUG_VALIDATION");
+  return Boolean(debug && debug !== "0" && debug !== "false");
+}
+function shouldSkipValidation() {
+  return getEnv("DOCLO_SKIP_VALIDATION") === "true";
+}
+function detectRuntime() {
+  if (typeof navigator !== "undefined" && navigator.userAgent === "Cloudflare-Workers") {
+    return "workerd";
+  }
+  if (typeof globalThis !== "undefined" && "EdgeRuntime" in globalThis) {
+    return "edge-vercel";
+  }
+  if (typeof process !== "undefined" && process.versions?.node) {
+    return "node";
+  }
+  if (typeof window !== "undefined" && typeof document !== "undefined") {
+    return "browser";
+  }
+  return "unknown";
+}
+function isEdgeRuntime() {
+  const runtime = detectRuntime();
+  return runtime === "edge-vercel" || runtime === "workerd";
+}
+function isNodeRuntime() {
+  return detectRuntime() === "node";
+}
+export {
+  clearRuntimeEnv,
+  detectRuntime,
+  getEnv,
+  getRuntimeEnv,
+  isDebugValidation,
+  isDevelopment,
+  isEdgeRuntime,
+  isNodeRuntime,
+  isProduction,
+  isTest,
+  setRuntimeEnv,
+  shouldSkipValidation
+};
+//# sourceMappingURL=env.js.map

package/dist/runtime/env.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/runtime/env.ts"],"sourcesContent":["/**\n * Universal Environment Configuration\n *\n * Provides environment variable access for both Node.js and Edge Runtime.\n * Supports multiple patterns:\n * - Node.js: process.env\n * - Vercel Edge Functions: process.env (available)\n * - Cloudflare Workers: env bindings (passed as config)\n *\n * @module @doclo/core/runtime/env\n */\n\n/**\n * Runtime environment configuration\n *\n * Can be set explicitly or will fall back to process.env when available.\n */\nexport interface RuntimeEnv {\n  /**\n   * Node environment (development, production, test)\n   */\n  NODE_ENV?: string;\n\n  /**\n   * Debug flag for validation messages\n   */\n  DEBUG_VALIDATION?: string;\n\n  /**\n   * Skip flow validation (use with caution!)\n   */\n  DOCLO_SKIP_VALIDATION?: string;\n\n  /**\n   * Endpoint for security event logging\n   */\n  SECURITY_LOG_ENDPOINT?: string;\n\n  /**\n   * Additional environment variables\n   */\n  [key: string]: string | undefined;\n}\n\n/**\n * Global runtime environment configuration\n *\n * Set this at application startup to configure environment for Edge Runtime.\n * Falls back to process.env when not set.\n *\n * @example\n * ```typescript\n * // Cloudflare Workers\n * export default {\n *   async fetch(request: Request, env: Env) {\n *     setRuntimeEnv(env);\n *     // ... use SDK\n *   }\n * }\n *\n * // Vercel Edge Functions (process.env works, but can override)\n * setRuntimeEnv({ NODE_ENV: 'production' });\n * ```\n */\nlet globalRuntimeEnv: RuntimeEnv | null = null;\n\n/**\n * Set global runtime environment configuration\n *\n * Use this to configure environment variables in Edge Runtime environments\n * where process.env is not available (like Cloudflare Workers).\n *\n * @param env - Environment configuration object\n */\nexport function setRuntimeEnv(env: RuntimeEnv): void {\n  globalRuntimeEnv = env;\n}\n\n/**\n * Get global runtime environment configuration\n *\n * @returns Current runtime environment config or null\n */\nexport function getRuntimeEnv(): RuntimeEnv | null {\n  return globalRuntimeEnv;\n}\n\n/**\n * Clear global runtime environment configuration (for testing)\n */\nexport function clearRuntimeEnv(): void {\n  globalRuntimeEnv = null;\n}\n\n/**\n * Get environment variable value\n *\n * Priority:\n * 1. Explicitly set runtime env (via setRuntimeEnv)\n * 2. process.env (Node.js, Vercel Edge)\n * 3. undefined\n *\n * @param key - Environment variable name\n * @param defaultValue - Optional default value if not found\n * @returns Environment variable value or undefined\n *\n * @example\n * ```typescript\n * const nodeEnv = getEnv('NODE_ENV', 'development');\n * const isProduction = nodeEnv === 'production';\n *\n * const skipValidation = getEnv('DOCLO_SKIP_VALIDATION') === 'true';\n * ```\n */\nexport function getEnv(key: string, defaultValue?: string): string | undefined {\n  // 1. Check explicitly set runtime env\n  if (globalRuntimeEnv && key in globalRuntimeEnv) {\n    return globalRuntimeEnv[key];\n  }\n\n  // 2. Check process.env (Node.js, Vercel Edge)\n  if (typeof process !== 'undefined' && process.env) {\n    const value = process.env[key];\n    if (value !== undefined) {\n      return value;\n    }\n  }\n\n  // 3. Return default value\n  return defaultValue;\n}\n\n/**\n * Check if running in production mode\n *\n * @returns True if NODE_ENV is 'production'\n */\nexport function isProduction(): boolean {\n  return getEnv('NODE_ENV') === 'production';\n}\n\n/**\n * Check if running in development mode\n *\n * @returns True if NODE_ENV is 'development'\n */\nexport function isDevelopment(): boolean {\n  return getEnv('NODE_ENV') === 'development';\n}\n\n/**\n * Check if running in test mode\n *\n * @returns True if NODE_ENV is 'test'\n */\nexport function isTest(): boolean {\n  return getEnv('NODE_ENV') === 'test';\n}\n\n/**\n * Check if debug validation is enabled\n *\n * @returns True if DEBUG_VALIDATION is set to any truthy value\n */\nexport function isDebugValidation(): boolean {\n  const debug = getEnv('DEBUG_VALIDATION');\n  return Boolean(debug && debug !== '0' && debug !== 'false');\n}\n\n/**\n * Check if validation should be skipped\n *\n * CAUTION: Only use in trusted environments!\n *\n * @returns True if DOCLO_SKIP_VALIDATION is 'true'\n */\nexport function shouldSkipValidation(): boolean {\n  return getEnv('DOCLO_SKIP_VALIDATION') === 'true';\n}\n\n/**\n * Detect current runtime environment\n *\n * @returns Runtime type: 'node', 'edge-vercel', 'workerd' (Cloudflare), 'browser', or 'unknown'\n */\nexport function detectRuntime(): 'node' | 'edge-vercel' | 'workerd' | 'browser' | 'unknown' {\n  // Check for Cloudflare Workers\n  if (typeof navigator !== 'undefined' && navigator.userAgent === 'Cloudflare-Workers') {\n    return 'workerd';\n  }\n\n  // Check for Vercel Edge Functions\n  if (typeof globalThis !== 'undefined' && 'EdgeRuntime' in globalThis) {\n    return 'edge-vercel';\n  }\n\n  // Check for Node.js\n  if (typeof process !== 'undefined' && process.versions?.node) {\n    return 'node';\n  }\n\n  // Check for browser\n  if (typeof window !== 'undefined' && typeof document !== 'undefined') {\n    return 'browser';\n  }\n\n  return 'unknown';\n}\n\n/**\n * Check if running in an Edge Runtime environment\n *\n * @returns True if running in Vercel Edge or Cloudflare Workers\n */\nexport function isEdgeRuntime(): boolean {\n  const runtime = detectRuntime();\n  return runtime === 'edge-vercel' || runtime === 'workerd';\n}\n\n/**\n * Check if running in Node.js\n *\n * @returns True if running in Node.js\n */\nexport function isNodeRuntime(): boolean {\n  return detectRuntime() === 'node';\n}\n"],"mappings":";AAgEA,IAAI,mBAAsC;AAUnC,SAAS,cAAc,KAAuB;AACnD,qBAAmB;AACrB;AAOO,SAAS,gBAAmC;AACjD,SAAO;AACT;AAKO,SAAS,kBAAwB;AACtC,qBAAmB;AACrB;AAsBO,SAAS,OAAO,KAAa,cAA2C;AAE7E,MAAI,oBAAoB,OAAO,kBAAkB;AAC/C,WAAO,iBAAiB,GAAG;AAAA,EAC7B;AAGA,MAAI,OAAO,YAAY,eAAe,QAAQ,KAAK;AACjD,UAAM,QAAQ,QAAQ,IAAI,GAAG;AAC7B,QAAI,UAAU,QAAW;AACvB,aAAO;AAAA,IACT;AAAA,EACF;AAGA,SAAO;AACT;AAOO,SAAS,eAAwB;AACtC,SAAO,OAAO,UAAU,MAAM;AAChC;AAOO,SAAS,gBAAyB;AACvC,SAAO,OAAO,UAAU,MAAM;AAChC;AAOO,SAAS,SAAkB;AAChC,SAAO,OAAO,UAAU,MAAM;AAChC;AAOO,SAAS,oBAA6B;AAC3C,QAAM,QAAQ,OAAO,kBAAkB;AACvC,SAAO,QAAQ,SAAS,UAAU,OAAO,UAAU,OAAO;AAC5D;AASO,SAAS,uBAAgC;AAC9C,SAAO,OAAO,uBAAuB,MAAM;AAC7C;AAOO,SAAS,gBAA4E;AAE1F,MAAI,OAAO,cAAc,eAAe,UAAU,cAAc,sBAAsB;AACpF,WAAO;AAAA,EACT;AAGA,MAAI,OAAO,eAAe,eAAe,iBAAiB,YAAY;AACpE,WAAO;AAAA,EACT;AAGA,MAAI,OAAO,YAAY,eAAe,QAAQ,UAAU,MAAM;AAC5D,WAAO;AAAA,EACT;AAGA,MAAI,OAAO,WAAW,eAAe,OAAO,aAAa,aAAa;AACpE,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAOO,SAAS,gBAAyB;AACvC,QAAM,UAAU,cAAc;AAC9B,SAAO,YAAY,iBAAiB,YAAY;AAClD;AAOO,SAAS,gBAAyB;AACvC,SAAO,cAAc,MAAM;AAC7B;","names":[]}

package/dist/security/index.d.ts

@@ -0,0 +1,236 @@
+/**
+ * URL Validation and SSRF Protection
+ *
+ * ⚠️ SECURITY CRITICAL: SSRF (Server-Side Request Forgery) Prevention
+ *
+ * This module blocks URLs that could be used in Server-Side Request Forgery attacks:
+ * - Internal IP addresses (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
+ * - Loopback addresses (127.0.0.0/8, ::1)
+ * - Cloud metadata services (AWS, GCP, Aliyun, etc.)
+ * - Link-local addresses (169.254.0.0/16)
+ *
+ * Attack example: An attacker tricks your server to make requests to:
+ * - http://169.254.169.254 (AWS credentials endpoint)
+ * - http://10.0.0.1:8080/admin (internal service)
+ * - http://localhost/api/admin (localhost admin endpoint)
+ *
+ * Prevents Server-Side Request Forgery attacks by validating URLs against blocklist
+ */
+/**
+ * Validate a URL to prevent SSRF (Server-Side Request Forgery) attacks
+ *
+ * ⚠️ SECURITY CRITICAL: SSRF Prevention
+ *
+ * This function blocks URLs that could be used to exploit the server:
+ * - Internal IP addresses (breaks firewall perimeter security)
+ * - Cloud metadata services (leaks credentials, API keys)
+ * - Localhost/loopback (access admin services, debug ports)
+ *
+ * By default, blocks internal network access automatically.
+ *
+ * @param urlString - The URL to validate
+ * @param options - Validation options
+ *   - blockInternal (default: true) - Block internal IP ranges. ⚠️ Set to false only if you understand SSRF risks
+ *   - allowedProtocols (default: ['http:', 'https:']) - Restrict to specific protocols
+ * @throws Error if URL is invalid, uses blocked protocol, or points to blocked IP/host
+ * @returns The validated URL object
+ * @security Always validate user-provided URLs. Do not set blockInternal to false without SSRF security review
+ *
+ * @example
+ * ```typescript
+ * // Validate user-provided URL
+ * try {
+ *   const url = validateUrl(userInput);
+ *   const response = await fetch(url.toString());
+ * } catch (error) {
+ *   // URL was malicious or pointed to internal resource
+ * }
+ * ```
+ */
+declare function validateUrl(urlString: string, options?: {
+    blockInternal?: boolean;
+    allowedProtocols?: string[];
+}): URL;
+/**
+ * Fetch a URL with SSRF protection and timeout
+ * @param url - The URL to fetch
+ * @param timeoutMs - Request timeout in milliseconds (default 30s)
+ * @throws Error if URL is invalid, blocked, or request times out
+ */
+declare function secureFetch(url: string, timeoutMs?: number): Promise<Response>;
+/**
+ * Extract hostname from URL string for validation
+ * Useful for pre-validation checks before full URL parsing
+ */
+declare function getHostnameFromUrl(urlString: string): string;
+
+/**
+ * Path Validation and Path Traversal Prevention
+ * Prevents attackers from accessing arbitrary files through path traversal
+ */
+/**
+ * Validate and normalize a file path to prevent traversal attacks
+ * @param filePath - The file path to validate
+ * @param basePath - The base directory that paths must be within
+ * @throws Error if path attempts to traverse outside basePath
+ * @returns The normalized safe path
+ */
+declare function validatePath(filePath: string, basePath: string): string;
+/**
+ * Validate a path without a required base path (more permissive)
+ * Still prevents obvious traversal attempts
+ * @param filePath - The file path to validate
+ * @throws Error if path contains suspicious traversal patterns
+ * @returns The normalized path
+ */
+declare function validatePathSimple(filePath: string): string;
+/**
+ * Check if a path would be safe to access
+ * @param filePath - The file path to check
+ * @param basePath - Optional base path restriction
+ * @returns true if path is safe, false otherwise
+ */
+declare function isPathSafe(filePath: string, basePath?: string): boolean;
+/**
+ * Get the absolute path with validation
+ * @param filePath - The file path
+ * @param basePath - Optional base directory
+ * @returns Absolute path if valid
+ * @throws Error if path is invalid
+ */
+declare function getSafePath(filePath: string, basePath?: string): string;
+
+/**
+ * Resource Limits and DoS Protection
+ *
+ * ⚠️ SECURITY WARNING: Resource limits are critical for protecting against:
+ * - Resource exhaustion attacks (large file downloads)
+ * - Denial of Service (slow loris, timeout attacks)
+ * - Memory exhaustion (deeply nested JSON, large arrays)
+ *
+ * Prevents resource exhaustion attacks through file size limits and timeouts
+ */
+/**
+ * Default resource limits
+ *
+ * ⚠️ SECURITY CRITICAL: These are conservative defaults designed to prevent DoS attacks.
+ *
+ * - MAX_FILE_SIZE (100MB): Prevents downloading very large files that could exhaust memory or disk
+ * - REQUEST_TIMEOUT (30s): Prevents slow-loris attacks and hung connections
+ * - MAX_JSON_DEPTH (100): Prevents billion laughs attack (deeply nested JSON)
+ *
+ * Do not increase these limits without understanding the security implications:
+ * - Higher file size limit → Greater risk of resource exhaustion
+ * - Lower timeout → May reject legitimate slow requests
+ * - Lower JSON depth → May reject valid documents
+ *
+ * @security These limits can be overridden by SDK users, but doing so reduces security.
+ */
+declare const DEFAULT_LIMITS: {
+    MAX_FILE_SIZE: number;
+    REQUEST_TIMEOUT: number;
+    MAX_JSON_DEPTH: number;
+};
+/**
+ * Validate file size before processing
+ *
+ * ⚠️ SECURITY WARNING: File size validation prevents resource exhaustion.
+ * - Without limits: attackers can force downloads of multi-gigabyte files
+ * - Memory impact: files are loaded into memory for base64 encoding
+ * - Disk impact: temporary storage of downloaded files
+ *
+ * @param size - The file size in bytes
+ * @param maxSize - Maximum allowed size in bytes (default 100MB, can be customized)
+ * @throws Error if file exceeds size limit
+ * @security Do not disable this check without understanding resource implications
+ *
+ * @example
+ * ```typescript
+ * // Standard check with default limit (100MB)
+ * validateFileSize(fileSize);
+ *
+ * // Custom limit for use case that requires larger files
+ * validateFileSize(fileSize, 500 * 1024 * 1024); // 500MB
+ * ```
+ */
+declare function validateFileSize(size: number, maxSize?: number): void;
+/**
+ * Create a fetch controller with timeout
+ * @param timeoutMs - Timeout in milliseconds (default 30s)
+ * @returns AbortController with timeout configured
+ */
+declare function createFetchController(timeoutMs?: number): AbortController;
+/**
+ * Clean up fetch controller timeout
+ * @param controller - The AbortController to clean up
+ */
+declare function cleanupFetchController(controller: AbortController): void;
+/**
+ * Execute a fetch with automatic timeout and cleanup
+ *
+ * ⚠️ SECURITY WARNING: Timeout protection prevents slow-loris and other timing attacks.
+ * - Without timeout: requests can hang indefinitely, consuming server resources
+ * - Slow-loris attack: attacker sends requests slowly to exhaust connection pool
+ * - Zombie connections: closed clients but open server connections
+ *
+ * Default timeout (30s) balances security with legitimate use:
+ * - Too short: may reject slow networks or legitimate large downloads
+ * - Too long: keeps server resources tied up, enables DoS attacks
+ *
+ * @param url - The URL to fetch
+ * @param options - Fetch options (method, headers, body, etc.)
+ * @param timeoutMs - Timeout in milliseconds (default 30s, can be customized)
+ * @returns The fetch response
+ * @throws Error if request times out
+ * @security Do not use very long timeouts without understanding DoS implications
+ *
+ * @example
+ * ```typescript
+ * // Default timeout (30 seconds)
+ * const response = await fetchWithTimeout('https://example.com/file.pdf');
+ *
+ * // Custom timeout for slower connections
+ * const response = await fetchWithTimeout(url, options, 60000); // 60 seconds
+ * ```
+ */
+declare function fetchWithTimeout(url: string, options?: RequestInit, timeoutMs?: number): Promise<Response>;
+/**
+ * Check buffer size before allocation
+ * @param size - The buffer size in bytes
+ * @param maxSize - Maximum allowed size (default 100MB)
+ * @throws Error if buffer would exceed memory limit
+ */
+declare function validateBufferSize(size: number, maxSize?: number): void;
+/**
+ * Memory-safe JSON parse with depth limit
+ *
+ * ⚠️ SECURITY WARNING: Depth limits prevent billion laughs / XML bomb attacks in JSON format.
+ * - Billion laughs attack: deeply nested JSON causes exponential memory expansion
+ * - Stack overflow: deeply nested structures can exhaust call stack
+ * - Resource exhaustion: parsing deeply nested JSON consumes CPU and memory
+ *
+ * Attack example (evil.json):
+ * ```json
+ * {"a":{"b":{"c":{"d":{"e":...}}}}} // 1000+ levels deep
+ * ```
+ *
+ * Default limit (100 levels) prevents attacks while allowing legitimate documents.
+ *
+ * @param text - JSON string to parse
+ * @param maxDepth - Maximum nesting depth in levels (default 100, can be customized)
+ * @returns Parsed object
+ * @throws Error if JSON exceeds depth limit, size limit, or is invalid
+ * @security Do not disable depth checking without understanding XML bomb implications
+ *
+ * @example
+ * ```typescript
+ * // Standard parsing with default depth limit (100 levels)
+ * const data = safeJsonParse(jsonString);
+ *
+ * // Custom depth limit for data that needs deeper nesting
+ * const data = safeJsonParse(jsonString, 200); // 200 levels
+ * ```
+ */
+declare function safeJsonParse(text: string, maxDepth?: number): unknown;
+
+export { DEFAULT_LIMITS, cleanupFetchController, createFetchController, fetchWithTimeout, getHostnameFromUrl, getSafePath, isPathSafe, safeJsonParse, secureFetch, validateBufferSize, validateFileSize, validatePath, validatePathSimple, validateUrl };