@aliyunrds/ctxdb-shared 0.0.7 → 0.0.8

package/README.md

@@ -64,3 +64,18 @@ pnpm install
 pnpm test    # → vitest unit tests
 pnpm build   # → dist/index.{js,d.ts}
 ```
+
+## Public CLI authentication
+
+`selectDataApiCredential` preserves environment AT/API-Key priority. `DataApiAuthorizationProvider`
+rereads the persistent Agent choice before requests and delegates Device refresh to
+`OAuthProfileProvider` / `OAuthSessionStore`. Legacy profile references retain their profile
+check; shared references require the explicit Agent → login ID → credential relationship.
+
+`login-bindings.ts` owns shared registration, switching, unbind and optimistic login commits.
+`auth-config.ts` supplies short config-lock transactions used by ordinary CLI config writers too.
+The config lock is never held across a network request; credential locks can acquire it, and
+config writers never wait for credential locks. Login IDs are stable, credential references are
+replaced on reauthorization, and rotation/ambiguity/tombstone behavior is common to all consumers.
+
+See [configuration and lifecycle contract](../../docs/cli-shared-login.md).

package/dist/index.d.ts

@@ -399,7 +399,7 @@ declare function sanitizeQuery(raw: string): string;
  */
 declare function recall(provider: Mem0Provider, query: string, userId: string, config?: SkillsConfig, sessionId?: string): Promise<RecallResult>;
 
-declare const OFFICIAL_PRODUCTION_BASE_URLS: readonly ["https://context-database.aliyuncs.com"];
+declare const OFFICIAL_PRODUCTION_BASE_URLS: readonly ["https://api.cn-hangzhou.agentcontext.aliyuncs.com", "https://context-database.aliyuncs.com"];
 type DebugReason = "non_production_base_url" | null;
 interface DebugPolicy {
     debugConfigured: boolean;
@@ -495,4 +495,515 @@ 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 };
+declare const ACTIVE_CONTEXTDB_CREDENTIAL: "contextdb/active";
+type CredentialKey = typeof ACTIVE_CONTEXTDB_CREDENTIAL;
+interface ApiKeyCredentialRecord {
+    kind: "api-key";
+    payload: {
+        apiKey: string;
+    };
+    metadata: {
+        baseUrl: string;
+        loginServer: string;
+        authorizationMethod: "browser-loopback" | "device-code";
+        issuedAt: string;
+    };
+}
+type CredentialRecord = ApiKeyCredentialRecord;
+interface CredentialInfo {
+    configured: boolean;
+    kind?: "api-key" | "oauth-session";
+    writable: boolean;
+}
+interface ResolvedRequestAuthorization {
+    scheme: "Token" | "Bearer";
+    value: string;
+    expiresAt: number | null;
+    baseUrl: string;
+}
+
+type CredentialOwner = {
+    distribution: "internal";
+} | {
+    distribution: "public";
+    agent: string;
+    loginId?: string;
+};
+type CredentialMetadata = {
+    owner: CredentialOwner;
+    generation: string;
+    revision: number;
+    state: "ready" | "refreshing" | "reauth_required" | "logged_out";
+    [field: string]: any;
+};
+type StoredCredential = {
+    kind: "api-key" | "oauth-session";
+    payload: Record<string, any>;
+    metadata: CredentialMetadata;
+};
+type CredentialCandidate = Omit<StoredCredential, "metadata"> & {
+    metadata: {
+        owner: CredentialOwner;
+        state: CredentialMetadata["state"];
+        [field: string]: any;
+    };
+};
+type CredentialSnapshot = {
+    key: string;
+    fingerprint: string;
+    record?: StoredCredential;
+};
+type CredentialCommit = {
+    before: CredentialSnapshot;
+    after: CredentialSnapshot;
+};
+declare function defaultCredentialsPath(): string;
+declare function internalCandidate(record: ApiKeyCredentialRecord): CredentialCandidate;
+/** One store for both distributions. Every commit rereads and changes only its own record. */
+declare class LocalCredentialProvider {
+    private readonly listeners;
+    readonly path: string;
+    constructor(path?: string);
+    snapshot(key: string): CredentialSnapshot;
+    readStoredRecord(key: string): StoredCredential | undefined;
+    readRecord(key: CredentialKey): Promise<ApiKeyCredentialRecord | undefined>;
+    describeRecord(key: string): Promise<CredentialInfo>;
+    onRecordUpdated(listener: (key: CredentialKey) => void): () => void;
+    /** Synchronous short commit; callbacks may acquire a config lock, never the reverse. */
+    transaction<T>(operation: (tx: {
+        read(key: string): CredentialSnapshot;
+        put(key: string, record: CredentialCandidate, expected?: CredentialSnapshot): CredentialCommit;
+        remove(expected: CredentialSnapshot): void;
+    }) => T): T;
+    commit(key: string, record: CredentialCandidate, expected?: CredentialSnapshot): CredentialCommit;
+    rollback(receipt: CredentialCommit): boolean;
+    modifyRecord(key: CredentialKey, mutate: (current: ApiKeyCredentialRecord | undefined) => Promise<ApiKeyCredentialRecord | undefined>, signal?: AbortSignal): Promise<ApiKeyCredentialRecord | undefined>;
+    deleteRecord(key: CredentialKey, signal?: AbortSignal): Promise<void>;
+}
+declare function readActiveCredentialSync(path?: string): ApiKeyCredentialRecord | undefined;
+declare function withAuthorizationLock<T>(path: string, operation: (signal?: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<T>;
+
+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" | "logged_out";
+type OAuthOwner = string | {
+    loginId: string;
+};
+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"]);
+}
+/** Public session lifecycle over the same credentials.json provider used by internal login. */
+declare class OAuthSessionStore {
+    private readonly provider;
+    private readonly now;
+    private readonly lockWaitMs;
+    readonly path: string;
+    constructor(path: string, options?: {
+        now?: () => number;
+        lockWaitMs?: number;
+    });
+    saveLogin(profile: string, session: OAuthLogin, loginId?: string): string;
+    status(ref: string, owner: OAuthOwner): {
+        state: "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, owner: OAuthOwner, transport: OAuthRefreshTransport): Promise<OAuthRequestAuthorization>;
+    share<T>(ref: string, profile: string, loginId: string, commit: () => T): Promise<T>;
+    /** Setup changes the DATA endpoint without replacing the identity or racing a refresh. */
+    changeBaseUrl(ref: string, owner: OAuthOwner, baseUrl: string, beforeWrite: () => void): Promise<void>;
+    logout(ref: string, owner: OAuthOwner, transport: OAuthRevokeTransport, beforeRevoke?: () => void): Promise<{
+        remoteRevoked: boolean;
+    }>;
+    /** Release config references under the write lock, then delete an unused session.
+     * Waiting on the operation lock first lets an in-flight refresh supply its latest RT.
+     * Returning false from release preserves a session that still has users.
+     */
+    retire(ref: string, owner: OAuthOwner, transport: OAuthRevokeTransport, release: () => boolean): Promise<{
+        removed: boolean;
+        remoteRevoked: boolean;
+        remoteUnconfirmed: boolean;
+    }>;
+    private needsRefresh;
+    private read;
+    private write;
+    private withLock;
+}
+/** Keep storage layout mapping in shared; callers use the same candidate for commit and compensation. */
+declare function oauthSessionCandidate(profile: string, session: OAuthLogin, loginId?: string): CredentialCandidate;
+declare function oauthSessionFromCredential(record: CredentialCandidate): OAuthLogin;
+
+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 requestTimeoutMs;
+    private readonly sleep;
+    constructor(baseUrl: string, options?: {
+        fetchImpl?: typeof fetch;
+        now?: () => number;
+        requestTimeoutMs?: number;
+        sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    });
+    login(options: {
+        onPrompt: (prompt: DevicePrompt) => void;
+        signal?: AbortSignal;
+        initialAgent?: string;
+    }): Promise<OAuthLogin>;
+    refresh(refreshToken: string, baseUrl: string): Promise<OAuthRefreshResponse>;
+    revoke(refreshToken: string, baseUrl: string): Promise<void>;
+    private requireSameOrigin;
+    private post;
+}
+
+type AuthConfig = {
+    version: 2;
+    agents: Record<string, Record<string, any>>;
+    logins?: Record<string, {
+        credential_ref: string;
+        [key: string]: unknown;
+    }>;
+    [key: string]: any;
+};
+declare class AuthConfigError extends Error {
+    constructor(message: string);
+}
+declare function readAuthConfig(path: string): AuthConfig;
+declare function ownAuthProfile(raw: AuthConfig, agent: string): Record<string, any>;
+declare function requireLoginId(id: unknown): asserts id is string;
+declare function loginUsers(raw: AuthConfig, id: string): string[];
+/** Validate BEFORE the caller merges default fields. Legacy-only profiles keep their old precedence. */
+declare function validateLoginChoice(section: Record<string, any>): void;
+/** No token values in errors. This snapshot is private process state, never printed. */
+declare function authSnapshot(raw: AuthConfig, agent: string): string;
+declare function assertAuthSnapshot(raw: AuthConfig, agent: string, expected: string): void;
+/** Preserve only existing legacy profiles that really inherited the default key. Never synthesize Agents. */
+declare function preserveDefaultApiKey(raw: AuthConfig, store?: (agent: string, key: string, baseUrl: string) => string): void;
+declare function rejectAuthEnvironment(env: Record<string, string | undefined>): void;
+/** Short, synchronous critical sections only. Never hold this lock across network IO or an await.
+ * Credential operations may acquire this config lock, but config writers never acquire a credential lock.
+ * This is also used by ordinary CLI config writers, so a business-field save cannot lose a login commit.
+ */
+declare function withAuthConfigLock<T>(path: string, task: () => T): T;
+declare function updateAuthConfig<T>(path: string, task: (raw: AuthConfig) => T): T;
+
+/** Safe config metadata, never AT/RT. References are explicit per profile and are not inherited. */
+type OAuthProfile = {
+    reference: string;
+    profile: string;
+    configPath: string;
+    credentialsPath: string;
+    baseUrl: string;
+    loginId?: string;
+};
+declare function oauthProfile(reference: unknown, configPath: string, profile: string, baseUrl: string): OAuthProfile | undefined;
+/** Resolve explicit Agent -> login -> credential relationships before default inheritance. No writes. */
+declare function oauthProfileFromConfig(raw: AuthConfig, path: string, agent: string, baseUrlOverride?: string): OAuthProfile | undefined;
+declare function oauthOwner(profile: OAuthProfile): string | {
+    loginId: string;
+};
+declare function oauthProfileStatus(profile: OAuthProfile): {
+    state: "missing";
+    profile?: undefined;
+    baseUrl?: undefined;
+    workspaceId?: undefined;
+    memberId?: undefined;
+    clientId?: undefined;
+    scope?: undefined;
+    sessionId?: undefined;
+    accountDisplay?: undefined;
+    accessExpiresAt?: undefined;
+} | {
+    state: "ready" | "refreshing" | "reauth_required" | "logged_out";
+    profile: string;
+    baseUrl: string;
+    workspaceId: string;
+    memberId: string;
+    clientId: "ctxdb-cli";
+    scope: OAuthScope;
+    sessionId: string;
+    accountDisplay: string;
+    accessExpiresAt: number;
+};
+/** 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(options?: {
+        timeoutMs?: number;
+    }): Promise<OAuthRequestAuthorization>;
+}
+
+declare function selectedLogin(path: string, agent: string): OAuthProfile | undefined;
+/** --login default is resolved now, never stored as a chain through another Agent. */
+declare function namedLogin(raw: AuthConfig, path: string, name: string): OAuthProfile;
+declare function beginLogin(path: string, agent: string, name?: string): {
+    path: string;
+    agent: string;
+    name: string;
+    previous: OAuthProfile;
+    loginId: string;
+    update: boolean;
+    snapshot: string;
+    previousState: "missing" | ("ready" | "refreshing" | "reauth_required" | "logged_out");
+    group: string;
+    users: string[];
+};
+type PendingLogin = ReturnType<typeof beginLogin>;
+declare function commitLogin(pending: PendingLogin, reference: string, baseUrl: string): void;
+declare function unbindLogin(path: string, agent: string): void;
+declare function bindLogin(path: string, agent: string, name: string): Promise<void>;
+type SetupAuthenticationOptions = {
+    apiKey?: string;
+    login?: string;
+    baseUrl?: string;
+    preserveBaseUrl?: boolean;
+};
+/** Setup keeps the selected identity, but resets its DATA endpoint unless explicitly supplied. */
+declare function setupAuthentication(path: string, agent: string, options: SetupAuthenticationOptions, env?: Record<string, string | undefined>): Promise<void>;
+
+/** Config mutation and reference check occur together, after any concurrent refresh.
+ * The caller's mutation must only use the supplied config (the credential write lock is held).
+ */
+declare function releaseLogin(profile: OAuthProfile, transport: OAuthRevokeTransport, detach?: (raw: AuthConfig) => void): Promise<{
+    removed: boolean;
+    remoteRevoked: boolean;
+    remoteUnconfirmed: boolean;
+}>;
+/** Collect catalogued orphans after a successful authentication change. Never scan arbitrary
+ * credentials: an unpublished concurrent login or an internal/API-key record is not an orphan.
+ */
+declare function collectUnusedLogins(path: string, transport: OAuthRevokeTransport, previous?: OAuthProfile): Promise<{
+    removed: number;
+    unconfirmed: number;
+}>;
+
+declare const DEFAULT_DATA_BASE_URL = "https://api.cn-hangzhou.agentcontext.aliyuncs.com";
+/** Validate explicit input before any config/credential write; never echo a supplied URL's secrets. */
+declare function validateDataBaseUrl(value: unknown, coreOrigin?: boolean): asserts value is string;
+
+type DataAuthContext = {
+    configPath: string;
+    agent: string;
+    baseUrl: string;
+    inheritDefaultKey: boolean;
+    baseUrlOverride?: string;
+    managedCredentials?: boolean;
+    credentialsPath?: string;
+};
+type DataApiCredential = {
+    type: "access-token";
+    value: string;
+    context?: undefined;
+} | {
+    type: "oauth-session";
+    profile: OAuthProfile;
+    value?: undefined;
+    context?: DataAuthContext;
+} | {
+    type: "api-key";
+    value: string;
+    context?: DataAuthContext;
+};
+declare function selectDataApiCredential(cfg: {
+    apiKey: string | null;
+    oauthCredential?: OAuthProfile;
+    authContext?: DataAuthContext;
+}, env?: Record<string, string | undefined>): DataApiCredential | null;
+/** Used by both HTTP clients. Persisted choices are reread for every request, including API Key switches.
+ * Runtime environment credentials are selected first by selectDataApiCredential and never enter this store.
+ */
+declare class DataApiAuthorizationProvider {
+    private readonly context;
+    constructor(context: DataAuthContext);
+    resolve(options?: {
+        timeoutMs?: number;
+    }): Promise<{
+        scheme: "Token" | "Bearer";
+        value: string;
+        baseUrl: string;
+        expiresAt: number | null;
+    }>;
+}
+/** Referenced credentials own their endpoint. Legacy config addresses never select or redirect them.
+ * Only an explicit runtime override is compared, before any credential can be sent.
+ */
+declare function publicAuthenticationFromConfig(raw: AuthConfig, path: string, agent: string, baseUrlOverride?: string): {
+    baseUrl: string;
+    apiKey?: string;
+    oauthCredential?: OAuthProfile;
+} | undefined;
+/** Compatibility export; resolution and origin checks live in the unified reader. */
+declare function publicApiKeyFromConfig(raw: AuthConfig, path: string, agent: string, baseUrl?: string): string | undefined;
+declare function createRequestAuthorizationProvider(credential: DataApiCredential | null, baseUrl: string): OAuthProfileProvider | DataApiAuthorizationProvider | {
+    resolve(_options?: {
+        timeoutMs?: number;
+    }): Promise<{
+        scheme: "Token" | "Bearer";
+        value: string;
+        baseUrl: string;
+        expiresAt: any;
+    }>;
+};
+
+interface AuthorizationMethod {
+    id: string;
+    label: string;
+}
+interface AuthorizationNotice {
+    message: string;
+    url?: string;
+    code?: string;
+}
+type AuthorizationPrompt = {
+    kind: "text" | "secret";
+    message: string;
+    placeholder?: string;
+    signal?: AbortSignal;
+} | {
+    kind: "select";
+    message: string;
+    options: readonly {
+        id: string;
+        label: string;
+    }[];
+    signal?: AbortSignal;
+};
+interface AuthorizationInteraction {
+    notify(notice: AuthorizationNotice): void;
+    prompt(prompt: AuthorizationPrompt): Promise<string>;
+}
+interface AuthorizationSession {
+    readonly method: string;
+    readonly signal: AbortSignal;
+    notify(notice: AuthorizationNotice): void;
+    prompt(prompt: AuthorizationPrompt): Promise<string>;
+}
+/** key identifies the protocol flow, independently of the target credential reference. */
+interface AuthorizationFlow {
+    key: string;
+    label: string;
+    methods: readonly [AuthorizationMethod, ...AuthorizationMethod[]];
+    run(session: AuthorizationSession): Promise<CredentialCandidate>;
+    validate?(candidate: CredentialCandidate, signal: AbortSignal): Promise<void>;
+    revoke(candidate: CredentialCandidate): Promise<void>;
+}
+interface AuthorizationEntry {
+    key: string;
+    label: string;
+    methods: readonly AuthorizationMethod[];
+    inFlight: boolean;
+}
+interface AuthorizationTarget {
+    /** Opaque begin-state and commit receipts stay inside the adapter. */
+    commit(candidate: CredentialCandidate): unknown;
+    rollback(receipt: unknown): boolean;
+    discard?(): void;
+    retirePrevious?(): Promise<void>;
+}
+type AuthorizationOutcome = {
+    status: "authorized" | "cancelled";
+};
+
+declare class AuthorizationError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+declare class AuthorizationDeclinedError extends Error {
+    constructor(message?: string);
+}
+/** Protocols issue candidates. This module owns commit, cancellation compensation and retirement. */
+declare class AuthorizationService {
+    private readonly flows;
+    private readonly running;
+    private readonly credentials?;
+    constructor(credentials?: LocalCredentialProvider);
+    registerFlow(flow: AuthorizationFlow): () => void;
+    list(): readonly AuthorizationEntry[];
+    cancel(key: string): void;
+    begin(request: {
+        key: string;
+        credentialKey?: string;
+        method?: string;
+        interaction: AuthorizationInteraction;
+        signal?: AbortSignal;
+        target?: AuthorizationTarget;
+        previousCleanupWarning?: string;
+        finalize?: () => Promise<void>;
+        warn?: (message: string) => void;
+    }): Promise<AuthorizationOutcome>;
+}
+
+/** Publishes a stable login ID only after its fresh record exists. CAS preserves newer Agent choices. */
+declare function publicAuthorizationTarget(pending: PendingLogin, revoke: OAuthRevokeTransport): AuthorizationTarget;
+
+export { ACTIVE_CONTEXTDB_CREDENTIAL, type AddOptions, type AddResult, type AddResultItem, type ApiKeyCredentialRecord, type AuthConfig, AuthConfigError, AuthorizationDeclinedError, type AuthorizationEntry, AuthorizationError, type AuthorizationFlow, type AuthorizationInteraction, type AuthorizationMethod, type AuthorizationNotice, type AuthorizationOutcome, type AuthorizationPrompt, AuthorizationService, type AuthorizationSession, type AuthorizationTarget, type CategoryConfig, CoreDeviceClient, type CredentialCandidate, type CredentialCommit, type CredentialInfo, type CredentialKey, type CredentialRecord, type CredentialSnapshot, DEFAULT_DATA_BASE_URL, DOCUMENT_EVIDENCE_SECTION_TITLE, DataApiAuthorizationProvider, type DataApiCredential, type DataAuthContext, 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, LocalCredentialProvider, 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 ResolvedRequestAuthorization, type SearchOptions, type SearchResultWithExternalContext, type SelectTurnOptions, type SelectedRecallMemory, type SkillsConfig, type StoredCredential, assertAuthSnapshot, authSnapshot, beginLogin, bindLogin, buildExternalKnowledgeBlock, buildExternalKnowledgePreamble, buildNormalizedGraphContext, collectUnusedLogins, commitLogin, createRecallFinishRecord, createRecallStartRecord, createRequestAuthorizationProvider, defaultCredentialsPath, extractKnowledgeBaseIds, extractKnowledgeChunkContent, extractKnowledgeChunkSourceLabel, extractKnowledgeChunkTags, filterMessagesForExtraction, formatExternalKnowledgeChunks, formatRecalledMemoriesBlock, internalCandidate, isGenericAssistantMessage, isGraphContextChunk, isKnowledgeBaseUploadTurn, isNoiseMessage, isOfficialProductionUrl, isSessionSpecificContent, loginUsers, namedLogin, normalizeBaseUrl, normalizeCoreOrigin, oauthOwner, oauthProfile, oauthProfileFromConfig, oauthProfileStatus, oauthSessionCandidate, oauthSessionFromCredential, ownAuthProfile, partitionKnowledgeChunks, preserveDefaultApiKey, publicApiKeyFromConfig, publicAuthenticationFromConfig, publicAuthorizationTarget, readActiveCredentialSync, readAuthConfig, readRecallTraces, recall, recallTracePath, rejectAuthEnvironment, releaseLogin, requireLoginId, resolveDebugPolicy, sanitizeChunkContent, sanitizeQuery, sanitizeRecallFailureReason, selectAndFormatRecalledMemories, selectDataApiCredential, selectTurnMessages, selectedLogin, setupAuthentication, stripNoiseFromContent, truncateGraphContext, unbindLogin, updateAuthConfig, validateDataBaseUrl, validateLoginChoice, withAuthConfigLock, withAuthorizationLock, writeRecallTrace };