opencode-plugboard 0.9.1 → 0.11.0

package/README.md

@@ -30,7 +30,7 @@ export PLUGBOARD_KEY_MY_APP=choose-a-long-random-string
 {
   "plugins": [
     {
-      "package": "opencode-plugboard@0.9.1",
+      "package": "opencode-plugboard@0.11.0",
       "options": {
         "keys": { "my-app": "{env:PLUGBOARD_KEY_MY_APP}" },
         "models": ["anthropic/claude-sonnet-4-6", "github-copilot/*", "opencode-go/glm-5.3-flash"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "type": "module",
   "license": "MIT",
   "description": "Use the ChatGPT, Claude, Copilot and OpenCode Go logins in your OpenCode server from any app. An OpenCode V2 plugin serving OpenAI-compatible Chat Completions, Responses and model endpoints.",
@@ -19,11 +19,20 @@
   },
   "files": ["index.ts", "src/", "README.md", "LICENSE"],
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p test",
+    "test": "bun test",
+    "smoke:pack": "bun .github/scripts/smoke-pack.ts",
     "release": "bun .github/scripts/release.ts"
   },
+  "dependencies": {
+    "escape-html": "1.0.3",
+    "ipaddr.js": "2.5.0",
+    "safe-stable-stringify": "2.5.0"
+  },
   "devDependencies": {
     "@opencode/plugin": "2.0.26",
+    "@types/bun": "1.4.2",
+    "@types/escape-html": "^1.0.4",
     "@types/node": "^26.6.2",
     "effect": "4.0.0-rc.112",
     "typescript": "^5.9.3"

package/src/abort.ts

@@ -0,0 +1,26 @@
+/** The one "settle or reject when aborted" helper that request-side code races host calls against. */
+
+/**
+ * Settles with `promise`, or rejects with `signal.reason` as soon as `signal` aborts. The promise
+ * itself keeps running (it cannot be cancelled): it is always observed, so a late rejection after
+ * the race was lost never becomes an unhandled rejection. A signal that is already aborted rejects
+ * at once.
+ */
+export function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  promise.catch(() => {})
+  if (signal.aborted) return Promise.reject(signal.reason)
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(signal.reason)
+    signal.addEventListener("abort", onAbort, { once: true })
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort)
+        resolve(value)
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort)
+        reject(error)
+      },
+    )
+  })
+}

package/src/config.ts

@@ -1,5 +1,6 @@
 /** Plugin options: type, defaults, validation, caller authentication and the loopback check. */
 
+import { createHash, timingSafeEqual } from "node:crypto"
 import type { PlugError } from "./contract.js"
 import { parseAllowEntry, type RemoteImages } from "./session/media.js"
 import type { HistoryLimits } from "./session/prune.js"
@@ -125,6 +126,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   }
   // Own-property construction: a key such as `__proto__` must stay a key, never reach the prototype.
   const keys: Record<string, string> = Object.fromEntries(keyEntries)
+  digestsOf(keys)
   if (keyEntries.length === 0 && !isLoopbackHost(host))
     throw new Error(`plugboard refuses to listen on non-loopback host \`${host}\` without \`keys\``)
 
@@ -186,20 +188,30 @@ const UNAUTHORIZED: PlugError = {
   code: "invalid_api_key",
 }
 
-function same(a: string, b: string): boolean {
-  let diff = a.length ^ b.length
-  const length = Math.max(a.length, b.length)
-  for (let i = 0; i < length; i++) diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0)
-  return diff === 0
+const sha256 = (text: string): Buffer => createHash("sha256").update(text).digest()
+
+/**
+ * SHA-256 digest of each key, computed once per `keys` object (at parse; lazily for an options
+ * object built without `parseOptions`). Comparing fixed-size digests means a wrong token's length
+ * and content do not change how long the comparison takes.
+ */
+const keyDigests = new WeakMap<object, ReadonlyArray<readonly [string, Buffer]>>()
+
+function digestsOf(keys: Readonly<Record<string, string>>): ReadonlyArray<readonly [string, Buffer]> {
+  let digests = keyDigests.get(keys)
+  if (!digests) keyDigests.set(keys, (digests = Object.entries(keys).map(([name, key]) => [name, sha256(key)] as const)))
+  return digests
 }
 
 /** No keys -> app `default`; with keys every request needs `Authorization: Bearer <key>`. */
 export function authenticate(options: PlugboardOptions, authorization: string | undefined): { app: string } | PlugError {
-  const entries = Object.entries(options.keys)
+  const entries = digestsOf(options.keys)
   if (entries.length === 0) return { app: DEFAULT_APP }
   const token = /^Bearer\s+(\S+)\s*$/i.exec(authorization ?? "")?.[1]
   if (!token) return UNAUTHORIZED
+  const digest = sha256(token)
   let app: string | undefined
-  for (const [name, key] of entries) if (same(token, key)) app = name
+  // Every key is compared, no early exit.
+  for (const [name, expected] of entries) if (timingSafeEqual(digest, expected)) app = name
   return app === undefined ? UNAUTHORIZED : { app }
 }

