@aliyunrds/ctxdb 1.0.8-beta.2 → 1.0.8-beta.4

package/README.md

@@ -17,9 +17,42 @@ Config and logs live under `~/.ctxdb/`. `~/.ctxdb/ctxdb.json` is one file, but r
 
 ## Install
 
+### Public Device Flow login (requires the enabled Core/API phase 2 service)
+
+```sh
+ctxdb login --agent qoder --server https://<core-host> --no-browser
+# Complete the displayed user code through the console/independent POP test client.
+ctxdb auth status --agent qoder --json
+ctxdb setup --agent qoder
+ctxdb logout --agent qoder --json
+```
+
+Public login uses Core Device Flow only; it never calls POP, starts a localhost callback,
+or uses the internal login server. `--device-code` explicitly selects the same default flow.
+Device Flow always uses `default`, following the current Member permissions and resource ACLs.
+`login` does not accept `--scope`; creation and approval do not send a scope selector.
+Login does not install hooks/skills. Run setup separately for each selected Agent.
+
+Each profile contains only an `oauth_credential_ref`; AT/RT live in owner-only files under
+`~/.ctxdb/oauth-credentials/`. `CTXDB_CONFIG_PATH` can select an isolated configuration file;
+the OAuth directory is its sibling. CLI, Hooks and OpenCode share a cross-process, single-flight
+refresh implementation. A lost refresh response or crashed refresh requires a new login, not
+a retry of the old RT. Managed failure/logout never falls back to an API key or another profile.
+Re-login replaces only the selected profile; logout reports remote-revoke failure separately.
+AT/RT must not be copied into Agent/Skill configuration or handed to a sandbox.
+
+The optional sibling `device-environments.json` (`version: 1`, `environments: [{core_url,
+authorization_url}]`) maps a Core origin to a deployment-approved HTTPS console page.
+CLI appends only `user_code` to that locally configured URL. There is no server discovery or
+invented default console page. Without a mapping, the code can be used with the independent POP
+test client. This phase never opens a browser automatically; `--no-browser` is supported.
+
+POSIX uses private files/directories; Windows validates an owner-only ACL using local PowerShell.
+Native Windows acceptance remains separate from the macOS local test record.
+
 ### Internal browser-login distribution
 
-The same source also builds `@ali/ctxdb-internal`. That artifact alone
+The same source also builds `@ali/ctxdb-internal`. Its existing prototype
 adds `ctxdb login --server <url>`, `ctxdb login --device-code`, `ctxdb logout`,
 and `ctxdb auth status`. The default login uses a browser loopback callback;
 `--device-code` supports remote or headless terminals. Both methods discover a
@@ -31,17 +64,19 @@ Internal login stores its single active connection in owner-only
 without writing an `api_key` field into the Agent or default profile; an
 existing field in either updated profile is removed. At runtime this managed
 credential overrides the API key and DATA URL in the existing v2
-`~/.ctxdb/ctxdb.json`; `CTXDB_API_KEY` and `CTXDB_BASE_URL` remain the highest
-priority overrides. Re-login replaces the active connection and revokes the
-previous key after setup succeeds. The public `@aliyunrds/ctxdb` build does not
-contain or advertise these commands and continues to use `ctxdb setup` and the
-v2 config exactly as before. Build the internal staging package with
-`pnpm build:internal`.
+`~/.ctxdb/ctxdb.json`; `CTXDB_ACCESS_TOKEN`, `CTXDB_API_KEY`, and
+`CTXDB_BASE_URL` remain higher-priority overrides. `ctxdb login` rejects all
+three while `ctxdb logout` rejects the two credential overrides, so command
+output cannot disagree with subsequent DATA requests. Re-login replaces the
+active connection and revokes the previous key after setup succeeds. The
+public `@aliyunrds/ctxdb` build uses the distinct Device Flow implementation above and
+continues to support API-key setup. It never reads the internal credential store. Build the
+internal staging package with `pnpm build:internal`.
 
 The distinction is a compile-time distribution manifest, not a runtime
 environment-variable or file-existence check. The `public` manifest disables
