@fargowealth/fargo-ai-cli 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.4.0
+
+- **Behavior change:** Fargo CLI is explicitly WorkBuddy-only. On macOS, credentials use the sandbox-compatible private file at `~/.fargo/credentials.json`; the unsupported Keychain mode is rejected. Windows remains protected by DPAPI.
+- `workbuddy install` writes the macOS credential mode and absolute credential/refresh-lock paths into WorkBuddy's MCP configuration.
+- On macOS, `workbuddy install` resolves an absolute `npx` executable and supplies a stable GUI `PATH`.
+- Windows opens the complete OAuth authorization URL directly through Explorer instead of `cmd.exe start`, preventing `&` query separators from truncating `redirect_uri`.
+- Private-file writes are atomic and `fsync`-backed; directory/file modes are repaired to `0700`/`0600`, and symbolic-link credential reads are rejected.
+- Existing macOS 0.3.x Keychain credentials are not copied into the file store. Users must reconnect once; the previous Keychain item should be removed separately if it exists.

package/README.md

@@ -1,14 +1,27 @@
-# Fargo CLI
+# Fargo CLI for WorkBuddy
 
-`fargo-cli` provides WorkBuddy with Device Authorization Grant login and a local stdio bridge to the hosted Fargo AI MCP server.
+`fargo-cli` is the compatibility bridge that connects WorkBuddy to the hosted Fargo AI MCP server. It uses OAuth Authorization Code + PKCE over an ephemeral loopback callback and exposes the remote MCP over local stdio.
 
 ```sh
-npm install --global @fargowealth/fargo-ai-cli
-fargo workbuddy install --open-browser=always --output=jsonl
-fargo auth device --open-browser=always --output=jsonl
-fargo auth status --output=json
-fargo mcp serve
-fargo auth logout
+npx -y @fargowealth/fargo-ai-cli@latest workbuddy install --open-browser=always --output=jsonl
+npx -y @fargowealth/fargo-ai-cli@latest auth status --output=json
+npx -y @fargowealth/fargo-ai-cli@latest auth logout --output=json
 ```
 
