npm - @gethmy/mcp - Versions diffs - 2.9.4 → 2.9.6 - Mend

@gethmy/mcp 2.9.4 → 2.9.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/README.md +15 -15
package/dist/cli.js +674 -275
package/dist/index.js +530 -205
package/dist/lib/api-client.js +352 -182
package/dist/lib/config.js +37 -26
package/package.json +3 -2
package/src/api-client.ts +50 -4
package/src/cli.ts +13 -2
package/src/config.ts +53 -25
package/src/graph-expansion.ts +7 -4
package/src/http.ts +3 -14
package/src/memory-floor.ts +2 -1
package/src/oauth-login.ts +288 -0
package/src/oauth-refresh.ts +209 -0
package/src/server.ts +6 -6
package/src/skills.ts +4 -2
package/src/tui/setup.ts +106 -16

package/src/oauth-login.ts ADDED Viewed

@@ -0,0 +1,288 @@
+// Loopback + PKCE OAuth login for `npx @gethmy/mcp setup` (card #364).
+//
+// Replaces passing a long-lived, unscoped API key through argv. The CLI binds
+// an ephemeral loopback port, dynamically registers a public OAuth client whose
+// redirect_uri is that exact `http://127.0.0.1:{port}/callback`, opens the
+// browser to the consent page, and exchanges the returned code (+ PKCE verifier)
+// for a workspace-scoped, expiring access/refresh token pair.
+//
+// No backend change: the OAuth authorization server already requires PKCE S256,
+// already permits loopback redirect URIs (RFC 8252), and `harmony-api` already
+// accepts `hmy_at_` access tokens on the `X-API-Key` header. See card #364.
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+// The MCP resource the token is bound to (RFC 8707). harmony-api does not check
+// audience, so a token bound to the MCP resource authenticates against the REST
+// API too. Overridable for self-host / staging.
+const MCP_RESOURCE_URL =
+  process.env.HARMONY_MCP_RESOURCE || "https://mcp.gethmy.com";
+// How long to wait for the user to complete browser consent before giving up.
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+export interface OAuthTokens {
+  accessToken: string;
+  refreshToken: string;
+  /** Epoch ms at which the access token expires. */
+  expiresAt: number;
+  clientId: string;
+}
+function base64Url(buf: Buffer): string {
+  return buf
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+/**
+ * RFC 7636 PKCE pair. The verifier is 43 chars of base64url (32 random bytes),
+ * which is within the spec's 43–128 unreserved-char range.
+ */
+export function generatePkce(): { verifier: string; challenge: string } {
+  const verifier = base64Url(randomBytes(32));
+  const challenge = base64Url(createHash("sha256").update(verifier).digest());
+  return { verifier, challenge };
+}
+/** Derive the OAuth endpoint base (`https://host/oauth`) from the REST apiUrl. */
+export function oauthBaseFromApiUrl(apiUrl: string): string {
+  return `${new URL(apiUrl).origin}/oauth`;
+}
+/** Best-effort cross-platform "open this URL in the default browser". */
+function openBrowser(url: string): void {
+  const platform = process.platform;
+  const cmd =
+    platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+  // cmd.exe treats `&` as a command separator, so the authorize URL's
+  // `&`-joined query params (PKCE challenge, state, …) must be caret-escaped;
+  // otherwise it opens a URL truncated at the first param and runs the rest as
+  // bogus commands, silently breaking auto-open (the printed URL still works).
+  const args =
+    platform === "win32" ? ["/c", "start", "", url.replace(/&/g, "^&")] : [url];
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+      /* swallow — the printed URL is the fallback */
+    });
+    child.unref();
+  } catch {
+    // Headless / no browser — the caller already printed the URL.
+  }
+}
+interface DcrResponse {
+  client_id: string;
+}
+interface TokenResponse {
+  access_token: string;
+  refresh_token: string;
+  expires_in: number;
+}
+const SUCCESS_HTML = `<!doctype html><html><head><meta charset="utf-8"><title>Harmony connected</title></head>
+<body style="font-family:system-ui,sans-serif;background:#0f1729;color:#dce4ef;display:flex;align-items:center;justify-content:center;height:100vh;margin:0">
+<div style="text-align:center"><h1 style="color:#57b8a5">✓ Connected to Harmony</h1>
+<p>You can close this tab and return to your terminal.</p></div></body></html>`;
+const FAILURE_HTML = `<!doctype html><html><head><meta charset="utf-8"><title>Harmony</title></head>
+<body style="font-family:system-ui,sans-serif;background:#0f1729;color:#dce4ef;display:flex;align-items:center;justify-content:center;height:100vh;margin:0">
+<div style="text-align:center"><h1 style="color:#ff6b6b">Authorization failed</h1>
+<p>Return to your terminal for details.</p></div></body></html>`;
+/**
+ * Run the full loopback + PKCE browser login. Resolves with the token pair, or
+ * rejects on timeout / consent failure. `onUrl` receives the authorize URL so
+ * the caller can print it as a no-browser fallback.
+ */
+export async function loginWithBrowser(opts: {
+  apiUrl: string;
+  workspaceId?: string;
+  onUrl?: (url: string) => void;
+}): Promise<OAuthTokens> {
+  const base = oauthBaseFromApiUrl(opts.apiUrl);
+  const { verifier, challenge } = generatePkce();
+  const state = base64Url(randomBytes(16));
+  // 1. Bind an ephemeral loopback port BEFORE registering, so the redirect_uri
+  //    we register is the exact one the server will receive.
+  const { server, port, waitForCode } = await startLoopbackServer(state);
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  try {
+    // 2. Dynamically register a throwaway public client for this exact redirect.
+    const clientId = await registerClient(base, redirectUri);
+    // 3. Build the authorize URL and open the browser.
+    const authorizeUrl = new URL(`${base}/authorize`);
+    authorizeUrl.searchParams.set("response_type", "code");
+    authorizeUrl.searchParams.set("client_id", clientId);
+    authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+    authorizeUrl.searchParams.set("code_challenge", challenge);
+    authorizeUrl.searchParams.set("code_challenge_method", "S256");
+    authorizeUrl.searchParams.set("state", state);
+    authorizeUrl.searchParams.set("scope", "mcp");
+    authorizeUrl.searchParams.set("resource", MCP_RESOURCE_URL);
+    if (opts.workspaceId) {
+      authorizeUrl.searchParams.set("workspace_id", opts.workspaceId);
+    }
+    const authUrlStr = authorizeUrl.toString();
+    opts.onUrl?.(authUrlStr);
+    openBrowser(authUrlStr);
+    // 4. Wait for the browser redirect to our loopback listener.
+    const code = await waitForCode;
+    // 5. Exchange the code (+ verifier) for tokens.
+    return await exchangeCode(base, {
+      code,
+      redirectUri,
+      clientId,
+      verifier,
+    });
+  } finally {
+    server.close();
+  }
+}
+async function registerClient(
+  base: string,
+  redirectUri: string,
+): Promise<string> {
+  const res = await fetch(`${base}/register`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_name: "Harmony CLI (setup)",
+      redirect_uris: [redirectUri],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none",
+    }),
+  });
+  const body = (await res.json().catch(() => ({}))) as Partial<DcrResponse> & {
+    error_description?: string;
+  };
+  if (!res.ok || !body.client_id) {
+    throw new Error(
+      body.error_description ||
+        `Could not register OAuth client (HTTP ${res.status})`,
+    );
+  }
+  return body.client_id;
+}
+async function exchangeCode(
+  base: string,
+  params: {
+    code: string;
+    redirectUri: string;
+    clientId: string;
+    verifier: string;
+  },
+): Promise<OAuthTokens> {
+  const res = await fetch(`${base}/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code: params.code,
+      redirect_uri: params.redirectUri,
+      client_id: params.clientId,
+      code_verifier: params.verifier,
+    }).toString(),
+  });
+  const body = (await res
+    .json()
+    .catch(() => ({}))) as Partial<TokenResponse> & {
+    error_description?: string;
+  };
+  if (!res.ok || !body.access_token || !body.refresh_token) {
+    throw new Error(
+      body.error_description || `Token exchange failed (HTTP ${res.status})`,
+    );
+  }
+  return {
+    accessToken: body.access_token,
+    refreshToken: body.refresh_token,
+    expiresAt: Date.now() + (body.expires_in ?? 0) * 1000,
+    clientId: params.clientId,
+  };
+}
+/**
+ * Start a one-shot loopback HTTP server. Resolves the `waitForCode` promise when
+ * `/callback?code=…&state=…` arrives with a matching `state`. Rejects on an
+ * OAuth error redirect, a state mismatch, or timeout.
+ */
+function startLoopbackServer(expectedState: string): Promise<{
+  server: ReturnType<typeof createServer>;
+  port: number;
+  waitForCode: Promise<string>;
+}> {
+  return new Promise((resolveOuter, rejectOuter) => {
+    let resolveCode: (code: string) => void;
+    let rejectCode: (err: Error) => void;
+    const waitForCode = new Promise<string>((res, rej) => {
+      resolveCode = res;
+      rejectCode = rej;
+    });
+    const timeout = setTimeout(() => {
+      rejectCode(
+        new Error("Timed out waiting for browser authorization (5 min)."),
+      );
+    }, LOGIN_TIMEOUT_MS);
+    // Don't let the pending timer keep the process alive on its own.
+    timeout.unref?.();
+    const server = createServer((req, res) => {
+      const url = new URL(req.url ?? "/", "http://127.0.0.1");
+      if (url.pathname !== "/callback") {
+        res.writeHead(404).end();
+        return;
+      }
+      clearTimeout(timeout);
+      const error = url.searchParams.get("error");
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      const fail = (msg: string) => {
+        res.writeHead(400, { "Content-Type": "text/html" }).end(FAILURE_HTML);
+        rejectCode(new Error(msg));
+      };
+      if (error) {
+        return fail(
+          `Authorization denied: ${url.searchParams.get("error_description") || error}`,
+        );
+      }
+      if (!state || state !== expectedState) {
+        return fail("State mismatch — possible CSRF, aborting.");
+      }
+      if (!code) {
+        return fail("No authorization code returned.");
+      }
+      res.writeHead(200, { "Content-Type": "text/html" }).end(SUCCESS_HTML);
+      resolveCode(code);
+    });
+    server.on("error", (err) => {
+      clearTimeout(timeout);
+      rejectOuter(err);
+    });
+    // Bind to loopback on an ephemeral port (0 → OS assigns a free one).
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address() as AddressInfo;
+      resolveOuter({ server, port: addr.port, waitForCode });
+    });
+  });
+}

package/src/oauth-refresh.ts ADDED Viewed

@@ -0,0 +1,209 @@
+// OAuth access-token refresh for the running MCP server (card #364).
+//
+// The stdio server owns its credential (unlike the remote server, which gets a
+// fresh Bearer per request). Refresh is reactive: when harmony-api returns 401
+// the api-client calls this to exchange the rotating refresh token for a new
+// pair, persist it, and retry. There is no proactive near-expiry refresh — the
+// stored access token is sent until a 401 proves it stale, which is why
+// `oauthExpiresAt` is persisted but not consulted here. Returns the new access
+// token, or null if refresh is impossible (no refresh token) or the grant was
+// rejected (token revoked / expired — the user must re-run `setup`).
+import {
+  closeSync,
+  openSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeSync,
+} from "node:fs";
+import { join } from "node:path";
+import { getConfigDir, loadConfig, saveConfig } from "./config.js";
+import { oauthBaseFromApiUrl } from "./oauth-login.js";
+interface RefreshResponse {
+  access_token: string;
+  refresh_token: string;
+  expires_in: number;
+}
+// In-process dedup — a burst of in-flight requests all hitting 401 should
+// trigger one refresh, not N (the first consumes the refresh token; the rest
+// would trip reuse detection and revoke the whole family).
+let inFlight: Promise<string | null> | null = null;
+// Cross-process serialization. Every Claude Code session spawns its own stdio
+// MCP process, and they all share ~/.harmony-mcp/config.json. The refresh
+// token rotates on use, so two processes refreshing concurrently would each
+// POST a refresh: the first consumes the token, the second replays a now-
+// consumed token and trips the server's reuse detection, revoking the whole
+// grant family and logging every session out. A lockfile mutex serializes the
+// refresh across processes, and the holder re-reads config inside the lock so a
+// process that lost the race adopts the freshly-rotated token instead of
+// replaying its stale one.
+const LOCK_FILENAME = "refresh.lock";
+// A live holder releases in well under a second; this only bounds how long we
+// wait on a peer that crashed mid-refresh before we treat its lock as stale.
+const LOCK_STALE_MS = 30_000;
+// Acquire timeout sits above the stale threshold so a dead holder's lock is
+// always taken over rather than falling through unlocked.
+const LOCK_ACQUIRE_TIMEOUT_MS = 35_000;
+const LOCK_RETRY_MS = 100;
+function lockPath(): string {
+  return join(getConfigDir(), LOCK_FILENAME);
+}
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Acquire the cross-process refresh lock, run `fn`, and release. If the lock
+ * can't be acquired within the timeout (a peer wedged without crashing), `fn`
+ * runs unlocked anyway — a stuck peer must not permanently block refresh, and
+ * the in-lock re-read in `doRefresh` still guards the common race.
+ */
+async function withRefreshLock<T>(fn: () => Promise<T>): Promise<T> {
+  const path = lockPath();
+  const deadline = Date.now() + LOCK_ACQUIRE_TIMEOUT_MS;
+  let held = false;
+  while (Date.now() < deadline) {
+    try {
+      // wx: exclusive create — fails with EEXIST if another process holds it.
+      const fd = openSync(path, "wx");
+      writeSync(fd, String(process.pid));
+      closeSync(fd);
+      held = true;
+      break;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") {
+        // Can't even attempt the lock (e.g. dir perms) — proceed unlocked.
+        break;
+      }
+      // Lock exists. Take it over if it's stale (holder crashed without
+      // releasing); otherwise back off and retry.
+      try {
+        const age = Date.now() - statSync(path).mtimeMs;
+        if (age > LOCK_STALE_MS) {
+          // Claim the stale lock by atomically renaming it aside, rather than
+          // stat-then-rmSync: that gap let two processes both delete a stale
+          // lock and both proceed, re-introducing the concurrent refresh this
+          // mutex exists to prevent. rename is atomic, so only the process
+          // whose rename wins owns the takeover; a loser's rename throws
+          // (the file is already gone) and it falls back to the retry loop.
+          const claim = `${path}.stale.${process.pid}`;
+          try {
+            renameSync(path, claim);
+            rmSync(claim, { force: true });
+          } catch {
+            // Lost the takeover race — retry against the winner's fresh lock.
+          }
+          continue;
+        }
+      } catch {
+        // Lock vanished between open and stat — retry immediately.
+        continue;
+      }
+      await sleep(LOCK_RETRY_MS);
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    if (held) {
+      try {
+        rmSync(path, { force: true });
+      } catch {
+        // Best-effort release; stale takeover covers a missed unlink.
+      }
+    }
+  }
+}
+/**
+ * Refresh the stored OAuth tokens and persist the new pair. Concurrent callers
+ * share a single in-flight refresh in-process and serialize across processes.
+ * Returns the new access token or null.
+ */
+export function refreshOAuthToken(): Promise<string | null> {
+  if (inFlight) return inFlight;
+  inFlight = doRefresh().finally(() => {
+    inFlight = null;
+  });
+  return inFlight;
+}
+async function doRefresh(): Promise<string | null> {
+  // Snapshot the refresh token we intend to rotate before contending for the
+  // lock, so we can tell inside the lock whether a peer rotated ahead of us.
+  const before = loadConfig();
+  if (!before.oauthRefreshToken || !before.oauthClientId) return null;
+  return withRefreshLock(async () => {
+    // Re-read inside the lock: a peer may have rotated while we waited. If the
+    // stored refresh token changed, our snapshot is now consumed — adopt the
+    // peer's fresh access token instead of replaying ours (which would trip
+    // reuse detection and revoke the whole family).
+    const config = loadConfig();
+    if (
+      config.oauthRefreshToken !== before.oauthRefreshToken &&
+      config.oauthAccessToken
+    ) {
+      return config.oauthAccessToken;
+    }
+    if (!config.oauthRefreshToken || !config.oauthClientId) return null;
+    const base = oauthBaseFromApiUrl(config.apiUrl);
+    let res: Response;
+    try {
+      res = await fetch(`${base}/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "refresh_token",
+          refresh_token: config.oauthRefreshToken,
+          client_id: config.oauthClientId,
+        }).toString(),
+      });
+    } catch {
+      // Network error — leave stored tokens intact so a later attempt can retry.
+      return null;
+    }
+    if (!res.ok) {
+      // Only invalid_grant (revoked / expired / rotated refresh token) is
+      // terminal: clear the dead OAuth credentials so the runtime stops retrying
+      // and surfaces a re-auth prompt. A transient 4xx (429 rate-limit, an
+      // intermediary 400) or 5xx must leave the stored tokens intact so a later
+      // attempt can retry — wiping on the broad 4xx class would force a full
+      // re-setup on a passing rate-limit. The token endpoint returns
+      // { error: "invalid_grant" } for every terminal case (oauth/index.ts).
+      const errorCode = await res
+        .json()
+        .then((b) => (b as { error?: string } | null)?.error ?? null)
+        .catch(() => null);
+      if (errorCode === "invalid_grant") {
+        saveConfig({
+          oauthAccessToken: null,
+          oauthRefreshToken: null,
+          oauthExpiresAt: null,
+          oauthClientId: null,
+        });
+      }
+      return null;
+    }
+    const body = (await res.json().catch(() => null)) as RefreshResponse | null;
+    if (!body?.access_token || !body.refresh_token) return null;
+    saveConfig({
+      oauthAccessToken: body.access_token,
+      oauthRefreshToken: body.refresh_token,
+      oauthExpiresAt: Date.now() + (body.expires_in ?? 0) * 1000,
+    });
+    return body.access_token;
+  });
+}

