@empirical-gauzza/cli 1.0.9

package/lib/auth.js

@@ -0,0 +1,804 @@
+'use strict';
+
+const fs = require('fs');
+const http = require('http');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { log, warn, uiQuestion, uiDim, uiLink, ask } = require('./ui');
+const { readJsonIfExists, writeFile, ensureDir, quotePowerShellArg, runResolvedCommand } = require('./fsUtils');
+const { httpGet, httpJson, httpForm } = require('./http');
+const { getEnv, parseFlag, parseOption } = require('./env');
+const {
+  getLocalOAuthClientPath,
+  readStoredOAuthClient,
+  writeStoredOAuthClient,
+  clearStoredOAuthClient,
+  maskSecret,
+  generateRandomString,
+  generatePKCE,
+  isJwtToken,
+  isJwtExpired,
+  readHeadlessToken,
+  readOAuthSession,
+  writeOAuthSession,
+  clearOAuthSession,
+  hasFreshAccessToken,
+  writeHeadlessEnvFile
+} = require('./oauthClient');
+const { deriveBaseUrlFromMcpUrl } = require('./constants');
+
+async function oauthPreflight(baseMcpUrl) {
+  try {
+    const base = new URL(baseMcpUrl);
+    const loginUrl = new URL('/oauth/authorize/login', `${base.protocol}//${base.host}`);
+    loginUrl.searchParams.set('client_id', 'installer-preflight');
+    loginUrl.searchParams.set('redirect_uri', 'http://127.0.0.1:63626/');
+    loginUrl.searchParams.set('state', 'installer-check');
+
+    const response = await httpGet(loginUrl.toString());
+    if (response.statusCode < 200 || response.statusCode >= 400) {
+      return {
+        ok: false,
+        message: `OAuth login endpoint returned HTTP ${response.statusCode}`
+      };
+    }
+
+    const csp = String(response.headers['content-security-policy'] || '');
+    const cspAllowsLoopback =
+      csp.includes('http://127.0.0.1:*') ||
+      csp.includes('http://localhost:*') ||
+      csp.includes('http://[::1]:*');
+
+    const locationHeader = String(response.headers.location || '');
+    const hasReactLoginRedirect =
+      response.statusCode >= 300 &&
+      response.statusCode < 400 &&
+      locationHeader.includes('/oauth-login');
+
+    const hasExpectedLoginAssets =
+      response.body.includes('Authorize Empirical MCP') &&
+      response.body.includes('oauth-user-id') &&
+      response.body.includes('oauth-api-key');
+
+    if (!hasReactLoginRedirect && !hasExpectedLoginAssets) {
+      return {
+        ok: false,
+        message: 'OAuth login page appears stale (missing current login assets).'
+      };
+    }
+
+    if (csp && !cspAllowsLoopback) {
+      return {
+        ok: false,
+        message: 'OAuth login CSP does not include loopback callbacks (127.0.0.1/localhost).'
+      };
+    }
+
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, message: `OAuth preflight failed: ${error.message}` };
+  }
+}
+
+function openBrowser(url) {
+  if (process.platform === 'win32') {
+    const script = `Start-Process ${quotePowerShellArg(url)}`;
+    spawnSync('pwsh', ['-NoProfile', '-Command', script], { stdio: 'ignore' });
+  } else if (process.platform === 'darwin') {
+    spawnSync('open', [url], { stdio: 'ignore' });
+  } else {
+    spawnSync('xdg-open', [url], { stdio: 'ignore' });
+  }
+}
+
+async function runMcpOAuthFlow(baseUrl) {
+  return new Promise((resolve, reject) => {
+    const { codeVerifier, codeChallenge } = generatePKCE();
+    const state = generateRandomString(32);
+    let server = null;
+    let resolved = false;
+
+    const handleTimeout = setTimeout(() => {
+      if (server) server.close();
+      if (!resolved) {
+        resolved = true;
+        reject(new Error('OAuth callback timeout (5 minutes)'));
+      }
+    }, 5 * 60 * 1000);
+
+    server = http.createServer((req, res) => {
+      const url = new URL(`http://localhost${req.url}`);
+      const code = url.searchParams.get('code');
+      const returnedState = url.searchParams.get('state');
+
+      if (code && returnedState === state) {
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(
+          '<html><body style="font-family:sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;">' +
+          '<div style="text-align:center;"><h1>Authorization successful!</h1><p>You can close this window.</p></div></body></html>'
+        );
+
+        clearTimeout(handleTimeout);
+        if (server) server.close();
+
+        if (!resolved) {
+          resolved = true;
+          resolveOAuthCode(code, codeVerifier, baseUrl)
+            .then((token) => {
+              writeOAuthSession(token);
+              resolve(token);
+            })
+            .catch(reject);
+        }
+      } else {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end(
+          '<html><body style="font-family:sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;">' +
+          '<div style="text-align:center;"><h1>Authorization failed!</h1><p>Invalid or missing code. You can close this window.</p></div></body></html>'
+        );
+
+        clearTimeout(handleTimeout);
+        if (server) server.close();
+
+        if (!resolved) {
+          resolved = true;
+          reject(new Error('Invalid OAuth callback'));
+        }
+      }
+    });
+
+    server.listen(0, '127.0.0.1', async () => {
+      const port = server.address().port;
+      const redirectUri = `http://127.0.0.1:${port}/callback`;
+
+      const authUrl = new URL('/oauth/authorize/login', baseUrl);
+      authUrl.searchParams.set('client_id', 'empirical-cli-mcp');
+      authUrl.searchParams.set('response_type', 'code');
+      authUrl.searchParams.set('redirect_uri', redirectUri);
+      authUrl.searchParams.set('state', state);
+      authUrl.searchParams.set('code_challenge', codeChallenge);
+      authUrl.searchParams.set('code_challenge_method', 'S256');
+      authUrl.searchParams.set('scope', 'memory:read memory:write memory:delete offline_access');
+
+      log(uiQuestion('Opening browser for Empirical MCP authentication...'));
+      openBrowser(authUrl.toString());
+      log(uiDim(`If browser doesn't open, visit: ${uiLink(authUrl.toString())}`));
+    });
+
+    server.on('error', (error) => {
+      clearTimeout(handleTimeout);
+      if (!resolved) {
+        resolved = true;
+        reject(error);
+      }
+    });
+  });
+}
+
+async function resolveOAuthCode(code, codeVerifier, baseUrl) {
+  const tokenUrl = new URL('/oauth/token', baseUrl).toString();
+  const tokenRequest = {
+    grant_type: 'authorization_code',
+    client_id: 'empirical-cli-mcp',
+    code,
+    code_verifier: codeVerifier,
+    redirect_uri: 'http://127.0.0.1:0/callback'
+  };
+
+  const token = await httpForm(tokenUrl, 'POST', tokenRequest);
+  if (!token.access_token) {
+    throw new Error('Token exchange succeeded but no access_token was returned.');
+  }
+
+  return {
+    baseUrl,
+    accessToken: token.access_token,
+    refreshToken: token.refresh_token || null,
+    expiresIn: token.expires_in || null,
+    tokenType: token.token_type || 'Bearer',
+    obtainedAt: new Date().toISOString()
+  };
+}
+
+function updateClaudeMcpServerAuth(serverName, accessToken) {
+  const home = os.homedir();
+  const claudeConfigPath = path.join(home, '.claude.json');
+
+  if (!fs.existsSync(claudeConfigPath)) {
+    throw new Error(`Claude config not found at ${claudeConfigPath}`);
+  }
+
+  const config = readJsonIfExists(claudeConfigPath);
+  if (!config || !config.mcpServers || !config.mcpServers[serverName]) {
+    throw new Error(`MCP server '${serverName}' not found in Claude config`);
+  }
+
+  config.mcpServers[serverName].httpHeaders = {
+    Authorization: `Bearer ${accessToken}`
+  };
+
+  writeFile(claudeConfigPath, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+// ─── Shared helpers for memory commands ──────────────────────────────────────
+
+function resolveAccessToken() {
+  // Priority 1: env var — but only trust it if it isn't a stale, expired JWT.
+  // A permanent apiKey isn't a JWT and has no expiry, so it always passes
+  // through here unchanged. A session JWT can end up permanently written to
+  // this env var (e.g. via `setx` on Windows from a prior bootstrap) and
+  // otherwise silently shadow a perfectly good apiKey in the token file below
+  // once it expires, forcing a manual unset every ~hour.
+  const fromEnv = (process.env.EMPIRICAL_ACCESS_TOKEN || '').trim();
+  if (fromEnv && !(isJwtToken(fromEnv) && isJwtExpired(fromEnv))) return fromEnv;
+
+  // Priority 2/3: token file
+  const tokenFileCandidates = [
+    (process.env.EMPIRICAL_TOKEN_OUTPUT || '').trim(),
+    path.resolve(process.cwd(), '.empirical', 'headless-token.json'),
+    path.join(os.homedir(), '.empirical', 'headless-token.json')
+  ].filter(Boolean);
+
+  for (const candidate of tokenFileCandidates) {
+    if (!fs.existsSync(candidate)) continue;
+    try {
+      const parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+      if (parsed && typeof parsed === 'object') {
+        const apiKey = (parsed.apiKey || '').trim();
+        if (apiKey) return apiKey;
+        const accessToken = (parsed.accessToken || '').trim();
+        if (accessToken) return accessToken;
+      }
+    } catch (_error) {
+      // ignore parse errors and try next
+    }
+  }
+
+  const session = readOAuthSession();
+  if (session?.accessToken && !(isJwtToken(session.accessToken) && isJwtExpired(session.accessToken))) {
+    return session.accessToken;
+  }
+
+  // Priority 4: EMPIRICAL_API_KEY / EMPIRICAL_CLIENT_SECRET env vars, used
+  // directly as a permanent Bearer credential. In a client_credentials setup
+  // the client secret IS the API key (see runHeadlessBootstrap's `apiKey:
+  // clientSecret`), and the server already accepts it as a raw Bearer token
+  // with no token exchange required. This lets a stateless/ephemeral agent
+  // environment (no persisted headless-token.json between runs) authenticate
+  // from client_id/secret alone, with nothing to expire and nothing to
+  // bootstrap first. Only kicks in when nothing above matched, so it never
+  // overrides a real token file or a still-valid env access token.
+  const apiKeyFromEnv = (process.env.EMPIRICAL_API_KEY || process.env.EMPIRICAL_CLIENT_SECRET || '').trim();
+  if (apiKeyFromEnv) return apiKeyFromEnv;
+
+  return null;
+}
+
+function resolveCachedSessionAccessToken() {
+  const tokenFileCandidates = [
+    (process.env.EMPIRICAL_TOKEN_OUTPUT || '').trim(),
+    path.resolve(process.cwd(), '.empirical', 'headless-token.json'),
+    path.join(os.homedir(), '.empirical', 'headless-token.json')
+  ].filter(Boolean);
+
+  for (const candidate of tokenFileCandidates) {
+    if (!fs.existsSync(candidate)) continue;
+    try {
+      const parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+      const accessToken = (parsed?.accessToken || '').trim();
+      if (accessToken && isJwtToken(accessToken) && !isJwtExpired(accessToken)) {
+        return accessToken;
+      }
+    } catch (_error) {
+      // ignore parse errors and try next candidate
+    }
+  }
+  return null;
+}
+
+function resolveApiBaseUrl() {
+  const fromEnv = (process.env.EMPIRICAL_BASE_URL || '').trim();
+  if (fromEnv) return fromEnv;
+  const derived = deriveBaseUrlFromMcpUrl();
+  if (derived) return derived;
+  return 'https://empirical.gauzza.com';
+}
+
+function requireAccessToken() {
+  const token = resolveAccessToken();
+  if (!token) {
+    warn('No access token found. Run: empirical auth login, or configure headless credentials with empirical oauth bootstrap headless.');
+    process.exit(1);
+  }
+  return token;
+}
+
+function isAuthCommand(args) {
+  return args[0] === 'auth' && ['login', 'logout'].includes(args[1]);
+}
+
+async function runAuthCommand(args) {
+  const action = args[1];
+  if (action === 'login') {
+    const baseUrl = getEnv('EMPIRICAL_BASE_URL', 'https://empirical.gauzza.com');
+    await runMcpOAuthFlow(baseUrl);
+    log('Empirical OAuth login complete. CLI session saved.');
+    return;
+  }
+  clearOAuthSession();
+  log('Empirical OAuth session cleared.');
+}
+
+function buildApiAuthHeaders(token) {
+  const context = globalThis.__empiricalCliAnalyticsContext || {};
+  const workspaceId = globalThis.__empiricalCliWorkspaceId || null;
+  return {
+    Authorization: `Bearer ${token}`,
+    'x-empirical-surface': 'cli',
+    ...(context.command ? { 'x-empirical-cli-command': context.command } : {}),
+    ...(context.subcommand ? { 'x-empirical-cli-subcommand': context.subcommand } : {}),
+    ...(workspaceId ? { 'x-workspace-id': workspaceId } : {})
+  };
+}
+
+async function ensureHeadlessToken(options = {}) {
+  const promptCredentials = options.promptCredentials === true;
+  const existing = readHeadlessToken();
+  if (existing?.apiKey) {
+    return existing;
+  }
+  if (hasFreshAccessToken(existing)) {
+    return existing;
+  }
+
+  if (existing?.refreshToken && existing?.clientId) {
+    try {
+      await runHeadlessRefresh(['oauth', 'refresh', 'headless', '--write-env']);
+      const refreshed = readHeadlessToken();
+      if (refreshed?.apiKey || hasFreshAccessToken(refreshed)) {
+        return refreshed;
+      }
+    } catch (_error) {
+      // Fall through to bootstrap if refresh is unavailable or rejected.
+    }
+  }
+
+  const bootstrapArgs = ['oauth', 'bootstrap', 'headless', '--write-env'];
+  if (promptCredentials) {
+    bootstrapArgs.push('--prompt-credentials');
+  }
+  await runHeadlessBootstrap(bootstrapArgs);
+  return readHeadlessToken();
+}
+
+function isHeadlessBootstrapCommand(args) {
+  if (args.length >= 3) {
+    return args[0] === 'oauth' && args[1] === 'bootstrap' && ['headless', 'docker', 'openclaw'].includes(args[2]);
+  }
+  return args.includes('--oauth-bootstrap-headless') || args.includes('--oauth-bootstrap-openclaw');
+}
+
+function isHeadlessRefreshCommand(args) {
+  if (args.length >= 3) {
+    return args[0] === 'oauth' && args[1] === 'refresh' && ['headless', 'docker', 'openclaw'].includes(args[2]);
+  }
+  return args.includes('--oauth-refresh-headless') || args.includes('--oauth-refresh-openclaw');
+}
+
+function isOAuthClientCommand(args) {
+  return args[0] === 'oauth' && args[1] === 'client' && ['set', 'show', 'clear'].includes(args[2]);
+}
+
+async function runOAuthClientCommand(args) {
+  const action = args[2];
+  const storePath = getLocalOAuthClientPath();
+
+  if (action === 'show') {
+    const stored = readStoredOAuthClient();
+    if (!stored) {
+      log(`No saved OAuth client credentials at ${storePath}.`);
+      return;
+    }
+    log('Saved OAuth client credentials:');
+    log(`  - Path: ${storePath}`);
+    log(`  - Client ID: ${stored.clientId}`);
+    log(`  - Client Secret: ${maskSecret(stored.clientSecret)}`);
+    return;
+  }
+
+  if (action === 'clear') {
+    const existed = fs.existsSync(storePath);
+    clearStoredOAuthClient();
+    log(
+      existed
+        ? `Removed saved OAuth client credentials: ${storePath}`
+        : `No saved OAuth client credentials at ${storePath}.`
+    );
+
+    // `clear` means "forget my client credentials" — that has to include env
+    // vars too (env vars take priority over the file — see the clientId/
+    // clientSecret lookups in runHeadlessBootstrap), not just the JSON file,
+    // or a stale EMPIRICAL_ACCESS_TOKEN persisted via `setx` on Windows by a
+    // prior bootstrap silently keeps overriding a "cleared" state. Scrub
+    // everything we're actually able to reach automatically; only the
+    // current shell's already-exported values are outside a child process's
+    // reach on any OS.
+    const envVarsToScrub = [
+      'EMPIRICAL_CLIENT_ID',
+      'EMPIRICAL_CLIENT_SECRET',
+      'DEFAULT_CLIENT_ID',
+      'DEFAULT_CLIENT_SECRET',
+      'EMPIRICAL_ACCESS_TOKEN'
+    ].filter((name) => getEnv(name));
+
+    if (envVarsToScrub.length > 0) {
+      for (const name of envVarsToScrub) {
+        delete process.env[name];
+      }
+      if (process.platform === 'win32') {
+        for (const name of envVarsToScrub) {
+          runResolvedCommand('setx', [name, ''], { stdio: 'ignore' });
+        }
+        log(`  - Also cleared ${envVarsToScrub.join(', ')} from your persisted Windows user environment.`);
+        log('    Open a new terminal for that to take effect there too — this shell keeps the old value(s) until then.');
+      } else {
+        warn(
+          `  - ${envVarsToScrub.join(', ')} ${envVarsToScrub.length > 1 ? 'are' : 'is'} still exported in this shell and will override the cleared file for the rest of this session.`
+        );
+        warn(`    Unset with: unset ${envVarsToScrub.join(' ')} (and remove from your shell profile if exported there).`);
+      }
+    }
+    return;
+  }
+
+  let clientId = parseOption(args, '--client-id', getEnv('EMPIRICAL_CLIENT_ID'));
+  let clientSecret = parseOption(args, '--client-secret', getEnv('EMPIRICAL_CLIENT_SECRET'));
+
+  if (!clientId && process.stdin.isTTY) {
+    clientId = (await ask('OAuth client ID: ')).trim();
+  }
+  if (!clientId) {
+    throw new Error('OAuth client ID is required. Provide --client-id or EMPIRICAL_CLIENT_ID.');
+  }
+
+  if (!clientSecret && process.stdin.isTTY) {
+    clientSecret = (await ask('OAuth client secret (optional): ')).trim();
+  }
+
+  writeStoredOAuthClient(clientId, clientSecret);
+  log(`Saved OAuth client credentials to ${storePath}`);
+  log('Use "empirical oauth client show" to verify and "empirical -install" to apply to supported CLIs.');
+}
+
+async function ensureOAuthClient({ baseUrl, redirectUri }) {
+  const configuredClientId = getEnv('EMPIRICAL_CLIENT_ID');
+  const configuredClientSecret = getEnv('EMPIRICAL_CLIENT_SECRET');
+  if (configuredClientId) {
+    return {
+      clientId: configuredClientId,
+      clientSecret: configuredClientSecret || ''
+    };
+  }
+
+  const storedClient = readStoredOAuthClient();
+  if (storedClient?.clientId) {
+    return storedClient;
+  }
+
+  const registerUrl = new URL('/oauth/register', baseUrl).toString();
+  const redirectUrisSet = new Set([redirectUri]);
+  ['http://127.0.0.1/', 'http://localhost/', 'http://[::1]/'].forEach((loopback) => {
+    redirectUrisSet.add(loopback);
+  });
+
+  const payload = {
+    client_name: getEnv('EMPIRICAL_CLIENT_NAME', 'Empirical Headless Client'),
+    redirect_uris: Array.from(redirectUrisSet),
+    grant_types: ['authorization_code', 'refresh_token'],
+    response_types: ['code'],
+    scope: getEnv('EMPIRICAL_SCOPE', 'memory:read memory:write memory:delete'),
+    token_endpoint_auth_method: getEnv('EMPIRICAL_TOKEN_ENDPOINT_AUTH_METHOD', 'none')
+  };
+
+  const created = await httpJson(registerUrl, 'POST', payload);
+  return {
+    clientId: created.client_id,
+    clientSecret: created.client_secret || ''
+  };
+}
+
+async function fetchSelfServiceCredentials(baseUrl, accessToken, { rotate = false, label } = {}) {
+  const url = new URL('/api/v1/users/me/credentials', baseUrl).toString();
+  const body = { rotate };
+  if (label) body.label = label;
+  return httpJson(url, 'POST', body, { Authorization: `Bearer ${accessToken}` });
+}
+
+async function fetchSelfServiceCredentialStatus(baseUrl, accessToken) {
+  const url = new URL('/api/v1/users/me/credentials', baseUrl).toString();
+  return httpJson(url, 'GET', undefined, { Authorization: `Bearer ${accessToken}` });
+}
+
+async function selfProvisionHeadlessCredentials({ baseUrl, allowBrowserLogin = true } = {}) {
+  let bearer = resolveAccessToken();
+
+  if (!bearer && allowBrowserLogin && process.stdin.isTTY) {
+    log('  - No local credentials found. Opening browser once to identify your account...');
+    const mcpToken = await runMcpOAuthFlow(baseUrl);
+    bearer = mcpToken.accessToken;
+  }
+
+  if (!bearer) {
+    return null;
+  }
+
+  try {
+    await fetchSelfServiceCredentialStatus(baseUrl, bearer);
+  } catch (error) {
+    // A stale/expired EMPIRICAL_ACCESS_TOKEN (e.g. persisted via `setx` by a
+    // prior bootstrap) shouldn't dead-end self-provisioning at a manual
+    // prompt — re-identify the account with one browser login instead.
+    const looksUnauthorized = error.statusCode === 401 || error.statusCode === 403;
+    if (!looksUnauthorized || !allowBrowserLogin || !process.stdin.isTTY) {
+      throw error;
+    }
+    log('  - Saved access token was rejected. Opening browser once to re-identify your account...');
+    const mcpToken = await runMcpOAuthFlow(baseUrl);
+    bearer = mcpToken.accessToken;
+  }
+
+  // Minting always requires a real session bearer, whether or not the account already has
+  // a key — the server rejects a permanent API key for this endpoint specifically (see
+  // requireSessionAuthForCredentialMutation server-side), so one leaked key can't mint
+  // itself unlimited independently-valid siblings. Minting an ADDITIONAL key never touches
+  // any existing key, so — unlike the old rotate-only model — there's no more "already has
+  // a key" consent branch needed here at all.
+  let sessionBearer = resolveCachedSessionAccessToken();
+  if (!sessionBearer) {
+    if (!allowBrowserLogin || !process.stdin.isTTY) {
+      warn('  - Creating an API key requires a signed-in session, and no valid cached session was found.');
+      warn('    Run this command in an interactive terminal to sign in once, or set EMPIRICAL_CLIENT_ID/EMPIRICAL_CLIENT_SECRET from Settings.');
+      return null;
+    }
+    log('  - Creating an API key requires a signed-in session. Opening browser once...');
+    const mcpToken = await runMcpOAuthFlow(baseUrl);
+    sessionBearer = mcpToken.accessToken;
+  }
+
+  const minted = await fetchSelfServiceCredentials(baseUrl, sessionBearer, {
+    rotate: false,
+    label: 'CLI self-provision'
+  });
+  const result = minted.data || minted;
+  if (!result.apiKey) return null;
+  return { clientId: result.clientId || result.userId, clientSecret: result.apiKey };
+}
+
+async function runHeadlessBootstrap(args) {
+  const printAccessToken = parseFlag(args, '--print-access-token');
+  const writeEnv = parseFlag(args, '--write-env');
+  const promptCredentials = parseFlag(args, '--prompt-credentials');
+  const baseUrl = getEnv('EMPIRICAL_BASE_URL', 'https://empirical.gauzza.com');
+  const storedClient = readStoredOAuthClient();
+  let clientId = parseOption(
+    args,
+    '--client-id',
+    getEnv('DEFAULT_CLIENT_ID') || getEnv('EMPIRICAL_CLIENT_ID') || storedClient?.clientId || ''
+  );
+  let clientSecret = parseOption(
+    args,
+    '--client-secret',
+    getEnv('DEFAULT_CLIENT_SECRET') || getEnv('EMPIRICAL_CLIENT_SECRET') || storedClient?.clientSecret || ''
+  );
+  const outputPath = getEnv('EMPIRICAL_TOKEN_OUTPUT', '.empirical/headless-token.json');
+  const envOutputPath = parseOption(args, '--env-output', getEnv('EMPIRICAL_ENV_OUTPUT', '.empirical/headless.env'));
+
+  if (!promptCredentials && !clientId) {
+    log('No headless credentials found. Self-provisioning from your account...');
+    try {
+      const provisioned = await selfProvisionHeadlessCredentials({ baseUrl });
+      if (provisioned?.clientId) {
+        clientId = provisioned.clientId;
+        clientSecret = provisioned.clientSecret || clientSecret;
+        writeStoredOAuthClient(clientId, clientSecret);
+        log(`  - Saved credentials for ${clientId} to ${getLocalOAuthClientPath()}.`);
+      }
+    } catch (error) {
+      warn(`  - Self-provisioning failed: ${error.message}`);
+    }
+  }
+
+  if (process.stdin.isTTY && (promptCredentials || !clientId)) {
+    const idPrompt = clientId
+      ? `Client ID (from Settings) [${clientId}]: `
+      : 'Client ID (from Settings): ';
+    const idAnswer = (await ask(idPrompt)).trim();
+    clientId = idAnswer || clientId;
+  }
+  if (process.stdin.isTTY && (promptCredentials || !clientSecret)) {
+    const secretPrompt = clientSecret
+      ? 'Client secret (from Settings) [press Enter to keep saved secret]: '
+      : 'Client secret (from Settings): ';
+    const secretAnswer = (await ask(secretPrompt)).trim();
+    clientSecret = secretAnswer || clientSecret;
+  }
+  if (!clientId || !clientSecret) {
+    throw new Error(
+      'Client ID and client secret are required for headless bootstrap, and auto-provisioning did not succeed. ' +
+        'Check EMPIRICAL_BASE_URL/network connectivity, or pass --client-id/--client-secret manually.'
+    );
+  }
+
+  const tokenUrl = new URL('/oauth/token', baseUrl).toString();
+  const explicitClientId = Boolean(parseOption(args, '--client-id', ''));
+  const requestToken = (id, secret) =>
+    httpForm(tokenUrl, 'POST', {
+      grant_type: 'client_credentials',
+      client_id: id,
+      client_secret: secret,
+      scope: getEnv('EMPIRICAL_SCOPE', 'memory:read memory:write memory:delete offline_access')
+    });
+
+  let token;
+  try {
+    token = await requestToken(clientId, clientSecret);
+  } catch (error) {
+    const looksInvalid = /invalid.?client/i.test(error.message);
+    if (!looksInvalid || explicitClientId) {
+      throw error;
+    }
+    log('Stored credentials were rejected by the server. Re-provisioning from your account...');
+    clearStoredOAuthClient();
+    let provisioned = null;
+    try {
+      provisioned = await selfProvisionHeadlessCredentials({ baseUrl, allowBrowserLogin: false });
+    } catch (_reprovisionError) {
+      throw error;
+    }
+    if (!provisioned?.clientId) {
+      throw error;
+    }
+    clientId = provisioned.clientId;
+    clientSecret = provisioned.clientSecret || '';
+    writeStoredOAuthClient(clientId, clientSecret);
+    log(`  - Saved refreshed credentials for ${clientId}.`);
+    token = await requestToken(clientId, clientSecret);
+  }
+
+  if (!token.access_token) {
+    throw new Error('Token exchange succeeded but no access_token was returned.');
+  }
+
+  writeStoredOAuthClient(clientId, clientSecret);
+
+  const result = {
+    baseUrl,
+    obtainedAt: new Date().toISOString(),
+    tokenType: token.token_type || 'Bearer',
+    accessToken: token.access_token,
+    refreshToken: token.refresh_token || null,
+    expiresIn: token.expires_in || null,
+    clientId,
+    clientSecret: clientSecret || null,
+    // clientSecret IS the API key for client_credentials flows.
+    // Storing it as apiKey lets writeHeadlessEnvFile emit a permanent
+    // Bearer credential that never expires.
+    apiKey: clientSecret || null
+  };
+
+  ensureDir(path.dirname(path.resolve(outputPath)));
+  fs.writeFileSync(path.resolve(outputPath), `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+  if (writeEnv) {
+    writeHeadlessEnvFile(result, envOutputPath);
+  }
+
+  if (printAccessToken) {
+    log(result.accessToken);
+    return;
+  }
+
+  log('Headless OAuth bootstrap complete.');
+  log(`  - Token file: ${path.resolve(outputPath)}`);
+  if (writeEnv) {
+    log(`  - Env file: ${path.resolve(envOutputPath)}`);
+  }
+  log(`  - Client ID: ${clientId}`);
+  log(`  - Access token expires in: ${result.expiresIn || 'unknown'} seconds`);
+}
+
+async function runHeadlessRefresh(args) {
+  const printAccessToken = parseFlag(args, '--print-access-token');
+  const writeEnv = parseFlag(args, '--write-env');
+  const configuredOutput = getEnv('EMPIRICAL_TOKEN_OUTPUT', '.empirical/headless-token.json');
+  let outputPath = path.resolve(configuredOutput);
+  const legacyOutputPath = path.resolve('.empirical/openclaw-token.json');
+  if (!fs.existsSync(outputPath) && configuredOutput === '.empirical/headless-token.json' && fs.existsSync(legacyOutputPath)) {
+    outputPath = legacyOutputPath;
+  }
+  const envOutputPath = parseOption(args, '--env-output', getEnv('EMPIRICAL_ENV_OUTPUT', '.empirical/headless.env'));
+  if (!fs.existsSync(outputPath)) {
+    throw new Error(`Token file not found: ${outputPath}. Run bootstrap first.`);
+  }
+
+  const current = JSON.parse(fs.readFileSync(outputPath, 'utf8'));
+  const baseUrl = String(current.baseUrl || getEnv('EMPIRICAL_BASE_URL', 'https://empirical.gauzza.com'));
+  const clientId = String(current.clientId || '');
+  const refreshToken = String(current.refreshToken || '');
+  const clientSecret = String(current.clientSecret || '');
+
+  if (!clientId || !refreshToken) {
+    throw new Error('Token file is missing clientId or refreshToken. Re-run bootstrap.');
+  }
+
+  const tokenUrl = new URL('/oauth/token', baseUrl).toString();
+  const tokenRequest = {
+    grant_type: 'refresh_token',
+    refresh_token: refreshToken,
+    client_id: clientId
+  };
+  if (clientSecret) {
+    tokenRequest.client_secret = clientSecret;
+  }
+
+  const token = await httpForm(tokenUrl, 'POST', tokenRequest);
+  if (!token.access_token) {
+    throw new Error('Refresh succeeded but no access_token was returned.');
+  }
+
+  const next = {
+    ...current,
+    baseUrl,
+    obtainedAt: new Date().toISOString(),
+    tokenType: token.token_type || current.tokenType || 'Bearer',
+    accessToken: token.access_token,
+    refreshToken: token.refresh_token || refreshToken,
+    expiresIn: token.expires_in || current.expiresIn || null,
+    clientId,
+    clientSecret: clientSecret || current.clientSecret || current.authClientSecret || null,
+    apiKey: current.apiKey || current.clientSecret || current.authClientSecret || clientSecret || null
+  };
+
+  fs.writeFileSync(outputPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  if (writeEnv) {
+    writeHeadlessEnvFile(next, envOutputPath);
+  }
+
+  if (printAccessToken) {
+    log(next.accessToken);
+    return;
+  }
+
+  log('Headless OAuth token refreshed.');
+  log(`  - Token file: ${outputPath}`);
+  if (writeEnv) {
+    log(`  - Env file: ${path.resolve(envOutputPath)}`);
+  }
+  log(`  - Access token expires in: ${next.expiresIn || 'unknown'} seconds`);
+}
+
+module.exports = {
+  oauthPreflight,
+  openBrowser,
+  runMcpOAuthFlow,
+  isAuthCommand,
+  runAuthCommand,
+  resolveOAuthCode,
+  updateClaudeMcpServerAuth,
+  resolveAccessToken,
+  resolveCachedSessionAccessToken,
+  resolveApiBaseUrl,
+  requireAccessToken,
+  buildApiAuthHeaders,
+  ensureHeadlessToken,
+  isHeadlessBootstrapCommand,
+  isHeadlessRefreshCommand,
+  isOAuthClientCommand,
+  runOAuthClientCommand,
+  ensureOAuthClient,
+  fetchSelfServiceCredentials,
+  fetchSelfServiceCredentialStatus,
+  selfProvisionHeadlessCredentials,
+  runHeadlessBootstrap,
+  runHeadlessRefresh
+};