import { type IncomingHttpHeaders } from "node:http";
import type { FetchOptions } from "./types.js";
export type CollectorSecurityErrorCode = "INVALID_URL" | "UNSAFE_PROTOCOL" | "UNSAFE_CREDENTIALS" | "UNSAFE_HOST" | "DNS_FAILED" | "TOO_MANY_REDIRECTS" | "UNSAFE_REDIRECT" | "RESPONSE_TOO_LARGE" | "UNSUPPORTED_ENCODING" | "TIMEOUT" | "UNSAFE_REQUEST_DATA";
/** A stable, machine-readable failure for collector trust-boundary violations. */
export declare class CollectorSecurityError extends Error {
    readonly code: CollectorSecurityErrorCode;
    constructor(code: CollectorSecurityErrorCode, message: string, options?: ErrorOptions);
}
export type ResolvedAddress = {
    address: string;
    family: 4 | 6;
};
export type SafeResolvedTarget = {
    url: URL;
    /** A public address selected after checking every DNS answer. */
    address: string;
    family: 4 | 6;
    /** All validated answers, retained for dual-stack connection fallback. */
    addresses: readonly ResolvedAddress[];
};
export type SafeTransportResponse = {
    statusCode: number;
    statusMessage: string;
    headers: IncomingHttpHeaders;
    body: AsyncIterable<Uint8Array>;
    cancel: () => void;
};
export type SafeFetchDependencies = {
    resolve?: (hostname: string) => Promise<readonly ResolvedAddress[]>;
    request?: (target: SafeResolvedTarget, init: {
        signal: AbortSignal;
        userAgent: string;
    }) => Promise<SafeTransportResponse>;
};
export type SafeFetchResult = {
    text: string;
    rawBytes: number;
    finalUrl: string;
    redirects: number;
};
/** True when an address must never be contacted by the web collector. */
export declare function isUnsafeCollectorAddress(address: string): boolean;
/**
 * Resolve and validate a URL, rejecting every target that is not public HTTP(S).
 * Every DNS answer is checked, then one approved address is pinned into the
 * socket request so a second DNS lookup cannot rebind it to a private service.
 */
export declare function resolveSafeCollectorTarget(rawUrl: string | URL, resolver?: (hostname: string) => Promise<readonly ResolvedAddress[]>): Promise<SafeResolvedTarget>;
/** Fetch text through the SSRF-safe, redirect-validating transport. */
export declare function fetchExternalText(rawUrl: string, options?: FetchOptions, dependencies?: SafeFetchDependencies): Promise<SafeFetchResult>;