251 lines
17 KiB
TypeScript
251 lines
17 KiB
TypeScript
/** 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<string, unknown> => {
|
|
if (!value || typeof value !== "object" || Array.isArray(value)) return refuse()
|
|
return value as Record<string, unknown>
|
|
}
|
|
const array = (value: unknown, max = 256): unknown[] => {
|
|
if (!Array.isArray(value) || value.length > max) return refuse()
|
|
return value
|
|
}
|
|
function plainScope(raw: Readonly<BandwidthOperatorScope>): Readonly<BandwidthOperatorScope> {
|
|
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<typeof policySchema>, 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<BandwidthOperatorScope>) {
|
|
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<BandwidthOperatorScope>): Promise<unknown> {
|
|
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<unknown>((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<BandwidthOperatorScope>) {
|
|
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<BandwidthOperatorScope>) {
|
|
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<BandwidthOperatorScope>) {
|
|
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<BandwidthOperatorScope>) {
|
|
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<BandwidthOperatorScope>) {
|
|
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<BandwidthOperatorScope>) {
|
|
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<BandwidthOperatorWriterCompositionDependencies, "externalStop"> & {
|
|
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),
|
|
})
|
|
}
|