ispyx 1.0.7 → 1.1.0

package/README.md

@@ -2,6 +2,8 @@
 
 # ispyx
 
+<p align="center"><a href="docs/showcase/ispyx-demo.mp4"><img src="docs/showcase/ispyx-demo.gif" alt="ispyx demo: an AI clicks, drags cards between columns, types and scrolls while an eye fires a beam at the pointer" width="720"></a></p>
+
 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, move the mouse, click, drag, scroll, type, press hotkeys and use the clipboard.
 
 - Runs on your machine, talks to the AI app over **stdio**, opens **no network port** (the settings panel only listens while it is open).

package/native/win32-unlock/provider/install.ps1

@@ -0,0 +1,84 @@
+# Elevated setup step for the "let the AI unlock this PC" feature. Run by src/platform/win32/unlock.js via
+# Start-Process -Verb RunAs (one UAC prompt, per docs/unlock-windows.md). Never called with the password as a
+# plain argument: SecretFile is a path to a temp file (domain\nusername\npassword) that this script reads once
+# and deletes, so the password never appears in a process command line (visible via Task Manager / WMI).
+# ResultFile: Start-Process -Verb RunAs runs this in its own console with no stdout/stderr redirection back to
+# the caller (confirmed: -RedirectStandardOutput is rejected together with -Verb, same as -WindowStyle), so the
+# only way the caller learns what happened is this file.
+param(
+    [Parameter(Mandatory)][string]$SecretFile,
+    [Parameter(Mandatory)][string]$DllPath,
+    [Parameter(Mandatory)][string]$ResultFile
+)
+Set-StrictMode -Version 2
+$ErrorActionPreference = 'Stop'
+
+try {
+    $lines = Get-Content -Path $SecretFile -Encoding UTF8
+    $domain = $lines[0]
+    $username = $lines[1]
+    $password = $lines[2]
+    if ([string]::IsNullOrEmpty($domain)) { $domain = $env:COMPUTERNAME }
+    if ([string]::IsNullOrEmpty($username) -or [string]::IsNullOrEmpty($password)) {
+        throw 'Missing username or password.'
+    }
+
+    Add-Type -AssemblyName System.Security
+
+    $root = 'C:\ProgramData\ispyx'
+    New-Item -ItemType Directory -Force -Path $root | Out-Null
+    icacls $root /inheritance:r | Out-Null
+    icacls $root /grant 'SYSTEM:(OI)(CI)F' 'Administrators:(OI)(CI)F' | Out-Null
+
+    function Write-LenPrefixed([System.IO.MemoryStream]$ms, [string]$s) {
+        $bytes = [System.Text.Encoding]::UTF8.GetBytes($s)
+        $ms.Write([BitConverter]::GetBytes([uint32]$bytes.Length), 0, 4)
+        $ms.Write($bytes, 0, $bytes.Length)
+    }
+    $ms = New-Object System.IO.MemoryStream
+    Write-LenPrefixed $ms $domain
+    Write-LenPrefixed $ms $username
+    Write-LenPrefixed $ms $password
+    $plain = $ms.ToArray()
+    $protected = [System.Security.Cryptography.ProtectedData]::Protect($plain, $null, [System.Security.Cryptography.DataProtectionScope]::LocalMachine)
+    [Array]::Clear($plain, 0, $plain.Length) # best effort; managed GC may have copied it already
+
+    $secretPath = Join-Path $root 'unlock.secret'
+    [System.IO.File]::WriteAllBytes($secretPath, $protected)
+    icacls $secretPath /inheritance:r | Out-Null
+    icacls $secretPath /grant 'SYSTEM:F' 'Administrators:F' | Out-Null
+
+    # The resident (this same user, not elevated day to day) needs write access to just this one file. (A
+    # named Win32 event was tried here instead, to drop the watcher's poll loop entirely -- reverted: a named
+    # kernel object only exists while some process holds a handle open, and nothing in this architecture runs
+    # continuously between an enable() and a much later signal() to be that holder. See docs/unlock-windows.md.
+    # The watcher still avoids polling, via FindFirstChangeNotificationW on this directory instead.)
+    $signalPath = Join-Path $root 'unlock.signal'
+    if (-not (Test-Path $signalPath)) { New-Item -ItemType File -Path $signalPath | Out-Null }
+    $me = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
+    icacls $signalPath /inheritance:r | Out-Null
+    icacls $signalPath /grant 'SYSTEM:F' 'Administrators:F' "${me}:M" | Out-Null
+
+    # regsvr32's exit code is not trustworthy with /s (confirmed in docs/unlock-windows.md); verify by reading
+    # the registry back instead of trusting $LASTEXITCODE.
+    # LogonUI loads this DLL as SYSTEM, so it must live somewhere only admins can write -- never in the npm
+    # package dir (user-writable): that would let any local user swap it and get code running as SYSTEM.
+    $installedDll = Join-Path $root 'ispyx_unlock.dll'
+    try { Copy-Item -Path $DllPath -Destination $installedDll -Force } catch {
+        # Already loaded by LogonUI from a previous install: keep it if it is byte-identical.
+        if (-not (Test-Path $installedDll) -or (Get-FileHash $installedDll).Hash -ne (Get-FileHash $DllPath).Hash) { throw }
+    }
+    regsvr32.exe /s $installedDll 2>$null
+    $actual = (Get-ItemProperty -Path 'HKLM:\SOFTWARE\Classes\CLSID\{1aa7e1e6-21de-4ad5-ae6e-454401b4b427}\InprocServer32' -Name '(default)' -ErrorAction SilentlyContinue).'(default)'
+    if ($actual -ne $installedDll) {
+        throw "Registration did not take effect (registry has '$actual', expected '$installedDll')."
+    }
+
+    Set-Content -Path $ResultFile -Value 'OK' -NoNewline
+    exit 0
+} catch {
+    Set-Content -Path $ResultFile -Value "ERROR: $($_.Exception.Message)" -NoNewline
+    exit 1
+} finally {
+    Remove-Item -Path $SecretFile -Force -ErrorAction SilentlyContinue
+}

