From 474d6e520aafcaae95068dc6257cda68c643bfb9 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 05:49:45 -0400 Subject: [PATCH] docs: document auth health helpers --- src/agents/auth-health.test.ts | 5 +++++ src/agents/auth-health.ts | 7 +++++++ src/agents/auth-profile-runtime-contract.test.ts | 5 +++++ src/agents/auth-profiles/clone.ts | 5 +++++ src/agents/auth-profiles/constants.ts | 13 +++++++++++++ src/agents/auth-profiles/credential-state.test.ts | 5 +++++ src/agents/auth-profiles/credential-state.ts | 5 +++++ src/agents/auth-profiles/display.test.ts | 4 ++++ src/agents/auth-profiles/display.ts | 4 ++++ src/agents/auth-profiles/doctor.ts | 5 +++++ 10 files changed, 58 insertions(+) diff --git a/src/agents/auth-health.test.ts b/src/agents/auth-health.test.ts index a572bb20d603..e396bde2c159 100644 --- a/src/agents/auth-health.test.ts +++ b/src/agents/auth-health.test.ts @@ -1,3 +1,8 @@ +/** + * Tests auth health rollups. + * Covers OAuth/API-key status classification, external CLI bootstrap, provider + * auth ordering, and prompt-free credential checks. + */ import { MAX_DATE_TIMESTAMP_MS } from "@openclaw/normalization-core/number-coercion"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import type { OAuthCredential } from "./auth-profiles/types.js"; diff --git a/src/agents/auth-health.ts b/src/agents/auth-health.ts index 69f2d74aa4b8..0c8081228ac4 100644 --- a/src/agents/auth-health.ts +++ b/src/agents/auth-health.ts @@ -1,3 +1,8 @@ +/** + * Auth profile health summarization. + * Classifies stored and runtime credentials into profile/provider rollups for + * status commands and doctor output without prompting keychain access. + */ import { findNormalizedProviderValue, normalizeProviderId, @@ -61,6 +66,7 @@ function resolveAuthProfileSource(_profileId: string): AuthProfileSource { return "store"; } +/** Format a remaining-duration value for compact auth status displays. */ export function formatRemainingShort( remainingMs?: number, opts?: { @@ -253,6 +259,7 @@ function buildProfileHealth(params: { }; } +/** Build profile and provider auth health rollups from an auth profile store. */ export function buildAuthHealthSummary(params: { store: AuthProfileStore; cfg?: OpenClawConfig; diff --git a/src/agents/auth-profile-runtime-contract.test.ts b/src/agents/auth-profile-runtime-contract.test.ts index aa1fc1525f42..65176059bdd5 100644 --- a/src/agents/auth-profile-runtime-contract.test.ts +++ b/src/agents/auth-profile-runtime-contract.test.ts @@ -1,3 +1,8 @@ +/** + * Runtime contract tests for auth profile forwarding. + * Ensures CLI and embedded agent runtimes receive the selected auth profile + * across provider aliases and plugin runtime manifests. + */ import fs from "node:fs/promises"; import os from "node:os"; import path from "node:path"; diff --git a/src/agents/auth-profiles/clone.ts b/src/agents/auth-profiles/clone.ts index bd3b2b54195f..565257a367dd 100644 --- a/src/agents/auth-profiles/clone.ts +++ b/src/agents/auth-profiles/clone.ts @@ -1,3 +1,8 @@ +/** + * Auth profile store cloning helpers. + * Keeps store snapshots JSON-serializable before callers mutate or persist + * profile state. + */ import type { AuthProfileStore } from "./types.js"; /** Deep-clones an auth profile store and rejects non-JSON values. */ diff --git a/src/agents/auth-profiles/constants.ts b/src/agents/auth-profiles/constants.ts index bedadaa96066..559990cc7010 100644 --- a/src/agents/auth-profiles/constants.ts +++ b/src/agents/auth-profiles/constants.ts @@ -1,3 +1,8 @@ +/** + * Shared auth-profile constants. + * Defines store versions, built-in CLI profile ids, lock budgets, refresh + * timing, and logging used by auth profile runtime modules. + */ import { createSubsystemLogger } from "../../logging/subsystem.js"; export { AUTH_PROFILE_FILENAME, @@ -5,16 +10,19 @@ export { LEGACY_AUTH_FILENAME, } from "./path-constants.js"; +/** Current persisted auth profile store schema version. */ export const AUTH_STORE_VERSION = 1; /** @deprecated Anthropic provider-owned CLI profile id; do not use from third-party plugins. */ export const CLAUDE_CLI_PROFILE_ID = "anthropic:claude-cli"; /** @deprecated OpenAI provider-owned CLI profile id; do not use from third-party plugins. */ export const CODEX_CLI_PROFILE_ID = "openai:codex-cli"; +/** Default OpenAI/Codex OAuth profile id used for migrated stores. */ export const OPENAI_CODEX_DEFAULT_PROFILE_ID = "openai:default"; /** @deprecated MiniMax provider-owned CLI profile id; do not use from third-party plugins. */ export const MINIMAX_CLI_PROFILE_ID = "minimax-portal:minimax-cli"; +/** File-lock policy for auth profile store reads/writes. */ export const AUTH_STORE_LOCK_OPTIONS = { retries: { retries: 10, @@ -40,6 +48,7 @@ export const AUTH_STORE_LOCK_OPTIONS = { // Retry budget note: keep the MINIMUM cumulative retry window comfortably // above OAUTH_REFRESH_CALL_TIMEOUT_MS so waiters do not give up while a // legitimate slow refresh is still within its allowed runtime budget. +/** Cross-agent lock policy for shared OAuth refresh operations. */ export const OAUTH_REFRESH_LOCK_OPTIONS = { retries: { retries: 20, @@ -56,9 +65,13 @@ export const OAUTH_REFRESH_LOCK_OPTIONS = { // surfaced as a refresh failure. Keep strictly below // OAUTH_REFRESH_LOCK_OPTIONS.stale so the lock is never treated as stale // by a waiter while the owner is still doing legitimate work. +/** Maximum duration for one OAuth refresh call inside the refresh lock. */ export const OAUTH_REFRESH_CALL_TIMEOUT_MS = 120_000; +/** Freshness window for syncing external CLI auth into auth profiles. */ export const EXTERNAL_CLI_SYNC_TTL_MS = 15 * 60 * 1000; +/** Near-expiry threshold that triggers external CLI credential resync. */ export const EXTERNAL_CLI_NEAR_EXPIRY_MS = 10 * 60 * 1000; +/** Auth profile subsystem logger. */ export const log = createSubsystemLogger("agents/auth-profiles"); diff --git a/src/agents/auth-profiles/credential-state.test.ts b/src/agents/auth-profiles/credential-state.test.ts index d9682241e9f0..7e1c93e95e94 100644 --- a/src/agents/auth-profiles/credential-state.test.ts +++ b/src/agents/auth-profiles/credential-state.test.ts @@ -1,3 +1,8 @@ +/** + * Tests credential eligibility and expiry classification. + * Protects missing, expired, near-expiry, and SecretRef credential handling for + * auth profile selection. + */ import { describe, expect, it } from "vitest"; import { DEFAULT_OAUTH_REFRESH_MARGIN_MS, diff --git a/src/agents/auth-profiles/credential-state.ts b/src/agents/auth-profiles/credential-state.ts index 5f6b4f75e0b8..d0f440aa0b00 100644 --- a/src/agents/auth-profiles/credential-state.ts +++ b/src/agents/auth-profiles/credential-state.ts @@ -1,3 +1,8 @@ +/** + * Credential state classification for auth profiles. + * Centralizes expiry, missing-secret, and unresolved-reference checks used by + * auth selection, refresh, health, and doctor flows. + */ import { MAX_DATE_TIMESTAMP_MS } from "@openclaw/normalization-core/number-coercion"; import { coerceSecretRef, normalizeSecretInputString } from "../../config/types.secrets.js"; import type { AuthProfileCredential, OAuthCredential } from "./types.js"; diff --git a/src/agents/auth-profiles/display.test.ts b/src/agents/auth-profiles/display.test.ts index 129a8c22e267..7f095fd4a1e4 100644 --- a/src/agents/auth-profiles/display.test.ts +++ b/src/agents/auth-profiles/display.test.ts @@ -1,3 +1,7 @@ +/** + * Tests auth profile display labels. + * Verifies configured display names/emails are used without fabricating labels. + */ import { describe, expect, it } from "vitest"; import { resolveAuthProfileDisplayLabel } from "./display.js"; diff --git a/src/agents/auth-profiles/display.ts b/src/agents/auth-profiles/display.ts index 1d6f4a8491b5..2465bc1e04ed 100644 --- a/src/agents/auth-profiles/display.ts +++ b/src/agents/auth-profiles/display.ts @@ -1,3 +1,7 @@ +/** + * Auth profile display labels. + * Combines profile ids with configured human metadata for CLI/status output. + */ import type { OpenClawConfig } from "../../config/types.openclaw.js"; import { resolveAuthProfileMetadata } from "./identity.js"; import type { AuthProfileStore } from "./types.js"; diff --git a/src/agents/auth-profiles/doctor.ts b/src/agents/auth-profiles/doctor.ts index 39117362fccd..1bb6e1dbc306 100644 --- a/src/agents/auth-profiles/doctor.ts +++ b/src/agents/auth-profiles/doctor.ts @@ -1,3 +1,8 @@ +/** + * Provider-specific auth doctor hints. + * Adds local migration guidance for known legacy profiles before falling back + * to provider plugin doctor copy. + */ import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id"; import type { OpenClawConfig } from "../../config/types.openclaw.js"; import { buildProviderAuthDoctorHintWithPlugin } from "../../plugins/provider-runtime.runtime.js";