@bman654/clodex 1.2.2 → 2.0.0

package/docs/credential-helpers.md

@@ -24,7 +24,13 @@ previous store; remove that credential with the previous backend's tooling.
 
 Clodex verifies the selected store with a disposable write, read, and delete
 before starting device authorization. It also reads back real credential
-writes.
+writes. OAuth refresh returns the new access token only after the rotated
+credential has been stored and verified. An environment override rejected by
+the upstream service remains bypassed until its value changes or the process
+restarts, preventing the same stale value from causing a 401 on every request.
+For stored OAuth credentials, a rejected-access marker is cleared when refresh
+returns a different access token. If the identity provider keeps returning the
+same rejected token, run `clodex providers auth <provider>` to reauthenticate.
 
 Credential storage is fail-closed. If the selected credential store fails its
 probe, Clodex stops before device authorization and includes the backend
@@ -32,6 +38,27 @@ diagnostic in the error instead of continuing with tokens that cannot be
 durably stored. Set `CLODEX_CREDENTIAL_HELPER` to the absolute path of an
 external helper, then run the authorization command again.
 
+Provider creation, replacement, and removal use the durable cleanup journal at
+`~/.clodex/credential-cleanup.json` (under `CLODEX_HOME` when set). Keeping the
+journal separate from `providers.json` prevents registry writers that only know
+schema 1 provider fields from dropping pending cleanup. A new unreferenced
+credential is journaled before it is written, provider changes are saved before
+superseded credentials are deleted, and uncertain deletion outcomes remain
+queued. Per-credential cross-process locks serialize writes, activation,
+removal, and reconciliation for the same reference. Reconciliation is
+best-effort and sequential: a contended credential can delay later entries
+until its lock attempt times out, but the timeout does not turn an already-saved
+provider into a failed creation. The next `clodex providers` command retries
+queued deletions idempotently and never deletes a credential that is referenced
+by an active provider. If the registry cannot be read and validated, cleanup
+stays queued instead of treating the registry as empty.
+
+The cleanup journal accepts only credential accounts generated for Clodex
+provider and OAuth records, including replacement, custom-provider, and scoped
+credential instances. It rejects symbolic links, foreign ownership, broad
+permissions on POSIX, files over 1 MiB, and more than 1,024 queued entries
+before attempting any credential-store deletion.
+
 ## Protocol
 
 The helper receives one of these invocations:
@@ -56,9 +83,16 @@ contents are never passed in arguments or environment variables. Helper
 standard error is not copied into Clodex diagnostics, and output and runtime
 are bounded.
 
+The helper protocol transports credential bytes without interpreting them.
+For non-OAuth provider references, Clodex preserves valid opaque JSON secrets.
+OAuth references accept only complete OAuth records or well-known token
+records; malformed or unknown JSON is never used as a bearer token.
+
 ## Security responsibilities
 
-The helper owns storage and its security properties. A helper should:
+Clodex owns OAuth parsing, refresh decisions, replacement-token serialization,
+and in-process refresh deduplication per provider and credential reference. The
+helper owns storage and its security properties. A helper should:
 
 - encrypt credentials at rest using a system or user trust root;
 - serialize concurrent updates when its backend requires it;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bman654/clodex",
-  "version": "1.2.2",
+  "version": "2.0.0",
   "publishConfig": {
     "access": "public"
   },

package/dist/chunk-3XM6UZWP.js

