dsh-permission-rules 0.4.2 → 0.5.2

package/src/prose.ts

@@ -58,6 +58,16 @@ export interface UiProse {
   unreachableWarning: (numbers: readonly number[]) => string
   /** Empty-source placeholder in the rules header. */
   emptySource: string
+  /** Line shown when the network policy is disabled (`network.enabled: false`). */
+  networkDisabled: string
+  /** Header naming the network mode, its sandbox preset, and proxy liveness. */
+  networkHeader: (mode: string, sandboxMode: string | undefined, configuredMode: string, proxyActive: boolean, proxyPort: number) => string
+  /** Cumulative block counters line. */
+  networkCounters: (denied: number, askBlocked: number) => string
+  /** Line shown when no proxy blocks were recorded yet. */
+  noNetworkBlocks: string
+  /** One recent proxy-block row. */
+  networkBlockLine: (time: number, tool: string, attributed: boolean, domain: string, scheme: string | undefined, port: number | undefined, action: string, matched: boolean, ruleIndex: number | undefined, reason: string | undefined) => string
 }
 
 /** Tokens `describeRule` uses for its match-dimension prefixes. */
@@ -70,6 +80,11 @@ export interface DescribeTokens {
   absent: string
   when: string
   platform: string
+  network: string
+  domains: string
+  ips: string
+  ports: string
+  schemes: string
   disabled: string
   tags: string
   /** Prefix of the per-rule source-file attribution. */
@@ -90,7 +105,7 @@ const EN: UiProse = {
   lastReloadWarning: error => `Warning: the last reload failed (${error}); the rules listed above are the previous ones.`,
   dryRunNotice: 'Dry-run mode (enforce: false): deny/ask hits are audit-logged only — every call is passed through.',
   unknownArg: arg => `Unknown /rules argument "${arg}". ${EN.usage}`,
-  usage: 'Usage: /rules [list | reload | decisions [n] | test <tool> <json-args>]',
+  usage: 'Usage: /rules [list | reload | network | decisions [n] | test <tool> <json-args>]',
   decisionsHeader: (shown, total) => `Last ${shown} of ${total} permission decision(s) for this session:`,
   noDecisions: 'No permission decisions recorded in this session yet.',
   auditDisabledNotice: 'Session-log audit is disabled on this host: its Session.append predates the ignorable marker and would make sessions unresumable elsewhere (set allowUnmarkedAudit: true to opt back in).',
@@ -110,6 +125,18 @@ const EN: UiProse = {
   testUsage: 'Usage: /rules test [--cwd <dir>] [--env KEY=VALUE]... [--agent <selector>]... [--platform <name>] <tool> <json-args>, e.g. /rules test bash {"command":"git push origin main"}',
   unreachableWarning: numbers => `Warning: rule${numbers.length > 1 ? 's' : ''} ${numbers.join(', ')} ${numbers.length > 1 ? 'are' : 'is'} unreachable (shadowed by an earlier catch-all rule).`,
   emptySource: '(no rule file — empty rule set)',
+  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.`,
+  noNetworkBlocks: 'No network blocks recorded yet.',
+  networkBlockLine: (time, tool, attributed, domain, scheme, port, action, matched, ruleIndex, reason) => {
+    const when = new Date(time).toISOString()
+    const who = `${tool}${attributed ? '' : ' (unattributed)'}`
+    const target = `${scheme ?? '?'}://${domain}${port === undefined ? '' : `:${port}`}`
+    const by = matched ? (ruleIndex === undefined ? '' : ` (rule ${ruleIndex + 1})`) : ' (mode default)'
+    const why = reason === undefined ? '' : `: ${short(reason)}`
+    return `- ${when} ${action} ${who} → ${target}${by}${why}`
+  },
 }
 
 const ZH: UiProse = {
@@ -121,7 +148,7 @@ const ZH: UiProse = {
   lastReloadWarning: error => `警告：上次重载失败（${error}）；以上列出的是之前的规则。`,
   dryRunNotice: '干跑模式（enforce: false）：deny/ask 命中仅写入审计日志——所有调用照常透传。',
   unknownArg: arg => `未知的 /rules 参数 "${arg}"。${ZH.usage}`,
-  usage: '用法：/rules [list | reload | decisions [n] | test <工具名> <json-参数>]',
+  usage: '用法：/rules [list | reload | network | decisions [n] | test <工具名> <json-参数>]',
   decisionsHeader: (shown, total) => `本会话最近 ${shown}/${total} 条权限裁决：`,
   noDecisions: '本会话还没有记录任何权限裁决。',
   auditDisabledNotice: '本宿主上会话日志审计已停用：其 Session.append 早于 ignorable 标记支持，会令会话在其他宿主上无法恢复（设 allowUnmarkedAudit: true 可重新开启）。',
@@ -141,6 +168,18 @@ const ZH: UiProse = {
   testUsage: '用法：/rules test [--cwd <目录>] [--env 键=值]... [--agent <选择器>]... [--platform <平台名>] <工具名> <json-参数>，例如 /rules test bash {"command":"git push origin main"}',
   unreachableWarning: numbers => `警告：规则 ${numbers.join('、')} 不可达（被前面的通配规则遮蔽）。`,
   emptySource: '（无规则文件——空规则集）',
+  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} 次。`,
+  noNetworkBlocks: '尚未记录任何网络拦截。',
+  networkBlockLine: (time, tool, attributed, domain, scheme, port, action, matched, ruleIndex, reason) => {
+    const when = new Date(time).toISOString()
+    const who = `${tool}${attributed ? '' : '（未归属）'}`
+    const target = `${scheme ?? '?'}://${domain}${port === undefined ? '' : `:${port}`}`
+    const by = matched ? (ruleIndex === undefined ? '' : `（规则 ${ruleIndex + 1}）`) : '（模式默认）'
+    const why = reason === undefined ? '' : `：${short(reason)}`
+    return `- ${when} ${action} ${who} → ${target}${by}${why}`
+  },
 }
 
 const ES: UiProse = {
@@ -152,7 +191,7 @@ const ES: UiProse = {
   lastReloadWarning: error => `Aviso: la última recarga falló (${error}); las reglas mostradas son las anteriores.`,
   dryRunNotice: 'Modo simulación (enforce: false): los aciertos deny/ask solo se registran en auditoría — todas las llamadas pasan.',
   unknownArg: arg => `Argumento de /rules desconocido "${arg}". ${ES.usage}`,
-  usage: 'Uso: /rules [list | reload | decisions [n] | test <herramienta> <json-args>]',
+  usage: 'Uso: /rules [list | reload | network | decisions [n] | test <herramienta> <json-args>]',
   decisionsHeader: (shown, total) => `Últimas ${shown} de ${total} decisión(es) de permiso de esta sesión:`,
   noDecisions: 'Esta sesión aún no registra decisiones de permiso.',
   auditDisabledNotice: 'La auditoría del registro de sesión está desactivada en este host: su Session.append es anterior al marcador ignorable y haría las sesiones irrecuperables en otros hosts (establece allowUnmarkedAudit: true para reactivarla).',
@@ -172,6 +211,18 @@ const ES: UiProse = {
   testUsage: 'Uso: /rules test [--cwd <dir>] [--env CLAVE=VALOR]... [--agent <selector>]... [--platform <nombre>] <herramienta> <json-args>, p. ej. /rules test bash {"command":"git push origin main"}',
   unreachableWarning: numbers => `Aviso: ${numbers.length > 1 ? 'las reglas' : 'la regla'} ${numbers.join(', ')} ${numbers.length > 1 ? 'son inalcanzables' : 'es inalcanzable'} (tapada por una regla general anterior).`,
   emptySource: '(sin archivo de reglas — conjunto vacío)',
+  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.`,
+  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()
+    const who = `${tool}${attributed ? '' : ' (sin atribuir)'}`
+    const target = `${scheme ?? '?'}://${domain}${port === undefined ? '' : `:${port}`}`
+    const by = matched ? (ruleIndex === undefined ? '' : ` (regla ${ruleIndex + 1})`) : ' (modo predeterminado)'
+    const why = reason === undefined ? '' : `: ${short(reason)}`
+    return `- ${when} ${action} ${who} → ${target}${by}${why}`
+  },
 }
 
 const PT: UiProse = {
@@ -183,7 +234,7 @@ const PT: UiProse = {
   lastReloadWarning: error => `Aviso: a última recarga falhou (${error}); as regras listadas são as anteriores.`,
   dryRunNotice: 'Modo simulação (enforce: false): acertos deny/ask são apenas registrados na auditoria — todas as chamadas passam.',
   unknownArg: arg => `Argumento de /rules desconhecido "${arg}". ${PT.usage}`,
-  usage: 'Uso: /rules [list | reload | decisions [n] | test <ferramenta> <json-args>]',
+  usage: 'Uso: /rules [list | reload | network | decisions [n] | test <ferramenta> <json-args>]',
   decisionsHeader: (shown, total) => `Últimas ${shown} de ${total} decisão(ões) de permissão desta sessão:`,
   noDecisions: 'Esta sessão ainda não registrou decisões de permissão.',
   auditDisabledNotice: 'A auditoria do registro da sessão está desativada neste host: seu Session.append é anterior ao marcador ignorable e tornaria as sessões irrecuperáveis em outros hosts (defina allowUnmarkedAudit: true para reativar).',
@@ -203,6 +254,18 @@ const PT: UiProse = {
   testUsage: 'Uso: /rules test [--cwd <dir>] [--env CHAVE=VALOR]... [--agent <seletor>]... [--platform <nome>] <ferramenta> <json-args>, ex.: /rules test bash {"command":"git push origin main"}',
   unreachableWarning: numbers => `Aviso: ${numbers.length > 1 ? 'as regras' : 'a regra'} ${numbers.join(', ')} ${numbers.length > 1 ? 'são inalcançáveis' : 'é inalcançável'} (encoberta por uma regra geral anterior).`,
   emptySource: '(sem arquivo de regras — conjunto vazio)',
+  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.`,
+  noNetworkBlocks: 'Nenhum bloqueio de rede registrado ainda.',
+  networkBlockLine: (time, tool, attributed, domain, scheme, port, action, matched, ruleIndex, reason) => {
+    const when = new Date(time).toISOString()
+    const who = `${tool}${attributed ? '' : ' (não atribuído)'}`
+    const target = `${scheme ?? '?'}://${domain}${port === undefined ? '' : `:${port}`}`
+    const by = matched ? (ruleIndex === undefined ? '' : ` (regra ${ruleIndex + 1})`) : ' (modo padrão)'
+    const why = reason === undefined ? '' : `: ${short(reason)}`
+    return `- ${when} ${action} ${who} → ${target}${by}${why}`
+  },
 }
 
 const HI: UiProse = {
@@ -214,7 +277,7 @@ const HI: UiProse = {
   lastReloadWarning: error => `चेतावनी: अंतिम पुनः लोड विफल रहा (${error}); ऊपर सूचीबद्ध नियम पिछले वाले हैं।`,
   dryRunNotice: 'ड्राई-रन मोड (enforce: false): deny/ask हिट केवल ऑडिट में दर्ज होते हैं — हर कॉल पास हो जाती है।',
   unknownArg: arg => `अज्ञात /rules तर्क "${arg}"। ${HI.usage}`,
-  usage: 'उपयोग: /rules [list | reload | decisions [n] | test <टूल> <json-args>]',
+  usage: 'उपयोग: /rules [list | reload | network | decisions [n] | test <टूल> <json-args>]',
   decisionsHeader: (shown, total) => `इस सत्र के अंतिम ${shown}/${total} अनुमति निर्णय:`,
   noDecisions: 'इस सत्र में अभी कोई अनुमति निर्णय दर्ज नहीं है।',
   auditDisabledNotice: 'इस होस्ट पर सत्र-लॉग ऑडिट अक्षम है: इसका Session.append ignorable मार्कर से पुराना है और सत्र अन्य होस्ट पर अप्राप्य बन जाते (पुनः चालू करने के लिए allowUnmarkedAudit: true सेट करें)।',
@@ -234,6 +297,18 @@ const HI: UiProse = {
   testUsage: 'उपयोग: /rules test [--cwd <dir>] [--env KEY=मान]... [--agent <चयनकर्ता>]... [--platform <नाम>] <टूल> <json-args>, जैसे /rules test bash {"command":"git push origin main"}',
   unreachableWarning: numbers => `चेतावनी: नियम ${numbers.join(', ')} अप्राप्य हैं (पहले वाले सर्व-मिलान नियम से ढके हुए)।`,
   emptySource: '(कोई नियम फ़ाइल नहीं — खाली नियम-समूह)',
+  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} अनुमोदन-ब्लॉक।`,
+  noNetworkBlocks: 'अभी तक कोई नेटवर्क ब्लॉक दर्ज नहीं हुआ।',
+  networkBlockLine: (time, tool, attributed, domain, scheme, port, action, matched, ruleIndex, reason) => {
+    const when = new Date(time).toISOString()
+    const who = `${tool}${attributed ? '' : ' (असाइन नहीं)'}`
+    const target = `${scheme ?? '?'}://${domain}${port === undefined ? '' : `:${port}`}`
+    const by = matched ? (ruleIndex === undefined ? '' : ` (नियम ${ruleIndex + 1})`) : ' (मोड डिफ़ॉल्ट)'
+    const why = reason === undefined ? '' : `: ${short(reason)}`
+    return `- ${when} ${action} ${who} → ${target}${by}${why}`
+  },
 }
 
 /** The localized prose tables by language. */
@@ -241,9 +316,9 @@ export const UI_PROSE: Readonly<Record<UiLanguage, UiProse>> = { en: EN, zh: ZH,
 
 /** `describeRule` match-dimension tokens by language. */
 export const DESCRIBE_TOKENS: Readonly<Record<UiLanguage, DescribeTokens>> = {
-  en: { allTools: 'all tools', tools: 'tools', agents: 'agents', params: 'params', paths: 'paths', absent: 'absent', when: 'when', platform: 'platform', disabled: 'disabled', tags: 'tags', src: 'src' },
-  zh: { allTools: '全部工具', tools: '工具', agents: '代理', params: '参数', paths: '路径', absent: '缺省键', when: '条件', platform: '平台', disabled: '已禁用', tags: '标签', src: '来源' },
-  es: { allTools: 'todas las herramientas', tools: 'herramientas', agents: 'agentes', params: 'parámetros', paths: 'rutas', absent: 'ausentes', when: 'cuándo', platform: 'plataforma', disabled: 'deshabilitada', tags: 'etiquetas', src: 'origen' },
-  pt: { allTools: 'todas as ferramentas', tools: 'ferramentas', agents: 'agentes', params: 'parâmetros', paths: 'caminhos', absent: 'ausentes', when: 'quando', platform: 'plataforma', disabled: 'desativada', tags: 'etiquetas', src: 'origem' },
-  hi: { allTools: 'सभी टूल', tools: 'टूल', agents: 'एजेंट', params: 'पैरामीटर', paths: 'पथ', absent: 'अनुपस्थित', when: 'शर्त', platform: 'प्लेटफ़ॉर्म', disabled: 'अक्षम', tags: 'टैग', src: 'स्रोत' },
+  en: { allTools: 'all tools', tools: 'tools', agents: 'agents', params: 'params', paths: 'paths', absent: 'absent', when: 'when', platform: 'platform', network: 'network', domains: 'domains', ips: 'ips', ports: 'ports', schemes: 'schemes', disabled: 'disabled', tags: 'tags', src: 'src' },
+  zh: { allTools: '全部工具', tools: '工具', agents: '代理', params: '参数', paths: '路径', absent: '缺省键', when: '条件', platform: '平台', network: '网络', domains: '域名', ips: 'IP', ports: '端口', schemes: '协议', disabled: '已禁用', tags: '标签', src: '来源' },
+  es: { allTools: 'todas las herramientas', tools: 'herramientas', agents: 'agentes', params: 'parámetros', paths: 'rutas', absent: 'ausentes', when: 'cuándo', platform: 'plataforma', network: 'red', domains: 'dominios', ips: 'IP', ports: 'puertos', schemes: 'esquemas', disabled: 'deshabilitada', tags: 'etiquetas', src: 'origen' },
+  pt: { allTools: 'todas as ferramentas', tools: 'ferramentas', agents: 'agentes', params: 'parâmetros', paths: 'caminhos', absent: 'ausentes', when: 'quando', platform: 'plataforma', network: 'rede', domains: 'domínios', ips: 'IP', ports: 'portas', schemes: 'esquemas', disabled: 'desativada', tags: 'etiquetas', src: 'origem' },
+  hi: { allTools: 'सभी टूल', tools: 'टूल', agents: 'एजेंट', params: 'पैरामीटर', paths: 'पथ', absent: 'अनुपस्थित', when: 'शर्त', platform: 'प्लेटफ़ॉर्म', network: 'नेटवर्क', domains: 'डोमेन', ips: 'IP', ports: 'पोर्ट', schemes: 'स्कीम', disabled: 'अक्षम', tags: 'टैग', src: 'स्रोत' },
 }

package/src/proxy.ts

@@ -0,0 +1,327 @@
+/**
+ * The plugin's built-in local HTTP/CONNECT proxy: the process-level
+ * network gate for shell subprocess traffic. Bash/pwsh children inherit
+ * `HTTP(S)_PROXY`/`ALL_PROXY` environment variables pointing here, and the
+ * proxy adjudicates EVERY connection target against the loaded network
+ * rules and the active policy mode — the domain decision lives in the
+ * proxy layer, not in per-command wrappers.
+ *
+ * Boundaries (documented in the README): DSH's official `ctx.sandbox`
+ * enforces FILE effects only, so network interception is entirely this
+ * plugin's job; the proxy has no session context, so an `ask` decision at
+ * the proxy layer cannot ride the interactive approval seam — it blocks
+ * the connection with a structured message and is audit-logged instead
+ * (web tools get the real approval seam at `tools/pre-execute`).
+ * @module dsh-permission-rules/proxy
+ */
+
+import { createServer, request as httpRequest } from 'node:http'
+import { request as httpsRequest } from 'node:https'
+import { connect } from 'node:net'
+import { lookup } from 'node:dns/promises'
+import type { AddressInfo } from 'node:net'
+import type { Duplex } from 'node:stream'
+import type { Server, IncomingMessage, ServerResponse } from 'node:http'
+import type { CallId } from '@deepseek-ai/dsh-llm'
+import type { NetworkDecision, NetworkMode } from './network.ts'
+import { blockMessage } from './network.ts'
+import { isIpLiteral, parseUrlTarget } from './rules.ts'
+import type { NetworkTarget, SchemeName } from './rules.ts'
+
+/** Proxy environment variable names the injector sets/restores (uppercase + lowercase for mixed-ecosystem CLIs). */
+export const PROXY_ENV_NAMES: readonly string[] = ['HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'http_proxy', 'https_proxy', 'all_proxy']
+
+/** NO_PROXY names cleared (or preserved) by the injector. */
+export const NO_PROXY_ENV_NAMES: readonly string[] = ['NO_PROXY', 'no_proxy']
+
+/** One recorded proxy-layer block (settings-page list + session audit + logger). */
+export interface NetworkBlockRecord {
+  readonly time: number
+  readonly tool: string
+  readonly attributed: boolean
+  readonly callId?: CallId
+  readonly domain: string
+  readonly scheme?: SchemeName
+  readonly port?: number
+  readonly action: 'deny' | 'ask'
+  readonly mode: NetworkMode
+  readonly matched: boolean
+  readonly source: string
+  readonly ruleIndex?: number
+  readonly reason?: string
+}
+
+/** Cumulative proxy-layer block counters. */
+export interface NetworkStats {
+  denied: number
+  askBlocked: number
+}
+
+/** The attribution the runtime supplies for one connection (the newest in-flight shell execution). */
+export interface ProxyAttribution {
+  readonly tool: string
+  readonly callId?: CallId
+  readonly agent?: {
+    readonly session: { append(type: 'permissionRules/network', data: unknown, options?: { ignorable?: true }): unknown }
+  }
+}
+
+/** Construction options for {@link NetworkProxy}. */
+export interface NetworkProxyOptions {
+  /** Bind address (loopback by config). */
+  readonly bind: string
+  /** Requested port; `0` binds an ephemeral port. */
+  readonly port: number
+  /** Cap on recent-block records kept in memory. */
+  readonly maxRecent: number
+  /** Decision function supplied by the runtime (rules + mode). */
+  readonly decide: (target: NetworkTarget) => NetworkDecision
+  /** Current attribution (newest in-flight shell execution), or undefined. */
+  readonly attribution?: () => ProxyAttribution | undefined
+  /** Called for every blocked connection, after the response is sent. */
+  readonly onBlock?: (record: NetworkBlockRecord, attribution: ProxyAttribution | undefined) => void
+  /** Logger sink (proxy failures must never crash the host). */
+  readonly logger: { warn(message: string): void }
+}
+
+/**
+ * The local HTTP/CONNECT policy proxy. Binds on demand (the plugin calls
+ * {@link start} inside an effect and {@link close} from its disposer);
+ * every live tunnel socket is tracked and destroyed on close so updates
+ * and uninstalls leave no orphaned connections.
+ */
+export class NetworkProxy {
+  private server: Server | undefined
+  private readonly sockets = new Set<Duplex>()
+  private readonly recent: NetworkBlockRecord[] = []
+  private readonly stats: NetworkStats = { denied: 0, askBlocked: 0 }
+  private actualPort = 0
+
+  constructor(private readonly options: NetworkProxyOptions) {}
+
+  /** The bound port (valid after {@link start} resolves). */
+  get port(): number {
+    return this.actualPort
+  }
+
+  /** Deny/ask blocks recorded since mount, newest first (settings-page list). */
+  recentBlocks(): readonly NetworkBlockRecord[] {
+    return this.recent
+  }
+
+  /** Cumulative block counters. */
+  blockStats(): NetworkStats {
+    return { ...this.stats }
+  }
+
+  /** Bind the server and return the actual port. */
+  start(): Promise<number> {
+    const server = createServer((req, res) => {
+      void this.handleRequest(req, res)
+    })
+    server.on('connect', (req, socket, head) => {
+      void this.handleConnect(req, socket, head)
+    })
+    server.on('error', (error: unknown) => {
+      this.options.logger.warn(`permission-rules: proxy server error: ${String(error)}`)
+    })
+    this.server = server
+    return new Promise((resolve, reject) => {
+      const onError = (error: Error): void => {
+        server.off('listening', onListening)
+        reject(error)
+      }
+      const onListening = (): void => {
+        server.off('error', onError)
+        const address = server.address() as AddressInfo
+        this.actualPort = address.port
+        resolve(address.port)
+      }
+      server.once('error', onError)
+      server.once('listening', onListening)
+      server.listen(this.options.port, this.options.bind)
+    })
+  }
+
+  /** Stop the server and destroy every tunnel; resolves when sockets are closed. */
+  close(): Promise<void> {
+    const server = this.server
+    this.server = undefined
+    for (const socket of this.sockets) socket.destroy()
+    this.sockets.clear()
+    if (server === undefined) return Promise.resolve()
+    return new Promise(resolve => {
+      server.close(() => resolve())
+    })
+  }
+
+  /** 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 ?? '')
+    if (target === undefined || target.scheme === undefined) {
+      res.writeHead(404, { 'content-type': 'text/plain' })
+      res.end('permission-rules proxy: only absolute-form proxy requests are served here\n')
+      return
+    }
+    await this.forwardOrBlock(res, target, () => {
+      const upstream = new URL(req.url as string)
+      const send = upstream.protocol === 'https:' ? httpsRequest : httpRequest
+      const proxyReq = send(upstream, { method: req.method, headers: req.headers }, proxyRes => {
+        res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers)
+        proxyRes.pipe(res)
+      })
+      proxyReq.on('error', (error: unknown) => {
+        if (!res.headersSent) {
+          res.writeHead(502, { 'content-type': 'text/plain' })
+          res.end(`[network: upstream error] ${String(error)}\n`)
+        } else {
+          res.destroy()
+        }
+      })
+      req.pipe(proxyReq)
+    })
+  }
+
+  /** CONNECT tunneling (HTTPS and friends): adjudicate, then either 403 or an established TCP tunnel. */
+  private async handleConnect(req: IncomingMessage, socket: Duplex, head: Buffer): Promise<void> {
+    const target = connectTarget(req.url ?? '')
+    if (target === undefined) {
+      socket.end('HTTP/1.1 400 Bad Request\r\n\r\n')
+      return
+    }
+    const decision = await this.decideWithResolution(target)
+    if (decision.action !== 'allow') {
+      this.recordBlock(decision, target)
+      const body = blockMessage(decision)
+      socket.end(`HTTP/1.1 403 Forbidden\r\ncontent-type: text/plain\r\ncontent-length: ${Buffer.byteLength(body)}\r\n\r\n${body}`)
+      return
+    }
+    const upstream = connect(target.port ?? 443, target.host)
+    this.sockets.add(socket)
+    this.sockets.add(upstream)
+    const cleanup = (): void => {
+      this.sockets.delete(socket)
+      this.sockets.delete(upstream)
+    }
+    socket.on('close', cleanup)
+    upstream.on('close', cleanup)
+    upstream.on('error', () => socket.destroy())
+    socket.on('error', () => upstream.destroy())
+    upstream.once('connect', () => {
+      socket.write('HTTP/1.1 200 Connection Established\r\n\r\n')
+      if (head.length > 0) upstream.write(head)
+      upstream.pipe(socket)
+      socket.pipe(upstream)
+    })
+  }
+
+  /** Adjudicate one plain-HTTP request; deny/ask blocks with a structured 403 before any forwarding. */
+  private async forwardOrBlock(res: ServerResponse, target: NetworkTarget, forward: () => void): Promise<void> {
+    const decision = await this.decideWithResolution(target)
+    if (decision.action !== 'allow') {
+      this.recordBlock(decision, target)
+      const body = blockMessage(decision)
+      res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8', 'content-length': Buffer.byteLength(body) })
+      res.end(body)
+      return
+    }
+    forward()
+  }
+
+  /** Resolve a hostname once so `ips`-scoped rules see the real addresses, then decide. */
+  private async decideWithResolution(target: NetworkTarget): Promise<NetworkDecision> {
+    if (!isIpLiteral(target.host)) {
+      try {
+        const addresses = await lookup(target.host, { all: true, verbatim: true })
+        const resolved = addresses.map(entry => entry.address)
+        if (resolved.length > 0) return this.options.decide({ ...target, ips: [...target.ips, ...resolved] })
+      } catch {
+        // Unresolvable target: decide on the literal name (ip-scoped rules simply cannot fire).
+      }
+    }
+    return this.options.decide(target)
+  }
+
+  /** 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 record: NetworkBlockRecord = {
+      time: Date.now(),
+      tool: attribution?.tool ?? 'subprocess',
+      attributed: attribution !== undefined,
+      ...(attribution?.callId !== undefined ? { callId: attribution.callId } : {}),
+      domain: target.host,
+      ...(target.scheme !== undefined ? { scheme: target.scheme } : {}),
+      ...(target.port !== undefined ? { port: target.port } : {}),
+      action: decision.action === 'ask' ? 'ask' : 'deny',
+      mode: decision.mode,
+      matched: decision.matched,
+      source: decision.source ?? '',
+      ...(decision.ruleIndex !== undefined ? { ruleIndex: decision.ruleIndex } : {}),
+      ...(decision.rule !== undefined ? { reason: decision.rule.reason } : {}),
+    }
+    if (record.action === 'deny') this.stats.denied += 1
+    else this.stats.askBlocked += 1
+    this.recent.unshift(record)
+    if (this.recent.length > this.options.maxRecent) this.recent.length = this.options.maxRecent
+    this.options.logger.warn(`permission-rules: network ${record.action === 'deny' ? 'denied' : 'ask-blocked'} ${target.scheme ?? '?'}://${target.host}${target.port !== undefined ? `:${target.port}` : ''} (mode ${decision.mode}${decision.matched ? `, rule ${(decision.ruleIndex ?? 0) + 1}` : ', mode default'})`)
+    try {
+      this.options.onBlock?.(record, attribution)
+    } catch (error: unknown) {
+      this.options.logger.warn(`permission-rules: network block hook failed: ${String(error)}`)
+    }
+  }
+}
+
+/** Parse a CONNECT authority (`host:port`) into an https target with an explicit port. */
+function connectTarget(authority: string): NetworkTarget | undefined {
+  const colon = authority.lastIndexOf(':')
+  if (colon <= 0) return undefined
+  const host = authority.slice(0, colon).replace(/^\[|\]$/g, '').toLowerCase().replace(/\.+$/, '')
+  const port = Number(authority.slice(colon + 1))
+  if (host.length === 0 || !Number.isInteger(port) || port < 1 || port > 65535) return undefined
+  return { scheme: 'https', host, port, ips: isIpLiteral(host) ? [host] : [] }
+}
+
+/**
+ * Inject the proxy environment variables for subprocesses and return a
+ * disposer restoring every previous value exactly (so updates and
+ * uninstalls leave the host environment untouched). `noProxy: 'clear'`
+ * empties NO_PROXY so the policy cannot be bypassed through ambient
+ * exclusions; `preserve` keeps ambient values.
+ *
+ * The snapshot pass covers EVERY name BEFORE any write: on Windows
+ * `process.env` is case-insensitive, so the uppercase/lowercase spellings
+ * share one variable — writing `HTTP_PROXY` mid-loop would otherwise
+ * poison the later snapshot of `http_proxy` and make the restore write
+ * the proxy address back over the original.
+ * @param port - the bound proxy port.
+ * @param noProxy - the configured NO_PROXY handling.
+ * @returns the restore disposer.
+ */
+export function injectProxyEnv(port: number, noProxy: 'clear' | 'preserve'): () => void {
+  const previous = new Map<string, string | undefined>()
+  const value = `http://127.0.0.1:${port}`
+  for (const name of PROXY_ENV_NAMES) previous.set(name, process.env[name])
+  if (noProxy === 'clear') {
+    for (const name of NO_PROXY_ENV_NAMES) previous.set(name, process.env[name])
+  }
+  for (const name of PROXY_ENV_NAMES) process.env[name] = value
+  if (noProxy === 'clear') {
+    for (const name of NO_PROXY_ENV_NAMES) process.env[name] = ''
+  }
+  return () => {
+    for (const name of PROXY_ENV_NAMES) {
+      const old = previous.get(name)
+      if (old === undefined) delete process.env[name]
+      else process.env[name] = old
+    }
+    if (noProxy === 'clear') {
+      for (const name of NO_PROXY_ENV_NAMES) {
+        const old = previous.get(name)
+        if (old === undefined) delete process.env[name]
+        else process.env[name] = old
+      }
+    }
+  }
+}

package/src/remote-service.ts

@@ -0,0 +1,109 @@
+/**
+ * The settings-page Remote service: exposes the `permissionRules` Typert
+ * namespace (network snapshot + rule-file read/save/reload) to the
+ * browser half. All state lives in the {@link PermissionRulesRuntime}
+ * this service delegates to; the service itself only bridges the wire
+ * vocabulary. The rule editor only ever touches KNOWN rule sources —
+ * arbitrary paths are refused by the runtime.
+ * @module dsh-permission-rules/remote-service
+ */
+
+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'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** Settings-page snapshot + rule-editor bridge (this package). */
+    permissionRules: PermissionRulesRemoteService
+  }
+}
+
+/** Service config: the runtime instance whose state the wire exposes. */
+export interface PermissionRulesRemoteServiceConfig {
+  /** The runtime holding the loaded rules, proxy state, and block records. */
+  runtime: PermissionRulesRuntime
+}
+
+/**
+ * The Typert Remote service behind the settings page. Registered through
+ * `ctx.plugin(PermissionRulesRemoteService, { runtime })` in
+ * {@link apply}; the typert gateway binds its public methods to the
+ * invocation descriptors in `./wire.ts`.
+ */
+export class PermissionRulesRemoteService extends TypertRemoteService {
+  static inject = [] as string[]
+
+  constructor(ctx: Context, private readonly config: PermissionRulesRemoteServiceConfig) {
+    super(ctx, 'permissionRules')
+  }
+
+  /** The settings-page snapshot: mode mapping, proxy liveness, counters, recent blocks, editable rule sources. */
+  networkStatus(): PermissionRulesSnapshot {
+    const snapshot = this.config.runtime.networkSnapshot()
+    const sources = this.config.runtime.knownRuleSources().map(path => {
+      const owner = this.config.runtime.sourceOwner(path)
+      return { path, exists: existsSync(path), cwd: owner ?? null }
+    })
+    return {
+      enabled: snapshot.enabled,
+      mode: snapshot.mode,
+      configuredMode: snapshot.configuredMode,
+      sandboxMode: snapshot.sandboxMode ?? null,
+      proxyPort: snapshot.proxyPort,
+      proxyActive: snapshot.proxyActive,
+      denied: snapshot.denied,
+      askBlocked: snapshot.askBlocked,
+      recent: snapshot.recent.map(block => ({
+        time: block.time,
+        tool: block.tool,
+        attributed: block.attributed,
+        domain: block.domain,
+        scheme: block.scheme ?? null,
+        port: block.port ?? null,
+        action: block.action,
+        mode: block.mode,
+        matched: block.matched,
+        source: block.source,
+        ruleIndex: block.ruleIndex ?? null,
+        reason: block.reason ?? null,
+      })),
+      sources,
+    }
+  }
+
+  /** Read one known rule file for the editor. */
+  rulesRead(path: string): RulesReadResult {
+    const result = this.config.runtime.readRuleFile(path)
+    return {
+      path: result.path,
+      exists: result.exists,
+      text: result.text,
+      error: result.error ?? null,
+    }
+  }
+
+  /** Validate and write one known rule file; invalid edits are rejected before anything touches disk. */
+  rulesSave(path: string, text: string): RulesSaveResult {
+    const result = this.config.runtime.saveRuleFile(path, text)
+    return {
+      ok: result.ok,
+      error: result.error ?? null,
+      reloaded: result.reloaded ?? null,
+    }
+  }
+
+  /** Re-read every cached workspace chain (after an external edit). */
+  reload(): RulesReloadResult {
+    try {
+      this.config.runtime.reloadAll()
+      return { ok: true, error: null }
+    } catch (error: unknown) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) }
+    }
+  }
+}
+
+export default PermissionRulesRemoteService