@aliyunrds/ctxdb 1.0.8-beta.3 → 1.0.8

package/dist/{chunk-BUK4SZC2.js → chunk-3FAQREIU.js}

@@ -1,17 +1,14 @@
 #!/usr/bin/env node
 import {
   DISTRIBUTION_MANIFEST
-} from "./chunk-R67JELM7.js";
+} from "./chunk-5ITT5GSP.js";
 
 // src/lib/credentials.ts
+import { selectDataApiCredential } from "@aliyunrds/ctxdb-shared";
 function apiKeyCredential(apiKey) {
   return { type: "api-key", value: apiKey };
 }
-function resolveDataApiCredential(cfg, env = process.env) {
-  const accessToken = env.CTXDB_ACCESS_TOKEN?.trim();
-  if (accessToken) return { type: "access-token", value: accessToken };
-  return cfg.apiKey ? apiKeyCredential(cfg.apiKey) : null;
-}
+var resolveDataApiCredential = selectDataApiCredential;
 function isDataApiReady(cfg, env = process.env) {
   return Boolean(cfg.baseUrl && resolveDataApiCredential(cfg, env));
 }
@@ -82,6 +79,8 @@ var PACKAGE_NAME = PACKAGE_IDENTITY.name;
 var PACKAGE_VERSION = PACKAGE_IDENTITY.version;
 
 // src/lib/http-client.ts