package/src/server.ts CHANGED Viewed

@@ -2287,7 +2287,7 @@ async function handleToolCall(
     case "harmony_delete_label": {
       const labelId = z.string().uuid().parse(args.labelId);
       const result = await client.deleteLabel(labelId);
-      return { success: true, ...result };
+      return { ...result };
     }
     case "harmony_add_label_to_card": {
@@ -2612,7 +2612,7 @@ async function handleToolCall(
         language: (args.language as string) || "en-US",
         execute: args.execute === true,
       });
-      return { success: true, ...result };
+      return { success: true, ...(result as Record<string, unknown>) };
     }
     // Agent context operations
@@ -2692,8 +2692,8 @@ async function handleToolCall(
           const workspaceId = deps.getActiveWorkspaceId();
           if (workspaceId) {
             const { members } = await client.getWorkspaceMembers(workspaceId);
-            const user = members.find(
-              (m: { email: string }) => m.email === userEmail,
+            const user = (members as Array<{ id: string; email: string }>).find(
+              (m) => m.email === userEmail,
             );
             if (user) {
               await client.updateCard(cardId, { assigneeId: user.id });
@@ -3815,8 +3815,8 @@ async function handleToolCall(
             content: summary,
             type: "lesson",
             scope: "project",
-            workspaceId,
-            projectId: plan.project_id,
+            workspace_id: workspaceId,
+            project_id: plan.project_id,
             tags: ["plan", "archived"],
             confidence: 0.8,
           });

package/src/skills.ts CHANGED Viewed

@@ -7,7 +7,7 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { HarmonyApiClient } from "./api-client.js";
+import { getClient } from "./api-client.js";
 import { areSkillsInstalled, isConfigured } from "./config.js";
 import { loadHmyConfig } from "./hmy-config.js";
@@ -286,7 +286,9 @@ export async function refreshSkills(
     const status = areSkillsInstalled();
     if (!status.installed) return { updated: false };
-    const client = new HarmonyApiClient();
+    // Shared singleton so the startup skills check inherits the refresh-on-401
+    // path; a bare client couldn't refresh a stale OAuth token (card #364).
+    const client = getClient();
     const versionInfo = await client.fetchSkillsVersion();
     // We hit the network — reset the TTL window regardless of outcome.
     recordCheck();