Files
MikrotikManager/backend/src/services/bandwidth-operator-docker-stop.ts
T

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),
})
}