bridgerator 1.0.5 → 1.0.7

package/README.md

@@ -1,107 +1,109 @@
-# Bridgerator
-
-Connect your Windows PC to ChatGPT. The assistant can read and edit files, search folders and run
-PowerShell commands on **your** computer — through a bridge that only makes an **outbound**
-connection. No inbound ports, no remote-desktop software.
-
-```
-ChatGPT ──OAuth 2.1 + MCP (HTTPS)──► relay (mcp.bridgerator.recondeck.com) ──WebSocket──► bridgerator on your PC ──stdio──► bundled MCP engine
-```
-
-This repository is the part that runs on your PC. It is small on purpose so you (or an AI agent
-installing it for you) can read all of it: `src/bridge.mjs` (forwarder), `src/policy.mjs` (access
-rules), `src/dc-isolate.mjs` (separate engine config), `src/cli.mjs` (setup/autostart), `install.ps1` (installer).
-
-## What people use it for
-
-- "Sort my Downloads folder by type and month" — ChatGPT lists, plans and moves the files on your PC.
-- "Find every invoice PDF in Documents and rename it by date" — search and rename in plain words.
-- "Why is drive C almost full?" — disk usage, big folders, what is safe to delete.
-- "Check the event log for errors since yesterday" / "Read the end of this log" — diagnostics.
-- Work on code: "explain how D:\\Projects\\app is built and run its tests".
-
-Everything runs as your Windows user and only inside the folders you allow.
-
-## Plans
-
-Free: 15,000 tool calls per month per account, any number of PCs. Pro: $10/month, unlimited.
-Details: https://bridgerator.recondeck.com/pricing
-
-## Install (Windows)
-
-1. Create an account and a device key at https://bridgerator.recondeck.com.
-2. In PowerShell (no admin rights needed):
-   ```powershell
-   & ([scriptblock]::Create((irm https://bridgerator.recondeck.com/install.ps1))) -Token <device key>
-   ```
-   It downloads portable Node.js LTS if missing (checksum-verified, no admin), installs this package and runs `bridgerator setup`.
-   Update later with the same line without `-Token` (the key and folder settings are kept).
-   Prefer to read first? Download `install.ps1`, read it, run it with `-Token`.
-3. In ChatGPT: Settings → Apps & Connectors → Advanced → Developer mode → Create → URL
-   `https://mcp.bridgerator.recondeck.com/mcp`, authentication OAuth, sign in with your account.
-
-Manual install (PowerShell): `$env:PUPPETEER_SKIP_DOWNLOAD=1; npm install -g bridgerator`, then `bridgerator setup --token <key>`. The variable skips a ~700 MB Chrome download that only PDF export needs; PDF export fetches a browser itself on first use.
-
-## Access rules — what the assistant can and cannot touch
-
-Config: `%APPDATA%\Bridgerator\config.json` (written by `setup`, edit and restart to change).
-
-| Key | Meaning | Default |
-|---|---|---|
-| `allowedDirectories` | File tools work only inside these folders (enforced by the engine). Empty = whole disk. | your user folder |
-| `deniedDirectories` | Folders excluded **inside** the allowed ones (enforced by Bridgerator, see below). | `~\.ssh`, `~\AppData` |
-| `blockedCommands` | Commands the engine refuses to run. Leave it out to keep the built-in list. | built-in list (`format`, `diskpart`, `reg`, `net`, `sc`, `runas`, `netsh`, `takeown`, …) |
-| `disabledTools` | Tools never shown to the assistant, e.g. `["start_process","interact_with_process"]` to turn the terminal off. | none |
-
-Full file, search and terminal toolset, including ChatGPT widgets (file preview,
-config view). Hidden: `set_config_value` (would let the assistant change its own limits), feedback and
-usage-stats tools.
-
-How exclusions work (`src/policy.mjs`): every path argument is resolved (symlinks and junctions
-included) and refused if it lies inside an excluded folder; result lines that mention an excluded
-path (search hits, recursive listings) are removed; `set_config_value` is never exposed, so the
-assistant cannot change these limits.
-
-⚠ **The terminal is not a folder sandbox.** A shell command runs with your Windows user's rights
-and can read anything you can. Bridgerator refuses commands that literally name an excluded folder,
-but that is a courtesy, not a boundary. If folder limits must be strict, add the terminal tools to
-`disabledTools`.
-
-The bridge runs as **your** Windows user (hidden scheduled task at logon), never as SYSTEM.
-
-Bridgerator gives its bundled engine its **own** config folder (`%APPDATA%\Bridgerator\dc`, see `src/dc-isolate.mjs`): if you already run the same open-source MCP server for Claude or another app, its settings and folder limits are not touched. The engine keeps a local log of recent tool calls in that folder; it never leaves your PC.
-
-## Commands
-
-```
-bridgerator setup --token <key> [--allow <dir>]... [--deny <dir>]...   # config + autostart + start
-bridgerator run                                                       # foreground (what autostart runs)
-bridgerator status                                                    # config (token masked) + log tail
-bridgerator uninstall                                                 # stop + remove autostart
-```
-Log: `%APPDATA%\Bridgerator\bridge.log`. Stopping the bridge cuts access immediately.
-
-## Privacy
-
-File contents and command output go to ChatGPT (OpenAI) as tool results; the relay forwards them
-in memory and does not store them. Engine telemetry, remote feature flags and any browser pop-ups are turned off by the bridge.
-Policy: https://bridgerator.recondeck.com/privacy
-
-## Development
-
-`npm test` — policy unit tests plus an end-to-end run against the real bundled engine
-(throw-away folders; asserts that an existing config of the same engine stays byte-identical).
-
-## License
-
-MIT. The bundled open-source MCP engine is MIT-licensed as well; its copyright notice is kept in
-`LICENSE` and the dependency is listed in `package.json`.
-
----
-
-### По-русски коротко
-Bridgerator подключает ваш ПК к ChatGPT: файлы, поиск, терминал. Мост только исходящий, входящих
-портов нет. Установка — одна строка PowerShell с ключом устройства из кабинета (см. выше).
-Разрешённые папки — `allowedDirectories`, исключения внутри них — `deniedDirectories`
-(исключения обеспечивает сам Bridgerator). Терминал папками не
-ограничивается — для строгих границ выключите его через `disabledTools`.
+# Bridgerator
+
+Connect your Windows PC to ChatGPT. The assistant can read and edit files, search folders and run
+PowerShell commands on **your** computer — through a bridge that only makes an **outbound**
+connection. No inbound ports, no remote-desktop software.
+
+```
+ChatGPT ──OAuth 2.1 + MCP (HTTPS)──► relay (mcp.bridgerator.recondeck.com) ──WebSocket──► bridgerator on your PC ──stdio──► bundled MCP engine
+```
+
+This repository is the part that runs on your PC. It is small on purpose so you (or an AI agent
+installing it for you) can read all of it: `src/bridge.mjs` (forwarder), `src/policy.mjs` (access
+rules), `src/dc-isolate.mjs` (separate engine config), `src/cli.mjs` (setup/autostart), `src/pair.mjs` (browser pairing), `install.ps1` (installer).
+
+## What people use it for
+
+- "Sort my Downloads folder by type and month" — ChatGPT lists, plans and moves the files on your PC.
+- "Find every invoice PDF in Documents and rename it by date" — search and rename in plain words.
+- "Why is drive C almost full?" — disk usage, big folders, what is safe to delete.
+- "Check the event log for errors since yesterday" / "Read the end of this log" — diagnostics.
+- Work on code: "explain how D:\\Projects\\app is built and run its tests".
+
+Everything runs as your Windows user and only inside the folders you allow.
+
+## Plans
+
+Free: 10,000 tool calls per month per account, any number of PCs. Pro: $10/month, unlimited.
+Details: https://bridgerator.recondeck.com/pricing
+
+## Install (Windows)
+
+1. In ChatGPT, add the Bridgerator app and sign in with Google (an account is created for you), or sign up at https://bridgerator.recondeck.com.
+2. On the PC, in PowerShell (no admin rights needed):
+   ```powershell
+   & ([scriptblock]::Create((irm https://bridgerator.recondeck.com/install.ps1)))
+   ```
+   It downloads portable Node.js LTS if missing (checksum-verified, no admin), installs this package and runs `bridgerator.cmd setup`.
+3. A browser tab opens with a code: check that it matches the one in PowerShell and click **Connect this computer**. Done — no key to copy.
+
+Update later with the same line (the key and folder settings are kept). Prefer to read first? Download `install.ps1`, read it, then run it.
+Servers or PCs without a browser: create a device key in your account (Add a computer → Advanced) and add `-Token <device key>` to the line.
+
+Manual install (PowerShell): `$env:PUPPETEER_SKIP_DOWNLOAD=1; npm install -g bridgerator`, then `bridgerator.cmd setup` (or `bridgerator.cmd setup --token <key>`). The variable skips a ~700 MB Chrome download that only PDF export needs; PDF export fetches a browser itself on first use.
+
+Other MCP clients: server URL `https://mcp.bridgerator.recondeck.com/mcp`, OAuth sign-in.
+
+## Access rules — what the assistant can and cannot touch
+
+Config: `%APPDATA%\Bridgerator\config.json` (written by `setup`, edit and restart to change).
+
+| Key | Meaning | Default |
+|---|---|---|
+| `allowedDirectories` | File tools work only inside these folders (enforced by the engine). Empty = whole disk. | your user folder |
+| `deniedDirectories` | Folders excluded **inside** the allowed ones (enforced by Bridgerator, see below). | `~\.ssh`, `~\AppData` |
+| `blockedCommands` | Commands the engine refuses to run. Leave it out to keep the built-in list. | built-in list (`format`, `diskpart`, `reg`, `net`, `sc`, `runas`, `netsh`, `takeown`, …) |
+| `disabledTools` | Tools never shown to the assistant, e.g. `["start_process","interact_with_process"]` to turn the terminal off. | none |
+
+Full file, search and terminal toolset, including ChatGPT widgets (file preview,
+config view). Hidden: `set_config_value` (would let the assistant change its own limits), feedback and
+usage-stats tools.
+
+How exclusions work (`src/policy.mjs`): every path argument is resolved (symlinks and junctions
+included) and refused if it lies inside an excluded folder; result lines that mention an excluded
+path (search hits, recursive listings) are removed; `set_config_value` is never exposed, so the
+assistant cannot change these limits.
+
+⚠ **The terminal is not a folder sandbox.** A shell command runs with your Windows user's rights
+and can read anything you can. Bridgerator refuses commands that literally name an excluded folder,
+but that is a courtesy, not a boundary. If folder limits must be strict, add the terminal tools to
+`disabledTools`.
+
+The bridge runs as **your** Windows user (hidden scheduled task at logon), never as SYSTEM.
+
+Bridgerator gives its bundled engine its **own** config folder (`%APPDATA%\Bridgerator\dc`, see `src/dc-isolate.mjs`): if you already run the same open-source MCP server for Claude or another app, its settings and folder limits are not touched. The engine keeps a local log of recent tool calls in that folder; it never leaves your PC.
+
+## Commands
+
+```
+bridgerator.cmd setup [--token <key> | --pair] [--allow <dir>]... [--deny <dir>]...  # pair in the browser (no key yet / --pair) + config + autostart + start
+bridgerator.cmd run                                                       # foreground (what autostart runs)
+bridgerator.cmd status                                                    # config (token masked) + log tail
+bridgerator.cmd uninstall                                                 # stop + remove autostart
+```
+Log: `%APPDATA%\Bridgerator\bridge.log`. Stopping the bridge cuts access immediately.
+
+## Privacy
+
+File contents and command output go to ChatGPT (OpenAI) as tool results; the relay forwards them
+in memory and does not store them. Engine telemetry, remote feature flags and any browser pop-ups are turned off by the bridge.
+Policy: https://bridgerator.recondeck.com/privacy
+
+## Development
+
+`npm test` — policy unit tests plus an end-to-end run against the real bundled engine
+(throw-away folders; asserts that an existing config of the same engine stays byte-identical).
+
+## License
+
+MIT. The bundled open-source MCP engine is MIT-licensed as well; its copyright notice is kept in
+`LICENSE` and the dependency is listed in `package.json`.
+
+---
+
+### По-русски коротко
+Bridgerator подключает ваш ПК к ChatGPT: файлы, поиск, терминал. Мост только исходящий, входящих
+портов нет. Установка — одна строка PowerShell, затем подтверждение компьютера во вкладке браузера (см. выше).
+Разрешённые папки — `allowedDirectories`, исключения внутри них — `deniedDirectories`
+(исключения обеспечивает сам Bridgerator). Терминал папками не
+ограничивается — для строгих границ выключите его через `disabledTools`.

