granttap-mcp 0.6.4 → 0.6.7

package/README.md

@@ -75,16 +75,23 @@ not separate MCP billing.
 Add GrantTap to each agent you use:
 
 ```bash
-codex mcp add granttap -- npx -y granttap-mcp@latest
-claude mcp add granttap -- npx -y granttap-mcp@latest
+npm install
+npm install -g .
+codex mcp add granttap -- granttap
+claude mcp add granttap -- granttap
 ```
 
+Those commands use this checkout. Publish/release it before replacing the local
+install with an npm registry version.
+
 Start a fresh agent task and say **“Connect GrantTap.”** The `connect` tool:
 
 1. creates a new end-to-end encrypted pairing;
-2. returns a scannable one-time QR directly in the agent chat;
-3. installs the Codex and Claude Code approval hooks; and
-4. installs the per-user background helper for task sync and schedules.
+2. returns a scannable one-time QR directly in the agent chat.
+
+Then run the separate MCP `setup` tool. It installs Cursor shell/MCP policy
+hooks, the complete Claude Code matcher, both Codex hooks, and the per-user
+background helper for task sync and schedules.
 
 Scan the QR with GrantTap on iPhone. No terminal QR, copied pairing JSON, or
 open background terminal is required.
@@ -93,8 +100,9 @@ If an MCP client cannot render image content, use the CLI fallback:
 
 ```bash
 npm install -g granttap-mcp
-granttap-mcp connect
-granttap-mcp setup
+granttap connect
+granttap setup
+granttap status
 ```
 
 CLI `connect` prints a one-time QR and short manual code. `setup` is idempotent:
@@ -102,6 +110,72 @@ it preserves unrelated agent settings and backs up a configuration file before
 changing it. The pairing is stored locally in `~/.granttap/machine.json`.
 Existing beta state under `~/.nodvox/` is migrated automatically.
 
+After setup, open `/hooks` in Codex, review and trust both exact GrantTap hooks,
+then restart Codex. Installation alone is not reported as trusted or connected.
+
+## Cursor Settings → Authorize
+
+Cursor only shows **Authorize / Sign in** for **HTTP/SSE** MCP servers that
+speak OAuth (same pattern as Lovable / Figma). The default stdio entry
+(`command` + `args`) cannot show that button — Cursor documents stdio auth as
+**Manual**.
+
+To enable Authorize for GrantTap, use the one-step local setup:
+
+```bash
+npm install -g granttap-mcp
+granttap authorize
+```
+
+It preserves unrelated entries in `~/.cursor/mcp.json`, replaces only the
+`granttap` entry with the loopback HTTP endpoint, keeps a one-time
+`.bak-granttap`, and starts the OAuth MCP server. Then open
+**Cursor Settings → MCP → GrantTap → Authorize**. The local consent page shows
+the pairing QR plus a manual-token fallback when the Mac is not paired yet.
+`granttap authorize` installs a loopback-only per-user LaunchAgent, verifies its
+exact `/healthz` identity, writes Cursor config only after that check succeeds,
+and exits. The service uses RunAtLoad + KeepAlive, so closing the terminal or
+restarting the Mac does not leave Cursor pointing at a dead URL.
+
+The foreground troubleshooting flow is:
+
+1. Run the local HTTP OAuth server (loopback only):
+
+```bash
+granttap serve
+# listens on http://127.0.0.1:17342/mcp
+```
+
+2. Point Cursor at the HTTP URL in `~/.cursor/mcp.json` (replace the stdio
+   `command` entry):
+
+```json
+{
+  "mcpServers": {
+    "granttap": {
+      "url": "http://127.0.0.1:17342/mcp"
+    }
+  }
+}
+```
+
+3. Open **Cursor Settings → MCP → GrantTap** and click **Authorize**.
+   A local browser page confirms linking Cursor to this Mac’s pairing
+   (`~/.granttap`). If unpaired, it shows a one-time QR first.
+
+OAuth tokens are stored in `~/.granttap/mcp-oauth.json` (mode `0600`). They do
+**not** replace E2EE pairing keys. Claude Code / Codex can keep using the
+stdio transport; Authorize is a Cursor Settings affordance.
+
+Details: [docs/cursor-authorize.md](docs/cursor-authorize.md).
+
+`granttap setup` is the policy-hook entry point: it installs Cursor
+`beforeShellExecution`, `afterShellExecution`, and `beforeMCPExecution` hooks,
+plus Claude/Codex hooks and background task sync. It does not opt a new user
+into OAuth; when an exact Cursor HTTP entry already exists, it also repairs the
+persistent OAuth service. Per-chat blocks are checked before phone routing,
+and ambiguous/unscoped Cursor calls fall back to Cursor's native permission UI.
+
 ## Codex and Claude Code: honest capability matrix
 
 | Capability | Codex | Claude Code |
