@agnt-sdk/simon-server 0.0.0-stage → 0.1.0

package/dist/http.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Serving HTTP: a request and reply independent of node:http (so tests can drive a server in-process), a
+ * small router, and the adapter to node:http. A body is read only up to its route's cap, so an oversized
+ * one is refused without being held. Every error leaves as an RFC 9457 problem (spec section 9), with the
+ * headers its WireError names: its content type, `WWW-Authenticate` on a 401, Retry-After.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { WireError } from '@agnt-sdk/simon-protocol';
+import { type Network } from './net/ip.ts';
+export interface Request {
+    method: string;
+    /** The request target exactly as sent: the path and query a signature covers. */
+    target: string;
+    path: string;
+    query: URLSearchParams;
+    /** The route's `:name` segments, percent-decoded. */
+    params: Record<string, string>;
+    /** Lower-case names, as node:http gives them. */
+    headers: Record<string, string | string[] | undefined>;
+    body: Buffer;
+    /** The client's address, as the socket saw it. */
+    ip: string;
+}
+export interface Reply {
+    status: number;
+    /** A JSON body, sent in canonical form, as application/json unless `headers` name another type. */
+    json?: unknown;
+    /** A byte body, sent as application/octet-stream. */
+    bytes?: Buffer;
+    headers?: Record<string, string>;
+}
+export interface Route<Api = unknown> {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** A path whose `:name` segments match any one segment, e.g. `/simon/agents/:address`. */
+    path: string;
+    /** The largest body accepted; the server's `requestBodyBytes` when absent. */
+    maxBody?: number;
+    handle(req: Request, api: Api): Reply | Promise<Reply>;
+}
+export declare const json: (body: unknown, status?: number) => Reply;
+export declare const errorReply: (e: WireError) => Reply;
+export declare class Router<Api> {
+    #private;
+    add(route: Route<Api>): void;
+    /** The route for a method and path, with its parameters; null when none matches. */
+    match(method: string, path: string): {
+        route: Route<Api>;
+        params: Record<string, string>;
+    } | null;
+}
+/** What the node:http adapter serves: the body cap for a request, and the handling of a whole one. */
+export interface App {
+    bodyLimit(method: string, path: string): number;
+    handle(req: Request): Promise<Reply>;
+}
+/** Where a client's address comes from behind proxies: the header they set, and the networks they connect from. */
+export interface ProxySettings {
+    clientIpHeader: string | null;
+    trustedProxies: readonly Network[];
+}
+/**
+ * The client's address. With no `clientIpHeader`, the connection's. With one, the header is a list each proxy
+ * appends the address it heard from to, so it is read from the right: while the address so far is a trusted
+ * proxy, the entry before it names who that proxy heard from. A client can write anything at the left of the
+ * list, but never past the last trusted hop, so no spoofed entry is reached; an entry that is not an address
+ * stops the walk.
+ */
+export declare function clientIp(req: IncomingMessage, { clientIpHeader, trustedProxies }: ProxySettings): string;
+export declare function nodeListener(app: App, proxies: ProxySettings): (req: IncomingMessage, res: ServerResponse) => void;

package/dist/http.js

