securenow 7.6.7 → 7.6.8

package/docs/AUTO-BODY-CAPTURE.md

@@ -1,412 +0,0 @@
-# 🚀 Automatic Body Capture - Zero Code Changes!
-
-## ✨ The Easiest Way (Recommended!)
-
-**Your customers don't need to wrap handlers or change any code!**
-
----
-
-## 🎯 Quick Start (2 Lines!)
-
-### Step 1: Enable in .env.local
-
-```bash
-SECURENOW_CAPTURE_BODY=1
-```
-
-### Step 2: Add one import to instrumentation.ts
-
-```typescript
-import { registerSecureNow } from 'securenow/nextjs';
-import 'securenow/nextjs-auto-capture'; // ← Add this line!
-
-export function register() {
-  registerSecureNow();
-}
-```
-
-**That's it!** 🎉 All request bodies are now captured automatically!
-
-**No wrapping, no middleware, no handler changes needed!**
-
----
-
-## ✅ How It Works
-
-### Automatic Patching
-
-When you import `securenow/nextjs-auto-capture`, it automatically patches Next.js's Request object to:
-
-1. **Cache body text** when `.text()`, `.json()`, or `.formData()` is called
-2. **Capture for tracing** in the background
-3. **Redact sensitive fields** automatically
-4. **Never interfere** with your handlers
-
-### Your Code Stays Unchanged
-
-```typescript
-// app/api/login/route.ts
-// NO CHANGES NEEDED!
-
-export async function POST(request: Request) {
-  const body = await request.json(); // ← Auto-captured here!
-  
-  // Your logic...
-  
-  return Response.json({ success: true });
-}
-```
-
-**The body is automatically captured when you call `.json()`!**
-
----
-
-## 🔒 Security (Built-In)
-
-### Automatic Redaction
-
-**20+ sensitive fields redacted by default:**
-```
-password, passwd, pwd, secret, token, api_key, apikey,
-access_token, auth, credentials, card, cvv, cvc, ssn, pin
-```
-
-**Example:**
-```json
-// Request body:
-{"email": "john@example.com", "password": "secret123"}
-
-// Captured in trace:
-{"email": "john@example.com", "password": "[REDACTED]"}
-```
-
-### Custom Sensitive Fields
-
-```bash
-# .env.local
-SECURENOW_SENSITIVE_FIELDS=credit_card,phone,ssn
-```
-
-### Size Limits
-
-```bash
-# .env.local
-SECURENOW_MAX_BODY_SIZE=20480  # 20KB (default: 10KB)
-```
-
----
-
-## 📊 What Gets Captured
-
-### ✅ JSON Requests
-
-```typescript
-export async function POST(request: Request) {
-  const body = await request.json(); // ← Auto-captured!
-  return Response.json({ success: true });
-}
-```
-
-### ✅ GraphQL Requests
-
-```typescript
-export async function POST(request: Request) {
-  const { query, variables } = await request.json(); // ← Auto-captured!
-  return Response.json({ data: executeQuery(query) });
-}
-```
-
-### ✅ Form Data
-
-```typescript
-export async function POST(request: Request) {
-  const formData = await request.formData(); // ← Auto-captured!
-  return Response.json({ received: true });
-}
-```
-
-### ✅ Text Bodies
-
-```typescript
-export async function POST(request: Request) {
-  const text = await request.text(); // ← Auto-captured!
-  return Response.json({ length: text.length });
-}
-```
-
----
-
-## 🎯 Benefits
-
-### Zero Code Changes
-- ✅ No wrapping needed
-- ✅ No middleware to configure
-- ✅ Handlers stay exactly as-is
-- ✅ Just one import line!
-
-### Safe & Non-Invasive
-- ✅ Patches Request prototype safely
-- ✅ Caches body text (readable multiple times)
-- ✅ Captures in background (non-blocking)
-- ✅ Fails silently (never breaks app)
-
-### Works Everywhere
-- ✅ App Router & Pages Router
-- ✅ All HTTP methods (POST/PUT/PATCH)
-- ✅ All content types (JSON, GraphQL, Form)
-- ✅ With NextAuth and any middleware
-
-### Automatic Security
-- ✅ 20+ sensitive fields redacted
-- ✅ Custom fields supported
-- ✅ Size limits enforced
-- ✅ Production-ready
-
----
-
-## 🎓 Complete Setup Example
-
-### instrumentation.ts
-
-```typescript
-import { registerSecureNow } from 'securenow/nextjs';
-import 'securenow/nextjs-auto-capture'; // ← Enable auto-capture
-
-export function register() {
-  registerSecureNow();
-}
-```
-
-### .env.local
-
-```bash
-# Required
-SECURENOW_APPID=my-nextjs-app
-SECURENOW_INSTANCE=http://otel-collector:4318
-
-# Enable auto-capture
-SECURENOW_CAPTURE_BODY=1
-
-# Optional
-SECURENOW_MAX_BODY_SIZE=10240
-SECURENOW_SENSITIVE_FIELDS=custom_field
-```
-
-### API Routes (No Changes!)
-
-```typescript
-// app/api/login/route.ts
-export async function POST(request: Request) {
-  const { email, password } = await request.json();
-  // Your auth logic...
-  return Response.json({ success: true });
-}
-
-// app/api/register/route.ts
-export async function POST(request: Request) {
-  const formData = await request.formData();
-  // Your registration logic...
-  return Response.json({ registered: true });
-}
-
-// app/api/graphql/route.ts
-export async function POST(request: Request) {
-  const { query } = await request.json();
-  // Your GraphQL logic...
-  return Response.json({ data: result });
-}
-```
-
-**All bodies automatically captured with sensitive data redacted!**
-
----
-
-## 💡 How Patching Works
-
-### The Magic
-
-```javascript
-// Before patching:
-Request.prototype.json = async function() {
-  // Read and parse body
-  return JSON.parse(await this.text());
-}
-
-// After patching (automatic):
-Request.prototype.json = async function() {
-  const text = await this.text(); // ← Cached!
-  // Body is captured here for tracing
-  return JSON.parse(text);
-}
-```
-
-**Benefits:**
-- Body text is cached (can be read multiple times)
-- Capture happens automatically when you call `.json()`
-- Your code doesn't change at all
-- Works with any handler pattern
-
----
-
-## ⚡ Performance
-
-**Overhead:**
-- First call to `.json()`: < 1ms (patch + cache)
-- Subsequent calls: 0ms (uses cache)
-- Capture: Async, non-blocking
-- Memory: Body text cached once, then GC'd
-
-**Impact:**
-- ✅ Negligible performance impact
-- ✅ Non-blocking design
-- ✅ Production-ready
-
----
-
-## 🔄 Comparison with Other Approaches
-
-| Approach | Code Changes | Middleware Conflicts | Setup Complexity |
-|----------|--------------|---------------------|------------------|
-| **Auto-Capture** | ✅ None | ✅ None | ✅ 1 import line |
-| Wrapper | ⚠️ Wrap each route | ✅ None | ⚠️ Per-route |
-| Middleware | ✅ None | ❌ Possible | ⚠️ Matcher config |
-
-**Auto-Capture wins!** Easiest setup, zero code changes, no conflicts.
-
----
-
-## ❓ FAQ
-
-### Q: Do I need to change my API routes?
-
-**A:** No! Keep them exactly as-is. The capture happens automatically when you call `.json()`, `.text()`, or `.formData()`.
-
-### Q: Will this conflict with NextAuth?
-
-**A:** No! This patches the Request object at a lower level. Your middleware stays completely untouched.
-
-### Q: What if I don't want to capture certain routes?
-
-**A:** The capture is automatic for all routes when enabled. If you need per-route control, use the wrapper approach instead. But for most users, capturing everything is fine (sensitive data is redacted anyway).
-
-### Q: Is this safe for production?
-
-**A:** Yes! The patching is:
-- Non-invasive (only caches body text)
-- Non-blocking (capture is async)
-- Fail-safe (errors don't break app)
-- Battle-tested (standard monkey-patching pattern)
-
-### Q: Can I still use request.json() multiple times?
-
-**A:** Yes! The body is cached, so you can call `.json()` multiple times safely.
-
-### Q: What happens if patching fails?
-
-**A:** It logs a warning and disables auto-capture. Your app continues to work normally with just tracing (no body capture).
-
----
-
-## 🎉 Success Story
-
-### Before (Wrapper Approach)
-
-```typescript
-// Had to wrap EVERY route
-import { withSecureNow } from 'securenow/nextjs-wrapper';
-
-export const POST = withSecureNow(async (request) => {
-  // handler
-});
-```
-
-**Pain points:**
-- ⚠️ Wrap 50+ routes
-- ⚠️ Easy to forget on new routes
-- ⚠️ More boilerplate
-
-### After (Auto-Capture)
-
-```typescript
-// instrumentation.ts - ONE TIME SETUP
-import 'securenow/nextjs-auto-capture';
-
-// ALL routes automatically capture bodies!
-export async function POST(request) {
-  // handler - no changes!
-}
-```
-
-**Benefits:**
-- ✅ One import for entire app
-- ✅ Never forget to capture
-- ✅ Zero boilerplate
-
----
-
-## 🚀 Migration Guide
-
-### From Wrapper Approach
-
-**Before:**
-```typescript
-// Every route
-import { withSecureNow } from 'securenow/nextjs-wrapper';
-export const POST = withSecureNow(handler);
-```
-
-**After:**
-```typescript
-// instrumentation.ts (once)
-import 'securenow/nextjs-auto-capture';
-
-// Routes (remove wrappers)
-export async function POST(request) {
-  // No wrapper needed!
-}
-```
-
-### From Middleware Approach
-
-**Before:**
-```typescript
-// middleware.ts
-export { middleware } from 'securenow/nextjs-middleware';
-```
-
-**After:**
-```typescript
-// middleware.ts - Delete securenow import!
-
-// instrumentation.ts
-import 'securenow/nextjs-auto-capture';
-```
-
----
-
-## ✅ Summary
-
-**Setup:**
-1. Add `SECURENOW_CAPTURE_BODY=1` to `.env.local`
-2. Add `import 'securenow/nextjs-auto-capture';` to `instrumentation.ts`
-
-**Result:**
-- ✅ All request bodies captured automatically
-- ✅ Sensitive fields redacted automatically
-- ✅ Zero code changes in handlers
-- ✅ No middleware conflicts
-- ✅ Production-ready
-
-**The easiest way to capture bodies in Next.js!** 🎊
-
----
-
-## 📚 See Also
-
-- `QUICKSTART-BODY-CAPTURE.md` - Quick setup guide
-- `NEXTJS-WRAPPER-APPROACH.md` - Manual wrapper approach (more control)
-- `NEXTJS-BODY-CAPTURE-COMPARISON.md` - Compare all approaches
-
-
-
-