package/install.ps1

@@ -1,9 +1,11 @@
 # Bridgerator installer for Windows (PowerShell 5.1+). Source: npm package "bridgerator" (https://www.npmjs.com/package/bridgerator)
 # Usage (one line, from your Bridgerator account page):
-#   & ([scriptblock]::Create((irm https://bridgerator.recondeck.com/install.ps1))) -Token <device key>
-# Update an installed bridge (keeps its key and folders): the same line without -Token.
+#   & ([scriptblock]::Create((irm https://bridgerator.recondeck.com/install.ps1)))
+# A browser tab opens: sign in and confirm this computer — no key to paste. Run again to update
+# (keeps the key and folders). Servers / headless PCs: add -Token <device key> from the account page.
 # What it does: installs Node.js LTS if missing (portable zip, no admin), installs the bridgerator npm package,
-# then runs `bridgerator setup` (config + hidden autostart at logon for THIS user, no admin rights),
+# then runs `bridgerator setup` (pairing in the browser if there is no key yet, config + hidden autostart
+# at logon for THIS user, no admin rights),
 # then opens the welcome page in the default browser (skip with -NoBrowser).
 param(
   [string]$Token,
@@ -13,7 +15,7 @@ param(
   [switch]$NoBrowser
 )
 $ErrorActionPreference = 'Stop'
-if (-not $Token -and -not (Test-Path (Join-Path $env:APPDATA 'Bridgerator\config.json'))) { throw 'Add -Token <device key> from your Bridgerator account page (https://bridgerator.recondeck.com/app).' }
+$paired = $Token -or (Test-Path (Join-Path $env:APPDATA 'Bridgerator\config.json'))
 
 function Refresh-Path {
   $env:Path = [Environment]::GetEnvironmentVariable('Path', 'Machine') + ';' + [Environment]::GetEnvironmentVariable('Path', 'User')
@@ -58,8 +60,8 @@ if ($major -lt 20) { throw "Node.js 20+ required, found $(& node -v). Update fro
 # The engine's PDF export brings puppeteer, whose postinstall downloads Chrome (~700 MB);
 # skipped here, PDF export fetches a browser itself the first time it is used.
 $env:PUPPETEER_SKIP_DOWNLOAD = '1'
-Write-Host "Installing bridgerator from $Package ..."
-& npm install -g $Package --no-audit --no-fund --loglevel=error
+Write-Host "Installing Bridgerator from $Package - this takes 2-4 minutes, please wait..."
+& npm.cmd install -g $Package --no-audit --no-fund --loglevel=error
 if ($LASTEXITCODE -ne 0) { throw 'npm install failed' }
 Refresh-Path
 
@@ -67,9 +69,10 @@ $setupArgs = @('setup')
 if ($Token) { $setupArgs += @('--token', $Token) }
 foreach ($a in $Allow) { $setupArgs += @('--allow', $a) }
 foreach ($d in $Deny) { $setupArgs += @('--deny', $d) }
-& bridgerator @setupArgs
+if (-not $paired) { Write-Host 'Next: a browser tab opens - sign in with the same account you use for Bridgerator and click "Connect this computer".' }
+& bridgerator.cmd @setupArgs
 if ($LASTEXITCODE -ne 0) { throw 'bridgerator setup failed' }
-Write-Host 'Done. Check with: bridgerator status'
+Write-Host 'Done. Bridgerator starts in the background in about 10 seconds. Check any time with: bridgerator.cmd status'
 
 # Next steps (connect ChatGPT, example prompts) on the welcome page; skipped for -NoBrowser and
 # non-interactive sessions (scheduled tasks, remote shells). Never fails the install.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bridgerator",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Connect ChatGPT to your Windows PC: files, search and terminal through an outbound-only bridge with folder limits. No inbound ports, no admin rights.",
   "license": "MIT",
   "type": "module",

package/src/bridge.mjs

@@ -88,7 +88,7 @@ export function connect(cfg, dc, log = console.log) {
     setTimeout(() => connect(cfg, dc, log), RECONNECT_MS);
   };
   ws.on('close', (code) => {
-    if (code === 4003) { log('[bridgerator] relay rejected the device token — run `bridgerator setup --token <new token>`'); process.exit(2); }
+    if (code === 4003) { log('[bridgerator] relay rejected the device token — run the install command from your account page again (or `bridgerator.cmd setup --pair`)'); process.exit(2); }
     die(`close ${code}`);
   });
   ws.on('error', (e) => { if (!alive) die(`connect: ${e.message}`); });

package/src/cli.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-// bridgerator setup --token <t> [--relay <wss url>] [--allow <dir>]... [--deny <dir>]...  → config + autostart + start
+// bridgerator setup [--token <t> | --pair] [--relay <wss url>] [--allow <dir>]... [--deny <dir>]...  → config + autostart + start
+//   (no key yet: pairs this PC through the browser — the signed-in owner confirms a code)
 // bridgerator run | status | uninstall
 import fs from 'node:fs';
 import os from 'node:os';
@@ -7,6 +8,7 @@ import path from 'node:path';
 import { spawn, execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { startDesktopCommander, connect } from './bridge.mjs';
+import { pair, siteOf } from './pair.mjs';
 
 const DEFAULT_RELAY = 'wss://mcp.bridgerator.recondeck.com/link';
 const TASK = 'Bridgerator';
@@ -82,10 +84,14 @@ async function main() {
   const cmd = o._[0];
   if (cmd === 'setup') {
     const prev = readConfig() || {};
-    const token = o.token || prev.token;
-    if (!token || token === true) throw new Error('setup needs --token <device key from your Bridgerator account>');
+    if (o.token === true) throw new Error('--token needs the device key from your Bridgerator account');
+    const relay = o.relay || prev.relay || DEFAULT_RELAY;
+    // --pair: get a new key through the browser even if one is configured (computer removed in the account).
+    const paired = !o.token && (o.pair || !prev.token);
+    const token = o.token || (paired ? (await pair(siteOf(relay), os.hostname())).token : prev.token);
+    if (paired) console.log('Confirmed — this computer is linked to your account.');
     const cfg = {
-      relay: o.relay || prev.relay || DEFAULT_RELAY,
+      relay,
       token,
       allowedDirectories: o.allow || prev.allowedDirectories || [home],
       deniedDirectories: o.deny || prev.deniedDirectories || [path.join(home, '.ssh'), path.join(home, 'AppData')],
@@ -102,12 +108,12 @@ async function main() {
     stopRunning();
     startHidden();
     console.log(`started in background — log: ${LOG}`);
-    console.log('Next: in ChatGPT add the connector https://mcp.bridgerator.recondeck.com/mcp and sign in.');
+    console.log('Next: in ChatGPT add the Bridgerator app and sign in with the same account.');
     return;
   }
   if (cmd === 'run') {
     const cfg = readConfig();
-    if (!cfg) throw new Error(`no config at ${CONFIG} — run: bridgerator setup --token <device key>`);
+    if (!cfg) throw new Error(`no config at ${CONFIG} — run: bridgerator setup`);
     const dc = await startDesktopCommander({ ...cfg, dcConfigDir: path.join(DIR, 'dc') }, log);
     connect(cfg, dc, log);
     return;
@@ -125,7 +131,7 @@ async function main() {
     console.log(`stopped and autostart removed. Config kept at ${CONFIG}. Remove the package: npm rm -g bridgerator`);
     return;
   }
-  console.log('usage: bridgerator setup --token <key> [--allow <dir>]... [--deny <dir>]... | run | status | uninstall');
+  console.log('usage: bridgerator setup [--token <key> | --pair] [--allow <dir>]... [--deny <dir>]... | run | status | uninstall');
 }
 
 main().catch((e) => { console.error(`[bridgerator] ${e?.message || e}`); process.exit(1); });

package/src/notice.mjs

@@ -11,7 +11,7 @@ const xml = (s) => String(s).replace(/[<>&"']/g, (c) => ({ '<': '&lt;', '>': '&g
 export function noticeText(n) {
   const t = {
     limit: ['Bridgerator: monthly limit reached', `${n.calls} of ${n.limit} tool calls used. ChatGPT can't use this PC until the 1st. Turn on Pro in your account.`],
-    expired: ['Bridgerator Pro has ended', "You're on Free now (15,000 tool calls a month). Renew Pro in your account."],
+    expired: ['Bridgerator Pro has ended', "You're on Free now (10,000 tool calls a month). Renew Pro in your account."],
     expiring: [`Bridgerator Pro ends on ${day(n.until)}`, 'Pay for 30 more days in your account to keep unlimited calls.'],
   }[n.kind];
   return t && { title: t[0], body: t[1], button: 'Open account' };

package/src/pair.mjs

@@ -0,0 +1,43 @@
+// Key-less setup: ask the relay for a pairing code, open the confirmation page in the browser, wait
+// until the signed-in owner confirms this computer there, and get this PC's device key back.
+import { spawn } from 'node:child_process';
+
+// wss://mcp.bridgerator.recondeck.com/link → https://bridgerator.recondeck.com (the site host, where the account pages live).
+export const siteOf = (relay) => { const u = new URL(relay); return `${u.protocol === 'ws:' ? 'http' : 'https'}://${u.host.replace(/^mcp\./, '')}`; };
+
+// Opens the URL in the default browser. Only a URL we checked ourselves reaches cmd's `start`.
+export function openBrowser(url) {
+  if (!/^https?:\/\/[A-Za-z0-9.:-]+\/pair\?code=[A-Z0-9]{4}-[A-Z0-9]{4}$/.test(url)) return;
+  try {
+    const p = process.platform === 'win32'
+      ? spawn('cmd', ['/c', `start "" "${url}"`], { windowsHide: true, windowsVerbatimArguments: true, stdio: 'ignore', detached: true })
+      : spawn(process.platform === 'darwin' ? 'open' : 'xdg-open', [url], { stdio: 'ignore', detached: true });
+    p.on('error', () => {});
+    p.unref();
+  } catch { /* no browser: the URL is printed */ }
+}
+
+/** → { token, name } once the owner confirmed; throws when the code expires. */
+export async function pair(site, name, { fetch: f = globalThis.fetch, open = openBrowser, log = console.log, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), everyMs = 3000 } = {}) {
+  const post = (path, body) => f(`${site}${path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(20000) });
+  const r = await post('/pair/start', { name });
+  if (!r.ok) throw new Error(`could not start pairing (HTTP ${r.status}) — try again in a minute`);
+  const s = await r.json();
+  const url = `${site}/pair?code=${s.code}`;
+  if (!/^[A-Z0-9]{4}-[A-Z0-9]{4}$/.test(String(s.code)) || typeof s.poll !== 'string') throw new Error('unexpected answer from the relay');
+  log('');
+  log(`  Confirm this computer in your browser:  ${url}`);
+  log(`  Code: ${s.code}   (check that the page shows the same code)`);
+  log('');
+  open(url);
+  log('Waiting for the confirmation (up to 15 minutes)...');
+  const until = Date.now() + (Number(s.expiresIn) || 900) * 1000;
+  while (Date.now() < until) {
+    await sleep(everyMs);
+    let p;
+    try { p = await post('/pair/poll', { poll: s.poll }); } catch { continue; } // network blip: try again
+    if (p.status === 200) { const j = await p.json(); if (j.token) return { token: j.token, name: j.name || name }; }
+    if (p.status === 410) break;
+  }
+  throw new Error('the code expired before it was confirmed — run the command again');
+}