@@ -109,7 +183,7 @@ Existing beta state under `~/.nodvox/` is migrated automatically.
 | Approval hook | `PermissionRequest` when Codex hooks are enabled | `PreToolUse` |
 | Resume an existing task | Yes, through the local Codex CLI | Yes, through the local Claude CLI |
 | Start a new persistent task | Yes | Yes |
-| Up to five attachments | Images through Codex image inputs; documents as local paths | Local image/document paths in the turn |
+| Up to five attachments within one encrypted-frame budget | Images through Codex image inputs; documents as local paths | Local image/document paths in the turn |
 | Change filesystem access from iPhone | Read-only, workspace, or full for the next GrantTap turn | Not exposed; the existing Claude policy remains authoritative |
 | Disable MCP per task | Enforced for later GrantTap-delivered turns | Enforced for later GrantTap-delivered turns |
 | Usage and context | Reported when present in local task logs | Reported when present in local task logs |
@@ -133,7 +207,7 @@ Repository skills are discovered only in the selected task workspace under
 | `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 update |
-| `setup` | Registers both approval hooks and the terminal-free helper |
+| `setup` | Registers Cursor/Claude/Codex policy hooks and the terminal-free helper |
 
 The default answer timeout is three minutes. Override it with
 `GRANTTAP_ASK_TIMEOUT_MS`.
@@ -152,6 +226,14 @@ The default answer timeout is three minutes. Override it with
   Durable Objects, and APNs path.
 - APNs carries only a content-neutral wake. It contains no title, prompt,
   command, path, task kind, or response.
+- Cloudflare accepts at most a 32 MiB WebSocket frame. Because task messages are
+  sealed and base64-encoded twice, attachments share a 16,000,000-character
+  base64 budget (about 12 MB raw total); five small files fit, five 6 MB files do not.
+
+The in-chat QR is marked user-only for MCP hosts, but that annotation is not a
+cryptographic separation from the model provider. Use CLI `connect` when the
+model provider itself is part of your threat model; Cloudflare still receives
+only the mailbox id and ciphertext in either flow.
 
 The relay can still observe operational metadata: opaque room/mailbox IDs, IP
 addresses, timing, ciphertext sizes, and APNs device token/environment. A
@@ -181,8 +263,19 @@ time, agent, status, result, and created task ID.
 | Command | Purpose |
 | --- | --- |
 | *(no command)* | Starts the GrantTap MCP stdio server |
+| `serve` | HTTP MCP + loopback OAuth for Cursor Settings → Authorize |
+| `authorize` | Installs the persistent loopback OAuth service, verifies health, and configures Cursor |
 | `connect [relayUrl]` | Creates an E2EE pairing; optionally targets a self-hosted `wss://` relay |
-| `setup` | Registers the Codex/Claude hooks and background helper |
+| `setup` | Registers Cursor/Claude/Codex hooks, background sync, and repairs configured OAuth |
+| `status [--json]` | Reads local readiness; JSON uses `granttap.provider-status.v1` and contains no keys |
+
+The installed public command is `granttap`; `granttap-mcp` remains an alias for
+existing scripts. `status` only reads configuration and runtime state—it does
+not install hooks, pair a device, start OAuth, or reload the background helper.
+If Cursor has an HTTP GrantTap entry, status requires both an owned persistent
+service and a live identity-checked health response; a dead URL is never shown
+as connected. Without an HTTP entry, OAuth remains optional and Cursor policy
+readiness is based on the full hook set, pairing, and background sync.
 
 ## Development
 

package/SECURITY.md

@@ -18,8 +18,8 @@ to an issue, or pasted into logs. The package avoids printing device secret
 keys. Existing configuration files are backed up before hook installation.
 
 Current pairings contain three independent secret classes: NaCl endpoint keys,