package/src/discovery.ts

@@ -16,6 +16,7 @@
  */
 
 import type { ServerResponse } from "node:http"
+import escapeText from "escape-html"
 import type { PlugboardOptions } from "./config.js"
 import type { CatalogModel } from "./contract.js"
 import { listAvailableModels } from "./models.js"
@@ -40,8 +41,7 @@ export function sendText(response: ServerResponse, status: number, contentType:
   response.end(body)
 }
 
-const escapeHtml = (value: unknown): string =>
-  String(value).replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char] ?? char)
+const escapeHtml = (value: unknown): string => escapeText(String(value))
 
 /** `http://host:port` for a listen address; an IPv6 literal gets brackets. */
 function origin(listen: PlugboardOptions["listen"]): string {

package/src/http.ts

@@ -5,6 +5,7 @@
  */
 
 import type { IncomingMessage, ServerResponse } from "node:http"
+import { raceAbort } from "./abort.js"
 import { isLoopbackHost, type PlugboardOptions } from "./config.js"
 import type { PlugError, PlugEvent } from "./contract.js"
 
@@ -49,9 +50,9 @@ export interface RequestScope {
 
 /**
  * Establishes cancellation and the deadline. Call before the first `await` of a request: a socket
- * that is already gone aborts immediately, so abandoned work never starts.
+ * that is already gone aborts immediately, so abandoned work never starts. `graceMs` is for tests.
  */
-export function beginRequest(request: IncomingMessage, response: ServerResponse, timeoutMs: number): RequestScope {
+export function beginRequest(request: IncomingMessage, response: ServerResponse, timeoutMs: number, graceMs = DEADLINE_GRACE_MS): RequestScope {
   const controller = new AbortController()
   const abort = (kind: RequestAborted["kind"]) => {
     if (!controller.signal.aborted) controller.abort(new RequestAborted(kind))
@@ -68,7 +69,7 @@ export function beginRequest(request: IncomingMessage, response: ServerResponse,
     graceTimer = setTimeout(() => {
       response.destroy()
       request.socket?.destroy()
-    }, DEADLINE_GRACE_MS)
+    }, graceMs)
     graceTimer.unref?.()
   }
   timer = setTimeout(onDeadline, Math.min(Math.max(timeoutMs, 1), MAX_TIMER_MS))
@@ -98,24 +99,7 @@ export function beginRequest(request: IncomingMessage, response: ServerResponse,
       code: "timeout",
       message: `Request timed out after ${timeoutMs} ms (option requestTimeoutMs)`,
     },
-    race<T>(promise: Promise<T>): Promise<T> {
-      promise.catch(() => {})
-      if (signal.aborted) return Promise.reject(signal.reason)
-      return new Promise<T>((resolve, reject) => {
-        const onAbort = () => reject(signal.reason)
-        signal.addEventListener("abort", onAbort, { once: true })
-        promise.then(
-          (value) => {
-            signal.removeEventListener("abort", onAbort)
-            resolve(value)
-          },
-          (error) => {
-            signal.removeEventListener("abort", onAbort)
-            reject(error)
-          },
-        )
-      })
-    },
+    race: (promise) => raceAbort(promise, signal),
     dispose,
   }
 }

package/src/responses/response.ts

@@ -79,10 +79,16 @@ const structuredFailure = (exchange: ResponsesExchange, finish: Exclude<PlugFini
         message: `The model finished without calling the \`${exchange.structuredTool}\` tool, so there is no structured output`,
       }
 
+/**
+ * `committed`: whether the transport already committed a 200 stream before any event was emitted
+ * (the SSE writer does at the first reasoning event, #49). A failure then still opens the response
+ * and ends it with `response.failed`, instead of leaving the client an empty 200 stream.
+ */
 export async function runResponse(
   events: AsyncIterable<PlugEvent>,
   exchange: ResponsesExchange,
   emit: (event: ResponsesStreamEvent) => void,
+  committed: () => boolean = () => false,
 ): Promise<ResponseRun> {
   const id = newId("resp")
   const createdAt = Math.floor(Date.now() / 1000)
@@ -203,14 +209,15 @@ export async function runResponse(
   const structuredAnswer = exchange.structuredTool !== undefined && !passthrough
   failure ??= finish ? (passthrough ? undefined : structuredFailure(exchange, finish, answered)) : noFinish()
   if (failure) {
-    if (!started) return { failure, started }
+    if (!started && !committed()) return { failure, started }
+    start()
     closeMessage()
     const response = envelope("failed", items, {
       error: { code: failure.code ?? failure.kind, message: failure.message },
       ...(usage ? { usage: encodeUsage(usage) } : {}),
     })
     send("response.failed", { response })
-    return { failure, started, response }
+    return { failure, started: true, response }
   }
   start()
   if (held && structuredAnswer) text(args(held.input))

package/src/responses/route.ts

@@ -56,7 +56,7 @@ export async function serveResponses(host: RouteHost, { app, body, response, sco
 
   if (exchange.stream) {
     const sse = sseWriter(response, scope.signal)
-    const { failure } = await runResponse(sse.paced(events), exchange, (event) => sse.write(sseFrame(event)))
+    const { failure } = await runResponse(sse.paced(events), exchange, (event) => sse.write(sseFrame(event)), () => sse.started)
     if (!sse.started && !response.headersSent) {
       if (!scope.signal.aborted || scope.timedOut) fail(failure ?? { status: 502, kind: "server", message: "No response from the model" })
     } else {

package/src/runtime.ts

@@ -44,7 +44,10 @@
  */
 
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http"
+import { setTimeout as delay } from "node:timers/promises"
 import { Cause, Effect, Stream } from "effect"
+import stableStringify from "safe-stable-stringify"
+import { raceAbort } from "./abort.js"
 import { isPlugError, type CatalogModel, type PlugError } from "./contract.js"
 import { errorMessage, log, logError, outsideRequest, setLogFormat } from "./log.js"
 import { createMetrics, type Metrics, type RuntimeSnapshot } from "./metrics.js"
@@ -104,8 +107,8 @@ const BACKEND_POLL_MS = 25
 const BIND_RETRY_MS = 15_000
 const BIND_REMINDER_MS = 5 * 60_000
 
-/** 6: the listener retries a failed bind (new fields on `Listener`). 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
-const VERSION = 6
+/** 7: the options fingerprint comes from safe-stable-stringify, so it must not be compared with an older one. 6: the listener retries a failed bind (new fields on `Listener`). 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
+const VERSION = 7
 const KEY = Symbol.for("opencode-plugboard.runtime")
 
 interface Listener {
@@ -298,19 +301,9 @@ export function loadServingCatalog(fallback: () => Promise<ReadonlyArray<Catalog
   return (rt ? (preferred(rt)?.loadCatalog ?? fallback) : fallback)()
 }
 
-/** JSON with object keys sorted at every level, so equal options compare equal whatever their key order. */
+/** JSON with object keys sorted at every level, so equal options compare equal whatever their key order (undefined values are left out, as in `JSON.stringify`). */
 function canonicalJson(value: unknown): string {
-  const canonical = (item: unknown): unknown => {
-    if (Array.isArray(item)) return item.map(canonical)
-    if (typeof item !== "object" || item === null) return item
-    return Object.fromEntries(
-      Object.entries(item)
-        .filter(([, entry]) => entry !== undefined)
-        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
-        .map(([key, entry]) => [key, canonical(entry)]),
-    )
-  }
-  return JSON.stringify(canonical(value))
+  return stableStringify(value) ?? ""
 }
 
 const unavailable = (response: ServerResponse, message: string) => {
@@ -512,30 +505,8 @@ export function ensurePump(subscribe: () => Stream.Stream<unknown, unknown, neve
 
 const backendUnavailable = (message: string): PlugError => ({ status: 503, kind: "server", code: "backend_unavailable", message })
 
-/** Rejects when `signal` aborts; the underlying promise is left running (its late result or error is swallowed). */
-function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
-  return new Promise<T>((resolve, reject) => {
-    const onAbort = () => reject(new Error("aborted"))
-    if (signal.aborted) return onAbort()
-    signal.addEventListener("abort", onAbort, { once: true })
-    promise.then(
-      (value) => (signal.removeEventListener("abort", onAbort), resolve(value)),
-      (error) => (signal.removeEventListener("abort", onAbort), reject(error)),
-    )
-  })
-}
-
-const sleep = (ms: number, signal: AbortSignal) =>
-  new Promise<void>((resolve) => {
-    if (signal.aborted) return resolve()
-    const timer = setTimeout(done, ms)
-    function done() {
-      clearTimeout(timer)
-      signal.removeEventListener("abort", done)
-      resolve()
-    }
-    signal.addEventListener("abort", done, { once: true })
-  })
+/** Waits `ms`, or until `signal` aborts (which resolves, never rejects). */
+const sleep = (ms: number, signal: AbortSignal): Promise<void> => delay(ms, undefined, { signal }).catch(() => {})
 
 /** Rebuild the transforms of a generation set up before its directory was confirmed; shared by concurrent requests. */
 function activate(generation: Generation): Promise<void> {
@@ -593,7 +564,7 @@ export async function ensureBackend(
         if (!booted) {
           booted = true
           try {
-            await abortable(boot(directory), bounded)
+            await raceAbort(boot(directory), bounded)
           } catch (error) {
             if (bounded.aborted) continue
             logError("backend.boot_failed", { app, error: errorMessage(error) })
@@ -603,7 +574,7 @@ export async function ensureBackend(
         }
       } else {
         try {
-          await abortable(Promise.all(here.filter((generation) => !generation.activated).map(activate)), bounded)
+          await raceAbort(Promise.all(here.filter((generation) => !generation.activated).map(activate)), bounded)
         } catch (error) {
           if (bounded.aborted) continue
           throw error

package/src/session/caller.ts

@@ -17,6 +17,7 @@
  */
 
 import { randomUUID } from "node:crypto"
+import { raceAbort } from "../abort.js"
 import { APP_NAME_PATTERN, DEFAULT_APP } from "../config.js"
 import { isPlugError, type CallContext, type ModelCaller, type PlugError, type PlugEvent, type PlugRequest } from "../contract.js"
 import { log, logError } from "../log.js"
@@ -72,17 +73,6 @@ function checkPreparation(request: PlugRequest, images: number, maxTools: number
   return undefined
 }
 
-/** Settles with `promise`, or rejects as soon as `signal` aborts. Request side only: the promise itself keeps running. */
-function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
-  promise.catch(() => {}) // a late rejection after the race was lost must not become unhandled
-  if (signal.aborted) return Promise.reject(signal.reason)
-  return new Promise<T>((resolve, reject) => {
-    const onAbort = () => reject(signal.reason)
-    signal.addEventListener("abort", onAbort, { once: true })
-    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort))
-  })
-}
-
 export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
   const { port, sessions, maxTools, ensureBackend } = deps
   const remoteImages = deps.remoteImages ?? false

package/src/session/media.ts

@@ -9,15 +9,17 @@
  * server's own network (#84): the host is resolved first, every address it resolves to must be a
  * public one (loopback, private, link-local, CGNAT, ULA, multicast, reserved and mapped or
  * translated forms of those are refused) unless the operator's `remoteImages.allow` list names the
- * host or the address, and the request then connects to the address that was checked, not to the
- * name, so a second DNS answer cannot redirect it (DNS rebinding). The caller sees one generic
- * error for every fetch failure, whatever the cause.
+ * host or the address, and the request then connects to the addresses that were checked (tried in
+ * order until one accepts), not to the name, so a second DNS answer cannot redirect it (DNS
+ * rebinding). Addresses are classified by ipaddr.js. The caller sees one generic error for every
+ * fetch failure, whatever the cause.
  */
 
 import { lookup } from "node:dns/promises"
 import { request as httpRequest, type IncomingMessage } from "node:http"
 import { request as httpsRequest } from "node:https"
 import { isIP } from "node:net"
+import ipaddr from "ipaddr.js"
 import type { PlugRequest } from "../contract.js"
 import { log } from "../log.js"
 
@@ -49,127 +51,64 @@ export class ImageError extends Error {
 
 // ---- addresses
 
-interface Ip {
-  readonly family: 4 | 6
-  readonly bytes: ReadonlyArray<number>
-}
+type Ip = ipaddr.IPv4 | ipaddr.IPv6
 
-/** Dotted IPv4 or any IPv6 text form (compressed, with an embedded IPv4 tail, with a zone) to bytes. */
+/** Strict dotted IPv4 or any IPv6 text form (compressed, with an embedded IPv4 tail, with a zone). Odd IPv4 spellings (`0x7f.1`) never get here: a URL host is normalized by `new URL` first. */
 function parseIp(text: string): Ip | undefined {
-  const family = isIP(text)
-  if (family === 4) return { family, bytes: text.split(".").map(Number) }
-  if (family !== 6) return undefined
-  let head = text.split("%")[0]!
-  const dot = head.lastIndexOf(".")
-  if (dot !== -1) {
-    const colon = head.lastIndexOf(":")
-    const v4 = head.slice(colon + 1).split(".").map(Number)
-    head = `${head.slice(0, colon + 1)}${((v4[0]! << 8) | v4[1]!).toString(16)}:${((v4[2]! << 8) | v4[3]!).toString(16)}`
-  }
-  const [left = "", right = ""] = head.split("::")
-  const first = left === "" ? [] : left.split(":")
-  const last = head.includes("::") ? (right === "" ? [] : right.split(":")) : []
-  const groups = head.includes("::") ? [...first, ...Array<string>(8 - first.length - last.length).fill("0"), ...last] : head.split(":")
-  const bytes: number[] = []
-  for (const group of groups) {
-    const value = Number.parseInt(group, 16)
-    bytes.push(value >> 8, value & 0xff)
-  }
-  return { family, bytes }
-}
-
-interface Cidr {
-  readonly ip: Ip
-  readonly bits: number
-}
-
-function inCidr(ip: Ip, cidr: Cidr): boolean {
-  if (ip.family !== cidr.ip.family) return false
-  let left = cidr.bits
-  for (let i = 0; left > 0; i++, left -= 8) {
-    const mask = left >= 8 ? 0xff : (0xff << (8 - left)) & 0xff
-    if ((ip.bytes[i]! & mask) !== (cidr.ip.bytes[i]! & mask)) return false
+  if (isIP(text) === 0) return undefined
+  try {
+    return ipaddr.parse(text)
+  } catch {
+    return undefined
   }
-  return true
 }
 
-function parseCidr(text: string): Cidr | undefined {
-  const [address = "", length, extra] = text.split("/")
-  const ip = parseIp(address)
-  if (!ip || extra !== undefined) return undefined
-  const max = ip.family === 4 ? 32 : 128
-  if (length === undefined) return { ip, bits: max }
-  const bits = Number(length)
-  return /^\d{1,3}$/.test(length) && bits <= max ? { ip, bits } : undefined
-}
+/** `address/bits` match; false for another family (ipaddr.js throws on one). */
+const inNet = (ip: Ip, net: Ip, bits: number): boolean => ip.kind() === net.kind() && ip.match(net, bits)
 
-const cidrs = (list: string[]): Cidr[] => list.map((entry) => parseCidr(entry)!)
+const NAT64 = ipaddr.IPv6.parseCIDR("64:ff9b::/96")
+/** `::/96`: unspecified, loopback and the deprecated IPv4-compatible form (`::7f00:1`), which ipaddr.js calls unicast. */
+const IPV4_COMPATIBLE = ipaddr.IPv6.parseCIDR("::/96")
 
-/** IPv4 that is not a public unicast address. */
-const BLOCKED_V4 = cidrs([
-  "0.0.0.0/8", // "this network"
-  "10.0.0.0/8",
-  "100.64.0.0/10", // CGNAT
-  "127.0.0.0/8", // loopback
-  "169.254.0.0/16", // link-local, cloud metadata
-  "172.16.0.0/12",
-  "192.0.0.0/24", // IETF protocol assignments
-  "192.0.2.0/24", // documentation
-  "192.168.0.0/16",
-  "198.18.0.0/15", // benchmarking
-  "198.51.100.0/24", // documentation
-  "203.0.113.0/24", // documentation
-  "224.0.0.0/4", // multicast
-  "240.0.0.0/4", // reserved, broadcast
-])
+const v4From = (high: number, low: number) => new ipaddr.IPv4([high >> 8, high & 0xff, low >> 8, low & 0xff])
 
 /**
- * IPv6 that is not a public unicast address. NAT64 (`64:ff9b::/96`) and 6to4 (`2002::/16`) are
- * not listed: they embed an IPv4 address, which `isPublic` checks as IPv4 (a DNS64 network answers
- * with NAT64 addresses for ordinary public hosts).
+ * A public unicast address. ipaddr.js names the special ranges (loopback, private, link-local, CGNAT,
+ * multicast, reserved and documentation, ULA, Teredo, local-use NAT64, IPv4-mapped, ...); only
+ * `unicast` passes. NAT64 (`64:ff9b::/96`) and 6to4 (`2002::/16`) embed an IPv4 address, which is
+ * checked as IPv4 instead of being refused outright (a DNS64 network answers with NAT64 addresses
+ * for ordinary public hosts). An IPv4-mapped address is never a real answer for a public host.
  */
-const BLOCKED_V6 = cidrs([
-  "::/96", // unspecified, loopback, deprecated IPv4-compatible
-  "::ffff:0:0/96", // IPv4-mapped: never a real answer for a public host
-  "64:ff9b:1::/48", // local-use NAT64
-  "100::/64", // discard
-  "2001::/32", // Teredo
-  "2001:db8::/32", // documentation
-  "fc00::/7", // unique local
-  "fe80::/10", // link-local
-  "fec0::/10", // site-local (deprecated)
-  "ff00::/8", // multicast
-])
-
-/** The IPv4 address embedded in a NAT64 or 6to4 address (or a mapped one), if it is one. */
-function embeddedV4(ip: Ip): Ip | undefined {
-  if (ip.family !== 6) return undefined
-  const b = ip.bytes
-  const mapped = b.slice(0, 10).every((x) => x === 0) && b[10] === 0xff && b[11] === 0xff
-  const nat64 = b[0] === 0 && b[1] === 0x64 && b[2] === 0xff && b[3] === 0x9b && b.slice(4, 12).every((x) => x === 0)
-  if (mapped || nat64) return { family: 4, bytes: b.slice(12, 16) }
-  if (b[0] === 0x20 && b[1] === 0x02) return { family: 4, bytes: b.slice(2, 6) }
-  return undefined
+export function isPublicAddress(text: string): boolean {
+  const ip = parseIp(text)
+  return ip !== undefined && isPublic(ip)
 }
 
 function isPublic(ip: Ip): boolean {
-  const inner = embeddedV4(ip)
-  if (inner && !isPublic(inner)) return false
-  return !(ip.family === 4 ? BLOCKED_V4 : BLOCKED_V6).some((cidr) => inCidr(ip, cidr))
+  if (ip instanceof ipaddr.IPv4) return ip.range() === "unicast"
+  const range = ip.range()
+  const inner = range === "6to4" ? v4From(ip.parts[1]!, ip.parts[2]!) : ip.match(NAT64) ? v4From(ip.parts[6]!, ip.parts[7]!) : undefined
+  if (inner) return isPublic(inner)
+  return range === "unicast" && !ip.match(IPV4_COMPATIBLE)
 }
 
 // ---- allowlist
 
 /** One `remoteImages.allow` entry: a host name (`images.internal`, or `*.internal` for subdomains), an IP address, or a CIDR range. */
-type AllowEntry = { readonly kind: "host"; readonly name: string } | { readonly kind: "net"; readonly cidr: Cidr }
+type AllowEntry = { readonly kind: "host"; readonly name: string } | { readonly kind: "net"; readonly address: Ip; readonly bits: number }
 
 const HOSTNAME = /^(?:\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/
 
 /** Undefined when `entry` is none of the three forms. */
 export function parseAllowEntry(entry: string): AllowEntry | undefined {
   const text = entry.trim().toLowerCase()
-  const cidr = parseCidr(text)
-  if (cidr) return { kind: "net", cidr }
+  const [address = "", length, extra] = text.split("/")
+  const ip = parseIp(address)
+  if (ip && extra === undefined) {
+    const max = ip instanceof ipaddr.IPv4 ? 32 : 128
+    if (length === undefined) return { kind: "net", address: ip, bits: max }
+    if (/^\d{1,3}$/.test(length) && Number(length) <= max) return { kind: "net", address: ip, bits: Number(length) }
+  }
   return HOSTNAME.test(text) && !text.includes("/") ? { kind: "host", name: text } : undefined
 }
 
@@ -190,11 +129,12 @@ function resolveAddresses(host: string, signal: AbortSignal): Promise<string[]>
 }
 
 /**
- * Resolve the URL's host and decide which address to connect to. Every address the name resolves
- * to has to be allowed (a name that answers with one public and one private address is refused),
- * so the pinned one cannot be a surprise. Throws the generic fetch error when anything is refused.
+ * Resolve the URL's host and return the addresses to connect to, in resolver order. Every address
+ * the name resolves to has to be allowed (a name that answers with one public and one private
+ * address is refused), so a pinned one cannot be a surprise. Throws the generic fetch error when
+ * anything is refused.
  */
-async function pickAddress(url: URL, allow: ReadonlyArray<AllowEntry>, signal: AbortSignal): Promise<string> {
+async function checkedAddresses(url: URL, allow: ReadonlyArray<AllowEntry>, signal: AbortSignal): Promise<string[]> {
   const host = url.hostname.replace(/^\[|\]$/g, "").toLowerCase()
   const literal = parseIp(host)
   const addresses = literal ? [host] : await resolveAddresses(host, signal)
@@ -202,14 +142,14 @@ async function pickAddress(url: URL, allow: ReadonlyArray<AllowEntry>, signal: A
   const permitted = (address: string): boolean => {
     const ip = parseIp(address)
     if (!ip) return false
-    return nameAllowed || isPublic(ip) || allow.some((entry) => entry.kind === "net" && inCidr(ip, entry.cidr))
+    return nameAllowed || isPublic(ip) || allow.some((entry) => entry.kind === "net" && inNet(ip, entry.address, entry.bits))
   }
   if (addresses.length === 0 || !addresses.every(permitted)) {
     // The log says which kind of refusal, never the host or the URL.
     log("media.remote_refused", { reason: addresses.length === 0 ? "no_address" : "address_not_allowed" })
     throw FETCH_FAILED()
   }
-  return addresses[0]!
+  return addresses
 }
 
 /** GET `url` over a connection to `address` (already checked), keeping the URL's host for `Host` and TLS. No redirects are followed by the caller. */
@@ -239,6 +179,18 @@ function get(url: URL, address: string, signal: AbortSignal): Promise<IncomingMe
   })
 }
 
+/** The first connection that succeeds, trying each checked address in order (#134); only a connection failure moves on, never a response. */
+async function getFirst(url: URL, addresses: ReadonlyArray<string>, signal: AbortSignal): Promise<IncomingMessage> {
+  for (const address of addresses) {
+    try {
+      return await get(url, address, signal)
+    } catch {
+      if (signal.aborted) break
+    }
+  }
+  throw FETCH_FAILED()
+}
+
 // ---- preparation
 
 async function toDataUrl(url: string, signal: AbortSignal, remoteImages: RemoteImages, budget: Budget): Promise<string> {
@@ -260,12 +212,10 @@ async function toDataUrl(url: string, signal: AbortSignal, remoteImages: RemoteI
     throw FETCH_FAILED()
   }
   const allow = typeof remoteImages === "object" ? remoteImages.allow.flatMap((entry) => parseAllowEntry(entry) ?? []) : []
-  const address = await pickAddress(target, allow, bounded).catch((error: unknown) => {
+  const addresses = await checkedAddresses(target, allow, bounded).catch((error: unknown) => {
     throw error instanceof ImageError ? error : FETCH_FAILED()
   })
-  const response = await get(target, address, bounded).catch(() => {
-    throw FETCH_FAILED()
-  })
+  const response = await getFirst(target, addresses, bounded)
   // A redirect is never followed (it could point inside); anything but a plain success is a failed fetch.
   if (response.statusCode === undefined || response.statusCode < 200 || response.statusCode > 299) {
     response.destroy()