chore: sync from internal

Author: phantom-commit-bot[bot]

packages/mcp-server/src/auth/DeviceCodeAuthProvider.test.ts

@@ -231,4 +231,50 @@ describe("DeviceCodeAuthProvider", () => {
       }),
     );
   });
+
+  it("emits a text prompt instead of launching the browser when openBrowser is false", async () => {
+    mockAxiosPost
+      .mockResolvedValueOnce({
+        data: {
+          device_code: "device-code",
+          user_code: "ABCD-1234",
+          verification_uri: "https://auth.phantom.app/oauth2/device",
+          expires_in: 600,
+          interval: 1,
+        },
+      })
+      .mockResolvedValueOnce({
+        data: {
+          access_token: "access-token",
+          refresh_token: "refresh-token",
+          id_token:
+            "header." + Buffer.from(JSON.stringify({ organization_id: "org-123" })).toString("base64url") + ".sig",
+          expires_in: 3600,
+          token_type: "Bearer",
+        },
+      });
+    mockFromAccessToken.mockReturnValue({
+      sub: "auth-user-1",
+      clientId: "env-client-id",
+      wallet: { id: "wallet-from-token", derivationIndex: 0 },
+    });
+    mockGetOrCreateAppWallet.mockResolvedValue({ walletId: "agent-wallet-id", tags: [] });
+
+    const onPrompt = jest.fn();
+    const provider = new DeviceCodeAuthProvider(stamper as never, {
+      authBaseUrl: "https://auth.phantom.app",
+      connectBaseUrl: "https://connect.phantom.app",
+      walletsApiBaseUrl: "https://api.phantom.app/v1/wallets",
+      appId: "phantom-mcp",
+      sessionDir: "/tmp/test-phantom-mcp",
+    });
+
+    await provider.authenticate({ openBrowser: false, onPrompt });
+
+    expect(mockExecFile).not.toHaveBeenCalled();
+    expect(onPrompt).toHaveBeenCalledTimes(1);
+    expect(onPrompt.mock.calls[0][0]).toContain("Phantom Wallet — Device Authorization");
+    expect(onPrompt.mock.calls[0][0]).toContain("ABCD-1234");
+    expect(onPrompt.mock.calls[0][0]).toContain("https://connect.phantom.app/device-connect");
+  });
 });

packages/mcp-server/src/auth/DeviceCodeAuthProvider.ts

@@ -48,6 +48,12 @@ export type DeviceCodeAuthResult = {
   appId: string;
 };
 