-OAuth credentials are stored in macOS Keychain, protected with Windows DPAPI, or written to an owner-only file on Linux.
+The login opens the shared Fargo AI consent page and returns to `http://127.0.0.1:<random-port>/oauth/callback/...`. The CLI binds only to IPv4 loopback, validates OAuth `state`, uses PKCE S256, closes the listener after the callback, and never prints private OAuth credentials.
+
+## Credential storage
+
+- **WorkBuddy on macOS:** `~/.fargo/credentials.json`. WorkBuddy's sandbox blocks both the `security` CLI and native Keychain Services. The CLI therefore uses a private file by default and never asks for Full Disk Access.
+- **WorkBuddy on Windows:** DPAPI `CurrentUser`, stored as encrypted bytes under `%APPDATA%\Fargo AI\credentials.bin`.
+- **WorkBuddy on Linux:** `~/.fargo/credentials.json`.
+
+On macOS and Linux, the credential directory is forced to `0700` and the credential file to `0600`. Writes use an `fsync`-backed temporary file followed by atomic replacement, symbolic-link reads are rejected, and refresh-token rotation is serialized across local CLI processes.
+
+The local file contains an OAuth refresh credential. Do not copy, upload, commit, print, or include it in logs. Use `npx -y @fargowealth/fargo-ai-cli@latest auth logout` to remove it when a device is no longer trusted, and revoke the connection from Fargo AI.
+
+Device Authorization Grant remains available only as an explicit fallback:
+
+```sh
+npx -y @fargowealth/fargo-ai-cli@latest auth device --open-browser=always --output=jsonl
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fargowealth/fargo-ai-cli",
-  "version": "0.2.1",
-  "description": "Fargo AI authentication and stdio MCP bridge for WorkBuddy",
+  "version": "0.4.0",
+  "description": "Fargo AI OAuth and stdio MCP bridge for WorkBuddy",
   "type": "module",
   "bin": {
     "fargo": "bin/fargo.mjs",
@@ -10,6 +10,7 @@
   "files": [
     "bin",
     "src",
+    "CHANGELOG.md",
     "README.md"
   ],
   "engines": {

package/src/auth.mjs

@@ -1,5 +1,90 @@
 import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
 import { CLI_VERSION, DEFAULT_AUTH_URL, DEFAULT_MCP_URL, DEVICE_CODE_GRANT_TYPE, OAUTH_CLIENT_ID, OAUTH_SCOPE } from "./constants.mjs";
+import { createLoopbackReceiver } from "./loopback-receiver.mjs";
+
+export async function authorizePkce(store, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const authUrl = options.authUrl ?? process.env.FARGO_AUTH_URL ?? DEFAULT_AUTH_URL;
+  const mcpUrl = options.mcpUrl ?? process.env.FARGO_MCP_URL ?? DEFAULT_MCP_URL;
+  const metadata = await discoverOAuthMetadata(authUrl, fetchImpl);
+  const random = options.randomBytes ?? randomBytes;
+  const verifier = random(32).toString("base64url");
+  const state = random(32).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  const receiver = await (options.loopbackReceiverFactory ?? createLoopbackReceiver)({
+    expectedState: state,
+    randomBytes: random,
+    timeoutMs: options.authorizationTimeoutMs
+  });
+
+  try {
+    const registrationResponse = await fetchImpl(metadata.registration_endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "User-Agent": `fargo-cli/${CLI_VERSION} WorkBuddy` },
+      body: JSON.stringify({
+        agent_type: "workbuddy",
+        client_name: "Fargo CLI for WorkBuddy",
+        grant_types: ["authorization_code", "refresh_token"],
+        redirect_uris: [receiver.redirectUri],
+        response_types: ["code"],
+        software_id: "@fargowealth/fargo-ai-cli",
+        software_version: CLI_VERSION,
+        token_endpoint_auth_method: "none"
+      })
+    });
+    const registration = await readOAuthResponse(registrationResponse);
+    if (typeof registration.client_id !== "string" || !registration.client_id) {
+      throw new Error("OAuth client registration did not return a client_id");
+    }
+
+    const authorizationUrl = new URL(metadata.authorization_endpoint);
+    authorizationUrl.search = new URLSearchParams({
+      client_id: registration.client_id,
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+      redirect_uri: receiver.redirectUri,
+      resource: mcpUrl,
+      response_type: "code",
+      scope: OAUTH_SCOPE,
+      state
+    }).toString();
+    await options.onAuthorization?.({ authorizationUrl: authorizationUrl.toString(), redirectUri: receiver.redirectUri });
+    if (options.openBrowser !== false) (options.browserOpener ?? openBrowser)(authorizationUrl.toString());
+
+    const callback = await receiver.waitForCallback();
+    if (callback.searchParams.get("state") !== state) {
+      throw new Error("OAuth callback state did not match the pending Fargo authorization");
+    }
+    const oauthError = callback.searchParams.get("error");
+    if (oauthError) throw new Error(`OAuth authorization was not completed (${oauthError})`);
+    const code = callback.searchParams.get("code");
+    if (!code) throw new Error("OAuth callback did not contain an authorization code");
+
+    const tokenResponse = await fetchImpl(metadata.token_endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded", "User-Agent": `fargo-cli/${CLI_VERSION} WorkBuddy` },
+      body: new URLSearchParams({
+        client_id: registration.client_id,
+        code,
+        code_verifier: verifier,
+        grant_type: "authorization_code",
+        redirect_uri: receiver.redirectUri
+      })
+    });
+    const payload = await readOAuthResponse(tokenResponse);
+    const credential = credentialFromToken(payload, authUrl, {
+      authorization_method: "authorization_code_pkce",
+      client_id: registration.client_id,
+      resource_url: mcpUrl,
+      token_endpoint: metadata.token_endpoint
+    });
+    await store.save(credential);
+    return credential;
+  } finally {
+    await receiver.close();
+  }
+}
 
 export async function startDeviceAuthorization(options = {}) {
   const fetchImpl = options.fetchImpl ?? fetch;
@@ -28,7 +113,12 @@ export async function pollDeviceAuthorization(device, store, options = {}) {
     });
     const payload = await response.json().catch(() => ({}));
     if (response.ok) {
-      const credential = credentialFromToken(payload, authUrl);
+      const credential = credentialFromToken(payload, authUrl, {
+        authorization_method: "device_flow",
+        client_id: OAUTH_CLIENT_ID,
+        resource_url: options.mcpUrl ?? process.env.FARGO_MCP_URL ?? DEFAULT_MCP_URL,
+        token_endpoint: `${authUrl}/v1/mcp/oauth/token`
+      });
       await store.save(credential);
       return credential;
     }
@@ -42,13 +132,20 @@ export async function pollDeviceAuthorization(device, store, options = {}) {
 export async function refreshCredential(store, credential, options = {}) {
   const fetchImpl = options.fetchImpl ?? fetch;
   const authUrl = credential.auth_url ?? options.authUrl ?? process.env.FARGO_AUTH_URL ?? DEFAULT_AUTH_URL;
-  const response = await fetchImpl(`${authUrl}/v1/mcp/oauth/token`, {
+  const clientId = credential.client_id ?? OAUTH_CLIENT_ID;
+  const tokenEndpoint = credential.token_endpoint ?? `${authUrl}/v1/mcp/oauth/token`;
+  const response = await fetchImpl(tokenEndpoint, {
     method: "POST",
     headers: { "Content-Type": "application/x-www-form-urlencoded", "User-Agent": `fargo-cli/${CLI_VERSION} WorkBuddy` },
-    body: new URLSearchParams({ grant_type: "refresh_token", client_id: OAUTH_CLIENT_ID, refresh_token: credential.refresh_token })
+    body: new URLSearchParams({ grant_type: "refresh_token", client_id: clientId, refresh_token: credential.refresh_token })
   });
   const payload = await readOAuthResponse(response);
-  const refreshed = credentialFromToken(payload, authUrl);
+  const refreshed = credentialFromToken(payload, authUrl, {
+    authorization_method: credential.authorization_method,
+    client_id: clientId,
+    resource_url: credential.resource_url,
+    token_endpoint: tokenEndpoint
+  });
   await store.save(refreshed);
   return refreshed;
 }
@@ -57,23 +154,51 @@ export async function currentCredential(store, options = {}) {
   let credential = await store.load();
   if (!credential) return undefined;
   if (!credential.access_token || Number(credential.expires_at) <= Date.now() + 60_000) {
-    credential = await refreshCredential(store, credential, options);
+    credential = await refreshCurrentCredential(store, credential, options);
   }
   return credential;
 }
 
+export async function refreshCurrentCredential(store, observedCredential, options = {}) {
+  const refresh = async () => {
+    const latest = await store.load();
+    if (!latest) return undefined;
+    if (latest.refresh_token !== observedCredential.refresh_token) return latest;
+    try {
+      return await refreshCredential(store, latest, options);
+    } catch (error) {
+      const recovered = await store.load();
+      if (recovered?.refresh_token && recovered.refresh_token !== latest.refresh_token) return recovered;
+      throw error;
+    }
+  };
+  return typeof store.withRefreshLock === "function" ? store.withRefreshLock(refresh) : refresh();
+}
+
 export function openBrowser(url, platform = process.platform) {
-  const command = platform === "darwin" ? "open" : platform === "win32" ? "cmd.exe" : "xdg-open";
-  const args = platform === "win32" ? ["/d", "/s", "/c", "start", "", url] : [url];
+  const { args, command } = browserLaunchCommand(url, platform);
   const child = spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true });
+  child.on("error", () => {
+    // The authorization URL is emitted before this best-effort launch, so the
+    // host can still open it when no platform browser launcher is available.
+  });
   child.unref();
 }
 
-function credentialFromToken(payload, authUrl) {
+export function browserLaunchCommand(url, platform = process.platform) {
+  if (platform === "win32") {
+    // Do not route OAuth URLs through `cmd.exe start`: unescaped `&` query
+    // separators are parsed by CMD and truncate the URL after client_id.
+    return { command: "explorer.exe", args: [url] };
+  }
+  return { command: platform === "darwin" ? "open" : "xdg-open", args: [url] };
+}
+
+function credentialFromToken(payload, authUrl, metadata = {}) {
   if (typeof payload.access_token !== "string" || typeof payload.refresh_token !== "string") {
     throw new Error("OAuth token response did not contain rotating credentials");
   }
-  return { ...payload, auth_url: authUrl, obtained_at: Date.now(), expires_at: Date.now() + Math.max(1, Number(payload.expires_in) || 3600) * 1000 };
+  return { ...payload, ...metadata, auth_url: authUrl, obtained_at: Date.now(), expires_at: Date.now() + Math.max(1, Number(payload.expires_in) || 3600) * 1000 };
 }
 
 async function readOAuthResponse(response) {
@@ -81,3 +206,23 @@ async function readOAuthResponse(response) {
   if (!response.ok) throw new Error(payload.error_description || payload.message || payload.error || `OAuth request failed (${response.status})`);
   return payload;
 }
+
+async function discoverOAuthMetadata(authUrl, fetchImpl) {
+  const response = await fetchImpl(`${authUrl.replace(/\/+$/, "")}/.well-known/oauth-authorization-server`, {
+    headers: { "Accept": "application/json", "User-Agent": `fargo-cli/${CLI_VERSION} WorkBuddy` }
+  });
+  const metadata = await readOAuthResponse(response);
+  for (const field of ["authorization_endpoint", "registration_endpoint", "token_endpoint"]) {
+    if (typeof metadata[field] !== "string" || !metadata[field]) {
+      throw new Error(`OAuth metadata did not contain ${field}`);
+    }
+    const endpoint = new URL(metadata[field]);
+    if (endpoint.protocol !== "https:" && endpoint.hostname !== "127.0.0.1" && endpoint.hostname !== "localhost") {
+      throw new Error(`OAuth metadata returned an unsafe ${field}`);
+    }
+  }
+  if (!Array.isArray(metadata.code_challenge_methods_supported) || !metadata.code_challenge_methods_supported.includes("S256")) {
+    throw new Error("OAuth server does not advertise PKCE S256 support");
+  }
+  return metadata;
+}

package/src/cli.mjs

@@ -1,5 +1,5 @@
 import { createCredentialStore } from "./credential-store.mjs";
-import { currentCredential, openBrowser, pollDeviceAuthorization, startDeviceAuthorization } from "./auth.mjs";
+import { authorizePkce, currentCredential, openBrowser, pollDeviceAuthorization, startDeviceAuthorization } from "./auth.mjs";
 import { CLI_VERSION } from "./constants.mjs";
 import { runMcpProxy } from "./mcp-proxy.mjs";
 import { installWorkBuddyMcp } from "./workbuddy-install.mjs";
@@ -17,9 +17,13 @@ export async function runCli(args, options = {}) {
       await authorizeDevice(args, stdout, store, options);
       return;
     }
+    if (args[0] === "auth" && (args[1] === "login" || args[1] === "pkce")) {
+      await authorizeWithPkce(args, stdout, store, options);
+      return;
+    }
     if (args[0] === "auth" && args[1] === "status") {
       const credential = await store.load();
-      stdout.write(`${JSON.stringify({ logged_in: Boolean(credential?.refresh_token), method: credential?.refresh_token ? "oauth" : null, credential_store: store.kind, expires_at: credential?.expires_at ?? null })}\n`);
+      stdout.write(`${JSON.stringify({ logged_in: Boolean(credential?.refresh_token), method: credential?.authorization_method ?? (credential?.refresh_token ? "oauth" : null), credential_store: store.kind, expires_at: credential?.expires_at ?? null })}\n`);
       return;
     }
     if (args[0] === "auth" && (args[1] === "logout" || args[1] === "revoke")) {
@@ -42,11 +46,14 @@ export async function runCli(args, options = {}) {
           credential = undefined;
         }
       }
-      if (!credential?.refresh_token) await authorizeDevice(args, stdout, store, options);
+      if (credential?.authorization_method !== "authorization_code_pkce") {
+        credential = undefined;
+      }
+      if (!credential?.refresh_token) await authorizeWithPkce(args, stdout, store, options);
       stdout.write(`${JSON.stringify(await installWorkBuddyMcp(options))}\n`);
       return;
     }
-    throw new Error("Usage: fargo auth device|status|logout | fargo workbuddy install | fargo mcp serve | fargo version");
+    throw new Error("Usage: fargo auth login|device|status|logout | fargo workbuddy install | fargo mcp serve | fargo version");
   } catch (error) {
     stderr.write(`fargo: ${error instanceof Error ? error.message : "unknown error"}\n`);
     if (options.throwOnError) throw error;
@@ -54,6 +61,24 @@ export async function runCli(args, options = {}) {
   }
 }
 
+async function authorizeWithPkce(args, stdout, store, options) {
+  const browserMode = optionValue(args, "--open-browser") ?? "auto";
+  await authorizePkce(store, {
+    ...options,
+    openBrowser: browserMode !== "never" && options.openBrowser !== false,
+    async onAuthorization(details) {
+      stdout.write(`${JSON.stringify({
+        type: "authorization_required",
+        method: "authorization_code_pkce",
+        authorization_url: details.authorizationUrl,
+        callback: "loopback"
+      })}\n`);
+      await options.onAuthorization?.(details);
+    }
+  });
+  stdout.write(`${JSON.stringify({ type: "authorization_complete", logged_in: true, method: "authorization_code_pkce" })}\n`);
+}
+
 async function authorizeDevice(args, stdout, store, options) {
   const device = await startDeviceAuthorization(options);
   stdout.write(`${JSON.stringify({

package/src/constants.mjs

@@ -1,6 +1,6 @@
-export const CLI_VERSION = "0.2.1";
+export const CLI_VERSION = "0.4.0";
 export const DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
 export const DEFAULT_AUTH_URL = "https://auth.fargowealth.app";
 export const DEFAULT_MCP_URL = "https://mcp.fargowealth.app/mcp";
 export const OAUTH_CLIENT_ID = "fargo-cli-workbuddy";
-export const OAUTH_SCOPE = "fargo:forum:read fargo:hub:read fargo:lego:read fargo:knowledge:read";
+export const OAUTH_SCOPE = "fargo:forum:read fargo:forum:write fargo:hub:read fargo:lego:read fargo:lego:write fargo:knowledge:read fargo:knowledge:write fargo:knowledge:share";

package/src/credential-store.mjs

@@ -1,42 +1,36 @@
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { spawn } from "node:child_process";
-
-const KEYCHAIN_SERVICE = "com.fargowealth.fargo-cli.oauth";
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
 
 export function createCredentialStore(options = {}) {
   const platform = options.platform ?? process.platform;
   const env = options.env ?? process.env;
   const home = options.home ?? homedir();
   const run = options.run ?? runCommand;
-  const filePath = env.FARGO_CREDENTIAL_PATH ?? join(home, ".fargo", "credentials.json");
-  const forceFile = env.FARGO_CREDENTIAL_STORE === "file";
-
-  if (!forceFile && platform === "darwin") {
-    const account = env.USER || env.LOGNAME || "fargo-user";
-    return {
-      kind: "macos-keychain",
-      async load() {
-        const result = await run("security", ["find-generic-password", "-a", account, "-s", KEYCHAIN_SERVICE, "-w"], { allowFailure: true });
-        if (result.code !== 0 || !result.stdout.trim()) return undefined;
-        return parseCredential(result.stdout.trim());
-      },
-      async save(value) {
-        const serialized = JSON.stringify(value);
-        const result = await run("security", ["add-generic-password", "-a", account, "-s", KEYCHAIN_SERVICE, "-w", serialized, "-U"], { allowFailure: true });
-        if (result.code !== 0) throw new Error("Unable to save Fargo credentials in macOS Keychain");
-      },
-      async clear() {
-        await run("security", ["delete-generic-password", "-a", account, "-s", KEYCHAIN_SERVICE], { allowFailure: true });
-      }
-    };
+  const storeKind = env.FARGO_CREDENTIAL_STORE;
+  if (storeKind === "keychain") {
+    throw new Error("FARGO_CREDENTIAL_STORE=keychain is not supported by the WorkBuddy CLI; use file on macOS");
+  }
+  if (storeKind && !["dpapi", "file"].includes(storeKind)) {
+    throw new Error(`Unsupported FARGO_CREDENTIAL_STORE: ${storeKind}`);
   }
+  if (storeKind === "dpapi" && platform !== "win32") {
+    throw new Error("FARGO_CREDENTIAL_STORE=dpapi is only supported on Windows");
+  }
+  const filePath = env.FARGO_CREDENTIAL_PATH ?? join(home, ".fargo", "credentials.json");
+  const refreshLockPath = env.FARGO_REFRESH_LOCK_PATH ?? (platform === "win32"
+    ? join(env.APPDATA || home, "Fargo AI", "oauth-refresh.lock")
+    : join(home, ".fargo", "oauth-refresh.lock"));
+  const withRefreshLock = (callback) => withFileLock(refreshLockPath, callback);
 
-  if (!forceFile && platform === "win32") {
+  if (platform === "win32" && storeKind !== "file") {
     const protectedPath = env.FARGO_CREDENTIAL_PATH ?? join(env.APPDATA || home, "Fargo AI", "credentials.bin");
     return {
       kind: "windows-dpapi",
+      withRefreshLock,
       async load() {
         const script = "$p=$env:FARGO_CREDENTIAL_PATH;if(!(Test-Path -LiteralPath $p)){exit 3};$e=[IO.File]::ReadAllBytes($p);$b=[Security.Cryptography.ProtectedData]::Unprotect($e,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser);[Console]::Out.Write([Text.Encoding]::UTF8.GetString($b))";
         const result = await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { allowFailure: true, env: { ...env, FARGO_CREDENTIAL_PATH: protectedPath } });
@@ -56,8 +50,10 @@ export function createCredentialStore(options = {}) {
 
   return {
     kind: "private-file",
+    withRefreshLock,
     async load() {
       try {
+        await secureExistingFile(filePath);
         return parseCredential(await readFile(filePath, "utf8"));
       } catch (error) {
         if (error?.code === "ENOENT") return undefined;
@@ -65,15 +61,96 @@ export function createCredentialStore(options = {}) {
       }
     },
     async save(value) {
-      await mkdir(dirname(filePath), { recursive: true, mode: 0o700 });
-      await writeFile(filePath, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+      const directory = dirname(filePath);
+      await ensurePrivateDirectory(directory);
+      const temporaryPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+      let handle;
+      try {
+        handle = await open(temporaryPath, "wx", 0o600);
+        await handle.writeFile(`${JSON.stringify(value)}\n`, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await chmod(temporaryPath, 0o600);
+        await rename(temporaryPath, filePath);
+        await secureExistingFile(filePath);
+      } finally {
+        await handle?.close().catch(() => {});
+        await rm(temporaryPath, { force: true });
+      }
     },
     async clear() {
+      await secureExistingFile(filePath).catch((error) => {
+        if (error?.code !== "ENOENT") throw error;
+      });
       await rm(filePath, { force: true });
     }
   };
 }
 
+async function withFileLock(lockPath, callback) {
+  await ensurePrivateDirectory(dirname(lockPath));
+  const deadline = Date.now() + 15_000;
+  const owner = `${process.pid}:${randomUUID()}`;
+  let handle;
+  while (!handle) {
+    try {
+      handle = await open(lockPath, "wx", 0o600);
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      try {
+        const lockStat = await stat(lockPath);
+        if (Date.now() - lockStat.mtimeMs > 120_000) {
+          await rm(lockPath, { force: true });
+          continue;
+        }
+      } catch (statError) {
+        if (statError?.code !== "ENOENT") throw statError;
+        continue;
+      }
+      if (Date.now() >= deadline) throw new Error("Timed out waiting for another Fargo session to refresh OAuth");
+      await delay(75);
+    }
+  }
+  await handle.writeFile(owner, "utf8");
+  try {
+    return await callback();
+  } finally {
+    await handle.close();
+    const currentOwner = await readFile(lockPath, "utf8").catch((error) => {
+      if (error?.code === "ENOENT") return undefined;
+      throw error;
+    });
+    if (currentOwner === owner) await rm(lockPath, { force: true });
+  }
+}
+
+async function ensurePrivateDirectory(directoryPath) {
+  await mkdir(directoryPath, { recursive: true, mode: 0o700 });
+  const details = await lstat(directoryPath);
+  if (!details.isDirectory() || details.isSymbolicLink()) {
+    throw new Error(`Fargo credential directory is not a private directory: ${directoryPath}`);
+  }
+  assertCurrentUserOwns(details, "credential directory");
+  await chmod(directoryPath, 0o700);
+}
+
+async function secureExistingFile(filePath) {
+  const details = await lstat(filePath);
+  if (!details.isFile() || details.isSymbolicLink()) {
+    throw new Error(`Fargo credential path is not a regular file: ${filePath}`);
+  }
+  assertCurrentUserOwns(details, "credential file");
+  await chmod(filePath, 0o600);
+}
+
+function assertCurrentUserOwns(details, label) {
+  if (typeof process.getuid !== "function") return;
+  if (details.uid !== process.getuid()) {
+    throw new Error(`Fargo ${label} is not owned by the current user`);
+  }
+}
+
 function parseCredential(value) {
   const parsed = JSON.parse(value);
   if (!parsed || typeof parsed !== "object" || typeof parsed.refresh_token !== "string") {

package/src/loopback-receiver.mjs

@@ -0,0 +1,107 @@
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+
+const LOOPBACK_HOST = "127.0.0.1";
+
+export async function createLoopbackReceiver(options = {}) {
+  const callbackPath = `/oauth/callback/${(options.randomBytes ?? randomBytes)(18).toString("base64url")}`;
+  const timeoutMs = Math.max(1_000, Number(options.timeoutMs) || 10 * 60 * 1_000);
+  let address;
+  let settled = false;
+  let timer;
+  let resolveCallback;
+  let rejectCallback;
+  const callback = new Promise((resolve, reject) => {
+    resolveCallback = resolve;
+    rejectCallback = reject;
+  });
+
+  const server = createServer((request, response) => {
+    const requestUrl = new URL(request.url || "/", `http://${LOOPBACK_HOST}:${address?.port || 0}`);
+    if (request.method !== "GET" || requestUrl.pathname !== callbackPath) {
+      response.writeHead(404, secureHtmlHeaders());
+      response.end(completionPage(false, "这个本地回调地址无效，请返回 Fargo AI 重新授权。"));
+      return;
+    }
+    if (settled) {
+      response.writeHead(409, secureHtmlHeaders());
+      response.end(completionPage(false, "这次授权回调已经处理，请返回 WorkBuddy。"));
+      return;
+    }
+    settled = true;
+    clearTimeout(timer);
+    if (options.expectedState && requestUrl.searchParams.get("state") !== options.expectedState) {
+      response.writeHead(400, secureHtmlHeaders());
+      response.end(completionPage(false, "这次授权回调无法验证，请返回 Fargo AI 重新授权。"));
+      rejectCallback(new Error("OAuth callback state did not match the pending Fargo authorization"));
+      return;
+    }
+    const failed = Boolean(requestUrl.searchParams.get("error"));
+    response.writeHead(failed ? 400 : 200, secureHtmlHeaders());
+    response.end(completionPage(!failed, failed
+      ? "没有签发任何凭据。你可以关闭此页面后重新尝试。"
+      : "Fargo CLI 已收到授权结果，正在安全完成连接。现在可以关闭此页面。"));
+    resolveCallback(requestUrl);
+  });
+
+  await new Promise((resolve, reject) => {
+    const onError = (error) => {
+      server.off("listening", onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off("error", onError);
+      resolve();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen({ host: LOOPBACK_HOST, port: 0, exclusive: true });
+  });
+
+  address = server.address();
+  if (!address || typeof address === "string") {
+    await closeServer(server);
+    throw new Error("Unable to allocate a Fargo OAuth loopback port");
+  }
+
+  timer = setTimeout(() => {
+    if (settled) return;
+    settled = true;
+    rejectCallback(new Error("Fargo OAuth authorization timed out"));
+    void closeServer(server);
+  }, timeoutMs);
+
+  return {
+    redirectUri: `http://${LOOPBACK_HOST}:${address.port}${callbackPath}`,
+    async waitForCallback() {
+      return callback;
+    },
+    async close() {
+      clearTimeout(timer);
+      await closeServer(server);
+    }
+  };
+}
+
+function secureHtmlHeaders() {
+  return {
+    "Cache-Control": "no-store",
+    "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'",
+    "Content-Type": "text/html; charset=utf-8",
+    "Referrer-Policy": "no-referrer",
+    "X-Content-Type-Options": "nosniff"
+  };
+}
+
+function completionPage(success, message) {
+  const title = success ? "授权成功" : "授权未完成";
+  const marker = success ? "✓ 安全连接" : "连接未完成";
+  return `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${title}</title><style>
+  :root{color-scheme:light;--ink:#11110f;--muted:#68635b;--line:#aaa49a;--green:#27704e}*{box-sizing:border-box}body{min-height:100vh;margin:0;display:grid;place-items:center;background:#f3f2ee;color:var(--ink);font-family:Inter,"Noto Sans SC",system-ui,sans-serif;padding:24px}main{width:min(100%,620px);border:1px solid var(--line);border-top:4px solid var(--ink);background:#fff;padding:40px;box-shadow:0 8px 24px rgba(0,0,0,.05)}.marker{color:${success ? "var(--green)" : "var(--muted)"};font-weight:850}h1{font-size:36px;margin:12px 0}p{color:var(--muted);line-height:1.65}
+  </style></head><body><main><span class="marker">${marker}</span><h1>${title}</h1><p>${message}</p></main></body></html>`;
+}
+
+function closeServer(server) {
+  if (!server.listening) return Promise.resolve();
+  return new Promise((resolve) => server.close(() => resolve()));
+}

package/src/mcp-proxy.mjs

@@ -1,6 +1,6 @@
 import { createInterface } from "node:readline";
 import { CLI_VERSION, DEFAULT_MCP_URL } from "./constants.mjs";
-import { currentCredential, refreshCredential } from "./auth.mjs";
+import { currentCredential, refreshCurrentCredential } from "./auth.mjs";
 
 export async function runMcpProxy(store, options = {}) {
   const input = options.input ?? process.stdin;
@@ -39,7 +39,8 @@ export async function runMcpProxy(store, options = {}) {
     if (sessionId) headers["Mcp-Session-Id"] = sessionId;
     const response = await fetchImpl(mcpUrl, { method: "POST", headers, body: JSON.stringify(message) });
     if (response.status === 401 && !didRefresh) {
-      credential = await refreshCredential(store, credential, { fetchImpl });
+      credential = await refreshCurrentCredential(store, credential, { fetchImpl });
+      if (!credential) throw new Error("Fargo CLI is not authenticated");
       return forward(message, true);
     }
     if (!response.ok && response.status !== 202) throw new Error(`Fargo MCP returned HTTP ${response.status}`);

package/src/workbuddy-install.mjs

@@ -1,22 +1,38 @@
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { access, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { CLI_VERSION } from "./constants.mjs";
 
 const PACKAGE_NAME = "@fargowealth/fargo-ai-cli";
 
 export async function installWorkBuddyMcp(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const homeDirectory = options.home ?? homedir();
   const configPath = options.configPath
-    ?? process.env.FARGO_WORKBUDDY_MCP_CONFIG
-    ?? defaultWorkBuddyConfigPath();
+    ?? env.FARGO_WORKBUDDY_MCP_CONFIG
+    ?? defaultWorkBuddyConfigPath(homeDirectory);
   const packageSpec = `${PACKAGE_NAME}@${options.packageVersion ?? CLI_VERSION}`;
   const config = await readConfig(configPath);
+  const npxCommand = options.npxCommand ?? (platform === "darwin"
+    ? await resolveNpxCommand({ env, execPath: options.execPath, platform })
+    : "npx");
   const nextServer = {
     type: "stdio",
-    command: "npx",
+    command: npxCommand,
     args: ["-y", packageSpec, "mcp", "serve"],
     timeout: 60000
   };
+  if (platform === "darwin") {
+    const credentialDirectory = join(homeDirectory, ".fargo");
+    nextServer.env = {
+      FARGO_CREDENTIAL_PATH: join(credentialDirectory, "credentials.json"),
+      FARGO_CREDENTIAL_STORE: "file",
+      FARGO_REFRESH_LOCK_PATH: join(credentialDirectory, "oauth-refresh.lock"),
+      PATH: buildMacPath(npxCommand)
+    };
+  }
   const previousServer = config.mcpServers?.["fargo-ai"];
   const changed = JSON.stringify(previousServer) !== JSON.stringify(nextServer);
 
@@ -37,6 +53,40 @@ export async function installWorkBuddyMcp(options = {}) {
   };
 }
 
+export async function resolveNpxCommand(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const execPath = options.execPath ?? process.execPath;
+  const executableName = platform === "win32" ? "npx.cmd" : "npx";
+  const pathDelimiter = platform === "win32" ? ";" : ":";
+  const candidates = [
+    join(dirname(execPath), executableName),
+    ...String(env.PATH ?? "").split(pathDelimiter).filter(Boolean).map((entry) => join(entry, executableName))
+  ];
+  for (const candidate of candidates) {
+    const absoluteCandidate = isAbsolute(candidate) ? candidate : resolve(candidate);
+    try {
+      await access(absoluteCandidate, platform === "win32" ? fsConstants.F_OK : fsConstants.X_OK);
+      return absoluteCandidate;
+    } catch {
+      // Keep searching for an executable that will also be visible to the GUI host.
+    }
+  }
+  throw new Error("Unable to locate an absolute npx executable for WorkBuddy");
+}
+
+function buildMacPath(npxCommand) {
+  return [...new Set([
+    dirname(npxCommand),
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+    "/usr/bin",
+    "/bin",
+    "/usr/sbin",
+    "/sbin"
+  ])].join(":");
+}
+
 export function defaultWorkBuddyConfigPath(homeDirectory = homedir()) {
   return join(homeDirectory, ".workbuddy-ai", "mcp.json");
 }