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

package/dist/request.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The Docker Engine API transports every capability module is given.
+ *
+ * Each capability lives in its own module and receives its transport as a
+ * parameter rather than reaching for `http` itself. That is not decoration: a
+ * module that opens its own socket can only be tested by intercepting HTTP, and
+ * the things worth testing here — a push that reports failure inside a 200
+ * response body, an eviction that must refuse when it cannot see what is in use —
+ * are decisions about response CONTENT, not about wire mechanics. Injecting the
+ * request function makes each of those a plain function call in a test.
+ *
+ * Three transports rather than one, because the Engine API genuinely has three
+ * shapes: JSON in/JSON out, a tar stream out, and a tar stream in. Forcing the
+ * streaming pair through the JSON transport would mean buffering a whole project
+ * tree in memory, which is the thing bulk transfer exists to avoid.
+ *
+ * @module
+ */
+/**
+ * Issues a Docker Engine API request and returns the parsed JSON response (or
+ * the raw text when the body is not JSON — several endpoints stream JSON lines).
+ *
+ * Implementations MUST reject on a 4xx/5xx status. Several Engine endpoints also
+ * report failure INSIDE a 200 body; see {@link assertNoStreamError}.
+ *
+ * @param path - API path below the version prefix, e.g. `/containers/create`.
+ * @param method - HTTP method; defaults to `GET`.
+ * @param body - Optional JSON request body.
+ * @param timeoutMs - Request timeout.
+ * @param headers - Extra request headers (e.g. `X-Registry-Auth`).
+ * @returns The parsed JSON response, or raw text for non-JSON bodies.
+ */
+export type DockerRequest = (path: string, method?: string, body?: unknown, timeoutMs?: number, headers?: Record<string, string>) => Promise<unknown>;
+/**
+ * Issues a Docker Engine API GET and hands back the response body as a byte
+ * stream, unbuffered.
+ *
+ * @param path - API path below the version prefix.
+ * @param timeoutMs - Request timeout.
+ * @returns The response body as an async byte stream.
+ */
+export type DockerDownload = (path: string, timeoutMs?: number) => Promise<AsyncIterable<Uint8Array>>;
+/**
+ * Issues a Docker Engine API PUT whose request body is a byte stream,
+ * unbuffered and with backpressure.
+ *
+ * @param path - API path below the version prefix.
+ * @param body - The request body as an async byte stream.
+ * @param timeoutMs - Request timeout.
+ */
+export type DockerUpload = (path: string, body: AsyncIterable<Uint8Array>, timeoutMs?: number) => Promise<void>;
+/**
+ * Fail on an error reported inside an otherwise-successful streaming response.
+ *
+ * `/images/create` (pull), `/images/{name}/push` and friends answer `200 OK` and
+ * then stream newline-delimited JSON progress objects. A failure — no such
+ * manifest, denied credentials, a broken layer — arrives as an `error` field in
+ * that stream, LONG after the status line. Treating the 200 as success is how a
+ * fleet ends up believing every host has a template that only one host has.
+ *
+ * @param response - The value returned by a {@link DockerRequest} for a streaming endpoint.
+ * @param operation - Short description used in the thrown message.
+ * @throws {Error} When the stream carried an error object.
+ */
+export declare function assertNoStreamError(response: unknown, operation: string): void;
+//# sourceMappingURL=request.d.ts.map

package/dist/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,EACd,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC7B,OAAO,CAAC,OAAO,CAAC,CAAA;AAErB;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,CAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,KACf,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC,CAAA;AAEvC;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,CACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,EAC/B,SAAS,CAAC,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,CAAA;AAElB;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAsB9E"}

package/dist/request.js