+import { createRequestAuthorizationProvider } from "@aliyunrds/ctxdb-shared";
+import "@aliyunrds/ctxdb-shared";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var CtxdbError = class extends Error {
   constructor(message) {
@@ -175,7 +174,7 @@ var HttpClient = class {
     this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
     this.credential = credential;
     this.apiKey = opts.apiKey ?? "";
-    this.authorizationProvider = opts.authorizationProvider;
+    this.authorizationProvider = opts.authorizationProvider ?? createRequestAuthorizationProvider(credential, this.baseUrl);
     this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this.userAgent = opts.userAgent ?? `ctxdb-cli/${PACKAGE_VERSION}`;
     this.extraHeaders = { ...opts.extraHeaders ?? {} };
@@ -190,16 +189,21 @@ var HttpClient = class {
       ...this.extraHeaders,
       ...requestHeaders
     };
+    if (authorization.scheme === "Bearer") {
+      for (const key of Object.keys(h)) if (key.toLowerCase() === "authorization") delete h[key];
+      h.Authorization = `Bearer ${authorization.value}`;
+    }
     if (contentType) h["Content-Type"] = contentType;
     return h;
   }
   async doRequest(method, path, init = {}) {
+    const effectiveTimeout = init.timeoutMs ?? this.timeoutMs, started = Date.now();
     let authorization;
     if (this.authorizationProvider) {
-      authorization = await this.authorizationProvider.resolve();
+      authorization = await this.authorizationProvider.resolve({ timeoutMs: effectiveTimeout });
     } else {
       const credential = this.credential;
-      if (!credential) throw new CtxdbError("DATA API credential is required");
+      if (!credential || credential.type === "oauth-session") throw new CtxdbError("DATA API credential is required");
       authorization = {
         scheme: credential.type === "access-token" ? "Bearer" : "Token",
         value: credential.value,
@@ -207,6 +211,10 @@ var HttpClient = class {
         expiresAt: null
       };
     }
+    const safeText = (value) => {
+      const text = String(value);
+      return text.split(authorization.value).join("[REDACTED]");
+    };
     let url = `${authorization.baseUrl.replace(/\/+$/, "")}${path}`;
     if (init.params) {
       const qs = new URLSearchParams();
@@ -216,7 +224,6 @@ var HttpClient = class {
       const s = qs.toString();
       if (s) url = `${url}?${s}`;
     }
-    const effectiveTimeout = init.timeoutMs ?? this.timeoutMs;
     const dbg = isDebug();
     let t0 = 0;
     if (dbg) {
@@ -224,7 +231,7 @@ var HttpClient = class {
       debug("http", `\u2192 ${method} ${url} (timeout=${effectiveTimeout}ms)`);
     }
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), effectiveTimeout);
+    const timer = setTimeout(() => controller.abort(), Math.max(1, effectiveTimeout - (Date.now() - started)));
     try {
       let resp;
       try {
@@ -236,15 +243,16 @@ var HttpClient = class {
             init.headers
           ),
           body: init.body,
-          signal: controller.signal
+          signal: controller.signal,
+          ...authorization.scheme === "Bearer" ? { redirect: "error" } : {}
         });
       } catch (err) {
         if (err?.name === "AbortError") {
           if (dbg) debug("http", `\u2717 ${method} ${path} timeout after ${Date.now() - t0}ms`);
           throw new CtxdbError(`request timeout after ${effectiveTimeout}ms: ${url}`);
         }
-        if (dbg) debug("http", `\u2717 ${method} ${path} network error after ${Date.now() - t0}ms: ${err?.message ?? err}`);
-        throw new CtxdbError(`network error contacting ${url}: ${err?.message ?? err}`);
+        if (dbg) debug("http", `\u2717 ${method} ${path} network error after ${Date.now() - t0}ms: ${safeText(err?.message ?? err)}`);
+        throw new CtxdbError(`network error contacting ${url}: ${safeText(err?.message ?? err)}`);
       }
       if (resp.status === 204) {
         if (dbg) debug("http", `\u2190 ${method} ${path} 204 (${Date.now() - t0}ms)`);
@@ -252,14 +260,15 @@ var HttpClient = class {
       }
       let text;
       try {
-        text = await resp.text();
+        const bodyText = await resp.text();
+        text = authorization.scheme === "Bearer" || !resp.ok ? safeText(bodyText) : bodyText;
       } catch (err) {
         if (err?.name === "AbortError") {
           if (dbg) debug("http", `\u2717 ${method} ${path} body-read timeout after ${Date.now() - t0}ms`);
           throw new CtxdbError(`request timeout after ${effectiveTimeout}ms (body read): ${url}`);
         }
-        if (dbg) debug("http", `\u2717 ${method} ${path} body-read error after ${Date.now() - t0}ms: ${err?.message ?? err}`);
-        throw new CtxdbError(`network error reading body from ${url}: ${err?.message ?? err}`);
+        if (dbg) debug("http", `\u2717 ${method} ${path} body-read error after ${Date.now() - t0}ms: ${safeText(err?.message ?? err)}`);
+        throw new CtxdbError(`network error reading body from ${url}: ${safeText(err?.message ?? err)}`);
       }
       if (!resp.ok) {
         const parsedError = parseErrorResponse(text, `HTTP ${resp.status}`);
@@ -593,9 +602,10 @@ function agentFromArgvWithFallback(argv = process.argv.slice(2), env = process.e
 }
 
 // src/lib/config.ts
-import { readFileSync as readFileSync3, existsSync as existsSync4, unlinkSync as unlinkSync3 } from "fs";
-import { homedir as homedir4 } from "os";
-import { dirname as dirname5, join as join5 } from "path";
+import { publicAuthenticationFromConfig } from "@aliyunrds/ctxdb-shared";
+import { readFileSync as readFileSync2, existsSync as existsSync3, unlinkSync as unlinkSync2 } from "fs";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname4, join as join4 } from "path";
 
 // src/lib/secure-file.ts
 import {
@@ -695,145 +705,39 @@ function secureAtomicWrite(target, content, options = {}) {
 // src/lib/secrets.ts
 import { createHmac, randomBytes as randomBytes2 } from "crypto";
 var PROCESS_FINGERPRINT_KEY = randomBytes2(32);
-
-// src/credentials/local-credential-provider.ts
-import {
-  closeSync as closeSync2,
-  existsSync as existsSync3,
-  mkdirSync as mkdirSync3,
-  openSync as openSync2,
-  readFileSync as readFileSync2,
-  statSync as statSync2,
-  unlinkSync as unlinkSync2,
-  writeFileSync as writeFileSync2
-} from "fs";
-import { homedir as homedir3 } from "os";
-import { dirname as dirname4, join as join4 } from "path";
-import { setTimeout as delay } from "timers/promises";
-
-// src/credentials/types.ts
-var ACTIVE_CONTEXTDB_CREDENTIAL = "contextdb/active";
-
-// src/credentials/local-credential-provider.ts
-var DOCUMENT_VERSION = 1;
-var STALE_LOCK_MS = 10 * 60 * 1e3;
-function defaultCredentialsPath() {
-  return join4(homedir3(), ".ctxdb", "credentials.json");
-}
-function emptyDocument() {
-  return { version: DOCUMENT_VERSION, records: {} };
-}
-function normalizeOrigin(value, field) {
-  if (typeof value !== "string" || !value) {
-    throw new Error(`credentials: ${field} must be a non-empty URL`);
-  }
-  let url;
-  try {
-    url = new URL(value);
-  } catch {
-    throw new Error(`credentials: ${field} must be a valid URL`);
-  }
-  if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
-    throw new Error(`credentials: ${field} must be an HTTP(S) origin`);
-  }
-  return url.toString().replace(/\/$/, "");
-}
-function parseRecord(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error("credentials: record must be an object");
-  }
-  const raw = value;
-  if (raw.kind !== "api-key") {
-    throw new Error(`credentials: unsupported record kind ${String(raw.kind)}`);
-  }
-  const payload = raw.payload;
-  const metadata = raw.metadata;
-  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
-    throw new Error("credentials: api-key payload must be an object");
-  }
-  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
-    throw new Error("credentials: api-key metadata must be an object");
-  }
-  const body = payload;
-  const meta = metadata;
-  if (typeof body.api_key !== "string" || !body.api_key) {
-    throw new Error("credentials: api_key must be a non-empty string");
-  }
-  if (meta.authorization_method !== "browser-loopback" && meta.authorization_method !== "device-code") {
-    throw new Error("credentials: authorization_method is invalid");
-  }
-  if (typeof meta.issued_at !== "string" || !Number.isFinite(Date.parse(meta.issued_at))) {
-    throw new Error("credentials: issued_at is invalid");
-  }
-  return {
-    kind: "api-key",
-    payload: {
-      apiKey: body.api_key,
-      baseUrl: normalizeOrigin(body.base_url, "base_url"),
-      loginServer: normalizeOrigin(body.login_server, "login_server")
-    },
-    metadata: {
-      authorizationMethod: meta.authorization_method,
-      issuedAt: meta.issued_at
-    }
-  };
-}
-function parseDocument(text) {
-  let raw;
-  try {
-    raw = JSON.parse(text);
-  } catch {
-    throw new Error("credentials: credentials.json is not valid JSON");
-  }
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-    throw new Error("credentials: document must be an object");
-  }
-  const document = raw;
-  if (document.version !== DOCUMENT_VERSION) {
-    throw new Error(`credentials: unsupported document version ${String(document.version)}`);
-  }
-  if (!document.records || typeof document.records !== "object" || Array.isArray(document.records)) {
-    throw new Error("credentials: records must be an object");
-  }
-  const records = document.records;
-  const unknown = Object.keys(records).filter((key) => key !== ACTIVE_CONTEXTDB_CREDENTIAL);
-  if (unknown.length > 0) {
-    throw new Error(`credentials: unsupported record key ${unknown[0]}`);
-  }
-  const active = records[ACTIVE_CONTEXTDB_CREDENTIAL];
-  return {
-    version: DOCUMENT_VERSION,
-    records: active === void 0 ? {} : { [ACTIVE_CONTEXTDB_CREDENTIAL]: parseRecord(active) }
-  };
-}
-function assertOwnerOnly(path) {
-  if (process.platform === "win32" || !existsSync3(path)) return;
-  const mode = statSync2(path).mode & 511;
-  if ((mode & 63) !== 0) {
-    throw new Error(`credentials: ${path} must be owner-only (run chmod 600)`);
-  }
-}
-function readDocument(path) {
-  if (!existsSync3(path)) return emptyDocument();
-  assertOwnerOnly(path);
-  return parseDocument(readFileSync2(path, "utf8"));
+function maskApiKey(apiKey) {
+  if (!apiKey) return "";
+  const payload = apiKey.startsWith("ctxdb-") ? apiKey.slice("ctxdb-".length) : null;
+  if (payload && payload.length > 12) return `ctxdb-xxxxxx${payload.slice(-6)}`;
+  if (payload !== null) return "x".repeat(apiKey.length);
+  if (apiKey.length <= 12) return "x".repeat(apiKey.length);
+  return `xxxxxx${apiKey.slice(-6)}`;
 }
-function readActiveCredentialSync(path = defaultCredentialsPath()) {
-  return readDocument(path).records[ACTIVE_CONTEXTDB_CREDENTIAL];
+function credentialFingerprint(apiKey, processKey = PROCESS_FINGERPRINT_KEY) {
+  if (!apiKey) return "";
+  return createHmac("sha256", processKey).update(apiKey).digest("hex").slice(0, 12);
 }
 
+// src/credentials/local-credential-provider.ts
+import { LocalCredentialProvider, defaultCredentialsPath, readActiveCredentialSync, withAuthorizationLock, internalCandidate } from "@aliyunrds/ctxdb-shared";
+
 // src/lib/config.ts
 import {
-  resolveDebugPolicy
+  resolveDebugPolicy,
+  oauthProfile,
+  validateLoginChoice,
+  authSnapshot,
+  assertAuthSnapshot,
+  withAuthConfigLock
 } from "@aliyunrds/ctxdb-shared";
-function defaultConfigPath() {
-  return join5(homedir4(), ".ctxdb", "ctxdb.json");
+function defaultConfigPath(env = process.env) {
+  return env.CTXDB_CONFIG_PATH || join4(homedir3(), ".ctxdb", "ctxdb.json");
 }
-var DEFAULT_CONFIG_PATH = join5(homedir4(), ".ctxdb", "ctxdb.json");
+var DEFAULT_CONFIG_PATH = join4(homedir3(), ".ctxdb", "ctxdb.json");
 function configDir() {
-  return join5(homedir4(), ".ctxdb");
+  return join4(homedir3(), ".ctxdb");
 }
-var DEFAULT_BASE_URL = "https://context-database.aliyuncs.com";
+var DEFAULT_BASE_URL = "https://api.cn-hangzhou.agentcontext.aliyuncs.com";
 var DEFAULT_USER_ID = "default";
 var DEFAULT_TOP_K = 5;
 var DEFAULT_THRESHOLD = 0.4;
@@ -865,9 +769,9 @@ function coerceKbCatalogInjection(v) {
   return DEFAULT_KB_CATALOG_INJECTION;
 }
 function readRaw(path) {
-  if (!existsSync4(path)) return {};
+  if (!existsSync3(path)) return {};
   try {
-    const parsed = JSON.parse(readFileSync3(path, "utf-8"));
+    const parsed = JSON.parse(readFileSync2(path, "utf-8"));
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       return parsed;
     }
@@ -875,6 +779,99 @@ function readRaw(path) {
   }
   return {};
 }
+function asRawObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function explicitAgentRaw(raw, agent) {
+  const agents = asRawObject(raw.agents);
+  return agents ? asRawObject(agents[agent]) : null;
+}
+function explicitString(raw, key) {
+  const value = raw?.[key];
+  return typeof value === "string" && value ? value : null;
+}
+function inspectConfig(options = {}) {
+  const path = options.path ?? defaultConfigPath();
+  const env = options.env ?? process.env;
+  if (!existsSync3(path)) {
+    return {
+      path,
+      state: "missing",
+      profiles: diagnosticProfiles({}, env),
+      unknownProfiles: [],
+      safeMessage: null
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync2(path, "utf-8"));
+  } catch {
+    return {
+      path,
+      state: "malformed-json",
+      profiles: diagnosticProfiles({}, env),
+      unknownProfiles: [],
+      safeMessage: "Configuration contains malformed JSON and requires confirmation before repair."
+    };
+  }
+  const raw = asRawObject(parsed);
+  if (!raw || !isV2Schema(raw)) {
+    return {
+      path,
+      state: "unsupported-schema",
+      profiles: diagnosticProfiles({}, env),
+      unknownProfiles: [],
+      safeMessage: "Configuration schema is unsupported and requires confirmation before repair."
+    };
+  }
+  const agents = asRawObject(raw.agents) ?? {};
+  const known = /* @__PURE__ */ new Set(["default", ...SUPPORTED_AGENTS]);
+  return {
+    path,
+    state: "valid-v2",
+    profiles: diagnosticProfiles(raw, env),
+    unknownProfiles: Object.keys(agents).filter((name) => !known.has(name)),
+    safeMessage: null
+  };
+}
+function diagnosticProfiles(raw, env) {
+  const profiles = ["default", ...SUPPORTED_AGENTS];
+  return profiles.map((agent) => {
+    const explicit = explicitAgentRaw(raw, agent);
+    const inherited = agent === "default" ? null : explicitAgentRaw(raw, "default");
+    const explicitKey = explicitString(explicit, "api_key");
+    const inheritedKey = explicitString(inherited, "api_key");
+    const apiKey = env.CTXDB_API_KEY || explicitKey || inheritedKey;
+    const credentialSource = env.CTXDB_API_KEY ? "environment" : explicitKey ? "profile" : inheritedKey ? "default" : "none";
+    const credentialProfile = credentialSource === "profile" ? agent : credentialSource === "default" ? "default" : null;
+    const explicitBase = explicitString(explicit, "base_url");
+    const inheritedBase = explicitString(inherited, "base_url");
+    const baseUrl = (env.CTXDB_BASE_URL || explicitBase || inheritedBase || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const baseUrlSource = env.CTXDB_BASE_URL ? "environment" : explicitBase ? "profile" : inheritedBase ? "default" : "built-in";
+    const explicitUser = explicitString(explicit, "user_id");
+    const inheritedUser = explicitString(inherited, "user_id");
+    const userId = env.CTXDB_USER_ID || explicitUser || inheritedUser || DEFAULT_USER_ID;
+    const userIdSource = env.CTXDB_USER_ID ? "environment" : explicitUser ? "profile" : inheritedUser ? "default" : "built-in";
+    return {
+      agent,
+      explicitProfile: explicit !== null,
+      explicitFields: explicit ? Object.keys(explicit).sort() : [],
+      credential: {
+        source: credentialSource,
+        profile: credentialProfile,
+        masked: apiKey ? maskApiKey(apiKey) : null,
+        fingerprint: apiKey ? credentialFingerprint(apiKey) : null
+      },
+      effective: {
+        baseUrl,
+        baseUrlSource,
+        userId,
+        userIdSource,
+        complete: Boolean(apiKey && baseUrl)
+      }
+    };
+  });
+}
 function agentRawFromFile(raw, agent) {
   const agents = raw.agents;
   if (agents && typeof agents === "object" && !Array.isArray(agents)) {
@@ -928,8 +925,8 @@ function applyEnv(cfg, env) {
   return applyDebugPolicy(cfg);
 }
 function load(options = {}) {
-  const path = options.path ?? defaultConfigPath();
   const env = options.env ?? process.env;
+  const path = options.path ?? defaultConfigPath(env);
   const raw = readRaw(path);
   const agent = resolveConfigAgent({ ...options, path, env }, raw);
   if (!isV2Schema(raw)) {
@@ -942,20 +939,32 @@ function load(options = {}) {
     }
     const cfg2 = configFromDisk({});
     const managed2 = !DISTRIBUTION_MANIFEST.capabilities.managedCredentials || options.managedCredentials === false ? void 0 : readActiveCredentialSync(
-      options.credentialsPath ?? join5(dirname5(path), "credentials.json")
+      options.credentialsPath ?? join4(dirname4(path), "credentials.json")
     );
     if (managed2) {
       cfg2.apiKey = managed2.payload.apiKey;
-      cfg2.baseUrl = managed2.payload.baseUrl;
+      cfg2.baseUrl = managed2.metadata.baseUrl;
     }
-    return applyEnv(cfg2, env);
+    applyEnv(cfg2, env);
+    if (managed2) cfg2.authContext = {
+      configPath: path,
+      agent,
+      baseUrl: cfg2.baseUrl,
+      inheritDefaultKey: true,
+      managedCredentials: true,
+      credentialsPath: options.credentialsPath,
+      ...env.CTXDB_BASE_URL ? { baseUrlOverride: env.CTXDB_BASE_URL } : {}
+    };
+    return cfg2;
   }
-  const agentRaw = agentRawFromFile(raw, agent);
+  const explicit = agentRawFromFile(raw, agent);
+  if (DISTRIBUTION_MANIFEST.capabilities.deviceFlow) validateLoginChoice(explicit);
+  const agentRaw = { ...explicit };
   if (agent !== "default") {
     const defaultRaw = agentRawFromFile(raw, "default");
     if (Object.keys(defaultRaw).length > 0) {
       for (const [k, v] of Object.entries(defaultRaw)) {
-        if (!(k in agentRaw)) {
+        if (k !== "credential_ref" && k !== "oauth_credential_ref" && k !== "access_credential" && !(k in agentRaw)) {
           agentRaw[k] = v;
         }
       }
@@ -963,18 +972,62 @@ function load(options = {}) {
   }
   const cfg = configFromDisk(agentRaw);
   const managed = !DISTRIBUTION_MANIFEST.capabilities.managedCredentials || options.managedCredentials === false ? void 0 : readActiveCredentialSync(
-    options.credentialsPath ?? join5(dirname5(path), "credentials.json")
+    options.credentialsPath ?? join4(dirname4(path), "credentials.json")
   );
   if (managed) {
     cfg.apiKey = managed.payload.apiKey;
-    cfg.baseUrl = managed.payload.baseUrl;
+    cfg.baseUrl = managed.metadata.baseUrl;
+  }
+  const environmentCredential = !!(env.CTXDB_API_KEY || env.CTXDB_ACCESS_TOKEN?.trim());
+  if (DISTRIBUTION_MANIFEST.capabilities.deviceFlow) {
+    cfg.credentialRef = explicit.credential_ref;
+    const stored = environmentCredential ? void 0 : publicAuthenticationFromConfig({ ...raw, version: 2, agents: raw.agents ?? {} }, path, agent, env.CTXDB_BASE_URL);
+    if (stored) {
+      cfg.baseUrl = stored.baseUrl;
+      cfg.apiKey = stored.apiKey ?? null;
+      cfg.oauthCredential = stored.oauthCredential;
+    } else if (cfg.credentialRef) cfg.apiKey = null;
+    if (environmentCredential && explicit.oauth_credential_ref) cfg.oauthCredential = oauthProfile(explicit.oauth_credential_ref, path, agent, cfg.baseUrl);
   }
-  return applyEnv(cfg, env);
+  const persistedApiKey = cfg.apiKey;
+  applyEnv(cfg, env);
+  if (DISTRIBUTION_MANIFEST.capabilities.deviceFlow) {
+    const authRaw = { ...raw, version: 2, agents: raw.agents ?? {} };
+    if (Object.hasOwn(explicit, "access_credential")) {
+      cfg.accessCredential = explicit.access_credential;
+      if (!env.CTXDB_API_KEY) cfg.apiKey = null;
+    }
+    if (env.CTXDB_API_KEY) {
+      cfg.environmentApiKey = env.CTXDB_API_KEY;
+      cfg.persistedApiKey = cfg.accessCredential !== void 0 || cfg.oauthCredential ? null : persistedApiKey;
+    }
+    cfg.authSnapshot = authSnapshot(authRaw, agent);
+    cfg.authAgent = agent;
+    cfg.authContext = {
+      configPath: path,
+      agent,
+      baseUrl: cfg.baseUrl,
+      inheritDefaultKey: true,
+      ...env.CTXDB_BASE_URL ? { baseUrlOverride: env.CTXDB_BASE_URL } : {}
+    };
+  }
+  if (managed) cfg.authContext = {
+    configPath: path,
+    agent,
+    baseUrl: cfg.baseUrl,
+    inheritDefaultKey: true,
+    managedCredentials: true,
+    credentialsPath: options.credentialsPath,
+    ...env.CTXDB_BASE_URL ? { baseUrlOverride: env.CTXDB_BASE_URL } : {}
+  };
+  return cfg;
 }
 function configToDisk(cfg) {
   return {
-    api_key: cfg.apiKey,
-    base_url: cfg.baseUrl,
+    ...cfg.credentialRef ? { credential_ref: cfg.credentialRef } : {},
+    ...cfg.accessCredential !== void 0 ? { access_credential: cfg.accessCredential } : cfg.oauthCredential ? { oauth_credential_ref: cfg.oauthCredential.reference } : {},
+    api_key: cfg.credentialRef || cfg.accessCredential !== void 0 || cfg.oauthCredential ? null : cfg.environmentApiKey && cfg.apiKey === cfg.environmentApiKey ? cfg.persistedApiKey ?? null : cfg.apiKey,
+    ...!cfg.credentialRef && cfg.accessCredential === void 0 && !cfg.oauthCredential && !cfg.authContext?.managedCredentials ? { base_url: cfg.baseUrl } : {},
     user_id: cfg.userId,
     agent_id: cfg.agentId,
     app_id: cfg.appId,
@@ -991,53 +1044,85 @@ function configToDisk(cfg) {
 }
 function removeAgent(agent, path, options = {}) {
   const target = path ?? defaultConfigPath();
-  if (!existsSync4(target)) {
-    return { removed: false, remainingAgents: [], fileDeleted: false };
-  }
-  const raw = readRaw(target);
-  if (!isV2Schema(raw) || !raw.agents || typeof raw.agents !== "object" || Array.isArray(raw.agents)) {
-    return { removed: false, remainingAgents: [], fileDeleted: false };
-  }
-  const agents = { ...raw.agents };
-  if (!(agent in agents)) {
-    return {
-      removed: false,
-      remainingAgents: Object.keys(agents),
-      fileDeleted: false
-    };
-  }
-  delete agents[agent];
-  const remaining = Object.keys(agents);
-  if (remaining.length === 0 && !options.keepEmptyShell) {
-    try {
-      unlinkSync3(target);
-      return { removed: true, remainingAgents: [], fileDeleted: true };
-    } catch {
+  return withAuthConfigLock(target, () => {
+    if (!existsSync3(target)) {
+      return { removed: false, remainingAgents: [], fileDeleted: false };
     }
-  }
-  const onDisk = { ...raw, version: 2, agents };
-  delete onDisk.default_agent;
-  secureAtomicWrite(target, JSON.stringify(onDisk, null, 2) + "\n");
-  return { removed: true, remainingAgents: remaining, fileDeleted: false };
+    const raw = readRaw(target);
+    if (!isV2Schema(raw) || !raw.agents || typeof raw.agents !== "object" || Array.isArray(raw.agents)) {
+      return { removed: false, remainingAgents: [], fileDeleted: false };
+    }
+    const agents = { ...raw.agents };
+    if (!(agent in agents)) {
+      return {
+        removed: false,
+        remainingAgents: Object.keys(agents),
+        fileDeleted: false
+      };
+    }
+    delete agents[agent];
+    const remaining = Object.keys(agents);
+    if (remaining.length === 0 && !options.keepEmptyShell && !Object.keys(asRawObject(raw.logins) ?? {}).length) {
+      try {
+        unlinkSync2(target);
+        return { removed: true, remainingAgents: [], fileDeleted: true };
+      } catch {
+      }
+    }
+    const onDisk = { ...raw, version: 2, agents };
+    delete onDisk.default_agent;
+    secureAtomicWrite(target, JSON.stringify(onDisk, null, 2) + "\n");
+    return { removed: true, remainingAgents: remaining, fileDeleted: false };
+  });
 }
 function save(cfg, path, options = {}) {
   const target = path ?? defaultConfigPath();
   const agent = resolveConfigAgent(options);
-  const raw = readRaw(target);
-  const validRaw = isV2Schema(raw) ? raw : {};
-  const existingAgents = validRaw.agents && typeof validRaw.agents === "object" && !Array.isArray(validRaw.agents) ? { ...validRaw.agents } : {};
-  const serialized = configToDisk(cfg);
-  if (options.omitApiKey) delete serialized.api_key;
-  const onDisk = {
-    ...validRaw,
-    version: 2,
-    agents: {
-      ...existingAgents,
-      [agent]: serialized
+  withAuthConfigLock(target, () => {
+    const raw = readRaw(target);
+    const validRaw = isV2Schema(raw) ? raw : {};
+    if (DISTRIBUTION_MANIFEST.capabilities.deviceFlow) {
+      const authRaw = { ...validRaw, version: 2, agents: validRaw.agents ?? {} };
+      if (cfg.authSnapshot && cfg.authAgent === agent) assertAuthSnapshot(authRaw, agent, cfg.authSnapshot);
     }
-  };
-  delete onDisk.default_agent;
-  secureAtomicWrite(target, JSON.stringify(onDisk, null, 2) + "\n");
+    const existingAgents = validRaw.agents && typeof validRaw.agents === "object" && !Array.isArray(validRaw.agents) ? { ...validRaw.agents } : {};
+    const serialized = configToDisk(cfg);
+    if (options.omitApiKey) delete serialized.api_key;
+    const previous = asRawObject(existingAgents[agent]) ?? {};
+    const next = { ...previous, ...serialized };
+    if (cfg.credentialRef) {
+      delete next.access_credential;
+      delete next.oauth_credential_ref;
+      delete next.api_key;
+    } else if (cfg.accessCredential !== void 0) {
+      delete next.credential_ref;
+      delete next.oauth_credential_ref;
+      delete next.api_key;
+    } else if (cfg.oauthCredential) {
+      delete next.access_credential;
+      next.api_key = null;
+    } else {
+      delete next.access_credential;
+      delete next.oauth_credential_ref;
+    }
+    if (options.omitApiKey) {
+      delete next.api_key;
+      for (const field of ["access_credential", "credential_ref", "oauth_credential_ref"]) {
+        if (Object.hasOwn(previous, field)) next[field] = previous[field];
+      }
+    }
+    if (next.credential_ref || Object.hasOwn(next, "access_credential") || next.oauth_credential_ref || cfg.authContext?.managedCredentials) delete next.base_url;
+    const onDisk = {
+      ...validRaw,
+      version: 2,
+      agents: {
+        ...existingAgents,
+        [agent]: next
+      }
+    };
+    delete onDisk.default_agent;
+    secureAtomicWrite(target, JSON.stringify(onDisk, null, 2) + "\n");
+  });
 }
 function configuredAgents(path) {
   const target = path ?? defaultConfigPath();
@@ -1057,21 +1142,23 @@ function hasConfiguredAgent(agent, path) {
 }
 function updateConfiguredDebug(agent, configured, path) {
   const target = path ?? defaultConfigPath();
-  const raw = readRaw(target);
-  if (!isV2Schema(raw) || !raw.agents || typeof raw.agents !== "object" || Array.isArray(raw.agents)) {
-    return false;
-  }
-  const agents = { ...raw.agents };
-  const profile = agents[agent];
-  if (!profile || typeof profile !== "object" || Array.isArray(profile)) {
-    return false;
-  }
-  agents[agent] = { ...profile, debug: configured };
-  secureAtomicWrite(
-    target,
-    JSON.stringify({ ...raw, agents }, null, 2) + "\n"
-  );
-  return true;
+  return withAuthConfigLock(target, () => {
+    const raw = readRaw(target);
+    if (!isV2Schema(raw) || !raw.agents || typeof raw.agents !== "object" || Array.isArray(raw.agents)) {
+      return false;
+    }
+    const agents = { ...raw.agents };
+    const profile = agents[agent];
+    if (!profile || typeof profile !== "object" || Array.isArray(profile)) {
+      return false;
+    }
+    agents[agent] = { ...profile, debug: configured };
+    secureAtomicWrite(
+      target,
+      JSON.stringify({ ...raw, agents }, null, 2) + "\n"
+    );
+    return true;
+  });
 }
 function writeInstalledPkgVersion(version, path) {
   const target = path ?? defaultConfigPath();
@@ -1081,7 +1168,6 @@ function writeInstalledPkgVersion(version, path) {
 }
 
 export {
-  apiKeyCredential,
   resolveDataApiCredential,
   isDataApiReady,
   setDebug,
@@ -1103,9 +1189,11 @@ export {
   detectInstalledAgents,
   agentFromEnv,
   agentFromArgvWithFallback,
+  defaultConfigPath,
   configDir,
   DEFAULT_BASE_URL,
   DEFAULT_USER_ID,
+  inspectConfig,
   load,
   removeAgent,
   save,