@@ -0,0 +1,112 @@
+import { isIP } from 'node:net';
+import { bodyTooLarge, canonicalize, WireError } from '@agnt-sdk/simon-protocol';
+import { inNetworks, parseNetwork } from "./net/ip.js";
+export const json = (body, status = 200) => ({ status, json: body });
+export const errorReply = (e) => ({ status: e.status, json: e.toProblem(), headers: e.headers });
+export class Router {
+    #routes = [];
+    add(route) {
+        if (this.#routes.some(r => r.route.method === route.method && r.route.path === route.path)) {
+            throw new Error(`Two routes for ${route.method} ${route.path}.`);
+        }
+        this.#routes.push({ route, segments: route.path.split('/') });
+    }
+    /** The route for a method and path, with its parameters; null when none matches. */
+    match(method, path) {
+        const parts = path.split('/');
+        for (const { route, segments } of this.#routes) {
+            if (route.method !== method || segments.length !== parts.length)
+                continue;
+            const params = {};
+            const fits = segments.every((s, i) => {
+                if (!s.startsWith(':'))
+                    return s === parts[i];
+                try {
+                    params[s.slice(1)] = decodeURIComponent(parts[i]);
+                }
+                catch {
+                    return false;
+                }
+                return parts[i] !== '';
+            });
+            if (fits)
+                return { route, params };
+        }
+        return null;
+    }
+}
+/** This machine, always a trusted proxy: a tunnel's connector runs here. */
+const LOOPBACK = ['127.0.0.0/8', '::1/128'].map(cidr => parseNetwork(cidr));
+/**
+ * The client's address. With no `clientIpHeader`, the connection's. With one, the header is a list each proxy
+ * appends the address it heard from to, so it is read from the right: while the address so far is a trusted
+ * proxy, the entry before it names who that proxy heard from. A client can write anything at the left of the
+ * list, but never past the last trusted hop, so no spoofed entry is reached; an entry that is not an address
+ * stops the walk.
+ */
+export function clientIp(req, { clientIpHeader, trustedProxies }) {
+    let ip = req.socket.remoteAddress ?? '';
+    if (!clientIpHeader)
+        return ip;
+    const named = req.headers[clientIpHeader];
+    const hops = typeof named === 'string' ? named.split(',').map(s => s.trim()) : [];
+    while (hops.length && (inNetworks(ip, LOOPBACK) || inNetworks(ip, trustedProxies))) {
+        const hop = hops.pop();
+        if (!isIP(hop))
+            break;
+        ip = hop;
+    }
+    return ip;
+}
+export function nodeListener(app, proxies) {
+    return (req, res) => {
+        const target = req.url ?? '/';
+        const path = target.split('?')[0];
+        const limit = app.bodyLimit(req.method ?? 'GET', path);
+        readBody(req, limit)
+            .then(body => body === null
+            ? errorReply(bodyTooLarge(limit))
+            : app.handle({
+                method: req.method ?? 'GET',
+                target,
+                path,
+                query: new URLSearchParams(target.includes('?') ? target.slice(target.indexOf('?') + 1) : ''),
+                params: {},
+                headers: req.headers,
+                body,
+                ip: clientIp(req, proxies),
+            }))
+            .then(reply => write(res, reply))
+            .catch(() => res.destroy());
+    };
+}
+/** The body, or null as soon as it passes `limit` bytes. */
+function readBody(req, limit) {
+    if (Number(req.headers['content-length'] ?? 0) > limit) {
+        req.resume();
+        return Promise.resolve(null);
+    }
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (c) => {
+            size += c.length;
+            if (size <= limit)
+                return void chunks.push(c);
+            req.removeAllListeners('data');
+            req.resume();
+            resolve(null);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks)));
+        req.on('error', reject);
+    });
+}
+function write(res, reply) {
+    const body = reply.bytes ?? (reply.json === undefined ? Buffer.alloc(0) : Buffer.from(canonicalize(reply.json)));
+    res.writeHead(reply.status, {
+        'content-type': reply.bytes ? 'application/octet-stream' : 'application/json',
+        'content-length': String(body.length),
+        ...reply.headers,
+    });
+    res.end(body);
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The basic SIMON server: the whole protocol and client API, with Node's standard library only. An
+ * application builds on it through `createServer`'s extensions and its `Store`, without editing the core.
+ */
+export { createServer, type SimonServer, type ServerOptions } from './server.ts';
+export { defineConfig, loadConfig, DEFAULT_RATES, type Config, type ConfigInput, type Rate, type RateName, } from './config.ts';
+export type { MailboxNote, MailboxSender } from './context.ts';
+export type { AddressDecision, AddressRequest, Arrival, Decision, Events, Extension, Listeners, Log, PrincipalAnswer, PrincipalRequest, ReaderDecision, ReaderRequest, ServerApi, Upload, } from './extensions.ts';
+export { json, type Reply, type Request, type Route } from './http.ts';
+export { systemDns, DnsFailure, type Dns } from './net/dns.ts';
+export { guardedHttp, Unreachable, type Http, type HttpRequest, type HttpResponse } from './net/fetch.ts';
+export { clientKey, isBlockedAddress } from './net/ip.ts';
+export { SqliteStore } from './store/sqlite.ts';
+export { MAX_STORED_KEYS, StoreCapacityError, resolveRetractionCapacity, type RetractionCapacity, } from './store/store.ts';
+export type { Agent, AgentKey, AgentAdmission, Delivery, HeldSignal, PartFetch, PartSource, Page, QueuedArrival, Store, StoredMessage, SweepCounts, SyncEntry, SyncPage, Webhook, } from './store/store.ts';

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * The basic SIMON server: the whole protocol and client API, with Node's standard library only. An
+ * application builds on it through `createServer`'s extensions and its `Store`, without editing the core.
+ */
+export { createServer } from "./server.js";
+export { defineConfig, loadConfig, DEFAULT_RATES, } from "./config.js";
+export { json } from "./http.js";
+export { systemDns, DnsFailure } from "./net/dns.js";
+export { guardedHttp, Unreachable } from "./net/fetch.js";
+export { clientKey, isBlockedAddress } from "./net/ip.js";
+export { SqliteStore } from "./store/sqlite.js";
+export { MAX_STORED_KEYS, StoreCapacityError, resolveRetractionCapacity, } from "./store/store.js";

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * The server as a process: `node server/src/main.ts`, or `simon-server` installed from npm. Configuration
+ * comes from the environment (see config.ts or README.md); storage is the sqlite file SIMON_DB.
+ * `simon-server help` prints how to run it and exits.
+ */
+import { loadConfig } from "./config.js";
+import { createServer } from "./server.js";
+import { SqliteStore } from "./store/sqlite.js";
+const [command] = process.argv.slice(2);
+if (command === 'help' || command === '--help' || command === '-h') {
+    process.stdout.write(`simon-server: the SIMON reference server, configured by the environment.
+
+  SIMON_ORIGIN=https://simon.example.com SIMON_SERVER_KEY=<alg>:<seed> simon-server
+
+  SIMON_ORIGIN         this server's origin                                   required
+  SIMON_SERVER_KEY     the signing key, <alg>:<base64url 32-byte seed>        or SIMON_SERVER_KEY_FILE
+  SIMON_DB             the sqlite file (default simon.sqlite)
+  SIMON_PORT           the port to listen on (default 8080)
+  SIMON_DEV=1          development: http and local hosts, a throwaway key
+
+Every setting: https://github.com/agnt-ai/simon-protocol/tree/main/server#readme
+`);
+    process.exit(0);
+}
+if (command !== undefined) {
+    console.error(`simon-server: unknown command ${command}; "simon-server help" says how to run it.`);
+    process.exit(2);
+}
+const config = loadConfig();
+const store = new SqliteStore(config.database);
+const server = createServer({ config, store, retiredAgentDocuments: config.retiredAgentDocuments });
+const port = await server.listen();
+console.error(JSON.stringify({ level: 'info', message: 'listening', origin: config.origin, port, dev: config.dev }));
+for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.once(signal, async () => {
+        await server.close();
+        await store.close();
+        process.exit(0);
+    });
+}

