@tuturuuu/utils 0.8.0 → 0.10.0

package/src/abuse-protection/edge-trust.ts

@@ -21,6 +21,7 @@ import {
 } from '../upstash-rest';
 
 const TRUST_CACHE_PREFIX = 'trust:mult';
+const APPEAL_RELIEF_CACHE_PREFIX = 'trust:appeal-relief';
 
 // Mirrors the DB CHECK constraint on trust_multiplier (> 0 AND <= 1000).
 const MIN_TRUST_MULTIPLIER = 0.35;
@@ -39,9 +40,12 @@ export interface CachedTrustEntry {
   mode?: 'absolute' | 'unlimited';
   /** For mode=absolute: explicit per-window READ limits. */
   abs?: { minute?: number; hour?: number; day?: number };
+  /** Server-verified session marker. Does not increase limits by itself. */
+  verified?: boolean;
 }
 
 const DEFAULT_TRUST_CACHE_TTL_SECONDS = 3600; // 1 hour
+const DEFAULT_APPEAL_RELIEF_TTL_SECONDS = 15 * 60; // 15 minutes
 
 let trustRedisClient: UpstashRestRedisClient | null = null;
 let trustRedisInitialized = false;
@@ -63,6 +67,13 @@ export function getTrustCacheTtlSeconds(): number {
   );
 }
 
