granttap-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Serhii Ziborov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# GrantTap MCP
+
+[![npm](https://img.shields.io/npm/v/granttap-mcp)](https://www.npmjs.com/package/granttap-mcp)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+The public, auditable machine-side bridge for [GrantTap](https://granttap.com):
+ask a person, send a status update, or request an approval on their iPhone or
+Apple Watch without sending agent traffic through a model proxy.
+
+GrantTap MCP complements the agents' native permission hooks:
+
+- MCP is the voluntary channel: the agent calls `ask`, `ask_yes_no`, or `notify`.
+- Hooks are the mandatory approval channel: Claude Code or Codex pauses before
+  a tool call and waits for Allow or Deny.
+- Both channels use the same end-to-end encrypted GrantTap pairing.
+
+## Install
+
+The shortest MCP-only setup is:
+
+```bash
+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:
+
+```bash
+npm install -g granttap-mcp
+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.
+
+## MCP tools
+
+| Tool | Result |
+| --- | --- |
+| `ask` | Sends an open question and waits for a spoken or typed reply |
+| `ask_yes_no` | Sends a yes/no question and waits for a tap |
+| `notify` | Sends a non-blocking status message |
+| `setup` | Registers the Claude Code and Codex approval hooks |
+
+The default answer timeout is three minutes. Override it with
+`GRANTTAP_ASK_TIMEOUT_MS`.
+
+## Security model
+
+Message payloads are authenticated and encrypted locally with NaCl
+public-key boxes. The relay receives only routing metadata and opaque
+ciphertext. It has no device secret key and cannot decrypt questions,
+commands, replies, or approvals.
+
+This repository intentionally includes the protocol, crypto client, relay
+client, MCP server, and agent hook adapters so that the complete public
+machine-side trust boundary can be reviewed.
+
+The relay still observes metadata such as room identifiers, IP addresses,
+timing, and message sizes. Review or self-host the public
+[GrantTap relay](https://github.com/sergii-ziborov/granttap-relay) if that
+metadata matters to your deployment.
+
+## Development
+
+Requires Node.js 20 or newer.
+
+```bash
+git clone https://github.com/sergii-ziborov/granttap-mcp.git
+cd granttap-mcp
+npm install
+npm test
+npm run typecheck
+```
+
+Start the stdio server with `npm start`. Run `npm run setup` only on a machine
+where you want the hooks installed; existing config files are backed up once
+as `*.bak-granttap`.
+
+## Related
+
+- Product: [granttap.com](https://granttap.com)
+- Relay: [sergii-ziborov/granttap-relay](https://github.com/sergii-ziborov/granttap-relay)
+
+GrantTap is not affiliated with Anthropic or OpenAI.

package/apps/bridge/src/adapters.ts

@@ -0,0 +1,124 @@
+/**
+ * Agent adapters — translate each agent's native permission format into our
+ * neutral ApprovalRequest, and translate our ApprovalDecision back into the
+ * shape that agent expects. The phone UI never learns which agent it approves.
+ *
+ * Both are wired end to end. The stdin payloads are nearly identical across
+ * Claude Code and Codex (tool_name / tool_input / cwd / session_id), so one
+ * mapper feeds both; only the ids and the stdout contract differ.
+ *
+ * Claude Code  — PreToolUse hook. stdout: hookSpecificOutput.permissionDecision
+ *                = "allow" | "deny" | "ask".  (docs: code.claude.com/docs/en/hooks)
+ * Codex        — requires `[features] hooks = true`, then the PermissionRequest
+ *                hook, the only one that can return BOTH allow and deny. stdout:
+ *                hookSpecificOutput.decision = { behavior: "allow" | "deny", message? }.
+ *                (Codex PreToolUse can only deny and only wraps `shell`.)
+ */
+import type { ApprovalDecision, ApprovalRequest, Risk } from "../../../packages/protocol/schema";
+import { randomId } from "../../../packages/core/crypto";
+
+/** Heuristic risk tag so the watch can color/rank the request at a glance. */
+export function guessRisk(tool: string, command: string | undefined): Risk {
+  const c = (command ?? "").toLowerCase();
+  const HIGH = [
+    /\brm\s+-rf?\b/,
+    /\bsudo\b/,
+    /\bgit\s+push\b.*--force/,
+    /\bgit\s+reset\s+--hard\b/,
+    /\bcurl\b[^|]*\|\s*(sh|bash)\b/,
+    /\bnpm\s+publish\b/,
+    /\bdd\s+if=/,
+    /\b(drop|truncate)\s+table\b/,
+    /:\s*>\s*\//, // truncate a file
+    /\bchmod\s+-r\b/,
+  ];
+  if (HIGH.some((re) => re.test(c))) return "high";
+  const READONLY = ["Read", "Glob", "Grep", "NotebookRead", "WebFetch", "WebSearch"];
+  if (READONLY.includes(tool)) return "low";
+  return "medium";
+}
+
+/** Fields shared by the Claude and Codex hook stdin payloads. */
+export type HookInput = {
+  session_id?: string;
+  cwd?: string;
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  tool_use_id?: string;
+  hook_event_name?: string;
+  permission_mode?: string;
+  transcript_path?: string;
+};
+
+function extractCommand(tool: string, ti: Record<string, unknown>): string {
+  const cmd = ti["command"];
+  if (typeof cmd === "string") return cmd;
+  if (Array.isArray(cmd)) return cmd.map(String).join(" "); // Codex shell: string[]
+  const path = ti["file_path"] ?? ti["path"] ?? ti["notebook_path"];
+  if (typeof path === "string") return `${tool} ${path}`;
+  const url = ti["url"];
+  if (typeof url === "string") return `${tool} ${url}`;
+  return tool;
+}
+
+function toRequest(agent: string, input: HookInput, idHint?: string): ApprovalRequest {
+  const tool = input.tool_name ?? "tool";
+  const command = extractCommand(tool, input.tool_input ?? {});
+  return {
+    type: "approval.request",
+    requestId: idHint ?? randomId(6),
+    agent,
+    kind: "permission",
+    tool,
+    title: shortTitle(tool, command),
+    command,
+    cwd: input.cwd,
+    sessionId: input.session_id,
+    risk: guessRisk(tool, command),
+    createdAt: Date.now(),
+  };
+}
+
+// ---------------------------------------------------------------- Claude Code
+
+export const claudeToRequest = (input: HookInput): ApprovalRequest => toRequest("claude", input);
+
+export function decisionToClaudeOutput(d: ApprovalDecision): unknown {
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: d.decision === "allow" ? "allow" : "deny",
+      permissionDecisionReason:
+        d.note ??
+        (d.decision === "allow" ? "Approved from GrantTap" : "Denied from GrantTap"),
+    },
+  };
+}
+
+// --------------------------------------------------------------------- Codex
+
+export const codexToRequest = (input: HookInput): ApprovalRequest =>
+  toRequest("codex", input, input.tool_use_id);
+
+export function decisionToCodexOutput(d: ApprovalDecision): unknown {
+  const decision =
+    d.decision === "allow"
+      ? { behavior: "allow" }
+      : { behavior: "deny", message: d.note ?? "Denied from GrantTap" };
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PermissionRequest",
+      decision,
+    },
+  };
+}
+
+// ------------------------------------------------------------------ helpers
+
+function shortTitle(tool: string, command: string): string {
+  if (command) {
+    const oneLine = command.replace(/\s+/g, " ").trim();
+    return oneLine.length > 80 ? oneLine.slice(0, 77) + "…" : oneLine;
+  }
+  return tool;
+}

package/apps/bridge/src/approval.ts

@@ -0,0 +1,67 @@
+/**
+ * Core approval round-trip, agent-agnostic.
+ *
+ * Connect to the relay, send one ApprovalRequest, block until the paired phone
+ * replies with a matching ApprovalDecision (or the timeout fires — fail closed,
+ * i.e. deny). This is what makes a phone tap gate a real tool call.
+ */
+import type { PeerConfig } from "../../../packages/core/relay-client";
+import { RelayClient } from "../../../packages/core/relay-client";
+import type { ApprovalDecision, ApprovalRequest, Payload } from "../../../packages/protocol/schema";
+
+export type RequestApprovalOpts = {
+  timeoutMs?: number;
+  /** Inject a client in tests instead of opening a socket. */
+  client?: RelayClient;
+};
+
+export async function requestApproval(
+  cfg: PeerConfig,
+  req: ApprovalRequest,
+  opts: RequestApprovalOpts = {},
+): Promise<ApprovalDecision> {
+  const timeoutMs = opts.timeoutMs ?? 60_000;
+  const client = opts.client ?? new RelayClient(cfg);
+  const ownsClient = !opts.client;
+
+  try {
+    if (ownsClient) {
+      try {
+        await client.connect();
+      } catch (err) {
+        // Relay unreachable is a different animal from "phone stayed silent":
+        // hooks translate it into "ask locally" so normal desk work keeps flowing.
+        return {
+          ...failClosed(req, `Relay недоступен: ${(err as Error).message}`),
+          decidedBy: "unreachable",
+        };
+      }
+    }
+    await client.send(req, "phone", { ttlMs: timeoutMs });
+    const decision = await client
+      .waitFor(
+        (p: Payload): p is ApprovalDecision =>
+          p.type === "approval.decision" && p.requestId === req.requestId,
+        timeoutMs,
+      )
+      .catch(() => null);
+
+    if (decision) return decision;
+    return failClosed(req, "No response from phone before timeout");
+  } catch (err) {
+    return failClosed(req, `Approval channel error: ${(err as Error).message}`);
+  } finally {
+    if (ownsClient) client.close();
+  }
+}
+
+function failClosed(req: ApprovalRequest, note: string): ApprovalDecision {
+  return {
+    type: "approval.decision",
+    requestId: req.requestId,
+    decision: "deny",
+    note,
+    decidedBy: "system",
+    decidedAt: Date.now(),
+  };
+}

package/apps/bridge/src/bin/claude-hook.ts

@@ -0,0 +1,92 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * Claude Code PreToolUse hook entry point.
+ *
+ * Registered in ~/.claude/settings.json so that before Claude runs a tool, this
+ * program receives the tool call on stdin, forwards it to your phone for
+ * approval, and prints the allow/deny decision Claude expects on stdout.
+ *
+ *   Reads:  PreToolUse JSON on stdin
+ *   Writes: { hookSpecificOutput: { permissionDecision, ... } } on stdout
+ *
+ * Fails closed: any error or timeout denies the tool call rather than letting it
+ * through unattended.
+ */
+import { claudeToRequest, decisionToClaudeOutput, type HookInput } from "../adapters";
+import { requestApproval } from "../approval";
+import { isGatingSkipped, loadConfig, machineConfigPath } from "../config";
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function main(): Promise<void> {
+  const raw = await readStdin();
+  let input: HookInput = {};
+  try {
+    input = JSON.parse(raw) as HookInput;
+  } catch {
+    // Unparseable input -> deny, but don't crash the agent.
+  }
+
+  // Gating paused, or this session is exempt → abstain (empty output = Claude
+  // uses its normal permission flow, exactly as if GrantTap weren't installed).
+  if (isGatingSkipped(input.session_id)) return;
+
+  let cfg;
+  try {
+    cfg = loadConfig(machineConfigPath());
+  } catch {
+    // No pairing yet: don't block the user's normal workflow — defer to Claude's
+    // own prompt by emitting "ask".
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "ask",
+          permissionDecisionReason: "GrantTap not paired (run `npm run init`)",
+        },
+      }),
+    );
+    return;
+  }
+
+  const req = claudeToRequest(input);
+  const timeoutMs = Number(
+    process.env.GRANTTAP_APPROVAL_TIMEOUT_MS ??
+      process.env.NODVOX_APPROVAL_TIMEOUT_MS ??
+      60_000,
+  );
+  const decision = await requestApproval(cfg, req, { timeoutMs });
+
+  // Relay down ≠ phone said no: hand the question back to the local prompt.
+  if (decision.decision === "deny" && decision.decidedBy === "unreachable") {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "ask",
+          permissionDecisionReason: "GrantTap relay недоступен — решай локально",
+        },
+      }),
+    );
+    return;
+  }
+
+  process.stdout.write(JSON.stringify(decisionToClaudeOutput(decision)));
+}
+
+main().catch((err) => {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: `GrantTap hook error: ${(err as Error).message}`,
+      },
+    }),
+  );
+  process.exit(0);
+});

