ispyx 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Murat Mehmet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+<p align="center"><img src="docs/banner.png" alt="ispyx: an eye on a window, scanning it" width="100%"></p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# ispyx
+
+A local desktop-control [MCP](https://modelcontextprotocol.io) server. It lets an AI assistant use your computer the way a person does: look at the screen or at one window, move the mouse, click, drag, scroll, type, press hotkeys and use the clipboard.
+
+- Runs on your machine, talks to the MCP client over **stdio**, opens **no network port**.
+- Node 22+, `koffi` for the Windows API, `@modelcontextprotocol/sdk` for MCP.
+- Windows and macOS (see [Platform status](#platform-status)).
+
+## Features
+
+- **Tools** for windows, monitors, screenshots (screen, monitor, region or a single window), mouse (click, move, drag, scroll, press/release), keyboard (typing, hotkeys, hold/release) and clipboard (text, image, files).
+- **Human-paced input.** The pointer glides along a gently curved path to each target, scrolling is smoothed, and typing goes one character at a time with natural pauses.
+- **On-screen feedback.** An eye opens and a scan line sweeps the captured area after a screenshot; clicks, drags, scrolls, key presses, typing and waits each get a small animation; `list_windows` sends out a sonar ping that lights up window frames. A banner shows while a tool runs. All of it is click-through and can be turned off.
+- **Safety.**
+  - **Alt+Esc** (Option+Esc on macOS) stops everything: one press cancels all running and queued calls, a second press within 5 s shuts the server down.
+  - A **denylist** of programs that are never driven (password managers by default).
+  - Refuses to type into **password fields**.
+  - An optional **password gate** that asks you before the first tool call.
+  - An action log of everything the server did.
+  - **Single resident app:** on Windows one background process (`ispyx --resident`, tray icon) does the work and every MCP client talks to it through a thin `ispyx mcp` process, so there is one stop key, one banner and one unlock state.
+
+## Install on Windows
+
+Open PowerShell (Start menu, type "PowerShell") and paste:
+
+```
+irm https://raw.githubusercontent.com/murat-mehmet/ispyx/master/scripts/install.ps1 | iex
+```
+
+No administrator rights are needed. The script explains each step as it goes. It:
+
+- finds Node.js 22+ or installs it for your user only (winget, or the official zip with a checksum check);
+- installs ispyx with `npm install -g ispyx`;
+- puts an `Ispyx` shortcut on your Desktop, turns on start at login and starts ispyx.
+
+Then it prints the commands to connect your AI app, for Claude Code: `claude mcp add ispyx --scope user -- ispyx mcp`.
+
+**Opening it.** Double-click the `Ispyx` Desktop shortcut or run `ispyx`. ispyx lives in the tray (next to the clock, maybe under the `^` arrow); right-click the icon for its menu (panel, start at login, quit). `ispyx update` updates it. Alt+Esc is the emergency stop.
+
+**Uninstall.** Run the installer again with `-Uninstall` (add `-Purge` to also delete settings and logs):
+
+```
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/murat-mehmet/ispyx/master/scripts/install.ps1))) -Uninstall
+```
+
+**Manual install.** Install Node.js 22+ from [nodejs.org](https://nodejs.org), then `npm i -g ispyx` and run `ispyx`.
+
+Details, options and troubleshooting: [docs/windows-install.md](docs/windows-install.md).
+
+## Install and run (npx, macOS and advanced)
+
+No installation is needed, the client starts it with `npx`.
+
+Claude Code:
+
+```
+claude mcp add ispyx --scope user -- npx -y ispyx
+```
+
+Claude Desktop and other MCP clients (JSON form; on Windows some clients need `cmd /c` around `npx`):
+
+```json
+{
+  "mcpServers": {
+    "ispyx": {
+      "command": "npx",
+      "args": ["-y", "ispyx"]
+    }
+  }
+}
+```
+
+Requires Node.js 22 or newer.
+
+### Windows: the resident app
+
+On Windows ispyx is a single resident app, like `Ispyx.app` on macOS:
+
+- `ispyx` (in a console, or from a shortcut) starts the resident app hidden in the background if it is not running, opens its panel and exits.
+- `ispyx --resident` is the resident itself (tray icon, effects, stop key). A second one exits at once. It writes no output; errors go to `%APPDATA%\ispyx\ispyx.log`.
+- `ispyx mcp` is the stdio MCP server for your client. It forwards every call to the resident and starts it first if needed. Prefer registering `npx -y ispyx mcp`; an old registration without `mcp` still works (it is detected by the missing console).
+- `ispyx quit` stops the resident (tray menu: Quit).
+
+Details: [src/core/RESIDENT.md](src/core/RESIDENT.md).
+
+macOS: install `Ispyx.app` from the [Releases](https://github.com/murat-mehmet/ispyx/releases) page instead, which carries its own Node and needs nothing else. See [native/macos/README.md](native/macos/README.md).
+
+## Configuration
+
+Settings are applied in this order, later wins: built-in defaults, `config.json` (in the package folder, or the file named by `ISPYX_CONFIG`), environment variables. See `config.example.json`.
+
+| `config.json` key | Environment variable | Default | Meaning |
+| --- | --- | --- | --- |
+| (the file itself) | `ISPYX_CONFIG` | `config.json` in the package root | Path of a config file. |
+| `denylist` | `ISPYX_DENYLIST` (comma separated) | `keepass.exe`, `keepassxc.exe`, `1password.exe`, `bitwarden.exe`; macOS: `1Password`, `Bitwarden`, `KeePassXC`, `Keychain Access`, `Enpass` (app names, case-insensitive) | Programs that are never driven or focused. |
+| `logPath` | `ISPYX_LOG` | `logs/actions.jsonl` (macOS: `~/Library/Application Support/Ispyx/logs/actions.jsonl`) | Action log (JSON lines). |
+| `auth` | `ISPYX_AUTH` (`0`/`1`) | `false` | Ask for a password before the first tool call. |
+| `authFile` | `ISPYX_AUTH_FILE` | `%APPDATA%\ispyx\auth.json` (macOS: `~/Library/Application Support/Ispyx/auth.json`) | Where the password hash is stored. |
+| `overlay` | `ISPYX_OVERLAY` (`0`/`1`) | `true` | The "ispyx is working" banner. |
+| `animations` | `ISPYX_ANIMATIONS` (`0`/`1`) | `true` | The eye, scan and other effects. |
+| `typeSpeed` | `ISPYX_TYPE_SPEED` | `1` | Typing speed multiplier (2 = twice as fast, 0 = fixed 8 ms per character). |
+| `stopChord` | `ISPYX_STOP_CHORD` | `alt+esc` | Emergency stop keys (mainly for tests). |
+| `maxTypeLength` | | `10000` | Longest text one `type_text` call accepts. |
+| `moveMinMs`, `moveMaxMs` | | `300`, `1000` | Duration range of pointer glides. |
+| `typeMinMs`, `typeMaxMs`, `typeCapMs` | | `40`, `120`, `60000` | Pause range per typed character; a text is sped up to finish within the cap. |
+
+The older `WIN_INPUT_*` names (and `WIN_INPUT_MCP_CONFIG`) still work as fallbacks; an `ISPYX_*` variable wins when both are set.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `list_windows` | Visible top-level windows with handle, title, class, process, rectangle, whether allowed (not denylisted) and whether elevated. |
+| `list_monitors` | Monitor rectangles and the virtual desktop bounds. |
+| `cursor_position` | Current pointer position. |
+| `focus_window` | Restore and bring a window to the front. |
+| `screenshot_screen` | PNG of one monitor, all monitors, or a region. |
+| `screenshot_window` | PNG of one window (also GPU-rendered content), optionally cropped to a region. |
+| `click` | Left, right or middle click; double or triple; with held modifiers. |
+| `move` | Move the pointer. |
+| `mouse_down`, `mouse_up` | Press and release a mouse button. |
+| `drag` | Press at one point, glide to another, release. |
+| `scroll` | Smooth vertical and/or horizontal wheel, with optional modifiers. |
+| `type_text` | Type Unicode text into the focused control at a human pace; refused in password fields. |
+| `press_keys` | Key chords such as `ctrl+v`, `alt+tab`, `win+r`. |
+| `key_down`, `key_up` | Hold and release keys. |
+| `wait` | Pause up to 60 s. |
+| `get_clipboard`, `set_clipboard` | Read clipboard text; write text, an image or a file. |
+
+Typical flow: `screenshot_screen`, read coordinates off the image, `click` (with `space: "shot"`) or `type_text`, then `screenshot_screen` to check. Details on coordinates and per-tool behaviour are in [docs/behavior.md](docs/behavior.md).
+
+## Safety notes
+
+- **Alt+Esc** (Option+Esc on macOS) is the emergency stop. It is caught by a low-level keyboard hook, so it does not also cycle windows.
+- **Elevated (administrator) windows cannot be controlled**: Windows ignores input from a normal process (UIPI). The server refuses with a plain message; it works if the server itself runs elevated. UAC prompts, the lock screen and Ctrl+Alt+Del run on the secure desktop where no input or capture is possible.
+- **Denylist.** Programs on the denylist are never focused, clicked or typed into, and show up as not allowed in `list_windows`. The default covers common password managers.
+- **No credentials.** The server never reads, stores or types saved passwords. Typing into password fields is refused.
+- **Action log.** Every action, refusal and error is logged locally, including typed text (except text aimed at a password field). Clipboard reads log the length only.
+- This tool gives an AI control of your computer. Only connect it to clients you trust, and consider turning on the password gate.
+
+## Platform status
+
+| Platform | Status |
+| --- | --- |
+| Windows | Supported. |
+| macOS | Supported, macOS 13 or later (tested on Apple Silicon with macOS 26; the app is universal, Intel Macs are not tested). A menu-bar app (`native/macos`, `Ispyx.app`) does the OS work and bundles Node and this server. There is no elevation concept; the stop key is Option+Esc. |
+| Linux | Not planned yet. |
+
+## Development
+
+```
+git clone https://github.com/murat-mehmet/ispyx
+cd ispyx
+npm install
+node src/server.js
+```
+
+Layout:
+
+- `src/core/` shared, platform independent: MCP server and tools, safety guard, input motion, image encoding, password gate, single-instance IPC.
+- `src/platform/` the platform layer behind `src/platform/index.js`; the contract is in `src/platform/CONTRACT.md`. `win32/` is the Windows implementation (Win32 through `koffi`, PowerShell helpers), `darwin/` the macOS one (a client of `Ispyx.app`).
+- `src/effects/` the on-screen animations.
+- `native/macos/` the macOS app (Swift).
+- `src/server.js` is the entry point (`bin`) and only loads `src/core/server.js`.
+- `test/` tests; most drive the real desktop of the machine they run on.
+
+Releases (npm package and macOS DMG) are made by pushing a version tag, see [docs/releasing.md](docs/releasing.md).
+
+```
+npm test              # unit checks (no desktop needed for most)
+npm run smoke         # drives the real server against Notepad
+npm run motion-test   # pointer glide duration, curvature, exact arrival
+npm run typing-test   # typing pace and accuracy
+npm run instances-test
+npm run shutdown-test
+```
+
+See [docs/testing.md](docs/testing.md) for all test scripts. Tests use their own `ISPYX_*`/`WIN_INPUT_*` settings (own stop chord, own pipe) so they never interfere with a server you are using.
+
+## License
+
+Not yet decided. `package.json` currently says `UNLICENSED`.

package/config.example.json

@@ -0,0 +1,15 @@
+{
+  "denylist": [
+    "keepass.exe",
+    "keepassxc.exe",
+    "1password.exe",
+    "bitwarden.exe"
+  ],
+  "logPath": "logs/actions.jsonl",
+  "maxTypeLength": 10000,
+  "moveMinMs": 300,
+  "moveMaxMs": 1000,
+  "animations": true,
+  "overlay": true,
+  "auth": false
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "ispyx",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Local desktop-control MCP server: lets an AI use your keyboard, mouse and screen (windows, screenshots, clicks, typing, clipboard). stdio only, Windows and macOS.",
+  "type": "module",
+  "main": "src/server.js",
+  "bin": { "ispyx": "src/server.js" },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE",
+    "config.example.json"
+  ],
+  "engines": { "node": ">=22" },
+  "keywords": ["mcp", "model-context-protocol", "computer-use", "desktop-automation", "windows", "macos", "screenshot", "keyboard", "mouse", "claude"],
+  "repository": { "type": "git", "url": "git+https://github.com/murat-mehmet/ispyx.git" },
+  "bugs": { "url": "https://github.com/murat-mehmet/ispyx/issues" },
+  "homepage": "https://github.com/murat-mehmet/ispyx#readme",
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "node test/unit.js",
+    "smoke": "node test/smoke.js",
+    "chrome-test": "node test/chrome.js",
+    "instagram-test": "node test/instagram.js",
+    "motion-test": "node test/motion.js",
+    "stop-test": "node test/stop.js",
+    "instances-test": "node test/instances.js",
+    "hook-test": "node test/hook-life.js",
+    "shutdown-test": "node test/shutdown-all.js",
+    "scan-test": "node test/scan.js",
+    "radar-multi-test": "node test/radar-multi.js",
+    "scan-multi-test": "node test/scan-multi.js",
+    "auth-test": "node test/auth.js",
+    "typing-test": "node test/typing.js",
+    "core-test": "node test/core/effects-fake.js",
+    "ipc-test": "node test/core/ipc-unix.js",
+    "auth-panel-test": "node test/core/auth-panel.js",
+    "resident-test": "node test/core/resident-fake.js",
+    "darwin-test": "node test/darwin/client.js",
+    "tray-test": "node test/win32-tray.js",
+    "panel-test": "node test/panel.js"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "koffi": "^3.3.3",
+    "zod": "^4.6.7"
+  }
+}

package/src/core/RESIDENT.md

@@ -0,0 +1,45 @@
+# Resident model (Windows, and macOS inside Ispyx.app)
+
+On Windows ispyx is one resident app per user. On macOS Ispyx.app runs the same resident (`--resident`, started by
+the app, see `src/platform/darwin/PROTOCOL.md`) and its MCP launcher is `ispyx mcp`; there the app, not a tray icon,
+shows the panel (`platform.servePanel`) and owns start at login. npx on macOS, Linux and the fake platform keep the
+classic model (every process is an MCP server, one of them owns the pipe); nothing below applies to them unless a
+process is started with an explicit `--resident` / `mcp` argument (used by tests with `ISPYX_PLATFORM=fake`).
+
+| Command | Role |
+|---|---|
+| `ispyx` (console / shortcut) | Launcher. If a resident answers on the pipe: open the panel and exit. Otherwise start `ispyx --resident` detached and hidden, wait up to 10 s, open the panel, exit. |
+| `ispyx --resident` | The single owner of the pipe (`ipc.listenOwner`). Runs the guard, stop hotkey, effects, tool queue, tray and panel. No stdio. A second resident finds the pipe taken and exits at once (code 0). |
+| `ispyx mcp` | Thin stdio MCP server: same tool list and schemas, every call forwarded with `callOwner`. If no resident runs it starts one first (up to 10 s). If the resident dies mid-call the call returns a tool error. Keeps a watch connection so the resident's shutdown (second stop press, tray Quit) also ends it. |
+| `ispyx quit` | Ask the resident to exit. |
+| `ispyx` without a console on stdin | Old MCP registration pointing at `src/server.js`: behaves as `mcp`. |
+
+Mode selection is `src/core/mode.js`. Start/reach helpers are `src/core/launcher.js`; resident extras are
+`src/core/resident.js`.
+
+Logging: the resident writes nothing to stdout; stdout, stderr, `console.*` and uncaught errors go to
+`%APPDATA%\ispyx\ispyx.log` (rotated to `ispyx.log.1` at start when over 256 KB). The action log is unchanged.
+
+## Contracts with sibling modules
+
+All optional: a missing module is skipped.
+
+- `platform.Tray` (`src/platform/win32/tray.js`): `new Tray({ tooltip, onOpen, onQuit, getStatus })`, `.destroy()`.
+  `onOpen()` opens the panel in the default browser; `onQuit()` runs the shutdown-all path (tell every `mcp`
+  process to exit, release held keys, exit). `getStatus()` returns `{ text, clients, uptimeMs, stopLabel, effectsEnabled }`.
+- `platform.autostart` (`src/platform/win32/autostart.js`): `{ get(): boolean, set(bool): void }`.
+- `src/core/panel/index.js`: `startPanel({ getState, actions })` returns `{ url, close() }` (may be a promise).
+- `getState()` returns `{ version, platform, pid, uptimeMs, clients, recent: [{ time, tool, summary }], stopLabel,
+  effectsEnabled, passwordSet, denylist, autostart }`. `clients` is the number of connected `ispyx mcp` processes;
+  `recent` is the last 50 tool calls, newest first (typed text appears only as a length).
+- `actions` is `{ quit(), setAutostart(bool), setEffects(bool), clearRecent() }`.
+
+## Control calls
+
+Over the pipe, names starting with `__` are handled by the resident and never reach tools: `__ping` (`'pong'`),
+`__panel` (opens the panel window; it is started on demand and closed again two minutes after its window is gone), `__quit` (shuts down).
+
+## Environment
+
+`ISPYX_IDLE_EXIT_MS`: the resident exits when no `mcp` process has been connected for that many ms. Unset (default)
+means it never does; tests set it so an auto-started resident does not outlive them.

package/src/core/auth.js

@@ -0,0 +1,129 @@
+// Optional password gate. Off by default (config `auth`). When on, the first tool call opens a password
+// window; a correct password unlocks this server for a duration the user picks. The unlock is kept in memory
+// only, so every server start (every /mcp reconnect) asks again. No answer within 30 s closes the window and
+// the tool fails. Only a salted PBKDF2 hash is stored, never the password.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { ToolError } from './guard.js';
+import platform from '../platform/index.js';
+
+const UNIT_MIN = { minutes: 1, hours: 60, days: 1440 };
+const MAX_MIN = 365 * 1440;
+const MIN_PASSWORD = 6;
+const MAX_WRONG = 3;
+const ITER = 200000;
+
+/** A refusal whose message is meant for the person at the panel. */
+export class PasswordError extends Error { constructor(m) { super(m); this.expose = true; } }
+
+export const defaultAuthFile = () => path.join(platform.dataDir(), 'auth.json');
+
+export const toMinutes = (value, unit) => Math.min(MAX_MIN, Math.max(1, Math.round(Number(value) * (UNIT_MIN[unit] ?? 60))));
+
+/** Minutes -> the largest whole unit it fits, for the dialog's initial value. */
+export function fromMinutes(min) {
+  if (min % 1440 === 0 && min >= 2880) return { value: min / 1440, unit: 'days' };
+  if (min % 60 === 0) return { value: min / 60, unit: 'hours' };
+  return { value: min, unit: 'minutes' };
+}
+
+const hash = (pw, salt, iter) => crypto.pbkdf2Sync(pw, Buffer.from(salt, 'hex'), iter, 32, 'sha256').toString('hex');
+
+export class Auth {
+  /** `prompt(opts, ms)` is injectable so tests need no window. */
+  constructor({ enabled, file = defaultAuthFile(), timeoutMs = 30000 /* fixed for the server */, prompt = platform.showDialog, now = () => Date.now() }) {
+    Object.assign(this, { enabled, file, timeoutMs, prompt, now });
+    this.pending = null;
+    this.until = 0;
+    this.wrongTries = 0;
+    this.lockedUntil = 0;
+  }
+
+  read() {
+    try { return JSON.parse(fs.readFileSync(this.file, 'utf8')); } catch { return {}; }
+  }
+
+  write(data) {
+    fs.mkdirSync(path.dirname(this.file), { recursive: true });
+    fs.writeFileSync(this.file, JSON.stringify(data, null, 2));
+  }
+
+  passwordSet() {
+    return !!this.read().hash;
+  }
+
+  /** True when `pw` is the stored password. Three wrong tries lock further tries for 30 s (in memory). */
+  verify(pw) {
+    const data = this.read();
+    if (!data.hash) return false;
+    if (this.lockedUntil > this.now()) throw new PasswordError('Too many wrong passwords. Try again in a few seconds.');
+    const a = Buffer.from(hash(String(pw ?? ''), data.salt, data.iter), 'hex');
+    const ok = crypto.timingSafeEqual(a, Buffer.from(data.hash, 'hex'));
+    if (ok) { this.wrongTries = 0; return true; }
+    if (++this.wrongTries >= MAX_WRONG) { this.wrongTries = 0; this.lockedUntil = this.now() + 30000; }
+    return false;
+  }
+
+  /** Panel use: sets the first password, or changes it when `current` matches. Throws PasswordError with a plain message. */
+  setPassword(next, current) {
+    next = String(next ?? '');
+    if (next.length < MIN_PASSWORD) throw new PasswordError(`Password must be at least ${MIN_PASSWORD} characters.`);
+    if (this.passwordSet() && !this.verify(current)) throw new PasswordError('The current password is wrong.');
+    const data = this.read();
+    const salt = crypto.randomBytes(16).toString('hex');
+    Object.assign(data, { salt, iter: ITER, hash: hash(next, salt, ITER) });
+    this.write(data);
+  }
+
+  /** The unlock lives in memory only: every server start (and every /mcp reconnect) asks again. */
+  unlocked() {
+    return this.until > this.now();
+  }
+
+  /** Resolves when the server is unlocked; throws a plain message otherwise. Parallel calls share one window. */
+  async ensure() {
+    if (!this.enabled || this.unlocked()) return;
+    this.pending ??= this.ask().finally(() => { this.pending = null; });
+    await this.pending;
+  }
+
+  /**
+   * Each window waits 30 s. A wrong password reopens the window (up to 3 tries) without answering the tool;
+   * only after the third wrong one, a timeout or a cancel does the tool get an error.
+   */
+  async ask() {
+    let message = '';
+    let wrong = 0;
+    let chosen = null; // what the user last picked, kept when the window reopens
+    for (;;) {
+      const data = this.read();
+      const setup = !data.hash;
+      const dur = chosen ?? fromMinutes(data.defaultMinutes ?? 1440);
+      const r = await this.prompt({ mode: setup ? 'setup' : 'unlock', message, ...dur }, this.timeoutMs);
+      if (r.cancel) throw new ToolError(`Password was not entered (${r.reason || 'window closed'}), so the action was refused. Ask the user to enter it, then try again.`);
+      chosen = { value: r.value, unit: r.unit };
+      const pw = String(r.password ?? '');
+      if (setup) {
+        if (pw.length < MIN_PASSWORD) { message = `Password must be at least ${MIN_PASSWORD} characters.`; continue; }
+        if (pw !== r.confirm) { message = 'The two passwords do not match.'; continue; }
+        const salt = crypto.randomBytes(16).toString('hex');
+        Object.assign(data, { salt, iter: ITER, hash: hash(pw, salt, ITER) });
+      } else {
+        const a = Buffer.from(hash(pw, data.salt, data.iter), 'hex');
+        const b = Buffer.from(data.hash, 'hex');
+        if (!crypto.timingSafeEqual(a, b)) {
+          if (++wrong >= MAX_WRONG) throw new ToolError(`The wrong password was entered ${MAX_WRONG} times, so the action was refused. Ask the user to try again.`);
+          message = `Wrong password (${MAX_WRONG - wrong} ${MAX_WRONG - wrong === 1 ? 'try' : 'tries'} left).`;
+          continue;
+        }
+      }
+      const minutes = toMinutes(r.value, r.unit);
+      this.until = this.now() + minutes * 60000;
+      delete data.unlockedUntil; // older versions kept the unlock on disk
+      if (r.makeDefault) data.defaultMinutes = minutes;
+      this.write(data);
+      return;
+    }
+  }
+}