From ff02e520acc157bdda15ae861868f11f915f1f6f Mon Sep 17 00:00:00 2001
From: silentgeckoaudit3801 <silentgeckoaudit3801@users.noreply.github.com>
Date: Thu, 23 Jul 2026 00:03:11 -0600
Subject: [PATCH] docs: expand safe logging guidance

---
 docs/logging.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/docs/logging.md b/docs/logging.md
index 2f880af..92cbdb1 100644
--- a/docs/logging.md
+++ b/docs/logging.md
@@ -18,6 +18,19 @@ console.log('Signing transaction from public key:', publicKey);
 logger.info('Transaction signed', { publicKey, txHash });
 console.error('Signing failed', { publicKey, error: err.message });
 
+## Data That Must Never Be Logged
+
+Never write the following values to console output, app logs, crash reports, or
+third-party log aggregation systems:
+
+- Secret keys, seed phrases, private signing material, or wallet backup blobs
+- Raw signed transactions or envelopes before submission
+- Full transaction payloads that include memos, destination accounts, amounts,
+  or user-provided metadata unless each field has been reviewed and redacted
+- Authorization headers, API keys, bearer tokens, session identifiers, or device
+  push tokens
+- Complete error objects from wallet, signing, or Horizon/Soroban submission
+  paths when those objects may include request bodies or user input
 ## Safe Identifiers to Log
 
 These are safe to include in logs:
@@ -49,6 +62,39 @@ try {
   throw error;
 }
 
+## Debug Logging Expectations
+
+Debug mode may include extra timing, network, and SDK-state context, but it must
+still use the same redaction rules as production logging. Prefer small,
+structured fields that are already public or derived from public data.
+
+### Unsafe Debug Logging
+
+```typescript
+logger.debug("submitting payment", { secretKey, transactionXdr, requestBody });
+logger.debug("wallet created", wallet);
+```
+
+### Safe Debug Logging
+
+```typescript
+logger.debug("submitting payment", {
+  sourcePublicKey,
+  destinationPublicKey,
+  assetCode,
+  amount,
+  horizonNetworkPassphrase,
+});
+
+logger.debug("payment submitted", {
+  txHash,
+  ledger,
+  operationCount,
+});
+```
+
+When in doubt, log an event name, public account, transaction hash, ledger, or
+SDK error code instead of the raw input that produced it.
 ## Environment-Specific Logging
 
 ### Development