passclaude 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "passclaude",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Let Claude Code log into websites and use your API keys without ever seeing them.",
+  "type": "module",
+  "bin": {
+    "passclaude": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "hook",
+    "assets",
+    "docs/e2e.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "os": [
+    "win32"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "brand": "node scripts/brand/build.js && node scripts/brand/phone.js",
+    "site": "node scripts/site/build.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "mcp",
+    "mcp-server",
+    "password",
+    "secrets",
+    "ai-agents",
+    "remote-control"
+  ],
+  "license": "MIT",
+  "passclaude": {
+    "pageUrl": "https://daniardel.github.io/passclaude-phone/"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.6.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daniardel/passclaude.git"
+  },
+  "homepage": "https://github.com/daniardel/passclaude#readme",
+  "bugs": {
+    "url": "https://github.com/daniardel/passclaude/issues"
+  },
+  "devDependencies": {
+    "jsqr": "^1.4.0",
+    "sharp": "^0.35.5"
+  }
+}

package/src/cli.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// Entry point for `npx passclaude`. No arguments: run the MCP server over stdio (Claude Code starts this).
+// Never print to stdout in server mode: stdout carries the MCP protocol.
+
+const HELP = `passClaude - let Claude Code use your passwords and API keys without ever seeing them.
+
+Add it to Claude Code (one time):
+  claude mcp add --scope user passclaude -- npx -y passclaude
+
+Commands:
+  npx passclaude                 run the MCP server (Claude Code does this for you)
+  npx passclaude install-guard   optional: block shell commands that read saved secrets directly
+  npx passclaude help            show this help`;
+
+const [cmd] = process.argv.slice(2);
+
+if (process.platform !== 'win32') {
+  console.error('passClaude currently works on Windows only.');
+  process.exitCode = 1;
+} else if (!cmd) {
+  const { startServer } = await import('./server.js');
+  await startServer();
+} else if (cmd === 'install-guard') {
+  const { installGuard } = await import('./install-guard.js');
+  process.exitCode = await installGuard();
+} else if (['help', '--help', '-h'].includes(cmd)) {
+  console.log(HELP);
+} else {
+  console.error(`Unknown command "${cmd}".\n\n${HELP}`);
+  process.exitCode = 1;
+}

package/src/install-guard.js

@@ -0,0 +1,80 @@
+// `node src/cli.js install-guard`: copies the guard to ~/.claude/passclaude/ and registers it in
+// ~/.claude/settings.json, after showing the exact change and asking first. Backs the file up before writing.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+
+export const GUARD_SOURCE = fileURLToPath(new URL('../hook/guard.cjs', import.meta.url));
+// The MCP tool is listed too: a run_with_secret command can run passClaude's own cred.ps1 and print a saved value.
+export const MATCHER = 'Bash|PowerShell|mcp__passclaude__run_with_secret';
+
+export function guardCommand(guardPath) {
+  return `node "${guardPath.replace(/\\/g, '/')}"`;
+}
+
+export function addGuardHook(settings, command) {
+  const next = structuredClone(settings ?? {});
+  next.hooks ??= {};
+  next.hooks.PreToolUse ??= [];
+  const present = next.hooks.PreToolUse.some((entry) => entry?.hooks?.some((h) => h?.command === command));
+  if (present) return { settings: next, changed: false };
+  next.hooks.PreToolUse.push({ matcher: MATCHER, hooks: [{ type: 'command', command }] });
+  return { settings: next, changed: true };
+}
+
+async function askYesNo(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return /^y(es)?$/i.test((await rl.question(question)).trim());
+  } finally {
+    rl.close();
+  }
+}
+
+export async function installGuard({ home = os.homedir(), ask = askYesNo, log = console.log } = {}) {
+  const claudeDir = path.join(home, '.claude');
+  const settingsPath = path.join(claudeDir, 'settings.json');
+  const guardPath = path.join(claudeDir, 'passclaude', 'guard.cjs');
+  const command = guardCommand(guardPath);
+
+  let current = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      const text = fs.readFileSync(settingsPath, 'utf8').replace(/^/, '');
+      current = text.trim() ? JSON.parse(text) : {};
+    } catch {
+      log(`Couldn't read ${settingsPath} (it is not valid JSON). Fix it and try again. Nothing changed.`);
+      return 1;
+    }
+  }
+
+  const { settings, changed } = addGuardHook(current, command);
+  if (!changed) {
+    fs.mkdirSync(path.dirname(guardPath), { recursive: true }); // the hook entry can outlive this folder
+    fs.copyFileSync(GUARD_SOURCE, guardPath); // refresh the copy in case passClaude was updated
+    log('The passClaude guard is already installed.');
+    return 0;
+  }
+
+  const entry = { matcher: MATCHER, hooks: [{ type: 'command', command }] };
+  log(`This adds the passClaude guard to ${settingsPath}:\n`);
+  log(JSON.stringify({ hooks: { PreToolUse: [entry] } }, null, 2));
+  log('\nIt blocks shell commands that try to read saved secrets directly. Your current settings are backed up first.');
+  if (!(await ask('Add it? (y/N) '))) {
+    log('Nothing changed.');
+    return 0;
+  }
+
+  fs.mkdirSync(path.dirname(guardPath), { recursive: true });
+  fs.copyFileSync(GUARD_SOURCE, guardPath);
+  if (fs.existsSync(settingsPath)) {
+    const backup = `${settingsPath}.passclaude-backup-${Date.now()}`;
+    fs.copyFileSync(settingsPath, backup);
+    log(`Backup saved: ${backup}`);
+  }
+  fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  log('Guard installed. Restart Claude Code to turn it on.');
+  return 0;
+}

