@robmclarty/volley 0.5.4 → 0.6.0

package/dist/index.d.ts

@@ -276,8 +276,8 @@ type ResolveOptions = {
     env?: Record<string, string | undefined>;
 };
 /** Merge, expand, and validate a raw `VolleyConfig` into a `ResolvedConfig`.
- * `check_resolved` is filled in later by check detection (workspace-relative);
- * it starts as `none` and `resolve_check_runner` overrides it. */
+ * `check_resolved` comes from check detection against the workspace, so the
+ * SDK and the CLI resolve `auto` and a command check the same way. */
 declare function resolve_config(raw: VolleyConfig, options?: ResolveOptions): ResolvedConfig;
 
 type Role = 'builder' | 'critic' | 'check';
@@ -349,6 +349,89 @@ declare const verdict_schema: z.ZodObject<{
 }, z.core.$strip>;
 type VerdictOutput = z.infer<typeof verdict_schema>;
 
+/** Canonical identity of the allowlist bridge the examples create (`docker
+ * network create --subnet <SANDBOX_NETWORK_SUBNET> <SANDBOX_NETWORK_NAME>`) and
+ * the host `DOCKER-USER` rules scope to. Exported so the blessed examples
+ * share one spelling of the invocation spec. */
+declare const SANDBOX_NETWORK_NAME = "volley-sandbox-net";
+declare const SANDBOX_NETWORK_SUBNET = "172.31.99.0/24";
+/**
+ * The container's egress posture. Under whole-process containment
+ * the model client and the `fetch` tool run inside the container, so its
+ * legitimate egress is the package registry for `pnpm install` plus the host LLM
+ * endpoint the model client reaches via host-gateway.
+ *
+ * - `'none'` — `--network none`: no interface at all, a complete L3 egress deny.
+ *   The default-deny default; it fits a genuinely offline run where the model and
+ *   deps are already in-container (a host-run model is unreachable under `none`).
+ *   With the whole process in-container, `fetch` has no route either, so it
+ *   degrades cleanly to a returned error result and the run continues.
+ * - `'allowlist'` — the container sits on volley's dedicated user-defined bridge
+ *   with `host.docker.internal:host-gateway`, collapsing the allowlist targets
+ *   (the package registry, and the host LLM endpoint the in-container model
+ *   client now reaches) onto the host gateway. The L3/L4 default-DROP that
+ *   makes the bridge a true allowlist is the host-applied, subnet-scoped
+ *   `DOCKER-USER` rule the operator installs (volley never installs it — that
+ *   chain is root and host-global, and on Docker Desktop lives inside a VM). The
+ *   always-on tool-level SSRF deny-list is the second, in-process defense-in-depth
+ *   layer. Host hardening, run once as root on a Linux host, scoped to volley's
+ *   subnet so it never touches other containers (insert ahead of the chain's
+ *   terminating RETURN, in order):
+ *     iptables -I DOCKER-USER -s 172.31.99.0/24 -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
+ *     iptables -I DOCKER-USER -s 172.31.99.0/24 -d <host-gateway-ip> -j ACCEPT   # collapsed allowlist
+ *     iptables -I DOCKER-USER -s 172.31.99.0/24 -p udp --dport 53 -j ACCEPT      # DNS
+ *     iptables -I DOCKER-USER -s 172.31.99.0/24 -j DROP                          # default-deny the rest
+ */
+type SandboxNetwork = 'none' | 'allowlist';
+/**
+ * The network-related `docker run` args for a posture, pure and exported
+ * so the policy is unit-testable without a daemon. `'none'` denies all egress
+ * (`--network none`); `'allowlist'` attaches the dedicated user-defined bridge and
+ * collapses the allowlist targets onto the host gateway (`host.docker.internal`,
+ * the Linux-portable spelling — harmless where Docker Desktop already provides it).
+ */
+declare function network_run_args(network: SandboxNetwork, network_name: string): string[];
+/**
+ * The hardened `docker run` argv that launches volley inside its container.
+ * Pure and exported so the flag set is unit-testable without a
+ * daemon and the blessed examples / `--dry-run` preflight can render it.
+ *
+ * A one-shot, foreground `--rm` container — the whole run *is* this
+ * container (an earlier design ran a detached `-d … sleep infinity` daemon volley
+ * `exec`'d against), so `--rm` cleans it up when volley exits. `command`
+ * appends the container command (the volley args); omit it to use the image's
+ * `volley` entrypoint. `env` injects `-e KEY=VALUE` pairs (the `VOLLEY_MODEL_HOST`
+ * crossing). `labels` adds `--label KEY=VALUE` pairs, so a caller that owns the
+ * container's lifecycle can find and reap it by label. `entrypoint` overrides
+ * the image entrypoint (the opt-in real-docker isolation test runs a raw `sh`
+ * this way).
+ *
+ * `store_volume` mounts the named volume as the pnpm store; omit it and no store
+ * is mounted. A store is shared by every run that mounts it, so a caller that
+ * installs dependencies in a separate container first can keep the builder's
+ * container off it, and no builder can leave files in a store a later install
+ * trusts.
+ *
+ * Never emits `--privileged` and refuses `--user 0`: volley must not hand
+ * the sandbox root or full capabilities. Everything writable under the
+ * `--read-only` rootfs is an explicit tmpfs or volume; the bind-mounted worktree
+ * is the one host-visible write path.
+ */
+declare function sandbox_run_args(options: {
+    image: string;
+    build_root: string;
+    uid: number | null;
+    gid: number | null;
+    store_volume?: string | null;
+    network: SandboxNetwork;
+    network_name: string;
+    name?: string | null;
+    env?: ReadonlyArray<readonly [string, string]>;
+    labels?: ReadonlyArray<readonly [string, string]>;
+    entrypoint?: string | null;
+    command?: ReadonlyArray<string>;
+}): string[];
+
 declare const EXIT_SUCCESS = 0;
 declare const EXIT_BUDGET_EXHAUSTED = 2;
 declare const EXIT_BUILDER_ERROR = 3;
