@cantinasecurity/apex-cli 0.1.16 → 0.1.18

package/dist/onboarding.js

@@ -0,0 +1,661 @@
+import { createHash, randomBytes } from "node:crypto";
+import { loginWithoutPersist } from "./auth.js";
+import { isClaimProofAvailable } from "./claim-proof.js";
+import { ApiError, getApiErrorCode, redactSensitiveText, } from "./api-client.js";
+import { clearCredentialsIfCurrent, clearGuestFieldsIfClaimTokenMatches, getOrCreateConfigString, loadConfig, loadCredentials, replaceCredentialsIfCurrent, updateConfig, withCredentialLifecycleLock, } from "./config.js";
+import { APEX_CLI_VERSION } from "./version.js";
+import { loadWorkspaceBinding, saveWorkspaceBinding } from "./workspace-binding.js";
+const ONBOARDING_CODE_PATTERN = /^SPBT-[A-Z0-9]{2,24}-[A-Z0-9]{8}$/;
+const ONBOARDING_FINGERPRINT_PATTERN = /^[a-f0-9]{64}$/;
+const DEFAULT_CLIENT_NAME = "apex";
+const HOSTED_APEX_ORIGIN = "https://ai.cantina.xyz";
+function assertHostedOnboardingOrigin(baseUrl) {
+    const configuredUrl = new URL(baseUrl);
+    if (configuredUrl.origin !== HOSTED_APEX_ORIGIN) {
+        throw new Error(`Trial onboarding only works against ${HOSTED_APEX_ORIGIN} — this CLI is configured for ${configuredUrl.host}`);
+    }
+}
+function isGuestClaimLandingUrl(value, baseUrl) {
+    if (!value)
+        return false;
+    try {
+        const pathname = new URL(value, baseUrl).pathname.replace(/\/+$/u, "");
+        return pathname === "/apex/claim";
+    }
+    catch {
+        return false;
+    }
+}
+function parseCliVersion(version) {
+    const match = version.trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/u);
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+export function compareCliVersions(left, right) {
+    const leftParts = parseCliVersion(left);
+    const rightParts = parseCliVersion(right);
+    if (!leftParts || !rightParts) {
+        throw new Error("Apex returned an invalid minimum CLI version requirement.");
+    }
+    for (let index = 0; index < leftParts.length; index += 1) {
+        const difference = leftParts[index] - rightParts[index];
+        if (difference !== 0)
+            return Math.sign(difference);
+    }
+    return 0;
+}
+function assertSupportedCliVersion(minimumCliVersion) {
+    if (!minimumCliVersion)
+        return;
+    if (compareCliVersions(APEX_CLI_VERSION, minimumCliVersion) < 0) {
+        throw new Error(`This trial requires Apex CLI ${minimumCliVersion} or newer (current: ${APEX_CLI_VERSION}). Upgrade with \`npm install -g @cantinasecurity/apex-cli@latest\`, then run \`apex redeem\` again.`);
+    }
+}
+export function resolveOnboardingCode(code) {
+    const normalized = (code ?? process.env.APEX_ONBOARDING_CODE ?? "")
+        .trim()
+        .toUpperCase();
+    if (!normalized) {
+        throw new Error("A Cantina trial code is required. Pass it to `apex redeem` or set APEX_ONBOARDING_CODE.");
+    }
+    if (!ONBOARDING_CODE_PATTERN.test(normalized)) {
+        throw new Error("The Cantina trial code format is invalid.");
+    }
+    return normalized;
+}
+export function getLocalTrialStatus(credentials, nowMs = Date.now()) {
+    return {
+        guest: credentials?.guest === true,
+        guestSessionExpiresAt: credentials?.guestSessionExpiresAt ?? null,
+        claimDeadline: credentials?.claimExpiresAt ?? null,
+        claimAvailable: isClaimProofAvailable(credentials, nowMs),
+    };
+}
+export function isProofOnlyOnboardingCredentials(credentials) {
+    return Boolean(credentials?.guest !== true &&
+        credentials?.claimToken?.trim() &&
+        !credentials.accessToken?.trim() &&
+        !credentials.refreshToken?.trim());
+}
+function hasStoredAccountSession(credentials) {
+    return Boolean(credentials &&
+        credentials.guest !== true &&
+        (credentials.accessToken.trim() || credentials.refreshToken.trim()));
+}
+export async function getOrCreateOnboardingFingerprint() {
+    return getOrCreateConfigString("onboardingFingerprint", (value) => {
+        const normalized = typeof value === "string"
+            ? value.trim().toLowerCase()
+            : "";
+        return ONBOARDING_FINGERPRINT_PATTERN.test(normalized)
+            ? normalized
+            : null;
+    }, () => randomBytes(32).toString("hex"));
+}
+async function clearRevokedGuestCredentials(credentials) {
+    if (await clearCredentialsIfCurrent(credentials))
+        return;
+    const claimToken = credentials.claimToken?.trim() ?? "";
+    if (claimToken) {
+        await clearGuestFieldsIfClaimTokenMatches(claimToken);
+    }
+    throw new Error("Apex credentials changed while the guest trial was being revoked. The server trial was revoked and the newer credentials were kept; retry the command before continuing.");
+}
+async function revokeGuestOnboardingSessionUnlocked(client, options = {}) {
+    const credentials = options.expectedCredentials ?? await loadCredentials();
+    if (credentials?.guest !== true && !credentials?.claimToken?.trim()) {
+        return false;
+    }
+    const claimToken = credentials.claimToken?.trim() ?? "";
+    const config = await loadConfig();
+    assertHostedOnboardingOrigin(config.baseUrl);
+    const fingerprint = config.onboardingFingerprint?.trim().toLowerCase() ?? "";
+    const proof = claimToken && ONBOARDING_FINGERPRINT_PATTERN.test(fingerprint)
+        ? { claimToken, fingerprint }
+        : null;
+    const proofOnly = isProofOnlyOnboardingCredentials(credentials);
+    let bearerTerminalError = null;
+    if (credentials.guest === true) {
+        try {
+            await client.request("/api/cli/v1/onboarding/revoke", {
+                method: "POST",
+                auth: false,
+                bearerToken: credentials.accessToken,
+                retryOnUnauthorized: false,
+                telemetryAttribution: false,
+                requestBaseUrl: config.baseUrl,
+                ...(proof ? { json: proof } : {}),
+            });
+            await clearRevokedGuestCredentials(credentials);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof ApiError &&
+                [
+                    "GUEST_SESSION_EXPIRED",
+                    "GUEST_SESSION_REVOKED",
+                    "GUEST_SESSION_CLAIMED",
+                ].includes(error.code ?? "")) {
+                bearerTerminalError = error;
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    if (bearerTerminalError?.code === "GUEST_SESSION_REVOKED") {
+        await clearRevokedGuestCredentials(credentials);
+        return true;
+    }
+    if (proof &&
+        (credentials.guest !== true ||
+            bearerTerminalError?.code === "GUEST_SESSION_EXPIRED")) {
+        try {
+            await client.request("/api/cli/v1/onboarding/revoke", {
+                method: "POST",
+                auth: false,
+                retryOnUnauthorized: false,
+                telemetryAttribution: false,
+                requestBaseUrl: config.baseUrl,
+                json: proof,
+            });
+        }
+        catch (error) {
+            if (!((proofOnly || bearerTerminalError?.code === "GUEST_SESSION_EXPIRED") &&
+                options.clearLocalOnTerminal &&
+                error instanceof ApiError &&
+                error.code === "GUEST_SESSION_INVALID")) {
+                throw error;
+            }
+            const cleared = await clearCredentialsIfCurrent(credentials);
+            if (!cleared) {
+                throw new Error("Apex credentials changed while the stale trial proof was being cleared. The newer credentials were kept; retry logout before continuing.");
+            }
+            return false;
+        }
+        await clearRevokedGuestCredentials(credentials);
+        return true;
+    }
+    if (proofOnly && options.clearLocalOnTerminal) {
+        // Explicitly confirmed logout may discard an unverifiable proof-only stub.
+        // This changes local state only; server retention remains authoritative.
+        const cleared = await clearCredentialsIfCurrent(credentials);
+        if (!cleared) {
+            throw new Error("Apex credentials changed while the unverifiable trial proof was being cleared. The newer credentials were kept; retry logout before continuing.");
+        }
+        return false;
+    }
+    if (bearerTerminalError && options.clearLocalOnTerminal) {
+        // Explicit logout may clear unusable local bearer state when there is no
+        // proof available for a server-side revoke. The generation check protects
+        // any login that completed while the revoke request was in flight.
+        const cleared = await clearCredentialsIfCurrent(credentials, bearerTerminalError.code === "GUEST_SESSION_EXPIRED"
+            ? { preserveClaimProof: true }
+            : {});
+        if (!cleared) {
+            throw new Error("Apex credentials changed while terminal guest access was being cleared. The newer credentials were kept; retry logout before continuing.");
+        }
+        return false;
+    }
+    if (bearerTerminalError)
+        throw bearerTerminalError;
+    throw new Error("The stored trial claim proof cannot be verified on this machine. Run `apex claim` before replacing the trial.");
+}
+export function revokeGuestOnboardingSession(client, options = {}) {
+    return withCredentialLifecycleLock(() => revokeGuestOnboardingSessionUnlocked(client, options));
+}
+class RedeemedGuestRecoveryFailure extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RedeemedGuestRecoveryFailure";
+    }
+}
+function sanitizedError(error) {
+    return new Error(redactSensitiveText(error instanceof Error ? error.message : String(error)));
+}
+function buildRedeemedGuestCredentials(redeemed, codeHash, claimToken) {
+    return {
+        accessToken: redeemed.accessToken,
+        refreshToken: redeemed.refreshToken,
+        accessTokenExpiresAt: redeemed.accessTokenExpiresAt,
+        refreshTokenExpiresAt: redeemed.refreshTokenExpiresAt,
+        issuerOrigin: HOSTED_APEX_ORIGIN,
+        guest: true,
+        guestCompanyId: redeemed.company.id,
+        ...(claimToken ? { claimToken } : {}),
+        claimExpiresAt: redeemed.claimDeadline,
+        guestSessionExpiresAt: redeemed.guestSessionExpiresAt,
+        onboardingCodeHash: codeHash,
+    };
+}
+async function revokeRedeemedGuestByBearer(client, redeemed, requestBaseUrl) {
+    await client.request("/api/cli/v1/onboarding/revoke", {
+        method: "POST",
+        auth: false,
+        bearerToken: redeemed.accessToken,
+        retryOnUnauthorized: false,
+        telemetryAttribution: false,
+        requestBaseUrl,
+    });
+}
+/**
+ * A successful redeem creates the server guest before the CLI can validate the
+ * version gate or mint a claim proof. Preserve that bearer generation so the
+ * user can finish setup (or explicitly replace/revoke it). If another auth
+ * lifecycle won the local CAS, revoke this response instead; a same-guest
+ * winner is already a locally actionable handle to the one server lifecycle.
+ */
+async function recoverRedeemedGuestAfterSetupFailure(client, expectedCredentials, redeemed, codeHash, requestBaseUrl) {
+    const recoveryCredentials = buildRedeemedGuestCredentials(redeemed, codeHash);
+    let committed;
+    try {
+        committed = await replaceCredentialsIfCurrent(expectedCredentials, recoveryCredentials);
+    }
+    catch {
+        // A write can throw after its atomic rename (for example, on the final
+        // chmod). Reload before deciding whether the response guest lacks a local
+        // handle. Never revoke here: if storage truly failed before persistence,
+        // the still-active server guest remains recoverable by redeeming the same
+        // campaign code again on this fingerprint.
+        const persisted = await loadCredentials().catch(() => null);
+        const persistedGuestCompanyId = persisted?.guestCompanyId?.trim() ?? "";
+        if (persisted?.guest === true &&
+            persisted.refreshToken === recoveryCredentials.refreshToken &&
+            persistedGuestCompanyId === redeemed.company.id) {
+            await updateConfig({ defaultCompanyId: redeemed.company.id }).catch(() => undefined);
+            return "saved";
+        }
+        if (persisted?.guest === true &&
+            (persistedGuestCompanyId.length === 0 ||
+                persistedGuestCompanyId === redeemed.company.id)) {
+            return "newer_guest_kept";
+        }
+        let staleProofCleanupFailed = false;
+        if (hasStoredAccountSession(persisted)) {
+            const staleClaimToken = expectedCredentials?.claimToken?.trim() ?? "";
+            if (staleClaimToken) {
+                try {
+                    await clearGuestFieldsIfClaimTokenMatches(staleClaimToken);
+                }
+                catch {
+                    staleProofCleanupFailed = true;
+                }
+            }
+        }
+        if (hasStoredAccountSession(persisted)) {
+            throw new RedeemedGuestRecoveryFailure(staleProofCleanupFailed
+                ? "A newer Cantina account session was kept, but Apex could not remove its stale trial proof after local guest persistence failed. The server guest remains active. Run `apex logout`, then retry the same `apex redeem <code>` command; contact support if recovery still fails."
+                : "A newer Cantina account session was kept while local guest persistence failed. The server guest remains active. Finish or log out of that account session, then retry the same `apex redeem <code>` command; contact support if recovery still fails.");
+        }
+        if (persisted?.guest === true) {
+            throw new RedeemedGuestRecoveryFailure("A different local guest session was kept while persistence failed. The server guest created by this redeem remains active. Finish or log out of the local guest, then retry the same `apex redeem <code>` command; contact support if recovery still fails.");
+        }
+        try {
+            // If a different proof lifecycle remains, fail closed rather than
+            // deleting it. The same-code server lifecycle is still recoverable.
+            if (expectedCredentials?.claimToken?.trim()) {
+                await clearGuestFieldsIfClaimTokenMatches(expectedCredentials.claimToken.trim());
+            }
+        }
+        catch {
+            throw new RedeemedGuestRecoveryFailure("Local guest persistence failed and Apex could not clear the stale trial proof. The server guest remains active. Run `apex logout`, then retry the same `apex redeem <code>` command; contact support if recovery still fails.");
+        }
+        throw new RedeemedGuestRecoveryFailure("Local guest persistence failed, but the server guest remains active. Retry the same `apex redeem <code>` command to recover it; contact support if recovery still fails.");
+    }
+    if (committed.saved) {
+        // The credential file is the recovery invariant. A best-effort default
+        // company update must not make an actionable guest look orphaned or cause
+        // cleanup to revoke the session we just saved.
+        await updateConfig({ defaultCompanyId: redeemed.company.id }).catch(() => undefined);
+        return "saved";
+    }
+    const winnerIsGuest = committed.credentials?.guest === true;
+    const winnerGuestCompanyId = committed.credentials?.guestCompanyId?.trim() ?? "";
+    if (winnerIsGuest &&
+        (winnerGuestCompanyId.length === 0 ||
+            winnerGuestCompanyId === redeemed.company.id)) {
+        return "newer_guest_kept";
+    }
+    if (!winnerIsGuest) {
+        const staleClaimToken = expectedCredentials?.claimToken?.trim() ?? "";
+        if (staleClaimToken) {
+            try {
+                await clearGuestFieldsIfClaimTokenMatches(staleClaimToken);
+            }
+            catch {
+                // Keep the response guest active when local proof cleanup cannot be
+                // made durable. Once storage is writable, logging out the account and
+                // re-redeeming the same code can rotate the invalid proof safely.
+                throw new RedeemedGuestRecoveryFailure("A newer Cantina account session was kept, but Apex could not remove its stale trial proof. The server guest remains active. Repair local Apex config permissions, finish or log out of the account, then retry the same `apex redeem <code>` command; contact support if recovery still fails.");
+            }
+        }
+    }
+    try {
+        await revokeRedeemedGuestByBearer(client, redeemed, requestBaseUrl);
+    }
+    catch {
+        throw new RedeemedGuestRecoveryFailure("A newer local account or different guest session was kept, and Apex could not confirm cleanup of the incomplete server guest. Do not assume this trial code is reusable. Finish or log out of the newer local session, then use the Cantina account or contact support to recover or clear the guest before trying another code.");
+    }
+    return "revoked";
+}
+function redeemRecoveryError(error, outcome) {
+    const originalMessage = redactSensitiveText(error instanceof Error ? error.message : String(error));
+    let guidance;
+    if (outcome === "saved") {
+        guidance =
+            "The guest session was saved locally; retry the same `apex redeem <code>` command to finish claim-proof setup, or use `--replace` with a different code to revoke it first.";
+    }
+    else if (outcome === "newer_guest_kept") {
+        guidance =
+            "Newer local guest credentials were kept; retry the redeem command from that credential state.";
+    }
+    else {
+        guidance =
+            "The incomplete guest session was revoked. This trial code is consumed on this machine; use a Cantina account, another trial code, or contact support.";
+    }
+    return new Error(`${originalMessage} ${guidance}`);
+}
+async function throwAfterRedeemedGuestSetupFailure(setupError, client, expectedCredentials, redeemed, codeHash, requestBaseUrl) {
+    let recovery;
+    try {
+        recovery = await recoverRedeemedGuestAfterSetupFailure(client, expectedCredentials, redeemed, codeHash, requestBaseUrl);
+    }
+    catch (recoveryError) {
+        const setupMessage = redactSensitiveText(setupError instanceof Error ? setupError.message : String(setupError));
+        const recoveryGuidance = recoveryError instanceof RedeemedGuestRecoveryFailure
+            ? redactSensitiveText(recoveryError.message)
+            : "Apex could not save the guest or confirm server cleanup. Do not assume this trial code is reusable; use a Cantina account or contact support before trying another code.";
+        throw new AggregateError([sanitizedError(setupError), sanitizedError(recoveryError)], `${setupMessage} ${recoveryGuidance}`);
+    }
+    throw redeemRecoveryError(setupError, recovery);
+}
+async function throwAfterTerminalClaimTokenFailure(error, expectedCredentials) {
+    const staleClaimToken = expectedCredentials?.claimToken?.trim() ?? "";
+    let clearedExpectedGeneration = false;
+    if (expectedCredentials) {
+        try {
+            // An active guest must lose its terminal bearer pair as one unit. Merely
+            // stripping guest metadata would leave revoked tokens looking like a
+            // Cantina account session to hasStoredAccountSession().
+            clearedExpectedGeneration = await clearCredentialsIfCurrent(expectedCredentials);
+        }
+        catch {
+            throw new Error("The guest became terminal before Apex could mint a new claim proof, and its exact local credential generation could not be removed. Repair local Apex config permissions, run `apex logout`, then log in with the claimed Cantina account or contact support; this trial code cannot be redeemed again on this machine.");
+        }
+    }
+    if (!clearedExpectedGeneration && staleClaimToken) {
+        try {
+            // A newer account login can win after the observed guest generation and
+            // preserve only its stale proof fields. Strip those fields without
+            // touching the winning account token pair.
+            await clearGuestFieldsIfClaimTokenMatches(staleClaimToken);
+        }
+        catch {
+            throw new Error("The guest became terminal before Apex could mint a new claim proof, and its stale proof could not be removed from newer account credentials. Repair local Apex config permissions, then log in with the claimed Cantina account or contact support; this trial code cannot be redeemed again on this machine.");
+        }
+    }
+    const originalMessage = redactSensitiveText(error instanceof Error ? error.message : String(error));
+    const code = getApiErrorCode(error);
+    const guidance = code === "GUEST_SESSION_CLAIMED"
+        ? "The guest was claimed before claim-proof setup finished. Run `apex login` to use the claimed Cantina account; this trial code cannot be redeemed again on this machine."
+        : "The guest expired or was revoked before claim-proof setup finished. This trial code cannot be redeemed again on this machine; use a Cantina account, another trial code, or contact support.";
+    throw new Error(`${originalMessage} ${guidance}`);
+}
+async function clearTerminalClaimState(expectedCredentials, claimToken) {
+    if (expectedCredentials?.guest === true &&
+        await clearCredentialsIfCurrent(expectedCredentials)) {
+        return;
+    }
+    // A concurrent account login may have preserved this proof while replacing
+    // the guest bearer pair. In that case remove only the consumed proof; never
+    // clear the newer account generation.
+    await clearGuestFieldsIfClaimTokenMatches(claimToken);
+}
+async function redeemOnboardingCodeUnlocked(client, options = {}) {
+    const code = resolveOnboardingCode(options.code);
+    const config = await loadConfig();
+    assertHostedOnboardingOrigin(config.baseUrl);
+    const codeHash = createHash("sha256").update(code).digest("hex");
+    const fingerprint = await getOrCreateOnboardingFingerprint();
+    const existingCredentials = await loadCredentials();
+    const hasGuestCredentials = existingCredentials?.guest === true;
+    const claimProofAvailable = isClaimProofAvailable(existingCredentials);
+    if (hasStoredAccountSession(existingCredentials)) {
+        return {
+            outcome: "already_authenticated",
+            redeemed: false,
+            warning: "the next scan would use your account's paid credits",
+        };
+    }
+    if ((hasGuestCredentials || claimProofAvailable) &&
+        existingCredentials?.onboardingCodeHash !== codeHash &&
+        options.replace !== true) {
+        throw new Error(claimProofAvailable
+            ? "This machine still holds an unclaimed Apex trial. Run `apex claim` to keep it, or re-run with `--replace` to revoke it and queue its data for deletion."
+            : "This machine still holds an Apex guest trial without a usable local claim proof. Re-run its original code to recover it, or re-run this different code with `--replace` to revoke the guest and queue its data for deletion.");
+    }
+    if (options.replace === true &&
+        existingCredentials?.onboardingCodeHash === codeHash) {
+        throw new Error("`--replace` is only for a different trial code. Re-run this same code without `--replace` for an idempotent retry.");
+    }
+    let expectedCredentials = existingCredentials;
+    if (options.replace === true &&
+        (existingCredentials?.guest === true || existingCredentials?.claimToken?.trim())) {
+        await revokeGuestOnboardingSessionUnlocked(client, {
+            expectedCredentials: existingCredentials,
+        });
+        expectedCredentials = null;
+    }
+    const redeemed = await client.request("/api/cli/v1/onboarding/redeem", {
+        method: "POST",
+        auth: false,
+        retryOnUnauthorized: false,
+        telemetryAttribution: false,
+        json: {
+            code,
+            fingerprint,
+            clientName: options.clientName ?? DEFAULT_CLIENT_NAME,
+            clientVersion: options.clientVersion ?? APEX_CLI_VERSION,
+        },
+        requestBaseUrl: config.baseUrl,
+    });
+    try {
+        assertSupportedCliVersion(redeemed.minimumCliVersion);
+    }
+    catch (error) {
+        return throwAfterRedeemedGuestSetupFailure(error, client, expectedCredentials, redeemed, codeHash, config.baseUrl);
+    }
+    let claimToken;
+    try {
+        const claim = await client.request("/api/cli/v1/onboarding/claim-token", {
+            method: "POST",
+            auth: false,
+            bearerToken: redeemed.accessToken,
+            retryOnUnauthorized: false,
+            telemetryAttribution: false,
+            requestBaseUrl: config.baseUrl,
+        });
+        claimToken = claim.claimToken;
+    }
+    catch (error) {
+        if ([
+            "GUEST_SESSION_REVOKED",
+            "GUEST_SESSION_CLAIMED",
+            "GUEST_SESSION_EXPIRED",
+        ].includes(getApiErrorCode(error) ?? "")) {
+            return throwAfterTerminalClaimTokenFailure(error, expectedCredentials);
+        }
+        return throwAfterRedeemedGuestSetupFailure(error, client, expectedCredentials, redeemed, codeHash, config.baseUrl);
+    }
+    const nextCredentials = buildRedeemedGuestCredentials(redeemed, codeHash, claimToken);
+    const committed = await replaceCredentialsIfCurrent(expectedCredentials, nextCredentials);
+    if (!committed.saved) {
+        const winnerIsGuest = committed.credentials?.guest === true;
+        const winnerGuestCompanyId = committed.credentials?.guestCompanyId?.trim() ?? "";
+        const shouldRevokeDiscardedGuest = !winnerIsGuest ||
+            (winnerGuestCompanyId.length > 0 &&
+                winnerGuestCompanyId !== redeemed.company.id);
+        if (!winnerIsGuest) {
+            const staleClaimToken = expectedCredentials?.claimToken?.trim() ?? "";
+            if (staleClaimToken) {
+                await clearGuestFieldsIfClaimTokenMatches(staleClaimToken);
+            }
+        }
+        // Same-code idempotent redeems share a guest tenant/session even though
+        // claim proofs rotate. Revoke the discarded proof only when the winner is
+        // an account or has a known, different guest tenant identity.
+        if (shouldRevokeDiscardedGuest) {
+            await client.request("/api/cli/v1/onboarding/revoke", {
+                method: "POST",
+                auth: false,
+                retryOnUnauthorized: false,
+                telemetryAttribution: false,
+                requestBaseUrl: config.baseUrl,
+                json: { claimToken, fingerprint },
+            });
+        }
+        if (winnerIsGuest) {
+            throw new Error(shouldRevokeDiscardedGuest
+                ? "Guest credentials changed while this code was being redeemed. The discarded guest trial was revoked and this trial code is consumed; use the newer guest, another trial code, or contact support."
+                : "Guest credentials changed while this code was being redeemed. The newer credentials were kept; retry after that operation finishes.");
+        }
+        else {
+            throw new Error("Apex credentials changed while the trial was being redeemed. The new guest trial was revoked and this trial code is consumed; use the winning Cantina account, another trial code, or contact support.");
+        }
+    }
+    // Credentials and claim proof are already durable. Default-company
+    // convenience must not turn a successful redemption into a reported failure.
+    await updateConfig({ defaultCompanyId: redeemed.company.id }).catch(() => undefined);
+    return {
+        outcome: redeemed.outcome,
+        redeemed: true,
+        guestSessionExpiresAt: redeemed.guestSessionExpiresAt,
+        claimDeadline: redeemed.claimDeadline,
+        company: redeemed.company,
+        grant: redeemed.grant,
+        termsUrl: redeemed.termsUrl,
+        notice: redeemed.notice,
+        ...(redeemed.minimumCliVersion
+            ? { minimumCliVersion: redeemed.minimumCliVersion }
+            : {}),
+    };
+}
+export function redeemOnboardingCode(client, options = {}) {
+    return withCredentialLifecycleLock(() => redeemOnboardingCodeUnlocked(client, options));
+}
+async function claimOnboardingSessionUnlocked(client, cwd, options = {}) {
+    let expectedCredentials = await loadCredentials();
+    const config = await loadConfig();
+    assertHostedOnboardingOrigin(config.baseUrl);
+    const claimToken = expectedCredentials?.claimToken?.trim() ?? "";
+    const fingerprint = config.onboardingFingerprint?.trim().toLowerCase() ?? "";
+    if (!claimToken || !ONBOARDING_FINGERPRINT_PATTERN.test(fingerprint)) {
+        throw new Error("No Apex trial claim proof is stored on this machine. If the guest session is still active, run `apex redeem <code>` again here, then run `apex claim`.");
+    }
+    let accountAccessToken = null;
+    if (hasStoredAccountSession(expectedCredentials)) {
+        accountAccessToken = await client.getAccessToken(expectedCredentials);
+        const refreshedCredentials = await loadCredentials();
+        if (!refreshedCredentials ||
+            refreshedCredentials?.claimToken?.trim() !== claimToken) {
+            throw new Error("Apex credentials changed before the trial claim started. Re-run `apex claim`.");
+        }
+        if (accountAccessToken && !hasStoredAccountSession(refreshedCredentials)) {
+            throw new Error("Apex credentials changed before the trial claim started. Re-run `apex claim`.");
+        }
+        if (accountAccessToken &&
+            refreshedCredentials.accessToken !== accountAccessToken) {
+            throw new Error("Apex credentials changed before the trial claim started. Re-run `apex claim`.");
+        }
+        // getAccessToken may rotate the account token pair. Compare-and-swap from
+        // that refreshed (or proof-only) generation so claim cannot overwrite a
+        // later login.
+        expectedCredentials = refreshedCredentials;
+    }
+    if (!accountAccessToken) {
+        const accountCredentials = await loginWithoutPersist(client, {
+            noOpen: options.noOpen,
+            quiet: options.quiet,
+            onVerification: options.onVerification,
+            requestBaseUrl: config.baseUrl,
+        });
+        accountAccessToken = accountCredentials.accessToken;
+    }
+    let claimed;
+    try {
+        claimed = await client.request("/api/cli/v1/onboarding/claim", {
+            method: "POST",
+            auth: false,
+            bearerToken: accountAccessToken,
+            retryOnUnauthorized: false,
+            telemetryAttribution: false,
+            requestBaseUrl: config.baseUrl,
+            json: {
+                claimToken,
+                fingerprint,
+            },
+        });
+    }
+    catch (error) {
+        if (["CLAIM_EXPIRED", "ALREADY_CLAIMED", "CLAIM_INVALID"].includes(getApiErrorCode(error) ?? "")) {
+            await clearTerminalClaimState(expectedCredentials, claimToken);
+        }
+        throw error;
+    }
+    const claimedCredentials = {
+        accessToken: claimed.accessToken,
+        refreshToken: claimed.refreshToken,
+        accessTokenExpiresAt: claimed.accessTokenExpiresAt,
+        refreshTokenExpiresAt: claimed.refreshTokenExpiresAt,
+        issuerOrigin: HOSTED_APEX_ORIGIN,
+    };
+    const persisted = await replaceCredentialsIfCurrent(expectedCredentials, claimedCredentials);
+    if (!persisted.saved) {
+        // The server claim is committed. Remove only the consumed proof from a
+        // concurrently installed account generation; never overwrite its tokens.
+        await clearGuestFieldsIfClaimTokenMatches(claimToken);
+        throw new Error("The trial was claimed, but local Apex credentials changed while it completed. Run `apex login` to load the claimed account.");
+    }
+    // The server claim and local account credentials are already durable. These
+    // convenience writes must not turn that successful claim into a reported
+    // failure; later commands can rediscover the default company and binding.
+    await updateConfig({ defaultCompanyId: claimed.company.id }).catch(() => undefined);
+    const currentBinding = await loadWorkspaceBinding(cwd).catch(() => null);
+    const claimedCurrentWorkspace = currentBinding &&
+        (currentBinding.companyId === claimed.company.id ||
+            (expectedCredentials?.guestCompanyId &&
+                currentBinding.companyId === expectedCredentials.guestCompanyId) ||
+            (claimed.workspaceId &&
+                currentBinding.workspaceId === claimed.workspaceId))
+        ? currentBinding
+        : null;
+    const workspaceId = claimedCurrentWorkspace?.workspaceId ?? claimed.workspaceId;
+    const storedScanUrl = claimedCurrentWorkspace?.lastScanUrl ?? null;
+    const storedScanUrlIsGuestClaimLanding = isGuestClaimLandingUrl(storedScanUrl, config.baseUrl);
+    const scanUrl = claimedCurrentWorkspace
+        ? (!storedScanUrlIsGuestClaimLanding ? storedScanUrl : null) ??
+            (claimedCurrentWorkspace.workspaceId === claimed.workspaceId
+                ? claimed.scanUrl
+                : new URL(`/workspace/${encodeURIComponent(claimedCurrentWorkspace.workspaceId)}`, config.baseUrl).toString())
+        : claimed.scanUrl;
+    if (claimedCurrentWorkspace) {
+        await Promise.resolve(saveWorkspaceBinding(cwd, {
+            ...claimedCurrentWorkspace,
+            companyId: claimed.company.id,
+            ...(storedScanUrlIsGuestClaimLanding ? { lastScanUrl: scanUrl } : {}),
+            lastSyncedAt: new Date().toISOString(),
+        })).catch(() => undefined);
+    }
+    return {
+        outcome: "claimed",
+        claimed: true,
+        company: claimed.company,
+        workspaceId,
+        scanUrl,
+        ...(claimed.discountCode ? { discountCode: claimed.discountCode } : {}),
+    };
+}
+export function claimOnboardingSession(client, cwd, options = {}) {
+    return withCredentialLifecycleLock(() => claimOnboardingSessionUnlocked(client, cwd, options));
+}