@aliyunrds/ctxdb-shared 0.0.6 → 0.0.8-beta.0

package/README.md

@@ -6,7 +6,7 @@ Shared B-rule modules + memory/KB types for RDS ContextDatabase access layers.
 
 ctxdb-dev ships two access layers that both implement the same B-rules
 (B-0 wrapper strip / B-1 KB anti-injection preamble / B-2 KB content
-sanitize / B-3c KB-upload-turn skip) and the same memory/KB type system:
+sanitize / B-3c KB-create-or-update-turn skip) and the same memory/KB type system:
 
 - **`openclaw_memory_rds_ctxdb`** — OpenClaw plugin (Mem0-mode platform / OSS)
 - **`@aliyunrds/ctxdb-qoder`** — Qoder hooks + `rds-ctxdb` CLI
@@ -21,7 +21,7 @@ This package is the single source of truth.
 
 | Module | Purpose |
 |---|---|
-| `kb-detection.ts` | B-3c — detect KB-upload turns by scanning assistant tool_use blocks; short-circuits autoCapture |
+| `kb-detection.ts` | B-3c — detect KB create/update turns by scanning assistant tool_use blocks; short-circuits autoCapture |
 | `graph-context.ts` | Classify GraphRAG synthesis rows and normalize graph content, KB IDs, and citation semantics |
 | `external-knowledge.ts` | B-1 + B-2 — preamble + chunk sanitize; render graph synthesis and document evidence separately inside `<external-knowledge>` |
 | `filtering.ts` | B-0 — strip wrapper tags from messages before extraction; drop noise messages |

package/dist/index.d.ts