@@ -360,4 +443,4 @@ declare const EXIT_INTERRUPTED = 130;
 declare function exit_code_for_status(status: RunStatus): number;
 declare function exit_code_for_error(err: unknown): number;
 
-export { type BuilderPermissionMode, type CheckArtifact, type CheckMode, type CheckResult, type CheckRunnerKind, type CostSource, type CriticPreset, type CriticProvider, EXIT_BUDGET_EXHAUSTED, EXIT_BUILDER_ERROR, EXIT_CHECK_ERROR, EXIT_CONFIG_ERROR, EXIT_COST_CAP, EXIT_CRITIC_ERROR, EXIT_INTERRUPTED, EXIT_SUCCESS, type HaltReason, type LoopState, type PhaseRecord, type RenderMode, type Renderer, type RendererOptions, type ResolvedConfig, type RunResult, type RunStatus, type Verdict, type VerdictOutput, type VolleyConfig, create_renderer, exit_code_for_error, exit_code_for_status, expand_at_file, gate, initial_state, load_config_file, resolve_config, run_volley, status_of, verdict_schema };
+export { type BuilderPermissionMode, type CheckArtifact, type CheckMode, type CheckResult, type CheckRunnerKind, type CostSource, type CriticPreset, type CriticProvider, EXIT_BUDGET_EXHAUSTED, EXIT_BUILDER_ERROR, EXIT_CHECK_ERROR, EXIT_CONFIG_ERROR, EXIT_COST_CAP, EXIT_CRITIC_ERROR, EXIT_INTERRUPTED, EXIT_SUCCESS, type HaltReason, type LoopState, type PhaseRecord, type RenderMode, type Renderer, type RendererOptions, type ResolvedConfig, type RunResult, type RunStatus, SANDBOX_NETWORK_NAME, SANDBOX_NETWORK_SUBNET, type SandboxNetwork, type Verdict, type VerdictOutput, type VolleyConfig, create_renderer, exit_code_for_error, exit_code_for_status, expand_at_file, gate, initial_state, load_config_file, network_run_args, resolve_config, run_volley, sandbox_run_args, status_of, verdict_schema };