dsh-permission-rules 0.6.21 → 0.7.1

package/src/runtime.ts

@@ -23,6 +23,9 @@ import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import { resolveConfig } from './config.ts'
 import type { Config, ResolvedConfig } from './config.ts'
 import type { CallId } from './call-id.ts'
+import { insertAllowRule, isWritableHost, normalizeAllowHost, resolveAllowHostTarget } from './allow-host.ts'
+import type { AllowHostInsertion } from './allow-host.ts'
+import type { AllowHostRequest, AllowHostResult } from './wire.ts'
 import { compileRules, compileSourceRules, describeRule, findUnreachableRules, isShellTool, matchRules, mergeCompiledRules, normalizeWorkspacePath, parseRulesDocument, PLATFORMS, RuleError } from './rules.ts'
 import type { CompileOptions, CompiledRule, CompiledRuleset, MatchContext, NetworkTarget, RuleHit } from './rules.ts'
 import { DESCRIBE_TOKENS, UI_PROSE } from './prose.ts'
@@ -35,8 +38,8 @@ function readSessionEvents(session: { snapshotEvents?: () => readonly SessionEve
   if (typeof session.snapshotEvents === 'function') return session.snapshotEvents()
   return session.events ?? []
 }
-import { injectProxyEnv, NetworkProxy } from './proxy.ts'
-import type { NetworkBlockRecord, ProxyAttribution } from './proxy.ts'
+import { injectProxyEnv, NetworkProxy, readAmbientProxy, redactProxyUrl } from './proxy.ts'
+import type { AmbientUpstream, NetworkBlockRecord, ProxyAttribution } from './proxy.ts'
 import { PermissionRulesRemoteService } from './remote-service.ts'
 import { attachSettingsSection } from './settings.ts'
 import { isMarkedAuditEvent } from './events.ts'
@@ -137,6 +140,23 @@ const POLLING_WATCH_OPTIONS = { usePolling: true, interval: POLLING_WATCH_INTERV
  * State and behavior. One instance per plugin mount; disposals are owned by
  * the watcher/timer/proxy effects registered in {@link apply}.
  */
+/**
+ * Whether a configured upstream addresses this proxy's own bind address and
+ * port, which would make every chained connection recurse into this proxy.
+ */
+function isSelfUpstream(value: string, bind: string, port: number): boolean {
+  try {
+    const parsed = new URL(value)
+    const bindIsLocal = bind === '127.0.0.1' || bind === 'localhost' || bind === '::1' || bind === '0.0.0.0'
+    const host = parsed.hostname
+    const valueIsLocal = host === '127.0.0.1' || host === 'localhost' || host === '::1' || host === '[::1]'
+    const valuePort = parsed.port === '' ? (parsed.protocol === 'https:' ? 443 : 80) : Number(parsed.port)
+    return bindIsLocal && valueIsLocal && valuePort === port
+  } catch {
+    return false
+  }
+}
+
 export class PermissionRulesRuntime {
   /** Loaded (or failed) rules per workspace cwd, least-recently-used first for eviction. */
   private readonly byCwd = new Map<string, LoadedRules>()
@@ -164,6 +184,11 @@ export class PermissionRulesRuntime {
 
   /** The network proxy, when the policy is enabled and mounted. */
   private networkProxy: NetworkProxy | undefined
+  /** Ambient upstream candidates, captured ONCE before this plugin injects its own (see {@link captureAmbientUpstream}). */
+  private ambientUpstream: AmbientUpstream | undefined
+  private ambientCaptured = false
+  private upstreamWarned = false
+  private selfLoopWarned = false
 
   /** Restores the injected proxy environment (set after a successful bind). */
   private envRestore: (() => void) | undefined
@@ -721,6 +746,9 @@ export class PermissionRulesRuntime {
    */
   async attachNetworkProxy(): Promise<void> {
     const cfg = this.config.network
+    // Capture the ambient proxy BEFORE injectProxyEnv() rewrites the
+    // environment: afterwards the only proxy this process can still see is ours.
+    this.captureAmbientUpstream()
     const proxy = new NetworkProxy({
       bind: cfg.proxyBind,
       port: cfg.proxyPort,
@@ -729,6 +757,7 @@ export class PermissionRulesRuntime {
       attribution: () => this.proxyAttribution(),
       onBlock: (record, attribution) => this.auditNetworkBlock(record, attribution),
       logger: this.ctx.logger,
+      upstream: () => this.upstreamFor(),
     })
     this.networkProxy = proxy
     this.ctx.effect(() => () => {
@@ -769,6 +798,91 @@ export class PermissionRulesRuntime {
     await this.attachNetworkProxy()
   }
 
+  /**
+   * Capture the launch environment's proxy names exactly ONCE, before this
+   * plugin injects its own. `onNetworkConfigChanged()` closes the old proxy and
+   * restores the environment around a rebind, so a second capture could read
+   * this plugin's own address back as if the operator had exported it — hence
+   * the memo. The launch snapshot is immutable and preferred; `process.env` is
+   * the fallback for hosts that expose no snapshot.
+   */
+  private captureAmbientUpstream(): void {
+    if (this.ambientCaptured) return
+    this.ambientCaptured = true
+    const launch = this.ctx.get('launchEnvironment') as { get(name: string): { value: string } | undefined } | undefined
+    const lookup = (name: string): string | undefined => launch?.get(name)?.value ?? process.env[name]
+    this.ambientUpstream = readAmbientProxy(lookup)
+    this.warnAboutUpstream()
+  }
+
+  /** The one-shot upstream diagnostics: a discarded ambient proxy, or an `inherit` with nothing to inherit. */
+  private warnAboutUpstream(): void {
+    if (this.upstreamWarned) return
+    this.upstreamWarned = true
+    const cfg = this.config.network
+    const ambient = this.ambientUpstream
+    const has = ambient !== undefined && (ambient.http !== undefined || ambient.https !== undefined)
+    if (cfg.upstreamProxy === 'off' && cfg.injectEnv && has) {
+      this.ctx.logger.warn(`permission-rules: an ambient proxy (${redactProxyUrl(ambient.https ?? ambient.http ?? '')}) is discarded for traffic through this proxy; set network.upstreamProxy to "inherit" to chain through it, or leave it to subprocesses only`)
+    }
+    if (cfg.upstreamProxy === 'inherit' && !cfg.injectEnv) {
+      this.ctx.logger.warn('permission-rules: network.upstreamProxy is only consulted for connections that reach this proxy; with injectEnv false, subprocess traffic keeps its own route')
+    }
+    if (cfg.upstreamProxy === 'inherit' && !has) {
+      this.ctx.logger.warn('permission-rules: network.upstreamProxy is "inherit" but the launch environment named no usable http(s) proxy (a SOCKS or malformed value is ignored; Node has no SOCKS client)')
+    }
+  }
+
+  /**
+   * The upstream getter the proxy consults per connection. Undefined when the
+   * setting is `off`, when no candidate is usable, or when the candidate points
+   * back into this very proxy — a self-loop would recurse forever, so chaining
+   * is disabled for it and warned about once.
+   */
+  private upstreamFor(): AmbientUpstream | undefined {
+    if (this.config.network.upstreamProxy === 'off') return undefined
+    const ambient = this.ambientUpstream
+    if (ambient === undefined) return undefined
+    const selfPort = this.networkProxy?.port ?? 0
+    const selfHost = this.config.network.proxyBind
+    const usable = (value: string | undefined): string | undefined => {
+      if (value === undefined) return undefined
+      if (selfPort > 0 && isSelfUpstream(value, selfHost, selfPort)) {
+        if (!this.selfLoopWarned) {
+          this.selfLoopWarned = true
+          this.ctx.logger.warn(`permission-rules: network.upstreamProxy points at this proxy itself (${redactProxyUrl(value)}); chaining is disabled for it`)
+        }
+        return undefined
+      }
+      return value
+    }
+    const http = usable(ambient.http)
+    const https = usable(ambient.https)
+    if (http === undefined && https === undefined) return undefined
+    return { ...(http === undefined ? {} : { http }), ...(https === undefined ? {} : { https }) }
+  }
+
+  /** The upstream block of the network snapshot, already redacted. */
+  private upstreamSnapshot(): {
+    readonly mode: 'off' | 'inherit' | 'url'
+    readonly http: string | null
+    readonly https: string | null
+    readonly active: boolean
+    readonly chained: number
+  } {
+    const setting = this.config.network.upstreamProxy
+    const mode: 'off' | 'inherit' | 'url' = setting === 'off' ? 'off' : setting === 'inherit' ? 'inherit' : 'url'
+    const http = mode === 'off' ? undefined : mode === 'url' ? setting : this.ambientUpstream?.http
+    const https = mode === 'off' ? undefined : mode === 'url' ? setting : this.ambientUpstream?.https
+    return {
+      mode,
+      http: http === undefined ? null : redactProxyUrl(http),
+      https: https === undefined ? null : redactProxyUrl(https),
+      active: mode !== 'off' && this.upstreamFor() !== undefined,
+      chained: this.networkProxy?.chainedConnections() ?? 0,
+    }
+  }
+
   /** The network snapshot the settings page and `/rules network` render. */
   networkSnapshot(): {
     readonly enabled: boolean
@@ -780,6 +894,15 @@ export class PermissionRulesRuntime {
     readonly denied: number
     readonly askBlocked: number
     readonly recent: readonly NetworkBlockRecord[]
+    readonly upstream: {
+      readonly mode: 'off' | 'inherit' | 'url'
+      readonly http: string | null
+      readonly https: string | null
+      readonly active: boolean
+      readonly chained: number
+    }
+    /** Whether the settings page may offer the per-block allow action. */
+    readonly allowHostAction: boolean
   } {
     const cfg = this.config.network
     const { mode, sandboxMode } = this.resolveNetworkMode()
@@ -795,16 +918,18 @@ export class PermissionRulesRuntime {
       denied: stats.denied,
       askBlocked: stats.askBlocked,
       recent: proxy?.recentBlocks() ?? [],
+      upstream: this.upstreamSnapshot(),
+      allowHostAction: cfg.allowHostAction,
     }
   }
 
-  /**
-   * The rule-file paths the settings-page editor may read or write: every
-   * currently loaded source plus the per-workspace project files and the
-   * configured fallback (so a not-yet-existing project file can be
-   * created). The editor never touches arbitrary paths — and the built-in
-   * baseline is excluded entirely (it is a shipped, read-only baseline,
-   * shown via `/rules` attribution instead).
+  /** The rule-file paths the settings-page editor may read or write: every
+   * currently loaded source plus the per-workspace project files, the
+   * configured fallback, and the host-level project file the session-less
+   * chain resolves (so a not-yet-existing project file can be created). The
+   * editor never touches arbitrary paths — and the built-in baseline is
+   * excluded entirely (it is a shipped, read-only baseline, shown via
+   * `/rules` attribution instead).
    */
   knownRuleSources(): readonly string[] {
     const cfg = this.config
@@ -819,6 +944,11 @@ export class PermissionRulesRuntime {
     }
     if (cfg.fallbackPath !== undefined) set.add(isAbsolute(cfg.fallbackPath) ? cfg.fallbackPath : resolve(cfg.fallbackPath))
     if (isAbsolute(cfg.rulesFile)) set.add(cfg.rulesFile)
+    // The host-level chain (see hostChain) resolves its project file against
+    // the process cwd; it must be editable and allow-able even while no
+    // workspace chain is loaded, or the settings page could show a block the
+    // operator can see but not act on.
+    else set.add(join(process.cwd(), cfg.rulesFile))
     return [...set]
   }
 
@@ -894,6 +1024,109 @@ export class PermissionRulesRuntime {
     return { ok: true, reloaded }
   }
 
+  /**
+   * The settings-page "allow this host" action (issue #19 item 3): write ONE
+   * minimal `match.network.domains` allow rule for a blocked target into the
+   * nearest effective rule file, at index 0, then report the decision the
+   * runtime makes for that target afterwards.
+   *
+   * Why index 0: rules are first-match-wins, so appending the rule after an
+   * existing `deny` would leave the connection blocked — the rule would be
+   * dead text the operator cannot see the reason for.
+   *
+   * Why `domains` only: that dimension is subdomain-inclusive and
+   * port/scheme-agnostic; narrowing the generated rule to the blocked port
+   * would re-block the same host on its next connection from another port.
+   * The rule can never widen TOOL permissions either — an allow hit on
+   * `tools/pre-execute` is delegated downstream, never claimed.
+   *
+   * Failure modes are fail-closed and leave the disk untouched: the action is
+   * disabled, the host is not a host name/IP literal, the request names an
+   * unknown workspace, the target resolves outside the known rule sources or
+   * onto the built-in baseline, the file cannot be read, the document does
+   * not parse / has no `rules` list, or the written text fails the same
+   * `parseRulesDocument` + `compileRules` gate every hand edit passes.
+   *
+   * The write goes through {@link saveRuleFile}, so the per-workspace chains
+   * AND the session-less host chain are re-read — no restart, no
+   * `/rules reload` — and the returned `outcome` is the REAL decision
+   * recomputed after the write (with the target as given, no DNS: an
+   * `ips`-scoped allow rule cannot be seen here). Cross-process concurrent
+   * writes to one rule file are out of scope: last writer wins.
+   *
+   * @param request - the blocked target plus the workspace it belongs to.
+   * @returns the action result, never a throw.
+   */
+  allowHost(request: AllowHostRequest): AllowHostResult {
+    const fail = (error: string, path: string | null = null): AllowHostResult => ({
+      ok: false,
+      path,
+      created: false,
+      reloaded: 0,
+      outcome: null,
+      alreadyAllowed: false,
+      error,
+    })
+    if (!this.config.network.allowHostAction) {
+      return fail('the allow-host action is disabled by network.allowHostAction')
+    }
+    const host = normalizeAllowHost(request.host)
+    if (!isWritableHost(host)) {
+      return fail(`refusing to allow ${JSON.stringify(request.host)}: not a host name or IP literal`)
+    }
+    const target: NetworkTarget = { scheme: request.scheme ?? undefined, host, port: request.port ?? undefined, ips: [] }
+    if (this.decideProxyTarget(target).action === 'allow') {
+      return { ok: true, path: null, created: false, reloaded: 0, outcome: 'allow', alreadyAllowed: true, error: null }
+    }
+    let path: string
+    try {
+      path = resolveAllowHostTarget({
+        cwd: request.cwd,
+        loadedCwds: [...this.byCwd.values()].map(loaded => loaded.cwd),
+        knownSources: this.knownRuleSources(),
+        rulesFile: this.config.rulesFile,
+        fallbackPath: this.config.fallbackPath,
+        processCwd: process.cwd(),
+        builtinPath: this.builtinSource(),
+        exists: existsSync,
+      })
+    } catch (error: unknown) {
+      return fail(error instanceof Error ? error.message : String(error))
+    }
+    const existed = existsSync(path)
+    let existing = ''
+    if (existed) {
+      try {
+        existing = readFileSync(path, 'utf8')
+      } catch (error: unknown) {
+        return fail(`cannot read ${path}: ${error instanceof Error ? error.message : String(error)}`, path)
+      }
+    }
+    let edit: AllowHostInsertion
+    try {
+      edit = insertAllowRule(existing, host)
+    } catch (error: unknown) {
+      return fail(error instanceof Error ? error.message : String(error), path)
+    }
+    if (!edit.inserted) {
+      // The file already leads with this exact allow rule: first-match
+      // semantics make a second copy a no-op, so the file stays untouched.
+      return { ok: true, path, created: false, reloaded: 0, outcome: this.decideProxyTarget(target).action, alreadyAllowed: true, error: null }
+    }
+    const hadHostChain = this.hostLoaded !== undefined
+    const saved = this.saveRuleFile(path, edit.text)
+    if (!saved.ok) return fail(saved.error ?? `refusing to write ${path}`, path)
+    return {
+      ok: true,
+      path,
+      created: !existed,
+      reloaded: (saved.reloaded ?? 0) + (hadHostChain ? 1 : 0),
+      outcome: this.decideProxyTarget(target).action,
+      alreadyAllowed: false,
+      error: null,
+    }
+  }
+
   /** The installed `@deepseek-ai/dsh-session` version, or `null` when unresolvable (falls back to the append probe). */
   private peerVersion(): string | null {
     try {
@@ -1090,6 +1323,7 @@ export class PermissionRulesRuntime {
     }
     lines.push(prose.networkHeader(snapshot.mode, snapshot.sandboxMode, snapshot.configuredMode, snapshot.proxyActive, snapshot.proxyPort))
     lines.push(prose.networkCounters(snapshot.denied, snapshot.askBlocked))
+    lines.push(prose.networkUpstream(snapshot.upstream.mode, snapshot.upstream.http, snapshot.upstream.https, snapshot.upstream.active, snapshot.upstream.chained))
     if (snapshot.recent.length === 0) {
       lines.push(prose.noNetworkBlocks)
     } else {

package/src/wire.ts

@@ -33,6 +33,12 @@ export interface NetworkBlockView {
   source: string
   ruleIndex: number | null
   reason: string | null
+  /**
+   * The workspace of the agent the block was attributed to, or null when the
+   * connection carried no session attribution (a host-level fetch). The
+   * allow-host action needs it to pick the rule file it writes.
+   */
+  cwd: string | null
 }
 
 /** One rule file the editor may read/write (a known rule source only). */
@@ -56,7 +62,20 @@ export interface PermissionRulesSnapshot {
   denied: number
   askBlocked: number
   recent: readonly NetworkBlockView[]
+  /** Upstream chaining state; any credential in a proxy URL is already masked. */
+  upstream: {
+    mode: 'off' | 'inherit' | 'url'
+    http: string | null
+    https: string | null
+    active: boolean
+    chained: number
+  }
   sources: readonly RuleSourceView[]
+  /**
+   * Whether the settings page may run its per-block "allow this host" action
+   * (`network.allowHostAction`); false hides the button.
+   */
+  allowHostAction: boolean
 }
 
 /** Strict wire schema for {@link PermissionRulesSnapshot}. */
@@ -82,12 +101,21 @@ export const PERMISSION_RULES_SNAPSHOT_SCHEMA = z.object({
     source: z.string(),
     ruleIndex: z.number().int().nullable(),
     reason: z.string().nullable(),
+    cwd: z.string().nullable(),
   })),
   sources: z.array(z.object({
     path: z.string(),
     exists: z.boolean(),
     cwd: z.string().nullable(),
   })),
+  allowHostAction: z.boolean(),
+  upstream: z.object({
+    mode: z.union([z.literal('off'), z.literal('inherit'), z.literal('url')]),
+    http: z.string().nullable(),
+    https: z.string().nullable(),
+    active: z.boolean(),
+    chained: z.number().int(),
+  }),
 })
 
 /** Result of `permissionRules/rulesRead`. */
@@ -132,6 +160,68 @@ export const RULES_RELOAD_SCHEMA = z.object({
   error: z.string().nullable(),
 })
 
+/**
+ * The `permissionRules/allowHost` request: the blocked target exactly as the
+ * block view reported it, plus the workspace the rule belongs in (`null` for
+ * a host-level block). The action never accepts a PATH — the runtime maps the
+ * cwd onto its own known rule sources, so the wire cannot widen the write set.
+ */
+export interface AllowHostRequest {
+  /** The blocked host (host name or IP literal). */
+  host: string
+  /** The blocked scheme, or null when the block record had none. */
+  scheme: 'http' | 'https' | null
+  /** The blocked port, or null when the block record had none. */
+  port: number | null
+  /** The workspace whose rule file should receive the rule, or null. */
+  cwd: string | null
+}
+
+/** Strict wire schema for {@link AllowHostRequest}. */
+export const ALLOW_HOST_REQUEST_SCHEMA = z.object({
+  host: z.string(),
+  scheme: z.union([z.literal('http'), z.literal('https'), z.null()]),
+  port: z.number().int().nullable(),
+  cwd: z.string().nullable(),
+})
+
+/**
+ * The `permissionRules/allowHost` result. `ok` reports whether the WRITE
+ * succeeded; `outcome` is the decision recomputed after it, so a page can
+ * never claim success while the connection is still blocked.
+ */
+export interface AllowHostResult {
+  ok: boolean
+  /** The rule file written, or null when nothing was written. */
+  path: string | null
+  /** Whether the file did not exist before this action created it. */
+  created: boolean
+  /**
+   * Rule chains that were re-read (the per-workspace chains, plus the
+   * session-less host chain when one was cached and had to be dropped).
+   */
+  reloaded: number
+  /** The decision for the target AFTER the action, or null when nothing was written. */
+  outcome: 'allow' | 'deny' | 'ask' | null
+  /**
+   * Nothing was written because the target was already allowed by the current
+   * decision, or because the file already leads with this exact allow rule.
+   */
+  alreadyAllowed: boolean
+  error: string | null
+}
+
+/** Strict wire schema for {@link AllowHostResult}. */
+export const ALLOW_HOST_RESULT_SCHEMA = z.object({
+  ok: z.boolean(),
+  path: z.string().nullable(),
+  created: z.boolean(),
+  reloaded: z.number().int(),
+  outcome: z.union([z.literal('allow'), z.literal('deny'), z.literal('ask'), z.null()]),
+  alreadyAllowed: z.boolean(),
+  error: z.string().nullable(),
+})
+
 /** The `permissionRules/networkStatus` invocation descriptor (no parameters). */
 export const NETWORK_STATUS_DESCRIPTOR = Object.freeze({
   id: 'dsh-permission-rules#permissionRules/networkStatus',
@@ -226,6 +316,34 @@ export const RULES_RELOAD_DESCRIPTOR = Object.freeze({
   sourceLocation: Object.freeze({ file: 'src/wire.ts', line: 1, column: 1 }),
 } as const) satisfies InvocationDescriptor
 
+/**
+ * The `permissionRules/allowHost` invocation descriptor: one request object in,
+ * one result object out.
+ */
+export const ALLOW_HOST_DESCRIPTOR = Object.freeze({
+  id: 'dsh-permission-rules#permissionRules/allowHost',
+  service: 'permissionRules',
+  namespace: 'permissionRules',
+  method: 'allowHost',
+  invocation: Object.freeze({ kind: 'direct' }),
+  parameters: Object.freeze([Object.freeze({
+    name: 'request',
+    wire: 'request',
+    source: 'json',
+    codec: Object.freeze({
+      mode: 'strict',
+      typeSymbol: 'dsh-permission-rules/types#AllowHostRequest',
+      schema: ALLOW_HOST_REQUEST_SCHEMA,
+    }),
+  } satisfies InvocationDescriptor['parameters'][number])]),
+  result: Object.freeze({
+    mode: 'strict',
+    typeSymbol: 'dsh-permission-rules/types#AllowHostResult',
+    schema: ALLOW_HOST_RESULT_SCHEMA,
+  }),
+  sourceLocation: Object.freeze({ file: 'src/wire.ts', line: 1, column: 1 }),
+} as const) satisfies InvocationDescriptor
+
 /**
  * The canonical invocation list both Typert faces register — the host
  * manifest and the client contribution share these exact descriptor
@@ -236,4 +354,5 @@ export const PERMISSION_RULES_INVOCATIONS = Object.freeze([
   RULES_READ_DESCRIPTOR,
   RULES_SAVE_DESCRIPTOR,
   RULES_RELOAD_DESCRIPTOR,
+  ALLOW_HOST_DESCRIPTOR,
 ])