@moda-ai/cli 1.13.0 → 1.13.1

package/dist/auth.js

@@ -1,11 +1,20 @@
-// src/auth.ts — Browser-based authentication for moda init via frontend
+// src/auth.ts — Browser-based authentication for moda init via frontend.
+// Owns the interactive login flow (localhost callback server, PKCE exchange,
+// manual paste fallback) and authFetch. Session persistence lives in
+// ./auth-storage.ts; the moda_ct renew/revoke/401-classification lifecycle
+// lives in ./cli-session.ts — both re-exported here so auth.js stays the
+// single import surface for auth.
 import { createServer } from 'node:http';
-import { existsSync, readFileSync, rmSync } from 'node:fs';
-import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { hostname } from 'node:os';
 import { createInterface } from 'node:readline';
 import { resolveModaBaseUrl } from './config.js';
-import { CliAuthError } from './errors.js';
-import { getModaPaths, loadProfileConfig, saveProfileConfig, secretFilePathFromRef, writeSecretJsonFile, } from './profiles.js';
+import { CliAuthError, CliInputError } from './errors.js';
+import { loadProfileConfig } from './profiles.js';
+import { isModaCtSession, loadAuthSession, persistAuthSession, resolveStorageProfile, saveAuthSession, } from './auth-storage.js';
+import { classifyModaCtUnauthorized, cliSessionExpiredError, scheduleRenewalIfNearExpiry, } from './cli-session.js';
+export { clearAuthSession, isAuthSessionValid, loadAuthSession, loadToken, saveAuthSession, } from './auth-storage.js';
+export { revokeCliSessionToken } from './cli-session.js';
 const CALLBACK_PORT = 8432;
 // Fallback ports tried in order when CALLBACK_PORT is taken. The frontend
 // callback redirect is port-parameterized, so any of these works as long as
@@ -13,6 +22,8 @@ const CALLBACK_PORT = 8432;
 const CALLBACK_PORT_LADDER = [CALLBACK_PORT, 8433, 8434, 8435];
 const AUTH_TIMEOUT_MS = 120_000;
 const DEFAULT_EXPIRES_IN_SECONDS = 86_400;
