chore: sync from internal

Author: phantom-commit-bot[bot]

.github/CODEOWNERS

@@ -1,4 +1,5 @@
-# Security can use overrides to approve when needed
+/.github/workflows/*.yml @phantom/security
 
+# Security can use overrides to approve when needed rather than CO
 **/yarn.lock @phantom/wallet-platform
 **/package.json @phantom/wallet-platform

packages/auth2/src/Auth2Stamper.ts

@@ -25,7 +25,7 @@ export class Auth2Stamper implements Auth2StamperWithKeyManagement {
   private _refreshToken: string | null = null;
   private _tokenExpiresAt: number | null = null;
 
-  private isRefreshingTokens: boolean = false;
+  private refreshingTokensPromise: Promise<boolean> | null = null;
 
   // Because TOKEN_REFRESH_BUFFER_MS proactively handles refresh, we can safely use void here
   // and return the existing cached values immediately.
@@ -124,43 +124,51 @@ export class Auth2Stamper implements Auth2StamperWithKeyManagement {
 
   /**
    * Checks if tokens should be refreshed and performs a refresh if needed.
-   * Returns void after attempting any necessary refresh.
+   * Returns true if a refresh succeeded, false otherwise.
    */
-  private async maybeRefreshTokens(): Promise<void> {
+  async maybeRefreshTokens(): Promise<boolean> {
+    if (this.refreshingTokensPromise) {
+      return this.refreshingTokensPromise;
+    }
+
     if (
-      this.isRefreshingTokens ||
       !this.refreshConfig ||
       !this._refreshToken ||
       !this._tokenExpiresAt ||
-      // Skip refresh if the token still has plenty of time left.
       Date.now() < this._tokenExpiresAt - TOKEN_REFRESH_BUFFER_MS
     ) {
-      return;
+      return false;
     }
 
-    this.isRefreshingTokens = true;
-
-    try {
-      const refreshed = await refreshTokenRequest({
-        authApiBaseUrl: this.refreshConfig.authApiBaseUrl,
-        clientId: this.refreshConfig.clientId,
-        redirectUri: this.refreshConfig.redirectUri,
-        refreshToken: this._refreshToken,
-      });
+    const refreshConfig = this.refreshConfig;
+    const refreshToken = this._refreshToken;
+
+    this.refreshingTokensPromise = (async () => {
+      try {
+        const refreshed = await refreshTokenRequest({
+          authApiBaseUrl: refreshConfig.authApiBaseUrl,
+          clientId: refreshConfig.clientId,
+          redirectUri: refreshConfig.redirectUri,
+          refreshToken,
+        });
+
+        await this.setTokens({
+          accessToken: refreshed.accessToken,
+          idType: refreshed.idType,
+          refreshToken: refreshed.refreshToken,
+          expiresInMs: refreshed.expiresInMs,
+        });
+        return true;
+      } catch (error) {
+        console.error("Failed to refresh tokens:", error);
+        return false;
+      } finally {
+        this.refreshingTokensPromise = null;
+      }
+    })();
 
-      await this.setTokens({
-        accessToken: refreshed.accessToken,
-        idType: refreshed.idType,
-        refreshToken: refreshed.refreshToken,
-        expiresInMs: refreshed.expiresInMs,
-      });
-    } catch (error) {
-      console.error("Failed to refresh tokens:", error);
-    } finally {
-      this.isRefreshingTokens = false;
-    }
+    return this.refreshingTokensPromise;
   }
-
   async stamp(params: { data: Buffer; type?: "PKI" } | { data: Buffer; type: "OIDC" }): Promise<string> {
     if (!this._keyPair || !this._keyInfo || !this.auth2Token) {
       throw new Error("Auth2Stamper not initialized. Call init() first.");

packages/auth2/src/__tests__/Auth2Stamper.test.ts

@@ -455,6 +455,143 @@ describe("Auth2Stamper", () => {
     });
   });
 
+  describe("maybeRefreshTokens()", () => {
+    it("returns true and updates bearerToken after a successful refresh", async () => {
+      const mockFetch = globalThis.fetch as jest.Mock;
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            access_token: "forced-new-access",
+            refresh_token: "forced-new-refresh",
+            token_type: "Bearer",
+            expires_in: 3600,
+          }),
+      });
+
+      const storage = makeStorage(STORED_RECORD);
+      const stamper = new Auth2Stamper(storage, {
+        authApiBaseUrl: "https://auth.example.com",
+        clientId: "client-1",
+        redirectUri: "https://app.example.com/callback",
+      });
+      await stamper.init();
+      (stamper as any)._tokenExpiresAt = Date.now() - 1000;
+
+      const result = await stamper.maybeRefreshTokens();
+
+      expect(result).toBe(true);
+      expect(stamper.bearerToken).toBe("Bearer forced-new-access");
+    });
+
+    it("returns false when no refreshToken is available", async () => {
+      const storage = makeStorage({ ...STORED_RECORD, refreshToken: undefined });
+      const stamper = new Auth2Stamper(storage, {
+        authApiBaseUrl: "https://auth.example.com",
+        clientId: "client-1",
+        redirectUri: "https://app.example.com/callback",
+      });
+      await stamper.init();
+      (stamper as any)._refreshToken = null;
+
+      const result = await stamper.maybeRefreshTokens();
+
+      expect(result).toBe(false);
+    });
+
+    it("returns false when no refreshConfig is provided", async () => {
+      const storage = makeStorage(STORED_RECORD);
+      const stamper = new Auth2Stamper(storage); // no refreshConfig
+      await stamper.init();
+
+      const result = await stamper.maybeRefreshTokens();
+
+      expect(result).toBe(false);
+    });
+
+    it("returns false and does not throw when the refresh request fails", async () => {
+      const mockFetch = globalThis.fetch as jest.Mock;
+      mockFetch.mockRejectedValueOnce(new Error("network error"));
+
+      const storage = makeStorage(STORED_RECORD);
+      const stamper = new Auth2Stamper(storage, {
+        authApiBaseUrl: "https://auth.example.com",
+        clientId: "client-1",
+        redirectUri: "https://app.example.com/callback",
+      });
+      await stamper.init();
+      (stamper as any)._refreshToken = "stored-refresh-token";
+      (stamper as any)._tokenExpiresAt = Date.now() - 1000;
+
+      const result = await stamper.maybeRefreshTokens();
+
+      expect(result).toBe(false);
+      // bearerToken unchanged — still the stored access token
+      expect(stamper.bearerToken).toBe("Bearer stored-access-token");
+    });
+
+    it("shares the in-flight refresh result and does not make a second request when already refreshing", async () => {
+      const mockFetch = globalThis.fetch as jest.Mock;
+      let resolveRefresh!: () => void;
+      mockFetch.mockReturnValueOnce(
+        new Promise(resolve => {
+          resolveRefresh = () =>
+            resolve({
+              ok: true,
+              json: () =>
+                Promise.resolve({
+                  access_token: "new",
+                  refresh_token: "new-r",
+                  token_type: "Bearer",
+                  expires_in: 3600,
+                }),
+            });
+        }),
+      );
+
+      const storage = makeStorage(STORED_RECORD);
+      const stamper = new Auth2Stamper(storage, {
+        authApiBaseUrl: "https://auth.example.com",
+        clientId: "c",
+        redirectUri: "https://app.example.com/cb",
+      });
+      await stamper.init();
+      (stamper as any)._refreshToken = "stored-refresh-token";
+      (stamper as any)._tokenExpiresAt = Date.now() - 1000;
+
+      // Start a refresh but don't await it yet
+      const firstRefresh = stamper.maybeRefreshTokens();
+      // Second call while first is in flight
+      const secondRefresh = stamper.maybeRefreshTokens();
+
+      resolveRefresh();
+      const [firstResult, secondResult] = await Promise.all([firstRefresh, secondRefresh]);
+      expect(firstResult).toBe(true);
+      expect(secondResult).toBe(true);
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+
+    it("returns false when the token is not near expiry", async () => {
+      const mockFetch = globalThis.fetch as jest.Mock;
+
+      const storage = makeStorage(STORED_RECORD);
+      const stamper = new Auth2Stamper(storage, {
+        authApiBaseUrl: "https://auth.example.com",
+        clientId: "c",
+        redirectUri: "https://app.example.com/cb",
+      });
+      await stamper.init();
+
+      (stamper as any)._tokenExpiresAt = Date.now() + 3_600_000;
+      (stamper as any)._refreshToken = "stored-refresh-token";
+
+      const result = await stamper.maybeRefreshTokens();
+
+      expect(result).toBe(false);
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+  });
+
   describe("token refresh", () => {
     it("triggers a background refresh when the token is near expiry", async () => {
       const mockFetch = globalThis.fetch as jest.Mock;

packages/auth2/src/types.ts

@@ -5,6 +5,7 @@ export interface Auth2StamperWithKeyManagement extends StamperWithKeyManagement
   auth2Token: Auth2Token | null;
   bearerToken: string | null;
   getCryptoKeyPair(): CryptoKeyPair | null;
+  maybeRefreshTokens(): Promise<boolean>;
   setTokens(options: {
     accessToken: string;
     idType: string;

packages/mcp-server/README.md

@@ -1,13 +1,5 @@
 # @phantom/mcp-server
 
-> **⚠️ PREVIEW DISCLAIMER**
->
-> This MCP server is currently in **preview** and may break or change at any time without notice.
->
-> **Always use a separate Phantom account specifically for testing with AI agents. These accounts should not contain significant assets.**
->
-> **Phantom makes no guarantees whatsoever around anything your agent may do using this MCP server.** Use at your own risk.
-
 An MCP (Model Context Protocol) server that provides LLMs like Claude with direct access to Phantom wallet operations. This enables AI assistants to interact with embedded wallets, view addresses, simulate transactions, check token approvals, sign and send transactions, and sign messages across Solana and EVM chains through natural language interactions.
 
 ## Features
@@ -52,15 +44,15 @@ An MCP (Model Context Protocol) server that provides LLMs like Claude with direc
 Use npx to run the server without global installation. This ensures you always use the latest version:
 
 ```bash
-npx -y @phantom/mcp-server
+npx -y @phantom/mcp-server@latest
 ```
 
 ### Option 2: Global Install
 
 Install the package globally for faster startup:
 
 ```bash
-npm install -g @phantom/mcp-server
+npm install -g @phantom/mcp-server@latest
 ```
 
 Then run:
@@ -87,7 +79,7 @@ Add the MCP server to your Claude Desktop configuration file:
   "mcpServers": {
     "phantom": {
       "command": "npx",
-      "args": ["-y", "@phantom/mcp-server"]
+      "args": ["-y", "@phantom/mcp-server@latest"]
     }
   }
 }
@@ -153,7 +145,7 @@ In current versions, agents receive a new wallet when they authenticate. That me
 Test the server directly using the MCP inspector:
 
 ```bash
-npx @modelcontextprotocol/inspector npx -y @phantom/mcp-server
+npx @modelcontextprotocol/inspector npx -y @phantom/mcp-server@latest
 ```
 
 This opens an interactive web UI where you can test tool calls without Claude Desktop.
@@ -196,11 +188,6 @@ All EVM tools (`send_evm_transaction`, `sign_evm_personal_message`, `sign_evm_ty
 
 ## Available Tools
 
-> **Execution Warning**
-> `send_solana_transaction`, `send_evm_transaction`, `transfer_tokens`, `buy_token` (when `execute: true`), `deposit_to_hyperliquid`, `open_perp_position`, `close_perp_position`, `cancel_perp_order`, `update_perp_leverage`, `transfer_spot_to_perps`, and `withdraw_from_perps` all submit transactions immediately and irreversibly. Always verify parameters before calling these tools.
-
----
-
 ### 1. get_connection_status
 
 Lightweight check of the current Phantom wallet connection state. Does not make any network or API calls — reads local session state only. Use this to confirm the user is authenticated before other operations.

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phantom/mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP Server for Phantom Wallet",
   "repository": {
     "type": "git",