-`interactiveLogin` and `managedCredentials`; the `internal` manifest enables
-both. The CLI hooks and the separately bundled OpenCode plugin receive the
+internal-protocol flags `interactiveLogin` and `managedCredentials`, and enables `deviceFlow`;
+the `internal` manifest enables the former two and disables `deviceFlow`. The CLI hooks and the separately bundled OpenCode plugin receive the
 same manifest, so installing a public build on a machine that happens to have
 `~/.ctxdb/credentials.json` does not make that build consume the file.
 
@@ -603,7 +638,9 @@ Field reference:
 | `knowledge_top_k` | int | `6` | KB chunks pulled per recall (only effective when `recall_knowledge: true`) |
 | `debug` | bool | `false` | Configured preference for verbose hook logging and full recall tracing. Effective debug is forced on for every final `base_url` outside the exact official-production allowlist; see “Debug control and recall replay”. General logs go to `~/.ctxdb/logs/ctxdb.log`, structured full-content recall records to `~/.ctxdb/logs/recall-trace.jsonl` |
 
-Env-var overrides apply to the selected agent config (env wins): `CTXDB_AGENT` / `CTXDB_API_KEY` / `CTXDB_BASE_URL` / `CTXDB_USER_ID` / `CTXDB_AGENT_ID` / `CTXDB_APP_ID`. The internal login command additionally reads `CTXDB_LOGIN_SERVER` as its provider-neutral login endpoint. The last two default to unset — the request body omits `agent_id`/`app_id` entirely; set them only when you want per-agent / per-app scope isolation on the server.
+Env-var overrides apply to the selected agent config (env wins): `CTXDB_AGENT` / `CTXDB_ACCESS_TOKEN` / `CTXDB_API_KEY` / `CTXDB_BASE_URL` / `CTXDB_USER_ID` / `CTXDB_AGENT_ID` / `CTXDB_APP_ID`. The internal login command additionally reads `CTXDB_LOGIN_SERVER` as its provider-neutral login endpoint. The last two default to unset — the request body omits `agent_id`/`app_id` entirely; set them only when you want per-agent / per-app scope isolation on the server.
+
+Downstream Agent hosts can set `CTXDB_ACCESS_TOKEN` to send `Authorization: Bearer <token>` to the Data API. It is runtime-only, never written to `~/.ctxdb/ctxdb.json`, and takes precedence over a managed session or API key for CLI, process hooks, and OpenCode; a rejected token does not fall back to another credential. `ctxdb setup` can use a managed reference or an environment AT for validation, but never persists the AT. An environment-only credential must remain available to the Agent runtime after setup.
 
 Hook/plugin escape hatch: set `CTXDB_SKIP_HOOKS=TRUE` on the agent process to make all ctxdb hook entrypoints exit immediately before reading config or calling the API. Direct `ctxdb memory` / `ctxdb kb` / `ctxdb setup` CLI commands are unchanged.
 

package/dist/{chunk-X75B57M2.js → chunk-5DGRNP55.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   configDir
-} from "./chunk-DMS5YHIK.js";
+} from "./chunk-SVO6H62S.js";
 
 // src/lib/circuit.ts
 import { statSync, writeFileSync, unlinkSync, mkdirSync, readdirSync, readFileSync } from "fs";

package/dist/{chunk-R67JELM7.js → chunk-5ITT5GSP.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   define_CTXDB_DISTRIBUTION_MANIFEST_default
-} from "./chunk-VIG4SYLU.js";
+} from "./chunk-PI2SUS3M.js";
 
 // src/lib/distribution-capabilities.ts
 var PUBLIC_DISTRIBUTION = {
@@ -10,7 +10,8 @@ var PUBLIC_DISTRIBUTION = {
   packageRegistry: null,
   capabilities: {
     interactiveLogin: false,
-    managedCredentials: false
+    managedCredentials: false,
+    deviceFlow: true
   }
 };
 var DISTRIBUTION_MANIFEST = typeof define_CTXDB_DISTRIBUTION_MANIFEST_default === "undefined" ? PUBLIC_DISTRIBUTION : define_CTXDB_DISTRIBUTION_MANIFEST_default;

package/dist/{chunk-5ZSZMN2T.js → chunk-6MEWI73Y.js}

@@ -2,10 +2,10 @@
 import {
   fetchKbCatalogBlock,
   recallTurn
-} from "./chunk-H33NUAHP.js";
+} from "./chunk-WJTV7JNR.js";
 import {
   debug
-} from "./chunk-DMS5YHIK.js";
+} from "./chunk-SVO6H62S.js";
 
 // src/lib/warmup-recall.ts
 import { execSync } from "child_process";

