From 1a8263c2f51843aed44eeeb6348eff059cd3e81b Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 06:55:31 -0400 Subject: [PATCH] docs: document auth redaction helpers --- src/agents/embedded-agent-payloads.ts | 6 ++++-- src/agents/mcp-oauth.ts | 9 +++++++++ src/agents/model-auth-env-vars.ts | 5 +++++ src/agents/model-auth-runtime-shared.ts | 9 +++++++-- src/agents/openclaw-tools.runtime.ts | 6 ++++-- src/agents/payload-redaction.ts | 5 +++++ 6 files changed, 34 insertions(+), 6 deletions(-) diff --git a/src/agents/embedded-agent-payloads.ts b/src/agents/embedded-agent-payloads.ts index fc72e4ef848f..b471f9a398a8 100644 --- a/src/agents/embedded-agent-payloads.ts +++ b/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[]; diff --git a/src/agents/mcp-oauth.ts b/src/agents/mcp-oauth.ts index c57d3c2112c9..f0f2c601d81e 100644 --- a/src/agents/mcp-oauth.ts +++ b/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; diff --git a/src/agents/model-auth-env-vars.ts b/src/agents/model-auth-env-vars.ts index f5d692668b5d..76f5546df12d 100644 --- a/src/agents/model-auth-env-vars.ts +++ b/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, diff --git a/src/agents/model-auth-runtime-shared.ts b/src/agents/model-auth-runtime-shared.ts index a9f80c48f6db..9ee0abbf5c15 100644 --- a/src/agents/model-auth-runtime-shared.ts +++ b/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. */ diff --git a/src/agents/openclaw-tools.runtime.ts b/src/agents/openclaw-tools.runtime.ts index 64fc4cc9e1a5..d603c997b747 100644 --- a/src/agents/openclaw-tools.runtime.ts +++ b/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"; diff --git a/src/agents/payload-redaction.ts b/src/agents/payload-redaction.ts index 45c696078b7c..cb37599573af 100644 --- a/src/agents/payload-redaction.ts +++ b/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";