@@ -495,4 +495,147 @@ declare function sanitizeRecallFailureReason(reason: string, secrets?: Array<str
 declare function writeRecallTrace(record: RecallTraceRecord, options?: RecallTraceStoreOptions): boolean;
 declare function readRecallTraces(options?: ReadRecallTraceOptions): ReadRecallTraceResult;
 
-export { type AddOptions, type AddResult, type AddResultItem, type CategoryConfig, DOCUMENT_EVIDENCE_SECTION_TITLE, type DebugPolicy, type DebugReason, type DetectionResult, EXTERNAL_KNOWLEDGE_PREAMBLE_HEAD, type ExcludedRecallMemory, type ExternalContext, type ExternalContextChunk, GRAPH_CONTEXT_MAX_CHARS, GRAPH_CONTEXT_SECTION_TITLE, GRAPH_CONTEXT_SOURCE_LABEL, GRAPH_CONTEXT_TAG, GRAPH_CONTEXT_TRUNCATION_MARKER, GRAPH_CONTEXT_USAGE_NOTICE, type ListOptions, type Mem0Provider, type MemoryItem, type NormalizedGraphContext, OFFICIAL_PRODUCTION_BASE_URLS, type ParsedMessage, RECALLED_MEMORIES_SAFETY_NOTICE, RECALL_TRACE_AGENTS, RECALL_TRACE_FILENAME, RECALL_TRACE_MAX_BYTES, RECALL_TRACE_OUTCOMES, RECALL_TRACE_ROTATED_GENERATIONS, RECALL_TRACE_SCHEMA_VERSION, type ReadRecallTraceOptions, type ReadRecallTraceResult, type RecallFinishTraceInput, type RecallFinishTraceRecord, type RecallMemoryExclusionReason, type RecallMemorySelectionBase, type RecallResult, type RecallSelectionResult, type RecallStartTraceInput, type RecallStartTraceRecord, type RecallTraceAgent, type RecallTraceKind, type RecallTraceOutcome, type RecallTraceRecord, type RecallTraceRequest, type RecallTraceSelection, type RecallTraceStoreOptions, type SearchOptions, type SearchResultWithExternalContext, type SelectTurnOptions, type SelectedRecallMemory, type SkillsConfig, buildExternalKnowledgeBlock, buildExternalKnowledgePreamble, buildNormalizedGraphContext, createRecallFinishRecord, createRecallStartRecord, extractKnowledgeBaseIds, extractKnowledgeChunkContent, extractKnowledgeChunkSourceLabel, extractKnowledgeChunkTags, filterMessagesForExtraction, formatExternalKnowledgeChunks, formatRecalledMemoriesBlock, isGenericAssistantMessage, isGraphContextChunk, isKnowledgeBaseUploadTurn, isNoiseMessage, isOfficialProductionUrl, isSessionSpecificContent, normalizeBaseUrl, partitionKnowledgeChunks, readRecallTraces, recall, recallTracePath, resolveDebugPolicy, sanitizeChunkContent, sanitizeQuery, sanitizeRecallFailureReason, selectAndFormatRecalledMemories, selectTurnMessages, stripNoiseFromContent, truncateGraphContext, writeRecallTrace };
+type OAuthScope = "read_only" | "read_write" | "default";
+type OAuthLogin = {
+    baseUrl: string;
+    workspaceId: string;
+    memberId: string;
+    clientId: "ctxdb-cli";
+    scope: OAuthScope;
+    sessionId: string;
+    accountDisplay: string;
+    accessToken: string;
+    refreshToken: string;
+    /** Milliseconds; use the start of the successful token request, not response arrival, for the expiry bound. */
+    issuedAt: number;
+    expiresAt: number;
+};
+type Phase = "ready" | "refreshing" | "reauth_required";
+type OAuthRefreshResponse = {
+    access_token: string;
+    refresh_token: string;
+    token_type: string;
+    expires_in: number;
+    session_id: string;
+    scope: string;
+};
+type OAuthRefreshTransport = {
+    refresh(refreshToken: string, baseUrl: string): Promise<OAuthRefreshResponse>;
+};
+type OAuthRevokeTransport = {
+    revoke(refreshToken: string, baseUrl: string): Promise<void>;
+};
+type OAuthRequestAuthorization = {
+    scheme: "Bearer";
+    value: string;
+    baseUrl: string;
+    expiresAt: number;
+};
+declare class OAuthCredentialError extends Error {
+    readonly code: "login_required" | "credential_busy" | "invalid_profile" | "unsafe_storage";
+    constructor(code: OAuthCredentialError["code"]);
+}
+/** A reference identifies one login, not an agent or a mutable global credential slot.
+ * Profiles store only this reference. A new login gets a new reference, so it never steals a
+ * crashed refresher's lock or lets a late response overwrite the replacement login.
+ */
+declare class OAuthSessionStore {
+    private readonly directory;
+    private readonly now;
+    private readonly lockWaitMs;
+    constructor(directory: string, options?: {
+        now?: () => number;
+        lockWaitMs?: number;
+    });
+    saveLogin(profile: string, session: OAuthLogin): string;
+    status(ref: string, profile: string): {
+        state: "logged_out" | "missing";
+        profile?: undefined;
+        baseUrl?: undefined;
+        workspaceId?: undefined;
+        memberId?: undefined;
+        clientId?: undefined;
+        scope?: undefined;
+        sessionId?: undefined;
+        accountDisplay?: undefined;
+        accessExpiresAt?: undefined;
+    } | {
+        state: Phase;
+        profile: string;
+        baseUrl: string;
+        workspaceId: string;
+        memberId: string;
+        clientId: "ctxdb-cli";
+        scope: OAuthScope;
+        sessionId: string;
+        accountDisplay: string;
+        accessExpiresAt: number;
+    };
+    resolve(ref: string, profile: string, transport: OAuthRefreshTransport): Promise<OAuthRequestAuthorization>;
+    logout(ref: string, profile: string, transport: OAuthRevokeTransport): Promise<{
+        remoteRevoked: boolean;
+    }>;
+    private needsRefresh;
+    private path;
+    private isLoggedOut;
+    private prepareDirectory;
+    private read;
+    private write;
+    private atomicWrite;
+    private withLock;
+}
+
+type DevicePrompt = {
+    requestId: string;
+    userCode: string;
+    expiresIn: number;
+    interval: number;
+};
+type ErrorCode = "authorization_pending" | "slow_down" | "access_denied" | "expired_token" | "invalid_grant" | "invalid_response" | "network_error" | "cancelled" | "request_rejected" | "service_unavailable";
+declare class DeviceFlowError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode);
+}
+/** Strict Core origin; console routing/discovery does not belong to this client. */
+declare function normalizeCoreOrigin(value: string): string;
+/** JSON + Box adaptation. Never follows redirects, emits raw response errors, or retries a Token request. */
+declare class CoreDeviceClient {
+    readonly baseUrl: string;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly sleep;
+    constructor(baseUrl: string, options?: {
+        fetchImpl?: typeof fetch;
+        now?: () => number;
+        sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    });
+    login(options: {
+        onPrompt: (prompt: DevicePrompt) => void;
+        signal?: AbortSignal;
+    }): Promise<OAuthLogin>;
+    refresh(refreshToken: string, baseUrl: string): Promise<OAuthRefreshResponse>;
+    revoke(refreshToken: string, baseUrl: string): Promise<void>;
+    private requireSameOrigin;
+    private post;
+}
+
+/** Safe config metadata, never AT/RT. References are explicit per profile and are not inherited. */
+type OAuthProfile = {
+    reference: string;
+    profile: string;
+    configPath: string;
+    directory: string;
+    baseUrl: string;
+};
+declare function oauthProfile(reference: unknown, configPath: string, profile: string, baseUrl: string): OAuthProfile | undefined;
+/** Shared by CLI, out-of-process hooks and the in-process OpenCode runtime.
+ * Re-read the selected reference so a long-lived runtime sees a new login. An endpoint
+ * change requires reloading the runtime; no credential is sent to the replacement host.
+ */
+declare class OAuthProfileProvider {
+    private readonly selected;
+    constructor(selected: OAuthProfile);
+    resolve(): Promise<OAuthRequestAuthorization>;
+}
+
+export { type AddOptions, type AddResult, type AddResultItem, type CategoryConfig, CoreDeviceClient, DOCUMENT_EVIDENCE_SECTION_TITLE, type DebugPolicy, type DebugReason, type DetectionResult, DeviceFlowError, type DevicePrompt, EXTERNAL_KNOWLEDGE_PREAMBLE_HEAD, type ExcludedRecallMemory, type ExternalContext, type ExternalContextChunk, GRAPH_CONTEXT_MAX_CHARS, GRAPH_CONTEXT_SECTION_TITLE, GRAPH_CONTEXT_SOURCE_LABEL, GRAPH_CONTEXT_TAG, GRAPH_CONTEXT_TRUNCATION_MARKER, GRAPH_CONTEXT_USAGE_NOTICE, type ListOptions, type Mem0Provider, type MemoryItem, type NormalizedGraphContext, OAuthCredentialError, type OAuthLogin, type OAuthProfile, OAuthProfileProvider, type OAuthRequestAuthorization, type OAuthScope, OAuthSessionStore, OFFICIAL_PRODUCTION_BASE_URLS, type ParsedMessage, RECALLED_MEMORIES_SAFETY_NOTICE, RECALL_TRACE_AGENTS, RECALL_TRACE_FILENAME, RECALL_TRACE_MAX_BYTES, RECALL_TRACE_OUTCOMES, RECALL_TRACE_ROTATED_GENERATIONS, RECALL_TRACE_SCHEMA_VERSION, type ReadRecallTraceOptions, type ReadRecallTraceResult, type RecallFinishTraceInput, type RecallFinishTraceRecord, type RecallMemoryExclusionReason, type RecallMemorySelectionBase, type RecallResult, type RecallSelectionResult, type RecallStartTraceInput, type RecallStartTraceRecord, type RecallTraceAgent, type RecallTraceKind, type RecallTraceOutcome, type RecallTraceRecord, type RecallTraceRequest, type RecallTraceSelection, type RecallTraceStoreOptions, type SearchOptions, type SearchResultWithExternalContext, type SelectTurnOptions, type SelectedRecallMemory, type SkillsConfig, buildExternalKnowledgeBlock, buildExternalKnowledgePreamble, buildNormalizedGraphContext, createRecallFinishRecord, createRecallStartRecord, extractKnowledgeBaseIds, extractKnowledgeChunkContent, extractKnowledgeChunkSourceLabel, extractKnowledgeChunkTags, filterMessagesForExtraction, formatExternalKnowledgeChunks, formatRecalledMemoriesBlock, isGenericAssistantMessage, isGraphContextChunk, isKnowledgeBaseUploadTurn, isNoiseMessage, isOfficialProductionUrl, isSessionSpecificContent, normalizeBaseUrl, normalizeCoreOrigin, oauthProfile, partitionKnowledgeChunks, readRecallTraces, recall, recallTracePath, resolveDebugPolicy, sanitizeChunkContent, sanitizeQuery, sanitizeRecallFailureReason, selectAndFormatRecalledMemories, selectTurnMessages, stripNoiseFromContent, truncateGraphContext, writeRecallTrace };

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/kb-detection.ts
 var KB_PATH_FRAGMENT = "/v1/knowledge/";
 var SHELL_TOOL_NAMES = /* @__PURE__ */ new Set(["exec", "bash", "shell", "sh"]);