package/dist/{chunk-LYHGJOHM.js → chunk-76AXXLVE.js}

@@ -4,12 +4,13 @@ import {
   isConnectionError,
   resetCircuit,
   tripCircuit
-} from "./chunk-X75B57M2.js";
+} from "./chunk-5DGRNP55.js";
 import {
   CtxdbError,
   debug,
+  isDataApiReady,
   isDebug
-} from "./chunk-DMS5YHIK.js";
+} from "./chunk-SVO6H62S.js";
 
 // src/lib/capture-orchestrator.ts
 import {
@@ -398,7 +399,7 @@ async function captureParsedMessages(parsed, cfg, client, agent = "default", ses
   };
 }
 function capturePreflight(cfg, agent) {
-  if (!cfg.apiKey || !cfg.baseUrl) {
+  if (!isDataApiReady(cfg)) {
     return { captured: false, reason: "config_incomplete", messageCount: 0 };
   }
   if (!cfg.autoCapture) {

package/dist/{chunk-4FCZ2TZM.js → chunk-O6MKQ2I3.js}

@@ -2,7 +2,7 @@
 import {
   fetchKbCatalogBlock,
   recallTurn
-} from "./chunk-H33NUAHP.js";
+} from "./chunk-WJTV7JNR.js";
 
 // src/lib/user-prompt-submit-compose.ts
 async function composeUserPromptSubmit(cfg, agent, client, prompt, sessionId = null) {

package/dist/{chunk-ULAWTBBC.js → chunk-OEZM2ZYA.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   DISTRIBUTION_MANIFEST
-} from "./chunk-R67JELM7.js";
+} from "./chunk-5ITT5GSP.js";
 
 // src/lib/self-update.ts
 import { spawnSync } from "child_process";

package/dist/{chunk-VIG4SYLU.js → chunk-PI2SUS3M.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // <define:__CTXDB_DISTRIBUTION_MANIFEST__>
-var define_CTXDB_DISTRIBUTION_MANIFEST_default = { id: "public", packageName: "@aliyunrds/ctxdb", packageRegistry: null, capabilities: { interactiveLogin: false, managedCredentials: false } };
+var define_CTXDB_DISTRIBUTION_MANIFEST_default = { id: "public", packageName: "@aliyunrds/ctxdb", packageRegistry: null, capabilities: { interactiveLogin: false, managedCredentials: false, deviceFlow: true } };
 
 export {
   define_CTXDB_DISTRIBUTION_MANIFEST_default

package/dist/{chunk-DMS5YHIK.js → chunk-SVO6H62S.js}

@@ -1,7 +1,22 @@
 #!/usr/bin/env node
 import {
   DISTRIBUTION_MANIFEST
-} from "./chunk-R67JELM7.js";
+} from "./chunk-5ITT5GSP.js";
+
+// src/lib/credentials.ts
+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 };
+  if (env.CTXDB_API_KEY) return apiKeyCredential(env.CTXDB_API_KEY);
+  if (cfg.oauthCredential) return { type: "oauth-session", profile: cfg.oauthCredential };
+  return cfg.apiKey ? apiKeyCredential(cfg.apiKey) : null;
+}
+function isDataApiReady(cfg, env = process.env) {
+  return Boolean(cfg.baseUrl && resolveDataApiCredential(cfg, env));
+}
 
 // src/lib/logger.ts
 import { appendFileSync, mkdirSync } from "fs";
@@ -69,6 +84,7 @@ var PACKAGE_NAME = PACKAGE_IDENTITY.name;
 var PACKAGE_VERSION = PACKAGE_IDENTITY.version;
 
 // src/lib/http-client.ts
+import { OAuthProfileProvider } from "@aliyunrds/ctxdb-shared";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var CtxdbError = class extends Error {
   constructor(message) {
@@ -82,7 +98,7 @@ var AuthError = class extends CtxdbError {
   errorMessage;
   data;
   responseBody;
-  constructor(message = "Unauthorized (HTTP 401) \u2014 check api_key", fields = {}) {
+  constructor(message = "Unauthorized (HTTP 401) \u2014 check Data API credential", fields = {}) {
     super(message);
     this.name = "AuthError";
     this.errorCode = fields.errorCode;
@@ -147,6 +163,7 @@ var CtxdbHttpError = class extends CtxdbError {
 };
 var HttpClient = class {
   baseUrl;
+  credential;
   apiKey;
   timeoutMs;
   userAgent;
@@ -154,12 +171,14 @@ var HttpClient = class {
   fetchImpl;
   authorizationProvider;
   constructor(opts) {
-    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
-    if (!opts.apiKey && !opts.authorizationProvider) {
-      throw new Error("HttpClient requires apiKey or authorizationProvider");
+    const credential = opts.credential ?? (opts.apiKey ? apiKeyCredential(opts.apiKey) : null);
+    if (!credential && !opts.authorizationProvider) {
+      throw new CtxdbError("DATA API credential is required");
     }
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.credential = credential;
     this.apiKey = opts.apiKey ?? "";
-    this.authorizationProvider = opts.authorizationProvider;
+    this.authorizationProvider = opts.authorizationProvider ?? (credential?.type === "oauth-session" ? new OAuthProfileProvider(credential.profile) : void 0);
     this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this.userAgent = opts.userAgent ?? `ctxdb-cli/${PACKAGE_VERSION}`;
     this.extraHeaders = { ...opts.extraHeaders ?? {} };
@@ -174,15 +193,30 @@ 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 authorization = this.authorizationProvider ? await this.authorizationProvider.resolve() : {
-      scheme: "Token",
-      value: this.apiKey,
-      baseUrl: this.baseUrl,
-      expiresAt: null
+    let authorization;
+    if (this.authorizationProvider) {
+      authorization = await this.authorizationProvider.resolve();
+    } else {
+      const credential = this.credential;
+      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,
+        baseUrl: this.baseUrl,
+        expiresAt: null
+      };
+    }
+    const safeText = (value) => {
+      const text = String(value);
+      return authorization.scheme === "Bearer" ? text.split(authorization.value).join("[REDACTED]") : text;
     };
     let url = `${authorization.baseUrl.replace(/\/+$/, "")}${path}`;
     if (init.params) {
@@ -213,15 +247,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)`);
@@ -229,14 +264,14 @@ var HttpClient = class {
       }
       let text;
       try {
-        text = await resp.text();
+        text = safeText(await resp.text());
       } 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}`);
@@ -801,10 +836,11 @@ function readActiveCredentialSync(path = defaultCredentialsPath()) {
 
 // src/lib/config.ts
 import {
-  resolveDebugPolicy
+  resolveDebugPolicy,
+  oauthProfile
 } from "@aliyunrds/ctxdb-shared";
-function defaultConfigPath() {
-  return join5(homedir4(), ".ctxdb", "ctxdb.json");
+function defaultConfigPath(env = process.env) {
+  return env.CTXDB_CONFIG_PATH || join5(homedir4(), ".ctxdb", "ctxdb.json");
 }
 var DEFAULT_CONFIG_PATH = join5(homedir4(), ".ctxdb", "ctxdb.json");
 function configDir() {
@@ -816,9 +852,6 @@ var DEFAULT_TOP_K = 5;
 var DEFAULT_THRESHOLD = 0.4;
 var DEFAULT_KNOWLEDGE_TOP_K = 6;
 var DEFAULT_KB_CATALOG_INJECTION = "session_start";
-function isComplete(cfg) {
-  return Boolean(cfg.apiKey && cfg.baseUrl);
-}
 function resolveConfigAgent(options = {}, preloadedRaw) {
   if (isAgentSlug(options.agent)) return options.agent;
   return agentFromEnv(options.env);
@@ -908,8 +941,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)) {
@@ -935,7 +968,7 @@ function load(options = {}) {
     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 !== "oauth_credential_ref" && !(k in agentRaw)) {
           agentRaw[k] = v;
         }
       }
@@ -949,11 +982,16 @@ function load(options = {}) {
     cfg.apiKey = managed.payload.apiKey;
     cfg.baseUrl = managed.payload.baseUrl;
   }
-  return applyEnv(cfg, env);
+  applyEnv(cfg, env);
+  if (DISTRIBUTION_MANIFEST.capabilities.deviceFlow) {
+    cfg.oauthCredential = oauthProfile(agentRaw.oauth_credential_ref, path, agent, cfg.baseUrl);
+  }
+  return cfg;
 }
 function configToDisk(cfg) {
   return {
-    api_key: cfg.apiKey,
+    ...cfg.oauthCredential ? { oauth_credential_ref: cfg.oauthCredential.reference } : {},
+    api_key: cfg.oauthCredential ? null : cfg.apiKey,
     base_url: cfg.baseUrl,
     user_id: cfg.userId,
     agent_id: cfg.agentId,
@@ -1061,6 +1099,8 @@ function writeInstalledPkgVersion(version, path) {
 }
 
 export {
+  resolveDataApiCredential,
+  isDataApiReady,
   setDebug,
   isDebug,
   debug,
@@ -1080,10 +1120,11 @@ export {
   detectInstalledAgents,
   agentFromEnv,
   agentFromArgvWithFallback,
+  secureAtomicWrite,
+  defaultConfigPath,
   configDir,
   DEFAULT_BASE_URL,
   DEFAULT_USER_ID,
-  isComplete,
   load,
   removeAgent,
   save,

package/dist/{chunk-H33NUAHP.js → chunk-WJTV7JNR.js}

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
 import {
   listKnowledgeBases
-} from "./chunk-CULTDVI2.js";
+} from "./chunk-ZW7YXNJ6.js";
 import {
   isConnectionError,
   resetCircuit,
   tripCircuit
-} from "./chunk-X75B57M2.js";
+} from "./chunk-5DGRNP55.js";
 import {
-  CtxdbError
-} from "./chunk-DMS5YHIK.js";
+  CtxdbError,
+  isDataApiReady,
+  resolveDataApiCredential
+} from "./chunk-SVO6H62S.js";
 
 // src/lib/kb-catalog.ts
 function sanitizeKeyEntities(raw) {
@@ -152,12 +154,13 @@ async function recallTurn(prompt, cfg, client, agentOrOptions = "default") {
   const options = typeof agentOrOptions === "string" ? { agent: agentOrOptions } : agentOrOptions;
   const agent = options.agent ?? "default";
   if (!prompt.trim()) return { ...EMPTY, reason: "empty_prompt" };
-  if (!cfg.apiKey || !cfg.baseUrl) {
+  if (!isDataApiReady(cfg)) {
     return { ...EMPTY, reason: "config_incomplete" };
   }
   if (!cfg.autoRecall) {
     return { ...EMPTY, reason: "auto_recall_disabled" };
   }
+  const credential = resolveDataApiCredential(cfg);
   const query = stripSystemReminders(prompt);
   const trace = cfg.debug ? {
     agent,
@@ -175,7 +178,11 @@ async function recallTurn(prompt, cfg, client, agentOrOptions = "default") {
     },
     store: {
       ...options.traceStore,
-      secrets: [...options.traceStore?.secrets ?? [], cfg.apiKey]
+      secrets: [
+        ...options.traceStore?.secrets ?? [],
+        cfg.apiKey,
+        credential.value
+      ]
     }
   } : null;
   if (trace) {

package/dist/{chunk-CULTDVI2.js → chunk-ZW7YXNJ6.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   CtxdbError
-} from "./chunk-DMS5YHIK.js";
+} from "./chunk-SVO6H62S.js";
 
 // src/lib/kb.ts
 import {