package/native/win32-unlock/provider/uninstall.ps1

@@ -0,0 +1,17 @@
+# Elevated teardown for the "let the AI unlock this PC" feature: unregisters the Credential Provider and deletes
+# the stored secret and the installed DLL copy. Run by src/platform/win32/unlock.js via Start-Process -Verb
+# RunAs. See install.ps1 for why ResultFile exists (no stdout/stderr redirection back to the caller with -Verb RunAs).
+param(
+    [Parameter(Mandatory)][string]$ResultFile
+)
+Set-StrictMode -Version 2
+$ErrorActionPreference = 'Continue' # best effort: still clean up what we can if one step fails
+
+$root = 'C:\ProgramData\ispyx'
+regsvr32.exe /u /s (Join-Path $root 'ispyx_unlock.dll') 2>$null
+Remove-Item -Path (Join-Path $root 'unlock.secret') -Force -ErrorAction SilentlyContinue
+Remove-Item -Path (Join-Path $root 'unlock.signal') -Force -ErrorAction SilentlyContinue
+# May be held open by a running LogonUI until the next lock cycle; harmless once unregistered.
+Remove-Item -Path (Join-Path $root 'ispyx_unlock.dll') -Force -ErrorAction SilentlyContinue
+Set-Content -Path $ResultFile -Value 'OK' -NoNewline
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ispyx",
-  "version": "1.0.7",
+  "version": "1.1.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",
@@ -9,6 +9,9 @@
   },
   "files": [
     "src/",
+    "native/win32-unlock/bin/",
+    "native/win32-unlock/provider/install.ps1",
+    "native/win32-unlock/provider/uninstall.ps1",
     "README.md",
     "LICENSE",
     "config.example.json"

package/src/core/panel/README.md

@@ -31,6 +31,7 @@ Only `version` and `platform` are required. Every other key is optional and the
   recent: [{ time, tool, summary }],          // time = epoch ms
   stopLabel,                                  // e.g. "Esc x3" or "⌥ Option + Esc"
   effectsEnabled, passwordSet, denylist: [],
+  unlockSupported, unlockEnabled,             // win32 only: "Let the AI unlock this PC"
   autostart: boolean, autostartLabel?,        // label defaults by platform
   permissions: [{ id: 'accessibility' | 'screen-recording', title, detail, granted }],
   connect: { claudeCodeCommand, desktopConfigJson, desktopConfigPath } }
