chore: sync from internal

Author: phantom-commit-bot[bot]

packages/auth2/src/Auth2Stamper.ts

@@ -11,10 +11,18 @@ import type { Auth2StamperStorage } from "./Auth2StamperStorage";
 /** Refresh the access token when fewer than this many ms remain before expiry. */
 const TOKEN_REFRESH_BUFFER_MS = 15 * 60 * 1000;
 
+export type Auth2Logger = {
+  debug?(message: string): void;
+  info?(message: string): void;
+  warn?(message: string): void;
+  error?(message: string): void;
+};
+
 export type Auth2StamperRefreshConfig = {
   authApiBaseUrl: string;
   clientId: string;
   redirectUri: string;
+  logger?: Auth2Logger;
 };
 
 export class Auth2Stamper implements Auth2StamperWithKeyManagement {
@@ -123,16 +131,26 @@ export class Auth2Stamper implements Auth2StamperWithKeyManagement {
    * Returns true if a refresh succeeded, false otherwise.
    */
   async maybeRefreshTokens(): Promise<boolean> {
+    this.refreshConfig?.logger?.debug?.("Auth2Stamper.maybeRefreshTokens() called");
+
     if (this.refreshingTokensPromise) {
+      this.refreshConfig?.logger?.debug?.("Auth2Stamper.maybeRefreshTokens(): awaiting in-flight refresh");
       return this.refreshingTokensPromise;
     }
 
-    if (
-      !this.refreshConfig ||
-      !this._refreshToken ||
-      !this._tokenExpiresAt ||
-      Date.now() < this._tokenExpiresAt - TOKEN_REFRESH_BUFFER_MS
-    ) {
+    if (!this.refreshConfig) {
+      return false;
+    }
+    if (!this._refreshToken) {
+      this.refreshConfig.logger?.debug?.("Auth2Stamper.maybeRefreshTokens(): skipped — missing refresh token");
+      return false;
+    }
+    if (!this._tokenExpiresAt) {
+      this.refreshConfig.logger?.debug?.("Auth2Stamper.maybeRefreshTokens(): skipped — missing token expiry");
+      return false;
+    }
+    if (Date.now() < this._tokenExpiresAt - TOKEN_REFRESH_BUFFER_MS) {
+      this.refreshConfig.logger?.debug?.("Auth2Stamper.maybeRefreshTokens(): skipped — token not near expiry");
       return false;
     }
 
@@ -141,6 +159,7 @@ export class Auth2Stamper implements Auth2StamperWithKeyManagement {
 
     this.refreshingTokensPromise = (async () => {
       try {
+        refreshConfig.logger?.info?.("Auth2Stamper.maybeRefreshTokens(): attempting token refresh");
         const refreshed = await refreshTokenRequest({
           authApiBaseUrl: refreshConfig.authApiBaseUrl,
           clientId: refreshConfig.clientId,
@@ -154,9 +173,11 @@ export class Auth2Stamper implements Auth2StamperWithKeyManagement {
           refreshToken: refreshed.refreshToken,
           expiresInMs: refreshed.expiresInMs,
         });
+        refreshConfig.logger?.info?.("Auth2Stamper.maybeRefreshTokens(): token refresh succeeded");
         return true;
       } catch (error) {
-        console.error("Failed to refresh tokens:", error);
+        const message = error instanceof Error ? error.message : String(error);
+        refreshConfig.logger?.error?.(`Auth2Stamper.maybeRefreshTokens(): token refresh failed: ${message}`);
         return false;
       } finally {
         this.refreshingTokensPromise = null;
@@ -166,11 +187,15 @@ export class Auth2Stamper implements Auth2StamperWithKeyManagement {
     return this.refreshingTokensPromise;
   }
   async stamp(params: { data: Buffer; type?: "PKI" } | { data: Buffer; type: "OIDC" }): Promise<string> {
+    this.refreshConfig?.logger?.debug?.("Auth2Stamper.stamp(): called");
+
     if (!this._keyPair || !this._keyInfo) {
       throw new Error("Auth2Stamper not initialized. Call init() first.");
     }
 
+    this.refreshConfig?.logger?.debug?.("Auth2Stamper.stamp(): awaiting maybeRefreshTokens()");
     await this.maybeRefreshTokens();
+    this.refreshConfig?.logger?.debug?.("Auth2Stamper.stamp(): maybeRefreshTokens() completed");
 
     if (!this.auth2Token) {
       throw new Error("Auth2Stamper not initialized. Call init() first.");

packages/auth2/src/index.ts

@@ -1,5 +1,5 @@
 export { Auth2KmsRpcClient, type Auth2KmsClientOptions } from "./Auth2KmsRpcClient";
-export { Auth2Stamper, type Auth2StamperRefreshConfig } from "./Auth2Stamper";
+export { Auth2Stamper, type Auth2StamperRefreshConfig, type Auth2Logger } from "./Auth2Stamper";
 export type { Auth2StamperStorage, Auth2StamperStoredRecord } from "./Auth2StamperStorage";
 export { Auth2Token, Auth2TokenExpiredError, decodeJwtClaims } from "./Auth2Token";
 export { exchangeAuthCode, refreshToken } from "./tokenExchange";

packages/auth2/src/tokenExchange.ts

@@ -39,15 +39,17 @@ export async function refreshToken(options: {
   redirectUri: string;
   refreshToken: string;
 }): Promise<TokenExchangeResult<"refresh_token">> {
-  const result = await _postTokenRequest(
-    options.authApiBaseUrl,
-    new URLSearchParams({
-      grant_type: "refresh_token",
-      client_id: options.clientId,
-      redirect_uri: options.redirectUri,
-      refresh_token: options.refreshToken,
-    }),
-  );
+  const params = new URLSearchParams({
+    grant_type: "refresh_token",
+    client_id: options.clientId,
+    refresh_token: options.refreshToken,
+  });
+
+  if (options.redirectUri.trim().length > 0) {
+    params.set("redirect_uri", options.redirectUri);
+  }
+
+  const result = await _postTokenRequest(options.authApiBaseUrl, params);
   if (!result.refreshToken) {
     throw new Error("Auth2 refresh token request did not return a refresh_token.");
   }

packages/mcp-server/package.json

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

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

@@ -334,4 +334,37 @@ describe("DCRClient", () => {
       }
     });
   });
+
+  describe("registerForDeviceFlow", () => {
+    beforeEach(() => {
+      dcrClient = new DCRClient("https://auth.phantom.app", "phantom-mcp");
+    });
+
+    it("registers a public device-flow client with a wallet-tag audience matching its client_id", async () => {
+      const mockResponse = {
+        data: {
+          client_id: "test-device-client-id",
+          client_secret: "",
+          client_id_issued_at: 1234567890,
+        },
+      };
+
+      mockedAxios.post.mockResolvedValueOnce(mockResponse);
+
+      await dcrClient.registerForDeviceFlow();
+
+      const callArgs = mockedAxios.post.mock.calls[0];
+      const payload = callArgs[1] as {
+        client_id: string;
+        audience: string[];
+        grant_types: string[];
+        token_endpoint_auth_method: string;
+      };
+
+      expect(payload.client_id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+      expect(payload.audience).toEqual([`urn:phantom:wallet-tag:${payload.client_id}`]);
+      expect(payload.grant_types).toEqual(["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"]);
+      expect(payload.token_endpoint_auth_method).toBe("none");
+    });
+  });
 });

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

@@ -4,19 +4,22 @@
  */
 
 import axios, { type AxiosError } from "axios";
+import { randomUUID } from "crypto";
 import { Logger } from "../utils/logger";
 import type { DCRClientConfig } from "../session/types";
 
 /**
  * RFC 7591 Dynamic Client Registration request payload
  */
 interface DCRRegistrationRequest {
+  client_id?: string;
   client_name: string;
   redirect_uris: string[];
   grant_types: string[];
   response_types: string[];
   application_type: string;
   token_endpoint_auth_method: string;
+  audience?: string[];
   scope?: string;
 }
 
@@ -91,13 +94,16 @@ export class DCRClient {
   async registerForDeviceFlow(): Promise<DCRClientConfig> {
     const registrationEndpoint = `${this.authBaseUrl}/oauth2/register`;
     const clientName = `${this.appId}-${Date.now()}`;
+    const clientId = randomUUID();
 
     const payload: DCRRegistrationRequest = {
+      client_id: clientId,
       client_name: clientName,
       redirect_uris: [],
       grant_types: ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"],
       response_types: [],
       application_type: "native",
+      audience: [`urn:phantom:wallet-tag:${clientId}`],
       // Device flow clients are public per RFC 8628 — no client secret
       token_endpoint_auth_method: "none",
       scope: "openid offline_access",

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

@@ -186,11 +186,15 @@ describe("SessionManager", () => {
     const manager = new SessionManager({ authFlow: "device-code" });
     await manager.initialize();
 
-    expect(Auth2Stamper).toHaveBeenCalledWith(expect.anything(), {
-      authApiBaseUrl: "https://auth.phantom.app",
-      clientId: "phantom-mcp",
-      redirectUri: "",
-    });
+    expect(Auth2Stamper).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        authApiBaseUrl: "https://auth.phantom.app",
+        clientId: "phantom-mcp",
+        redirectUri: "",
+        logger: expect.anything(),
+      }),
+    );
     expect(DeviceCodeAuthProvider).toHaveBeenCalledWith(
       expect.anything(),
       {

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

@@ -258,7 +258,7 @@ export class SessionManager {
       return Promise.resolve(false);
     }
     this.logger.info("tryRefreshSession: attempting stamper token refresh");
-    return this.stamper.maybeRefreshTokens().then(result => {
+    return this.stamper.maybeRefreshTokens().then((result: boolean) => {
       this.logger.info(`tryRefreshSession: refresh ${result ? "succeeded" : "did not run or failed"}`);
       return result;
     });
@@ -343,6 +343,7 @@ export class SessionManager {
       authApiBaseUrl: this.authBaseUrl,
       clientId: this.resolveAppId(),
       redirectUri: "",
+      logger: this.logger.child("Auth2Stamper"),
     });
     const deviceFlow = new DeviceCodeAuthProvider(
       stamper,
@@ -447,6 +448,7 @@ export class SessionManager {
       authApiBaseUrl: this.authBaseUrl,
       clientId: session.appId ?? appId,
       redirectUri: "",
+      logger: this.logger.child("Auth2Stamper"),
     });
     await stamper.init();
     this.stamper = stamper;

packages/phantom-openclaw-plugin/README.md

@@ -92,27 +92,6 @@ Supported optional config keys mirror the MCP server environment surface used by
 - **`PHANTOM_VERSION`**: Optional version header override
 - **`PHANTOM_MCP_DEBUG`**: Enable debug logging (set to `"1"` or `"true"`)
 
-Example staging config:
-
-```json
-{
-  "plugins": {
-    "enabled": true,
-    "entries": {
-      "phantom-openclaw-plugin": {
-        "enabled": true,
-        "config": {
-          "PHANTOM_AUTH_BASE_URL": "https://staging-auth.phantom.app",
-          "PHANTOM_CONNECT_BASE_URL": "https://staging-connect.phantom.app",
-          "PHANTOM_WALLETS_API_BASE_URL": "https://staging-api.phantom.app/v1/wallets",
-          "PHANTOM_API_BASE_URL": "https://staging-api.phantom.app"
-        }
-      }
-    }
-  }
-}
-```
-
 ## Available Tools
 
 The plugin exposes the following tools from the Phantom MCP Server:

packages/phantom-openclaw-plugin/package.json

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