@namzu/sandbox 14.0.0 → 16.0.0

package/dist/backends/docker/index.d.ts

@@ -22,7 +22,7 @@
  */
 import { type ContainerSandboxLayout, type ResolvedContainerSandboxLayout } from '@namzu/sdk';
 import type { BrokeredCredential, EgressProxyOptions } from '../../egress/index.js';
-import { type EgressPolicy, type SandboxBackend } from '../../index.js';
+import { type EgressPolicy, type SandboxBackend, type SandboxBackendOptions } from '../../index.js';
 /**
  * Backend-specific tuning. Most hosts use the defaults; advanced
  * deployments override `image` to point at their own pre-built
@@ -47,13 +47,66 @@ export interface DockerBackendInternalConfig {
     /**
      * `--user` value for the container, e.g. `'1000:1000'` or `'nobody'`.
      *
-     * Left unset by default because the correct uid depends on the image's
-     * own filesystem ownership, and forcing one would break every image
-     * that expects root at startup. Set it whenever the image supports a
-     * non-root user — a container running as root is one bind-mount
-     * misconfiguration away from writing the host.
+     * Left unset by default because `--user` does not ADD a non-root user, it
+     * OVERRIDES the image's own choice of one. The reference image ends with
+     * `USER namzu` (uid 1001, its `/workspace` chowned to match), so this
+     * backend's default is already non-root for the image it ships — a
+     * hard-coded uid here would replace that with a guess, and the guess is
+     * wrong for any image whose files are owned by someone else, which
+     * surfaces as `EACCES` on a path the workload was told it could write.
+     * Set it when the image does not declare a user of its own, or when the
+     * host wants a different one than it declares.
      */
     readonly runAsUser?: string;
+    /**
+     * CPU cores the container may use, rendered as `--cpus`. Unset by default.
+     *
+     * `--memory` and `--pids-limit` bound what a workload can take from the
+     * host, and CPU had no equivalent at all — no default, no knob — which
+     * reads as an oversight rather than a decision. It stays unset for the
+     * same reason neither of those two has a numeric default: the right value
+     * is a property of the host's machine and of what the workload is for, and
+     * any number this backend picked would silently throttle a run that
+     * finishes inside its timeout today. A host that wants the bound says what
+     * it is; the value is a decimal (`--cpus 1.5` is one and a half cores'
+     * worth of time, not a rounding).
+     *
+     * It lives on this config rather than beside `memoryLimitMb` on the
+     * per-call options because the documented deployment constructs one
+     * provider per task, so construction time IS per-task — and a control
+     * added to the tier-agnostic per-call shape would have to be refused by
+     * the ACI and kubernetes backends, which cannot apply a per-sandbox CPU
+     * limit any more than they can apply the memory and process ones.
+     */
+    readonly cpuLimit?: number;
+    /**
+     * Mount the container's root filesystem read-only. Default `true`.
+     *
+     * See {@link HARDENING_ARGS} for why the default is on and
+     * {@link renderWritableRootfsArgs} for the paths that stay writable while
+     * it is. Set it to `false` to make every path inside the container
+     * writable again, which is what a host whose image writes somewhere the
+     * writable set cannot describe needs, and which is why the switch exists
+     * instead of an unwritten rule that the baseline is absolute. It turns off
+     * that one control and nothing else: `--cap-drop=ALL`,
+     * `--security-opt=no-new-privileges` and `--ipc private` are applied
+     * whatever this says. It is a config field rather than an argument so that
+     * turning it off is a line somebody wrote on purpose, and not the default
+     * anyone gets by not looking.
+     */
+    readonly readOnlyRootfs?: boolean;
+    /**
+     * Extra paths to keep writable under `--read-only`, each mounted `--tmpfs`.
+     *
+     * The default set ({@link DEFAULT_WRITABLE_ROOTFS_PATHS}) is the reference
+     * image's needs, read off its Dockerfile; this is how a host that points
+     * `image` somewhere else says what ITS image needs, because the backend
+     * cannot read that out of an image and guessing is what these paths would
+     * otherwise be. A path the layout already mounts is refused rather than
+     * mounted twice (`Duplicate mount point`), and setting this at all beside
+     * `readOnlyRootfs: false` is refused as a contradiction.
+     */
+    readonly writableRootfsPaths?: readonly string[];
     /**
      * Credentials the egress proxy stamps on, per host.
      *
@@ -207,6 +260,116 @@ export declare function assertNetworkCarriesThePolicy(network: string, reachabil
  * receives is the failure this shape exists to make testable.
  */
 export declare function egressProxyOptions(config: Pick<DockerBackendInternalConfig, 'brokeredCredentials' | 'allowInwardFor'>, policy: EgressPolicy): EgressProxyOptions;
