granttap-mcp 0.6.4 → 0.6.5

package/README.md

@@ -109,7 +109,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 |
@@ -152,6 +152,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

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/bin/claude-hook.ts

@@ -28,7 +28,16 @@ async function main(): Promise<void> {
   try {
     input = JSON.parse(raw) as HookInput;
   } catch {
-    // Unparseable input -> deny, but don't crash the agent.
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "deny",
+          permissionDecisionReason: "GrantTap received invalid hook JSON",
+        },
+      }),
+    );
+    return;
   }
 
   // Gating paused, or this session is exempt → abstain (empty output = Claude

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

@@ -37,7 +37,8 @@ async function main(): Promise<void> {
   try {
     input = JSON.parse(raw) as HookInput;
   } catch {
-    // fall through: unparseable -> deny
+    process.stdout.write(denyOutput("GrantTap received invalid hook JSON"));
+    return;
   }
 
   // Gating paused or this session exempt → stay silent (Codex uses its own flow).

package/apps/bridge/src/capabilities.ts

@@ -166,7 +166,9 @@ async function safeIconData(src: string, remoteUrl?: URL): Promise<{
 } | undefined> {
   const dataMatch = src.match(/^data:image\/(png|jpe?g);base64,([a-z0-9+/=\s]+)$/i);
   if (dataMatch) {
-    const bytes = Buffer.from(dataMatch[2]!, "base64");
+    const encoded = dataMatch[2]!.replace(/\s/g, "");
+    if (encoded.length > Math.ceil(MAX_MCP_ICON_BYTES * 4 / 3) + 4) return undefined;
+    const bytes = Buffer.from(encoded, "base64");
     const mimeType = imageMime(bytes);
     if (!mimeType || bytes.length > MAX_MCP_ICON_BYTES) return undefined;
     return { src: `data:${mimeType};base64,${bytes.toString("base64")}`, mimeType };
@@ -197,7 +199,8 @@ async function safeIconData(src: string, remoteUrl?: URL): Promise<{
       if (!response.ok) return undefined;
       const length = Number(response.headers.get("content-length") ?? 0);
       if (Number.isFinite(length) && length > MAX_MCP_ICON_BYTES) return undefined;
-      const bytes = Buffer.from(await response.arrayBuffer());
+      const bytes = await readResponseBodyLimited(response, MAX_MCP_ICON_BYTES);
+      if (!bytes) return undefined;
       const mimeType = imageMime(bytes);
       if (!mimeType || bytes.length > MAX_MCP_ICON_BYTES) return undefined;
       return { src: `data:${mimeType};base64,${bytes.toString("base64")}`, mimeType };
@@ -208,6 +211,24 @@ async function safeIconData(src: string, remoteUrl?: URL): Promise<{
   return undefined;
 }
 
+async function readResponseBodyLimited(response: Response, maxBytes: number): Promise<Buffer | undefined> {
+  if (!response.body) return undefined;
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel().catch(() => {});
+      return undefined;
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total);
+}
+
 async function normalizedIcons(
   info: Implementation,
   descriptor: McpDescriptor,
@@ -272,7 +293,7 @@ async function normalizeServerMetadata(
 async function probeMetadata(descriptor: McpDescriptor): Promise<ServerMetadata | undefined> {
   const config = descriptor.transport;
   if (!config || !descriptor.configuredEnabled) return undefined;
-  const client = new Client({ name: "granttap-metadata", version: "0.6.4" });
+  const client = new Client({ name: "granttap-metadata", version: "0.6.5" });
   try {
     const type = typeof config.type === "string" ? config.type : undefined;
     if ((type === "streamable_http" || type === "http" || type === "sse") &&

package/apps/bridge/src/config.ts

@@ -8,7 +8,7 @@
  */
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { chmodSync, 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";
@@ -88,7 +88,8 @@ export function loadRuntimeConfig(): RuntimeConfig {
 
 export function saveRuntimeConfig(cfg: RuntimeConfig): void {
   mkdirSync(configDir(), { recursive: true });
-  writeFileSync(runtimeConfigPath(), JSON.stringify(cfg, null, 2) + "\n");
+  writeFileSync(runtimeConfigPath(), JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(runtimeConfigPath(), 0o600);
 }
 
 /** True when the hook should stay out of the way for this session. */
@@ -105,6 +106,8 @@ export function phonePairingPath(): string {
 export function saveConfig(path: string, cfg: PeerConfig): void {
   mkdirSync(configDir(), { recursive: true });
   writeFileSync(path, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+  // `mode` only applies when creating a file; repair permissive legacy files too.
+  chmodSync(path, 0o600);
 }
 
 export function loadConfig(path: string): PeerConfig {
@@ -123,6 +126,32 @@ const unb64url = (s: string): string => {
   return t + "=".repeat((4 - (t.length % 4)) % 4);
 };
 
+/** Canonicalize relay endpoints and reject schemes that can expose pairing data. */
+export function normalizeRelayUrl(value: string): string {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("relay URL is invalid");
+  }
+  if (url.protocol !== "wss:" && url.protocol !== "ws:") {
+    throw new Error("relay URL must use wss:// (ws:// is allowed for local development)");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname.endsWith(".localhost")
+    || url.hostname === "[::1]" || /^127(?:\.\d{1,3}){3}$/.test(url.hostname);
+  if (url.protocol === "ws:" && !loopback) {
+    throw new Error("unencrypted ws:// is allowed only for a loopback development relay");
+  }
+  if (url.username || url.password || url.hash || url.search) {
+    throw new Error("relay URL must not contain credentials, a query, or a fragment");
+  }
+  return url.toString().replace(/\/$/, "");
+}
+
+function validPairingKey(value: string): boolean {
+  return /^[A-Za-z0-9_-]{43,44}$/.test(value) && Buffer.from(unb64url(value), "base64").length === 32;
+}
+
 export function pairingUri(cfg: PeerConfig): string {
   const q = new URLSearchParams({
     v: "1",
@@ -148,9 +177,17 @@ export function parsePairingUri(uri: string): PeerConfig | null {
     return null;
   }
   const get = (k: string) => q.get(k) ?? "";
-  if (!get("u") || !get("r") || !get("s") || !get("p")) return null;
+  if (get("v") !== "1" || !/^[a-f0-9]{16,64}$/.test(get("r"))) return null;
+  if (!["s", "p", "k"].every((key) => validPairingKey(get(key)))) return null;
+  if (get("i").length > 180 || (get("a") && !/^[a-f0-9]{64}$/.test(get("a")))) return null;
+  let relayUrl: string;
+  try {
+    relayUrl = normalizeRelayUrl(get("u"));
+  } catch {
+    return null;
+  }
   return {
-    relayUrl: get("u"),
+    relayUrl,
     room: get("r"),
     role: "phone",
     deviceName: "phone",
@@ -164,9 +201,11 @@ export function parsePairingUri(uri: string): PeerConfig | null {
 
 /** Create a fresh machine<->phone pairing. */
 export function createPairing(relayUrl: string): { machineCfg: PeerConfig; phoneCfg: PeerConfig } {
+  relayUrl = normalizeRelayUrl(relayUrl);
   const machine = generateKeyPair();
   const phone = generateKeyPair();
-  const room = randomId(8);
+  // 128 bits keeps the relay's TOFU room rendezvous unguessable in practice.
+  const room = randomId(16);
   const pushAuth = randomId(32);
 
   const machineCfg: PeerConfig = {

package/apps/bridge/src/delivery.ts

@@ -1,39 +1,87 @@
 /** Persistent idempotency ledger for phone messages and their delivery receipts. */
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { configDir } from "./config";
 
 const LIMIT = 500;
 const MAX_AGE_MS = 7 * 24 * 60 * 60_000;
+const PROCESSING_LEASE_MS = 5 * 60_000;
+
+type DeliveryRecord = {
+  state: "processing" | "completed";
+  updatedAt: number;
+};
+
+export type DeliveryStart = "started" | "processing" | "completed";
 
 export function deliveryLedgerPath(): string {
   return join(configDir(), "delivery-ledger.json");
 }
 
-function load(): Record<string, number> {
+function load(): Record<string, DeliveryRecord> {
   try {
     const raw = JSON.parse(readFileSync(deliveryLedgerPath(), "utf8"));
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
-    return Object.fromEntries(
-      Object.entries(raw).filter((entry): entry is [string, number] =>
-        typeof entry[0] === "string" && typeof entry[1] === "number"),
-    );
+    const records: Record<string, DeliveryRecord> = {};
+    for (const [id, value] of Object.entries(raw)) {
+      // Migrate the original `{ id: acceptedAt }` ledger as completed work.
+      if (typeof value === "number") records[id] = { state: "completed", updatedAt: value };
+      else if (value && typeof value === "object"
+          && ((value as DeliveryRecord).state === "processing"
+            || (value as DeliveryRecord).state === "completed")
+          && typeof (value as DeliveryRecord).updatedAt === "number") {
+        records[id] = value as DeliveryRecord;
+      }
+    }
+    return records;
   } catch {
     return {};
   }
 }
 
 export function hasAcceptedDelivery(messageId: string, now = Date.now()): boolean {
-  const acceptedAt = load()[messageId];
-  return acceptedAt != null && acceptedAt >= now - MAX_AGE_MS;
+  const record = load()[messageId];
+  return record?.state === "completed" && record.updatedAt >= now - MAX_AGE_MS;
 }
 
-export function rememberAcceptedDelivery(messageId: string, now = Date.now()): void {
+function save(records: Record<string, DeliveryRecord>, now: number): void {
   const cutoff = now - MAX_AGE_MS;
-  const entries = Object.entries(load())
-    .filter(([, acceptedAt]) => acceptedAt >= cutoff && acceptedAt <= now)
-    .sort((a, b) => b[1] - a[1]);
-  const next = Object.fromEntries([[messageId, now], ...entries.filter(([id]) => id !== messageId)].slice(0, LIMIT));
+  const next = Object.fromEntries(Object.entries(records)
+    .filter(([, record]) => record.updatedAt >= cutoff && record.updatedAt <= now)
+    .sort((a, b) => b[1].updatedAt - a[1].updatedAt)
+    .slice(0, LIMIT));
   mkdirSync(configDir(), { recursive: true });
   writeFileSync(deliveryLedgerPath(), `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(deliveryLedgerPath(), 0o600);
+}
+
+/** Acquire a durable processing lease before invoking an agent. */
+export function beginDelivery(messageId: string, now = Date.now()): DeliveryStart {
+  const records = load();
+  const current = records[messageId];
+  if (current?.state === "completed" && current.updatedAt >= now - MAX_AGE_MS) return "completed";
+  if (current?.state === "processing" && current.updatedAt >= now - PROCESSING_LEASE_MS) {
+    return "processing";
+  }
+  records[messageId] = { state: "processing", updatedAt: now };
+  save(records, now);
+  return "started";
+}
+
+export function completeDelivery(messageId: string, now = Date.now()): void {
+  const records = load();
+  records[messageId] = { state: "completed", updatedAt: now };
+  save(records, now);
+}
+
+/** Release a failed attempt so a relay retry can safely try again. */
+export function abandonDelivery(messageId: string, now = Date.now()): void {
+  const records = load();
+  delete records[messageId];
+  save(records, now);
+}
+
+/** @deprecated Compatibility wrapper for callers/tests from the old ledger. */
+export function rememberAcceptedDelivery(messageId: string, now = Date.now()): void {
+  completeDelivery(messageId, now);
 }

package/apps/bridge/src/monitor.ts

@@ -20,7 +20,7 @@ import { configDir, loadRuntimeConfig, saveRuntimeConfig } from "./config";
 import { mcpServersForSession, workspaceSkills } from "./capabilities";
 import { compactCodexSession } from "./codex-control";
 import { createClaudeSession, createCodexSession, deliverToSession } from "./reply";
-import { hasAcceptedDelivery, rememberAcceptedDelivery } from "./delivery";
+import { abandonDelivery, beginDelivery, completeDelivery } from "./delivery";
 import { inspectAgentIntegrations } from "./install";
 import { primeSessionKeys, sendSessionPayload } from "./session-keys";
 import {
@@ -132,47 +132,72 @@ export function startSessionMonitor(client: RelayClient): SessionMonitor {
     }
   };
 
-  const off = client.onMessage((payload) => {
+  const off = client.onMessage(async (payload) => {
     // Codex may start one MCP server per open task. Exactly one instance owns
     // phone routing, so a single phone message can never create duplicate tasks.
-    if (!leadership.acquire()) return;
+    if (!leadership.acquire()) return false;
     if (payload.type === "user.message") {
+      // Correlated replies belong to the MCP `ask` waiter in one process.
+      if (payload.requestId) return false;
+      let deliveryStarted = false;
       if (payload.messageId) {
-        const duplicate = hasAcceptedDelivery(payload.messageId);
-        if (!duplicate) rememberAcceptedDelivery(payload.messageId);
-        void sendDeliveryReceipt(client, payload.messageId, "accepted", undefined, payload.sessionId);
-        if (duplicate) return;
+        const state = beginDelivery(payload.messageId);
+        if (state === "completed") {
+          await sendDeliveryReceipt(client, payload.messageId, "accepted", undefined, payload.sessionId);
+          return true;
+        }
+        if (state === "processing") return false;
+        deliveryStarted = true;
       }
-      // Replies correlated with an MCP `ask` are consumed by that tool call.
-      if (!payload.requestId) {
-        void handleUserMessage(client, payload).finally(() => publish().catch(() => {}));
+      try {
+        await handleUserMessage(client, payload);
+        if (payload.messageId && deliveryStarted) {
+          completeDelivery(payload.messageId);
+          await sendDeliveryReceipt(client, payload.messageId, "accepted", undefined, payload.sessionId);
+        }
+        void publish().catch(() => {});
+        return true;
+      } catch {
+        if (payload.messageId && deliveryStarted) abandonDelivery(payload.messageId);
+        return false;
       }
     } else if (payload.type === "config.set") {
       handleConfigSet(payload);
       void publish().catch(() => {});
+      return true;
     } else if (payload.type === "session.subscribe") {
       handleSubscription(subscriptions, payload);
       void publish().catch(() => {});
+      return true;
     } else if (payload.type === "session.access.set") {
       handleAccessSet(payload);
       void publish().catch(() => {});
+      return true;
     } else if (payload.type === "session.mcp.set") {
       handleMcpSet(payload);
       void publish().catch(() => {});
+      return true;
     } else if (payload.type === "session.compact") {
-      void handleCompact(client, payload).finally(() => publish().catch(() => {}));
+      await handleCompact(client, payload);
+      void publish().catch(() => {});
+      return true;
     } else if (payload.type === "schedule.set") {
       handleScheduleSet(payload);
       void publish().catch(() => {});
+      return true;
     } else if (payload.type === "schedule.delete") {
       handleScheduleDelete(payload);
       void publish().catch(() => {});
+      return true;
     } else if (payload.type === "schedule.run") {
       handleScheduleRun(payload);
       void publish().catch(() => {});
+      return true;
     } else if (payload.type === "schedule.plan.request") {
-      void handleSchedulePlan(client, payload);
+      await handleSchedulePlan(client, payload);
+      return true;
     }
+    return false;
   });
 
   const timer = setInterval(() => void publish().catch(() => {}), INTERVAL_MS);

package/apps/bridge/src/pairing.ts

@@ -8,6 +8,7 @@ import {
 import {
   createPairing,
   machineConfigPath,
+  normalizeRelayUrl,
   phonePairingPath,
   saveConfig,
 } from "./config";
@@ -30,7 +31,9 @@ export type OneTimePairing = {
 };
 
 export function relayHttpBase(relayUrl: string): string {
-  return relayUrl.replace(/^ws:/, "http:").replace(/^wss:/, "https:").replace(/\/$/, "");
+  const url = new URL(normalizeRelayUrl(relayUrl));
+  url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+  return url.toString().replace(/\/$/, "");
 }
 
 /**
@@ -66,6 +69,7 @@ export async function createOneTimePairing(
       headers: { "content-type": "application/json" },
       body: JSON.stringify(sealed),
       signal: AbortSignal.timeout(10_000),
+      redirect: "error",
     });
   } catch (error) {
     throw new Error(

package/apps/bridge/src/scheduler.ts

@@ -1,6 +1,6 @@
 /** Terminal-free local schedules shared by Codex and Claude Code. */
 import { randomUUID } from "node:crypto";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import {
@@ -42,6 +42,7 @@ export function scheduleHistorySnapshot(): ScheduleRunRecord[] {
 function saveHistory(history: ScheduleRunRecord[]): void {
   mkdirSync(configDir(), { recursive: true });
   writeFileSync(scheduleHistoryPath(), `${JSON.stringify(history.slice(0, 200), null, 2)}\n`, { mode: 0o600 });
+  chmodSync(scheduleHistoryPath(), 0o600);
 }
 
 export function loadSchedules(): ScheduledTask[] {
@@ -60,6 +61,7 @@ export function loadSchedules(): ScheduledTask[] {
 function saveSchedules(tasks: ScheduledTask[]): void {
   mkdirSync(configDir(), { recursive: true });
   writeFileSync(schedulesPath(), `${JSON.stringify(tasks, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(schedulesPath(), 0o600);
 }
 
 export function scheduledSnapshot(now = Date.now()): ScheduledTask[] {

package/apps/bridge/src/session-keys.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { generateTransferKey } from "../../../packages/core/crypto";
 import { RelayClient, type SendOptions } from "../../../packages/core/relay-client";
@@ -25,6 +25,7 @@ function load(): SessionKeys {
 function save(keys: SessionKeys): void {
   mkdirSync(configDir(), { recursive: true });
   writeFileSync(sessionKeysPath(), `${JSON.stringify(keys, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(sessionKeysPath(), 0o600);
 }
 
 export function sessionKey(sessionId: string): string {

package/apps/mcp/src/server.ts

@@ -19,7 +19,7 @@ import { z } from "zod";
 import QRCode from "qrcode";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { RelayClient } from "../../../packages/core/relay-client";
-import { loadConfig, machineConfigPath } from "../../bridge/src/config";
+import { loadConfig, machineConfigPath, normalizeRelayUrl } from "../../bridge/src/config";
 import { installClaudeHook, installCodexHook, installMonitorHelper } from "../../bridge/src/install";
 import { randomId } from "../../../packages/core/crypto";
 import type { Payload } from "../../../packages/protocol/schema";
@@ -67,7 +67,7 @@ async function main(): Promise<void> {
   const server = new McpServer({
     name: "granttap",
     title: "GrantTap",
-    version: "0.6.4",
+    version: "0.6.5",
     websiteUrl: "https://granttap.com",
     icons: [
       {
@@ -84,7 +84,13 @@ async function main(): Promise<void> {
     {
       relayUrl: z
         .string()
+        .max(2_048)
         .url()
+        .refine((value) => {
+          try { normalizeRelayUrl(value); return true; } catch { return false; }
+        }, {
+          message: "Relay URL must use wss:// (or loopback ws:// for local development)",
+        })
         .optional()
         .describe("Optional wss:// relay URL. Omit to use the GrantTap production relay."),
     },
@@ -107,13 +113,18 @@ async function main(): Promise<void> {
               type: "text",
               text: [
                 "Scan this QR with GrantTap on iPhone to pair this computer.",
-                `Manual secure token: ${pairing.manualToken}`,
                 `Relay: ${pairing.httpBase}`,
                 `The encrypted mailbox is single-use and expires after ${PAIRING_CODE_TTL_MINUTES} minutes.`,
-                "The relay receives only a random mailbox id and ciphertext; the independent 256-bit transfer key stays in this QR/token.",
+                "The relay receives only a random mailbox id and ciphertext; the independent 256-bit transfer key stays in this user-only QR.",
               ].join("\n"),
+              annotations: { audience: ["user"] },
+            },
+            {
+              type: "image",
+              data: png.toString("base64"),
+              mimeType: "image/png",
+              annotations: { audience: ["user"] },
             },
-            { type: "image", data: png.toString("base64"), mimeType: "image/png" },
           ],
         };
       } catch (error) {
@@ -133,7 +144,7 @@ async function main(): Promise<void> {
   server.tool(
     "notify",
     "Push a short status/message to the user's phone. Fire-and-forget — use it to keep them informed without blocking.",
-    { message: z.string().describe("Text to show on the phone") },
+    { message: z.string().min(1).max(8_000).describe("Text to show on the phone") },
     async ({ message }) => {
       const c = await relay();
       if (!c) return { content: [{ type: "text", text: NOT_PAIRED }] };
@@ -149,7 +160,7 @@ async function main(): Promise<void> {
   server.tool(
     "ask_yes_no",
     "Ask the user a yes/no question on their phone/watch and wait for the tap. Returns 'yes' or 'no'.",
-    { question: z.string().describe("A question answerable with yes/no") },
+    { question: z.string().min(1).max(8_000).describe("A question answerable with yes/no") },
     async ({ question }) => {
       const c = await relay();
       if (!c) return { content: [{ type: "text", text: NOT_PAIRED }] };
@@ -183,7 +194,7 @@ async function main(): Promise<void> {
   server.tool(
     "ask",
     "Ask the user an open question on their phone/watch and wait for their spoken or typed reply. Returns their answer text.",
-    { question: z.string().describe("The question to ask") },
+    { question: z.string().min(1).max(8_000).describe("The question to ask") },
     async ({ question }) => {
       const c = await relay();
       if (!c) return { content: [{ type: "text", text: NOT_PAIRED }] };

package/bin/granttap-mcp.mjs

@@ -32,7 +32,8 @@ if (command === "mcp") {
   process.exit(1);
 }
 
-const child = spawn(process.execPath, ["--import", "tsx", entry], {
+const forwardedArgs = command === "connect" ? process.argv.slice(3) : [];
+const child = spawn(process.execPath, ["--import", "tsx", entry, ...forwardedArgs], {
   stdio: "inherit",
   env: process.env,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "granttap-mcp",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "Control Codex and Claude Code from iPhone and Apple Watch with zero-knowledge E2EE approvals, replies, and task sync.",
   "type": "module",
   "bin": {
@@ -22,9 +22,9 @@
     "prepublishOnly": "npm test && npm run typecheck"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "qrcode": "^1.5.4",
-    "tsx": "^4.19.2",
+    "tsx": "^4.23.4",
     "tweetnacl": "^1.0.3",
     "ws": "^8.18.0",
     "zod": "^3.24.1"

package/packages/core/relay-client.ts

@@ -10,7 +10,7 @@
  * the Cloudflare Durable Object deployment.
  */
 import WebSocket from "ws";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { Envelope, PROTOCOL_VERSION, Payload, type Role } from "../protocol/schema";
 import { open, openWithTransferKey, seal, sealWithTransferKey } from "./crypto";
 
@@ -27,7 +27,8 @@ export type PeerConfig = {
   pushAuth?: string;
 };
 
-type Listener = (p: Payload) => void;
+/** Return true only after this consumer has durably accepted the payload. */
+type Listener = (p: Payload) => boolean | void | Promise<boolean | void>;
 
 export type RelayClientOptions = {
   /** Persistent processes reconnect in the background; one-shot hooks leave this off. */
@@ -52,6 +53,15 @@ export class RelayClient {
   private reconnectTimer?: NodeJS.Timeout;
   private reconnectDelay: number;
   private readonly sessionKeys = new Map<string, string>();
+  /**
+   * Delivery ids are relay-controlled metadata, so replay protection is bound
+   * to the authenticated ciphertext itself. Keep a bounded process-local set:
+   * relay retries are acknowledged, but never delivered to the application
+   * twice even if an attacker changes the clear-text delivery id.
+   */
+  private readonly seenCiphertexts = new Set<string>();
+  private readonly processingCiphertexts = new Set<string>();
+  private static readonly MAX_SEEN_CIPHERTEXTS = 2_048;
 
   constructor(
     private readonly cfg: PeerConfig,
@@ -101,7 +111,7 @@ export class RelayClient {
           .catch(() => {});
         resolve();
       });
-      ws.on("message", (data: WebSocket.RawData) => this.onRaw(data.toString()));
+      ws.on("message", (data: WebSocket.RawData) => void this.onRaw(data.toString()));
       ws.on("error", (err) => {
         clearTimeout(timer);
         if (!opened) reject(err);
@@ -119,11 +129,13 @@ export class RelayClient {
     return this.connectPromise;
   }
 
-  private onRaw(raw: string): void {
+  private async onRaw(raw: string): Promise<void> {
     const parsed = Envelope.safeParse(safeJson(raw));
     if (!parsed.success) return;
     const env = parsed.data;
     if (env.room !== this.cfg.room) return;
+    if (env.from !== this.otherRole()) return;
+    if (env.to !== this.cfg.role && env.to !== "all") return;
     if (env.expiresAt != null && env.expiresAt <= Date.now()) return;
     const body = open(env.nonce, env.box, this.cfg.peerPublicKey, this.cfg.mySecretKey);
     if (body === null) return; // not for us, or tampered
@@ -131,20 +143,60 @@ export class RelayClient {
     if (!parsedPayload.success) return;
     let payload: Payload = parsedPayload.data;
     if (payload.type === "session.key.grant") {
-      this.sessionKeys.set(payload.sessionId, payload.key);
+      // Only the machine may attach a task and grant its independent key.
+      if (this.cfg.role !== "phone") return;
     } else if (payload.type === "session.sealed") {
       const key = this.sessionKeys.get(payload.sessionId);
       if (!key) return;
       const inner = openWithTransferKey(payload.nonce, payload.box, key);
       const parsedInner = Payload.safeParse(inner);
-      if (!parsedInner.success || parsedInner.data.type === "session.key.grant"
-          || parsedInner.data.type === "session.sealed") return;
+      if (
+        !parsedInner.success ||
+        parsedInner.data.type === "session.key.grant" ||
+        parsedInner.data.type === "session.sealed"
+      ) return;
+      const innerSessionId = "sessionId" in parsedInner.data ? parsedInner.data.sessionId : undefined;
+      if (typeof innerSessionId === "string" && innerSessionId !== payload.sessionId) return;
       payload = parsedInner.data;
     }
-    if (env.deliveryId && this.ws?.readyState === WebSocket.OPEN) {
-      this.ws.send(JSON.stringify({ type: "relay.ack", deliveryId: env.deliveryId }));
+
+    const fingerprint = createHash("sha256")
+      .update(env.nonce)
+      .update(".")
+      .update(env.box)
+      .digest("base64url");
+    if (this.seenCiphertexts.has(fingerprint)) {
+      this.ackDelivery(env.deliveryId);
+      return;
+    }
+    if (payload.type === "session.key.grant") {
+      this.sessionKeys.set(payload.sessionId, payload.key);
+    }
+    if (this.processingCiphertexts.has(fingerprint)) return;
+    this.processingCiphertexts.add(fingerprint);
+    try {
+      const results = await Promise.all([...this.listeners].map(async (listener) => {
+        try { return (await listener(payload)) === true; } catch { return false; }
+      }));
+      // Hello and key grants are completely consumed by RelayClient itself.
+      const accepted = payload.type === "hello" || payload.type === "session.key.grant"
+        || results.some(Boolean);
+      if (!accepted) return;
+      this.seenCiphertexts.add(fingerprint);
+      if (this.seenCiphertexts.size > RelayClient.MAX_SEEN_CIPHERTEXTS) {
+        const oldest = this.seenCiphertexts.values().next().value;
+        if (oldest) this.seenCiphertexts.delete(oldest);
+      }
+      this.ackDelivery(env.deliveryId);
+    } finally {
+      this.processingCiphertexts.delete(fingerprint);
+    }
+  }
+
+  private ackDelivery(deliveryId: string | undefined): void {
+    if (deliveryId && this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify({ type: "relay.ack", deliveryId }));
     }
-    for (const l of this.listeners) l(payload);
   }
 
   async send(
@@ -214,7 +266,9 @@ export class RelayClient {
           clearTimeout(timer);
           off();
           resolve(p);
+          return true;
         }
+        return false;
       });
     });
   }

package/packages/protocol/schema.ts

@@ -65,6 +65,13 @@ export const UserAttachment = z.object({
 });
 export type UserAttachment = z.infer<typeof UserAttachment>;
 
+/**
+ * Task messages are sealed twice (task key, then device key), and each NaCl
+ * layer base64-encodes its ciphertext. This budget keeps the final frame below
+ * Cloudflare's 32 MiB WebSocket receive limit with JSON overhead.
+ */
+export const MAX_ATTACHMENT_BASE64_CHARS = 16_000_000;
+
 export const UserMessage = z.object({
   type: z.literal("user.message"),
   /** Stable id makes phone retries idempotent and powers delivery receipts. */
@@ -477,7 +484,17 @@ export const Payload = z.discriminatedUnion("type", [
   SchedulePlanRequest,
   SchedulePlanResult,
   Hello,
-]);
+]).superRefine((payload, ctx) => {
+  if (payload.type !== "user.message") return;
+  const encodedCharacters = payload.attachments?.reduce((total, item) => total + item.data.length, 0) ?? 0;
+  if (encodedCharacters > MAX_ATTACHMENT_BASE64_CHARS) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["attachments"],
+      message: `attachments exceed the ${MAX_ATTACHMENT_BASE64_CHARS}-character encrypted transport budget`,
+    });
+  }
+});
 export type Payload = z.infer<typeof Payload>;
 
 /** The routed unit. `nonce`+`box` are the sealed Payload; relay can't open it. */