feat: add auth related base classes

core/src/auth/auth_credential.ts

@@ -26,6 +26,11 @@ export interface HttpAuth {
    */
   scheme: string;
   credentials: HttpCredentials;
+
+  /**
+   * Additional HTTP headers to include in the request.
+   */
+  additionalHeaders?: Record<string, string>;
 }
 
 /**
@@ -133,6 +138,16 @@ export interface ServiceAccount {
   serviceAccountCredential?: ServiceAccountCredential;
   scopes?: string[];
   useDefaultCredential?: boolean;
+
+  /**
+   * If true, get an ID token instead of an access token.
+   */
+  useIdToken?: boolean;
+
+  /**
+   * The audience for the ID token. Required if useIdToken is true.
+   */
+  audience?: string;
 }
 
 /*

core/src/auth/auth_provider_registry.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {AuthScheme} from './auth_schemes.js';
+import {BaseAuthProvider} from './base_auth_provider.js';
+
+/**
+ * Registry for auth provider instances.
+ */
+export class AuthProviderRegistry {
+  private readonly providers = new Map<string, BaseAuthProvider>();
+
+  /**
+   * Register a provider instance for an auth scheme type.
+   *
+   * @param authSchemeType The auth scheme type (e.g., 'oauth2', 'apiKey').
+   * @param providerInstance The provider instance to register.
+   */
+  register(authSchemeType: string, providerInstance: BaseAuthProvider): void {
+    this.providers.set(authSchemeType, providerInstance);
+  }
+
+  /**
+   * Get the provider instance for an auth scheme.
+   *
+   * @param authScheme The auth scheme to get provider for.
+   * @returns The provider instance if registered, undefined otherwise.
+   */
+  getProvider(authScheme: AuthScheme): BaseAuthProvider | undefined {
+    return this.providers.get(authScheme.type);
+  }
+}

core/src/auth/base_auth_provider.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {AuthCredential} from './auth_credential.js';
+import {AuthConfig} from './auth_tool.js';
+
+/**
+ * Abstract base interface for custom authentication providers.
+ */
+export interface BaseAuthProvider {
+  /**
+   * Provide an AuthCredential asynchronously.
+   *
+   * @param authConfig The current authentication configuration.
+   * @param context The current callback context (placeholder).
+   * @returns The retrieved AuthCredential, or undefined if unavailable.
+   */
+  getAuthCredential(
+    authConfig: AuthConfig,
+    context?: unknown,
+  ): Promise<AuthCredential | undefined>;
+}

core/src/auth/credential_service/session_state_credential_service.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {Context} from '../../agents/context.js';
+import {AuthCredential} from '../auth_credential.js';
+import {AuthConfig} from '../auth_tool.js';
+import {BaseCredentialService} from './base_credential_service.js';
+
+/**
+ * Class for implementation of credential service using session state as the store.
+ * Note: store credential in session may not be secure, use at your own risk.
+ */
+export class SessionStateCredentialService implements BaseCredentialService {
+  loadCredential(
+    authConfig: AuthConfig,
+    toolContext: Context,
+  ): Promise<AuthCredential | undefined> {
+    return Promise.resolve(toolContext.state.get(authConfig.credentialKey));
+  }
+
+  async saveCredential(
+    authConfig: AuthConfig,
+    toolContext: Context,
+  ): Promise<void> {
+    if (authConfig.exchangedAuthCredential) {
+      toolContext.state.set(
+        authConfig.credentialKey,
+        authConfig.exchangedAuthCredential,
+      );
+    }
+  }
+}

core/src/auth/exchanger/base_credential_exchanger.ts

@@ -12,6 +12,14 @@ import {AuthScheme} from '../auth_schemes.js';
  */
 export class CredentialExchangeError extends Error {}
 
+/**
+ * Result of a credential exchange.
+ */
+export interface ExchangeResult {
+  credential: AuthCredential;
+  wasExchanged: boolean;
+}
+
 /**
  * Base interface for credential exchangers.
  *
@@ -29,10 +37,10 @@ export interface BaseCredentialExchanger {
    */
 
   exchange({
-    authCredential,
     authScheme,
+    authCredential,
   }: {
-    authCredential: AuthCredential;
     authScheme?: AuthScheme;
-  }): Promise<AuthCredential>;
+    authCredential: AuthCredential;
+  }): Promise<ExchangeResult>;
 }