@@ -1,540 +0,0 @@
-#!/usr/bin/env node
-
-// src/server-runtime.ts
-import {
-  closeSync,
-  mkdirSync as mkdirSync2,
-  openSync,
-  readFileSync,
-  renameSync,
-  rmSync,
-  unlinkSync,
-  writeFileSync
-} from "fs";
-import { dirname, join as join2 } from "path";
-
-// src/paths.ts
-import { homedir } from "os";
-import { join } from "path";
-import { cpSync, existsSync, mkdirSync, readdirSync } from "fs";
-var APP_DIR_NAME = "clodex";
-var LEGACY_APP_DIR_NAME = "relay-ai";
-function userHome(env = process.env) {
-  return env.HOME ?? env.USERPROFILE ?? homedir();
-}
-function resolveAppHomeOverride(env = process.env) {
-  const override = env.CLODEX_HOME;
-  return override?.trim() || void 0;
-}
-function getAppHome(env = process.env) {
-  const override = resolveAppHomeOverride(env);
-  if (override) return override;
-  return join(userHome(env), `.${APP_DIR_NAME}`);
-}
-function getLegacyAppHome(env = process.env) {
-  return join(userHome(env), `.${LEGACY_APP_DIR_NAME}`);
-}
-var legacyMigrationDone = false;
-function ensureLegacyAppHomeMigrated(env = process.env) {
-  if (legacyMigrationDone) return;
-  legacyMigrationDone = true;
-  try {
-    const appHome = getAppHome(env);
-    if (existsSync(appHome)) return;
-    const legacyHome = getLegacyAppHome(env);
-    if (!existsSync(legacyHome)) return;
-    mkdirSync(appHome, { recursive: true, mode: 448 });
-    for (const entry of readdirSync(legacyHome)) {
-      if (entry === "logs") continue;
-      cpSync(join(legacyHome, entry), join(appHome, entry), { recursive: true });
-    }
-  } catch {
-  }
-}
-function getConfigPath(env = process.env) {
-  return join(getAppHome(env), "config.json");
-}
-function getProvidersPath(env = process.env) {
-  return join(getAppHome(env), "providers.json");
-}
-function getLogsPath(env = process.env) {
-  return join(getAppHome(env), "logs");
-}
-
-// src/server-runtime.ts
-function getServerRuntimePath(env = process.env) {
-  return join2(getAppHome(env), "server-runtime.json");
-}
-function getServerRuntimeLockPath(env = process.env) {
-  return join2(getAppHome(env), "server-runtime.lock");
-}
-function isDiscoveryDisabled(flag, env = process.env) {
-  if (flag !== void 0) return flag;
-  const raw = env.CLODEX_NO_DISCOVERY?.trim().toLowerCase();
-  return raw === "1" || raw === "true";
-}
-function isPort(value) {
-  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65535;
-}
-function parseServerRuntimeRecord(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  const record = value;
-  const mode = record["mode"];
-  if (mode !== "endpoint" && mode !== "proxy") return null;
-  if (!isPort(record["port"])) return null;
-  const pid = record["pid"];
-  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) return null;
-  const startedAt = typeof record["startedAt"] === "string" ? record["startedAt"] : "";
-  const caPath = record["caPath"];
-  if (mode === "proxy") {
-    if (typeof caPath !== "string" || !caPath.trim()) return null;
-    return { mode, port: record["port"], pid, caPath, startedAt };
-  }
-  return { mode, port: record["port"], pid, startedAt };
-}
-function parseServerRuntimeStates(raw) {
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return [];
-  }
-  const items = Array.isArray(parsed) ? parsed : [parsed];
-  const states = [];
-  for (const item of items) {
-    const state = parseServerRuntimeRecord(item);
-    if (state) states.push(state);
-  }
-  return states;
-}
-function isPidAlive(pid, kill = process.kill.bind(process)) {
-  try {
-    kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err?.code === "EPERM";
-  }
-}
-var RUNTIME_LOCK_STALE_MS = 1e4;
-var RUNTIME_LOCK_WAIT_MS = 500;
-var RUNTIME_LOCK_RETRY_MS = 25;
-function tryAcquireRuntimeLock(lockPath, opts = {}) {
-  const now = opts.now ?? Date.now();
-  const alive = opts.isAlive ?? isPidAlive;
-  mkdirSync2(dirname(lockPath), { recursive: true, mode: 448 });
-  for (let attempt = 0; attempt < 2; attempt++) {
-    try {
-      const fd = openSync(lockPath, "wx");
-      const content = { pid: process.pid, startedAt: now };
-      writeFileSync(fd, JSON.stringify(content));
-      closeSync(fd);
-      return () => {
-        try {
-          unlinkSync(lockPath);
-        } catch {
-        }
-      };
-    } catch {
-      let stale = false;
-      try {
-        const existing = JSON.parse(readFileSync(lockPath, "utf8"));
-        stale = !existing.pid || !alive(existing.pid) || typeof existing.startedAt === "number" && now - existing.startedAt > RUNTIME_LOCK_STALE_MS;
-      } catch {
-        stale = true;
-      }
-      if (!stale) return null;
-      try {
-        unlinkSync(lockPath);
-      } catch {
-      }
-    }
-  }
-  return null;
-}
-function sleepSync(ms) {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-function withRuntimeWriteLock(env, mutate) {
-  const lockPath = getServerRuntimeLockPath(env);
-  let release = null;
-  const deadline = Date.now() + RUNTIME_LOCK_WAIT_MS;
-  for (; ; ) {
-    release = tryAcquireRuntimeLock(lockPath);
-    if (release || Date.now() >= deadline) break;
-    sleepSync(RUNTIME_LOCK_RETRY_MS);
-  }
-  try {
-    mutate();
-  } finally {
-    release?.();
-  }
-}
-function readAllRecords(env) {
-  let raw;
-  try {
-    raw = readFileSync(getServerRuntimePath(env), "utf8");
-  } catch {
-    return [];
-  }
-  return parseServerRuntimeStates(raw);
-}
-function atomicWriteRecords(path, records) {
-  mkdirSync2(dirname(path), { recursive: true, mode: 448 });
-  const tmpPath = `${path}.${process.pid}.tmp`;
-  writeFileSync(tmpPath, `${JSON.stringify(records, null, 2)}
-`, { encoding: "utf8", mode: 384 });
-  renameSync(tmpPath, path);
-}
-function registerServerRuntimeState(state, env = process.env, options = {}) {
-  const alive = options.isAlive ?? isPidAlive;
-  try {
-    withRuntimeWriteLock(env, () => {
-      const records = readAllRecords(env).filter(
-        (record) => record.pid !== state.pid && alive(record.pid)
-      );
-      records.push(state);
-      atomicWriteRecords(getServerRuntimePath(env), records);
-    });
-  } catch {
-  }
-}
-function unregisterServerRuntimeState(pid = process.pid, env = process.env, options = {}) {
-  const alive = options.isAlive ?? isPidAlive;
-  try {
-    withRuntimeWriteLock(env, () => {
-      const records = readAllRecords(env).filter(
-        (record) => record.pid !== pid && alive(record.pid)
-      );
-      if (records.length === 0) {
-        rmSync(getServerRuntimePath(env), { force: true });
-      } else {
-        atomicWriteRecords(getServerRuntimePath(env), records);
-      }
-    });
-  } catch {
-  }
-}
-function readLiveServerRuntimeStates(env = process.env, options = {}) {
-  const alive = options.isAlive ?? isPidAlive;
-  return readAllRecords(env).filter((state) => alive(state.pid));
-}
-function orderWrapperServerCandidates(records) {
-  return [...records].sort((a, b) => {
-    if (a.mode !== b.mode) return a.mode === "proxy" ? -1 : 1;
-    return (Date.parse(b.startedAt) || 0) - (Date.parse(a.startedAt) || 0);
-  });
-}
-
-// src/config.ts
-import { dirname as dirname2 } from "path";
-import { mkdirSync as mkdirSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-function readJsonFile(path) {
-  try {
-    const parsed = JSON.parse(readFileSync2(path, "utf8"));
-    return parsed && typeof parsed === "object" ? parsed : null;
-  } catch {
-    return null;
-  }
-}
-function readConfig() {
-  ensureLegacyAppHomeMigrated();
-  return readJsonFile(getConfigPath()) ?? {};
-}
-function writeConfig(config) {
-  const configPath = getConfigPath();
-  mkdirSync3(dirname2(configPath), { recursive: true, mode: 448 });
-  writeFileSync2(configPath, `${JSON.stringify(config, null, 2)}
-`, { encoding: "utf8", mode: 384 });
-}
-function loadPreferences() {
-  const config = readConfig();
-  return {
-    lastModel: config.lastModel,
-    lastProvider: config.lastProvider,
-    recentModelsByProvider: config.recentModelsByProvider,
-    favoriteModels: config.favoriteModels,
-    modelAliases: config.modelAliases,
-    claudeBridgeMode: config.claudeBridgeMode,
-    serverBridgeMode: config.serverBridgeMode,
-    appPathOverrides: config.appPathOverrides,
-    recentLaunchFolders: config.recentLaunchFolders,
-    server: config.server
-  };
-}
-function savePreferences(prefs) {
-  const config = readConfig();
-  if (prefs.lastModel !== void 0) config.lastModel = prefs.lastModel;
-  if (prefs.lastProvider !== void 0) config.lastProvider = prefs.lastProvider;
-  if (prefs.recentModelsByProvider !== void 0) config.recentModelsByProvider = prefs.recentModelsByProvider;
-  if (prefs.favoriteModels !== void 0) config.favoriteModels = prefs.favoriteModels;
-  if (prefs.modelAliases !== void 0) config.modelAliases = prefs.modelAliases;
-  if (prefs.claudeBridgeMode !== void 0) config.claudeBridgeMode = prefs.claudeBridgeMode;
-  if (prefs.serverBridgeMode !== void 0) config.serverBridgeMode = prefs.serverBridgeMode;
-  if (prefs.appPathOverrides !== void 0) config.appPathOverrides = prefs.appPathOverrides;
-  if (prefs.recentLaunchFolders !== void 0) config.recentLaunchFolders = prefs.recentLaunchFolders;
-  writeConfig(config);
-}
-function getAppPathOverride(appId) {
-  const value = loadPreferences().appPathOverrides?.[appId];
-  return typeof value === "string" && value.trim() ? value : void 0;
-}
-function resolveBridgeMode(command, explicit, opts = {}) {
-  const key = command === "claude" ? "claudeBridgeMode" : "serverBridgeMode";
-  if (explicit) {
-    if (opts.persist === true) savePreferences({ [key]: explicit });
-    return explicit;
-  }
-  return loadPreferences()[key] ?? "proxy";
-}
-var MAX_RECENT_MODELS = 3;
-function recordLaunchSelection(_agent, providerId, modelId, prefs) {
-  const prevRecent = prefs.recentModelsByProvider?.[providerId] ?? [];
-  const updatedRecent = [modelId, ...prevRecent.filter((id) => id !== modelId)].slice(0, MAX_RECENT_MODELS);
-  savePreferences({
-    lastProvider: providerId,
-    lastModel: modelId,
-    recentModelsByProvider: { ...prefs.recentModelsByProvider, [providerId]: updatedRecent }
-  });
-}
-var SERVER_PASSWORD_SERVICE = "clodex-server-password";
-var SERVER_PASSWORD_ACCOUNT = "server-password";
-async function getServerPasswordKeyring() {
-  try {
-    const { Entry } = await import("@napi-rs/keyring");
-    return new Entry(SERVER_PASSWORD_SERVICE, SERVER_PASSWORD_ACCOUNT);
-  } catch {
-    return null;
-  }
-}
-async function getSavedServerPassword() {
-  const config = readConfig();
-  if (config.server?.savedPassword) {
-    const pwd = config.server.savedPassword;
-    const keyring2 = await getServerPasswordKeyring();
-    if (keyring2) {
-      try {
-        await keyring2.setPassword(pwd);
-        delete config.server.savedPassword;
-        if (Object.keys(config.server).length === 0) delete config.server;
-        writeConfig(config);
-      } catch {
-      }
-    }
-    return pwd;
-  }
-  const keyring = await getServerPasswordKeyring();
-  if (keyring) {
-    try {
-      return await keyring.getPassword();
-    } catch {
-      return null;
-    }
-  }
-  return null;
-}
-async function setSavedServerPassword(password) {
-  const keyring = await getServerPasswordKeyring();
-  if (keyring) {
-    try {
-      await keyring.setPassword(password);
-      return;
-    } catch {
-    }
-  }
-  const config = readConfig();
-  config.server = {
-    ...config.server ?? {},
-    savedPassword: password
-  };
-  writeConfig(config);
-}
-function getServerExposedProviders() {
-  const list = readConfig().server?.exposedProviders;
-  return list && list.length > 0 ? list : null;
-}
-function setServerExposedProviders(providerIds) {
-  const config = readConfig();
-  config.server = {
-    ...config.server ?? {},
-    exposedProviders: providerIds
-  };
-  writeConfig(config);
-}
-function getServerMaskGatewayIds() {
-  return readConfig().server?.maskGatewayIds ?? true;
-}
-function setServerMaskGatewayIds(mask) {
-  const config = readConfig();
-  config.server = {
-    ...config.server ?? {},
-    maskGatewayIds: mask
-  };
-  writeConfig(config);
-}
-function getServerFavoritesOnly() {
-  return readConfig().server?.favoritesOnly ?? false;
-}
-function setServerFavoritesOnly(favoritesOnly) {
-  const config = readConfig();
-  config.server = {
-    ...config.server ?? {},
-    favoritesOnly
-  };
-  writeConfig(config);
-}
-function getServerListenMode() {
-  return readConfig().server?.listenMode === "network" ? "network" : "local";
-}
-function setServerListenMode(listenMode) {
-  const config = readConfig();
-  config.server = {
-    ...config.server ?? {},
-    listenMode
-  };
-  writeConfig(config);
-}
-
-// src/launch.ts
-import { execSync, spawn } from "child_process";
-import { existsSync as existsSync3, appendFileSync } from "fs";
-import { homedir as homedir2 } from "os";
-import { join as join3 } from "path";
-
-// src/binary-lookup.ts
-import { execFileSync } from "child_process";
-import { existsSync as existsSync2 } from "fs";
-function findBinaryOnPath(name, fallbackPaths, options = {}) {
-  const isWindows2 = options.isWindows ?? process.platform === "win32";
-  const exists = options.exists ?? existsSync2;
-  const runWhich = options.runWhich ?? ((binary, win) => execFileSync(win ? "where.exe" : "which", [binary], {
-    encoding: "utf8",
-    stdio: ["pipe", "pipe", "pipe"]
-  }));
-  try {
-    const lines = runWhich(name, isWindows2).trim().split("\n").map((line) => line.trim()).filter(Boolean);
-    const path = (isWindows2 ? lines.find((line) => line.toLowerCase().endsWith(".cmd")) : null) ?? lines[0];
-    if (path && (!options.verifyWhichResult || exists(path))) return path;
-  } catch {
-  }
-  for (const path of fallbackPaths) {
-    if (exists(path)) return path;
-  }
-  return null;
-}
-
-// src/launch.ts
-var isWindows = process.platform === "win32";
-var FALLBACK_PATHS = isWindows ? [
-  join3(process.env["APPDATA"] ?? homedir2(), "npm", "claude.cmd"),
-  join3(process.env["APPDATA"] ?? homedir2(), "npm", "claude"),
-  join3(homedir2(), "AppData", "Roaming", "npm", "claude.cmd")
-] : [
-  join3(homedir2(), ".local", "bin", "claude"),
-  join3(homedir2(), ".npm", "bin", "claude"),
-  "/usr/local/bin/claude",
-  "/opt/homebrew/bin/claude"
-];
-function findClaudeBinary() {
-  const environmentOverride = process.env["CLODEX_CLAUDE_PATH"];
-  if (environmentOverride?.trim()) {
-    return existsSync3(environmentOverride) ? environmentOverride : null;
-  }
-  const override = getAppPathOverride("claude");
-  if (override) return existsSync3(override) ? override : null;
-  return findBinaryOnPath("claude", FALLBACK_PATHS);
-}
-function getInstalledClaudeVersion() {
-  try {
-    const claudePath = findClaudeBinary();
-    if (!claudePath) return "2.1.183";
-    const result = execSync(`${isWindows ? `"${claudePath}"` : claudePath} --version`, {
-      encoding: "utf8",
-      stdio: ["pipe", "pipe", "pipe"]
-    });
-    const match = result.match(/(\d+\.\d+\.\d+)/);
-    if (match) return match[1];
-  } catch {
-  }
-  return "2.1.183";
-}
-function buildClaudeArgs(model, extraArgs) {
-  return model ? ["--model", model, ...extraArgs] : [...extraArgs];
-}
-function launchClaude(env, model, extraArgs) {
-  return new Promise((resolve) => {
-    const claudePath = findClaudeBinary();
-    const args = buildClaudeArgs(model, extraArgs);
-    const debugFileIdx = extraArgs.indexOf("--debug-file");
-    const debugLogPath = debugFileIdx !== -1 && extraArgs[debugFileIdx + 1] ? extraArgs[debugFileIdx + 1] : void 0;
-    const originalStdoutWrite = process.stdout.write;
-    const originalStderrWrite = process.stderr.write;
-    const muteWrite = (chunk, encoding, callback) => {
-      if (typeof encoding === "function") {
-        callback = encoding;
-      }
-      if (debugLogPath) {
-        try {
-          const str = typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
-          appendFileSync(debugLogPath, `[parent] ${str}`);
-        } catch {
-        }
-      }
-      if (callback) callback();
-      return true;
-    };
-    process.stdout.write = muteWrite;
-    process.stderr.write = muteWrite;
-    const restore = () => {
-      process.stdout.write = originalStdoutWrite;
-      process.stderr.write = originalStderrWrite;
-    };
-    const child = spawn(claudePath, args, {
-      stdio: "inherit",
-      env,
-      shell: isWindows
-    });
-    const forward = (signal) => {
-      child.kill(signal);
-    };
-    process.once("SIGINT", () => forward("SIGINT"));
-    process.once("SIGTERM", () => forward("SIGTERM"));
-    child.on("exit", (code) => {
-      restore();
-      resolve(code ?? 0);
-    });
-    child.on("error", (err) => {
-      restore();
-      resolve(1);
-    });
-  });
-}
-
-export {
-  getAppHome,
-  ensureLegacyAppHomeMigrated,
-  getProvidersPath,
-  getLogsPath,
-  isDiscoveryDisabled,
-  registerServerRuntimeState,
-  unregisterServerRuntimeState,
-  readLiveServerRuntimeStates,
-  orderWrapperServerCandidates,
-  loadPreferences,
-  savePreferences,
-  resolveBridgeMode,
-  recordLaunchSelection,
-  getSavedServerPassword,
-  setSavedServerPassword,
-  getServerExposedProviders,
-  setServerExposedProviders,
-  getServerMaskGatewayIds,
-  setServerMaskGatewayIds,
-  getServerFavoritesOnly,
-  setServerFavoritesOnly,
-  getServerListenMode,
-  setServerListenMode,
-  findClaudeBinary,
-  getInstalledClaudeVersion,
-  launchClaude
-};
-//# sourceMappingURL=chunk-3XM6UZWP.js.map