docs: document auth profile persistence

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. */

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";

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";

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";

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,

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";
 

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";

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";

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;

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,