@sigrun/sigrun 0.1.5 → 0.2.0

package/dist/server/helpers.js

@@ -8,6 +8,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, resolve } from "node:path";
 import { effectiveServerSection, } from "../config.js";
+import { pendingRestart } from "../settings/pending.js";
 import { DEFAULT_AUTH_KEY } from "../harness/auth.js";
 import { OPENAI_API_KEY_ENV } from "../harness/providers/index.js";
 import { SessionMetaDoc } from "./session-meta.js";
@@ -198,12 +199,15 @@ export const ID_PARAMS_SCHEMA = {
 /** The settings response over the live store + registry snapshot. */
 /**
  * The `/v1/settings` payload (GET and the post-PATCH readback): the
- * file's effective contents, the registry-computed `toolRoster`, and
- * the `effective` block (spec §6.6) — every server key's resolved value
- * and source, computed PER REQUEST over the fresh file read (a PATCH
- * lands as a `file` source on the next GET) and the boot env/config.
+ * file's effective contents, the registry-computed `toolRoster`, the
+ * `effective` block (spec §6.6), and the `pendingRestart` diff
+ * (UI-blocks U4 §13.2) — every server key's resolved value and source,
+ * computed PER REQUEST over the fresh file read (a PATCH lands as a
+ * `file` source on the next GET) and the boot env/config. A PATCH
+ * response additionally carries the write's own `applied`/`pending`
+ * classification (§13.1) via the optional `write` argument.
  */
-export function settingsResponse(opened, config, env) {
+export function settingsResponse(opened, config, env, write) {
     const names = opened.registry
         .snapshot()
         .tools()
@@ -215,6 +219,8 @@ export function settingsResponse(opened, config, env) {
         ...file,
         toolRoster: [...new Set(names)],
         effective: effectiveServerSection(env, file.server, config),
+        pendingRestart: pendingRestart(file, opened.settingsBootSnapshot),
+        ...(write === undefined ? {} : { applied: write.applied, pending: write.pending }),
     };
 }
 /** Re-brand a route id as a ConversationId (the branded Id type is a number). */
@@ -241,12 +247,18 @@ export async function readView(conversation) {
  * copied state (`fork: "current"`), so the caller's identity OVERWRITES
  * the source's.
  */
-export async function stampSessionOwner(conversation, owner) {
+export async function stampSessionOwner(conversation, owner, opened) {
     if (owner === undefined)
         return;
+    await stampOwnerInCommit(conversation, owner, opened);
+}
+/** Stamp/replace an owner and rewrite per-user selection in ONE commit. */
+export async function stampOwnerInCommit(conversation, owner, opened) {
     await conversation.commit(async (tx) => {
         const draft = await tx.doc(SessionMetaDoc, conversation.id);
+        const previous = draft.owner;
         draft.owner = owner;
+        await opened.rewriteUserSelection(tx, conversation.id, previous, owner);
     }, BACKGROUND_CONTEXT);
 }
 /**

package/dist/server/host-bridge.js

@@ -16,25 +16,22 @@
  * superuser's HTTP list does: every row visible, `access: "write"`.
  */
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
-import { accessOf as accessOfShared, } from "@sigrun/shared/access";
-import { isSuperuser } from "./auth/principal.js";
+import { accessOf as accessOfShared } from "@sigrun/shared/access";
+import { effectiveAdmin } from "../harness/identity/groups.js";
+import { userWire } from "./routes/users.js";
+import { accessPrincipalOf } from "./auth/access-principal.js";
 import { abortOp, compactOp, configureOp, ConversationOpError, createConversationOp, forkOp, listConversationsOp, patchMetaOp, readFileOp, readMetaOp, submitOp, uploadOp, } from "./conversation-ops.js";
 import { listModels } from "./helpers.js";
 import { SessionMetaDoc } from "./session-meta.js";
-import { serializeConversationView } from "./views.js";
+import { accountLinkWire, serializeConversationView } from "./views.js";
 /**
- * The effective-admin projection of one directory user (gateway C8):
- * host-side callers (chat commands, no request headers) see the STORED
- * flag OR the persisted group grant, plus the raw `groupAdmin` as a
- * definite boolean. The `/v1/users` wire keeps `admin` = the stored
- * flag (the users-admin UI toggles that one); the two surfaces are
- * deliberately different.
+ * Host-side callers see effective admin derived from stored groups;
+ * `groupAdmin` remains the derived compatibility field on the wire.
  */
-function effectiveAdminOf(record) {
+function effectiveAdminOf(record, adminGroups) {
     return {
-        ...record,
-        admin: record.admin || record.groupAdmin === true,
-        groupAdmin: record.groupAdmin === true,
+        ...userWire(record, adminGroups),
+        admin: effectiveAdmin(record, adminGroups),
     };
 }
 /** Build the host bridge over one server context. */
@@ -136,6 +133,7 @@ export function createHostBridge(ctx) {
                 await configureOp(ctx, conversation, {
                     ...(opts.model === undefined ? {} : { model: opts.model }),
                     ...(opts.thinking === undefined ? {} : { thinking: opts.thinking }),
+                    ...(opts.extensions === undefined ? {} : { extensions: opts.extensions }),
                 });
             },
             async compact(id) {
@@ -176,11 +174,36 @@ export function createHostBridge(ctx) {
             // admin-gated /v1/users routes) — with EFFECTIVE admin (gateway
             // C8): a persisted group grant counts for host-side checks.
             async list() {
-                return opened.identity.users.list().map(effectiveAdminOf);
+                return opened.identity.users.list().map((record) => effectiveAdminOf(record, ctx.config.auth.adminGroups));
             },
             async get(user) {
                 const record = opened.identity.users.get(user);
-                return record === undefined ? undefined : effectiveAdminOf(record);
+                return record === undefined ? undefined : effectiveAdminOf(record, ctx.config.auth.adminGroups);
+            },
+        },
+        accounts: {
+            // The one link table (multi-user §11.3): core code over core's
+            // store — the single write path, with the store's own validation
+            // and conflict refusal. `account_link_conflict:` errors cross the
+            // bridge as plain Errors (extensions match the message prefix).
+            async lookup(provider, subject) {
+                const link = opened.identity.accounts.lookup(provider, subject);
+                return link === undefined ? undefined : accountLinkWire(link);
+            },
+            async link(provider, subject, user, via) {
+                const link = await opened.identity.accounts.link({
+                    provider,
+                    subject,
+                    user,
+                    via,
+                });
+                return accountLinkWire(link);
+            },
+            async unlink(provider, subject) {
+                return await opened.identity.accounts.unlink(provider, subject);
+            },
+            async listForUser(user) {
+                return opened.identity.accounts.listForUser(user).map(accountLinkWire);
             },
         },
         access: {
@@ -190,10 +213,7 @@ export function createHostBridge(ctx) {
                 // directory admin is not a superuser for accessOf); the bare
                 // `{user}` shape is the shared rule's own principal.
                 const resolved = "admin" in principal
-                    ? {
-                        user: principal.user,
-                        superuser: isSuperuser(principal),
-                    }
+                    ? accessPrincipalOf(principal, opened.identity.users)
                     : { user: principal.user };
                 return accessOfShared(resolved, resource);
             },
@@ -241,7 +261,7 @@ export function createHostBridge(ctx) {
                     user: record.user,
                     ...(record.name === undefined ? {} : { name: record.name }),
                     ...(record.email === undefined ? {} : { email: record.email }),
-                    admin: effectiveAdminOf(record).admin,
+                    admin: effectiveAdmin(record, ctx.config.auth.adminGroups),
                     service: false,
                     method: "host",
                 };

package/dist/server/images/cache.js

@@ -0,0 +1,205 @@
+/**
+ * The image proxy's on-disk LRU cache (UI-blocks U7 Task 3, spec §11.2):
+ * entries live under `<cacheDir>/images/` (pod-local and outside backups,
+ * like the other cache roots), keyed by `sha256(u)` plus the `as`
+ * variant — NEVER the signed URL, whose signature changes on every
+ * serve. Capacity is 256 MiB by default; eviction is least-recently-hit
+ * first. Failures are never cached (callers `put` successful fetches
+ * only).
+ *
+ * Layout: each entry is one file `<sha256(u)>.<variant>` beside ONE
+ * `index.json` (the metadata table: type, size, added-at, last-hit,
+ * pin). The index is written atomically on every mutation, so a re-open
+ * (the same cache dir, a new process) serves the prior entries.
+ *
+ * Eviction never deletes a file currently being STREAMED or WRITTEN
+ * (Review Focus 5): a `get` hit pins its entry until the returned
+ * stream closes (or the caller's response finishes), and a `put` holds
+ * its pin for the write's duration; the eviction pass skips pinned
+ * entries and takes the next-oldest instead.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/** The images subdirectory under the cache root. */
+export const IMAGES_CACHE_DIR = "images";
+/** The default capacity: 256 MiB (spec §11.2). */
+export const CACHE_CAPACITY_BYTES = 256 * 1024 * 1024;
+/** The sha256-of-url + variant entry key (never the signed URL). */
+function entryKey(u, variant) {
+    return `${createHash("sha256").update(u, "utf8").digest("hex")}.${variant}`;
+}
+/**
+ * The `<cacheDir>/images/` LRU cache. Construct with the CACHE ROOT (the
+ * `images/` child is created lazily on the first put / at open when the
+ * index exists). `capacityBytes` is test-overridable; the default is the
+ * spec's 256 MiB.
+ */
+export class ImageCache {
+    dir;
+    indexPath;
+    capacityBytes;
+    entries = new Map();
+    opened = false;
+    closed = false;
+    constructor(cacheRoot, options) {
+        this.dir = join(cacheRoot, IMAGES_CACHE_DIR);
+        this.indexPath = join(this.dir, "index.json");
+        this.capacityBytes = options?.capacityBytes ?? CACHE_CAPACITY_BYTES;
+    }
+    /** Open: load the index (creating the dir lazily). Idempotent. */
+    async open() {
+        if (this.opened)
+            return;
+        this.opened = true;
+        let raw;
+        try {
+            raw = await readFile(this.indexPath, "utf8");
+        }
+        catch (cause) {
+            if (cause.code === "ENOENT")
+                return;
+            throw cause;
+        }
+        // A corrupt index is rebuilt EMPTY (the files on disk are then
+        // orphaned until their names recur; a fresh fetch rewrites them).
+        // The cache is a cache: losing it is never an error worth
+        // refusing to boot over.
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        for (const [key, entry] of Object.entries(parsed.entries)) {
+            this.entries.set(key, { ...entry, pins: 0 });
+        }
+    }
+    /** One hit, or `undefined` on a miss. `now` stamps the LRU order. */
+    async get(u, variant, now) {
+        await this.open();
+        const key = entryKey(u, variant);
+        const entry = this.entries.get(key);
+        if (entry === undefined)
+            return undefined;
+        const file = join(this.dir, key);
+        try {
+            await stat(file);
+        }
+        catch {
+            // The index names a file that isn't there (a hand-cleaned dir):
+            // drop the row and miss.
+            this.entries.delete(key);
+            await this.persist();
+            return undefined;
+        }
+        entry.lastHit = now ?? Date.now();
+        entry.pins += 1;
+        await this.persist();
+        const stream = createReadStream(file);
+        const unpin = () => {
+            entry.pins -= 1;
+        };
+        stream.once("close", unpin);
+        stream.once("error", unpin);
+        return { type: entry.type, stream };
+    }
+    /**
+     * Store one fetched image. The write is staged and renamed (atomic:
+     * a concurrent `get` never reads a half-written file) and the entry
+     * is pinned for the write's duration — the eviction pass a same-key
+     * overwrite triggers can never remove the file mid-rename.
+     */
+    async put(u, variant, type, body, now) {
+        await this.open();
+        if (this.closed)
+            return;
+        const key = entryKey(u, variant);
+        const at = now ?? Date.now();
+        const entry = {
+            type,
+            size: body.byteLength,
+            addedAt: at,
+            lastHit: at,
+            pins: 1,
+        };
+        this.entries.set(key, entry);
+        await mkdir(this.dir, { recursive: true });
+        const file = join(this.dir, key);
+        const staged = `${file}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(staged, body, { mode: 0o644 });
+            await rename(staged, file);
+        }
+        catch (cause) {
+            await rm(staged, { force: true }).catch(() => { });
+            this.entries.delete(key);
+            throw cause;
+        }
+        finally {
+            entry.pins -= 1;
+        }
+        await this.evict();
+        await this.persist();
+    }
+    /** Evict least-recently-hit entries until total size fits capacity. */
+    async evict() {
+        let total = 0;
+        for (const entry of this.entries.values())
+            total += entry.size;
+        if (total <= this.capacityBytes)
+            return;
+        const oldestFirst = [...this.entries.entries()].sort((a, b) => a[1].lastHit - b[1].lastHit || a[1].addedAt - b[1].addedAt);
+        for (const [key, entry] of oldestFirst) {
+            if (total <= this.capacityBytes)
+                break;
+            // Never delete a file a response is streaming or a put is
+            // writing (Review Focus 5): skip it and take the next-oldest.
+            if (entry.pins > 0)
+                continue;
+            this.entries.delete(key);
+            total -= entry.size;
+            await rm(join(this.dir, key), { force: true }).catch(() => { });
+        }
+    }
+    /** Write the index (staged + renamed; the stores' discipline). */
+    async persist() {
+        if (this.closed)
+            return;
+        if (this.entries.size === 0) {
+            // An empty table is written too — a re-open then starts empty
+            // instead of resurrecting rows whose files are gone.
+        }
+        await mkdir(this.dir, { recursive: true });
+        const file = {
+            entries: Object.fromEntries([...this.entries.entries()].map(([key, entry]) => [
+                key,
+                {
+                    type: entry.type,
+                    size: entry.size,
+                    addedAt: entry.addedAt,
+                    lastHit: entry.lastHit,
+                },
+            ])),
+        };
+        const staged = `${this.indexPath}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(staged, `${JSON.stringify(file)}\n`, { mode: 0o644 });
+            await chmod(staged, 0o644);
+            await rename(staged, this.indexPath);
+        }
+        catch (cause) {
+            await rm(staged, { force: true }).catch(() => { });
+            throw cause;
+        }
+    }
+    /** Flush the index; further `put`/`persist` calls no-op. */
+    async close() {
+        if (this.closed)
+            return;
+        await this.persist();
+        this.closed = true;
+    }
+}

package/dist/server/images/convert.js

@@ -0,0 +1,13 @@
+/**
+ * PNG conversion for the image proxy (UI-blocks U7 Task 3, spec §11.2
+ * ruling 17): with `as=png`, the server converts the fetched (or
+ * source-form) image to PNG with `sharp` (a server dependency) and the
+ * route caches the result beside the original variant. The TUI asks for
+ * it (pi-tui draws only PNG on Kitty without a registered transcoder);
+ * the webui doesn't.
+ */
+import sharp from "sharp";
+/** Convert image bytes (PNG/JPEG/GIF/WebP) to PNG bytes. */
+export async function toPng(bytes) {
+    return await sharp(bytes).png().toBuffer();
+}

package/dist/server/images/fetch.js

@@ -0,0 +1,302 @@
+/**
+ * Vetted-address image fetching (UI-blocks U7, spec §11.2 verbatim):
+ * the proxy's DNS-rebinding defense. Every hop is ONE `https.request`
+ * whose `lookup` option answers with the SINGLE vetted address for
+ * that hop — the connection can never re-resolve, so a resolver that
+ * answers a public address first and `127.0.0.1` second cannot cause
+ * a connection to loopback.
+ *
+ * Rules (each enforced per hop, redirects included):
+ * - https only; `http:` URLs and `http:` redirect targets are refused;
+ * - the host is resolved ONCE per hop through `deps.resolve`; every
+ *   returned address is checked against the refused ranges — one bad
+ *   address refuses the host (no happy-eyeballs fallback into it);
+ * - `servername` (SNI) and the `Host` header keep the ORIGINAL host
+ *   name, never the resolved address;
+ * - redirects are followed BY HAND (no library follow option): at most
+ *   3 in total, each target re-resolved and re-checked the same way;
+ * - 10 s total timeout for the whole fetch — ABSOLUTE across the
+ *   resolve, connect, and header phases of every hop plus the body
+ *   read (a socket-inactivity timeout would never fire on a drip);
+ * - no agent reuse across hops (`agent: false`): Node's default
+ *   keep-alive agent could serve a redirect hop from a pooled socket
+ *   whose connection was vetted on the FIRST hop only;
+ * - 10 MiB body cap;
+ * - the body must sniff as PNG/JPEG/GIF/WebP (Content-Type is never
+ *   trusted; SVG and AVIF are refused).
+ */
+import * as https from "node:https";
+import { isRefusedAddress } from "./ranges.js";
+import { isAcceptedImageType, sniffImage } from "./sniff.js";
+/** The whole-fetch budget: 10 s, spec §11.2. */
+export const FETCH_TIMEOUT_MS = 10_000;
+/** The response body cap: 10 MiB, spec §11.2. */
+export const FETCH_MAX_BYTES = 10 * 1024 * 1024;
+/** At most 3 redirects in total, spec §11.2. */
+export const FETCH_MAX_REDIRECTS = 3;
+/** A refusal: the reason plus the message the caller logs. */
+export class FetchRefusal extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "FetchRefusal";
+    }
+}
+/** Race `p` against the whole-fetch deadline.
+ *
+ * The deadline must be absolute even in phases a socket-inactivity
+ * timeout can never cut: a resolver that hangs, or a server dripping
+ * header bytes. Rejects with `timeout` when the deadline passes
+ * before `p` settles.
+ */
+function withDeadline(p, deps, deadline, phase) {
+    return new Promise((resolve, reject) => {
+        const remaining = deadline - deps.now();
+        if (remaining <= 0) {
+            // Mark `p`'s (possible later) rejection handled: the
+            // deadline refusal is the one the caller sees.
+            void p.catch(() => { });
+            reject(new FetchRefusal("timeout", `deadline reached before ${phase}`));
+            return;
+        }
+        const timer = setTimeout(() => {
+            reject(new FetchRefusal("timeout", `deadline reached ${phase}`));
+        }, remaining);
+        p.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (cause) => {
+            clearTimeout(timer);
+            reject(cause);
+        });
+    });
+}
+/** Resolve and vet one hop's host, or refuse it. */
+async function vettedAddress(host, deps) {
+    let addresses;
+    try {
+        addresses = await deps.resolve(host);
+    }
+    catch (cause) {
+        throw new FetchRefusal("resolve", `resolving ${host}: ${String(cause)}`);
+    }
+    if (addresses.length === 0) {
+        throw new FetchRefusal("resolve", `${host} resolved to no addresses`);
+    }
+    const vet = deps.vet ?? isRefusedAddress;
+    for (const address of addresses) {
+        if (vet(address)) {
+            throw new FetchRefusal("refused-address", `${host} resolves to refused address ${address}`);
+        }
+    }
+    // The FIRST vetted address is the one the connection uses; the
+    // lookup callback never consults the resolver again.
+    return addresses[0];
+}
+/** One `https.request` hop: connect to `address`, keep SNI/Host.
+ *
+ * The connect+header phase is cut by an ABSOLUTE whole-fetch deadline
+ * timer (not `req.setTimeout`, which is socket-inactivity: a
+ * header-drip server resets it forever). The timer is cleared the
+ * moment headers resolve; the body read has its own deadline timer.
+ */
+function hop(options) {
+    const { url, address, deps, deadline } = options;
+    return new Promise((resolve, reject) => {
+        const remaining = deadline - deps.now();
+        if (remaining <= 0) {
+            reject(new FetchRefusal("timeout", "deadline reached before connecting"));
+            return;
+        }
+        const req = https.request({
+            protocol: "https:",
+            host: url.hostname,
+            port: url.port || 443,
+            servername: url.hostname,
+            path: `${url.pathname}${url.search}`,
+            method: "GET",
+            // The rebinding defense: the connection dials the ONE
+            // vetted address, never the hostname (and never a second
+            // resolution). Node calls `lookup` with `all: true`.
+            lookup(_host, opts, callback) {
+                const family = address.includes(":") ? 6 : 4;
+                if (opts && typeof opts === "object" && "all" in opts && opts.all) {
+                    callback(null, [{ address, family }]);
+                }
+                else {
+                    callback(null, address, family);
+                }
+            },
+            // No explicit Host header: Node derives it from the
+            // ORIGINAL hostname (and the port), never the address the
+            // lookup returned.
+            ca: deps.ca,
+            // NO agent reuse across hops: with the default keep-alive
+            // global agent (Node >= 19), a redirect hop to the same
+            // host:port could be served by the pooled FIRST-hop
+            // socket — whose lookup (and vetted address) is the first
+            // hop's, so this hop's vetting would never run.
+            agent: false,
+        }, (res) => {
+            // Headers are in: the hop's absolute timer comes down; the
+            // caller owns the stream (redirect hops drain it, the
+            // final hop reads it).
+            clearTimeout(timer);
+            resolve({ status: res.statusCode ?? 0, headers: res.headers, stream: res });
+        });
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            req.destroy();
+            reject(new FetchRefusal("timeout", `deadline reached awaiting headers from ${url.hostname}`));
+        }, remaining);
+        // The absolute timer: cleared on headers (above) AND on a
+        // connect-phase error — an early failure must not leave a timer
+        // holding the event loop (or fake clocks) open for the full
+        // remaining budget (Task 3 pickup of Task 2's review P2).
+        req.on("error", (cause) => {
+            clearTimeout(timer);
+            if (timedOut)
+                return; // the destroy() above already rejected
+            reject(new FetchRefusal("network", `connecting to ${url.hostname}: ${cause.message}`));
+        });
+        req.end();
+    });
+}
+/** Read a body stream under the deadline and the byte cap. */
+function readBody(stream, deps, deadline) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let received = 0;
+        const fail = (refusal) => {
+            stream.destroy?.();
+            reject(refusal);
+        };
+        // The whole-fetch deadline: checked on every read and by a
+        // timer, so a drip that stops delivering entirely is cut too.
+        const timer = setTimeout(() => {
+            fail(new FetchRefusal("timeout", "deadline reached reading body"));
+        }, Math.max(0, deadline - deps.now()));
+        stream.on("data", (chunk) => {
+            received += chunk.length;
+            if (received > FETCH_MAX_BYTES) {
+                clearTimeout(timer);
+                fail(new FetchRefusal("too-large", `body over ${FETCH_MAX_BYTES} bytes`));
+                return;
+            }
+            chunks.push(chunk);
+            const remaining = deadline - deps.now();
+            if (remaining <= 0) {
+                clearTimeout(timer);
+                fail(new FetchRefusal("timeout", "deadline reached reading body"));
+            }
+        });
+        stream.on("end", () => {
+            clearTimeout(timer);
+            resolve(Buffer.concat(chunks));
+        });
+        stream.on("error", (cause) => {
+            clearTimeout(timer);
+            fail(new FetchRefusal("network", `reading body: ${cause.message}`));
+        });
+    });
+}
+/** Parse `Cache-Control: max-age=N` from response headers. */
+function maxAgeOf(headers) {
+    const raw = headers["cache-control"];
+    if (raw === undefined)
+        return undefined;
+    for (const header of Array.isArray(raw) ? raw : [raw]) {
+        for (const directive of header.split(",")) {
+            const trimmed = directive.trim();
+            if (trimmed.startsWith("max-age=")) {
+                const parsed = Number(trimmed.slice("max-age=".length));
+                if (Number.isFinite(parsed) && parsed >= 0)
+                    return parsed;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Fetch `u` as an image: resolve-and-vet every hop, follow at most 3
+ * redirects by hand, cap the body, and require the sniffed type.
+ */
+export async function fetchImage(u, deps) {
+    const deadline = deps.now() + FETCH_TIMEOUT_MS;
+    let current;
+    try {
+        current = new URL(u);
+    }
+    catch {
+        throw new FetchRefusal("bad-url", `not a URL: ${u}`);
+    }
+    if (current.protocol !== "https:") {
+        throw new FetchRefusal("scheme", `not https: ${current.protocol}`);
+    }
+    let redirects = 0;
+    // Each loop iteration is one hop: vet, connect, then either take
+    // the redirect (draining and looping) or read the body.
+    for (;;) {
+        // Every hop resolves through `deps.resolve` — including IP
+        // literal hosts (the real resolver, `dns.lookup`, passes literals
+        // through verbatim, so literals get range-checked like any other
+        // answer). Brackets stripped for the resolver and SNI; the Host
+        // header keeps Node's own derivation from the URL. The deadline
+        // is ABSOLUTE here too: a resolver that hangs is cut at it.
+        const bareHost = current.hostname.replace(/^\[|\]$/g, "");
+        const address = await withDeadline(vettedAddress(bareHost, deps), deps, deadline, `resolving ${bareHost}`);
+        const response = await hop({ url: current, address, deps, deadline });
+        const status = response.status;
+        if (status >= 300 && status < 400 && response.headers.location !== undefined) {
+            // Redirect hops count against the same total budget even
+            // when refused for scheme or address — the attempt was made.
+            if (redirects >= FETCH_MAX_REDIRECTS) {
+                void consume(response.stream);
+                throw new FetchRefusal("too-many-redirects", `over ${FETCH_MAX_REDIRECTS} redirects at ${current.toString()}`);
+            }
+            redirects += 1;
+            let target;
+            try {
+                target = new URL(response.headers.location, current);
+            }
+            catch {
+                void consume(response.stream);
+                throw new FetchRefusal("bad-url", `redirect target not a URL: ${u}`);
+            }
+            if (target.protocol !== "https:") {
+                void consume(response.stream);
+                throw new FetchRefusal("redirect-scheme", `redirect to ${target.protocol} refused`);
+            }
+            // Drain the redirect response so the server sees it consumed
+            // and the socket closes cleanly (with `agent: false` there is
+            // no pool for it to return to — the drain is hygiene, not reuse).
+            void consume(response.stream);
+            current = target;
+            continue;
+        }
+        if (status < 200 || status >= 300) {
+            void consume(response.stream);
+            throw new FetchRefusal("http-status", `status ${status} from ${current.toString()}`);
+        }
+        const bytes = await readBody(response.stream, deps, deadline);
+        const sniffed = sniffImage(bytes);
+        if (!isAcceptedImageType(sniffed)) {
+            throw new FetchRefusal("bad-type", sniffed === undefined
+                ? `body did not sniff as an accepted image type`
+                : `body sniffed as ${sniffed}, which is refused`);
+        }
+        const maxAge = maxAgeOf(response.headers);
+        return { bytes, type: sniffed, ...(maxAge === undefined ? {} : { maxAge }) };
+    }
+}
+/** Best-effort drain of a refused hop's response so the server sees
+ * the response consumed and the socket closes cleanly. */
+function consume(stream) {
+    return new Promise((resolve) => {
+        stream.on("data", () => { });
+        stream.on("end", () => resolve());
+        stream.on("error", () => resolve());
+    });
+}