package/dist/net/dns.d.ts

@@ -0,0 +1,31 @@
+/**
+ * DNS through c-ares (node:dns Resolver), never getaddrinfo: every query has a timeout, and an absence
+ * (NXDOMAIN, no records) is told apart from a failure that may pass (SERVFAIL, a timeout, a refusal), as
+ * resolution requires (spec section 3).
+ *
+ * With two or more DNS-over-HTTPS resolvers configured, every TXT answer is confirmed: c-ares and each
+ * resolver must return the same records, or the answer is a failure that may pass (spec section 11.1).
+ * A validating resolver answers SERVFAIL for a DNSSEC failure, which is therefore temporary too.
+ */
+import { Resolver } from 'node:dns/promises';
+export interface Dns {
+    /** TXT records at a name, each as its character strings; [] when there are none. Throws on a failure. */
+    txt(name: string): Promise<string[][]>;
+    /** The A and AAAA addresses of a host; [] when it does not exist. Throws on a failure. */
+    addresses(host: string): Promise<string[]>;
+}
+/** A DNS answer that may change: retried later, never read as "none". */
+export declare class DnsFailure extends Error {
+    constructor(message: string);
+}
+/** The c-ares calls used, so tests can stand in for them. */
+export type Lookups = Pick<Resolver, 'resolveTxt' | 'resolve4' | 'resolve6'>;
+export declare function systemDns(opts?: {
+    timeoutMs?: number;
+    doh?: string[];
+    servers?: string[];
+    resolver?: Lookups;
+    fetch?: typeof fetch;
+}): Dns;
+/** A TXT record's character strings from presentation form (`"a" "b\"c"`); unquoted text is one string. */
+export declare function txtStrings(data: string): string[];

