docs: document auth profile persistence helpers

steipete · steipete · commit ac2dbfcfca8a · 2026-06-03T22:28:03.000-04:00
diff --git a/src/agents/auth-profiles/clone.ts b/src/agents/auth-profiles/clone.ts
@@ -1,5 +1,6 @@
 import type { AuthProfileStore } from "./types.js";
 
+/** Deep-clones an auth profile store and rejects non-JSON values. */
 export function cloneAuthProfileStore(store: AuthProfileStore): AuthProfileStore {
   return JSON.parse(
     JSON.stringify(store, (_key, value: unknown) => {
diff --git a/src/agents/auth-profiles/persisted.ts b/src/agents/auth-profiles/persisted.ts
@@ -30,6 +30,7 @@ import type {
   OAuthCredentials,
 } from "./types.js";
 
+/** Legacy auth.json store shape before auth-profiles.json/SQLite. */
 export type LegacyAuthStore = Record<string, AuthProfileCredential>;
 
 type LoadPersistedAuthProfileStoreOptions = {
@@ -42,6 +43,8 @@ type RejectedCredentialEntry = { key: string; reason: CredentialRejectReason };
 
 const AUTH_PROFILE_TYPES = new Set<AuthProfileCredential["type"]>(["api_key", "oauth", "token"]);
 
+// Persisted credential normalization accepts old field names and SecretRef-ish
+// values, then emits the current credential discriminated union.
 function normalizeOptionalCredentialString(value: unknown): string | undefined {
   if (typeof value !== "string") {
     return undefined;
@@ -70,6 +73,8 @@ function normalizeCredentialMetadata(value: unknown): Record<string, string> | u
   return Object.keys(metadata).length > 0 ? metadata : undefined;
 }
 
+// Secret-backed key/token fields may have been stored in the value field by old
+// writers. Move them to the ref field so secret values are not treated as text.
 function normalizeSecretBackedField(params: {
   entry: Record<string, unknown>;
   valueField: "key" | "token";
@@ -258,6 +263,7 @@ function coerceLegacyAuthStore(raw: unknown): LegacyAuthStore | null {
   return Object.keys(entries).length > 0 ? entries : null;
 }
 
+/** Coerces a persisted auth profile store payload into the current store shape. */
 export function coercePersistedAuthProfileStore(raw: unknown): AuthProfileStore | null {
   if (!isRecord(raw)) {
     return null;
@@ -286,6 +292,8 @@ export function coercePersistedAuthProfileStore(raw: unknown): AuthProfileStore
   };
 }
 
+// Merge store/state records by key. Undefined means "no persisted record", not
+// "empty override", so preserve the other side in that case.
 function mergeRecord<T>(
   base?: Record<string, T>,
   override?: Record<string, T>,
@@ -306,6 +314,8 @@ function dedupeMergedProfileOrder(profileIds: string[]): string[] {
   return uniqueStrings(profileIds);
 }
 
+// Legacy OAuth profiles may be replaced by safer main-store profiles when the
+// main store has a newer compatible credential for the same provider identity.
 function hasComparableOAuthIdentityConflict(
   existing: OAuthCredential,
   candidate: OAuthCredential,
@@ -498,6 +508,7 @@ function reconcileMainStoreOAuthProfileDrift(params: {
   });
 }
 
+/** Merges two auth profile stores, preserving valid runtime external profile metadata. */
 export function mergeAuthProfileStores(
   base: AuthProfileStore,
   override: AuthProfileStore,
@@ -525,6 +536,8 @@ export function mergeAuthProfileStores(
       : [],
   );
   const profiles = { ...base.profiles, ...override.profiles };
+  // Authoritative runtime snapshots may remove stale external profiles that are
+  // no longer observed, unless the caller is intentionally preserving base ones.
   for (const profileId of removedRuntimeExternalProfileIds) {
     delete profiles[profileId];
   }
@@ -596,6 +609,7 @@ export function mergeAuthProfileStores(
   });
 }
 
+/** Builds the persisted secrets store, stripping resolved literals when refs exist. */
 export function buildPersistedAuthProfileSecretsStore(
   store: AuthProfileStore,
   shouldPersistProfile?: (params: {
@@ -628,6 +642,7 @@ export function buildPersistedAuthProfileSecretsStore(
   };
 }
 
+/** Applies legacy auth.json credentials into an auth profile store. */
 export function applyLegacyAuthStore(store: AuthProfileStore, legacy: LegacyAuthStore): void {
   for (const [provider, cred] of Object.entries(legacy)) {
     const profileId = `${provider}:default`;
@@ -665,6 +680,7 @@ export function applyLegacyAuthStore(store: AuthProfileStore, legacy: LegacyAuth
   }
 }
 
+/** Imports the legacy oauth.json file into missing default OAuth profiles. */
 export function mergeOAuthFileIntoStore(store: AuthProfileStore): boolean {
   const oauthPath = resolveOAuthPath();
   const oauthRaw = loadJsonFile(oauthPath);
@@ -691,6 +707,7 @@ export function mergeOAuthFileIntoStore(store: AuthProfileStore): boolean {
   return mutated;
 }
 
+/** Loads the persisted auth profile store and merges runtime state. */
 export function loadPersistedAuthProfileStore(
   agentDir?: string,
   options?: LoadPersistedAuthProfileStoreOptions,
@@ -710,6 +727,7 @@ export function loadPersistedAuthProfileStore(
   return merged;
 }
 
+/** Loads the legacy auth.json auth profile store if present. */
 export function loadLegacyAuthProfileStore(agentDir?: string): LegacyAuthStore | null {
   return coerceLegacyAuthStore(loadJsonFile(resolveLegacyAuthStorePath(agentDir)));
 }
diff --git a/src/agents/auth-profiles/sqlite.ts b/src/agents/auth-profiles/sqlite.ts
@@ -24,6 +24,8 @@ type AuthProfileDatabase = Pick<
   "auth_profile_store" | "auth_profile_state"
 >;
 
+// Auth profiles store one JSON blob for secrets and one JSON blob for runtime
+// state. SQLite owns durability/transactions; JSON shape owns compatibility.
 const PRIMARY_ROW_KEY = "primary";
 
 function resolveAgentDir(agentDir?: string): string {
@@ -42,6 +44,8 @@ function inferAgentIdFromDir(agentDir: string): string {
   return `custom-${hash}`;
 }
 
+// The auth database lives in the agent dir and shares the openclaw-agent schema
+// so auth store/state can move with the rest of agent-local durable state.
 function resolveAuthProfileDatabaseOptions(agentDir?: string) {
   const dir = resolveAgentDir(agentDir);
   return {
@@ -50,15 +54,19 @@ function resolveAuthProfileDatabaseOptions(agentDir?: string) {
   };
 }
 
+/** Resolves the SQLite database path that stores auth profiles for an agent dir. */
 export function resolveAuthProfileDatabasePath(agentDir?: string): string {
   return resolveAuthProfileDatabaseOptions(agentDir).path;
 }
 
+/** Resolves the SQLite database and sidecar paths used by auth profiles. */
 export function resolveAuthProfileDatabaseFilePaths(agentDir?: string): string[] {
   const databasePath = resolveAuthProfileDatabasePath(agentDir);
   return [databasePath, `${databasePath}-wal`, `${databasePath}-shm`];
 }
 
+// Read-only probes must tolerate old/corrupt/missing rows. Coercion happens
+// above this layer; this layer only returns raw JSON-ish payloads.
 function parseJsonCell(raw: string | null | undefined): unknown {
   if (!raw) {
     return null;
@@ -74,6 +82,7 @@ function getAuthProfileKysely(db: DatabaseSync) {
   return getNodeSqliteKysely<AuthProfileDatabase>(db);
 }
 
+/** Opens the auth profile SQLite database for an agent dir. */
 export function openAuthProfileDatabase(agentDir?: string): OpenClawAgentDatabase {
   return openOpenClawAgentDatabase(resolveAuthProfileDatabaseOptions(agentDir));
 }
@@ -109,6 +118,7 @@ function readAuthProfileJsonCellReadOnly(pathname: string, target: "store" | "st
   }
 }
 
+/** Reads the raw persisted auth profile store payload. */
 export function readPersistedAuthProfileStoreRaw(
   agentDir?: string,
   database?: OpenClawAgentDatabase,
@@ -131,6 +141,7 @@ export function readPersistedAuthProfileStoreRaw(
   return readAuthProfileJsonCellReadOnly(databasePath, "store");
 }
 
+/** Reads the raw persisted auth profile runtime state payload. */
 export function readPersistedAuthProfileStateRaw(
   agentDir?: string,
   database?: OpenClawAgentDatabase,
@@ -153,6 +164,7 @@ export function readPersistedAuthProfileStateRaw(
   return readAuthProfileJsonCellReadOnly(databasePath, "state");
 }
 
+/** Writes the raw persisted auth profile store payload. */
 export function writePersistedAuthProfileStoreRaw(
   payload: unknown,
   agentDir?: string,
@@ -184,6 +196,7 @@ export function writePersistedAuthProfileStoreRaw(
   runOpenClawAgentWriteTransaction(write, resolveAuthProfileDatabaseOptions(agentDir));
 }
 
+/** Deletes the raw persisted auth profile store payload. */
 export function deletePersistedAuthProfileStoreRaw(
   agentDir?: string,
   database?: OpenClawAgentDatabase,
@@ -202,6 +215,7 @@ export function deletePersistedAuthProfileStoreRaw(
   runOpenClawAgentWriteTransaction(remove, resolveAuthProfileDatabaseOptions(agentDir));
 }
 
+/** Writes or deletes the raw persisted auth profile runtime state payload. */
 export function writePersistedAuthProfileStateRaw(
   payload: unknown,
   agentDir?: string,
@@ -240,6 +254,7 @@ export function writePersistedAuthProfileStateRaw(
   runOpenClawAgentWriteTransaction(write, resolveAuthProfileDatabaseOptions(agentDir));
 }
 
+/** Runs an auth-profile database write transaction. */
 export function runAuthProfileWriteTransaction<T>(
   agentDir: string | undefined,
   operation: (database: OpenClawAgentDatabase) => T,
diff --git a/src/agents/auth-profiles/state-observation.ts b/src/agents/auth-profiles/state-observation.ts
@@ -5,6 +5,7 @@ import type { AuthProfileFailureReason, ProfileUsageStats } from "./types.js";
 
 const observationLog = createSubsystemLogger("agent/embedded");
 
+/** Logs an auth profile failure/cooldown/disable state transition. */
 export function logAuthProfileFailureStateChange(params: {
   runId?: string;
   profileId: string;
@@ -18,8 +19,8 @@ export function logAuthProfileFailureStateChange(params: {
     params.reason === "billing" || params.reason === "auth_permanent" ? "disabled" : "cooldown";
   const previousCooldownUntil = params.previous?.cooldownUntil;
   const previousDisabledUntil = params.previous?.disabledUntil;
-  // Active cooldown/disable windows are intentionally immutable; log whether this
-  // update reused the existing window instead of extending it.
+  // Active cooldown/disable windows are intentionally immutable; log whether
+  // this update reused the existing window instead of extending it.
   const windowReused =
     windowType === "disabled"
       ? typeof previousDisabledUntil === "number" &&
diff --git a/src/agents/auth-profiles/state.ts b/src/agents/auth-profiles/state.ts
@@ -34,6 +34,8 @@ const AUTH_FAILURE_REASONS = new Set<AuthProfileFailureReason>([
 const AUTH_BLOCKED_REASONS = new Set<AuthProfileBlockedReason>(["subscription_limit"]);
 const AUTH_BLOCKED_SOURCES = new Set<AuthProfileBlockedSource>(["codex_rate_limits", "wham"]);
 
+// Runtime auth state is operator-controlled durability. Coerce every persisted
+// field through closed enums/numbers so bad rows do not poison auth selection.
 function normalizeFiniteNumber(value: unknown): number | undefined {
   return asFiniteNumber(value);
 }
@@ -145,6 +147,7 @@ function normalizeUsageStats(raw: unknown): AuthProfileState["usageStats"] {
   return Object.keys(normalized).length > 0 ? normalized : undefined;
 }
 
+/** Coerces persisted auth profile runtime state into the current shape. */
 export function coerceAuthProfileState(raw: unknown): AuthProfileState {
   if (!isRecord(raw)) {
     return {};
@@ -156,6 +159,7 @@ export function coerceAuthProfileState(raw: unknown): AuthProfileState {
   };
 }
 
+/** Merges auth profile runtime state, with override records winning per key. */
 export function mergeAuthProfileState(
   base: AuthProfileState,
   override: AuthProfileState,
@@ -180,13 +184,15 @@ export function mergeAuthProfileState(
   };
 }
 
+/** Loads persisted auth profile runtime state from SQLite. */
 export function loadPersistedAuthProfileState(
   agentDir?: string,
   database?: OpenClawAgentDatabase,
 ): AuthProfileState {
   return coerceAuthProfileState(readPersistedAuthProfileStateRaw(agentDir, database));
 }
 
+/** Builds the persisted auth profile runtime state payload. */
 export function buildPersistedAuthProfileState(
   store: AuthProfileState,
 ): AuthProfileStateStore | null {
@@ -202,6 +208,7 @@ export function buildPersistedAuthProfileState(
   };
 }
 
+/** Saves auth profile runtime state when it differs from the persisted payload. */
 export function savePersistedAuthProfileState(
   store: AuthProfileState,
   agentDir?: string,
diff --git a/src/agents/auth-profiles/upsert-with-lock.ts b/src/agents/auth-profiles/upsert-with-lock.ts
@@ -2,6 +2,8 @@ import { normalizeSecretInput } from "../../utils/normalize-secret-input.js";
 import { updateAuthProfileStoreWithLock } from "./store.js";
 import type { AuthProfileCredential, AuthProfileStore } from "./types.js";
 
+// Upserts normalize literal secrets before persistence; SecretRef fields are
+// preserved by leaving non-string key/token values untouched.
 function normalizeAuthProfileCredential(credential: AuthProfileCredential): AuthProfileCredential {
   if (credential.type === "api_key") {
     if (typeof credential.key !== "string") {
@@ -25,6 +27,7 @@ function normalizeAuthProfileCredential(credential: AuthProfileCredential): Auth
   return credential;
 }
 
+/** Upserts an auth profile under the store lock, returning null on write failure. */
 export async function upsertAuthProfileWithLock(params: {
   profileId: string;
   credential: AuthProfileCredential;
