@molecule/api-code-sandbox-docker 1.1.0 → 1.1.2

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-08-05T12:53:11.363Z
+Generated: 2026-09-18T06:33:40.632Z
 -->
 
 # @molecule/api-code-sandbox-docker
@@ -236,7 +236,7 @@ export function setupCodeSandboxDocker(): void {
 Peer dependencies:
 
 - `@molecule/api-bond` ^1.0.1
-- `@molecule/api-code-sandbox` ^1.0.1
+- `@molecule/api-code-sandbox` ^1.2.0
 - `@molecule/api-i18n` ^1.0.1
 
 ### Runtime Dependencies
@@ -260,7 +260,13 @@ on the host. The daemon is reached over a unix socket by default
 remote or rootless daemon can be selected with `config.host`/`config.port` or a
 `DOCKER_HOST` (`tcp://host:port` or `unix:///path`). Only PLAIN (unencrypted)
 TCP is supported — front a TLS-protected daemon (2376) with a local socket
-proxy. The provider never pulls images, so `create()` fails with a no-such-image
+proxy. When the plain-TCP endpoint comes from the ambient `DOCKER_HOST` env
+(not explicit config) and `NODE_ENV=production`, the provider REFUSES to
+connect — exec payloads would cross the network unencrypted — unless
+`MOL_DOCKER_ALLOW_PLAIN_TCP=1` is set, which is honored with a loud warning.
+Caller-supplied container ids are shape-validated (`[A-Za-z0-9][A-Za-z0-9_.:-]*`,
+so Docker hex ids, names, and fly-style `app:machine` ids pass) before they are
+interpolated into Docker API paths. The provider never pulls images, so `create()` fails with a no-such-image
 error if the base image (default `node:22-slim`, or `config.baseImage`) is
 absent. The isolated sandbox network is auto-created on first use; it is NOT a
 prerequisite.

package/dist/index.d.ts

@@ -17,7 +17,13 @@
  * remote or rootless daemon can be selected with `config.host`/`config.port` or a
  * `DOCKER_HOST` (`tcp://host:port` or `unix:///path`). Only PLAIN (unencrypted)
  * TCP is supported — front a TLS-protected daemon (2376) with a local socket
- * proxy. The provider never pulls images, so `create()` fails with a no-such-image
+ * proxy. When the plain-TCP endpoint comes from the ambient `DOCKER_HOST` env
+ * (not explicit config) and `NODE_ENV=production`, the provider REFUSES to
+ * connect — exec payloads would cross the network unencrypted — unless
+ * `MOL_DOCKER_ALLOW_PLAIN_TCP=1` is set, which is honored with a loud warning.
+ * Caller-supplied container ids are shape-validated (`[A-Za-z0-9][A-Za-z0-9_.:-]*`,
+ * so Docker hex ids, names, and fly-style `app:machine` ids pass) before they are
+ * interpolated into Docker API paths. The provider never pulls images, so `create()` fails with a no-such-image
  * error if the base image (default `node:22-slim`, or `config.baseImage`) is
  * absent. The isolated sandbox network is auto-created on first use; it is NOT a
  * prerequisite.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAE1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAMjE;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,eAUrB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAE1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAMjE;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,eAUrB,CAAA"}

package/dist/index.js

@@ -17,7 +17,13 @@
  * remote or rootless daemon can be selected with `config.host`/`config.port` or a
  * `DOCKER_HOST` (`tcp://host:port` or `unix:///path`). Only PLAIN (unencrypted)
  * TCP is supported — front a TLS-protected daemon (2376) with a local socket
- * proxy. The provider never pulls images, so `create()` fails with a no-such-image
+ * proxy. When the plain-TCP endpoint comes from the ambient `DOCKER_HOST` env
+ * (not explicit config) and `NODE_ENV=production`, the provider REFUSES to
+ * connect — exec payloads would cross the network unencrypted — unless
+ * `MOL_DOCKER_ALLOW_PLAIN_TCP=1` is set, which is honored with a loud warning.
+ * Caller-supplied container ids are shape-validated (`[A-Za-z0-9][A-Za-z0-9_.:-]*`,
+ * so Docker hex ids, names, and fly-style `app:machine` ids pass) before they are
+ * interpolated into Docker API paths. The provider never pulls images, so `create()` fails with a no-such-image
  * error if the base image (default `node:22-slim`, or `config.baseImage`) is
  * absent. The isolated sandbox network is auto-created on first use; it is NOT a
  * prerequisite.

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,KAAK,EAcV,eAAe,EAOhB,MAAM,4BAA4B,CAAA;AAoBnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AA6J9C;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAQ9D;AAkCD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,EAAE;IACJ,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACjC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IACrC,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAC1D,GACA,OAAO,CAAC,CAAC,CAAC,CA2BZ;AA21CD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,eAAe,CAErE"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,KAAK,EAcV,eAAe,EAOhB,MAAM,4BAA4B,CAAA;AAoBnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AA4K9C;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAQ9D;AAkCD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,EAAE;IACJ,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACjC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IACrC,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAC1D,GACA,OAAO,CAAC,CAAC,CAAC,CA2BZ;AA07CD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,eAAe,CAErE"}

