vexp-cli 3.2.5 → 3.3.0

package/dist/license.js

@@ -16,7 +16,21 @@ function vexpHomeDir() {
     return os.homedir();
 }
 const VEXP_LICENSE_PUBLIC_KEY = "MCowBQYDK2VwAyEApwiWYGCyhCaGHAHWn/RTBSGo/1MNmGyZUgSNBQ5YE4g=";
-const VEXP_WEB_ORIGIN = process.env.VEXP_WEB_ORIGIN || "https://vexp.dev";
+let licensePublicKeyDer = VEXP_LICENSE_PUBLIC_KEY;
+/**
+ * Tests only: verify tokens against a key the test generated, so the success
+ * paths run through real Ed25519 verification without the server's private
+ * key. Not reachable from the command line or the environment: only code
+ * already running inside this process can call it.
+ */
+export function __setLicensePublicKeyForTests(derBase64) {
+    licensePublicKeyDer = derBase64 ?? VEXP_LICENSE_PUBLIC_KEY;
+}
+/** Read at call time, not import time, so a test (or a user who exports it
+ *  after a long-lived process started) always hits the origin it names. */
+function webOrigin() {
+    return process.env.VEXP_WEB_ORIGIN || "https://vexp.dev";
+}
 // 14-day grace window after the last successful online refresh before we
 // stop trusting the cached freshToken and fall back to the long JWT only.
 const GRACE_MS = 14 * 24 * 60 * 60 * 1000;
@@ -28,52 +42,193 @@ const REFRESH_BACKOFF_MS = 24 * 60 * 60 * 1000;
 // fresh.jwt alive quietly never landed and users fell back to the long
 // JWT — or, once that lapsed, to the free tier.
 const VALIDATE_TIMEOUT_MS = 10_000;
+/** Where the user gets a current key: the account page re-mints it. */
+export const ACCOUNT_URL = "https://vexp.dev/account";
+function vexpDir() {
+    return path.join(vexpHomeDir(), ".vexp");
+}
 function getLicensePath() {
-    return path.join(vexpHomeDir(), ".vexp", "license.jwt");
+    return path.join(vexpDir(), "license.jwt");
 }
 function getFreshTokenPath() {
-    return path.join(vexpHomeDir(), ".vexp", "fresh.jwt");
+    return path.join(vexpDir(), "fresh.jwt");
 }
 function getLastCheckPath() {
-    return path.join(vexpHomeDir(), ".vexp", "last_online_check");
+    return path.join(vexpDir(), "last_online_check");
 }
 function getDeviceIdPath() {
-    return path.join(vexpHomeDir(), ".vexp", "device.id");
+    return path.join(vexpDir(), "device.id");
 }
 /**
- * Stable anonymous device identifier. First call creates and persists it.
- * Uses OS hostname + a random salt — no PII, no hardware fingerprinting.
+ * Write a file so that a reader never sees it half-written: the content goes
+ * to a temp file next to the target and is renamed over it. The Rust engine,
+ * the VS Code extension and this CLI all write these files, sometimes at the
+ * same moment; with a plain writeFileSync one of them could read a truncated
+ * token and fall to FREE. When the rename is refused (a Windows reader
+ * holding the target open), fall back to a direct write rather than lose the
+ * update. Throws only when neither works.
  */
