@tuturuuu/utils 0.7.0 → 0.9.0

package/src/abuse-protection/index.ts

@@ -34,6 +34,18 @@ export * from './user-agent';
 // In-memory fallback store
 const memoryStore = new Map<string, { count: number; expiresAt: number }>();
 
+const SHARED_IP_THROTTLE_ONLY_BLOCK_REASONS = new Set<AbuseEventType>([
+  'otp_send',
+  'otp_verify_failed',
+  'mfa_verify_failed',
+  'reauth_verify_failed',
+  'password_login_failed',
+]);
+
+export function isSharedIpThrottleOnlyBlockReason(reason: AbuseEventType) {
+  return SHARED_IP_THROTTLE_ONLY_BLOCK_REASONS.has(reason);
+}
+
 // Redis client singleton (lazy initialized)
 let redisClient: RedisClient | null = null;
 let redisInitialized = false;
@@ -239,44 +251,6 @@ async function getCounter(key: string): Promise<number> {
   return existing.count;
 }
 
-async function getCounterWithTTL(
-  key: string
-): Promise<{ count: number; ttl: number }> {
-  const redis = await getRedisClient();
-
-  if (redis) {
-    try {
-      const [count, ttl] = await Promise.all([
-        redis.get<number>(key),
-        redis.ttl(key),
-      ]);
-
-      return {
-        count: count || 0,
-        ttl: ttl > 0 ? ttl : 0,
-      };
-    } catch {
-      // Fall through to memory
-    }
-  }
-
-  const existing = memoryStore.get(key);
-  if (!existing) {
-    return { count: 0, ttl: 0 };
-  }
-
-  const now = Date.now();
-  if (now > existing.expiresAt) {
-    memoryStore.delete(key);
-    return { count: 0, ttl: 0 };
-  }
-
-  return {
-    count: existing.count,
-    ttl: Math.ceil((existing.expiresAt - now) / 1000),
-  };
-}
-
 /**
  * Delete keys from Redis or memory
  */
