@hyperdrive.bot/cli 1.0.2

package/dist/utils/account-flow.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Options for executing the AWS account add flow
+ */
+export interface AccountAddOptions {
+    skipAliasPrompt?: boolean;
+    tenantDomain: string;
+}
+/**
+ * Result of the account add flow
+ */
+export interface AccountResult {
+    accountAlias?: string;
+    accountId?: string;
+    error?: string;
+    quickCreateUrl?: string;
+    roleVerified?: boolean;
+    success: boolean;
+}
+/**
+ * AWS Account add request data
+ */
+export interface AccountAddData {
+    accountId: string;
+    defaultRegion: string;
+    name?: string;
+    roleArn?: string;
+}
+/**
+ * Validate AWS Account ID format
+ */
+export declare function validateAccountId(input: string): boolean | string;
+/**
+ * Prompt user for AWS account details
+ */
+export declare function promptAccountDetails(existingData?: Partial<AccountAddData>): Promise<AccountAddData>;
+/**
+ * Register an AWS account with the API (no user prompts)
+ *
+ * This function is separated from user input collection to allow
+ * proper spinner timing and better separation of concerns.
+ *
+ * @param accountData - Account details to register
+ * @returns AccountResult indicating success or failure
+ */
+export declare function registerAccount(accountData: AccountAddData): Promise<AccountResult>;
+/**
+ * Execute the AWS account add flow
+ *
+ * This function handles:
+ * 1. Prompting for account details (ID, name, region)
+ * 2. Making API call to register the account
+ * 3. Returning result with quickCreateUrl if role needs to be created
+ *
+ * @param options - Configuration options for the account add flow
+ * @returns AccountResult indicating success or failure
+ */
+export declare function executeAccountAdd(options: AccountAddOptions): Promise<AccountResult>;
+/**
+ * Open CloudFormation URL in browser for role creation
+ *
+ * Validates URL is an AWS domain before opening to prevent opening malicious URLs
+ */
+export declare function openCloudFormationUrl(quickCreateUrl: string): Promise<void>;
+/**
+ * Prompt user to open CloudFormation URL
+ */
+export declare function promptOpenCloudFormation(quickCreateUrl: string): Promise<boolean>;
+/**
+ * Wait for role verification with polling
+ */
+export declare function waitForRoleVerification(accountId: string, onProgress?: (message: string) => void): Promise<{
+    message?: string;
+    verified: boolean;
+}>;

package/dist/utils/account-flow.js

