@aliyunrds/ctxdb 1.0.8-beta.3 → 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
@@ -36,14 +69,14 @@ credential overrides the API key and DATA URL in the existing v2
 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 does not contain or advertise these commands and
-continues to use `ctxdb setup` and the v2 config exactly as before. Build 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.
 
@@ -607,7 +640,7 @@ Field reference:
 
 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 an API key for CLI, process hooks, and the in-process OpenCode plugin; a rejected token does not fall back to the API key. `ctxdb setup` remains API-key-only and never persists or validates an access token.
+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-EI63DQX3.js → chunk-5DGRNP55.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   configDir
-} from "./chunk-BUK4SZC2.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-LZ2LOWZL.js → chunk-6MEWI73Y.js}

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

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

@@ -4,13 +4,13 @@ import {
   isConnectionError,
   resetCircuit,
   tripCircuit
-} from "./chunk-EI63DQX3.js";
+} from "./chunk-5DGRNP55.js";
 import {
   CtxdbError,
   debug,
   isDataApiReady,
   isDebug
-} from "./chunk-BUK4SZC2.js";
+} from "./chunk-SVO6H62S.js";
 
 // src/lib/capture-orchestrator.ts
 import {

package/dist/{chunk-AUBVVYQL.js → chunk-O6MKQ2I3.js}

@@ -2,7 +2,7 @@
 import {
   fetchKbCatalogBlock,
   recallTurn
-} from "./chunk-7OX6UVPB.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-BUK4SZC2.js → chunk-SVO6H62S.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   DISTRIBUTION_MANIFEST
-} from "./chunk-R67JELM7.js";
+} from "./chunk-5ITT5GSP.js";
 
 // src/lib/credentials.ts
 function apiKeyCredential(apiKey) {
@@ -10,6 +10,8 @@ function apiKeyCredential(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) {
@@ -82,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) {
@@ -175,7 +178,7 @@ var HttpClient = class {
     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 ?? {} };
@@ -190,6 +193,10 @@ 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;
   }
@@ -199,7 +206,7 @@ var HttpClient = class {
       authorization = await this.authorizationProvider.resolve();
     } 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 +214,10 @@ var HttpClient = class {
         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) {
       const qs = new URLSearchParams();
@@ -236,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)`);
@@ -252,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}`);
@@ -824,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() {
@@ -928,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)) {
@@ -955,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;
         }
       }
@@ -969,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,
@@ -1081,7 +1099,6 @@ function writeInstalledPkgVersion(version, path) {
 }
 
 export {
-  apiKeyCredential,
   resolveDataApiCredential,
   isDataApiReady,
   setDebug,
@@ -1103,6 +1120,8 @@ export {
   detectInstalledAgents,
   agentFromEnv,
   agentFromArgvWithFallback,
+  secureAtomicWrite,
+  defaultConfigPath,
   configDir,
   DEFAULT_BASE_URL,
   DEFAULT_USER_ID,

package/dist/{chunk-7OX6UVPB.js → chunk-WJTV7JNR.js}

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
 import {
   listKnowledgeBases
-} from "./chunk-3NJ37TEY.js";
+} from "./chunk-ZW7YXNJ6.js";
 import {
   isConnectionError,
   resetCircuit,
   tripCircuit
-} from "./chunk-EI63DQX3.js";
+} from "./chunk-5DGRNP55.js";
 import {
   CtxdbError,
   isDataApiReady,
   resolveDataApiCredential
-} from "./chunk-BUK4SZC2.js";
+} from "./chunk-SVO6H62S.js";
 
 // src/lib/kb-catalog.ts
 function sanitizeKeyEntities(raw) {

package/dist/{chunk-3NJ37TEY.js → chunk-ZW7YXNJ6.js}

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