-var CTXDB_QODER_KB_UPLOAD_RE = /\b(?:(?:rds|qoder)[-_]ctxdb|ctxdb[-_]qoder|ctxdb)\s+kb\s+upload[-_](?:text|file)\b/i;
+var CTXDB_QODER_KB_UPLOAD_RE = /\b(?:(?:rds|qoder)[-_]ctxdb|ctxdb[-_]qoder|ctxdb)\s+kb\s+(?:upload|update)[-_](?:text|file)\b/i;
 var KB_PLUGIN_TOOL_NAMES = /* @__PURE__ */ new Set(["kb_upload_text", "kb_upload_file"]);
 var WRITE_METHOD_RE = /-X\s+(?:POST|PUT|DELETE|PATCH)\b/i;
 var MULTIPART_UPLOAD_RE = /-F\s+["']?(?:file|content)=@/i;
@@ -32,7 +32,7 @@ function isKnowledgeBaseUploadTurn(messages) {
       if (CTXDB_QODER_KB_UPLOAD_RE.test(command)) {
         return {
           detected: true,
-          reason: `shell tool "${name}" invoked a ctxdb-qoder CLI kb upload command (direct KB upload via CLI)`
+          reason: `shell tool "${name}" invoked a ctxdb CLI KB upload/update command (direct KB write via CLI)`
         };
       }
       if (!command.includes(KB_PATH_FRAGMENT)) continue;
@@ -483,8 +483,8 @@ function getMemoryImportance(memory) {
   };
   return defaults[cat] ?? 0.5;
 }
-function estimateTokens(text) {
-  return Math.ceil(text.length / CHARS_PER_TOKEN);
+function estimateTokens(text2) {
+  return Math.ceil(text2.length / CHARS_PER_TOKEN);
 }
 function rankMemories(memories, categoryOrder) {
   const orderMap = new Map(categoryOrder.map((cat, i) => [cat, i]));
@@ -809,9 +809,9 @@ function sanitizeRecallFailureReason(reason, secrets = []) {
 }
 function sanitizeTraceString(value, secrets) {
   let sanitized = value.replace(/authorization\s*[:=]\s*[^\r\n]*/gi, "Authorization: [REDACTED]").replace(/(api[_-]?key|access[_-]?token)\s*[:=]\s*[^\s,;]+/gi, "$1=[REDACTED]");
-  for (const secret of secrets) {
-    if (!secret) continue;
-    sanitized = sanitized.split(secret).join("[REDACTED]");
+  for (const secret2 of secrets) {
+    if (!secret2) continue;
+    sanitized = sanitized.split(secret2).join("[REDACTED]");
   }
   return sanitized;
 }
@@ -946,6 +946,7 @@ function isRecallTraceRecord(value) {
   const baseValid = record.schema_version === RECALL_TRACE_SCHEMA_VERSION && (record.type === "recall.start" || record.type === "recall.finish") && isIsoTimestamp(record.timestamp) && typeof record.recall_event_id === "string" && record.recall_event_id.length > 0 && (typeof record.session_id === "string" || record.session_id === null) && isRecallTraceAgent(record.agent) && (record.kind === "prompt" || record.kind === "warmup") && typeof record.query === "string" && isRecallTraceRequest(record.request);
   if (!baseValid) return false;
   if (record.type === "recall.start") return true;
+  if (record.type !== "recall.finish") return false;
   const selection = record.selection;
   return isNonNegativeFinite(record.duration_ms) && typeof record.outcome === "string" && TRACE_OUTCOMES.has(record.outcome) && (typeof record.failure_reason === "string" || record.failure_reason === null) && Array.isArray(record.returned_memories) && Array.isArray(record.returned_knowledge) && Boolean(selection) && Array.isArray(selection?.selected) && Array.isArray(selection?.excluded) && isNonNegativeFinite(selection?.token_estimate) && typeof record.recall_context === "string";
 }
@@ -993,8 +994,567 @@ function readRecallTraces(options = {}) {
   });
   return { records: records.map(({ record }) => record), malformedLines };
 }
+
+// src/device-flow.ts
+import { setTimeout as delay } from "timers/promises";
+var DeviceFlowError = class extends Error {
+  code;
+  constructor(code) {
+    super(code === "service_unavailable" ? "ContextDB authentication service is unavailable. No automatic retry was performed; start a new login later if authorization could not be completed." : `ContextDB device authorization: ${code}. Start a new login if authorization could not be completed.`);
+    this.name = "DeviceFlowError";
+    this.code = code;
+  }
+};
+var invalid = () => new DeviceFlowError("invalid_response");
+var scopes = ["read_only", "read_write", "default"];
+var clientId = "ctxdb-cli";
+var grantType = "urn:ietf:params:oauth:grant-type:device_code";
+function normalizeCoreOrigin(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Invalid Core server origin");
+  }
+  const local = ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname);
+  if (url.username || url.password || url.search || url.hash || url.pathname !== "/" || !(url.protocol === "https:" || local && url.protocol === "http:")) throw new Error("Invalid Core server origin");
+  return url.origin;
+}
+var CoreDeviceClient = class {
+  baseUrl;
+  fetchImpl;
+  now;
+  sleep;
+  constructor(baseUrl, options = {}) {
+    this.baseUrl = normalizeCoreOrigin(baseUrl);
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    this.now = options.now ?? Date.now;
+    this.sleep = options.sleep ?? ((ms, signal) => delay(ms, void 0, { signal }));
+  }
+  async login(options) {
+    const started = this.now();
+    const initial = await this.post("/v1/auth/device/authorize", { client_id: clientId }, options.signal);
+    if (!initial.ok) throw new DeviceFlowError("request_rejected");
+    const data = initial.data;
+    const requestId = text(data.request_id, 32), userCode = text(data.user_code, 9), code = text(data.device_code, 43);
+    if (!/^[0-9a-f]{32}$/.test(requestId) || !/^[0-9A-HJKMNP-TV-Z]{4}-[0-9A-HJKMNP-TV-Z]{4}$/.test(userCode) || !/^[A-Za-z0-9_-]{43}$/.test(code)) throw invalid();
+    const expiresIn = integer(data.expires_in, 1, 3600);
+    let interval = integer(data.interval, 1, 3600);
+    const deadline = started + expiresIn * 1e3;
+    options.onPrompt({ requestId, userCode, expiresIn, interval });
+    while (true) {
+      if (options.signal?.aborted) throw new DeviceFlowError("cancelled");
+      if (this.now() >= deadline) throw new DeviceFlowError("expired_token");
+      try {
+        await this.sleep(Math.min(interval * 1e3, deadline - this.now()), options.signal);
+      } catch {
+        throw new DeviceFlowError("cancelled");
+      }
+      if (this.now() >= deadline) throw new DeviceFlowError("expired_token");
+      const issuedAt = this.now();
+      const result = await this.post("/v1/auth/device/token", { grant_type: grantType, client_id: clientId, device_code: code }, options.signal);
+      if (result.ok) return loginResult(result.data, this.baseUrl, issuedAt, this.now());
+      const error = result.data.error;
+      if (error === "authorization_pending") continue;
+      if (error === "slow_down") {
+        interval = Math.max(interval + 5, integer(result.data.interval, 1, 3605));
+        continue;
+      }
+      if (error === "access_denied" || error === "expired_token" || error === "invalid_grant") throw new DeviceFlowError(error);
+      throw new DeviceFlowError("request_rejected");
+    }
+  }
+  async refresh(refreshToken, baseUrl) {
+    this.requireSameOrigin(baseUrl);
+    const result = await this.post("/v1/auth/token/refresh", { refresh_token: secret(refreshToken) });
+    if (!result.ok) throw new DeviceFlowError("request_rejected");
+    return credentialResult(result.data);
+  }
+  async revoke(refreshToken, baseUrl) {
+    this.requireSameOrigin(baseUrl);
+    const result = await this.post("/v1/auth/token/revoke", { refresh_token: secret(refreshToken) });
+    if (!result.ok) throw new DeviceFlowError("request_rejected");
+  }
+  requireSameOrigin(baseUrl) {
+    if (normalizeCoreOrigin(baseUrl) !== this.baseUrl) throw new Error("OAuth credential Core origin cannot change");
+  }
+  async post(path, body, signal) {
+    if (signal?.aborted) throw new DeviceFlowError("cancelled");
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(abort, 3e4);
+    timer.unref?.();
+    try {
+      const response = await this.fetchImpl(this.baseUrl + path, {
+        method: "POST",
+        body: JSON.stringify(body),
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        redirect: "error",
+        credentials: "omit",
+        cache: "no-store",
+        signal: controller.signal
+      });
+      const box = await boundedJson(response);
+      if (!Number.isInteger(box.errorCode)) throw invalid();
+      const ok = response.ok && box.errorCode === 0;
+      const data = (!ok || path === "/v1/auth/token/revoke") && box.data == null ? {} : object(box.data);
+      if (!ok && response.status >= 500) throw new DeviceFlowError("service_unavailable");
+      return { ok, data };
+    } catch (error) {
+      if (signal?.aborted) throw new DeviceFlowError("cancelled");
+      if (error instanceof DeviceFlowError) throw error;
+      throw new DeviceFlowError("network_error");
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+    }
+  }
+};
+function text(value, maximum) {
+  if (typeof value !== "string" || !value || value.length > maximum || /[\x00-\x1f\x7f]/.test(value)) throw invalid();
+  return value;
+}
+function integer(value, min, max) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw invalid();
+  return value;
+}
+function secret(value) {
+  const token = text(value, 8192);
+  if (/\s/.test(token)) throw invalid();
+  return token;
+}
+function object(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw invalid();
+  return value;
+}
+function credentialResult(data) {
+  if (data.token_type !== "Bearer" || !scopes.includes(data.scope)) throw invalid();
+  return {
+    access_token: secret(data.access_token),
+    refresh_token: secret(data.refresh_token),
+    token_type: "Bearer",
+    expires_in: integer(data.expires_in, 1, 3600),
+    session_id: text(data.session_id, 64),
+    scope: data.scope
+  };
+}
+function loginResult(data, baseUrl, issuedAt, now) {
+  const tokens = credentialResult(data), scope = tokens.scope;
+  if (data.client_id !== clientId || scope !== "default") throw invalid();
+  const expiresAt = issuedAt + tokens.expires_in * 1e3;
+  if (expiresAt <= now) throw invalid();
+  return {
+    baseUrl,
+    workspaceId: text(data.workspace_id, 64),
+    memberId: text(data.member_id, 64),
+    scope,
+    clientId,
+    sessionId: tokens.session_id,
+    accountDisplay: text(data.account_display, 256),
+    issuedAt,
+    expiresAt,
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token
+  };
+}
+async function boundedJson(response) {
+  if (!response.body || Number(response.headers.get("content-length")) > 65536) throw invalid();
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > 65536) {
+        await reader.cancel();
+        throw invalid();
+      }
+      chunks.push(value);
+    }
+    try {
+      return object(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+    } catch {
+      throw invalid();
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/oauth-credentials.ts
+import {
+  constants,
+  closeSync as closeSync2,
+  existsSync as existsSync2,
+  fstatSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync as mkdirSync2,
+  openSync as openSync2,
+  readFileSync as readFileSync2,
+  renameSync as renameSync2,
+  unlinkSync,
+  writeFileSync
+} from "fs";
+import { randomBytes } from "crypto";
+import { join as join3 } from "path";
+import { setTimeout as delay2 } from "timers/promises";
+
+// src/windows-private-storage.ts
+import { execFileSync } from "child_process";
+import { join as join2 } from "path";
+var SCRIPT = `
+$ErrorActionPreference = 'Stop'
+$path = $env:CTXDB_PRIVATE_STORAGE_PATH
+$sid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+$item = Get-Item -LiteralPath $path -Force
+if (($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0) { throw 'reparse' }
+if ($env:CTXDB_PRIVATE_STORAGE_INITIALIZE -eq '1') {
+  if (-not $item.PSIsContainer) { throw 'not directory' }
+  $acl = [System.Security.AccessControl.DirectorySecurity]::new()
+  $acl.SetOwner($sid)
+  $acl.SetAccessRuleProtection($true, $false)
+  $rule = [System.Security.AccessControl.FileSystemAccessRule]::new($sid, 'FullControl', 'ContainerInherit,ObjectInherit', 'None', 'Allow')
+  $acl.AddAccessRule($rule)
+  Set-Acl -LiteralPath $path -AclObject $acl
+}
+$acl = Get-Acl -LiteralPath $path
+if ($acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $sid.Value) { throw 'owner' }
+$self = $false
+foreach ($rule in $acl.GetAccessRules($true, $true, [System.Security.Principal.SecurityIdentifier])) {
+  if ($rule.AccessControlType -eq 'Allow') {
+    if ($rule.IdentityReference.Value -ne $sid.Value) { throw 'other principal' }
+    if (($rule.FileSystemRights -band [System.Security.AccessControl.FileSystemRights]::FullControl) -eq [System.Security.AccessControl.FileSystemRights]::FullControl) { $self = $true }
+  }
+}
+if (-not $self) { throw 'missing owner access' }
+Write-Output 'private'
+`;
+function checkWindowsPrivateStorage(path, initialize, run = execFileSync) {
+  const systemRoot = process.env.SystemRoot;
+  if (!systemRoot) throw new Error("Private Windows credential storage could not be verified.");
+  try {
+    const result = run(
+      join2(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"),
+      ["-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(SCRIPT, "utf16le").toString("base64")],
+      {
+        env: { ...process.env, CTXDB_PRIVATE_STORAGE_PATH: path, CTXDB_PRIVATE_STORAGE_INITIALIZE: initialize ? "1" : "0" },
+        encoding: "utf8",
+        windowsHide: true,
+        timeout: 1e4,
+        maxBuffer: 4096,
+        stdio: ["ignore", "pipe", "pipe"]
+      }
+    );
+    if (String(result).trim() !== "private") throw new Error();
+  } catch {
+    throw new Error("Private Windows credential storage could not be verified.");
+  }
+}
+
+// src/oauth-credentials.ts
+var OAuthCredentialError = class extends Error {
+  code;
+  constructor(code) {
+    const messages = {
+      login_required: "OAuth session needs login; run ctxdb login for this profile.",
+      credential_busy: "OAuth credential is busy. If its previous process crashed, run ctxdb login for a new credential.",
+      invalid_profile: "OAuth credential does not belong to this profile.",
+      unsafe_storage: "OAuth credential storage is not private or is invalid."
+    };
+    super(messages[code]);
+    this.name = "OAuthCredentialError";
+    this.code = code;
+  }
+};
+var loginRequired = () => new OAuthCredentialError("login_required");
+var unsafe = () => new OAuthCredentialError("unsafe_storage");
+var OAuthSessionStore = class {
+  directory;
+  now;
+  lockWaitMs;
+  constructor(directory, options = {}) {
+    this.directory = directory;
+    this.now = options.now ?? Date.now;
+    this.lockWaitMs = options.lockWaitMs ?? 3e4;
+  }
+  saveLogin(profile, session) {
+    requireProfile(profile);
+    validateSession(session);
+    this.prepareDirectory();
+    const ref = randomBytes(16).toString("hex");
+    this.write(ref, { version: 1, profile, state: "ready", session });
+    return ref;
+  }
+  status(ref, profile) {
+    const record = this.read(ref, profile);
+    if (!record) return { state: this.isLoggedOut(ref) ? "logged_out" : "missing" };
+    const s = record.session;
+    return {
+      state: record.state,
+      profile,
+      baseUrl: s.baseUrl,
+      workspaceId: s.workspaceId,
+      memberId: s.memberId,
+      clientId: s.clientId,
+      scope: s.scope,
+      sessionId: s.sessionId,
+      accountDisplay: s.accountDisplay,
+      accessExpiresAt: s.expiresAt
+    };
+  }
+  async resolve(ref, profile, transport) {
+    const first = this.read(ref, profile);
+    if (!first || first.state === "reauth_required") throw loginRequired();
+    if (first.state === "ready" && !this.needsRefresh(first.session)) return authorization(first.session);
+    return this.withLock(ref, async () => {
+      const current = this.read(ref, profile);
+      if (!current || current.state !== "ready") throw loginRequired();
+      if (!this.needsRefresh(current.session)) return authorization(current.session);
+      const started = this.now();
+      this.write(ref, { ...current, state: "refreshing" });
+      try {
+        const response = await transport.refresh(current.session.refreshToken, current.session.baseUrl);
+        const next = rotated(current.session, response, started);
+        if (next.expiresAt <= this.now()) throw loginRequired();
+        this.write(ref, { ...current, state: "ready", session: next });
+        return authorization(next);
+      } catch {
+        if (!this.isLoggedOut(ref)) this.write(ref, { ...current, state: "reauth_required" });
+        throw loginRequired();
+      }
+    });
+  }
+  async logout(ref, profile, transport) {
+    const current = this.read(ref, profile);
+    let remoteRevoked = false;
+    try {
+      if (current) {
+        await transport.revoke(current.session.refreshToken, current.session.baseUrl);
+        remoteRevoked = true;
+      }
+    } catch {
+    } finally {
+      this.prepareDirectory();
+      this.atomicWrite(this.path(ref, ".logged-out"), "");
+      remove(this.path(ref));
+    }
+    return { remoteRevoked };
+  }
+  needsRefresh(session) {
+    const advance = Math.min(3e4, (session.expiresAt - session.issuedAt) / 2);
+    return this.now() >= session.expiresAt - advance;
+  }
+  path(ref, suffix = ".json") {
+    if (!/^[a-f0-9]{32}$/.test(ref)) throw unsafe();
+    return join3(this.directory, ref + suffix);
+  }
+  isLoggedOut(ref) {
+    return existsSync2(this.path(ref, ".logged-out"));
+  }
+  prepareDirectory() {
+    if (!existsSync2(this.directory)) {
+      mkdirSync2(join3(this.directory, ".."), { recursive: true, mode: 448 });
+      try {
+        mkdirSync2(this.directory, { mode: 448 });
+        if (process.platform === "win32") checkWindowsPrivateStorage(this.directory, true);
+      } catch (error) {
+        if (error.code !== "EEXIST") throw unsafe();
+      }
+    }
+    requirePrivate(this.directory, true);
+  }
+  read(ref, profile) {
+    requireProfile(profile);
+    if (this.isLoggedOut(ref)) return void 0;
+    const path = this.path(ref);
+    if (!existsSync2(path)) return void 0;
+    requirePrivate(this.directory, true);
+    requirePrivate(path, false);
+    const fd = openSync2(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    let text2;
+    try {
+      const stat = fstatSync(fd);
+      if (stat.size > 65536 || !stat.isFile()) throw unsafe();
+      text2 = readFileSync2(fd, "utf8");
+    } finally {
+      closeSync2(fd);
+    }
+    let doc;
+    try {
+      doc = JSON.parse(text2);
+    } catch {
+      throw unsafe();
+    }
+    if (!doc || doc.version !== 1 || !["ready", "refreshing", "reauth_required"].includes(doc.state)) throw unsafe();
+    if (doc.profile !== profile) throw new OAuthCredentialError("invalid_profile");
+    validateSession(doc.session);
+    return this.isLoggedOut(ref) ? void 0 : doc;
+  }
+  write(ref, doc) {
+    if (this.isLoggedOut(ref)) throw loginRequired();
+    this.atomicWrite(this.path(ref), JSON.stringify(doc));
+    if (this.isLoggedOut(ref)) {
+      remove(this.path(ref));
+      throw loginRequired();
+    }
+  }
+  atomicWrite(path, text2) {
+    this.prepareDirectory();
+    const temporary = path + "." + randomBytes(12).toString("hex") + ".tmp";
+    let fd;
+    try {
+      fd = openSync2(temporary, "wx", 384);
+      writeFileSync(fd, text2);
+      fsyncSync(fd);
+      closeSync2(fd);
+      fd = void 0;
+      renameSync2(temporary, path);
+      if (process.platform !== "win32") {
+        const dir = openSync2(this.directory, "r");
+        try {
+          fsyncSync(dir);
+        } finally {
+          closeSync2(dir);
+        }
+      }
+    } finally {
+      if (fd !== void 0) closeSync2(fd);
+      remove(temporary);
+    }
+  }
+  async withLock(ref, task) {
+    const path = this.path(ref, ".lock");
+    const deadline = Date.now() + this.lockWaitMs;
+    this.prepareDirectory();
+    while (true) {
+      let fd;
+      try {
+        fd = openSync2(path, "wx", 384);
+      } catch (error) {
+        if (error.code !== "EEXIST") throw unsafe();
+        if (Date.now() >= deadline) throw new OAuthCredentialError("credential_busy");
+        await delay2(25);
+        continue;
+      }
+      try {
+        writeFileSync(fd, String(process.pid));
+        fsyncSync(fd);
+      } catch {
+        closeSync2(fd);
+        remove(path);
+        throw unsafe();
+      }
+      closeSync2(fd);
+      try {
+        return await task();
+      } finally {
+        remove(path);
+      }
+    }
+  }
+};
+function requireProfile(profile) {
+  if (typeof profile !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(profile)) throw new OAuthCredentialError("invalid_profile");
+}
+function requirePrivate(path, directory) {
+  const s = lstatSync(path);
+  if (s.isSymbolicLink() || (directory ? !s.isDirectory() : !s.isFile())) throw unsafe();
+  if (process.platform === "win32") {
+    try {
+      checkWindowsPrivateStorage(path, false);
+    } catch {
+      throw unsafe();
+    }
+    return;
+  }
+  if ((s.mode & 63) !== 0 || process.getuid && s.uid !== process.getuid()) throw unsafe();
+}
+function remove(path) {
+  try {
+    unlinkSync(path);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw unsafe();
+  }
+}
+function validateSession(s) {
+  if (!s || typeof s !== "object" || s.clientId !== "ctxdb-cli" || !["read_only", "read_write", "default"].includes(s.scope) || !Number.isSafeInteger(s.issuedAt) || !Number.isSafeInteger(s.expiresAt) || s.expiresAt - s.issuedAt < 1e3 || s.expiresAt - s.issuedAt > 36e5) throw unsafe();
+  for (const value of [s.workspaceId, s.memberId, s.sessionId, s.accountDisplay]) {
+    if (typeof value !== "string" || !value || value.length > 256 || /[\r\n\x00-\x1f]/.test(value)) throw unsafe();
+  }
+  for (const value of [s.accessToken, s.refreshToken]) {
+    if (typeof value !== "string" || !value || value.length > 8192 || /\s/.test(value)) throw unsafe();
+  }
+  let url;
+  try {
+    url = new URL(s.baseUrl);
+  } catch {
+    throw unsafe();
+  }
+  const loopback = ["127.0.0.1", "[::1]", "localhost"].includes(url.hostname);
+  if (url.username || url.password || url.search || url.hash || url.pathname !== "/" || !(url.protocol === "https:" || loopback && url.protocol === "http:")) throw unsafe();
+}
+function rotated(current, response, issuedAt) {
+  if (!response || response.token_type !== "Bearer" || response.session_id !== current.sessionId || response.scope !== current.scope || !Number.isSafeInteger(response.expires_in) || response.expires_in < 1 || response.expires_in > 3600 || response.refresh_token === current.refreshToken) throw loginRequired();
+  const next = {
+    ...current,
+    accessToken: response.access_token,
+    refreshToken: response.refresh_token,
+    issuedAt,
+    expiresAt: issuedAt + response.expires_in * 1e3
+  };
+  validateSession(next);
+  return next;
+}
+function authorization(session) {
+  return { scheme: "Bearer", value: session.accessToken, baseUrl: session.baseUrl, expiresAt: session.expiresAt };
+}
+
+// src/oauth-profile.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { dirname as dirname2, join as join4, resolve } from "path";
+function oauthProfile(reference, configPath, profile, baseUrl) {
+  if (reference === void 0) return void 0;
+  if (typeof reference !== "string" || !/^[a-f0-9]{32}$/.test(reference) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(profile)) throw new OAuthCredentialError("unsafe_storage");
+  const path = resolve(configPath);
+  return {
+    reference,
+    profile,
+    configPath: path,
+    directory: join4(dirname2(path), "oauth-credentials"),
+    baseUrl: normalizeCoreOrigin(baseUrl)
+  };
+}
+var OAuthProfileProvider = class {
+  selected;
+  constructor(selected) {
+    this.selected = selected;
+  }
+  async resolve() {
+    const selected = this.selected;
+    let raw;
+    try {
+      raw = JSON.parse(readFileSync3(selected.configPath, "utf8"));
+    } catch {
+      throw new OAuthCredentialError("login_required");
+    }
+    const profile = raw?.version === 2 ? raw.agents?.[selected.profile] : void 0;
+    if (!profile || !Object.hasOwn(profile, "oauth_credential_ref")) throw new OAuthCredentialError("login_required");
+    const current = oauthProfile(profile.oauth_credential_ref, selected.configPath, selected.profile, profile.base_url);
+    if (!current || current.baseUrl !== selected.baseUrl) throw new OAuthCredentialError("login_required");
+    const store = new OAuthSessionStore(current.directory);
+    const status = store.status(current.reference, current.profile);
+    if (!("baseUrl" in status) || typeof status.baseUrl !== "string" || normalizeCoreOrigin(status.baseUrl) !== current.baseUrl) throw new OAuthCredentialError("login_required");
+    return store.resolve(current.reference, current.profile, new CoreDeviceClient(current.baseUrl));
+  }
+};
 export {
+  CoreDeviceClient,
   DOCUMENT_EVIDENCE_SECTION_TITLE,
+  DeviceFlowError,
   EXTERNAL_KNOWLEDGE_PREAMBLE_HEAD,
   GRAPH_CONTEXT_MAX_CHARS,
   GRAPH_CONTEXT_SECTION_TITLE,
@@ -1002,6 +1562,9 @@ export {
   GRAPH_CONTEXT_TAG,
   GRAPH_CONTEXT_TRUNCATION_MARKER,
   GRAPH_CONTEXT_USAGE_NOTICE,
+  OAuthCredentialError,
+  OAuthProfileProvider,
+  OAuthSessionStore,
   OFFICIAL_PRODUCTION_BASE_URLS,
   RECALLED_MEMORIES_SAFETY_NOTICE,
   RECALL_TRACE_AGENTS,
@@ -1029,6 +1592,8 @@ export {
   isOfficialProductionUrl,
   isSessionSpecificContent,
   normalizeBaseUrl,
+  normalizeCoreOrigin,
+  oauthProfile,
   partitionKnowledgeChunks,
   readRecallTraces,
   recall,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliyunrds/ctxdb-shared",
-  "version": "0.0.6",
+  "version": "0.0.8-beta.0",
   "type": "module",
   "description": "Shared B-rule modules + memory/KB types for RDS ContextDatabase access layers (OpenClaw fork + Qoder hooks).",
   "license": "Apache-2.0",