@@ -0,0 +1,228 @@
+import inquirer from 'inquirer';
+import open from 'open';
+import { HyperdriveSigV4Service } from '../services/hyperdrive-sigv4.js';
+/**
+ * Comprehensive list of AWS regions
+ * Updated to include all major commercial regions as of 2025
+ */
+const AWS_REGIONS = [
+    // US Regions
+    'us-east-1', // N. Virginia
+    'us-east-2', // Ohio
+    'us-west-1', // N. California
+    'us-west-2', // Oregon
+    // South America
+    'sa-east-1', // São Paulo
+    // Europe
+    'eu-west-1', // Ireland
+    'eu-west-2', // London
+    'eu-west-3', // Paris
+    'eu-central-1', // Frankfurt
+    'eu-central-2', // Zurich
+    'eu-north-1', // Stockholm
+    'eu-south-1', // Milan
+    'eu-south-2', // Spain
+    // Asia Pacific
+    'ap-northeast-1', // Tokyo
+    'ap-northeast-2', // Seoul
+    'ap-northeast-3', // Osaka
+    'ap-southeast-1', // Singapore
+    'ap-southeast-2', // Sydney
+    'ap-southeast-3', // Jakarta
+    'ap-southeast-4', // Melbourne
+    'ap-south-1', // Mumbai
+    'ap-south-2', // Hyderabad
+    'ap-east-1', // Hong Kong
+    // Middle East
+    'me-south-1', // Bahrain
+    'me-central-1', // UAE
+    // Africa
+    'af-south-1', // Cape Town
+    // Canada
+    'ca-central-1', // Canada (Central)
+    'ca-west-1', // Canada West (Calgary)
+];
+/**
+ * Validate AWS Account ID format
+ */
+export function validateAccountId(input) {
+    if (!/^\d{12}$/.test(input)) {
+        return 'AWS Account ID must be exactly 12 digits';
+    }
+    return true;
+}
+/**
+ * Prompt user for AWS account details
+ */
+export async function promptAccountDetails(existingData) {
+    // Prompts array - using any[] due to complex inquirer types, but validated by inquirer.prompt()
+    const prompts = [];
+    if (!existingData?.accountId) {
+        prompts.push({
+            message: 'Enter the AWS Account ID (12 digits):',
+            name: 'accountId',
+            type: 'input',
+            validate: validateAccountId,
+        });
+    }
+    if (!existingData?.name) {
+        prompts.push({
+            default: 'Production',
+            message: 'Enter a friendly name for this account (optional):',
+            name: 'name',
+            type: 'input',
+        });
+    }
+    if (!existingData?.defaultRegion) {
+        prompts.push({
+            choices: AWS_REGIONS,
+            default: 'us-east-1',
+            message: 'Select the default AWS region:',
+            name: 'defaultRegion',
+            type: 'list',
+        });
+    }
+    if (prompts.length === 0) {
+        return existingData;
+    }
+    const responses = await inquirer.prompt(prompts);
+    return { ...existingData, ...responses };
+}
+/**
+ * Register an AWS account with the API (no user prompts)
+ *
+ * This function is separated from user input collection to allow
+ * proper spinner timing and better separation of concerns.
+ *
+ * @param accountData - Account details to register
+ * @returns AccountResult indicating success or failure
+ */
+export async function registerAccount(accountData) {
+    try {
+        // Initialize API service
+        const service = new HyperdriveSigV4Service();
+        // Make API call to add account
+        const result = await service.accountAdd({
+            accountId: accountData.accountId,
+            defaultRegion: accountData.defaultRegion,
+            name: accountData.name,
+            roleArn: accountData.roleArn,
+        });
+        return {
+            accountAlias: result.name,
+            accountId: result.accountId,
+            quickCreateUrl: result.quickCreateUrl,
+            roleVerified: result.roleVerified,
+            success: true,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            error: errorMessage,
+            success: false,
+        };
+    }
+}
+/**
+ * Execute the AWS account add flow
+ *
+ * This function handles:
+ * 1. Prompting for account details (ID, name, region)
+ * 2. Making API call to register the account
+ * 3. Returning result with quickCreateUrl if role needs to be created
+ *
+ * @param options - Configuration options for the account add flow
+ * @returns AccountResult indicating success or failure
+ */
+export async function executeAccountAdd(options) {
+    try {
+        // Step 1: Prompt for account details (no spinner - user needs to see prompts)
+        const accountData = await promptAccountDetails();
+        // Step 2: Register account with API (caller should wrap this with spinner)
+        return await registerAccount(accountData);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            error: errorMessage,
+            success: false,
+        };
+    }
+}
+/**
+ * Open CloudFormation URL in browser for role creation
+ *
+ * Validates URL is an AWS domain before opening to prevent opening malicious URLs
+ */
+export async function openCloudFormationUrl(quickCreateUrl) {
+    try {
+        // Validate URL is from AWS before opening
+        const url = new URL(quickCreateUrl);
+        const validDomains = ['console.aws.amazon.com', 'us-east-1.console.aws.amazon.com'];
+        const isAwsDomain = validDomains.some(domain => url.hostname === domain || url.hostname.endsWith('.console.aws.amazon.com'));
+        if (!isAwsDomain) {
+            throw new Error(`Invalid CloudFormation URL: ${quickCreateUrl}. Expected AWS console domain.`);
+        }
+        await open(quickCreateUrl);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`Failed to open browser: ${error.message}`);
+        }
+        throw new Error('Failed to open browser for CloudFormation stack creation');
+    }
+}
+/**
+ * Prompt user to open CloudFormation URL
+ */
+export async function promptOpenCloudFormation(quickCreateUrl) {
+    const { openBrowser } = await inquirer.prompt([{
+            default: true,
+            message: 'Open CloudFormation in browser to create the cross-account role?',
+            name: 'openBrowser',
+            type: 'confirm',
+        }]);
+    return openBrowser;
+}
+const VERIFY_POLL_INTERVAL = 5000; // 5 seconds
+const VERIFY_TIMEOUT = 300000; // 5 minutes
+/**
+ * Wait for role verification with polling
+ */
+export async function waitForRoleVerification(accountId, onProgress) {
+    const service = new HyperdriveSigV4Service();
+    const startTime = Date.now();
+    let attemptCount = 0;
+    while (Date.now() - startTime < VERIFY_TIMEOUT) {
+        attemptCount++;
+        const elapsed = Math.floor((Date.now() - startTime) / 1000);
+        try {
+            if (onProgress) {
+                onProgress(`Verifying role... (attempt ${attemptCount}, ${elapsed}s elapsed)`);
+            }
+            const result = await service.accountVerify({ accountId });
+            if (result.verified) {
+                return { message: 'Cross-account role verified successfully', verified: true };
+            }
+            // Role exists but not verified yet
+            if (onProgress) {
+                onProgress(`Role not ready yet: ${result.message || 'waiting...'} (attempt ${attemptCount}, ${elapsed}s)`);
+            }
+        }
+        catch (error) {
+            // API error - role not ready yet, continue polling
+            const errorMessage = error instanceof Error ? error.message : 'unknown error';
+            if (onProgress) {
+                onProgress(`Checking role... ${errorMessage} (attempt ${attemptCount}, ${elapsed}s)`);
+            }
+        }
+        // Wait before next poll
+        await new Promise(resolve => setTimeout(resolve, VERIFY_POLL_INTERVAL));
+    }
+    // Timeout reached
+    return {
+        message: `Verification timed out after ${VERIFY_TIMEOUT / 1000} seconds`,
+        verified: false,
+    };
+}

