@od-oneapp/security 2026.1.1301

package/README.md

@@ -0,0 +1,807 @@
+# @repo/security
+
+Comprehensive security infrastructure for Next.js and Node.js applications, providing rate limiting, bot detection, and
+security headers.
+
+## Package Information
+
+- **Can build:** NO (library package)
+- **Framework:** Next.js 16+ (optional), Node.js 22+
+- **Dependencies:** Arcjet, Nosecone, Upstash Redis
+
+## Exports
+
+The package uses conditional exports for framework-specific implementations:
+
+```typescript
+// Next.js Server-Side
+import { secure, createRateLimiter } from "@repo/security/server/next";
+
+// Generic Server-Side (Node.js, workers, etc.)
+import { createRateLimiter } from "@repo/security/server";
+
+// Next.js Client-Side (limited functionality)
+import { getSecurityHeaders } from "@repo/security/client/next";
+
+// Middleware (Next.js)
+import { noseconeMiddleware, noseconeOptions } from "@repo/security/middleware";
+
+// Environment utilities
+import { env, safeEnv } from "@repo/security/keys";
+```
+
+## Core Features
+
+### 🤖 Bot Detection (Arcjet)
+
+AI-powered bot detection with customizable allow/deny lists, Shield protection, and decision logging.
+
+### 🛡️ Security Headers (Nosecone)
+
+Production-ready security headers including CSP, HSTS, X-Frame-Options, and more.
+
+### ⏱️ Rate Limiting (Upstash)
+
+Distributed rate limiting with multiple strategies:
+
+- **Sliding Window**: Smooth rate limiting over rolling time windows
+- **Fixed Window**: Traditional rate limiting per fixed time period
+- **Token Bucket**: Burst handling with token refill
+
+### 🌍 Environment Aware
+
+Graceful degradation in development with production validation:
+
+- Development: Logs warnings, allows requests without configuration
+- Production: Fails closed, requires proper configuration
+
+## Quick Start
+
+### 1. Environment Setup
+
+Create a `.env` file with the following variables:
+
+```bash
+# Development (optional - graceful degradation without these)
+ARCJET_KEY=ajkey_test_xxxxxxxxxxxxx
+UPSTASH_REDIS_REST_URL=https://xxxxx.upstash.io
+UPSTASH_REDIS_REST_TOKEN=xxxxxxxxxx
+
+# Production (required for full functionality)
+ARCJET_KEY=ajkey_xxxxxxxxxxxxx
+UPSTASH_REDIS_REST_URL=https://xxxxx.upstash.io
+UPSTASH_REDIS_REST_TOKEN=xxxxxxxxxx
+```
+
+**Getting API Keys:**
+
+- Arcjet: https://app.arcjet.com
+- Upstash Redis: https://console.upstash.com
+
+### 2. Middleware Configuration (Next.js)
+
+Add security headers middleware to your Next.js application:
+
+```typescript
+// middleware.ts
+import { noseconeMiddleware, noseconeOptions } from "@repo/security/middleware";
+
+export const config = {
+  matcher: [
+    /*
+     * Match all request paths except:
+     * - _next/static (static files)
+     * - _next/image (image optimization files)
+     * - favicon.ico (favicon file)
+     */
+    "/((?!_next/static|_next/image|favicon.ico).*)"
+  ]
+};
+
+export default noseconeMiddleware(noseconeOptions);
+```
+
+### 3. API Route Protection
+
+Protect API routes with bot detection and rate limiting:
+
+```typescript
+// app/api/protected/route.ts
+import { secure, createRateLimiter } from "@repo/security/server/next";
+import { Ratelimit } from "@upstash/ratelimit";
+
+const limiter = createRateLimiter({
+  limiter: Ratelimit.slidingWindow(10, "1 m"),
+  prefix: "api:protected"
+});
+
+export async function POST(request: Request) {
+  // 1. Bot Detection - Allow only Google and Bing bots
+  await secure(["GOOGLEBOT", "BINGBOT"], request);
+
+  // 2. Rate Limiting - 10 requests per minute
+  const ip = request.headers.get("x-forwarded-for") ?? "unknown";
+  const result = await limiter.limit(`api:protected:${ip}`);
+
+  if (!result.success) {
+    return new Response("Too many requests", {
+      status: 429,
+      headers: {
+        "Retry-After": String(Math.ceil((result.reset - Date.now()) / 1000))
+      }
+    });
+  }
+
+  // 3. Process request
+  return Response.json({ success: true });
+}
+```
+
+## Detailed Usage
+
+### Bot Detection
+
+The `secure()` function provides Arcjet-powered bot detection with Shield protection.
+
+#### Allow Specific Bots
+
+```typescript
+import { secure } from "@repo/security/server/next";
+
+// Allow search engine crawlers
+await secure(["GOOGLEBOT", "BINGBOT", "DUCKDUCKBOT"], request);
+
+// Allow social media preview bots
+await secure(["FACEBOOKBOT", "TWITTERBOT", "LINKEDINBOT"], request);
+
+// Allow monitoring tools
+await secure(["MONITOR"], request); // Category: monitoring tools
+
+// Allow AI crawlers
+await secure(["AI"], request); // Category: AI scrapers
+```
+
+#### Block All Bots
+
+```typescript
+// Block all automated traffic
+await secure([], request);
+```
+
+#### Available Bot Categories
+
+**Individual Bots:**
+
+- `GOOGLEBOT` - Google search crawler
+- `BINGBOT` - Bing search crawler
+- `DUCKDUCKBOT` - DuckDuckGo crawler
+- `FACEBOOKBOT` - Facebook link preview
+- `TWITTERBOT` - Twitter card preview
+- `LINKEDINBOT` - LinkedIn preview
+- `SLACKBOT` - Slack link preview
+- `DISCORDBOT` - Discord embed preview
+
+**Categories:**
+
+- `CRAWLER` - All web crawlers
+- `PREVIEW` - Social media preview bots
+- `MONITOR` - Monitoring and uptime tools
+- `AI` - AI training scrapers
+- `SEO` - SEO analysis tools
+- `ARCHIVE` - Web archiving services
+
+#### Error Handling
+
+```typescript
+import { secure, SecurityDenialError } from "@repo/security/server/next";
+
+try {
+  await secure(["GOOGLEBOT"], request);
+  // Request is allowed
+} catch (error) {
+  if (error instanceof SecurityDenialError) {
+    console.error("Security denial:", {
+      reason: error.reason, // 'bot' | 'rate_limit' | 'shield' | 'unknown'
+      ip: error.metadata?.ip,
+      path: error.metadata?.path,
+      userAgent: error.metadata?.userAgent,
+      decisionId: error.metadata?.decisionId
+    });
+
+    return new Response("Access denied", { status: 403 });
+  }
+  throw error;
+}
+```
+
+### Rate Limiting
+
+#### Basic Usage
+
+```typescript
+import { applyRateLimit } from "@repo/security/server/next";
+
+// Apply rate limit using pre-configured limiter
+const ip = request.headers.get("x-forwarded-for") ?? "unknown";
+const result = await applyRateLimit(ip, "api");
+
+if (!result.success) {
+  return new Response("Too many requests", {
+    status: 429,
+    headers: {
+      "X-RateLimit-Limit": String(result.limit),
+      "X-RateLimit-Remaining": String(result.remaining),
+      "X-RateLimit-Reset": String(result.reset),
+      "Retry-After": String(Math.ceil((result.reset - Date.now()) / 1000))
+    }
+  });
+}
+```
+
+#### Pre-configured Rate Limiters
+
+The package provides pre-configured rate limiters for common use cases:
+
+```typescript
+import { rateLimiters } from "@repo/security/server/next";
+
+// API endpoints - 100 requests per minute
+const apiResult = await rateLimiters.api.limit(identifier);
+
+// Authentication - 5 attempts per 15 minutes
+const authResult = await rateLimiters.auth.limit(userId);
+
+// File uploads - 10 uploads per hour
+const uploadResult = await rateLimiters.upload.limit(userId);
+
+// Webhooks - 1000 requests per hour
+const webhookResult = await rateLimiters.webhook.limit(webhookId);
+
+// Search - 500 requests per minute
+const searchResult = await rateLimiters.search.limit(ip);
+```
+
+#### Custom Rate Limiters
+
+Create custom rate limiters with different strategies:
+
+```typescript
+import { createRateLimiter, slidingWindow, fixedWindow, tokenBucket } from "@repo/security/server/next";
+
+// Sliding window - 50 requests per 10 seconds
+const customLimiter = createRateLimiter({
+  limiter: slidingWindow(50, "10 s"),
+  prefix: "custom:api"
+});
+
+// Fixed window - 1000 requests per hour
+const hourlyLimiter = createRateLimiter({
+  limiter: fixedWindow(1000, "1 h"),
+  prefix: "hourly"
+});
+
+// Token bucket - 100 requests with 10 per second refill
+const burstLimiter = createRateLimiter({
+  limiter: tokenBucket(100, "10 s"),
+  prefix: "burst"
+});
+```
+
+#### Rate Limit Utilities
+
+```typescript
+import { applyRateLimit, isRateLimited, getRateLimitInfo } from "@repo/security/server/next";
+
+// Check if request should be blocked
+const isBlocked = await isRateLimited(identifier, "api");
+if (isBlocked) {
+  return new Response("Rate limited", { status: 429 });
+}
+
+// Get rate limit info without applying limits
+const info = await getRateLimitInfo(identifier, "api");
+console.log(`Remaining: ${info.remaining}/${info.limit}`);
+
+// Apply rate limit and get full result
+const result = await applyRateLimit(identifier, "api");
+console.log(result);
+// {
+//   success: true,
+//   limit: 100,
+//   remaining: 99,
+//   reset: 1234567890,
+//   retryAfter: undefined
+// }
+```
+
+### Security Headers
+
+Configure security headers via Nosecone middleware:
+
+```typescript
+// middleware.ts
+import { noseconeMiddleware } from "@repo/security/middleware";
+import type { NoseconeOptions } from "@nosecone/next";
+
+// Custom configuration
+const customOptions: NoseconeOptions = {
+  // Content Security Policy
+  contentSecurityPolicy: {
+    directives: {
+      defaultSrc: ["'self'"],
+      scriptSrc: ["'self'", "'unsafe-inline'"],
+      styleSrc: ["'self'", "'unsafe-inline'"],
+      imgSrc: ["'self'", "data:", "https:"],
+      fontSrc: ["'self'", "data:"],
+      connectSrc: ["'self'"],
+      frameSrc: ["'none'"]
+    }
+  },
+
+  // Strict Transport Security
+  strictTransportSecurity: {
+    maxAge: 31536000,
+    includeSubDomains: true,
+    preload: true
+  },
+
+  // X-Frame-Options
+  xFrameOptions: "DENY",
+
+  // X-Content-Type-Options
+  xContentTypeOptions: "nosniff",
+
+  // Referrer Policy
+  referrerPolicy: "strict-origin-when-cross-origin",
+
+  // Permissions Policy
+  permissionsPolicy: {
+    camera: ["none"],
+    microphone: ["none"],
+    geolocation: ["none"]
+  }
+};
+
+export default noseconeMiddleware(customOptions);
+```
+
+### Environment Management
+
+The package uses `@t3-oss/env-core` for type-safe environment variable validation:
+
+```typescript
+import { env, safeEnv, isProduction, hasArcjetConfig, hasUpstashConfig } from "@repo/security/keys";
+
+// Access validated environment variables
+console.log(env.ARCJET_KEY); // string | undefined
+console.log(env.NODE_ENV); // 'development' | 'test' | 'production'
+
+// Safe access (always returns object, no exceptions)
+const config = safeEnv();
+console.log(config.UPSTASH_REDIS_REST_URL);
+
+// Helper functions
+if (isProduction()) {
+  // Production-only logic
+}
+
+if (hasArcjetConfig()) {
+  // Arcjet is configured
+}
+
+if (hasUpstashConfig()) {
+  // Redis is configured
+}
+```
+
+### Custom Logger
+
+Replace the default logger with your own implementation:
+
+```typescript
+import { setLogger } from "@repo/security/keys";
+import pino from "pino";
+
+const logger = pino({
+  level: "info",
+  transport: {
+    target: "pino-pretty"
+  }
+});
+
+setLogger({
+  warn: (message, context) => logger.warn(context, message),
+  error: (message, context) => logger.error(context, message)
+});
+```
+
+## Architecture
+
+### Module Organization
+
+```
+@repo/security/
+├── src/
+│   ├── server.ts           # Generic server exports
+│   ├── server-next.ts      # Next.js server exports (Arcjet, rate limiting)
+│   ├── client.ts           # Generic client exports
+│   └── client-next.ts      # Next.js client exports
+├── env.ts                  # Environment variable validation
+├── rate-limit.ts           # Rate limiting logic (Upstash)
+├── middleware.ts           # Security headers middleware (Nosecone)
+└── __tests__/              # Test suites
+```
+
+### Dependency Graph
+
+```
+src/server-next.ts
+  ├─> env.ts                (environment validation)
+  ├─> rate-limit.ts         (rate limiting)
+  │   └─> env.ts
+  │   └─> @repo/db-upstash-redis/server
+  └─> middleware.ts         (security headers)
+      └─> @nosecone/next
+```
+
+### Design Principles
+
+1. **Graceful Degradation**: Works without configuration in development
+2. **Fail Closed**: Denies requests on errors in production
+3. **Framework Agnostic**: Core logic works with any framework
+4. **Type Safe**: Full TypeScript support with branded types
+5. **Observable**: Structured logging for monitoring
+
+## Edge Cases & Failure Scenarios
+
+### Missing Environment Variables
+
+**Development:**
+
+- Rate limiting: Returns no-op limiter, logs warning
+- Bot detection: Skips validation, allows all requests
+
+**Production:**
+
+- Rate limiting: Throws error on limiter creation
+- Bot detection: Throws error on validation failure
+
+### Redis Connection Failures
+
+**Development:**
+
+- Falls back to allowing requests
+- Logs error with context
+
+**Production:**
+
+- Denies requests (fail closed)
+- Returns 500 error
+
+### Arcjet API Failures
+
+**Development:**
+
+- Allows requests after logging error
+- Useful for local development
+
+**Production:**
+
+- Denies requests (fail closed)
+- Returns 403 error
+
+### Rate Limit Identifier Validation
+
+```typescript
+// Valid identifiers (alphanumeric, hyphens, underscores, colons, dots)
+await applyRateLimit("user-123", "api"); // ✓
+await applyRateLimit("192.168.1.1", "api"); // ✓
+await applyRateLimit("api:v1:users", "api"); // ✓
+
+// Invalid identifiers (contains special characters)
+await applyRateLimit("user@example.com", "api"); // ✗ Throws error
+await applyRateLimit("user/123", "api"); // ✗ Throws error
+
+// Too long (>255 characters)
+await applyRateLimit("a".repeat(256), "api"); // ✗ Throws error
+```
+
+## Common Patterns
+
+### Authenticated vs Anonymous Rate Limiting
+
+```typescript
+import { applyRateLimit } from "@repo/security/server/next";
+
+export async function POST(request: Request) {
+  const session = await getSession(request);
+
+  // Different rate limits for authenticated vs anonymous
+  const identifier = session?.userId
+    ? `user:${session.userId}`
+    : `ip:${request.headers.get("x-forwarded-for") ?? "unknown"}`;
+
+  const limiterType = session?.userId ? "api" : "auth";
+
+  const result = await applyRateLimit(identifier, limiterType);
+
+  if (!result.success) {
+    return new Response("Rate limit exceeded", { status: 429 });
+  }
+
+  // Process request
+}
+```
+
+### Progressive Rate Limiting
+
+```typescript
+import { createRateLimiter, slidingWindow } from "@repo/security/server/next";
+
+// Tier 1: 10 requests per minute (free tier)
+const freeLimiter = createRateLimiter({
+  limiter: slidingWindow(10, "1 m"),
+  prefix: "free"
+});
+
+// Tier 2: 100 requests per minute (pro tier)
+const proLimiter = createRateLimiter({
+  limiter: slidingWindow(100, "1 m"),
+  prefix: "pro"
+});
+
+// Tier 3: 1000 requests per minute (enterprise)
+const enterpriseLimiter = createRateLimiter({
+  limiter: slidingWindow(1000, "1 m"),
+  prefix: "enterprise"
+});
+
+export async function GET(request: Request) {
+  const user = await getUser(request);
+  const limiter = user.tier === "enterprise" ? enterpriseLimiter : user.tier === "pro" ? proLimiter : freeLimiter;
+
+  const result = await limiter.limit(`user:${user.id}`);
+  // ... handle result
+}
+```
+
+### Combined Protection
+
+```typescript
+import { secure, applyRateLimit, SecurityDenialError } from "@repo/security/server/next";
+
+export async function POST(request: Request) {
+  try {
+    // 1. Shield Protection (Arcjet)
+    await secure([], request); // Block all bots
+
+    // 2. Rate Limiting
+    const ip = request.headers.get("x-forwarded-for") ?? "unknown";
+    const result = await applyRateLimit(ip, "api");
+
+    if (!result.success) {
+      return new Response("Rate limit exceeded", {
+        status: 429,
+        headers: {
+          "Retry-After": String(Math.ceil((result.reset - Date.now()) / 1000))
+        }
+      });
+    }
+
+    // 3. Process request
+    return Response.json({ success: true });
+  } catch (error) {
+    if (error instanceof SecurityDenialError) {
+      // Log security event
+      console.error("Security denial:", error.metadata);
+
+      return new Response("Access denied", {
+        status: 403,
+        headers: {
+          "X-Denial-Reason": error.reason
+        }
+      });
+    }
+    throw error;
+  }
+}
+```
+
+### Rate Limit Headers
+
+```typescript
+import { getRateLimitInfo } from "@repo/security/server/next";
+
+export async function GET(request: Request) {
+  const ip = request.headers.get("x-forwarded-for") ?? "unknown";
+  const info = await getRateLimitInfo(ip, "api");
+
+  return new Response("OK", {
+    headers: {
+      "X-RateLimit-Limit": String(info.limit),
+      "X-RateLimit-Remaining": String(info.remaining),
+      "X-RateLimit-Reset": String(info.reset)
+    }
+  });
+}
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Run with coverage
+pnpm test:coverage
+
+# Generate coverage report
+pnpm coverage:collect
+```
+
+### Test Structure
+
+```typescript
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { applyRateLimit } from "@repo/security/server/next";
+
+describe("rate limiting", () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  it("should enforce rate limits", async () => {
+    const result = await applyRateLimit("test-user", "api");
+    expect(result.success).toBe(true);
+  });
+
+  it("should return retryAfter when limit exceeded", async () => {
+    // Exhaust rate limit
+    for (let i = 0; i < 100; i++) {
+      await applyRateLimit("test-user", "api");
+    }
+
+    const result = await applyRateLimit("test-user", "api");
+    expect(result.success).toBe(false);
+    expect(result.retryAfter).toBeGreaterThan(0);
+  });
+});
+```
+
+## Troubleshooting
+
+### Rate Limiting Not Working
+
+**Symptoms:** All requests are allowed, no rate limiting
+
+**Causes:**
+
+1. Redis not configured (check `UPSTASH_REDIS_REST_TOKEN` and `UPSTASH_REDIS_REST_URL`)
+2. Running in development mode (graceful degradation)
+3. Identifier is different for each request (check IP extraction)
+
+**Solution:**
+
+```typescript
+import { hasUpstashConfig } from "@repo/security/keys";
+
+if (!hasUpstashConfig()) {
+  console.error("Redis not configured - rate limiting disabled");
+}
+```
+
+### Bot Detection Not Blocking
+
+**Symptoms:** Bots are not being blocked
+
+**Causes:**
+
+1. Arcjet not configured (check `ARCJET_KEY`)
+2. Bot is in allow list
+3. Running in development mode
+
+**Solution:**
+
+```typescript
+import { hasArcjetConfig } from "@repo/security/keys";
+
+if (!hasArcjetConfig()) {
+  console.error("Arcjet not configured - bot detection disabled");
+}
+
+// Check bot allow list
+await secure([], request); // Empty array = block all bots
+```
+
+### Memory Leaks
+
+**Symptoms:** Server memory usage growing over time
+
+**Causes:**
+
+1. Rate limit info cache not being cleaned up
+2. Too many unique identifiers
+
+**Solution:**
+
+- Monitor cache size
+- Implement LRU cache with size limit
+- Use consistent identifier format
+
+## Performance Considerations
+
+### Rate Limiting Overhead
+
+- **Redis latency**: ~2-5ms per rate limit check
+- **Cache hit rate**: ~60-80% for typical usage
+- **Timeout**: 5 seconds (configurable)
+
+### Optimization Tips
+
+1. **Use cache**: `getRateLimitInfo()` caches for 1 second
+2. **Batch requests**: Check rate limit once per session
+3. **Use sliding window**: More efficient than token bucket
+4. **Pre-warm cache**: Prime cache on server start
+
+## Migration Guide
+
+### From v1 to v2
+
+**Breaking Changes:**
+
+1. `secure()` now throws `SecurityDenialError` instead of returning boolean
+2. Rate limiters require Redis configuration in production
+3. Environment variables must follow new validation schema
+
+**Migration Steps:**
+
+```typescript
+// Before (v1)
+const isAllowed = await secure(["GOOGLEBOT"], request);
+if (!isAllowed) {
+  return new Response("Denied", { status: 403 });
+}
+
+// After (v2)
+try {
+  await secure(["GOOGLEBOT"], request);
+} catch (error) {
+  if (error instanceof SecurityDenialError) {
+    return new Response("Denied", { status: 403 });
+  }
+  throw error;
+}
+```
+
+## Related Packages
+
+- `@repo/auth` - Authentication package (uses `@repo/security` for rate limiting)
+- `@repo/db-upstash-redis` - Shared Redis client
+- `@arcjet/next` - Arcjet Next.js SDK
+- `@nosecone/next` - Nosecone security headers
+- `@upstash/ratelimit` - Upstash rate limiting SDK
+
+## Additional Resources
+
+- [Arcjet Documentation](https://docs.arcjet.com)
+- [Nosecone Documentation](https://docs.arcjet.com/nosecone/quick-start)
+- [Upstash Rate Limiting](https://upstash.com/docs/oss/sdks/ts/ratelimit/overview)
+- [Security Best Practices](../../apps/docs/packages/security.mdx)
+
+## License
+
+Private package - not for external distribution.
+
+## 📚 Comprehensive Documentation
+
+For detailed documentation, see:
+
+- **[Audit Reports](../../apps/docs/content/docs/audits/security/)** - Comprehensive audits, fixes, and security reviews
+- **[Technical Guides](../../apps/docs/content/docs/packages/security/)** - Implementation guides and best practices
+
+All comprehensive documentation has been centralized in the docs app.