package/apps/bridge/src/bin/codex-hook.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * Codex PermissionRequest hook entry point.
+ *
+ * Requires `[features] hooks = true` in ~/.codex/config.toml. Registered as a
+ * PermissionRequest hook (the only Codex hook that can return BOTH allow and
+ * deny). Same job as the Claude hook: forward the tool call to your phone,
+ * print the decision Codex expects.
+ *
+ *   Reads:  PermissionRequest JSON on stdin
+ *   Writes: { hookSpecificOutput: { decision: { behavior, message? } } } on stdout
+ *
+ * Fails closed on error/timeout.
+ */
+import { codexToRequest, decisionToCodexOutput, type HookInput } from "../adapters";
+import { requestApproval } from "../approval";
+import { isGatingSkipped, loadConfig, machineConfigPath } from "../config";
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function denyOutput(message: string): string {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PermissionRequest",
+      decision: { behavior: "deny", message },
+    },
+  });
+}
+
+async function main(): Promise<void> {
+  const raw = await readStdin();
+  let input: HookInput = {};
+  try {
+    input = JSON.parse(raw) as HookInput;
+  } catch {
+    // fall through: unparseable -> deny
+  }
+
+  // Gating paused or this session exempt → stay silent (Codex uses its own flow).
+  if (isGatingSkipped(input.session_id)) return;
+
+  let cfg;
+  try {
+    cfg = loadConfig(machineConfigPath());
+  } catch {
+    process.stdout.write(denyOutput("GrantTap not paired (run `npm run init`)"));
+    return;
+  }
+
+  const req = codexToRequest(input);
+  const timeoutMs = Number(
+    process.env.GRANTTAP_APPROVAL_TIMEOUT_MS ??
+      process.env.NODVOX_APPROVAL_TIMEOUT_MS ??
+      60_000,
+  );
+  const decision = await requestApproval(cfg, req, { timeoutMs });
+
+  // Relay down: stay silent — an empty hook result sends Codex back to its own
+  // approval flow, so desk work keeps going.
+  if (decision.decision === "deny" && decision.decidedBy === "unreachable") return;
+
+  process.stdout.write(JSON.stringify(decisionToCodexOutput(decision)));
+}
+
+main().catch((err) => {
+  process.stdout.write(denyOutput(`GrantTap hook error: ${(err as Error).message}`));
+  process.exit(0);
+});

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