@@ -0,0 +1,56 @@
+/**
+ * The Docker Engine API transports every capability module is given.
+ *
+ * Each capability lives in its own module and receives its transport as a
+ * parameter rather than reaching for `http` itself. That is not decoration: a
+ * module that opens its own socket can only be tested by intercepting HTTP, and
+ * the things worth testing here — a push that reports failure inside a 200
+ * response body, an eviction that must refuse when it cannot see what is in use —
+ * are decisions about response CONTENT, not about wire mechanics. Injecting the
+ * request function makes each of those a plain function call in a test.
+ *
+ * Three transports rather than one, because the Engine API genuinely has three
+ * shapes: JSON in/JSON out, a tar stream out, and a tar stream in. Forcing the
+ * streaming pair through the JSON transport would mean buffering a whole project
+ * tree in memory, which is the thing bulk transfer exists to avoid.
+ *
+ * @module
+ */
+/**
+ * Fail on an error reported inside an otherwise-successful streaming response.
+ *
+ * `/images/create` (pull), `/images/{name}/push` and friends answer `200 OK` and
+ * then stream newline-delimited JSON progress objects. A failure — no such
+ * manifest, denied credentials, a broken layer — arrives as an `error` field in
+ * that stream, LONG after the status line. Treating the 200 as success is how a
+ * fleet ends up believing every host has a template that only one host has.
+ *
+ * @param response - The value returned by a {@link DockerRequest} for a streaming endpoint.
+ * @param operation - Short description used in the thrown message.
+ * @throws {Error} When the stream carried an error object.
+ */
+export function assertNoStreamError(response, operation) {
+    if (typeof response !== 'string') {
+        // A parsed object comes from a single-JSON-document endpoint; those already
+        // surfaced failure through the status code.
+        return;
+    }
+    for (const line of response.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('{'))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch (_error) {
+            // A partial line from a chunked stream is not an error report; the error
+            // object, if there is one, is a complete line of its own.
+            continue;
+        }
+        const message = parsed.errorDetail?.message ?? parsed.error;
+        if (message !== undefined && message !== null && message !== '') {
+            throw new Error(`Docker ${operation} failed: ${String(message)}`);
+        }
+    }
+}

