@taliesinb/mash 0.0.0-stage → 0.1.0

package/src/policy/effects.ts

@@ -0,0 +1,102 @@
+/**
+ * Effects: what a command does to the world, as predicted by a behavior
+ * definition or derived from redirections. Paths are absolute abstract values
+ * (concrete at runtime).
+ */
+
+import type { AValue } from '../analysis/value.ts'
+import { describe } from '../analysis/value.ts'
+
+/**
+ * Provenance of a nested effect: the inner command it comes from, for effects
+ * of `bash -c`, script files, `eval`, `source` and `trap` actions. A list,
+ * outermost hop first (`bash -c "bash s.sh"` → [`bash s.sh`, s.sh line 3]).
+ */
+export interface Via {
+  /** Source text of the inner command. */
+  text: string
+  /** Line of the inner command in its script (1-based). */
+  line: number
+  /** The script file, when the code came from one. */
+  file?: string
+}
+
+interface EffectBase {
+  /** The command name the effect was predicted for (behavior name, `redirect`). */
+  source?: string
+  /** Where a nested effect came from (see {@link Via}). */
+  via?: Via[]
+}
+
+/**
+ * `maybe`: the command might do this (e.g. a build tool writing into its
+ * directory, or a conditional command in a nested script) — a possible
+ * effect never yields a definite policy `deny`, only `unknown`, so it cannot
+ * cause a pre-flight rejection on its own.
+ */
+export type Effect = EffectBase & (
+  /** `names`: only names and metadata are read (`find`, `ls -R`, `du`), never file contents. */
+  | { kind: 'read'; path: AValue; recursive?: boolean; maybe?: boolean; names?: boolean }
+  | { kind: 'write'; path: AValue; recursive?: boolean; append?: boolean; maybe?: boolean }
+  /** `ifExists`: a missing path is not an error and nothing happens (`rm -f`). */
+  | { kind: 'delete'; path: AValue; recursive?: boolean; maybe?: boolean; ifExists?: boolean }
+  | { kind: 'network'; target?: AValue; detail: string; maybe?: boolean }
+  | { kind: 'exec'; argv: AValue[]; maybe?: boolean }
+  | { kind: 'chdir'; path: AValue }
+  | { kind: 'process'; detail: string }
+  /** The command's effects could not be determined (no behavior definition, or opaque arguments). */
+  | { kind: 'unknown'; detail: string; maybe?: boolean }
+)
+
+export function describeEffect(e: Effect): string {
+  return describeEffectOnly(e) + viaSuffix(e)
+}
+
+function describeEffectOnly(e: Effect): string {
+  const r = ((e as { recursive?: boolean }).recursive ? ' (recursive)' : '') + ((e as { maybe?: boolean }).maybe ? ' (possibly)' : '')
+  switch (e.kind) {
+    case 'read': return `read ${describe(e.path)}${r}`
+    case 'write': return `${e.append ? 'append' : 'write'} ${describe(e.path)}${r}`
+    case 'delete': return `delete ${describe(e.path)}${r}`
+    case 'network': return `network ${e.target ? describe(e.target) : ''} ${e.detail}${r}`.replace(/ +/g, ' ').trim()
+    case 'exec': return `exec ${e.argv.map(describe).join(' ')}${r}`
+    case 'chdir': return `cd ${describe(e.path)}`
+    case 'process': return `process ${e.detail}`
+    case 'unknown': return `unknown: ${e.detail}${r}`
+  }
+}
+
+const MAX_VIA_TEXT = 60
+
+/** `` `rm -rf /opt/x` (s.sh:3) → `touch y` `` */
+export function describeVia(via: readonly Via[]): string {
+  return via
+    .map((v) => {
+      const one = v.text.replace(/\s*\n\s*/g, '; ')
+      const t = one.length > MAX_VIA_TEXT ? one.slice(0, MAX_VIA_TEXT - 1) + '…' : one
+      const where = v.file ? ` (${v.file}:${v.line})` : v.line > 1 ? ` (line ${v.line})` : ''
+      return `\`${t}\`${where}`
+    })
+    .join(' → ')
+}
+
+/** ` (via …)` for nested effects, else empty. */
+export function viaSuffix(e: Effect): string {
+  return e.via && e.via.length > 0 ? ` (via ${describeVia(e.via)})` : ''
+}
+
+/** Prepend a provenance hop to an effect (a copy). */
+export function withVia(e: Effect, hop: Via): Effect {
+  return { ...e, via: [hop, ...(e.via ?? [])] }
+}
+
+/** The effect as a possible one: a conditional command in a nested script. */
+export function asPossible(e: Effect): Effect {
+  switch (e.kind) {
+    case 'chdir':
+    case 'process':
+      return e
+    default:
+      return { ...e, maybe: true }
+  }
+}