package/dist/net/dns.js

@@ -0,0 +1,100 @@
+/**
+ * DNS through c-ares (node:dns Resolver), never getaddrinfo: every query has a timeout, and an absence
+ * (NXDOMAIN, no records) is told apart from a failure that may pass (SERVFAIL, a timeout, a refusal), as
+ * resolution requires (spec section 3).
+ *
+ * With two or more DNS-over-HTTPS resolvers configured, every TXT answer is confirmed: c-ares and each
+ * resolver must return the same records, or the answer is a failure that may pass (spec section 11.1).
+ * A validating resolver answers SERVFAIL for a DNSSEC failure, which is therefore temporary too.
+ */
+import { Resolver } from 'node:dns/promises';
+/** A DNS answer that may change: retried later, never read as "none". */
+export class DnsFailure extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DnsFailure';
+    }
+}
+const ABSENT = new Set(['ENOTFOUND', 'ENODATA']);
+export function systemDns(opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 3000;
+    const resolver = opts.resolver ?? cares(timeoutMs, opts.servers ?? []);
+    const get = opts.fetch ?? fetch;
+    async function query(name, lookup) {
+        try {
+            return await lookup();
+        }
+        catch (e) {
+            const code = e.code ?? '';
+            if (ABSENT.has(code))
+                return [];
+            throw new DnsFailure(`${name}: ${code || e.message}`);
+        }
+    }
+    return {
+        async txt(name) {
+            const [local, ...confirmations] = await Promise.all([
+                query(name, () => resolver.resolveTxt(name)),
+                ...(opts.doh ?? []).map(url => dohTxt(get, url, name, timeoutMs)),
+            ]);
+            const answer = recordSet(local);
+            if (confirmations.some(c => recordSet(c) !== answer)) {
+                throw new DnsFailure(`${name}: resolvers disagree`);
+            }
+            return local;
+        },
+        async addresses(host) {
+            const results = await Promise.allSettled([resolver.resolve4(host), resolver.resolve6(host)]);
+            const found = results.flatMap(r => (r.status === 'fulfilled' ? r.value : []));
+            const failed = results.some(r => r.status === 'rejected' && !ABSENT.has(r.reason.code ?? ''));
+            if (!found.length && failed)
+                throw new DnsFailure(`${host}: address lookup failed`);
+            return found;
+        },
+    };
+}
+/** Records compared as resolution reads them: each joined, sorted. */
+const recordSet = (records) => JSON.stringify(records.map(r => r.join('')).sort());
+/**
+ * TXT records from a DNS-over-HTTPS JSON endpoint (`?name=&type=TXT`, as Google and Cloudflare serve).
+ * Status 0 is an answer, 3 (NXDOMAIN) is none, and anything else (2 is SERVFAIL, a DNSSEC failure at a
+ * validating resolver among them) is a failure.
+ */
+async function dohTxt(get, endpoint, name, timeoutMs) {
+    let body;
+    try {
+        const url = `${endpoint}?name=${encodeURIComponent(name)}&type=TXT&do=1`;
+        const res = await get(url, {
+            headers: { accept: 'application/dns-json' },
+            redirect: 'error',
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (res.status !== 200)
+            throw new Error(`HTTP ${res.status}`);
+        const text = await res.text();
+        if (text.length > 65_536)
+            throw new Error('answer too large');
+        body = JSON.parse(text);
+    }
+    catch (e) {
+        throw new DnsFailure(`${name} via ${endpoint}: ${e.message}`);
+    }
+    if (body.Status === 3)
+        return [];
+    if (body.Status !== 0)
+        throw new DnsFailure(`${name} via ${endpoint}: status ${body.Status}`);
+    return (body.Answer ?? []).filter(a => a.type === 16).map(a => txtStrings(a.data));
+}
+/** A TXT record's character strings from presentation form (`"a" "b\"c"`); unquoted text is one string. */
+export function txtStrings(data) {
+    if (!data.startsWith('"'))
+        return [data];
+    return [...data.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map(m => m[1].replace(/\\(\d{3}|.)/g, (_, c) => (c.length === 3 ? String.fromCharCode(Number(c)) : c)));
+}
+/** A c-ares resolver with a timeout, asking `servers` when given and the system's DNS servers otherwise. */
+function cares(timeoutMs, servers) {
+    const resolver = new Resolver({ timeout: timeoutMs, tries: 2 });
+    if (servers.length)
+        resolver.setServers(servers);
+    return resolver;
+}

package/dist/net/fetch.d.ts

@@ -0,0 +1,48 @@
+import type { Dns } from './dns.ts';
+import { type Network } from './ip.ts';
+export interface HttpRequest {
+    method: 'GET' | 'POST';
+    url: string;
+    headers?: Record<string, string>;
+    body?: Uint8Array;
+    /** The largest answer body accepted; a larger one fails the request. */
+    maxBytes: number;
+    /** The deadline for the whole exchange. */
+    timeoutMs?: number;
+    /** Refuse to connect to an address this answers true for, as if it refused the connection. */
+    avoid?: (address: string) => boolean;
+}
+export interface HttpResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: Buffer;
+}
+export interface Http {
+    request(r: HttpRequest): Promise<HttpResponse>;
+}
+/**
+ * Why a request got no answer:
+ *   absent       the host does not exist
+ *   forbidden    the URL or an address it resolves to is one this server must not call
+ *   refused      the connection was refused, or the address is one the caller avoids
+ *   certificate  the server's certificate is not valid for the host
+ *   connect      no connection within the connect timeout
+ *   timeout      connected, but no whole answer before the deadline
+ *   too_large    the answer is larger than `maxBytes`
+ *   failed       anything else that may pass: a DNS failure, a TLS failure, a reset
+ *
+ * `address` is the address a connection was tried to, when one was.
+ */
+export declare class Unreachable extends Error {
+    readonly kind: 'absent' | 'forbidden' | 'refused' | 'certificate' | 'connect' | 'timeout' | 'too_large' | 'failed';
+    readonly address?: string;
+    constructor(kind: Unreachable['kind'], message: string, address?: string);
+}
+export declare function guardedHttp(opts: {
+    dns: Dns;
+    dev?: boolean;
+    /** Networks whose addresses may be called although they are not public (config.trustedNetworks). */
+    trustedNetworks?: readonly Network[];
+    connectTimeoutMs?: number;
+    timeoutMs?: number;
+}): Http;

package/dist/net/fetch.js

@@ -0,0 +1,173 @@
+/**
+ * Outbound HTTP with an SSRF guard. Every request this server makes to a URL it did not choose (another
+ * server, a domain's well-known answer) goes through here:
+ *
+ *   - https only, TLS 1.3 or later; http and this machine's own addresses only in development;
+ *   - no address outside the public internet, except in the networks the operator trusts
+ *     (SIMON_TRUSTED_NETWORKS, for a private network such as a Tailscale tailnet);
+ *   - no credentials in the URL, no redirects followed;
+ *   - the host resolved through `Dns` (c-ares), every address checked, and the connection pinned to the
+ *     checked address, so a second lookup cannot swap in another one;
+ *   - a short connect timeout, a deadline for the whole exchange, and a cap on the answer's bytes;
+ *   - an address the caller knows is dead (`avoid`) is not connected to at all, so many names for one
+ *     tarpit cost one timeout, not one each.
+ */
+import http from 'node:http';
+import https from 'node:https';
+import net from 'node:net';
+import { inNetworks, isBlockedAddress, isLoopback } from "./ip.js";
+/**
+ * Why a request got no answer:
+ *   absent       the host does not exist
+ *   forbidden    the URL or an address it resolves to is one this server must not call
+ *   refused      the connection was refused, or the address is one the caller avoids
+ *   certificate  the server's certificate is not valid for the host
+ *   connect      no connection within the connect timeout
+ *   timeout      connected, but no whole answer before the deadline
+ *   too_large    the answer is larger than `maxBytes`
+ *   failed       anything else that may pass: a DNS failure, a TLS failure, a reset
+ *
+ * `address` is the address a connection was tried to, when one was.
+ */
+export class Unreachable extends Error {
+    kind;
+    address;
+    constructor(kind, message, address) {
+        super(message);
+        this.name = 'Unreachable';
+        this.kind = kind;
+        this.address = address;
+    }
+}
+/** Node's codes for a certificate that does not authenticate the host (RFC 9525). */
+const CERTIFICATE_ERRORS = new Set([
+    'ERR_TLS_CERT_ALTNAME_INVALID',
+    'CERT_HAS_EXPIRED',
+    'CERT_NOT_YET_VALID',
+    'DEPTH_ZERO_SELF_SIGNED_CERT',
+    'SELF_SIGNED_CERT_IN_CHAIN',
+    'UNABLE_TO_GET_ISSUER_CERT',
+    'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+    'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+    'CERT_REVOKED',
+    'CERT_UNTRUSTED',
+]);
+export function guardedHttp(opts) {
+    const connectTimeoutMs = opts.connectTimeoutMs ?? 3000;
+    const allowLocal = opts.dev ?? false;
+    const trusted = opts.trustedNetworks ?? [];
+    async function target(raw) {
+        let url;
+        try {
+            url = new URL(raw);
+        }
+        catch {
+            throw new Unreachable('forbidden', `not a URL: ${raw}`);
+        }
+        if (url.username || url.password)
+            throw new Unreachable('forbidden', 'credentials in a URL');
+        if (!(url.protocol === 'https:' || (allowLocal && url.protocol === 'http:'))) {
+            throw new Unreachable('forbidden', `${url.protocol} is not allowed`);
+        }
+        const host = url.hostname.replace(/^\[|\]$/g, '');
+        let addresses;
+        if (net.isIP(host))
+            addresses = [host];
+        else if (allowLocal && host === 'localhost')
+            addresses = ['127.0.0.1'];
+        else {
+            try {
+                addresses = await opts.dns.addresses(host);
+            }
+            catch (e) {
+                throw new Unreachable('failed', e.message);
+            }
+        }
+        if (!addresses.length)
+            throw new Unreachable('absent', `no such host: ${host}`);
+        const refused = addresses.find(a => isBlockedAddress(a) && !(allowLocal && isLoopback(a)) && !inNetworks(a, trusted));
+        if (refused)
+            throw new Unreachable('forbidden', `${host} resolves to ${refused}, not a public address`);
+        return { url, address: addresses[0] };
+    }
+    return {
+        async request(r) {
+            const deadline = r.timeoutMs ?? opts.timeoutMs ?? 10_000;
+            const abort = new AbortController();
+            const timer = setTimeout(() => abort.abort(new Unreachable('timeout', `no answer within ${deadline} ms`)), deadline);
+            try {
+                const t = await Promise.race([target(r.url), aborted(abort.signal)]);
+                if (r.avoid?.(t.address))
+                    throw new Unreachable('refused', `${t.address} is avoided`, t.address);
+                return await send(r, t, abort.signal, connectTimeoutMs);
+            }
+            catch (e) {
+                if (abort.signal.aborted)
+                    throw abort.signal.reason;
+                throw e instanceof Unreachable ? e : new Unreachable('failed', e.message);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+}
+const aborted = (signal) => new Promise((_, reject) => signal.addEventListener('abort', () => reject(signal.reason), { once: true }));
+function send(r, { url, address }, signal, connectTimeoutMs) {
+    const secure = url.protocol === 'https:';
+    return new Promise((resolve, reject) => {
+        const req = (secure ? https : http).request({
+            host: address,
+            port: url.port || (secure ? 443 : 80),
+            servername: net.isIP(url.hostname) ? undefined : url.hostname,
+            path: url.pathname + url.search,
+            method: r.method,
+            minVersion: 'TLSv1.3',
+            headers: { ...r.headers, host: url.host, ...(r.body ? { 'content-length': String(r.body.length) } : {}) },
+            agent: false,
+            signal,
+        });
+        req.on('socket', socket => {
+            const timer = setTimeout(() => {
+                req.destroy(new Unreachable('connect', `no connection to ${url.host} within ${connectTimeoutMs} ms`, address));
+            }, connectTimeoutMs);
+            socket.once(secure ? 'secureConnect' : 'connect', () => clearTimeout(timer));
+            socket.once('close', () => clearTimeout(timer));
+        });
+        req.on('response', res => {
+            const declared = Number(res.headers['content-length'] ?? 0);
+            if (declared > r.maxBytes) {
+                res.destroy();
+                return reject(new Unreachable('too_large', `answer larger than ${r.maxBytes} bytes`));
+            }
+            const chunks = [];
+            let size = 0;
+            res.on('data', (c) => {
+                size += c.length;
+                if (size <= r.maxBytes)
+                    return void chunks.push(c);
+                res.destroy();
+                reject(new Unreachable('too_large', `answer larger than ${r.maxBytes} bytes`));
+            });
+            res.on('end', () => {
+                const headers = {};
+                for (const [k, v] of Object.entries(res.headers))
+                    headers[k] = Array.isArray(v) ? v.join(', ') : String(v ?? '');
+                resolve({ status: res.statusCode ?? 0, headers, body: Buffer.concat(chunks) });
+            });
+            res.on('error', reject);
+        });
+        req.on('error', e => {
+            if (e instanceof Unreachable)
+                return reject(e);
+            const code = e.code ?? '';
+            const kind = ['ECONNREFUSED', 'EHOSTUNREACH', 'ENETUNREACH'].includes(code)
+                ? 'refused'
+                : CERTIFICATE_ERRORS.has(code)
+                    ? 'certificate'
+                    : 'failed';
+            reject(new Unreachable(kind, e.message, address));
+        });
+        req.end(r.body);
+    });
+}

package/dist/net/ip.d.ts

@@ -0,0 +1,38 @@
+/** The eight 16-bit groups of an IPv6 address in any spelling (embedded IPv4 included), or null. */
+export declare function v6Groups(ip: string): number[] | null;
+/**
+ * Whether this server must not connect to an address. IPv6 forms that reach IPv4 are judged by the IPv4
+ * they reach (mapped, compatible, SIIT), and those that reach arbitrary IPv4 are refused outright (NAT64,
+ * 6to4, Teredo), as are unique-local, link-local, site-local, multicast and documentation ranges.
+ */
+export declare function isBlockedAddress(ip: string): boolean;
+/** A network an operator trusts: an address range in CIDR notation, parsed. */
+export interface Network {
+    /** The network as written in canonical form: `100.64.0.0/10`, `fd7a:115c:a1e0:0:0:0:0:0/48`. */
+    cidr: string;
+    /** The address as 16-bit groups: two for IPv4, eight for IPv6. */
+    groups: number[];
+    prefix: number;
+}
+/** The narrowest prefix a trusted network may have: /8 and longer, for IPv4 and IPv6 alike. */
+export declare const NARROWEST_TRUSTED_PREFIX = 8;
+/**
+ * A network from CIDR notation (`address/prefix`), or a reason it is refused: not CIDR, broader than /8,
+ * with bits set after the prefix (`100.64.0.1/10` is a host, not a network), or IPv4 written as mapped
+ * IPv6, which `inNetworks` judges as IPv4 and so would never match.
+ */
+export declare function parseNetwork(text: string): Network | string;
+/** Whether an address is inside one of the networks. An IPv4-mapped IPv6 address is judged as its IPv4. */
+export declare function inNetworks(ip: string, networks: readonly Network[]): boolean;
+/** Whether an address is this machine: allowed only in development. */
+export declare const isLoopback: (ip: string) => boolean;
+/**
+ * The key a client is rate-limited under: an IPv4 address as is, an IPv6 address by its /64, since one
+ * subscriber holds a whole /64. An IPv4-mapped IPv6 address counts as its IPv4.
+ */
+export declare function clientKey(ip: string): string;
+/**
+ * The network a client is in, wider than `clientKey`: an IPv4 address by its /24, an IPv6 address by its /48.
+ * What one party needs many of to look like many, so a bound kept per network holds for carriers it makes up.
+ */
+export declare function networkKey(ip: string): string;