package/dist/templates.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Sandbox templates on Docker — capture a sandbox's filesystem, boot new
+ * sandboxes from it, share it between hosts, and reclaim it on a budget.
+ *
+ * ## Why the capture is not just `commit`
+ *
+ * `POST /commit` snapshots a container's WRITABLE LAYER, and a mounted volume is
+ * not part of it. A sandbox keeps the project on a volume — that is the whole
+ * point of the volume — so committing a sandbox directly produces an image that
+ * builds, tags, boots, and contains no project. Everything succeeds; the template
+ * is empty. So the capture copies the caller-named paths into a throwaway
+ * container that has NO volume, and commits that instead.
+ *
+ * The paths are named by the CALLER (`capturePaths`). They are not discovered,
+ * because the two answers a discovery would produce — "this sandbox has no
+ * project files" and "I looked in the wrong place" — are indistinguishable, and
+ * the wrong one silently ships an empty template that later boots as a working
+ * sandbox with an empty workspace.
+ *
+ * ## The throwaway container is a tenant boundary
+ *
+ * It extracts a TENANT-AUTHORED archive and is then committed into a template
+ * that OTHER tenants boot. So it runs with no network, no capabilities beyond the
+ * three the extraction needs, a memory cap and a process cap — and setuid/setgid
+ * bits are stripped after extraction, so a tenant cannot bake a privilege
+ * escalation into an image somebody else boots. A previous unhardened version of
+ * this step ran on the default bridge, outside every firewall rule, holding
+ * Docker's full default capability set.
+ *
+ * @module
+ */
+import type { CommitTemplateOptions, ListTemplatesOptions, SandboxTemplate } from '@molecule/api-code-sandbox';
+import { type DockerDownload, type DockerRequest, type DockerUpload } from './request.js';
+/** What the template capability needs from the provider. */
+export interface TemplateContext {
+    request: DockerRequest;
+    download: DockerDownload;
+    upload: DockerUpload;
+    /** Image the throwaway capture container runs. It only needs a shell. */
+    baseImage: string;
+    /** Local Docker repository that holds templates. One tag per template id. */
+    repository: string;
+    /** Remote registry host for publish/fetch, or `''` when none is configured. */
+    registry: string;
+    /** Base64 `X-Registry-Auth` value for the remote registry. */
+    registryAuth: string;
+    /** Label namespace for the template's own metadata labels. */
+    labelPrefix: string;
+    warn?: (message: string, meta?: Record<string, unknown>) => void;
+    debug?: (message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Validate a caller-supplied template id.
+ *
+ * REJECTS rather than sanitizes. Sanitizing would map two distinct ids onto one
+ * tag, and the second commit would silently overwrite the first — a project
+ * restoring its own template and receiving somebody else's filesystem.
+ *
+ * @param templateId - The caller's identifier.
+ * @throws {Error} When the id cannot be used as a Docker tag.
+ */
+export declare function assertTemplateId(templateId: string): void;
+/**
+ * Capture a sandbox's filesystem into a reusable template.
+ *
+ * @param ctx - Template context.
+ * @param options - What to capture and what to call it.
+ * @returns The template as it now exists.
+ */
+export declare function commitTemplate(ctx: TemplateContext, options: CommitTemplateOptions): Promise<SandboxTemplate>;
+/**
+ * Read one template by the caller's identifier.
+ *
+ * @param ctx - Template context.
+ * @param templateId - The caller's identifier.
+ * @returns The template, or `null` when no image carries that tag.
+ */
+export declare function getTemplate(ctx: TemplateContext, templateId: string): Promise<SandboxTemplate | null>;
+/**
+ * Enumerate templates so the caller can apply its retention policy.
+ *
+ * @param ctx - Template context.
+ * @param options - Narrowing by id prefix.
+ * @returns Every matching template.
+ */
+export declare function listTemplates(ctx: TemplateContext, options?: ListTemplatesOptions): Promise<SandboxTemplate[]>;
+/**
+ * Delete a template, refusing while anything still boots from it.
+ *
+ * @param ctx - Template context.
+ * @param templateId - The caller's identifier.
+ */
+export declare function removeTemplate(ctx: TemplateContext, templateId: string): Promise<void>;
+/**
+ * Copy a local template into the configured registry.
+ *
+ * @param ctx - Template context.
+ * @param templateId - The caller's identifier.
+ */
+export declare function publishTemplate(ctx: TemplateContext, templateId: string): Promise<void>;
+/**
+ * Pull a template from the configured registry onto this host.
+ *
+ * @param ctx - Template context.
+ * @param templateId - The caller's identifier.
+ * @returns The now-local template, or `null` when the registry does not have it.
+ */
+export declare function fetchTemplate(ctx: TemplateContext, templateId: string): Promise<SandboxTemplate | null>;
+//# sourceMappingURL=templates.d.ts.map

package/dist/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EAChB,MAAM,4BAA4B,CAAA;AAEnC,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAA;AAErB,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,aAAa,CAAA;IACtB,QAAQ,EAAE,cAAc,CAAA;IACxB,MAAM,EAAE,YAAY,CAAA;IACpB,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAA;IACjB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAA;IAClB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAA;IACpB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IAChE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CAClE;AAaD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CASzD;AAiID;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAoF1B;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,eAAe,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAiCjC;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,eAAe,EACpB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,eAAe,EAAE,CAAC,CAmC5B;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAc5F;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB7F;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,eAAe,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CA6BjC"}

package/dist/templates.js

@@ -0,0 +1,381 @@
+/**
+ * Sandbox templates on Docker — capture a sandbox's filesystem, boot new
+ * sandboxes from it, share it between hosts, and reclaim it on a budget.
+ *
+ * ## Why the capture is not just `commit`
+ *
+ * `POST /commit` snapshots a container's WRITABLE LAYER, and a mounted volume is
+ * not part of it. A sandbox keeps the project on a volume — that is the whole
+ * point of the volume — so committing a sandbox directly produces an image that
+ * builds, tags, boots, and contains no project. Everything succeeds; the template
+ * is empty. So the capture copies the caller-named paths into a throwaway
+ * container that has NO volume, and commits that instead.
+ *
+ * The paths are named by the CALLER (`capturePaths`). They are not discovered,
+ * because the two answers a discovery would produce — "this sandbox has no
+ * project files" and "I looked in the wrong place" — are indistinguishable, and
+ * the wrong one silently ships an empty template that later boots as a working
+ * sandbox with an empty workspace.
+ *
+ * ## The throwaway container is a tenant boundary
+ *
+ * It extracts a TENANT-AUTHORED archive and is then committed into a template
+ * that OTHER tenants boot. So it runs with no network, no capabilities beyond the
+ * three the extraction needs, a memory cap and a process cap — and setuid/setgid
+ * bits are stripped after extraction, so a tenant cannot bake a privilege
+ * escalation into an image somebody else boots. A previous unhardened version of
+ * this step ran on the default bridge, outside every firewall rule, holding
+ * Docker's full default capability set.
+ *
+ * @module
+ */
+import { assertNoStreamError, } from './request.js';
+/**
+ * Legal Docker tag component, which is also a legal container-name component.
+ * A template id becomes both, so it must satisfy the stricter of the two.
+ */
+const VALID_TEMPLATE_ID = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,110}$/;
+/** Timeouts sized for operations that move gigabytes rather than metadata. */
+const COMMIT_TIMEOUT_MS = 300_000;
+const TRANSFER_TIMEOUT_MS = 600_000;
+const REGISTRY_TIMEOUT_MS = 300_000;
+/**
+ * Validate a caller-supplied template id.
+ *
+ * REJECTS rather than sanitizes. Sanitizing would map two distinct ids onto one
+ * tag, and the second commit would silently overwrite the first — a project
+ * restoring its own template and receiving somebody else's filesystem.
+ *
+ * @param templateId - The caller's identifier.
+ * @throws {Error} When the id cannot be used as a Docker tag.
+ */
+export function assertTemplateId(templateId) {
+    if (!VALID_TEMPLATE_ID.test(templateId)) {
+        throw new Error(`Invalid template id ${JSON.stringify(templateId.slice(0, 32))}: must match ` +
+            `${String(VALID_TEMPLATE_ID)} so it can be used verbatim as a Docker tag. ` +
+            'Ids are rejected rather than sanitized, because sanitizing would let two ' +
+            'distinct ids collide onto one template.');
+    }
+}
+/**
+ * Absolute, traversal-free path inside a sandbox. Interpolated into a `sh -c`
+ * argument and into a URL query, so both shapes are checked here.
+ *
+ * @param path - Candidate path.
+ * @throws {Error} When the path is not a safe absolute path.
+ */
+function assertCapturePath(path) {
+    if (!/^\/[^\0'"`$\\\n]*$/.test(path) || path.includes('..')) {
+        throw new Error(`Invalid capture path ${JSON.stringify(path.slice(0, 64))}: must be absolute`);
+    }
+}
+/** The provider-native reference for a template id. */
+function templateRef(ctx, templateId) {
+    return `${ctx.repository}:${templateId}`;
+}
+/** The remote reference for a template id, in the configured registry. */
+function remoteRef(ctx, templateId) {
+    return `${ctx.registry}/${ctx.repository}:${templateId}`;
+}
+/**
+ * Require a configured shared store, naming the setting that turns it on.
+ *
+ * A Docker daemon can always talk to a registry, so the capability is present;
+ * what is missing is the address. Throwing distinguishes that from "this
+ * template is not in the shared store", which is what a `null` return would say.
+ *
+ * @param ctx - Template context.
+ * @throws {Error} When no registry is configured.
+ */
+function assertRegistry(ctx) {
+    if (!ctx.registry) {
+        throw new Error('No shared template store is configured for the Docker sandbox provider. ' +
+            'Set `templateRegistry` (or SANDBOX_TEMPLATE_REGISTRY) to a Docker registry ' +
+            'host to publish and fetch templates across hosts.');
+    }
+}
+/** The parent directory an archive of `path` must be extracted into. */
+function parentOf(path) {
+    const trimmed = path.endsWith('/') && path.length > 1 ? path.slice(0, -1) : path;
+    const index = trimmed.lastIndexOf('/');
+    return index <= 0 ? '/' : trimmed.slice(0, index);
+}
+/**
+ * Run a command in a container and fail loudly if it did not run.
+ *
+ * Best-effort would be wrong here: every exec in the capture path is a
+ * correctness step (make the destination exist, strip setuid bits), and a
+ * capture that skipped one produces a template that looks fine.
+ *
+ * @param ctx - Template context.
+ * @param containerId - Container to run in.
+ * @param command - Shell command.
+ */
+async function execInContainer(ctx, containerId, command) {
+    const created = (await ctx.request(`/containers/${containerId}/exec`, 'POST', {
+        Cmd: ['sh', '-c', command],
+        AttachStdout: true,
+        AttachStderr: true,
+    }));
+    await ctx.request(`/exec/${created.Id}/start`, 'POST', { Detach: false, Tty: false });
+    const inspected = (await ctx.request(`/exec/${created.Id}/json`));
+    if (inspected?.ExitCode !== 0) {
+        throw new Error(`Command failed inside capture container (exit ${String(inspected?.ExitCode)}): ${command}`);
+    }
+}
+/** Remove a container by id or name, tolerating one that is already gone. */
+async function removeContainer(ctx, ref) {
+    await ctx.request(`/containers/${ref}?force=true`, 'DELETE').catch((error) => {
+        ctx.debug?.('Capture container removal failed (it may already be gone)', { ref, error });
+    });
+}
+/**
+ * Every image reference currently backing a container, running or not.
+ *
+ * A stopped container still owns its filesystem, so it counts. The fallback on
+ * failure is deliberately `null` — the caller turns that into `inUse: true`,
+ * because a wrong `false` here authorizes deleting the image a live sandbox
+ * boots from.
+ *
+ * @param ctx - Template context.
+ * @returns The set of in-use image refs and ids, or `null` when it could not be read.
+ */
+async function inUseImageRefs(ctx) {
+    try {
+        const containers = (await ctx.request('/containers/json?all=true'));
+        const refs = new Set();
+        for (const container of Array.isArray(containers) ? containers : []) {
+            if (container.Image)
+                refs.add(container.Image);
+            if (container.ImageID)
+                refs.add(container.ImageID.replace(/^sha256:/, ''));
+        }
+        return refs;
+    }
+    catch (error) {
+        ctx.warn?.('Could not list containers to determine template usage — assuming in use', { error });
+        return null;
+    }
+}
+/** Whether `imageId`/`ref` appears in the in-use set. `null` means "assume yes". */
+function isInUse(inUse, ref, imageId) {
+    if (inUse === null)
+        return true;
+    if (inUse.has(ref))
+        return true;
+    const bare = imageId.replace(/^sha256:/, '');
+    for (const used of inUse) {
+        if (used === bare || bare.startsWith(used) || used.startsWith(bare))
+            return true;
+    }
+    return false;
+}
+/**
+ * Capture a sandbox's filesystem into a reusable template.
+ *
+ * @param ctx - Template context.
+ * @param options - What to capture and what to call it.
+ * @returns The template as it now exists.
+ */
+export async function commitTemplate(ctx, options) {
+    assertTemplateId(options.templateId);
+    const capturePaths = options.capturePaths ?? [];
+    for (const path of capturePaths)
+        assertCapturePath(path);
+    const ref = templateRef(ctx, options.templateId);
+    const captureName = `mol-capture-${options.templateId}`;
+    // A previous run that died before its cleanup leaves this name taken, and the
+    // create below would fail on the conflict rather than on anything real.
+    await removeContainer(ctx, captureName);
+    const created = (await ctx.request(`/containers/create?name=${captureName}`, 'POST', {
+        Image: ctx.baseImage,
+        Cmd: ['tail', '-f', '/dev/null'],
+        Labels: {
+            [`${ctx.labelPrefix}.template.id`]: options.templateId,
+            ...(options.label ? { [`${ctx.labelPrefix}.template.label`]: options.label } : {}),
+        },
+        HostConfig: {
+            // It is driven entirely over the Docker socket by this process. It needs
+            // no network, and having one puts it outside the sandbox firewall's
+            // subnet match while it handles tenant bytes.
+            NetworkMode: 'none',
+            AutoRemove: false,
+            RestartPolicy: { Name: '' },
+            CapDrop: ['ALL'],
+            CapAdd: ['CHOWN', 'SETGID', 'SETUID'],
+            SecurityOpt: ['no-new-privileges'],
+            Memory: 2 * 1024 * 1024 * 1024,
+            MemorySwap: 2 * 1024 * 1024 * 1024,
+            PidsLimit: 256,
+        },
+    }));
+    try {
+        await ctx.request(`/containers/${created.Id}/start`, 'POST');
+        for (const path of capturePaths) {
+            const parent = parentOf(path);
+            await execInContainer(ctx, created.Id, `mkdir -p '${parent}'`);
+            // Streamed straight through: a project tree is gigabytes, and buffering it
+            // in this process would trade a slow capture for a dead API.
+            const archive = await ctx.download(`/containers/${options.sandboxId}/archive?path=${encodeURIComponent(path)}`, TRANSFER_TIMEOUT_MS);
+            await ctx.upload(`/containers/${created.Id}/archive?path=${encodeURIComponent(parent)}`, archive, TRANSFER_TIMEOUT_MS);
+            // Strip setuid/setgid from the extracted tree. Docker's archive extraction
+            // honors the mode bits in the archive, and the archive came from a
+            // container the tenant controls — so without this a tenant can plant a
+            // setuid-root binary in an image OTHER tenants boot. Scoped by `-perm` so
+            // it touches only the handful of files that have those bits, not the whole
+            // tree.
+            await execInContainer(ctx, created.Id, `find '${path}' -type f -perm /6000 -exec chmod a-s {} + 2>/dev/null; exit 0`);
+        }
+        const params = new URLSearchParams({
+            container: created.Id,
+            repo: ctx.repository,
+            tag: options.templateId,
+            pause: 'false',
+        });
+        if (options.label)
+            params.set('comment', options.label);
+        await ctx.request(`/commit?${params.toString()}`, 'POST', undefined, COMMIT_TIMEOUT_MS);
+    }
+    finally {
+        await removeContainer(ctx, created.Id);
+    }
+    const template = await getTemplate(ctx, options.templateId);
+    if (!template) {
+        throw new Error(`Template "${options.templateId}" was committed as ${ref} but cannot be read back`);
+    }
+    return template;
+}
+/**
+ * Read one template by the caller's identifier.
+ *
+ * @param ctx - Template context.
+ * @param templateId - The caller's identifier.
+ * @returns The template, or `null` when no image carries that tag.
+ */
+export async function getTemplate(ctx, templateId) {
+    assertTemplateId(templateId);
+    const ref = templateRef(ctx, templateId);
+    let image;
+    try {
+        image = (await ctx.request(`/images/${encodeURIComponent(ref)}/json`));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        // A 404 is the answer "no such template". Anything else is a failure to
+        // look, and reporting it as absence would turn a transient daemon hiccup
+        // into a full cold rebuild on every boot.
+        if (/\b404\b|no such image/i.test(message))
+            return null;
+        throw error;
+    }
+    const inUse = await inUseImageRefs(ctx);
+    const labels = image.Config?.Labels ?? {};
+    return {
+        id: labels[`${ctx.labelPrefix}.template.id`] ?? templateId,
+        ref,
+        createdAt: image.Created ?? '',
+        sizeBytes: typeof image.Size === 'number' ? image.Size : null,
+        ...(labels[`${ctx.labelPrefix}.template.label`]
+            ? { label: labels[`${ctx.labelPrefix}.template.label`] }
+            : {}),
+        inUse: isInUse(inUse, ref, image.Id ?? ''),
+    };
+}
+/**
+ * Enumerate templates so the caller can apply its retention policy.
+ *
+ * @param ctx - Template context.
+ * @param options - Narrowing by id prefix.
+ * @returns Every matching template.
+ */
+export async function listTemplates(ctx, options) {
+    const filters = encodeURIComponent(JSON.stringify({ reference: [`${ctx.repository}:*`] }));
+    // No try/catch: a failed listing must reach the caller. Returning `[]` would
+    // tell a caller whose next step is deletion that nothing is over budget, and
+    // it would believe it.
+    const images = (await ctx.request(`/images/json?filters=${filters}`));
+    const inUse = await inUseImageRefs(ctx);
+    const templates = [];
+    for (const image of Array.isArray(images) ? images : []) {
+        for (const tag of image.RepoTags ?? []) {
+            if (!tag.startsWith(`${ctx.repository}:`))
+                continue;
+            const labels = image.Labels ?? {};
+            const id = labels[`${ctx.labelPrefix}.template.id`] ?? tag.slice(ctx.repository.length + 1);
+            if (options?.idPrefix && !id.startsWith(options.idPrefix))
+                continue;
+            templates.push({
+                id,
+                ref: tag,
+                createdAt: typeof image.Created === 'number' ? new Date(image.Created * 1000).toISOString() : '',
+                sizeBytes: typeof image.Size === 'number' ? image.Size : null,
+                ...(labels[`${ctx.labelPrefix}.template.label`]
+                    ? { label: labels[`${ctx.labelPrefix}.template.label`] }
+                    : {}),
+                inUse: isInUse(inUse, tag, image.Id ?? ''),
+            });
+        }
+    }
+    return templates;
+}
+/**
+ * Delete a template, refusing while anything still boots from it.
+ *
+ * @param ctx - Template context.
+ * @param templateId - The caller's identifier.
+ */
+export async function removeTemplate(ctx, templateId) {
+    const template = await getTemplate(ctx, templateId);
+    // Already gone is a success — callers reconcile, and reconciliation re-runs.
+    if (!template)
+        return;
+    if (template.inUse) {
+        throw new Error(`Refusing to remove template "${templateId}" (${template.ref}): a sandbox is still ` +
+            'backed by it, and removing it would destroy that sandbox.');
+    }
+    // Deliberately no `force`: the daemon independently refuses to remove an image
+    // a container references, which is a second net behind the check above for the
+    // sandbox that was created in between.
+    await ctx.request(`/images/${encodeURIComponent(template.ref)}`, 'DELETE');
+}
+/**
+ * Copy a local template into the configured registry.
+ *
+ * @param ctx - Template context.
+ * @param templateId - The caller's identifier.
+ */
+export async function publishTemplate(ctx, templateId) {
+    assertRegistry(ctx);
+    const template = await getTemplate(ctx, templateId);
+    if (!template)
+        throw new Error(`Cannot publish template "${templateId}": it does not exist locally`);
+    await ctx.request(`/images/${encodeURIComponent(template.ref)}/tag?repo=${encodeURIComponent(`${ctx.registry}/${ctx.repository}`)}&tag=${encodeURIComponent(templateId)}`, 'POST');
+    const pushed = await ctx.request(`/images/${encodeURIComponent(`${ctx.registry}/${ctx.repository}`)}/push?tag=${encodeURIComponent(templateId)}`, 'POST', undefined, REGISTRY_TIMEOUT_MS, { 'X-Registry-Auth': ctx.registryAuth });
+    assertNoStreamError(pushed, `push of ${remoteRef(ctx, templateId)}`);
+}
+/**
+ * Pull a template from the configured registry onto this host.
+ *
+ * @param ctx - Template context.
+ * @param templateId - The caller's identifier.
+ * @returns The now-local template, or `null` when the registry does not have it.
+ */
+export async function fetchTemplate(ctx, templateId) {
+    assertRegistry(ctx);
+    const remote = `${ctx.registry}/${ctx.repository}`;
+    try {
+        const pulled = await ctx.request(`/images/create?fromImage=${encodeURIComponent(remote)}&tag=${encodeURIComponent(templateId)}`, 'POST', undefined, REGISTRY_TIMEOUT_MS, { 'X-Registry-Auth': ctx.registryAuth });
+        assertNoStreamError(pulled, `pull of ${remoteRef(ctx, templateId)}`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        // "The registry does not have it" is an answer, and the caller's next move is
+        // to build the template. Anything else is a failure to look, and must not be
+        // reported as absence.
+        if (/manifest unknown|not found|\b404\b/i.test(message))
+            return null;
+        throw error;
+    }
+    await ctx.request(`/images/${encodeURIComponent(`${remote}:${templateId}`)}/tag?repo=${encodeURIComponent(ctx.repository)}&tag=${encodeURIComponent(templateId)}`, 'POST');
+    return getTemplate(ctx, templateId);
+}

package/dist/types.d.ts

@@ -42,6 +42,29 @@ export interface DockerConfig {
     labelPrefix?: string;
     /** Preview URL template. Use {port} placeholder. */
     previewUrlTemplate?: string;
+    /**
+     * Docker repository holding sandbox TEMPLATES — one tag per template id.
+     * Defaults to `molecule-sandbox-template` (or `SANDBOX_TEMPLATE_REPOSITORY`).
+     *
+     * Deliberately NOT the base image's repository. Sharing one repository between
+     * the base image and every template makes `docker images <repo>` and any
+     * cleanup written against it operate on both, and the only thing standing
+     * between a template sweep and the base image is a tag-prefix convention.
+     */
+    templateRepository?: string;
+    /**
+     * Registry host for sharing templates across hosts, e.g. `registry.example.com`
+     * (or `SANDBOX_TEMPLATE_REGISTRY`). When unset, `publishTemplate`/`fetchTemplate`
+     * throw with an actionable message: the daemon CAN talk to a registry, so the
+     * capability is present and only the address is missing.
+     */
+    templateRegistry?: string;
+    /**
+     * Base64-encoded Docker `X-Registry-Auth` value for {@link DockerConfig.templateRegistry}
+     * (or `SANDBOX_TEMPLATE_REGISTRY_AUTH`). Defaults to an empty credential set,
+     * which is what an anonymous or already-logged-in daemon needs.
+     */
+    templateRegistryAuth?: string;
 }
 /**
  * Container Info interface.
@@ -65,5 +88,11 @@ export interface ProcessEnv {
     DOCKER_HOST?: string;
     /** Docker network sandbox containers attach to (default `molecule-sandbox`, ICC-off). Overridden by `config.network`. [C1-1] */
     SANDBOX_DOCKER_NETWORK?: string;
+    /** Docker repository holding sandbox templates (default `molecule-sandbox-template`). Overridden by `config.templateRepository`. */
+    SANDBOX_TEMPLATE_REPOSITORY?: string;
+    /** Registry host for sharing templates across hosts. Overridden by `config.templateRegistry`. */
+    SANDBOX_TEMPLATE_REGISTRY?: string;
+    /** Base64 `X-Registry-Auth` value for `SANDBOX_TEMPLATE_REGISTRY`. Overridden by `config.templateRegistryAuth`. */
+    SANDBOX_TEMPLATE_REGISTRY_AUTH?: string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sHAAsH;IACtH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0IAA0I;IAC1I,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sCAAsC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oDAAoD;IACpD,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,kHAAkH;IAClH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,wJAAwJ;IACxJ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gIAAgI;IAChI,sBAAsB,CAAC,EAAE,MAAM,CAAA;CAChC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sHAAsH;IACtH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0IAA0I;IAC1I,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sCAAsC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oDAAoD;IACpD,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,kHAAkH;IAClH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,wJAAwJ;IACxJ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gIAAgI;IAChI,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,oIAAoI;IACpI,2BAA2B,CAAC,EAAE,MAAM,CAAA;IACpC,iGAAiG;IACjG,yBAAyB,CAAC,EAAE,MAAM,CAAA;IAClC,mHAAmH;IACnH,8BAA8B,CAAC,EAAE,MAAM,CAAA;CACxC"}