@tuturuuu/utils 0.8.0 → 0.10.0

package/src/api-proxy-guard.ts

@@ -5,6 +5,7 @@ import { extractIPFromRequest, isIPBlockedEdge } from './abuse-protection/edge';
 import {
   type CachedTrustEntry,
   getCachedTrustEntries,
+  hasCachedIpBlockAppealRelief,
 } from './abuse-protection/edge-trust';
 import { DEV_MODE, MAX_PAYLOAD_SIZE } from './constants';
 import { validateRequestEmojiLimit } from './request-emoji-limit';
@@ -31,10 +32,10 @@ function isEnvFlagEnabled(name: string, defaultOn = true): boolean {
 }
 
 /**
- * Whether trusted accounts/locations get scaled read limits (and trusted
+ * Whether trusted accounts/locations get scaled read limits (and verified
  * sessions get their own per-session bucket) at the edge. Default on; set
  * `API_PROXY_EDGE_TRUST_ENABLED=0` to disable trust uplift and fall back to
- * legacy per-IP read limiting without a deploy.
+ * legacy per-IP keying without a deploy.
  */
 function edgeTrustEnabled(): boolean {
   return isEnvFlagEnabled('API_PROXY_EDGE_TRUST_ENABLED');
@@ -187,18 +188,39 @@ const DEFAULT_ANONYMOUS_MUTATE_RATE_LIMITS: RateLimitConfig[] = [
   createConfig('day', '1 d', 600, 'API_PROXY_ANON_MUTATE_LIMIT_DAY'),
 ];
 
+const DEFAULT_AUTHENTICATED_READ_RATE_LIMITS: RateLimitConfig[] = [
+  createConfig('minute', '1 m', 600, 'API_PROXY_AUTH_READ_LIMIT_MINUTE'),
+  createConfig('hour', '1 h', 6000, 'API_PROXY_AUTH_READ_LIMIT_HOUR'),
+  createConfig('day', '1 d', 40_000, 'API_PROXY_AUTH_READ_LIMIT_DAY'),
+];
+
 const DEFAULT_MUTATE_RATE_LIMITS: RateLimitConfig[] = [
   { window: 'minute', limit: 60, duration: '1 m' },
   { window: 'hour', limit: 300, duration: '1 h' },
   { window: 'day', limit: 2000, duration: '1 d' },
 ];
 
+const USERS_ME_READ_RATE_LIMITS: RateLimitConfig[] = [
+  createConfig('minute', '1 m', 600, 'API_PROXY_USERS_ME_READ_LIMIT_MINUTE'),
+  createConfig('hour', '1 h', 6000, 'API_PROXY_USERS_ME_READ_LIMIT_HOUR'),
+  createConfig('day', '1 d', 40_000, 'API_PROXY_USERS_ME_READ_LIMIT_DAY'),
+];
+
 const USERS_ME_MUTATE_RATE_LIMITS: RateLimitConfig[] = [
   { window: 'minute', limit: 60, duration: '1 m' },
   { window: 'hour', limit: 200, duration: '1 h' },
   { window: 'day', limit: 1200, duration: '1 d' },
 ];
 
+const WORKSPACE_DASHBOARD_READ_RATE_LIMITS: RateLimitProfile = {
+  get: [
+    createConfig('minute', '1 m', 600, 'API_PROXY_WORKSPACE_READ_LIMIT_MINUTE'),
+    createConfig('hour', '1 h', 6000, 'API_PROXY_WORKSPACE_READ_LIMIT_HOUR'),
+    createConfig('day', '1 d', 40_000, 'API_PROXY_WORKSPACE_READ_LIMIT_DAY'),
+  ],
+  mutate: DEFAULT_MUTATE_RATE_LIMITS,
+};
+
 const AUTH_RATE_LIMITS: RateLimitProfile = {
   get: NO_READ_RATE_LIMITS,
   mutate: [
@@ -235,6 +257,20 @@ const OTP_VERIFY_RATE_LIMITS: RateLimitProfile = {
   ],
 };
 
+const RATE_LIMIT_APPEAL_RATE_LIMITS: RateLimitProfile = {
+  get: NO_READ_RATE_LIMITS,
+  mutate: [
+    createConfig(
+      'minute',
+      '1 m',
+      1,
+      'API_PROXY_RATE_LIMIT_APPEAL_LIMIT_MINUTE'
+    ),
+    createConfig('hour', '1 h', 3, 'API_PROXY_RATE_LIMIT_APPEAL_LIMIT_HOUR'),
+    createConfig('day', '1 d', 10, 'API_PROXY_RATE_LIMIT_APPEAL_LIMIT_DAY'),
+  ],
+};
+
 const CRON_RATE_LIMITS: RateLimitProfile = {
   get: [
     createConfig('minute', '1 m', 10, 'API_PROXY_CRON_READ_LIMIT_MINUTE'),
@@ -312,6 +348,25 @@ const USERS_DATABASE_READ_OVER_POST_RATE_LIMITS: RateLimitProfile = {
   ],
 };
 
+const USERS_ADMIN_READ_RATE_LIMITS: RateLimitProfile = {
+  get: [
+    createConfig(
+      'minute',
+      '1 m',
+      1200,
+      'API_PROXY_USERS_ADMIN_READ_LIMIT_MINUTE'
+    ),
+    createConfig(
+      'hour',
+      '1 h',
+      12_000,
+      'API_PROXY_USERS_ADMIN_READ_LIMIT_HOUR'
+    ),
+    createConfig('day', '1 d', 80_000, 'API_PROXY_USERS_ADMIN_READ_LIMIT_DAY'),
+  ],
+  mutate: DEFAULT_MUTATE_RATE_LIMITS,
+};
+
 const FINANCE_READ_RATE_LIMITS: RateLimitProfile = {
   get: [
     createConfig('minute', '1 m', 1200, 'API_PROXY_FINANCE_READ_LIMIT_MINUTE', [
@@ -362,7 +417,46 @@ function isUsersDatabaseReadOverPost(req: NextRequest) {
   );
 }
 
+function isUsersAdminRead(req: NextRequest) {
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    return false;
+  }
+
+  const pathname = req.nextUrl.pathname;
+
+  return (
+    /^\/api\/v1\/workspaces\/[^/]+\/users(?:\/(?:database|groups|feedbacks|attendance\/export|[^/]+\/(?:attendance|emails|referrals|linked-promotions|referral-discounts|user-groups)))?\/?$/u.test(
+      pathname
+    ) ||
+    /^\/api\/v1\/workspaces\/[^/]+\/user-groups\/[^/]+(?:\/(?:attendance|members(?:\/[^/]+(?:\/feedbacks)?)?|posts(?:\/[^/]+(?:\/status)?)?|linked-products|storage|indicators(?:\/.*)?))?\/?$/u.test(
+      pathname
+    )
+  );
+}
+
+function isWorkspaceDashboardRead(req: NextRequest) {
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    return false;
+  }
+
+  return /^\/api(?:\/v1)?\/workspaces\/[^/]+(?:\/|$)/u.test(
+    req.nextUrl.pathname
+  );
+}
+
+function isRateLimitAppealSubmission(req: NextRequest) {
+  return (
+    req.method === 'POST' &&
+    /^\/api\/v1\/rate-limit-appeals\/?$/u.test(req.nextUrl.pathname)
+  );
+}
+
 const DEFAULT_ROUTE_POLICIES: ProxyRoutePolicy[] = [
+  {
+    key: 'rate-limit-appeal',
+    matches: isRateLimitAppealSubmission,
+    rateLimits: RATE_LIMIT_APPEAL_RATE_LIMITS,
+  },
   {
     key: 'cron',
     matches: (req) =>
@@ -441,6 +535,16 @@ const DEFAULT_ROUTE_POLICIES: ProxyRoutePolicy[] = [
     matches: isFinanceInvoiceCreateSupportRead,
     rateLimits: FINANCE_READ_RATE_LIMITS,
   },
+  {
+    key: 'users-admin-read',
+    matches: isUsersAdminRead,
+    rateLimits: USERS_ADMIN_READ_RATE_LIMITS,
+  },
+  {
+    key: 'workspace-dashboard-read',
+    matches: isWorkspaceDashboardRead,
+    rateLimits: WORKSPACE_DASHBOARD_READ_RATE_LIMITS,
+  },
   {
     key: 'high-fanout',
     matches: (req) =>
@@ -467,7 +571,7 @@ const DEFAULT_ROUTE_POLICIES: ProxyRoutePolicy[] = [
     key: 'users-me',
     matches: (req) => req.nextUrl.pathname.startsWith('/api/v1/users/me'),
     rateLimits: {
-      get: NO_READ_RATE_LIMITS,
+      get: USERS_ME_READ_RATE_LIMITS,
       mutate: USERS_ME_MUTATE_RATE_LIMITS,
     },
   },
@@ -813,9 +917,10 @@ function getCallerClass(req: NextRequest): CallerClass {
   // Intentionally always 'anonymous'. Auth headers/cookies are forgeable at the
   // edge (we can't verify signatures cheaply here), so presence alone must never
   // grant an elevated proxy budget — real per-user enforcement happens
-  // downstream. Higher read throughput for genuinely trusted accounts/locations
-  // is granted instead via the server-written trust cache (see resolveProxyIdentity
-  // + getCachedTrustMultiplier), which cannot be forged.
+  // downstream. Per-session proxy buckets and higher read throughput for
+  // genuinely trusted accounts/locations are granted instead via the
+  // server-written trust cache (see resolveProxyIdentity +
+  // getCachedTrustEntries), which cannot be forged.
   void req;
   return 'anonymous';
 }
@@ -837,6 +942,13 @@ async function hashStableSubjectEdge(value: string): Promise<string> {
     .slice(0, 24);
 }
 
+export async function buildProxySessionSubjectKey(
+  cookieName: string,
+  cookieValue: string
+): Promise<string> {
+  return `session:${await hashStableSubjectEdge(`${cookieName}:${cookieValue}`)}`;
+}
+
 function parseCookieHeaderEdge(
   cookieHeader: string | null
 ): Array<{ name: string; value: string }> {
@@ -876,6 +988,19 @@ function getSessionAuthCookie(
   );
 }
 
+export async function getProxySessionSubjectKeyFromCookieHeader(
+  cookieHeader: string | null
+): Promise<string | null> {
+  const cookie =
+    parseCookieHeaderEdge(cookieHeader).find(
+      (entry) =>
+        entry.name === 'tuturuuu_app_session' ||
+        GENERIC_SUPABASE_AUTH_COOKIE_NAME_PATTERN.test(entry.name)
+    ) ?? null;
+
+  return cookie ? buildProxySessionSubjectKey(cookie.name, cookie.value) : null;
+}
+
 /**
  * Mirrors `reputation.ts getCidrSubjectKey` so the edge cidr subject key matches
  * the DB-side trusted-location key.
@@ -935,7 +1060,7 @@ async function resolveProxyIdentity(
   const normalizedIp = ip && ip !== 'unknown' ? ip : null;
   const sessionCookie = getSessionAuthCookie(req);
   const sessionKey = sessionCookie
-    ? `session:${await hashStableSubjectEdge(`${sessionCookie.name}:${sessionCookie.value}`)}`
+    ? await buildProxySessionSubjectKey(sessionCookie.name, sessionCookie.value)
     : null;
 
   return {
@@ -1050,6 +1175,13 @@ function getEffectiveRateLimits(
   callerClass: CallerClass
 ): RateLimitProfile {
   if (callerClass === 'authenticated') {
+    if (routePolicy.key === 'default') {
+      return {
+        get: DEFAULT_AUTHENTICATED_READ_RATE_LIMITS,
+        mutate: DEFAULT_MUTATE_RATE_LIMITS,
+      };
+    }
+
     return routePolicy.rateLimits;
   }
 
@@ -1161,75 +1293,102 @@ export async function guardApiProxyRequest(
     const callerClass = getCallerClass(req);
     const ip = extractIPFromRequest(req.headers);
     const identity = await resolveProxyIdentity(req, ip);
+    const routePolicy = getRoutePolicy(req, routePolicies);
 
     if (ip !== 'unknown') {
       const blockInfo = await isIPBlockedEdge(ip);
       if (blockInfo) {
-        const retryAfter = Math.max(
-          1,
-          Math.ceil((blockInfo.expiresAt.getTime() - Date.now()) / 1000)
-        );
-
-        return buildRateLimitResponse(429, retryAfter, {
-          'X-Proxy-Block-Reason': 'ip-already-blocked',
-        });
+        const hasTemporaryRelief =
+          routePolicy.key === 'rate-limit-appeal' ||
+          (identity.sessionKey && identity.ipKey
+            ? await hasCachedIpBlockAppealRelief(
+                identity.sessionKey,
+                identity.ipKey
+              )
+            : false);
+
+        if (hasTemporaryRelief) {
+          // Keep processing: appeal submissions and matching temporary relief
+          // still go through the route limiter below.
+        } else {
+          const retryAfter = Math.max(
+            1,
+            Math.ceil((blockInfo.expiresAt.getTime() - Date.now()) / 1000)
+          );
+
+          return buildRateLimitResponse(429, retryAfter, {
+            'X-Proxy-Block-Reason': 'ip-already-blocked',
+          });
+        }
       }
     }
 
-    const routePolicy = getRoutePolicy(req, routePolicies);
     const isRead = req.method === 'GET' || req.method === 'HEAD';
 
-    // Resolve trust for reads only. Account trust (session key) and location
+    // Resolve server-verified session keying for reads and mutations, but apply
+    // trust uplift to read limits only. Account trust (session key) and location
     // trust (cidr/ip keys) are distinguished so that:
-    //   * a genuinely trusted SESSION (cache entry keyed on the real cookie's
-    //     hash — unforgeable) gets its OWN per-session bucket, so trusted
+    //   * a server-verified SESSION (cache entry keyed on the real cookie's
+    //     hash — unforgeable) gets its OWN per-session bucket, so signed-in
     //     teammates behind one NAT no longer collide; and
     //   * a trusted LOCATION (office cidr/ip) uplifts the shared per-IP bucket
     //     for the whole team without any per-request credential.
     // Untrusted traffic keeps legacy per-IP keying, preserving single-IP abuse
-    // caps. A forged cookie hashes to a key with no cache entry → no uplift,
-    // no per-session escape.
+    // caps. A forged cookie hashes to a key with no cache entry, so it cannot
+    // escape the shared IP bucket.
     let trustEntry: CachedTrustEntry | null = null;
-    let sessionTrusted = false;
-    if (isRead && edgeTrustEnabled()) {
+    let sessionScoped = false;
+    if (edgeTrustEnabled()) {
       const lookupKeys = [
         identity.sessionKey,
-        identity.cidrKey,
-        identity.ipKey,
-        identity.workspaceKey,
+        ...(isRead
+          ? [identity.cidrKey, identity.ipKey, identity.workspaceKey]
+          : []),
       ].filter((key): key is string => key != null);
       const entries = await getCachedTrustEntries(lookupKeys);
 
       const sessionEntry = identity.sessionKey
         ? entries.get(identity.sessionKey)
         : undefined;
-      // Location/workspace trust applies to the shared per-IP bucket for the
-      // whole team; session trust applies to the per-session bucket.
-      const locationEntry = combineTrustEntries([
-        identity.cidrKey ? entries.get(identity.cidrKey) : undefined,
-        identity.ipKey ? entries.get(identity.ipKey) : undefined,
-        identity.workspaceKey ? entries.get(identity.workspaceKey) : undefined,
-      ]);
-
-      trustEntry = combineTrustEntries([sessionEntry, locationEntry]);
-      sessionTrusted = !!identity.sessionKey && !!sessionEntry;
+      sessionScoped = !!identity.sessionKey && !!sessionEntry;
+
+      if (isRead) {
+        // Location/workspace trust applies to the shared per-IP bucket for the
+        // whole team; session trust applies to the per-session bucket.
+        const locationEntry = combineTrustEntries([
+          identity.cidrKey ? entries.get(identity.cidrKey) : undefined,
+          identity.ipKey ? entries.get(identity.ipKey) : undefined,
+          identity.workspaceKey
+            ? entries.get(identity.workspaceKey)
+            : undefined,
+        ]);
+
+        trustEntry = combineTrustEntries([sessionEntry, locationEntry]);
+      }
     }
 
-    // Trusted sessions key per-session; everyone else keys per-IP.
+    // Server-verified sessions key per-session; everyone else keys per-IP.
     const limiterId =
-      sessionTrusted && identity.sessionKey
+      sessionScoped && identity.sessionKey
         ? identity.sessionKey
         : identity.ipKey;
 
     if (limiterId) {
-      const baseRateLimits = getEffectiveRateLimits(routePolicy, callerClass);
-      const { profile: rateLimits, suffix: trustSuffix } =
-        applyTrustEntryToReads(baseRateLimits, trustEntry);
+      const effectiveCallerClass: CallerClass = sessionScoped
+        ? 'authenticated'
+        : callerClass;
+      const baseRateLimits = getEffectiveRateLimits(
+        routePolicy,
+        effectiveCallerClass
+      );
+      const { profile: rateLimits, suffix: trustSuffix } = isRead
+        ? applyTrustEntryToReads(baseRateLimits, trustEntry)
+        : { profile: baseRateLimits, suffix: '' };
 
       const limiterPrefix = getRateLimitPrefix(
         options.prefixBase,
         routePolicy,
-        callerClass,
+        effectiveCallerClass,
         trustSuffix
       );
       const limiterCacheKey = `${limiterPrefix}:${JSON.stringify(rateLimits)}`;
@@ -1283,7 +1442,7 @@ export async function guardApiProxyRequest(
             'X-RateLimit-Limit': `${limit}`,
             'X-RateLimit-Remaining': `${remaining}`,
             'X-RateLimit-Reset': `${Math.ceil(reset / 1000)}`,
-            'X-RateLimit-Caller-Class': callerClass,
+            'X-RateLimit-Caller-Class': effectiveCallerClass,
             'X-RateLimit-Window': window,
             'X-RateLimit-Policy': routePolicy.key,
           });

package/src/currencies.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import {
+  getCurrencyConfig,
+  getCurrencyLocale,
+  isSupportedCurrency,
+  resolveSupportedCurrency,
+} from './currencies';
+
+describe('resolveSupportedCurrency', () => {
+  it('normalizes supported currency codes', () => {
+    expect(resolveSupportedCurrency(' sgd ')).toBe('SGD');
+    expect(resolveSupportedCurrency('eur')).toBe('EUR');
+  });
+
+  it('uses a supported fallback for missing or unsupported values', () => {
+    expect(resolveSupportedCurrency(undefined, 'VND')).toBe('VND');
+    expect(resolveSupportedCurrency(null, 'EUR')).toBe('EUR');
+    expect(resolveSupportedCurrency('XYZ', 'SGD')).toBe('SGD');
+  });
+
+  it('falls back to USD when the fallback is unsupported', () => {
+    expect(resolveSupportedCurrency('', 'XYZ')).toBe('USD');
+    expect(resolveSupportedCurrency('ZZZ', 'XYZ')).toBe('USD');
+  });
+});
+
+describe('currency lookup normalization', () => {
+  it('trims currency codes before support and locale checks', () => {
+    expect(isSupportedCurrency(' vnd ')).toBe(true);
+    expect(getCurrencyLocale(' php ')).toBe('en-PH');
+    expect(getCurrencyConfig(' eur ')?.code).toBe('EUR');
+  });
+});

package/src/currencies.ts

@@ -66,9 +66,8 @@ export type CurrencyConfig = (typeof SUPPORTED_CURRENCIES)[number];
  * @returns The BCP 47 locale string for the currency
  */
 export function getCurrencyLocale(currency = 'VND'): string {
-  const found = SUPPORTED_CURRENCIES.find(
-    (c) => c.code === currency.toUpperCase()
-  );
+  const code = currency.trim().toUpperCase();
+  const found = SUPPORTED_CURRENCIES.find((c) => c.code === code);
   return found?.locale ?? 'en-US';
 }
 
@@ -81,7 +80,30 @@ export function getCurrencyLocale(currency = 'VND'): string {
 export function isSupportedCurrency(
   currency: string
 ): currency is SupportedCurrency {
-  return SUPPORTED_CURRENCIES.some((c) => c.code === currency.toUpperCase());
+  const code = currency.trim().toUpperCase();
+  return SUPPORTED_CURRENCIES.some((c) => c.code === code);
+}
+
+/**
+ * Normalize a currency code to the supported uppercase code set.
+ *
+ * @param value - The candidate currency code
+ * @param fallback - The fallback currency code when value is missing or unsupported
+ * @returns A supported currency code
+ */
+export function resolveSupportedCurrency(
+  value: string | null | undefined,
+  fallback: string = 'USD'
+): SupportedCurrency {
+  const normalizedFallback = fallback.trim().toUpperCase();
+  const safeFallback = isSupportedCurrency(normalizedFallback)
+    ? normalizedFallback
+    : 'USD';
+  const normalizedValue = value?.trim().toUpperCase();
+
+  return normalizedValue && isSupportedCurrency(normalizedValue)
+    ? normalizedValue
+    : safeFallback;
 }
 
 /**
@@ -93,5 +115,6 @@ export function isSupportedCurrency(
 export function getCurrencyConfig(
   currency: string
 ): CurrencyConfig | undefined {
-  return SUPPORTED_CURRENCIES.find((c) => c.code === currency.toUpperCase());
+  const code = currency.trim().toUpperCase();
+  return SUPPORTED_CURRENCIES.find((c) => c.code === code);
 }