@heroku/heroku-fetch 0.1.1-beta.0

package/dist/cli/cli-login.js

@@ -0,0 +1,7 @@
+/**
+ * CLI Login Module
+ *
+ * Re-exports the Login class from the login subfolder.
+ * This file maintains backward compatibility with the original import path.
+ */
+export { Login } from './login/index.js';

package/dist/cli/cli-two-factor-prompt.d.ts

@@ -0,0 +1,62 @@
+/**
+ * CLI Two-Factor Authentication Prompt
+ *
+ * Provides a reusable 2FA challenge handler for Heroku CLIs.
+ * This module requires @heroku/heroku-cli-util to be installed.
+ *
+ * @example
+ * ```typescript
+ * import { HerokuApiClient } from '@heroku/heroku-fetch';
+ * import { cliTwoFactorPrompt } from '@heroku/heroku-fetch/cli-two-factor-prompt';
+ *
+ * const client = new HerokuApiClient({
+ *   service: 'platform',
+ *   twoFactor: {
+ *     onChallenge: cliTwoFactorPrompt,
+ *   },
+ * });
+ * ```
+ */
+/**
+ * Two-factor authentication challenge handler for Heroku CLIs.
+ *
+ * This function prompts the user for their 2FA code using heroku-cli-util's hux.prompt
+ * with masked input for security.
+ *
+ * @returns Promise that resolves with the 2FA code entered by the user
+ *
+ * @example
+ * ```typescript
+ * const client = new HerokuApiClient({
+ *   service: 'platform',
+ *   twoFactor: {
+ *     onChallenge: cliTwoFactorPrompt,
+ *   },
+ * });
+ * ```
+ */
+export declare function cliTwoFactorPrompt(): Promise<string>;
+/**
+ * Factory function to create a custom 2FA prompt with options.
+ *
+ * @param options - Customization options for the prompt
+ * @param options.message - Custom prompt message (default: "Enter your 2FA code")
+ * @returns A function that can be used as the onChallenge callback
+ *
+ * @example
+ * ```typescript
+ * import { createCliTwoFactorPrompt } from '@heroku/heroku-fetch/cli-two-factor-prompt';
+ *
+ * const client = new HerokuApiClient({
+ *   service: 'platform',
+ *   twoFactor: {
+ *     onChallenge: createCliTwoFactorPrompt({
+ *       message: 'Enter your Heroku 2FA code',
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+export declare function createCliTwoFactorPrompt(options?: {
+    message?: string;
+}): () => Promise<string>;

package/dist/cli/cli-two-factor-prompt.js

@@ -0,0 +1,93 @@
+/**
+ * CLI Two-Factor Authentication Prompt
+ *
+ * Provides a reusable 2FA challenge handler for Heroku CLIs.
+ * This module requires @heroku/heroku-cli-util to be installed.
+ *
+ * @example
+ * ```typescript
+ * import { HerokuApiClient } from '@heroku/heroku-fetch';
+ * import { cliTwoFactorPrompt } from '@heroku/heroku-fetch/cli-two-factor-prompt';
+ *
+ * const client = new HerokuApiClient({
+ *   service: 'platform',
+ *   twoFactor: {
+ *     onChallenge: cliTwoFactorPrompt,
+ *   },
+ * });
+ * ```
+ */
+import { prompt } from '@heroku/heroku-cli-util/hux';
+/**
+ * Two-factor authentication challenge handler for Heroku CLIs.
+ *
+ * This function prompts the user for their 2FA code using heroku-cli-util's hux.prompt
+ * with masked input for security.
+ *
+ * @returns Promise that resolves with the 2FA code entered by the user
+ *
+ * @example
+ * ```typescript
+ * const client = new HerokuApiClient({
+ *   service: 'platform',
+ *   twoFactor: {
+ *     onChallenge: cliTwoFactorPrompt,
+ *   },
+ * });
+ * ```
+ */
+export async function cliTwoFactorPrompt() {
+    // Dynamic import to avoid requiring @heroku/heroku-cli-util for non-CLI users
+    try {
+        const code = await prompt('Enter your 2FA code', {
+            type: 'password',
+        });
+        return code;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('Cannot find module')) {
+            throw new Error('cliTwoFactorPrompt requires @heroku/heroku-cli-util to be installed. '
+                + 'Please run: npm install @heroku/heroku-cli-util');
+        }
+        throw error;
+    }
+}
+/**
+ * Factory function to create a custom 2FA prompt with options.
+ *
+ * @param options - Customization options for the prompt
+ * @param options.message - Custom prompt message (default: "Enter your 2FA code")
+ * @returns A function that can be used as the onChallenge callback
+ *
+ * @example
+ * ```typescript
+ * import { createCliTwoFactorPrompt } from '@heroku/heroku-fetch/cli-two-factor-prompt';
+ *
+ * const client = new HerokuApiClient({
+ *   service: 'platform',
+ *   twoFactor: {
+ *     onChallenge: createCliTwoFactorPrompt({
+ *       message: 'Enter your Heroku 2FA code',
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+export function createCliTwoFactorPrompt(options) {
+    const message = options?.message || 'Enter your 2FA code';
+    return async () => {
+        try {
+            const code = await prompt(message, {
+                type: 'password',
+            });
+            return code;
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('Cannot find module')) {
+                throw new Error('createCliTwoFactorPrompt requires @heroku/heroku-cli-util to be installed. '
+                    + 'Please run: npm install @heroku/heroku-cli-util');
+            }
+            throw error;
+        }
+    };
+}

package/dist/cli/login/browser-login.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Browser-based OAuth login flow
+ */
+import type { LoginConfig, NetrcEntry } from './types.js';
+/**
+ * Perform browser-based OAuth login
+ */
+export declare function browserLogin(config: LoginConfig, browser?: string): Promise<NetrcEntry>;

