@tuturuuu/utils 0.0.2 → 0.6.0

package/src/abuse-protection/__tests__/reputation.test.ts

@@ -0,0 +1,192 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mockRpc = vi.fn();
+const mockCreateAdminClient = vi.fn(() => ({
+  rpc: mockRpc,
+}));
+
+vi.mock('@tuturuuu/supabase/next/server', () => ({
+  createAdminClient: () => mockCreateAdminClient(),
+}));
+
+import {
+  buildAbuseRiskSubjects,
+  resolveAbuseRiskDecision,
+} from '../reputation';
+
+const browserHeaders = {
+  cookie: 'sb-test-auth-token=stable-session-token',
+  'user-agent':
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36',
+};
+
+describe('adaptive abuse reputation', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-05-17T00:00:00.000Z'));
+    mockRpc.mockResolvedValue({ data: [], error: null });
+  });
+
+  it('does not earn trust from old account and browser shape alone', async () => {
+    const decision = await resolveAbuseRiskDecision({
+      authKind: 'session',
+      headers: browserHeaders,
+      ipAddress: '203.0.113.10',
+      isRead: true,
+      method: 'GET',
+      route: '/api/v1/workspaces/ws-1/tasks',
+      userCreatedAt: '2025-01-01T00:00:00.000Z',
+      userId: 'user-1',
+    });
+
+    expect(decision.tier).toBe('standard');
+    expect(decision.trustMultiplier).toBe(1);
+    expect(decision.reasons).toContain('established_account');
+  });
+
+  it('allows clean long-lived reputation to receive trusted limits', async () => {
+    mockRpc.mockResolvedValue({
+      data: [
+        {
+          decision_source: 'reputation',
+          subject_key: 'user:user-1',
+          tier: 'trusted',
+          trust_multiplier: 3,
+        },
+      ],
+      error: null,
+    });
+
+    const decision = await resolveAbuseRiskDecision({
+      authKind: 'session',
+      headers: browserHeaders,
+      ipAddress: '203.0.113.10',
+      isRead: true,
+      method: 'GET',
+      route: '/api/v1/workspaces/ws-1/tasks',
+      userCreatedAt: '2025-01-01T00:00:00.000Z',
+      userId: 'user-1',
+    });
+
+    expect(decision.tier).toBe('trusted');
+    expect(decision.trustMultiplier).toBe(3);
+    expect(decision.reasons).toContain('server_reputation_trusted');
+  });
+
+  it('suppresses trusted reputation when current browser mutation is scripted', async () => {
+    mockRpc.mockResolvedValue({
+      data: [
+        {
+          decision_source: 'reputation',
+          subject_key: 'user:user-1',
+          tier: 'trusted',
+          trust_multiplier: 3,
+        },
+      ],
+      error: null,
+    });
+
+    const decision = await resolveAbuseRiskDecision({
+      authKind: 'session',
+      headers: {
+        'user-agent': 'curl/8.7.1',
+      },
+      ipAddress: '203.0.113.10',
+      isRead: false,
+      method: 'POST',
+      route: '/api/v1/workspaces/ws-1/tasks',
+      userCreatedAt: '2025-01-01T00:00:00.000Z',
+      userId: 'user-1',
+    });
+
+    expect(decision.tier).toBe('challenge_required');
+    expect(decision.trustMultiplier).toBe(1);
+    expect(decision.reasons).toContain('scripted_http_client');
+    expect(decision.reasons).toContain('suspicious_browser_mutation');
+  });
+
+  it('keeps recent abuse restrictions stronger than account age', async () => {
+    mockRpc.mockResolvedValue({
+      data: [
+        {
+          decision_source: 'reputation',
+          subject_key: 'user:user-1',
+          tier: 'restricted',
+          trust_multiplier: 0.35,
+        },
+      ],
+      error: null,
+    });
+
+    const decision = await resolveAbuseRiskDecision({
+      authKind: 'session',
+      headers: browserHeaders,
+      ipAddress: '203.0.113.10',
+      isRead: true,
+      method: 'GET',
+      route: '/api/v1/workspaces/ws-1/tasks',
+      userCreatedAt: '2025-01-01T00:00:00.000Z',
+      userId: 'user-1',
+    });
+
+    expect(decision.tier).toBe('restricted');
+    expect(decision.trustMultiplier).toBe(0.35);
+    expect(decision.reasons).toContain('server_reputation_restricted');
+  });
+
+  it('builds API-key reputation subjects without browser challenge semantics', async () => {
+    mockRpc.mockResolvedValue({
+      data: [
+        {
+          decision_source: 'reputation',
+          subject_key: 'api-key:key-1',
+          tier: 'trusted',
+          trust_multiplier: 2,
+        },
+      ],
+      error: null,
+    });
+
+    const decision = await resolveAbuseRiskDecision({
+      apiKeyId: 'key-1',
+      authKind: 'api-key',
+      headers: {
+        'user-agent': 'Dart/3.9 (dart:io)',
+      },
+      ipAddress: '203.0.113.10',
+      isRead: false,
+      method: 'POST',
+      route: '/api/v1/workspaces/ws-1/tasks',
+      workspaceId: 'ws-1',
+    });
+
+    expect(decision.tier).toBe('trusted');
+    expect(decision.trustMultiplier).toBe(2);
+    expect(decision.subjects).toContainEqual({
+      subject_key: 'api-key:key-1',
+      subject_type: 'api_key',
+    });
+  });
+
+  it('tracks user, session, IP, CIDR, and user-location subjects together', () => {
+    expect(
+      buildAbuseRiskSubjects({
+        headers: browserHeaders,
+        ipAddress: '203.0.113.10',
+        userId: 'user-1',
+      })
+    ).toEqual(
+      expect.arrayContaining([
+        { subject_key: 'user:user-1', subject_type: 'user' },
+        { subject_key: 'ip:203.0.113.10', subject_type: 'ip' },
+        { subject_key: 'cidr:203.0.113.0/24', subject_type: 'cidr' },
+        {
+          subject_key: 'user-location:user-1:203.0.113.10',
+          subject_type: 'user_location',
+        },
+        expect.objectContaining({ subject_type: 'session' }),
+      ])
+    );
+  });
+});

