stikfix 1.2.0

package/dist/host/src/bootstrap/register.js

@@ -0,0 +1,556 @@
+/**
+ * Native-messaging manifest writer, per-OS path resolver, Windows registry
+ * registration, uninstall enumerator, and desktop launcher creator for stikfix.
+ *
+ * Node builtins only — no WXT, no Chrome imports.
+ *
+ * Security:
+ * - T-09-02: buildManifest resolves an ABSOLUTE path (Pitfall 4)
+ * - T-09-03: Windows registry writes use HKCU (Pitfall 5), execFileSync (never exec)
+ * - T-09-05: enumerateArtifacts lists every init-created artifact (ONB-05)
+ * - Launcher shortcut: execFile(powershell, [argArray]) — NEVER exec or shell interpolation
+ *
+ * Analog: host/src/config.ts (mkdirSync/writeFileSync/existsSync/rmSync patterns)
+ */
+import { mkdirSync, writeFileSync, rmSync, chmodSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { isInsideDir } from '../security.js';
+// The native host name — must match the manifest JSON `name` field and the
+// value passed to chrome.runtime.sendNativeMessage in background.ts.
+const NATIVE_HOST_NAME = 'com.stikfix.host';
+const MANIFEST_FILENAME = `${NATIVE_HOST_NAME}.json`;
+// On Windows the Firefox manifest shares the stikfix data dir with the Chrome
+// one, so it needs a distinct filename to avoid clobbering the Chrome manifest.
+// (On macOS/Linux Firefox uses a separate Mozilla dir, so this filename only
+// differs the win32 on-disk JSON; the registry value points straight at it.)
+const FIREFOX_MANIFEST_FILENAME = `${NATIVE_HOST_NAME}.firefox.json`;
+// Native-messaging launcher wrapper file names. On Windows, Chrome launches the
+// native host via CreateProcess, which cannot execute a .cjs directly — so the
+// manifest must point at a wrapper that runs `node <abs cjs>`.
+const NATIVE_WRAPPER_WIN = `${NATIVE_HOST_NAME}.bat`;
+const NATIVE_WRAPPER_NIX = `${NATIVE_HOST_NAME}.sh`;
+// Firefox wrapper file names — MUST be distinct from the Chrome wrapper. On
+// Windows both browsers share the stikfix data dir, so a shared wrapper file
+// would be deleted by a Firefox uninstall and break a co-installed Chrome whose
+// manifest still references that absolute path (cross-browser regression). The
+// suffix mirrors FIREFOX_MANIFEST_FILENAME so manifest+wrapper stay paired.
+const NATIVE_WRAPPER_WIN_FIREFOX = `${NATIVE_HOST_NAME}.firefox.bat`;
+const NATIVE_WRAPPER_NIX_FIREFOX = `${NATIVE_HOST_NAME}.firefox.sh`;
+// Chrome/Edge registry key prefixes (Windows HKCU — Pitfall 5: never HKLM)
+const REG_CHROME_KEY = `HKCU\\Software\\Google\\Chrome\\NativeMessagingHosts\\${NATIVE_HOST_NAME}`;
+const REG_EDGE_KEY = `HKCU\\Software\\Microsoft\\Edge\\NativeMessagingHosts\\${NATIVE_HOST_NAME}`;
+// Firefox registry key prefix (Windows HKCU — same HKCU rule as Chrome/Edge)
+const REG_FIREFOX_KEY = `HKCU\\Software\\Mozilla\\NativeMessagingHosts\\${NATIVE_HOST_NAME}`;
+// The default add-on id used by the Firefox path. Must match
+// browser_specific_settings.gecko.id in wxt.config.ts and the
+// allowed_extensions entry in the Firefox native-messaging manifest.
+export const DEFAULT_GECKO_ID = 'stikfix@stikfix.com';
+// Config file location (read by native host at startup)
+const CONFIG_DIR = (home) => join(home, '.config', 'stikfix');
+const CONFIG_PATH = (home) => join(CONFIG_DIR(home), 'config.json');
+// Launcher file names used across functions
+const LAUNCHER_BATCH_FILENAME = 'stikfix-host.bat';
+const LAUNCHER_VBS_FILENAME = 'stikfix-host.vbs';
+const LAUNCHER_LNK_FILENAME = 'Stikfix Host.lnk';
+const LAUNCHER_COMMAND_FILENAME = 'stikfix-host.command';
+const LAUNCHER_DESKTOP_FILENAME = 'stikfix-host.desktop';
+const LAUNCHER_SH_FILENAME = 'stikfix-host.sh';
+// ---------------------------------------------------------------------------
+// nativeManifestPath — per-OS path resolver
+// ---------------------------------------------------------------------------
+/**
+ * Return the absolute path where the native-messaging manifest JSON should
+ * be written for the given platform and home directory.
+ *
+ * Paths verified via Chrome + Edge native-messaging docs (RESEARCH Pattern 4):
+ *   darwin: ~/Library/App Support/Google/Chrome/NativeMessagingHosts/
+ *   linux:  ~/.config/google-chrome/NativeMessagingHosts/
+ *   win32:  ~/.local/share/stikfix/  (manifest only; registry key written separately)
+ */
+export function nativeManifestPath(plat = process.platform, home = homedir(), browser = 'chrome') {
+    if (browser === 'firefox') {
+        switch (plat) {
+            case 'darwin':
+                return join(home, 'Library', 'Application Support', 'Mozilla', 'NativeMessagingHosts', MANIFEST_FILENAME);
+            case 'linux':
+                return join(home, '.mozilla', 'native-messaging-hosts', MANIFEST_FILENAME);
+            case 'win32':
+                // Windows: the manifest JSON lives on disk in the stikfix data dir
+                // (same place as the Chrome one would, but a distinct filename via the
+                // firefox suffix so both can coexist); the registry key points at it.
+                return join(home, '.local', 'share', 'stikfix', FIREFOX_MANIFEST_FILENAME);
+            default:
+                throw new Error(`Unsupported platform: ${plat}`);
+        }
+    }
+    switch (plat) {
+        case 'darwin':
+            return join(home, 'Library', 'Application Support', 'Google', 'Chrome', 'NativeMessagingHosts', MANIFEST_FILENAME);
+        case 'linux':
+            return join(home, '.config', 'google-chrome', 'NativeMessagingHosts', MANIFEST_FILENAME);
+        case 'win32':
+            return join(home, '.local', 'share', 'stikfix', MANIFEST_FILENAME);
+        default:
+            throw new Error(`Unsupported platform: ${plat}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// nativeWrapperPath / writeNativeWrapper — native-messaging launcher wrapper
+// ---------------------------------------------------------------------------
+/**
+ * Return the path of the native-messaging launcher wrapper, in the SAME
+ * directory as the manifest. On win32 a .bat, otherwise a .sh.
+ */
+export function nativeWrapperPath(plat = process.platform, home = homedir(), browser = 'chrome') {
+    const dir = dirname(nativeManifestPath(plat, home, browser));
+    const winName = browser === 'firefox' ? NATIVE_WRAPPER_WIN_FIREFOX : NATIVE_WRAPPER_WIN;
+    const nixName = browser === 'firefox' ? NATIVE_WRAPPER_NIX_FIREFOX : NATIVE_WRAPPER_NIX;
+    return join(dir, plat === 'win32' ? winName : nixName);
+}
+/**
+ * Write the per-OS launcher wrapper that runs `node <abs cjs>`, returning its
+ * path. Chrome's CreateProcess (Windows) cannot execute a .cjs directly; the
+ * manifest must point at this wrapper instead of the raw .cjs.
+ *
+ * Security: `abs` is a developer-controlled absolute path (no user input);
+ * this is a file write, not exec — no injection vector.
+ */
+export function writeNativeWrapper(hostBinPath, plat = process.platform, home = homedir(), browser = 'chrome') {
+    const wrapperPath = nativeWrapperPath(plat, home, browser);
+    mkdirSync(dirname(wrapperPath), { recursive: true });
+    const abs = resolve(hostBinPath);
+    if (plat === 'win32') {
+        const content = `@echo off\r\n"node" "${abs}" %*\r\n`;
+        writeFileSync(wrapperPath, content, { encoding: 'utf8' });
+    }
+    else {
+        const content = `#!/bin/sh\nexec node "${abs}" "$@"\n`;
+        writeFileSync(wrapperPath, content, { encoding: 'utf8', mode: 0o755 });
+    }
+    return wrapperPath;
+}
+// ---------------------------------------------------------------------------
+// launcherDir — where launcher files are stored (alongside the manifest on win32)
+// ---------------------------------------------------------------------------
+/**
+ * Return the directory where launcher files (batch, .command, .desktop) are written.
+ * On win32: ~/.local/share/stikfix/ (same dir as the manifest)
+ * On darwin/linux: ~/.config/stikfix/
+ */
+export function launcherDir(plat = process.platform, home = homedir()) {
+    if (plat === 'win32') {
+        return join(home, '.local', 'share', 'stikfix');
+    }
+    return join(home, '.config', 'stikfix');
+}
+/**
+ * Return the expected paths of all launcher files for the given platform.
+ * These paths are used by both createLauncherFiles and enumerateArtifacts.
+ */
+export function getLauncherPaths(plat = process.platform, home = homedir()) {
+    const dir = launcherDir(plat, home);
+    if (plat === 'win32') {
+        return {
+            launcher: join(dir, LAUNCHER_BATCH_FILENAME),
+            shortcut: join(home, 'Desktop', LAUNCHER_LNK_FILENAME),
+            desktopEntry: null,
+        };
+    }
+    if (plat === 'darwin') {
+        return {
+            launcher: join(dir, LAUNCHER_COMMAND_FILENAME),
+            shortcut: null,
+            desktopEntry: null,
+        };
+    }
+    // linux
+    return {
+        launcher: join(dir, LAUNCHER_SH_FILENAME),
+        shortcut: null,
+        desktopEntry: join(home, '.local', 'share', 'applications', LAUNCHER_DESKTOP_FILENAME),
+    };
+}
+// ---------------------------------------------------------------------------
+// buildManifest — manifest object builder
+// ---------------------------------------------------------------------------
+/** Regex: exactly 32 lowercase a-p characters (Chrome extension ID alphabet) */
+const EXT_ID_RE = /^[a-p]{32}$/;
+/**
+ * Regex: a Firefox/gecko add-on id. Firefox accepts either an email-style id
+ * (`name@domain`) or a UUID in braces; stikfix ships the email-style id
+ * `stikfix@stikfix.com`. We validate the `local@domain` shape (no spaces,
+ * a single @, a dot-bearing domain) rather than the Chrome a-p alphabet.
+ */
+const GECKO_ID_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/**
+ * Build a native-messaging manifest object for the given extension identity
+ * and host binary path.
+ *
+ * - hostBinPath is resolved to an ABSOLUTE path (Pitfall 4).
+ * - browser 'chrome' (default): `extensionId` must be exactly 32 lowercase a-p
+ *   chars; emits `allowed_origins: ["chrome-extension://<id>/"]`.
+ * - browser 'firefox': `extensionId` is the gecko add-on id (e.g.
+ *   `stikfix@stikfix.com`); emits `allowed_extensions: [<gecko-id>]`.
+ *   Firefox rejects a manifest carrying `allowed_origins`, so the two shapes
+ *   are mutually exclusive.
+ */
+export function buildManifest(extensionId, hostBinPath, browser = 'chrome') {
+    const absPath = resolve(hostBinPath);
+    if (browser === 'firefox') {
+        if (!GECKO_ID_RE.test(extensionId)) {
+            throw new Error(`Invalid Firefox add-on id "${extensionId}": must be a gecko id like "name@domain.tld".`);
+        }
+        return {
+            name: NATIVE_HOST_NAME,
+            description: 'stikfix native messaging host',
+            path: absPath,
+            type: 'stdio',
+            allowed_extensions: [extensionId],
+        };
+    }
+    if (!EXT_ID_RE.test(extensionId)) {
+        throw new Error(`Invalid extension ID "${extensionId}": must be exactly 32 lowercase a-p characters.`);
+    }
+    return {
+        name: NATIVE_HOST_NAME,
+        description: 'stikfix native messaging host',
+        path: absPath,
+        type: 'stdio',
+        allowed_origins: [`chrome-extension://${extensionId}/`],
+    };
+}
+// ---------------------------------------------------------------------------
+// writeManifest — write manifest JSON to disk
+// ---------------------------------------------------------------------------
+/**
+ * Write the manifest object to `manifestPath`, creating parent directories
+ * if needed. Mode 0o644 (non-credential — readable by Chrome process).
+ *
+ * Analog: ensureNotesDir (mkdirSync recursive) + writeTokenFile pattern.
+ */
+export function writeManifest(manifest, manifestPath) {
+    mkdirSync(dirname(manifestPath), { recursive: true });
+    writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), {
+        encoding: 'utf8',
+        mode: 0o644,
+    });
+}
+/**
+ * Create a double-click launcher that starts the HTTP host backend,
+ * so the user never has to open a terminal.
+ *
+ * Windows: writes stikfix-host.bat in the stikfix data dir, then creates
+ * a Desktop shortcut (.lnk) pointing at that batch file. If the .lnk creation
+ * fails, the batch file alone is the acceptable fallback.
+ *
+ * macOS: writes an executable stikfix-host.command (bash script).
+ *
+ * Linux: writes stikfix-host.sh + a .desktop entry.
+ *
+ * Security: the ONLY subprocess allowed is the Windows .lnk creation via
+ * execFile(powershell, [argArray]) — mirroring folder-picker.ts safety exactly.
+ * No user-controlled values are interpolated into the PowerShell script string;
+ * all paths are developer-controlled absolute paths validated before use.
+ *
+ * Node builtins only (fs, child_process.execFile).
+ */
+export function createLauncherFiles(opts) {
+    const plat = opts.plat ?? process.platform;
+    const home = opts.home ?? homedir();
+    const written = [];
+    const warnings = [];
+    const paths = getLauncherPaths(plat, home);
+    const launcherDirPath = launcherDir(plat, home);
+    mkdirSync(launcherDirPath, { recursive: true });
+    const nodeCmd = 'node';
+    const hostEntry = opts.hostEntryPath;
+    const rootArg = opts.root;
+    const portArg = opts.port !== undefined ? ` --port ${opts.port}` : '';
+    if (plat === 'win32') {
+        // Write batch file — plain text, no exec required
+        const batchContent = [
+            '@echo off',
+            `rem Stikfix HTTP host launcher — double-click to start the backend`,
+            `rem Generated by: npx stikfix init`,
+            `rem Root: ${rootArg}`,
+            ``,
+            `"${nodeCmd}" "${hostEntry}" --root "${rootArg}"${portArg}`,
+            `if %ERRORLEVEL% NEQ 0 pause`,
+        ].join('\r\n');
+        const batchPath = paths.launcher;
+        writeFileSync(batchPath, batchContent, { encoding: 'utf8' });
+        written.push(batchPath);
+        // Write a VBScript that launches the host HIDDEN (no console window) and
+        // shows an auto-dismissing native Windows dialog confirming it's running.
+        // VBS string-literal escaping: a literal " is doubled ("").
+        const vq = (s) => s.replace(/"/g, '""');
+        const vbsHostEntry = vq(hostEntry);
+        const vbsRoot = vq(rootArg);
+        const vbsPortArg = opts.port !== undefined ? ` --port ${opts.port}` : '';
+        const vbsContent = [
+            'Option Explicit',
+            'Dim sh, fso, hostEntry, root, portFile, msg, port, f',
+            'Set sh = CreateObject("WScript.Shell")',
+            'Set fso = CreateObject("Scripting.FileSystemObject")',
+            `hostEntry = "${vbsHostEntry}"`,
+            `root = "${vbsRoot}"`,
+            "' Launch the host hidden (window style 0), do not wait",
+            `sh.Run "cmd /c node """ & hostEntry & """ --root """ & root & """${vbsPortArg}", 0, False`,
+            "' Give it a moment to bind and write the port file",
+            'WScript.Sleep 1800',
+            'msg = "Stikfix host is running." & vbCrLf & vbCrLf & "You can start dropping notes."',
+            'portFile = root & "\\.stikfix-port"',
+            'If fso.FileExists(portFile) Then',
+            '  Set f = fso.OpenTextFile(portFile, 1)',
+            '  port = Trim(f.ReadAll)',
+            '  f.Close',
+            '  If Len(port) > 0 Then msg = "Stikfix host is running on port " & port & "." & vbCrLf & vbCrLf & "You can start dropping notes."',
+            'End If',
+            'sh.Popup msg, 5, "Stikfix", 64',
+        ].join('\r\n');
+        const vbsPath = join(launcherDir(plat, home), LAUNCHER_VBS_FILENAME);
+        writeFileSync(vbsPath, vbsContent, { encoding: 'utf8' });
+        written.push(vbsPath);
+        // Create Desktop shortcut (.lnk) via PowerShell WScript.Shell.
+        // The shortcut launches the VBS via wscript.exe so the console stays HIDDEN.
+        // Security: ALL paths are developer-controlled absolute strings — no user input.
+        // execFile (not exec) — no shell spawned, no injection vector.
+        // If this fails for any reason, fall through to the warning (batch file is the fallback).
+        if (paths.shortcut) {
+            const lnkPath = paths.shortcut;
+            const iconPath = opts.iconPath ?? '';
+            // Build PowerShell script as a single string — paths passed as PS variables
+            // set from the -Command string. No shell metacharacter interpolation from
+            // external data; all values are constants determined at registration time.
+            // PowerShell single-quote escaping: replace ' with '' in path strings.
+            const safeLnkPath = lnkPath.replace(/'/g, "''");
+            const safeIconPath = iconPath.replace(/'/g, "''");
+            const wscriptPath = join(process.env['SystemRoot'] ?? 'C:\\Windows', 'System32', 'wscript.exe');
+            const safeWscript = wscriptPath.replace(/'/g, "''");
+            const safeVbsPath = vbsPath.replace(/'/g, "''");
+            const psScript = `$ws = New-Object -ComObject WScript.Shell;` +
+                `$s = $ws.CreateShortcut('${safeLnkPath}');` +
+                `$s.TargetPath = '${safeWscript}';` +
+                `$s.Arguments = '"${safeVbsPath}"';` +
+                `$s.Description = 'Start the Stikfix HTTP backend host';` +
+                (safeIconPath ? `$s.IconLocation = '${safeIconPath},0';` : '') +
+                `$s.Save()`;
+            // execFileSync — NEVER exec; arg array is static with respect to user input.
+            // Synchronous so init reports the shortcut accurately (the async variant
+            // raced existsSync in the CLI and printed a false "skipped" message).
+            try {
+                execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', psScript], { timeout: 15_000, stdio: 'ignore' });
+                // Only record the shortcut once it actually exists on disk.
+                written.push(lnkPath);
+            }
+            catch (err) {
+                // Non-fatal: batch file is the acceptable fallback
+                warnings.push(`Desktop shortcut creation failed (non-fatal): ${String(err.message)}. ` +
+                    `The batch file at ${batchPath} can be used directly.`);
+            }
+        }
+    }
+    else if (plat === 'darwin') {
+        // macOS: executable .command file (double-click in Finder to run in Terminal)
+        const commandContent = [
+            '#!/bin/bash',
+            `# Stikfix HTTP host launcher — double-click in Finder or drag to Dock`,
+            `# Generated by: npx stikfix init`,
+            ``,
+            `exec "${nodeCmd}" "${hostEntry}" --root "${rootArg}"${portArg}`,
+        ].join('\n');
+        const commandPath = paths.launcher;
+        writeFileSync(commandPath, commandContent, { encoding: 'utf8', mode: 0o755 });
+        written.push(commandPath);
+    }
+    else {
+        // Linux: executable shell script + .desktop entry
+        const shContent = [
+            '#!/bin/sh',
+            `# Stikfix HTTP host launcher`,
+            `# Generated by: npx stikfix init`,
+            ``,
+            `exec "${nodeCmd}" "${hostEntry}" --root "${rootArg}"${portArg}`,
+        ].join('\n');
+        const shPath = paths.launcher;
+        writeFileSync(shPath, shContent, { encoding: 'utf8' });
+        try {
+            chmodSync(shPath, 0o755);
+        }
+        catch {
+            warnings.push(`Could not chmod 755 ${shPath} — run: chmod +x "${shPath}"`);
+        }
+        written.push(shPath);
+        // .desktop entry
+        if (paths.desktopEntry) {
+            const desktopDir = dirname(paths.desktopEntry);
+            mkdirSync(desktopDir, { recursive: true });
+            const iconLine = opts.iconPath ? `Icon=${opts.iconPath}` : 'Icon=utilities-terminal';
+            const desktopContent = [
+                '[Desktop Entry]',
+                'Version=1.0',
+                'Type=Application',
+                'Name=Stikfix Host',
+                'Comment=Start the Stikfix HTTP backend host',
+                `Exec=${shPath}`,
+                iconLine,
+                'Terminal=true',
+                'Categories=Development;',
+            ].join('\n');
+            writeFileSync(paths.desktopEntry, desktopContent, { encoding: 'utf8', mode: 0o644 });
+            written.push(paths.desktopEntry);
+        }
+    }
+    return { written, warnings };
+}
+/**
+ * Write the native-messaging manifest and, on Windows, register the matching
+ * HKCU registry key(s):
+ *   - chrome  → Google\Chrome + Microsoft\Edge keys, `allowed_origins`
+ *   - firefox → Mozilla key, `allowed_extensions`
+ *
+ * execFileSync is used (NEVER exec, NEVER shell) — T-09-03.
+ */
+export function registerNativeHost(opts) {
+    const plat = opts.plat ?? process.platform;
+    const home = opts.home ?? homedir();
+    const browser = opts.browser ?? 'chrome';
+    const manifestPath = nativeManifestPath(plat, home, browser);
+    // Chrome's CreateProcess (and Firefox on Windows) cannot run a .cjs directly —
+    // point the manifest at a per-OS wrapper that runs `node <abs cjs>` instead.
+    const wrapperPath = writeNativeWrapper(opts.hostBinPath, plat, home, browser);
+    const manifest = buildManifest(opts.extensionId, wrapperPath, browser);
+    writeManifest(manifest, manifestPath);
+    if (plat === 'win32') {
+        const execReg = opts.execReg ?? ((args) => {
+            execFileSync('reg', args);
+        });
+        if (browser === 'firefox') {
+            // Register for Firefox (HKCU — Pitfall 5, never HKLM)
+            execReg(['ADD', REG_FIREFOX_KEY, '/ve', '/t', 'REG_SZ', '/d', manifestPath, '/f']);
+        }
+        else {
+            // Register for Chrome (HKCU — Pitfall 5, never HKLM)
+            execReg(['ADD', REG_CHROME_KEY, '/ve', '/t', 'REG_SZ', '/d', manifestPath, '/f']);
+            // Register for Edge (drop-in, D-05)
+            execReg(['ADD', REG_EDGE_KEY, '/ve', '/t', 'REG_SZ', '/d', manifestPath, '/f']);
+        }
+    }
+}
+/**
+ * Remove the native-messaging manifest, launcher files, Desktop shortcut,
+ * and on Windows delete the matching HKCU registry key(s):
+ *   - chrome  → Google\Chrome + Microsoft\Edge keys
+ *   - firefox → Mozilla key
+ *
+ * Idempotent: does not throw if any artifact is already absent.
+ * execFileSync is used (NEVER exec) with the /f flag to tolerate absent keys.
+ */
+export function unregisterNativeHost(opts = {}) {
+    const plat = opts.plat ?? process.platform;
+    const home = opts.home ?? homedir();
+    const browser = opts.browser ?? 'chrome';
+    const manifestPath = opts.manifestPath ?? nativeManifestPath(plat, home, browser);
+    rmSync(manifestPath, { force: true });
+    rmSync(nativeWrapperPath(plat, home, browser), { force: true });
+    // Remove launcher files
+    const defaultPaths = getLauncherPaths(plat, home);
+    const lPaths = {
+        launcher: opts.launcherPaths?.launcher ?? defaultPaths.launcher,
+        shortcut: opts.launcherPaths?.shortcut !== undefined
+            ? opts.launcherPaths.shortcut
+            : defaultPaths.shortcut,
+        desktopEntry: opts.launcherPaths?.desktopEntry !== undefined
+            ? opts.launcherPaths.desktopEntry
+            : defaultPaths.desktopEntry,
+    };
+    rmSync(lPaths.launcher, { force: true });
+    if (lPaths.shortcut)
+        rmSync(lPaths.shortcut, { force: true });
+    if (lPaths.desktopEntry)
+        rmSync(lPaths.desktopEntry, { force: true });
+    // Remove the hidden-launch VBS (win32 only — written by createLauncherFiles)
+    if (plat === 'win32') {
+        rmSync(join(launcherDir(plat, home), LAUNCHER_VBS_FILENAME), { force: true });
+    }
+    if (plat === 'win32') {
+        // /f flag suppresses "are you sure?" prompt; tolerates absent key (non-zero exit ignored)
+        if (browser === 'firefox') {
+            try {
+                execFileSync('reg', ['DELETE', REG_FIREFOX_KEY, '/f']);
+            }
+            catch {
+                // Key may not exist — ignore
+            }
+        }
+        else {
+            try {
+                execFileSync('reg', ['DELETE', REG_CHROME_KEY, '/f']);
+            }
+            catch {
+                // Key may not exist — ignore
+            }
+            try {
+                execFileSync('reg', ['DELETE', REG_EDGE_KEY, '/f']);
+            }
+            catch {
+                // Key may not exist — ignore
+            }
+        }
+    }
+}
+/**
+ * Return the complete list of filesystem paths and registry keys that
+ * `registerNativeHost` + `createLauncherFiles` create, so `uninstall` can
+ * remove everything and leave no orphaned artifacts (ONB-05 / T-09-05).
+ *
+ * paths includes:
+ *   - native-messaging manifest JSON
+ *   - stikfix config file (~/.config/stikfix/config.json)
+ *   - <root>/.stikfix-port (written by HTTP host on startup)
+ *   - launcher batch/command/sh file
+ *   - Desktop shortcut (.lnk on win32) or .desktop entry (linux)
+ *
+ * registryKeys (win32 only):
+ *   - HKCU Chrome NativeMessagingHosts key
+ *   - HKCU Edge NativeMessagingHosts key
+ */
+export function enumerateArtifacts(opts = {}) {
+    const plat = opts.plat ?? process.platform;
+    const home = opts.home ?? homedir();
+    const root = opts.root;
+    const browser = opts.browser ?? 'chrome';
+    const paths = [
+        nativeManifestPath(plat, home, browser),
+        nativeWrapperPath(plat, home, browser),
+        CONFIG_PATH(home),
+    ];
+    // .stikfix-port is written by the HTTP host alongside .stikfix-token
+    if (root) {
+        paths.push(join(root, '.stikfix-port'));
+    }
+    else {
+        // Include a generic indicator when root is unknown
+        paths.push('.stikfix-port');
+    }
+    // Launcher files created by createLauncherFiles
+    const lPaths = getLauncherPaths(plat, home);
+    paths.push(lPaths.launcher);
+    if (lPaths.shortcut)
+        paths.push(lPaths.shortcut);
+    if (lPaths.desktopEntry)
+        paths.push(lPaths.desktopEntry);
+    if (plat === 'win32') {
+        paths.push(join(launcherDir(plat, home), LAUNCHER_VBS_FILENAME));
+    }
+    const registryKeys = plat === 'win32'
+        ? browser === 'firefox'
+            ? [REG_FIREFOX_KEY]
+            : [REG_CHROME_KEY, REG_EDGE_KEY]
+        : [];
+    return { paths, registryKeys };
+}
+// Re-export isInsideDir for consumers that need path validation
+export { isInsideDir };