package/dist/utils/auth-flow.d.ts

@@ -0,0 +1,146 @@
+import { TenantConfig } from '../services/tenant-service.js';
+/**
+ * Options for executing the OAuth PKCE authentication flow
+ */
+export interface AuthFlowOptions {
+    callbackPort?: number;
+    logger?: (message: string) => void;
+    tenantDomain: string;
+    timeout?: number;
+}
+/**
+ * Result of the authentication flow
+ */
+export interface AuthResult {
+    error?: string;
+    skipped?: boolean;
+    success: boolean;
+}
+/**
+ * Cognito tokens received from OAuth token exchange
+ */
+export interface CognitoTokens {
+    access_token: string;
+    expires_in: number;
+    id_token: string;
+    refresh_token: string;
+    token_type: string;
+}
+/**
+ * AWS credentials obtained from Cognito Identity Pool
+ */
+export interface AWSCredentials {
+    accessKeyId: string;
+    expiration: Date;
+    secretAccessKey: string;
+    sessionToken: string;
+}
+/**
+ * Cognito configuration for storing with credentials
+ */
+export interface CognitoConfig {
+    clientId: string;
+    domain: string;
+    identityPoolId: string;
+    userPoolId: string;
+}
+/**
+ * Complete stored credentials including tokens and AWS credentials
+ */
+export interface StoredCredentials extends CognitoTokens {
+    apiUrl: string;
+    awsCredentials: AWSCredentials;
+    cognitoConfig: CognitoConfig;
+    obtainedAt: string;
+    region: string;
+    tenantDomain: string;
+    tenantId: string;
+}
+/**
+ * Generate PKCE code verifier (random base64url string)
+ */
+export declare function generateCodeVerifier(): string;
+/**
+ * Generate PKCE code challenge (SHA256 hash of verifier)
+ */
+export declare function generateCodeChallenge(verifier: string): string;
+/**
+ * Build Cognito authorization URL with PKCE parameters
+ */
+export declare function buildAuthUrl(tenantConfig: TenantConfig, codeChallenge: string, port: number): string;
+/**
+ * Start local HTTP server to receive OAuth callback
+ * Returns a promise that resolves with the authorization code
+ */
+export declare function startCallbackServer(port: number, timeout: number): Promise<string>;
+/**
+ * Exchange authorization code for Cognito tokens
+ */
+export declare function exchangeCodeForTokens(tenantConfig: TenantConfig, code: string, codeVerifier: string, port: number): Promise<CognitoTokens>;
+/**
+ * Get AWS credentials from Cognito Identity Pool
+ */
+export declare function getAWSCredentials(tenantConfig: TenantConfig, idToken: string): Promise<AWSCredentials>;
+/**
+ * Save credentials to domain-specific path (always required)
+ */
+export declare function saveCredentials(credentials: StoredCredentials, domain: string): void;
+/**
+ * Get the path to the credentials file for a domain
+ */
+export declare function getCredentialsPath(domain: string): string;
+/**
+ * Execute the complete OAuth PKCE authentication flow
+ *
+ * This function orchestrates the entire authentication flow:
+ * 1. Bootstrap tenant to get Cognito config
+ * 2. Generate PKCE codes
+ * 3. Start callback server
+ * 4. Open browser for authentication
+ * 5. Wait for callback with timeout
+ * 6. Exchange code for tokens
+ * 7. Get AWS credentials from Identity Pool
+ * 8. Save credentials to file
+ *
+ * @param options - Configuration options for the auth flow
+ * @returns AuthResult indicating success or failure
+ */
+export declare function executeAuthFlow(options: AuthFlowOptions): Promise<AuthResult>;
+/**
+ * Options for CI authentication flow
+ */
+export interface CIAuthOptions {
+    logger?: (message: string) => void;
+    password: string;
+    tenantDomain: string;
+    username: string;
+}
+/**
+ * Execute CI authentication flow using USER_PASSWORD_AUTH
+ *
+ * This is for non-interactive CI/CD environments where browser-based
+ * OAuth is not possible. Uses Cognito's USER_PASSWORD_AUTH flow.
+ *
+ * @param options - CI authentication options
+ * @returns AuthResult indicating success or failure
+ */
+export declare function executeCIAuthFlow(options: CIAuthOptions): Promise<AuthResult>;
+/**
+ * Check if running in a CI environment
+ */
+export declare function isCI(): boolean;
+/**
+ * Decode a CI token into username and password
+ * Token format: hd_sk_{base64url(username:password)}
+ */
+export declare function decodeToken(token: string): {
+    password: string;
+    username: string;
+} | null;
+/**
+ * Get CI credentials from HD_TOKEN environment variable
+ */
+export declare function getCICredentials(): {
+    password: string;
+    username: string;
+} | null;