@tuturuuu/utils 0.6.1 → 0.8.0

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

@@ -0,0 +1,200 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+  getClient: vi.fn(),
+  mget: vi.fn(),
+  set: vi.fn(),
+}));
+
+vi.mock('../../upstash-rest', () => ({
+  getUpstashRestRedisClient: () => mocks.getClient(),
+}));
+
+function mockRedisClient() {
+  mocks.getClient.mockResolvedValue({
+    mget: (...keys: string[]) => mocks.mget(...keys),
+    set: (key: string, value: unknown, options?: unknown) =>
+      mocks.set(key, value, options),
+  });
+}
+
+describe('edge-trust cache', () => {
+  beforeEach(() => {
+    vi.resetModules();
+    mocks.getClient.mockReset();
+    mocks.mget.mockReset();
+    mocks.set.mockReset();
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('returns only elevated subjects from getCachedTrustMultipliers', async () => {
+    mockRedisClient();
+    // Order of values matches the order of keys requested.
+    mocks.mget.mockResolvedValue([3, null, 1, 2]);
+
+    const { getCachedTrustMultipliers } = await import('../edge-trust.js');
+    const result = await getCachedTrustMultipliers([
+      'session:aaa',
+      'cidr:1.2.3.0/24',
+      'ip:1.2.3.4',
+      'user:abc',
+    ]);
+
+    expect(result.get('session:aaa')).toBe(3);
+    expect(result.has('cidr:1.2.3.0/24')).toBe(false); // null
+    expect(result.has('ip:1.2.3.4')).toBe(false); // neutral (1)
+    expect(result.get('user:abc')).toBe(2);
+  });
+
+  it('clamps cached multipliers to the DB ceiling', async () => {
+    mockRedisClient();
+    mocks.mget.mockResolvedValue([5000]);
+
+    const { getCachedTrustMultipliers } = await import('../edge-trust.js');
+    const result = await getCachedTrustMultipliers(['session:aaa']);
+
+    expect(result.get('session:aaa')).toBe(1000);
+  });
+
+  it('takes the most-trusting multiplier in getCachedTrustMultiplier', async () => {
+    mockRedisClient();
+    mocks.mget.mockResolvedValue([2, 3]);
+
+    const { getCachedTrustMultiplier } = await import('../edge-trust.js');
+    const best = await getCachedTrustMultiplier([
+      'cidr:1.2.3.0/24',
+      'session:aaa',
+    ]);
+
+    expect(best).toBe(3);
+  });
+
+  it('parses string multipliers from Redis', async () => {
+    mockRedisClient();
+    mocks.mget.mockResolvedValue(['2.5']);
+
+    const { getCachedTrustMultiplier } = await import('../edge-trust.js');
+    expect(await getCachedTrustMultiplier(['session:aaa'])).toBe(2.5);
+  });
+
+  it('fails open to a neutral multiplier when Redis errors', async () => {
+    mockRedisClient();
+    mocks.mget.mockRejectedValue(new Error('redis down'));
+
+    const { getCachedTrustMultiplier, getCachedTrustMultipliers } =
+      await import('../edge-trust.js');
+
+    expect(await getCachedTrustMultiplier(['session:aaa'])).toBe(1);
+    expect((await getCachedTrustMultipliers(['session:aaa'])).size).toBe(0);
+  });
+
+  it('fails open when no Redis client is configured', async () => {
+    mocks.getClient.mockResolvedValue(null);
+
+    const { getCachedTrustMultiplier } = await import('../edge-trust.js');
+    expect(await getCachedTrustMultiplier(['session:aaa'])).toBe(1);
+  });
+
+  it('writes a clamped multiplier with a TTL', async () => {
+    mockRedisClient();
+    mocks.set.mockResolvedValue('OK');
+
+    const { setCachedTrustMultiplier } = await import('../edge-trust.js');
+    await setCachedTrustMultiplier('cidr:1.2.3.0/24', 5000, 7200);
+
+    expect(mocks.set).toHaveBeenCalledWith('trust:mult:cidr:1.2.3.0/24', 1000, {
+      ex: 7200,
+    });
+  });
+
+  it('skips neutral multipliers in writeTrustCacheForSubjects', async () => {
+    mockRedisClient();
+    mocks.set.mockResolvedValue('OK');
+
+    const { writeTrustCacheForSubjects } = await import('../edge-trust.js');
+    await writeTrustCacheForSubjects(['session:aaa', 'cidr:1.2.3.0/24'], 1);
+
+    expect(mocks.set).not.toHaveBeenCalled();
+  });
+
+  it('writes every subject key for an elevated multiplier', async () => {
+    mockRedisClient();
+    mocks.set.mockResolvedValue('OK');
+
+    const { writeTrustCacheForSubjects } = await import('../edge-trust.js');
+    await writeTrustCacheForSubjects(
+      ['session:aaa', 'cidr:1.2.3.0/24'],
+      3,
+      600
+    );
+
+    expect(mocks.set).toHaveBeenCalledWith('trust:mult:session:aaa', 3, {
+      ex: 600,
+    });
+    expect(mocks.set).toHaveBeenCalledWith('trust:mult:cidr:1.2.3.0/24', 3, {
+      ex: 600,
+    });
+  });
+
+  it('parses legacy plain numbers and rich JSON entries together', async () => {
+    mockRedisClient();
+    mocks.mget.mockResolvedValue([
+      3, // legacy plain number
+      { m: 1, mode: 'unlimited' }, // rich object (auto-deserialized by upstash)
+      { m: 1, mode: 'absolute', abs: { minute: 500 } },
+    ]);
+
+    const { getCachedTrustEntries } = await import('../edge-trust.js');
+    const entries = await getCachedTrustEntries([
+      'session:legacy',
+      'cidr:unl',
+      'ip:abs',
+    ]);
+
+    expect(entries.get('session:legacy')).toEqual({ m: 3 });
+    expect(entries.get('cidr:unl')).toEqual({ m: 1, mode: 'unlimited' });
+    expect(entries.get('ip:abs')).toEqual({
+      abs: { minute: 500 },
+      m: 1,
+      mode: 'absolute',
+    });
+  });
+
+  it('writes rich entries as JSON and multiplier-only as a plain number', async () => {
+    mockRedisClient();
+    mocks.set.mockResolvedValue('OK');
+
+    const { setCachedTrustEntry } = await import('../edge-trust.js');
+    await setCachedTrustEntry('session:a', { m: 3 }, 600);
+    await setCachedTrustEntry(
+      'cidr:b',
+      { abs: { minute: 500 }, m: 1, mode: 'absolute' },
+      600
+    );
+
+    expect(mocks.set).toHaveBeenCalledWith('trust:mult:session:a', 3, {
+      ex: 600,
+    });
+    expect(mocks.set).toHaveBeenCalledWith(
+      'trust:mult:cidr:b',
+      { abs: { minute: 500 }, m: 1, mode: 'absolute' },
+      { ex: 600 }
+    );
+  });
+
+  it('honors the configurable cache TTL', async () => {
+    vi.stubEnv('EDGE_TRUST_CACHE_TTL_SECONDS', '900');
+    mockRedisClient();
+    mocks.set.mockResolvedValue('OK');
+
+    const { setCachedTrustMultiplier } = await import('../edge-trust.js');
+    await setCachedTrustMultiplier('session:aaa', 3);
+
+    expect(mocks.set).toHaveBeenCalledWith('trust:mult:session:aaa', 3, {
+      ex: 900,
+    });
+  });
+});

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

@@ -7,12 +7,15 @@ import {
   ABUSE_THRESHOLDS,
   BLOCK_DURATIONS,
   checkOTPSendAllowed,
+  checkPasswordLoginLimit,
   classifyPotentialSpamUserAgent,
+  clearPasswordLoginFailures,
   extractIPFromHeaders,
   hashEmail,
   MAX_BLOCK_LEVEL,
   REDIS_KEYS,
   recordOTPSendSuccess,
+  recordPasswordLoginFailure,
   resetOtpLimitsForEmail,
   WINDOW_MS,
 } from '../index';
@@ -241,6 +244,54 @@ describe('abuse-protection', () => {
         5 * 60 * 1000
       );
       expect(ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_MAX).toBe(10);
+      expect(ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_EMAIL_WINDOW_MS).toBe(
+        15 * 60 * 1000
+      );
+      expect(ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_EMAIL_MAX).toBe(10);
+    });
+  });
+
+  describe('password login failure limits', () => {
+    it('keeps the IP-wide failure counter after another account succeeds', async () => {
+      const ipAddress = '203.0.113.41';
+
+      for (let attempt = 0; attempt < 9; attempt += 1) {
+        await recordPasswordLoginFailure(ipAddress, 'victim@example.com');
+      }
+
+      await clearPasswordLoginFailures(ipAddress, 'attacker@example.com');
+
+      await expect(
+        checkPasswordLoginLimit(ipAddress, 'victim@example.com')
+      ).resolves.toMatchObject({
+        allowed: true,
+        remainingAttempts: 1,
+      });
+    });
+
+    it('clears only the successful account email failure counter', async () => {
+      const email = 'targeted-user@example.com';
+
+      for (let attempt = 0; attempt < 10; attempt += 1) {
+        await recordPasswordLoginFailure(`198.51.100.${attempt + 1}`, email);
+      }
+
+      await expect(
+        checkPasswordLoginLimit('198.51.100.200', email)
+      ).resolves.toMatchObject({
+        allowed: false,
+        reason: 'Too many failed login attempts for this email',
+        remainingAttempts: 0,
+      });
+
+      await clearPasswordLoginFailures('198.51.100.200', email);
+
+      await expect(
+        checkPasswordLoginLimit('198.51.100.200', email)
+      ).resolves.toMatchObject({
+        allowed: true,
+        remainingAttempts: 10,
+      });
     });
   });
 