package/dist/provider.js

@@ -86,20 +86,32 @@ function parseDockerHost(value) {
  * 2. `config.socketPath` → that unix socket;
  * 3. `DOCKER_HOST` env (`tcp://` or `unix://`, the docker-client convention);
  * 4. `DOCKER_SOCKET_PATH` env, else `/var/run/docker.sock` (the default transport).
+ *
+ * The result also reports whether the endpoint came from the ambient
+ * `DOCKER_HOST` env (vs. explicit code config) — the production plain-TCP
+ * guard treats those differently; see {@link DockerSandboxProvider.ensureEndpointSafety}.
+ *
  * @param config - the provider configuration.
- * @returns the resolved endpoint to spread into every Docker API request.
+ * @returns the resolved endpoint plus its source, to spread into every Docker
+ *   API request.
  */
 function resolveDockerEndpoint(config) {
     if (config.host !== undefined || config.port !== undefined) {
-        return { host: config.host ?? '127.0.0.1', port: config.port ?? DEFAULT_DOCKER_TCP_PORT };
+        return {
+            endpoint: { host: config.host ?? '127.0.0.1', port: config.port ?? DEFAULT_DOCKER_TCP_PORT },
+            fromDockerHostEnv: false,
+        };
     }
     if (config.socketPath !== undefined) {
-        return { socketPath: config.socketPath };
+        return { endpoint: { socketPath: config.socketPath }, fromDockerHostEnv: false };
     }
     const fromEnv = parseDockerHost(process.env.DOCKER_HOST);
     if (fromEnv)
-        return fromEnv;
-    return { socketPath: process.env.DOCKER_SOCKET_PATH ?? '/var/run/docker.sock' };
+        return { endpoint: fromEnv, fromDockerHostEnv: true };
+    return {
+        endpoint: { socketPath: process.env.DOCKER_SOCKET_PATH ?? '/var/run/docker.sock' },
+        fromDockerHostEnv: false,
+    };
 }
 /**
  * Parses Docker's multiplexed binary stream from a raw socket.
@@ -300,8 +312,16 @@ class DockerSandboxProvider {
      * providers (and two tests) do not inherit each other's verdict.
      */
     checkpoints = { supported: true };
+    /** Resolved daemon endpoint source: ambient `DOCKER_HOST` env vs explicit config. */
+    endpointFromDockerHostEnv;
+    /** {@link ensureEndpointSafety} runs once per provider instance (successful checks only). */
+    endpointSafetyChecked = false;
+    /** Whether the plain-TCP override warning has fired (once per provider). */
+    plainTcpOverrideWarned = false;
     constructor(config = {}) {
-        this.endpoint = resolveDockerEndpoint(config);
+        const resolved = resolveDockerEndpoint(config);
+        this.endpoint = resolved.endpoint;
+        this.endpointFromDockerHostEnv = resolved.fromDockerHostEnv;
         this.baseImage = config.baseImage ?? DEFAULT_IMAGE;
         this.labelPrefix = config.labelPrefix ?? LABEL_PREFIX;
         this.previewUrlTemplate = config.previewUrlTemplate ?? 'http://localhost:{port}';
@@ -569,6 +589,9 @@ class DockerSandboxProvider {
      */
     async get(id) {
         try {
+            // Validate before interpolation into `/containers/${id}/json` — an
+            // id carrying path structure could retarget the request.
+            this.assertContainerId(id);
             const info = (await this.dockerApi(`/containers/${id}/json`));
             const projectId = info.Config.Labels[`${this.labelPrefix}.projectId`] ?? '';
             // Derive the real status from Docker's container state rather than
@@ -601,6 +624,8 @@ class DockerSandboxProvider {
      * @param id - The Docker container ID to destroy.
      */
     async destroy(id) {
+        // Validate before interpolation into `/containers/${id}...` paths.
+        this.assertContainerId(id);
         // Read volume name from container labels before removing
         let volumeName;
         try {
@@ -641,6 +666,9 @@ class DockerSandboxProvider {
      * @returns A `Sandbox` with lifecycle and file system methods bound to the container.
      */
     buildSandbox(containerId, _projectId, initialStatus = 'stopped') {
+        // Every method on the returned Sandbox interpolates containerId into
+        // Docker API paths (start/stop/exec) — validate once, here.
+        this.assertContainerId(containerId);
         // eslint-disable-next-line @typescript-eslint/no-this-alias
         const provider = this;
         return {
@@ -1189,7 +1217,79 @@ class DockerSandboxProvider {
      *   `X-Registry-Auth`, which the daemon requires even for anonymous pulls.
      * @returns The parsed JSON response, or raw text for non-JSON responses.
      */
+    /**
+     * Production guard for ambient plain-TCP daemon endpoints (DOCKER_HOST).
+     *
+     * A `tcp://` Docker endpoint speaks PLAIN HTTP: every API request —
+     * including exec payloads (arbitrary commands + file contents) and image
+     * operations — crosses the network unencrypted and unauthenticated.
+     * Reaching such a daemon because an ambient `DOCKER_HOST` env happens to
+     * be set is not a choice this library gets to make silently in production:
+     * it refuses unless the operator explicitly accepts the risk via
+     * `MOL_DOCKER_ALLOW_PLAIN_TCP=1` (which is honored with a loud warning).
+     *
+     * Explicit `config.host`/`config.port` is deliberately NOT guarded — that
+     * is a code-level decision by the embedding application, and dev/CI setups
+     * rely on it. Runs lazily (first API call) rather than in the constructor,
+     * matching the provider's env-reads-at-call-time convention.
+     */
+    ensureEndpointSafety() {
+        if (this.endpointSafetyChecked)
+            return;
+        if (!this.endpointFromDockerHostEnv || !('host' in this.endpoint)) {
+            this.endpointSafetyChecked = true;
+            return;
+        }
+        if (process.env.NODE_ENV !== 'production') {
+            this.endpointSafetyChecked = true;
+            return;
+        }
+        const override = process.env.MOL_DOCKER_ALLOW_PLAIN_TCP;
+        if (override === '1' || override === 'true') {
+            if (!this.plainTcpOverrideWarned) {
+                this.plainTcpOverrideWarned = true;
+                logger.warn('DOCKER_HOST selects a PLAIN-TCP Docker endpoint while NODE_ENV=production — ' +
+                    'container control traffic (incl. exec payloads) crosses the network unencrypted. ' +
+                    'Accepted only because MOL_DOCKER_ALLOW_PLAIN_TCP is set; prefer a unix socket ' +
+                    'or a TLS-terminating proxy.');
+            }
+            this.endpointSafetyChecked = true;
+            return;
+        }
+        // Refuse WITHOUT memoizing: an earlier refusal can land inside a
+        // best-effort try/catch (e.g. network ensure) and be swallowed — every
+        // subsequent call must keep refusing until the configuration changes.
+        throw new Error('DOCKER_HOST selects a plain-TCP (unencrypted, unauthenticated) Docker endpoint and ' +
+            'NODE_ENV=production — refusing. Set MOL_DOCKER_ALLOW_PLAIN_TCP=1 to explicitly accept ' +
+            'the risk, or point the provider at a unix socket / TLS-terminating proxy.');
+    }
+    /**
+     * Shape a caller-supplied container id must have before it is interpolated
+     * into a Docker API path. Docker's own ids are 64-char hex and container
+     * names match `[a-zA-Z0-9][a-zA-Z0-9_.-]*`; the E2B-style provider uses
+     * `app:machine` ids, so `:` is allowed too. Anything carrying URL/path
+     * structure (`/`, `?`, `#`), percent-encoding, or whitespace is rejected —
+     * interpolated raw, such a value could retarget the request path (e.g.
+     * `../exec` or `?force=true` on a different resource).
+     */
+    static CONTAINER_ID_SHAPE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+    /**
+     * Validates a container id before any Docker API path interpolation.
+     * @param id - the caller-supplied container id.
+     * @returns the validated id, unchanged.
+     * @throws {Error} when the id does not match {@link DockerSandboxProvider.CONTAINER_ID_SHAPE}.
+     */
+    assertContainerId(id) {
+        if (!DockerSandboxProvider.CONTAINER_ID_SHAPE.test(id)) {
+            throw new Error(`Invalid sandbox container id: ${JSON.stringify(id)}`);
+        }
+        return id;
+    }
+    /**
+     * Performs a JSON Docker Engine API request against the resolved endpoint.
+     */
     async dockerApi(path, method = 'GET', body, timeoutMs = 30_000, headers) {
+        this.ensureEndpointSafety();
         return new Promise((resolve, reject) => {
             const opts = {
                 ...this.endpoint,
@@ -1328,6 +1428,7 @@ class DockerSandboxProvider {
      * @returns The raw response buffer.
      */
     async dockerApiRaw(path, method = 'GET', body) {
+        this.ensureEndpointSafety();
         return new Promise((resolve, reject) => {
             const opts = {
                 ...this.endpoint,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-code-sandbox-docker",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Docker-based code sandbox container provider",
   "type": "module",
   "main": "dist/index.js",
@@ -29,11 +29,11 @@
   ],
   "license": "Apache-2.0",
   "devDependencies": {
-    "@molecule/api-bond": "1.0.1",
-    "@molecule/api-code-sandbox": "1.2.0",
+    "@molecule/api-bond": "1.0.2",
+    "@molecule/api-code-sandbox": "1.2.1",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
   "peerDependencies": {
     "@molecule/api-bond": "^1.0.1",
@@ -50,7 +50,7 @@
     "url": "https://github.com/molecule-dev/molecule.git",
     "directory": "packages/api/bonds/code-sandbox/docker"
   },
-  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/api/bonds/code-sandbox/docker",
+  "homepage": "https://www.molecule.dev/packages/api-code-sandbox-docker",
   "bugs": "https://github.com/molecule-dev/molecule/issues",
   "publishConfig": {
     "access": "public"