@@ -434,6 +408,10 @@ export async function blockIP(
   reason: AbuseEventType,
   metadata?: Record<string, unknown>
 ): Promise<void> {
+  if (isSharedIpThrottleOnlyBlockReason(reason)) {
+    return;
+  }
+
   try {
     const sbAdmin = await getSupabaseAdmin();
     if (!sbAdmin) return;
@@ -902,7 +880,10 @@ export async function resetOtpLimitsForEmail({
 }
 
 /**
- * Check and track OTP send attempts
+ * Check and reserve OTP send attempts.
+ *
+ * Accepted sends consume quota before provider delivery to prevent parallel
+ * requests from all observing the same pre-send counter state.
  */
 export async function checkOTPSendAllowed(
   ipAddress: string,
@@ -928,25 +909,22 @@ export async function checkOTPSendAllowed(
   const dailyKey = REDIS_KEYS.OTP_SEND_DAILY(ipAddress);
 
   const [minuteState, hourlyState, dailyState] = await Promise.all([
-    getCounterWithTTL(minuteKey),
-    getCounterWithTTL(hourlyKey),
-    getCounterWithTTL(dailyKey),
+    incrementCounter(minuteKey, WINDOW_MS.ONE_MINUTE),
+    incrementCounter(hourlyKey, WINDOW_MS.ONE_HOUR),
+    incrementCounter(dailyKey, WINDOW_MS.TWENTY_FOUR_HOURS),
   ]);
   const ipLimits = getOTPSendIpLimits();
 
-  if (minuteState.count >= ipLimits.perMinute) {
-    // Log and potentially block
+  if (minuteState.count > ipLimits.perMinute) {
     void logAbuseEvent(ipAddress, 'otp_send', {
       email,
       success: false,
-      metadata: { trigger: 'minute_limit' },
+      metadata: {
+        trigger: 'minute_limit',
+        hard_block_suppressed: minuteState.count >= ipLimits.perMinute * 2,
+      },
     });
 
-    if (minuteState.count >= ipLimits.perMinute * 2) {
-      // Aggressive abuse - block IP
-      void blockIP(ipAddress, 'otp_send', { trigger: 'rate_limit_exceeded' });
-    }
-
     return {
       allowed: false,
       reason: 'Too many OTP requests. Please try again later.',
@@ -955,15 +933,16 @@ export async function checkOTPSendAllowed(
     };
   }
 
-  if (hourlyState.count >= ipLimits.perHour) {
+  if (hourlyState.count > ipLimits.perHour) {
     void logAbuseEvent(ipAddress, 'otp_send', {
       email,
       success: false,
-      metadata: { trigger: 'hourly_rate_limit' },
+      metadata: {
+        trigger: 'hourly_rate_limit',
+        hard_block_suppressed: true,
+      },
     });
 
-    void blockIP(ipAddress, 'otp_send', { trigger: 'hourly_rate_limit' });
-
     return {
       allowed: false,
       reason: 'Hourly OTP limit reached. Please try again later.',
@@ -972,13 +951,15 @@ export async function checkOTPSendAllowed(
     };
   }
 
-  if (dailyState.count >= ipLimits.perDay) {
+  if (dailyState.count > ipLimits.perDay) {
     void logAbuseEvent(ipAddress, 'otp_send', {
       email,
       success: false,
-      metadata: { trigger: 'ip_daily_limit' },
+      metadata: {
+        trigger: 'ip_daily_limit',
+        hard_block_suppressed: true,
+      },
     });
-    void blockIP(ipAddress, 'otp_send', { trigger: 'ip_daily_limit' });
 
     return {
       allowed: false,
@@ -995,14 +976,11 @@ export async function checkOTPSendAllowed(
     const hourlyEmailKey = REDIS_KEYS.OTP_SEND_EMAIL_HOURLY(emailHash);
     const dailyEmailKey = REDIS_KEYS.OTP_SEND_EMAIL_DAILY(emailHash);
 
-    const [cooldownState, hourlyEmailState, dailyEmailState] =
-      await Promise.all([
-        getCounterWithTTL(cooldownKey),
-        getCounterWithTTL(hourlyEmailKey),
-        getCounterWithTTL(dailyEmailKey),
-      ]);
-
-    if (cooldownState.count >= 1) {
+    const cooldownState = await incrementCounter(
+      cooldownKey,
+      ABUSE_THRESHOLDS.OTP_SEND_EMAIL_COOLDOWN_WINDOW_MS
+    );
+    if (cooldownState.count > 1) {
       void logAbuseEvent(ipAddress, 'otp_send', {
         email,
         success: false,
@@ -1017,7 +995,12 @@ export async function checkOTPSendAllowed(
       };
     }
 
-    if (hourlyEmailState.count >= ABUSE_THRESHOLDS.OTP_SEND_EMAIL_PER_HOUR) {
+    const [hourlyEmailState, dailyEmailState] = await Promise.all([
+      incrementCounter(hourlyEmailKey, WINDOW_MS.ONE_HOUR),
+      incrementCounter(dailyEmailKey, WINDOW_MS.TWENTY_FOUR_HOURS),
+    ]);
+
+    if (hourlyEmailState.count > ABUSE_THRESHOLDS.OTP_SEND_EMAIL_PER_HOUR) {
       void logAbuseEvent(ipAddress, 'otp_send', {
         email,
         success: false,
@@ -1032,7 +1015,7 @@ export async function checkOTPSendAllowed(
       };
     }
 
-    if (dailyEmailState.count >= ABUSE_THRESHOLDS.OTP_SEND_EMAIL_PER_DAY) {
+    if (dailyEmailState.count > ABUSE_THRESHOLDS.OTP_SEND_EMAIL_PER_DAY) {
       void logAbuseEvent(ipAddress, 'otp_send', {
         email,
         success: false,
@@ -1050,10 +1033,7 @@ export async function checkOTPSendAllowed(
 
   return {
     allowed: true,
-    remainingAttempts: Math.max(
-      0,
-      ipLimits.perMinute - (minuteState.count + 1)
-    ),
+    remainingAttempts: Math.max(0, ipLimits.perMinute - minuteState.count),
   };
 }
 
@@ -1061,31 +1041,6 @@ export async function recordOTPSendSuccess(
   ipAddress: string,
   email?: string
 ): Promise<void> {
-  await Promise.all([
-    incrementCounter(REDIS_KEYS.OTP_SEND(ipAddress), WINDOW_MS.ONE_MINUTE),
-    incrementCounter(REDIS_KEYS.OTP_SEND_HOURLY(ipAddress), WINDOW_MS.ONE_HOUR),
-    incrementCounter(
-      REDIS_KEYS.OTP_SEND_DAILY(ipAddress),
-      WINDOW_MS.TWENTY_FOUR_HOURS
-    ),
-    ...(email
-      ? [
-          incrementCounter(
-            REDIS_KEYS.OTP_SEND_EMAIL_COOLDOWN(hashEmail(email)),
-            ABUSE_THRESHOLDS.OTP_SEND_EMAIL_COOLDOWN_WINDOW_MS
-          ),
-          incrementCounter(
-            REDIS_KEYS.OTP_SEND_EMAIL_HOURLY(hashEmail(email)),
-            WINDOW_MS.ONE_HOUR
-          ),
-          incrementCounter(
-            REDIS_KEYS.OTP_SEND_EMAIL_DAILY(hashEmail(email)),
-            WINDOW_MS.TWENTY_FOUR_HOURS
-          ),
-        ]
-      : []),
-  ]);
-
   void logAbuseEvent(ipAddress, 'otp_send', { email, success: true });
 }
 
@@ -1175,16 +1130,35 @@ export async function recordOTPVerifyFailure(
     ),
   ]);
 
-  // Log the failure
-  void logAbuseEvent(ipAddress, 'otp_verify_failed', { email, success: false });
+  void logAbuseEvent(ipAddress, 'otp_verify_failed', {
+    email,
+    success: false,
+    metadata: createHumanAuthRateLimitMetadata(
+      ipCount,
+      ABUSE_THRESHOLDS.OTP_VERIFY_FAILED_MAX
+    ),
+  });
+}
 
-  // Block if threshold exceeded
-  if (ipCount >= ABUSE_THRESHOLDS.OTP_VERIFY_FAILED_MAX) {
-    void blockIP(ipAddress, 'otp_verify_failed', {
-      trigger: 'max_failures_exceeded',
-      failedCount: ipCount,
-    });
+/**
+ * Shared NATs can represent a whole classroom, university, or enterprise.
+ * Human-auth counters still throttle the noisy flow, but they must not write a
+ * global IP block that prevents unrelated people on the same public address
+ * from signing in.
+ */
+function createHumanAuthRateLimitMetadata(
+  failedCount: number,
+  maxFailures: number
+): Record<string, unknown> | undefined {
+  if (failedCount < maxFailures) {
+    return undefined;
   }
+
+  return {
+    trigger: 'max_failures_exceeded',
+    failedCount,
+    hard_block_suppressed: true,
+  };
 }
 
 /**
@@ -1282,14 +1256,13 @@ export async function recordMFAVerifyFailure(ipAddress: string): Promise<void> {
     ABUSE_THRESHOLDS.MFA_VERIFY_FAILED_WINDOW_MS
   );
 
-  void logAbuseEvent(ipAddress, 'mfa_verify_failed', { success: false });
-
-  if (count >= ABUSE_THRESHOLDS.MFA_VERIFY_FAILED_MAX) {
-    void blockIP(ipAddress, 'mfa_verify_failed', {
-      trigger: 'max_failures_exceeded',
-      failedCount: count,
-    });
-  }
+  void logAbuseEvent(ipAddress, 'mfa_verify_failed', {
+    success: false,
+    metadata: createHumanAuthRateLimitMetadata(
+      count,
+      ABUSE_THRESHOLDS.MFA_VERIFY_FAILED_MAX
+    ),
+  });
 }
 
 /**
@@ -1383,11 +1356,13 @@ export async function recordReauthVerifyFailure(
     ABUSE_THRESHOLDS.REAUTH_VERIFY_FAILED_WINDOW_MS
   );
 
-  void logAbuseEvent(ipAddress, 'reauth_verify_failed', { success: false });
-
-  if (count >= ABUSE_THRESHOLDS.REAUTH_VERIFY_FAILED_MAX) {
-    void blockIP(ipAddress, 'reauth_verify_failed');
-  }
+  void logAbuseEvent(ipAddress, 'reauth_verify_failed', {
+    success: false,
+    metadata: createHumanAuthRateLimitMetadata(
+      count,
+      ABUSE_THRESHOLDS.REAUTH_VERIFY_FAILED_MAX
+    ),
+  });
 }
 
 /**
@@ -1404,9 +1379,16 @@ export async function clearReauthVerifyFailures(
  */
 export async function checkPasswordLoginLimit(
   ipAddress: string,
+  emailOrContext?: string | AbuseProtectionLogContext,
   context?: AbuseProtectionLogContext
 ): Promise<AbuseCheckResult> {
-  const blockInfo = await isIPBlocked(ipAddress, context);
+  const email =
+    typeof emailOrContext === 'string'
+      ? normalizeAbuseEventEmail(emailOrContext)
+      : null;
+  const logContext =
+    typeof emailOrContext === 'string' ? context : emailOrContext;
+  const blockInfo = await isIPBlocked(ipAddress, logContext);
   if (blockInfo) {
     return {
       allowed: false,
@@ -1418,10 +1400,16 @@ export async function checkPasswordLoginLimit(
     };
   }
 
-  const key = REDIS_KEYS.PASSWORD_LOGIN_FAILED(ipAddress);
-  const count = await getCounter(key);
+  const ipKey = REDIS_KEYS.PASSWORD_LOGIN_FAILED(ipAddress);
+  const emailKey = email
+    ? REDIS_KEYS.PASSWORD_LOGIN_FAILED_EMAIL(hashEmail(email))
+    : null;
+  const [ipCount, emailCount] = await Promise.all([
+    getCounter(ipKey),
+    emailKey ? getCounter(emailKey) : Promise.resolve(0),
+  ]);
 
-  if (count >= ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_MAX) {
+  if (ipCount >= ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_MAX) {
     return {
       allowed: false,
       reason: 'Too many failed login attempts',
@@ -1432,9 +1420,25 @@ export async function checkPasswordLoginLimit(
     };
   }
 
+  if (email && emailCount >= ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_EMAIL_MAX) {
+    return {
+      allowed: false,
+      reason: 'Too many failed login attempts for this email',
+      retryAfter: Math.ceil(
+        ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_EMAIL_WINDOW_MS / 1000
+      ),
+      remainingAttempts: 0,
+    };
+  }
+
   return {
     allowed: true,
-    remainingAttempts: ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_MAX - count,
+    remainingAttempts: Math.min(
+      ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_MAX - ipCount,
+      email
+        ? ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_EMAIL_MAX - emailCount
+        : ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_MAX - ipCount
+    ),
   };
 }
 
@@ -1445,32 +1449,48 @@ export async function recordPasswordLoginFailure(
   ipAddress: string,
   email?: string
 ): Promise<void> {
-  const key = REDIS_KEYS.PASSWORD_LOGIN_FAILED(ipAddress);
-  const { count } = await incrementCounter(
-    key,
-    ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_WINDOW_MS
-  );
+  const normalizedEmail = normalizeAbuseEventEmail(email);
+  const ipKey = REDIS_KEYS.PASSWORD_LOGIN_FAILED(ipAddress);
+  const emailKey = normalizedEmail
+    ? REDIS_KEYS.PASSWORD_LOGIN_FAILED_EMAIL(hashEmail(normalizedEmail))
+    : null;
+  const [{ count }] = await Promise.all([
+    incrementCounter(ipKey, ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_WINDOW_MS),
+    emailKey
+      ? incrementCounter(
+          emailKey,
+          ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_EMAIL_WINDOW_MS
+        )
+      : Promise.resolve({ count: 0, ttl: 0 }),
+  ]);
 
   void logAbuseEvent(ipAddress, 'password_login_failed', {
-    email,
+    email: normalizedEmail ?? undefined,
     success: false,
+    metadata: createHumanAuthRateLimitMetadata(
+      count,
+      ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_MAX
+    ),
   });
-
-  if (count >= ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_MAX) {
-    void blockIP(ipAddress, 'password_login_failed', {
-      trigger: 'max_failures_exceeded',
-      failedCount: count,
-    });
-  }
 }
 
 /**
- * Clear password login failures on success
+ * Clear password login failures for the successful account only.
+ * The IP-wide failure counter intentionally remains in place so a successful
+ * login for another account cannot reset brute-force pressure from the IP.
  */
 export async function clearPasswordLoginFailures(
-  ipAddress: string
+  _ipAddress: string,
+  email?: string
 ): Promise<void> {
-  await deleteKeys(REDIS_KEYS.PASSWORD_LOGIN_FAILED(ipAddress));
+  const normalizedEmail = normalizeAbuseEventEmail(email);
+  if (!normalizedEmail) {
+    return;
+  }
+
+  await deleteKeys(
+    REDIS_KEYS.PASSWORD_LOGIN_FAILED_EMAIL(hashEmail(normalizedEmail))
+  );
 }
 
 /**

package/src/abuse-protection/reputation.ts

@@ -23,11 +23,21 @@ export const ABUSE_REPUTATION_SUBJECT_TYPES = [
   'ip',
   'cidr',
   'user_location',
+  'workspace',
 ] as const;
 
 export type AbuseReputationSubjectType =
   (typeof ABUSE_REPUTATION_SUBJECT_TYPES)[number];
 
+export const RATE_LIMIT_MODES = [
+  'inherit_multiplier',
+  'absolute',
+  'unlimited',
+  'blocked',
+] as const;
+
+export type RateLimitMode = (typeof RATE_LIMIT_MODES)[number];
+
 export type AbuseSignalType =
   | 'organic_activity'
   | 'automation_client'