@fargowealth/fargo-ai-cli 0.3.0 → 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,17 +1,27 @@
-# Fargo CLI
+# Fargo CLI for WorkBuddy
 
-`fargo-cli` provides WorkBuddy with OAuth Authorization Code + PKCE login over an ephemeral loopback callback and a local stdio bridge to the hosted Fargo AI MCP server. Device Authorization Grant remains available as an explicit fallback for restricted environments.
+`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 login --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
 ```
 
-The default 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 the IPv4 loopback interface, validates OAuth `state`, uses PKCE S256, closes the listener after the callback, and never prints the verifier or private OAuth credentials.
+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.
 
-OAuth credentials are stored in macOS Keychain, protected with Windows DPAPI, or written to an owner-only file on Linux. Refresh-token rotation is serialized across local CLI processes so multiple WorkBuddy tasks can safely share the same credential.
+## 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.3.0",
-  "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

@@ -176,12 +176,24 @@ export async function refreshCurrentCredential(store, observedCredential, option
 }
 
 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();
 }
 
+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");

package/src/constants.mjs

@@ -1,4 +1,4 @@
-export const CLI_VERSION = "0.3.0";
+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";

package/src/credential-store.mjs

@@ -1,46 +1,32 @@
-import { mkdir, open, readFile, rm, stat, 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";
 import { randomUUID } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
 
-const KEYCHAIN_SERVICE = "com.fargowealth.fargo-cli.oauth";
-
 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 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 forceFile = env.FARGO_CREDENTIAL_STORE === "file";
   const withRefreshLock = (callback) => withFileLock(refreshLockPath, callback);
 
-  if (!forceFile && platform === "darwin") {
-    const account = env.USER || env.LOGNAME || "fargo-user";
-    return {
-      kind: "macos-keychain",
-      withRefreshLock,
-      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 });
-      }
-    };
-  }
-
-  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",
@@ -67,6 +53,7 @@ export function createCredentialStore(options = {}) {
     withRefreshLock,
     async load() {
       try {
+        await secureExistingFile(filePath);
         return parseCredential(await readFile(filePath, "utf8"));
       } catch (error) {
         if (error?.code === "ENOENT") return undefined;
@@ -74,17 +61,35 @@ 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 mkdir(dirname(lockPath), { recursive: true, mode: 0o700 });
+  await ensurePrivateDirectory(dirname(lockPath));
   const deadline = Date.now() + 15_000;
   const owner = `${process.pid}:${randomUUID()}`;
   let handle;
@@ -120,6 +125,32 @@ async function withFileLock(lockPath, callback) {
   }
 }
 
+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/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");
 }