/**
 * IP canonicalization for SSRF defense.
 *
 * The previous regex-based approach in `webhook.ts` only matched the literal
 * dotted-quad form. It missed every encoding that `getaddrinfo` (and therefore
 * `fetch`) accepts:
 *
 *   - Decimal:        http://2130706433/        → 127.0.0.1
 *   - Octal:          http://0177.0.0.1/        → 127.0.0.1
 *   - Hex:            http://0x7f.0.0.1/        → 127.0.0.1
 *   - Short-form:     http://127.1/             → 127.0.0.1
 *   - IPv4-mapped v6: http://[::ffff:127.0.0.1] → 127.0.0.1
 *   - IPv4-compat v6: http://[::127.0.0.1]      → 127.0.0.1
 *
 * This module canonicalizes any of those forms to a 4-octet IPv4 string (or
 * a normalized 16-byte IPv6 address), then range-checks against a complete
 * private/internal block list including AWS/GCP/Azure metadata endpoints and
 * the carrier-grade NAT range.
 */
/**
 * Result of {@link canonicalizeHostname}. There are exactly three valid
 * shapes:
 *
 *  - **Valid IPv4 literal** — `isHostname=false`, `isValidIp=true`, `ipv4` set.
 *  - **Valid IPv6 literal** — `isHostname=false`, `isValidIp=true`, `ipv6` set.
 *  - **Hostname (DNS name)** — `isHostname=true`, `isValidIp=false`, neither
 *    `ipv4` nor `ipv6` set.
 *  - **Malformed IP literal** — `isHostname=false`, `isValidIp=false`, neither
 *    IP field set. (Inputs that look like IP literals — e.g. contain `:` or
 *    only digits and dots — but fail to parse cleanly.)
 *
 * SSRF gates MUST treat the malformed shape as "reject" rather than as
 * "validated IP literal". Use `isValidIp` to distinguish the two `false`
 * `isHostname` cases.
 */
export interface CanonicalizedHost {
    /** Original hostname as it appeared in the URL. */
    raw: string;
    /** Canonical IPv4 dotted-quad string when the literal was IPv4 (in any form). */
    ipv4?: string;
    /** Canonical IPv6 hextet string when the literal was IPv6. */
    ipv6?: string;
    /** True when the input was a DNS name (not an IP literal in any form). */
    isHostname: boolean;
    /**
     * True when the input parsed cleanly into a canonical IP address (`ipv4`
     * or `ipv6` is set). False for both DNS hostnames and malformed IP-shaped
     * strings. Callers performing a security check on the parsed IP MUST
     * verify `isValidIp` before reading `ipv4` / `ipv6`.
     */
    isValidIp: boolean;
}
/**
 * Canonicalize a URL hostname into either a normalized IP address or a
 * passthrough hostname. Handles every IPv4 encoding accepted by `inet_aton`
 * (decimal, octal, hex, short-form), IPv4-mapped IPv6, and bracketed IPv6.
 */
export declare function canonicalizeHostname(rawHostname: string): CanonicalizedHost;
/**
 * Returns the matching private/internal range when the canonicalized host is
 * one, `null` when it's a safe public IP, or a "malformed" reason when the
 * input claims to be an IP literal but didn't parse cleanly.
 *
 * Defense-in-depth: even if a caller forgets to gate on `isValidIp`, this
 * function still fails closed on the malformed shape (`isHostname=false`
 * with no `ipv4`/`ipv6`).
 */
export declare function isPrivateAddress(host: CanonicalizedHost): {
    reason: string;
} | null;
//# sourceMappingURL=ip-canon.d.ts.map