opencode-plugboard 0.5.0 → 0.6.0

package/README.md

@@ -30,7 +30,7 @@ export PLUGBOARD_KEY_MY_APP=choose-a-long-random-string
 {
   "plugins": [
     {
-      "package": "opencode-plugboard@0.5.0",
+      "package": "opencode-plugboard@0.6.0",
       "options": {
         "keys": { "my-app": "{env:PLUGBOARD_KEY_MY_APP}" },
         "models": ["anthropic/claude-sonnet-4-6", "github-copilot/*", "opencode-go/glm-5.3-flash"],
@@ -81,10 +81,9 @@ Plugboard is early (0.x) and narrow on purpose.
 - **No concurrency limit per app** yet ([#54](https://github.com/jjjermiah/opencode-plugboard/issues/54), [#86](https://github.com/jjjermiah/opencode-plugboard/issues/86)).
 - **Not a gateway with its own provider keys.** It only reuses what OpenCode is logged in to.
 
-How it differs from the alternatives:
+How it differs from a standalone gateway:
 
-- [KochC/opencode-llm-proxy](https://github.com/KochC/opencode-llm-proxy) serves more API formats but targets OpenCode V1 only. Plugboard is V2 only and adds per-app keys and history, an explicit model allowlist, and rules that keep it from freezing the host (see [AGENTS.md](https://github.com/jjjermiah/opencode-plugboard/blob/main/AGENTS.md)).
-- [LiteLLM](https://github.com/BerriAI/litellm) is a separate gateway you run and give its own provider keys. It covers many more providers and API shapes. Pick it when you want a standalone service. Pick plugboard when OpenCode already holds the logins you want to reuse, such as a ChatGPT or Copilot subscription.
+- [LiteLLM](https://github.com/BerriAI/litellm) is a separate gateway you run and give its own provider keys. It covers many more providers and API shapes. Pick it when you want a standalone service. Pick plugboard when OpenCode already holds the logins you want to reuse, such as a ChatGPT or Copilot subscription. Plugboard also gives each app its own key and history, an explicit model allowlist, and rules that keep it from ever freezing the host.
 
 The most common first failure is an SDK defaulting to `/v1/responses` for newer models. Plugboard serves it, but some clients need `store: false` or a "use chat completions" switch. Check the client's page below.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.5.0",
+  "version": "0.6.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.",

package/src/config.ts

@@ -1,6 +1,7 @@
 /** Plugin options: type, defaults, validation, caller authentication and the loopback check. */
 
 import type { PlugError } from "./contract.js"
+import { parseAllowEntry, type RemoteImages } from "./session/media.js"
 import type { HistoryLimits } from "./session/prune.js"
 
 /** Plugin options, after defaults and validation (see `parseOptions`). */
@@ -14,8 +15,13 @@ export interface PlugboardOptions {
   readonly aliases: Readonly<Record<string, string>>
   readonly maxTools: number
   readonly requestTimeoutMs: number
-  /** Fetch http(s) image URLs server-side. Off by default: it is an SSRF vector into the host's network. */
-  readonly remoteImages: boolean
+  /**
+   * Fetch http(s) image URLs server-side. Off by default: it is an SSRF vector into the host's network.
+   * `true` fetches public addresses only (loopback, private, link-local, CGNAT and ULA ranges are refused);
+   * `{ allow }` is on too, and lists the hosts (`name`, `*.suffix`), addresses or CIDR ranges that may be
+   * fetched even when they are not public.
+   */
+  readonly remoteImages: RemoteImages
   /** Prune old request sessions (see `src/session/prune.ts`). A limit that is unset is not applied; with neither, history is kept forever. Applies per app. */
   readonly history: HistoryLimits
   /** Drop sampling parameters the target model is known to reject (reported in `x-plugboard-dropped-params`). On by default; off forwards them as sent. */
@@ -68,6 +74,23 @@ function positiveInt(value: unknown, name: string, fallback: number, max = Numbe
   return value
 }
 
+const REMOTE_IMAGES_ERROR =
+  "plugboard option `remoteImages` must be a boolean or `{ allow: [...] }` with host names, IP addresses or CIDR ranges that may be fetched even when they are not public"
+
+function parseRemoteImages(value: unknown): RemoteImages {
+  if (value === undefined) return false
+  if (typeof value === "boolean") return value
+  if (!isRecord(value)) throw new Error(REMOTE_IMAGES_ERROR)
+  for (const key of Object.keys(value))
+    if (key !== "allow") throw new Error(`Unknown plugboard option \`remoteImages.${key}\` (known: allow)`)
+  const allow = value.allow ?? []
+  if (!Array.isArray(allow)) throw new Error(REMOTE_IMAGES_ERROR)
+  for (const entry of allow)
+    if (typeof entry !== "string" || parseAllowEntry(entry) === undefined)
+      throw new Error(`plugboard \`remoteImages.allow\` entry \`${String(entry)}\` must be a host name (\`images.internal\`, \`*.internal\`), an IP address or a CIDR range`)
+  return { allow: allow as string[] }
+}
+
 /** Validates raw plugin options and applies defaults. Throws `Error` with an actionable message. */
 export function parseOptions(raw: unknown): PlugboardOptions {
   if (raw !== undefined && raw !== null && !isRecord(raw)) throw new Error("plugboard options must be an object")
@@ -122,8 +145,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   }
   const aliases: Record<string, string> = Object.fromEntries(aliasEntries)
 
-  if (input.remoteImages !== undefined && typeof input.remoteImages !== "boolean")
-    throw new Error("plugboard option `remoteImages` must be a boolean")
+  const remoteImages = parseRemoteImages(input.remoteImages)
   if (input.dropUnsupportedParams !== undefined && typeof input.dropUnsupportedParams !== "boolean")
     throw new Error("plugboard option `dropUnsupportedParams` must be a boolean")
 
@@ -145,7 +167,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     aliases,
     maxTools: positiveInt(input.maxTools, "maxTools", DEFAULTS.maxTools, 1024),
     requestTimeoutMs: positiveInt(input.requestTimeoutMs, "requestTimeoutMs", DEFAULTS.requestTimeoutMs, MAX_TIMER_MS),
-    remoteImages: input.remoteImages === true,
+    remoteImages,
     history: { ...(maxSessions === undefined ? {} : { maxSessions }), ...(maxAgeDays === undefined ? {} : { maxAgeDays }) },
     dropUnsupportedParams: input.dropUnsupportedParams !== false,
     logFormat: input.logFormat === "json" ? "json" : "text",

package/src/openai/route.ts

@@ -157,6 +157,11 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       return sendText(response, 200, "text/html; charset=utf-8", renderDiscoveryHtml(doc), PAGE_HEADERS)
     }
 
+    // Authenticate before anything reveals which routes exist: an unauthenticated caller sees 401 for every path but /healthz and the first-run pages.
+    const auth = authenticate(host.options, request.headers.authorization)
+    if (isPlugError(auth)) return fail(response, auth)
+    info.app = auth.app
+
     if (modelId === undefined && !known(route)) {
       return fail(response, {
         status: 404,
@@ -166,10 +171,6 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       })
     }
 
-    const auth = authenticate(host.options, request.headers.authorization)
-    if (isPlugError(auth)) return fail(response, auth)
-    info.app = auth.app
-
     if (route === "GET /v1/status") {
       const catalog = await optionalCatalog(scope)
       return sendJson(response, 200, buildStatus({ options: host.options, app: auth.app, runtime: runtimeStatus(), catalog }))

package/src/runtime.ts

@@ -100,8 +100,12 @@ const SWEEP_DEADLINE_MS = 60_000
 const BACKEND_TIMEOUT_MS = 15_000
 const BACKEND_POLL_MS = 25
 
-/** 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 = 5
+/** How often a listener that could not bind tries again, and how often it repeats the error while it still cannot (#87). */
+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
 const KEY = Symbol.for("opencode-plugboard.runtime")
 
 interface Listener {
@@ -111,6 +115,11 @@ interface Listener {
   fingerprint: string
   mismatchLogged: boolean
   bound: boolean
+  /** Failed bind attempts since the last success: while this is above 0 nothing receives requests on the port. */
+  bindFailures: number
+  /** When the bind failure was last logged (epoch ms). */
+  bindLoggedAt: number
+  retryTimer?: ReturnType<typeof setTimeout>
   graceTimer?: ReturnType<typeof setTimeout>
 }
 
@@ -312,7 +321,7 @@ const unavailable = (response: ServerResponse, message: string) => {
 }
 
 function startListener(rt: Runtime, listen: { host: string; port: number }, fingerprint: string): Listener {
-  const listener: Listener = { server: createServer(), listen, fingerprint, mismatchLogged: false, bound: false }
+  const listener: Listener = { server: createServer(), listen, fingerprint, mismatchLogged: false, bound: false, bindFailures: 0, bindLoggedAt: 0 }
   listener.server.on("request", (request, response) => {
     const current = preferred(rt)
     if (!current) return unavailable(response, "plugboard is reloading")
@@ -325,22 +334,39 @@ function startListener(rt: Runtime, listen: { host: string; port: number }, fing
   })
   listener.server.on("error", (error: NodeJS.ErrnoException) => {
     if (listener.bound) return logError("listener.error", { code: error.code, error: error.message })
-    // Never bound: another process (or an older runtime) owns the port. Log once, stay inert.
-    logError(error.code === "EADDRINUSE" ? "listener.address_in_use" : "listener.failed", {
-      listen: `${listen.host}:${listen.port}`,
-      error: error.message,
-    })
+    // Not bound: another process (or an older runtime) owns the port, so nothing here receives
+    // requests while clients may be sending their keys and prompts to whoever holds it. Say so
+    // loudly (error level, again every few minutes), keep trying, and mention it on every
+    // generation that registers meanwhile (`registerGeneration`).
+    listener.bindFailures++
+    if (Date.now() - listener.bindLoggedAt >= BIND_REMINDER_MS) {
+      listener.bindLoggedAt = Date.now()
+      logError(error.code === "EADDRINUSE" ? "listener.address_in_use" : "listener.failed", {
+        listen: `${listen.host}:${listen.port}`,
+        error: error.message,
+        status: "not serving: clients of this port reach another process",
+        action: "stop the process that holds the port or change `listen`; plugboard retries every 15s",
+      })
+    }
+    listener.retryTimer = setTimeout(() => {
+      listener.retryTimer = undefined
+      if (rt.listener === listener && !listener.bound) listener.server.listen(listen.port, listen.host)
+    }, BIND_RETRY_MS)
+    listener.retryTimer.unref?.()
   })
-  listener.server.listen(listen.port, listen.host, () => {
+  listener.server.on("listening", () => {
     listener.bound = true
-    log("listener.listening", { listen: `${listen.host}:${listen.port}` })
+    log("listener.listening", { listen: `${listen.host}:${listen.port}`, ...(listener.bindFailures > 0 ? { recoveredAfterFailedBinds: listener.bindFailures } : {}) })
+    listener.bindFailures = 0
   })
+  listener.server.listen(listen.port, listen.host)
   return listener
 }
 
 function closeListener(rt: Runtime, listener: Listener): void {
   if (rt.listener !== listener) return
   rt.listener = undefined
+  clearTimeout(listener.retryTimer)
   try {
     rt.pump?.stop()
   } catch {}
@@ -404,6 +430,13 @@ export function registerGeneration(input: GenerationInput): Registration {
   }
   if (listener.graceTimer) clearTimeout(listener.graceTimer)
   listener.graceTimer = undefined
+  if (listener.bindFailures > 0) {
+    logError("listener.not_serving", {
+      listen: `${listen.host}:${listen.port}`,
+      status: "another process holds the port; this generation serves nothing",
+      action: "stop that process or change `listen`",
+    })
+  }
   const generation: Generation = {
     directory,
     handler: input.handler,

package/src/session/caller.ts

@@ -23,7 +23,7 @@ import { log, logError } from "../log.js"
 import { RequestCollector } from "./events.js"
 import { ensureAppDir, makeTitle, renderTranscript } from "./history.js"
 import { describeError, type SessionPort } from "./host.js"
-import { ImageError, prepareImages } from "./media.js"
+import { ImageError, prepareImages, type RemoteImages } from "./media.js"
 import { REQUEST_PERMISSIONS, seedToolsFor } from "./seeds.js"
 import type { SessionStore } from "./state.js"
 
@@ -33,8 +33,8 @@ export interface SessionCallerDeps {
   readonly sessions: SessionStore
   /** The seed pool size of the app directories (option `maxTools`); a request needing more tools fails before dispatch. */
   readonly maxTools: number
-  /** Allow fetching http(s) image URLs (option `remoteImages`). */
-  readonly remoteImages?: boolean
+  /** Allow fetching http(s) image URLs (option `remoteImages`: off, public addresses only, or with an allowlist). */
+  readonly remoteImages?: RemoteImages
   /**
    * Make sure the backend of `app` can run request sessions (the app directory's plugin is loaded),
    * called right before `session.create`. An error ends the request without creating anything.
@@ -85,7 +85,7 @@ function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
 
 export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
   const { port, sessions, maxTools, ensureBackend } = deps
-  const remoteImages = deps.remoteImages === true
+  const remoteImages = deps.remoteImages ?? false
 
   return {
     async *stream(request: PlugRequest, context: CallContext): AsyncGenerator<PlugEvent> {
@@ -134,7 +134,7 @@ export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
         if (unavailable) return yield note({ type: "error", error: unavailable })
         if (context.signal.aborted) return
 
-        collector = new RequestCollector({ stopTurn: interrupt })
+        collector = new RequestCollector({ stopTurn: interrupt, requestID })
         const created = await raceAbort(port.create({
           directory,
           model: { providerID: request.ref.providerID, id: request.ref.id, ...(request.ref.variant ? { variant: request.ref.variant } : {}) },

package/src/session/events.ts

@@ -12,6 +12,7 @@
  */
 
 import { isPlugError, type PlugError, type PlugEvent, type PlugFinish, type PlugUsage } from "../contract.js"
+import { logError } from "../log.js"
 import type { BusEvent } from "./host.js"
 import { FAILURE_EVENT } from "./state.js"
 
@@ -116,6 +117,8 @@ interface RawError {
   readonly type?: string
   readonly message?: string
   readonly status?: number
+  /** Raw provider response. Read for classification and the log only; never copied to the caller. */
+  readonly response?: { readonly body?: string }
 }
 
 const total = (...parts: Array<number | undefined>): number | undefined =>
@@ -138,23 +141,56 @@ const toUsage = (tokens?: RawUsage): PlugUsage | undefined =>
       }
     : undefined
 
-/** Host `SessionError` (`{ type, message, status?, response? }`) to a `PlugError`. */
+/** Provider wording for "the prompt does not fit the model" (a subset of the host's own matcher; the host does not forward its classification). */
+const CONTEXT_OVERFLOW =
+  /context[_ ](?:length|window)|maximum context|prompt (?:is )?too long|too many tokens|token limit|input length.*exceeds|exceeds the (?:available )?context|reduce the length of the messages/i
+
+/**
+ * Host `SessionError` (`{ type, message, status?, response? }`) to a `PlugError`. Provider and host
+ * error text can carry endpoints, account or organization ids, so it never reaches the caller:
+ * the caller gets a stable `code` and a fixed message per class. The classes a caller can act on
+ * stay distinct (rate limit, quota, context length, provider credentials, timeout, content filter).
+ * The raw text goes to the log only (`RequestCollector.failFromHost`).
+ */
 function toPlugError(error: RawError | undefined, fallback: string): PlugError {
   const status = typeof error?.status === "number" && error.status >= 400 ? error.status : undefined
-  const message = error?.message || fallback
-  const base = { message, ...(error?.type ? { code: error.type } : {}) }
-  if (status === 401) return { status, kind: "authentication", ...base }
-  if (status === 403) return { status, kind: "permission", ...base }
-  if (status === 404) return { status, kind: "not_found", ...base }
-  if (status === 429) return { status, kind: "rate_limit", ...base }
-  if (status === 408 || status === 504) return { status, kind: "timeout", ...base }
-  if (status !== undefined && status < 500) return { status, kind: "invalid_request", ...base }
-  return { status: status ?? 502, kind: "server", ...base }
+  const type = error?.type ?? ""
+  // Our own constant (the session caller reports a prompt that could not start); the host never uses this type.
+  if (type === "prompt_failed") return { status: 502, kind: "server", code: "prompt_failed", message: error?.message || fallback }
+  if (type === "provider.rate-limit" || status === 429) {
+    return { status: 429, kind: "rate_limit", code: "rate_limited", message: "The model provider is rate limiting requests; retry later" }
+  }
+  if (type === "provider.quota") {
+    return { status: 429, kind: "rate_limit", code: "quota_exceeded", message: "The model provider's usage quota is exhausted" }
+  }
+  if ((type === "provider.invalid-request" || status === 400 || status === 413) && CONTEXT_OVERFLOW.test(`${error?.message ?? ""}\n${error?.response?.body ?? ""}`)) {
+    return { status: 400, kind: "invalid_request", code: "context_length_exceeded", param: "messages", message: "The request is longer than the model's context window" }
+  }
+  if (type === "provider.auth" || status === 401 || status === 403) {
+    const message = "The model provider rejected its credentials; the plugboard host needs to sign in again"
+    if (status === 401) return { status, kind: "authentication", code: "provider_auth_failed", message }
+    if (status === 403) return { status, kind: "permission", code: "provider_auth_failed", message }
+    return { status: 502, kind: "server", code: "provider_auth_failed", message }
+  }
+  if (type === "provider.content-filter") {
+    return { status: 400, kind: "invalid_request", code: "content_filter", message: "The model provider's content filter blocked the request" }
+  }
+  if (type === "provider.timeout" || status === 408 || status === 504) {
+    return { status: 504, kind: "timeout", code: "provider_timeout", message: "The model provider timed out" }
+  }
+  if (type.startsWith("provider.")) {
+    if (status === 404) return { status, kind: "not_found", code: "provider_rejected_request", message: "The model provider rejected the request" }
+    if (status !== undefined && status < 500) return { status, kind: "invalid_request", code: "provider_rejected_request", message: "The model provider rejected the request" }
+    return { status: status ?? 502, kind: "server", code: "provider_unavailable", message: "The model provider is unavailable or returned an error" }
+  }
+  return { status: 502, kind: "server", code: "model_run_failed", message: fallback }
 }
 
 export interface CollectorHooks {
   /** The step ended with tool calls: stop the turn before the runner starts another model step. */
   readonly stopTurn: () => void
+  /** The request's id, for the log line that carries a failure's raw host text. */
+  readonly requestID?: string
 }
 
 export class RequestCollector {
@@ -268,11 +304,11 @@ export class RequestCollector {
         if (this.calls.size > 0 && error?.type === "aborted") return this.finishWith("tool-calls")
         if (item.finish === "content-filter") return this.finishWith("content-filter")
         if (error?.type === "aborted" && this.wasCancelled) return this.end()
-        return this.fail(toPlugError(error, "Model step failed"))
+        return this.failFromHost(error, "Model step failed")
       }
       case "session.execution.failed":
         this.executionDone = true
-        if (!this.finished) this.fail(toPlugError(item.error as RawError | undefined, "Session execution failed"))
+        if (!this.finished) this.failFromHost(item.error as RawError | undefined, "Session execution failed")
         this.end()
         return
       case "session.execution.interrupted":
@@ -310,6 +346,18 @@ export class RequestCollector {
     this.end()
   }
 
+  /** Fail with the caller-safe mapping of a host error; the raw text is logged here and goes nowhere else. */
+  private failFromHost(raw: RawError | undefined, fallback: string): void {
+    if (this.finished) return
+    logError("model.failed", {
+      requestID: this.hooks.requestID,
+      type: raw?.type,
+      status: raw?.status,
+      message: raw?.message?.slice(0, 500),
+    })
+    this.fail(toPlugError(raw, fallback))
+  }
+
   private fail(error: PlugError): void {
     if (this.finished) return
     this.emit({ type: "error", error })

package/src/session/history.ts

@@ -50,9 +50,20 @@ const firstUserText = (request: PlugRequest): string => {
   return request.model
 }
 
-/** Session title: the first user text, whitespace-collapsed and cut to 60 characters. */
+/**
+ * Control characters that terminal and app UIs act on: C0 (ESC, BEL, CR, ...), DEL, C1 (8-bit CSI),
+ * and the bidirectional marks and overrides (ALM, LRM, RLM, U+202A-202E, U+2066-2069) that reorder text.
+ * `\t` and `\n` are included here; callers that keep layout use `LAYOUT_SAFE`.
+ */
+const CONTROLS = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g
+const CONTROLS_KEEP_LAYOUT = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g
+
+/** One display line: whitespace (including line breaks) collapsed to single spaces, then control and bidi characters removed. */
+export const oneLine = (text: string): string => text.replace(/\s+/g, " ").replace(CONTROLS, "").trim()
+
+/** Session title: the first user text, one line, control and bidi characters removed, cut to 60 characters. */
 export const makeTitle = (request: PlugRequest): string => {
-  const flat = firstUserText(request).replace(/\s+/g, " ").trim()
+  const flat = oneLine(firstUserText(request))
   return flat.length > TITLE_LENGTH ? flat.slice(0, TITLE_LENGTH - 1) + "…" : flat
 }
 
@@ -74,16 +85,17 @@ export function renderTranscript(request: PlugRequest): string {
           lines.push(`[image ${++image}]`)
           break
         case "tool-call":
-          lines.push(`[tool call ${part.name} (${part.id})] ${typeof part.input === "string" ? part.input : JSON.stringify(part.input)}`)
+          lines.push(`[tool call ${oneLine(part.name)} (${oneLine(part.id)})] ${typeof part.input === "string" ? part.input : JSON.stringify(part.input)}`)
           break
         case "tool-result":
-          lines.push(`[tool result ${part.name} (${part.id})${part.isError ? " (error)" : ""}] ${part.result}`)
+          lines.push(`[tool result ${oneLine(part.name)} (${oneLine(part.id)})${part.isError ? " (error)" : ""}] ${part.result}`)
           break
       }
     }
     lines.push("")
   }
-  if (request.tools.length > 0) lines.push("## tools", request.tools.map((tool) => tool.name).join(", "), "")
-  const text = lines.join("\n").trim()
+  if (request.tools.length > 0) lines.push("## tools", request.tools.map((tool) => oneLine(tool.name)).join(", "), "")
+  // The stored text is display only (the model sees the structured request): body text keeps its line breaks and tabs, nothing else that a UI would act on.
+  const text = lines.join("\n").replace(CONTROLS_KEEP_LAYOUT, "").trim()
   return text.length > 0 ? text : "(empty request)"
 }

package/src/session/media.ts

@@ -4,20 +4,39 @@
  * Prompt files must be inline `data:` URLs. http(s) images are fetched once, only when the
  * `remoteImages` option is on, with no redirects, a 20 s timeout and a 20 MB cap. All images of
  * one request together may hold at most 50 MB (`images_too_large`), data URLs and fetched ones alike.
+ *
+ * A remote fetch is a request the server makes on a caller's behalf, so it must not reach the
+ * 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.
  */
 
+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 type { PlugRequest } from "../contract.js"
+import { log } from "../log.js"
 
 const MAX_REMOTE_IMAGE_BYTES = 20 * 1024 * 1024
 /** Aggregate size of the prepared data URLs of one request. */
 const MAX_TOTAL_IMAGE_BYTES = 50 * 1024 * 1024
+const FETCH_TIMEOUT_MS = 20_000
 const TOO_MANY = () => new ImageError("images_too_large", "The request's images are larger than 50 MB in total")
+/** The one message for every failed fetch (blocked address, DNS, refused, timeout, bad status): no oracle for the server's network. */
+const FETCH_FAILED = () => new ImageError("image_fetch_failed", "Could not fetch image")
 
 /** What one request's images may still use, in data URL characters (== bytes held). */
 interface Budget {
   remaining: number
 }
 
+/** The `remoteImages` option as the session caller receives it: off, on (public addresses only), or on with an allowlist. */
+export type RemoteImages = boolean | { readonly allow: ReadonlyArray<string> }
+
 /** A caller image that cannot be used; `code` becomes the error code of the 400 response. */
 export class ImageError extends Error {
   constructor(
@@ -28,41 +47,255 @@ export class ImageError extends Error {
   }
 }
 
-async function toDataUrl(url: string, signal: AbortSignal, remoteImages: boolean, budget: Budget): Promise<string> {
+// ---- addresses
+
+interface Ip {
+  readonly family: 4 | 6
+  readonly bytes: ReadonlyArray<number>
+}
+
+/** Dotted IPv4 or any IPv6 text form (compressed, with an embedded IPv4 tail, with a zone) to bytes. */
+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
+  }
+  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
+}
+
+const cidrs = (list: string[]): Cidr[] => list.map((entry) => parseCidr(entry)!)
+
+/** 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
+])
+
+/**
+ * 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).
+ */
+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
+}
+
+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))
+}
+
+// ---- 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 }
+
+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 }
+  return HOSTNAME.test(text) && !text.includes("/") ? { kind: "host", name: text } : undefined
+}
+
+const hostMatches = (entry: { readonly name: string }, host: string): boolean =>
+  entry.name.startsWith("*.") ? host.endsWith(entry.name.slice(1)) : host === entry.name
+
+/** All addresses of `host`, in resolver order; rejects when `signal` aborts (the lookup itself cannot be cancelled). */
+function resolveAddresses(host: string, signal: AbortSignal): Promise<string[]> {
+  return new Promise((done, fail) => {
+    const onAbort = () => fail(signal.reason)
+    if (signal.aborted) return onAbort()
+    signal.addEventListener("abort", onAbort, { once: true })
+    lookup(host, { all: true, verbatim: true }).then(
+      (found) => (signal.removeEventListener("abort", onAbort), done(found.map((entry) => entry.address))),
+      (error) => (signal.removeEventListener("abort", onAbort), fail(error)),
+    )
+  })
+}
+
+/**
+ * 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.
+ */
+async function pickAddress(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)
+  const nameAllowed = allow.some((entry) => entry.kind === "host" && hostMatches(entry, host))
+  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))
+  }
+  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]!
+}
+
+/** 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. */
+function get(url: URL, address: string, signal: AbortSignal): Promise<IncomingMessage> {
+  return new Promise((resolve, reject) => {
+    const secure = url.protocol === "https:"
+    const name = url.hostname.replace(/^\[|\]$/g, "")
+    const request = (secure ? httpsRequest : httpRequest)(
+      {
+        host: address,
+        port: url.port === "" ? (secure ? 443 : 80) : Number(url.port),
+        path: `${url.pathname}${url.search}`,
+        method: "GET",
+        agent: false,
+        headers: { host: url.host, accept: "image/*", "user-agent": "opencode-plugboard" },
+        // Certificate checks use the URL's host name, not the pinned address.
+        ...(secure && isIP(name) === 0 ? { servername: name } : {}),
+      },
+      resolve,
+    )
+    request.on("error", reject)
+    const abort = () => request.destroy(new Error("aborted"))
+    request.on("close", () => signal.removeEventListener("abort", abort))
+    if (signal.aborted) return abort()
+    signal.addEventListener("abort", abort, { once: true })
+    request.end()
+  })
+}
+
+// ---- preparation
+
+async function toDataUrl(url: string, signal: AbortSignal, remoteImages: RemoteImages, budget: Budget): Promise<string> {
   if (url.startsWith("data:")) {
     if (url.length > budget.remaining) throw TOO_MANY()
     return url
   }
   if (!/^https?:\/\//i.test(url)) throw new ImageError("unsupported_image_url", "Unsupported image URL scheme; use a data: URL or an http(s) URL")
-  if (!remoteImages)
+  if (remoteImages === false)
     throw new ImageError("remote_images_disabled", "Remote image URLs are disabled; send a data: URL or set the plugboard `remoteImages` option")
-  // Messages never carry the URL or the fetch error text: both can hold credentials in the query string.
-  const response = await fetch(url, { redirect: "error", signal: AbortSignal.any([signal, AbortSignal.timeout(20_000)]) }).catch((error: unknown) => {
-    const reason = error instanceof Error && error.name === "TimeoutError" ? "timed out" : "network error"
-    throw new ImageError("image_fetch_failed", `Could not fetch image (${reason})`)
+
+  // Messages never carry the URL, the status, the content type or the fetch error text: they can hold
+  // credentials in the query string or describe the server's network to the caller.
+  const bounded = AbortSignal.any([signal, AbortSignal.timeout(FETCH_TIMEOUT_MS)])
+  let target: URL
+  try {
+    target = new URL(url)
+  } catch {
+    throw FETCH_FAILED()
+  }
+  const allow = typeof remoteImages === "object" ? remoteImages.allow.flatMap((entry) => parseAllowEntry(entry) ?? []) : []
+  const address = await pickAddress(target, allow, bounded).catch((error: unknown) => {
+    throw error instanceof ImageError ? error : FETCH_FAILED()
+  })
+  const response = await get(target, address, bounded).catch(() => {
+    throw FETCH_FAILED()
   })
-  if (!response.ok) throw new ImageError("image_fetch_failed", `Could not fetch image (HTTP ${response.status})`)
-  const mediaType = response.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase() ?? ""
-  if (!mediaType.startsWith("image/")) throw new ImageError("invalid_image", `URL did not return an image (content-type: ${mediaType || "none"})`)
-  const declared = Number(response.headers.get("content-length"))
+  // 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()
+    throw FETCH_FAILED()
+  }
+  const mediaType = (response.headers["content-type"] ?? "").split(";")[0]?.trim().toLowerCase() ?? ""
+  if (!mediaType.startsWith("image/")) {
+    response.destroy()
+    throw new ImageError("invalid_image", "URL did not return an image")
+  }
+  const declared = Number(response.headers["content-length"])
   // The data URL is 4/3 of the raw size plus a short prefix: stop reading once it cannot fit the budget.
   const budgetRaw = Math.floor((budget.remaining * 3) / 4)
   const limit = Math.min(MAX_REMOTE_IMAGE_BYTES, budgetRaw)
   const tooLarge = () => (limit < MAX_REMOTE_IMAGE_BYTES ? TOO_MANY() : new ImageError("image_too_large", "Image is larger than 20 MB"))
-  if (Number.isFinite(declared) && declared > limit) throw tooLarge()
-  const chunks: Uint8Array[] = []
+  if (Number.isFinite(declared) && declared > limit) {
+    response.destroy()
+    throw tooLarge()
+  }
+  const chunks: Buffer[] = []
   let size = 0
-  const reader = response.body?.getReader()
-  if (!reader) throw new ImageError("invalid_image", "Image response had no body")
-  while (true) {
-    const { done, value } = await reader.read()
-    if (done) break
-    size += value.byteLength
-    if (size > limit) {
-      void reader.cancel().catch(() => {})
-      throw tooLarge()
+  try {
+    for await (const chunk of response as AsyncIterable<Buffer>) {
+      size += chunk.byteLength
+      if (size > limit) throw tooLarge()
+      chunks.push(chunk)
     }
-    chunks.push(value)
+  } catch (error) {
+    response.destroy()
+    throw error instanceof ImageError ? error : FETCH_FAILED()
   }
   const dataUrl = `data:${mediaType};base64,${Buffer.concat(chunks).toString("base64")}`
   if (dataUrl.length > budget.remaining) throw TOO_MANY()
@@ -73,7 +306,7 @@ async function toDataUrl(url: string, signal: AbortSignal, remoteImages: boolean
 export async function prepareImages(
   request: PlugRequest,
   signal: AbortSignal,
-  remoteImages: boolean,
+  remoteImages: RemoteImages,
 ): Promise<Array<{ uri: string; name: string }>> {
   const images: Array<{ uri: string; name: string }> = []
   const budget: Budget = { remaining: MAX_TOTAL_IMAGE_BYTES }