mcp-3d-printer-server 1.2.9 → 1.2.12

package/src/safety/archive.ts

@@ -0,0 +1,181 @@
+import { open } from 'node:fs/promises';
+import { promisify, TextDecoder } from 'node:util';
+import { inflateRaw } from 'node:zlib';
+import JSZip from 'jszip';
+
+// Fixed inspection limits, not caller-overridable printer safety options.
+export const MAX_PRINT_FILE_BYTES = 256 * 1024 * 1024;
+const MAX_ENTRY_BYTES = 256 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 512 * 1024 * 1024;
+const inflate = promisify(inflateRaw);
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+const fail = (message: string): never => { throw new Error(`Print archive safety: ${message}`); };
+const crcTable = Uint32Array.from({ length: 256 }, (_, index) => {
+  let value = index;
+  for (let bit = 0; bit < 8; bit++) value = (value >>> 1) ^ ((value & 1) ? 0xedb88320 : 0);
+  return value >>> 0;
+});
+function crc32(bytes: Buffer): number {
+  let crc = 0xffffffff;
+  for (const byte of bytes) crc = (crc >>> 8) ^ crcTable[(crc ^ byte) & 0xff];
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/** Read no more than the fixed print-artifact limit, even if the file grows. */
+export async function readBoundedPrintFile(filePath: string): Promise<Buffer> {
+  const file = await open(filePath, 'r');
+  try {
+    const stat = await file.stat();
+    if (!stat.isFile()) return fail('print artifact must be a regular file');
+    if (stat.size > MAX_PRINT_FILE_BYTES) return fail('compressed archive or G-code file size exceeds the 256 MiB inspection limit');
+    const bytes = Buffer.alloc(stat.size);
+    let read = 0;
+    while (read < bytes.length) {
+      const result = await file.read(bytes, read, bytes.length - read, read);
+      if (!result.bytesRead) return fail('file changed while being read');
+      read += result.bytesRead;
+    }
+    if ((await file.read(Buffer.alloc(1), 0, 1, read)).bytesRead) return fail('file size changed while being read');
+    return bytes;
+  } finally { await file.close(); }
+}
+
+interface Entry {
+  name: string;
+  rawName: Buffer;
+  flags: number;
+  method: number;
+  crc: number;
+  compressed: number;
+  uncompressed: number;
+  local: number;
+  data?: Buffer;
+}
+function decodeName(raw: Buffer): string {
+  let name: string;
+  try { name = utf8.decode(raw); } catch { return fail('entry name is not valid UTF-8'); }
+  const segments = name.replace(/\/$/, '').split('/');
+  if (!name || /[\\\x00-\x1f]/.test(name) || segments.some(part => !part || part === '.' || part === '..')) {
+    return fail('ambiguous archive entry path');
+  }
+  return name;
+}
+function checkExtra(extra: Buffer, rawName: Buffer, name: string): void {
+  let offset = 0;
+  while (offset < extra.length) {
+    if (offset + 4 > extra.length) return fail('malformed ZIP extra field');
+    const kind = extra.readUInt16LE(offset);
+    const length = extra.readUInt16LE(offset + 2);
+    offset += 4;
+    if (offset + length > extra.length) return fail('malformed ZIP extra field length');
+    if (kind === 0x0001) return fail('ZIP64 archives are unsupported for verified printing');
+    if (kind === 0x7075) {
+      const field = extra.subarray(offset, offset + length);
+      if (length < 5 || field[0] !== 1 || field.readUInt32LE(1) !== crc32(rawName) || decodeName(field.subarray(5)) !== name) {
+        return fail('Unicode path metadata disagrees with the archive entry name');
+      }
+    }
+    offset += length;
+  }
+}
+
+/** Parse every central and local record before decompression. Competing names and
+ * orphan local records could cause the firmware to execute a different plate. */
+function parseEntries(bytes: Buffer): Entry[] {
+  if (bytes.length > MAX_PRINT_FILE_BYTES) return fail('compressed archive size exceeds the 256 MiB inspection limit');
+  let end = -1;
+  for (let i = bytes.length - 22; i >= Math.max(0, bytes.length - 65557); i--) {
+    if (bytes.readUInt32LE(i) === 0x06054b50 && i + 22 + bytes.readUInt16LE(i + 20) === bytes.length) { end = i; break; }
+  }
+  if (end < 0) return fail('missing or malformed ZIP central-directory end record');
+  const count = bytes.readUInt16LE(end + 10);
+  const size = bytes.readUInt32LE(end + 12);
+  const start = bytes.readUInt32LE(end + 16);
+  if (count === 0xffff || size === 0xffffffff || start === 0xffffffff || (end >= 20 && bytes.readUInt32LE(end - 20) === 0x07064b50)) {
+    return fail('ZIP64 archives are unsupported for verified printing');
+  }
+  if (bytes.readUInt16LE(end + 4) || bytes.readUInt16LE(end + 6) || bytes.readUInt16LE(end + 8) !== count) return fail('multi-disk ZIP archives are unsupported');
+  if (start + size !== end) return fail('ambiguous ZIP central-directory extent');
+  const entries: Entry[] = [];
+  const names = new Set<string>();
+  const foldedNames = new Set<string>();
+  let offset = start;
+  let total = 0;
+  for (let i = 0; i < count; i++) {
+    if (offset + 46 > end || bytes.readUInt32LE(offset) !== 0x02014b50) return fail('malformed ZIP central-directory entry');
+    const nameLength = bytes.readUInt16LE(offset + 28);
+    const extraLength = bytes.readUInt16LE(offset + 30);
+    const commentLength = bytes.readUInt16LE(offset + 32);
+    const next = offset + 46 + nameLength + extraLength + commentLength;
+    if (next > end) return fail('truncated ZIP central-directory entry');
+    const rawName = bytes.subarray(offset + 46, offset + 46 + nameLength);
+    const name = decodeName(rawName);
+    if (names.has(name)) return fail(`duplicate archive entry '${name}'`);
+    if (foldedNames.has(name.toLowerCase())) return fail(`case-colliding archive entry '${name}'`);
+    names.add(name); foldedNames.add(name.toLowerCase());
+    const entry: Entry = {
+      name, rawName, flags: bytes.readUInt16LE(offset + 8), method: bytes.readUInt16LE(offset + 10),
+      crc: bytes.readUInt32LE(offset + 16), compressed: bytes.readUInt32LE(offset + 20),
+      uncompressed: bytes.readUInt32LE(offset + 24), local: bytes.readUInt32LE(offset + 42),
+    };
+    if ([entry.compressed, entry.uncompressed, entry.local].includes(0xffffffff)) return fail('ZIP64 archives are unsupported for verified printing');
+    if (bytes.readUInt16LE(offset + 34)) return fail('multi-disk ZIP entries are unsupported');
+    if (entry.flags & ~0x080e || ![0, 8].includes(entry.method)) return fail('encrypted or unsupported ZIP entry encoding');
+    if (entry.uncompressed > MAX_ENTRY_BYTES) return fail(`entry size for '${name}' exceeds the 256 MiB inspection limit`);
+    total += entry.uncompressed;
+    if (total > MAX_TOTAL_BYTES) return fail('total uncompressed archive size exceeds the 512 MiB inspection limit');
+    if (name.endsWith('/') && (entry.compressed || entry.uncompressed)) return fail('directory entry contains hidden file data');
+    checkExtra(bytes.subarray(offset + 46 + nameLength, offset + 46 + nameLength + extraLength), rawName, name);
+    entries.push(entry); offset = next;
+  }
+  if (offset !== end) return fail('unaccounted central-directory entries');
+  let cursor = 0;
+  for (const entry of [...entries].sort((a, b) => a.local - b.local)) {
+    if (entry.local !== cursor) return fail('unreferenced, overlapping, or ambiguous local ZIP entries');
+    if (cursor + 30 > start || bytes.readUInt32LE(cursor) !== 0x04034b50) return fail('malformed local ZIP entry');
+    const nameLength = bytes.readUInt16LE(cursor + 26);
+    const extraLength = bytes.readUInt16LE(cursor + 28);
+    const dataStart = cursor + 30 + nameLength + extraLength;
+    const dataEnd = dataStart + entry.compressed;
+    if (dataEnd > start) return fail('local entry extends into the central directory');
+    if (bytes.readUInt16LE(cursor + 6) !== entry.flags || bytes.readUInt16LE(cursor + 8) !== entry.method || !bytes.subarray(cursor + 30, cursor + 30 + nameLength).equals(entry.rawName)) {
+      return fail('local and central ZIP entry names or encoding disagree');
+    }
+    checkExtra(bytes.subarray(cursor + 30 + nameLength, dataStart), entry.rawName, entry.name);
+    const localFields = [bytes.readUInt32LE(cursor + 14), bytes.readUInt32LE(cursor + 18), bytes.readUInt32LE(cursor + 22)];
+    const expected = [entry.crc, entry.compressed, entry.uncompressed];
+    if (localFields.some((value, i) => value !== expected[i] && (!(entry.flags & 8) || value !== 0))) return fail('local and central ZIP entry sizes or CRC disagree');
+    entry.data = bytes.subarray(dataStart, dataEnd);
+    cursor = dataEnd;
+    if (entry.flags & 8) {
+      if (cursor + 12 > start) return fail('missing ZIP data descriptor');
+      if (bytes.readUInt32LE(cursor) === 0x08074b50) cursor += 4;
+      if (cursor + 12 > start || expected.some((value, i) => bytes.readUInt32LE(cursor + i * 4) !== value)) return fail('ZIP data descriptor disagrees with central entry');
+      cursor += 12;
+    }
+  }
+  if (cursor !== start) return fail('unreferenced local ZIP data before the central directory');
+  return entries;
+}
+
+/** Bounded native inflation prevents false size fields from making JSZip allocate
+ * unbounded output. Populate JSZip only with the verified, uniquely named bytes. */
+export async function loadSafe3mfArchive(bytes: Buffer): Promise<JSZip> {
+  const entries = parseEntries(bytes);
+  const zip = new JSZip();
+  for (const entry of entries) {
+    let data: Buffer;
+    try {
+      data = entry.method === 0 ? entry.data! : await inflate(entry.data!, { maxOutputLength: Math.max(1, entry.uncompressed) });
+    } catch { return fail(`entry inflation exceeds its declared size or is corrupt: '${entry.name}'`); }
+    if (data.length !== entry.uncompressed) return fail(`uncompressed entry size mismatch for '${entry.name}'`);
+    if (crc32(data) !== entry.crc) return fail(`entry CRC mismatch for '${entry.name}'`);
+    zip.file(entry.name, data, { dir: entry.name.endsWith('/'), createFolders: false });
+  }
+  return zip;
+}
+
+export async function readSafe3mfArchive(filePath: string): Promise<{ bytes: Buffer; zip: JSZip }> {
+  const bytes = await readBoundedPrintFile(filePath);
+  return { bytes, zip: await loadSafe3mfArchive(bytes) };
+}

package/src/safety/artifact.ts

@@ -0,0 +1,58 @@
+import fs from "node:fs/promises";
+import { rmSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { randomUUID } from "node:crypto";
+
+// Serialise mutations from this server for a printer. Stop/cancel remain available.
+const operations = new Map<string, Promise<unknown>>();
+const generations = new Map<string, number>();
+export function cancelPendingPrinterOperations(_host: string, serial: string): void {
+  generations.set(serial, (generations.get(serial) ?? 0) + 1);
+}
+const retained = new Set<string>();
+process.once("exit", () => {
+  for (const directory of retained) {
+    try { rmSync(directory, { recursive: true, force: true }); } catch { /* OS temp cleanup remains available. */ }
+  }
+});
+export async function withPrinterOperation<T>(_host: string, serial: string, operation: (assertActive: () => void) => Promise<T>): Promise<T> {
+  const key = serial;
+  const generation = generations.get(key) ?? 0;
+  const assertActive = () => {
+    if ((generations.get(key) ?? 0) !== generation) throw new Error("Pending printer operation cancelled by stop or heater-off request.");
+  };
+  const previous = operations.get(key) ?? Promise.resolve();
+  const next = previous.catch(() => undefined).then(() => { assertActive(); return operation(assertActive); });
+  operations.set(key, next);
+  try { return await next; }
+  finally { if (operations.get(key) === next) operations.delete(key); }
+}
+
+/** Inspect and send a private copy, so changes to the user's source cannot change the job. */
+export async function withPrintSnapshot<T>(source: string, operation: (snapshot: string, retainForDispatchedUpload: () => void) => Promise<T>): Promise<T> {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bambu-print-"));
+  const snapshot = path.join(directory, path.basename(source));
+  let retainUntilExit = false;
+  try {
+    await fs.copyFile(source, snapshot);
+    await fs.chmod(snapshot, 0o400);
+    return await operation(snapshot, () => { retainUntilExit = true; });
+  } finally {
+    // Native bridge APIs may return before their asynchronous upload completes.
+    if (retainUntilExit) retained.add(directory);
+    else await fs.rm(directory, { recursive: true, force: true });
+  }
+}
+
+export function uniquePrintName(filename: string): string {
+  return `checked-${randomUUID()}-${path.basename(filename)}`;
+}
+
+export function normalizedRemotePath(filename: string): string {
+  const normalized = filename.replace(/^\/+/, "");
+  if (!normalized || normalized.includes("\\") || normalized.split("/").some(part => !part || part === "." || part === "..") || /[\r\n\0]/.test(normalized)) {
+    throw new Error("Printer filename must be a relative path without traversal or control characters.");
+  }
+  return normalized.includes("/") ? normalized : `cache/${normalized}`;
+}

package/src/safety/confirmation.ts

@@ -0,0 +1,56 @@
+/** Human confirmation for physical printer mutations (print start, positive heating). */
+export type ConfirmHardware = (message: string) => Promise<boolean>;
+export type ConfirmationScope = "bambu" | "generic";
+
+/**
+ * Ordinary print/heat prompts are on by default. Only an explicit "0" opts out.
+ * PRINT_REQUIRE_CONFIRMATION applies to every printer type; the older
+ * BAMBU_REQUIRE_CONFIRMATION applies to Bambu printers only. If any variable
+ * relevant to the scope is set to another value, confirmation stays required.
+ */
+export function confirmationOptOut(scope: ConfirmationScope): boolean {
+  const names = scope === "bambu"
+    ? ["BAMBU_REQUIRE_CONFIRMATION", "PRINT_REQUIRE_CONFIRMATION"]
+    : ["PRINT_REQUIRE_CONFIRMATION"];
+  const values = names
+    .map((name) => process.env[name]?.trim())
+    .filter((value): value is string => value !== undefined && value !== "");
+  return values.length > 0 && values.every((value) => value === "0");
+}
+
+/**
+ * How long a human has to answer a confirmation prompt. The MCP SDK's default
+ * request timeout (60 s) is too short for someone walking to the printer.
+ */
+export function confirmationTimeoutMs(): number {
+  const raw = process.env.PRINT_CONFIRMATION_TIMEOUT_MS?.trim();
+  const value = raw ? Number(raw) : 600_000;
+  return Number.isInteger(value) && value >= 1_000 && value <= 3_600_000 ? value : 600_000;
+}
+
+export function confirmationTimedOut(timeoutMs: number): string {
+  const minutes = timeoutMs / 60_000;
+  return `No confirmation was received within ${minutes >= 1 ? `${Number(minutes.toFixed(1))} minute(s)` : `${timeoutMs / 1000} seconds`}; ` +
+    "nothing was sent to the printer. Ask again when you are at the printer, or raise PRINT_CONFIRMATION_TIMEOUT_MS.";
+}
+
+export const CONFIRMATION_UNAVAILABLE =
+  "Human hardware confirmation requires an MCP client with elicitation support. For deliberately headless operation, " +
+  "PRINT_REQUIRE_CONFIRMATION=0 (or BAMBU_REQUIRE_CONFIRMATION=0 for Bambu printers) disables ordinary print/heat prompts; " +
+  "finished-bed clearance still requires elicitation. No command was sent.";
+
+/**
+ * physicalCheck marks confirmations that software cannot replace (for example a
+ * previous part left on the bed). Those are required even when prompts are opted out.
+ */
+export async function requireHumanConfirmation(
+  confirm: ConfirmHardware | undefined,
+  message: string,
+  scope: ConfirmationScope,
+  physicalCheck = false
+): Promise<void> {
+  if (!physicalCheck && confirmationOptOut(scope)) return;
+  if (!confirm || !(await confirm(message))) {
+    throw new Error("Hardware safety confirmation was declined or unavailable. Use an MCP client with elicitation support. No command was sent.");
+  }
+}

package/src/safety/expected-peaks.ts

@@ -0,0 +1,47 @@
+export interface ExpectedPeakTemperatures {
+  /** Expected highest positive nozzle target (S and R forms, every tool). */
+  nozzle?: number;
+  /** Expected highest positive bed target (S and R forms). */
+  bed?: number;
+}
+
+/** Caller-declared options for guarded print and heating mutations. */
+export interface PrintSafetyOptions {
+  /** Bambu printer model (validated against the file and the live printer). */
+  bambuModel?: string;
+  /** Declared material for positive nozzle heating or G-code without slicer material metadata. */
+  material?: string;
+  /** Installed nozzle diameter for Bambu manual nozzle heating. */
+  nozzleDiameter?: number;
+  /** process_and_print_stl expectations; any mismatch refuses before upload. */
+  expectedPeaks?: ExpectedPeakTemperatures;
+}
+
+/** Validate caller expectations before any network use. */
+export function validateExpectedPeaks(expected: ExpectedPeakTemperatures | undefined): void {
+  if (!expected) return;
+  for (const component of ["nozzle", "bed"] as const) {
+    const value = expected[component];
+    if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value) || value < 0)) {
+      throw new Error(`Expected ${component} temperature must be a finite nonnegative number.`);
+    }
+  }
+}
+
+/** A requested expected peak must equal the inspected peak; a mismatch stops before upload. */
+export function assertExpectedPeaks(
+  expected: ExpectedPeakTemperatures | undefined,
+  actual: { nozzle: number; bed: number }
+): void {
+  validateExpectedPeaks(expected);
+  if (!expected) return;
+  for (const component of ["nozzle", "bed"] as const) {
+    const value = expected[component];
+    if (value !== undefined && actual[component] !== value) {
+      throw new Error(
+        `Print safety: the job's highest ${component} target is ${actual[component]} C (S and R forms, every tool), ` +
+        `but ${value} C was expected. Re-slice or correct the expected temperature. Nothing was uploaded or started.`
+      );
+    }
+  }
+}