@cantinasecurity/apex-cli 0.1.17 → 0.1.18

package/dist/redaction.js

@@ -0,0 +1,34 @@
+const APEX_SECRET_PATTERN = /(apex_(?:ct|at|rt|dc)_)[A-Za-z0-9._~+/=-]+/gi;
+const ONBOARDING_CODE_PATTERN = /SPBT-[A-Z0-9]{2,24}-[A-Z0-9]{8}/gi;
+// Hex-only boundaries avoid redacting a 64-character window from a longer hex
+// value while still catching fingerprints next to punctuation or prose.
+const ONBOARDING_FINGERPRINT_PATTERN = /(?<![A-Fa-f0-9])[A-Fa-f0-9]{64}(?![A-Fa-f0-9])/g;
+export function redactSensitiveText(value) {
+    return value
+        .replace(APEX_SECRET_PATTERN, (_match, prefix) => `${prefix}[REDACTED]`)
+        .replace(ONBOARDING_CODE_PATTERN, "SPBT-[REDACTED]")
+        .replace(ONBOARDING_FINGERPRINT_PATTERN, "[REDACTED]");
+}
+export function containsSensitiveText(value) {
+    return redactSensitiveText(value) !== value;
+}
+/** Redacts every string key and value in an API error body without mutating it. */
+export function redactSensitiveValue(value) {
+    const seen = new WeakSet();
+    const visit = (current) => {
+        if (typeof current === "string")
+            return redactSensitiveText(current);
+        if (!current || typeof current !== "object")
+            return current;
+        if (seen.has(current))
+            return "[CIRCULAR]";
+        seen.add(current);
+        if (Array.isArray(current))
+            return current.map(visit);
+        return Object.fromEntries(Object.entries(current).map(([key, nested]) => [
+            redactSensitiveText(key),
+            visit(nested),
+        ]));
+    };
+    return visit(value);
+}

package/dist/session.js

@@ -1,7 +1,8 @@
 import path from "node:path";
 import { canPromptInteractively, getFlagList, getFlagString, isJsonMode, } from "./args.js";
-import { login } from "./auth.js";
+import { getMe, login } from "./auth.js";
 import { ApiError } from "./api-client.js";
+import { isClaimProofAvailable } from "./claim-proof.js";
 import { openInBrowser } from "./browser.js";
 import { loadConfig } from "./config.js";
 import { chooseOne, confirm, promptText, waitForEnter } from "./prompt.js";
