@aisa-one/cli 0.5.1 → 0.6.0

package/dist/commands/oauth-login.js

@@ -4,7 +4,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import { createInterface } from "node:readline/promises";
 import { error, hint, info, success } from "../utils/display.js";
-import { setApiKey } from "../config.js";
+import { replaceTokens, tokenExpiresAt } from "../config.js";
 import { maskKey } from "../config.js";
 import { httpFetch } from "../utils/http.js";
 import { canOpenBrowser } from "../utils/browser.js";
@@ -13,16 +13,14 @@ import { renderSignInPage } from "./signin-page.js";
 import { handOverSignInPage, SIGNIN_PAGE_TTL_MS } from "./serve-signin.js";
 /**
  * `aisa login` without a key: sign in once in a browser, come back with the
- * CLI's long-lived key.
+ * CLI's access and refresh tokens.
  *
  * The flow is the standard one every CLI converges on (gh, flyctl, claude):
  *
  *   1. register a public OAuth client (Clerk supports dynamic registration)
  *   2. authorization-code + PKCE, redirecting to a loopback port
  *   3. exchange the code for an access token
- *   4. trade that token for the durable "aisa cli" key at /v1/keys/mint,
- *      and store the key — the token itself is then dropped. One secret on
- *      disk, and it is the one that does not expire in a day.
+ *   4. store access/refresh tokens and the registered client ID for silent refresh.
  *
  * A machine with no browser of its own takes the paste-back variant, and it
  * is chosen for the user rather than asked for: the URL is printed, the user
@@ -32,7 +30,7 @@ import { handOverSignInPage, SIGNIN_PAGE_TTL_MS } from "./serve-signin.js";
  * the verifier never left this machine. What travels through the clipboard
  * is a one-time code, not a key.
  */
-const AUTH_SERVER = "https://clerk.aisa.one";
+import { AUTH_SERVER } from "../constants.js";
 /**
  * Where the sign-in lands when the browser is on a different machine.
  *
@@ -46,7 +44,6 @@ const AUTH_SERVER = "https://clerk.aisa.one";
  * have to be added alongside.
  */
 const HOSTED_REDIRECT = "https://aisa.one/cli/auth";