+// PKCE code exchange against {base}/api/cli/auth/exchange.
+const EXCHANGE_TIMEOUT_MS = 10_000;
 function escapeHtml(value) {
     return value
         .replace(/&/g, '&')
@@ -28,140 +39,42 @@ function safeEqual(a, b) {
         return false;
     return timingSafeEqual(aBuf, bBuf);
 }
-function tokenPath(options = {}) {
-    return getModaPaths(options).legacyAuthPath;
+/**
+ * Classify a bare paste as a PKCE one-time code vs a legacy token. One-time
+ * codes are base64url(32 random bytes) = 43 chars with no dots; legacy Auth0
+ * access tokens are JWTs (dot-separated segments, hundreds of chars). Only
+ * pastes that plausibly ARE codes (base64url alphabet, code-sized) go down
+ * the exchange path — everything else keeps the legacy bare-token behavior.
+ * Collision analysis: every legacy Moda credential is a JWT, and a JWT always
+ * contains dots, so the dot-free 32-96 char band cannot match one — a paste
+ * classified as a code here is never a misrouted legacy token.
+ */
+function looksLikeOneTimeCode(value) {
+    return /^[A-Za-z0-9_-]{32,96}$/.test(value);
 }
-function authTokenRefForProfile(profile) {
-    return `file:secrets/auth/${profile}.json`;
+// --- PKCE (RFC 7636, S256) ---
+/** base64url(sha256(verifier)) — the S256 code challenge for a verifier. */
+export function computePkceChallenge(codeVerifier) {
+    return createHash('sha256').update(codeVerifier).digest('base64url');
 }
-function parseStoredAuth(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        return null;
-    }
-    const data = value;
-    if (typeof data.access_token !== 'string' ||
-        typeof data.expires_at !== 'number') {
-        return null;
-    }
-    return {
-        access_token: data.access_token,
-        expires_at: data.expires_at,
-        profile: typeof data.profile === 'string' ? data.profile : undefined,
-        token_type: data.token_type === 'bearer' ? 'bearer' : undefined,
-    };
-}
-export function isAuthSessionValid(data, now = Date.now()) {
-    if (!data)
-        return false;
-    return now / 1000 <= data.expires_at - 60;
+function generatePkceVerifier() {
+    // 32 random bytes -> 43 base64url chars, within the RFC 7636 43-128 range.
+    return randomBytes(32).toString('base64url');
 }
-function readStoredAuth(path) {
-    try {
-        if (!existsSync(path))
-            return null;
-        return parseStoredAuth(JSON.parse(readFileSync(path, 'utf8')));
-    }
-    catch {
+/**
+ * The most recent PKCE exchange response for THIS process, so `moda init`
+ * can skip one /api/cli/context round-trip right after login. Never
+ * persisted to disk. Keyed by the storage profile the login targeted, and
+ * cleared at the start of every login(), so a context from one profile's
+ * exchange can never leak into another profile's init.
+ */
+let cachedLoginContext = null;
+export function getCachedLoginContext(options = {}) {
+    if (!cachedLoginContext)
         return null;
-    }
-}
-export function loadToken(options = {}) {
-    return loadAuthSession(options)?.access_token ?? null;
-}
-export function loadAuthSession(options = {}) {
-    const profileSession = loadProfileAuthSession(options);
-    if (profileSession)
-        return profileSession;
-    const legacy = readStoredAuth(tokenPath(options));
-    if (!legacy)
-        return null;
-    if (!options.includeExpired && !isAuthSessionValid(legacy)) {
-        return null;
-    }
-    return legacy;
-}
-function loadProfileAuthSession(options) {
-    const profileName = options.profile ?? (options.env ?? process.env).MODA_PROFILE;
-    if (!profileName)
+    if (cachedLoginContext.profile !== resolveStorageProfile(options))
         return null;
-    try {
-        const profile = loadProfileConfig(options).profiles[profileName];
-        const tokenRef = profile?.auth_token_ref;
-        if (!tokenRef)
-            return null;
-        const path = secretFilePathFromRef(tokenRef, options);
-        if (!path)
-            return null;
-        const session = readStoredAuth(path);
-        if (!session)
-            return null;
-        if (!options.includeExpired && !isAuthSessionValid(session))
-            return null;
-        return session;
-    }
-    catch {
-        return null;
-    }
-}
-export function saveAuthSession(accessToken, expiresIn, options = {}) {
-    const profile = options.profile ?? (options.env ?? process.env).MODA_PROFILE;
-    const data = {
-        access_token: accessToken,
-        expires_at: Math.floor(Date.now() / 1000) + expiresIn,
-        profile,
-        token_type: 'bearer',
-    };
-    if (profile) {
-        const ref = authTokenRefForProfile(profile);
-        const path = secretFilePathFromRef(ref, options);
-        if (!path)
-            throw new Error(`Unsupported auth token reference: ${ref}`);
-        const config = loadProfileConfig(options);
-        const existing = config.profiles[profile];
-        if (!existing) {
-            throw new Error(`Moda profile '${profile}' does not exist.`);
-        }
-        writeSecretJsonFile(path, data);
-        saveProfileConfig({
-            ...config,
-            profiles: {
-                ...config.profiles,
-                [profile]: {
-                    ...existing,
-                    auth_token_ref: ref,
-                },
-            },
-        }, options);
-        return data;
-    }
-    writeSecretJsonFile(tokenPath(options), data);
-    return data;
-}
-export function clearAuthSession(options = {}) {
-    const profile = options.profile ?? (options.env ?? process.env).MODA_PROFILE;
-    if (profile) {
-        const ref = authTokenRefForProfile(profile);
-        const path = secretFilePathFromRef(ref, options);
-        if (path)
-            rmSync(path, { force: true });
-        const config = loadProfileConfig(options);
-        const existing = config.profiles[profile];
-        if (existing) {
-            const { auth_token_ref: _drop, ...profileWithoutToken } = existing;
-            saveProfileConfig({
-                ...config,
-                profiles: {
-                    ...config.profiles,
-                    [profile]: profileWithoutToken,
-                },
-            }, options);
-        }
-        return;
-    }
-    rmSync(tokenPath(options), { force: true });
-}
-function saveToken(accessToken, expiresIn, options = {}) {
-    saveAuthSession(accessToken, expiresIn, options);
+    return cachedLoginContext.context;
 }
 // --- Login Flow ---
 const SUCCESS_HTML = `<!DOCTYPE html>
@@ -201,8 +114,10 @@ function closeAuthServer(server) {
 }
 export async function login(screen = 'login', options = {}) {
     return new Promise((resolve, reject) => {
+        // A fresh login invalidates any context cached by a previous login in
+        // this process (which may have targeted a different profile).
+        cachedLoginContext = null;
         let settled = false;
-        const state = randomBytes(16).toString('hex');
         // An explicit callbackPort is used as-is (tests bind port 0 for an
         // ephemeral port); only the default flow walks the fallback ladder.
         const portsToTry = options.callbackPort !== undefined
@@ -211,19 +126,95 @@ export async function login(screen = 'login', options = {}) {
         let portIndex = 0;
         let localPort = portsToTry[0];
         let timeout;
-        // Manual-paste fallback state (used when the browser can't reach this box).
         let promptInput;
+        let promptStream;
         let promptStreamIsTTY = false;
-        // Holds a bare token awaiting the interactive [y/N] confirmation.
-        let pendingBareToken = null;
+        let pendingBarePaste = null;
+        let exchangeInFlight = false;
+        const state = randomBytes(16).toString('hex');
+        // PKCE: the verifier never leaves this process; only its S256 challenge
+        // rides the auth URL. An old deployed frontend ignores the challenge
+        // params and falls back to the legacy fragment flow, which the /callback
+        // handler below still supports.
+        const codeVerifier = generatePkceVerifier();
+        const codeChallenge = computePkceChallenge(codeVerifier);
+        // Every token save site (HTTP callback and manual paste) must honor the
+        // caller's profile context, or `--profile X` logins land in the legacy
+        // ~/.moda/auth.json instead of ~/.moda/secrets/auth/X.json.
+        const storageOptions = {
+            home: options.home,
+            profile: options.profile,
+            now: options.now,
+            env: options.env,
+        };
+        // Fail fast on an unknown profile BEFORE binding the callback server or
+        // opening the browser: deferring to the save at the end of the flow would
+        // complete the whole browser roundtrip only to throw from inside the
+        // request handler (unhandled) and leave the user's tab hanging.
+        const targetProfile = options.profile ?? (options.env ?? process.env).MODA_PROFILE;
+        if (targetProfile && !loadProfileConfig(storageOptions).profiles[targetProfile]) {
+            reject(new CliInputError(`Moda profile '${targetProfile}' does not exist.`, 'Create it with "moda profiles create <name>" or check "moda profiles list".'));
+            return;
+        }
         const server = createServer(async (req, res) => {
-            if (settled)
+            if (settled) {
+                // Answer stragglers instead of leaving the socket dangling: an
+                // unanswered in-flight request would hold the event loop open.
+                res.writeHead(410, { Connection: 'close' });
+                res.end('Login attempt already completed');
                 return;
+            }
             const url = new URL(req.url || '/', `http://localhost:${localPort}`);
-            // Serve fragment extractor at /callback — the frontend redirects here
-            // with token in the URL fragment (#token=...) which never reaches the server.
-            // This page extracts it client-side and forwards to /callback-token as query params.
             if (url.pathname === '/callback') {
+                const code = url.searchParams.get('code');
+                if (code) {
+                    // PKCE path: the frontend redirected with ?code=&state= query
+                    // params (no fragment hop). Validate state, then exchange the
+                    // one-time code + verifier for a moda_ct session token.
+                    const callbackState = url.searchParams.get('state');
+                    if (!callbackState || !safeEqual(callbackState, state)) {
+                        res.writeHead(400, { 'Content-Type': 'text/html', Connection: 'close' });
+                        res.end('<html><body><h2>Error</h2><p>Invalid authentication state.</p></body></html>', () => {
+                            fail(new Error('Invalid authentication state.'));
+                        });
+                        return;
+                    }
+                    if (exchangeInFlight) {
+                        res.writeHead(409, { Connection: 'close' });
+                        res.end('Login code exchange already in progress');
+                        return;
+                    }
+                    exchangeInFlight = true;
+                    void (async () => {
+                        try {
+                            const cliToken = await exchangeCodeForSession(code);
+                            // Leave exchangeInFlight true on success: succeed() only runs
+                            // in the res.end flush callback, so resetting here (or in a
+                            // finally) would open a window where a second valid-state
+                            // callback could start a concurrent exchange before `settled`
+                            // flips. The flag only needs to clear on failure, where a
+                            // retry paste is still legitimate.
+                            res.writeHead(200, { 'Content-Type': 'text/html', Connection: 'close' });
+                            res.end(SUCCESS_HTML, () => {
+                                succeed(cliToken);
+                            });
+                        }
+                        catch (err) {
+                            exchangeInFlight = false;
+                            const error = err instanceof Error ? err : new Error(String(err));
+                            res.writeHead(400, { 'Content-Type': 'text/html', Connection: 'close' });
+                            res.end(`<html><body><h2>Error</h2><p>${escapeHtml(error.message)}</p></body></html>`, () => {
+                                fail(error);
+                            });
+                        }
+                    })();
+                    return;
+                }
+                // Legacy fallback: an old deployed frontend (no PKCE support) ignores
+                // the code_challenge params and redirects here with the token in the
+                // URL fragment (#token=...), which never reaches the server. Serve
+                // the extractor page that forwards it to /callback-token as query
+                // params.
                 res.writeHead(200, { 'Content-Type': 'text/html', Connection: 'close' });
                 res.end(FRAGMENT_EXTRACTOR_HTML);
                 return;
@@ -261,10 +252,19 @@ export async function login(screen = 'login', options = {}) {
                 });
                 return;
             }
-            saveToken(token, parseInt(expiresIn || '86400', 10), {
-                profile: options.profile,
-                env: options.env,
-            });
+            // Backstop for the fail-fast profile check above: a save failure must
+            // reject the login promise (not crash the process) and still answer the
+            // browser so the tab does not hang.
+            try {
+                saveAuthSession(token, parseInt(expiresIn || String(DEFAULT_EXPIRES_IN_SECONDS), 10), storageOptions);
+            }
+            catch (err) {
+                res.writeHead(500, { 'Content-Type': 'text/html', Connection: 'close' });
+                res.end('<html><body><h2>Error</h2><p>Authenticated, but the CLI could not store the token. Return to your terminal.</p></body></html>', () => {
+                    fail(err instanceof Error ? err : new Error(String(err)));
+                });
+                return;
+            }
             res.writeHead(200, { 'Content-Type': 'text/html', Connection: 'close' });
             res.end(SUCCESS_HTML, () => {
                 succeed(token);
@@ -277,9 +277,13 @@ export async function login(screen = 'login', options = {}) {
         function closePromptInput() {
             if (!promptInput)
                 return;
-            promptInput.removeListener('line', handlePastedLine);
             promptInput.close();
             promptInput = undefined;
+            if (promptStream === process.stdin) {
+                // Let the process exit naturally once auth settles.
+                process.stdin.pause();
+            }
+            promptStream = undefined;
         }
         function finish(callback) {
             if (settled)
@@ -301,32 +305,142 @@ export async function login(screen = 'login', options = {}) {
         function fail(error) {
             finish(() => reject(error));
         }
-        function completeWithToken(token, expiresIn) {
-            saveToken(token, expiresIn, { profile: options.profile, env: options.env });
-            succeed(token);
-        }
         function handleSigint() {
             fail(new Error('Authentication cancelled.'));
         }
         function handleSigterm() {
             fail(new Error('Authentication terminated.'));
         }
+        function completeWithToken(token, expiresIn) {
+            // Backstop: this runs inside a readline 'line' handler, where an
+            // uncaught save error would crash the process instead of rejecting.
+            try {
+                saveAuthSession(token, expiresIn, storageOptions);
+            }
+            catch (err) {
+                fail(err instanceof Error ? err : new Error(String(err)));
+                return;
+            }
+            succeed(token);
+        }
+        /**
+         * PKCE exchange: POST the one-time code + verifier and store the
+         * resulting moda_ct session. Throws with a user-facing message on any
+         * failure; the raw code and token are never logged.
+         */
+        async function exchangeCodeForSession(code) {
+            let response;
+            try {
+                // redirect: 'manual' — never follow a redirect on this POST: a
+                // 307/308 would re-send the one-time code and verifier to whatever
+                // host the Location header names. Any redirect is treated as a hard
+                // failure below (clearer than redirect:'error', whose rejection is
+                // indistinguishable from a network failure in the catch).
+                response = await fetch(`${resolveModaBaseUrl(storageOptions)}/api/cli/auth/exchange`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        code,
+                        code_verifier: codeVerifier,
+                        label: hostname(),
+                    }),
+                    redirect: 'manual',
+                    signal: AbortSignal.timeout(EXCHANGE_TIMEOUT_MS),
+                });
+            }
+            catch {
+                throw new Error('Could not reach the Moda API to exchange the login code. Check your network and try again.');
+            }
+            if (response.status >= 300 && response.status < 400) {
+                throw new Error(`The Moda API redirected the login code exchange (HTTP ${response.status}). ` +
+                    'Refusing to re-send the login code across a redirect. ' +
+                    'Check MODA_BASE_URL (use https://moda.dev, not www.moda.dev) and try again.');
+            }
+            if (response.status === 401) {
+                throw new Error('The login code was rejected (invalid, expired, or already used). Run the login command again.');
+            }
+            if (!response.ok) {
+                throw new Error(`Login code exchange failed (HTTP ${response.status}). Try again.`);
+            }
+            let payload;
+            try {
+                payload = (await response.json());
+            }
+            catch {
+                throw new Error('The login code exchange returned an unreadable response. Try again.');
+            }
+            const cliToken = typeof payload.cli_token === 'string' ? payload.cli_token : undefined;
+            const expiresAtMs = typeof payload.expires_at === 'string' ? Date.parse(payload.expires_at) : NaN;
+            if (!cliToken || !Number.isFinite(expiresAtMs)) {
+                throw new Error('The login code exchange returned an incomplete response. Try again.');
+            }
+            const userEmail = typeof payload.user?.email === 'string' ? payload.user.email : undefined;
+            persistAuthSession({
+                access_token: cliToken,
+                expires_at: Math.floor(expiresAtMs / 1000),
+                profile: resolveStorageProfile(storageOptions),
+                token_type: 'bearer',
+                token_kind: 'moda_ct',
+                ...(userEmail ? { user_email: userEmail } : {}),
+            }, storageOptions);
+            cachedLoginContext = {
+                profile: resolveStorageProfile(storageOptions),
+                context: {
+                    user: {
+                        email: userEmail ?? '',
+                        name: typeof payload.user?.name === 'string' ? payload.user.name : null,
+                    },
+                    tenants: Array.isArray(payload.tenants)
+                        ? payload.tenants
+                        : [],
+                },
+            };
+            return cliToken;
+        }
+        /**
+         * Paste-path variant of the exchange: converts throws into fail().
+         * Shares the exchangeInFlight guard with the HTTP callback path so a
+         * double paste (or a paste racing the browser callback) never runs two
+         * concurrent exchanges; the duplicate line is simply dropped and the
+         * first exchange settles the login.
+         */
+        async function completeWithCode(code) {
+            if (exchangeInFlight)
+                return;
+            exchangeInFlight = true;
+            try {
+                const cliToken = await exchangeCodeForSession(code);
+                succeed(cliToken);
+            }
+            catch (err) {
+                exchangeInFlight = false;
+                fail(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
         // Accepts a line pasted by the user when the browser cannot reach this
-        // machine: a full /callback-token?token=... URL, a /callback#token=...
-        // fragment URL, or a bare token string.
+        // machine: a full PKCE /callback?code=... URL, a /callback-token?token=...
+        // URL, a /callback#token=... fragment URL, a bare one-time code (copied
+        // from the consent page), or a bare token string.
         function handlePastedLine(line) {
             if (settled)
                 return;
             const trimmed = line.trim();
-            if (pendingBareToken !== null) {
-                const token = pendingBareToken;
-                pendingBareToken = null;
+            if (pendingBarePaste !== null) {
+                const pending = pendingBarePaste;
+                pendingBarePaste = null;
                 if (/^y(es)?$/i.test(trimmed)) {
-                    completeWithToken(token, DEFAULT_EXPIRES_IN_SECONDS);
+                    if (pending.kind === 'code') {
+                        void completeWithCode(pending.value);
+                    }
+                    else {
+                        completeWithToken(pending.value, DEFAULT_EXPIRES_IN_SECONDS);
+                    }
                 }
                 else {
                     // A bare Enter is the conventional No for a [y/N] prompt.
-                    fail(new Error('Bare token rejected: state cannot be verified.'));
+                    fail(new Error(pending.kind === 'code'
+                        ? 'Pasted code rejected: state cannot be verified.'
+                        : 'Bare token rejected: state cannot be verified.'));
                 }
                 return;
             }
@@ -343,33 +457,46 @@ export async function login(screen = 'login', options = {}) {
                     fail(new Error('Could not parse the pasted URL. Paste the full callback URL from the browser.'));
                     return;
                 }
-                // Fragment URLs (/callback#token=...) carry the same key/value pairs as
-                // the /callback-token query string; parse whichever is present.
+                // Fragment URLs (/callback#token=...) carry the same key/value pairs
+                // as the /callback-token query string; parse whichever is present.
                 const params = pastedUrl.hash.length > 1
                     ? new URLSearchParams(pastedUrl.hash.slice(1))
                     : pastedUrl.searchParams;
                 const token = params.get('token');
+                const code = params.get('code');
                 const expiresIn = params.get('expires_in');
                 const pastedState = params.get('state');
                 if (!pastedState || !safeEqual(pastedState, state)) {
                     fail(new Error('Invalid authentication state.'));
                     return;
                 }
-                if (!token) {
-                    fail(new Error('No token received'));
+                if (token) {
+                    completeWithToken(token, parseInt(expiresIn || String(DEFAULT_EXPIRES_IN_SECONDS), 10));
+                    return;
+                }
+                if (code) {
+                    // New-style PKCE callback URL pasted manually: state verified
+                    // above, so exchange the one-time code like the HTTP path does.
+                    void completeWithCode(code);
                     return;
                 }
-                completeWithToken(token, parseInt(expiresIn || String(DEFAULT_EXPIRES_IN_SECONDS), 10));
+                fail(new Error('No token received'));
                 return;
             }
-            // Bare token: there is no state to verify, so require an explicit,
-            // interactive confirmation before trusting it.
+            // Bare paste. A one-time code (the consent page renders a copy block)
+            // has no state to verify either, so it gets the same explicit
+            // interactive confirmation gate as a bare token.
+            const kind = looksLikeOneTimeCode(trimmed) ? 'code' : 'token';
             if (promptStreamIsTTY) {
-                pendingBareToken = trimmed;
-                console.error('  State cannot be verified for a bare token. Continue? [y/N]');
+                pendingBarePaste = { kind, value: trimmed };
+                console.error(kind === 'code'
+                    ? '  State cannot be verified for a pasted code. Continue? [y/N]'
+                    : '  State cannot be verified for a bare token. Continue? [y/N]');
                 return;
             }
-            fail(new Error('State cannot be verified for a bare token in non-interactive mode. Paste the full callback URL instead.'));
+            fail(new Error(kind === 'code'
+                ? 'State cannot be verified for a pasted code in non-interactive mode. Paste the full callback URL instead.'
+                : 'State cannot be verified for a bare token in non-interactive mode. Paste the full callback URL instead.'));
         }
         function attachPromptInput() {
             if (settled || promptInput)
@@ -380,6 +507,7 @@ export async function login(screen = 'login', options = {}) {
                     : undefined);
             if (!stream)
                 return;
+            promptStream = stream;
             promptStreamIsTTY = Boolean(stream.isTTY);
             promptInput = createInterface({ input: stream, terminal: false });
             promptInput.on('line', handlePastedLine);
@@ -412,7 +540,7 @@ export async function login(screen = 'login', options = {}) {
                 fail(err);
             }
         });
-        server.listen(localPort, '127.0.0.1', async () => {
+        async function onListening() {
             if (settled)
                 return;
             const address = server.address();
@@ -422,7 +550,11 @@ export async function login(screen = 'login', options = {}) {
             // Resolve the auth URL with the same profile/env context so `--profile
             // staging` opens the staging flow (not whatever the active profile is)
             // and the minted session matches where it will be stored.
-            const authUrl = `${resolveModaBaseUrl({ profile: options.profile, env: options.env })}/auth/cli?port=${localPort}&screen=${screen}&state=${state}`;
+            // code_challenge/challenge_method upgrade the frontend to the PKCE
+            // consent flow; an old deployed frontend ignores them and runs the
+            // legacy fragment flow, which the /callback handler still accepts.
+            const authUrl = `${resolveModaBaseUrl(storageOptions)}/auth/cli?port=${localPort}&screen=${screen}&state=${state}` +
+                `&code_challenge=${codeChallenge}&challenge_method=S256`;
             attachPromptInput();
             try {
                 await (options.openUrl ?? openAuthUrl)(authUrl);
@@ -432,21 +564,37 @@ export async function login(screen = 'login', options = {}) {
             }
             console.error(`  Open this URL in your browser if it did not open automatically:\n  ${authUrl}`);
             console.error("  Paste the callback URL or code here if the browser can't reach this machine\n" +
-                "(if the browser page failed to redirect, copy the URL from the browser's address bar):");
-        });
+                "  (if the browser page failed to redirect, copy the URL from the browser's address bar):");
+        }
+        // Register the listening handler exactly once: passing a callback to each
+        // server.listen() call would accumulate once('listening') handlers across
+        // ladder retries, and every accumulated callback would fire on the
+        // eventual successful bind (opening the browser multiple times).
+        server.once('listening', onListening);
+        server.listen(localPort, '127.0.0.1');
         process.once('SIGINT', handleSigint);
         process.once('SIGTERM', handleSigterm);
     });
 }
 // --- Authenticated Fetch ---
 export async function authFetch(path, options = {}, authOptions = {}) {
-    const token = loadToken(authOptions);
-    if (!token) {
-        throw new CliAuthError('Not authenticated. Run "moda auth login" to log in.', {
+    const session = loadAuthSession(authOptions);
+    if (!session) {
+        // An expired moda_ct session is a classifiable auth failure; legacy
+        // sessions keep the historical plain error.
+        const expired = loadAuthSession({ ...authOptions, includeExpired: true });
+        if (expired && isModaCtSession(expired)) {
+            throw cliSessionExpiredError();
+        }
+        throw new CliAuthError('Not authenticated. Run "moda init" to log in.', {
             reason: 'no_stored_credentials',
-            login_command: ['moda', 'auth', 'login'],
+            login_command: ['moda', 'init'],
         });
     }
+    const token = session.access_token;
+    // Sliding expiry: renew opportunistically when a moda_ct session is inside
+    // the renewal window. Fire-and-forget; the request below never waits on it.
+    scheduleRenewalIfNearExpiry(session, authOptions);
     const headers = new Headers(options.headers);
     headers.set('Authorization', `Bearer ${token}`);
     if (!headers.has('Content-Type') && options.body) {
@@ -468,6 +616,14 @@ export async function authFetch(path, options = {}, authOptions = {}) {
     for (let hop = 0;; hop++) {
         const response = await fetch(url, { ...options, headers, redirect: 'manual' });
         if (response.status < 300 || response.status >= 400) {
+            if (response.status === 401 && isModaCtSession(session)) {
+                // 401 taxonomy for moda_ct tokens: expired vs revoked vs a transient
+                // renewal failure (each with distinct recovery guidance). Legacy
+                // auth0-kind sessions keep the historical pass-through behavior.
+                const authError = await classifyModaCtUnauthorized(session, authOptions);
+                if (authError)
+                    throw authError;
+            }
             return response;
         }
         const location = response.headers.get('location');