package/src/abuse-protection/backend-rate-limit.ts

@@ -0,0 +1,44 @@
+import { blockIPEdge } from './edge';
+import type { BlockInfo } from './types';
+
+type BackendRateLimitSource = 'auth' | 'database';
+
+interface BackendRateLimitEscalationOptions {
+  endpoint?: string;
+  ipAddress?: string | null;
+  source: BackendRateLimitSource;
+  /**
+   * Deprecated/no-op. Backend 429s are shared availability signals, not enough
+   * evidence to create or extend a user suspension.
+   */
+  userId?: string | null;
+}
+
+interface BackendRateLimitErrorLike {
+  code?: string;
+  message?: string;
+  status?: number;
+}
+
+export function isBackendRateLimitError(
+  error: unknown
+): error is BackendRateLimitErrorLike {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+
+  const candidate = error as BackendRateLimitErrorLike;
+  return (
+    candidate.status === 429 ||
+    candidate.code === 'over_request_rate_limit' ||
+    (typeof candidate.message === 'string' &&
+      /request rate limit reached/i.test(candidate.message))
+  );
+}
+
+export async function cascadeBackendRateLimitToProxyBan({
+  ipAddress,
+}: BackendRateLimitEscalationOptions): Promise<BlockInfo | null> {
+  const shouldBlockIp = ipAddress && ipAddress !== 'unknown';
+  return shouldBlockIp ? blockIPEdge(ipAddress, 'api_abuse') : null;
+}

package/src/abuse-protection/constants.ts