@@ -51,6 +52,7 @@ Sections, top to bottom: header (icon, headline, status, version/uptime/pid), Pe
 | `openPermissionSettings` | permission id | "Open Settings" |
 | `showConfigFile` | none | reveal `desktopConfigPath` (or its folder) |
 | `copy` | text | clipboard fallback; the page tries `navigator.clipboard` first |
+| `setUnlock` | `{on, password, current}` | win32 only; "Let the AI unlock this PC". Always the resident's own account. `current` is the ispyx panel password, asked for when one is set (same as `removeDeny`) |
 
 ## Windows server (`index.js`)
 

package/src/core/panel/index.js

@@ -8,14 +8,14 @@ import { fileURLToPath } from 'node:url';
 const PAGE = fileURLToPath(new URL('./page.html', import.meta.url));
 const COOKIE = 'ispyx_panel';
 // Explicit whitelist; an action is also callable only if the host's `actions` object defines it.
-const ACTIONS = ['quit', 'setAutostart', 'setEffects', 'openLog', 'copy', 'close', 'requestPermission', 'openPermissionSettings', 'showConfigFile', 'clearRecent', 'addDeny', 'removeDeny', 'setPassword', 'setAuthRequired', 'update', 'checkUpdate'];
+const ACTIONS = ['quit', 'setAutostart', 'setEffects', 'openLog', 'copy', 'close', 'requestPermission', 'openPermissionSettings', 'showConfigFile', 'clearRecent', 'addDeny', 'removeDeny', 'setPassword', 'setAuthRequired', 'setUnlock', 'update', 'checkUpdate'];
 const BOOL_ACTIONS = new Set(['setAutostart', 'setEffects']);
 const STRING_ACTIONS = new Set(['copy', 'requestPermission', 'openPermissionSettings', 'addDeny']); // value must be a short string
-// value is an object of short strings (and a boolean for setAuthRequired.on)
-const OBJECT_ACTIONS = { setPassword: ['current', 'next'], setAuthRequired: ['current'], removeDeny: ['name', 'current'] };
+// value is an object of short strings (and a boolean for setAuthRequired.on / setUnlock.on)
+const OBJECT_ACTIONS = { setPassword: ['current', 'next'], setAuthRequired: ['current'], removeDeny: ['name', 'current'], setUnlock: ['password', 'current'] };
 const objectOk = (name, v) => {
   if (!v || typeof v !== 'object' || Array.isArray(v)) return false;
-  if (name === 'setAuthRequired' && typeof v.on !== 'boolean') return false;
+  if ((name === 'setAuthRequired' || name === 'setUnlock') && typeof v.on !== 'boolean') return false;
   return OBJECT_ACTIONS[name].every((k) => v[k] === undefined || (typeof v[k] === 'string' && v[k].length <= 200));
 };
 const PERMISSION_IDS = new Set(['accessibility', 'screen-recording']);

package/src/core/panel/page.html

@@ -156,6 +156,14 @@ button.link:hover{background:none;color:var(--fg)}
   </div>
 </section>
 
