securenow 7.6.7 → 7.6.8

package/docs/NEXTJS-WEBPACK-WARNINGS.md

@@ -1,267 +0,0 @@
-# Next.js Webpack Warnings - Fix Guide
-
-## The Problem
-
-When using SecureNow with Next.js, you might see webpack warnings like:
-
-```
-⚠ Critical dependency: the request of a dependency is an expression
-⚠ Module not found: Can't resolve '@opentelemetry/winston-transport'
-⚠ Module not found: Can't resolve '@opentelemetry/exporter-jaeger'
-```
-
-**Good news:** Your app still works! These are just webpack bundling warnings.
-
-**Why it happens:** OpenTelemetry instrumentations use dynamic `require()` statements that webpack can't analyze at build time. This is normal for Node.js server code but Next.js's bundler complains about it.
-
----
-
-## ✅ Solution 1: Suppress Warnings (Recommended)
-
-Add webpack configuration to suppress these warnings.
-
-### Step 1: Update your `next.config.js`
-
-```javascript
-const { getSecureNowWebpackConfig } = require('securenow/nextjs-webpack-config');
-
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  webpack: (config, options) => {
-    return getSecureNowWebpackConfig(config, options);
-  },
-  
-  // Optional: Tell Next.js not to bundle OpenTelemetry packages
-  serverExternalPackages: [
-    '@opentelemetry/sdk-node',
-    '@opentelemetry/auto-instrumentations-node',
-  ],
-};
-
-module.exports = nextConfig;
-```
-
-### Step 2: Restart your dev server
-
-```bash
-npm run dev
-```
-
-**Done!** No more warnings. ✨
-
----
-
-## ✅ Solution 2: Manual Webpack Config
-
-If you already have custom webpack config:
-
-```javascript
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  webpack: (config, options) => {
-    if (options.isServer) {
-      // Suppress OpenTelemetry warnings
-      config.ignoreWarnings = config.ignoreWarnings || [];
-      config.ignoreWarnings.push(
-        {
-          module: /@opentelemetry\/instrumentation/,
-          message: /Critical dependency/,
-        },
-        {
-          module: /@opentelemetry/,
-          message: /Module not found.*winston-transport/,
-        },
-        {
-          module: /@opentelemetry/,
-          message: /Module not found.*exporter-jaeger/,
-        }
-      );
-    }
-    
-    // Your other webpack config
-    return config;
-  },
-};
-
-module.exports = nextConfig;
-```
-
----
-
-## ✅ Solution 3: Disable Problematic Instrumentations
-
-If you don't need certain instrumentations, disable them:
-
-```typescript
-// instrumentation.ts
-import { registerSecureNow } from 'securenow/nextjs';
-
-export function register() {
-  registerSecureNow({
-    disableInstrumentations: [
-      'winston',      // Winston logger (optional)
-      'bunyan',       // Bunyan logger (optional)
-      'pino',         // Pino logger (optional)
-      'fs',           // File system (too noisy)
-    ],
-  });
-}
-```
-
----
-
-## 📋 Understanding the Warnings
-
-### "Critical dependency" warnings
-
-**What it means:** OpenTelemetry uses `require(moduleName)` where `moduleName` is a variable. Webpack can't analyze this statically.
-
-**Is it a problem?** No! These modules are only loaded at runtime on the server, not in the browser.
-
-**Solution:** Suppress the warnings using webpack config.
-
-### "Module not found" warnings
-
-**What it means:** Some instrumentations have optional peer dependencies that aren't installed.
-
-**Is it a problem?** No! These are optional. If you're not using Winston logging or Jaeger exporter, you don't need them.
-
-**Solution:** Either:
-1. Suppress the warnings (recommended)
-2. Disable those instrumentations
-3. Install the missing packages (only if you use them)
-
----
-
-## 🔧 Advanced: serverExternalPackages
-
-For Next.js 13+, you can tell Next.js not to bundle certain packages:
-
-```javascript
-const nextConfig = {
-  serverExternalPackages: [
-    '@opentelemetry/sdk-node',
-    '@opentelemetry/auto-instrumentations-node',
-    '@opentelemetry/instrumentation',
-  ],
-};
-```
-
-This tells Next.js to leave these packages as `require()` statements instead of bundling them.
-
----
-
-## 📦 Complete Example
-
-Here's a complete `next.config.js` that handles everything:
-
-```javascript
-const { getSecureNowWebpackConfig } = require('securenow/nextjs-webpack-config');
-
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  // Suppress warnings
-  webpack: (config, options) => {
-    return getSecureNowWebpackConfig(config, options);
-  },
-  
-  // Don't bundle OpenTelemetry
-  serverExternalPackages: [
-    '@opentelemetry/sdk-node',
-    '@opentelemetry/auto-instrumentations-node',
-  ],
-};
-
-module.exports = nextConfig;
-```
-
----
-
-## ❓ FAQ
-
-### Q: Will these warnings affect my production build?
-
-**A:** No. Your production build will work fine. These are just webpack warnings, not errors.
-
-### Q: Should I be concerned about these warnings?
-
-**A:** No. They're expected when using Node.js instrumentation in Next.js. Just suppress them using the webpack config.
-
-### Q: Do I need to install the missing packages?
-
-**A:** Only if you're actually using them. For example:
-- `@opentelemetry/winston-transport` - only if you use Winston logger
-- `@opentelemetry/exporter-jaeger` - only if you want to export to Jaeger
-
-### Q: Why doesn't SecureNow bundle these packages?
-
-**A:** OpenTelemetry instrumentations are designed for Node.js server environments and use features that don't work in bundled code (like dynamic requires and module patching).
-
-### Q: Can I use SecureNow without these warnings?
-
-**A:** Yes! Use the webpack config provided above to suppress them.
-
----
-
-## 🎯 Quick Fix (Copy-Paste)
-
-**Just add this to your `next.config.js`:**
-
-```javascript
-const { getSecureNowWebpackConfig } = require('securenow/nextjs-webpack-config');
-
-module.exports = {
-  webpack: getSecureNowWebpackConfig,
-};
-```
-
-**That's it!** ✅
-
----
-
-## 🆘 Still Having Issues?
-
-If you're still seeing warnings after applying the fix:
-
-1. **Restart your dev server completely**
-   ```bash
-   # Stop the server (Ctrl+C)
-   # Clear Next.js cache
-   rm -rf .next
-   # Start again
-   npm run dev
-   ```
-
-2. **Check your Next.js version**
-   ```bash
-   npm list next
-   ```
-   - Next.js 15+ works best
-   - Next.js 14 and below need `experimentalInstrumentationHook: true`
-
-3. **Verify webpack config is loading**
-   - Check that `next.config.js` is in your project root
-   - Make sure it's a `.js` file (not `.mjs` or `.ts`)
-
-4. **Check for conflicting webpack config**
-   - If you have other webpack plugins, they might conflict
-   - Try the SecureNow config alone first
-
----
-
-## 📚 More Help
-
-- [Next.js Webpack Documentation](https://nextjs.org/docs/app/api-reference/next-config-js/webpack)
-- [OpenTelemetry Next.js Guide](./NEXTJS-GUIDE.md)
-- [SecureNow Documentation](./README.md)
-
----
-
-**TL;DR:** Add webpack config to suppress warnings. Your app works fine, the warnings are just noise from webpack trying to analyze Node.js server code.
-
-
-
-
-
-
-

package/docs/NEXTJS-WRAPPER-APPROACH.md

@@ -1,414 +0,0 @@
-# ✅ Next.js Body Capture - Non-Invasive Wrapper Approach
-
-## 🎯 The Problem with Middleware
-
-**Middleware runs BEFORE your handlers** and can:
-- ❌ Conflict with NextAuth and other middleware
-- ❌ Block requests from reaching handlers
-- ❌ Cause "Response body disturbed or locked" errors
-- ❌ Interfere with routing
-
-## ✅ The Solution: Handler Wrappers
-
-**Wrappers run INSIDE your handlers** and:
-- ✅ Never conflict with middleware
-- ✅ Never block requests
-- ✅ Run after all routing is complete
-- ✅ Optional per-route (only wrap what you need)
-- ✅ Non-invasive and safe
-
----
-
-## 🚀 Quick Start
-
-### Step 1: Enable in Environment
-
-```bash
-# .env.local
-SECURENOW_CAPTURE_BODY=1
-```
-
-### Step 2: Wrap Your API Routes
-
-```typescript
-// app/api/login/route.ts
-import { withSecureNow } from 'securenow/nextjs-wrapper';
-
-export const POST = withSecureNow(async (request: Request) => {
-  const body = await request.json();
-  // Your handler code...
-  return Response.json({ success: true });
-});
-```
-
-**That's it!** Body is captured with sensitive fields redacted.
-
----
-
-## 📊 How It Works
-
-### Traditional Middleware (Problematic)
-
-```
-Request → Middleware (reads body) → Conflicts → Handler (may not receive)
-          ❌ Can block/interfere
-```
-
-### Wrapper Approach (Safe)
-
-```
-Request → All Middleware → Routing → Handler (your code)
-                                      ↓
-                                  Wrapper captures body in background
-                                      ↓
-                                  Response returned
-          ✅ Never blocks or interferes
-```
-
-**Key difference:** The wrapper runs INSIDE your handler, not before it!
-
----
-
-## 🎓 Usage Examples
-
-### Basic Usage
-
-```typescript
-import { withSecureNow } from 'securenow/nextjs-wrapper';
-
-export const POST = withSecureNow(async (request: Request) => {
-  const data = await request.json();
-  return Response.json({ received: data });
-});
-```
-
-### With NextAuth (No Conflicts!)
-
-```typescript
-// middleware.ts - Your auth middleware (no securenow here!)
-import { getToken } from 'next-auth/jwt';
-
-export async function middleware(request) {
-  // Just your auth logic - no securenow interference
-  const token = await getToken({ req: request });
-  if (!token) {
-    return NextResponse.redirect('/login');
-  }
-  return NextResponse.next();
-}
-
-// app/api/protected/route.ts - Wrap individual routes
-import { withSecureNow } from 'securenow/nextjs-wrapper';
-
-export const POST = withSecureNow(async (request: Request) => {
-  // This runs AFTER middleware, so no conflicts!
-  const body = await request.json();
-  return Response.json({ success: true });
-});
-```
-
-### Selective Wrapping
-
-```typescript
-import { withSecureNow } from 'securenow/nextjs-wrapper';
-
-// Capture body for sensitive routes
-export const POST = withSecureNow(async (request: Request) => {
-  const body = await request.json();
-  return Response.json({ success: true });
-});
-
-// Don't capture for other routes
-export async function GET(request: Request) {
-  return Response.json({ data: 'public' });
-}
-```
-
-### With Context (Next.js 14+)
-
-```typescript
-import { withSecureNow } from 'securenow/nextjs-wrapper';
-
-export const POST = withSecureNow(async (
-  request: Request,
-  context: { params: { id: string } }
-) => {
-  const body = await request.json();
-  const { id } = context.params;
-  return Response.json({ id, body });
-});
-```
-
-### Pages Router (API Routes)
-
-```typescript
-import { withSecureNow } from 'securenow/nextjs-wrapper';
-
-async function handler(req, res) {
-  if (req.method === 'POST') {
-    // Your logic
-    res.json({ success: true });
-  }
-}
-
-export default withSecureNow(handler);
-```
-
----
-
-## 🔒 Security Features
-
-### Automatic Redaction
-
-**20+ sensitive fields redacted automatically:**
-```
-password, passwd, pwd, secret, token, api_key, apikey,
-access_token, auth, credentials, card, cvv, cvc, ssn, pin
-```
-
-**Example:**
-```typescript
-// Request body:
-{ "username": "john", "password": "secret123" }
-
-// Captured in trace:
-{ "username": "john", "password": "[REDACTED]" }
-```
-
-### Custom Sensitive Fields
-
-```bash
-# .env.local
-SECURENOW_SENSITIVE_FIELDS=email,phone,address
-```
-
-### Size Limits
-
-```bash
-# .env.local
-SECURENOW_MAX_BODY_SIZE=20480  # 20KB (default: 10KB)
-```
-
----
-
-## ⚡ Performance
-
-**Non-blocking design:**
-- Body capture runs in background
-- Handler returns immediately
-- < 1ms overhead
-- Fails silently (never breaks your app)
-
-**Overhead comparison:**
-```
-Without wrapper:     0ms baseline
-With wrapper:        < 1ms (async capture)
-Your handler logic:  Unchanged
-```
-
----
-
-## 🎯 When to Use
-
-### ✅ Use Wrapper When:
-- You want body capture on specific routes
-- You have NextAuth or other middleware
-- You want zero conflicts
-- You want per-route control
-
-### ❌ Don't Use When:
-- You don't need body capture
-- You only want basic tracing (already included!)
-
-**Remember:** Body capture is OPTIONAL. You get full tracing without it!
-
----
-
-## 📝 Complete Setup
-
-### 1. instrumentation.ts (Required for all tracing)
-
-```typescript
-import { registerSecureNow } from 'securenow/nextjs';
-
-export function register() {
-  registerSecureNow();
-}
-```
-
-### 2. .env.local
-
-```bash
-# Required
-SECURENOW_APPID=my-nextjs-app
-SECURENOW_INSTANCE=http://otel-collector:4318
-
-# Optional: Enable body capture
-SECURENOW_CAPTURE_BODY=1
-SECURENOW_MAX_BODY_SIZE=10240
-SECURENOW_SENSITIVE_FIELDS=custom_field
-```
-
-### 3. API Routes (Optional - only for body capture)
-
-```typescript
-import { withSecureNow } from 'securenow/nextjs-wrapper';
-
-export const POST = withSecureNow(async (request: Request) => {
-  const body = await request.json();
-  return Response.json({ success: true });
-});
-```
-
-### 4. middleware.ts (Your auth logic - no securenow!)
-
-```typescript
-// Just your regular middleware - no securenow imports needed!
-import { getToken } from 'next-auth/jwt';
-
-export async function middleware(request) {
-  // Your auth logic
-  const token = await getToken({ req: request });
-  if (!token) return NextResponse.redirect('/login');
-  return NextResponse.next();
-}
-```
-
----
-
-## 🎉 Benefits
-
-### No Middleware Conflicts
-- ✅ Works with NextAuth
-- ✅ Works with any middleware
-- ✅ Never interferes with routing
-- ✅ Runs after all middleware completes
-
-### Non-Blocking
-- ✅ Captures in background
-- ✅ Handler returns immediately
-- ✅ Never delays responses
-- ✅ Fails silently
-
-### Flexible
-- ✅ Per-route control
-- ✅ Wrap only what you need
-- ✅ Easy to add/remove
-- ✅ Works with App Router & Pages Router
-
-### Safe
-- ✅ Uses request.clone() (doesn't consume original)
-- ✅ Error handling (never crashes app)
-- ✅ Size limits (prevents memory issues)
-- ✅ Automatic redaction (protects sensitive data)
-
----
-
-## ❓ FAQ
-
-### Q: Do I need to change my middleware?
-
-**A:** No! Your middleware stays exactly as-is. The wrapper runs inside your handlers, not in middleware.
-
-### Q: Will this conflict with NextAuth?
-
-**A:** No! NextAuth runs in middleware, this runs in handlers. They never interact.
-
-### Q: What if I don't want body capture on all routes?
-
-**A:** Only wrap the routes you want! Other routes still get traced, just no body capture.
-
-### Q: Does this block my requests?
-
-**A:** No! The capture runs asynchronously in the background.
-
-### Q: What happens if capture fails?
-
-**A:** It fails silently. Your handler always executes normally.
-
-### Q: Can I use both middleware and wrapper?
-
-**A:** Use wrapper for Next.js (safe). Middleware is kept for backward compatibility but not recommended.
-
----
-
-## 🎯 Summary
-
-### Wrapper Approach (Recommended)
-```typescript
-// ✅ SAFE - Runs inside handler
-import { withSecureNow } from 'securenow/nextjs-wrapper';
-export const POST = withSecureNow(handler);
-```
-
-**Benefits:**
-- ✅ No middleware conflicts
-- ✅ No blocking
-- ✅ Per-route control
-- ✅ Works with NextAuth
-
-### Middleware Approach (Not Recommended for Next.js)
-```typescript
-// ❌ Can cause conflicts
-export { middleware } from 'securenow/nextjs-middleware';
-```
-
-**Issues:**
-- ❌ Conflicts with NextAuth
-- ❌ Can block requests
-- ❌ Runs before routing
-- ❌ All-or-nothing
-
----
-
-## 🚀 Migration Guide
-
-**If you're using middleware approach:**
-
-### Before (Middleware - Problematic)
-```typescript
-// middleware.ts
-import { middleware as securenowMiddleware } from 'securenow/nextjs-middleware';
-export async function middleware(request) {
-  await securenowMiddleware(request); // ❌ Can conflict
-  // Your auth logic...
-}
-```
-
-### After (Wrapper - Safe)
-```typescript
-// middleware.ts - Remove securenow completely!
-export async function middleware(request) {
-  // Just your auth logic - no securenow!
-}
-
-// app/api/*/route.ts - Add wrapper to individual routes
-import { withSecureNow } from 'securenow/nextjs-wrapper';
-export const POST = withSecureNow(async (request) => {
-  // Your handler
-});
-```
-
-**Result:** Zero conflicts, full control, no blocking!
-
----
-
-## ✅ Ready to Use!
-
-**The wrapper approach is:**
-- ✅ Production-ready
-- ✅ Conflict-free
-- ✅ Non-invasive
-- ✅ Self-sufficient
-
-**Your customers get:**
-- ✅ Full tracing (always)
-- ✅ Optional body capture (per route)
-- ✅ No code changes needed (except wrapping routes)
-- ✅ Works with any middleware
-
-**Status: Recommended for all Next.js apps!** 🎊
-
-
-
-