@@ -0,0 +1,117 @@
+/**
+ * Configuration constants for OTP Abuse Protection System
+ */
+
+/**
+ * Rate limiting thresholds for different operations
+ */
+export const ABUSE_THRESHOLDS = {
+  // OTP Send limits
+  OTP_SEND_PER_MINUTE: 30,
+  OTP_SEND_PER_HOUR: 180,
+  OTP_SEND_PER_DAY: 300,
+  OTP_SEND_EMAIL_COOLDOWN_WINDOW_MS: 15 * 60 * 1000, // 15 minutes
+  OTP_SEND_EMAIL_PER_HOUR: 2,
+  OTP_SEND_EMAIL_PER_DAY: 4,
+
+  // OTP Verify limits (per IP)
+  OTP_VERIFY_FAILED_WINDOW_MS: 5 * 60 * 1000, // 5 minutes
+  OTP_VERIFY_FAILED_MAX: 5,
+
+  // OTP Verify limits (per email - distributed attack protection)
+  OTP_VERIFY_FAILED_EMAIL_WINDOW_MS: 15 * 60 * 1000, // 15 minutes
+  OTP_VERIFY_FAILED_EMAIL_MAX: 10,
+
+  // MFA limits
+  MFA_CHALLENGE_PER_MINUTE: 5,
+  MFA_VERIFY_FAILED_WINDOW_MS: 5 * 60 * 1000, // 5 minutes
+  MFA_VERIFY_FAILED_MAX: 5,
+
+  // Reauth limits
+  REAUTH_SEND_PER_MINUTE: 3,
+  REAUTH_VERIFY_FAILED_WINDOW_MS: 5 * 60 * 1000, // 5 minutes
+  REAUTH_VERIFY_FAILED_MAX: 5,
+
+  // Password login limits
+  PASSWORD_LOGIN_FAILED_WINDOW_MS: 5 * 60 * 1000, // 5 minutes
+  PASSWORD_LOGIN_FAILED_MAX: 10,
+
+  // API auth failure limits (session-auth routes)
+  API_AUTH_FAILED_WINDOW_MS: 5 * 60 * 1000, // 5 minutes
+  API_AUTH_FAILED_MAX: 20, // 20 failed auths in 5 min → auto-block IP
+
+  // Malformed session cookie abuse at the proxy/edge layer
+  MALFORMED_AUTH_COOKIE_WINDOW_MS: 60 * 1000, // 1 minute
+  MALFORMED_AUTH_COOKIE_MAX: 3, // 3 malformed-cookie hits in 1 min → block IP
+
+  // Generic suspicious anonymous API traffic at the proxy/edge layer
+  SUSPICIOUS_API_WINDOW_MS: 60 * 1000, // 1 minute
+  SUSPICIOUS_API_MAX: 3, // 3 suspicious proxy hits in 1 min → block IP
+} as const;
+
+/**
+ * Progressive block durations in seconds
+ * Level increases with repeated offenses within 24 hours
+ */
+export const BLOCK_DURATIONS: Record<1 | 2 | 3 | 4, number> = {
+  1: 5 * 60, // Level 1: 5 minutes
+  2: 15 * 60, // Level 2: 15 minutes
+  3: 60 * 60, // Level 3: 1 hour
+  4: 24 * 60 * 60, // Level 4: 24 hours
+} as const;
+
+/**
+ * Maximum block level
+ */
+export const MAX_BLOCK_LEVEL = 4;
+
+/**
+ * Redis key prefixes for rate limiting
+ */
+export const REDIS_KEYS = {
+  // OTP Send attempts per IP (sliding window)
+  OTP_SEND: (ip: string) => `otp:send:${ip}`,
+  OTP_SEND_HOURLY: (ip: string) => `otp:send:hourly:${ip}`,
+  OTP_SEND_DAILY: (ip: string) => `otp:send:daily:${ip}`,
+  OTP_SEND_EMAIL_COOLDOWN: (emailHash: string) =>
+    `otp:send:email:cooldown:${emailHash}`,
+  OTP_SEND_EMAIL_HOURLY: (emailHash: string) =>
+    `otp:send:email:hourly:${emailHash}`,
+  OTP_SEND_EMAIL_DAILY: (emailHash: string) =>
+    `otp:send:email:daily:${emailHash}`,
+
+  // OTP Verify failed attempts
+  OTP_VERIFY_FAILED: (ip: string) => `otp:verify:failed:${ip}`,
+  OTP_VERIFY_FAILED_EMAIL: (emailHash: string) =>
+    `otp:verify:failed:email:${emailHash}`,
+
+  // MFA attempts
+  MFA_CHALLENGE: (ip: string) => `mfa:challenge:${ip}`,
+  MFA_VERIFY_FAILED: (ip: string) => `mfa:verify:failed:${ip}`,
+
+  // Reauth attempts
+  REAUTH_SEND: (ip: string) => `reauth:send:${ip}`,
+  REAUTH_VERIFY_FAILED: (ip: string) => `reauth:verify:failed:${ip}`,
+
+  // Password login attempts
+  PASSWORD_LOGIN_FAILED: (ip: string) => `password:login:failed:${ip}`,
+
+  // API auth failure attempts (session-auth routes)
+  API_AUTH_FAILED: (ip: string) => `api:auth:failed:${ip}`,
+  API_MALFORMED_AUTH_COOKIE: (ip: string) => `api:auth:malformed-cookie:${ip}`,
+  API_SUSPICIOUS: (ip: string) => `api:suspicious:${ip}`,
+
+  // IP block cache
+  IP_BLOCKED: (ip: string) => `ip:blocked:${ip}`,
+  IP_BLOCK_LEVEL: (ip: string) => `ip:block:level:${ip}`,
+} as const;
+
+/**
+ * Window durations in milliseconds for different operations
+ */
+export const WINDOW_MS = {
+  ONE_MINUTE: 60 * 1000,
+  TEN_MINUTES: 10 * 60 * 1000,
+  ONE_HOUR: 60 * 60 * 1000,
+  TWENTY_FOUR_HOURS: 24 * 60 * 60 * 1000,
+} as const;

