Authentication

/**
 * Enhanced authentication class extending GoogleAuth with memoization and static references
 */
class AuthPlus extends GoogleAuth {
  /** Static reference to JWT class for direct instantiation */
  JWT: typeof JWT;
  /** Static reference to Compute class for direct instantiation */
  Compute: typeof Compute;
  /** Static reference to OAuth2Client class for direct instantiation */
  OAuth2: typeof OAuth2Client;
  /** Static reference to GoogleAuth class for direct instantiation */
  GoogleAuth: typeof GoogleAuth;
  /** Static reference to AwsClient class for direct instantiation */
  AwsClient: typeof AwsClient;
  /** Static reference to IdentityPoolClient class for direct instantiation */
  IdentityPoolClient: typeof IdentityPoolClient;
  /** Static reference to ExternalAccountClient class for direct instantiation */
  ExternalAccountClient: typeof ExternalAccountClient;

  /**
   * Override getClient(), memoizing an instance of auth for subsequent calls to getProjectId()
   * @param options - GoogleAuth options for client configuration
   * @returns Promise resolving to an authenticated client instance
   */
  getClient(options?: GoogleAuthOptions): Promise<
    Compute | JWT | UserRefreshClient | BaseExternalAccountClient | Impersonated
  >;

  /**
   * Override getProjectId(), using the most recently configured auth instance when fetching projectId
   * @returns Promise resolving to the project ID string
   */
  getProjectId(): Promise<string>;

  /**
   * Override getProjectId() with callback, using the most recently configured auth instance
   * @param callback - Callback function to receive project ID or error
   */
  getProjectId(callback: ProjectIdCallback): void;
}

import { AuthPlus } from "googleapis-common";

// Create enhanced auth instance
const auth = new AuthPlus({
  scopes: ['https://www.googleapis.com/auth/cloud-platform'],
  keyFile: 'path/to/service-account.json'
});

// Get authenticated client (memoized)
const client = await auth.getClient();

// Get project ID using memoized auth
const projectId = await auth.getProjectId();

// Access static references for direct instantiation
const jwt = new auth.JWT({
  email: 'service-account@project.iam.gserviceaccount.com',
  key: privateKey,
  scopes: ['https://www.googleapis.com/auth/cloud-platform']
});

const oauth2 = new auth.OAuth2(clientId, clientSecret, redirectUri);

/**
 * OAuth2 client for three-legged OAuth2 flows
 */
class OAuth2Client extends import('google-auth-library').OAuth2Client {
  constructor(clientId?: string, clientSecret?: string, redirectUri?: string);
  generateAuthUrl(opts: GenerateAuthUrlOpts): string;
  getToken(code: string): Promise<{tokens: Credentials}>;
  setCredentials(credentials: Credentials): void;
  refreshAccessToken(): Promise<{credentials: Credentials}>;
}

/**
 * JWT (JSON Web Token) client for service account authentication
 */
class JWT extends import('google-auth-library').JWT {
  constructor(options: JWTOptions);
  authorize(): Promise<{access_token: string}>;
  createScoped(scopes: string | string[]): JWT;
}

/**
 * Compute Engine metadata service client for VM authentication
 */
class Compute extends import('google-auth-library').Compute {
  constructor(options?: ComputeOptions);
  getProjectId(): Promise<string>;
  getToken(): Promise<{access_token: string}>;
}

/**
 * User refresh client for OAuth2 refresh tokens
 */
class UserRefreshClient extends import('google-auth-library').UserRefreshClient {
  constructor(clientId?: string, clientSecret?: string, refreshToken?: string);
  refreshAccessToken(): Promise<{credentials: Credentials}>;
}

/**
 * Main authentication class with automatic credential detection
 */
class GoogleAuth extends import('google-auth-library').GoogleAuth {
  constructor(options?: GoogleAuthOptions);
  getClient(): Promise<AuthClient>;
  getApplicationDefault(): Promise<AuthClient>;
  getProjectId(): Promise<string>;
}

/**
 * Base class for external account clients (AWS, Azure, etc.)
 */
class BaseExternalAccountClient extends import('google-auth-library').BaseExternalAccountClient {
  retrieveSubjectToken(): Promise<string>;
  getAccessToken(): Promise<{token?: string | null}>;
}

/**
 * External account client for workload identity federation
 */
class ExternalAccountClient extends import('google-auth-library').ExternalAccountClient {
  constructor(options: ExternalAccountClientOptions);
}

/**
 * Identity pool client for workload identity federation with identity pools
 */
class IdentityPoolClient extends import('google-auth-library').IdentityPoolClient {
  constructor(options: IdentityPoolClientOptions);
}

/**
 * AWS client for workload identity federation with AWS
 */
class AwsClient extends import('google-auth-library').AwsClient {
  constructor(options: AwsClientOptions);
}

/**
 * Options for GoogleAuth constructor
 */
interface GoogleAuthOptions {
  scopes?: string | string[];
  keyFile?: string;
  keyFilename?: string;
  credentials?: object;
  projectId?: string;
  clientOptions?: {
    [key: string]: any;
  };
}

/**
 * Authentication credentials object
 */
interface Credentials {
  access_token?: string | null;
  refresh_token?: string | null;
  id_token?: string | null;
  token_type?: string | null;
  expiry_date?: number | null;
}

/**
 * JWT authentication options
 */
interface JWTOptions {
  email?: string;
  keyFile?: string;
  key?: string;
  keyId?: string;
  scopes?: string | string[];
  subject?: string;
  additionalClaims?: object;
}

/**
 * Project ID callback function type
 */
type ProjectIdCallback = (err: Error | null, projectId?: string | null) => void;

/**
 * General authentication client type
 */
type AuthClient = OAuth2Client | JWT | Compute | UserRefreshClient | BaseExternalAccountClient;