@tuturuuu/utils 0.0.3 → 0.6.0

package/src/abuse-protection/user-agent.ts

@@ -0,0 +1,124 @@
+export type UserAgentRiskLevel = 'allow' | 'block';
+
+export interface UserAgentClassification {
+  matchedPattern: string | null;
+  normalizedUserAgent: string | null;
+  reason: string | null;
+  riskLevel: UserAgentRiskLevel;
+}
+
+const NATIVE_APP_SIGNATURE_REGEX =
+  /\b(?:cfnetwork|dart(?:\/|\s)|dart:io|dalvik|flutter|okhttp)\b/i;
+const KNOWN_AUTOMATION_REGEX =
+  /\b(?:headlesschrome|phantomjs|puppeteer|playwright|selenium|webdriver)\b/i;
+const KNOWN_SCRIPT_CLIENT_REGEX =
+  /\b(?:axios\/|curl\/|go-http-client|java\/|node-fetch|python-requests|wget\/)\b/i;
+const KNOWN_CRAWLER_REGEX = /\b(?:bot|crawler|scrapy|spider)\b/i;
+const BROWSER_SIGNATURE_REGEX =
+  /\b(?:applewebkit|chrome\/|edg\/|firefox\/|gecko\/|mozilla\/5\.0|opr\/|safari\/|version\/)\b/i;
+
+function normalizeUserAgent(value?: string | null) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+export function extractUserAgentFromHeaders(
+  headers: Headers | Map<string, string> | Record<string, string | null>
+) {
+  if (headers instanceof Headers) {
+    return normalizeUserAgent(headers.get('user-agent'));
+  }
+
+  if (headers instanceof Map) {
+    return normalizeUserAgent(headers.get('user-agent') || null);
+  }
+
+  return normalizeUserAgent(headers['user-agent']);
+}
+
+export function classifyPotentialSpamUserAgent(
+  userAgent?: string | null,
+  options: { allowNativeAppUserAgents?: boolean } = {}
+): UserAgentClassification {
+  const normalizedUserAgent = normalizeUserAgent(userAgent);
+
+  if (!normalizedUserAgent) {
+    return {
+      matchedPattern: null,
+      normalizedUserAgent,
+      reason: 'missing_user_agent',
+      riskLevel: 'block',
+    };
+  }
+
+  if (
+    options.allowNativeAppUserAgents &&
+    NATIVE_APP_SIGNATURE_REGEX.test(normalizedUserAgent)
+  ) {
+    return {
+      matchedPattern: null,
+      normalizedUserAgent,
+      reason: null,
+      riskLevel: 'allow',
+    };
+  }
+
+  const blockedMatchers = [
+    {
+      reason: 'known_automation_framework',
+      regex: KNOWN_AUTOMATION_REGEX,
+    },
+    {
+      reason: 'scripted_http_client',
+      regex: KNOWN_SCRIPT_CLIENT_REGEX,
+    },
+    {
+      reason: 'known_crawler_agent',
+      regex: KNOWN_CRAWLER_REGEX,
+    },
+  ] as const;
+
+  for (const matcher of blockedMatchers) {
+    const match = normalizedUserAgent.match(matcher.regex);
+    if (match) {
+      return {
+        matchedPattern: match[0] || null,
+        normalizedUserAgent,
+        reason: matcher.reason,
+        riskLevel: 'block',
+      };
+    }
+  }
+
+  if (normalizedUserAgent.length < 20) {
+    return {
+      matchedPattern: null,
+      normalizedUserAgent,
+      reason: 'short_user_agent',
+      riskLevel: 'block',
+    };
+  }
+
+  if (
+    normalizedUserAgent.startsWith('Mozilla/5.0') &&
+    !BROWSER_SIGNATURE_REGEX.test(normalizedUserAgent)
+  ) {
+    return {
+      matchedPattern: 'Mozilla/5.0',
+      normalizedUserAgent,
+      reason: 'malformed_browser_claim',
+      riskLevel: 'block',
+    };
+  }
+
+  return {
+    matchedPattern: null,
+    normalizedUserAgent,
+    reason: null,
+    riskLevel: 'allow',
+  };
+}

