securenow 7.6.6 → 7.6.8

package/docs/AUTOMATIC-IP-CAPTURE.md

@@ -1,359 +0,0 @@
-# 📊 Automatic IP and Request Metadata Capture
-
-SecureNow automatically captures user IP addresses and detailed request metadata in your Next.js traces!
-
----
-
-## ✅ What Gets Captured Automatically
-
-### 🌐 Client Information
-- **IP Address** (`http.client_ip`)
-  - From `x-forwarded-for` (Vercel, most proxies)
-  - From `x-real-ip`
-  - From `cf-connecting-ip` (Cloudflare)
-  - From `x-client-ip`
-  - From socket `remoteAddress`
-
-### 📱 Request Details
-- **User Agent** (`http.user_agent`) - Browser/device info
-- **Referer** (`http.referer`) - Where the user came from
-- **Host** (`http.host`) - Your domain
-- **Scheme** (`http.scheme`) - http or https
-- **Request ID** (`http.request_id`) - Correlation ID if present
-
-### 🌍 Geographic Data (when available)
-- **Country** (`http.geo.country`)
-  - From Vercel: `x-vercel-ip-country`
-  - From Cloudflare: `cf-ipcountry`
-- **Region** (`http.geo.region`) - From `x-vercel-ip-country-region`
-- **City** (`http.geo.city`) - From `x-vercel-ip-city`
-
-### 📊 Response Data
-- **Status Code** (`http.status_code`) - 200, 404, 500, etc.
-
----
-
-## 🚀 Usage
-
-**No configuration needed!** Just use SecureNow:
-
-```typescript
-// instrumentation.ts
-import { registerSecureNow } from 'securenow/nextjs';
-
-export function register() {
-  registerSecureNow();
-}
-```
-
-That's it! All request metadata is automatically captured.
-
----
-
-## 📈 View in SecureNow
-
-In your SecureNow dashboard, you'll see these attributes on every span:
-
-```json
-{
-  "http.client_ip": "203.0.113.45",
-  "http.user_agent": "Mozilla/5.0...",
-  "http.referer": "https://google.com",
-  "http.host": "your-app.vercel.app",
-  "http.scheme": "https",
-  "http.status_code": 200,
-  "http.geo.country": "US",
-  "http.geo.region": "CA",
-  "http.geo.city": "San Francisco"
-}
-```
-
----
-
-## 🔍 Use Cases
-
-### 1. Debug Location-Specific Issues
-Filter traces by country/region to debug geographic problems:
-```
-http.geo.country = "JP" AND http.status_code >= 500
-```
-
-### 2. Track User Journey
-Follow a specific user through your app using IP:
-```
-http.client_ip = "203.0.113.45"
-```
-
-### 3. Monitor Bot Traffic
-Identify and filter bot requests:
-```
-http.user_agent CONTAINS "bot" OR http.user_agent CONTAINS "crawler"
-```
-
-### 4. Analyze Referer Sources
-See where your traffic comes from:
-```
-GROUP BY http.referer
-```
-
-### 5. Performance by Region
-Compare response times across regions:
-```
-AVG(duration) GROUP BY http.geo.country
-```
-
----
-
-## 🛠️ Customization
-
-### Option 1: Add More Attributes
-
-You can add custom attributes in your Next.js code:
-
-```typescript
-// In your API route or server component
-import { trace } from '@opentelemetry/api';
-
-export async function GET(request: Request) {
-  const span = trace.getActiveSpan();
-  
-  if (span) {
-    // Add custom attributes
-    span.setAttributes({
-      'user.id': getUserId(request),
-      'user.subscription': 'premium',
-      'request.path': new URL(request.url).pathname,
-    });
-  }
-  
-  // Your code...
-}
-```
-
-### Option 2: Disable Auto-Capture
-
-If you don't want automatic IP capture, you can use a simpler configuration:
-
-```typescript
-// instrumentation.ts
-import { registerSecureNow } from 'securenow/nextjs';
-
-export function register() {
-  // This will use the simple @vercel/otel default
-  // (no automatic IP capture)
-  process.env.SECURENOW_SIMPLE_MODE = '1';
-  registerSecureNow();
-}
-```
-
----
-
-## 🔒 Privacy Considerations
-
-### IP Address Handling
-
-**By default, SecureNow captures IP addresses.** Consider these privacy aspects:
-
-1. **GDPR Compliance**
-   - IP addresses are considered personal data under GDPR
-   - Ensure you have legal basis for processing
-   - Consider anonymizing IPs in some regions
-
-2. **Data Retention**
-   - Configure SecureNow retention policies
-   - Consider shorter retention for IP data
-
-3. **Anonymization Option**
-
-```typescript
-// Custom middleware to anonymize IPs
-import { trace } from '@opentelemetry/api';
-
-export function middleware(request: NextRequest) {
-  const span = trace.getActiveSpan();
-  
-  if (span) {
-    const ip = request.ip || 'unknown';
-    // Anonymize last octet: 203.0.113.45 → 203.0.113.0
-    const anonymized = ip.replace(/\.\d+$/, '.0');
-    span.setAttribute('http.client_ip', anonymized);
-  }
-  
-  return NextResponse.next();
-}
-```
-
----
-
-## 🎯 Examples
-
-### Example 1: Geographic Load Balancing Debugging
-
-**Problem:** Users in Asia report slow performance
-
-**Solution:** Query traces by region
-```
-http.geo.country IN ["JP", "CN", "KR"] 
-AND duration > 1000ms
-```
-
-### Example 2: Bot Detection
-
-**Problem:** Suspicious traffic patterns
-
-**Solution:** Filter by user agent
-```
-http.user_agent CONTAINS "bot" 
-OR http.user_agent CONTAINS "crawler"
-OR http.user_agent CONTAINS "spider"
-```
-
-### Example 3: Referer Analysis
-
-**Problem:** Want to track marketing campaigns
-
-**Solution:** Group by referer
-```
-http.referer CONTAINS "utm_source"
-GROUP BY http.referer
-```
-
-### Example 4: Rate Limiting Analysis
-
-**Problem:** Need to identify IPs hitting rate limits
-
-**Solution:** Track by IP and status
-```
-http.status_code = 429
-GROUP BY http.client_ip
-ORDER BY COUNT DESC
-```
-
----
-
-## 📊 Dashboard Queries
-
-### Top Countries by Traffic
-```sql
-SELECT 
-  http.geo.country,
-  COUNT(*) as requests,
-  AVG(duration) as avg_duration
-FROM spans
-WHERE http.geo.country IS NOT NULL
-GROUP BY http.geo.country
-ORDER BY requests DESC
-LIMIT 10
-```
-
-### Slowest Requests by Region
-```sql
-SELECT 
-  http.geo.country,
-  http.target,
-  MAX(duration) as max_duration
-FROM spans
-WHERE http.geo.country IS NOT NULL
-GROUP BY http.geo.country, http.target
-ORDER BY max_duration DESC
-LIMIT 20
-```
-
-### Error Rate by User Agent
-```sql
-SELECT 
-  http.user_agent,
-  COUNT(*) as total,
-  SUM(CASE WHEN http.status_code >= 400 THEN 1 ELSE 0 END) as errors,
-  (errors / total * 100) as error_rate
-FROM spans
-GROUP BY http.user_agent
-ORDER BY error_rate DESC
-LIMIT 10
-```
-
----
-
-## 🔧 Technical Details
-
-### How It Works
-
-1. **HttpInstrumentation** intercepts incoming HTTP requests
-2. **requestHook** extracts headers and metadata
-3. **Attributes** are added to the active span
-4. **Data flows** to SecureNow with the trace
-
-### Headers Priority
-
-IP address is extracted in this order:
-1. `x-forwarded-for` (first IP in list)
-2. `x-real-ip`
-3. `cf-connecting-ip` (Cloudflare)
-4. `x-client-ip`
-5. `socket.remoteAddress`
-
-### Performance Impact
-
-- **Minimal overhead:** < 1ms per request
-- **No blocking:** Runs async with request processing
-- **Fail-safe:** Errors don't break requests
-
----
-
-## ❓ FAQ
-
-### Q: Is this GDPR compliant?
-
-**A:** IP addresses are personal data. Ensure you:
-- Have legal basis (legitimate interest, consent, etc.)
-- Document in privacy policy
-- Configure appropriate retention
-- Consider anonymization for EU users
-
-### Q: Can I disable IP capture?
-
-**A:** Yes, use simple mode:
-```typescript
-process.env.SECURENOW_SIMPLE_MODE = '1';
-registerSecureNow();
-```
-
-### Q: Does this work on Edge Runtime?
-
-**A:** Currently only Node.js runtime is supported. Edge runtime support coming soon.
-
-### Q: What about bot traffic?
-
-**A:** Bot traffic is captured automatically. Filter using:
-```
-http.user_agent NOT CONTAINS "bot"
-```
-
-### Q: Can I capture custom headers?
-
-**A:** Yes! Use OpenTelemetry API:
-```typescript
-import { trace } from '@opentelemetry/api';
-
-const span = trace.getActiveSpan();
-span.setAttribute('custom.header', request.headers.get('x-custom'));
-```
-
----
-
-## 🎉 Summary
-
-SecureNow automatically captures:
-- ✅ IP addresses (multiple sources)
-- ✅ User agents
-- ✅ Referers
-- ✅ Geographic data (Vercel/Cloudflare)
-- ✅ Request/response metadata
-
-**Zero configuration required** - it just works!
-
-View everything in SecureNow for powerful analytics and debugging.
-
-
-
-