-random per-task keys, and a random `pushAuth` room credential that only
-authorizes APNs device-token registration at the relay. None may be logged.
+random per-task keys, and a random `pushAuth` room credential that authorizes
+the room WebSocket and APNs device-token registration at the relay. None may be logged.
 The relay receives only a hash of `pushAuth` and never receives an endpoint's
 secret encryption key.
 
@@ -31,6 +31,11 @@ secret encryption key.
   separate random 256-bit transfer key. Only the mailbox id is used in the HTTP
   path. The key stays in the QR/manual token, so a relay operator or a Durable
   Object database dump cannot open the parked pairing blob.
+- The terminal `connect` flow keeps that transfer key outside model context.
+  The MCP `connect` tool deliberately returns a QR in chat for convenience and
+  marks it user-only, but MCP audience annotations are not a cryptographic
+  boundary: depending on the host, the chat/model provider may receive tool
+  images. Use terminal pairing when the model provider is in your threat model.
 - Every attached Codex or Claude Code task receives a separate random 256-bit
   task key. Task messages, attachments, visible activity, access/MCP changes,
   compaction results, and task-bound approvals use this additional authenticated
@@ -43,6 +48,8 @@ secret encryption key.
   transport, network, Cloudflare, Durable Objects, and APNs.
 - APNs is only a content-neutral wake. It contains no task kind, request id,
   delivery id, title, prompt, command, path, or response.
+  It is a best-effort silent background notification; after waking, iOS pulls
+  and decrypts the queue and creates the single actionable local notification.
 - Scheduler-planner turns and their structured drafts cross Cloudflare only as
   authenticated device-to-device ciphertext. The selected CLI runs locally in
   ephemeral read-only/plan mode; it cannot silently turn planning into a
@@ -65,7 +72,10 @@ different task's key—not against an already authorized endpoint.
 
 The delivery ledger and scheduler history are stored only on the paired Mac.
 They contain random message ids and local task metadata and are bounded and
-expired; do not attach real copies to bug reports.
+expired; do not attach real copies to bug reports. Delivery ACK is emitted only
+after a consumer accepts the decrypted payload. A processing lease recovers
+after a crash; agent execution is at-least-once across that rare crash window,
+because third-party Codex/Claude CLIs do not expose a transactional idempotency key.
 
 Chat history and capability metadata follow the same cryptographic boundary.
 The bridge reads a bounded set of local Codex/Claude logs, emits only chat

package/apps/bridge/src/adapters.ts

@@ -113,6 +113,56 @@ export function decisionToCodexOutput(d: ApprovalDecision): unknown {
   };
 }
 
+// --------------------------------------------------------------------- Cursor
+
+export type CursorHookInput = {
+  conversation_id?: string;
+  generation_id?: string;
+  command?: string;
+  cwd?: string;
+  hook_event_name?: string;
+  workspace_roots?: string[];
+  session_id?: string;
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+};
+
+export function cursorToRequest(input: CursorHookInput): ApprovalRequest {
+  const command = typeof input.command === "string" && input.command.trim()
+    ? input.command
+    : extractCommand("Shell", input.tool_input ?? {});
+  const sessionId = input.conversation_id ?? input.session_id;
+  const cwd = (typeof input.cwd === "string" && input.cwd.trim() ? input.cwd : undefined)
+    ?? (Array.isArray(input.workspace_roots) ? input.workspace_roots[0] : undefined);
+  return {
+    type: "approval.request",
+    requestId: randomId(6),
+    agent: "cursor",
+    kind: "permission",
+    tool: input.tool_name ?? "Shell",
+    title: shortTitle("Shell", command),
+    command,
+    cwd,
+    sessionId,
+    risk: guessRisk("Shell", command),
+    createdAt: Date.now(),
+  };
+}
+
+export function decisionToCursorOutput(d: ApprovalDecision): unknown {
+  const permission = d.decision === "allow" ? "allow" : "deny";
+  const message = d.note
+    ?? (d.decision === "allow" ? "Approved from GrantTap" : "Denied from GrantTap");
+  return {
+    permission,
+    continue: d.decision === "allow",
+    user_message: message,
+    agent_message: message,
+    userMessage: message,
+    agentMessage: message,
+  };
+}
+
 // ------------------------------------------------------------------ helpers
 
 function shortTitle(tool: string, command: string): string {