package/src/abuse-protection/edge.ts

@@ -0,0 +1,223 @@
+/**
+ * Edge-compatible abuse protection utilities.
+ *
+ * Unlike the main index.ts (which uses node:crypto), this module only
+ * relies on the @upstash/redis REST client and is safe to run in
+ * Vercel Edge Runtime or Next.js proxy/middleware.
+ */
+
+import {
+  getUpstashRestRedisClient,
+  type UpstashRestRedisClient,
+} from '../upstash-rest';
+import {
+  ABUSE_THRESHOLDS,
+  BLOCK_DURATIONS,
+  REDIS_KEYS,
+  WINDOW_MS,
+} from './constants';
+import type { BlockInfo } from './types';
+
+let edgeRedisClient: UpstashRestRedisClient | null = null;
+let edgeRedisInitialized = false;
+
+function parsePositiveIntEnv(name: string, fallback: number): number {
+  const rawValue = process.env[name];
+  if (!rawValue) {
+    return fallback;
+  }
+
+  const parsed = Number.parseInt(rawValue, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+async function getEdgeRedisClient() {
+  if (edgeRedisInitialized) return edgeRedisClient;
+
+  try {
+    edgeRedisClient = await getUpstashRestRedisClient();
+    edgeRedisInitialized = true;
+    return edgeRedisClient;
+  } catch {
+    edgeRedisInitialized = true;
+    return null;
+  }
+}
+
+/**
+ * Check if an IP is blocked using Redis cache only (no DB fallback).
+ * Designed for Edge Runtime where speed > completeness.
+ * The serverless layer provides full DB-backed check as backup.
+ */
+export async function isIPBlockedEdge(
+  ipAddress: string
+): Promise<BlockInfo | null> {
+  try {
+    const redis = await getEdgeRedisClient();
+    if (!redis) return null;
+
+    const cached = await redis.get<string>(REDIS_KEYS.IP_BLOCKED(ipAddress));
+    if (!cached) return null;
+
+    const blockInfo = typeof cached === 'string' ? JSON.parse(cached) : cached;
+    if (new Date(blockInfo.expiresAt) <= new Date()) return null;
+
+    return {
+      id: blockInfo.id,
+      blockLevel: blockInfo.level,
+      reason: blockInfo.reason,
+      expiresAt: new Date(blockInfo.expiresAt),
+      blockedAt: new Date(blockInfo.blockedAt),
+    };
+  } catch {
+    // Fail-open: if Redis is unavailable, allow request through
+    return null;
+  }
+}
+
+export async function blockIPEdge(
+  ipAddress: string,
+  reason: BlockInfo['reason']
+): Promise<BlockInfo | null> {
+  try {
+    const redis = await getEdgeRedisClient();
+    if (!redis) return null;
+
+    const currentLevel =
+      (await redis.get<number>(REDIS_KEYS.IP_BLOCK_LEVEL(ipAddress))) || 0;
+    const newLevel = Math.min(currentLevel + 1, 4) as 1 | 2 | 3 | 4;
+    const blockDuration = BLOCK_DURATIONS[newLevel];
+    const blockedAt = new Date();
+    const expiresAt = new Date(blockedAt.getTime() + blockDuration * 1000);
+    const blockInfo = {
+      id: `edge:${ipAddress}:${blockedAt.getTime()}`,
+      blockLevel: newLevel,
+      reason,
+      blockedAt,
+      expiresAt,
+    } satisfies BlockInfo;
+
+    await Promise.all([
+      redis.set(
+        REDIS_KEYS.IP_BLOCKED(ipAddress),
+        JSON.stringify({
+          id: blockInfo.id,
+          level: blockInfo.blockLevel,
+          reason: blockInfo.reason,
+          expiresAt: blockInfo.expiresAt.toISOString(),
+          blockedAt: blockInfo.blockedAt.toISOString(),
+        }),
+        { ex: blockDuration }
+      ),
+      redis.set(REDIS_KEYS.IP_BLOCK_LEVEL(ipAddress), newLevel, {
+        ex: WINDOW_MS.TWENTY_FOUR_HOURS / 1000,
+      }),
+    ]);
+
+    return blockInfo;
+  } catch {
+    return null;
+  }
+}
+
+async function recordEdgeAbuseSignal(
+  ipAddress: string,
+  redisKey: string,
+  {
+    maxAttempts,
+    windowMs,
+  }: {
+    maxAttempts: number;
+    windowMs: number;
+  }
+): Promise<BlockInfo | null> {
+  try {
+    const redis = await getEdgeRedisClient();
+    if (!redis) return null;
+
+    const attempts = await redis.incr(redisKey);
+
+    if (attempts === 1) {
+      await redis.expire(redisKey, Math.ceil(windowMs / 1000));
+    }
+
+    if (attempts < maxAttempts) {
+      return null;
+    }
+
+    return blockIPEdge(ipAddress, 'api_abuse');
+  } catch {
+    return null;
+  }
+}
+
+export async function recordMalformedAuthCookieEdge(
+  ipAddress: string
+): Promise<BlockInfo | null> {
+  return recordEdgeAbuseSignal(
+    ipAddress,
+    REDIS_KEYS.API_MALFORMED_AUTH_COOKIE(ipAddress),
+    {
+      maxAttempts: parsePositiveIntEnv(
+        'EDGE_MALFORMED_AUTH_COOKIE_MAX',
+        ABUSE_THRESHOLDS.MALFORMED_AUTH_COOKIE_MAX
+      ),
+      windowMs: parsePositiveIntEnv(
+        'EDGE_MALFORMED_AUTH_COOKIE_WINDOW_MS',
+        ABUSE_THRESHOLDS.MALFORMED_AUTH_COOKIE_WINDOW_MS
+      ),
+    }
+  );
+}
+
+export async function recordSuspiciousApiRequestEdge(
+  ipAddress: string
+): Promise<BlockInfo | null> {
+  return recordEdgeAbuseSignal(
+    ipAddress,
+    REDIS_KEYS.API_SUSPICIOUS(ipAddress),
+    {
+      maxAttempts: parsePositiveIntEnv(
+        'EDGE_SUSPICIOUS_API_MAX',
+        ABUSE_THRESHOLDS.SUSPICIOUS_API_MAX
+      ),
+      windowMs: parsePositiveIntEnv(
+        'EDGE_SUSPICIOUS_API_WINDOW_MS',
+        ABUSE_THRESHOLDS.SUSPICIOUS_API_WINDOW_MS
+      ),
+    }
+  );
+}
+
+/**
+ * Lightweight IP extraction for Edge Runtime.
+ * Checks standard proxy headers in priority order.
+ */
+export function extractIPFromRequest(headers: Headers): string {
+  // cf-connecting-ip (Cloudflare)
+  const cfIP = headers.get('cf-connecting-ip');
+  if (cfIP && isValidIPEdge(cfIP)) return cfIP;
+
+  // true-client-ip (some Cloudflare/enterprise proxy setups)
+  const trueClientIP = headers.get('true-client-ip');
+  if (trueClientIP && isValidIPEdge(trueClientIP)) return trueClientIP;
+
+  // x-forwarded-for (most common generic proxy header)
+  const forwardedFor = headers.get('x-forwarded-for');
+  if (forwardedFor) {
+    const firstIP = forwardedFor.split(',')[0]?.trim();
+    if (firstIP && isValidIPEdge(firstIP)) return firstIP;
+  }
+
+  // x-real-ip (Nginx)
+  const realIP = headers.get('x-real-ip');
+  if (realIP && isValidIPEdge(realIP)) return realIP;
+
+  return 'unknown';
+}
+
+function isValidIPEdge(ip: string): boolean {
+  const ipv4Regex = /^(\d{1,3}\.){3}\d{1,3}$/;
+  const ipv6Regex = /^([0-9a-fA-F]{0,4}:){2,7}[0-9a-fA-F]{0,4}$/;
+  return ipv4Regex.test(ip) || ipv6Regex.test(ip);
+}