/**
 * Safe JSON Parser
 *
 * Provides secure JSON parsing with prototype pollution protection,
 * schema validation, depth limits, and size limits.
 *
 * Security features:
 * - Removes __proto__, constructor, and prototype properties
 * - Validates against Zod schemas
 * - Limits object nesting depth to prevent stack overflow
 * - Limits JSON size to prevent memory exhaustion
 * - Uses Object.create(null) for prototype-free objects where appropriate
 *
 * @packageDocumentation
 */
import { z, ZodSchema } from "zod";
/**
 * Options for safe JSON parsing
 */
export interface SafeParseOptions<T = unknown> {
    /**
     * Zod schema to validate the parsed JSON against.
     * If provided, the parsed result will be validated and typed according to the schema.
     */
    schema?: ZodSchema<T>;
    /**
     * Maximum nesting depth allowed for the parsed object.
     * Prevents stack overflow attacks from deeply nested structures.
     * @default 20
     */
    maxDepth?: number;
    /**
     * Maximum size in bytes for the JSON string.
     * Prevents memory exhaustion from extremely large payloads.
     * @default 10485760 (10MB)
     */
    maxSize?: number;
    /**
     * Whether to strip dangerous prototype properties from the parsed object.
     * This includes __proto__, constructor, and prototype.
     * @default true
     */
    stripPrototype?: boolean;
    /**
     * Whether to use Object.create(null) for the resulting object.
     * This creates an object with no prototype, providing additional protection.
     * Only applies to the top-level object and its nested objects.
     * @default false
     */
    useNullPrototype?: boolean;
}
/**
 * Result of a safe parse operation
 */
export interface SafeParseResult<T> {
    /** Whether the parse was successful */
    success: boolean;
    /** The parsed and validated data (only present if success is true) */
    data?: T;
    /** The error that occurred (only present if success is false) */
    error?: SafeJsonError;
}
/**
 * Error codes for safe JSON operations
 */
export declare enum SafeJsonErrorCode {
    /** JSON syntax is invalid */
    INVALID_JSON = "INVALID_JSON",
    /** JSON exceeds maximum size limit */
    SIZE_EXCEEDED = "SIZE_EXCEEDED",
    /** JSON nesting exceeds maximum depth */
    DEPTH_EXCEEDED = "DEPTH_EXCEEDED",
    /** JSON failed schema validation */
    SCHEMA_VALIDATION_FAILED = "SCHEMA_VALIDATION_FAILED",
    /** Prototype pollution attempt detected */
    PROTOTYPE_POLLUTION = "PROTOTYPE_POLLUTION"
}
/**
 * Error class for safe JSON operations
 */
export declare class SafeJsonError extends Error {
    /** Error code identifying the type of error */
    code: SafeJsonErrorCode;
    /** Original error that caused this error (if any) */
    cause?: Error;
    /** Validation errors from Zod (if applicable) */
    validationErrors?: z.ZodIssue[];
    constructor(message: string, code: SafeJsonErrorCode, cause?: Error, validationErrors?: z.ZodIssue[]);
}
/**
 * Recursively remove dangerous prototype properties from an object.
 *
 * This function walks through an object and its nested properties,
 * removing any properties that could be used for prototype pollution attacks.
 *
 * @param obj - The object to sanitize
 * @returns A new sanitized object with dangerous properties removed
 *
 * @example
 * ```typescript
 * const malicious = { __proto__: { isAdmin: true }, name: 'test' };
 * const safe = sanitizeObject(malicious);
 * // safe = { name: 'test' }
 * ```
 */
export declare function sanitizeObject<T extends object>(obj: T): T;
/**
 * Safely parse a JSON string with security protections.
 *
 * This function provides multiple layers of protection against common
 * JSON-based attacks:
 * - Size limits to prevent memory exhaustion
 * - Depth limits to prevent stack overflow
 * - Prototype pollution protection
 * - Optional schema validation
 *
 * @param json - The JSON string to parse
 * @param options - Parsing options
 * @returns The parsed and validated object
 * @throws {SafeJsonError} If parsing fails or validation fails
 *
 * @example
 * ```typescript
 * // Basic usage
 * const data = safeJsonParse<{ name: string }>('{"name": "test"}');
 *
 * // With schema validation
 * const schema = z.object({ name: z.string(), age: z.number() });
 * const validated = safeJsonParse('{"name": "test", "age": 25}', { schema });
 *
 * // With all options
 * const secure = safeJsonParse(untrustedJson, {
 *   schema: mySchema,
 *   maxDepth: 10,
 *   maxSize: 1024 * 1024, // 1MB
 *   stripPrototype: true,
 *   useNullPrototype: true,
 * });
 * ```
 */
