@zhin.js/plugin-nettools 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @zhin.js/plugin-nettools
+
+## 0.1.1
+
+### Patch Changes
+
+- 17e1cae: Add `@zhin.js/plugin-nettools`: multi-region `ping` (check-host.net), `whois` (RDAP with rdap.org and WHOIS fallbacks), `dns` over HTTPS (Cloudflare → AliDNS → Google) and `domain-price` comparison (nazhumi.com), plus Agent tools `net_ping`, `whois_lookup`, `dns_lookup` and `domain_price`. Targets are canonicalised and refused when private, loopback, link-local, reserved, multicast or cloud-metadata (including hostnames resolving there); every request has a timeout, retry with exponential backoff and jitter, Retry-After handling and a per-user cooldown.
+- Updated dependencies [1a11207]
+- Updated dependencies [9943df6]
+  - @zhin.js/tool@1.1.8
+  - @zhin.js/skill@1.1.8

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# @zhin.js/plugin-nettools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Network tools for Zhin.js: multi-region ping, RDAP whois, DNS-over-HTTPS lookups and domain price comparison. Platform-agnostic, keyless (every upstream API is public), with per-user cooldown, an SSRF guard and resilient HTTP.
+
+## Installation
+
+```bash
+pnpm exec zhin install @zhin.js/plugin-nettools
+```
+
+## Usage
+
+Run the installation command from your application directory. It installs the package and mounts the `nettools` instance in 主配置 `plugins` 映射. The corresponding `zhin.config.yml` node is:
+
+```yaml
+configVersion: 2
+plugins:
+  nettools: "@zhin.js/plugin-nettools"
+nettools: {}
+```
+
+### Commands
+
+| Command | Description | Upstream |
+|---------|-------------|----------|
+| `ping <host>` | Ping a public host from several regions; shows average/min/max latency and packet loss per node | [check-host.net](https://check-host.net/about/api) |
+| `whois <domain>` | Registrar, creation/expiry/update dates, status, name servers, DNSSEC | RDAP via the [IANA bootstrap](https://data.iana.org/rdap/dns.json), fallback [rdap.org](https://rdap.org), then the [60s API](https://60s.viki.moe) WHOIS (covers `.cn` and other TLDs without RDAP; registrant personal data is not shown) |
+| `dns <name> [type]` | DNS records; `type` is one of `A AAAA CNAME MX TXT NS SOA CAA SRV PTR DS DNSKEY` (default `A`). `dns 1.1.1.1 PTR` does a reverse lookup | Cloudflare DoH, fallback AliDNS DoH, then Google DoH |
+| `domain-price <suffix> [register\|renew\|transfer]` (alias `域名比价`) | Cheapest registrars for a suffix (`com`, `.cn`, `.co.uk`, or a full domain); Chinese kinds `注册 / 续费 / 转入` also work | [nazhumi.com](https://www.nazhumi.com) |
+
+### Agent tools
+
+Skill `nettools` exposes `net_ping`, `whois_lookup`, `dns_lookup` and `domain_price`, sharing the same validation, cooldown and resilience as the commands.
+
+## Configuration
+
+All fields are optional; defaults are conservative because every upstream is a free, shared service. Out-of-range values are clamped.
+
+| Field | Default | Range | Meaning |
+|-------|---------|-------|---------|
+| `cooldownSeconds` | `10` | 0–3600 | Per-user cooldown shared by all commands/tools (0 disables). Spent after input validation, so typos are free |
+| `requestTimeoutMs` | `8000` | 1000–30000 | Timeout for each HTTP attempt |
+| `maxRetries` | `2` | 0–5 | Retries for transient failures |
+| `pingMaxNodes` | `4` | 1–10 | check-host.net probe nodes |
+| `pingPollIntervalMs` | `2000` | 500–10000 | Wait between result polls |
+| `pingMaxPolls` | `5` | 1–10 | Poll budget; unfinished nodes are reported as "no result" |
+| `dohProviders` | `["cloudflare", "alidns", "google"]` | — | DoH providers in fallback order |
+| `priceListLimit` | `8` | 1–20 | Registrars shown per comparison |
+
+```yaml
+nettools:
+  cooldownSeconds: 30
+  pingMaxNodes: 6
+```
+
+## Security: target policy (SSRF guard)
+
+User input is canonicalised with the WHATWG URL host parser (the parser `fetch` uses), so odd spellings such as `2130706433`, `0x7f.1`, `017700000001`, `127.1` or `[::ffff:127.0.0.1]` are checked in their real form. URLs, ports, paths, user-info, zone ids and percent-encoding are refused outright.
+
+Refused targets:
+
+- IPv4: `0.0.0.0/8`, private `10/8`, `172.16/12`, `192.168/16`, CGNAT `100.64/10`, loopback `127/8`, link-local `169.254/16`, IETF/documentation/benchmark ranges, multicast `224/4`, reserved `240/4`;
+- IPv6: `::`, `::1`, ULA `fc00::/7`, link-local `fe80::/10`, site-local `fec0::/10`, multicast `ff00::/8`, documentation, Teredo, anything outside global unicast `2000::/3`; IPv4-mapped, NAT64 and 6to4 addresses are unwrapped and judged by their embedded IPv4;
+- cloud metadata: `169.254.169.254`, `169.254.170.2`, `100.100.100.200`, `168.63.129.16`, `fd00:ec2::254`, `metadata.google.internal`, …;
+- names: single-label hosts, `localhost`, and internal/reserved suffixes (`.local`, `.internal`, `.lan`, `.home.arpa`, `.test`, `.invalid`, …).
+
+For `ping`, hostnames are also resolved (A + AAAA over DoH) and refused if **any** address is blocked; resolution failure fails closed. The probe itself runs on check-host.net, so this process never connects to the target.
+
+## Resilience
+
+Every external request has a per-attempt timeout, retries network errors, timeouts, 408/425/429/5xx with exponential backoff plus jitter, honours `Retry-After` up to 10 s (longer waits fail fast with a rate-limit message), caps response bodies at 1 MiB and parses JSON defensively. DoH falls back Cloudflare → AliDNS → Google (only one retry per provider while another remains, to bound latency); whois falls back registry RDAP → rdap.org → 60s WHOIS (the IANA bootstrap is cached for 24 h, stale copies are reused if IANA is down); a failed ping poll does not discard a running check. Failures are reported as short, specific messages.

package/commands/dns/[name]/[[type]]/index.js

@@ -0,0 +1,18 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { commandCallerKey } from "../../../../lib/cooldown.js";
+import { nettoolsServiceToken } from "../../../../lib/runtime.js";
+export default defineCommand({
+    description: 'DNS 查询（DoH），类型可选 A/AAAA/CNAME/MX/TXT/NS/SOA/CAA/SRV/PTR/DS/DNSKEY',
+    params: {
+        name: { type: 'string', description: '域名；PTR 查询时可填 IP' },
+        type: { type: 'string', description: '记录类型，默认 A' },
+    },
+    async execute({ params, input, use, signal }) {
+        const service = use(nettoolsServiceToken);
+        const name = String(params.name ?? '');
+        const type = params.type == null ? undefined : String(params.type);
+        const callerKey = commandCallerKey(input);
+        return service.run(() => service.dns(name, type, callerKey, signal));
+    },
+});

package/commands/dns/[name]/[[type]]/index.ts

@@ -0,0 +1,18 @@
+import { defineCommand } from 'zhin.js/command';
+import { commandCallerKey } from '../../../../src/cooldown.js';
+import { nettoolsServiceToken } from '../../../../src/runtime.js';
+
+export default defineCommand({
+  description: 'DNS 查询（DoH），类型可选 A/AAAA/CNAME/MX/TXT/NS/SOA/CAA/SRV/PTR/DS/DNSKEY',
+  params: {
+    name: { type: 'string', description: '域名；PTR 查询时可填 IP' },
+    type: { type: 'string', description: '记录类型，默认 A' },
+  },
+  async execute({ params, input, use, signal }) {
+    const service = use(nettoolsServiceToken);
+    const name = String(params.name ?? '');
+    const type = params.type == null ? undefined : String(params.type);
+    const callerKey = commandCallerKey(input);
+    return service.run(() => service.dns(name, type, callerKey, signal));
+  },
+});

package/commands/domain-price/[suffix]/[[order]]/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { commandCallerKey } from "../../../../lib/cooldown.js";
+import { nettoolsServiceToken } from "../../../../lib/runtime.js";
+export default defineCommand({
+    description: '域名注册/续费/转入价格比价（nazhumi.com）',
+    alias: ['域名比价'],
+    params: {
+        suffix: { type: 'string', description: '域名后缀（com、.cn、.co.uk）或完整域名' },
+        order: { type: 'string', description: '注册(register) / 续费(renew) / 转入(transfer)，默认注册' },
+    },
+    async execute({ params, input, use, signal }) {
+        const service = use(nettoolsServiceToken);
+        const suffix = String(params.suffix ?? '');
+        const order = params.order == null ? undefined : String(params.order);
+        const callerKey = commandCallerKey(input);
+        return service.run(() => service.domainPrice(suffix, order, callerKey, signal));
+    },
+});

package/commands/domain-price/[suffix]/[[order]]/index.ts

@@ -0,0 +1,19 @@
+import { defineCommand } from 'zhin.js/command';
+import { commandCallerKey } from '../../../../src/cooldown.js';
+import { nettoolsServiceToken } from '../../../../src/runtime.js';
+
+export default defineCommand({
+  description: '域名注册/续费/转入价格比价（nazhumi.com）',
+  alias: ['域名比价'],
+  params: {
+    suffix: { type: 'string', description: '域名后缀（com、.cn、.co.uk）或完整域名' },
+    order: { type: 'string', description: '注册(register) / 续费(renew) / 转入(transfer)，默认注册' },
+  },
+  async execute({ params, input, use, signal }) {
+    const service = use(nettoolsServiceToken);
+    const suffix = String(params.suffix ?? '');
+    const order = params.order == null ? undefined : String(params.order);
+    const callerKey = commandCallerKey(input);
+    return service.run(() => service.domainPrice(suffix, order, callerKey, signal));
+  },
+});

package/commands/ping/[host]/index.js

@@ -0,0 +1,14 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { commandCallerKey } from "../../../lib/cooldown.js";
+import { nettoolsServiceToken } from "../../../lib/runtime.js";
+export default defineCommand({
+    description: '从多个地区 Ping 一个公网主机（check-host.net）',
+    params: { host: { type: 'string', description: '域名或公网 IP' } },
+    async execute({ params, input, use, signal }) {
+        const service = use(nettoolsServiceToken);
+        const host = String(params.host ?? '');
+        const callerKey = commandCallerKey(input);
+        return service.run(() => service.ping(host, callerKey, signal));
+    },
+});

package/commands/ping/[host]/index.ts

@@ -0,0 +1,14 @@
+import { defineCommand } from 'zhin.js/command';
+import { commandCallerKey } from '../../../src/cooldown.js';
+import { nettoolsServiceToken } from '../../../src/runtime.js';
+
+export default defineCommand({
+  description: '从多个地区 Ping 一个公网主机（check-host.net）',
+  params: { host: { type: 'string', description: '域名或公网 IP' } },
+  async execute({ params, input, use, signal }) {
+    const service = use(nettoolsServiceToken);
+    const host = String(params.host ?? '');
+    const callerKey = commandCallerKey(input);
+    return service.run(() => service.ping(host, callerKey, signal));
+  },
+});

package/commands/whois/[domain]/index.js

@@ -0,0 +1,14 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { commandCallerKey } from "../../../lib/cooldown.js";
+import { nettoolsServiceToken } from "../../../lib/runtime.js";
+export default defineCommand({
+    description: '查询域名注册信息（RDAP / WHOIS）',
+    params: { domain: { type: 'string', description: '要查询的域名' } },
+    async execute({ params, input, use, signal }) {
+        const service = use(nettoolsServiceToken);
+        const domain = String(params.domain ?? '');
+        const callerKey = commandCallerKey(input);
+        return service.run(() => service.whois(domain, callerKey, signal));
+    },
+});

package/commands/whois/[domain]/index.ts

@@ -0,0 +1,14 @@
+import { defineCommand } from 'zhin.js/command';
+import { commandCallerKey } from '../../../src/cooldown.js';
+import { nettoolsServiceToken } from '../../../src/runtime.js';
+
+export default defineCommand({
+  description: '查询域名注册信息（RDAP / WHOIS）',
+  params: { domain: { type: 'string', description: '要查询的域名' } },
+  async execute({ params, input, use, signal }) {
+    const service = use(nettoolsServiceToken);
+    const domain = String(params.domain ?? '');
+    const callerKey = commandCallerKey(input);
+    return service.run(() => service.whois(domain, callerKey, signal));
+  },
+});

package/lib/address-policy.d.ts

@@ -0,0 +1,44 @@
+export type ParsedHost = {
+    readonly kind: 'ipv4';
+    readonly address: string;
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: 'ipv6';
+    readonly address: string;
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: 'domain';
+    readonly name: string;
+};
+export type AddressVerdict = {
+    readonly blocked: false;
+} | {
+    readonly blocked: true;
+    readonly reason: string;
+};
+export interface ParseHostOptions {
+    /** Allow `_` in labels (needed for DNS names such as `_dmarc.example.com`). */
+    readonly allowUnderscore?: boolean;
+    /** Minimum number of labels for a domain (default 2, i.e. a full domain). */
+    readonly minLabels?: number;
+}
+/**
+ * Parse and canonicalise one user-supplied host (domain, IPv4 or IPv6).
+ * Throws {@link NettoolsError} (`invalid_input`) for anything that is not a
+ * bare host: URLs, ports, paths, user-info, zone ids and percent-encoding are
+ * all refused rather than "helpfully" stripped.
+ */
+export declare function parseHostInput(input: string, options?: ParseHostOptions): ParsedHost;
+/** Classify a parsed host without any network access. Domains are checked by name only. */
+export declare function classifyParsedHost(host: ParsedHost): AddressVerdict;
+/** Classify a literal address string (any spelling the URL parser understands). */
+export declare function classifyAddress(address: string): AddressVerdict;
+export declare function classifyHostname(name: string): AddressVerdict;
+/** Dotted-quad IPv4 to 4 bytes. Callers must pass a canonical dotted quad. */
+export declare function ipv4ToBytes(address: string): Uint8Array;
+/** Textual IPv6 (with optional `::` and dotted IPv4 tail) to 16 bytes. */
+export declare function ipv6ToBytes(address: string): Uint8Array;
+/** Build the PTR query name for an IP (`in-addr.arpa` / `ip6.arpa`). */
+export declare function reverseLookupName(host: ParsedHost): string;
+/** Human label for a parsed host. */
+export declare function displayHost(host: ParsedHost): string;

package/lib/address-policy.js

@@ -0,0 +1,388 @@
+/**
+ * Target address policy (SSRF guard).
+ *
+ * Network tools probe hosts that users type into chat. Even though the probes
+ * themselves run on third-party services (check-host.net, public DoH, RDAP),
+ * we refuse anything that points at private, loopback, link-local, reserved or
+ * cloud-metadata space so the bot can never be used to map internal networks
+ * or poke metadata endpoints through a relay.
+ *
+ * Design:
+ * 1. Canonicalise first. The input is fed through the WHATWG URL host parser,
+ *    the same parser browsers and Node's fetch use. It turns odd IPv4 spellings
+ *    (`2130706433`, `0x7f.1`, `017700000001`, `127.1`) into dotted quads,
+ *    normalises IPv6 and converts IDN to punycode. We then classify the
+ *    canonical form, so "what we checked" is exactly "what we send".
+ * 2. Classify by bytes. IPv4 and IPv6 are compared as raw bytes against
+ *    prefix tables. Embedded IPv4 (IPv4-mapped, NAT64, 6to4) is unwrapped and
+ *    classified as IPv4.
+ * 3. Allow-list IPv6. Only global unicast (2000::/3) is accepted, minus the
+ *    documentation / Teredo / special ranges listed below.
+ * 4. Names. Single-label names, internal suffixes (`.local`, `.internal`, ...)
+ *    and well-known metadata hostnames are refused before any lookup.
+ *    Hostnames are additionally resolved (see target-guard.ts) and refused
+ *    when any A/AAAA record is blocked.
+ */
+import { isIPv4, isIPv6 } from 'node:net';
+import { NettoolsError } from './errors.js';
+const ALLOWED = Object.freeze({ blocked: false });
+function blocked(reason) {
+    return Object.freeze({ blocked: true, reason });
+}
+const CLOUD_METADATA_REASON = '云服务元数据地址';
+/** Exact IPv4 metadata endpoints, checked before the range table for a clearer message. */
+const CLOUD_METADATA_IPV4 = new Set([
+    '169.254.169.254', // AWS / GCP / Azure / Oracle / OpenStack instance metadata
+    '169.254.170.2', // AWS ECS task metadata
+    '169.254.169.123', // AWS Time Sync
+    '100.100.100.200', // Alibaba Cloud metadata
+    '168.63.129.16', // Azure WireServer (public range, still host-internal)
+]);
+/** Exact IPv6 metadata endpoints. */
+const CLOUD_METADATA_IPV6 = ['fd00:ec2::254', 'fd00:ec2::23'];
+const BLOCKED_IPV4_RANGES = [
+    ipv4Rule('0.0.0.0', 8, '未指定 / “本网络”地址'),
+    ipv4Rule('10.0.0.0', 8, '私有地址 (RFC 1918)'),
+    ipv4Rule('100.64.0.0', 10, '运营商级 NAT 地址 (CGNAT, RFC 6598)'),
+    ipv4Rule('127.0.0.0', 8, '回环地址'),
+    ipv4Rule('169.254.0.0', 16, '链路本地地址'),
+    ipv4Rule('172.16.0.0', 12, '私有地址 (RFC 1918)'),
+    ipv4Rule('192.0.0.0', 24, 'IETF 协议保留地址'),
+    ipv4Rule('192.0.2.0', 24, '文档示例地址'),
+    ipv4Rule('192.88.99.0', 24, '已废弃的 6to4 中继地址'),
+    ipv4Rule('192.168.0.0', 16, '私有地址 (RFC 1918)'),
+    ipv4Rule('198.18.0.0', 15, '基准测试保留地址'),
+    ipv4Rule('198.51.100.0', 24, '文档示例地址'),
+    ipv4Rule('203.0.113.0', 24, '文档示例地址'),
+    ipv4Rule('224.0.0.0', 4, '组播地址'),
+    ipv4Rule('240.0.0.0', 4, '保留地址（含广播地址）'),
+];
+/** Special IPv6 ranges inside 2000::/3 that are still refused. */
+const BLOCKED_GLOBAL_IPV6_RANGES = [
+    ipv6Rule('2001::', 32, 'Teredo 隧道地址'),
+    ipv6Rule('2001:2::', 48, '基准测试保留地址'),
+    ipv6Rule('2001:10::', 28, 'ORCHID 保留地址'),
+    ipv6Rule('2001:db8::', 32, '文档示例地址'),
+    ipv6Rule('3fff::', 20, '文档示例地址'),
+];
+const BLOCKED_HOSTNAMES = new Set([
+    'localhost',
+    'metadata',
+    'metadata.google.internal',
+    'metadata.goog',
+    'instance-data',
+    'instance-data.ec2.internal',
+]);
+/** Suffixes that only make sense inside a private network or are reserved (RFC 2606 / 6761 / 6762). */
+const BLOCKED_SUFFIXES = [
+    'localhost',
+    'local',
+    'localdomain',
+    'internal',
+    'intranet',
+    'private',
+    'corp',
+    'home',
+    'lan',
+    'home.arpa',
+    'arpa',
+    'test',
+    'invalid',
+    'example',
+    'onion',
+];
+const MAX_HOSTNAME_LENGTH = 253;
+const MAX_LABEL_LENGTH = 63;
+/* ------------------------------------------------------------------ */
+/* Parsing                                                             */
+/* ------------------------------------------------------------------ */
+/**
+ * Parse and canonicalise one user-supplied host (domain, IPv4 or IPv6).
+ * Throws {@link NettoolsError} (`invalid_input`) for anything that is not a
+ * bare host: URLs, ports, paths, user-info, zone ids and percent-encoding are
+ * all refused rather than "helpfully" stripped.
+ */
+export function parseHostInput(input, options = {}) {
+    const trimmed = input.trim();
+    if (trimmed.length === 0) {
+        throw invalid('请提供主机名或 IP 地址');
+    }
+    if (trimmed.length > MAX_HOSTNAME_LENGTH + 2) {
+        throw invalid('主机名过长');
+    }
+    if (/[\s/\\@?#%]/u.test(trimmed)) {
+        throw invalid('只接受裸主机名或 IP，不要带协议、端口、路径或特殊字符');
+    }
+    const bracketed = trimmed.startsWith('[') && trimmed.endsWith(']');
+    const ipv6Candidate = bracketed ? trimmed.slice(1, -1) : trimmed;
+    if (bracketed || trimmed.includes(':')) {
+        if (!isIPv6(ipv6Candidate)) {
+            throw invalid('不是有效的 IPv6 地址（如需端口请去掉端口）');
+        }
+        const canonical = canonicalizeWithUrlParser(`[${ipv6Candidate}]`);
+        const address = canonical.slice(1, -1);
+        return Object.freeze({ kind: 'ipv6', address, bytes: ipv6ToBytes(address) });
+    }
+    const canonical = canonicalizeWithUrlParser(trimmed);
+    if (isIPv4(canonical)) {
+        return Object.freeze({ kind: 'ipv4', address: canonical, bytes: ipv4ToBytes(canonical) });
+    }
+    const name = canonical.endsWith('.') ? canonical.slice(0, -1) : canonical;
+    validateDomainSyntax(name, options);
+    return Object.freeze({ kind: 'domain', name });
+}
+/**
+ * Run the WHATWG host parser by assigning to `URL#hostname` on a placeholder
+ * URL. An invalid host leaves the placeholder untouched, which we detect.
+ */
+function canonicalizeWithUrlParser(host) {
+    const placeholder = 'placeholder.invalid';
+    const probe = new URL(`http://${placeholder}/`);
+    probe.hostname = host;
+    const result = probe.hostname;
+    const unchanged = result === placeholder && host.toLowerCase() !== placeholder;
+    if (unchanged || result.length === 0) {
+        throw invalid('不是有效的主机名或 IP 地址');
+    }
+    return result;
+}
+function validateDomainSyntax(name, options) {
+    if (name.length === 0 || name.length > MAX_HOSTNAME_LENGTH) {
+        throw invalid('主机名长度不合法');
+    }
+    const labels = name.split('.');
+    if (labels.length < (options.minLabels ?? 2)) {
+        throw invalid('请提供完整域名（例如 example.com）');
+    }
+    const labelPattern = options.allowUnderscore
+        ? /^[a-z0-9_](?:[a-z0-9_-]*[a-z0-9_])?$/u
+        : /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/u;
+    for (const label of labels) {
+        if (label.length === 0 || label.length > MAX_LABEL_LENGTH || !labelPattern.test(label)) {
+            throw invalid(`域名标签不合法：${label || '(空)'}`);
+        }
+    }
+    const topLevel = labels[labels.length - 1] ?? '';
+    if (/^\d+$/u.test(topLevel)) {
+        throw invalid('顶级域不能是纯数字');
+    }
+}
+function invalid(message) {
+    return new NettoolsError('invalid_input', message);
+}
+/* ------------------------------------------------------------------ */
+/* Classification                                                      */
+/* ------------------------------------------------------------------ */
+/** Classify a parsed host without any network access. Domains are checked by name only. */
+export function classifyParsedHost(host) {
+    if (host.kind === 'domain') {
+        return classifyHostname(host.name);
+    }
+    if (host.kind === 'ipv4') {
+        return classifyIpv4Bytes(host.bytes);
+    }
+    return classifyIpv6Bytes(host.bytes);
+}
+/** Classify a literal address string (any spelling the URL parser understands). */
+export function classifyAddress(address) {
+    const parsed = parseHostInput(address);
+    if (parsed.kind === 'domain') {
+        throw invalid(`不是 IP 地址：${address}`);
+    }
+    return classifyParsedHost(parsed);
+}
+export function classifyHostname(name) {
+    const normalized = name.toLowerCase().replace(/\.$/u, '');
+    if (BLOCKED_HOSTNAMES.has(normalized)) {
+        return normalized.startsWith('localhost')
+            ? blocked('本机主机名')
+            : blocked(CLOUD_METADATA_REASON);
+    }
+    for (const suffix of BLOCKED_SUFFIXES) {
+        if (normalized === suffix || normalized.endsWith(`.${suffix}`)) {
+            return blocked(`内网或保留域名后缀 .${suffix}`);
+        }
+    }
+    return ALLOWED;
+}
+function classifyIpv4Bytes(bytes) {
+    const dotted = Array.from(bytes).join('.');
+    if (CLOUD_METADATA_IPV4.has(dotted)) {
+        return blocked(CLOUD_METADATA_REASON);
+    }
+    for (const rule of BLOCKED_IPV4_RANGES) {
+        if (matchesPrefix(bytes, rule.prefix, rule.bits)) {
+            return blocked(rule.reason);
+        }
+    }
+    return ALLOWED;
+}
+const IPV4_MAPPED_PREFIX = ipv6ToBytes('::ffff:0:0');
+const NAT64_WELL_KNOWN_PREFIX = ipv6ToBytes('64:ff9b::');
+const NAT64_LOCAL_PREFIX = ipv6ToBytes('64:ff9b:1::');
+const SIX_TO_FOUR_PREFIX = ipv6ToBytes('2002::');
+const GLOBAL_UNICAST_PREFIX = ipv6ToBytes('2000::');
+const UNIQUE_LOCAL_PREFIX = ipv6ToBytes('fc00::');
+const LINK_LOCAL_PREFIX = ipv6ToBytes('fe80::');
+const SITE_LOCAL_PREFIX = ipv6ToBytes('fec0::');
+const MULTICAST_PREFIX = ipv6ToBytes('ff00::');
+const CLOUD_METADATA_IPV6_BYTES = CLOUD_METADATA_IPV6.map((address) => ipv6ToBytes(address));
+function classifyIpv6Bytes(bytes) {
+    if (bytes.every((byte) => byte === 0)) {
+        return blocked('未指定地址 (::)');
+    }
+    const isLoopback = bytes.slice(0, 15).every((byte) => byte === 0) && bytes[15] === 1;
+    if (isLoopback) {
+        return blocked('回环地址 (::1)');
+    }
+    for (const metadata of CLOUD_METADATA_IPV6_BYTES) {
+        if (matchesPrefix(bytes, metadata, 128)) {
+            return blocked(CLOUD_METADATA_REASON);
+        }
+    }
+    if (matchesPrefix(bytes, IPV4_MAPPED_PREFIX, 96)) {
+        return classifyEmbeddedIpv4(bytes.slice(12, 16), 'IPv4 映射地址');
+    }
+    if (matchesPrefix(bytes, NAT64_WELL_KNOWN_PREFIX, 96)) {
+        return classifyEmbeddedIpv4(bytes.slice(12, 16), 'NAT64 地址');
+    }
+    if (matchesPrefix(bytes, NAT64_LOCAL_PREFIX, 48)) {
+        return blocked('本地 NAT64 地址');
+    }
+    if (matchesPrefix(bytes, SIX_TO_FOUR_PREFIX, 16)) {
+        return classifyEmbeddedIpv4(bytes.slice(2, 6), '6to4 地址');
+    }
+    if (matchesPrefix(bytes, UNIQUE_LOCAL_PREFIX, 7)) {
+        return blocked('唯一本地地址 (ULA, fc00::/7)');
+    }
+    if (matchesPrefix(bytes, LINK_LOCAL_PREFIX, 10)) {
+        return blocked('链路本地地址 (fe80::/10)');
+    }
+    if (matchesPrefix(bytes, SITE_LOCAL_PREFIX, 10)) {
+        return blocked('已废弃的站点本地地址 (fec0::/10)');
+    }
+    if (matchesPrefix(bytes, MULTICAST_PREFIX, 8)) {
+        return blocked('组播地址 (ff00::/8)');
+    }
+    if (!matchesPrefix(bytes, GLOBAL_UNICAST_PREFIX, 3)) {
+        return blocked('非全球单播 IPv6 地址');
+    }
+    for (const rule of BLOCKED_GLOBAL_IPV6_RANGES) {
+        if (matchesPrefix(bytes, rule.prefix, rule.bits)) {
+            return blocked(rule.reason);
+        }
+    }
+    return ALLOWED;
+}
+function classifyEmbeddedIpv4(embedded, wrapper) {
+    const verdict = classifyIpv4Bytes(embedded);
+    if (!verdict.blocked) {
+        return verdict;
+    }
+    const dotted = Array.from(embedded).join('.');
+    return blocked(`${wrapper}指向 ${dotted}（${verdict.reason}）`);
+}
+/* ------------------------------------------------------------------ */
+/* Byte helpers                                                        */
+/* ------------------------------------------------------------------ */
+function matchesPrefix(bytes, prefix, bits) {
+    if (bytes.length !== prefix.length) {
+        return false;
+    }
+    const fullBytes = Math.floor(bits / 8);
+    for (let index = 0; index < fullBytes; index += 1) {
+        if (bytes[index] !== prefix[index]) {
+            return false;
+        }
+    }
+    const remainingBits = bits % 8;
+    if (remainingBits === 0) {
+        return true;
+    }
+    const mask = (0xff << (8 - remainingBits)) & 0xff;
+    return ((bytes[fullBytes] ?? 0) & mask) === ((prefix[fullBytes] ?? 0) & mask);
+}
+/** Dotted-quad IPv4 to 4 bytes. Callers must pass a canonical dotted quad. */
+export function ipv4ToBytes(address) {
+    const parts = address.split('.').map((part) => Number(part));
+    const valid = parts.length === 4 && parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255);
+    if (!valid) {
+        throw invalid(`不是有效的 IPv4 地址：${address}`);
+    }
+    return Uint8Array.from(parts);
+}
+/** Textual IPv6 (with optional `::` and dotted IPv4 tail) to 16 bytes. */
+export function ipv6ToBytes(address) {
+    let text = address.toLowerCase();
+    const groups = [];
+    const lastColon = text.lastIndexOf(':');
+    const tail = text.slice(lastColon + 1);
+    const tailGroups = [];
+    if (tail.includes('.')) {
+        const v4 = ipv4ToBytes(tail);
+        tailGroups.push(((v4[0] ?? 0) << 8) | (v4[1] ?? 0));
+        tailGroups.push(((v4[2] ?? 0) << 8) | (v4[3] ?? 0));
+        text = text.slice(0, lastColon + 1) + '0:0';
+    }
+    const halves = text.split('::');
+    if (halves.length > 2) {
+        throw invalid(`不是有效的 IPv6 地址：${address}`);
+    }
+    const head = parseGroups(halves[0] ?? '');
+    const rest = halves.length === 2 ? parseGroups(halves[1] ?? '') : [];
+    const missing = 8 - head.length - rest.length;
+    if (halves.length === 2 ? missing < 1 : missing !== 0) {
+        throw invalid(`不是有效的 IPv6 地址：${address}`);
+    }
+    groups.push(...head);
+    for (let index = 0; index < missing && halves.length === 2; index += 1) {
+        groups.push(0);
+    }
+    groups.push(...rest);
+    if (tailGroups.length === 2) {
+        groups.splice(6, 2, ...tailGroups);
+    }
+    const bytes = new Uint8Array(16);
+    groups.forEach((group, index) => {
+        bytes[index * 2] = (group >> 8) & 0xff;
+        bytes[index * 2 + 1] = group & 0xff;
+    });
+    return bytes;
+}
+function parseGroups(text) {
+    if (text.length === 0) {
+        return [];
+    }
+    return text.split(':').map((group) => {
+        if (!/^[0-9a-f]{1,4}$/u.test(group)) {
+            throw invalid(`IPv6 分组不合法：${group}`);
+        }
+        return Number.parseInt(group, 16);
+    });
+}
+function ipv4Rule(base, bits, reason) {
+    return Object.freeze({ prefix: ipv4ToBytes(base), bits, reason });
+}
+function ipv6Rule(base, bits, reason) {
+    return Object.freeze({ prefix: ipv6ToBytes(base), bits, reason });
+}
+/** Build the PTR query name for an IP (`in-addr.arpa` / `ip6.arpa`). */
+export function reverseLookupName(host) {
+    if (host.kind === 'ipv4') {
+        return `${Array.from(host.bytes).reverse().join('.')}.in-addr.arpa`;
+    }
+    if (host.kind === 'ipv6') {
+        const nibbles = [];
+        for (const byte of host.bytes) {
+            nibbles.push((byte >> 4).toString(16));
+            nibbles.push((byte & 0x0f).toString(16));
+        }
+        return `${nibbles.reverse().join('.')}.ip6.arpa`;
+    }
+    throw invalid('反向解析需要 IP 地址');
+}
+/** Human label for a parsed host. */
+export function displayHost(host) {
+    return host.kind === 'domain' ? host.name : host.address;
+}
+//# sourceMappingURL=address-policy.js.map