Authentication

/**
 * Interface for request authentication handlers
 */
interface RequestHandler {
  /**
   * Prepare request by adding authentication headers
   * @param options - HTTP request options to modify
   */
  prepareRequest(options: http.RequestOptions): void;
  
  /**
   * Check if handler can handle authentication challenge
   * @param response - HTTP response to examine
   * @returns True if handler can handle the authentication challenge
   */
  canHandleAuthentication(response: HttpClientResponse): boolean;
  
  /**
   * Handle authentication challenge by retrying request
   * @param httpClient - HTTP client instance
   * @param requestInfo - Original request information
   * @param data - Original request data
   * @returns Promise resolving to authenticated response
   */
  handleAuthentication(
    httpClient: HttpClient,
    requestInfo: RequestInfo,
    data: string | NodeJS.ReadableStream | null
  ): Promise<HttpClientResponse>;
}

/**
 * Basic authentication handler using username/password
 * Adds Authorization header with Base64-encoded credentials
 */
class BasicCredentialHandler implements RequestHandler {
  /**
   * Create Basic authentication handler
   * @param username - Username for authentication
   * @param password - Password for authentication
   */
  constructor(username: string, password: string);
  
  /** Username for authentication */
  username: string;
  
  /** Password for authentication */
  password: string;
  
  /**
   * Add Basic authentication header to request
   * @param options - HTTP request options to modify
   */
  prepareRequest(options: http.RequestOptions): void;
  
  /**
   * Basic handler cannot handle authentication challenges
   * @returns Always false
   */
  canHandleAuthentication(): boolean;
  
  /**
   * Not implemented for Basic authentication
   * @throws Error indicating not implemented
   */
  handleAuthentication(): Promise<HttpClientResponse>;
}

/**
 * Bearer token authentication handler
 * Adds Authorization header with Bearer token
 */
class BearerCredentialHandler implements RequestHandler {
  /**
   * Create Bearer token authentication handler
   * @param token - Bearer token for authentication
   */
  constructor(token: string);
  
  /** Bearer token for authentication */
  token: string;
  
  /**
   * Add Bearer authentication header to request
   * @param options - HTTP request options to modify
   */
  prepareRequest(options: http.RequestOptions): void;
  
  /**
   * Bearer handler cannot handle authentication challenges
   * @returns Always false
   */
  canHandleAuthentication(): boolean;
  
  /**
   * Not implemented for Bearer authentication
   * @throws Error indicating not implemented
   */
  handleAuthentication(): Promise<HttpClientResponse>;
}

/**
 * Personal Access Token authentication handler
 * Adds Authorization header with PAT in Basic auth format
 */
class PersonalAccessTokenCredentialHandler implements RequestHandler {
  /**
   * Create PAT authentication handler
   * @param token - Personal access token for authentication
   */
  constructor(token: string);
  
  /** Personal access token for authentication */
  token: string;
  
  /**
   * Add PAT authentication header to request (uses Basic auth with "PAT" as username)
   * @param options - HTTP request options to modify
   */
  prepareRequest(options: http.RequestOptions): void;
  
  /**
   * PAT handler cannot handle authentication challenges
   * @returns Always false
   */
  canHandleAuthentication(): boolean;
  
  /**
   * Not implemented for PAT authentication
   * @throws Error indicating not implemented
   */
  handleAuthentication(): Promise<HttpClientResponse>;
}

import { HttpClient } from "@actions/http-client";
import { 
  BasicCredentialHandler, 
  BearerCredentialHandler, 
  PersonalAccessTokenCredentialHandler 
} from "@actions/http-client/lib/auth";

// Basic authentication
const basicAuth = new BasicCredentialHandler("username", "password");
const basicClient = new HttpClient("my-action/1.0", [basicAuth]);

const response1 = await basicClient.get("https://api.example.com/protected");
// Automatically adds: Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

// Bearer token authentication
const bearerAuth = new BearerCredentialHandler("your-oauth-token");
const bearerClient = new HttpClient("my-action/1.0", [bearerAuth]);

const response2 = await bearerClient.get("https://api.example.com/oauth/user");
// Automatically adds: Authorization: Bearer your-oauth-token

// GitHub Personal Access Token
const patAuth = new PersonalAccessTokenCredentialHandler("ghp_1234567890abcdef");
const githubClient = new HttpClient("my-action/1.0", [patAuth]);

const response3 = await githubClient.get("https://api.github.com/user");
// Automatically adds: Authorization: Basic UEFUOmdocF8xMjM0NTY3ODkwYWJjZGVm

// Multiple handlers (tried in order)
const multiClient = new HttpClient("my-action/1.0", [
  patAuth,
  bearerAuth,
  basicAuth
]);

// From environment variables
const githubToken = process.env.GITHUB_TOKEN;
if (githubToken) {
  const auth = new PersonalAccessTokenCredentialHandler(githubToken);
  const client = new HttpClient("github-action/1.0", [auth]);
  
  const repos = await client.getJson("https://api.github.com/user/repos");
  console.log(`Found ${repos.result?.length} repositories`);
}

// Manual header vs handler comparison
// Manual approach:
const manualClient = new HttpClient("my-action/1.0");
const manualResponse = await manualClient.get("https://api.github.com/user", {
  "Authorization": `token ${process.env.GITHUB_TOKEN}`
});

// Handler approach (recommended):
const handlerAuth = new PersonalAccessTokenCredentialHandler(process.env.GITHUB_TOKEN!);
const handlerClient = new HttpClient("my-action/1.0", [handlerAuth]);
const handlerResponse = await handlerClient.get("https://api.github.com/user");
// Handlers are reused across all requests automatically