c64bridge 1.0.5 → 1.0.7

package/dist/vice/mockServer.js

@@ -40,10 +40,16 @@ export class ViceMockServer {
         this.registerMetadata = buildDefaultRegisterMetadata();
         this.registerValues = new Map();
         this.resources = new Map();
+        /** Output lines of VICE's I/O simulation joyport device per port (0 = port 1). */
+        this.joyportOutput = [0, 0];
         this.sockets = new Set();
+        /** Images attached with autostart, and drive CPU resets, as observed by tests. */
+        this.autostarts = [];
+        this.driveResets = [];
         this.host = options?.host ?? "127.0.0.1";
         this.requestedPort = options?.port;
         this.resetState();
+        this.resetResources();
     }
     async start() {
         if (this.server)
@@ -114,9 +120,26 @@ export class ViceMockServer {
         switch (cmd) {
             case 0x85: // info
                 return buildResponse(cmd, reqId);
-            case 0xCC: // reset
-                this.resetState();
+            case 0xCC: { // reset: types 8-11 reset only that drive's CPU
+                const type = body[0] ?? 0;
+                if (type >= 8 && type <= 11) {
+                    this.driveResets.push(type);
+                }
+                else {
+                    this.resetState();
+                }
+                return buildResponse(cmd, reqId);
+            }
+            case 0xDD: { // autostart: power-cycles, attaches the image to drive 8 and loads (run=1 also runs)
+                const nameLength = body[3] ?? 0;
+                this.autostarts.push({
+                    run: body[0] === 1,
+                    fileIndex: body.readUInt16LE(1),
+                    filename: body.subarray(4, 4 + nameLength).toString("utf8"),
+                });
+                this.renderAutoload(body[0] === 1);
                 return buildResponse(cmd, reqId);
+            }
             case 0x11: { // checkpoint get
                 const id = body.readUInt32LE(0);
                 const checkpoint = this.checkpoints.get(id);
@@ -185,13 +208,17 @@ export class ViceMockServer {
             case 0x01: { // mem get
                 const start = body.readUInt16LE(1);
                 const end = body.readUInt16LE(3);
-                const length = Math.max(0, end - start + 1);
+                if (start > end) {
+                    return buildResponse(cmd, reqId, Buffer.alloc(0), 0x81); // VICE rejects start > end with INVALID_PARAMETER.
+                }
+                const length = end - start + 1;
                 const payload = Buffer.alloc(2 + length);
                 payload.writeUInt16LE(length & 0xffff, 0); // Like VICE: a full 64 KB read reports ML = 0.
                 for (let i = 0; i < length; i += 1) {
                     payload[2 + i] = this.memory[(start + i) & 0xffff];
                 }
                 this.applyHeartbeatOverlay(start, length, payload);
+                this.applyJoyportOverlay(start, length, payload);
                 return buildResponse(cmd, reqId, payload);
             }
             case 0x02: { // mem set
@@ -246,7 +273,7 @@ export class ViceMockServer {
                 const name = body.subarray(1, 1 + nameLen).toString("utf8");
                 const value = this.resources.get(name);
                 if (value === undefined) {
-                    return buildResponse(cmd, reqId, Buffer.from([0, 0]));
+                    return buildResponse(cmd, reqId, Buffer.alloc(0), 0x01); // VICE: OBJECT_MISSING for an unknown resource.
                 }
                 if (typeof value === "number") {
                     const buffer = Buffer.alloc(2 + 4);
@@ -266,12 +293,20 @@ export class ViceMockServer {
                 const isNumber = body[0] === 1;
                 const nameLen = body[1] ?? 0;
                 const name = body.subarray(2, 2 + nameLen).toString("utf8");
+                if (!this.resources.has(name)) {
+                    // VICE: an unknown integer resource fails resources_set (CMD_FAILURE); an unknown string one is OBJECT_MISSING.
+                    return buildResponse(cmd, reqId, Buffer.alloc(0), isNumber ? 0x8f : 0x01);
+                }
                 if (isNumber) {
                     const valueLen = body[2 + nameLen] ?? 0;
                     const valueBytes = body.subarray(3 + nameLen, 3 + nameLen + valueLen);
                     const padded = Buffer.alloc(4);
                     valueBytes.copy(padded, 0, 0, Math.min(4, valueBytes.length));
                     const value = padded.readInt32LE(0);
+                    // VICE rejects joyport device ids it does not have (JOYPORT_MAX_DEVICES is 44 in 3.10).
+                    if (/^JoyPort\dDevice$/.test(name) && (value < 0 || value >= 44)) {
+                        return buildResponse(cmd, reqId, Buffer.alloc(0), 0x8f);
+                    }
                     this.resources.set(name, value);
                 }
                 else {
@@ -281,6 +316,18 @@ export class ViceMockServer {
                 }
                 return buildResponse(cmd, reqId);
             }
+            case 0xA2: { // joyport set: like VICE, it only stores the I/O simulation device's output lines
+                const port = body.readUInt16LE(0);
+                const value = body.readUInt16LE(2);
+                if (port > 1) {
+                    return buildResponse(cmd, reqId, Buffer.alloc(0), 0x01);
+                }
+                if (value > 0xff) {
+                    return buildResponse(cmd, reqId, Buffer.alloc(0), 0x81);
+                }
+                this.joyportOutput[port] = value & 0x1f;
+                return buildResponse(cmd, reqId);
+            }
             case 0xAA: // exit monitor
                 return buildResponse(cmd, reqId);
             case 0xBB: // quit
@@ -434,11 +481,51 @@ export class ViceMockServer {
         for (const meta of this.registerMetadata) {
             this.registerValues.set(meta.id, 0);
         }
+        this.joyportOutput = [0, 0];
+    }
+    // Resources survive a machine reset in VICE. Only resources that exist in
+    // VICE 3.10 are known; others fail the way VICE fails (see below).
+    resetResources() {
         this.resources = new Map([
-            ["C64Model", 2],
             ["SidEngine", 1],
+            ["JoyPort1Device", 1],
+            ["JoyPort2Device", 1],
+            ["Drive8Type", 1541],
+            ["Drive9Type", 0],
+            ["Drive10Type", 0],
+            ["Drive11Type", 0],
+            ["VICIIDoubleSize", 0],
+            ["VICIIBorderMode", 0],
+            ["VICIIFullscreen", 0],
+            ["SoundVolume", 100],
+            ["SidModel", 0],
+            ["MachineVideoStandard", 1],
+            ["KernalName", "kernal-901227-03.bin"],
         ]);
     }
+    /** Lines a joyport device drives, as CIA1 sees them (active low); only the I/O simulation device (37) is modelled. */
+    joyportLines(port) {
+        return this.resources.get(`JoyPort${port}Device`) === 37 ? this.joyportOutput[port - 1] : 0xff;
+    }
+    // CIA1 port A ($DC00) reads joyport 2 and port B ($DC01) joyport 1, ANDed with the keyboard lines.
+    applyJoyportOverlay(start, length, payload) {
+        for (const [address, port] of [[0xdc00, 2], [0xdc01, 1]]) {
+            if (address >= start && address < start + length) {
+                payload[2 + address - start] = 0xff & this.joyportLines(port);
+            }
+        }
+    }
+    // What VICE's autoload leaves on screen after its power cycle: the typed LOAD and READY.
+    renderAutoload(run) {
+        // The power cycle's KERNAL reset clears $0200-$03FF (RAMTAS).
+        this.memory.fill(0x00, 0x0200, 0x0400);
+        this.memory.fill(0x20, SCREEN_BASE, SCREEN_BASE + 1000);
+        const lines = ['LOAD"*",8,1', "", "SEARCHING FOR *", "LOADING", "READY.", ...(run ? ["RUN"] : [])];
+        lines.forEach((line, row) => {
+            const codes = asciiToScreenCodes(line);
+            codes.copy(Buffer.from(this.memory.buffer, SCREEN_BASE + row * 40, codes.length));
+        });
+    }
     renderHello() {
         if (this.helloReady)
             return;

package/dist/vice/readiness.js

@@ -126,15 +126,10 @@ export function asciiToScreenCodes(text) {
             out.push(ch.charCodeAt(0) - 64);
         else if (ch >= '0' && ch <= '9')
             out.push(0x30 + (ch.charCodeAt(0) - 48));
-        else if (ch === ' ')
-            out.push(0x20);
-        else if (ch === '.')
-            out.push(0x2E);
-        else if (ch === ':')
-            out.push(0x3A);
-        else if (ch === '-')
-            out.push(0x2D);
-        // extend as needed; ignore others
+        // Space, digits and punctuation ($20-$3F) have the same screen codes as ASCII.
+        else if (ch >= ' ' && ch <= '?')
+            out.push(ch.charCodeAt(0));
+        // ignore others
     }
     return Buffer.from(out);
 }

package/dist/vice/viceClient.js

@@ -159,6 +159,24 @@ export class ViceClient {
     async resetSoft() { await this.send(0xCC, Buffer.from([0x00])); }
     async resetHard() { await this.send(0xCC, Buffer.from([0x01])); }
     async reset(type = 0) { await this.send(0xCC, Buffer.from([type])); }
+    /** Reset only the drive CPU of unit 8-11 (BM 0xCC reset types 8-11). */
+    async resetDrive(unit) { await this.send(0xCC, Buffer.from([unit])); }
+    /**
+     * Attach an image and load from it (BM 0xDD Autostart). With run=false VICE
+     * uses its autoload mode, which attaches to drive 8 and LOADs without RUN.
+     */
+    async autostart(filename, options) {
+        const name = Buffer.from(filename, "utf8");
+        if (name.length === 0 || name.length > 255) {
+            throw new Error("Autostart file names must be 1-255 bytes");
+        }
+        const body = Buffer.alloc(4 + name.length);
+        body[0] = options.run ? 1 : 0;
+        body.writeUInt16LE(options.fileIndex ?? 0, 1);
+        body[3] = name.length;
+        name.copy(body, 4);
+        await this.send(0xDD, body);
+    }
     /**
      * Exit the emulator process (BM 0xBB Quit). The socket will be closed by VICE.
      * Consumers should still call close() to dispose any local resources.

package/doc/audit/secret-handling.md

@@ -0,0 +1,61 @@
+# Ultimate network password handling audit
+
+**Summary: yes, a leak exists.** An Ultimate request failure can leave the password in an Axios error's request configuration, which reaches stderr when a screen read fails during BASIC execution or polling. This is a source audit, supplemented by a local synthetic Axios serialization/console check; it does not establish that a real password was exposed. Diagnostics usually reduce actual `Error` objects to selected fields, and ordinary MCP error conversion usually uses only the message, but neither is a general secret boundary. Firmware-returned data and arbitrary error messages are not redacted.
+
+## Paths checked
+
+- **Password source and transport — leak (error object).** `src/config.ts:139`–`146` and `src/config.ts:201`–`205` resolve the environment or configuration password; `src/c64Client.ts:351`–`354`, `src/device.ts:221`–`230`, `src/device.ts:1550`–`1551`, and `src/mcp-server.ts:642`–`645` attach it to `X-Password`. Generated `HttpClient.request` returns the Axios request directly (`generated/c64/index.ts:299`–`334`). The HTTP interceptor rejects the original error (`src/loggingHttpClient.ts:49`–`57`), preserving `error.config.headers`. The installed Axios implementation serializes config in `AxiosError.toJSON` unless opt-in redaction is configured (`node_modules/axios/lib/core/AxiosError.js:171`–`196`); a synthetic `JSON.stringify` of an Axios error with this header printed the password. This is an in-process disclosure to error consumers, and makes downstream serialization dangerous.
+
+- **HTTP logging — safe for the configured header on the normal interceptor path.** `src/loggingHttpClient.ts:17`–`23` redacts sensitive header names case-insensitively; request metadata stores the redacted copy (`:32`–`:45`), and success/error debug records use it (`:63`–`:115`). The error summary uses only the message (`src/logger.ts:191`–`199`). Request bodies, parameters, response bodies and messages are not redacted, so a server echo or a password entered separately as data is outside this safe verdict.
+
+- **General logger and console — leak.** `src/logger.ts:37`–`47` passes details to console unchanged; `src/bootstrap/stdio-logger.ts:25`–`33` directs console output to stderr. `C64Client.readScreen` calls `readMemoryRaw` (`src/c64Client.ts:900`–`904`), which rethrows a non-unsupported facade error (`:2169`–`:2177`). After BASIC upload, `src/tools/programRunners.ts:381`–`385` logs that raw error as details (`:34`–`:41`); Node console inspection prints Axios `config.headers`, including the password. With debug logging enabled, `src/tools/pollValidator.ts:169`–`170` and `:192`–`:193` likewise log the raw error (also `:255`–`:256`, `:279`–`:280`). Other console sites were inspected by search: startup connectivity logs a message rather than the Axios object (`src/mcp-server.ts:650`–`660`), while fatal logging prints an arbitrary raw error (`:738`–`:745`), so it has the same unsafe sink if such an error reaches it. `src/config.ts:62`–`69` prints JSON parser error messages; malformed configuration can put a fragment of the file in that message, so this is another potential credential disclosure, dependent on the malformed input and Node version.
+
+- **Diagnostic event files — safe for ordinary Axios Error configuration; otherwise unclear.** `writeDiagnosticEvent` calls `sanitize` before appending NDJSON (`src/diagnostics.ts:112`–`128`); actual `Error` instances are reduced to name, message, stack, code and sanitized cause, omitting Axios config (`:444`–`:453`). This applies to the raw connectivity error (`src/mcp-server.ts:650`–`659`), span failures (`src/diagnostics.ts:198`–`211`), MCP failure events (`src/mcp-server.ts:395`–`415`), and process handlers (`src/diagnostics.ts:410`–`422`). However, plain objects are traversed without key redaction (`:483`–`:488`), and strings, messages and stacks are retained (`:445`–`:456`); call-tool arguments are recorded (`src/mcp-server.ts:350`–`357`). Thus a serialized error, echoed credential, or user-supplied password can be persisted; no automatic flow from the configured header into those plain-object events was established. Diagnostics are enabled by default outside tests unless explicitly disabled (`src/diagnostics.ts:434`–`441`).
+
+- **MCP results and errors — safe for ordinary Axios config; unclear for returned firmware data.** `C64Client.normaliseError` selects message, status and response data for Axios errors (`src/c64Client.ts:2426`–`2439`); for example `readMemory` returns those details (`:927`–`:949`). `unknownErrorResult` uses an Error's message rather than serializing the Error (`src/tools/errors.ts:104`–`121`), while `toolErrorResult` includes supplied details (`:78`–`:93`) and `toCallToolResult` passes result fields through (`src/mcp-server.ts:690`–`713`). `version`, `info` and `configGet` can propagate raw Axios errors (`src/device.ts:357`–`358`, `:418`–`:422`; `src/c64Client.ts:1145`–`1152`, `:1416`–`:1423`), but their ordinary tool catches use the message. No direct serialization of one of these raw Axios errors into a client result was established. Response data is unfiltered, however: `config_get` returns firmware values (`src/tools/developer.ts:219`–`237`); whether firmware exposes its password there or echoes it on error is not established. User-supplied config values can also be returned (`:255`–`:280`).
+
+- **MCP resources and diagnostic reports — unclear for indirect content.** Platform status constructs backend and capability text, not endpoint credentials (`src/mcp-server.ts:197`–`219`, `:543`–`:604`); resource failures log messages, record sanitized errors and rethrow (`:236`–`:249`). `performance_report` reads diagnostic records and returns a summary (`src/tools/meta/diagnostics.ts:75`–`99`; `src/diagnostics.ts:235`–`249`, `:256` onward), so any sensitive content retained in the diagnostic timeline may reach a client. No direct configured-header-to-resource leak was established.
+
+- **Thrown and rethrown errors — leak across internal error boundary.** The original Axios error is rethrown by `readMemoryRaw` (`src/c64Client.ts:2169`–`2177`), by `withDiagnosticSpan` (`src/diagnostics.ts:198`–`211`), and by stream retry and capture paths (`src/c64Client.ts:1963`–`1971`, `:1978`–`:1983`, `:1633`–`:1638`, `:1883`–`:1895`). It still contains the request config; `JSON.stringify` invokes Axios's `toJSON` and exposes the header without opt-in redaction. `ensureStreamSuccess` embeds serialized result details in a new error (`:2023`–`:2027`), but no proven route from a raw Axios config into those details was found. Raw errors reaching generic console sinks remain a concrete risk.
+
+- **Other files — unclear for firmware-returned secrets.** Config snapshot collection stores returned values (`src/tools/meta/configInventory.ts:86`–`101`) and snapshot writes them to a file (`src/tools/meta/config.ts:40`–`54`). Whether the firmware returns the network password is unverified; the bridge does not insert its configured header value into the snapshot itself.
+
+## Recommended fixes
+
+1. In `createLoggingHttpClient`, replace or sanitize rejected Axios errors before they leave the transport, removing sensitive headers from config and request objects; apply the same boundary to direct Axios calls in `logConnectivity` and `C64uBackend.ping`. Preserve useful status and message fields without retaining credential-bearing causes.
+2. In `createPrefixedLogger` and the error logging in `pollBasicOutcome`, the ASM polling function, and BASIC program execution, log safe error summaries rather than raw objects; in `loadConfig`, avoid printing parser excerpts from configuration files. Review the fatal `main().catch` console sink as well.
+3. In `sanitize` and `writeDiagnosticEvent`, redact sensitive keys recursively and handle serialized Axios errors, arguments and error strings deliberately. In `normaliseError`, `unknownErrorResult`, `toolErrorResult`, and `toCallToolResult`, enforce a safe output boundary for errors and echoed data.
+4. In `config_get`'s `execute` and `captureConfigSnapshot`, decide how sensitive firmware configuration values should be handled and redact them if returned. Add focused tests with a synthetic password covering stderr, diagnostics, serialized errors, tool responses and snapshots.
+
+## Outcome of the fix
+
+The audit findings above describe the code before this change. This change adds one shared helper, `src/redact.ts`, and applies it at each sink.
+
+- `registerSecret` records the password. It is called from `resolveUltimateEndpoint` (`src/config.ts`), from `createLoggingHttpClient` (which reads the `X-Password` header it is configured with), and before the direct connectivity probe in `src/mcp-server.ts`.
+- `scrubRequestError` is applied to every rejected request in `createLoggingHttpClient`. It replaces sensitive values in `error.config.headers` and `error.response.config.headers`, clears `error.request` and `error.response.request` (the raw client request keeps the serialised header block), and redacts the password in a string response body. The status, code, message and response data otherwise remain available to callers. This closes the "thrown and rethrown errors" and `JSON.stringify` leaks.
+- `redactValue` and `redactText` are applied in `createPrefixedLogger` (`src/logger.ts`) to the message and details, in `sanitize` (`src/diagnostics.ts`) before the existing size limiting, in `toCallToolResult` (`src/mcp-server.ts`) to `content`, `structuredContent` and `metadata`, and to the fatal error in `main().catch`. `redactValue` reduces `Error` objects to name, message, stack, code, status and cause, redacts credential header names at any depth, and replaces registered secrets in all strings.
+- `loadConfig` now logs only the error name for an unreadable configuration file, because the JSON parser message can quote part of the file.
+
+Remaining limitation: redaction replaces the exact registered password string. A transformed form of the password (for example base64-encoded) is not detected. Firmware configuration values are handled separately, see below.
+
+Regression test: `test/secretRedaction.test.mjs` configures a distinctive password through `C64U_PASSWORD`, then drives HTTP 401 (with the password echoed in the body), HTTP 403, a client timeout and a refused connection against local servers. It asserts that the password is absent from captured console output, diagnostics files and records, `util.inspect`, `JSON.stringify`, `toJSON` and `stack` of the errors, and from `toCallToolResult` output for `toolErrorResult` and `unknownErrorResult`. With `src/redact.ts` replaced by no-op functions and the other `src/` changes reverted, the test fails with "password leaked in: AxiosError: Request failed with status code 401". With the fix it passes. `npm test` passes.
+
+## Firmware-returned configuration values
+
+**Evidence in the repository.** The repository does not list individual configuration item names for the credential settings. What it records:
+
+- `doc/c64u/c64-rest-api.md:17`: firmware 3.12 has an optional "Network Password".
+- `doc/c64u/c64-rest-api.md:93`–`95` (and the captured `scripts/compare-rest/rest-compare-2025-11-01T00-25-21-830Z.json:371`–`376`): the category list contains "Network settings", "WiFi settings" and "Modem Settings". These are the categories that can hold network, Wi-Fi and service credentials (network password, FTP/Telnet passwords, Wi-Fi key).
+- `doc/c64u/c64-rest-api.md:108`–`143`: category reads return `{ "<Category>": { "<Item>": value } }`, and item reads return `{ "<Category>": { "<Item>": { current, min, max, ... } } }`.
+- `doc/c64u/c64-openapi.yaml` and `doc/u2/u2-openapi.yaml` describe `X-Password` only; they define no password item.
+
+Whether the firmware returns the password through `/v1/configs` is therefore not established by repository data. The fix assumes that it can.
+
+**Behaviour.** `config_get` and `config_snapshot_and_restore` (snapshot and diff) now replace the value of credential items with `***` and keep the item name. An item is treated as a credential when its name contains `password`, `passwd`, `passphrase`, `passcode`, `psk` or `secret`, or is a bare Wi-Fi `key`. Matching is by item name (`isSensitiveConfigItem` in `src/redact.ts`), not by category, so it also applies to items in categories not listed above. For item reads, the whole item object (including `min`/`max`/`default`) is replaced by `***`.
+
+- Opt-in: `includeSecretValues: true` on `config_get` and on `config_snapshot_and_restore` returns or stores the values in plain text. Without the flag the values are never returned or written. The configured network password is still replaced by the registered-secret redaction in `toCallToolResult`, even with the flag.
+- Restore: a default snapshot contains `***`. `stripRedactedSecrets` removes those placeholders from the restore payload, so a restore never sets a password to the literal `***`. Credentials in a default snapshot are therefore not restored. Snapshots made with `includeSecretValues: true` restore them.
+- Diff: both sides are redacted by default, so a changed password is not reported unless the flag is set when the snapshot is taken and when diffing.
+- Limitation: detection is by item name. A credential item with a name that does not match the patterns above is not redacted.
+
+**Test.** `test/configSecretRedaction.test.mjs` uses a mocked firmware with "Network Password", "FTP Password", "Telnet Password" and a Wi-Fi "Password". It asserts redaction in the `config_get` result and in the written snapshot file, that other values (Hostname, Volume, access point name) are unchanged, that restore does not write `***`, and that the opt-in flag returns plain values. With `isSensitiveConfigItem` changed to always return false, 3 of its 4 tests fail.

package/mcp/schemas/c64_config.schema.json

@@ -35,6 +35,14 @@
       "description": "Specific configuration item inside the selected category (e.g. 'Volume').",
       "minLength": 1
     },
+    "includeSecretValues": {
+      "type": [
+        "boolean",
+        "null"
+      ],
+      "description": "Return credential values (network password, FTP/Telnet passwords, Wi-Fi keys) in plain text. Default false: those values are replaced with ***.",
+      "default": false
+    },
     "value": {
       "description": "Primitive configuration value (string, number, or boolean).",
       "type": [
@@ -128,7 +136,7 @@
   "required": [
     "op"
   ],
-  "description": "Configuration operations available via the c64_config tool.\n\nOperations:\n- list: List configuration categories reported by the firmware. Required inputs: none.\n- get: Read a configuration category or specific item. Required inputs: category. Optional inputs: item.\n- set: Write a configuration value in the selected category. Required inputs: category, item, value.\n- batch_update: Apply multiple configuration updates in a single request. Required inputs: none.\n- load_flash: Load configuration from flash storage. Required inputs: none.\n- save_flash: Persist the current configuration to flash storage. Required inputs: none.\n- reset_defaults: Reset firmware configuration to factory defaults. Required inputs: none.\n- read_debugreg: Read the Ultimate debug register ($D7FF). Required inputs: none.\n- write_debugreg: Write a hex value to the Ultimate debug register ($D7FF). Required inputs: value.\n- info: Retrieve Ultimate hardware information and status. Required inputs: none.\n- version: Fetch firmware version details. Required inputs: none.\n- snapshot: Snapshot configuration to disk for later restore or diff. Required inputs: path.\n- restore: Restore configuration from a snapshot file. Required inputs: path. Optional inputs: applyToFlash.\n- diff: Compare the current configuration with a snapshot. Required inputs: path.\n- shuffle: Discover PRG/CRT files and run each with optional screen capture. Required inputs: none. Optional inputs: root, extensions, durationMs, captureScreen, maxPrograms, outputPath, resetDelayMs.",
+  "description": "Configuration operations available via the c64_config tool.\n\nOperations:\n- list: List configuration categories reported by the firmware. Required inputs: none.\n- get: Read a configuration category or specific item. Required inputs: category. Optional inputs: item, includeSecretValues.\n- set: Write a configuration value in the selected category. Required inputs: category, item, value.\n- batch_update: Apply multiple configuration updates in a single request. Required inputs: none.\n- load_flash: Load configuration from flash storage. Required inputs: none.\n- save_flash: Persist the current configuration to flash storage. Required inputs: none.\n- reset_defaults: Reset firmware configuration to factory defaults. Required inputs: none.\n- read_debugreg: Read the Ultimate debug register ($D7FF). Required inputs: none.\n- write_debugreg: Write a hex value to the Ultimate debug register ($D7FF). Required inputs: value.\n- info: Retrieve Ultimate hardware information and status. Required inputs: none.\n- version: Fetch firmware version details. Required inputs: none.\n- snapshot: Snapshot configuration to disk for later restore or diff. Required inputs: path.\n- restore: Restore configuration from a snapshot file. Required inputs: path. Optional inputs: applyToFlash.\n- diff: Compare the current configuration with a snapshot. Required inputs: path.\n- shuffle: Discover PRG/CRT files and run each with optional screen capture. Required inputs: none. Optional inputs: root, extensions, durationMs, captureScreen, maxPrograms, outputPath, resetDelayMs.",
   "additionalProperties": false,
   "x-c64bridge-operations": [
     {
@@ -157,7 +165,8 @@
         "category"
       ],
       "optional": [
-        "item"
+        "item",
+        "includeSecretValues"
       ],
       "inputSchema": {
         "type": "object",
@@ -176,6 +185,14 @@
             "description": "Specific configuration item inside the selected category (e.g. 'Volume').",
             "minLength": 1
           },
+          "includeSecretValues": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Return credential values (network password, FTP/Telnet passwords, Wi-Fi keys) in plain text. Default false: those values are replaced with ***.",
+            "default": false
+          },
           "op": {
             "const": "get"
           }

package/mcp/schemas/c64_disk.schema.json

@@ -119,7 +119,7 @@
         "integer",
         "null"
       ],
-      "description": "Track count (D64 supports 35 or 40; DNP requires explicit tracks).",
+      "description": "Track count (D64 supports 35 to 41; DNP requires explicit tracks).",
       "minimum": 1,
       "maximum": 255
     },
@@ -421,7 +421,7 @@
               "integer",
               "null"
             ],
-            "description": "Track count (D64 supports 35 or 40; DNP requires explicit tracks).",
+            "description": "Track count (D64 supports 35 to 41; DNP requires explicit tracks).",
             "minimum": 1,
             "maximum": 255
           },

package/mcp/schemas/c64_input.schema.json

@@ -178,7 +178,7 @@
   "required": [
     "op"
   ],
-  "description": "Input operations: write_text, key, keyboard, joystick, release_all, state.\n\nOperations:\n- write_text: Send a text string to the keyboard buffer, with PETSCII token expansion. Required inputs: text. Optional inputs: delayMs.\n- key: Tap a single key or hold it for a duration. Required inputs: key. Optional inputs: durationMs, count.\n- joystick: Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set. Required inputs: port, controls, action. Optional inputs: durationMs.\n- keyboard: Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: inputs, transition.\n- release_all: Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.\n- state: Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.",
+  "description": "Input operations: write_text, key, keyboard, joystick, release_all, state.\n\nOperations:\n- write_text: Send a text string to the keyboard buffer, with PETSCII token expansion. Required inputs: text. Optional inputs: delayMs.\n- key: Tap a single key or hold it for a duration. Required inputs: key. Optional inputs: durationMs, count.\n- joystick: Simulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches VICE's I/O simulation joyport device while pressed; that device also pulls CIA lines 5-7 low, so port 1 produces phantom keys (e.g. SHIFT+C=) and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4. Required inputs: port, controls, action. Optional inputs: durationMs.\n- keyboard: Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: inputs, transition.\n- release_all: Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.\n- state: Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.",
   "additionalProperties": false,
   "x-c64bridge-operations": [
     {
@@ -274,7 +274,7 @@
     },
     {
       "op": "joystick",
-      "description": "Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set.",
+      "description": "Simulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches VICE's I/O simulation joyport device while pressed; that device also pulls CIA lines 5-7 low, so port 1 produces phantom keys (e.g. SHIFT+C=) and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4.",
       "required": [
         "port",
         "controls",
@@ -285,7 +285,7 @@
       ],
       "inputSchema": {
         "type": "object",
-        "description": "Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set.",
+        "description": "Simulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches VICE's I/O simulation joyport device while pressed; that device also pulls CIA lines 5-7 low, so port 1 produces phantom keys (e.g. SHIFT+C=) and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4.",
         "properties": {
           "op": {
             "const": "joystick"

package/mcp/schemas/c64_program.schema.json

@@ -60,7 +60,7 @@
               "properties": {
                 "type": {
                   "type": "string",
-                  "description": "Assertion type",
+                  "description": "Assertion type; sid_silent needs the C64 Ultimate audio stream (c64u backend).",
                   "enum": [
                     "screen_contains",
                     "memory_equals",
@@ -462,7 +462,7 @@
                     "properties": {
                       "type": {
                         "type": "string",
-                        "description": "Assertion type",
+                        "description": "Assertion type; sid_silent needs the C64 Ultimate audio stream (c64u backend).",
                         "enum": [
                           "screen_contains",
                           "memory_equals",

package/mcp/schemas/c64_vice.schema.json

@@ -11,7 +11,7 @@
     },
     "name": {
       "type": "string",
-      "description": "VICE resource name (example: SidEngine, C64Model).",
+      "description": "VICE resource name (example: SidEngine, SidModel).",
       "minLength": 1,
       "maxLength": 64,
       "pattern": "^[A-Z][A-Za-z0-9_.-]{0,63}$"
@@ -46,7 +46,7 @@
           },
           "name": {
             "type": "string",
-            "description": "VICE resource name (example: SidEngine, C64Model).",
+            "description": "VICE resource name (example: SidEngine, SidModel).",
             "minLength": 1,
             "maxLength": 64,
             "pattern": "^[A-Z][A-Za-z0-9_.-]{0,63}$"
@@ -76,7 +76,7 @@
           },
           "name": {
             "type": "string",
-            "description": "VICE resource name (example: SidEngine, C64Model).",
+            "description": "VICE resource name (example: SidEngine, SidModel).",
             "minLength": 1,
             "maxLength": 64,
             "pattern": "^[A-Z][A-Za-z0-9_.-]{0,63}$"

package/mcp/server.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Stdio-based Model Context Protocol (MCP) server that bridges Commodore 64 Ultimate hardware with AI agents.",
   "transports": [
     "stdio"

package/mcp/tools.json

@@ -66,7 +66,7 @@
                     "properties": {
                       "type": {
                         "type": "string",
-                        "description": "Assertion type",
+                        "description": "Assertion type; sid_silent needs the C64 Ultimate audio stream (c64u backend).",
                         "enum": [
                           "screen_contains",
                           "memory_equals",
@@ -468,7 +468,7 @@
                           "properties": {
                             "type": {
                               "type": "string",
-                              "description": "Assertion type",
+                              "description": "Assertion type; sid_silent needs the C64 Ultimate audio stream (c64u backend).",
                               "enum": [
                                 "screen_contains",
                                 "memory_equals",
@@ -4483,7 +4483,7 @@
               "integer",
               "null"
             ],
-            "description": "Track count (D64 supports 35 or 40; DNP requires explicit tracks).",
+            "description": "Track count (D64 supports 35 to 41; DNP requires explicit tracks).",
             "minimum": 1,
             "maximum": 255
           },
@@ -4785,7 +4785,7 @@
                     "integer",
                     "null"
                   ],
-                  "description": "Track count (D64 supports 35 or 40; DNP requires explicit tracks).",
+                  "description": "Track count (D64 supports 35 to 41; DNP requires explicit tracks).",
                   "minimum": 1,
                   "maximum": 255
                 },
@@ -4949,6 +4949,10 @@
           "vice"
         ],
         "operationPlatforms": {
+          "unmount": [
+            "c64u",
+            "u2"
+          ],
           "file_info": [
             "c64u",
             "u2"
@@ -5721,6 +5725,14 @@
             "description": "Specific configuration item inside the selected category (e.g. 'Volume').",
             "minLength": 1
           },
+          "includeSecretValues": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Return credential values (network password, FTP/Telnet passwords, Wi-Fi keys) in plain text. Default false: those values are replaced with ***.",
+            "default": false
+          },
           "value": {
             "description": "Primitive configuration value (string, number, or boolean).",
             "type": [
@@ -5814,7 +5826,7 @@
         "required": [
           "op"
         ],
-        "description": "Configuration operations available via the c64_config tool.\n\nOperations:\n- list: List configuration categories reported by the firmware. Required inputs: none.\n- get: Read a configuration category or specific item. Required inputs: category. Optional inputs: item.\n- set: Write a configuration value in the selected category. Required inputs: category, item, value.\n- batch_update: Apply multiple configuration updates in a single request. Required inputs: none.\n- load_flash: Load configuration from flash storage. Required inputs: none.\n- save_flash: Persist the current configuration to flash storage. Required inputs: none.\n- reset_defaults: Reset firmware configuration to factory defaults. Required inputs: none.\n- read_debugreg: Read the Ultimate debug register ($D7FF). Required inputs: none.\n- write_debugreg: Write a hex value to the Ultimate debug register ($D7FF). Required inputs: value.\n- info: Retrieve Ultimate hardware information and status. Required inputs: none.\n- version: Fetch firmware version details. Required inputs: none.\n- snapshot: Snapshot configuration to disk for later restore or diff. Required inputs: path.\n- restore: Restore configuration from a snapshot file. Required inputs: path. Optional inputs: applyToFlash.\n- diff: Compare the current configuration with a snapshot. Required inputs: path.\n- shuffle: Discover PRG/CRT files and run each with optional screen capture. Required inputs: none. Optional inputs: root, extensions, durationMs, captureScreen, maxPrograms, outputPath, resetDelayMs.",
+        "description": "Configuration operations available via the c64_config tool.\n\nOperations:\n- list: List configuration categories reported by the firmware. Required inputs: none.\n- get: Read a configuration category or specific item. Required inputs: category. Optional inputs: item, includeSecretValues.\n- set: Write a configuration value in the selected category. Required inputs: category, item, value.\n- batch_update: Apply multiple configuration updates in a single request. Required inputs: none.\n- load_flash: Load configuration from flash storage. Required inputs: none.\n- save_flash: Persist the current configuration to flash storage. Required inputs: none.\n- reset_defaults: Reset firmware configuration to factory defaults. Required inputs: none.\n- read_debugreg: Read the Ultimate debug register ($D7FF). Required inputs: none.\n- write_debugreg: Write a hex value to the Ultimate debug register ($D7FF). Required inputs: value.\n- info: Retrieve Ultimate hardware information and status. Required inputs: none.\n- version: Fetch firmware version details. Required inputs: none.\n- snapshot: Snapshot configuration to disk for later restore or diff. Required inputs: path.\n- restore: Restore configuration from a snapshot file. Required inputs: path. Optional inputs: applyToFlash.\n- diff: Compare the current configuration with a snapshot. Required inputs: path.\n- shuffle: Discover PRG/CRT files and run each with optional screen capture. Required inputs: none. Optional inputs: root, extensions, durationMs, captureScreen, maxPrograms, outputPath, resetDelayMs.",
         "additionalProperties": false,
         "x-c64bridge-operations": [
           {
@@ -5843,7 +5855,8 @@
               "category"
             ],
             "optional": [
-              "item"
+              "item",
+              "includeSecretValues"
             ],
             "inputSchema": {
               "type": "object",
@@ -5862,6 +5875,14 @@
                   "description": "Specific configuration item inside the selected category (e.g. 'Volume').",
                   "minLength": 1
                 },
+                "includeSecretValues": {
+                  "type": [
+                    "boolean",
+                    "null"
+                  ],
+                  "description": "Return credential values (network password, FTP/Telnet passwords, Wi-Fi keys) in plain text. Default false: those values are replaced with ***.",
+                  "default": false
+                },
                 "op": {
                   "const": "get"
                 }
@@ -8075,7 +8096,7 @@
           },
           "name": {
             "type": "string",
-            "description": "VICE resource name (example: SidEngine, C64Model).",
+            "description": "VICE resource name (example: SidEngine, SidModel).",
             "minLength": 1,
             "maxLength": 64,
             "pattern": "^[A-Z][A-Za-z0-9_.-]{0,63}$"
@@ -8110,7 +8131,7 @@
                 },
                 "name": {
                   "type": "string",
-                  "description": "VICE resource name (example: SidEngine, C64Model).",
+                  "description": "VICE resource name (example: SidEngine, SidModel).",
                   "minLength": 1,
                   "maxLength": 64,
                   "pattern": "^[A-Z][A-Za-z0-9_.-]{0,63}$"
@@ -8140,7 +8161,7 @@
                 },
                 "name": {
                   "type": "string",
-                  "description": "VICE resource name (example: SidEngine, C64Model).",
+                  "description": "VICE resource name (example: SidEngine, SidModel).",
                   "minLength": 1,
                   "maxLength": 64,
                   "pattern": "^[A-Z][A-Za-z0-9_.-]{0,63}$"
@@ -8392,7 +8413,7 @@
         "required": [
           "op"
         ],
-        "description": "Input operations: write_text, key, keyboard, joystick, release_all, state.\n\nOperations:\n- write_text: Send a text string to the keyboard buffer, with PETSCII token expansion. Required inputs: text. Optional inputs: delayMs.\n- key: Tap a single key or hold it for a duration. Required inputs: key. Optional inputs: durationMs, count.\n- joystick: Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set. Required inputs: port, controls, action. Optional inputs: durationMs.\n- keyboard: Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: inputs, transition.\n- release_all: Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.\n- state: Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.",
+        "description": "Input operations: write_text, key, keyboard, joystick, release_all, state.\n\nOperations:\n- write_text: Send a text string to the keyboard buffer, with PETSCII token expansion. Required inputs: text. Optional inputs: delayMs.\n- key: Tap a single key or hold it for a duration. Required inputs: key. Optional inputs: durationMs, count.\n- joystick: Simulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches VICE's I/O simulation joyport device while pressed; that device also pulls CIA lines 5-7 low, so port 1 produces phantom keys (e.g. SHIFT+C=) and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4. Required inputs: port, controls, action. Optional inputs: durationMs.\n- keyboard: Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: inputs, transition.\n- release_all: Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.\n- state: Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.",
         "additionalProperties": false,
         "x-c64bridge-operations": [
           {
@@ -8488,7 +8509,7 @@
           },
           {
             "op": "joystick",
-            "description": "Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set.",
+            "description": "Simulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches VICE's I/O simulation joyport device while pressed; that device also pulls CIA lines 5-7 low, so port 1 produces phantom keys (e.g. SHIFT+C=) and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4.",
             "required": [
               "port",
               "controls",
@@ -8499,7 +8520,7 @@
             ],
             "inputSchema": {
               "type": "object",
-              "description": "Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set.",
+              "description": "Simulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches VICE's I/O simulation joyport device while pressed; that device also pulls CIA lines 5-7 low, so port 1 produces phantom keys (e.g. SHIFT+C=) and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4.",
               "properties": {
                 "op": {
                   "const": "joystick"

package/mcp.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Stdio-based Model Context Protocol (MCP) server that bridges Commodore 64 Ultimate hardware with AI agents.",
   "entry": "dist/index.js",
   "type": "stdio",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "mcpName": "io.github.chrisgleissner/c64bridge",
   "description": "C64 Bridge MCP server for Commodore 64 Ultimate hardware and VICE emulator control",
   "repository": {
@@ -73,7 +73,7 @@
     "date-fns": "^4.4.0",
     "fastify": "^5.12.5",
     "jimp": "^1.6.1",
-    "meyda": "^5.6.3",
+    "meyda": "5.6.2",
     "octokit": "^5.0.5",
     "pitchfinder": "^2.3.4",
     "reflect-metadata": "^0.2.2",
@@ -82,6 +82,9 @@
   "optionalDependencies": {
     "naudiodon": "^2.3.6"
   },
+  "overrides": {
+    "zod": "^4.6.6"
+  },
   "devDependencies": {
     "@types/node": "^25.9.5",
     "tsx": "^4.23.11",