export declare function safeJsonParse<T = unknown>(json: string, options?: SafeParseOptions<T>): T;
/**
 * Safely parse a JSON string, returning a result object instead of throwing.
 *
 * This is the "safe" variant that never throws, making it suitable for
 * use cases where you want to handle errors gracefully.
 *
 * @param json - The JSON string to parse
 * @param options - Parsing options
 * @returns A result object with success/failure status
 *
 * @example
 * ```typescript
 * const result = safeJsonParseSafe(userInput, { schema: mySchema });
 * if (result.success) {
 *   console.log('Parsed:', result.data);
 * } else {
 *   console.error('Failed:', result.error?.message);
 * }
 * ```
 */
export declare function safeJsonParseSafe<T = unknown>(json: string, options?: SafeParseOptions<T>): SafeParseResult<T>;
/**
 * Create a Map from JSON instead of a plain object.
 *
 * Maps are inherently safe from prototype pollution because they
 * don't have a prototype chain for data access.
 *
 * @param json - The JSON string to parse (must be an object)
 * @param options - Parsing options (schema is not applicable for Maps)
 * @returns A Map with string keys
 *
 * @example
 * ```typescript
 * const map = safeJsonParseAsMap('{"key1": "value1", "key2": "value2"}');
 * console.log(map.get('key1')); // "value1"
 * ```
 */
export declare function safeJsonParseAsMap<V = unknown>(json: string, options?: Omit<SafeParseOptions, "schema" | "useNullPrototype">): Map<string, V>;
/**
 * Stringify an object to JSON safely.
 *
 * This function sanitizes the object before stringifying to ensure
 * dangerous properties are not serialized.
 *
 * @param value - The value to stringify
 * @param space - Indentation for pretty printing
 * @returns The JSON string
 *
 * @example
 * ```typescript
 * const json = safeJsonStringify({ name: 'test', __proto__: { evil: true } });
 * // json = '{"name":"test"}'
 * ```
 */
export declare function safeJsonStringify(value: unknown, space?: string | number): string;
/**
 * Create a type-safe parser for a specific schema.
 *
 * This creates a reusable parser function that always validates
 * against the provided schema.
 *
 * @param schema - The Zod schema to validate against
 * @param defaultOptions - Default options for all parse calls
 * @returns A parser function
 *
 * @example
 * ```typescript
 * const userSchema = z.object({
 *   id: z.string().uuid(),
 *   name: z.string(),
 *   email: z.string().email(),
 * });
 *
 * const parseUser = createSafeParser(userSchema);
 *
 * // Later...
 * const user = parseUser(jsonString);
 * // user is typed as { id: string; name: string; email: string }
 * ```
 */
export declare function createSafeParser<T>(schema: ZodSchema<T>, defaultOptions?: Omit<SafeParseOptions<T>, "schema">): (json: string, options?: Omit<SafeParseOptions<T>, "schema">) => T;
/**
 * Create a type-safe parser that returns a SafeParseResult.
 *
 * @param schema - The Zod schema to validate against
 * @param defaultOptions - Default options for all parse calls
 * @returns A parser function that returns SafeParseResult
 */
export declare function createSafeParserSafe<T>(schema: ZodSchema<T>, defaultOptions?: Omit<SafeParseOptions<T>, "schema">): (json: string, options?: Omit<SafeParseOptions<T>, "schema">) => SafeParseResult<T>;
/**
 * A JSON.parse reviver function that strips dangerous properties.
 *
 * This can be used directly with JSON.parse when you need low-level control.
 *
 * @param key - The property key
 * @param value - The property value
 * @returns The value (or undefined to skip)
 *
 * @example
 * ```typescript
 * const parsed = JSON.parse(json, safeReviver);
 * ```
 */
export declare function safeReviver(key: string, value: unknown): unknown;
//# sourceMappingURL=safe-json.d.ts.map