docs: document auth redaction helpers

src/agents/embedded-agent-payloads.ts

@@ -1,5 +1,7 @@
-// Channel-facing reply payload emitted by embedded agents. Keep this type small:
-// channel adapters decide how to render text/media/reply targeting.
+/**
+ * Channel-facing reply payload emitted by embedded agents. Keep this type
+ * small: channel adapters decide how to render text, media, and reply targets.
+ */
 export type BlockReplyPayload = {
   text?: string;
   mediaUrls?: string[];

src/agents/mcp-oauth.ts

@@ -1,3 +1,7 @@
+/**
+ * MCP OAuth credential store and login helpers. Credentials are stored in the
+ * private OpenClaw state directory with one hashed file per MCP server URL.
+ */
 import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -31,6 +35,7 @@ type McpOAuthConfig = {
   clientMetadataUrl?: unknown;
 };
 
+/** Persisted OAuth credential presence flags for one MCP server. */
 export type McpOAuthCredentialsStatus = {
   hasTokens: boolean;
   hasClientInformation: boolean;
@@ -75,6 +80,7 @@ function buildOAuthClientMetadata(config: McpOAuthConfig): OAuthClientMetadata {
   };
 }
 
+/** Creates the MCP SDK OAuth provider backed by OpenClaw's private store. */
 export function createMcpOAuthClientProvider(params: {
   serverName: string;
   serverUrl: string;
@@ -168,6 +174,7 @@ export function createMcpOAuthClientProvider(params: {
   };
 }
 
+/** Deletes stored OAuth credentials for one MCP server. */
 export async function clearMcpOAuthCredentials(params: {
   serverName: string;
   serverUrl: string;
@@ -175,6 +182,7 @@ export async function clearMcpOAuthCredentials(params: {
   await fs.rm(oauthStorePath(params.serverName, params.serverUrl), { force: true });
 }
 
+/** Reads stored OAuth credential presence without exposing credential values. */
 export async function readMcpOAuthCredentialsStatus(params: {
   serverName: string;
   serverUrl: string;
@@ -189,6 +197,7 @@ export async function readMcpOAuthCredentialsStatus(params: {
   };
 }
 
+/** Runs the MCP OAuth login flow, returning whether it authorized or needs redirect. */
 export async function runMcpOAuthLogin(params: {
   serverName: string;
   serverUrl: string;

src/agents/model-auth-env-vars.ts

@@ -1,3 +1,8 @@
+/**
+ * Provider auth env/evidence lookup facade for agent auth code. It keeps
+ * provider-env-var source paths centralized while exposing API-key oriented
+ * helper names to model/auth modules.
+ */
 import {
   listKnownProviderAuthEnvVarNames,
   resolveProviderAuthEvidence,

src/agents/model-auth-runtime-shared.ts

@@ -1,12 +1,16 @@
+/**
+ * Shared provider-auth runtime types and errors. Provider calls use these
+ * helpers to fail with actionable auth provenance while keeping secret
+ * normalization local.
+ */
 import { normalizeSecretInput } from "../utils/normalize-secret-input.js";
 
-// Shared provider-auth runtime types and errors. Provider calls use these helpers
-// to fail with actionable auth provenance while keeping secret normalization local.
 const AWS_BEARER_ENV = "AWS_BEARER_TOKEN_BEDROCK";
 const AWS_ACCESS_KEY_ENV = "AWS_ACCESS_KEY_ID";
 const AWS_SECRET_KEY_ENV = "AWS_SECRET_ACCESS_KEY";
 const AWS_PROFILE_ENV = "AWS_PROFILE";
 
+/** Resolved credential material and provenance for one provider request. */
 export type ResolvedProviderAuth = {
   apiKey?: string;
   profileId?: string;
@@ -14,6 +18,7 @@ export type ResolvedProviderAuth = {
   mode: "api-key" | "oauth" | "token" | "aws-sdk";
 };
 
+/** Stable provider auth error code used by fallback/retry paths. */
 export type ProviderAuthErrorCode = "missing-api-key" | "missing-provider-auth";
 
 /** Base provider auth error with a stable code for retry/fallback logic. */

src/agents/openclaw-tools.runtime.ts

@@ -1,3 +1,5 @@
-// Runtime seam for tests and lazy imports that need OpenClaw tool creation
-// without depending on the full tool module path.
+/**
+ * Runtime seam for tests and lazy imports that need OpenClaw tool creation
+ * without depending on the full tool module path.
+ */
 export { createOpenClawTools } from "./openclaw-tools.js";

src/agents/payload-redaction.ts

@@ -1,3 +1,8 @@
+/**
+ * Redacts diagnostic payloads before persistence. It removes credential-like
+ * fields, masks embedded auth strings, and replaces image/base64 data with
+ * size and digest metadata.
+ */
 import crypto from "node:crypto";
 import { estimateBase64DecodedBytes } from "@openclaw/media-core/base64";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";