package/docs/BODY-CAPTURE-FIX.md

@@ -1,261 +0,0 @@
-# ✅ Body Capture Fix - Self-Sufficient Solution Complete!
-
-## 🐛 The Bug (FIXED!)
-
-**Error:** `TypeError: Response body object should not be disturbed or locked`
-
-**Cause:** Reading the HTTP request stream directly locks it, preventing Next.js from parsing the body.
-
-**Fix:** Use Next.js middleware with `request.clone()` instead of HTTP instrumentation hooks.
-
----
-
-## ✅ The Solution (100% Self-Sufficient!)
-
-### For Your Customers - Zero Code to Write!
-
-**Installation automatically creates everything:**
-
-```bash
-$ npm install securenow
-
-┌─────────────────────────────────────────────────┐
-│  🎉 SecureNow installed successfully!          │
-└─────────────────────────────────────────────────┘
-
-Would you like to automatically create instrumentation file? (Y/n) Y
-✅ Created instrumentation.ts
-
-Would you like to enable request body capture? (y/N) y  
-✅ Created middleware.ts
-   → Captures JSON, GraphQL, Form bodies with auto-redaction
-✅ Created .env.local template
-```
-
-**Files created (all by installer):**
-
-1. **instrumentation.ts**
-   ```typescript
-   import { registerSecureNow } from 'securenow/nextjs';
-   export function register() { registerSecureNow(); }
-   ```
-
-2. **middleware.ts** (if they choose body capture)
-   ```typescript
-   export { middleware } from 'securenow/nextjs-middleware';
-   export const config = { matcher: '/api/:path*' };
-   ```
-
-3. **.env.local**
-   ```bash
-   SECURENOW_APPID=my-app
-   SECURENOW_INSTANCE=http://otel-collector:4318
-   SECURENOW_CAPTURE_BODY=1
-   ```
-
-**Customer code written: 0 lines!** ✨
-
----
-
-## 🎯 Technical Fix
-
-### What Changed
-
-**Before (Broken):**
-```javascript
-// In nextjs.js - requestHook
-request.on('data', (chunk) => {
-  chunks.push(chunk);  // ❌ Locks stream
-});
-// → Next.js can't read → ERROR
-```
-
-**After (Fixed):**
-```javascript
-// In nextjs-middleware.js
-const cloned = request.clone();  // ✅ Clone first
-const body = await cloned.text();  // ✅ Read clone
-// → Original untouched → No error!
-```
-
-### New Files Created
-
-1. **nextjs-middleware.js** (part of package)
-   - Exports ready-to-use middleware
-   - All parsing/redaction logic included
-   - Uses `request.clone()` - safe!
-   - 150+ lines of logic customers don't write
-
-2. **examples/nextjs-middleware.ts** (.js)
-   - Show how to import
-   - Matcher configurations
-   - Best practices
-
-3. **NEXTJS-BODY-CAPTURE.md**
-   - Complete guide
-   - Examples
-   - Troubleshooting
-
-4. **Updated postinstall.js**
-   - Now offers to create middleware.ts
-   - Auto-creates with correct import
-   - Updates .env.local template
-
----
-
-## 🚀 Package Exports
-
-```json
-{
-  "exports": {
-    "./nextjs-middleware": "./nextjs-middleware.js"
-  }
-}
-```
-
-**Customers import:**
-```typescript
-export { middleware } from 'securenow/nextjs-middleware';
-```
-
-**Package provides:**
-- Middleware function
-- Redaction logic
-- Parsing logic
-- Size limits
-- Error handling
-
----
-
-## ✨ Self-Sufficient Design
-
-### What's in the Package
-
-✅ **nextjs-middleware.js** - Complete middleware implementation  
-✅ **Redaction logic** - 20+ sensitive fields  
-✅ **Parser** - JSON, GraphQL, Form  
-✅ **Size limits** - Configurable  
-✅ **Error handling** - Fail-safe  
-✅ **Type detection** - Auto-detect content type  
-
-### What Customer Does
-
-✅ **Re-export** - `export { middleware } from 'securenow/nextjs-middleware'`  
-✅ **Configure** - Add matcher config (which routes to apply to)  
-✅ **Enable** - Set `SECURENOW_CAPTURE_BODY=1`  
-
-**No logic to write!** Just configuration.
-
----
-
-## 🎓 Customer Experience
-
-### Automatic (Recommended)
-
-```bash
-npm install securenow
-# Press Y → Creates instrumentation.ts
-# Press Y → Creates middleware.ts
-# Edit .env.local → Set SECURENOW_CAPTURE_BODY=1
-# Run app → Bodies captured!
-```
-
-**Total time: 2 minutes**  
-**Lines of code: 0**
-
-### Manual (If they skip auto-setup)
-
-```bash
-npm install securenow
-npx securenow init  # Creates both files
-# Edit .env.local
-# Run app
-```
-
-**Total time: 3 minutes**  
-**Lines of code: 0**
-
-### Super Manual (If they want control)
-
-```bash
-npm install securenow
-
-# Create middleware.ts manually:
-echo 'export { middleware } from "securenow/nextjs-middleware";' > middleware.ts
-
-# Enable in .env.local
-# Run app
-```
-
-**Total time: 5 minutes**  
-**Lines of code: 1** (the export line)
-
----
-
-## 🎉 Result
-
-**The error is fixed AND the solution is self-sufficient!**
-
-✅ **No stream locking errors**  
-✅ **No code for customers to write**  
-✅ **All logic in package**  
-✅ **Installer creates files automatically**  
-✅ **Just configuration needed**  
-✅ **Works perfectly with Next.js**
-
-### Before Fix
-```
-Customer enables SECURENOW_CAPTURE_BODY=1
-→ Stream locked
-→ TypeError
-→ App broken ❌
-```
-
-### After Fix
-```
-Customer enables SECURENOW_CAPTURE_BODY=1
-Customer adds middleware (auto-created by installer)
-→ Request cloned
-→ Body captured
-→ Sensitive data redacted
-→ App works perfectly ✅
-```
-
----
-
-## 📦 Files Modified
-
-1. **nextjs.js** - Removed stream-consuming code
-2. **nextjs-middleware.js** - NEW! Complete middleware
-3. **postinstall.js** - Now offers middleware creation
-4. **package.json** - Added middleware export
-5. **examples/** - Added middleware examples
-6. **Documentation** - Added guides
-
----
-
-## ✅ Testing Checklist
-
-- [x] No linter errors
-- [x] Middleware uses request.clone()
-- [x] All logic in package
-- [x] Installer creates files
-- [x] Documentation complete
-- [x] Examples provided
-
----
-
-## 🚀 Status: READY TO SHIP!
-
-**The package is now:**
-- ✅ Self-sufficient (customers write 0 lines)
-- ✅ Bug-free (no stream locking)
-- ✅ Secure (auto-redaction)
-- ✅ Easy (installer creates files)
-- ✅ Flexible (env var configuration)
-
-**No more `Response body object should not be disturbed or locked` error!** 🎯
-
-
-
-