-const MINT_URL = "https://api.aisa.one/v1/keys/mint";
 const b64url = (buf) => buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 async function registerClient(redirectUri) {
     const res = await httpFetch(`${AUTH_SERVER}/oauth/register`, {
@@ -55,10 +52,10 @@ async function registerClient(redirectUri) {
         body: JSON.stringify({
             client_name: "AIsa CLI",
             redirect_uris: [redirectUri],
-            grant_types: ["authorization_code"],
+            grant_types: ["authorization_code", "refresh_token"],
             response_types: ["code"],
             token_endpoint_auth_method: "none",
-            scope: "openid profile email",
+            scope: "openid profile email offline_access",
         }),
         signal: AbortSignal.timeout(15_000),
     });
@@ -227,7 +224,7 @@ function openBrowser(url) {
     const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
     void run(cmd, [url], { timeout: 30_000 }).catch(() => { });
 }
-export async function mintCliKey(options = {}) {
+export async function signInAndStoreTokens(options = {}) {
     const lang = options.lang ?? "en";
     // Unset means "work it out": a server has no browser to open and waiting
     // for a click on a machine with no screen is the worst way to find out.
@@ -253,7 +250,7 @@ export async function mintCliKey(options = {}) {
         response_type: "code",
         client_id: clientId,
         redirect_uri: redirectUri,
-        scope: "openid profile email",
+        scope: "openid profile email offline_access",
         state,
         code_challenge: challenge,
         code_challenge_method: "S256",
@@ -297,27 +294,28 @@ export async function mintCliKey(options = {}) {
         signal: AbortSignal.timeout(20_000),
     });
     const tokens = (await tokenRes.json());
-    if (!tokens.access_token) {
+    if (!tokenRes.ok || !tokens.access_token) {
         throw new Error(`token exchange failed: ${tokens.error_description ?? tokens.error ?? tokenRes.status}`);
     }
-    // The token is a day-long credential; the key is the durable one. Trade up
-    // and keep only the key.
-    const mintRes = await httpFetch(MINT_URL, {
-        method: "POST",
-        headers: { Authorization: `Bearer ${tokens.access_token}` },
-        signal: AbortSignal.timeout(20_000),
-    });
-    if (mintRes.status === 404) {
-        // A deployment without the mint endpoint. The sign-in still proved the
-        // account works; the key just has to travel by hand once.
-        throw new Error("this deployment cannot issue CLI keys — copy one from https://console.aisa.one/api-keys and run: aisa login --key <key>");
+    if (typeof tokens.refresh_token !== "string" || !tokens.refresh_token.trim()) {
+        throw new Error("token exchange did not return a refresh token. Existing credentials were kept; retry sign-in with offline access enabled.");
     }
-    const minted = (await mintRes.json());
-    if (!mintRes.ok || !minted.key) {
-        throw new Error(`could not issue a key: ${minted.error ?? `HTTP ${mintRes.status}`}`);
-    }
-    setApiKey(minted.key);
-    return minted.key;
+    await replaceTokens(tokens.access_token, tokens.refresh_token, tokenExpiresAt(tokens.expires_in), clientId);
+    return tokens.access_token;
+}
+/** Commander after-help for `aisa login`. Mechanics only; runtime is unchanged. */
+export function loginHelpAfter() {
+    return `
+Default: open a browser this person can actually use (SSH/CI/no display skip the local open). The live authorize URL is printed at the same time — relay that exact URL immediately. Do not invent, shorten, or delay it.
+
+--no-browser needs a persistent interactive TTY. Agents request only the one-time redirect URL or code — never an API key, access token, or refresh token. Paste that result into this same living process once. Reuse a running login; do not start another. "Done" is not that input. If they cannot type here, relay the paste through chat into this PTY. An empty line cancels.
+
+If this process already timed out, or the URL/code is from an older run, start a fresh aisa login and use the new URL and its result. Do not reuse a stale paste.
+
+No browser and no TTY: this CLI cannot complete OAuth here. Normal setup is native MCP OAuth at https://tools.aisa.one/mcp.
+
+Do not report connected unless login stored credentials and the following balance check succeeded. aisa whoami and stored local credentials are not proof. Scripts/CI: AISA_API_KEY or --key.
+`;
 }
 export async function oauthLogin(options = {}) {
     if (options.open === false && !process.stdin.isTTY) {
@@ -326,8 +324,8 @@ export async function oauthLogin(options = {}) {
         process.exitCode = 1;
         return;
     }
-    const key = await mintCliKey(options);
+    const key = await signInAndStoreTokens(options);
     // The balance follows from the caller, so no "try aisa balance" here: being
     // told to go and check is worse than being shown.
-    success(`Signed in — CLI key ${maskKey(key)} stored`);
+    success(`Signed in — access token ${maskKey(key)} stored`);
 }

package/dist/commands/signin-page.js

@@ -53,14 +53,14 @@ const ENDING_MARKUP = [
     "  function tick() {",
     "    var left = Math.ceil((until - Date.now()) / 1000);",
     "    if (left <= 0) {",
-    '      show("This page has closed", "Nothing here is needed any more \u2014 your key was saved on the machine you signed in from.");',
+    '      show("This page has closed", "Nothing here is needed any more \u2014 return to your terminal to check the sign-in result.");',
     "      return;",
     "    }",
     // Silent until the last minute, as before: a countdown running for five
     // minutes is furniture. What changed is that it ends in a dialog rather
     // than in a line nobody was looking at.
     "    if (left > 60) { setTimeout(tick, 1000); return; }",
-    '    show("This page closes in " + left + " seconds", "You can close it now \u2014 your key is already saved.");',
+    '    show("This page closes in " + left + " seconds", "You can close it now \u2014 check your terminal for the sign-in result.");',
     "    setTimeout(tick, 1000);",
     "  }",
     "  tick();",
@@ -69,9 +69,8 @@ const ENDING_MARKUP = [
 ].join("\n");
 const COPY = {
     ok: {
-        kicker: "SIGNED IN",
-        title: "You're all set",
-        body: "Your key was created on the machine you started from — it never travelled through this browser. You can close this tab.",
+        kicker: "AUTHORIZED",
+        title: "Return to your terminal",
         /**
          * The one moment a mention of the console is welcome rather than in the
          * way — and a sentence, not a button.
@@ -171,7 +170,7 @@ export function renderSignInPage(outcome, closesAt) {
   <div class="wrap">
     <div class="tick"><span>${good ? "✓" : "!"}</span><b>${c.kicker}</b></div>
     <h1>${c.title}</h1>
-    <p>${c.body}</p>
+    ${c.body ? `<p>${c.body}</p>` : ""}
     ${c.cta
         ? `<p class="cta">${c.cta.before}<a href="${c.cta.href}" rel="noopener">${c.cta.domain}</a>${c.cta.after}</p>`
         : ""}

package/dist/commands/tools.js

@@ -1,6 +1,6 @@
 import ora from "ora";
 import chalk from "chalk";
-import { getApiKey, MISSING_API_KEY_GUIDANCE } from "../config.js";
+import { getAccessToken, MISSING_API_KEY_GUIDANCE } from "../config.js";
 import { CliError, EXIT_PARTIAL, EXIT_TRANSPORT, transportError } from "../cli-error.js";
 import { routerPost } from "../router.js";
 import { error as printError } from "../utils/display.js";
@@ -22,14 +22,14 @@ export async function callAction(options) {
 }
 async function runToolCommand(kind, operands, options, auth) {
     const prepared = await prepareRouterRequest(kind, operands, options);
-    const apiKey = auth.auth === "required" ? requireRouterKey(kind) : getApiKey();
+    const accessToken = auth.auth === "required" ? await requireRouterKey(kind) : await getAccessToken();
     const spinner = options.json ? undefined : ora(spinnerText(kind)).start();
     let result;
     try {
         result = await routerPost({
             operation: kind,
             body: prepared.body,
-            apiKey,
+            accessToken,
         });
     }
     catch (err) {
@@ -57,11 +57,11 @@ async function runToolCommand(kind, operands, options, auth) {
         process.exitCode = EXIT_PARTIAL;
     }
 }
-function requireRouterKey(kind) {
-    const key = getApiKey();
+async function requireRouterKey(kind) {
+    const key = await getAccessToken();
     if (!key) {
         throw new CliError(`${MISSING_API_KEY_GUIDANCE} ` +
-            `search and schema may be anonymous; ${kind} will not run without a key. ` +
+            `search and schema may be anonymous; ${kind} will not run without authentication. ` +
             `Do not invent a business result.`, EXIT_TRANSPORT);
     }
     return key;

package/dist/config.d.ts

@@ -1,10 +1,23 @@
-export declare function getApiKey(): string | undefined;
-/** Next step when no local credential is present. Browser login first; env/--key are CI. */
-export declare const AUTH_SETUP_GUIDANCE = "Run \"aisa login\". For CI, set AISA_API_KEY or use \"aisa login --key <key>\".";
-export declare const MISSING_API_KEY_GUIDANCE = "No API key found. Run \"aisa login\". For CI, set AISA_API_KEY or use \"aisa login --key <key>\".";
-export declare function requireApiKey(): string;
-export declare function setApiKey(key: string): void;
-export declare function clearApiKey(): void;
+export interface StoredTokens {
+    accessToken: string;
+    refreshToken?: string;
+    /** Unix timestamp in milliseconds. */
+    expiresAt?: number;
+    clientId?: string;
+}
+/** Next step when no local credential is present. */
+export { AUTH_SETUP_GUIDANCE, MISSING_API_KEY_GUIDANCE } from "./constants.js";
+export declare function getAccessToken(): Promise<string | undefined>;
+export declare function requireAccessToken(): Promise<string>;
+/** Low-level storage; interactive login must use replaceTokens to retire the previous grant. */
+export declare function storeTokens(accessToken: string, refreshToken?: string, expiresAt?: number, clientId?: string): Promise<void>;
+/** All reads, rotation and persistence are serialized across CLI processes. */
+export declare function refreshAccessToken(accessToken?: string): Promise<string | undefined>;
+export declare function tokenExpiresAt(expiresIn?: number): number | undefined;
+/** Replace a login only after revoking the previous OAuth grant. */
+export declare function replaceTokens(accessToken: string, refreshToken?: string, expiresAt?: number, clientId?: string): Promise<void>;
+export declare function revokeAndClearTokens(): Promise<boolean>;
+export declare function clearTokens(): Promise<void>;
 export declare function getKeySource(): "env" | "config" | "none";
 export declare function getConfig(key: string): unknown;
 export declare function setConfig(key: string, value: string): void;

package/dist/config.js

@@ -1,27 +1,102 @@
 import Conf from "conf";
-import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { ENV_VAR_NAME } from "./constants.js";
-// ~/.aisa is the credential home: one visible, portable, platform-stable
-// place for the key, next door to ~/.claude and ~/.codex. The conf store
-// (platform-specific path, invisible to other tools) remains a legacy read
-// source and a sync target so older CLI versions keep working.
+import lockfile from "proper-lockfile";
+import { createHash, randomUUID } from "node:crypto";
+import { httpFetch } from "./utils/http.js";
+import { AUTH_SERVER, MISSING_API_KEY_GUIDANCE, ENV_VAR_NAME } from "./constants.js";
+// tokens.json is authoritative; conf is a write-only compatibility mirror.
 const aisaDir = () => join(homedir(), ".aisa");
 const keyFile = () => join(aisaDir(), "key");
-function readKeyFile() {
+const tokenFile = () => join(aisaDir(), "tokens.json");
+// Only call under withTokenLock, except the read-only source indicator.
+function readTokenFile() {
     try {
-        const k = readFileSync(keyFile(), "utf-8").trim();
-        return k || undefined;
+        const tokens = JSON.parse(readFileSync(tokenFile(), "utf-8"));
+        if (typeof tokens?.accessToken !== "string" || !tokens.accessToken)
+            throw new Error("Invalid token file. Restore it before changing credentials.");
+        return tokens;
     }
-    catch {
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function readLegacyKey() {
+    try {
+        return readFileSync(keyFile(), "utf-8").trim() || undefined;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function readTokens() {
+    const tokens = readTokenFile();
+    if (tokens)
+        return tokens;
+    const accessToken = readLegacyKey();
+    if (!accessToken)
         return undefined;
+    const migrated = { accessToken };
+    writeTokens(migrated);
+    return migrated;
+}
+async function withTokenLock(work) {
+    mkdirSync(aisaDir(), { recursive: true });
+    let compromised;
+    const release = await lockfile.lock(tokenFile(), {
+        realpath: false,
+        stale: 30_000,
+        update: 1_000,
+        retries: { retries: 400, factor: 1, minTimeout: 100, maxTimeout: 100 },
+        onCompromised: (error) => { compromised = error; },
+    });
+    // Fail closed before any writes if a suspended process loses its lease.
+    const previousGuard = assertTokenLock;
+    assertTokenLock = () => { if (compromised)
+        throw compromised; };
+    try {
+        return await work();
     }
+    finally {
+        assertTokenLock = previousGuard;
+        await release();
+    }
+}
+let assertTokenLock = () => { };
+const rotationFile = () => join(aisaDir(), ".token-rotation.json");
+const pendingFile = () => join(aisaDir(), ".pending-tokens.json");
+const tokenHash = (token) => createHash("sha256").update(token).digest("hex");
+function writeJson(path, value) {
+    assertTokenLock();
+    writeIndependentJson(path, value);
 }
-function writeKeyFile(key) {
+// Unique recovery files do not share a name and can be created without the main lock.
+function writeIndependentJson(path, value) {
     mkdirSync(aisaDir(), { recursive: true });
-    writeFileSync(keyFile(), key + "\n", { mode: 0o600 });
-    chmodSync(keyFile(), 0o600);
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, JSON.stringify(value) + "\n", { mode: 0o600 });
+        renameSync(temporary, path);
+    }
+    finally {
+        if (existsSync(temporary))
+            unlinkSync(temporary);
+    }
+}
+function removeFile(path) {
+    assertTokenLock();
+    try {
+        unlinkSync(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
 }
 /**
  * 0600, because this file holds credentials.
@@ -41,6 +116,7 @@ const config = new Conf({
     projectName: "aisa-cli",
     configFileMode: CONFIG_FILE_MODE,
     schema: {
+        tokens: { type: "object", default: {} },
         apiKey: { type: "string", default: "" },
         defaultModel: { type: "string", default: "gpt-4.1-mini" },
         baseUrl: { type: "string", default: "https://api.aisa.one/v1" },
@@ -63,58 +139,245 @@ try {
 catch {
     /* not ours to chmod, or gone — neither is worth failing a command over */
 }
-export function getApiKey() {
-    const envKey = process.env[ENV_VAR_NAME];
-    if (envKey)
-        return envKey;
-    const fileKey = readKeyFile();
-    if (fileKey)
-        return fileKey;
-    const stored = config.get("apiKey");
-    if (stored) {
-        // Legacy location — migrate on first read so every other tool (wrappers,
-        // scripts) finds the key at the one agreed place from now on.
-        try {
-            writeKeyFile(stored);
-        }
-        catch {
-            /* migration is best-effort; the key itself is still returned */
+/** Next step when no local credential is present. */
+export { AUTH_SETUP_GUIDANCE, MISSING_API_KEY_GUIDANCE } from "./constants.js";
+export async function getAccessToken() {
+    if (process.env[ENV_VAR_NAME])
+        return process.env[ENV_VAR_NAME];
+    return withTokenLock(async () => {
+        const tokens = readTokens();
+        if (!tokens)
+            return undefined;
+        if (canRefresh(tokens) && typeof tokens.expiresAt === "number" && tokens.expiresAt <= Date.now() + 60_000) {
+            return (await refreshLocked(tokens)) ?? tokens.accessToken;
         }
-        return stored;
-    }
-    return undefined;
+        return tokens.accessToken;
+    });
 }
-/** Next step when no local credential is present. Browser login first; env/--key are CI. */
-export const AUTH_SETUP_GUIDANCE = `Run "aisa login". For CI, set ${ENV_VAR_NAME} or use "aisa login --key <key>".`;
-export const MISSING_API_KEY_GUIDANCE = `No API key found. ${AUTH_SETUP_GUIDANCE}`;
-export function requireApiKey() {
-    const key = getApiKey();
-    if (!key) {
+export async function requireAccessToken() {
+    const token = await getAccessToken();
+    if (!token) {
         console.error(MISSING_API_KEY_GUIDANCE);
         process.exit(1);
     }
-    return key;
+    return token;
 }
-export function setApiKey(key) {
-    writeKeyFile(key);
-    config.set("apiKey", key);
+function makeTokens(accessToken, refreshToken, expiresAt, clientId) {
+    return accessToken.startsWith("sk-") ? { accessToken } : { accessToken, refreshToken, expiresAt, clientId };
 }
-export function clearApiKey() {
+/** Low-level storage; interactive login must use replaceTokens to retire the previous grant. */
+export async function storeTokens(accessToken, refreshToken, expiresAt, clientId) {
+    await withTokenLock(() => writeTokens(makeTokens(accessToken, refreshToken, expiresAt, clientId)));
+}
+function writeTokens(tokens, previousAccessToken) {
+    assertTokenLock();
+    // The rotated credential is authoritative. Auxiliary metadata must never
+    // prevent its persistence or turn a successful refresh into an old-token fallback.
+    writeJson(tokenFile(), tokens);
+    try {
+        if (previousAccessToken) {
+            writeJson(rotationFile(), { previous: tokenHash(previousAccessToken), current: tokenHash(tokens.accessToken) });
+        }
+        else
+            removeFile(rotationFile());
+    }
+    catch { /* rotation hints are optional; their hashes are checked before reuse */ }
     try {
-        if (existsSync(keyFile()))
-            unlinkSync(keyFile());
+        config.set("tokens", tokens);
+        config.set("apiKey", tokens.accessToken);
+        writeFileSync(keyFile(), tokens.accessToken + "\n", { mode: 0o600 });
+        chmodSync(keyFile(), 0o600);
     }
     catch {
-        /* the conf delete below still applies */
+        console.error("Credentials saved, but legacy credential mirrors could not be updated.");
     }
+}
+function canRefresh(tokens) {
+    return !tokens.accessToken.startsWith("sk-") &&
+        typeof tokens.refreshToken === "string" && !!tokens.refreshToken &&
+        typeof tokens.clientId === "string" && !!tokens.clientId;
+}
+/** All reads, rotation and persistence are serialized across CLI processes. */
+export async function refreshAccessToken(accessToken) {
+    if (process.env[ENV_VAR_NAME])
+        return undefined;
+    return withTokenLock(async () => {
+        const tokens = readTokens();
+        if (!tokens || !canRefresh(tokens))
+            return undefined;
+        if (accessToken && accessToken !== tokens.accessToken) {
+            try {
+                const rotation = JSON.parse(readFileSync(rotationFile(), "utf-8"));
+                return rotation.previous === tokenHash(accessToken) && rotation.current === tokenHash(tokens.accessToken)
+                    ? tokens.accessToken : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return refreshLocked(tokens);
+    });
+}
+async function refreshLocked(tokens) {
+    let next;
+    try {
+        const response = await httpFetch(`${AUTH_SERVER}/oauth/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: tokens.refreshToken, client_id: tokens.clientId }),
+            timeoutMs: 20_000, idempotent: false, redirect: "error",
+        });
+        if (!response.ok)
+            return undefined;
+        next = await response.json();
+        if (typeof next.access_token !== "string" || !next.access_token)
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        writeTokens(makeTokens(next.access_token, typeof next.refresh_token === "string" && next.refresh_token ? next.refresh_token : tokens.refreshToken, tokenExpiresAt(next.expires_in), tokens.clientId), tokens.accessToken);
+    }
+    catch {
+        throw new Error("Clerk refreshed the session, but the new credentials could not be saved. Restore credential-directory write access and sign in again.");
+    }
+    return next.access_token;
+}
+export function tokenExpiresAt(expiresIn) {
+    return typeof expiresIn === "number" && Number.isFinite(expiresIn) && expiresIn >= 0
+        ? Date.now() + expiresIn * 1000 : undefined;
+}
+async function revokeTokens(tokens) {
+    if (!tokens?.refreshToken || tokens.accessToken.startsWith("sk-"))
+        return false;
+    if (!tokens.clientId)
+        throw new Error("Stored OAuth client ID is missing. Credentials retained; server revocation could not be completed.");
+    let response;
+    try {
+        response = await httpFetch(`${AUTH_SERVER}/oauth/token/revoke`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({ token: tokens.refreshToken, token_type_hint: "refresh_token", client_id: tokens.clientId }),
+            timeoutMs: 20_000, idempotent: false, redirect: "error",
+        });
+    }
+    catch {
+        throw new Error("Could not reach Clerk to revoke the OAuth session. Credentials retained; retry the command.");
+    }
+    if (!response.ok)
+        throw new Error(`OAuth revocation failed (HTTP ${response.status}). Credentials retained; retry the command.`);
+    return true;
+}
+// A replacement is journaled before revoking the old grant. Failed cleanup
+// never discards the only copy of a newly issued, non-expiring refresh token.
+function readPending() {
+    let pending;
+    try {
+        pending = JSON.parse(readFileSync(pendingFile(), "utf-8"));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        pending = [];
+    }
+    // Import lock-acquisition failures atomically into the ordinary cleanup queue.
+    for (const name of readdirSync(aisaDir())) {
+        if (!/^\.pending-login-[0-9a-f-]+\.json$/.test(name))
+            continue;
+        const path = join(aisaDir(), name);
+        const recovered = JSON.parse(readFileSync(path, "utf-8"));
+        if (!pending.some((entry) => sameGrant(entry, recovered)))
+            pending.push(recovered);
+        writeJson(pendingFile(), pending);
+        removeFile(path);
+    }
+    return pending;
+}
+function sameGrant(a, b) {
+    return !!a && a.clientId === b.clientId && a.refreshToken === b.refreshToken &&
+        (b.refreshToken ? true : a.accessToken === b.accessToken);
+}
+async function cleanupPending(keep) {
+    const current = readTokenFile();
+    const pending = readPending();
+    for (let i = pending.length - 1; i >= 0; i--) {
+        if (keep && sameGrant(keep, pending[i]))
+            continue;
+        if (!sameGrant(current, pending[i]))
+            await revokeTokens(pending[i]);
+        pending.splice(i, 1);
+        writeJson(pendingFile(), pending);
+    }
+    if (!pending.length)
+        removeFile(pendingFile());
+}
+/** Replace a login only after revoking the previous OAuth grant. */
+export async function replaceTokens(accessToken, refreshToken, expiresAt, clientId) {
+    const next = makeTokens(accessToken, refreshToken, expiresAt, clientId);
+    let journaled = false;
+    try {
+        await withTokenLock(async () => {
+            const pending = readPending();
+            if (!pending.some((entry) => sameGrant(entry, next)))
+                pending.push(next);
+            writeJson(pendingFile(), pending);
+            journaled = true;
+            await cleanupPending(next);
+            const previous = readTokens();
+            if (previous?.refreshToken && previous.refreshToken === next.refreshToken && previous.clientId === next.clientId) {
+                writeTokens(next);
+                removeFile(pendingFile());
+                return;
+            }
+            await revokeTokens(previous);
+            writeTokens(next);
+            removeFile(pendingFile());
+        });
+    }
+    catch (error) {
+        if (!journaled && next.refreshToken) {
+            // Clerk already issued this grant before we attempted to acquire the lock.
+            // Preserve it independently so later login/logout can revoke it.
+            try {
+                writeIndependentJson(join(aisaDir(), `.pending-login-${randomUUID()}.json`), next);
+            }
+            catch {
+                try {
+                    await revokeTokens(next);
+                }
+                catch {
+                    throw new Error("Login failed; the newly issued OAuth grant could neither be saved for cleanup nor revoked. Check Clerk authorization management.");
+                }
+            }
+        }
+        throw error;
+    }
+}
+export async function revokeAndClearTokens() {
+    return withTokenLock(async () => {
+        await cleanupPending();
+        const revoked = await revokeTokens(readTokens());
+        clearTokensLocked();
+        return revoked;
+    });
+}
+export async function clearTokens() {
+    await withTokenLock(async () => {
+        await cleanupPending();
+        clearTokensLocked();
+    });
+}
+function clearTokensLocked() {
+    for (const path of [tokenFile(), keyFile(), rotationFile()])
+        removeFile(path);
+    config.delete("tokens");
     config.delete("apiKey");
 }
 export function getKeySource() {
     if (process.env[ENV_VAR_NAME])
         return "env";
-    if (readKeyFile() || config.get("apiKey"))
-        return "config";
-    return "none";
+    return readTokenFile() || readLegacyKey() ? "config" : "none";
 }
 export function getConfig(key) {
     return config.get(key);

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.5.1";
+export declare const VERSION = "0.6.0";
 /** Root of the platform. Per-surface bases are derived in api.ts#resolveBases. */
 export declare const BASE_URL = "https://api.aisa.one";
 export declare const ENV_VAR_NAME = "AISA_API_KEY";
@@ -103,3 +103,6 @@ export declare function categoryOf(providerId: string): string;
 export declare const API_CATEGORIES: readonly [...string[], "other"];
 export declare const MODEL_PROVIDERS: readonly ["openai", "anthropic", "google", "deepseek", "xai", "moonshot", "alibaba", "bytedance"];
 export type ModelProvider = (typeof MODEL_PROVIDERS)[number];
+export declare const AUTH_SERVER = "https://clerk.aisa.one";
+export declare const AUTH_SETUP_GUIDANCE = "Run \"aisa login\" to sign in with OAuth. For CI, set AISA_API_KEY or use \"aisa login --key <key>\".";
+export declare const MISSING_API_KEY_GUIDANCE = "Not authenticated. Run \"aisa login\" to sign in with OAuth. For CI, set AISA_API_KEY or use \"aisa login --key <key>\".";