pi-mcp-extension 1.7.2 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-extension",
-  "version": "1.7.2",
+  "version": "1.8.0",
   "description": "MCP (Model Context Protocol) client extension for the Pi coding agent — connect Pi to any MCP server",
   "type": "module",
   "keywords": [

package/src/auth-lock.ts

@@ -0,0 +1,426 @@
+/**
+ * Cross-process per-server interactive OAuth authorization lock.
+ *
+ * Uses an atomic lock file (<hash>.json.lock, mode 0600) containing a
+ * versioned JSON record (PID, hostname, random nonce, creation timestamp)
+ * plus a periodic mtime heartbeat. Automatically reclaims locks left behind
+ * by crashed or SIGKILLed processes using a nonce-verified rename protocol.
+ */
+
+import {
+  open,
+  readFile,
+  stat,
+  rename,
+  unlink,
+  link,
+  utimes,
+  mkdir,
+  chmod,
+} from "node:fs/promises";
+import { readFileSync, unlinkSync } from "node:fs";
+import { hostname as osHostname } from "node:os";
+import { join } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { z } from "zod";
+import { agentDir } from "./config.js";
+
+// ─── Constants & Schema ───────────────────────────────────────────────────────
+
+export const HEARTBEAT_MS = 30_000;
+export const STALE_MS = 90_000; // 3 × 30s heartbeat
+
+export const LockRecordSchema = z.object({
+  v: z.literal(1),
+  pid: z.number().int().positive(),
+  hostname: z.string().min(1),
+  nonce: z.string().min(1),
+  createdAt: z.number(),
+});
+
+export type LockRecord = z.output<typeof LockRecordSchema>;
+
+// ─── Errors ───────────────────────────────────────────────────────────────────
+
+export class AuthRequiredError extends Error {
+  constructor(
+    serverName: string,
+    message = `Authorization required for ${serverName}. Connect in an interactive Pi session or use /mcp:auth ${serverName}.`,
+  ) {
+    super(message);
+    this.name = "AuthRequiredError";
+  }
+}
+
+export class AuthLockError extends AuthRequiredError {
+  constructor(serverName: string, details?: string) {
+    const message = details
+      ? details.startsWith("Authorization lock") || details.startsWith("Another Pi process")
+        ? details
+        : `Another Pi process (${details}) is authorizing ${serverName}. Retry after it finishes.`
+      : `Another Pi process is authorizing ${serverName}. Retry after it finishes.`;
+    super(serverName, message);
+    this.name = "AuthLockError";
+  }
+}
+
+// ─── Dependency Injection Types ───────────────────────────────────────────────
+
+export interface AuthLockFileHandle {
+  writeFile(data: string): Promise<void>;
+  sync(): Promise<void>;
+  close(): Promise<void>;
+}
+
+export interface AuthLockFs {
+  open(path: string, flags: string, mode?: number): Promise<AuthLockFileHandle>;
+  readFile(path: string, encoding: BufferEncoding): Promise<string>;
+  stat(path: string): Promise<{ mtimeMs: number }>;
+  rename(oldPath: string, newPath: string): Promise<void>;
+  unlink(path: string): Promise<void>;
+  link(existingPath: string, newPath: string): Promise<void>;
+  utimes(path: string, atime: number | string | Date, mtime: number | string | Date): Promise<void>;
+  mkdir(path: string, options?: { recursive?: boolean; mode?: number }): Promise<string | undefined | void>;
+  chmod(path: string, mode: number): Promise<void>;
+}
+
+export interface AuthLockTimer {
+  unref?: () => void;
+}
+
+export interface AuthLockClock {
+  now(): number;
+  setInterval(callback: () => void, ms: number): ReturnType<typeof setInterval> | AuthLockTimer;
+  clearInterval(timer: any): void;
+}
+
+export interface AuthLockDeps {
+  fs: AuthLockFs;
+  clock: AuthLockClock;
+  pid: number;
+  hostname: string;
+  isPidAlive: (pid: number) => boolean;
+}
+
+export interface AcquireAuthLockOptions {
+  onLost?: (() => void) | undefined;
+  deps?: Partial<AuthLockDeps> | undefined;
+}
+
+export type AuthLockHandle = (() => Promise<void>) & {
+  assertHeld: () => Promise<void>;
+  isLost: () => boolean;
+};
+
+// ─── Path & Default Dependency Helpers ────────────────────────────────────────
+
+export function authDir(storageDir?: string): string {
+  return storageDir ?? join(agentDir(), "mcp-auth");
+}
+
+export function statePath(serverName: string, storageDir?: string): string {
+  // Hash the server name to avoid filesystem issues with special chars
+  const hash = createHash("sha256").update(serverName).digest("hex").slice(0, 16);
+  return join(authDir(storageDir), `${hash}.json`);
+}
+
+export function lockPath(serverName: string, storageDir?: string): string {
+  return `${statePath(serverName, storageDir)}.lock`;
+}
+
+export function defaultIsPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+export function createDefaultAuthLockDeps(): AuthLockDeps {
+  return {
+    fs: {
+      open: (path, flags, mode) => open(path, flags, mode),
+      readFile: (path, encoding) => readFile(path, encoding),
+      stat: (path) => stat(path),
+      rename: (oldPath, newPath) => rename(oldPath, newPath),
+      unlink: (path) => unlink(path),
+      link: (existingPath, newPath) => link(existingPath, newPath),
+      utimes: (path, atime, mtime) => utimes(path, atime, mtime),
+      mkdir: (path, options) => mkdir(path, options),
+      chmod: (path, mode) => chmod(path, mode),
+    },
+    clock: {
+      now: () => Date.now(),
+      setInterval: (cb, ms) => setInterval(cb, ms),
+      clearInterval: (timer) => clearInterval(timer),
+    },
+    pid: process.pid,
+    hostname: osHostname(),
+    isPidAlive: defaultIsPidAlive,
+  };
+}
+
+// ─── Pure Staleness Policy ────────────────────────────────────────────────────
+
+export function parseLockRecord(raw: string): LockRecord | null {
+  if (!raw) return null;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    const result = LockRecordSchema.safeParse(parsed);
+    return result.success ? result.data : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pure policy determining whether an existing lock file is stale and safe to reclaim.
+ */
+export function isLockStale(
+  record: LockRecord | null,
+  mtimeMs: number,
+  now: number,
+  self: { hostname: string; isPidAlive: (pid: number) => boolean },
+): boolean {
+  if (now - mtimeMs > STALE_MS) {
+    return true;
+  }
+  if (record === null) {
+    return false;
+  }
+  if (record.hostname === self.hostname && !self.isPidAlive(record.pid)) {
+    return true;
+  }
+  return false;
+}
+
+function formatHolderDetails(record: LockRecord | null): string | undefined {
+  if (!record) return undefined;
+  return `pid ${record.pid} on ${record.hostname}`;
+}
+
+// ─── Lock Acquisition, Heartbeat & Release ────────────────────────────────────
+
+const MAX_ACQUIRE_ATTEMPTS = 3;
+
+export async function acquireAuthLock(
+  serverName: string,
+  storageDir?: string,
+  options?: AcquireAuthLockOptions,
+): Promise<AuthLockHandle> {
+  const defaults = createDefaultAuthLockDeps();
+  const deps: AuthLockDeps = {
+    fs: options?.deps?.fs ?? defaults.fs,
+    clock: options?.deps?.clock ?? defaults.clock,
+    pid: options?.deps?.pid ?? defaults.pid,
+    hostname: options?.deps?.hostname ?? defaults.hostname,
+    isPidAlive: options?.deps?.isPidAlive ?? defaults.isPidAlive,
+  };
+  const usingRealFs = options?.deps?.fs === undefined;
+
+  const directory = authDir(storageDir);
+  await deps.fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  await deps.fs.chmod(directory, 0o700);
+  const path = lockPath(serverName, storageDir);
+
+  for (let attempt = 0; attempt < MAX_ACQUIRE_ATTEMPTS; attempt++) {
+    const myRecord: LockRecord = {
+      v: 1,
+      pid: deps.pid,
+      hostname: deps.hostname,
+      nonce: randomUUID(),
+      createdAt: deps.clock.now(),
+    };
+
+    try {
+      const file = await deps.fs.open(path, "wx", 0o600);
+      try {
+        await file.writeFile(JSON.stringify(myRecord));
+        await file.sync();
+      } catch (writeErr) {
+        await file.close().catch(() => {});
+        await deps.fs.unlink(path).catch(() => {});
+        throw writeErr;
+      }
+      await file.close();
+
+      let released = false;
+      let lost = false;
+      let heartbeatTimer: ReturnType<typeof setInterval> | AuthLockTimer | null = null;
+
+      const stopHeartbeat = () => {
+        if (heartbeatTimer !== null) {
+          deps.clock.clearInterval(heartbeatTimer);
+          heartbeatTimer = null;
+        }
+      };
+
+      const onExit = () => {
+        if (released || lost || !usingRealFs) return;
+        try {
+          const raw = readFileSync(path, "utf8");
+          const current = parseLockRecord(raw);
+          if (current && current.nonce === myRecord.nonce) {
+            unlinkSync(path);
+          }
+        } catch {
+          // Best-effort cleanup on process exit
+        }
+      };
+
+      const markLost = () => {
+        if (lost || released) return;
+        lost = true;
+        stopHeartbeat();
+        process.removeListener("exit", onExit);
+        options?.onLost?.();
+      };
+
+      process.once("exit", onExit);
+
+      heartbeatTimer = deps.clock.setInterval(async () => {
+        if (released || lost) return;
+        let current: LockRecord | null = null;
+        try {
+          const raw = await deps.fs.readFile(path, "utf8");
+          current = parseLockRecord(raw);
+        } catch {
+          current = null;
+        }
+        if (released || lost) return;
+        if (!current || current.nonce !== myRecord.nonce) {
+          markLost();
+          return;
+        }
+        const nowSec = deps.clock.now() / 1000;
+        try {
+          await deps.fs.utimes(path, nowSec, nowSec);
+        } catch {
+          if (!released && !lost) {
+            markLost();
+          }
+        }
+      }, HEARTBEAT_MS);
+      heartbeatTimer.unref?.();
+
+      const assertHeld = async (): Promise<void> => {
+        if (lost || released) {
+          throw new AuthLockError(serverName, `Authorization lock lost for ${serverName}; retry`);
+        }
+        let current: LockRecord | null = null;
+        try {
+          const raw = await deps.fs.readFile(path, "utf8");
+          current = parseLockRecord(raw);
+        } catch {
+          current = null;
+        }
+        if (!current || current.nonce !== myRecord.nonce) {
+          markLost();
+          throw new AuthLockError(serverName, `Authorization lock lost for ${serverName}; retry`);
+        }
+      };
+
+      const unlock = async (): Promise<void> => {
+        if (released) return;
+        released = true;
+        stopHeartbeat();
+        process.removeListener("exit", onExit);
+        if (lost) return;
+        let current: LockRecord | null = null;
+        try {
+          const raw = await deps.fs.readFile(path, "utf8");
+          current = parseLockRecord(raw);
+        } catch {
+          current = null;
+        }
+        if (current && current.nonce === myRecord.nonce) {
+          await deps.fs.unlink(path).catch(() => {});
+        }
+      };
+
+      return Object.assign(unlock, {
+        assertHeld,
+        isLost: () => lost,
+      });
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") {
+        throw err;
+      }
+
+      // Lock file already exists — inspect and check staleness
+      let statResult: { mtimeMs: number };
+      try {
+        statResult = await deps.fs.stat(path);
+      } catch (statErr) {
+        if ((statErr as NodeJS.ErrnoException).code === "ENOENT") {
+          continue;
+        }
+        throw statErr;
+      }
+
+      let record: LockRecord | null = null;
+      try {
+        const raw = await deps.fs.readFile(path, "utf8");
+        record = parseLockRecord(raw);
+      } catch (readErr) {
+        if ((readErr as NodeJS.ErrnoException).code === "ENOENT") {
+          continue;
+        }
+        record = null;
+      }
+
+      const stale = isLockStale(record, statResult.mtimeMs, deps.clock.now(), {
+        hostname: deps.hostname,
+        isPidAlive: deps.isPidAlive,
+      });
+      if (!stale) {
+        throw new AuthLockError(serverName, formatHolderDetails(record));
+      }
+
+      // Reclaim protocol: move stale candidate aside, verify identity, then delete or restore
+      const movedPath = `${path}.stale-${randomUUID()}`;
+      try {
+        await deps.fs.rename(path, movedPath);
+      } catch (renameErr) {
+        if ((renameErr as NodeJS.ErrnoException).code === "ENOENT") {
+          continue;
+        }
+        throw renameErr;
+      }
+
+      let movedRecord: LockRecord | null = null;
+      try {
+        const movedRaw = await deps.fs.readFile(movedPath, "utf8");
+        movedRecord = parseLockRecord(movedRaw);
+      } catch {
+        movedRecord = null;
+      }
+
+      let matchesStale = false;
+      if (record !== null) {
+        matchesStale = movedRecord !== null && movedRecord.nonce === record.nonce;
+      } else {
+        try {
+          const movedStat = await deps.fs.stat(movedPath);
+          matchesStale = movedRecord === null && movedStat.mtimeMs === statResult.mtimeMs;
+        } catch {
+          matchesStale = false;
+        }
+      }
+
+      if (matchesStale) {
+        await deps.fs.unlink(movedPath).catch(() => {});
+        continue;
+      }
+
+      await deps.fs.link(movedPath, path).catch(() => {});
+      await deps.fs.unlink(movedPath).catch(() => {});
+      throw new AuthLockError(serverName, formatHolderDetails(movedRecord));
+    }
+  }
+
+  throw new AuthLockError(serverName);
+}
+
+export { acquireAuthLock as acquireLock };

package/src/callback-server.ts

@@ -8,6 +8,7 @@
 import { createServer, type Server, type IncomingMessage, type ServerResponse } from "http";
 import type { Socket } from "net";
 import { URL } from "url";
+import { CallbackUrlValidationError, isLocalCallbackHost, parseCallbackUrl } from "./callback-url.js";
 
 interface PendingAuth {
   resolve: (code: string) => void;
@@ -73,72 +74,52 @@ function escapeHtml(text: string): string {
  * Handle incoming HTTP requests to the callback server.
  */
 function handleRequest(req: IncomingMessage, res: ServerResponse): void {
-  const url = new URL(req.url || "/", "http://localhost");
-
-  // Only handle the callback path
-  if (url.pathname !== CALLBACK_PATH) {
-    res.writeHead(404, { "Content-Type": "text/plain", "Connection": "close" });
-    res.end("Not found");
-    return;
-  }
-
-  const code = url.searchParams.get("code");
-  const state = url.searchParams.get("state");
-  const error = url.searchParams.get("error");
-  const errorDescription = url.searchParams.get("error_description");
-
-  // Enforce state parameter presence for CSRF protection
-  if (!state) {
-    const errorMsg = "Missing required state parameter - potential CSRF attack";
+  let parsed: ReturnType<typeof parseCallbackUrl>;
+  try {
+    const requestUrl = new URL(req.url || "/", "http://localhost").toString();
+    parsed = parseCallbackUrl(requestUrl, {
+      expectedState: (state) => pendingAuths.has(state),
+    });
+  } catch (err) {
+    if (err instanceof CallbackUrlValidationError) {
+      if (err.reason === "wrong_path") {
+        res.writeHead(404, { "Content-Type": "text/plain", "Connection": "close" });
+        res.end("Not found");
+        return;
+      }
+      res.writeHead(400, { "Content-Type": "text/html", "Connection": "close" });
+      res.end(HTML_ERROR(err.message));
+      return;
+    }
     res.writeHead(400, { "Content-Type": "text/html", "Connection": "close" });
-    res.end(HTML_ERROR(errorMsg));
+    res.end(HTML_ERROR("Invalid callback request"));
     return;
   }
 
   // Handle OAuth errors
-  if (error) {
-    const errorMsg = errorDescription || error;
+  if ("error" in parsed) {
     res.writeHead(200, { "Content-Type": "text/html", "Connection": "close" });
-    res.end(HTML_ERROR(errorMsg));
-    if (pendingAuths.has(state)) {
-      const pending = pendingAuths.get(state)!;
+    res.end(HTML_ERROR(parsed.error));
+    if (pendingAuths.has(parsed.state)) {
+      const pending = pendingAuths.get(parsed.state)!;
       clearTimeout(pending.timeout);
-      pendingAuths.delete(state);
-      setTimeout(() => pending.reject(new Error(errorMsg)), 0);
+      pendingAuths.delete(parsed.state);
+      setTimeout(() => pending.reject(new Error(parsed.error)), 0);
     }
     return;
   }
 
-  // Require authorization code
-  if (!code) {
-    res.writeHead(400, { "Content-Type": "text/html", "Connection": "close" });
-    res.end(HTML_ERROR("No authorization code provided"));
-    return;
-  }
-
-  // Validate state parameter
-  if (!pendingAuths.has(state)) {
-    const errorMsg = "Invalid or expired state parameter - potential CSRF attack";
-    res.writeHead(400, { "Content-Type": "text/html", "Connection": "close" });
-    res.end(HTML_ERROR(errorMsg));
-    return;
-  }
-
-  const pending = pendingAuths.get(state)!;
+  const pending = pendingAuths.get(parsed.state)!;
 
   // Clear timeout and resolve the pending promise
   clearTimeout(pending.timeout);
-  pendingAuths.delete(state);
-  pending.resolve(code);
+  pendingAuths.delete(parsed.state);
+  pending.resolve(parsed.code);
 
   res.writeHead(200, { "Content-Type": "text/html", "Connection": "close" });
   res.end(HTML_SUCCESS);
 }
 
-function isLocalCallbackHost(hostname: string): boolean {
-  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
-}
-
 async function closeCurrentServer(): Promise<void> {
   if (!server) return;
 

package/src/callback-url.ts

@@ -0,0 +1,136 @@
+/**
+ * Pure URL validation and parsing helpers for MCP OAuth authorization and callbacks.
+ */
+
+export type CallbackUrlValidationReason =
+  | "invalid_url"
+  | "wrong_origin"
+  | "wrong_path"
+  | "missing_state"
+  | "invalid_state"
+  | "missing_code";
+
+export class CallbackUrlValidationError extends Error {
+  readonly reason: CallbackUrlValidationReason;
+
+  constructor(reason: CallbackUrlValidationReason, message: string) {
+    super(message);
+    this.name = "CallbackUrlValidationError";
+    this.reason = reason;
+  }
+}
+
+export interface ParseCallbackUrlOptions {
+  redirectUrl?: string | URL | undefined;
+  expectedState?: string | ((state: string) => boolean) | undefined;
+}
+
+export function isLocalCallbackHost(hostname: string): boolean {
+  return (
+    hostname === "localhost" ||
+    hostname === "127.0.0.1" ||
+    hostname === "::1" ||
+    hostname === "[::1]"
+  );
+}
+
+/**
+ * Validate that an OAuth authorization URL is safe to pass to a system browser opener.
+ * Only allows `https:` URLs or loopback `http:` URLs (`localhost`, `127.0.0.1`, `::1`, `[::1]`).
+ */
+export function isSafeAuthorizationUrl(input: string | URL): boolean {
+  let url: URL;
+  try {
+    url = input instanceof URL ? input : new URL(input);
+  } catch {
+    return false;
+  }
+
+  if (url.protocol === "https:") {
+    return true;
+  }
+
+  if (url.protocol === "http:" && isLocalCallbackHost(url.hostname)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Parse and validate an OAuth callback URL (either from an incoming HTTP callback request
+ * or from a user-pasted redirect URL).
+ */
+export function parseCallbackUrl(
+  input: string,
+  options: ParseCallbackUrlOptions = {},
+): { state: string; code: string } | { state: string; error: string } {
+  const trimmed = input.trim();
+  let url: URL;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    throw new CallbackUrlValidationError("invalid_url", "Invalid redirect URL");
+  }
+
+  if (options.redirectUrl !== undefined) {
+    const expected =
+      options.redirectUrl instanceof URL
+        ? options.redirectUrl
+        : new URL(String(options.redirectUrl));
+    if (
+      url.protocol !== expected.protocol ||
+      url.hostname !== expected.hostname ||
+      url.port !== expected.port
+    ) {
+      throw new CallbackUrlValidationError(
+        "wrong_origin",
+        `Redirect URL origin must match ${expected.origin}`,
+      );
+    }
+    if (url.pathname !== expected.pathname) {
+      throw new CallbackUrlValidationError(
+        "wrong_path",
+        `Redirect URL path must be ${expected.pathname}`,
+      );
+    }
+  } else if (url.pathname !== "/callback") {
+    throw new CallbackUrlValidationError("wrong_path", "Redirect URL path must be /callback");
+  }
+
+  const code = url.searchParams.get("code");
+  const state = url.searchParams.get("state");
+  const error = url.searchParams.get("error");
+  const errorDescription = url.searchParams.get("error_description");
+
+  if (!state) {
+    throw new CallbackUrlValidationError(
+      "missing_state",
+      "Missing required state parameter - potential CSRF attack",
+    );
+  }
+
+  if (typeof options.expectedState === "string" && state !== options.expectedState) {
+    throw new CallbackUrlValidationError(
+      "invalid_state",
+      "Invalid or expired state parameter - potential CSRF attack",
+    );
+  }
+
+  if (error) {
+    return { state, error: errorDescription || error };
+  }
+
+  if (!code) {
+    throw new CallbackUrlValidationError("missing_code", "No authorization code provided");
+  }
+
+  if (typeof options.expectedState === "function" && !options.expectedState(state)) {
+    throw new CallbackUrlValidationError(
+      "invalid_state",
+      "Invalid or expired state parameter - potential CSRF attack",
+    );
+  }
+
+  return { state, code };
+}