package/src/ntfy.js

@@ -0,0 +1,42 @@
+// Minimal ntfy client: publish a message, stream messages from a topic.
+
+export function createNtfy({ baseUrl = 'https://ntfy.sh', fetchImpl = globalThis.fetch } = {}) {
+  const base = baseUrl.replace(/\/+$/, '');
+  return {
+    baseUrl: base,
+
+    async publish(topic, message) {
+      const res = await fetchImpl(`${base}/${topic}`, { method: 'POST', body: message });
+      if (!res.ok) throw new Error(`Relay publish failed: HTTP ${res.status}`);
+      return res.json();
+    },
+
+    /**
+     * Calls onMessage(text, id) for each message until the stream ends or `signal` aborts.
+     * Calls onOpen() once, as soon as the relay has accepted the subscription.
+     */
+    async subscribe(topic, onMessage, { since, signal, onOpen } = {}) {
+      const query = since ? `?since=${encodeURIComponent(since)}` : '';
+      const res = await fetchImpl(`${base}/${topic}/json${query}`, { signal });
+      if (!res.ok) throw new Error(`Relay subscribe failed: HTTP ${res.status}`);
+      onOpen?.();
+      const decoder = new TextDecoder();
+      let buffer = '';
+      for await (const chunk of res.body) {
+        buffer += decoder.decode(chunk, { stream: true });
+        let nl;
+        while ((nl = buffer.indexOf('\n')) >= 0) {
+          const line = buffer.slice(0, nl);
+          buffer = buffer.slice(nl + 1);
+          let event;
+          try {
+            event = JSON.parse(line);
+          } catch {
+            continue;
+          }
+          if (event.event === 'message') await onMessage(event.message, event.id);
+        }
+      }
+    },
+  };
+}

package/src/phone.js