package/dist/cli/login/browser-login.js

@@ -0,0 +1,115 @@
+/**
+ * Browser-based OAuth login flow
+ */
+import os from 'node:os';
+import { debugCliLogin } from '../../debug-loggers.js';
+import { headers } from './types.js';
+const hostname = os.hostname();
+/**
+ * Show the manual browser login URL to the user
+ */
+function showManualBrowserLoginUrl(url) {
+    console.warn('If browser does not open, visit:');
+    console.error(`\u001B[32m${url}\u001B[0m`); // Green color
+}
+/**
+ * Poll the auth server for the access token with retry logic
+ */
+async function fetchAuth(loginHost, cliUrl, token, retries = 3) {
+    try {
+        debugCliLogin('Polling auth server: %s%s (retries left: %d)', loginHost, cliUrl, retries);
+        const response = await fetch(`${loginHost}${cliUrl}`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!response.ok && retries > 0 && response.status >= 500) {
+            debugCliLogin('Auth server returned %d, retrying...', response.status);
+            return fetchAuth(loginHost, cliUrl, token, retries - 1);
+        }
+        if (!response.ok) {
+            debugCliLogin('Auth polling failed with status: %d', response.status);
+            throw new Error(`Login failed: ${response.statusText}`);
+        }
+        debugCliLogin('Access token received from auth server');
+        return (await response.json());
+    }
+    catch (error) {
+        if (retries > 0
+            && error instanceof Error
+            && error.message.includes('500')) {
+            debugCliLogin('Caught 500 error, retrying...');
+            return fetchAuth(loginHost, cliUrl, token, retries - 1);
+        }
+        debugCliLogin('Auth polling failed: %O', error);
+        throw error;
+    }
+}
+/**
+ * Perform browser-based OAuth login
+ */
+export async function browserLogin(config, browser) {
+    debugCliLogin('Starting browser login flow');
+    debugCliLogin('Creating auth session at %s/auth', config.loginHost);
+    // Create auth session
+    const response = await fetch(`${config.loginHost}/auth`, {
+        body: JSON.stringify({
+            description: `Heroku CLI login from ${hostname}`,
+        }),
+        headers: { 'Content-Type': 'application/json' },
+        method: 'POST',
+    });
+    if (!response.ok) {
+        debugCliLogin('Failed to create auth session: %d %s', response.status, response.statusText);
+        throw new Error(`Failed to initiate browser login: ${response.statusText}`);
+    }
+    const urls = (await response.json());
+    const url = `${config.loginHost}${urls.browser_url}`;
+    debugCliLogin('Auth session created, browser URL: %s', url);
+    console.error(`Opening browser to ${url}\n`);
+    let urlDisplayed = false;
+    const showUrl = () => {
+        if (!urlDisplayed)
+            console.warn('Cannot open browser.');
+        urlDisplayed = true;
+    };
+    showManualBrowserLoginUrl(url);
+    const open = (await import('open')).default;
+    debugCliLogin('Opening browser with %s', browser ? `browser: ${browser}` : 'default browser');
+    const cp = await open(url, {
+        wait: false,
+        ...(browser ? { app: { name: browser } } : {}),
+    });
+    cp.on('error', err => {
+        debugCliLogin('Browser open error: %O', err);
+        console.warn(err);
+        showUrl();
+    });
+    if (process.env.HEROKU_TESTING_HEADLESS_LOGIN === '1')
+        showUrl();
+    cp.on('close', code => {
+        if (code !== 0) {
+            debugCliLogin('Browser process exited with non-zero code: %d', code);
+            showUrl();
+        }
+    });
+    console.error('heroku: Waiting for login...');
+    const auth = await fetchAuth(config.loginHost, urls.cli_url, urls.token);
+    if (auth.error) {
+        debugCliLogin('Auth response contained error: %s', auth.error);
+        throw new Error(auth.error);
+    }
+    console.error('Logging in...');
+    debugCliLogin('Fetching account information from %s/account', config.apiUrl);
+    const accountResponse = await fetch(`${config.apiUrl}/account`, {
+        headers: headers(auth.access_token),
+    });
+    if (!accountResponse.ok) {
+        debugCliLogin('Failed to fetch account: %d %s', accountResponse.status, accountResponse.statusText);
+        throw new Error(`Failed to fetch account: ${accountResponse.statusText}`);
+    }
+    const account = (await accountResponse.json());
+    debugCliLogin('Browser login successful for user: %s', account.email);
+    return {
+        login: account.email,
+        password: auth.access_token,
+    };
+}

