remove plaintext session fallback, keychain-only tokens (v0.6.1)

Remove ~/.robinhood-for-agents/session.json plaintext fallback from
token-store. Tokens are now stored exclusively in the OS keychain
via Bun.secrets. No tokens are written to disk.

Update ClawHub skill metadata to declare Chrome dependency and
credential storage mechanism. Rewrite domain files as client-API-first
(no MCP references in main flow).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: kevin1chun

CLAUDE.md

@@ -59,7 +59,7 @@ await rh.restoreSession();
 ```
 - All methods are `async` (native `fetch` under the hood)
 - Multi-account is first-class: every account-scoped method accepts `accountNumber`
-- Session cached in OS keychain via `Bun.secrets` (macOS Keychain Services); plaintext fallback for CI
+- Session cached in OS keychain via `Bun.secrets` (macOS Keychain Services) — no plaintext fallback, no tokens on disk
 - Token refresh via `refresh_token` + `device_token` when access token expires
 - Proper exceptions: `AuthenticationError`, `APIError`
 - **Do NOT use `phoenix.robinhood.com`** — it rejects TLS. Use `api.robinhood.com` endpoints only.

__tests__/client/auth.test.ts

@@ -4,7 +4,7 @@ import { AuthenticationError } from "../../src/client/errors.js";
 // Mock token-store
 vi.mock("../../src/client/token-store.js", () => ({
   loadTokens: vi.fn().mockResolvedValue(null),
-  saveTokens: vi.fn().mockResolvedValue("/tmp/session.enc"),
+  saveTokens: vi.fn().mockResolvedValue("keychain"),
   deleteTokens: vi.fn().mockResolvedValue(undefined),
 }));
 

__tests__/client/token-store.test.ts

@@ -1,22 +1,8 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-// Mock node:fs before importing the module
-vi.mock("node:fs", () => ({
-  existsSync: vi.fn(),
-  mkdirSync: vi.fn(),
-  writeFileSync: vi.fn(),
-  renameSync: vi.fn(),
-  unlinkSync: vi.fn(),
-}));
-
-import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 import type { Mock } from "vitest";
 import { deleteTokens, loadTokens, saveTokens } from "../../src/client/token-store.js";
 
-const mockExistsSync = existsSync as Mock;
-const mockWriteFileSync = writeFileSync as Mock;
-const mockUnlinkSync = unlinkSync as Mock;
-
 const sampleTokens = {
   access_token: "tok123",
   refresh_token: "ref456",
@@ -52,7 +38,7 @@ describe("token-store", () => {
     vi.restoreAllMocks();
   });
 
-  describe("saveTokens (keychain available)", () => {
+  describe("saveTokens", () => {
     it("stores tokens in Bun.secrets", async () => {
       const result = await saveTokens(sampleTokens);
 
@@ -71,27 +57,9 @@ describe("token-store", () => {
       expect(parsed.saved_at).toBeTypeOf("number");
     });
 
-    it("does not write to filesystem when keychain available", async () => {
-      await saveTokens(sampleTokens);
-      expect(mockWriteFileSync).not.toHaveBeenCalled();
-    });
-  });
-
-  describe("saveTokens (keychain unavailable)", () => {
-    it("falls back to plaintext JSON file", async () => {
-      mockSecrets.get.mockRejectedValueOnce(new Error("unavailable"));
-      const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-
-      await saveTokens(sampleTokens);
-
-      expect(mkdirSync).toHaveBeenCalled();
-      expect(mockWriteFileSync).toHaveBeenCalled();
-
-      const writtenData = mockWriteFileSync.mock.calls[0]?.[1];
-      const parsed = JSON.parse(writtenData);
-      expect(parsed.access_token).toBe("tok123");
-
-      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("Bun.secrets unavailable"));
+    it("throws when Bun.secrets is unavailable", async () => {
+      mockSecrets.set.mockRejectedValueOnce(new Error("unavailable"));
+      await expect(saveTokens(sampleTokens)).rejects.toThrow("unavailable");
     });
   });
 
@@ -106,44 +74,42 @@ describe("token-store", () => {
     });
 
     it("returns null when no tokens stored", async () => {
-      mockExistsSync.mockReturnValue(false);
       const result = await loadTokens();
       expect(result).toBeNull();
     });
 
     it("returns null for invalid JSON in keychain", async () => {
       mockSecretsStore.set("robinhood-for-agents:session-tokens", "not json");
-      mockExistsSync.mockReturnValue(false);
-
       const result = await loadTokens();
       expect(result).toBeNull();
     });
 
     it("returns null for JSON without access_token", async () => {
       mockSecretsStore.set("robinhood-for-agents:session-tokens", JSON.stringify({ foo: "bar" }));
-      mockExistsSync.mockReturnValue(false);
+      const result = await loadTokens();
+      expect(result).toBeNull();
+    });
 
+    it("returns null when Bun.secrets throws", async () => {
+      mockSecrets.get.mockRejectedValueOnce(new Error("keychain locked"));
       const result = await loadTokens();
       expect(result).toBeNull();
     });
   });
 
   describe("deleteTokens", () => {
-    it("deletes from keychain and cleans up fallback file", async () => {
+    it("deletes from keychain", async () => {
       mockSecretsStore.set("robinhood-for-agents:session-tokens", "data");
-      mockExistsSync.mockReturnValue(true);
 
       await deleteTokens();
 
       expect(mockSecrets.delete).toHaveBeenCalledWith({
         service: "robinhood-for-agents",
         name: "session-tokens",
       });
-      expect(mockUnlinkSync).toHaveBeenCalled();
     });
 
     it("does not throw when nothing to delete", async () => {
-      mockExistsSync.mockReturnValue(false);
       await expect(deleteTokens()).resolves.toBeUndefined();
     });
   });

skills/robinhood-for-agents/SKILL.md

@@ -8,7 +8,8 @@ install:
     package: robinhood-for-agents
     bins: [robinhood-for-agents]
 requires:
-  bins: [bun]
+  bins: [bun, google-chrome]
+metadata: {"credentials":"OAuth tokens stored in OS keychain via Bun.secrets (macOS Keychain Services, Linux libsecret, Windows Credential Manager). No tokens on disk. Browser login captures tokens via Playwright intercepting network traffic — no DOM interaction. Tokens expire ~24h.","chrome":"Required only for initial login (bunx robinhood-for-agents login). Not needed for subsequent API calls."}
 ---
 
 # robinhood-for-agents

skills/robinhood-for-agents/setup.md

@@ -37,7 +37,7 @@ Confirm to the user that authentication is complete.
 ## Security Warning
 After successful login, **always** remind the user:
 
-> **The session file at `~/.robinhood-for-agents/session.enc` contains encrypted Robinhood OAuth tokens. The encryption key is stored in the OS keychain (AES-256-GCM via node:crypto). Anyone with access to this machine can decrypt them. Tokens expire after ~24 hours. Never copy these files to untrusted locations.**
+> **Robinhood OAuth tokens are stored in the OS keychain (macOS Keychain Services, Linux libsecret, Windows Credential Manager) via Bun.secrets. No tokens are written to disk. Tokens expire after ~24 hours. Anyone with access to this machine's keychain can read them.**
 
 ## Notes
 - No credentials (username/password) pass through the tool layer — login happens on the real Robinhood website

src/client/token-store.ts

@@ -4,20 +4,12 @@
  * Tokens are stored as JSON directly in the OS keychain
  * (macOS Keychain Services, Linux libsecret, Windows Credential Manager).
  *
- * Falls back to plaintext JSON at ~/.robinhood-for-agents/session.json
- * if Bun.secrets is unavailable (e.g. in CI or minimal environments).
+ * Bun.secrets is required — no plaintext fallback.
  */
 
-import { existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
 const KEYRING_SERVICE = "robinhood-for-agents";
 const KEYRING_NAME = "session-tokens";
 
-const TOKEN_DIR = join(homedir(), ".robinhood-for-agents");
-const FALLBACK_FILE = join(TOKEN_DIR, "session.json");
-
 export interface TokenData {
   access_token: string;
   refresh_token: string;
@@ -27,18 +19,6 @@ export interface TokenData {
   saved_at: number;
 }
 
-async function secretsAvailable(): Promise<boolean> {
-  try {
-    if (typeof Bun !== "undefined" && Bun.secrets) {
-      await Bun.secrets.get(KEYRING_SERVICE, KEYRING_NAME);
-      return true;
-    }
-    return false;
-  } catch {
-    return false;
-  }
-}
-
 function isTokenData(data: unknown): data is TokenData {
   if (typeof data !== "object" || data === null) return false;
   const obj = data as Record<string, unknown>;
@@ -54,44 +34,21 @@ function isTokenData(data: unknown): data is TokenData {
 export async function saveTokens(tokens: Omit<TokenData, "saved_at">): Promise<string> {
   const data: TokenData = { ...tokens, saved_at: Date.now() / 1000 };
   const json = JSON.stringify(data);
-
-  if (await secretsAvailable()) {
-    await Bun.secrets.set(KEYRING_SERVICE, KEYRING_NAME, json);
-    return "keychain";
-  }
-
-  // Fallback: plaintext JSON file (atomic write with correct permissions from creation)
-  console.warn("[robinhood-for-agents] Bun.secrets unavailable — saving tokens as plaintext JSON");
-  mkdirSync(TOKEN_DIR, { recursive: true, mode: 0o700 });
-  const tmpFile = `${FALLBACK_FILE}.tmp`;
-  writeFileSync(tmpFile, json, { mode: 0o600 });
-  renameSync(tmpFile, FALLBACK_FILE);
-  return FALLBACK_FILE;
+  await Bun.secrets.set(KEYRING_SERVICE, KEYRING_NAME, json);
+  return "keychain";
 }
 
 export async function loadTokens(): Promise<TokenData | null> {
   try {
-    if (await secretsAvailable()) {
-      const json = await Bun.secrets.get(KEYRING_SERVICE, KEYRING_NAME);
-      if (json) {
-        const data: unknown = JSON.parse(json);
-        if (isTokenData(data)) return data;
-      }
+    const json = await Bun.secrets.get(KEYRING_SERVICE, KEYRING_NAME);
+    if (json) {
+      const data: unknown = JSON.parse(json);
+      if (isTokenData(data)) return data;
     }
   } catch {
-    // Fall through to file fallback
-  }
-
-  // Fallback: plaintext JSON file
-  if (!existsSync(FALLBACK_FILE)) return null;
-  try {
-    const raw = Bun.file(FALLBACK_FILE);
-    const data: unknown = await raw.json();
-    if (isTokenData(data)) return data;
-    return null;
-  } catch {
-    return null;
+    // Bun.secrets unavailable or keychain access denied
   }
+  return null;
 }
 
 export async function deleteTokens(): Promise<void> {
@@ -100,8 +57,4 @@ export async function deleteTokens(): Promise<void> {
   } catch {
     // Bun.secrets unavailable
   }
-
-  if (existsSync(FALLBACK_FILE)) {
-    unlinkSync(FALLBACK_FILE);
-  }
 }