/** Optional trusted-construction Docker-only automatic-executor stop adapter. * Engine RestartPolicy=no and already stopped inventoried recreation controllers * enforce automatic restart/recreation prohibition in this supported boundary. * Complete Docker-only inventory is a trusted authenticated operator assertion; * host/remote supervisors must be absent, manual/root administrators trusted. * Live GETs verify stopped state/policy repeatedly; signatures, SQL locks and * sourceArtifacts provenance assertions alone never prove stop or code hashes. * No stop/start/configuration operations, startup activation or default wiring. * Operating acceptance remains required before this can satisfy S3-06. */ import http from "node:http" import { createHash, createPublicKey, verify } from "node:crypto" import { posix } from "node:path" import { performance } from "node:perf_hooks" import { z } from "zod" import { canonicalBandwidthNodeValue } from "./bandwidth-node-bootstrap.js" import { BandwidthOperatorWriterFenceError, type BandwidthOperatorExternalStopAdapter, type BandwidthOperatorOriginalAuthoritySnapshot, type BandwidthOperatorScope } from "./bandwidth-operator-writer-window.js" import { createBandwidthOperatorWriterComposition, type BandwidthOperatorWriterCompositionDependencies } from "./bandwidth-operator-writer-composition.js" const hash = z.string().regex(/^[a-f0-9]{64}$/) const id = hash, label = z.string().min(1).max(200) const socket = z.string().max(256).refine(value => value.startsWith("/") && posix.normalize(value) === value && !/[\x00-\x20\x7f]/.test(value)) const target = z.object({ containerId: id, imageId: z.string().regex(/^sha256:[a-f0-9]{64}$/), project: label, service: label, role: z.enum(["backend", "updater", "recreation-controller", "unrelated"]), }).strict() const policySchema = z.object({ format: z.literal("mmapp-bandwidth-docker-only-quiescence-v1"), installationId: z.string().uuid(), daemonId: z.string().min(1).max(200), socketPath: socket, // These are explicit signed scope restrictions, not evidence of live state. automaticExecutorScope: z.literal("complete-docker-only-inventory"), outsideAutomaticControllers: z.literal("none-operator-asserted"), administratorBoundary: z.literal("trusted-no-manual-start-create-or-policy-change-during-window"), socketAliases: z.array(socket).min(1).max(16), containers: z.array(target).min(1).max(256), sourceArtifacts: z.array(z.object({ name: label, sha256: hash }).strict()).min(1).max(32), }).strict() export interface DockerBandwidthOperatorStopConfig { socketPath: string daemonId: string /** Exact canonical UTF-8 signed policy, never a path/URL or mutable callback. */ inventoryCanonicalJson: string inventorySignatureBase64url: string inventoryPublicKeyPem: string inventoryPublicKeySha256: string } const sha = (data: string | Buffer) => createHash("sha256").update(data).digest("hex") const refuse = (): never => { throw new BandwidthOperatorWriterFenceError() } const object = (value: unknown): Record => { if (!value || typeof value !== "object" || Array.isArray(value)) return refuse() return value as Record } const array = (value: unknown, max = 256): unknown[] => { if (!Array.isArray(value) || value.length > max) return refuse() return value } function plainScope(raw: Readonly): Readonly { if (!raw || Object.getPrototypeOf(raw) !== Object.prototype || Reflect.ownKeys(raw).length !== Object.keys(raw).length || Object.keys(raw).some(key => key !== "deadlineAt" && key !== "signal") || Object.values(Object.getOwnPropertyDescriptors(raw)).some(value => !("value" in value) || !value.enumerable) || !Number.isSafeInteger(raw.deadlineAt) || raw.signal !== undefined && !(raw.signal instanceof AbortSignal)) return refuse() return Object.freeze({ deadlineAt: raw.deadlineAt, signal: raw.signal }) } /** Trusted construction only; no transport/client escapes this closure. Only * fixed Docker Engine v1.45 GET paths over the pinned Unix socket are issued. * Import and construction perform no Docker I/O. Test via synthetic HTTP mock. */ export function createDockerBandwidthOperatorStopAdapter(raw: DockerBandwidthOperatorStopConfig): BandwidthOperatorExternalStopAdapter { let policy: z.infer, inventoryHash: string try { if (!raw || Object.getPrototypeOf(raw) !== Object.prototype || Reflect.ownKeys(raw).length !== 6 || Object.values(Object.getOwnPropertyDescriptors(raw)).some(value => !("value" in value) || !value.enumerable) || typeof raw.inventoryCanonicalJson !== "string" || Buffer.byteLength(raw.inventoryCanonicalJson) > 131072 || typeof raw.inventoryPublicKeyPem !== "string" || Buffer.byteLength(raw.inventoryPublicKeyPem) > 16384) refuse() const socketPath = socket.parse(raw.socketPath), daemonId = label.parse(raw.daemonId) const bytes = Buffer.from(raw.inventoryCanonicalJson, "utf8") const key = createPublicKey(raw.inventoryPublicKeyPem) if (key.asymmetricKeyType !== "ed25519" || sha(key.export({ type: "spki", format: "der" })) !== hash.parse(raw.inventoryPublicKeySha256) || !/^[A-Za-z0-9_-]{86}$/.test(raw.inventorySignatureBase64url)) refuse() const signature = Buffer.from(raw.inventorySignatureBase64url, "base64url") if (signature.toString("base64url") !== raw.inventorySignatureBase64url || !verify(null, bytes, key, signature)) refuse() policy = policySchema.parse(JSON.parse(raw.inventoryCanonicalJson)) if (canonicalBandwidthNodeValue(policy) !== raw.inventoryCanonicalJson || policy.socketPath !== socketPath || policy.daemonId !== daemonId || !policy.socketAliases.includes(socketPath) || !policy.socketAliases.includes("/var/run/docker.sock") || new Set(policy.socketAliases).size !== policy.socketAliases.length || policy.containers.filter(item => item.role === "backend").length < 1 || new Set(policy.containers.map(item => item.containerId)).size !== policy.containers.length || policy.containers.some((item, index) => index > 0 && item.containerId <= policy.containers[index - 1].containerId) || new Set(policy.sourceArtifacts.map(item => item.name)).size !== policy.sourceArtifacts.length) refuse() inventoryHash = sha(bytes) } catch { return refuse() } // zod parsed a detached copy. Nothing later reads the caller's config/policy. const pinnedSocket = policy.socketPath, pinnedDaemon = policy.daemonId const targets = new Map(policy.containers.map(item => [item.containerId, Object.freeze(item)])) const aliases = Object.freeze([...policy.socketAliases]) const expectedIds = [...targets.keys()] const MAX_BODY = 2 * 1024 * 1024 type Lifetime = { original: BandwidthOperatorOriginalAuthoritySnapshot; proof: string; end: number; deadlineAt: number; originalSignal?: AbortSignal; inputSignal?: AbortSignal; controller: AbortController; stopped: boolean; busy: boolean } function live(state: Lifetime, scope: Readonly) { if (state.stopped || state.originalSignal?.aborted || state.inputSignal?.aborted || scope.signal?.aborted || Date.now() >= state.deadlineAt || Date.now() >= scope.deadlineAt || Date.now() >= state.original.grant.expiresAt || performance.now() >= state.end) refuse() } async function get(path: string, state: Lifetime, scope: Readonly): Promise { live(state, scope) const remaining = Math.min(state.end - performance.now(), state.deadlineAt - Date.now(), scope.deadlineAt - Date.now(), state.original.grant.expiresAt - Date.now()) const result = await new Promise((resolve, reject) => { let done = false, bytes = 0, request: http.ClientRequest | undefined const signals = [...new Set([state.originalSignal, state.inputSignal, scope.signal, state.controller.signal].filter((value): value is AbortSignal => !!value))] const finish = (failure?: unknown, value?: unknown) => { if (done) return done = true; clearTimeout(timer); signals.forEach(signal => signal.removeEventListener("abort", abort)) if (failure) { request?.destroy(); reject(new BandwidthOperatorWriterFenceError()) } else resolve(value) } const abort = () => finish(true) const timer = setTimeout(abort, Math.max(1, Math.ceil(remaining))) signals.forEach(signal => signal.addEventListener("abort", abort, { once: true })) try { live(state, scope) request = http.request({ socketPath: pinnedSocket, path, method: "GET", agent: false, headers: { Accept: "application/json", Connection: "close" }, maxHeaderSize: 16384 }, response => { const chunks: Buffer[] = [] if (response.statusCode !== 200 || response.headers["content-encoding"] && response.headers["content-encoding"] !== "identity" || !/^application\/json(?:\s*;|$)/i.test(String(response.headers["content-type"])) || response.headers["content-length"] !== undefined && (!/^\d+$/.test(String(response.headers["content-length"])) || Number(response.headers["content-length"]) > MAX_BODY)) { response.resume(); finish(true); return } response.on("data", (chunk: Buffer) => { try { live(state, scope); bytes += chunk.length; if (bytes > MAX_BODY) { response.destroy(); finish(true) } else chunks.push(Buffer.from(chunk)) } catch { response.destroy(); finish(true) } }) response.on("aborted", abort); response.on("error", abort) response.on("end", () => { try { live(state, scope) if (!response.complete) return finish(true) finish(undefined, JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)))) } catch { finish(true) } }) }) request.on("error", abort); request.end() } catch { finish(true) } }) live(state, scope); return result } async function daemon(state: Lifetime, scope: Readonly) { const info = object(await get("/v1.45/info", state, scope)) if (info.ID !== pinnedDaemon || object(info.Swarm).LocalNodeState !== "inactive") refuse() } async function inventory(state: Lifetime, scope: Readonly) { const listed = array(await get("/v1.45/containers/json?all=1&size=0", state, scope)).map(value => id.parse(object(value).Id)).sort() if (listed.length !== expectedIds.length || listed.some((value, index) => value !== expectedIds[index])) refuse() } async function inspect(containerId: string, state: Lifetime, scope: Readonly) { const expected = targets.get(containerId)! const data = object(await get(`/v1.45/containers/${containerId}/json`, state, scope)) const config = object(data.Config), labels = object(config.Labels), host = object(data.HostConfig), status = object(data.State) if (data.Id !== containerId || data.Image !== expected.imageId || labels["com.docker.compose.project"] !== expected.project || labels["com.docker.compose.service"] !== expected.service) refuse() // Inspect ALL containers, including unrelated ones. Read-only bind mounts // still grant Docker HTTP writes; parent-directory binds can expose sockets. const mountAccess = array(data.Mounts).map(value => { const mount = object(value) const destination = mount.Destination const canonicalPath = (path: unknown): path is string => typeof path === "string" && path.startsWith("/") && posix.normalize(path) === path && !/[\x00-\x1f\x7f]/.test(path) if (!canonicalPath(destination)) return refuse() // Genuine tmpfs has no host source. Its destination, even docker.sock, // does not create a host Docker socket bind. Unknown/nonempty sources // are not reclassified as tmpfs merely because they look harmless. if (mount.Type === "tmpfs") { if (mount.Source !== undefined && mount.Source !== "") return refuse() return false } if (mount.Type !== "bind" && mount.Type !== "volume" || !canonicalPath(mount.Source)) return refuse() const source = mount.Source return aliases.some(alias => source === alias || alias.startsWith(source.replace(/\/$/, "") + "/")) || /(^|\/)docker\.sock$/.test(source) || /(^|\/)docker\.sock$/.test(destination) }).some(Boolean) const remoteAccess = array(config.Env, 4096).some(value => { if (typeof value !== "string") return refuse() return /^(DOCKER_HOST|DOCKER_CONTEXT|CONTAINER_HOST)=/.test(value) }) if (typeof host.Privileged !== "boolean" || typeof host.PidMode !== "string") refuse() const dangerous = mountAccess || remoteAccess || host.Privileged || host.PidMode === "host" if (expected.role === "unrelated") { if (dangerous) refuse(); return } if (status.Running !== false || status.Restarting !== false || status.Paused !== false || status.Dead !== false || status.Status !== "exited" || status.Pid !== 0 || object(host.RestartPolicy).Name !== "no" || object(host.RestartPolicy).MaximumRetryCount !== 0) refuse() // Existing executor process must have exited no later than the signed // stopped-at assertion. Created containers are deliberately unsupported. const finished = typeof status.FinishedAt === "string" ? Date.parse(status.FinishedAt) : NaN if (!Number.isFinite(finished) || finished <= 0 || finished > state.original.grant.executorsStoppedAt) refuse() } async function scan(state: Lifetime, scope: Readonly) { live(state, scope); await daemon(state, scope); await inventory(state, scope) for (const containerId of expectedIds) await inspect(containerId, state, scope) // Recheck all facts across I/O. Still a sampled observation, never an // atomic prohibition against trusted administrators changing the daemon. for (const containerId of expectedIds) await inspect(containerId, state, scope) await inventory(state, scope); await daemon(state, scope); live(state, scope) } return Object.freeze({ async acquire(original: BandwidthOperatorOriginalAuthoritySnapshot, rawScope: Readonly) { const scope = plainScope(rawScope), wall = Date.now(), mono = performance.now() if (!original || original.grant.executorInventorySha256 !== inventoryHash || original.grant.installationId !== policy.installationId || !Number.isFinite(original.end) || !/^[a-f0-9]{64}$/.test(original.proof)) refuse() // Preserve the SAME original monotonic horizon, cancellation and grant. const state: Lifetime = { original, proof: sha(canonicalBandwidthNodeValue(original.grant)), end: Math.min(original.end, mono + Math.max(0, Math.min(5000, scope.deadlineAt - wall, original.grant.expiresAt - wall))), deadlineAt: scope.deadlineAt, originalSignal: original.signal, inputSignal: scope.signal, controller: new AbortController(), stopped: false, busy: false } try { await scan(state, scope) } catch { state.stopped = true; state.controller.abort(); return refuse() } // Opaque closure-held capability: no evidence booleans/client/HTTP leaks. return Object.freeze({ async assertCurrent(current: BandwidthOperatorOriginalAuthoritySnapshot, requested: Readonly) { try { const checkScope = plainScope(requested) if (state.busy || current !== original || current.proof !== original.proof || sha(canonicalBandwidthNodeValue(current.grant)) !== state.proof) refuse() state.busy = true; await scan(state, checkScope) } catch { state.stopped = true; state.controller.abort(); return refuse() } finally { state.busy = false } }, close() { state.stopped = true; state.controller.abort() }, }) }, }) } export type DockerBandwidthOperatorWriterCompositionDependencies = Omit & { docker: DockerBandwidthOperatorStopConfig } /** Explicit Linux-host operator composition; backend target remains stopped. * Same existing original authority -> external Q -> node source -> registry * path, one held SESSION lease. Construction performs no I/O and installs no * runtime default. register requires separate operational preparation/acceptance. * Trusted dependencies only, never an HTTP/MCP/model-provided config surface. */ export function createDockerBandwidthOperatorWriterComposition(dependencies: DockerBandwidthOperatorWriterCompositionDependencies) { return createBandwidthOperatorWriterComposition({ config: dependencies.config, nodeSource: dependencies.nodeSource, observationSource: dependencies.observationSource, createObservationSource: dependencies.createObservationSource, externalStop: createDockerBandwidthOperatorStopAdapter(dependencies.docker), }) }