@herodevs/cli 2.0.0-beta.14 → 2.0.0-beta.16

package/dist/api/user-setup.client.js

@@ -0,0 +1,92 @@
+import { config } from "../config/constants.js";
+import { getTokenProvider } from "../service/auth.svc.js";
+import { debugLogger } from "../service/log.svc.js";
+import { withRetries } from "../utils/retry.js";
+import { createApollo } from "./apollo.client.js";
+import { ApiError, isApiErrorCode } from "./errors.js";
+import { completeUserSetupMutation, userSetupStatusQuery } from "./gql-operations.js";
+import { getGraphQLErrors } from "./graphql-errors.js";
+const USER_SETUP_MAX_ATTEMPTS = 3;
+const USER_SETUP_RETRY_DELAY_MS = 500;
+const USER_FACING_SERVER_ERROR = 'Please contact support@herodevs.com.';
+const SERVER_ERROR_CODES = ['INTERNAL_SERVER_ERROR', 'SERVER_ERROR', 'SERVICE_UNAVAILABLE'];
+const getGraphqlUrl = () => `${config.graphqlHost}${config.graphqlPath}`;
+function extractErrorCode(errors) {
+    const code = errors[0]?.extensions?.code;
+    if (!code || !isApiErrorCode(code))
+        return;
+    return code;
+}
+export async function getUserSetupStatus(options) {
+    const tokenProvider = getTokenProvider(options?.preferOAuth, options?.orgAccessToken);
+    const client = createApollo(getGraphqlUrl(), tokenProvider);
+    const res = await client.query({ query: userSetupStatusQuery });
+    const errors = getGraphQLErrors(res);
+    if (res?.error || errors?.length) {
+        debugLogger('Error returned from userSetupStatus query: %o', res.error || errors);
+        if (errors?.length) {
+            const rawCode = errors[0]?.extensions?.code;
+            if (rawCode && SERVER_ERROR_CODES.includes(rawCode)) {
+                throw new Error(USER_FACING_SERVER_ERROR);
+            }
+            const code = extractErrorCode(errors);
+            const message = errors[0].message ?? 'Failed to check user setup status';
+            if (code) {
+                throw new ApiError(message, code);
+            }
+            throw new Error(message);
+        }
+        throw new Error('Failed to check user setup status');
+    }
+    const status = res.data?.eol?.userSetupStatus;
+    if (!status || typeof status.isComplete !== 'boolean') {
+        debugLogger('Unexpected userSetupStatus query response: %o', res.data);
+        throw new Error('Failed to check user setup status');
+    }
+    return { isComplete: status.isComplete, orgId: status.orgId ?? undefined };
+}
+export async function completeUserSetup(options) {
+    const tokenProvider = getTokenProvider(options?.preferOAuth, options?.orgAccessToken);
+    const client = createApollo(getGraphqlUrl(), tokenProvider);
+    const res = await client.mutate({ mutation: completeUserSetupMutation });
+    const errors = getGraphQLErrors(res);
+    if (res?.error || errors?.length) {
+        debugLogger('Error returned from completeUserSetup mutation: %o', res.error || errors);
+        if (errors?.length) {
+            const rawCode = errors[0]?.extensions?.code;
+            if (rawCode && SERVER_ERROR_CODES.includes(rawCode)) {
+                throw new Error(USER_FACING_SERVER_ERROR);
+            }
+            const code = extractErrorCode(errors);
+            const message = errors[0].message ?? 'Failed to complete user setup';
+            if (code) {
+                throw new ApiError(message, code);
+            }
+            throw new Error(message);
+        }
+        throw new Error('Failed to complete user setup');
+    }
+    const result = res.data?.eol?.completeUserSetup;
+    if (!result || result.isComplete !== true) {
+        debugLogger('completeUserSetup mutation returned unsuccessful response: %o', res.data);
+        throw new Error('Failed to complete user setup');
+    }
+    return { isComplete: true, orgId: result.orgId ?? undefined };
+}
+export async function ensureUserSetup(options) {
+    const status = await withRetries('user-setup-status', () => getUserSetupStatus(options), {
+        attempts: USER_SETUP_MAX_ATTEMPTS,
+        baseDelayMs: USER_SETUP_RETRY_DELAY_MS,
+    });
+    if (status.isComplete && status.orgId != null) {
+        return status.orgId;
+    }
+    const result = await withRetries('user-setup-complete', () => completeUserSetup(options), {
+        attempts: USER_SETUP_MAX_ATTEMPTS,
+        baseDelayMs: USER_SETUP_RETRY_DELAY_MS,
+    });
+    if (result.orgId != null) {
+        return result.orgId;
+    }
+    throw new Error(`User setup did not return an organization ID. ${USER_FACING_SERVER_ERROR}`);
+}