+/** The backend config the hardening flags are rendered from. */
+export type DockerHardeningConfig = Pick<DockerBackendInternalConfig, 'cpuLimit' | 'layout' | 'readOnlyRootfs' | 'writableRootfsPaths'>;
+/**
+ * Refuse rootfs options that cannot both be honoured.
+ *
+ * `writableRootfsPaths` beside `readOnlyRootfs: false` is a contradiction: with
+ * a writable root filesystem every path is already writable, so the tmpfs
+ * mounts would either be dropped (a control accepted and not applied) or take a
+ * directory off the image for no reason. Refusing is the honest answer, and it
+ * is the same one the sibling backends give a per-sandbox control they cannot
+ * express.
+ *
+ * Called at construction and again where the argv is built, so a config that
+ * reaches `create()` by some path other than `buildDockerBackend` is refused
+ * too.
+ */
+export declare function assertRootfsOptionsAreCoherent(config: DockerHardeningConfig): void;
+/**
+ * Refuse a `--cpus` value that cannot mean what it says.
+ *
+ * This covers non-finite and non-positive values and does NOT claim to cover
+ * every bound the daemon would refuse. The difference is worth stating, because
+ * the two classes fail in different places and only one of them is decidable
+ * here. A negative, `NaN` or `Infinity` renders into the argv as text the
+ * daemon either rejects or turns into a bound nobody asked for, and `0` is the
+ * opposite of a bound (`NanoCPUs` of zero is how a container says "no CPU
+ * limit"), so a host that wrote one of those hears about it during wiring
+ * rather than as a container that never came up.
+ *
+ * The upper bound is not ours to check. Moby's `verifyPlatformContainerResources`
+ * refuses `NanoCPUs` above the DAEMON host's CPU count (`"range of CPUs is from
+ * 0.01 to N.00, as there are only N CPUs available"`), and the same function
+ * deliberately sets no floor of its own on Linux, leaving that to the kernel.
+ * Neither number is knowable from here: the `docker` binary this backend drives
+ * can be pointed at a daemon on another machine (`DOCKER_HOST`), and even
+ * locally `os.cpus().length` is this machine's view rather than the daemon's
+ * own `runtime.NumCPU()`. Refusing on a guess at it would break a host whose
+ * daemon has more cores than the process driving it, which is a worse failure
+ * than the one it would catch — those arrive from the daemon with its own
+ * message, at spawn, where every other daemon-side refusal arrives too.
+ */
+export declare function assertCpuLimitIsRenderable(cpuLimit: number | undefined): void;
+/**
+ * `--tmpfs` flags for the paths that stay writable under `--read-only`.
+ *
+ * See {@link DEFAULT_WRITABLE_ROOTFS_PATHS} for the paths themselves and why
+ * each is there. Returns nothing when the read-only root filesystem is off, and
+ * the two ways a host names paths that cannot be mounted — a contradiction with
+ * `readOnlyRootfs: false`, or a path the layout already mounts — are refusals
+ * rather than a silently shorter list.
+ */
+export declare function renderWritableRootfsArgs(config: DockerHardeningConfig): string[];
+/**
+ * The confinement preamble for one container, in argv order.
+ *
+ * A function rather than a bare constant because `--read-only` is switchable
+ * and the flags that follow it describe what stays writable while it is on:
+ * `readOnlyRootfs: false` removes both the flag and the mounts. That is the only
+ * thing it removes. Everything in {@link HARDENING_ARGS} is applied
+ * unconditionally and no field can turn one of those off, so the argv for
+ * `readOnlyRootfs: false` is the argv this backend produced before any of this
+ * existed PLUS `--ipc private` — those two flags are the whole previous argv,
+ * and `--ipc private` is now unconditional. `--ipc` is not folded under this
+ * switch, because the field names the root filesystem: a host that turned the
+ * read-only rootfs off would be turning IPC isolation off as well, silently,
+ * for a reason the name of the field does not say. A switch has to mean one
+ * thing.
+ */
+export declare function renderHardeningArgs(config: DockerHardeningConfig): string[];
+/**
+ * Everything {@link buildDockerRunArgs} renders, as a value.
+ *
+ * The pieces that come from the daemon or from the host are inputs rather than
+ * lookups: which network the container attaches to, and whether an egress proxy
+ * is listening and on which port. Both are already resolved by the caller, and
+ * reading them here would put a daemon call back inside the function whose
+ * whole point is that it needs none.
+ */
+export interface DockerRunArgvInput {
+    readonly config: DockerBackendInternalConfig;
+    readonly options: SandboxBackendOptions;
+    readonly containerName: string;
+    readonly network: string;
+    readonly hostReachability: 'host-port' | 'container-network';
+    /**
+     * Port the host-side egress proxy listens on, when one is running. Absent
+     * means no proxy, and no proxy environment is passed in — which is not the
+     * same fact as a proxy that was configured and is unreachable.
+     */
+    readonly egressProxyPort?: number;
+}
+/**
+ * The complete `docker run` argv, as a value.
+ *
+ * Extracted for the same reason {@link resolveNetwork} and
+ * {@link egressProxyOptions} were: everything downstream of it needs a running
+ * Docker daemon, so a confinement flag that never reached the argv — or one
+ * that reached it in an order that cancels another — could only be caught by an
+ * operator noticing its effect missing in production. Spawning a fake `docker`
+ * and reading back what it was handed proves what the fake was told and nothing
+ * about the container the daemon would build. Here the whole baseline is one
+ * array, and an edit that drops a flag fails a test rather than a deployment.
+ *
+ * Order matters in exactly two places, and both are asserted by the test that
+ * pins this: the image is the last argument, because everything after it is a
+ * command for the container rather than a flag for docker; and every flag that
+ * takes a value is pushed as two argv entries rather than one string, so no
+ * value is ever re-split by anything downstream.
+ */
+export declare function buildDockerRunArgs(input: DockerRunArgvInput): string[];
 /**
  * Validate and resolve a {@link ContainerSandboxLayout}. Returns a
  * {@link ResolvedContainerSandboxLayout} with every container path

package/dist/backends/docker/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/backends/docker/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EACN,KAAK,sBAAsB,EAE3B,KAAK,8BAA8B,EAkBnC,MAAM,YAAY,CAAA;AAEnB,OAAO,KAAK,EACX,kBAAkB,EAClB,kBAAkB,EAElB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EAEN,KAAK,YAAY,EACjB,KAAK,cAAc,EAEnB,MAAM,gBAAgB,CAAA;AAcvB;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,2BAA2B;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,8BAA8B,CAAA;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAE9B;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAE3B;;;;;;;;;OASG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAE5D;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAE3C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;IAC7C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAA;IAC5C;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,WAAW,GAAG,mBAAmB,CAAA;IAC7D;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAClD;AAOD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,2BAA2B,GAAG,cAAc,CAiBtF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC7B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,YAAY,GAAG,SAAS,EAChC,QAAQ,UAAQ,GACd,MAAM,CAkBR;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAM1F;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAE1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,qBAAqB,EAAE,MAAM,GAAG,OAAO,CAExE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,6BAA6B,CAC5C,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,WAAW,GAAG,mBAAmB,EAC/C,MAAM,EAAE,YAAY,GAAG,SAAS,EAChC,qBAAqB,EAAE,MAAM,GAC3B,IAAI,CAcN;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,IAAI,CAAC,2BAA2B,EAAE,qBAAqB,GAAG,gBAAgB,CAAC,EACnF,MAAM,EAAE,YAAY,GAClB,kBAAkB,CASpB;AAirBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,sBAAsB,GAAG,8BAA8B,CAmI5F;AAkCD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,8BAA8B,GAAG,MAAM,EAAE,CA+BtF;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,8BAA8B,GAAG,MAAM,CAUvF;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,8BAA8B,GAAG,MAAM,CAKxF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/backends/docker/index.ts"],"names":[],"mappings":"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"}