@agentage/cli 0.38.0 → 0.39.0

package/dist/lib/auth/api.js

@@ -1,45 +1,52 @@
 import { mutateAuth } from '../fs/config.js';
-import { refreshTokens, TokenRequestError } from './oauth.js';
-import { requestHeaders } from '../net/user-agent.js';
+import { cliFetch, isRedirect } from '../net/fetch.js';
+import {} from '../net/origins.js';
 import { AuthRequiredError, isTerminalRefresh, TransientAuthError } from './auth-errors.js';
+import { refreshTokens, TokenRequestError, tokensFrom } from './oauth.js';
 export { AuthRequiredError, TransientAuthError } from './auth-errors.js';
-// Every authed call is CLI-originated; identify the caller alongside the bearer.
-const cliHeaders = () => requestHeaders();
-// Refresh the stored token in place. On success mutates auth + persists and returns. On failure it
-// throws: AuthRequiredError when the grant is dead (401/invalid_grant/invalid_client), else
-// TransientAuthError (429/5xx/network/timeout) - a blip that must not be read as a dead session.
-export const refreshOrThrow = async (auth, links) => {
-    if (auth.kind === 'pat')
-        throw new AuthRequiredError('personal access token expired or revoked - mint a new one in the dashboard (Settings -> API tokens)');
-    if (!auth.tokens.refreshToken)
-        throw new AuthRequiredError('no refresh token');
-    let fresh;
+const requestTokens = async (auth, links, rt) => {
     try {
-        fresh = await refreshTokens(links.auth, auth.clientId, auth.tokens.refreshToken);
+        return tokensFrom(await refreshTokens(links.auth, auth.clientId, rt), rt);
     }
     catch (err) {
         if (err instanceof TokenRequestError && isTerminalRefresh(err.status, err.oauthError))
             throw new AuthRequiredError('session expired');
         throw new TransientAuthError('refresh temporarily failed');
     }
-    const tokens = {
-        accessToken: fresh.access_token,
-        refreshToken: fresh.refresh_token ?? auth.tokens.refreshToken,
-        expiresAt: fresh.expires_in ? Date.now() + fresh.expires_in * 1000 : undefined,
-    };
-    auth.tokens = tokens; // the caller retries its request with this in-memory copy
-    // Persist under the lock, folding the new tokens onto the freshly-read state so a concurrent
-    // writer's other fields (clientId, siteFqdn) are not clobbered by a stale in-memory copy. A null
-    // re-read means a sign-out won the race: skip the write rather than resurrect it (issue #236).
+};
+// Never resurrect a sign-out (null) or overwrite a newer sign-in by another client.
+const persistTokens = async (clientId, tokens) => {
     await mutateAuth((current) => {
-        if (!current)
+        if (!current || current.clientId !== clientId)
             return null;
         current.tokens = tokens;
         return current;
     });
 };
-// Boolean shim for the request paths that just want "refresh once, then retry": any failure
-// (terminal or transient) collapses to false so they fall through to their own status handling.
+const refreshAndPersist = async (auth, links, rt) => {
+    const tokens = await requestTokens(auth, links, rt);
+    await persistTokens(auth.clientId, tokens);
+    return tokens;
+};
+// Keyed by refresh token: parallel 401s share one grant instead of racing its rotation.
+const inflight = new Map();
+const sharedRefresh = (auth, links, rt) => {
+    const pending = inflight.get(rt);
+    if (pending)
+        return pending;
+    const next = refreshAndPersist(auth, links, rt).finally(() => inflight.delete(rt));
+    inflight.set(rt, next);
+    return next;
+};
+// Throws AuthRequiredError for a dead grant, TransientAuthError for a blip (429/5xx/network).
+export const refreshOrThrow = async (auth, links) => {
+    if (auth.kind === 'pat')
+        throw new AuthRequiredError('personal access token expired or revoked - mint a new one in the dashboard (Settings -> API tokens)');
+    const rt = auth.tokens.refreshToken;
+    if (!rt)
+        throw new AuthRequiredError('no refresh token');
+    auth.tokens = await sharedRefresh(auth, links, rt); // the caller retries with this copy
+};
 const tryRefresh = async (auth, links) => {
     try {
         await refreshOrThrow(auth, links);
@@ -49,41 +56,28 @@ const tryRefresh = async (auth, links) => {
         return false;
     }
 };
-// redirect: 'manual' so the bearer is never replayed to a redirect target; any 3xx is an error.
-const isRedirect = (res) => res.type === 'opaqueredirect' || (res.status >= 300 && res.status < 400);
-export const authedGet = async (auth, links, url) => {
-    const call = () => fetch(url, {
-        headers: { authorization: `Bearer ${auth.tokens.accessToken}`, ...cliHeaders() },
-        redirect: 'manual',
-    });
-    let res = await call();
-    if (res.status === 401 && (await tryRefresh(auth, links)))
-        res = await call();
+const withBearer = (auth, init) => ({
+    ...init,
+    headers: { ...init.headers, authorization: `Bearer ${auth.tokens.accessToken}` },
+});
+// The raw Response after at most one refresh-and-retry on 401; callers branch on the status.
+export const authedFetch = async (auth, links, url, init = {}) => {
+    const res = await cliFetch(url, withBearer(auth, init));
+    if (res.status !== 401 || !(await tryRefresh(auth, links)))
+        return res;
+    await res.body?.cancel();
+    return cliFetch(url, withBearer(auth, init));
+};
+export const authedJson = async (auth, links, url, init = {}) => {
+    const method = init.method ?? 'GET';
+    const res = await authedFetch(auth, links, url, init);
     if (res.status === 401)
         throw new AuthRequiredError('session expired');
     if (isRedirect(res))
-        throw new Error(`GET ${url} refused redirect (${res.status})`);
+        throw new Error(`${method} ${url} refused redirect (${res.status})`);
     if (!res.ok)
-        throw new Error(`GET ${url} failed (${res.status})`);
+        throw new Error(`${method} ${url} failed (${res.status})`);
     return (await res.json());
 };
-// A bearer POST with the same refresh-once dance as authedGet. Unlike authedGet it returns the
-// raw Response (never throws on a non-2xx): callers branch on the status codes themselves.
-export const authedPost = async (auth, links, url, body) => {
-    const call = () => fetch(url, {
-        method: 'POST',
-        headers: {
-            authorization: `Bearer ${auth.tokens.accessToken}`,
-            'content-type': 'application/json',
-            ...cliHeaders(),
-        },
-        body: JSON.stringify(body),
-        redirect: 'manual',
-    });
-    let res = await call();
-    if (res.status === 401 && (await tryRefresh(auth, links)))
-        res = await call();
-    return res;
-};
 // Re-export the introspection surface so existing callers keep importing from './api.js'.
 export { introspectToken } from './introspect.js';

package/dist/lib/auth/callback-page.d.ts

@@ -0,0 +1,2 @@
+export declare const escapeHtml: (text: string) => string;
+export declare const callbackPage: (ok: boolean, detail: string) => string;

package/dist/lib/auth/callback-page.js

@@ -0,0 +1,40 @@
+// The one page the CLI ever serves: the sign-in result, on the design-system dark tokens.
+const LOGO = 'M143.8 33.7a13.2 13.2 0 00-23.6 0l-92.4 184.8a13.2 13.2 0 0015.4 18.6l66-18.9a13.2 13.2 0 ' +
+    '009.5-12.7v-60.3a13.2 13.2 0 1126.4 0v60.3a13.2 13.2 0 009.6 12.7l66 18.9a13.2 13.2 0 ' +
+    '0015.4-18.6l-92.3-184.8z';
+const STYLE = `
+*{margin:0;padding:0;box-sizing:border-box}
+html{color-scheme:dark}
+body{background:oklch(0.085 0.013 277);color:oklch(0.97 0.003 277);
+font-family:system-ui,-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;
+-webkit-font-smoothing:antialiased;min-height:100vh;display:grid;place-items:center;padding:24px}
+.card{background:oklch(0.17 0.018 277);border:1px solid oklch(0.237 0.017 277);border-radius:.75rem;
+padding:40px 32px;width:100%;max-width:400px;text-align:center;
+box-shadow:0 10px 15px -3px oklch(0 0 0/.1),0 4px 6px -4px oklch(0 0 0/.1)}
+.brand{display:inline-flex;align-items:center;gap:10px;margin-bottom:28px;font-weight:600;font-size:1rem}
+.brand svg{width:28px;height:28px}
+.icon{width:48px;height:48px;border-radius:9999px;margin:0 auto 20px;display:grid;place-items:center}
+.ok .icon{background:oklch(0.723 0.191 149.6/.15);color:oklch(0.723 0.191 149.6)}
+.err .icon{background:oklch(0.628 0.208 25.6/.15);color:oklch(0.628 0.208 25.6)}
+h1{font-size:1.25rem;font-weight:600;letter-spacing:-.02em;margin-bottom:8px}
+p{color:oklch(0.59 0.014 256);font-size:.875rem;line-height:1.5}
+.hint{margin-top:24px;font-size:.75rem;color:oklch(0.59 0.014 256)}
+`;
+const ICON = {
+    ok: '<svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>',
+    err: '<svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M18 6 6 18M6 6l12 12"/></svg>',
+};
+const ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' };
+// The error text comes from the authorization server's redirect: never trust it as markup.
+export const escapeHtml = (text) => text.replace(/[&<>"]/g, (c) => ESCAPES[c] ?? c);
+export const callbackPage = (ok, detail) => {
+    const kind = ok ? 'ok' : 'err';
+    const title = ok ? 'Signed in' : 'Sign-in failed';
+    const hint = ok ? 'You can close this tab.' : 'Run agentage setup again to retry.';
+    return (`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">` +
+        `<title>${title} - agentage</title><style>${STYLE}</style></head><body><main class="card ${kind}">` +
+        `<div class="brand"><svg viewBox="0 0 416 416" aria-hidden="true"><rect width="416" height="416" rx="83" fill="#f3a52b"/>` +
+        `<g transform="translate(25.7 25.7) scale(1.3812)"><path d="${LOGO}" fill="#000"/></g></svg>agentage</div>` +
+        `<div class="icon">${ICON[kind]}</div><h1>${title}</h1><p>${escapeHtml(detail)}</p>` +
+        `<p class="hint">${hint}</p></main></body></html>`);
+};

package/dist/lib/auth/callback-server.js

@@ -1,8 +1,5 @@
 import { createServer } from 'node:http';
-const page = (ok, detail) => '<!doctype html><html><head><meta charset="utf-8"><title>agentage</title></head>' +
-    '<body style="font-family:system-ui;display:grid;place-items:center;min-height:80vh">' +
-    `<div style="text-align:center"><h1>${ok ? 'Signed in' : 'Sign-in failed'}</h1>` +
-    `<p>${detail}</p></div></body></html>`;
+import { callbackPage as page } from './callback-page.js';
 export const startCallbackServer = (expectedState) => new Promise((resolveServer) => {
     let settle = null;
     let result = null;

package/dist/lib/auth/env-match.js

@@ -1,3 +1,4 @@
+import {} from '../fs/config.js';
 import { environment, normalizeFqdn } from '../net/origins.js';
 // The stored credential belongs to the environment it was issued for (auth.siteFqdn); the CLI's
 // current target comes from AGENTAGE_SITE_FQDN (production default). Introspecting a dev credential

package/dist/lib/auth/introspect.js

@@ -1,4 +1,6 @@
-import { authedGet, refreshOrThrow } from './api.js';
+import {} from '../fs/config.js';
+import {} from '../net/origins.js';
+import { authedJson, refreshOrThrow } from './api.js';
 import { AuthRequiredError, TransientAuthError } from './auth-errors.js';
 const isPast = (iso) => {
     if (!iso)
@@ -6,17 +8,14 @@ const isPast = (iso) => {
     const t = Date.parse(iso);
     return !Number.isNaN(t) && t <= Date.now();
 };
-const sleep = (ms) => new Promise((resolve) => {
-    // unref so a pending backoff never keeps `status` from exiting.
-    const timer = setTimeout(resolve, ms);
-    timer.unref();
-});
-// Introspection over global fetch: a network error reflects as a transient (a blip must not read as
-// a dead session), never letting the raw error escape to gatherStatus. Only a 401 stays terminal.
+const RETRY_BACKOFF_MS = 300;
+// Ref'd on purpose: an unref'd backoff let Node exit 13 mid-retry once nothing else held the loop.
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// Any failure but a 401 is a transient: a network blip must never read as a dead session.
 const getSession = async (auth, links) => {
     const url = `${links.auth}/api/auth/mcp/get-session`;
     try {
-        return await authedGet(auth, links, url);
+        return await authedJson(auth, links, url);
     }
     catch (err) {
         if (err instanceof AuthRequiredError)
@@ -75,7 +74,7 @@ const introspectOnce = async (auth, links) => {
     }
     return freshenIfStale(auth, links, body);
 };
-// A retry-once with a short unref'd backoff absorbs a lone transient blip; a terminal error skips it.
+// A retry-once with a short backoff absorbs a lone transient blip; a terminal error skips it.
 export const introspectToken = async (auth, links) => {
     try {
         return await introspectOnce(auth, links);
@@ -83,7 +82,7 @@ export const introspectToken = async (auth, links) => {
     catch (err) {
         if (err instanceof AuthRequiredError)
             throw err; // terminal: no point retrying a dead session
-        await sleep(300);
+        await sleep(RETRY_BACKOFF_MS);
         return introspectOnce(auth, links); // one transient-only retry; a 2nd transient propagates
     }
 };

package/dist/lib/auth/oauth.d.ts

@@ -1,3 +1,4 @@
+import { type StoredTokens } from '../fs/config.js';
 export interface PkcePair {
     verifier: string;
     challenge: string;
@@ -12,6 +13,7 @@ export interface TokenResponse {
 export declare const DEFAULT_SCOPE = "memory:read memory:write offline_access";
 export declare const pkcePair: () => PkcePair;
 export declare const randomState: () => string;
+export declare const tokensFrom: (res: TokenResponse, previousRefresh?: string) => StoredTokens;
 export declare const registerClient: (authUrl: string, redirectUri: string) => Promise<string>;
 export declare const buildAuthorizeUrl: (authUrl: string, params: {
     clientId: string;

package/dist/lib/auth/oauth.js

@@ -1,11 +1,11 @@
 import { createHash, randomBytes } from 'node:crypto';
-import { requestHeaders } from '../net/user-agent.js';
-// OAuth register/token/revoke are all CLI-originated; identify the caller on each.
-const cliHeaders = () => requestHeaders();
+import {} from '../fs/config.js';
+import { AUTH_TIMEOUT_MS, cliFetch } from '../net/fetch.js';
 const REGISTER_PATH = '/api/auth/mcp/register';
 const AUTHORIZE_PATH = '/api/auth/mcp/authorize';
 const TOKEN_PATH = '/api/auth/mcp/token';
 const REVOKE_PATH = '/api/auth/mcp/revoke';
+const REVOKE_TIMEOUT_MS = 3_000;
 export const DEFAULT_SCOPE = 'memory:read memory:write offline_access';
 export const pkcePair = () => {
     const verifier = randomBytes(32).toString('base64url');
@@ -13,18 +13,25 @@ export const pkcePair = () => {
     return { verifier, challenge };
 };
 export const randomState = () => randomBytes(16).toString('base64url');
+// A refresh that does not rotate keeps the previous refresh token.
+export const tokensFrom = (res, previousRefresh) => ({
+    accessToken: res.access_token,
+    refreshToken: res.refresh_token ?? previousRefresh,
+    expiresAt: res.expires_in ? Date.now() + res.expires_in * 1000 : undefined,
+});
+const registration = (redirectUri) => JSON.stringify({
+    client_name: 'agentage CLI',
+    redirect_uris: [redirectUri],
+    token_endpoint_auth_method: 'none',
+    grant_types: ['authorization_code', 'refresh_token'],
+    response_types: ['code'],
+});
 export const registerClient = async (authUrl, redirectUri) => {
-    const res = await fetch(`${authUrl}${REGISTER_PATH}`, {
+    const res = await cliFetch(`${authUrl}${REGISTER_PATH}`, {
         method: 'POST',
-        headers: { 'content-type': 'application/json', ...cliHeaders() },
-        body: JSON.stringify({
-            client_name: 'agentage CLI',
-            redirect_uris: [redirectUri],
-            token_endpoint_auth_method: 'none',
-            grant_types: ['authorization_code', 'refresh_token'],
-            response_types: ['code'],
-        }),
-    });
+        headers: { 'content-type': 'application/json' },
+        body: registration(redirectUri),
+    }, { timeoutMs: AUTH_TIMEOUT_MS });
     if (!res.ok)
         throw new Error(`client registration failed (${res.status})`);
     const body = (await res.json());
@@ -55,12 +62,13 @@ export class TokenRequestError extends Error {
         this.name = 'TokenRequestError';
     }
 }
+const formInit = (form) => ({
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams(form).toString(),
+});
 const postForm = async (url, form) => {
-    const res = await fetch(url, {
-        method: 'POST',
-        headers: { 'content-type': 'application/x-www-form-urlencoded', ...cliHeaders() },
-        body: new URLSearchParams(form).toString(),
-    });
+    const res = await cliFetch(url, formInit(form), { timeoutMs: AUTH_TIMEOUT_MS });
     if (!res.ok) {
         const body = (await res.json().catch(() => null));
         throw new TokenRequestError(res.status, body?.error);
@@ -79,18 +87,12 @@ export const refreshTokens = (authUrl, clientId, refreshToken) => postForm(`${au
     refresh_token: refreshToken,
     client_id: clientId,
 });
-// AbortSignal.timeout caps a stalled revoke on a packet-drop network; residual undici keepalive is
-// acceptable here since --disconnect exits right after and errors are swallowed anyway.
-export const revokeToken = async (authUrl, token, timeoutMs = 3000) => {
+// Best-effort with a short cap: local credentials are removed whatever the server says.
+export const revokeToken = async (authUrl, token, timeoutMs = REVOKE_TIMEOUT_MS) => {
     try {
-        await fetch(`${authUrl}${REVOKE_PATH}`, {
-            method: 'POST',
-            headers: { 'content-type': 'application/x-www-form-urlencoded', ...cliHeaders() },
-            body: new URLSearchParams({ token }).toString(),
-            signal: AbortSignal.timeout(timeoutMs),
-        });
+        await cliFetch(`${authUrl}${REVOKE_PATH}`, formInit({ token }), { timeoutMs });
     }
     catch {
-        // best-effort: local credentials are removed regardless
+        // a stalled or refused revoke never blocks sign-out
     }
 };

package/dist/lib/auth/sign-in.d.ts

@@ -0,0 +1,20 @@
+import { startCallbackServer } from './callback-server.js';
+import { introspectToken } from './introspect.js';
+import { exchangeCode, registerClient, revokeToken } from './oauth.js';
+export interface SignInOptions {
+    reauth?: boolean;
+    browser?: boolean;
+}
+export type SignInResult = 'signed-in' | 'already' | 'mismatch-resigned';
+export interface SignInDeps {
+    register: typeof registerClient;
+    exchange: typeof exchangeCode;
+    revoke: typeof revokeToken;
+    startServer: typeof startCallbackServer;
+    openBrowser: (url: string) => Promise<void>;
+    introspect: typeof introspectToken;
+    log: (msg: string) => void;
+}
+export declare const signIn: (opts: SignInOptions, deps?: SignInDeps) => Promise<void>;
+export declare const signOut: (deps?: SignInDeps) => Promise<void>;
+export declare const ensureSignedIn: (opts: SignInOptions, deps?: SignInDeps) => Promise<SignInResult>;

package/dist/lib/auth/sign-in.js

@@ -0,0 +1,95 @@
+import chalk from 'chalk';
+import { deleteAuth, ensureConfigDir, mutateAuth, readAuth } from '../fs/config.js';
+import { links, siteFqdn } from '../net/origins.js';
+import { AuthRequiredError } from './auth-errors.js';
+import { startCallbackServer } from './callback-server.js';
+import { detectEnvMismatch } from './env-match.js';
+import { introspectToken } from './introspect.js';
+import { buildAuthorizeUrl, exchangeCode, pkcePair, randomState, registerClient, revokeToken, tokensFrom, } from './oauth.js';
+const defaultDeps = {
+    register: registerClient,
+    exchange: exchangeCode,
+    revoke: revokeToken,
+    startServer: startCallbackServer,
+    openBrowser: async (url) => {
+        const { default: open } = await import('open');
+        await open(url);
+    },
+    introspect: introspectToken,
+    log: (msg) => console.log(msg),
+};
+const promptBrowser = async (url, opts, deps) => {
+    deps.log(`\nSign in to agentage (${siteFqdn()}):\n\n  ${url}\n`);
+    if (opts.browser === false)
+        deps.log('Open the URL above in a browser to continue.');
+    else
+        await deps
+            .openBrowser(url)
+            .catch(() => deps.log('Could not open a browser - use the URL above.'));
+    deps.log('Waiting for sign-in to complete...');
+};
+const authorize = async (server, state, opts, deps) => {
+    const authUrl = links(siteFqdn()).auth;
+    const { verifier, challenge } = pkcePair();
+    const clientId = await deps.register(authUrl, server.redirectUri);
+    const redirectUri = server.redirectUri;
+    const url = buildAuthorizeUrl(authUrl, { clientId, redirectUri, challenge, state });
+    await promptBrowser(url, opts, deps);
+    return { clientId, verifier, code: await server.waitForCode() };
+};
+// A fresh DCR client per run: the redirect URI binds this run's ephemeral callback port.
+export const signIn = async (opts, deps = defaultDeps) => {
+    const fqdn = siteFqdn();
+    ensureConfigDir();
+    const state = randomState();
+    const server = await deps.startServer(state);
+    try {
+        const { clientId, code, verifier } = await authorize(server, state, opts, deps);
+        const redirectUri = server.redirectUri;
+        const res = await deps.exchange(links(fqdn).auth, { clientId, code, redirectUri, verifier });
+        await mutateAuth(() => ({ siteFqdn: fqdn, clientId, tokens: tokensFrom(res) }));
+        deps.log(chalk.green('\nSigned in.\n'));
+    }
+    finally {
+        server.close();
+    }
+};
+export const signOut = async (deps = defaultDeps) => {
+    const auth = readAuth();
+    if (!auth) {
+        deps.log('Nothing to disconnect.');
+        return;
+    }
+    await deps.revoke(links(auth.siteFqdn).auth, auth.tokens.accessToken);
+    await deleteAuth();
+    deps.log('Disconnected - local credentials removed.');
+};
+const mismatchNote = (m) => `Signed in to ${m.credentialFqdn} (${m.credentialEnv}), but this run targets ` +
+    `${m.targetFqdn} (${m.targetEnv}) - signing you into ${m.targetEnv}.\n`;
+// Only a dead session re-signs: a transient verify failure keeps the credentials.
+const verifyStored = async (auth, deps) => {
+    try {
+        await deps.introspect(auth, links(auth.siteFqdn));
+        deps.log(`Already signed in. Run ${chalk.white('agentage setup --reauth')} to sign in again.\n`);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof AuthRequiredError) {
+            deps.log('Session expired - signing you in again.\n');
+            return false;
+        }
+        deps.log('You appear signed in (could not fully verify - temporary).\n');
+        return true;
+    }
+};
+// Never introspect a credential against another environment: it would misread as expired.
+export const ensureSignedIn = async (opts, deps = defaultDeps) => {
+    const stored = readAuth();
+    const mismatch = stored && !opts.reauth ? detectEnvMismatch(stored, siteFqdn()) : null;
+    if (mismatch)
+        deps.log(mismatchNote(mismatch));
+    else if (stored && !opts.reauth && (await verifyStored(stored, deps)))
+        return 'already';
+    await signIn(opts, deps);
+    return mismatch ? 'mismatch-resigned' : 'signed-in';
+};

package/dist/lib/fs/config.d.ts

@@ -15,6 +15,7 @@ export interface AuthState {
 }
 export declare const getConfigDir: () => string;
 export declare const ensureConfigDir: () => string;
+export declare const isAuthState: (value: unknown) => value is AuthState;
 export declare const readAuth: () => AuthState | null;
 export declare const saveAuth: (state: AuthState) => void;
 export declare const deleteAuth: () => Promise<void>;

package/dist/lib/fs/config.js

@@ -1,8 +1,8 @@
-import { randomBytes } from 'node:crypto';
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { existsSync, mkdirSync, unlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { withFileLock } from './file-lock.js';
+import { isRecord, readJson, writeJsonAtomic } from './json-file.js';
 export const getConfigDir = () => process.env['AGENTAGE_CONFIG_DIR'] || join(process.env['HOME'] || homedir(), '.agentage');
 export const ensureConfigDir = () => {
     const dir = getConfigDir();
@@ -11,27 +11,20 @@ export const ensureConfigDir = () => {
     return dir;
 };
 const authPath = () => join(getConfigDir(), 'auth.json');
-export const readAuth = () => {
-    const path = authPath();
-    if (!existsSync(path))
-        return null;
-    try {
-        return JSON.parse(readFileSync(path, 'utf-8'));
-    }
-    catch {
-        return null;
-    }
-};
-// Atomic 0600 write: a token file is never left half-written or briefly world-readable. Write a
-// per-save sibling temp (unique name: concurrent savers can never clobber each other's tmp),
-// chmod it 0600 BEFORE the rename, then rename over the target in one step.
+const isOptional = (value, type) => value === undefined || typeof value === type;
+const isStoredTokens = (value) => isRecord(value) &&
+    typeof value['accessToken'] === 'string' &&
+    isOptional(value['refreshToken'], 'string') &&
+    isOptional(value['expiresAt'], 'number');
+// A malformed auth.json (e.g. `{}`) reads as signed out rather than crashing every command.
+export const isAuthState = (value) => isRecord(value) &&
+    typeof value['siteFqdn'] === 'string' &&
+    typeof value['clientId'] === 'string' &&
+    isStoredTokens(value['tokens']);
+export const readAuth = () => readJson(authPath(), isAuthState);
 export const saveAuth = (state) => {
     ensureConfigDir();
-    const path = authPath();
-    const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
-    writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
-    chmodSync(tmp, 0o600);
-    renameSync(tmp, path);
+    writeJsonAtomic(authPath(), state);
 };
 // Sign-out under the same lock mutateAuth takes (issue #236), so a concurrent token refresh can
 // never slip its re-read+save between this existence check and the unlink.

package/dist/lib/fs/file-lock.d.ts

@@ -1,3 +1,8 @@
-export declare const acquireFileLock: (target: string, now?: number) => boolean;
+export interface LockOptions {
+    ttlMs?: number;
+    hardStaleMs?: number;
+    maxWaitMs?: number;
+}
+export declare const acquireFileLock: (target: string, now?: number, opts?: LockOptions) => boolean;
 export declare const releaseFileLock: (target: string) => void;
-export declare const withFileLock: <T>(target: string, fn: () => T) => Promise<T>;
+export declare const withFileLock: <T>(target: string, fn: () => T, opts?: LockOptions) => Promise<T>;