package/dist/commands/auth/login.d.ts

@@ -0,0 +1,14 @@
+import { Command } from '@oclif/core';
+export default class AuthLogin extends Command {
+    static description: string;
+    private server?;
+    private stopServerPromise?;
+    private readonly port;
+    private readonly redirectUri;
+    private readonly realmUrl;
+    private readonly clientId;
+    run(): Promise<void>;
+    private startServerAndAwaitCode;
+    private stopServer;
+    private exchangeCodeForToken;
+}

package/dist/commands/auth/login.js

@@ -0,0 +1,225 @@
+import crypto from 'node:crypto';
+import http from 'node:http';
+import { createInterface } from 'node:readline';
+import { URL } from 'node:url';
+import { Command } from '@oclif/core';
+import { ensureUserSetup } from "../../api/user-setup.client.js";
+import { OAUTH_CALLBACK_ERROR_CODES } from "../../config/constants.js";
+import { refreshIdentityFromStoredToken } from "../../service/analytics.svc.js";
+import { persistTokenResponse } from "../../service/auth.svc.js";
+import { getClientId, getRealmUrl } from "../../service/auth-config.svc.js";
+import { debugLogger, getErrorMessage } from "../../service/log.svc.js";
+import { openInBrowser } from "../../utils/open-in-browser.js";
+export default class AuthLogin extends Command {
+    static description = 'OAuth CLI login';
+    server;
+    stopServerPromise;
+    port = parseInt(process.env.OAUTH_CALLBACK_PORT || '4000', 10);
+    redirectUri = process.env.OAUTH_CALLBACK_REDIRECT || `http://localhost:${this.port}/oauth2/callback`;
+    realmUrl = getRealmUrl();
+    clientId = getClientId();
+    async run() {
+        if (typeof this.config.runHook === 'function') {
+            await this.parse(AuthLogin);
+        }
+        const codeVerifier = crypto.randomBytes(32).toString('base64url');
+        const codeChallenge = crypto.createHash('sha256').update(codeVerifier).digest('base64url');
+        const state = crypto.randomBytes(16).toString('hex');
+        const authUrl = `${this.realmUrl}/auth?` +
+            `client_id=${this.clientId}` +
+            `&response_type=code` +
+            `&redirect_uri=${encodeURIComponent(this.redirectUri)}` +
+            `&code_challenge=${codeChallenge}` +
+            `&code_challenge_method=S256` +
+            `&state=${state}`;
+        const code = await this.startServerAndAwaitCode(authUrl, state);
+        const token = await this.exchangeCodeForToken(code, codeVerifier);
+        try {
+            await persistTokenResponse(token);
+        }
+        catch (error) {
+            this.warn(`Failed to store tokens securely: ${error instanceof Error ? error.message : error}`);
+            return;
+        }
+        try {
+            await ensureUserSetup({ preferOAuth: true });
+        }
+        catch (error) {
+            this.error(`User setup failed. ${getErrorMessage(error)}`);
+        }
+        try {
+            await refreshIdentityFromStoredToken();
+        }
+        catch (error) {
+            this.warn(`Failed to refresh analytics identity: ${getErrorMessage(error)}`);
+        }
+        this.log('\nLogin completed successfully.');
+    }
+    startServerAndAwaitCode(authUrl, expectedState) {
+        return new Promise((resolve, reject) => {
+            this.server = http.createServer((req, res) => {
+                if (!req.url) {
+                    res.writeHead(400);
+                    res.end('Invalid request');
+                    return;
+                }
+                let parsedUrl;
+                try {
+                    parsedUrl = new URL(req.url, `http://localhost:${this.port}`);
+                }
+                catch {
+                    res.writeHead(400, { 'Content-Type': 'text/plain' });
+                    res.end('Invalid callback URL');
+                    this.stopServer();
+                    reject(new Error('Invalid callback URL'));
+                    return;
+                }
+                if (parsedUrl.pathname === '/oauth2/callback') {
+                    const code = parsedUrl.searchParams.get('code');
+                    const state = parsedUrl.searchParams.get('state');
+                    const oauthError = parsedUrl.searchParams.get('error');
+                    const oauthErrorDescription = parsedUrl.searchParams.get('error_description');
+                    if (!state) {
+                        res.writeHead(400, { 'Content-Type': 'text/plain' });
+                        res.end('Missing state parameter.');
+                        this.stopServer();
+                        return reject(new Error('Missing state parameter in callback'));
+                    }
+                    if (state !== expectedState) {
+                        res.writeHead(400, { 'Content-Type': 'text/plain' });
+                        res.end('State verification failed. Please restart the login flow.');
+                        this.stopServer();
+                        return reject(new Error('State verification failed'));
+                    }
+                    if (oauthError) {
+                        const isAlreadyLoggedIn = oauthError === OAUTH_CALLBACK_ERROR_CODES.ALREADY_LOGGED_IN;
+                        const isDifferentUserAuthenticated = oauthError === OAUTH_CALLBACK_ERROR_CODES.DIFFERENT_USER_AUTHENTICATED;
+                        debugLogger('OAuth callback returned error: %s (%s)', oauthError, oauthErrorDescription ?? 'no description');
+                        let browserMessage;
+                        let cliErrorMessage;
+                        if (isAlreadyLoggedIn) {
+                            browserMessage = "You're already signed in. We'll continue for you. Return to the terminal.";
+                            cliErrorMessage = `You're already signed in. Run "hd auth login" again to continue.`;
+                        }
+                        else if (isDifferentUserAuthenticated) {
+                            browserMessage =
+                                "You're signed in with a different account than this sign-in attempt. Return to the terminal.";
+                            cliErrorMessage =
+                                `You're signed in with a different account than this sign-in attempt. ` +
+                                    `Choose another account, or reset this sign-in session and try again. ` +
+                                    `If needed, run "hd auth logout" and then "hd auth login".`;
+                        }
+                        else {
+                            browserMessage = "We couldn't complete sign-in. Return to the terminal and try again.";
+                            cliErrorMessage = `We couldn't complete sign-in. Please run "hd auth login" again.`;
+                        }
+                        res.writeHead(400, { 'Content-Type': 'text/plain' });
+                        res.end(browserMessage);
+                        this.stopServer();
+                        return reject(new Error(cliErrorMessage));
+                    }
+                    if (code) {
+                        res.writeHead(200, { 'Content-Type': 'text/plain' });
+                        res.end('Login successful. You can close this window.');
+                        this.stopServer();
+                        resolve(code);
+                    }
+                    else {
+                        res.writeHead(400, { 'Content-Type': 'text/plain' });
+                        res.end('No authorization code returned. Please try again.');
+                        this.stopServer();
+                        reject(new Error('No code returned from Keycloak'));
+                    }
+                }
+                else {
+                    res.writeHead(404);
+                    res.end();
+                }
+            });
+            this.server.listen(this.port, async () => {
+                await new Promise((resolve) => {
+                    const rl = createInterface({ input: process.stdin, output: process.stdout });
+                    rl.question(`Press Enter to navigate to: ${authUrl}\n`, () => {
+                        rl.close();
+                        resolve();
+                    });
+                });
+                try {
+                    await openInBrowser(authUrl);
+                }
+                catch (err) {
+                    this.warn(`Failed to open browser automatically. Please open this URL manually:\n${authUrl}\n${err instanceof Error ? err.message : err}`);
+                }
+            });
+            this.server.on('error', (err) => {
+                this.stopServer();
+                reject(err);
+            });
+        });
+    }
+    stopServer() {
+        if (this.stopServerPromise) {
+            return this.stopServerPromise;
+        }
+        const server = this.server;
+        this.server = undefined;
+        if (!server) {
+            return Promise.resolve();
+        }
+        const stopPromise = new Promise((resolve) => {
+            const timeoutMs = 1000;
+            let settled = false;
+            let timeout;
+            const complete = (err) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                if (timeout) {
+                    clearTimeout(timeout);
+                    timeout = undefined;
+                }
+                const code = err?.code;
+                if (err && code !== 'ERR_SERVER_NOT_RUNNING') {
+                    this.warn('Failed to stop local OAuth callback server.');
+                    debugLogger('Failed to stop local OAuth callback server: %s', getErrorMessage(err));
+                }
+                resolve();
+            };
+            timeout = setTimeout(() => {
+                debugLogger('Timed out while stopping local OAuth callback server after %dms', timeoutMs);
+                complete();
+            }, timeoutMs);
+            try {
+                server.close((err) => complete(err));
+            }
+            catch (err) {
+                complete(err);
+            }
+        }).finally(() => {
+            this.stopServerPromise = undefined;
+        });
+        this.stopServerPromise = stopPromise;
+        return stopPromise;
+    }
+    async exchangeCodeForToken(code, codeVerifier) {
+        const tokenUrl = `${this.realmUrl}/token`;
+        const params = new URLSearchParams({
+            grant_type: 'authorization_code',
+            client_id: this.clientId,
+            redirect_uri: this.redirectUri,
+            code_verifier: codeVerifier,
+            code,
+        });
+        const response = await fetch(tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: params.toString(),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Token exchange failed: ${response.status} ${response.statusText}\n${text}`);
+        }
+        return response.json();
+    }
+}

package/dist/commands/auth/logout.d.ts

@@ -0,0 +1,5 @@
+import { Command } from '@oclif/core';
+export default class AuthLogout extends Command {
+    static description: string;
+    run(): Promise<void>;
+}

package/dist/commands/auth/logout.js

@@ -0,0 +1,27 @@
+import { Command } from '@oclif/core';
+import { clearTrackedIdentity } from "../../service/analytics.svc.js";
+import { logoutFromProvider } from "../../service/auth-refresh.svc.js";
+import { clearStoredTokens, getStoredTokens } from "../../service/auth-token.svc.js";
+export default class AuthLogout extends Command {
+    static description = 'Logs out of HeroDevs OAuth and clears stored tokens';
+    async run() {
+        if (typeof this.config.runHook === 'function') {
+            await this.parse(AuthLogout);
+        }
+        const tokens = await getStoredTokens();
+        if (!tokens?.accessToken && !tokens?.refreshToken) {
+            this.log('No stored authentication tokens found.');
+            return;
+        }
+        try {
+            await logoutFromProvider(tokens?.refreshToken);
+            this.log('Logged out of HeroDevs OAuth provider.');
+        }
+        catch (error) {
+            this.warn(`Failed to revoke tokens remotely: ${error instanceof Error ? error.message : error}`);
+        }
+        clearTrackedIdentity();
+        await clearStoredTokens();
+        this.log('Local authentication tokens removed from your system.');
+    }
+}

package/dist/commands/auth/provision-ci-token.d.ts

@@ -0,0 +1,5 @@
+import { Command } from '@oclif/core';
+export default class AuthProvisionCiToken extends Command {
+    static description: string;
+    run(): Promise<void>;
+}

package/dist/commands/auth/provision-ci-token.js

@@ -0,0 +1,72 @@
+import { Command } from '@oclif/core';
+import { provisionCIToken } from "../../api/ci-token.client.js";
+import { ensureUserSetup } from "../../api/user-setup.client.js";
+import { refreshIdentityFromStoredToken, track } from "../../service/analytics.svc.js";
+import { requireAccessToken } from "../../service/auth.svc.js";
+import { saveCIToken } from "../../service/ci-token.svc.js";
+import { getErrorMessage } from "../../service/log.svc.js";
+export default class AuthProvisionCiToken extends Command {
+    static description = 'Provision a CI/CD long-lived refresh token for headless auth';
+    async run() {
+        await this.parse(AuthProvisionCiToken);
+        try {
+            await requireAccessToken();
+        }
+        catch (error) {
+            this.error(`Must be logged in to provision CI token. Run 'hd auth login' first. ${getErrorMessage(error)}`);
+        }
+        try {
+            await refreshIdentityFromStoredToken();
+        }
+        catch (error) {
+            this.warn(`Failed to refresh analytics identity: ${getErrorMessage(error)}`);
+        }
+        track('CLI CI Token Provision Started', (context) => ({
+            command: 'auth provision-ci-token',
+            app_used: context.app_used,
+            ci_provider: context.ci_provider,
+            cli_version: context.cli_version,
+            started_at: context.started_at,
+        }));
+        let orgId;
+        try {
+            orgId = await ensureUserSetup();
+        }
+        catch (error) {
+            track('CLI CI Token Provision Failed', () => ({
+                command: 'auth provision-ci-token',
+                error: `user_setup_failed:${getErrorMessage(error)}`,
+            }));
+            this.error(`User setup failed. ${getErrorMessage(error)}`);
+        }
+        try {
+            const result = await provisionCIToken({ orgId });
+            try {
+                await ensureUserSetup({ orgAccessToken: result.access_token });
+            }
+            catch (error) {
+                track('CLI CI Token Provision Failed', () => ({
+                    command: 'auth provision-ci-token',
+                    error: `user_setup_failed:${getErrorMessage(error)}`,
+                }));
+                this.error(`User Org setup failed. ${getErrorMessage(error)}`);
+            }
+            const refreshToken = result.refresh_token;
+            saveCIToken(refreshToken);
+            this.log('CI token provisioned and saved locally.');
+            this.log('');
+            this.log('For CI/CD, set this environment variable:');
+            this.log(`  HD_CI_CREDENTIAL=${refreshToken}`);
+            track('CLI CI Token Provision Succeeded', () => ({
+                command: 'auth provision-ci-token',
+            }));
+        }
+        catch (error) {
+            track('CLI CI Token Provision Failed', () => ({
+                command: 'auth provision-ci-token',
+                error: `provision_failed:${getErrorMessage(error)}`,
+            }));
+            this.error(`CI token provisioning failed. ${getErrorMessage(error)}`);
+        }
+    }
+}

package/dist/commands/scan/eol.d.ts

@@ -16,11 +16,13 @@ export default class ScanEol extends Command {
         sbomOutput: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         saveTrimmedSbom: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         hideReportUrl: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        automated: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         version: import("@oclif/core/interfaces").BooleanFlag<void>;
     };
     run(): Promise<EolReport | undefined>;
     private loadSbom;
     private scanSbom;
+    private getScanLoadTime;
     private saveReport;
     private saveSbom;
     private saveTrimmedSbom;

package/dist/commands/scan/eol.js

@@ -1,9 +1,11 @@
 import { trimCdxBom } from '@herodevs/eol-shared';
 import { Command, Flags } from '@oclif/core';
 import ora from 'ora';
+import { ApiError } from "../../api/errors.js";
 import { submitScan } from "../../api/nes.client.js";
-import { config, filenamePrefix } from "../../config/constants.js";
+import { config, filenamePrefix, SCAN_ORIGIN_AUTOMATED, SCAN_ORIGIN_CLI } from "../../config/constants.js";
 import { track } from "../../service/analytics.svc.js";
+import { AUTH_ERROR_MESSAGES, getTokenForScanWithSource } from "../../service/auth.svc.js";
 import { createSbom } from "../../service/cdx.svc.js";
 import { countComponentsByStatus, formatDataPrivacyLink, formatReportSaveHint, formatScanResults, formatWebReportUrl, } from "../../service/display.svc.js";
 import { readSbomFromFile, saveArtifactToFile, validateDirectory } from "../../service/file.svc.js";
@@ -68,10 +70,19 @@ export default class ScanEol extends Command {
             default: false,
             description: 'Hide the generated web report URL for this scan',
         }),
+        automated: Flags.boolean({
+            default: false,
+            description: 'Mark scan as automated (for CI/CD pipelines)',
+        }),
         version: Flags.version(),
     };
     async run() {
         const { flags } = await this.parse(ScanEol);
+        const { source } = await getTokenForScanWithSource();
+        if (source === 'ci') {
+            this.log('CI credentials found');
+            this.log('Using CI credentials');
+        }
         track('CLI EOL Scan Started', (context) => ({
             command: context.command,
             command_flags: context.command_flags,
@@ -116,7 +127,6 @@ export default class ScanEol extends Command {
         }
         const scanStartTime = performance.now();
         const scan = await this.scanSbom(sbom);
-        const scanEndTime = performance.now();
         const componentCounts = countComponentsByStatus(scan);
         track('CLI EOL Scan Completed', (context) => ({
             command: context.command,
@@ -126,7 +136,7 @@ export default class ScanEol extends Command {
             nes_available_count: componentCounts.NES_AVAILABLE,
             number_of_packages: componentCounts.TOTAL,
             sbom_created: !flags.file,
-            scan_load_time: (scanEndTime - scanStartTime) / 1000,
+            scan_load_time: this.getScanLoadTime(scanStartTime),
             scanned_ecosystems: componentCounts.ECOSYSTEMS,
             web_report_link: !flags.hideReportUrl && scan.id ? `${config.eolReportUrl}/${scan.id}` : undefined,
             web_report_hidden: flags.hideReportUrl,
@@ -159,6 +169,8 @@ export default class ScanEol extends Command {
         return sbom;
     }
     async scanSbom(sbom) {
+        const scanStartTime = performance.now();
+        const numberOfPackages = sbom.components?.length ?? 0;
         const { flags } = await this.parse(ScanEol);
         const spinner = ora().start('Trimming SBOM');
         const trimmedSbom = trimCdxBom(sbom);
@@ -173,21 +185,39 @@ export default class ScanEol extends Command {
         }
         spinner.start('Scanning for EOL packages');
         try {
-            const scan = await submitScan({ sbom: trimmedSbom });
+            const scanOrigin = flags.automated ? SCAN_ORIGIN_AUTOMATED : SCAN_ORIGIN_CLI;
+            const scan = await submitScan({ sbom: trimmedSbom, scanOrigin });
             spinner.succeed('Scan completed');
             return scan;
         }
         catch (error) {
             spinner.fail('Scanning failed');
+            const scanLoadTime = this.getScanLoadTime(scanStartTime);
+            if (error instanceof ApiError) {
+                track('CLI EOL Scan Failed', (context) => ({
+                    command: context.command,
+                    command_flags: context.command_flags,
+                    scan_failure_reason: error.code,
+                    scan_load_time: scanLoadTime,
+                    number_of_packages: numberOfPackages,
+                }));
+                const message = AUTH_ERROR_MESSAGES[error.code] ?? error.message?.trim();
+                this.error(message);
+            }
             const errorMessage = getErrorMessage(error);
             track('CLI EOL Scan Failed', (context) => ({
                 command: context.command,
                 command_flags: context.command_flags,
                 scan_failure_reason: errorMessage,
+                scan_load_time: scanLoadTime,
+                number_of_packages: numberOfPackages,
             }));
             this.error(`Failed to submit scan to NES. ${errorMessage}`);
         }
     }
+    getScanLoadTime(scanStartTime) {
+        return (performance.now() - scanStartTime) / 1000;
+    }
     saveReport(report, dir, outputPath) {
         try {
             return saveArtifactToFile(dir, { kind: 'report', payload: report, outputPath });

package/dist/commands/tracker/run.d.ts

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+export default class Run extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        configDir: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        configFile: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    /**
+     * Fetches Git last commit
+     */
+    private fetchGitLastCommit;
+}