Authentication adjustments for JB integration (#350)

Updated authentication methods for IDEA compatibility and SDK compliance

#### New authentication type: gateway (url + custom headers)
 
- Required to support native IDEA authentication flows
 
#### Process argument to hide Claude Code authentication

- Ensures compliance with Anthropic’s third-party authentication
policies.

https://platform.claude.com/docs/en/agent-sdk/overview

> Unless previously approved, Anthropic does not allow third party
developers to offer claude.ai login or rate limits for their products,
including agents built on the Claude Agent SDK. Please use the API key
authentication methods described in this document instead.

---------

Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>

Author: AlexandrSuhinin

src/acp-agent.ts

@@ -2,6 +2,7 @@ import {
   Agent,
   AgentSideConnection,
   AuthenticateRequest,
+  AuthMethod,
   AvailableCommand,
   CancelNotification,
   ClientCapabilities,
@@ -152,6 +153,34 @@ export type NewSessionMeta = {
   };
 };
 
+/**
+ * Extended ClientCapabilities with `auth` field.
+ * TODO: Remove once `auth` is added to the ACP SDK schema.
+ */
+type ClientCapabilitiesWithAuth = ClientCapabilities & {
+  auth?: {
+    _meta?: {
+      gateway?: boolean;
+    };
+  };
+};
+
+/**
+ * Extra metadata for 'gateway' authentication requests.
+ */
+type GatewayAuthMeta = {
+  /**
+   * These parameters are mapped to environment variables to:
+   * - Redirect API calls via baseUrl
+   * - Inject custom headers
+   * - Bypass the default Claude login requirement
+   */
+  gateway: {
+    baseUrl: string;
+    headers: Record<string, string>;
+  };
+};
+
 /**
  * Extra metadata that the agent provides for each tool_call / tool_update update.
  */
@@ -190,6 +219,10 @@ function isStaticBinary(): boolean {
   return process.env.CLAUDE_AGENT_ACP_IS_SINGLE_FILE_BUN !== undefined;
 }
 
+function shouldHideClaudeAuth(): boolean {
+  return process.argv.includes("--hide-claude-auth");
+}
+
 // Bypass Permissions doesn't work if we are a root/sudo user
 const IS_ROOT = (process.geteuid?.() ?? process.getuid?.()) === 0;
 const ALLOW_BYPASS = !IS_ROOT || !!process.env.IS_SANDBOX;
@@ -241,6 +274,7 @@ export class ClaudeAcpAgent implements Agent {
   backgroundTerminals: { [key: string]: BackgroundTerminal } = {};
   clientCapabilities?: ClientCapabilities;
   logger: Logger;
+  gatewayAuthMeta?: GatewayAuthMeta;
 
   constructor(client: AgentSideConnection, logger?: Logger) {
     this.sessions = {};
@@ -259,8 +293,25 @@ export class ClaudeAcpAgent implements Agent {
       id: "claude-login",
     };
 
+    // Bypasses standard auth by routing requests through a custom Anthropic-protocol gateway.
+    // Only offered when the client advertises `auth._meta.gateway` capability.
+    const clientCaps = request.clientCapabilities as ClientCapabilitiesWithAuth | undefined;
+    const supportsGatewayAuth = clientCaps?.auth?._meta?.gateway === true;
+
+    const gatewayAuthMethod: AuthMethod = {
+      id: "gateway",
+      name: "Custom model gateway",
+      description: "Use a custom gateway to authenticate and access models",
+      _meta: {
+        gateway: {
+          protocol: "anthropic",
+        },
+      },
+    };
+
     // If client supports terminal-auth capability, use that instead.
-    if (request.clientCapabilities?._meta?.["terminal-auth"] === true) {
+    const supportsTerminalAuth = request.clientCapabilities?._meta?.["terminal-auth"] === true;
+    if (supportsTerminalAuth) {
       let command: string;
       let args: string[];
 
@@ -310,12 +361,17 @@ export class ClaudeAcpAgent implements Agent {
         title: "Claude Agent",
         version: packageJson.version,
       },
-      authMethods: [authMethod],
+      authMethods: [
+        // Terminal auth can also be used for API keys, so don't gate it on --hide-claude-auth.
+        ...(shouldHideClaudeAuth() && !supportsTerminalAuth ? [] : [authMethod]),
+        ...(supportsGatewayAuth ? [gatewayAuthMethod] : []),
+      ],
     };
   }
 
   async newSession(params: NewSessionRequest): Promise<NewSessionResponse> {
     if (
+      !this.gatewayAuthMeta &&
       fs.existsSync(path.resolve(os.homedir(), ".claude.json.backup")) &&
       !fs.existsSync(path.resolve(os.homedir(), ".claude.json"))
     ) {
@@ -415,6 +471,10 @@ export class ClaudeAcpAgent implements Agent {
   }
 
   async authenticate(_params: AuthenticateRequest): Promise<void> {
+    if (_params.methodId === "gateway") {
+      this.gatewayAuthMeta = _params._meta as GatewayAuthMeta | undefined;
+      return;
+    }
     throw new Error("Method not implemented.");
   }
 
@@ -1179,6 +1239,10 @@ export class ClaudeAcpAgent implements Agent {
       settingSources: ["user", "project", "local"],
       ...(maxThinkingTokens !== undefined && { maxThinkingTokens }),
       ...userProvidedOptions,
+      env: {
+        ...userProvidedOptions?.env,
+        ...createEnvForGateway(this.gatewayAuthMeta),
+      },
       // Override certain fields that must be controlled by ACP
       cwd: params.cwd,
       includePartialMessages: true,
@@ -1262,6 +1326,13 @@ export class ClaudeAcpAgent implements Agent {
       throw error;
     }
 
+    if (shouldHideClaudeAuth() && initializationResult.account.subscriptionType) {
+      throw RequestError.authRequired(
+        undefined,
+        "This integration does not support using claude.ai subscriptions.",
+      );
+    }
+
     const models = await getAvailableModels(q, initializationResult.models, settingsManager);
 
     const availableModes = [
@@ -1329,6 +1400,19 @@ export class ClaudeAcpAgent implements Agent {
   }
 }
 
+function createEnvForGateway(gatewayMeta?: GatewayAuthMeta) {
+  if (!gatewayMeta) {
+    return {};
+  }
+  return {
+    ANTHROPIC_BASE_URL: gatewayMeta.gateway.baseUrl,
+    ANTHROPIC_CUSTOM_HEADERS: Object.entries(gatewayMeta.gateway.headers)
+      .map(([key, value]) => `${key}: ${value}`)
+      .join("\n"),
+    ANTHROPIC_AUTH_TOKEN: "", // Must be specified to bypass claude login requirement
+  };
+}
+
 function buildConfigOptions(
   modes: SessionModeState,
   models: SessionModelState,

src/tests/authorization.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, it, Mock, vi, afterEach, beforeEach } from "vitest";
+import { ClaudeAcpAgent } from "../acp-agent.js";
+import { AgentSideConnection } from "@agentclientprotocol/sdk";
+
+describe("authorization", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    //await all pending events like
+    vi.runAllTimers();
+    vi.useRealTimers();
+
+    vi.unstubAllGlobals();
+    vi.resetAllMocks();
+  });
+
+  async function createAgentMock(): Promise<[ClaudeAcpAgent, Mock]> {
+    const mockQuery = vi.hoisted(() =>
+      vi.fn(() => ({
+        initializationResult: vi.fn().mockResolvedValue({
+          models: [{ value: "id", displayName: "name", description: "description" }],
+        }),
+        setModel: vi.fn(),
+        supportedCommands: vi.fn().mockResolvedValue([]),
+      })),
+    );
+
+    vi.mock("@anthropic-ai/claude-agent-sdk", () => ({
+      query: mockQuery,
+    }));
+
+    const connectionMock = {
+      sessionUpdate: async (_: any) => {},
+    } as AgentSideConnection;
+
+    const agent = new ClaudeAcpAgent(connectionMock);
+
+    return [agent, mockQuery];
+  }
+
+  it("gateway auth not offered without capability", async () => {
+    const [agent] = await createAgentMock();
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {},
+    });
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "gateway" }),
+    );
+  });
+
+  it("gateway auth offered when client advertises auth._meta.gateway capability", async () => {
+    const [agent] = await createAgentMock();
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        auth: { _meta: { gateway: true } },
+      } as any,
+    });
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "gateway" }),
+    );
+  });
+
+  it("uses gateway env after gateway auth", async () => {
+    const [agent, mockQuery] = await createAgentMock();
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        auth: { _meta: { gateway: true } },
+      } as any,
+    });
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "gateway" }),
+    );
+
+    await agent.authenticate({
+      methodId: "gateway",
+      _meta: { gateway: { baseUrl: "https://gateway.example", headers: { "x-api-key": "test" } } },
+    });
+
+    await agent.newSession({
+      cwd: "testRoot",
+      mcpServers: [],
+      _meta: {
+        claudeCode: {
+          options: {
+            env: {
+              userEnv: "userEnv",
+            },
+          },
+        },
+      },
+    });
+
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.objectContaining({
+        options: expect.objectContaining({
+          env: {
+            ANTHROPIC_AUTH_TOKEN: "",
+            ANTHROPIC_BASE_URL: "https://gateway.example",
+            ANTHROPIC_CUSTOM_HEADERS: "x-api-key: test",
+            userEnv: "userEnv",
+          },
+        }),
+      }),
+    );
+  });
+
+  it("hide claude authentication without terminal-auth", async () => {
+    const [agent] = await createAgentMock();
+    vi.stubGlobal("process", { ...process, argv: ["--hide-claude-auth"] });
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        auth: { _meta: { gateway: true } },
+      } as any,
+    });
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "claude-login" }),
+    );
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "gateway" }),
+    );
+  });
+
+  it("terminal auth still offered when --hide-claude-auth is set", async () => {
+    const [agent] = await createAgentMock();
+    vi.stubGlobal("process", { ...process, argv: ["--hide-claude-auth"] });
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        _meta: { "terminal-auth": true },
+      },
+    });
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "claude-login" }),
+    );
+  });
+
+  it("show claude authentication", async () => {
+    const [agent] = await createAgentMock();
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {},
+    });
+
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "claude-login" }),
+    );
+  });
+});