package/src/policy/policy.ts

@@ -0,0 +1,578 @@
+/**
+ * Sandbox policy and effect checking.
+ *
+ * The file vocabulary mirrors the DeepSea harness (`SandboxExecutionPolicy`
+ * in dsh-sandbox): `read-only`, `workspace-write` (workspace root, extra
+ * roots, temp areas) and `danger-full-access`. mash adds optional network,
+ * command and read restrictions that the OS sandbox cannot express.
+ *
+ * Checking works on abstract paths: a verdict is `deny` only when EVERY
+ * possible concretisation violates the policy, `allow` only when every one is
+ * permitted, and `unknown` otherwise. Unknown substrings that may contain
+ * `/` or `..` therefore never produce a definite verdict — the runtime check
+ * on the concrete value decides.
+ */
+
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import type { AValue, Seg } from '../analysis/value.ts'
+import { describe, isHole, isNameLike, isSlashFree } from '../analysis/value.ts'
+import type { Effect } from './effects.ts'
+import { describeEffect } from './effects.ts'
+
+export type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access'
+
+export interface Policy {
+  mode: SandboxMode
+  /** Absolute workspace root (writable under `workspace-write`). */
+  workspaceRoot: string
+  additionalWritableRoots?: readonly string[]
+  /** Temp areas are writable under `workspace-write` (default true). */
+  writableTemp?: boolean
+  /**
+   * Network access (default `allow`; the harness OS sandbox does not govern
+   * network). `{ allow: hosts }` permits only connections to those hosts:
+   * `example.com` (exactly), `*.example.com` (any subdomain), `*` (any).
+   */
+  network?: 'allow' | 'deny' | { allow: readonly string[] }
+  /** Commands without a behavior definition (default `allow`: the OS sandbox still confines them). */
+  unknownCommands?: 'allow' | 'deny'
+  /** Command names (basenames) that may never run. */
+  deniedCommands?: readonly string[]
+  /** Directories (or files) that may not be read, in every mode (e.g. `~/.ssh`). */
+  readDeniedRoots?: readonly string[]
+  /**
+   * Read policy coverage for credential stores: also deny reading the
+   * locations in {@link credentialReadRoots} (`~/.ssh`, `~/.aws`, `~/.config/gh`,
+   * keychains, …). Opt-in (default false).
+   */
+  readDenyCredentials?: boolean
+  /** Home directory for {@link credentialReadRoots} (default `os.homedir()`). */
+  home?: string
+  /**
+   * `rm -f` of a path that does not exist: `deny` (default; the attempt is the
+   * violation, as in path-based OS sandboxes) or `allow` (nothing happens, so
+   * nothing is violated; statically, when the path is missing now and the
+   * snippet does not create it).
+   */
+  missingDeletes?: 'deny' | 'allow'
+}
+
+/**
+ * Where credentials live: private keys, cloud and CLI tokens, keychains and
+ * password stores. Files and directories, relative to `home` unless absolute.
+ */
+export const CREDENTIAL_LOCATIONS: readonly string[] = [
+  '.ssh', '.gnupg', '.aws', '.azure', '.config/gcloud', '.config/gh', '.config/hub', '.config/op', '.config/doctl',
+  '.kube', '.docker/config.json', '.netrc', '.git-credentials', '.npmrc', '.yarnrc.yml', '.pypirc', '.gem/credentials',
+  '.cargo/credentials', '.cargo/credentials.toml', '.terraform.d/credentials.tfrc.json', '.vault-token', '.password-store',
+  '.local/share/keyrings', 'Library/Keychains', '/Library/Keychains', '/etc/shadow', '/etc/gshadow', '/private/etc/master.passwd',
+]
+
+/**
+ * Non-secret files inside credential locations that stay readable (agents
+ * debug ssh setups): public keys, `config`, `known_hosts`, `authorized_keys`.
+ * Listing a credential directory (`ls ~/.ssh`) is allowed too.
+ */
+export const CREDENTIAL_READ_EXCEPTIONS: readonly string[] = ['.ssh/*.pub', '.ssh/config', '.ssh/known_hosts', '.ssh/known_hosts.old', '.ssh/authorized_keys']
+
+/** Is every concretisation of `alt` one of the non-secret files (`dir/*.pub` or an exact name)? */
+function isCredentialException(alt: Seg[], home: string): boolean {
+  for (const ex of CREDENTIAL_READ_EXCEPTIONS) {
+    const full = path.join(home, ex)
+    const star = full.indexOf('*')
+    if (star === -1) {
+      if (alt.length === 1 && typeof alt[0] === 'string' && path.normalize(alt[0]) === full) return true
+      continue
+    }
+    // `dir/*suffix`: a literal `dir/`, then name-like holes and literals without `/`, ending in `suffix`
+    const dir = full.slice(0, star)
+    const suffix = full.slice(star + 1)
+    const first = alt[0]
+    if (typeof first !== 'string' || !first.startsWith(dir)) continue
+    const rest: Seg[] = [first.slice(dir.length), ...alt.slice(1)]
+    if (rest.some((s) => (typeof s === 'string' ? s.includes('/') : !isNameLike(s.type)))) continue
+    const last = rest[rest.length - 1]
+    const holes = rest.some((s) => typeof s !== 'string')
+    // a literal ending (with something before it), or a glob match whose pattern has the ending
+    if (typeof last === 'string' ? last.endsWith(suffix) && (holes || last.length > suffix.length) : last.pattern?.endsWith(suffix) === true) return true
+  }
+  return false
+}
+
+/** {@link CREDENTIAL_LOCATIONS} resolved against a home directory. */
+export function credentialReadRoots(home: string = os.homedir()): string[] {
+  return CREDENTIAL_LOCATIONS.map((p) => (p.startsWith('/') ? p : path.join(home, p)))
+}
+
+/** Every read-denied root of a policy (explicit ones, plus credential stores when enabled), with realpaths. */
+export function readDeniedRoots(policy: Policy): string[] {
+  const roots = [...(policy.readDeniedRoots ?? [])]
+  if (policy.readDenyCredentials) roots.push(...credentialReadRoots(policy.home ?? os.homedir()))
+  return withRealpaths(roots)
+}
+
+export type Verdict = 'allow' | 'deny' | 'unknown'
+
+export interface PolicyFinding {
+  effect: Effect
+  verdict: Verdict
+  reason: string
+}
+
+/** Paths every mode may write: sinks and terminals. */
+const ALWAYS_WRITABLE = ['/dev/null', '/dev/stdout', '/dev/stderr', '/dev/tty', '/dev/fd', '/dev/zero']
+
+function tempRoots(): string[] {
+  const roots = new Set<string>(['/tmp', '/private/tmp', '/var/tmp', '/private/var/tmp'])
+  const t = os.tmpdir()
+  roots.add(t)
+  try {
+    roots.add(fs.realpathSync(t))
+  } catch {
+    // ignore
+  }
+  if (process.env.TMPDIR) roots.add(process.env.TMPDIR.replace(/\/+$/, ''))
+  return [...roots]
+}
+
+function withRealpaths(roots: readonly string[]): string[] {
+  const out = new Set<string>()
+  for (const r of roots) {
+    const n = path.resolve(r)
+    out.add(n)
+    try {
+      out.add(fs.realpathSync(n))
+    } catch {
+      // ignore
+    }
+  }
+  return [...out]
+}
+
+export function writableRoots(policy: Policy): string[] {
+  if (policy.mode !== 'workspace-write') return []
+  const roots = [policy.workspaceRoot, ...(policy.additionalWritableRoots ?? [])]
+  if (policy.writableTemp !== false) roots.push(...tempRoots())
+  return withRealpaths(roots)
+}
+
+// ---------------------------------------------------------------------------
+// Abstract path shapes
+// ---------------------------------------------------------------------------
+
+/**
+ * What we can say about where an abstract absolute path points:
+ * - `exact`: one concrete normalised path
+ * - `below`: the path is `dir` or somewhere beneath it
+ * - `unknown`: nothing definite (an unknown part may contain `/..`)
+ */
+export type PathShape =
+  | { kind: 'exact'; path: string }
+  | { kind: 'below'; dir: string }
+  | { kind: 'unknown'; hint: string }
+
+/**
+ * A resolved path component: a literal name, or a `pattern` standing for one
+ * unknown real name (it never is `.`/`..`, so a later `..` pops exactly it).
+ * A `deep` pattern is the unknown tail of an anchored `path` hole: zero or
+ * more components, so a `..` that would pop it may escape the anchor.
+ */
+type Comp = string | { pattern: true; deep?: boolean }
+
+/** One component of the input alternative, before `.`/`..` resolution. */
+type RawComp =
+  | { kind: 'lit'; text: string }
+  /** Contains a name-like hole or a literal character other than `.`: one real name. */
+  | { kind: 'name' }
+  /** Only slash-free holes that may be empty/`.`/`..`, and dots: any of a name, `.` or `..`. */
+  | { kind: 'ambiguous' }
+
+const MAX_SHAPE_BRANCHES = 64
+
+/**
+ * Shapes of one alternative of an absolute (or cwd-relative already joined)
+ * path. Usually one shape; a component that may be `..` (a `segment` hole on
+ * its own) branches into the possible resolutions.
+ */
+export function altShapes(alt: Seg[]): PathShape[] {
+  const hint = alt.map((s) => (typeof s === 'string' ? s : `⟨${s.origin}⟩`)).join('')
+  const unknown: PathShape[] = [{ kind: 'unknown', hint }]
+  if (alt.length === 0) return unknown
+  let start: Comp[] = []
+  let i = 0
+  const first = alt[0]
+  if (isHole(first)) {
+    if (first.type === 'path' && first.under) {
+      start = path.resolve(first.under).split('/').filter(Boolean)
+      start.push({ pattern: true, deep: true })
+      i = 1
+    } else {
+      return unknown
+    }
+  } else if (!first.startsWith('/')) {
+    return unknown
+  }
+  // split into raw components
+  const raws: RawComp[] = []
+  let text = ''
+  let holes = false
+  let nameLike = false
+  const flush = (): void => {
+    if (!holes) raws.push({ kind: 'lit', text })
+    else if (nameLike || /[^.]/.test(text)) raws.push({ kind: 'name' })
+    else raws.push({ kind: 'ambiguous' })
+    text = ''
+    holes = false
+    nameLike = false
+  }
+  for (; i < alt.length; i++) {
+    const s = alt[i]
+    if (typeof s === 'string') {
+      for (const ch of s) {
+        if (ch === '/') flush()
+        else text += ch
+      }
+    } else if (isSlashFree(s.type)) {
+      holes = true
+      if (isNameLike(s.type)) nameLike = true
+    } else {
+      return unknown
+    }
+  }
+  flush()
+  // resolve `.`/`..`, branching on ambiguous components
+  const out: PathShape[] = []
+  let branches = 0
+  const walk = (k: number, comps: Comp[]): boolean => {
+    if (k === raws.length) {
+      if (++branches > MAX_SHAPE_BRANCHES) return false
+      out.push(finish(comps))
+      return true
+    }
+    const r = raws[k]
+    const pop = (): Comp[] | null => {
+      const top = comps[comps.length - 1]
+      if (top !== undefined && typeof top !== 'string' && top.deep) return null // may escape the anchor
+      return comps.slice(0, -1)
+    }
+    if (r.kind === 'lit') {
+      if (r.text === '' || r.text === '.') return walk(k + 1, comps)
+      if (r.text === '..') {
+        const next = pop()
+        return next !== null && walk(k + 1, next)
+      }
+      return walk(k + 1, [...comps, r.text])
+    }
+    if (r.kind === 'name') return walk(k + 1, [...comps, { pattern: true }])
+    // ambiguous: a name, `.`/empty, or `..`
+    const next = pop()
+    return next !== null && walk(k + 1, [...comps, { pattern: true }]) && walk(k + 1, comps) && walk(k + 1, next)
+  }
+  if (!walk(0, start)) return unknown
+  return out
+}
+
+/** All-literal components are an exact path; otherwise the literal prefix up to the first pattern is a `below` directory. */
+function finish(comps: Comp[]): PathShape {
+  const prefix: string[] = []
+  for (const c of comps) {
+    if (typeof c !== 'string') break
+    prefix.push(c)
+  }
+  const dir = '/' + prefix.join('/')
+  return prefix.length === comps.length ? { kind: 'exact', path: dir } : { kind: 'below', dir }
+}
+
+/** The first shape of one alternative (see {@link altShapes}). */
+export function altShape(alt: Seg[]): PathShape {
+  return altShapes(alt)[0]
+}
+
+export function shapesOf(v: AValue): PathShape[] {
+  return v.alts.flatMap(altShapes)
+}
+
+function isInside(p: string, root: string): boolean {
+  return p === root || p.startsWith(root.endsWith('/') ? root : root + '/')
+}
+
+/** Is a shape inside `root`? */
+function shapeInside(shape: PathShape, root: string): 'yes' | 'no' | 'maybe' {
+  switch (shape.kind) {
+    case 'exact':
+      return isInside(shape.path, root) ? 'yes' : 'no'
+    case 'below':
+      if (isInside(shape.dir, root)) return 'yes'
+      if (isInside(root, shape.dir)) return 'maybe'
+      return 'no'
+    case 'unknown':
+      return 'maybe'
+  }
+}
+
+function insideAny(shape: PathShape, roots: string[]): 'yes' | 'no' | 'maybe' {
+  let maybe = false
+  for (const r of roots) {
+    const v = shapeInside(shape, r)
+    if (v === 'yes') return 'yes'
+    if (v === 'maybe') maybe = true
+  }
+  return maybe ? 'maybe' : 'no'
+}
+
+function lexists(p: string): boolean {
+  try {
+    fs.lstatSync(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function isFile(p: string): boolean {
+  try {
+    return fs.statSync(p).isFile()
+  } catch {
+    return false
+  }
+}
+
+/** Resolve symlinks of the deepest existing ancestor of a concrete path. */
+export function realpathLoose(p: string): string {
+  let cur = p
+  const tail: string[] = []
+  for (;;) {
+    try {
+      const real = fs.realpathSync(cur)
+      return tail.length === 0 ? real : path.join(real, ...tail.reverse())
+    } catch {
+      const parent = path.dirname(cur)
+      if (parent === cur) return p
+      tail.push(path.basename(cur))
+      cur = parent
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Checking
+// ---------------------------------------------------------------------------
+
+export interface CheckOptions {
+  /** Concrete runtime check: also resolve symlinks. */
+  runtime?: boolean
+}
+
+function checkWritePath(p: AValue, policy: Policy, opts: CheckOptions): { verdict: Verdict; reason: string } {
+  if (policy.mode === 'danger-full-access') return { verdict: 'allow', reason: 'danger-full-access' }
+  const shapes = shapesOf(p)
+  const roots = [...writableRoots(policy), ...ALWAYS_WRITABLE]
+  let allYes = true
+  let allNo = true
+  for (const s of shapes) {
+    let v = insideAny(s, roots)
+    if (opts.runtime && s.kind === 'exact' && v === 'yes' && !ALWAYS_WRITABLE.some((r) => isInside(s.path, r))) {
+      // a symlink inside the workspace may point outside it
+      const real = realpathLoose(s.path)
+      if (real !== s.path) v = insideAny({ kind: 'exact', path: real }, roots)
+    }
+    if (v !== 'yes') allYes = false
+    if (v !== 'no') allNo = false
+  }
+  const where = policy.mode === 'read-only' ? 'the policy is read-only' : `outside the writable roots (${[policy.workspaceRoot, ...(policy.additionalWritableRoots ?? [])].join(', ')}${policy.writableTemp !== false ? ', temp' : ''})`
+  if (allYes) return { verdict: 'allow', reason: 'inside a writable root' }
+  if (allNo) return { verdict: 'deny', reason: `${describe(p)} is ${where}` }
+  return { verdict: 'unknown', reason: `${describe(p)} may be ${where}` }
+}
+
+/**
+ * Reads are denied inside read-denied roots. A recursive read (`grep -r`,
+ * `tar c`, `cp -r`) of a directory that contains a denied root reads into it,
+ * so it is denied too (`grep -r token ~`); when the directory is only possibly
+ * such a parent (an unknown path), it is `unknown`.
+ */
+function checkReadPath(p: AValue, policy: Policy, recursive: boolean, opts: CheckOptions, names = false): { verdict: Verdict; reason: string } {
+  const denied = readDeniedRoots(policy)
+  if (denied.length === 0) return { verdict: 'allow', reason: 'reads are unrestricted' }
+  // listing names and metadata (find, ls -R, du) reveals no file contents
+  if (names) return { verdict: 'allow', reason: 'lists names only' }
+  let anyMaybe = false
+  let allYes = true
+  const home = policy.home ?? os.homedir()
+  const shapes = p.alts.flatMap((alt) => (policy.readDenyCredentials && isCredentialException(alt, home) ? [] : altShapes(alt)))
+  if (shapes.length === 0) return { verdict: 'allow', reason: 'a non-secret file in a credential location' }
+  for (const s of shapes) {
+    let v = insideAny(s, denied)
+    // listing a denied directory itself (`ls ~/.ssh`) reads names, not contents
+    if (v === 'yes' && !recursive && s.kind === 'exact' && denied.includes(s.path) && !isFile(s.path)) v = 'no'
+    // at runtime, a symlink may lead into a denied root
+    if (opts.runtime && s.kind === 'exact' && v === 'no') {
+      const real = realpathLoose(s.path)
+      if (real !== s.path) {
+        v = insideAny({ kind: 'exact', path: real }, denied)
+        if (v === 'no' && recursive && denied.some((r) => isInside(r, real))) v = 'yes'
+      }
+    }
+    if (v === 'no' && recursive && s.kind === 'exact' && denied.some((r) => isInside(r, s.path))) v = 'yes'
+    if (v !== 'yes') allYes = false
+    if (v !== 'no') anyMaybe = true
+  }
+  const what = 'a read-denied location'
+  if (allYes) return { verdict: 'deny', reason: recursive ? `${describe(p)} is or contains ${what}` : `${describe(p)} is in ${what}` }
+  if (anyMaybe) return { verdict: 'unknown', reason: `${describe(p)} may be in or contain ${what}` }
+  return { verdict: 'allow', reason: 'not in a read-denied location' }
+}
+
+// ---------------------------------------------------------------------------
+// Network hosts
+// ---------------------------------------------------------------------------
+
+/**
+ * The host a network target names, when it is determined by the literal text
+ * of the value: `https://user@Host:8080/x` → `host`, `git@github.com:o/r` →
+ * `github.com`, `user@example.com` → `example.com`.
+ * Undefined when the host depends on an unknown part (`https://$H/x`), when
+ * there is none (`file:///x`), and for a bare word (`example.com`,
+ * `example.com/x`, `localhost:3000`): behaviors cannot always tell a host operand from an
+ * option's value (`ssh -i key host`, `git clone --depth 1 url`), so a bare
+ * word is never trusted for a definite verdict. Neither is anything that is
+ * not a host name or IP address (`BatchMode=yes`, `+short`, `8080`).
+ */
+export function targetHost(alt: Seg[]): string | undefined {
+  const complete = alt.every((s) => typeof s === 'string')
+  const lit = typeof alt[0] === 'string' ? alt[0] : ''
+  const text = complete ? alt.join('') : lit
+  // the literal part must reach past the end of the host (or be the whole value)
+  const upTo = (s: string, stops: RegExp): string | undefined => {
+    const m = stops.exec(s)
+    if (m) return s.slice(0, m.index)
+    return complete ? s : undefined
+  }
+  const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\//.exec(text)
+  let authority: string | undefined
+  if (scheme) {
+    if (scheme[1].toLowerCase() === 'file') return undefined
+    authority = upTo(text.slice(scheme[0].length), /[/?#]/)
+  } else {
+    // scp-like `user@host:path` (a `:` before any `/`), or `user@host`; without
+    // the `user@` it may be an option value (`ssh -L localhost:80:x:80 h`)
+    const scp = /^([^/:]*):(?!\/\/)/.exec(text)
+    authority = scp && !/^\[/.test(text) ? scp[1] : upTo(text, /[/?#]/)
+    if (authority !== undefined && !authority.includes('@')) return undefined
+  }
+  if (authority === undefined) return undefined
+  let host = authority.slice(authority.lastIndexOf('@') + 1)
+  if (host.startsWith('[')) {
+    const end = host.indexOf(']')
+    if (end === -1) return undefined
+    host = host.slice(1, end)
+  } else host = host.replace(/:\d*$/, '')
+  host = host.toLowerCase().replace(/\.$/, '')
+  const ipv6 = host.includes(':')
+  if (ipv6 ? !/^[0-9a-f:.]+$/.test(host) : !/^[a-z0-9_]([a-z0-9_-]*[a-z0-9_])?(\.[a-z0-9_]([a-z0-9_-]*[a-z0-9_])?)*$/.test(host) || /^\d+$/.test(host)) return undefined
+  return host
+}
+
+/** Does an allow-list entry match a host? */
+export function hostMatches(host: string, entry: string): boolean {
+  const e = entry.toLowerCase().replace(/\.$/, '')
+  if (e === '*') return true
+  if (e.startsWith('*.')) return host.endsWith(e.slice(1)) && host.length > e.length - 1
+  return host === e
+}
+
+function checkHosts(target: AValue | undefined, allow: readonly string[]): { verdict: Verdict; reason: string } {
+  const list = allow.join(', ')
+  if (!target) return { verdict: 'unknown', reason: `network access to hosts not known statically (allowed: ${list})` }
+  let allYes = true
+  let allNo = true
+  const bad: string[] = []
+  for (const alt of target.alts) {
+    const host = targetHost(alt)
+    if (host === undefined) {
+      allYes = false
+      allNo = false
+      continue
+    }
+    if (allow.some((e) => hostMatches(host, e))) allNo = false
+    else {
+      allYes = false
+      bad.push(host)
+    }
+  }
+  if (allYes) return { verdict: 'allow', reason: 'host allowed' }
+  if (allNo) return { verdict: 'deny', reason: `network access to ${[...new Set(bad)].join(', ')} is not allowed (allowed: ${list})` }
+  return { verdict: 'unknown', reason: `network access to ${describe(target)} may not be allowed (allowed: ${list})` }
+}
+
+export function checkEffect(effect: Effect, policy: Policy, opts: CheckOptions = {}): PolicyFinding {
+  const f = (verdict: Verdict, reason: string): PolicyFinding => ({ effect, verdict, reason })
+  switch (effect.kind) {
+    case 'read': {
+      const r = checkReadPath(effect.path, policy, effect.recursive === true, opts, effect.names === true)
+      return f(effect.maybe && r.verdict === 'deny' ? 'unknown' : r.verdict, r.reason)
+    }
+    case 'write':
+    case 'delete': {
+      // `rm -f` of a path that does not exist does nothing
+      if (opts.runtime && effect.kind === 'delete' && effect.ifExists && policy.missingDeletes === 'allow' && effect.path.alts.every((a) => a.length === 1 && typeof a[0] === 'string' && !lexists(a[0]))) {
+        return f('allow', 'delete: nothing to delete (missing path, -f)')
+      }
+      const r = checkWritePath(effect.path, policy, opts)
+      const verb = effect.kind === 'delete' ? 'delete' : 'write'
+      if (effect.maybe && r.verdict === 'deny') return f('unknown', `may ${verb}: ${r.reason}`)
+      return f(r.verdict, `${verb}: ${r.reason}`)
+    }
+    case 'network': {
+      if (policy.network === 'deny') return f(effect.maybe ? 'unknown' : 'deny', `network access is denied (${describeEffect(effect)})`)
+      if (policy.network === undefined || policy.network === 'allow') return f('allow', 'network allowed')
+      const r = checkHosts(effect.target, policy.network.allow)
+      return f(effect.maybe && r.verdict === 'deny' ? 'unknown' : r.verdict, r.reason)
+    }
+    case 'exec':
+    case 'chdir':
+    case 'process':
+      return f('allow', '')
+    case 'unknown':
+      if (policy.unknownCommands === 'deny' && policy.mode !== 'danger-full-access') return f(effect.maybe ? 'unknown' : 'deny', `effects unknown: ${effect.detail}`)
+      return f('unknown', effect.detail)
+  }
+}
+
+export function checkCommandName(name: string, policy: Policy): PolicyFinding | null {
+  const base = name.split('/').pop() ?? name
+  if (policy.deniedCommands?.includes(base)) {
+    return { effect: { kind: 'exec', argv: [{ alts: [[name]] }] }, verdict: 'deny', reason: `command '${base}' is denied by policy` }
+  }
+  return null
+}
+
+export function checkEffects(effects: Effect[], policy: Policy, opts: CheckOptions = {}): PolicyFinding[] {
+  return effects.map((e) => checkEffect(e, policy, opts))
+}
+
+/** Denied command names among nested `exec` effects (a possible exec is only `unknown`). */
+export function checkExecEffects(effects: Effect[], policy: Policy): PolicyFinding[] {
+  const out: PolicyFinding[] = []
+  for (const e of effects) {
+    if (e.kind !== 'exec') continue
+    const first = e.argv[0]
+    const n = first && first.alts.length === 1 && first.alts[0].length === 1 && typeof first.alts[0][0] === 'string' ? first.alts[0][0] : undefined
+    const f = n ? checkCommandName(n, policy) : null
+    if (f) out.push(e.maybe ? { effect: e, verdict: 'unknown', reason: `may run: ${f.reason}` } : { ...f, effect: e })
+  }
+  return out
+}
+
+/** The most severe verdict. */
+export function worstVerdict(findings: PolicyFinding[]): Verdict {
+  if (findings.some((f) => f.verdict === 'deny')) return 'deny'
+  if (findings.some((f) => f.verdict === 'unknown')) return 'unknown'
+  return 'allow'
+}
+
+export function defaultPolicy(workspaceRoot: string): Policy {
+  return { mode: 'workspace-write', workspaceRoot, writableTemp: true, network: 'allow', unknownCommands: 'allow' }
+}