@@ -350,14 +401,19 @@ describe('abuse-protection', () => {
   });
 
   describe('checkOTPSendAllowed', () => {
-    it('does not consume quota during preflight checks', async () => {
-      const email = `preflight-${Date.now()}@example.com`;
-
-      const firstAttempt = await checkOTPSendAllowed('198.51.100.1', email);
-      const secondAttempt = await checkOTPSendAllowed('198.51.100.2', email);
-
-      expect(firstAttempt.allowed).toBe(true);
-      expect(secondAttempt.allowed).toBe(true);
+    it('reserves same-email cooldown before provider success', async () => {
+      const email = `reserved-cooldown-${Date.now()}@example.com`;
+
+      const attempts = await Promise.all([
+        checkOTPSendAllowed('198.51.100.1', email),
+        checkOTPSendAllowed('198.51.100.2', email),
+      ]);
+      const allowedAttempts = attempts.filter((attempt) => attempt.allowed);
+      const blockedAttempts = attempts.filter((attempt) => !attempt.allowed);
+
+      expect(allowedAttempts).toHaveLength(1);
+      expect(blockedAttempts).toHaveLength(1);
+      expect(blockedAttempts[0]?.retryAfter).toBeGreaterThan(0);
     });
 
     it('blocks repeated sends to the same email across different IPs during cooldown', async () => {

package/src/abuse-protection/constants.ts

@@ -35,6 +35,8 @@ export const ABUSE_THRESHOLDS = {
   // Password login limits
   PASSWORD_LOGIN_FAILED_WINDOW_MS: 5 * 60 * 1000, // 5 minutes
   PASSWORD_LOGIN_FAILED_MAX: 10,
+  PASSWORD_LOGIN_FAILED_EMAIL_WINDOW_MS: 15 * 60 * 1000, // 15 minutes
+  PASSWORD_LOGIN_FAILED_EMAIL_MAX: 10,
 
   // API auth failure limits (session-auth routes)
   API_AUTH_FAILED_WINDOW_MS: 5 * 60 * 1000, // 5 minutes
@@ -95,6 +97,8 @@ export const REDIS_KEYS = {
 
   // Password login attempts
   PASSWORD_LOGIN_FAILED: (ip: string) => `password:login:failed:${ip}`,
+  PASSWORD_LOGIN_FAILED_EMAIL: (emailHash: string) =>
+    `password:login:failed:email:${emailHash}`,
 
   // API auth failure attempts (session-auth routes)
   API_AUTH_FAILED: (ip: string) => `api:auth:failed:${ip}`,

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

@@ -0,0 +1,344 @@
+/**
+ * Edge-compatible trust multiplier cache.
+ *
+ * Bridges the server-side abuse reputation/trust system (Postgres) to the edge
+ * proxy guard so that read rate limits can be scaled up for trusted accounts
+ * and trusted locations (CIDRs) without a per-request database round-trip.
+ *
+ * Like `edge.ts`, this module only relies on the @upstash/redis REST client and
+ * is safe to run in Vercel Edge Runtime / Next.js proxy middleware as well as in
+ * the Node serverless layer (used by the write-through path in reputation.ts).
+ *
+ * Trust can never be forged from the edge: cache entries are only written by the
+ * service-role write-through path keyed on hashes of real, observed subjects. A
+ * fabricated subject key simply misses the cache and resolves to a 1.0
+ * (neutral) multiplier — fail-open by design.
+ */
+
+import {
+  getUpstashRestRedisClient,
+  type UpstashRestRedisClient,
+} from '../upstash-rest';
+
+const TRUST_CACHE_PREFIX = 'trust:mult';
+
+// Mirrors the DB CHECK constraint on trust_multiplier (> 0 AND <= 1000).
+const MIN_TRUST_MULTIPLIER = 0.35;
+const MAX_TRUST_MULTIPLIER = 1000;
+const NEUTRAL_TRUST_MULTIPLIER = 1;
+
+/**
+ * A cached rate-limit decision for a subject as seen by the edge proxy. Stored
+ * as a plain number for the common multiplier-only case (back-compat), or as a
+ * JSON object when an admin rule carries a richer mode.
+ */
+export interface CachedTrustEntry {
+  /** Read-limit multiplier (uplift). 1 = neutral. Ignored when mode=unlimited. */
+  m: number;
+  /** Admin rule mode. Absent = plain multiplier. */
+  mode?: 'absolute' | 'unlimited';
+  /** For mode=absolute: explicit per-window READ limits. */
+  abs?: { minute?: number; hour?: number; day?: number };
+}
+
+const DEFAULT_TRUST_CACHE_TTL_SECONDS = 3600; // 1 hour
+
+let trustRedisClient: UpstashRestRedisClient | null = null;
+let trustRedisInitialized = 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;
+}
+
+export function getTrustCacheTtlSeconds(): number {
+  return parsePositiveIntEnv(
+    'EDGE_TRUST_CACHE_TTL_SECONDS',
+    DEFAULT_TRUST_CACHE_TTL_SECONDS
+  );
+}
+
+async function getTrustRedisClient() {
+  if (trustRedisInitialized) return trustRedisClient;
+
+  try {
+    trustRedisClient = await getUpstashRestRedisClient();
+    trustRedisInitialized = true;
+    return trustRedisClient;
+  } catch {
+    trustRedisInitialized = true;
+    return null;
+  }
+}
+
+/**
+ * Maps an abuse reputation subject key (e.g. `user:<id>`, `session:<hash>`,
+ * `cidr:1.2.3.0/24`) to its trust-cache Redis key.
+ */
+export function buildTrustCacheKey(subjectKey: string): string {
+  return `${TRUST_CACHE_PREFIX}:${subjectKey}`;
+}
+
+function clampMultiplier(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    return NEUTRAL_TRUST_MULTIPLIER;
+  }
+
+  return Math.min(MAX_TRUST_MULTIPLIER, Math.max(MIN_TRUST_MULTIPLIER, value));
+}
+
+function parseMultiplier(value: unknown): number | null {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : null;
+  }
+
+  if (typeof value === 'string') {
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+
+  return null;
+}
+
+function parseAbsLimits(value: unknown): CachedTrustEntry['abs'] | undefined {
+  if (!value || typeof value !== 'object') {
+    return undefined;
+  }
+
+  const source = value as Record<string, unknown>;
+  const abs: { minute?: number; hour?: number; day?: number } = {};
+  for (const window of ['minute', 'hour', 'day'] as const) {
+    const parsed = parseMultiplier(source[window]);
+    if (parsed != null && parsed > 0) {
+      abs[window] = Math.floor(parsed);
+    }
+  }
+
+  return abs.minute != null || abs.hour != null || abs.day != null
+    ? abs
+    : undefined;
+}
+
+/**
+ * Parses a cached value into a {@link CachedTrustEntry}, accepting BOTH legacy
+ * plain numbers/numeric strings (back-compat) and the richer JSON object form.
+ */
+function parseEntry(value: unknown): CachedTrustEntry | null {
+  const asNumber = parseMultiplier(value);
+  if (asNumber != null) {
+    return { m: clampMultiplier(asNumber) };
+  }
+
+  let source: unknown = value;
+  if (typeof value === 'string') {
+    try {
+      source = JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+
+  if (!source || typeof source !== 'object') {
+    return null;
+  }
+
+  const record = source as Record<string, unknown>;
+  const m = clampMultiplier(
+    parseMultiplier(record.m) ?? NEUTRAL_TRUST_MULTIPLIER
+  );
+  const mode =
+    record.mode === 'absolute' || record.mode === 'unlimited'
+      ? record.mode
+      : undefined;
+  const abs = parseAbsLimits(record.abs);
+
+  return { abs, m, mode };
+}
+
+/** 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) {
+    return m;
+  }
+
+  const serialized: CachedTrustEntry = { m };
+  if (entry.mode) {
+    serialized.mode = entry.mode;
+  }
+  if (entry.abs) {
+    const abs: { minute?: number; hour?: number; day?: number } = {};
+    for (const window of ['minute', 'hour', 'day'] as const) {
+      if (entry.abs[window] != null) {
+        abs[window] = entry.abs[window];
+      }
+    }
+    if (abs.minute != null || abs.hour != null || abs.day != null) {
+      serialized.abs = abs;
+    }
+  }
+  return serialized;
+}
+
+function isActiveEntry(entry: CachedTrustEntry): boolean {
+  return entry.mode != null || 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).
+ */
+export async function getCachedTrustEntries(
+  subjectKeys: string[]
+): Promise<Map<string, CachedTrustEntry>> {
+  const result = new Map<string, CachedTrustEntry>();
+  if (subjectKeys.length === 0) {
+    return result;
+  }
+
+  try {
+    const redis = await getTrustRedisClient();
+    if (!redis) {
+      return result;
+    }
+
+    const cacheKeys = subjectKeys.map(buildTrustCacheKey);
+    const values = await redis.mget<unknown[]>(...cacheKeys);
+
+    subjectKeys.forEach((subjectKey, index) => {
+      const entry = parseEntry(values[index]);
+      if (entry && isActiveEntry(entry)) {
+        result.set(subjectKey, entry);
+      }
+    });
+
+    return result;
+  } catch {
+    // Fail-open: trust uplift is a best-effort optimization, never a gate.
+    return result;
+  }
+}
+
+export async function getCachedTrustMultipliers(
+  subjectKeys: string[]
+): Promise<Map<string, number>> {
+  const entries = await getCachedTrustEntries(subjectKeys);
+  const result = new Map<string, number>();
+  for (const [subjectKey, entry] of entries) {
+    result.set(subjectKey, entry.m);
+  }
+  return result;
+}
+
+/**
+ * Resolves the most-trusting cached multiplier across the provided subject keys.
+ *
+ * Returns the max multiplier present (most-trusting wins, consistent with the
+ * DB `get_rate_limit_trust_decision` ordering where trusted > standard). Returns
+ * a neutral 1.0 when nothing is cached or on any Redis error (fail-open).
+ */
+export async function getCachedTrustMultiplier(
+  subjectKeys: string[]
+): Promise<number> {
+  const multipliers = await getCachedTrustMultipliers(subjectKeys);
+
+  let best = NEUTRAL_TRUST_MULTIPLIER;
+  for (const value of multipliers.values()) {
+    if (value > best) {
+      best = value;
+    }
+  }
+
+  return clampMultiplier(best);
+}
+
+/**
+ * Write-through a single subject's full rate-limit entry (multiplier + optional
+ * absolute/unlimited mode) to the edge cache. Stored as a plain number for the
+ * multiplier-only case (back-compat), JSON otherwise.
+ */
+export async function setCachedTrustEntry(
+  subjectKey: string,
+  entry: CachedTrustEntry,
+  ttlSeconds: number = getTrustCacheTtlSeconds()
+): Promise<void> {
+  try {
+    const redis = await getTrustRedisClient();
+    if (!redis) {
+      return;
+    }
+
+    await redis.set(buildTrustCacheKey(subjectKey), serializeEntry(entry), {
+      ex: ttlSeconds,
+    });
+  } catch {
+    // Cache writes must never block the protected request path.
+  }
+}
+
+/**
+ * Write-through a single subject's trust multiplier to the edge cache.
+ */
+export async function setCachedTrustMultiplier(
+  subjectKey: string,
+  multiplier: number,
+  ttlSeconds: number = getTrustCacheTtlSeconds()
+): Promise<void> {
+  try {
+    const redis = await getTrustRedisClient();
+    if (!redis) {
+      return;
+    }
+
+    await redis.set(
+      buildTrustCacheKey(subjectKey),
+      clampMultiplier(multiplier),
+      {
+        ex: ttlSeconds,
+      }
+    );
+  } catch {
+    // Cache writes must never block the protected request path.
+  }
+}
+
+/**
+ * Write-through the same trust multiplier to every subject key resolved for a
+ * request. Used by the reputation write-through path and the reconciliation
+ * cron. Skips writes entirely for the neutral multiplier to avoid pinning
+ * standard subjects in the cache.
+ */
+export async function writeTrustCacheForSubjects(
+  subjectKeys: string[],
+  multiplier: number,
+  ttlSeconds: number = getTrustCacheTtlSeconds()
+): Promise<void> {
+  const clamped = clampMultiplier(multiplier);
+  if (subjectKeys.length === 0 || clamped === NEUTRAL_TRUST_MULTIPLIER) {
+    return;
+  }
+
+  try {
+    const redis = await getTrustRedisClient();
+    if (!redis) {
+      return;
+    }
+
+    await Promise.all(
+      subjectKeys.map((subjectKey) =>
+        redis.set(buildTrustCacheKey(subjectKey), clamped, { ex: ttlSeconds })
+      )
+    );
+  } catch {
+    // Cache writes must never block the protected request path.
+  }
+}