package/dist/cli/login/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * CLI Login Module
+ *
+ * Provides login/logout functionality for Heroku CLI tools.
+ * Supports browser-based, interactive (username/password), and SSO login methods.
+ *
+ * @example
+ * ```typescript
+ * import { Login } from '@heroku/heroku-fetch/cli-login';
+ * import { HerokuApiClient } from '@heroku/heroku-fetch';
+ *
+ * const client = new HerokuApiClient({ service: 'platform' });
+ * const login = new Login(client);
+ *
+ * // Browser-based login (default)
+ * await login.login({ method: 'browser' });
+ *
+ * // Interactive login with username/password
+ * await login.login({ method: 'interactive' });
+ *
+ * // Logout
+ * await login.logout();
+ * ```
+ */
+import type { HerokuApiClient } from '../../client/index.js';
+import type { LoginOptions } from './types.js';
+export declare class Login {
+    private readonly heroku;
+    private config;
+    constructor(heroku: HerokuApiClient);
+    login(opts?: LoginOptions): Promise<void>;
+    logout(token?: string): Promise<void>;
+}
+export { type LoginOptions } from './types.js';

package/dist/cli/login/index.js

@@ -0,0 +1,193 @@
+/**
+ * CLI Login Module
+ *
+ * Provides login/logout functionality for Heroku CLI tools.
+ * Supports browser-based, interactive (username/password), and SSO login methods.
+ *
+ * @example
+ * ```typescript
+ * import { Login } from '@heroku/heroku-fetch/cli-login';
+ * import { HerokuApiClient } from '@heroku/heroku-fetch';
+ *
+ * const client = new HerokuApiClient({ service: 'platform' });
+ * const login = new Login(client);
+ *
+ * // Browser-based login (default)
+ * await login.login({ method: 'browser' });
+ *
+ * // Interactive login with username/password
+ * await login.login({ method: 'interactive' });
+ *
+ * // Logout
+ * await login.logout();
+ * ```
+ */
+import * as readline from 'node:readline';
+import { debugCliLogin } from '../../debug-loggers.js';
+import { browserLogin } from './browser-login.js';
+import { interactiveLogin } from './interactive-login.js';
+import { clearTokens, getNetrc, getStoredLogin, getStoredToken, saveToken, } from './netrc-utils.js';
+import { deleteOAuthTokens } from './oauth.js';
+import { ssoLogin } from './sso-login.js';
+import { LOGIN_TIMEOUT, THIRTY_DAYS } from './types.js';
+// Re-export types for convenience
+/**
+ * Prompt user for login method selection
+ */
+async function promptForLoginMethod() {
+    console.error('heroku: Press any key to open up the browser to login or \'q\' to exit');
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    // Set raw mode to get immediate keypresses
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    const key = await new Promise(resolve => {
+        process.stdin.once('data', data => {
+            const key = data.toString();
+            resolve(key);
+        });
+    });
+    // Restore normal terminal settings
+    process.stdin.setRawMode(false);
+    rl.close();
+    console.error('');
+    return key;
+}
+/**
+ * Convert keypress to login method
+ */
+function getLoginMethodFromPromptKey(key) {
+    if (key === '\u0003') {
+        // Ctrl+C
+        throw new Error('Login cancelled by user');
+    }
+    if (key.toLowerCase() === 'q') {
+        throw new Error('Login cancelled by user');
+    }
+    return 'browser';
+}
+export class Login {
+    constructor(heroku) {
+        this.heroku = heroku;
+        this.config = {
+            apiHost: 'api.heroku.com',
+            apiUrl: process.env.HEROKU_API_URL || 'https://api.heroku.com',
+            httpGitHost: 'git.heroku.com',
+            loginHost: process.env.HEROKU_LOGIN_HOST || 'https://cli-auth.heroku.com',
+        };
+    }
+    async login(opts = {}) {
+        debugCliLogin('Login initiated with options: %O', opts);
+        let loggedIn = false;
+        try {
+            // timeout after 10 minutes
+            setTimeout(() => {
+                if (!loggedIn)
+                    throw new Error('Login timed out');
+            }, LOGIN_TIMEOUT).unref();
+            if (process.env.HEROKU_API_KEY) {
+                debugCliLogin('Login blocked: HEROKU_API_KEY environment variable is set');
+                throw new Error('Cannot log in with HEROKU_API_KEY set');
+            }
+            if (opts.expiresIn && opts.expiresIn > THIRTY_DAYS) {
+                debugCliLogin('Login blocked: expiresIn (%d) exceeds 30 days', opts.expiresIn);
+                throw new Error('Cannot set an expiration longer than thirty days');
+            }
+            const netrc = getNetrc();
+            await netrc.load();
+            const previousEntry = netrc.machines[this.config.apiHost];
+            if (previousEntry) {
+                debugCliLogin('Found existing credentials in netrc for: %s', previousEntry.login);
+            }
+            let input = opts.method;
+            // Determine login method
+            if (input) {
+                debugCliLogin('Using specified login method: %s', input);
+            }
+            else if (opts.expiresIn) {
+                // can't use browser with --expires-in
+                input = 'interactive';
+                debugCliLogin('Selected interactive login (expiresIn specified)');
+            }
+            else if (process.env.HEROKU_LEGACY_SSO === '1') {
+                input = 'sso';
+                debugCliLogin('Selected SSO login (HEROKU_LEGACY_SSO=1)');
+            }
+            else {
+                const key = await promptForLoginMethod();
+                input = getLoginMethodFromPromptKey(key);
+                debugCliLogin('Selected %s login (from user prompt)', input);
+            }
+            // Logout previous session
+            try {
+                if (previousEntry && previousEntry.password) {
+                    debugCliLogin('Logging out previous session');
+                    await this.logout(previousEntry.password);
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                debugCliLogin('Previous session logout failed: %s', message);
+                console.warn(message);
+            }
+            // Perform login based on selected method
+            let auth;
+            switch (input) {
+                case 'b':
+                case 'browser': {
+                    debugCliLogin('Executing browser login');
+                    auth = await browserLogin(this.config, opts.browser);
+                    break;
+                }
+                case 'i':
+                case 'interactive': {
+                    debugCliLogin('Executing interactive login');
+                    const previousLogin = await getStoredLogin(this.config.apiHost);
+                    auth = await interactiveLogin(this.config, previousLogin, opts.expiresIn);
+                    break;
+                }
+                case 's':
+                case 'sso': {
+                    debugCliLogin('Executing SSO login');
+                    auth = await ssoLogin(this.config);
+                    break;
+                }
+                default: {
+                    debugCliLogin('Unknown login method: %s, retrying', input);
+                    return this.login(opts);
+                }
+            }
+            await saveToken(auth, this.config.apiHost, this.config.httpGitHost);
+            debugCliLogin('Login completed successfully for user: %s', auth.login);
+            console.error(`Logged in as ${auth.login}`);
+        }
+        finally {
+            loggedIn = true;
+        }
+    }
+    async logout(token) {
+        debugCliLogin('Logout initiated');
+        // Get token from netrc if not provided
+        if (!token) {
+            token = await getStoredToken(this.config.apiHost);
+        }
+        if (!token) {
+            debugCliLogin('no credentials to logout');
+            return;
+        }
+        // Delete OAuth tokens and sessions from API
+        // If this fails (e.g., token not found), we still want to clear local netrc
+        try {
+            await deleteOAuthTokens(this.heroku, token);
+        }
+        catch (error) {
+            debugCliLogin('Failed to delete OAuth tokens from API: %O', error);
+            // Continue to clear netrc even if API call fails
+        }
+        // Clear netrc entries
+        await clearTokens(this.config.apiHost, this.config.httpGitHost);
+        console.error('Logged out');
+    }
+}

package/dist/cli/login/interactive-login.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Interactive username/password login flow
+ */
+import type { LoginConfig, NetrcEntry } from './types.js';
+/**
+ * Perform interactive username/password login
+ */
+export declare function interactiveLogin(config: LoginConfig, previousLogin?: string, expiresIn?: number): Promise<NetrcEntry>;

package/dist/cli/login/interactive-login.js

@@ -0,0 +1,59 @@
+/**
+ * Interactive username/password login flow
+ */
+import { prompt } from '@heroku/heroku-cli-util/hux';
+import { debugCliLogin } from '../../debug-loggers.js';
+import { createOAuthToken } from './oauth.js';
+/**
+ * Perform interactive username/password login
+ */
+export async function interactiveLogin(config, previousLogin, expiresIn) {
+    debugCliLogin('Starting interactive login flow');
+    console.error('heroku: Enter your login credentials\n');
+    const email = await prompt('Email', {
+        default: previousLogin,
+        type: 'input',
+    });
+    const login = email;
+    debugCliLogin('Email provided: %s', login);
+    const password = await prompt('Password', {
+        type: 'password',
+    });
+    let auth;
+    try {
+        debugCliLogin('Creating OAuth token at %s', config.apiUrl);
+        auth = await createOAuthToken(config.apiUrl, login, password, { expiresIn });
+        debugCliLogin('OAuth token created successfully');
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            const errBody = error.body;
+            if (errBody?.id === 'device_trust_required') {
+                debugCliLogin('Device trust required error - 2FA must be enabled');
+                throw new Error('The interactive flag requires Two-Factor Authentication to be enabled on your account. Please use browser login.');
+            }
+            if (errBody?.id === 'two_factor') {
+                debugCliLogin('2FA challenge required, prompting for code');
+                const secondFactor = await prompt('Two-factor code', {
+                    type: 'password',
+                });
+                debugCliLogin('Retrying OAuth token creation with 2FA code');
+                auth = await createOAuthToken(config.apiUrl, login, password, {
+                    expiresIn,
+                    secondFactor,
+                });
+                debugCliLogin('OAuth token created successfully with 2FA');
+            }
+            else {
+                debugCliLogin('OAuth token creation failed: %O', error);
+                throw error;
+            }
+        }
+        else {
+            debugCliLogin('Unexpected error during OAuth token creation: %O', error);
+            throw error;
+        }
+    }
+    debugCliLogin('Interactive login successful for user: %s', auth.login);
+    return auth;
+}

package/dist/cli/login/netrc-utils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Netrc file management utilities
+ */
+import { Netrc } from 'netrc-parser';
+import type { NetrcEntry } from './types.js';
+export declare function getNetrc(): Netrc;
+/**
+ * Save authentication token to netrc file
+ */
+export declare function saveToken(entry: NetrcEntry, apiHost: string, httpGitHost: string): Promise<void>;
+/**
+ * Clear authentication tokens from netrc file
+ */
+export declare function clearTokens(apiHost: string, httpGitHost: string): Promise<void>;
+/**
+ * Get stored token from netrc file
+ */
+export declare function getStoredToken(apiHost: string): Promise<string | undefined>;
+/**
+ * Get stored login from netrc file
+ */
+export declare function getStoredLogin(apiHost: string): Promise<string | undefined>;