granttap-mcp 0.1.0 → 0.2.0

package/README.md

@@ -14,6 +14,15 @@ GrantTap MCP complements the agents' native permission hooks:
   a tool call and waits for Allow or Deny.
 - Both channels use the same end-to-end encrypted GrantTap pairing.
 
+| Visible iPhone activity | Approval on Apple Watch |
+| --- | --- |
+| ![GrantTap activity on iPhone](docs/images/phone-activity.png) | ![GrantTap approval on Apple Watch](docs/images/watch-approval.png) |
+
+The iPhone and Apple Watch app is preparing for App Store release. Current
+status and target date are published at [granttap.com](https://granttap.com).
+Support, privacy, terms, and license information are linked below and from the
+app's About screen.
+
 ## Install
 
 The shortest MCP-only setup is:
@@ -23,18 +32,23 @@ codex mcp add granttap -- npx -y granttap-mcp
 claude mcp add granttap -- npx -y granttap-mcp
 ```
 
-For approval hooks, install the command globally so the hook path remains
-stable, then register both supported agents:
+Pair this computer with the GrantTap app, then register the approval hooks:
 
 ```bash
 npm install -g granttap-mcp
+granttap-mcp connect
 granttap-mcp setup
 ```
 
-The GrantTap app and desktop bridge must already be paired. The pairing lives
-locally in `~/.granttap/machine.json`; this package reads it but never uploads
-the secret key. Existing beta installations using `~/.nodvox/` are migrated
-automatically.
+`connect` prints a QR and an optional one-time eight-character code. It uses
+the production zero-knowledge relay by default; pass your own `wss://` URL as
+the first argument to self-host. The pairing lives locally in
+`~/.granttap/machine.json`; this package never uploads the device secret key.
+Existing beta installations using `~/.nodvox/` are migrated automatically.
+
+`connect` also registers both hooks. `setup` is an idempotent standalone
+command for upgrades: it preserves unrelated settings and writes a backup
+before changing a configuration file.
 
 ## MCP tools
 
@@ -45,6 +59,14 @@ automatically.
 | `notify` | Sends a non-blocking status message |
 | `setup` | Registers the Claude Code and Codex approval hooks |
 
+## CLI commands
+
+| Command | Purpose |
+| --- | --- |
+| *(no command)* | Starts the GrantTap MCP stdio server |
+| `connect [relayUrl]` | Creates an E2EE pairing and prints a QR/short code |
+| `setup` | Registers the Claude Code and Codex approval hooks |
+
 The default answer timeout is three minutes. Override it with
 `GRANTTAP_ASK_TIMEOUT_MS`.
 
@@ -83,6 +105,10 @@ as `*.bak-granttap`.
 ## Related
 
 - Product: [granttap.com](https://granttap.com)
+- npm: [granttap-mcp](https://www.npmjs.com/package/granttap-mcp)
 - Relay: [sergii-ziborov/granttap-relay](https://github.com/sergii-ziborov/granttap-relay)
+- Privacy: [granttap.com/privacy](https://granttap.com/privacy)
+- Support: [granttap.com/support](https://granttap.com/support)
+- Security policy: [SECURITY.md](SECURITY.md)
 
 GrantTap is not affiliated with Anthropic or OpenAI.

package/SECURITY.md

@@ -0,0 +1,21 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Use GitHub's private
+[security advisory form](https://github.com/sergii-ziborov/granttap-mcp/security/advisories/new).
+For urgent coordination, contact `sergii.ziborov@gmail.com`.
+
+Do not open a public issue containing pairing codes, device keys, room
+identifiers, real prompts, command payloads, local configuration, or a working
+exploit. Include the affected package version or commit, expected impact, and
+a minimal reproduction using synthetic data.
+
+## Local secrets
+
+Pairing state belongs in `~/.granttap/` and must never be committed, attached
+to an issue, or pasted into logs. The package avoids printing device secret
+keys. Existing configuration files are backed up before hook installation.
+
+Relay vulnerabilities should be reported through the
+[GrantTap relay advisory form](https://github.com/sergii-ziborov/granttap-relay/security/advisories/new).

package/apps/bridge/src/bin/connect.ts

@@ -0,0 +1,109 @@
+import QRCode from "qrcode";
+import { generatePairingCode, sealWithCode } from "../../../../packages/core/crypto";
+import { installClaudeHook, installCodexHook, type InstallResult } from "../install";
+import {
+  createPairing,
+  machineConfigPath,
+  pairingUri,
+  phonePairingPath,
+  saveConfig,
+} from "../config";
+
+const DEFAULT_RELAY = "wss://granttap-relay.sergii-ziborov.workers.dev";
+
+function hookLine(name: string, result: InstallResult): string {
+  switch (result.status) {
+    case "installed":
+      return `  ✓ ${name}: hook installed (${result.detail}; backup: .bak-granttap)`;
+    case "already":
+      return `  ✓ ${name}: hook already installed (${result.detail})`;
+    case "manual":
+      return `  ! ${name}: ${result.detail}`;
+  }
+}
+
+async function connect(relayUrl: string): Promise<void> {
+  const { machineCfg, phoneCfg } = createPairing(relayUrl);
+  saveConfig(machineConfigPath(), machineCfg);
+  saveConfig(phonePairingPath(), phoneCfg);
+
+  const uri = pairingUri(phoneCfg);
+  const qr = await QRCode.toString(uri, {
+    type: "terminal",
+    small: true,
+    errorCorrectionLevel: "L",
+  });
+  process.stdout.write(["", "  Scan this code in GrantTap on iPhone:", "", qr].join("\n"));
+
+  const code = generatePairingCode(8);
+  const sealed = sealWithCode(phoneCfg, code);
+  const httpBase = relayUrl.replace(/^ws:/, "http:").replace(/^wss:/, "https:");
+  let codeReady = false;
+  try {
+    const response = await fetch(`${httpBase}/pair/${code}`, {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(sealed),
+    });
+    codeReady = response.ok;
+  } catch {
+    codeReady = false;
+  }
+
+  process.stdout.write(
+    codeReady
+      ? [
+          "",
+          "  Or enter this one-time code in the app:",
+          "",
+          `        ${code.slice(0, 4)} ${code.slice(4)}`,
+          "",
+          `  Relay: ${httpBase}`,
+          "  The code expires after 15 minutes and can be used once.",
+          "",
+        ].join("\n")
+      : [
+          "",
+          `  ! The relay at ${httpBase} did not accept a short code.`,
+          "    The QR still works. Check the relay and retry for code pairing.",
+          "",
+        ].join("\n"),
+  );
+
+  const skipHooks = process.env.GRANTTAP_SKIP_HOOKS === "1";
+  const claude = skipHooks ? null : installClaudeHook();
+  const codex = skipHooks ? null : installCodexHook();
+  process.stdout.write(
+    [
+      "",
+      "  GrantTap is paired on this machine.",
+      "",
+      `  room:        ${machineCfg.room}`,
+      `  relay:       ${relayUrl}`,
+      `  machine cfg: ${machineConfigPath()}`,
+      `  phone cfg:   ${phonePairingPath()} (manual fallback; keep private)`,
+      "",
+      ...(skipHooks
+        ? ["  Hooks: skipped (GRANTTAP_SKIP_HOOKS=1)"]
+        : [hookLine("Claude Code", claude!), hookLine("Codex", codex!)]),
+      "",
+      "  Keep the MCP server configured in your agent. Approval requests now",
+      "  use the paired phone and watch; if the relay is unavailable, hooks fall",
+      "  back to the agent's normal local approval flow.",
+      "",
+    ].join("\n"),
+  );
+}
+
+const relayUrl =
+  process.argv[2] ??
+  process.env.GRANTTAP_RELAY_URL ??
+  process.env.NODVOX_RELAY_URL ??
+  DEFAULT_RELAY;
+
+void connect(relayUrl).catch((error: unknown) => {
+  process.stderr.write(
+    `[granttap-mcp] connect failed: ${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exitCode = 1;
+});

package/bin/granttap-mcp.mjs

@@ -11,6 +11,8 @@ if (command === "mcp") {
   entry = join(root, "apps", "mcp", "src", "server.ts");
 } else if (command === "setup") {
   entry = join(root, "apps", "bridge", "src", "bin", "setup.ts");
+} else if (command === "connect") {
+  entry = join(root, "apps", "bridge", "src", "bin", "connect.ts");
 } else if (command === "hook" && (argument === "claude" || argument === "codex")) {
   entry = join(root, "apps", "bridge", "src", "bin", `${argument}-hook.ts`);
 } else {
@@ -18,6 +20,7 @@ if (command === "mcp") {
     [
       "Usage:",
       "  granttap-mcp                 Start the MCP stdio server",
+      "  granttap-mcp connect [url]   Pair this machine with iPhone/Apple Watch",
       "  granttap-mcp setup           Install Claude Code and Codex approval hooks",
       "  granttap-mcp hook <agent>    Internal hook entry point",
       "",

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "granttap-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "E2EE MCP bridge and approval hooks for GrantTap on iPhone and Apple Watch.",
   "type": "module",
   "bin": {
-    "granttap-mcp": "./bin/granttap-mcp.mjs"
+    "granttap-mcp": "bin/granttap-mcp.mjs"
   },
   "files": [
     "apps",
     "bin",
+    "docs",
     "packages",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "SECURITY.md"
   ],
   "scripts": {
     "start": "node bin/granttap-mcp.mjs",
@@ -22,6 +24,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "qrcode": "^1.5.4",
     "tsx": "^4.19.2",
     "tweetnacl": "^1.0.3",
     "ws": "^8.18.0",
@@ -29,6 +32,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
+    "@types/qrcode": "^1.5.6",
     "@types/ws": "^8.5.13",
     "typescript": "^5.7.2"
   },