@cantinasecurity/apex-cli 0.1.17 → 0.1.18

package/dist/api-client.js

@@ -1,13 +1,60 @@
-import { clearCredentials, loadConfig, loadCredentials, saveCredentials } from "./config.js";
+import { bindCredentialIssuerOriginIfCurrent, clearCredentials, clearCredentialsIfRefreshTokenMatches, loadConfig, loadCredentials, saveRefreshedCredentialsIfCurrent, } from "./config.js";
 import { getTelemetryRequestHeaders } from "./telemetry.js";
+import { redactSensitiveText, redactSensitiveValue, } from "./redaction.js";
+export { redactSensitiveText } from "./redaction.js";
+const CREDENTIAL_GENERATION_CHANGED_MESSAGE = "Apex credentials changed while this request was refreshing. The newer credentials were kept; retry the command.";
+const HOSTED_APEX_ORIGIN = "https://ai.cantina.xyz";
+const CREDENTIAL_ORIGIN_MISMATCH_MESSAGE = "Refusing to send stored Apex credentials because their issuer origin does not match the configured APEX_BASE_URL. Restore the origin used to sign in, or run `apex logout` before signing in to this origin.";
+export class CredentialGenerationChangedError extends Error {
+    constructor() {
+        super(CREDENTIAL_GENERATION_CHANGED_MESSAGE);
+        this.name = "CredentialGenerationChangedError";
+    }
+}
+export class CredentialOriginMismatchError extends Error {
+    constructor() {
+        super(CREDENTIAL_ORIGIN_MISMATCH_MESSAGE);
+        this.name = "CredentialOriginMismatchError";
+    }
+}
+function parseHttpOrigin(value) {
+    try {
+        const url = new URL(value);
+        return ["http:", "https:"].includes(url.protocol) ? url.origin : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function getApiErrorCode(error) {
+    if (!(error instanceof ApiError) || !error.body || typeof error.body !== "object") {
+        return null;
+    }
+    const code = error.body.code;
+    return typeof code === "string" && code.trim().length > 0 ? code.trim() : null;
+}
+const TERMINAL_GUEST_SESSION_CODES = new Set([
+    "GUEST_SESSION_EXPIRED",
+    "GUEST_SESSION_CLAIMED",
+    "GUEST_SESSION_REVOKED",
+]);
+export function isTerminalGuestSessionError(error) {
+    const code = getApiErrorCode(error);
+    return code !== null && TERMINAL_GUEST_SESSION_CODES.has(code);
+}
 export class ApiError extends Error {
     status;
     body;
+    code;
     constructor(message, status, body) {
-        super(message);
+        super(redactSensitiveText(message));
         this.name = "ApiError";
         this.status = status;
-        this.body = body;
+        this.body = redactSensitiveValue(body);
+        const code = this.body && typeof this.body === "object"
+            ? this.body.code
+            : null;
+        this.code = typeof code === "string" && code.trim().length > 0 ? code.trim() : null;
     }
 }
 function getApiErrorBodyMessage(body) {
@@ -17,11 +64,51 @@ function getApiErrorBodyMessage(body) {
     const error = body.error;
     return typeof error === "string" && error.trim().length > 0 ? error : null;
 }
+function getFriendlyApiErrorMessage(error) {
+    switch (error.code) {
+        case "ACTIVE_GUEST_SESSION":
+            return "A different guest trial is already active on this machine. Re-run `apex redeem <code> --replace` to revoke it first.";
+        case "TRIAL_ALREADY_REDEEMED":
+            return "This trial code has already funded a guest scan on this machine. Run `apex claim` to keep an unclaimed result, or use your Cantina account.";
+        case "GUEST_SESSION_EXPIRED":
+            return "Your guest trial session has expired. Run `apex claim` on this machine to keep its results.";
+        case "GUEST_SESSION_CLAIMED":
+            return "This guest trial was already claimed. Run `apex login` to use the claimed account.";
+        case "GUEST_SESSION_REVOKED":
+            return "This guest trial was revoked and can no longer be claimed. Run `apex login` to continue with your Cantina account, or redeem a different trial code.";
+        case "GUEST_TRIAL_CREDITS_EXHAUSTED":
+            return "Your guest trial credits have been used. Run `apex claim` to keep the results and continue with your account.";
+        case "GUEST_SCAN_REFUND_PENDING":
+            return "Your guest scan failed and its retry credit is still being restored. Retry shortly.";
+        case "GUEST_MODE_UNSUPPORTED":
+            return "Guest trials support standard scans only. Run `apex claim` before starting another scan mode.";
+        case "GUEST_WORKSPACE_LIMIT":
+            return "This guest trial has reached its workspace limit. Run `apex claim` to continue with your account.";
+        case "GUEST_CLAIM_REQUIRED":
+            return "This action requires an account. Run `apex claim`, then retry it.";
+        case "CLAIM_EXPIRED":
+            return "The trial claim window has expired. Run `apex login` to continue with your Cantina account.";
+        case "CLAIM_INVALID":
+            return "This trial claim proof is invalid or already consumed. Local trial state was cleared; run `apex login` to use the claimed Cantina account, or contact Cantina support if the results are missing.";
+        case "CLAIM_PERSONAL_TENANT_EXISTS":
+            return "This Cantina account already owns a personal Apex tenant, so CLI claim linking is not available yet. Contact Cantina support before the trial claim deadline.";
+        case "EMAIL_UNVERIFIED":
+            return "Verify your email, then run `apex claim` again. Your guest trial remains recoverable on this machine.";
+        case "FINGERPRINT_MISMATCH":
+            return "Run `apex claim` on the same machine that redeemed and scanned with this trial.";
+        case "TRIAL_CAPACITY":
+            return "Apex trial capacity is temporarily full. Retry later; no trial credentials were saved.";
+        default:
+            return null;
+    }
+}
 export function formatApiError(error) {
     if (error instanceof ApiError) {
-        return getApiErrorBodyMessage(error.body) ?? error.message;
+        return redactSensitiveText(getFriendlyApiErrorMessage(error) ??
+            getApiErrorBodyMessage(error.body) ??
+            error.message);
     }
-    return error instanceof Error ? error.message : String(error);
+    return redactSensitiveText(error instanceof Error ? error.message : String(error));
 }
 function expiresSoon(timestamp) {
     if (!timestamp)
@@ -46,24 +133,110 @@ export class ApexApiClient {
     async getCredentials() {
         return loadCredentials();
     }
-    async getAccessToken() {
-        const credentials = await this.refreshIfNeeded().catch(() => null);
-        return credentials?.accessToken ?? null;
+    async ensureCredentialIssuerOrigin(credentials, baseUrl) {
+        if (!credentials ||
+            (!credentials.accessToken.trim() && !credentials.refreshToken.trim())) {
+            return;
+        }
+        const configuredOrigin = parseHttpOrigin(baseUrl);
+        if (!configuredOrigin) {
+            throw new CredentialOriginMismatchError();
+        }
+        const storedIssuer = credentials.issuerOrigin?.trim() ?? "";
+        if (storedIssuer) {
+            if (parseHttpOrigin(storedIssuer) !== configuredOrigin) {
+                throw new CredentialOriginMismatchError();
+            }
+            return;
+        }
+        // Credentials written before issuer binding shipped can be attributed only
+        // to the canonical hosted origin without trusting a newly supplied custom
+        // APEX_BASE_URL. Persist that one safe migration before any bearer leaves.
+        if (configuredOrigin !== HOSTED_APEX_ORIGIN) {
+            throw new CredentialOriginMismatchError();
+        }
+        const migrated = await bindCredentialIssuerOriginIfCurrent(credentials, HOSTED_APEX_ORIGIN);
+        if (!migrated.saved) {
+            throw new CredentialGenerationChangedError();
+        }
+    }
+    async getAccessCredentials(snapshot) {
+        const credentials = snapshot === undefined
+            ? await loadCredentials()
+            : snapshot;
+        try {
+            const baseUrl = await this.getBaseUrl();
+            return await this.refreshIfNeeded(credentials, baseUrl);
+        }
+        catch (error) {
+            // A generation change is an identity boundary, not an ordinary refresh
+            // failure that callers may silently replace with another auth flow.
+            if (error instanceof CredentialGenerationChangedError)
+                throw error;
+            if (error instanceof CredentialOriginMismatchError)
+                throw error;
+            if (isTerminalGuestSessionError(error)) {
+                await this.clearCredentialsForGeneration(credentials?.refreshToken ?? "", error);
+                throw error;
+            }
+            return null;
+        }
+    }
+    async getAccessToken(snapshot) {
+        return (await this.getAccessCredentials(snapshot))?.accessToken ?? null;
     }
     async clearCredentials() {
-        await clearCredentials();
+        await clearCredentials({ preserveClaimProof: true });
     }
-    async refreshIfNeeded() {
-        const credentials = await loadCredentials();
+    /**
+     * Clears only the credential generation that received an unauthorized result.
+     * Typed terminal guest errors demote or remove the guest using the same policy
+     * as ordinary authenticated requests.
+     */
+    async clearCredentialsForGeneration(expectedRefreshToken, error) {
+        if (!expectedRefreshToken) {
+            return false;
+        }
+        const code = getApiErrorCode(error);
+        const guestSessionIsTerminal = isTerminalGuestSessionError(error);
+        const claimProofIsConsumed = code === "GUEST_SESSION_CLAIMED" ||
+            code === "GUEST_SESSION_REVOKED";
+        return clearCredentialsIfRefreshTokenMatches(expectedRefreshToken, {
+            preserveClaimProof: !claimProofIsConsumed,
+            preserveGuestSession: !guestSessionIsTerminal,
+        });
+    }
+    async clearCredentialsAfterUnauthorized(expectedRefreshToken, error) {
+        if (!expectedRefreshToken) {
+            return;
+        }
+        await this.clearCredentialsForGeneration(expectedRefreshToken, error);
+    }
+    async refreshIfNeeded(snapshot, requestBaseUrl) {
+        const credentials = snapshot === undefined
+            ? await loadCredentials()
+            : snapshot;
         if (!credentials)
             return null;
+        const baseUrl = requestBaseUrl ?? await this.getBaseUrl();
+        await this.ensureCredentialIssuerOrigin(credentials, baseUrl);
         if (!expiresSoon(credentials.accessTokenExpiresAt)) {
             return credentials;
         }
-        return this.refreshSession(credentials.refreshToken);
+        return this.refreshSession(credentials.refreshToken, {
+            expectedAccessToken: credentials.accessToken,
+            requestBaseUrl: baseUrl,
+        });
     }
-    async refreshSession(refreshToken) {
+    async refreshSession(refreshToken, options = {}) {
+        const baseUrl = options.requestBaseUrl ?? await this.getBaseUrl();
         const existing = await loadCredentials();
+        await this.ensureCredentialIssuerOrigin(existing, baseUrl);
+        if ((refreshToken !== undefined && existing?.refreshToken !== refreshToken) ||
+            (options.expectedAccessToken !== undefined &&
+                existing?.accessToken !== options.expectedAccessToken)) {
+            throw new CredentialGenerationChangedError();
+        }
         const effectiveRefreshToken = refreshToken ?? existing?.refreshToken ?? null;
         if (!effectiveRefreshToken)
             return null;
@@ -72,6 +245,8 @@ export class ApexApiClient {
             auth: false,
             json: { refreshToken: effectiveRefreshToken },
             retryOnUnauthorized: false,
+            telemetryAttribution: false,
+            requestBaseUrl: baseUrl,
         }));
         const nextCredentials = {
             accessToken: payload.accessToken,
@@ -79,55 +254,100 @@ export class ApexApiClient {
             accessTokenExpiresAt: payload.accessTokenExpiresAt,
             refreshTokenExpiresAt: payload.refreshTokenExpiresAt,
         };
-        await saveCredentials(nextCredentials);
-        return nextCredentials;
+        const persisted = await saveRefreshedCredentialsIfCurrent(effectiveRefreshToken, nextCredentials);
+        if (!persisted.saved) {
+            throw new CredentialGenerationChangedError();
+        }
+        return persisted.credentials;
     }
     async request(path, options = {}) {
-        const baseUrl = await this.getBaseUrl();
+        const { auth, bearerToken, json, retryOnUnauthorized, telemetryAttribution, requestBaseUrl, ...requestInit } = options;
+        const baseUrl = requestBaseUrl ?? await this.getBaseUrl();
+        const requestUrl = new URL(path, baseUrl);
+        if (requestUrl.origin !== parseHttpOrigin(baseUrl)) {
+            throw new CredentialOriginMismatchError();
+        }
         const headers = new Headers(options.headers ?? {});
-        const telemetryHeaders = await getTelemetryRequestHeaders();
-        let credentials = options.auth === false ? null : await this.refreshIfNeeded().catch(() => null);
+        const telemetryHeaders = telemetryAttribution === false
+            ? {}
+            : await getTelemetryRequestHeaders();
+        const hasExplicitBearer = bearerToken !== undefined;
+        const usesStoredCredentials = auth !== false && !hasExplicitBearer;
+        let credentials = null;
+        if (usesStoredCredentials) {
+            const snapshot = await loadCredentials();
+            try {
+                credentials = await this.refreshIfNeeded(snapshot, baseUrl);
+            }
+            catch (error) {
+                if (!(error instanceof CredentialGenerationChangedError) &&
+                    !(error instanceof CredentialOriginMismatchError)) {
+                    await this.clearCredentialsAfterUnauthorized(snapshot?.refreshToken, error);
+                }
+                throw error;
+            }
+        }
         for (const [key, value] of Object.entries(telemetryHeaders)) {
             headers.set(key, value);
         }
-        if (options.json !== undefined) {
+        if (json !== undefined) {
             headers.set("Content-Type", "application/json");
         }
-        if (credentials?.accessToken) {
+        if (hasExplicitBearer && bearerToken) {
+            headers.set("Authorization", `Bearer ${bearerToken}`);
+        }
+        else if (credentials?.accessToken) {
             headers.set("Authorization", `Bearer ${credentials.accessToken}`);
         }
-        const response = await fetch(new URL(path, baseUrl), {
-            ...options,
+        const response = await fetch(requestUrl, {
+            ...requestInit,
             headers,
-            body: options.json !== undefined ? JSON.stringify(options.json) : options.body,
+            body: json !== undefined ? JSON.stringify(json) : requestInit.body,
         });
         if (response.status === 401 &&
-            options.auth !== false &&
-            options.retryOnUnauthorized !== false) {
-            credentials = await this.refreshSession();
-            if (credentials?.accessToken) {
+            usesStoredCredentials &&
+            retryOnUnauthorized !== false) {
+            const attemptedRefreshToken = credentials?.refreshToken ?? null;
+            if (attemptedRefreshToken) {
+                try {
+                    credentials = await this.refreshSession(attemptedRefreshToken, {
+                        expectedAccessToken: credentials?.accessToken,
+                        requestBaseUrl: baseUrl,
+                    });
+                }
+                catch (error) {
+                    if (!(error instanceof CredentialGenerationChangedError) &&
+                        !(error instanceof CredentialOriginMismatchError)) {
+                        await this.clearCredentialsAfterUnauthorized(attemptedRefreshToken, error);
+                    }
+                    throw error;
+                }
+            }
+            if (attemptedRefreshToken && credentials?.accessToken) {
                 headers.set("Authorization", `Bearer ${credentials.accessToken}`);
-                const retryResponse = await fetch(new URL(path, baseUrl), {
-                    ...options,
+                const retryResponse = await fetch(requestUrl, {
+                    ...requestInit,
                     headers,
-                    body: options.json !== undefined ? JSON.stringify(options.json) : options.body,
+                    body: json !== undefined ? JSON.stringify(json) : requestInit.body,
                 });
                 const retryBody = await parseResponse(retryResponse);
                 if (!retryResponse.ok) {
+                    const retryError = new ApiError(`Request failed with ${retryResponse.status}`, retryResponse.status, retryBody);
                     if (retryResponse.status === 401) {
-                        await clearCredentials();
+                        await this.clearCredentialsAfterUnauthorized(credentials.refreshToken, retryError);
                     }
-                    throw new ApiError(`Request failed with ${retryResponse.status}`, retryResponse.status, retryBody);
+                    throw retryError;
                 }
                 return retryBody;
             }
         }
         const body = await parseResponse(response);
         if (!response.ok) {
-            if (response.status === 401) {
-                await clearCredentials();
+            const requestError = new ApiError(`Request failed with ${response.status}`, response.status, body);
+            if (response.status === 401 && usesStoredCredentials) {
+                await this.clearCredentialsAfterUnauthorized(credentials?.refreshToken, requestError);
             }
-            throw new ApiError(`Request failed with ${response.status}`, response.status, body);
+            throw requestError;
         }
         return body;
     }

package/dist/args.js

@@ -1,4 +1,11 @@
-const BOOLEAN_FLAGS = new Set(["force", "non-interactive", "json", "no-open", "help"]);
+const BOOLEAN_FLAGS = new Set([
+    "force",
+    "non-interactive",
+    "json",
+    "no-open",
+    "replace",
+    "help",
+]);
 const REPEATABLE_VALUE_FLAGS = new Set(["repo", "pr", "pr-path", "fix-pr-url", "label"]);
 export function parseArgs(argv) {
     const flags = {};

package/dist/auth.js

@@ -1,8 +1,10 @@
 import { openInBrowser } from "./browser.js";
-import { saveCredentials } from "./config.js";
-import { ApiError } from "./api-client.js";
+import { getClaimProofState } from "./claim-proof.js";
+import { getCredentialGeneration, saveDeviceLoginCredentialsIfGenerationMatches, withCredentialLifecycleLock, } from "./config.js";
+import { ApiError, formatApiError } from "./api-client.js";
 import { APEX_CLI_VERSION } from "./version.js";
 const DEVICE_CLIENT_NAME = "apex";
+const DEVICE_LOGIN_PREFLIGHT_ATTEMPTS = 3;
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -19,44 +21,18 @@ function toCredentials(poll) {
         refreshTokenExpiresAt: poll.refreshTokenExpiresAt,
     };
 }
-export async function getMe(client) {
-    try {
-        return await client.request("/api/cli/v1/me");
-    }
-    catch (error) {
-        if (error instanceof ApiError && error.status === 401) {
-            return null;
-        }
-        throw error;
-    }
-}
-export async function startDeviceLogin(client) {
-    return client.request("/api/cli/v1/auth/device/start", {
-        method: "POST",
-        auth: false,
-        json: {
-            clientName: DEVICE_CLIENT_NAME,
-            clientVersion: APEX_CLI_VERSION,
-        },
-    });
-}
-export async function pollDeviceLogin(client, deviceCode) {
-    return client.request("/api/cli/v1/auth/device/poll", {
-        method: "POST",
-        auth: false,
-        json: { deviceCode },
-        retryOnUnauthorized: false,
-    });
-}
-export async function waitForDeviceLoginApproval(client, options) {
+async function waitForDeviceLoginCredentials(client, options) {
     let intervalSeconds = Math.max(0, options.intervalSeconds ?? 5);
     let expiresAt = options.expiresAt ?? null;
+    let pollingBaseUrl = options.requestBaseUrl ?? null;
     const timeoutAt = Date.now() + Math.max(0, options.timeoutMs ?? 5 * 60 * 1000);
     function remainingTimeoutMs() {
         return Math.max(0, timeoutAt - Date.now());
     }
     while (remainingTimeoutMs() > 0) {
-        const expiresAtTime = expiresAt ? new Date(expiresAt).getTime() : Number.POSITIVE_INFINITY;
+        const expiresAtTime = expiresAt
+            ? new Date(expiresAt).getTime()
+            : Number.POSITIVE_INFINITY;
         if (Number.isFinite(expiresAtTime) && Date.now() >= expiresAtTime) {
             return {
                 status: "expired",
@@ -71,16 +47,19 @@ export async function waitForDeviceLoginApproval(client, options) {
             break;
         }
         try {
-            const polled = await pollDeviceLogin(client, options.deviceCode);
+            pollingBaseUrl ??= await client.getBaseUrl();
+            const polled = await pollDeviceLogin(client, options.deviceCode, pollingBaseUrl);
             if (polled.status === "pending") {
                 intervalSeconds = Math.max(0, polled.intervalSeconds);
                 expiresAt = polled.expiresAt;
                 continue;
             }
-            await saveCredentials(toCredentials(polled));
             return {
                 status: "approved",
-                me: await client.request("/api/cli/v1/me"),
+                credentials: {
+                    ...toCredentials(polled),
+                    issuerOrigin: new URL(pollingBaseUrl).origin,
+                },
             };
         }
         catch (error) {
@@ -99,12 +78,129 @@ export async function waitForDeviceLoginApproval(client, options) {
         expiresAt,
     };
 }
+export async function getMe(client) {
+    try {
+        return await client.request("/api/cli/v1/me");
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.status === 401) {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function startDeviceLogin(client, requestBaseUrl) {
+    return client.request("/api/cli/v1/auth/device/start", {
+        method: "POST",
+        auth: false,
+        json: {
+            clientName: DEVICE_CLIENT_NAME,
+            clientVersion: APEX_CLI_VERSION,
+        },
+        ...(requestBaseUrl ? { requestBaseUrl } : {}),
+    });
+}
+export async function pollDeviceLogin(client, deviceCode, requestBaseUrl) {
+    return client.request("/api/cli/v1/auth/device/poll", {
+        method: "POST",
+        auth: false,
+        json: { deviceCode },
+        retryOnUnauthorized: false,
+        ...(requestBaseUrl ? { requestBaseUrl } : {}),
+    });
+}
+export async function waitForDeviceLoginApproval(client, options) {
+    const currentCredentials = await client.getCredentials();
+    if (getCredentialGeneration(currentCredentials) !== options.credentialGeneration) {
+        return {
+            status: "superseded",
+            approvalReceived: false,
+            reason: "generation_changed",
+        };
+    }
+    const result = await waitForDeviceLoginCredentials(client, options);
+    if (result.status === "approved") {
+        // A normal login may happen after guest API access expires but before the
+        // longer claim window closes. Switch the active auth kind without erasing
+        // the locally held claim proof needed by a later `apex claim`.
+        const commitResult = await saveDeviceLoginCredentialsIfGenerationMatches(options.credentialGeneration, {
+            ...result.credentials,
+            guest: false,
+        });
+        if (commitResult !== "saved") {
+            return {
+                status: "superseded",
+                approvalReceived: true,
+                reason: commitResult,
+            };
+        }
+        return {
+            status: "approved",
+            me: await client.request("/api/cli/v1/me"),
+        };
+    }
+    return result;
+}
+export async function readStableDeviceLoginState(client) {
+    for (let attempt = 0; attempt < DEVICE_LOGIN_PREFLIGHT_ATTEMPTS; attempt += 1) {
+        const before = await client.getCredentials();
+        const credentialGeneration = getCredentialGeneration(before);
+        const me = await getMe(client);
+        const after = await client.getCredentials();
+        if (getCredentialGeneration(after) === credentialGeneration) {
+            return {
+                me,
+                credentials: after,
+                credentialGeneration,
+            };
+        }
+    }
+    throw new Error("The Apex credential state kept changing while device login was starting. The current state was kept; retry `apex login`.");
+}
+export async function loginWithoutPersist(client, options = {}) {
+    const requestBaseUrl = options.requestBaseUrl ?? await client.getBaseUrl();
+    const started = await startDeviceLogin(client, requestBaseUrl);
+    await options.onVerification?.(started);
+    log(`Login code: ${started.userCode}`, options.quiet);
+    log(`Open: ${started.verificationUrl}`, options.quiet);
+    if (!options.noOpen) {
+        try {
+            await openInBrowser(started.verificationUrl);
+        }
+        catch (error) {
+            log(`Failed to open browser automatically: ${formatApiError(error)}`, options.quiet);
+        }
+    }
+    const result = await waitForDeviceLoginCredentials(client, {
+        deviceCode: started.deviceCode,
+        requestBaseUrl,
+        intervalSeconds: started.intervalSeconds,
+        expiresAt: started.expiresAt,
+        timeoutMs: Math.max(0, new Date(started.expiresAt).getTime() - Date.now()),
+    });
+    if (result.status === "approved") {
+        return result.credentials;
+    }
+    throw new Error("CLI login timed out before approval completed");
+}
 export async function login(client, options) {
-    const existing = await getMe(client);
+    const loginState = await readStableDeviceLoginState(client);
+    const existing = loginState.me;
     if (existing) {
-        return existing;
+        const isGuest = existing.user.role?.trim().toLowerCase() === "guest";
+        if (!isGuest) {
+            return existing;
+        }
+        // An active guest normally stays in its recoverable trial flow. Once its
+        // locally known claim deadline has passed, explicit `apex login` is the
+        // supported escape hatch to an account. Starting device auth is
+        // non-destructive and approval preserves the local proof metadata.
+        if (getClaimProofState(loginState.credentials) !== "expired") {
+            return existing;
+        }
     }
-    const started = await startDeviceLogin(client);
+    const requestBaseUrl = await client.getBaseUrl();
+    const started = await startDeviceLogin(client, requestBaseUrl);
     log(`Login code: ${started.userCode}`, options.quiet);
     log(`Open: ${started.verificationUrl}`, options.quiet);
     if (!options.noOpen) {
@@ -112,11 +208,13 @@ export async function login(client, options) {
             await openInBrowser(started.verificationUrl);
         }
         catch (error) {
-            log(`Failed to open browser automatically: ${String(error)}`, options.quiet);
+            log(`Failed to open browser automatically: ${formatApiError(error)}`, options.quiet);
         }
     }
     const result = await waitForDeviceLoginApproval(client, {
         deviceCode: started.deviceCode,
+        credentialGeneration: loginState.credentialGeneration,
+        requestBaseUrl,
         intervalSeconds: started.intervalSeconds,
         expiresAt: started.expiresAt,
         timeoutMs: Math.max(0, new Date(started.expiresAt).getTime() - Date.now()),
@@ -124,20 +222,39 @@ export async function login(client, options) {
     if (result.status === "approved") {
         return result.me;
     }
+    if (result.status === "superseded") {
+        if (result.reason === "credential_operation_busy") {
+            throw new Error("Device login was approved, but another Apex credential operation was still in progress. Nothing was overwritten; retry the original command after it finishes.");
+        }
+        throw new Error(result.approvalReceived
+            ? "Device login was approved, but the Apex credential state changed before it could be saved. The current state was kept; retry the original command, or run `apex login` again only if authentication is still required."
+            : "The Apex credential state changed after device login started. The current state was kept; retry the original command, or run `apex login` again only if authentication is still required.");
+    }
     throw new Error("CLI login timed out before approval completed");
 }
-export async function logout(client) {
-    const credentials = await client.getCredentials();
-    if (!credentials) {
-        return;
-    }
-    try {
-        await client.request("/api/cli/v1/auth/logout", {
-            method: "POST",
-            auth: true,
-        });
-    }
-    finally {
-        await client.clearCredentials();
-    }
+export function logout(client, expectedCredentials) {
+    const expectedGeneration = getCredentialGeneration(expectedCredentials);
+    return withCredentialLifecycleLock(async () => {
+        const credentials = await client.getCredentials();
+        if (getCredentialGeneration(credentials) !== expectedGeneration) {
+            throw new Error("Apex credentials changed before logout completed. The current session was kept; retry `apex logout` so any guest trial can be confirmed explicitly.");
+        }
+        if (!credentials) {
+            return;
+        }
+        if (!credentials.accessToken.trim() && !credentials.refreshToken.trim()) {
+            // A proof-only onboarding stub is already logged out. Keep its claim proof
+            // locally and avoid an unauthenticated logout request that can only fail.
+            return;
+        }
+        try {
+            await client.request("/api/cli/v1/auth/logout", {
+                method: "POST",
+                auth: true,
+            });
+        }
+        finally {
+            await client.clearCredentials();
+        }
+    });
 }