@@ -0,0 +1,217 @@
+// Adding a secret from the phone: one-time link, end-to-end encrypted, relayed through ntfy.
+import { aadFor, deriveKey, fromB64u, generateKeyPair, randomTopic, seal, toB64u, unseal } from '../docs/e2e.js';
+
+export const LINK_TTL_MS = 5 * 60_000;
+
+/** How long start() waits for the relay connection to open before telling the user to use the PC popup instead. */
+export const RELAY_OPEN_WAIT_MS = 8000;
+
+/**
+ * How long close() waits for messages still being saved or acknowledged, before giving up on them. With CLOSE_DRAIN_MS it
+ * stays well under the 2 seconds the MCP client waits after closing stdin before it kills the server.
+ */
+export const CLOSE_ACK_WAIT_MS = 1500;
+
+/** Pause after the wait, so aborted relay connections can finish closing before the caller exits (see close()). */
+export const CLOSE_DRAIN_MS = 200;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Resolves once every promise has settled, or after `ms`. The timer is cleared as soon as either happens. */
+function settledWithin(promises, ms) {
+  if (promises.length === 0) return Promise.resolve();
+  let timer;
+  const timeout = new Promise((resolve) => { timer = setTimeout(resolve, ms); });
+  return Promise.race([Promise.allSettled(promises), timeout]).finally(() => clearTimeout(timer));
+}
+
+/** The relay's host, such as ntfy.sh, for messages to the user. */
+function relayHost(baseUrl) {
+  try {
+    return new URL(baseUrl).host;
+  } catch {
+    return baseUrl;
+  }
+}
+
+export function createPhone({
+  vault, ntfy, pageUrl, now = Date.now, ttlMs = LINK_TTL_MS, retryMs = 2000, openTimeoutMs = RELAY_OPEN_WAIT_MS,
+}) {
+  const pending = new Map(); // name -> request
+  const starting = new Set(); // names whose start() is still in progress
+  const inFlight = new Set(); // handle() calls still saving a secret or publishing its ack
+  let closed = false; // set by close(); nothing new may start after that
+
+  function finish(req, status) {
+    if (req.status !== 'waiting') return;
+    req.status = status;
+    req.keys = null;
+    clearTimeout(req.timer);
+    req.controller.abort();
+    for (const notify of req.waiters) notify(status);
+    req.waiters.clear();
+  }
+
+  /** Expiry and close() never interrupt a save in progress; the save decides the outcome. */
+  function expire(req) {
+    if (req.busy) req.expirePending = true;
+    else finish(req, 'expired');
+  }
+
+  async function handle(req, text) {
+    if (req.status !== 'waiting' || req.busy) return;
+    let msg;
+    try {
+      msg = JSON.parse(text);
+    } catch {
+      return;
+    }
+    if (msg?.t !== 'sub' || typeof msg.pk !== 'string') return;
+    let key;
+    let plain;
+    try {
+      key = await deriveKey(req.keys.privateKey, fromB64u(msg.pk), req.topic);
+      plain = await unseal(key, msg, aadFor(req, 'sub'));
+    } catch {
+      return; // not sealed for this link
+    }
+    // The link may have expired while decrypting. Claim it synchronously, so nothing else can save to it.
+    if (req.status !== 'waiting' || req.busy) return;
+    req.busy = true;
+    const reply = async (body) => {
+      const box = await seal(key, body, aadFor(req, 'ack'));
+      await ntfy.publish(req.topic, JSON.stringify({ t: 'ack', ...box })).catch(() => {});
+    };
+    try {
+      if (typeof plain?.value !== 'string') throw new Error('The secret must be text.');
+      await vault.put(req.name, { kind: req.kind, site: req.site || undefined, created: new Date(now()).toISOString() }, plain.value);
+    } catch (e) {
+      req.busy = false;
+      if (req.expirePending) finish(req, 'expired');
+      await reply({ ok: false, error: e.message });
+      return;
+    }
+    // The secret is in the vault: report it as saved before the ack goes out, so a slow relay cannot turn it into 'expired'.
+    req.busy = false;
+    finish(req, 'saved');
+    await reply({ ok: true });
+  }
+
+  /** Records a message that is still being saved or acknowledged, so close() can wait for it. */
+  async function track(work) {
+    inFlight.add(work);
+    try {
+      await work;
+    } finally {
+      inFlight.delete(work);
+    }
+  }
+
+  /**
+   * Keeps a relay connection open for req until it is finished, reconnecting when it drops. Calls reached(true) each time
+   * a connection opens and reached(false) each time one fails; start() only looks at the first call.
+   */
+  async function listen(req, since, reached) {
+    const seen = new Set();
+    while (req.status === 'waiting') {
+      try {
+        await ntfy.subscribe(req.topic, async (text, id) => {
+          if (seen.has(id)) return;
+          seen.add(id);
+          await track(handle(req, text));
+        }, { since, signal: req.controller.signal, onOpen: () => reached(true) });
+      } catch {
+        reached(false); // could not connect, dropped or aborted; the loop decides
+      }
+      if (req.status === 'waiting') await sleep(retryMs);
+    }
+  }
+
+  return {
+    async start({ name, kind, site }) {
+      if (closed) throw new Error('passClaude is shutting down.');
+      if (kind !== 'web' && kind !== 'command') throw new Error('Kind must be "web" or "command".');
+      if (kind === 'web' && !site) throw new Error('A web link needs a site, such as netflix.com.');
+      if (kind === 'command' && site) throw new Error('A command link cannot have a site.');
+      if (!pageUrl) throw new Error('Phone page not configured. Set PASSCLAUDE_PAGE_URL, or use add_secret (PC popup) instead.');
+      if (starting.has(name) || pending.get(name)?.status === 'waiting') {
+        throw new Error(`A phone link for "${name}" is already waiting. Use check_phone_secret.`);
+      }
+      starting.add(name); // reserved before the first await, so a concurrent start() is refused
+      try {
+        if (await vault.meta(name)) throw new Error(`"${name}" already exists. Delete it first if you want to replace it.`);
+
+        const keys = await generateKeyPair();
+        if (closed) throw new Error('passClaude is shutting down.'); // close() ran while we were waiting
+        const topic = randomTopic();
+        const created = now();
+        const expiresAt = created + ttlMs;
+        const req = {
+          topic, name, kind, site: site ?? '',
+          keys, status: 'waiting', busy: false, expirePending: false,
+          waiters: new Set(), controller: new AbortController(),
+        };
+        req.timer = setTimeout(() => expire(req), ttlMs);
+        req.timer.unref?.();
+        pending.set(name, req);
+        // Hand out the link only once the relay has accepted the connection: a link the PC can't hear would leave the user
+        // waiting for nothing. Only this first connection counts; later drops are retried quietly by listen().
+        let timer;
+        const opened = await new Promise((resolve) => {
+          timer = setTimeout(() => resolve(false), openTimeoutMs);
+          // 'all' returns only this link's messages (the topic is new and random), so no clock is involved.
+          listen(req, 'all', resolve).catch(() => {});
+        });
+        clearTimeout(timer);
+        if (!opened || closed) {
+          finish(req, 'expired'); // stops listening
+          pending.delete(name);
+          if (closed) throw new Error('passClaude is shutting down.');
+          throw new Error(`Could not reach the relay (${relayHost(ntfy.baseUrl)}) from this PC. Use add_secret (PC popup) instead.`);
+        }
+
+        const params = new URLSearchParams({
+          v: '1', t: topic, k: toB64u(keys.publicKeyRaw), n: name, kind, s: site ?? '',
+          e: String(Math.floor(expiresAt / 1000)), r: ntfy.baseUrl,
+        });
+        return { link: `${pageUrl}#${params}`, expiresAt };
+      } finally {
+        starting.delete(name);
+      }
+    },
+
+    check(name, timeoutMs = 60_000) {
+      const req = pending.get(name);
+      if (!req) return Promise.resolve('none');
+      if (req.status !== 'waiting') return Promise.resolve(req.status);
+      return new Promise((resolve) => {
+        const done = (status) => {
+          clearTimeout(timer);
+          resolve(status);
+        };
+        const timer = setTimeout(() => {
+          req.waiters.delete(done);
+          resolve('waiting');
+        }, timeoutMs);
+        req.waiters.add(done);
+      });
+    },
+
+    /** Drops a finished link for name (after its secret is deleted), so check() no longer reports it as saved. */
+    forget(name) {
+      if (pending.get(name)?.status !== 'waiting') pending.delete(name);
+    },
+
+    /**
+     * Ends every waiting link (which aborts its relay connection). Resolves once messages already being saved have been
+     * acknowledged (or after CLOSE_ACK_WAIT_MS), then after CLOSE_DRAIN_MS. The drain is needed because on Windows,
+     * calling process.exit() right after a streaming fetch is aborted trips a libuv assertion (src\win\async.c) and the
+     * process dies with exit code 127. Callers that exit afterwards must await close() first.
+     */
+    close() {
+      closed = true;
+      for (const req of pending.values()) expire(req);
+      return settledWithin([...inFlight], CLOSE_ACK_WAIT_MS).then(() => sleep(CLOSE_DRAIN_MS));
+    },
+  };
+}

