dsh-permission-rules 0.6.21 → 0.7.0

package/src/config.ts

@@ -64,8 +64,29 @@ export interface NetworkConfig {
   injectEnv?: boolean
   /** Subprocess NO_PROXY handling: `clear` enforces the policy (default) or `preserve` keeps ambient values. */
   noProxy?: NoProxyPolicy
+  /**
+   * Upstream proxy for connections this proxy ALLOWS: `off` (default — dial
+   * directly), `inherit` (reuse the proxy names from the launch environment),
+   * or an explicit `http(s)://` proxy URL. A blocked connection never reaches
+   * it, and `ips`-scoped decisions plus loopback targets are never chained —
+   * see the network section of the READMEs.
+   */
+  upstreamProxy?: UpstreamProxySetting
+  /**
+   * Whether the settings page may run its "allow this host" action, which
+   * writes one minimal `domains` allow rule into the nearest effective rule
+   * file (`true` by default). `false` hides the button and makes the
+   * `permissionRules/allowHost` RPC refuse: the page's rule EDITOR is
+   * strictly wider (it writes arbitrary rule text) and is not affected, so
+   * this is a narrow safety switch for deployments that want rule changes to
+   * stay a deliberate, hand-written act.
+   */
+  allowHostAction?: boolean
 }
 
