@cantinasecurity/apex-cli 0.1.17 → 0.1.18

package/dist/claim-proof.js

@@ -0,0 +1,65 @@
+const CLAIM_DEADLINE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/;
+function isLeapYear(year) {
+    return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+}
+function daysInMonth(year, month) {
+    if (month === 2)
+        return isLeapYear(year) ? 29 : 28;
+    return [4, 6, 9, 11].includes(month) ? 30 : 31;
+}
+/** Parses only the RFC3339 shape emitted by the onboarding API. */
+export function parseClaimDeadlineMs(value) {
+    if (typeof value !== "string")
+        return null;
+    const match = CLAIM_DEADLINE_PATTERN.exec(value);
+    if (!match)
+        return null;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = Number(match[6]);
+    const offset = match[7] ?? "";
+    if (year < 1 ||
+        month < 1 ||
+        month > 12 ||
+        day < 1 ||
+        day > daysInMonth(year, month) ||
+        hour > 23 ||
+        minute > 59 ||
+        second > 59) {
+        return null;
+    }
+    if (offset !== "Z") {
+        const offsetHour = Number(offset.slice(1, 3));
+        const offsetMinute = Number(offset.slice(4, 6));
+        if (offsetHour > 23 || offsetMinute > 59)
+            return null;
+    }
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/**
+ * Classifies the locally stored claim proof without mutating it.
+ *
+ * A missing or malformed deadline is treated conservatively as available: an
+ * older CLI or interrupted write may have left a valid proof without usable
+ * deadline metadata, and only the server can safely declare that proof dead.
+ * A known deadline is exclusive, so the proof expires exactly at that instant.
+ */
+export function getClaimProofState(credentials, nowMs = Date.now()) {
+    if (!credentials?.claimToken?.trim())
+        return "absent";
+    const rawDeadline = credentials.claimExpiresAt;
+    const deadline = typeof rawDeadline === "string" ? rawDeadline.trim() : "";
+    if (!deadline)
+        return "available";
+    const deadlineMs = parseClaimDeadlineMs(deadline);
+    if (deadlineMs === null || !Number.isFinite(nowMs))
+        return "available";
+    return deadlineMs > nowMs ? "available" : "expired";
+}
+export function isClaimProofAvailable(credentials, nowMs = Date.now()) {
+    return getClaimProofState(credentials, nowMs) === "available";
+}

package/dist/commands.js

@@ -1,11 +1,13 @@
 import { canPromptInteractively, getFlagList, getFlagString, isJsonMode, } from "./args.js";
-import { getMe, logout } from "./auth.js";
-import { ApiError } from "./api-client.js";
+import { getMe, login, logout } from "./auth.js";
+import { ApiError, formatApiError, getApiErrorCode, } from "./api-client.js";
 import { openInBrowser } from "./browser.js";
-import { loadConfig, saveConfig } from "./config.js";
+import { getClaimProofState, isClaimProofAvailable, parseClaimDeadlineMs, } from "./claim-proof.js";
+import { loadConfig, updateConfig } from "./config.js";
 import { createFindingComment, fetchScanExport, fetchScanFindings, isFindingUuid, normalizeFindingRef, resolveFindingSelection, resolveScanSelection, startFindingFixReviewScan, submitFindingFeedback, } from "./findings.js";
 import { prepareExplicitScanSources, supportsLegacyRemoteFlow, } from "./local-source-scan.js";
 import { logLine, printJson, withLoadingIndicator } from "./output.js";
+import { claimOnboardingSession, isProofOnlyOnboardingCredentials, redeemOnboardingCode, revokeGuestOnboardingSession, } from "./onboarding.js";
 import { confirm } from "./prompt.js";
 import { cancelScan, fetchScanProgress, fetchWorkspaceScans, findMostRelevantActiveScan, getScanDisplayLabel, getScanDisplayId, getTrackedScanId, isActiveScanStatus, matchesScanId, selectDefaultScanToCancel, } from "./scan.js";
 import { createServiceApiKey, isServiceApiScope, listServiceApiKeys, revokeServiceApiKey, SERVICE_API_SCOPES, } from "./service-keys.js";
@@ -13,7 +15,7 @@ import { chooseCompany, createWorkspaceBinding, ensureAuthenticated, remediateMi
 import { createWorkspaceBindingFromSummary, fetchCompanyCredits, fetchCompanyWorkspaces, findWorkspaceByRef, } from "./workspaces.js";
 import { loadWorkspaceBinding, saveWorkspaceBinding } from "./workspace-binding.js";
 import { commandSetup as runCliSetup } from "./setup.js";
-import { getTelemetryStatus, setTelemetryEnabled, } from "./telemetry.js";
+import { getTelemetryStatus, setTelemetryAuthKind, setTelemetryEnabled, setTelemetryOnboardingOutcome, } from "./telemetry.js";
 import { commandUpdate as runCliUpdate } from "./update.js";
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
@@ -54,13 +56,94 @@ const SERVICE_KEY_NAME_SCHEMA = z
     .min(1)
     .max(100)
     .refine((value) => !SERVICE_KEY_NAME_CONTROL_CHARACTER_PATTERN.test(value));
+function getRedeemTelemetryOutcome(error) {
+    switch (getApiErrorCode(error)) {
+        case "INVALID_CODE_FORMAT":
+        case "CODE_NOT_FOUND":
+            return "invalid";
+        case "CODE_EXPIRED":
+        case "CODE_REVOKED":
+        case "CODE_PAUSED":
+            return "expired";
+        case "CODE_EXHAUSTED":
+            return "exhausted";
+        case "RATE_LIMITED":
+            return "rate_limited";
+        case "TRIAL_CAPACITY":
+            return "capacity";
+        case "ACTIVE_GUEST_SESSION":
+            return "active_guest_session";
+        default:
+            return error instanceof Error && /trial code (?:format is invalid|is required)/i.test(error.message)
+                ? "invalid"
+                : "error";
+    }
+}
+function getClaimTelemetryOutcome(error) {
+    switch (getApiErrorCode(error)) {
+        case "CLAIM_INVALID":
+            return "invalid";
+        case "CLAIM_EXPIRED":
+            return "claim_expired";
+        case "ALREADY_CLAIMED":
+            return "already_claimed";
+        case "SCAN_IN_PROGRESS":
+            return "scan_in_progress";
+        case "EMAIL_UNVERIFIED":
+            return "email_unverified";
+        case "FINGERPRINT_MISMATCH":
+            return "fingerprint_mismatch";
+        default:
+            return "error";
+    }
+}
+async function getCommandAuthState(client, me) {
+    let credentials = null;
+    try {
+        credentials = await client.getCredentials();
+    }
+    catch {
+        // Local metadata is only for UX and telemetry; it must not break scan commands.
+    }
+    const guest = credentials?.guest === true || me.user.role?.trim().toLowerCase() === "guest";
+    return {
+        authKind: guest ? "guest" : "user",
+        // Ordinary device login intentionally keeps an unclaimed trial proof. Keep
+        // reminding the user after that auth-kind transition until claim consumes it.
+        guestCredentials: credentials &&
+            (credentials.guest === true || isClaimProofAvailable(credentials))
+            ? credentials
+            : null,
+    };
+}
+function logGuestScanFooter(authState, flags) {
+    if (isJsonMode(flags) || !authState.guestCredentials)
+        return;
+    const claimState = getClaimProofState(authState.guestCredentials);
+    if (claimState === "expired") {
+        logLine("Guest trial claim window expired — run 'apex login' to continue with a Cantina account.", flags);
+        return;
+    }
+    const deadlineTime = parseClaimDeadlineMs(authState.guestCredentials.claimExpiresAt);
+    const deadline = deadlineTime !== null
+        ? new Date(deadlineTime).toISOString()
+        : "the claim deadline";
+    if (claimState === "absent") {
+        logLine(`Guest trial claim proof is missing — run 'apex redeem <code>' again on this machine before ${deadline}, then run 'apex claim'.`, flags);
+        return;
+    }
+    const message = authState.authKind === "guest"
+        ? `Guest scan — create a Cantina account and run 'apex claim' by ${deadline} to keep it.`
+        : `Trial results are still unclaimed — run 'apex claim' by ${deadline} to keep them.`;
+    logLine(message, flags);
+}
+export function getRedeemExitCode(result) {
+    return result.redeemed ? 0 : 2;
+}
 async function saveCompanyDefault(companyId) {
     const config = await loadConfig();
     if (config.defaultCompanyId !== companyId) {
-        await saveConfig({
-            ...config,
-            defaultCompanyId: companyId,
-        });
+        await updateConfig({ defaultCompanyId: companyId });
     }
 }
 function formatCommandArgument(value) {
@@ -564,7 +647,13 @@ export async function initializeInteractiveSession(client, cwd, flags) {
     });
 }
 export async function commandLogin(client, flags) {
-    const me = await ensureAuthenticated(client, flags);
+    // Explicit login is the escape hatch from an unavailable guest session. It
+    // intentionally bypasses ordinary-command claim steering while preserving
+    // the proof for an authoritative `apex claim` attempt.
+    const me = await login(client, {
+        noOpen: flags["no-open"] === true,
+        quiet: isJsonMode(flags),
+    });
     if (isJsonMode(flags)) {
         printJson(me);
         return me;
@@ -572,6 +661,75 @@ export async function commandLogin(client, flags) {
     logLine(`Authenticated as ${me.user.username ?? me.user.id}`, flags);
     return me;
 }
+export async function commandRedeem(client, flags, code) {
+    try {
+        if (flags.replace === true) {
+            const warning = "Warning: --replace revokes the current guest trial and queues its unclaimed source, scans, and findings for deletion before redeeming the new code.";
+            if (isJsonMode(flags)) {
+                process.stderr.write(`${warning}\n`);
+            }
+            else {
+                logLine(warning, flags);
+            }
+        }
+        const result = await redeemOnboardingCode(client, {
+            code,
+            replace: flags.replace === true,
+        });
+        setTelemetryOnboardingOutcome(result.outcome);
+        if (isJsonMode(flags)) {
+            printJson(result);
+            return result;
+        }
+        if (!result.redeemed) {
+            logLine(`Trial redemption skipped: ${result.warning}.`, flags);
+            return result;
+        }
+        logLine(`Trial ${result.outcome}: ${result.grant.scans} standard scan${result.grant.scans === 1 ? "" : "s"}.`, flags);
+        logLine(`Guest session expires: ${result.guestSessionExpiresAt}`, flags);
+        logLine(`Claim deadline: ${result.claimDeadline}`, flags);
+        logLine(result.notice, flags);
+        logLine(`Terms and retention: ${result.termsUrl}`, flags);
+        return result;
+    }
+    catch (error) {
+        setTelemetryOnboardingOutcome(getRedeemTelemetryOutcome(error));
+        throw error;
+    }
+}
+export async function commandClaim(client, cwd, flags) {
+    const json = isJsonMode(flags);
+    try {
+        const result = await claimOnboardingSession(client, cwd, {
+            noOpen: json || flags["no-open"] === true,
+            quiet: json,
+            ...(json
+                ? {
+                    onVerification: async (login) => {
+                        process.stderr.write(`Complete Cantina account setup with code ${escapeTerminalControlCharacters(login.userCode)} at ${escapeTerminalControlCharacters(login.verificationUrl)}\n`);
+                    },
+                }
+                : {}),
+        });
+        setTelemetryOnboardingOutcome("claimed");
+        if (json) {
+            printJson(result);
+            return result;
+        }
+        logLine(`Claimed into: ${result.company.name ?? result.company.handle ?? result.company.id}`, flags);
+        if (result.scanUrl) {
+            logLine(`View: ${result.scanUrl}`, flags);
+        }
+        if (result.discountCode) {
+            logLine(`First credit-pack discount: ${result.discountCode}`, flags);
+        }
+        return result;
+    }
+    catch (error) {
+        setTelemetryOnboardingOutcome(getClaimTelemetryOutcome(error));
+        throw error;
+    }
+}
 export async function commandCredits(client, cwd, flags) {
     const me = await ensureAuthenticated(client, flags);
     const binding = await loadWorkspaceBinding(cwd);
@@ -607,10 +765,49 @@ export async function commandCredits(client, cwd, flags) {
     return payload;
 }
 export async function commandLogout(client, flags) {
-    await logout(client);
+    const credentials = await client.getCredentials().catch(() => null);
+    const proofOnly = isProofOnlyOnboardingCredentials(credentials);
+    const hasGuestLifecycle = credentials?.guest === true || proofOnly;
+    if (hasGuestLifecycle && flags.force !== true) {
+        if (!canPromptForConfirmation(flags)) {
+            throw new Error("Logging out revokes this guest trial and queues its unclaimed data for deletion. Re-run with --force to confirm.");
+        }
+        const approved = await confirm("Logging out revokes this guest trial and queues all unclaimed source, scans, and findings for deletion. Continue?", false);
+        if (!approved) {
+            logLine("Guest logout cancelled; the trial and claim proof were kept.", flags);
+            return {
+                loggedOut: false,
+                guestTrialRevoked: false,
+                confirmationRequired: true,
+            };
+        }
+    }
+    const guestTrialRevoked = hasGuestLifecycle
+        ? await revokeGuestOnboardingSession(client, {
+            clearLocalOnTerminal: true,
+            expectedCredentials: credentials ?? undefined,
+        })
+        : false;
+    if (!hasGuestLifecycle) {
+        await logout(client, credentials);
+    }
+    const serverRevocationUnavailable = hasGuestLifecycle && !guestTrialRevoked;
     if (!isJsonMode(flags)) {
-        logLine("Logged out", flags);
+        logLine(guestTrialRevoked
+            ? "Guest trial revoked; unclaimed trial data is queued for deletion."
+            : serverRevocationUnavailable
+                ? proofOnly
+                    ? "Guest trial proof cleared locally, but server revocation could not be confirmed."
+                    : "Guest access cleared locally, but the terminal server session could not be revoked."
+                : "Logged out", flags);
     }
+    return {
+        loggedOut: true,
+        guestTrialRevoked,
+        ...(serverRevocationUnavailable
+            ? { serverRevocationUnavailable: true }
+            : {}),
+    };
 }
 export async function commandServiceKeyCreate(client, flags) {
     const name = normalizeServiceKeyName(getFlagString(flags, "name"));
@@ -774,7 +971,7 @@ export async function commandDoctor(client, cwd, flags) {
         if (isJsonMode(flags)) {
             const payload = {
                 ok: false,
-                error: error instanceof Error ? error.message : String(error),
+                error: formatApiError(error),
             };
             printJson(payload);
             if (error instanceof Error) {
@@ -786,7 +983,9 @@ export async function commandDoctor(client, cwd, flags) {
     }
 }
 export async function commandStatus(client, cwd, flags) {
-    await ensureAuthenticated(client, flags);
+    const me = await ensureAuthenticated(client, flags);
+    const authState = await getCommandAuthState(client, me);
+    setTelemetryAuthKind(authState.authKind);
     const binding = await requireWorkspaceBinding(cwd);
     const requestedScanId = getFlagString(flags, "scan");
     const scanId = requestedScanId ?? binding.lastScanId;
@@ -807,6 +1006,7 @@ export async function commandStatus(client, cwd, flags) {
     if (binding.lastScanUrl && (!requestedScanId || requestedScanId === binding.lastScanId)) {
         logLine(`View: ${binding.lastScanUrl}`, flags);
     }
+    logGuestScanFooter(authState, flags);
     return { binding, scanId, progress };
 }
 export async function commandConnect(client, cwd, flags, provider) {
@@ -838,6 +1038,8 @@ export async function commandScan(client, cwd, flags) {
         throw new Error("PR scans require at least one --pr <number> selection.");
     }
     const me = await ensureAuthenticated(client, flags);
+    const authState = await getCommandAuthState(client, me);
+    setTelemetryAuthKind(authState.authKind);
     const selection = await selectWorkspaceTarget(cwd, me, flags);
     const result = await withLoadingIndicator("Resolving workspace and scan plan...", flags, () => resolveWorkspaceSelection(client, selection));
     if (!result.resolve.workspaceId) {
@@ -920,14 +1122,19 @@ export async function commandScan(client, cwd, flags) {
             });
         });
     }
+    const trackedScanId = getTrackedScanId(scan);
     const binding = {
         ...createWorkspaceBinding(result, result.binding),
         workspaceId,
-        lastScanId: getTrackedScanId(scan),
+        lastScanId: trackedScanId,
         lastScanUrl: scan.scanUrl ?? null,
     };
-    await saveWorkspaceBinding(cwd, binding);
-    await saveCompanyDefault(result.company.id);
+    const [workspaceBindingWrite, companyDefaultWrite] = await Promise.allSettled([
+        Promise.resolve().then(() => saveWorkspaceBinding(cwd, binding)),
+        Promise.resolve().then(() => saveCompanyDefault(result.company.id)),
+    ]);
+    const workspaceBindingSaved = workspaceBindingWrite.status === "fulfilled";
+    const companyDefaultSaved = companyDefaultWrite.status === "fulfilled";
     const summarySources = prScanSource
         ? getPrScanSelectedSources(result.sources, prScanSource)
         : result.sources;
@@ -946,6 +1153,14 @@ export async function commandScan(client, cwd, flags) {
             apexScanId: scan.apexScanId ?? scan.bedrockScanId ?? null,
         },
         binding,
+        ...(!workspaceBindingSaved || !companyDefaultSaved
+            ? {
+                localPersistence: {
+                    workspaceBindingSaved,
+                    companyDefaultSaved,
+                },
+            }
+            : {}),
     };
     if (isJsonMode(flags)) {
         printJson(payload);
@@ -954,16 +1169,31 @@ export async function commandScan(client, cwd, flags) {
     logLine(`Authenticated as ${me.user.username ?? me.user.id}`, flags);
     logLine(`Company: ${result.company.handle ?? result.company.id}`, flags);
     logLine(`Workspace: ${result.workspaceName}`, flags);
+    if (!workspaceBindingSaved) {
+        logLine(`Warning: the scan started, but Apex could not save this directory's workspace binding. Keep scan ID ${trackedScanId ?? "from the result"}; repair local repository permissions and bind this directory again before using status or findings commands here.`, flags);
+    }
+    if (!companyDefaultSaved) {
+        logLine("Warning: the scan started, but Apex could not save the default company. Pass --company explicitly until local Apex config permissions are repaired.", flags);
+    }
     logLine(`Sources selected: ${summarySources.length}`, flags);
     logLine(`Plan: ${summaryPlannedSources.length - localSnapshotCount} remote, ${localSnapshotCount} local snapshot`, flags);
-    logLine(`Scan: ${scan.status}${getTrackedScanId(scan) ? ` (${getTrackedScanId(scan)})` : ""}`, flags);
+    logLine(`Scan: ${scan.status}${trackedScanId ? ` (${trackedScanId})` : ""}`, flags);
     if (scan.scanUrl) {
         logLine(`View: ${scan.scanUrl}`, flags);
     }
     if (scan.fullScanRecommendation) {
         logLine(`Recommendation: ${scan.fullScanRecommendation}`, flags);
     }
-    logLine("Next: run `apex status` to watch progress, then `apex findings` when the scan finishes.", flags);
+    if (workspaceBindingSaved) {
+        logLine("Next: run `apex status` to watch progress, then `apex findings` when the scan finishes.", flags);
+    }
+    else if (trackedScanId) {
+        logLine(`Next: repair local repository permissions, run \`apex workspace use ${workspaceId}\`, then use \`apex status --scan ${trackedScanId}\` and \`apex findings --scan ${trackedScanId}\`.`, flags);
+    }
+    else {
+        logLine(`Next: repair local repository permissions, then run \`apex workspace use ${workspaceId}\` before using status or findings.`, flags);
+    }
+    logGuestScanFooter(authState, flags);
     return payload;
 }
 export async function commandWorkspaces(client, cwd, flags) {
@@ -1161,7 +1391,9 @@ export async function commandCancelScan(client, cwd, flags, requestedScanId) {
     return payload;
 }
 export async function commandFindings(client, cwd, flags) {
-    await ensureAuthenticated(client, flags);
+    const me = await ensureAuthenticated(client, flags);
+    const authState = await getCommandAuthState(client, me);
+    setTelemetryAuthKind(authState.authKind);
     const binding = await requireWorkspaceBinding(cwd);
     const { scan, response } = await withLoadingIndicator("Loading findings...", flags, async () => {
         const scan = await resolveScanSelection({
@@ -1190,6 +1422,7 @@ export async function commandFindings(client, cwd, flags) {
     logLine(`Scan: ${response.scan.displayName} (${response.scan.status})`, flags);
     if (response.findings.length === 0) {
         logLine("Findings: none for this scan.", flags);
+        logGuestScanFooter(authState, flags);
         return payload;
     }
     for (const finding of response.findings) {
@@ -1199,6 +1432,7 @@ export async function commandFindings(client, cwd, flags) {
             logLine(`View: ${finding.findingUrl}`, flags);
         }
     }
+    logGuestScanFooter(authState, flags);
     return payload;
 }
 export async function commandFindingComment(client, cwd, flags, requestedFindingRef, content, parentCommentId) {