chore: import upstream snapshot with attribution

2026-07-13 13:24:08 +08:00
commit 0d3cb498a3
5438 changed files with 1316560 additions and 0 deletions
@@ -0,0 +1,72 @@
+# Logging Guidelines
+
+## The Rule
+
+Always use the logger with an object as the second parameter:
+
+```typescript
+logger.debug('[Component] Message', { headers, body, config });
+```
+
+The object is **auto-sanitized** - sensitive fields are automatically redacted.
+
+## Why This Matters
+
+- **Security**: Prevents accidental exposure of secrets in logs
+- **Consistency**: Structured logs are easier to search and analyze
+- **Safety**: Red team test content may contain harmful/sensitive data
+
+## Correct Usage
+
+```typescript
+import logger from './logger';
+
+// Good - context object is auto-sanitized
+logger.debug('[Provider]: Making API request', {
+  url: 'https://api.example.com',
+  method: 'POST',
+  headers: { Authorization: 'Bearer secret-token' },
+  body: { apiKey: 'secret-key', data: 'value' },
+});
+// Output: Authorization and apiKey are [REDACTED]
+
+logger.error('Request failed', {
+  headers: response.headers,
+  body: errorResponse,
+});
+```
+
+## Anti-Pattern
+
+```typescript
+// WRONG - exposes secrets, bypasses sanitization
+logger.debug(`Config: ${JSON.stringify(config)}`);
+logger.debug(`Calling ${url} with headers: ${JSON.stringify(headers)}`);
+```
+
+## Manual Sanitization
+
+For non-logging contexts:
+
+```typescript
+import { sanitizeObject } from './util/sanitizer';
+
+const sanitizedConfig = sanitizeObject(providerConfig, {
+  context: 'provider config',
+});
+```
+
+## What Gets Sanitized
+
+Field names containing (case-insensitive, works with `-`, `_`, camelCase):
+
+| Category     | Fields                                                                     |
+| ------------ | -------------------------------------------------------------------------- |
+| Passwords    | `password`, `passwd`, `pwd`, `passphrase`                                  |
+| API Keys     | `apiKey`, `api_key`, `token`, `accessToken`, `refreshToken`, `bearerToken` |
+| Secrets      | `secret`, `clientSecret`, `webhookSecret`                                  |
+| Headers      | `authorization`, `cookie`, `x-api-key`, `x-auth-token`                     |
+| Certificates | `privateKey`, `certificatePassword`, `keystorePassword`                    |
+| Signatures   | `signature`, `sig`, `signingKey`                                           |
+
+See `src/util/sanitizer.ts` for the complete list.