+export function getAppealReliefTtlSeconds(): number {
+  return parsePositiveIntEnv(
+    'RATE_LIMIT_APPEAL_RELIEF_TTL_SECONDS',
+    DEFAULT_APPEAL_RELIEF_TTL_SECONDS
+  );
+}
+
 async function getTrustRedisClient() {
   if (trustRedisInitialized) return trustRedisClient;
 
@@ -84,6 +95,13 @@ export function buildTrustCacheKey(subjectKey: string): string {
   return `${TRUST_CACHE_PREFIX}:${subjectKey}`;
 }
 
+export function buildIpBlockAppealReliefKey(
+  sessionKey: string,
+  ipKey: string
+): string {
+  return `${APPEAL_RELIEF_CACHE_PREFIX}:${sessionKey}:${ipKey}`;
+}
+
 function clampMultiplier(value: number): number {
   if (!Number.isFinite(value) || value <= 0) {
     return NEUTRAL_TRUST_MULTIPLIER;
@@ -156,14 +174,25 @@ function parseEntry(value: unknown): CachedTrustEntry | null {
       ? record.mode
       : undefined;
   const abs = parseAbsLimits(record.abs);
+  const verified = record.verified === true;
 
-  return { abs, m, mode };
+  const entry: CachedTrustEntry = { m };
+  if (mode) {
+    entry.mode = mode;
+  }
+  if (abs) {
+    entry.abs = abs;
+  }
+  if (verified) {
+    entry.verified = true;
+  }
+  return entry;
 }
 
 /** Serializes an entry for storage: plain number when multiplier-only. */
 function serializeEntry(entry: CachedTrustEntry): number | CachedTrustEntry {
   const m = clampMultiplier(entry.m);
-  if (!entry.mode && !entry.abs) {
+  if (!entry.mode && !entry.abs && !entry.verified) {
     return m;
   }
 
@@ -182,20 +211,28 @@ function serializeEntry(entry: CachedTrustEntry): number | CachedTrustEntry {
       serialized.abs = abs;
     }
   }
+  if (entry.verified) {
+    serialized.verified = true;
+  }
   return serialized;
 }
 
 function isActiveEntry(entry: CachedTrustEntry): boolean {
-  return entry.mode != null || entry.m > NEUTRAL_TRUST_MULTIPLIER;
+  return (
+    entry.mode != null ||
+    entry.verified === true ||
+    entry.m > NEUTRAL_TRUST_MULTIPLIER
+  );
 }
 
 /**
  * Resolves the cached trust multiplier for each provided subject key.
  *
  * Returns a map of subject key -> clamped multiplier for keys that have a cache
- * entry above the neutral baseline. Missing keys are omitted. Returns an empty
- * map on any Redis error (fail-open). Lets callers distinguish account trust
- * (session key) from location trust (cidr/ip keys).
+ * entry above the neutral baseline, admin-mode entries, or neutral verified
+ * session entries. Missing keys are omitted. Returns an empty map on any Redis
+ * error (fail-open). Lets callers distinguish account trust (session key) from
+ * location trust (cidr/ip keys).
  */
 export async function getCachedTrustEntries(
   subjectKeys: string[]
@@ -342,3 +379,101 @@ export async function writeTrustCacheForSubjects(
     // Cache writes must never block the protected request path.
   }
 }
+
+/**
+ * Write-through a neutral marker for server-verified browser/app sessions.
+ * This only proves the session cookie was successfully validated downstream; it
+ * does not grant a read-limit multiplier or admin override.
+ */
+export async function writeVerifiedSessionCacheForSubjects(
+  subjectKeys: string[],
+  ttlSeconds: number = getTrustCacheTtlSeconds()
+): Promise<void> {
+  const sessionKeys = subjectKeys.filter((subjectKey) =>
+    subjectKey.startsWith('session:')
+  );
+  if (sessionKeys.length === 0) {
+    return;
+  }
+
+  try {
+    const redis = await getTrustRedisClient();
+    if (!redis) {
+      return;
+    }
+
+    const existingEntries = await getCachedTrustEntries(sessionKeys);
+    const verifiedEntry = serializeEntry({
+      m: NEUTRAL_TRUST_MULTIPLIER,
+      verified: true,
+    });
+    await Promise.all(
+      sessionKeys.map((subjectKey) => {
+        const existing = existingEntries.get(subjectKey);
+        if (
+          existing &&
+          (existing.mode != null || existing.abs != null || existing.m > 1)
+        ) {
+          return Promise.resolve();
+        }
+
+        return redis.set(buildTrustCacheKey(subjectKey), verifiedEntry, {
+          ex: ttlSeconds,
+        });
+      })
+    );
+  } catch {
+    // Cache writes must never block the protected request path.
+  }
+}
+
+/**
+ * Grants a short, session+IP-scoped bypass for the hard IP-block check. This is
+ * used only after an authenticated user passes Turnstile and submits an appeal;
+ * it does not clear the global IP block or elevate unrelated sessions.
+ */
+export async function setCachedIpBlockAppealRelief(
+  sessionKey: string,
+  ipKey: string,
+  ttlSeconds: number = getAppealReliefTtlSeconds()
+): Promise<void> {
+  if (!sessionKey || !ipKey) {
+    return;
+  }
+
+  try {
+    const redis = await getTrustRedisClient();
+    if (!redis) {
+      return;
+    }
+
+    await redis.set(buildIpBlockAppealReliefKey(sessionKey, ipKey), '1', {
+      ex: ttlSeconds,
+    });
+  } catch {
+    // Cache writes must never block the appeal path.
+  }
+}
+
+export async function hasCachedIpBlockAppealRelief(
+  sessionKey: string,
+  ipKey: string
+): Promise<boolean> {
+  if (!sessionKey || !ipKey) {
+    return false;
+  }
+
+  try {
+    const redis = await getTrustRedisClient();
+    if (!redis) {
+      return false;
+    }
+
+    return Boolean(
+      await redis.get<string>(buildIpBlockAppealReliefKey(sessionKey, ipKey))
+    );
+  } catch {
+    // Fail closed for the hard-block bypass.
+    return false;
+  }
+}

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;
@@ -396,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;
@@ -900,18 +916,15 @@ export async function checkOTPSendAllowed(
   const ipLimits = getOTPSendIpLimits();
 
   if (minuteState.count > ipLimits.perMinute) {
-    // Log and potentially block
     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.',
@@ -924,11 +937,12 @@ export async function checkOTPSendAllowed(
     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.',
@@ -941,9 +955,11 @@ export async function checkOTPSendAllowed(
     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,
@@ -1114,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,
+  };
 }
 
 /**
@@ -1221,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
+    ),
+  });
 }
 
 /**
@@ -1322,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
+    ),
+  });
 }
 
 /**
@@ -1431,14 +1467,11 @@ export async function recordPasswordLoginFailure(
   void logAbuseEvent(ipAddress, 'password_login_failed', {
     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,
-    });
-  }
 }
 
 /**