package/src/ps/brand.xaml

@@ -0,0 +1,22 @@
+<!-- Generated from brand/tokens.json by `npm run brand`. Do not edit by hand. -->
+<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
+  <SolidColorBrush x:Key="Violet" Color="#5B2EFF"/>
+  <SolidColorBrush x:Key="VioletDeep" Color="#3D17D6"/>
+  <SolidColorBrush x:Key="Yellow" Color="#FFC92E"/>
+  <SolidColorBrush x:Key="Ink" Color="#17132E"/>
+  <SolidColorBrush x:Key="Paper" Color="#F3EFFF"/>
+  <SolidColorBrush x:Key="White" Color="#FFFFFF"/>
+  <SolidColorBrush x:Key="Muted" Color="#4A4370"/>
+  <SolidColorBrush x:Key="MutedOnDark" Color="#CFC6EE"/>
+  <SolidColorBrush x:Key="Lilac200" Color="#DCD3FF"/>
+  <SolidColorBrush x:Key="Lilac300" Color="#C9BCFF"/>
+  <SolidColorBrush x:Key="Mint" Color="#0E9F6E"/>
+  <SolidColorBrush x:Key="Coral" Color="#E5432A"/>
+  <CornerRadius x:Key="RadiusSm">12</CornerRadius>
+  <CornerRadius x:Key="RadiusMd">16</CornerRadius>
+  <CornerRadius x:Key="RadiusLg">24</CornerRadius>
+  <CornerRadius x:Key="RadiusPill">999</CornerRadius>
+  <Thickness x:Key="Outline">2</Thickness>
+  <Thickness x:Key="ShadowButton">5,5,0,0</Thickness>
+  <Thickness x:Key="ShadowCard">8,8,0,0</Thickness>
+</ResourceDictionary>