-function getDeviceId() {
-    const p = getDeviceIdPath();
+export function atomicWriteFile(target, content) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const tmp = `${target}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
     try {
-        const existing = fs.readFileSync(p, "utf-8").trim();
-        if (existing)
-            return existing;
+        fs.writeFileSync(tmp, content, "utf-8");
+        try {
+            fs.renameSync(tmp, target);
+        }
+        catch {
+            fs.writeFileSync(target, content, "utf-8");
+        }
+    }
+    finally {
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch {
+            /* already renamed, or gone */
+        }
+    }
+}
+function readTrimmed(p) {
+    try {
+        const s = fs.readFileSync(p, "utf-8").trim();
+        return s.length > 0 ? s : null;
     }
     catch {
-        // first run
+        return null;
     }
-    const raw = `${os.hostname()}::${crypto.randomBytes(16).toString("hex")}`;
-    const id = crypto.createHash("sha256").update(raw).digest("hex").slice(0, 32);
+}
+function sleepSync(ms) {
     try {
-        fs.mkdirSync(path.dirname(p), { recursive: true });
-        fs.writeFileSync(p, id, "utf-8");
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
     }
     catch {
-        // read-only FS: return the ephemeral id, refresh will still work
+        /* no Atomics.wait on this thread: retry immediately */
     }
-    return id;
 }
-function readLastCheck() {
+/**
+ * Create `target` with `content` only if it does not exist yet, and return
+ * whatever the file holds afterwards: ours if we created it, the other
+ * writer's if they got there first. The content is staged in a temp file and
+ * hard-linked into place, so the file never exists empty; filesystems without
+ * hard links fall back to an exclusive create. A file that exists but is
+ * empty (a writer that died mid-write, or an exclusive create on a filesystem
+ * without hard links whose writer never finished) is replaced after a short
+ * wait, the Rust engine's rule: otherwise every caller would mint a new id
+ * that is never saved, and each check-in would register another device.
+ * Returns null when nothing can be written (read-only home).
+ */
+export function createFileIfAbsent(target, content) {
+    const existing = readTrimmed(target);
+    if (existing)
+        return existing;
     try {
-        const s = fs.readFileSync(getLastCheckPath(), "utf-8").trim();
-        const n = Number(s);
-        return Number.isFinite(n) ? n : 0;
+        fs.mkdirSync(path.dirname(target), { recursive: true });
     }
     catch {
-        return 0;
+        return null;
+    }
+    const tmp = `${target}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+    try {
+        fs.writeFileSync(tmp, content, "utf-8");
+        try {
+            fs.linkSync(tmp, target);
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== "EEXIST") {
+                try {
+                    fs.writeFileSync(target, content, { encoding: "utf-8", flag: "wx" });
+                }
+                catch {
+                    /* someone else created it, or we cannot write: read below */
+                }
+            }
+        }
+    }
+    catch {
+        /* cannot even stage the temp file */
+    }
+    finally {
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    // An exclusive create by another writer can be visible before its content
+    // is: give a writer that is still running a moment rather than mint a
+    // second id. A file untouched for longer than that is a dead writer's.
+    if (!emptyFileIsStale(target)) {
+        for (let i = 0; i < 20; i++) {
+            const now = readTrimmed(target);
+            if (now)
+                return now;
+            sleepSync(10);
+        }
+    }
+    const now = readTrimmed(target);
+    if (now)
+        return now;
+    if (!fs.existsSync(target))
+        return null;
+    // Still empty: replace it, then return what the file holds (a writer that
+    // raced us to the same repair may have won; its id is the machine's).
+    try {
+        atomicWriteFile(target, content);
     }
+    catch {
+        return null;
+    }
+    return readTrimmed(target);
+}
+/** True when `target` exists and was last written over 2 s ago. */
+function emptyFileIsStale(target) {
+    try {
+        return Date.now() - fs.statSync(target).mtimeMs > 2_000;
+    }
+    catch {
+        return false;
+    }
+}
+/** A new random device id: sha256(hostname::16 random bytes), 32 hex chars. */
+export function mintDeviceId() {
+    const raw = `${os.hostname()}::${crypto.randomBytes(16).toString("hex")}`;
+    return crypto.createHash("sha256").update(raw).digest("hex").slice(0, 32);
+}
+/**
+ * Stable anonymous device identifier, shared by every vexp client on the
+ * machine through `<home>/.vexp/device.id`. First caller creates it. Uses the
+ * OS hostname + a random salt — no PII, no hardware fingerprinting. The server
+ * counts these as devices, so two ids for one machine would burn two slots:
+ * the file is created only if absent and whoever loses the race adopts the
+ * winner's id.
+ */
+export function getDeviceId() {
+    const p = getDeviceIdPath();
+    const existing = readTrimmed(p);
+    if (existing)
+        return existing;
+    const id = mintDeviceId();
+    // Read-only FS: return the ephemeral id, refresh will still work.
+    return createFileIfAbsent(p, id) ?? id;
+}
+function readLastCheck() {
+    const s = readTrimmed(getLastCheckPath());
+    if (!s)
+        return 0;
+    const n = Number(s);
+    return Number.isFinite(n) ? n : 0;
+}
+/**
+ * When this machine last heard back from vexp.dev (a registration, a device
+ * cap refusal or a revocation), or null if it never has. Read from the same
+ * stamp that throttles the check-in, so every client reports the same date.
+ */
+export function lastCheckIn() {
+    const ts = readLastCheck();
+    return ts > 0 ? new Date(ts) : null;
 }
 /** Forget when we last checked in, so the next refresh is not throttled. */
 export function clearLastCheck() {
@@ -86,28 +241,19 @@ export function clearLastCheck() {
 }
 function writeLastCheck(ts) {
     try {
-        fs.mkdirSync(path.dirname(getLastCheckPath()), { recursive: true });
-        fs.writeFileSync(getLastCheckPath(), String(ts), "utf-8");
+        atomicWriteFile(getLastCheckPath(), String(ts));
     }
     catch {
         // ignore
     }
 }
 function loadFreshToken() {
-    try {
-        const jwt = fs.readFileSync(getFreshTokenPath(), "utf-8").trim();
-        if (!jwt)
-            return null;
-        return verifyAndDecode(jwt);
-    }
-    catch {
-        return null;
-    }
+    const jwt = readTrimmed(getFreshTokenPath());
+    return jwt ? verifyAndDecode(jwt) : null;
 }
 function saveFreshToken(jwt) {
     try {
-        fs.mkdirSync(path.dirname(getFreshTokenPath()), { recursive: true });
-        fs.writeFileSync(getFreshTokenPath(), jwt, "utf-8");
+        atomicWriteFile(getFreshTokenPath(), jwt);
     }
     catch {
         // ignore
@@ -121,8 +267,34 @@ function removeFreshToken() {
         // ignore
     }
 }
+/**
+ * Replace the long JWT on disk, but never with an older one. The Rust engine
+ * and the VS Code extension roll this file too; a slower writer holding a
+ * token minted earlier must not wind the machine back. Returns true when the
+ * file now holds `jwt`.
+ */
+function writeLongTokenIfNewer(jwt) {
+    const next = verifyAndDecode(jwt);
+    if (!next)
+        return false;
+    const currentJwt = readTrimmed(getLicensePath());
+    const current = currentJwt ? verifyAndDecode(currentJwt) : null;
+    if (current && current.exp > next.exp)
+        return false;
+    if (currentJwt === jwt)
+        return true;
+    try {
+        atomicWriteFile(getLicensePath(), jwt);
+        return true;
+    }
+    catch {
+        // read-only FS: the freshToken still carries the new entitlement for this
+        // session; we just can't persist the long JWT.
+        return false;
+    }
+}
 function getDeviceBlockedPath() {
-    return path.join(vexpHomeDir(), ".vexp", "device_blocked.json");
+    return path.join(vexpDir(), "device_blocked.json");
 }
 /** Returns the active device-blocked marker, if any. */
 export function readDeviceBlocked() {
@@ -143,8 +315,7 @@ export function readDeviceBlocked() {
 }
 function writeDeviceBlocked(info) {
     try {
-        fs.mkdirSync(path.dirname(getDeviceBlockedPath()), { recursive: true });
-        fs.writeFileSync(getDeviceBlockedPath(), JSON.stringify(info), "utf-8");
+        atomicWriteFile(getDeviceBlockedPath(), JSON.stringify(info));
     }
     catch {
         // ignore
@@ -158,33 +329,22 @@ function clearDeviceBlocked() {
         // ignore
     }
 }
+function num(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
 /**
- * Opportunistic online license refresh.
- *
- * Additive-only: any failure (network, 404, 5xx, timeout, server disabled)
- * results in a silent no-op. The caller keeps using the local long JWT
- * exactly as before. This MUST never throw.
+ * One POST to /api/license/validate, classified. No file is touched here:
+ * the caller decides whether to apply the answer ({@link applyValidateResult}),
+ * which lets a provisional activation ask first and change nothing on refusal.
+ * Never throws.
  */
-export async function tryOnlineRefresh(longJwt) {
-    // Global kill switch for users who want to stay fully offline
+async function callValidate(longJwt) {
     if (process.env.VEXP_OFFLINE === "1")
-        return;
-    // Rate limit: at most one network call per REFRESH_BACKOFF_MS,
-    // UNLESS the long JWT is within the last 7 days of validity.
-    // That window is where expiry is imminent — bypass backoff so any
-    // CLI invocation in the danger zone attempts a refresh.
-    const last = readLastCheck();
-    const longClaims = verifyAndDecode(longJwt);
-    const nearExpiryMs = 7 * 24 * 60 * 60 * 1000;
-    const nearExpiry = longClaims
-        ? longClaims.exp * 1000 - Date.now() < nearExpiryMs
-        : false;
-    if (!nearExpiry && Date.now() - last < REFRESH_BACKOFF_MS)
-        return;
+        return { outcome: { kind: "offline" } };
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), VALIDATE_TIMEOUT_MS);
     try {
-        const res = await fetch(`${VEXP_WEB_ORIGIN}/api/license/validate`, {
+        const res = await fetch(`${webOrigin()}/api/license/validate`, {
             method: "POST",
             headers: { "content-type": "application/json" },
             body: JSON.stringify({
@@ -194,70 +354,216 @@ export async function tryOnlineRefresh(longJwt) {
             }),
             signal: controller.signal,
         });
-        clearTimeout(timer);
-        // 404 = endpoint not deployed yet (old server), 503 = kill switch
-        if (res.status === 404 || res.status === 503) {
-            return;
-        }
+        // 404 = endpoint not deployed (old server), 503 = kill switch.
         if (!res.ok)
-            return;
-        const data = (await res.json());
-        if (data && data.valid && data.freshToken) {
-            // Only save if the freshToken itself verifies locally
-            if (verifyAndDecode(data.freshToken)) {
-                saveFreshToken(data.freshToken);
-                // The server re-issued the 30-day long token (rolled forward on every
-                // refresh since vexp-web 3.1; also on entitlement change). Overwrite
-                // the on-disk long JWT so the current entitlement survives even fully
-                // offline and a superseded one stops working — without the user
-                // re-pasting a key. Only persist if it verifies locally.
-                if (data.newLongToken && verifyAndDecode(data.newLongToken)) {
-                    try {
-                        const licensePath = getLicensePath();
-                        fs.mkdirSync(path.dirname(licensePath), { recursive: true });
-                        fs.writeFileSync(licensePath, data.newLongToken, "utf-8");
-                    }
-                    catch {
-                        // read-only FS: the freshToken still carries the new entitlement
-                        // for this session; we just can't persist the long JWT.
-                    }
-                }
-                writeLastCheck(Date.now());
-                // Any previous device-blocked state is stale once the server issues
-                // a freshToken for us — we are back in a good state.
-                clearDeviceBlocked();
+            return { outcome: { kind: "http", status: res.status } };
+        let data;
+        try {
+            data = (await res.json());
+        }
+        catch {
+            return { outcome: { kind: "rejected", reason: "unreadable_response" } };
+        }
+        if (!data || typeof data !== "object") {
+            return { outcome: { kind: "rejected", reason: "unreadable_response" } };
+        }
+        if (data.valid && data.freshToken) {
+            // Only trust a freshToken that verifies locally.
+            if (!verifyAndDecode(data.freshToken)) {
+                return { outcome: { kind: "rejected", reason: "unverifiable_token" }, data };
             }
+            // An old server never sends deviceRegistered and registers whenever it
+            // answers valid; a 3.3+ server says false when the device store did
+            // not take this device, and then nothing may claim it is registered.
+            if (data.deviceRegistered === false)
+                return { outcome: { kind: "unconfirmed" }, data };
+            return {
+                outcome: {
+                    kind: "registered",
+                    currentDevices: num(data.currentDevices),
+                    maxDevices: num(data.maxDevices),
+                },
+                data,
+            };
         }
-        else if (data && data.reason === "device_limit_exceeded") {
+        if (data.reason === "device_limit_exceeded") {
+            return {
+                outcome: {
+                    kind: "device_limit_exceeded",
+                    currentDevices: num(data.currentDevices),
+                    maxDevices: num(data.maxDevices) ?? 4,
+                    manageUrl: data.manageUrl ?? "https://vexp.dev/account/devices",
+                },
+                data,
+            };
+        }
+        if (data.revoked) {
+            return {
+                outcome: { kind: data.reason === "deactivated" ? "deactivated" : "revoked" },
+                data,
+            };
+        }
+        return { outcome: { kind: "rejected", reason: data.reason ?? "not_valid" }, data };
+    }
+    catch (err) {
+        // network error, timeout, abort
+        return { outcome: { kind: "unreachable", detail: networkErrorDetail(err) } };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * What actually failed. Node's fetch reports every network failure as
+ * "fetch failed" and keeps the cause (ECONNREFUSED, ENOTFOUND, a TLS code
+ * such as SELF_SIGNED_CERT_IN_CHAIN) one level down.
+ */
+export function networkErrorDetail(err) {
+    if (!(err instanceof Error))
+        return String(err);
+    if (err.name === "AbortError" || err.name === "TimeoutError")
+        return "timed out";
+    const cause = err.cause;
+    if (cause && typeof cause === "object") {
+        if (typeof cause.code === "string" && cause.code)
+            return cause.code;
+        if (typeof cause.message === "string" && cause.message)
+            return cause.message;
+    }
+    return err.message;
+}
+const CERT_ERROR = /CERT|SELF_SIGNED|UNABLE_TO_GET_ISSUER|UNABLE_TO_VERIFY|DEPTH_ZERO|ERR_TLS/i;
+/**
+ * One line of advice for an unreachable vexp.dev, or null. A proxy or an
+ * antivirus that re-signs HTTPS (common on company Windows machines) makes
+ * every check-in fail the same way, so "it will register on its next
+ * check-in" never comes true until Node trusts that certificate.
+ */
+export function unreachableHint(detail) {
+    if (!detail)
+        return null;
+    if (CERT_ERROR.test(detail)) {
+        return `The HTTPS certificate was not trusted (${detail}): a proxy or antivirus is probably inspecting HTTPS. Point NODE_EXTRA_CA_CERTS at its root certificate, or set NODE_USE_SYSTEM_CA=1 (Node 23.8 or later).`;
+    }
+    return `Cause: ${detail}.`;
+}
+/**
+ * Persist what the server said, exactly as every vexp client does, and
+ * return what the check-in came to. `sentJwt` is the long token that was
+ * posted: if license.jwt no longer holds it (another client activated a
+ * different key while the call was in flight), the answer is about the old
+ * key and nothing is written, or its tokens would replace the key just
+ * activated (the Rust engine's rule).
+ */
+function applyValidateResult(outcome, data, sentJwt) {
+    const writes = outcome.kind === "registered" ||
+        outcome.kind === "unconfirmed" ||
+        outcome.kind === "device_limit_exceeded" ||
+        outcome.kind === "revoked" ||
+        outcome.kind === "deactivated";
+    if (writes && readTrimmed(getLicensePath()) !== sentJwt) {
+        return { kind: "rejected", reason: "license_changed" };
+    }
+    switch (outcome.kind) {
+        case "registered":
+        case "unconfirmed": {
+            if (!data?.freshToken)
+                return outcome;
+            saveFreshToken(data.freshToken);
+            // The server re-issued the 30-day long token (rolled forward on every
+            // refresh since vexp-web 3.1; also on entitlement change). Replace the
+            // on-disk long JWT so the current entitlement survives even fully
+            // offline and a superseded one stops working — without the user
+            // re-pasting a key. Only if it verifies, and never with an older one.
+            if (data.newLongToken)
+                writeLongTokenIfNewer(data.newLongToken);
+            // Any previous device-blocked state is stale once the server issues
+            // a freshToken for us — we are back in a good state.
+            clearDeviceBlocked();
+            // The stamp says "this machine checked in and is on the device list".
+            // An unconfirmed answer is not that: no stamp, so the next check-in
+            // (any client) asks again instead of waiting a day.
+            if (outcome.kind === "registered")
+                writeLastCheck(Date.now());
+            return outcome;
+        }
+        case "device_limit_exceeded":
             // This machine is over the subscription's device cap. We do NOT touch
             // the long JWT on disk: the user still owns a valid subscription, they
             // just need to free a slot on vexp.dev/account/devices. We persist a
             // marker so the CLI can surface the error next time a command runs.
             writeDeviceBlocked({
                 at: Date.now(),
-                maxDevices: data.maxDevices ?? 4,
-                manageUrl: data.manageUrl ?? "https://vexp.dev/account/devices",
+                maxDevices: outcome.maxDevices,
+                manageUrl: outcome.manageUrl,
             });
             // Drop any stale freshToken so readLicenseLimits downgrades to FREE
             // until the user frees a slot and retries.
             removeFreshToken();
             writeLastCheck(Date.now());
-        }
-        else if (data && data.revoked) {
+            return outcome;
+        case "revoked":
+        case "deactivated":
             // Server confirmed revocation. Drop the cached freshToken but keep
             // the long JWT on disk — the user will fall back to whatever the
             // long JWT allows until it expires naturally.
             removeFreshToken();
             writeLastCheck(Date.now());
-        }
+            return outcome;
+        default:
+            // offline / unreachable / http / rejected: nothing changes, and no
+            // stamp, so the next command tries again.
+            return outcome;
     }
-    catch {
-        // network error, timeout, abort — silent no-op
+}
+/**
+ * Opportunistic online license refresh: the check-in that registers this
+ * device and rolls the tokens.
+ *
+ * Additive-only: any failure (network, 404, 5xx, timeout, server disabled)
+ * leaves the local long JWT in charge exactly as before. It now RETURNS what
+ * happened instead of swallowing it, so the commands a person runs can say
+ * whether this machine is registered. Never throws.
+ *
+ * `force` skips the 24 h throttle (activation, an explicit status check).
+ */
+export async function tryOnlineRefresh(longJwt, opts = {}) {
+    try {
+        // Global kill switch for users who want to stay fully offline
+        if (process.env.VEXP_OFFLINE === "1")
+            return { kind: "offline" };
+        const longClaims = verifyAndDecode(longJwt);
+        if (!longClaims)
+            return { kind: "no_license" };
+        // Rate limit: at most one network call per REFRESH_BACKOFF_MS,
+        // UNLESS the long JWT is within the last 7 days of validity.
+        // That window is where expiry is imminent — bypass backoff so any
+        // CLI invocation in the danger zone attempts a refresh. A machine the
+        // server refused for the device cap is not throttled either: the user
+        // was told to free a slot and run a command, and the refusal itself
+        // stamped the throttle, so the retry would otherwise wait a day.
+        if (!opts.force && !readDeviceBlocked()) {
+            const last = readLastCheck();
+            const nearExpiryMs = 7 * 24 * 60 * 60 * 1000;
+            const nearExpiry = longClaims.exp * 1000 - Date.now() < nearExpiryMs;
+            if (!nearExpiry && Date.now() - last < REFRESH_BACKOFF_MS) {
+                return { kind: "throttled" };
+            }
+        }
+        const { outcome, data } = await callValidate(longJwt);
+        return applyValidateResult(outcome, data, longJwt);
     }
-    finally {
-        clearTimeout(timer);
+    catch (err) {
+        return { kind: "unreachable", detail: networkErrorDetail(err) };
     }
 }
+/** Check in with the long JWT on disk (throttled unless `force`). */
+export async function refreshFromDisk(opts = {}) {
+    const longJwt = readTrimmed(getLicensePath());
+    if (!longJwt)
+        return { kind: "no_license" };
+    return tryOnlineRefresh(longJwt, opts);
+}
 function verifyAndDecode(jwt) {
     try {
         const parts = jwt.split(".");
@@ -267,7 +573,7 @@ function verifyAndDecode(jwt) {
         const signingInput = `${headerB64}.${payloadB64}`;
         const signature = Buffer.from(signatureB64, "base64url");
         const publicKey = crypto.createPublicKey({
-            key: Buffer.from(VEXP_LICENSE_PUBLIC_KEY, "base64"),
+            key: Buffer.from(licensePublicKeyDer, "base64"),
             format: "der",
             type: "spki",
         });
@@ -286,16 +592,9 @@ const FREE_LIMITS = {
     allTools: false,
     plan: "free",
 };
-/** Activate a license key: verify and save to ~/.vexp/license.jwt */
-export function activateLicense(jwt) {
-    const claims = verifyAndDecode(jwt);
-    if (!claims)
-        throw new Error("Invalid license key (signature verification failed)");
-    if (claims.exp * 1000 < Date.now())
-        throw new Error("License key has expired");
-    const licensePath = getLicensePath();
-    fs.mkdirSync(path.dirname(licensePath), { recursive: true });
-    fs.writeFileSync(licensePath, jwt, "utf-8");
+/** Install `jwt` as this machine's license (no network). */
+function installLicense(jwt) {
+    atomicWriteFile(getLicensePath(), jwt);
     // The freshly activated long JWT is authoritative. Drop any cached
     // freshToken: it may be a 7-day token minted at the PREVIOUS tier, and both
     // readLicenseLimits() and the Rust daemon prefer fresh.jwt over license.jwt —
@@ -310,8 +609,166 @@ export function activateLicense(jwt) {
     // to register it" to someone who just did exactly that. Reported by a tier-4
     // user whose dashboard read 0 of 10 right after activating.
     clearLastCheck();
+}
+/** Activate a license key: verify and save to ~/.vexp/license.jwt (no
+ *  network; {@link activateAndRegister} is what the commands call). */
+export function activateLicense(jwt) {
+    const claims = verifyAndDecode(jwt);
+    if (!claims)
+        throw new Error("Invalid license key (signature verification failed)");
+    if (claims.exp * 1000 < Date.now())
+        throw new Error("License key has expired");
+    installLicense(jwt);
     return claims;
 }
+/**
+ * Activate a key AND register this device, awaiting the check-in: the one
+ * path both `vexp activate` and the interactive menu take, so neither can
+ * forget the registration again (the menu did, for months).
+ *
+ * A key whose signature verifies but whose 30-day token has expired (the
+ * AppSumo key from the purchase email, used after a month) is accepted
+ * provisionally: the server is asked first, and only its renewal installs
+ * it. Revoked, deactivated or unreachable: nothing on disk changes and the
+ * error says where to get the current key.
+ */
+export async function activateAndRegister(jwt) {
+    const key = jwt.trim();
+    const claims = verifyAndDecode(key);
+    if (!claims)
+        throw new Error("Invalid license key (signature verification failed)");
+    if (claims.exp * 1000 >= Date.now()) {
+        installLicense(key);
+        const outcome = await tryOnlineRefresh(key, { force: true });
+        return { claims, outcome, renewed: false };
+    }
+    // Expired: ask before touching anything.
+    const { outcome, data } = await callValidate(key);
+    switch (outcome.kind) {
+        case "registered":
+        case "unconfirmed":
+        case "device_limit_exceeded":
+            // The key is good (a full device list does not make it bad): install
+            // it, then let the answer roll it forward and register the device.
+            installLicense(key);
+            return { claims, outcome: applyValidateResult(outcome, data, key), renewed: true };
+        case "revoked":
+            throw new Error(`This license key has expired and vexp.dev reports it as revoked. Get your current key from ${ACCOUNT_URL}`);
+        case "deactivated":
+            throw new Error(`This license key has expired and vexp.dev reports it as deactivated. Get your current key from ${ACCOUNT_URL}`);
+        case "offline":
+            throw new Error(`This license key has expired and VEXP_OFFLINE=1 stops vexp from renewing it. Get your current key from ${ACCOUNT_URL}`);
+        case "unreachable":
+        case "http":
+            throw new Error(`This license key has expired and vexp.dev could not be reached to renew it. Get your current key from ${ACCOUNT_URL}`);
+        default:
+            throw new Error(`This license key has expired and vexp.dev did not renew it (${outcome.kind === "rejected" ? outcome.reason : outcome.kind}). Get your current key from ${ACCOUNT_URL}`);
+    }
+}
+/**
+ * The one line a person reads after activating or checking the license: is
+ * this machine registered, and if not, what happens next. `ok` is false when
+ * something needs their attention; `hint`, when present, is a second line
+ * with the cause (an unreachable vexp.dev says why).
+ */
+export function registrationLine(outcome) {
+    switch (outcome.kind) {
+        case "registered": {
+            const counts = outcome.currentDevices !== undefined && outcome.maxDevices !== undefined
+                ? ` (${outcome.currentDevices} of ${outcome.maxDevices} devices)`
+                : "";
+            return { ok: true, text: `This device is registered with your license.${counts}` };
+        }
+        case "unconfirmed":
+            return {
+                ok: false,
+                text: "vexp.dev renewed your license but could not confirm this device on your account yet; run `vexp license` later to check again.",
+            };
+        case "throttled":
+            return { ok: true, text: "This device checked in with vexp.dev less than a day ago." };
+        case "unreachable": {
+            const hint = unreachableHint(outcome.detail);
+            return {
+                ok: false,
+                text: "Could not reach vexp.dev: vexp works offline and will register this device on its next check-in.",
+                ...(hint ? { hint } : {}),
+            };
+        }
+        case "http":
+            return {
+                ok: false,
+                text: `vexp.dev answered HTTP ${outcome.status}: vexp works offline and will register this device on its next check-in.`,
+            };
+        case "offline":
+            return {
+                ok: false,
+                text: "VEXP_OFFLINE=1 is set: this device is not registered with your license until vexp can check in with vexp.dev.",
+            };
+        case "revoked":
+            return {
+                ok: false,
+                text: `vexp.dev reports this license as revoked, so this device was not registered. Get your current key from ${ACCOUNT_URL}`,
+            };
+        case "deactivated":
+            return {
+                ok: false,
+                text: `vexp.dev reports this license as deactivated, so this device was not registered. Get your current key from ${ACCOUNT_URL}`,
+            };
+        case "device_limit_exceeded": {
+            const used = outcome.currentDevices ?? outcome.maxDevices;
+            return {
+                ok: false,
+                text: `This device is not registered: your license already has ${used} of ${outcome.maxDevices} devices. Free a slot at ${outcome.manageUrl}, then run \`vexp license\`.`,
+            };
+        }
+        case "no_license":
+            return { ok: false, text: "No license is active on this machine." };
+        case "rejected":
+            if (outcome.reason === "license_changed") {
+                return {
+                    ok: false,
+                    text: "The license key changed while vexp was checking in; the next check-in registers this device with the new key.",
+                };
+            }
+            return {
+                ok: false,
+                text: `vexp.dev did not register this device (${outcome.reason}). Get your current key from ${ACCOUNT_URL}`,
+            };
+    }
+}
+export function registrationState() {
+    const blocked = readDeviceBlocked();
+    if (blocked)
+        return { state: "blocked", blocked };
+    const at = lastCheckIn();
+    const fresh = loadFreshToken();
+    const freshValid = fresh !== null && fresh.exp * 1000 > Date.now();
+    if (at)
+        return freshValid ? { state: "registered", at } : { state: "not_registered", at };
+    return freshValid ? { state: "unconfirmed" } : { state: "never" };
+}
+/** A date and time the way the license screens print it. */
+export function formatCheckIn(at) {
+    return `${at.toLocaleDateString()} ${at.toLocaleTimeString()}`;
+}
+/** The status sentence for {@link registrationState}; `ok` only when registered. */
+export function registrationStateLine(r) {
+    switch (r.state) {
+        case "registered":
+            return { ok: true, text: `This device is registered with your license (last check-in ${formatCheckIn(r.at)}).` };
+        case "not_registered":
+            return { ok: false, text: `The last check-in (${formatCheckIn(r.at)}) did not register this device.` };
+        case "unconfirmed":
+            return { ok: false, text: "vexp.dev has not confirmed this device on your account yet." };
+        case "never":
+            return { ok: false, text: "This device has never checked in with vexp.dev, so it is not on your account's device list yet." };
+        case "blocked":
+            return {
+                ok: false,
+                text: `This device is not registered: the license's ${r.blocked.maxDevices} device slots are full; free one at ${r.blocked.manageUrl}.`,
+            };
+    }
+}
 /** Remove the current license file (and any cached freshToken) */
 export function deactivateLicense() {
     const licensePath = getLicensePath();
@@ -366,22 +823,16 @@ function claimsToLimits(claims) {
  *    (it was signed by the server during the last successful refresh).
  * 2. Otherwise, fall back to the long JWT in ~/.vexp/license.jwt exactly as
  *    before (this is the zero-change path for users who never hit the server).
- * 3. Fire a background refresh attempt. Any failure is silent — the caller
- *    never sees a network error.
+ * 3. Fire a background refresh attempt (unless `refresh: false`, for callers
+ *    that already awaited one). Any failure is silent — the caller never sees
+ *    a network error.
  *
  * The long JWT is NEVER deleted based on server response. The worst a
  * successful server revoke does is remove the cached freshToken, after
  * which the long JWT expires naturally at its own `exp`.
  */
-export function readLicenseLimits() {
-    const licensePath = getLicensePath();
-    let longJwt;
-    try {
-        longJwt = fs.readFileSync(licensePath, "utf-8").trim();
-    }
-    catch {
-        return FREE_LIMITS;
-    }
+export function readLicenseLimits(opts = {}) {
+    const longJwt = readTrimmed(getLicensePath());
     if (!longJwt)
         return FREE_LIMITS;
     const longClaims = verifyAndDecode(longJwt);
@@ -399,7 +850,8 @@ export function readLicenseLimits() {
     // CLI startup on the network. We send the long JWT *even if it's already
     // past `exp`*, because the server (Fix 3) accepts expired JWTs and
     // re-issues freshTokens as long as the Stripe subscription (`pe`) holds.
-    void tryOnlineRefresh(longJwt);
+    if (opts.refresh !== false)
+        void tryOnlineRefresh(longJwt);
     // Prefer a still-valid freshToken within the grace window
     const fresh = loadFreshToken();
     if (fresh && fresh.exp * 1000 > Date.now()) {