core/src/auth/refresher/base_credential_refresher.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {AuthCredential} from '../auth_credential.js';
+import {AuthScheme} from '../auth_schemes.js';
+
+/**
+ * Base exception for credential refresh errors.
+ */
+export class CredentialRefresherError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CredentialRefresherError';
+  }
+}
+
+/**
+ * Base interface for credential refreshers.
+ *
+ * Credential refreshers are responsible for checking if a credential is expired
+ * or needs to be refreshed, and for refreshing it if necessary.
+ */
+export interface BaseCredentialRefresher {
+  /**
+   * Checks if a credential needs to be refreshed.
+   *
+   * @param authCredential The credential to check.
+   * @param authScheme The authentication scheme (optional).
+   * @returns True if the credential needs to be refreshed, False otherwise.
+   */
+  isRefreshNeeded(
+    authCredential: AuthCredential,
+    authScheme?: AuthScheme,
+  ): Promise<boolean>;
+
+  /**
+   * Refreshes a credential if needed.
+   *
+   * @param authCredential The credential to refresh.
+   * @param authScheme The authentication scheme (optional).
+   * @returns The refreshed credential.
+   * @throws {CredentialRefresherError} If credential refresh fails.
+   */
+  refresh(
+    authCredential: AuthCredential,
+    authScheme?: AuthScheme,
+  ): Promise<AuthCredential>;
+}

core/src/auth/refresher/credential_refresher_registry.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {AuthCredentialTypes} from '../auth_credential.js';
+import {BaseCredentialRefresher} from './base_credential_refresher.js';
+
+/**
+ * Registry for credential refresher instances.
+ */
+export class CredentialRefresherRegistry {
+  private readonly refreshers: Record<
+    AuthCredentialTypes,
+    BaseCredentialRefresher | undefined
+  > = {
+    [AuthCredentialTypes.API_KEY]: undefined,
+    [AuthCredentialTypes.HTTP]: undefined,
+    [AuthCredentialTypes.OAUTH2]: undefined,
+    [AuthCredentialTypes.OPEN_ID_CONNECT]: undefined,
+    [AuthCredentialTypes.SERVICE_ACCOUNT]: undefined,
+  };
+
+  /**
+   * Register a refresher instance for a credential type.
+   *
+   * @param credentialType The credential type to register for.
+   * @param refresherInstance The refresher instance to register.
+   */
+  register(
+    credentialType: AuthCredentialTypes,
+    refresherInstance: BaseCredentialRefresher,
+  ): void {
+    this.refreshers[credentialType] = refresherInstance;
+  }
+
+  /**
+   * Get the refresher instance for a credential type.
+   *
+   * @param credentialType The credential type to get refresher for.
+   * @returns The refresher instance if registered, undefined otherwise.
+   */
+  getRefresher(
+    credentialType: AuthCredentialTypes,
+  ): BaseCredentialRefresher | undefined {
+    return this.refreshers[credentialType];
+  }
+}

core/src/common.ts

@@ -69,9 +69,17 @@ export type {
   ServiceAccount,
   ServiceAccountCredential,
 } from './auth/auth_credential.js';
+export {AuthHandler} from './auth/auth_handler.js';
+export {AuthProviderRegistry} from './auth/auth_provider_registry.js';
+export {OAuthGrantType} from './auth/auth_schemes.js';
 export type {AuthScheme, OpenIdConnectWithConfig} from './auth/auth_schemes.js';
 export type {AuthConfig} from './auth/auth_tool.js';
+export type {BaseAuthProvider} from './auth/base_auth_provider.js';
 export type {BaseCredentialService} from './auth/credential_service/base_credential_service.js';
+export {InMemoryCredentialService} from './auth/credential_service/in_memory_credential_service.js';
+export {SessionStateCredentialService} from './auth/credential_service/session_state_credential_service.js';
+export type {BaseCredentialRefresher} from './auth/refresher/base_credential_refresher.js';
+export {CredentialRefresherRegistry} from './auth/refresher/credential_refresher_registry.js';
 export {BaseCodeExecutor} from './code_executors/base_code_executor.js';
 export type {ExecuteCodeParams} from './code_executors/base_code_executor.js';
 export {BuiltInCodeExecutor} from './code_executors/built_in_code_executor.js';