@johnhenry/sitefile 0.0.0 → 0.0.1

package/lib/src/plugins/cache.js

@@ -5,15 +5,21 @@ import { sha256 } from '../digest.js';
 /**
  * Content-addressed cache of TRANSFORM results (see docs/PLUGINS.md, "Caching").
  *
- *   <dir>/entries/<key>.json   manifest: which blobs make up the result
+ *   <dir>/entries/<key>.json   manifest: which blobs make up the result, and the
+ *                              PLUGIN or TOOL that produced it ("plugin")
  *   <dir>/blobs/<hex>          result bytes, named by their SHA-256
  *
  * The key is the SHA-256 of a canonical JSON document describing everything the
  * result can depend on. Reads verify every blob's digest and size; a damaged
  * entry is removed and counts as a miss, so the next put rewrites it.
+ * "plugin" is optional (entries written before it was recorded have none and are
+ * still read) and not part of the key.
  */
 /** Bump to invalidate every existing entry when the key or entry format changes. */
 export const CACHE_VERSION = 1;
+function manifestOf(version, kind, files, plugin) {
+    return plugin === undefined ? { version, kind, files } : { version, kind, files, plugin };
+}
 /** JSON with sorted object keys, so equal values always serialize equally. */
 export function canonicalJson(value) {
     const norm = (v) => {
@@ -51,7 +57,8 @@ export class TransformCache {
     blobPath(hex) {
         return path.join(this.dir, 'blobs', hex);
     }
-    async get(key) {
+    /** `plugin`: the TRANSFORM's PLUGIN or TOOL, recorded on an entry fetched from the remote cache. */
+    async get(key, plugin) {
         const file = this.entryPath(key);
         let raw;
         try {
@@ -63,7 +70,7 @@ export class TransformCache {
                 this.stats.misses++;
                 return undefined;
             }
-            const m = { version: CACHE_VERSION, kind: fetched.kind, files: fetched.files };
+            const m = manifestOf(CACHE_VERSION, fetched.kind, fetched.files, plugin);
             raw = JSON.stringify(m);
             await this.writeAtomic(file, raw, false).catch(() => { });
         }
@@ -112,7 +119,8 @@ export class TransformCache {
         const result = m.kind === 'file' ? { kind: 'file', bytes: loaded[0][1] } : { kind: 'files', files: loaded };
         return { result, entry: { kind: m.kind, files: m.files.map((f) => [f[0], f[1], f[2]]) } };
     }
-    async put(key, result) {
+    /** `plugin`: the PLUGIN or TOOL that produced the result (see `usageByPlugin`, `prunePlugin`). */
+    async put(key, result, plugin) {
         try {
             const pairs = result.kind === 'file' ? [['', result.bytes]] : result.files;
             const files = [];
@@ -121,7 +129,7 @@ export class TransformCache {
                 await this.writeAtomic(this.blobPath(hex), bytes, true);
                 files.push([p, hex, bytes.byteLength]);
             }
-            const manifest = { version: CACHE_VERSION, kind: result.kind, files };
+            const manifest = manifestOf(CACHE_VERSION, result.kind, files, plugin);
             await this.writeAtomic(this.entryPath(key), JSON.stringify(manifest), false);
             this.stats.writes++;
             this.remote?.used(key, { kind: result.kind, files });
@@ -198,6 +206,97 @@ export class TransformCache {
         }
         return { entries: removedEntries, blobs: removedBlobs, bytes };
     }
+    /**
+     * Remove the entries `plugin` (a PLUGIN or TOOL name) wrote that were not used for `olderThanMs`
+     * (0: all of them), then the blobs they used that no remaining entry references. Entries of other
+     * plugins, entries that record no plugin, and blobs no entry references yet are kept.
+     */
+    async prunePlugin(plugin, olderThanMs = 0, now = Date.now()) {
+        let removedEntries = 0;
+        const live = new Set();
+        const removed = new Set();
+        for (const n of await readdir(path.join(this.dir, 'entries')).catch(() => [])) {
+            const file = path.join(this.dir, 'entries', n);
+            const st = await stat(file).catch(() => undefined);
+            if (!st)
+                continue;
+            let m;
+            try {
+                m = JSON.parse(await readFile(file, 'utf8'));
+            }
+            catch {
+                continue;
+            }
+            const refs = Array.isArray(m?.files) ? m.files.map((f) => f[1]) : [];
+            const old = olderThanMs === 0 || now - st.mtimeMs >= olderThanMs;
+            if (old && m.plugin === plugin) {
+                await rm(file, { force: true });
+                removedEntries++;
+                for (const r of refs)
+                    removed.add(r);
+            }
+            else {
+                for (const r of refs)
+                    live.add(r);
+            }
+        }
+        let removedBlobs = 0;
+        let bytes = 0;
+        for (const n of removed) {
+            if (live.has(n))
+                continue;
+            const file = path.join(this.dir, 'blobs', n);
+            const st = await stat(file).catch(() => undefined);
+            if (!st?.isFile())
+                continue;
+            await rm(file, { force: true });
+            removedBlobs++;
+            bytes += st.size;
+        }
+        return { entries: removedEntries, blobs: removedBlobs, bytes };
+    }
+    /** Entries, blobs and bytes per plugin, sorted by name (entries that record none first). Reads no blob. */
+    async usageByPlugin() {
+        const by = new Map();
+        for (const n of await readdir(path.join(this.dir, 'entries')).catch(() => [])) {
+            if (!n.endsWith('.json'))
+                continue;
+            let m;
+            try {
+                m = JSON.parse(await readFile(path.join(this.dir, 'entries', n), 'utf8'));
+            }
+            catch {
+                continue;
+            }
+            if (!Array.isArray(m?.files))
+                continue;
+            const name = typeof m.plugin === 'string' ? m.plugin : undefined;
+            const slot = by.get(name) ?? { entries: 0, blobs: new Set() };
+            slot.entries++;
+            for (const f of m.files)
+                if (typeof f?.[1] === 'string')
+                    slot.blobs.add(f[1]);
+            by.set(name, slot);
+        }
+        // (Array.prototype.sort puts undefined last without asking the comparator.)
+        const named = [...by.keys()].filter((k) => k !== undefined).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        const names = by.has(undefined) ? [undefined, ...named] : named;
+        const out = [];
+        for (const plugin of names) {
+            const slot = by.get(plugin);
+            let blobs = 0;
+            let bytes = 0;
+            for (const hex of slot.blobs) {
+                const st = await stat(this.blobPath(hex)).catch(() => undefined);
+                if (st?.isFile()) {
+                    blobs++;
+                    bytes += st.size;
+                }
+            }
+            out.push({ plugin, entries: slot.entries, blobs, bytes });
+        }
+        return out;
+    }
 }
 /** Digest of every regular file under `dir` (a plugin can read all of them, so any may change its output). */
 export async function digestFolder(dir, limits = { files: 2000, bytes: 128 * 1024 * 1024 }) {

package/lib/src/registry.d.ts

@@ -1,6 +1,7 @@
 import type { Readable } from 'node:stream';
 import { type Descriptor } from './oci.js';
 import type { Credentials } from './registry-auth.js';
+import { type NetworkSettings } from './resources/network.js';
 /**
  * Client for the OCI distribution API (distribution-spec v1.1): `/v2/` probe, Bearer-token and Basic
  * auth, manifest and blob GET/HEAD, monolithic blob upload, cross-repository mount, manifest PUT.
@@ -40,6 +41,11 @@ export interface RegistryOptions {
     readonly limits?: Partial<RegistryLimits> | undefined;
     /** Extra PEM CA certificate(s) (tests / private CAs). */
     readonly ca?: string | Buffer | undefined;
+    /**
+     * Proxy, host rules and timeouts (see {@link NetworkSettings}); the host rules apply to every
+     * request, the registry's own included. `readTimeoutMs` replaces `limits.timeoutMs`.
+     */
+    readonly network?: NetworkSettings | undefined;
 }
 export interface Body {
     readonly length: number;

package/lib/src/registry.js

@@ -7,7 +7,8 @@ import { sha256 } from './digest.js';
 import { SitefileError, isSitefileError } from './errors.js';
 import { MEDIA } from './oci.js';
 import { registryApiHost } from './ref.js';
-import { createGuardedLookup, redactUrl } from './resources/https.js';
+import { armTimeouts, createGuardedLookup, redactUrl, routeRequest } from './resources/https.js';
+import { checkHostRules } from './resources/network.js';
 import { isPublicAddress } from './resources/netpolicy.js';
 import { DEFAULT_FETCH_POLICY } from './resources/types.js';
 export const DEFAULT_REGISTRY_LIMITS = {
@@ -97,7 +98,8 @@ export class RegistryClient {
         this.registry = registry;
         this.options = options;
         this.host = registryApiHost(registry);
-        this.limits = { ...DEFAULT_REGISTRY_LIMITS, ...options.limits };
+        const read = options.network?.readTimeoutMs;
+        this.limits = { ...DEFAULT_REGISTRY_LIMITS, ...options.limits, ...(read ? { timeoutMs: read } : {}) };
         this.loopback = isLoopbackHost(hostnameOf(this.host));
         this.insecure = this.loopback || (options.insecureRegistries ?? []).some((h) => h.toLowerCase() === this.host.toLowerCase() || h.toLowerCase() === registry.toLowerCase());
     }
@@ -120,31 +122,48 @@ export class RegistryClient {
             throw new SitefileError('E_SSRF_BLOCKED', `${this.registry}: refusing to connect to non-public address ${host} (${redactUrl(u)}); use --allow-private-network to permit it`);
         }
     }
-    sendOnce(method, url, headers, body, timeoutMs) {
+    async sendOnce(method, url, headers, body, timeoutMs) {
+        const shown = redactUrl(url);
+        const network = this.options.network;
+        checkHostRules(url, network, shown);
+        const same = this.sameOrigin(url);
+        const host = url.hostname.replace(/^\[|\]$/g, '');
+        const loopbackPair = this.loopback && isLoopbackHost(host);
+        const policy = { ...DEFAULT_FETCH_POLICY, allowPrivateNetwork: same || loopbackPair || !!this.options.allowPrivateNetwork, network };
+        const h = { 'accept-encoding': 'identity', 'user-agent': 'sitefile/0.1', ...headers };
+        if (body)
+            h['content-length'] = String(body.length);
+        const o = { method, headers: h, lookup: createGuardedLookup(policy), agent: false, timeout: timeoutMs };
+        if (url.protocol === 'https:' && this.options.ca !== undefined) {
+            const get = tls.getCACertificates;
+            o.ca = [...(get ? get('default') : tls.rootCertificates), this.options.ca];
+        }
+        // The idle timeout is the request's own (`timeout`); only the connect timeout comes from `network`.
+        const connectOnly = network?.connectTimeoutMs ? { connectTimeoutMs: network.connectTimeoutMs } : undefined;
+        const connectTimeout = () => new SitefileError('E_FETCH_TIMEOUT', `${method} ${shown}: connecting timed out after ${network?.connectTimeoutMs} ms (connect timeout)`);
+        const idleTimeout = () => new SitefileError('E_FETCH_TIMEOUT', `${method} ${shown} timed out after ${timeoutMs} ms`);
+        const route = await routeRequest(url, o, policy, {
+            shown,
+            fail: (e) => (e.detail.endsWith('(connect timeout)') ? connectTimeout() : idleTimeout()),
+        }).catch((e) => {
+            // Proxy failures are registry transport failures (an insecure registry then falls back to http).
+            if (isSitefileError(e))
+                throw e.code === 'E_FETCH' ? new SitefileError('E_REGISTRY', e.detail, undefined, { cause: e }) : e;
+            throw new SitefileError('E_REGISTRY', `${method} ${shown} failed: ${e.message}`, undefined, { cause: e });
+        });
         return new Promise((resolve, reject) => {
-            const same = this.sameOrigin(url);
-            const host = url.hostname.replace(/^\[|\]$/g, '');
-            const loopbackPair = this.loopback && isLoopbackHost(host);
-            const policy = { ...DEFAULT_FETCH_POLICY, allowPrivateNetwork: same || loopbackPair || !!this.options.allowPrivateNetwork };
-            const h = { 'accept-encoding': 'identity', 'user-agent': 'sitefile/0.1', ...headers };
-            if (body)
-                h['content-length'] = String(body.length);
-            const o = { method, headers: h, lookup: createGuardedLookup(policy), agent: false, timeout: timeoutMs };
-            if (url.protocol === 'https:' && this.options.ca !== undefined) {
-                const get = tls.getCACertificates;
-                o.ca = [...(get ? get('default') : tls.rootCertificates), this.options.ca];
-            }
             let req;
             try {
-                req = (url.protocol === 'https:' ? httpsRequest : httpRequest)(url, o);
+                req = route.url ? route.fn(route.url, route.options) : route.fn(route.options);
             }
             catch (e) {
-                reject(new SitefileError('E_REGISTRY', `cannot request ${redactUrl(url)}: ${e.message}`, undefined, { cause: e }));
+                reject(new SitefileError('E_REGISTRY', `cannot request ${shown}: ${e.message}`, undefined, { cause: e }));
                 return;
             }
-            req.on('timeout', () => req.destroy(new SitefileError('E_FETCH_TIMEOUT', `${method} ${redactUrl(url)} timed out after ${timeoutMs} ms`)));
+            armTimeouts(req, connectOnly, route.proxied, () => req.destroy(connectTimeout()));
+            req.on('timeout', () => req.destroy(idleTimeout()));
             req.on('response', resolve);
-            req.on('error', (e) => reject(unwrap(e) ?? new SitefileError('E_REGISTRY', `${method} ${redactUrl(url)} failed: ${e.message}`, undefined, { cause: e })));
+            req.on('error', (e) => reject(unwrap(e) ?? new SitefileError('E_REGISTRY', `${method} ${shown} failed: ${e.message}`, undefined, { cause: e })));
             if (!body) {
                 req.end();
                 return;

package/lib/src/resources/https.d.ts

@@ -1,6 +1,8 @@
+import { request as httpRequest, type ClientRequest, type RequestOptions } from 'node:http';
 import { type LookupFunction } from 'node:net';
-import { type SourceSpan } from '../errors.js';
+import { SitefileError, type SourceSpan } from '../errors.js';
 import type { FetchPolicy } from './types.js';
+import { type NetworkSettings } from './network.js';
 export interface FetchResult {
     readonly bytes: Uint8Array;
     /** URL of the final hop after redirects. */
@@ -38,3 +40,35 @@ export declare function createGuardedLookup(policy: FetchPolicy, span?: SourceSp
  * whole fetch.
  */
 export declare function fetchRemote(url: string, policy: FetchPolicy, span?: SourceSpan, request?: FetchRequest): Promise<FetchResult>;
+/** How to send one request: directly, or through the configured proxy. */
+export interface Route {
+    readonly fn: typeof httpRequest;
+    /** The URL to pass to `fn`; undefined when `options` carry the proxy's host, port and absolute path. */
+    readonly url?: URL | undefined;
+    readonly options: RequestOptions;
+    /** True when the connection is to a proxy (the connect timeout then covers the tunnel). */
+    readonly proxied: boolean;
+}
+export interface RouteContext {
+    readonly signal?: AbortSignal | undefined;
+    readonly span?: SourceSpan | undefined;
+    /** The hop's URL as shown in messages. */
+    readonly shown: string;
+    /** Records a timeout error before the request is destroyed with it. */
+    readonly fail?: ((e: SitefileError) => SitefileError) | undefined;
+}
+/** E_FETCH_TIMEOUT for a connect or read (idle) timeout. */
+export declare function hopTimeout(kind: 'connect' | 'read', shown: string, network: NetworkSettings | undefined, span?: SourceSpan): SitefileError;
+/**
+ * Apply `network`'s connect timeout (until the TCP connection is up) and read timeout (socket idle time
+ * once connected) to a request; `onTimeout` destroys it. For a tunnelled request the socket is already
+ * connected (the tunnel had the connect timeout), so only the read timeout applies.
+ */
+export declare function armTimeouts(req: ClientRequest, network: NetworkSettings | undefined, _proxied: boolean, onTimeout: (kind: 'connect' | 'read') => void): void;
+/**
+ * Route one request: directly (with the guarded lookup in `options`), or through `policy.network.proxy`
+ * unless the host is in its no-proxy list. Through a proxy, the target host is still resolved here and
+ * refused if it is non-public (unless `allowPrivateNetwork`), so a proxy never widens the policy; the
+ * proxy itself is named by the user and may be on a private address.
+ */
+export declare function routeRequest(url: URL, options: RequestOptions, policy: FetchPolicy, ctx: RouteContext): Promise<Route>;

package/lib/src/resources/https.js

@@ -5,6 +5,7 @@ import * as tls from 'node:tls';
 import { isIP } from 'node:net';
 import { SitefileError, isSitefileError } from '../errors.js';
 import { isPublicAddress } from './netpolicy.js';
+import { checkHostRules, proxyFor } from './network.js';
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 const USER_AGENT = 'sitefile/0.1';
 /** A URL rendered without any userinfo, safe for error messages. */
@@ -37,6 +38,7 @@ export function validateHop(url, policy, span) {
     const host = stripBrackets(url.hostname);
     if (host === '')
         throw new SitefileError('E_PROTOCOL', `URL ${redactUrl(url)} has no host`, span);
+    checkHostRules(url, policy.network, redactUrl(url), span);
     if (isIP(host) !== 0 && !policy.allowPrivateNetwork && !isPublicAddress(host)) {
         throw new SitefileError('E_SSRF_BLOCKED', `refusing to connect to non-public address ${host} (${redactUrl(url)}); use --allow-private-network to permit it`, span);
     }
@@ -184,6 +186,8 @@ export async function fetchRemote(url, policy, span, request = {}) {
                     throw e;
                 if (controller.signal.aborted)
                     throw timeoutError();
+                if (state.failure)
+                    throw state.failure;
                 throw new SitefileError('E_FETCH', `error reading ${redactUrl(current)}: ${e.message}`, span, {
                     cause: e,
                 });
@@ -203,32 +207,47 @@ export async function fetchRemote(url, policy, span, request = {}) {
         state.req?.destroy();
     }
 }
-function openHop(url, policy, signal, state, span, timeoutError, method, extra, body) {
+async function openHop(url, policy, signal, state, span, timeoutError, method, extra, body) {
+    const options = {
+        method,
+        headers: { 'accept-encoding': 'identity', 'user-agent': USER_AGENT, accept: '*/*', ...extra, ...(body ? { 'content-length': String(body.byteLength) } : {}) },
+        lookup: createGuardedLookup(policy, span),
+        agent: false,
+        signal,
+    };
+    if (url.protocol === 'https:' && policy.ca !== undefined) {
+        // Additive: setting `ca` replaces Node's whole default store, so start from
+        // that store (bundled roots plus NODE_EXTRA_CA_CERTS / --use-system-ca),
+        // not just the bundled roots, and add the extra CA(s).
+        options.ca = [...defaultCaCertificates(), policy.ca];
+    }
+    const shown = redactUrl(url);
+    const fail = (e) => {
+        state.failure = e;
+        return e;
+    };
+    let route;
+    try {
+        route = await routeRequest(url, options, policy, { signal, span, shown, fail });
+    }
+    catch (e) {
+        if (signal.aborted)
+            throw timeoutError();
+        throw e;
+    }
     return new Promise((resolve, reject) => {
-        const options = {
-            method,
-            headers: { 'accept-encoding': 'identity', 'user-agent': USER_AGENT, accept: '*/*', ...extra, ...(body ? { 'content-length': String(body.byteLength) } : {}) },
-            lookup: createGuardedLookup(policy, span),
-            agent: false,
-            signal,
-        };
-        if (url.protocol === 'https:' && policy.ca !== undefined) {
-            // Additive: setting `ca` replaces Node's whole default store, so start from
-            // that store (bundled roots plus NODE_EXTRA_CA_CERTS / --use-system-ca),
-            // not just the bundled roots, and add the extra CA(s).
-            options.ca = [...defaultCaCertificates(), policy.ca];
-        }
-        const requestFn = url.protocol === 'https:' ? httpsRequest : httpRequest;
         let req;
         try {
-            req = requestFn(url, options);
+            req = route.url ? route.fn(route.url, route.options) : route.fn(route.options);
         }
         catch (e) {
-            reject(new SitefileError('E_FETCH', `cannot request ${redactUrl(url)}: ${e.message}`, span, { cause: e }));
+            reject(new SitefileError('E_FETCH', `cannot request ${shown}: ${e.message}`, span, { cause: e }));
             return;
         }
         state.req = req;
         state.res = undefined;
+        state.failure = undefined;
+        armTimeouts(req, policy.network, route.proxied, (kind) => req.destroy(fail(hopTimeout(kind, shown, policy.network, span))));
         req.on('response', (res) => {
             state.res = res;
             resolve(res);
@@ -243,11 +262,149 @@ function openHop(url, policy, signal, state, span, timeoutError, method, extra,
                 reject(inner);
                 return;
             }
-            reject(new SitefileError('E_FETCH', `fetching ${redactUrl(url)} failed: ${e.message}`, span, { cause: e }));
+            reject(new SitefileError('E_FETCH', `fetching ${shown} failed: ${e.message}`, span, { cause: e }));
         });
         req.end(body);
     });
 }
+/** E_FETCH_TIMEOUT for a connect or read (idle) timeout. */
+export function hopTimeout(kind, shown, network, span) {
+    return kind === 'connect'
+        ? new SitefileError('E_FETCH_TIMEOUT', `fetching ${shown}: connecting timed out after ${network?.connectTimeoutMs} ms (connect timeout)`, span)
+        : new SitefileError('E_FETCH_TIMEOUT', `fetching ${shown}: no data for ${network?.readTimeoutMs} ms (read timeout)`, span);
+}
+/**
+ * Apply `network`'s connect timeout (until the TCP connection is up) and read timeout (socket idle time
+ * once connected) to a request; `onTimeout` destroys it. For a tunnelled request the socket is already
+ * connected (the tunnel had the connect timeout), so only the read timeout applies.
+ */
+export function armTimeouts(req, network, _proxied, onTimeout) {
+    const connectMs = network?.connectTimeoutMs;
+    if (connectMs) {
+        const t = setTimeout(() => onTimeout('connect'), connectMs);
+        t.unref?.();
+        const clear = () => clearTimeout(t);
+        req.once('socket', (socket) => {
+            if (socket.connecting)
+                socket.once('connect', clear);
+            else
+                clear();
+        });
+        req.once('close', clear);
+        req.once('error', clear);
+    }
+    const readMs = network?.readTimeoutMs;
+    if (readMs)
+        req.setTimeout(readMs, () => onTimeout('read'));
+}
+/** Resolve `hostname` and apply the private-address rule, as a direct connection would at connect time. */
+function checkResolved(hostname, policy, span) {
+    return new Promise((resolve, reject) => {
+        createGuardedLookup(policy, span)(hostname, { all: true }, (err) => {
+            if (!err) {
+                resolve();
+                return;
+            }
+            if (isSitefileError(err)) {
+                reject(err);
+                return;
+            }
+            reject(new SitefileError('E_FETCH', `cannot resolve ${hostname} to check it against the private-network rule before using the proxy: ${err.code ?? err.message}`, span));
+        });
+    });
+}
+/**
+ * Route one request: directly (with the guarded lookup in `options`), or through `policy.network.proxy`
+ * unless the host is in its no-proxy list. Through a proxy, the target host is still resolved here and
+ * refused if it is non-public (unless `allowPrivateNetwork`), so a proxy never widens the policy; the
+ * proxy itself is named by the user and may be on a private address.
+ */
+export async function routeRequest(url, options, policy, ctx) {
+    const https = url.protocol === 'https:';
+    const proxy = proxyFor(url, policy.network);
+    if (!proxy)
+        return { fn: https ? httpsRequest : httpRequest, url, options, proxied: false };
+    const host = url.hostname.replace(/^\[|\]$/g, '');
+    if (!policy.allowPrivateNetwork && isIP(host) === 0)
+        await checkResolved(host, policy, ctx.span);
+    const port = url.port !== '' ? Number(url.port) : https ? 443 : 80;
+    const { lookup: _lookup, agent: _agent, ...rest } = options;
+    if (!https) {
+        const target = new URL(url.href);
+        target.hash = '';
+        return {
+            fn: httpRequest,
+            options: {
+                ...rest,
+                host: proxy.host,
+                port: proxy.port,
+                path: target.href,
+                agent: false,
+                headers: { ...options.headers, host: url.host, ...(proxy.authorization ? { 'proxy-authorization': proxy.authorization } : {}) },
+            },
+            proxied: true,
+        };
+    }
+    const socket = await openTunnel(proxy, host, port, policy.network, ctx);
+    const ca = options.ca;
+    return {
+        fn: httpsRequest,
+        url,
+        options: {
+            ...rest,
+            createConnection: () => tls.connect({ socket, host, ...(isIP(host) === 0 ? { servername: host } : {}), ...(ca !== undefined ? { ca } : {}), ALPNProtocols: ['http/1.1'] }),
+        },
+        proxied: true,
+    };
+}
+/** A CONNECT tunnel to `host:port` through `proxy`. */
+function openTunnel(proxy, host, port, network, ctx) {
+    const authority = `${isIP(host) === 6 ? `[${host}]` : host}:${port}`;
+    return new Promise((resolve, reject) => {
+        let req;
+        try {
+            req = httpRequest({
+                host: proxy.host,
+                port: proxy.port,
+                method: 'CONNECT',
+                path: authority,
+                agent: false,
+                headers: { host: authority, 'user-agent': USER_AGENT, ...(proxy.authorization ? { 'proxy-authorization': proxy.authorization } : {}) },
+                ...(ctx.signal ? { signal: ctx.signal } : {}),
+            });
+        }
+        catch (e) {
+            reject(new SitefileError('E_FETCH', `fetching ${ctx.shown} failed: proxy ${proxy.shown}: ${e.message}`, ctx.span, { cause: e }));
+            return;
+        }
+        const record = ctx.fail ?? ((e) => e);
+        armTimeouts(req, network, true, (kind) => req.destroy(record(hopTimeout(kind, ctx.shown, network, ctx.span))));
+        const refused = (status) => status === 407
+            ? new SitefileError('E_FETCH', `proxy ${proxy.shown} requires authentication (HTTP 407)`, ctx.span)
+            : new SitefileError('E_FETCH', `proxy ${proxy.shown} refused to connect to ${authority}`, ctx.span);
+        req.on('connect', (res, socket, head) => {
+            if (res.statusCode !== 200) {
+                socket.destroy();
+                reject(refused(res.statusCode));
+                return;
+            }
+            socket.setTimeout(0);
+            socket.removeAllListeners('timeout');
+            if (head.length)
+                socket.unshift(head);
+            resolve(socket);
+        });
+        req.on('response', (res) => {
+            res.resume();
+            reject(refused(res.statusCode));
+        });
+        req.on('error', (e) => {
+            const inner = findSitefileError(e);
+            reject(inner ?? new SitefileError('E_FETCH', `fetching ${ctx.shown} failed: proxy ${proxy.shown}: ${e.message}`, ctx.span, { cause: e }));
+        });
+        req.end();
+    });
+}
 /** Node's default CA store; `tls.getCACertificates` exists from Node 22.15/23.5. */
 function defaultCaCertificates() {
     const get = tls.getCACertificates;

package/lib/src/resources/network.d.ts

@@ -0,0 +1,70 @@
+import { type SourceSpan } from '../errors.js';
+/**
+ * Explicit network settings for everything sitefile fetches (IMPORT over http(s), Git, registries).
+ * Nothing here is read from the environment implicitly: `HTTP(S)_PROXY` stays ignored, and the CLI
+ * reads `SITEFILE_PROXY` and friends through {@link networkFromEnv}. Embedders pass this in code
+ * (`FetchPolicy.network`, `RegistryOptions.network`).
+ */
+export interface NetworkSettings {
+    /** `http://[user:password@]host[:port]`: a CONNECT tunnel for https targets, absolute-form requests for http. */
+    readonly proxy?: string | undefined;
+    /** Hosts reached directly, never through the proxy (`NO_PROXY` syntax, see {@link hostMatches}). */
+    readonly noProxy?: readonly string[] | undefined;
+    /** When non-empty, only hosts matching one of these patterns may be contacted. */
+    readonly allowHosts?: readonly string[] | undefined;
+    /** Hosts never contacted; a deny rule beats an allow rule. */
+    readonly denyHosts?: readonly string[] | undefined;
+    /** Time limit for establishing the TCP connection (to the target, or to the proxy), ms. */
+    readonly connectTimeoutMs?: number | undefined;
+    /** Longest wait for data once connected (idle time), ms. */
+    readonly readTimeoutMs?: number | undefined;
+}
+/** A configured HTTP proxy, parsed. */
+export interface ProxyConfig {
+    readonly host: string;
+    readonly port: number;
+    /** `Basic …` when the URL carries credentials. */
+    readonly authorization?: string | undefined;
+    /** The proxy URL without credentials, for messages. */
+    readonly shown: string;
+}
+/** Split a list given as one string (commas and/or whitespace). */
+export declare function splitList(raw: string | undefined): string[];
+/** Parse a proxy URL, or throw E_USAGE. Credentials never appear in the message. */
+export declare function parseProxy(raw: string): ProxyConfig;
+/**
+ * True when `host` (as in a URL, IPv6 without brackets) on `port` matches `pattern`:
+ *   `*`                      every host
+ *   `example.com`            example.com and every subdomain (`.example.com` and `*.example.com` too)
+ *   `10.0.0.0/8`, `fd00::/8` IP-literal hosts in that network; `192.0.2.1`, `::1` that address
+ *   any of these + `:port`   only that port (`[::1]:8080` for IPv6)
+ * Patterns match the host as written in the URL: a name pattern never matches an IP literal and an
+ * IP pattern never matches a name, whatever it resolves to (the private-address rule covers that).
+ */
+export declare function hostMatches(host: string, port: number, pattern: string): boolean;
+/** Default port of an http(s) URL. */
+export declare function urlPort(url: URL): number;
+/**
+ * Apply the allow/deny host rules to one hop (every redirect, token realm and blob CDN hop included).
+ * Throws E_HOST_BLOCKED naming the rule; a deny rule beats an allow rule.
+ */
+export declare function checkHostRules(url: URL, network: NetworkSettings | undefined, shown: string, span?: SourceSpan): void;
+/** The proxy to use for `url`, or undefined for a direct connection (no proxy, or a no-proxy match). */
+export declare function proxyFor(url: URL, network: NetworkSettings | undefined): ProxyConfig | undefined;
+/** A usage problem in `network` (bad proxy URL, host pattern or timeout), or undefined. */
+export declare function networkProblem(network: NetworkSettings): string | undefined;
+/** Parse `SITEFILE_FETCH_TIMEOUT`: `<ms>` (connect and read) or `connect=<ms>,read=<ms>` (either part optional). */
+export declare function parseFetchTimeout(raw: string): {
+    connectTimeoutMs?: number;
+    readTimeoutMs?: number;
+};
+/**
+ * Network settings from `SITEFILE_PROXY`, `SITEFILE_NO_PROXY`, `SITEFILE_ALLOW_HOSTS`,
+ * `SITEFILE_DENY_HOSTS` (comma- or space-separated) and `SITEFILE_FETCH_TIMEOUT`. Empty values are unset.
+ * `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` are never read.
+ */
+export declare function networkFromEnv(env?: NodeJS.ProcessEnv): NetworkSettings;
+/** `over` on top of `base`: the proxy and timeouts are replaced, the host lists are joined (duplicates dropped). */
+export declare function mergeNetwork(base: NetworkSettings, over: NetworkSettings): NetworkSettings;
+/** True when any setting is present. */
+export declare function hasNetworkSettings(n: NetworkSettings | undefined): boolean;