From f9613ff01e2bad1932983b07a1f4e3339f9bb792 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 05:59:08 -0400 Subject: [PATCH] docs: document auth profile persistence --- src/agents/auth-profiles/oauth-test-utils.ts | 7 ++++++- src/agents/auth-profiles/persisted-boundary.test.ts | 5 +++++ src/agents/auth-profiles/persisted.ts | 5 +++++ src/agents/auth-profiles/policy.ts | 5 +++++ src/agents/auth-profiles/portability.test.ts | 5 +++++ src/agents/auth-profiles/portability.ts | 5 +++++ src/agents/auth-profiles/profile-list.ts | 5 +++++ src/agents/auth-profiles/profiles.test.ts | 5 +++++ src/agents/auth-profiles/profiles.ts | 9 +++++++-- src/agents/auth-profiles/repair.ts | 5 +++++ 10 files changed, 53 insertions(+), 3 deletions(-) diff --git a/src/agents/auth-profiles/oauth-test-utils.ts b/src/agents/auth-profiles/oauth-test-utils.ts index 5b64e7c51005..34f9a0d0e77b 100644 --- a/src/agents/auth-profiles/oauth-test-utils.ts +++ b/src/agents/auth-profiles/oauth-test-utils.ts @@ -1,3 +1,8 @@ +/** + * Shared OAuth test fixtures and temp-dir helpers. + * Provides deterministic credential/store builders, state-dir setup, and + * provider-runtime mock reset helpers for auth-profile tests. + */ import fs from "node:fs/promises"; import os from "node:os"; import path from "node:path"; @@ -7,7 +12,7 @@ import { loadPersistedAuthProfileStore } from "./persisted.js"; import { saveAuthProfileStore } from "./store.js"; import type { AuthProfileStore, OAuthCredential } from "./types.js"; -// Shared OAuth test fixtures and temp-dir helpers. +/** Environment keys OAuth tests override while creating isolated state roots. */ export const OAUTH_AGENT_ENV_KEYS = ["OPENCLAW_STATE_DIR", "OPENCLAW_AGENT_DIR"]; /** Call resolveApiKeyForProfile with an empty config in tests. */ diff --git a/src/agents/auth-profiles/persisted-boundary.test.ts b/src/agents/auth-profiles/persisted-boundary.test.ts index 4a61c68bb76e..709605c2511f 100644 --- a/src/agents/auth-profiles/persisted-boundary.test.ts +++ b/src/agents/auth-profiles/persisted-boundary.test.ts @@ -1,3 +1,8 @@ +/** + * Tests persisted auth profile boundary normalization. + * Covers malformed credential coercion, state merging, legacy OAuth refs, and + * main/agent store drift repair. + */ import { describe, expect, it } from "vitest"; import { AUTH_STORE_VERSION } from "./constants.js"; import { coercePersistedAuthProfileStore, mergeAuthProfileStores } from "./persisted.js"; diff --git a/src/agents/auth-profiles/persisted.ts b/src/agents/auth-profiles/persisted.ts index a2d8980c7dac..c905fff15a08 100644 --- a/src/agents/auth-profiles/persisted.ts +++ b/src/agents/auth-profiles/persisted.ts @@ -1,3 +1,8 @@ +/** + * Persisted auth profile store loading and migration. + * Normalizes legacy JSON stores, SQLite/raw payloads, runtime state metadata, + * legacy OAuth files, and merged main/agent stores. + */ import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id"; import { isRecord } from "@openclaw/normalization-core/record-coerce"; import { uniqueStrings } from "@openclaw/normalization-core/string-normalization"; diff --git a/src/agents/auth-profiles/policy.ts b/src/agents/auth-profiles/policy.ts index 4f1a211d4835..98ae67b81886 100644 --- a/src/agents/auth-profiles/policy.ts +++ b/src/agents/auth-profiles/policy.ts @@ -1,3 +1,8 @@ +/** + * Auth profile policy validation. + * Rejects SecretRef-backed OAuth material because OAuth credentials are mutable + * runtime state and must stay directly persisted by refresh flows. + */ import type { OpenClawConfig } from "../../config/types.openclaw.js"; import { coerceSecretRef, resolveSecretInputRef } from "../../config/types.secrets.js"; import type { AuthProfileCredential, AuthProfileStore } from "./types.js"; diff --git a/src/agents/auth-profiles/portability.test.ts b/src/agents/auth-profiles/portability.test.ts index 5e8b3ce31799..c2e4f9c7ee46 100644 --- a/src/agents/auth-profiles/portability.test.ts +++ b/src/agents/auth-profiles/portability.test.ts @@ -1,3 +1,8 @@ +/** + * Tests auth profile portability decisions. + * Verifies static credential copy, OAuth opt-in behavior, and explicit + * copy-to-agent opt-outs. + */ import { describe, expect, it } from "vitest"; import { buildPortableAuthProfileSecretsStoreForAgentCopy, diff --git a/src/agents/auth-profiles/portability.ts b/src/agents/auth-profiles/portability.ts index f4f890f80a41..b4fea4958f2f 100644 --- a/src/agents/auth-profiles/portability.ts +++ b/src/agents/auth-profiles/portability.ts @@ -1,3 +1,8 @@ +/** + * Auth profile portability for agent-local copies. + * Decides which credentials can be copied to spawned agents without leaking or + * duplicating unsafe OAuth refresh material. + */ import { AUTH_STORE_VERSION } from "./constants.js"; import type { AuthProfileCredential, AuthProfileSecretsStore, AuthProfileStore } from "./types.js"; diff --git a/src/agents/auth-profiles/profile-list.ts b/src/agents/auth-profiles/profile-list.ts index 5c4ef1dd941e..abacd107040c 100644 --- a/src/agents/auth-profiles/profile-list.ts +++ b/src/agents/auth-profiles/profile-list.ts @@ -1,3 +1,8 @@ +/** + * Auth profile list helpers. + * Provides provider-compatible profile lookup and stable de-duplication used by + * ordering, repair, and profile mutation paths. + */ import { uniqueStrings } from "@openclaw/normalization-core/string-normalization"; import { resolveProviderIdForAuth } from "../provider-auth-aliases.js"; import type { AuthProfileStore } from "./types.js"; diff --git a/src/agents/auth-profiles/profiles.test.ts b/src/agents/auth-profiles/profiles.test.ts index a4f07be0e68b..b186a6e1e569 100644 --- a/src/agents/auth-profiles/profiles.test.ts +++ b/src/agents/auth-profiles/profiles.test.ts @@ -1,3 +1,8 @@ +/** + * Tests auth profile mutation helpers. + * Covers locked upserts, order promotion, last-good clearing, legacy OAuth file + * imports, and credential normalization. + */ import fs from "node:fs"; import os from "node:os"; import path from "node:path"; diff --git a/src/agents/auth-profiles/profiles.ts b/src/agents/auth-profiles/profiles.ts index 1cf5acebf0f5..3ad5ed225a97 100644 --- a/src/agents/auth-profiles/profiles.ts +++ b/src/agents/auth-profiles/profiles.ts @@ -1,3 +1,8 @@ +/** + * Auth profile mutation helpers. + * Updates profile order, last-good state, usage stats, and provider profile + * records through locked or immediate store writes. + */ import { findNormalizedProviderKey, normalizeProviderId, @@ -252,7 +257,7 @@ export async function removeProviderAuthProfilesWithLock(params: { }); } -/** Clears lastGood for a provider when it points at the supplied profile. */ +/** Clear the last-good profile pointer for a provider under the store lock. */ export async function clearLastGoodProfileWithLock(params: { provider: string; profileId: string; @@ -275,7 +280,7 @@ export async function clearLastGoodProfileWithLock(params: { }); } -/** Marks an auth profile as successful and updates lastGood/usage state. */ +/** Mark a profile as successfully used and update ordering/usage metadata. */ export async function markAuthProfileSuccess(params: { store: AuthProfileStore; provider: string; diff --git a/src/agents/auth-profiles/repair.ts b/src/agents/auth-profiles/repair.ts index d10692c842aa..0c655a41b742 100644 --- a/src/agents/auth-profiles/repair.ts +++ b/src/agents/auth-profiles/repair.ts @@ -1,3 +1,8 @@ +/** + * Auth profile repair helpers. + * Migrates legacy provider:default OAuth config references to safer modern + * profile ids chosen from store metadata and auth order. + */ import { findNormalizedProviderKey, normalizeProviderId,