package/src/ps/chromeui.ps1

@@ -0,0 +1,55 @@
+# Chrome helpers using UI Automation: read a window's address bar, check the focused element.
+Add-Type -AssemblyName UIAutomationClient, UIAutomationTypes
+$AE = [System.Windows.Automation.AutomationElement]
+$CT = [System.Windows.Automation.ControlType]
+$Descendants = [System.Windows.Automation.TreeScope]::Descendants
+
+function Test-InsideDocument($Element) {
+  $walker = [System.Windows.Automation.TreeWalker]::ControlViewWalker
+  $node = $walker.GetParent($Element)
+  while ($node) {
+    if ($node.Current.ControlType -eq $CT::Document) { return $true }
+    $node = $walker.GetParent($node)
+  }
+  return $false
+}
+
+# Text in the address bar of a Chrome window, or $null if it cannot be found.
+function Get-AddressBarText([IntPtr]$Hwnd) {
+  try {
+    $root = $AE::FromHandle($Hwnd)
+    $isEdit = [System.Windows.Automation.PropertyCondition]::new($AE::ControlTypeProperty, $CT::Edit)
+    $named = [System.Windows.Automation.PropertyCondition]::new($AE::NameProperty, 'Address and search bar')
+    $both = [System.Windows.Automation.AndCondition]::new([System.Windows.Automation.Condition[]]@($isEdit, $named))
+    $edit = $root.FindFirst($Descendants, $both)
+    # Never read a password box, whatever it is called, or a box in the web page that only calls itself the address bar
+    # (with aria-label, say). In non-English Chrome the real one has another name, so the page's would be the only match.
+    if ($edit -and ($edit.Current.IsPassword -or (Test-InsideDocument $edit))) { $edit = $null }
+    if (-not $edit) {
+      # Non-English Chrome: the first edit box that is neither a password box nor inside the web page is the address bar.
+      foreach ($candidate in $root.FindAll($Descendants, $isEdit)) {
+        if ($candidate.Current.IsPassword) { continue }
+        if (Test-InsideDocument $candidate) { continue }
+        $edit = $candidate
+        break
+      }
+    }
+    if (-not $edit) { return $null }
+    return $edit.GetCurrentPattern([System.Windows.Automation.ValuePattern]::Pattern).Current.Value
+  } catch {
+    return $null
+  }
+}
+
+# True if keyboard focus is on a password box in the window's process.
+function Test-FocusIsPassword([IntPtr]$Hwnd) {
+  $windowPid = [PassClaude.Win]::ProcessId($Hwnd)
+  for ($i = 0; $i -lt 5; $i++) {
+    try {
+      $focused = $AE::FocusedElement
+      if ($focused -and $focused.Current.IsPassword -and $focused.Current.ProcessId -eq $windowPid) { return $true }
+    } catch { }
+    Start-Sleep -Milliseconds 200
+  }
+  return $false
+}