@od-oneapp/security 2026.1.1301

package/src/server-next.ts

@@ -0,0 +1,347 @@
+/**
+ * @fileoverview Server-side security exports for Next.js
+ *
+ * This file provides server-side security functionality specifically for Next.js applications.
+ * Includes Arcjet integration for bot detection, rate limiting, and Shield protection.
+ *
+ * Features:
+ * - Bot detection and filtering
+ * - Rate limiting
+ * - Shield protection against common attacks
+ * - Security denial error handling
+ *
+ * @module @od-oneapp/security/server/next
+ */
+
+import {
+  arcjet,
+  type ArcjetBotCategory,
+  type ArcjetWellKnownBot,
+  detectBot,
+  request,
+  shield,
+} from '@integrations/arcjet/security-client';
+
+import { getLogger, safeEnv } from '../env';
+
+import type { NextRequest } from 'next/server';
+import 'server-only';
+
+// Re-export server functionality (explicit exports to avoid circular dependencies)
+export { createRateLimiter, env, safeEnv } from './server';
+
+// Re-export rate limiting functionality
+export {
+  applyRateLimit,
+  fixedWindow,
+  getRateLimitInfo,
+  hashIdentifier,
+  isRateLimited,
+  rateLimitConfigs,
+  rateLimiters,
+  slidingWindow,
+  tokenBucket,
+  type RateLimitResult,
+} from '../rate-limit';
+
+// Re-export middleware utilities for Next.js
+export { noseconeMiddleware, noseconeOptions } from '../middleware';
+
+// Re-export environment helpers
+export { getLogger, hasArcjetConfig, hasUpstashConfig, isProduction, setLogger } from '../env';
+
+/**
+ * Custom error class for security denials.
+ *
+ * @remarks
+ * Thrown when a request is denied by Arcjet security checks (bot detection,
+ * rate limiting, or Shield protection). Includes detailed metadata for logging
+ * and debugging. The `reason` field indicates the type of denial, allowing
+ * for specific error handling logic.
+ *
+ * **Denial Reasons**:
+ * - `'bot'`: Request was identified as a bot and blocked
+ * - `'rate_limit'`: Request exceeded rate limits
+ * - `'shield'`: Request triggered Shield protection (malicious pattern detected)
+ * - `'unknown'`: Request was denied for an unspecified reason
+ *
+ * **Metadata Fields**:
+ * - `ip`: Client IP address (useful for blocking/whitelisting)
+ * - `path`: Request path (useful for route-specific logging)
+ * - `userAgent`: User agent string (useful for bot identification)
+ * - `decisionId`: Arcjet decision ID (useful for support/debugging)
+ *
+ * @example
+ * ```typescript
+ * import { secure, SecurityDenialError } from '@od-oneapp/security/server/next';
+ *
+ * try {
+ *   await secure([], request); // Block all bots
+ * } catch (error) {
+ *   if (error instanceof SecurityDenialError) {
+ *     console.log(`Denied: ${error.reason}`, error.metadata);
+ *     return new Response('Access denied', { status: 403 });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Handle specific denial reasons
+ * catch (error) {
+ *   if (error instanceof SecurityDenialError) {
+ *     if (error.reason === 'rate_limit') {
+ *       return new Response('Too many requests', { status: 429 });
+ *     }
+ *     return new Response('Forbidden', { status: 403 });
+ *   }
+ * }
+ * ```
+ */
+export class SecurityDenialError extends Error {
+  /**
+   * Creates a new SecurityDenialError.
+   *
+   * @param message - Human-readable error message
+   * @param reason - Type of security denial
+   * @param metadata - Optional metadata about the denied request
+   */
+  constructor(
+    message: string,
+    public readonly reason: 'bot' | 'rate_limit' | 'shield' | 'unknown',
+    public readonly metadata?: {
+      /** Client IP address. */
+      ip?: string;
+      /** Request path. */
+      path?: string;
+      /** User agent string. */
+      userAgent?: string;
+      /** Arcjet decision ID for debugging. */
+      decisionId?: string;
+    },
+  ) {
+    super(message);
+    this.name = 'SecurityDenialError';
+  }
+}
+
+/**
+ * Secure a request using Arcjet bot detection and Shield protection.
+ *
+ * @remarks
+ * This function provides comprehensive security protection for Next.js routes:
+ * - **Bot Detection**: Blocks or allows bots based on the `allow` parameter
+ * - **Shield Protection**: Protects against common attacks (SQL injection, XSS, etc.)
+ * - **Rate Limiting**: Integrated rate limiting via Arcjet Shield
+ *
+ * The function uses Arcjet's decision system to evaluate requests. If a request
+ * is denied, a `SecurityDenialError` is thrown with detailed metadata for logging.
+ *
+ * **Error Handling**:
+ * - Network errors in development allow requests through with warnings (fail-open)
+ * - Non-network errors and all production errors fail closed for security
+ * - Detailed error logging helps debug configuration issues
+ *
+ * **Performance**: This function makes an external API call to Arcjet, so it
+ * adds latency. Consider caching decisions for high-traffic routes.
+ *
+ * @param allow - Array of bot categories or well-known bots to allow.
+ * Use empty array to block all bots. Common values:
+ * - `'GOOGLEBOT'`, `'BINGBOT'` for search engines
+ * - `'FACEBOOKBOT'`, `'TWITTERBOT'` for social media crawlers
+ * - `'AUTOMATED'` for all automated bots
+ * @param sourceRequest - Optional Next.js request object. If not provided,
+ * will use Arcjet's request() helper to get the current request.
+ * @returns Promise that resolves if request is allowed
+ * @throws {SecurityDenialError} If request is denied (bot, rate limit, or shield protection)
+ * @throws {Error} If security check fails in production or for non-network errors in development
+ *
+ * @example
+ * ```typescript
+ * // Allow only Google and Bing bots
+ * await secure(['GOOGLEBOT', 'BINGBOT'], request);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Block all bots
+ * await secure([], request);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In a Next.js API route handler
+ * import { secure } from '@od-oneapp/security/server/next';
+ * import { NextRequest } from 'next/server';
+ *
+ * export async function POST(request: NextRequest) {
+ *   try {
+ *     await secure([], request); // Block all bots
+ *     // Process request...
+ *   } catch (error) {
+ *     if (error instanceof SecurityDenialError) {
+ *       return Response.json(
+ *         { error: 'Access denied' },
+ *         { status: 403 }
+ *       );
+ *     }
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+export const secure = async (
+  allow: (ArcjetBotCategory | ArcjetWellKnownBot)[],
+  sourceRequest?: NextRequest | Request,
+): Promise<void> => {
+  const env = safeEnv();
+  const arcjetKey = env.ARCJET_KEY;
+
+  if (!arcjetKey) {
+    return;
+  }
+
+  try {
+    const base = arcjet({
+      // Identify the user by their IP address
+      characteristics: ['ip.src'],
+      // Get your site key from https://app.arcjet.com
+      key: arcjetKey,
+      rules: [
+        // Protect against common attacks with Arcjet Shield
+        shield({
+          // Will block requests. Use "DRY_RUN" to log only
+          mode: 'LIVE',
+        }),
+        // Other rules are added in different routes
+      ],
+    });
+
+    const req = sourceRequest ?? (await request());
+    const aj = base.withRule(detectBot({ allow, mode: 'LIVE' }));
+    const decision = await aj.protect(req);
+
+    if (decision.isDenied()) {
+      // Extract metadata for logging
+      const getIp = (request: NextRequest | Request): string => {
+        if ('ip' in request && request.ip && typeof request.ip === 'string') {
+          return request.ip;
+        }
+        const headers = 'headers' in request ? request.headers : null;
+        if (headers && typeof headers.get === 'function') {
+          const forwardedFor = headers.get('x-forwarded-for');
+          if (forwardedFor) {
+            return forwardedFor.split(',')[0]?.trim() ?? 'unknown';
+          }
+        }
+        return 'unknown';
+      };
+
+      const getHeader = (name: string): string => {
+        const headers = 'headers' in req ? req.headers : null;
+        if (headers && typeof headers.get === 'function') {
+          return headers.get(name) ?? 'unknown';
+        }
+        return 'unknown';
+      };
+
+      const metadata = {
+        ip: getIp(req as NextRequest | Request),
+        path: req.url ? new URL(req.url).pathname : 'unknown',
+        userAgent: getHeader('user-agent'),
+        decisionId: decision.id,
+      };
+
+      if (decision.reason.isBot()) {
+        throw new SecurityDenialError(
+          `Bot access denied: ${metadata.ip} attempted to access ${metadata.path}`,
+          'bot',
+          metadata,
+        );
+      }
+
+      if (decision.reason.isRateLimit()) {
+        throw new SecurityDenialError(
+          `Rate limit exceeded: ${metadata.ip} exceeded limits for ${metadata.path}`,
+          'rate_limit',
+          metadata,
+        );
+      }
+
+      if (decision.reason.isShield()) {
+        throw new SecurityDenialError(
+          `Shield protection triggered: ${metadata.ip} blocked from ${metadata.path}`,
+          'shield',
+          metadata,
+        );
+      }
+
+      throw new SecurityDenialError(
+        `Access denied: ${metadata.ip} denied access to ${metadata.path}`,
+        'unknown',
+        metadata,
+      );
+    }
+  } catch (error) {
+    if (error instanceof SecurityDenialError) {
+      getLogger().error('Arcjet protection denied request', {
+        error: error.message,
+        nodeEnv: env.NODE_ENV,
+        reason: error.reason,
+        decisionId: error.metadata?.decisionId,
+      });
+      throw error;
+    }
+
+    // Categorize error type for better handling
+    // Prefer robust error.code check (Node.js standard) before falling back to message matching
+    // This handles both Node.js network errors (with error.code) and fetch/Arcjet errors
+    // (which may only have error.message). The dual approach ensures we catch network failures
+    // reliably across different error sources.
+    //
+    // Note: In production, all errors result in fail-closed behavior for security.
+    // In development, only confirmed network errors allow requests through (with warnings).
+    // Non-network errors fail closed even in development to surface configuration issues early.
+    const isNetworkError =
+      error instanceof Error &&
+      (('code' in error &&
+        typeof (error as { code?: unknown }).code === 'string' &&
+        ((error as { code: string }).code === 'ECONNREFUSED' ||
+          (error as { code: string }).code === 'ETIMEDOUT' ||
+          (error as { code: string }).code === 'ENOTFOUND')) ||
+        // Fallback to message matching for fetch/Arcjet errors without error.code
+        error.message.includes('ECONNREFUSED') ||
+        error.message.includes('ETIMEDOUT') ||
+        error.message.includes('ENOTFOUND') ||
+        error.message.includes('fetch failed') ||
+        error.message.includes('network'));
+
+    const errorContext = {
+      error: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined,
+      nodeEnv: env.NODE_ENV,
+      errorType: isNetworkError ? 'network' : 'unknown',
+    };
+
+    getLogger().error('Arcjet protection failed', errorContext);
+
+    // In production, always fail closed for security
+    if (env.NODE_ENV === 'production') {
+      throw new Error('Security check failed. Request denied.');
+    }
+
+    // In development, fail closed for non-network errors
+    if (!isNetworkError) {
+      getLogger().warn('Failing closed in development for non-network error');
+      throw new Error('Security check failed. See logs for details.');
+    }
+
+    // Development + network error: allow with warning
+    getLogger().warn('Allowing request in development due to network error', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+};
+
+// Re-export Arcjet types for Next.js
+export type { ArcjetBotCategory, ArcjetWellKnownBot };

package/src/server.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Server-side security exports (non-Next.js)
+ *
+ * This file provides server-side security functionality for non-Next.js environments.
+ * For Next.js applications, use '@repo/security/server/next' instead.
+ *
+ * @module @repo/security/server
+ */
+
+// Re-export rate limiting functionality
+export { createRateLimiter } from '../rate-limit';
+
+// Re-export env helpers for server use
+export { env, safeEnv } from '../env';