+export type DeviceCodeAuthDisplayOptions = {
+  openBrowser?: boolean;
+  promptOnly?: boolean;
+  onPrompt?: (message: string) => void | Promise<void>;
+};
+
 const UUID_CLIENT_ID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export class DeviceCodeAuthProvider {
   constructor(
@@ -56,7 +62,7 @@ export class DeviceCodeAuthProvider {
     private readonly logger: Logger = new Logger("DeviceCodeAuthProvider"),
   ) {}
 
-  async authenticate(): Promise<DeviceCodeAuthResult> {
+  async authenticate(displayOptions: DeviceCodeAuthDisplayOptions = {}): Promise<DeviceCodeAuthResult> {
     if (!this.stamper.getKeyInfo()) {
       await this.stamper.init();
     }
@@ -72,7 +78,15 @@ export class DeviceCodeAuthProvider {
     const nonce = await _deriveNonce(keyPair, "");
     const deviceAuth = await this.requestDeviceCode(clientConfig.client_id, nonce);
 
-    await this.displayDeviceCode(deviceAuth, clientConfig.client_id, keyInfo.publicKey);
+    const promptText = await this.displayDeviceCode(
+      deviceAuth,
+      clientConfig.client_id,
+      keyInfo.publicKey,
+      displayOptions,
+    );
+    if (displayOptions.promptOnly && promptText) {
+      throw new Error(promptText);
+    }
 
     const tokens = await this.pollForTokens(
       clientConfig.client_id,
@@ -198,26 +212,29 @@ export class DeviceCodeAuthProvider {
     deviceAuth: DeviceAuthorizationResponse,
     clientId: string,
     publicKey: string,
-  ): Promise<void> {
+    displayOptions: DeviceCodeAuthDisplayOptions = {},
+  ): Promise<string | null> {
     const { user_code } = deviceAuth;
     const urlToOpen = `${this.options.connectBaseUrl}/device-connect?user_code=${encodeURIComponent(user_code)}&client_id=${encodeURIComponent(clientId)}&public_key=${encodeURIComponent(publicKey)}`;
     this.logger.info(`Generated device connect URL: ${urlToOpen}`);
 
     let browserOpened = false;
-    try {
-      await new Promise<void>((resolve, reject) => {
-        if (process.platform === "win32") {
-          execFile("cmd", ["/c", "start", "", urlToOpen], err => (err ? reject(err) : resolve()));
-        } else {
-          const cmd = process.platform === "darwin" ? "open" : "xdg-open";
-          execFile(cmd, [urlToOpen], err => (err ? reject(err) : resolve()));
-        }
-      });
-      browserOpened = true;
-      this.logger.info(`Browser opened for device authorization: ${urlToOpen}`);
-    } catch (error) {
-      const msg = error instanceof Error ? error.message : String(error);
-      this.logger.warn(`Could not open browser automatically: ${msg}`);
+    if (displayOptions.openBrowser !== false) {
+      try {
+        await new Promise<void>((resolve, reject) => {
+          if (process.platform === "win32") {
+            execFile("cmd", ["/c", "start", "", urlToOpen], err => (err ? reject(err) : resolve()));
+          } else {
+            const cmd = process.platform === "darwin" ? "open" : "xdg-open";
+            execFile(cmd, [urlToOpen], err => (err ? reject(err) : resolve()));
+          }
+        });
+        browserOpened = true;
+        this.logger.info(`Browser opened for device authorization: ${urlToOpen}`);
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        this.logger.warn(`Could not open browser automatically: ${msg}`);
+      }
     }
 
     const line = (content: string) => process.stderr.write(content + "\n");
@@ -233,14 +250,27 @@ export class DeviceCodeAuthProvider {
       line("║  Waiting for approval...                     ║");
       line("╚══════════════════════════════════════════════╝");
       line("");
-      return;
+      return null;
     }
 
     const hyperlink = `\x1b]8;;${urlToOpen}\x07${urlToOpen}\x1b]8;;\x07`;
     const qr = await new Promise<string>(resolve => {
       qrcode.generate(urlToOpen, { small: true }, resolve);
     });
 
+    if (displayOptions.onPrompt) {
+      const promptText = [
+        "Phantom Wallet — Device Authorization",
+        "",
+        "Please visit this link to approve the connection:",
+        urlToOpen,
+        "",
+        `Code: ${user_code}`,
+      ].join("\n");
+      await displayOptions.onPrompt(promptText);
+      return promptText;
+    }
+
     line("");
     line("╔══════════════════════════════════════════════╗");
     line("║  Phantom Wallet — Device Authorization       ║");
@@ -257,6 +287,7 @@ export class DeviceCodeAuthProvider {
     process.stderr.write(qr);
     line(hyperlink);
     line("");
+    return null;
   }
 
   private async pollForTokens(

packages/mcp-server/src/index.ts

@@ -4,6 +4,7 @@
 // Export SessionManager and types for external usage
 export { SessionManager } from "./session/manager.js";
 export type { SessionData } from "./session/types.js";
+export type { DeviceCodeAuthDisplayOptions } from "./auth/DeviceCodeAuthProvider.js";
 
 // Export tools for external usage
 export { tools } from "./tools/index.js";

packages/mcp-server/src/server.test.ts

@@ -191,6 +191,35 @@ describe("PhantomMCPServer", () => {
     expect(mockSetPaymentHandler).toHaveBeenCalledTimes(1);
   });
 
+  it("passes text display mode to phantom_login and returns the prompt text", async () => {
+    mockGetTool.mockReturnValue(mockTools[0]);
+    mockSessionManagerInstance.resetSession.mockImplementation((_opts?: unknown) => Promise.resolve(undefined));
+    mockSessionManagerInstance.getSession.mockReturnValue({
+      walletId: "wallet-login",
+      organizationId: "org-1",
+      appId: "session-client-id",
+      authFlow: "device-code",
+    });
+    mockSessionManagerInstance.getClient.mockReturnValue({
+      getWalletAddresses: jest.fn().mockResolvedValue([{ addressType: "solana", address: "So1Address" }]),
+    });
+
+    new PhantomMCPServer();
+    const { callTool } = getHandlers();
+    const result = await callTool({ params: { name: "phantom_login", arguments: { displayMode: "text" } } });
+
+    expect(mockSessionManagerInstance.resetSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        openBrowser: false,
+        onPrompt: expect.any(Function),
+      }),
+    );
+
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.success).toBe(true);
+    expect(parsed.authFlow).toBe("device-code");
+  });
+
   it("returns AUTH_EXPIRED and resets session when token refresh fails on 401", async () => {
     const toolHandler = jest.fn().mockRejectedValue({ response: { status: 401 } });
     mockGetTool.mockReturnValue({

packages/mcp-server/src/server.ts

@@ -211,12 +211,24 @@ export class PhantomMCPServer {
         // even when the session is not yet initialized (first run, expired, etc.)
         if (toolName === "phantom_login") {
           this.logger.info("Handling phantom_login: resetting session");
+          const displayMode = request.params.arguments?.displayMode;
+          const useTextPrompt = displayMode === "text";
+          let promptText: string | null = null;
           this.logger.info(
             "Starting authentication now. If using SSO, Phantom Connect will open in your browser. " +
               "If using device-code, a device connect URL and code will be shown in the terminal.",
           );
           try {
-            await this.sessionManager.resetSession();
+            await this.sessionManager.resetSession(
+              useTextPrompt
+                ? {
+                    openBrowser: false,
+                    onPrompt: message => {
+                      promptText = message;
+                    },
+                  }
+                : undefined,
+            );
             const session = this.sessionManager.getSession();
             this.logger.info(
               `phantom_login successful for walletId: ${session.walletId}, authFlow: ${session.authFlow}`,
@@ -235,6 +247,7 @@ export class PhantomMCPServer {
                     {
                       success: true,
                       message: "Authentication successful.",
+                      ...(promptText ? { prompt: promptText } : {}),
                       walletId: session.walletId,
                       authFlow: session.authFlow ?? "device-code",
                     },

packages/mcp-server/src/session/manager.ts

@@ -14,6 +14,7 @@ import { SessionStorage } from "./storage.js";
 import { OAuthFlow } from "../auth/oauth.js";
 import { DeviceCodeAuthProvider } from "../auth/DeviceCodeAuthProvider.js";
 import { NodeFileAuth2StamperStorage } from "../auth/NodeFileAuth2StamperStorage.js";
+import type { DeviceCodeAuthDisplayOptions } from "../auth/DeviceCodeAuthProvider.js";
 import type { SessionData } from "./types.js";
 import { Logger } from "../utils/logger.js";
 import * as packageJson from "../../package.json";
@@ -154,7 +155,7 @@ export class SessionManager {
    *
    * @throws Error if authentication fails
    */
-  async initialize(): Promise<void> {
+  async initialize(displayOptions?: DeviceCodeAuthDisplayOptions): Promise<void> {
     this.logger.info("Initializing session manager");
 
     // Step 1: Try to load existing session
@@ -179,7 +180,7 @@ export class SessionManager {
           this.storage.delete();
           this.session = null;
           this.client = null;
-          await this.authenticate();
+          await this.authenticate(displayOptions);
           return;
         }
         // Non-auth errors (network down, timeout) — keep the session and proceed
@@ -196,7 +197,7 @@ export class SessionManager {
       this.logger.info("No session found, authenticating");
     }
 
-    await this.authenticate();
+    await this.authenticate(displayOptions);
   }
 
   /**
@@ -269,7 +270,7 @@ export class SessionManager {
    *
    * @throws Error if authentication fails
    */
-  async resetSession(): Promise<void> {
+  async resetSession(displayOptions?: DeviceCodeAuthDisplayOptions): Promise<void> {
     this.logger.info("Resetting session");
 
     // Clear stored session
@@ -280,7 +281,7 @@ export class SessionManager {
     this.stamper = null;
 
     // Re-authenticate
-    await this.authenticate();
+    await this.authenticate(displayOptions);
   }
 
   /**
@@ -289,11 +290,11 @@ export class SessionManager {
    *
    * @throws Error if authentication fails
    */
-  private async authenticate(): Promise<void> {
+  private async authenticate(displayOptions?: DeviceCodeAuthDisplayOptions): Promise<void> {
     this.logger.info(`Starting authentication (flow: ${this.authFlow})`);
 
     if (this.authFlow === "device-code") {
-      await this.authenticateWithDeviceFlow();
+      await this.authenticateWithDeviceFlow(displayOptions);
     } else {
       await this.authenticateWithSso();
     }
@@ -338,7 +339,7 @@ export class SessionManager {
    *
    * @throws Error if device flow fails
    */
-  private async authenticateWithDeviceFlow(): Promise<void> {
+  private async authenticateWithDeviceFlow(displayOptions?: DeviceCodeAuthDisplayOptions): Promise<void> {
     const stamper = new Auth2Stamper(new NodeFileAuth2StamperStorage(this.storage.sessionDir), {
       authApiBaseUrl: this.authBaseUrl,
       clientId: this.resolveAppId(),
@@ -357,7 +358,7 @@ export class SessionManager {
       this.logger.child("DeviceCodeAuthProvider"),
     );
 
-    const result = await deviceFlow.authenticate();
+    const result = await deviceFlow.authenticate(displayOptions);
     this.logger.info("Device authorization flow completed successfully");
 
     const now = Math.floor(Date.now() / 1000);

packages/mcp-server/src/tools/login.ts

@@ -13,10 +13,18 @@ import type { ToolHandler } from "./types.js";
 export const loginTool: ToolHandler = {
   name: "phantom_login",
   description:
-    "Re-authenticate with Phantom. Use this to log in for the first time, switch accounts, or refresh an expired session.",
+    "Re-authenticate with Phantom. Use this to log in for the first time, switch accounts, or refresh an expired session. " +
+    "Set displayMode to 'text' if you want the login prompt returned as text instead of trying to open a browser automatically.",
   inputSchema: {
     type: "object",
-    properties: {},
+    properties: {
+      displayMode: {
+        type: "string",
+        enum: ["browser", "text"],
+        description:
+          "'browser' (default) tries to open the browser automatically. 'text' returns the login prompt text instead.",
+      },
+    },
   },
   annotations: {
     readOnlyHint: false,

packages/phantom-openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phantom/phantom-openclaw-plugin",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Phantom Embedded Wallet — sign transactions, transfer tokens, and swap on Solana and Ethereum. Powered by Phantom.",
   "repository": {
     "type": "git",

packages/phantom-openclaw-plugin/src/index.ts

@@ -115,13 +115,9 @@ function resetSession(): void {
 /**
  * Plugin registration function
  */
-export default async function register(api: OpenClawApi) {
+export default function register(api: OpenClawApi) {
   try {
-    // Initialize session (authenticate if needed)
     const session = getSession(api.config);
-    await session.initialize();
-
-    // Register all Phantom MCP tools
     registerPhantomTools(api, session);
   } catch (error) {
     console.error("Failed to initialize Phantom OpenClaw plugin:", error); // eslint-disable-line no-console