@@ -0,0 +1,11 @@
+import { installClaudeHook, installCodexHook } from "../install";
+
+const claude = installClaudeHook();
+const codex = installCodexHook();
+
+process.stdout.write(
+  [
+    `Claude Code: ${claude.status} (${claude.detail})`,
+    `Codex: ${codex.status} (${codex.detail})`,
+  ].join("\n") + "\n",
+);

package/apps/bridge/src/config.ts

@@ -0,0 +1,169 @@
+/**
+ * Device config + pairing.
+ *
+ * A "pairing" is two halves of one E2EE relationship:
+ *   - machine.json  stays on the computer (its secret key + the phone's pubkey)
+ *   - the phone half is handed to the phone (later via QR; for now a file)
+ * Neither half ever contains the other side's secret, and the relay sees no key.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { generateKeyPair, randomId } from "../../../packages/core/crypto";
+import type { PeerConfig } from "../../../packages/core/relay-client";
+
+export function configDir(): string {
+  const overridden = process.env.GRANTTAP_CONFIG_DIR ?? process.env.NODVOX_CONFIG_DIR;
+  if (overridden) return overridden;
+
+  const current = join(homedir(), ".granttap");
+  const legacy = join(homedir(), ".nodvox");
+  if (!existsSync(current) && existsSync(legacy)) {
+    try {
+      // Same-volume rename keeps the existing pairing keys and their modes intact.
+      renameSync(legacy, current);
+    } catch {
+      // If migration is impossible, keep using the old directory instead of
+      // silently generating a new identity and breaking the active pairing.
+      return legacy;
+    }
+  }
+  return current;
+}
+
+export function machineConfigPath(): string {
+  return join(configDir(), "machine.json");
+}
+
+// ------------------------------------------------------------- runtime config
+//
+// The on/off switch and per-session exclusions the hook reads on every call.
+// Editable from the phone (a config.set payload the monitor persists here), so
+// you can pause gating or exempt a specific chat without touching any files.
+
+export type RuntimeConfig = {
+  enabled: boolean;
+  excludedSessions: string[];
+};
+
+const DEFAULT_RUNTIME: RuntimeConfig = { enabled: true, excludedSessions: [] };
+
+export function runtimeConfigPath(): string {
+  return join(configDir(), "config.json");
+}
+
+export function loadRuntimeConfig(): RuntimeConfig {
+  try {
+    const raw = JSON.parse(readFileSync(runtimeConfigPath(), "utf8"));
+    return {
+      enabled: raw.enabled !== false,
+      excludedSessions: Array.isArray(raw.excludedSessions) ? raw.excludedSessions.map(String) : [],
+    };
+  } catch {
+    return { ...DEFAULT_RUNTIME };
+  }
+}
+
+export function saveRuntimeConfig(cfg: RuntimeConfig): void {
+  mkdirSync(configDir(), { recursive: true });
+  writeFileSync(runtimeConfigPath(), JSON.stringify(cfg, null, 2) + "\n");
+}
+
+/** True when the hook should stay out of the way for this session. */
+export function isGatingSkipped(sessionId: string | undefined): boolean {
+  const cfg = loadRuntimeConfig();
+  if (!cfg.enabled) return true;
+  return sessionId != null && cfg.excludedSessions.includes(sessionId);
+}
+
+export function phonePairingPath(): string {
+  return join(configDir(), "phone.pairing.json");
+}
+
+export function saveConfig(path: string, cfg: PeerConfig): void {
+  mkdirSync(configDir(), { recursive: true });
+  writeFileSync(path, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+}
+
+export function loadConfig(path: string): PeerConfig {
+  return JSON.parse(readFileSync(path, "utf8")) as PeerConfig;
+}
+
+// ---------------------------------------------------------------- pairing URI
+//
+// The phone half of a pairing, packed into a single scannable URI. `granttap connect`
+// renders this as a QR code in the terminal; the app scans it instead of having
+// the user paste JSON. Keys are base64url so the URI stays query-safe.
+
+const b64url = (s: string): string => s.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+const unb64url = (s: string): string => {
+  const t = s.replace(/-/g, "+").replace(/_/g, "/");
+  return t + "=".repeat((4 - (t.length % 4)) % 4);
+};
+
+export function pairingUri(cfg: PeerConfig): string {
+  const q = new URLSearchParams({
+    v: "1",
+    u: cfg.relayUrl,
+    r: cfg.room,
+    s: b64url(cfg.mySecretKey),
+    p: b64url(cfg.peerPublicKey),
+    k: b64url(cfg.myPublicKey),
+    i: cfg.senderId,
+  });
+  return `granttap://pair?${q.toString()}`;
+}
+
+/** Inverse of `pairingUri` — used by tests and by any non-Apple client. */
+export function parsePairingUri(uri: string): PeerConfig | null {
+  let q: URLSearchParams;
+  try {
+    const u = new URL(uri);
+    if (u.protocol !== "granttap:" && u.protocol !== "nodvox:") return null;
+    q = u.searchParams;
+  } catch {
+    return null;
+  }
+  const get = (k: string) => q.get(k) ?? "";
+  if (!get("u") || !get("r") || !get("s") || !get("p")) return null;
+  return {
+    relayUrl: get("u"),
+    room: get("r"),
+    role: "phone",
+    deviceName: "phone",
+    senderId: get("i") || "phone",
+    myPublicKey: unb64url(get("k")),
+    mySecretKey: unb64url(get("s")),
+    peerPublicKey: unb64url(get("p")),
+  };
+}
+
+/** Create a fresh machine<->phone pairing. */
+export function createPairing(relayUrl: string): { machineCfg: PeerConfig; phoneCfg: PeerConfig } {
+  const machine = generateKeyPair();
+  const phone = generateKeyPair();
+  const room = randomId(8);
+
+  const machineCfg: PeerConfig = {
+    relayUrl,
+    room,
+    role: "machine",
+    deviceName: hostname(),
+    senderId: randomId(4),
+    myPublicKey: machine.publicKey,
+    mySecretKey: machine.secretKey,
+    peerPublicKey: phone.publicKey,
+  };
+  const phoneCfg: PeerConfig = {
+    relayUrl,
+    room,
+    role: "phone",
+    deviceName: "phone",
+    senderId: randomId(4),
+    myPublicKey: phone.publicKey,
+    mySecretKey: phone.secretKey,
+    peerPublicKey: machine.publicKey,
+  };
+  return { machineCfg, phoneCfg };
+}