@@ -132,6 +133,14 @@ function ensurePlannedSources(selection, resolve) {
     };
 }
 export async function ensureAuthenticated(client, flags) {
+    const existing = await getMe(client);
+    if (existing) {
+        return existing;
+    }
+    const credentials = await client.getCredentials();
+    if (isClaimProofAvailable(credentials)) {
+        throw new Error("Your guest trial session is no longer available, but its claim proof is stored on this machine. Run `apex claim` to keep the trial results.");
+    }
     return login(client, {
         noOpen: flags["no-open"] === true,
         quiet: isJsonMode(flags),

package/dist/shell.js

@@ -1,11 +1,12 @@
 import { SHELL_HELP_TEXT } from "./help.js";
-import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindingFixReview, commandFindings, commandLogout, commandScan, commandScans, commandStatus, commandTelemetry, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, initializeInteractiveSession, openCurrentApexView, } from "./commands.js";
+import { commandCancelScan, commandClaim, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindingFixReview, commandFindings, commandLogout, commandScan, commandScans, commandStatus, commandTelemetry, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, initializeInteractiveSession, openCurrentApexView, } from "./commands.js";
 import { withFlag } from "./args.js";
 import { printCompanyDetails, printInteractiveSessionSummary, printSourceList, printWorkspaceDetails, } from "./output.js";
 import { readLine } from "./prompt.js";
 import { formatApiError } from "./api-client.js";
 import { createShellTelemetryInvocation, emitInvocationCompleted, emitInvocationStarted, withTelemetryContext, } from "./telemetry.js";
 const SHELL_COMPLETIONS = [
+    { command: "claim" },
     { command: "credits" },
     { command: "scan", args: ["standard", "audit", "ultra", "lite", "pr"] },
     { command: "scans" },
@@ -193,6 +194,13 @@ async function runShellCommand(client, cwd, parsed, shellFlags, session) {
         case "credits":
             await commandCredits(client, cwd, shellFlags);
             return {};
+        case "claim":
+            if (parsed.args.length > 0) {
+                process.stderr.write("Usage: /claim\n");
+                return {};
+            }
+            await commandClaim(client, cwd, shellFlags);
+            return false;
         case "scan": {
             const mode = parsed.args[0];
             if (mode && !["standard", "audit", "ultra", "lite", "pr"].includes(mode)) {
@@ -329,8 +337,7 @@ async function runShellCommand(client, cwd, parsed, shellFlags, session) {
             await commandUpdate(shellFlags);
             return false;
         case "logout":
-            await commandLogout(client, shellFlags);
-            return false;
+            return (await commandLogout(client, shellFlags)).loggedOut ? false : {};
         case "repos":
             printSourceList(session.sources);
             return {};

package/dist/telemetry.js

@@ -2,7 +2,8 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
-import { loadConfig, saveConfig } from "./config.js";
+import { loadConfig, updateConfig } from "./config.js";
+import { containsSensitiveText } from "./redaction.js";
 import { APEX_CLI_VERSION } from "./version.js";
 const TELEMETRY_ENDPOINT_PATH = "/api/cli/v1/telemetry/events";
 const TELEMETRY_SESSION_ID = randomUUID();
@@ -29,6 +30,7 @@ const KNOWN_CLI_FLAG_NAMES = [
     "parent-comment",
     "pr",
     "pr-path",
+    "replace",
     "repo",
     "review-target",
     "scan",
@@ -41,6 +43,7 @@ const KNOWN_CLI_FLAG_NAMES = [
 const KNOWN_CLI_COMMANDS = [
     "cancel-scan",
     "connect",
+    "claim",
     "credits",
     "doctor",
     "export",
@@ -59,6 +62,50 @@ const KNOWN_CLI_COMMANDS = [
     "update",
     "workspace",
     "workspaces",
+    "redeem",
+];
+const KNOWN_SHELL_COMMANDS = [
+    "cancel",
+    "cancel-scan",
+    "claim",
+    "clear",
+    "company",
+    "connect",
+    "credits",
+    "doctor",
+    "exit",
+    "export",
+    "findings",
+    "help",
+    "logout",
+    "open",
+    "quit",
+    "repos",
+    "scan",
+    "scans",
+    "status",
+    "telemetry",
+    "update",
+    "workspace",
+    "workspaces",
+];
+const ONBOARDING_TELEMETRY_OUTCOMES = [
+    "redeemed",
+    "idempotent",
+    "already_authenticated",
+    "invalid",
+    "expired",
+    "exhausted",
+    "rate_limited",
+    "capacity",
+    "active_guest_session",
+    "claimed",
+    "email_unverified",
+    "claim_expired",
+    "already_claimed",
+    "scan_in_progress",
+    "fingerprint_mismatch",
+    "error",
 ];
 let cachedParentProcesses = null;
 let volatileTelemetryInstallId = null;
@@ -83,6 +130,8 @@ function safeToken(value, fallback = "unknown") {
     const trimmed = value?.trim();
     if (!trimmed)
         return fallback;
+    if (containsSensitiveText(trimmed))
+        return fallback;
     const normalized = trimmed
         .slice(0, 80)
         .replace(/[^A-Za-z0-9_.:-]+/g, "_")
@@ -173,6 +222,7 @@ function sanitizeCliFlags(flags) {
         unknownFlagCount: unknownFlagCount(flags),
         json: boolFlag(flags, "json"),
         force: boolFlag(flags, "force"),
+        replace: boolFlag(flags, "replace"),
         nonInteractive: boolFlag(flags, "non-interactive"),
         noOpen: boolFlag(flags, "no-open"),
         companyProvided: stringFlag(flags, "company") !== null,
@@ -323,6 +373,11 @@ function safeCliCommand(parsed) {
     const command = parsed.command ?? "interactive-shell";
     return KNOWN_CLI_COMMANDS.includes(command) ? command : "unknown";
 }
+function safeShellCommand(command) {
+    return KNOWN_SHELL_COMMANDS.includes(command)
+        ? command
+        : "unknown";
+}
 function getInputKeys(input) {
     return Object.entries(input)
         .filter(([, value]) => value !== undefined)
@@ -556,7 +611,7 @@ export function createShellTelemetryInvocation(parsed, flags) {
         : null;
     return createInvocation({
         surface: "interactive_shell",
-        command: parsed.command,
+        command: safeShellCommand(parsed.command),
         metadata: {
             argCount: parsed.args.length,
             ...sanitizeCliFlags(flags),
@@ -587,6 +642,19 @@ export async function withTelemetryContext(invocation, action) {
 function currentInvocation() {
     return telemetryContext.getStore() ?? null;
 }
+export function setTelemetryAuthKind(authKind) {
+    const invocation = currentInvocation();
+    if (!invocation)
+        return;
+    invocation.metadata.authKind = authKind;
+}
+export function setTelemetryOnboardingOutcome(outcome) {
+    const invocation = currentInvocation();
+    if (!invocation)
+        return;
+    invocation.metadata.onboardingOutcome =
+        safeEnum(outcome, ONBOARDING_TELEMETRY_OUTCOMES) ?? "error";
+}
 function getTelemetryDisabled(config) {
     const disabledEnv = getDisabledEnvName();
     if (disabledEnv)
@@ -607,10 +675,7 @@ async function getTelemetryStatusInternal(options) {
         installId = randomUUID();
         volatileTelemetryInstallId = installId;
         try {
-            await saveConfig({
-                ...config,
-                telemetryInstallId: installId,
-            });
+            await updateConfig({ telemetryInstallId: installId });
         }
         catch {
             // Telemetry-only ID creation must not break normal CLI/API behavior.
@@ -635,10 +700,7 @@ export async function getTelemetryStatus(surface = "cli", options = {}) {
 }
 export async function setTelemetryEnabled(enabled) {
     const config = await loadConfig();
-    await saveConfig({
-        ...config,
-        telemetryDisabled: enabled ? false : true,
-    });
+    await updateConfig({ telemetryDisabled: enabled ? false : true });
     return getTelemetryStatus("cli", { createInstallId: enabled });
 }
 function runtimePayload() {
@@ -662,10 +724,19 @@ function errorPayload(error) {
     }
     const maybeError = error;
     const status = typeof maybeError.status === "number" ? maybeError.status : null;
+    const name = typeof maybeError.name === "string" &&
+        ["AbortError", "ApiError", "Error", "TypeError"].includes(maybeError.name)
+        ? maybeError.name
+        : "Error";
+    const code = typeof maybeError.code === "string" &&
+        !containsSensitiveText(maybeError.code) &&
+        /^[A-Z][A-Z0-9_]{1,63}$/.test(maybeError.code)
+        ? maybeError.code
+        : null;
     return {
-        name: typeof maybeError.name === "string" ? safeToken(maybeError.name) : "Error",
+        name,
         status,
-        code: typeof maybeError.code === "string" ? safeToken(maybeError.code) : null,
+        code,
         category: status ? `http_${status}` : "error",
     };
 }

package/dist/workspace-binding.js

@@ -1,4 +1,5 @@
-import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 function getWorkspaceDir(cwd) {
     return path.join(cwd, ".apex");
@@ -18,12 +19,21 @@ export async function loadWorkspaceBinding(cwd) {
 export async function saveWorkspaceBinding(cwd, binding) {
     const workspaceDir = getWorkspaceDir(cwd);
     const bindingPath = getWorkspaceBindingPath(cwd);
+    const temporaryPath = path.join(workspaceDir, `.workspace.json.${process.pid}.${randomUUID()}.tmp`);
     await mkdir(workspaceDir, { recursive: true, mode: 0o700 });
-    await writeFile(bindingPath, `${JSON.stringify(binding, null, 2)}\n`, {
-        encoding: "utf8",
-        mode: 0o600,
-    });
-    await chmod(bindingPath, 0o600);
+    try {
+        await writeFile(temporaryPath, `${JSON.stringify(binding, null, 2)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        await chmod(temporaryPath, 0o600);
+        await rename(temporaryPath, bindingPath);
+        await chmod(bindingPath, 0o600);
+    }
+    catch (error) {
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
 }
 export async function clearWorkspaceBinding(cwd) {
     await rm(getWorkspaceBindingPath(cwd), { force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cantinasecurity/apex-cli",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Standalone CLI and MCP server for Apex.",
   "private": false,
   "type": "module",
@@ -29,11 +29,13 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "ignore": "^7.0.5",
+    "proper-lockfile": "^4.1.2",
     "tar": "^7.4.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^22.18.6",
+    "@types/proper-lockfile": "^4.1.4",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^2.1.9"

package/skills/apex-cli/SKILL.md

@@ -15,22 +15,48 @@ For serverless, cron, or other HTTP-only integrations, use the hosted Apex REST
 
 For on-prem or other non-default Apex hosts, make sure the MCP server runs with `APEX_BASE_URL` set to the external HTTPS Bedrock origin before auth or provider connection flows.
 
+Trial-code exception: if the user supplied a Cantina trial code, do not call
+`apex-auth-start` or open a login URL. Run `apex redeem <code> --json` in a
+terminal from the repository root, then use the normal MCP scan tools with the
+shared guest credentials. Only when the first attempt has an ambiguous
+transport/connection failure or interrupted/missing response with no typed
+server error may you retry that exact same command once on the same machine,
+HOME, and repository root. Never retry a typed server rejection or make more
+than one recovery retry. Treat the code as a secret: pass it only to
+`apex redeem`; never echo it, write it to a file, or include it in an MCP call
+or tool result. Trial redemption, claim, and revocation are hosted-only; stop
+before passing the code when `APEX_BASE_URL` has any origin other than
+`https://ai.cantina.xyz`. Stop if the redeem outcome is not `redeemed` or
+`idempotent`.
+
 Workflow:
 
 1. Start with `apex-auth-status`.
-2. If Apex is unauthenticated, call `apex-auth-start`, ask the user to approve the device-login URL, then call `apex-auth-wait` with the returned `deviceCode`.
-3. For repository work, pass `cwd` explicitly.
-4. Call `apex-doctor` before starting a scan if workspace binding or source planning might be unclear.
-5. If the directory is not bound to the right workspace, call `apex-workspaces` and `apex-workspace-use`.
-6. Use `apex-scan`, `apex-status`, `apex-scans`, `apex-findings`, and `apex-export-findings` for the scan lifecycle.
-7. For Lite scans, call `apex-scan` with `mode: "lite"` only when the company has Lite Scan beta access and the sources are provider-backed.
-8. For PR scans, call `apex-scan` with `mode: "pr"` and `pullRequests`.
-9. Use `apex-finding-comment` and `apex-finding-feedback` when the user wants to leave review notes or valid/invalid feedback on a finding.
-10. For fix reviews, call `apex-finding-fix-review`. Pass `fixPrUrls` for a PR-based review, or omit them to review the current repository state when Bedrock has original scan repository context.
+2. Always call `apex-trial-status` next, even when account authentication succeeded. When `claimAvailable` is true, do not call `apex-auth-start`; tell the user to run `apex claim` in a terminal first so the trial workspace, scans, and findings are kept. When the claim deadline has passed and `claimAvailable` is false, continue normal account authentication instead of steering the user to an expired claim.
+3. Only when Apex is unauthenticated, no unexpired claim proof is available, and no trial code was supplied, call `apex-auth-start`, ask the user to approve the device-login URL, then call `apex-auth-wait` with both the returned `deviceCode` and opaque `credentialGeneration`. If the wait is superseded, keep the current credential state and re-check `apex-auth-status` before starting another login.
+4. For repository work, pass `cwd` explicitly.
+5. Call `apex-doctor` before starting a scan if workspace binding or source planning might be unclear.
+6. If the directory is not bound to the right workspace, call `apex-workspaces` and `apex-workspace-use`.
+7. Use `apex-scan`, `apex-status`, `apex-scans`, `apex-findings`, and `apex-export-findings` for the scan lifecycle.
+8. For Lite scans, call `apex-scan` with `mode: "lite"` only when the company has Lite Scan beta access and the sources are provider-backed.
+9. For PR scans, call `apex-scan` with `mode: "pr"` and `pullRequests`.
+10. Use `apex-finding-comment` and `apex-finding-feedback` when the user wants to leave review notes or valid/invalid feedback on a finding.
+11. For fix reviews, call `apex-finding-fix-review`. Pass `fixPrUrls` for a PR-based review, or omit them to review the current repository state when Bedrock has original scan repository context.
+
+If the Apex MCP server is not configured, fall back to the local CLI:
+
+- Prefer scripted commands over the interactive shell.
+- A trial redeem with an ambiguous transport or response-loss failure may be retried exactly once with the same code, machine, HOME, and repository root. Never retry a typed server rejection or use `--replace` for response-loss recovery.
+- After a successful scan JSON response, inspect `localPersistence.workspaceBindingSaved`. If it is `false`, the server scan already started: capture and report `binding.lastScanId`, then STOP; do not run status or findings until local repository permissions are repaired.
+- `apex-trial-status` is MCP-only; do not invoke it as a CLI command. In a CLI-only flow, use the `claimDeadline` returned by `apex redeem <code> --json` without repeating or persisting the secret code.
+- After a guest scan, tell the user to run `apex claim` on the same machine before that returned claim deadline. If the deadline is unavailable or uncertain, do not guess or start a replacement login; run `apex claim` and let the server validate the proof.
+- Claim currently requires a Cantina account that does not already own a personal Apex tenant. If the user already completed Cantina Apex onboarding, explain that CLI linking is not available yet and tell them to contact Cantina support before the claim deadline.
 
 Guidelines:
 
 - Do not rely on interactive CLI prompts. The MCP tools are intentionally non-interactive.
+- The MCP-only `apex-trial-status` tool may report local guest and claim deadlines, but it must never return a trial code or claim token. `claimAvailable` becomes false at a known passed deadline; missing or invalid local deadline metadata remains conservative and server-authoritative. There is intentionally no MCP redemption or claim tool.
+- When MCP remains available after a guest scan, remind the user to run `apex claim` on the same machine while `claimAvailable` is true; after a known passed deadline, continue with normal account login.
 - Service-key management has no MCP tools. Never ask a user to paste a service key into a prompt, and never place one in an MCP call, tool result, source file, or log.
 - If a user explicitly needs a new service key, tell them to run `apex login` if needed, then run `apex service-key create --name <name> --scope <scope[,scope]>` directly in their own terminal. Use only the required scopes: `scans:create` to trigger, `scans:read` to poll status, and `findings:read` to retrieve findings. A P1-only adapter can use `--scope scans:read,findings:read`; omitting `--scope` grants all three. The CLI automatically selects the company when only one is available and prompts when there are several; use `--company <id-or-handle>` to skip that prompt or resolve a non-interactive command. Service-key commands never initiate login, and the secret is shown once.
 - For a headless HTTP adapter, read the service key from a secret-backed environment variable, send it as a bearer token to `/api/apex/v1`, and redact it from errors and logs. Do not shell out to `apex` or launch MCP from the adapter.
@@ -48,9 +74,15 @@ Guidelines:
 - Use `force: true` on `apex-scan` only when the user explicitly wants to replace or overlap an active scan.
 - When checking a scan that is not the workspace binding's latest scan, pass `scanId` to `apex-status`; use `apex-scans` first if you need to discover scan IDs.
 - Prefer `apex-findings` for quick inspection and `apex-export-findings` when the user needs a file artifact.
-- Finding comments, feedback, and fix review scan starts use the same Apex device-login credentials as read tools. If a write tool reports missing auth, re-run `apex-auth-status` and complete `apex-auth-start` / `apex-auth-wait` instead of asking for browser cookies or auth tokens.
-- Anonymous telemetry records only sanitized command/tool metadata such as command names, enum modes, counts, durations, success/failure categories, CLI version, and client integration. It must not include raw repository paths, scan IDs, finding IDs, comments, file paths, PR URLs, or tokens.
+- Finding comments, feedback, and fix review scan starts use the same Apex device-login credentials as read tools. If a write tool reports missing auth, re-run `apex-auth-status`, check `apex-trial-status`, and complete `apex-auth-start` / `apex-auth-wait` only when no unexpired local claim proof is available, instead of asking for browser cookies or auth tokens.
+- Anonymous telemetry records only sanitized command/tool metadata such as command names, enum modes, counts, durations, success/failure categories, CLI version, and client integration. It must not include raw repository paths, scan IDs, finding IDs, comments, file paths, PR URLs, trial codes, claim tokens, onboarding fingerprints, or bearer tokens.
 - Invalid finding feedback requires `dismissalReason`; valid feedback can include `suggestedSeverity`, including `extreme`.
 - PR-based fix reviews can pass `fixPrUrls` directly to `apex-finding-fix-review`; agents that also need to record fixed feedback can first call `apex-finding-feedback` with `status: "valid"`, `labels: ["fixed"]`, and `fixPrUrls`.
 - Current-repository fix reviews omit `fixPrUrls` and require Bedrock original scan repository context for the finding.
 - Finding identifiers such as `KERN2-25` resolve against the selected or latest scan for the current workspace binding. Pass an explicit scan when needed, or use the finding UUID directly.
+
+Example trial flow: redeem a user-supplied code with `apex redeem <code> --json`
+in a terminal, use MCP for scan/status/findings after redemption, then check the
+MCP-only `apex-trial-status` tool and remind the user to run `apex claim`
+locally while `claimAvailable` remains true. In a CLI-only flow, use the
+redeem response's `claimDeadline` instead.