+<section id="sUnlock" hidden>
+  <h2>Unattended unlock</h2>
+  <div class="card">
+    <div class="item line" id="rUnlock" hidden><label for="unlockOn">Let the AI unlock this PC</label><span class="sw"><input type="checkbox" id="unlockOn"><i></i></span></div>
+    <div class="item" id="rUnlockNote" hidden><p class="note">Weakens the lock screen on purpose: stores this account's Windows password so the AI can unlock a locked session without you there. Needs a local account with a password (not a Microsoft-account PIN sign-in).</p></div>
+  </div>
+</section>
+
 <dialog id="dlg">
   <form id="dlgForm">
     <h3 id="dlgT"></h3>
@@ -317,6 +325,10 @@ function render(s){
   show("sSafe",hasPw||hasDeny||hasAuth);show("rPw",hasPw);show("rAuth",hasAuth);show("rDeny",hasDeny);
   if(hasPw){setText("pwTxt",s.passwordSet?"Password is set":"No password yet");setText("pwBtn",s.passwordSet?"Change…":"Set…")}
   if(hasAuth&&!busy.authOn)$("authOn").checked=s.authRequired;
+
+  var hasUnlock=typeof s.unlockSupported==="boolean";
+  show("sUnlock",hasUnlock);show("rUnlock",hasUnlock);show("rUnlockNote",hasUnlock);
+  if(hasUnlock&&!busy.unlockOn)$("unlockOn").checked=!!s.unlockEnabled;
   if(hasDeny){
     var d=$("deny"),sig=s.denylist.join("\n")+"|"+!!s.passwordSet;
     if(d.dataset.sig!==sig){ // rebuild only on change so a click is never lost to the 1 s refresh
@@ -417,6 +429,22 @@ $("authOn").addEventListener("change",function(){
   }
   act("setAuthRequired",{on:want,current:undefined}).catch(function(){box.checked=!want}).then(done);
 });
+$("unlockOn").addEventListener("change",function(){
+  var want=$("unlockOn").checked,box=$("unlockOn");
+  busy.unlockOn=true;
+  var done=function(){busy.unlockOn=false;poll()};
+  if(want){
+    box.checked=false;
+    ask("Let the AI unlock this PC",[{id:"password",label:"Windows password"}],"Turn on",function(v){return act("setUnlock",{on:true,password:v.password})});
+    done();return;
+  }
+  if(last&&last.passwordSet){
+    box.checked=true;
+    ask("Turn off unattended unlock",[{id:"current",label:"Ispyx password"}],"Turn off",function(v){return act("setUnlock",{on:false,current:v.current})});
+    done();return;
+  }
+  act("setUnlock",{on:false}).catch(function(){box.checked=true}).then(done);
+});
 function removeDeny(name){
   if(last&&last.passwordSet){
     ask("Remove "+name,[{id:"current",label:"Password"}],"Remove",function(v){return act("removeDeny",{name:name,current:v.current})});

package/src/core/resident.js

@@ -11,8 +11,10 @@
 //   ./panel/index.js     startPanel({ getState, actions }) -> { url, close() }   (local web panel)
 //
 //   getState() -> { version, platform, pid, uptimeMs, clients, recent: [{ time, tool, summary }],
-//                   stopLabel, effectsEnabled, passwordSet, denylist, autostart, connect (win32) }
-//   actions    -> { quit(), setAutostart(bool), setEffects(bool), clearRecent(), showConfigFile() }
+//                   stopLabel, effectsEnabled, passwordSet, denylist, autostart, connect (win32),
+//                   unlockSupported, unlockEnabled (win32 only, when platform.unlock exists) }
+//   actions    -> { quit(), setAutostart(bool), setEffects(bool), clearRecent(), showConfigFile(),
+//                   setUnlock({on, password, current}) (win32 only) }
 //
 // Control calls over the pipe (names start with "__", handled here, never reach the tools):
 //   __ping -> 'pong'      __panel -> panel url ('' if none)      __quit -> 'bye' and the resident shuts down.
@@ -139,6 +141,7 @@ export function panelModel(ctx) {
     passwordSet: safe(() => auth.passwordSet(), false),
     authRequired: !!config.auth,
     denylist: config.denylist.slice(),
+    ...(w.unlock ? { unlockSupported: true, unlockEnabled: safe(() => w.unlock.isEnabled(), false) } : {}),
     ...(updates.state() ? { update: { ...updates.state(), ...(running ? running.progress() : {}) } } : {}),
   });
   const actions = {
@@ -176,6 +179,16 @@ export function panelModel(ctx) {
       return true;
     },
     checkUpdate: async () => { await updates.check(); return updates.state(); },
+    // Turning this on lowers the lock screen's protection, so it asks for the ispyx password when one is set,
+    // same as removeDeny. w.unlock.enable/disable throw a plain message (wrong account type, UAC cancelled, ...).
+    setUnlock: async ({ on, password, current } = {}) => {
+      if (!w.unlock) throw new PanelError('Not available on this platform.');
+      if (auth.passwordSet() && !auth.verify(current)) throw new PanelError('The password is wrong.');
+      try {
+        if (on) await w.unlock.enable({ password });
+        else await w.unlock.disable();
+      } catch (e) { throw new PanelError(e.message); }
+    },
   };
   return { getState, actions, stop: () => updates.stop() };
 }

package/src/core/server.js

@@ -812,6 +812,21 @@ server.registerTool('set_clipboard', {
   return json({ ok: true, kind: 'file', path: p });
 }, { session: false }));
 
+server.registerTool('unlock', {
+  description: 'Unlocks the Windows session if it is currently locked, using the account password stored earlier in the panel ("Let the AI unlock this PC"). Takes no input. Fails if that feature was never turned on, or if the screen is not actually locked.',
+}, action('unlock', async () => {
+  if (!w.unlock) throw new ToolError('Unattended unlock is not available on this platform.');
+  if (!w.unlock.isEnabled()) throw new ToolError('Unattended unlock was never turned on. Ask the user to enable "Let the AI unlock this PC" in the panel.');
+  if (!w.isScreenLocked()) return json({ ok: true, alreadyUnlocked: true });
+  w.unlock.signal();
+  const deadline = Date.now() + 10000;
+  while (Date.now() < deadline) {
+    await w.sleep(300);
+    if (!w.isScreenLocked()) return json({ ok: true });
+  }
+  throw new ToolError('Signalled the unlock but the screen is still locked after 10 s. The stored password may be wrong, or the account may no longer qualify.');
+}, { session: false }));
+
 // ---------------------------------------------------------------- run
 
 process.on('exit', () => guard?.releaseAll());

package/src/platform/CONTRACT.md

@@ -129,3 +129,9 @@ Other platforms may lack these; callers must feature-test (`if (platform.Tray)`)
   Quit. Methods: `setTooltip(s)`, `destroy()`. Re-adds itself when Explorer restarts. Callbacks never throw into the host.
 - `autostart` `{ get(), set(on), command() }`: per-user HKCU Run entry `Ispyx` that starts `src/server.js` hidden
   via `wscript.exe` + `%APPDATA%\ispyx\start.vbs`. `ISPYX_AUTOSTART_VALUE` overrides the value name (tests).
+- `unlock` (`src/platform/win32/unlock.js`): `{ isEnabled(), checkAccount(), enable({password}), disable(), signal() }`.
+  "Let the AI unlock this PC" (see `docs/unlock-windows.md`). Only ever unlocks the account the resident itself
+  runs as, so `enable` asks for just the password. `enable`/`disable` run an
+  elevated `.ps1` in `native/win32-unlock/provider/` (one UAC prompt each); `signal()` never needs elevation.
+  `checkAccount()` refuses PIN/Microsoft-account and passwordless sign-ins (no replayable secret exists for
+  those). The `unlock` MCP tool (`src/core/server.js`) calls `signal()` then polls `isScreenLocked()`.

package/src/platform/win32/index.js

@@ -28,4 +28,5 @@ export const dataDir = () => {
 };
 export { Layer, textMask } from './layer.js';
 export { Tray } from './tray.js';
+export * as unlock from './unlock.js';
 export { autostart } from './autostart.js';

package/src/platform/win32/unlock.js

@@ -0,0 +1,140 @@
+// Optional win32 feature: "Let the AI unlock this PC" (see docs/unlock-windows.md for the full design and what
+// was validated). All native work lives in native/win32-unlock/provider (Rust Credential Provider COM DLL,
+// built separately, not part of this package's install) and its install.ps1/uninstall.ps1, each one elevated
+// UAC prompt, never run automatically.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = 'C:\\ProgramData\\ispyx';
+const SECRET_PATH = path.join(ROOT, 'unlock.secret');
+const SIGNAL_PATH = path.join(ROOT, 'unlock.signal');
+const PROVIDER_DIR = fileURLToPath(new URL('../../../native/win32-unlock/provider/', import.meta.url));
+const DLL_PATH = fileURLToPath(new URL('../../../native/win32-unlock/bin/ispyx_unlock.dll', import.meta.url));
+
+function run(cmd, args) {
+  return new Promise((resolve) => {
+    const p = spawn(cmd, args, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '', err = '';
+    p.stdout.on('data', (d) => { out += d; });
+    p.stderr.on('data', (d) => { err += d; });
+    p.on('close', (code) => resolve({ code, out, err }));
+    p.on('error', (e) => resolve({ code: -1, out, err: e.message }));
+  });
+}
+
+/**
+ * Runs a .ps1 elevated (one UAC prompt) and waits for it. Resolves { code, out }.
+ * -WindowStyle cannot be combined with -Verb RunAs in Windows PowerShell 5.1 (Start-Process throws a parameter
+ * error before the UAC prompt even appears) -- confirmed hitting exactly this, so it is deliberately omitted.
+ */
+function runElevated(scriptPath, args) {
+  const psArgs = ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', scriptPath, ...args];
+  const quoted = psArgs.map((a) => `'${String(a).replace(/'/g, "''")}'`).join(',');
+  const outer = `try { $p = Start-Process -FilePath powershell.exe -Verb RunAs -Wait -PassThru -ArgumentList @(${quoted}); exit $p.ExitCode } catch { Write-Output "ELEVATE-FAILED: $($_.Exception.Message)"; exit 1 }`;
+  return run('powershell.exe', ['-NoProfile', '-Command', outer]);
+}
+
+/**
+ * Runs an elevated .ps1 that takes a trailing -ResultFile path and writes 'OK' or 'ERROR: ...' there (the
+ * elevated child's own stdout/stderr never reaches this process -- see install.ps1's header comment). Resolves
+ * { ok, message }.
+ */
+async function runElevatedScript(scriptPath, args) {
+  const resultFile = path.join(os.tmpdir(), `ispyx-unlock-result-${crypto.randomBytes(8).toString('hex')}.tmp`);
+  try {
+    const { out } = await runElevated(scriptPath, [...args, resultFile]);
+    let result = '';
+    try { result = fs.readFileSync(resultFile, 'utf8'); } catch { /* elevation itself never ran the script */ }
+    if (result) {
+      return result.startsWith('ERROR:') ? { ok: false, message: result.slice(6).trim() } : { ok: true, message: result };
+    }
+    const outer = out.trim().split('\n').pop() || '';
+    return { ok: false, message: outer.replace(/^ELEVATE-FAILED:\s*/, '') || 'Setup was cancelled or failed.' };
+  } finally {
+    try { fs.unlinkSync(resultFile); } catch { /* did not get created, or the script already removed it */ }
+  }
+}
+
+/**
+ * `fs.existsSync` returns false on ANY stat error, not just "missing" -- and the secret file's ACL (by design,
+ * see install.ps1) denies read to this account's normal, non-elevated token, which is exactly the context the
+ * resident always runs in. So existsSync would report "not enabled" right after a successful install. statSync
+ * + checking the error code distinguishes "really missing" (ENOENT) from "there, just can't read it" (anything
+ * else) -- confirmed hitting this directly: a real install left this returning false until fixed.
+ */
+export function isEnabled() {
+  try {
+    fs.statSync(SECRET_PATH);
+    return true;
+  } catch (e) {
+    return e.code !== 'ENOENT';
+  }
+}
+
+/**
+ * Local-account check (see docs/unlock-windows.md "Known gaps" for why PIN/Microsoft-account and passwordless
+ * accounts cannot work here). Resolves { ok: true } or { ok: false, reason }.
+ *
+ * Deliberately does NOT try to detect "no password set" up front: the one signal Windows exposes for that,
+ * UserFlags' UF_PASSWD_NOTREQD bit ("net user"'s "Password required"), means the password-policy check is
+ * waived for this account, not that the password is blank -- confirmed a false positive on a real account with
+ * a working password. A wrong/blank stored secret is already caught safely at unlock time (one attempt, no
+ * retry -- see credential.rs), so there is no need to predict it here.
+ */
+export async function checkAccount() {
+  const ps = `
+    $src = $null
+    try { $src = (Get-LocalUser -Name $env:USERNAME -ErrorAction Stop).PrincipalSource.ToString() } catch {}
+    [PSCustomObject]@{ principalSource = $src } | ConvertTo-Json -Compress
+  `;
+  const { code, out } = await run('powershell.exe', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', ps]);
+  if (code !== 0) return { ok: false, reason: 'Could not check the account type.' };
+  let info;
+  try { info = JSON.parse(out.trim().split('\n').pop()); } catch { return { ok: false, reason: 'Could not check the account type.' }; }
+  if (info.principalSource && info.principalSource !== 'Local') {
+    return { ok: false, reason: 'This looks like a Microsoft-account or PIN-only sign-in. Unattended unlock only supports a local account with a password.' };
+  }
+  return { ok: true };
+}
+
+/**
+ * Panel action: writes the DPAPI secret and registers the Credential Provider (one UAC prompt). Only the
+ * password is asked for in the panel -- the account is always the one the resident itself runs as, since that
+ * is the only session this mechanism can ever unlock.
+ */
+export async function enable({ password }) {
+  if (!password) throw new Error('Enter the Windows account password.');
+  const check = await checkAccount();
+  if (!check.ok) throw new Error(check.reason);
+  const username = os.userInfo().username;
+  const domain = process.env.USERDOMAIN || '';
+  const tmp = path.join(os.tmpdir(), `ispyx-unlock-${crypto.randomBytes(8).toString('hex')}.tmp`);
+  fs.writeFileSync(tmp, `${domain}\n${username}\n${password}\n`);
+  try {
+    const r = await runElevatedScript(path.join(PROVIDER_DIR, 'install.ps1'), [tmp, DLL_PATH]);
+    if (!r.ok) throw new Error(r.message);
+  } finally {
+    try { fs.unlinkSync(tmp); } catch { /* install.ps1 deletes it too either way */ }
+  }
+}
+
+/** Panel action: unregisters the Credential Provider and deletes the stored secret (one UAC prompt). */
+export async function disable() {
+  const r = await runElevatedScript(path.join(PROVIDER_DIR, 'uninstall.ps1'), []);
+  if (!r.ok) throw new Error(r.message);
+}
+
+/**
+ * Called by the `unlock` tool while the screen is locked: touches the signal file the Credential Provider
+ * watches (a named Win32 event was tried instead, to drop the watcher's poll loop entirely -- reverted, see
+ * docs/unlock-windows.md: a named kernel object only exists while some process holds a handle open, and
+ * nothing here runs continuously between an enable() and a much later signal() to be that holder). Never
+ * needs elevation -- the install step already granted this account write access to this one file.
+ */
+export function signal() {
+  fs.writeFileSync(SIGNAL_PATH, '1');
+}