+/** Upstream chaining setting: `off`, `inherit`, or an explicit http(s) proxy URL. */
+export type UpstreamProxySetting = 'off' | 'inherit' | string
+
 /** Raw plugin config — every field optional; {@link Config} supplies the defaults. */
 export interface Config {
   /**
@@ -142,6 +163,8 @@ export interface ResolvedNetworkConfig {
   readonly loopback: LoopbackPolicy
   readonly injectEnv: boolean
   readonly noProxy: NoProxyPolicy
+  readonly upstreamProxy: UpstreamProxySetting
+  readonly allowHostAction: boolean
 }
 
 /** Builtin baseline after {@link resolveConfig}: the switch plus the resolved absolute path. */
@@ -200,6 +223,8 @@ export const Config: z<Config> = z.object({
     loopback: z.union(['allow', 'policy'] as const).default('allow'),
     injectEnv: z.boolean().default(true),
     noProxy: z.union(['clear', 'preserve'] as const).default('clear'),
+    upstreamProxy: z.string().default('off'),
+    allowHostAction: z.boolean().default(true),
   }),
   builtin: z.object({
     enabled: z.boolean().default(true),
@@ -292,6 +317,7 @@ function resolveNetworkConfig(raw: NetworkConfig | undefined): ResolvedNetworkCo
   assertEnum('network.noProxy', noProxy, ['clear', 'preserve'])
   assertBoolean('network.enabled', raw?.enabled ?? true)
   assertBoolean('network.injectEnv', raw?.injectEnv ?? true)
+  assertBoolean('network.allowHostAction', raw?.allowHostAction ?? true)
   const proxyBind = raw?.proxyBind ?? '127.0.0.1'
   if (typeof proxyBind !== 'string' || proxyBind.trim().length === 0) {
     throw new TypeError(`network.proxyBind must be a non-empty string, got ${typeof proxyBind}`)
@@ -304,6 +330,8 @@ function resolveNetworkConfig(raw: NetworkConfig | undefined): ResolvedNetworkCo
   if (!Number.isSafeInteger(proxyMaxRecent) || proxyMaxRecent <= 0) {
     throw new TypeError(`network.proxyMaxRecent must be a positive safe integer, got ${String(raw?.proxyMaxRecent)}`)
   }
+  const upstreamProxy = raw?.upstreamProxy ?? 'off'
+  assertUpstreamProxy(upstreamProxy)
   return {
     enabled: raw?.enabled ?? true,
     mode: mode as 'auto' | NetworkMode,
@@ -315,7 +343,35 @@ function resolveNetworkConfig(raw: NetworkConfig | undefined): ResolvedNetworkCo
     loopback,
     injectEnv: raw?.injectEnv ?? true,
     noProxy,
+    upstreamProxy,
+    allowHostAction: raw?.allowHostAction ?? true,
+  }
+}
+
+/**
+ * Throw unless `value` is `off`, `inherit`, or a usable http(s) proxy URL.
+ *
+ * Node has no SOCKS client, and the harness's own policy refuses a proxy URL it
+ * cannot express for a scheme, so a SOCKS value is rejected at the mount with an
+ * actionable message instead of failing at connect time. `''` is rejected too:
+ * an empty string reads as "no upstream" but silently disables chaining.
+ */
+function assertUpstreamProxy(value: string): void {
+  const invalid = (detail: string): TypeError =>
+    new TypeError(`network.upstreamProxy must be "off" | "inherit" | an http(s) proxy URL, got ${JSON.stringify(value)}${detail}`)
+  if (value === 'off' || value === 'inherit') return
+  if (typeof value !== 'string' || value.trim().length === 0) throw invalid('')
+  let parsed: URL | undefined
+  try {
+    parsed = new URL(value)
+  } catch {
+    parsed = undefined
+  }
+  if (parsed === undefined) throw invalid('')
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw invalid(` (${parsed.protocol}// is not supported: Node has no SOCKS client, so give an http:// or https:// proxy)`)
   }
+  if (parsed.hostname.length === 0) throw invalid(' (it must name a host)')
 }
 
 /** Throw unless `key` is one of `allowed` (TypeScript's closed enums are not runtime checks). */

package/src/prose.ts

@@ -64,6 +64,7 @@ export interface UiProse {
   networkHeader: (mode: string, sandboxMode: string | undefined, configuredMode: string, proxyActive: boolean, proxyPort: number) => string
   /** Cumulative block counters line. */
   networkCounters: (denied: number, askBlocked: number) => string
+  networkUpstream: (mode: 'off' | 'inherit' | 'url', http: string | null, https: string | null, active: boolean, chained: number) => string
   /** Line shown when no proxy blocks were recorded yet. */
   noNetworkBlocks: string
   /** One recent proxy-block row. */
@@ -129,6 +130,7 @@ const EN: UiProse = {
   networkDisabled: 'Network policy disabled (network.enabled: false): no proxy, no web-tool mode defaults.',
   networkHeader: (mode, sandboxMode, configuredMode, proxyActive, proxyPort) => `Network policy: mode ${mode}${sandboxMode === undefined ? '' : ` (sandbox preset ${sandboxMode})`}${configuredMode === 'auto' ? '' : ` (configured ${configuredMode})`}; proxy ${proxyActive ? `active on 127.0.0.1:${proxyPort}` : 'INACTIVE (bind failed — shell network policy is not enforced)'}.`,
   networkCounters: (denied, askBlocked) => `Blocks: ${denied} denied, ${askBlocked} ask-blocked.`,
+  networkUpstream: (mode, http, https, active, chained) => `Upstream: ${mode}${http === null ? '' : ` http ${http}`}${https === null ? '' : ` https ${https}`}${active ? '' : ' (inactive)'}, ${chained} chained.`,
   noNetworkBlocks: 'No network blocks recorded yet.',
   networkBlockLine: (time, tool, attributed, domain, scheme, port, action, matched, ruleIndex, reason) => {
     const when = new Date(time).toISOString()
@@ -172,6 +174,7 @@ const ZH: UiProse = {
   networkDisabled: '网络策略已停用（network.enabled: false）：无代理、无 web 工具模式默认裁决。',
   networkHeader: (mode, sandboxMode, configuredMode, proxyActive, proxyPort) => `网络策略：模式 ${mode}${sandboxMode === undefined ? '' : `（沙箱预设 ${sandboxMode}）`}${configuredMode === 'auto' ? '' : `（显式配置 ${configuredMode}）`}；代理${proxyActive ? `运行于 127.0.0.1:${proxyPort}` : '未激活（绑定失败——shell 网络策略未生效）'}。`,
   networkCounters: (denied, askBlocked) => `拦截：拒绝 ${denied} 次，待审批阻断 ${askBlocked} 次。`,
+  networkUpstream: (mode, http, https, active, chained) => `上游：${mode}${http === null ? '' : ` http ${http}`}${https === null ? '' : ` https ${https}`}${active ? '' : '（未生效）'}，已链式 ${chained} 条。`,
   noNetworkBlocks: '尚未记录任何网络拦截。',
   networkBlockLine: (time, tool, attributed, domain, scheme, port, action, matched, ruleIndex, reason) => {
     const when = new Date(time).toISOString()
@@ -215,6 +218,7 @@ const ES: UiProse = {
   networkDisabled: 'Política de red desactivada (network.enabled: false): sin proxy, sin valores predeterminados de modo para herramientas web.',
   networkHeader: (mode, sandboxMode, configuredMode, proxyActive, proxyPort) => `Política de red: modo ${mode}${sandboxMode === undefined ? '' : ` (preset sandbox ${sandboxMode})`}${configuredMode === 'auto' ? '' : ` (configurado ${configuredMode})`}; proxy ${proxyActive ? `activo en 127.0.0.1:${proxyPort}` : 'INACTIVO (fallo de bind — la política de red de shell no se aplica)'}.`,
   networkCounters: (denied, askBlocked) => `Bloqueos: ${denied} denegados, ${askBlocked} bloqueados por aprobación.`,
+  networkUpstream: (mode, http, https, active, chained) => `Upstream: ${mode}${http === null ? '' : ` http ${http}`}${https === null ? '' : ` https ${https}`}${active ? '' : ' (inactivo)'}, ${chained} encadenadas.`,
   noNetworkBlocks: 'Aún no se han registrado bloqueos de red.',
   networkBlockLine: (time, tool, attributed, domain, scheme, port, action, matched, ruleIndex, reason) => {
     const when = new Date(time).toISOString()
@@ -258,6 +262,7 @@ const PT: UiProse = {
   networkDisabled: 'Política de rede desativada (network.enabled: false): sem proxy, sem padrões de modo para ferramentas web.',
   networkHeader: (mode, sandboxMode, configuredMode, proxyActive, proxyPort) => `Política de rede: modo ${mode}${sandboxMode === undefined ? '' : ` (preset sandbox ${sandboxMode})`}${configuredMode === 'auto' ? '' : ` (configurado ${configuredMode})`}; proxy ${proxyActive ? `ativo em 127.0.0.1:${proxyPort}` : 'INATIVO (falha de bind — a política de rede do shell não está ativa)'}.`,
   networkCounters: (denied, askBlocked) => `Bloqueios: ${denied} negados, ${askBlocked} bloqueados por aprovação.`,
+  networkUpstream: (mode, http, https, active, chained) => `Upstream: ${mode}${http === null ? '' : ` http ${http}`}${https === null ? '' : ` https ${https}`}${active ? '' : ' (inativo)'}, ${chained} encadeadas.`,
   noNetworkBlocks: 'Nenhum bloqueio de rede registrado ainda.',
   networkBlockLine: (time, tool, attributed, domain, scheme, port, action, matched, ruleIndex, reason) => {
     const when = new Date(time).toISOString()
@@ -301,6 +306,7 @@ const HI: UiProse = {
   networkDisabled: 'नेटवर्क नीति अक्षम (network.enabled: false): कोई प्रॉक्सी नहीं, कोई वेब-टूल मोड डिफ़ॉल्ट नहीं।',
   networkHeader: (mode, sandboxMode, configuredMode, proxyActive, proxyPort) => `नेटवर्क नीति: मोड ${mode}${sandboxMode === undefined ? '' : ` (सैंडबॉक्स प्रीसेट ${sandboxMode})`}${configuredMode === 'auto' ? '' : ` (कॉन्फ़िगर किया ${configuredMode})`}; प्रॉक्सी ${proxyActive ? `सक्रिय 127.0.0.1:${proxyPort} पर` : 'निष्क्रिय (बाइंड विफल — शेल नेटवर्क नीति लागू नहीं)'}।`,
   networkCounters: (denied, askBlocked) => `ब्लॉक: ${denied} अस्वीकृत, ${askBlocked} अनुमोदन-ब्लॉक।`,
+  networkUpstream: (mode, http, https, active, chained) => `Upstream: ${mode}${http === null ? '' : ` http ${http}`}${https === null ? '' : ` https ${https}`}${active ? '' : ' (निष्क्रिय)'}, ${chained} श्रृंखलित।`,
   noNetworkBlocks: 'अभी तक कोई नेटवर्क ब्लॉक दर्ज नहीं हुआ।',
   networkBlockLine: (time, tool, attributed, domain, scheme, port, action, matched, ruleIndex, reason) => {
     const when = new Date(time).toISOString()

package/src/proxy.ts

@@ -24,7 +24,7 @@ import type { Duplex } from 'node:stream'
 import type { Server, IncomingMessage, RequestOptions, ServerResponse } from 'node:http'
 import type { CallId } from './call-id.ts'
 import type { NetworkDecision, NetworkMode } from './network.ts'
-import { blockMessage } from './network.ts'
+import { blockMessage, isLoopbackTarget } from './network.ts'
 import { isIpLiteral, parseUrlTarget } from './rules.ts'
 import type { NetworkTarget, SchemeName } from './rules.ts'
 
@@ -34,6 +34,73 @@ export const PROXY_ENV_NAMES: readonly string[] = ['HTTP_PROXY', 'HTTPS_PROXY',
 /** NO_PROXY names cleared (or preserved) by the injector. */
 export const NO_PROXY_ENV_NAMES: readonly string[] = ['NO_PROXY', 'no_proxy']
 
+/** How long a chained CONNECT waits for the upstream to answer before it gives up. */
+const UPSTREAM_CONNECT_TIMEOUT_MS = 10_000
+
+/** The upstream proxies the launch environment supplies, resolved per scheme. */
+export interface AmbientUpstream {
+  readonly http?: string
+  readonly https?: string
+}
+
+/**
+ * Resolve ambient upstream candidates the way the harness's own proxy policy
+ * does: the scheme-specific name (lowercase first, blank treated as unset),
+ * then `ALL_PROXY`, then — for https only — the http name. A value that is not
+ * a parseable `http(s)://` URL is dropped here; the runtime reports those once.
+ * @param lookup - reads one environment name (the launch snapshot, or `process.env`).
+ * @returns the usable candidates, each absent when it is unusable.
+ */
+export function readAmbientProxy(lookup: (name: string) => string | undefined): AmbientUpstream {
+  const pick = (names: readonly string[]): string | undefined => {
+    for (const name of names) {
+      const value = lookup(name)
+      if (value !== undefined && value.trim().length > 0) return value.trim()
+    }
+    return undefined
+  }
+  const usable = (value: string | undefined): string | undefined => {
+    if (value === undefined) return undefined
+    try {
+      const parsed = new URL(value)
+      return parsed.protocol === 'http:' || parsed.protocol === 'https:' ? value : undefined
+    } catch {
+      return undefined
+    }
+  }
+  const all = usable(pick(['ALL_PROXY', 'all_proxy']))
+  const http = usable(pick(['http_proxy', 'HTTP_PROXY'])) ?? all
+  const https = usable(pick(['https_proxy', 'HTTPS_PROXY'])) ?? all ?? http
+  return { ...(http === undefined ? {} : { http }), ...(https === undefined ? {} : { https }) }
+}
+
+/**
+ * The loggable form of a proxy URL: the password is replaced, everything else
+ * is kept verbatim. An upstream URL may carry credentials, and a proxy URL is
+ * printed in warnings, `/rules network` and the settings snapshot, so it must
+ * never be emitted raw.
+ * @param value - the configured upstream URL.
+ * @returns the same URL with its password masked, or the input when unparseable.
+ */
+export function redactProxyUrl(value: string): string {
+  try {
+    const parsed = new URL(value)
+    if (parsed.username === '' && parsed.password === '') return value
+    const user = parsed.username
+    const auth = parsed.password === '' ? `${user}@` : `${user}:***@`
+    return `${parsed.protocol}//${auth}${parsed.host}`
+  } catch {
+    return value
+  }
+}
+
+/** The `Proxy-Authorization` value for an upstream URL carrying userinfo. */
+function proxyAuthorization(url: URL): string | undefined {
+  if (url.username === '' && url.password === '') return undefined
+  const credentials = `${decodeURIComponent(url.username)}:${decodeURIComponent(url.password)}`
+  return `Basic ${Buffer.from(credentials).toString('base64')}`
+}
+
 /** One recorded proxy-layer block (settings-page list + session audit + logger). */
 export interface NetworkBlockRecord {
   readonly time: number
@@ -49,6 +116,13 @@ export interface NetworkBlockRecord {
   readonly source: string
   readonly ruleIndex?: number
   readonly reason?: string
+  /**
+   * The attributed agent's workspace root, when the block could be attributed
+   * to a session at all. The settings page needs it to name the rule file an
+   * "allow this host" action would write; an unattributed (host-level) block
+   * leaves it unset.
+   */
+  readonly cwd?: string
 }
 
 /** Cumulative proxy-layer block counters. */
@@ -62,7 +136,11 @@ export interface ProxyAttribution {
   readonly tool: string
   readonly callId?: CallId
   readonly agent?: {
-    readonly session: { append(type: 'permissionRules/network', data: unknown, options?: { ignorable?: true }): unknown }
+    readonly session: {
+      /** The session header the block's workspace is read from. */
+      readonly header: { readonly cwd?: string }
+      append(type: 'permissionRules/network', data: unknown, options?: { ignorable?: true }): unknown
+    }
   }
 }
 
@@ -82,6 +160,12 @@ export interface NetworkProxyOptions {
   readonly onBlock?: (record: NetworkBlockRecord, attribution: ProxyAttribution | undefined) => void
   /** Logger sink (proxy failures must never crash the host). */
   readonly logger: { warn(message: string): void }
+  /**
+   * The upstream proxies an ALLOWED connection may be chained through, or
+   * undefined to dial directly. A getter, so a live settings change takes
+   * effect on the next connection.
+   */
+  readonly upstream?: () => AmbientUpstream | undefined
 }
 
 /**
@@ -96,9 +180,15 @@ export class NetworkProxy {
   private readonly recent: NetworkBlockRecord[] = []
   private readonly stats: NetworkStats = { denied: 0, askBlocked: 0 }
   private actualPort = 0
+  private chained = 0
 
   constructor(private readonly options: NetworkProxyOptions) {}
 
+  /** Connections dispatched through the configured upstream since mount. */
+  chainedConnections(): number {
+    return this.chained
+  }
+
   /** The bound port (valid after {@link start} resolves). */
   get port(): number {
     return this.actualPort
@@ -155,6 +245,76 @@ export class NetworkProxy {
     })
   }
 
+  /**
+   * The upstream one ALLOWED connection may be chained through, or undefined to
+   * dial directly. Three vetoes, in order:
+   *
+   * 1. a loopback target never chains — a proxy outside this host cannot route
+   *    its loopback, and the harness's own policy bypasses loopback for the same
+   *    reason;
+   * 2. an `ips`-scoped decision never chains — chaining hands the hostname to
+   *    the upstream, so "the connection lands on an address the rules saw"
+   *    (the issue #21 invariant) would stop holding exactly where the rules
+   *    cared about the address;
+   * 3. no usable upstream for the target's scheme.
+   *
+   * A blocked connection never reaches this method: it is called only on the
+   * `allow` branch, after the decision is final.
+   * @param target - the adjudicated target.
+   * @param decision - the decision that allowed it.
+   * @returns the upstream URL to chain through, or undefined.
+   */
+  private upstreamRouteFor(target: NetworkTarget, decision: NetworkDecision): string | undefined {
+    const ambient = this.options.upstream?.()
+    if (ambient === undefined) return undefined
+    if (isLoopbackTarget(target)) return undefined
+    const ipsScope = decision.rule?.source.match.network?.ips
+    if (ipsScope !== undefined && ipsScope.length > 0) return undefined
+    return (target.scheme ?? 'http') === 'https' ? ambient.https : ambient.http
+  }
+
+  /**
+   * Open a tunnel by asking the upstream for one, and hand back the socket it
+   * established. The upstream's own hostname is resolved by the system: it is
+   * operator configuration, not agent input, so it takes no part in rule
+   * adjudication and is outside the adjudicated-address invariant.
+   * @param upstream - the upstream proxy URL.
+   * @param authority - the `host:port` to ask for (IPv6 already bracketed).
+   * @returns the established tunnel socket.
+   */
+  private connectViaUpstream(upstream: string, authority: string): Promise<Duplex> {
+    return new Promise((resolve, reject) => {
+      const via = new URL(upstream)
+      const send = via.protocol === 'https:' ? httpsRequest : httpRequest
+      const headers: Record<string, string> = { host: authority }
+      const auth = proxyAuthorization(via)
+      if (auth !== undefined) headers['proxy-authorization'] = auth
+      const req = send({
+        host: via.hostname,
+        port: via.port === '' ? (via.protocol === 'https:' ? 443 : 80) : Number(via.port),
+        method: 'CONNECT',
+        path: authority,
+        headers,
+      })
+      req.setTimeout(UPSTREAM_CONNECT_TIMEOUT_MS, () => { req.destroy(new Error('upstream CONNECT timed out')) })
+      req.on('connect', (response, socket) => {
+        const status = response.statusCode ?? 0
+        if (status >= 200 && status < 300) resolve(socket)
+        else {
+          socket.destroy()
+          reject(new Error(`upstream answered ${String(status)}`))
+        }
+      })
+      // A non-2xx CONNECT answer arrives as a plain response, not as 'connect'.
+      req.on('response', response => {
+        response.resume()
+        reject(new Error(`upstream answered ${String(response.statusCode ?? 0)}`))
+      })
+      req.on('error', reject)
+      req.end()
+    })
+  }
+
   /** Plain-HTTP proxying: absolute-form requests are adjudicated and forwarded (or blocked with a structured 403). */
   private async handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
     const target = parseUrlTarget(req.url ?? '')
@@ -172,20 +332,40 @@ export class NetworkProxy {
       return
     }
     const upstream = new URL(req.url as string)
-    const send = upstream.protocol === 'https:' ? httpsRequest : httpRequest
-    // The forwarded connection is pinned to the addresses the decision was made
-    // on, so a hostname that re-resolves between adjudication and connect
-    // (DNS rebinding) cannot reach an address the rules never approved.
-    const pinned = pinnedAddresses(adjudicated)
-    const options: RequestOptions = {
-      method: req.method,
-      headers: req.headers,
-      ...(pinned.length === 0 ? {} : { lookup: pinnedLookup(pinned) }),
-    }
-    const proxyReq = send(upstream, options, proxyRes => {
+    const onResponse = (proxyRes: IncomingMessage): void => {
       res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers)
       proxyRes.pipe(res)
-    })
+    }
+    const chained = this.upstreamRouteFor(adjudicated, decision)
+    let proxyReq: ReturnType<typeof httpRequest>
+    if (chained === undefined) {
+      // The forwarded connection is pinned to the addresses the decision was
+      // made on, so a hostname that re-resolves between adjudication and
+      // connect (DNS rebinding) cannot reach an address the rules never
+      // approved.
+      const pinned = pinnedAddresses(adjudicated)
+      const options: RequestOptions = {
+        method: req.method,
+        headers: req.headers,
+        ...(pinned.length === 0 ? {} : { lookup: pinnedLookup(pinned) }),
+      }
+      proxyReq = (upstream.protocol === 'https:' ? httpsRequest : httpRequest)(upstream, options, onResponse)
+    } else {
+      // Chained: the upstream does the resolving, which is exactly why an
+      // `ips`-scoped decision never takes this branch (see upstreamRouteFor).
+      const via = new URL(chained)
+      const headers: Record<string, string | string[] | undefined> = { ...req.headers }
+      const auth = proxyAuthorization(via)
+      if (auth !== undefined) headers['proxy-authorization'] = auth
+      proxyReq = (via.protocol === 'https:' ? httpsRequest : httpRequest)({
+        host: via.hostname,
+        port: via.port === '' ? (via.protocol === 'https:' ? 443 : 80) : Number(via.port),
+        method: req.method,
+        path: req.url, // absolute form, which is what a proxy expects
+        headers,
+      }, onResponse)
+      this.chained += 1
+    }
     proxyReq.on('error', (error: unknown) => {
       if (!res.headersSent) {
         res.writeHead(502, { 'content-type': 'text/plain' })
@@ -260,10 +440,14 @@ export class NetworkProxy {
       return
     }
     let tunnel: Duplex
+    const chained = this.upstreamRouteFor(adjudicated, decision)
     try {
-      tunnel = await this.connectUpstream(adjudicated, target.port ?? 443)
+      tunnel = chained === undefined
+        ? await this.connectUpstream(adjudicated, target.port ?? 443)
+        : await this.connectViaUpstream(chained, target.host.includes(':') ? `[${target.host}]:${String(target.port ?? 443)}` : `${target.host}:${String(target.port ?? 443)}`)
+      if (chained !== undefined) this.chained += 1
     } catch (error) {
-      this.options.logger.warn(`permission-rules: upstream connect failed for ${target.host}: ${String(error)}`)
+      this.options.logger.warn(`permission-rules: upstream connect failed for ${target.host}: ${String(error)}${chained === undefined ? '' : ` (via ${redactProxyUrl(chained)})`}`)
       socket.end('HTTP/1.1 502 Bad Gateway\r\n\r\n')
       return
     }
@@ -303,6 +487,7 @@ export class NetworkProxy {
   /** Record a block: counters, recent ring, and the runtime hook (logger + session audit). */
   private recordBlock(decision: NetworkDecision, target: NetworkTarget): void {
     const attribution = this.options.attribution?.()
+    const cwd = attribution?.agent?.session.header.cwd
     const record: NetworkBlockRecord = {
       time: Date.now(),
       tool: attribution?.tool ?? 'subprocess',
@@ -317,6 +502,7 @@ export class NetworkProxy {
       source: decision.source ?? '',
       ...(decision.ruleIndex !== undefined ? { ruleIndex: decision.ruleIndex } : {}),
       ...(decision.rule !== undefined ? { reason: decision.rule.reason } : {}),
+      ...(cwd !== undefined ? { cwd } : {}),
     }
     if (record.action === 'deny') this.stats.denied += 1
     else this.stats.askBlocked += 1

package/src/remote-service.ts

@@ -12,7 +12,7 @@ import { existsSync } from 'node:fs'
 import type { Context } from '@deepseek-ai/cordis'
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
 import type { PermissionRulesRuntime } from './runtime.ts'
-import type { PermissionRulesSnapshot, RulesReadResult, RulesReloadResult, RulesSaveResult } from './wire.ts'
+import type { AllowHostRequest, AllowHostResult, PermissionRulesSnapshot, RulesReadResult, RulesReloadResult, RulesSaveResult } from './wire.ts'
 
 declare module '@deepseek-ai/cordis' {
   interface Context {
@@ -69,8 +69,17 @@ export class PermissionRulesRemoteService extends TypertRemoteService {
         source: block.source,
         ruleIndex: block.ruleIndex ?? null,
         reason: block.reason ?? null,
+        cwd: block.cwd ?? null,
       })),
       sources,
+      allowHostAction: snapshot.allowHostAction,
+      upstream: {
+        mode: snapshot.upstream.mode,
+        http: snapshot.upstream.http,
+        https: snapshot.upstream.https,
+        active: snapshot.upstream.active,
+        chained: snapshot.upstream.chained,
+      },
     }
   }
 
@@ -104,6 +113,29 @@ export class PermissionRulesRemoteService extends TypertRemoteService {
       return { ok: false, error: error instanceof Error ? error.message : String(error) }
     }
   }
+
+  /**
+   * Write one minimal allow rule for a blocked host into the nearest
+   * effective rule file (the settings page's per-block action). The runtime
+   * owns the whole decision — which file, index 0, the validation gate, the
+   * reload — and never throws; the try/catch is the same containment
+   * `reload()` uses so the page always receives a well-formed result.
+   */
+  allowHost(request: AllowHostRequest): AllowHostResult {
+    try {
+      return this.config.runtime.allowHost(request)
+    } catch (error: unknown) {
+      return {
+        ok: false,
+        path: null,
+        created: false,
+        reloaded: 0,
+        outcome: null,
+        alreadyAllowed: false,
+        error: error instanceof Error ? error.message : String(error),
+      }
+    }
+  }
 }
 
 export default PermissionRulesRemoteService

package/src/rules.ts

@@ -1100,8 +1100,17 @@ function tryParseHttpUrl(text: string): NetworkTarget | undefined {
   return { scheme: url.protocol === 'https:' ? 'https' : 'http', host, port, ips: literalIpOf(host) }
 }
 
-/** Lowercase, strip IPv6 brackets, strip one trailing dot. */
-function normalizeHost(host: string): string {
+/**
+ * Lowercase, strip IPv6 brackets, strip one trailing dot.
+ *
+ * Exported because the settings-page allow action must normalize a blocked
+ * host EXACTLY the way target parsing does, or a rule generated from a block
+ * record could name a different host than the connection that was blocked
+ * (`Example.COM.` and `example.com` are the same target).
+ * @param host - a host name or IP literal as it arrived on the wire.
+ * @returns the canonical spelling.
+ */
+export function normalizeHost(host: string): string {
   let out = host.toLowerCase().replace(/^\[|\]$/g, '')
   while (out.endsWith('.')) out = out.slice(0, -1)
   return out