package/src/abuse-protection/user-suspension.ts

@@ -0,0 +1,231 @@
+/**
+ * User suspension utilities.
+ * Checks and manages user account suspensions.
+ */
+
+import { getUpstashRestRedisClient } from '../upstash-rest';
+import type { RedisClient } from './types';
+
+// Extend REDIS_KEYS locally (avoids modifying shared constants for this feature)
+const SUSPENSION_KEYS = {
+  USER_SUSPENDED: (userId: string) => `user:suspended:${userId}`,
+} as const;
+
+interface SuspensionResult {
+  suspended: boolean;
+  reason?: string;
+  expiresAt?: Date;
+}
+
+// Lazy-loaded Redis client
+let redisClient: RedisClient | null = null;
+let redisInitialized = false;
+
+async function getRedisClient(): Promise<RedisClient | null> {
+  if (redisInitialized) return redisClient;
+
+  try {
+    redisClient = await getUpstashRestRedisClient();
+    redisInitialized = true;
+    return redisClient;
+  } catch {
+    redisInitialized = true;
+    return null;
+  }
+}
+
+async function getSupabaseAdmin() {
+  try {
+    const { createAdminClient } = await import(
+      '@tuturuuu/supabase/next/server'
+    );
+    return await createAdminClient();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a user is currently suspended.
+ * Checks Redis cache first (60s TTL), then falls back to DB.
+ */
+export async function checkUserSuspension(
+  userId: string
+): Promise<SuspensionResult> {
+  const redis = await getRedisClient();
+
+  // Check Redis cache first
+  if (redis) {
+    try {
+      const cached = await redis.get<string>(
+        SUSPENSION_KEYS.USER_SUSPENDED(userId)
+      );
+      if (cached === 'not_suspended') {
+        return { suspended: false };
+      }
+      if (cached && cached !== 'not_suspended') {
+        const data = typeof cached === 'string' ? JSON.parse(cached) : cached;
+        if (!data.expiresAt || new Date(data.expiresAt) > new Date()) {
+          return {
+            suspended: true,
+            reason: data.reason,
+            expiresAt: data.expiresAt ? new Date(data.expiresAt) : undefined,
+          };
+        }
+      }
+    } catch {
+      // Fall through to DB check
+    }
+  }
+
+  // Check database
+  try {
+    const sbAdmin = await getSupabaseAdmin();
+    if (!sbAdmin) return { suspended: false };
+
+    const { data, error } = await sbAdmin
+      .from('user_suspensions')
+      .select('id, reason, expires_at')
+      .eq('user_id', userId)
+      .is('lifted_at', null)
+      .or('expires_at.is.null,expires_at.gt.now()')
+      .order('suspended_at', { ascending: false })
+      .limit(1)
+      .maybeSingle();
+
+    if (error || !data) {
+      // Cache negative result
+      if (redis) {
+        await redis.set(
+          SUSPENSION_KEYS.USER_SUSPENDED(userId),
+          'not_suspended',
+          { ex: 60 }
+        );
+      }
+      return { suspended: false };
+    }
+
+    const result: SuspensionResult = {
+      suspended: true,
+      reason: data.reason,
+      expiresAt: data.expires_at ? new Date(data.expires_at) : undefined,
+    };
+
+    // Cache positive result
+    if (redis) {
+      const ttl = data.expires_at
+        ? Math.min(
+            60,
+            Math.ceil((new Date(data.expires_at).getTime() - Date.now()) / 1000)
+          )
+        : 60;
+      await redis.set(
+        SUSPENSION_KEYS.USER_SUSPENDED(userId),
+        JSON.stringify({
+          reason: data.reason,
+          expiresAt: data.expires_at,
+        }),
+        { ex: Math.max(1, ttl) }
+      );
+    }
+
+    return result;
+  } catch {
+    // Fail-open: if check fails, don't block user
+    return { suspended: false };
+  }
+}
+
+/**
+ * Suspend a user account.
+ */
+export async function suspendUser(
+  userId: string,
+  reason: string,
+  suspendedBy: string | null,
+  expiresAt?: Date
+): Promise<boolean> {
+  try {
+    const sbAdmin = await getSupabaseAdmin();
+    if (!sbAdmin) return false;
+
+    const { error } = await sbAdmin.from('user_suspensions').insert({
+      user_id: userId,
+      reason,
+      suspended_by: suspendedBy,
+      expires_at: expiresAt?.toISOString() ?? null,
+    });
+
+    if (error) {
+      console.error('[User Suspension] Error suspending user:', error);
+      return false;
+    }
+
+    // Update Redis cache
+    const redis = await getRedisClient();
+    if (redis) {
+      const ttl = expiresAt
+        ? Math.ceil((expiresAt.getTime() - Date.now()) / 1000)
+        : 60;
+      await redis.set(
+        SUSPENSION_KEYS.USER_SUSPENDED(userId),
+        JSON.stringify({
+          reason,
+          expiresAt: expiresAt?.toISOString() ?? null,
+        }),
+        { ex: Math.max(1, ttl) }
+      );
+    }
+
+    return true;
+  } catch (error) {
+    console.error('[User Suspension] Error:', error);
+    return false;
+  }
+}
+
+/**
+ * Lift a user suspension.
+ */
+export async function liftSuspension(
+  suspensionId: string,
+  liftedBy: string
+): Promise<boolean> {
+  try {
+    const sbAdmin = await getSupabaseAdmin();
+    if (!sbAdmin) return false;
+
+    // Get the suspension to find the user_id
+    const { data: suspension } = await sbAdmin
+      .from('user_suspensions')
+      .select('user_id')
+      .eq('id', suspensionId)
+      .single();
+
+    if (!suspension) return false;
+
+    const { error } = await sbAdmin
+      .from('user_suspensions')
+      .update({
+        lifted_at: new Date().toISOString(),
+        lifted_by: liftedBy,
+      })
+      .eq('id', suspensionId);
+
+    if (error) {
+      console.error('[User Suspension] Error lifting suspension:', error);
+      return false;
+    }
+
+    // Clear Redis cache so next check hits DB
+    const redis = await getRedisClient();
+    if (redis) {
+      await redis.del(SUSPENSION_KEYS.USER_SUSPENDED(suspension.user_id));
+    }
+
+    return true;
+  } catch (error) {
+    console.error('[User Suspension] Error:', error);
+    return false;
+  }
+}

package/src/ai-temp-auth.ts

@@ -0,0 +1,315 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { getUpstashRestRedisClient } from './upstash-rest';
+
+export const AI_TEMP_AUTH_HEADER = 'x-tuturuuu-ai-temp-auth';
+export const AI_TEMP_AUTH_TTL_SECONDS = 60;
+export const AI_CREDIT_SNAPSHOT_TTL_SECONDS = 15;
+
+const USER_VERSION_TTL_SECONDS = 24 * 60 * 60;
+const CREDIT_SNAPSHOT_MAX_AGE_MS = AI_CREDIT_SNAPSHOT_TTL_SECONDS * 1000;
+const MINIMUM_SNAPSHOT_REMAINING_CREDITS = 50;
+
+type AiTempAuthUser = {
+  id: string;
+  email?: string | null;
+};
+
+export type AiTempAuthContext = {
+  user: AiTempAuthUser;
+  wsId?: string;
+  creditWsId?: string;
+  creditSource?: 'personal' | 'workspace';
+};
+
+type AiTempAuthPayload = AiTempAuthContext & {
+  tokenId: string;
+  authVersion: string;
+  issuedAt: number;
+  expiresAt: number;
+};
+
+export type AiTempAuthValidationResult =
+  | { status: 'missing' }
+  | { status: 'unavailable' }
+  | { status: 'invalid' }
+  | { status: 'expired' }
+  | { status: 'revoked' }
+  | { status: 'valid'; context: AiTempAuthContext };
+
+export type AiCreditSnapshot = {
+  remainingCredits: number;
+  maxOutputTokens: number | null;
+  tier: string;
+  allowedModels: string[];
+  allowedFeatures: string[];
+  dailyLimit: number | null;
+  updatedAt: number;
+};
+
+function tokenKey(digest: string) {
+  return `ai:temp-auth:token:${digest}`;
+}
+
+function userVersionKey(userId: string) {
+  return `ai:temp-auth:user-version:${userId}`;
+}
+
+function creditSnapshotKey({ wsId, userId }: { wsId: string; userId: string }) {
+  return `ai:credits:snapshot:${wsId}:${userId}`;
+}
+
+function creditInFlightKey({ wsId, userId }: { wsId: string; userId: string }) {
+  return `ai:credits:in-flight:${wsId}:${userId}`;
+}
+
+function digestToken(token: string) {
+  return createHash('sha256').update(token).digest('hex');
+}
+
+function getBearerToken(request: Pick<Request, 'headers'>) {
+  const value = request.headers.get(AI_TEMP_AUTH_HEADER);
+  return value?.trim() || null;
+}
+
+function isPayload(value: unknown): value is AiTempAuthPayload {
+  if (!value || typeof value !== 'object') return false;
+  const payload = value as Partial<AiTempAuthPayload>;
+
+  return (
+    typeof payload.tokenId === 'string' &&
+    typeof payload.authVersion === 'string' &&
+    typeof payload.issuedAt === 'number' &&
+    typeof payload.expiresAt === 'number' &&
+    !!payload.user &&
+    typeof payload.user === 'object' &&
+    typeof payload.user.id === 'string'
+  );
+}
+
+export async function mintAiTempAuthToken({
+  user,
+  wsId,
+  creditWsId,
+  creditSource,
+}: AiTempAuthContext): Promise<{
+  token: string;
+  expiresAt: number;
+} | null> {
+  const redis = await getUpstashRestRedisClient().catch(() => null);
+  if (!redis) return null;
+
+  const authVersion =
+    (
+      await redis.get<string>(userVersionKey(user.id)).catch(() => null)
+    )?.toString() ?? '0';
+  const tokenId = randomUUID();
+  const secret = randomBytes(32).toString('base64url');
+  const token = `${tokenId}.${secret}`;
+  const now = Date.now();
+  const expiresAt = now + AI_TEMP_AUTH_TTL_SECONDS * 1000;
+
+  const payload: AiTempAuthPayload = {
+    tokenId,
+    user: { id: user.id, email: user.email ?? null },
+    ...(wsId ? { wsId } : {}),
+    ...(creditWsId ? { creditWsId } : {}),
+    ...(creditSource ? { creditSource } : {}),
+    authVersion,
+    issuedAt: now,
+    expiresAt,
+  };
+
+  try {
+    await redis.set(tokenKey(digestToken(token)), payload, {
+      ex: AI_TEMP_AUTH_TTL_SECONDS,
+    });
+  } catch {
+    return null;
+  }
+
+  return { token, expiresAt };
+}
+
+export async function validateAiTempAuthRequest(
+  request: Pick<Request, 'headers'>
+): Promise<AiTempAuthValidationResult> {
+  const token = getBearerToken(request);
+  if (!token) return { status: 'missing' };
+
+  const redis = await getUpstashRestRedisClient().catch(() => null);
+  if (!redis) return { status: 'unavailable' };
+
+  const payload = await redis
+    .get<AiTempAuthPayload>(tokenKey(digestToken(token)))
+    .catch(() => null);
+  if (!isPayload(payload)) return { status: 'invalid' };
+
+  if (payload.expiresAt <= Date.now()) {
+    return { status: 'expired' };
+  }
+
+  const currentVersion =
+    (
+      await redis.get<string>(userVersionKey(payload.user.id)).catch(() => null)
+    )?.toString() ?? '0';
+  if (currentVersion !== payload.authVersion) {
+    return { status: 'revoked' };
+  }
+
+  return {
+    status: 'valid',
+    context: {
+      user: payload.user,
+      ...(payload.wsId ? { wsId: payload.wsId } : {}),
+      ...(payload.creditWsId ? { creditWsId: payload.creditWsId } : {}),
+      ...(payload.creditSource ? { creditSource: payload.creditSource } : {}),
+    },
+  };
+}
+
+export async function revokeUserAiTempAuthTokens(
+  userId: string
+): Promise<boolean> {
+  const redis = await getUpstashRestRedisClient().catch(() => null);
+  if (!redis) return false;
+
+  try {
+    await redis.incr(userVersionKey(userId));
+    await redis.expire(userVersionKey(userId), USER_VERSION_TTL_SECONDS);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function writeAiCreditSnapshot({
+  wsId,
+  userId,
+  snapshot,
+}: {
+  wsId: string;
+  userId: string;
+  snapshot: AiCreditSnapshot;
+}): Promise<boolean> {
+  const redis = await getUpstashRestRedisClient().catch(() => null);
+  if (!redis) return false;
+
+  try {
+    await redis.set(creditSnapshotKey({ wsId, userId }), snapshot, {
+      ex: AI_CREDIT_SNAPSHOT_TTL_SECONDS,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readAiCreditSnapshot({
+  wsId,
+  userId,
+}: {
+  wsId: string;
+  userId: string;
+}): Promise<AiCreditSnapshot | null> {
+  const redis = await getUpstashRestRedisClient().catch(() => null);
+  if (!redis) return null;
+
+  const snapshot = await redis
+    .get<AiCreditSnapshot>(creditSnapshotKey({ wsId, userId }))
+    .catch(() => null);
+  return snapshot ?? null;
+}
+
+export async function invalidateAiCreditSnapshot({
+  wsId,
+  userId,
+}: {
+  wsId: string;
+  userId: string;
+}): Promise<boolean> {
+  const redis = await getUpstashRestRedisClient().catch(() => null);
+  if (!redis) return false;
+
+  try {
+    await redis.del(creditSnapshotKey({ wsId, userId }));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function incrementAiCreditChargeInFlight({
+  wsId,
+  userId,
+}: {
+  wsId: string;
+  userId: string;
+}): Promise<boolean> {
+  const redis = await getUpstashRestRedisClient().catch(() => null);
+  if (!redis) return false;
+
+  try {
+    const key = creditInFlightKey({ wsId, userId });
+    await redis.incr(key);
+    await redis.expire(key, AI_TEMP_AUTH_TTL_SECONDS);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function decrementAiCreditChargeInFlight({
+  wsId,
+  userId,
+}: {
+  wsId: string;
+  userId: string;
+}): Promise<boolean> {
+  const redis = await getUpstashRestRedisClient().catch(() => null);
+  if (!redis) return false;
+
+  try {
+    const key = creditInFlightKey({ wsId, userId });
+    const value = await redis.decr(key);
+    if (Number(value) <= 0) {
+      await redis.del(key);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function hasAiCreditChargeInFlight({
+  wsId,
+  userId,
+}: {
+  wsId: string;
+  userId: string;
+}): Promise<boolean> {
+  const redis = await getUpstashRestRedisClient().catch(() => null);
+  if (!redis) return false;
+
+  try {
+    const value = await redis.get<number | string>(
+      creditInFlightKey({ wsId, userId })
+    );
+    return Number(value ?? 0) > 0;
+  } catch {
+    return false;
+  }
+}
+
+export function isAiCreditSnapshotUsable(
+  snapshot: AiCreditSnapshot | null | undefined,
+  options: { inFlight?: boolean; now?: number } = {}
+): snapshot is AiCreditSnapshot {
+  if (!snapshot) return false;
+  if (options.inFlight) return false;
+  if (snapshot.remainingCredits < MINIMUM_SNAPSHOT_REMAINING_CREDITS) {
+    return false;
+  }
+
+  const now = options.now ?? Date.now();
+  return now - snapshot.updatedAt <= CREDIT_SNAPSHOT_MAX_AGE_MS;
+}