vibes-plug 1.0.0 → 2.5.0

package/skills/rate-limit-abuse-prevention/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: rate-limit-abuse-prevention
+description: "Expert guide for API rate limiting, bot protection, DDoS mitigation, brute-force prevention, and abuse detection / Panduan ahli untuk rate limiting API, perlindungan bot, mitigasi DDoS, pencegahan brute-force, dan deteksi penyalahgunaan."
+author: "Roedy Rustam"
+---
+
+# Rate Limit & Abuse Prevention (2026 Edition)
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Description
+Production-grade guide for protecting APIs and web applications from abuse, overuse, and attacks. Covers **rate limiting algorithms** (Token Bucket, Sliding Window), **Upstash Ratelimit**, **bot protection** (Cloudflare Turnstile, hCaptcha), **DDoS mitigation** at edge, **brute-force login prevention**, **API key management & usage quotas**, and **response headers** (X-RateLimit, Retry-After).
+
+### Trigger Conditions
+Activate this skill when:
+- Implementing API rate limiting for public or authenticated endpoints.
+- Adding bot protection (CAPTCHA) to forms (login, signup, contact).
+- Setting up DDoS protection at the edge (Cloudflare, Vercel).
+- Preventing brute-force attacks on authentication endpoints.
+- Implementing API key issuance and usage quotas for SaaS.
+- Building tiered rate limits based on subscription plans.
+
+---
+
+### Rate Limiting Algorithm Comparison
+
+| Algorithm | Behavior | Best For | Burst Handling |
+|---|---|---|---|
+| **Fixed Window** | Resets counter at interval boundary | Simple endpoints | Allows double burst at window edge |
+| **Sliding Window** | Rolling window, smooth distribution | API endpoints | Smooth, no edge burst |
+| **Token Bucket** | Tokens refill at fixed rate | High-throughput APIs | Allows controlled bursts |
+| **Leaky Bucket** | Processes at fixed rate, queues excess | Stream processing | No bursts, constant rate |
+
+**Recommendation**: Use **Sliding Window** for most API endpoints. Use **Token Bucket** for endpoints that should allow burst traffic.
+
+---
+
+### 1. Upstash Ratelimit (Edge-Compatible)
+
+```typescript
+// lib/ratelimit.ts
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const redis = Redis.fromEnv();
+
+// Different rate limiters for different tiers
+export const rateLimiters = {
+  /** Public API: 10 requests per 10 seconds */
+  public: new Ratelimit({
+    redis,
+    limiter: Ratelimit.slidingWindow(10, '10s'),
+    prefix: 'rl:public',
+    analytics: true,
+  }),
+
+  /** Authenticated API: 100 requests per minute */
+  authenticated: new Ratelimit({
+    redis,
+    limiter: Ratelimit.slidingWindow(100, '1m'),
+    prefix: 'rl:auth',
+    analytics: true,
+  }),
+
+  /** Pro tier: 1000 requests per minute */
+  pro: new Ratelimit({
+    redis,
+    limiter: Ratelimit.slidingWindow(1000, '1m'),
+    prefix: 'rl:pro',
+    analytics: true,
+  }),
+
+  /** Login endpoint: 5 attempts per 15 minutes */
+  login: new Ratelimit({
+    redis,
+    limiter: Ratelimit.slidingWindow(5, '15m'),
+    prefix: 'rl:login',
+  }),
+
+  /** Password reset: 3 per hour */
+  passwordReset: new Ratelimit({
+    redis,
+    limiter: Ratelimit.slidingWindow(3, '1h'),
+    prefix: 'rl:pwreset',
+  }),
+};
+```
+
+```typescript
+// middleware.ts (Next.js)
+import { NextResponse, type NextRequest } from 'next/server';
+import { rateLimiters } from '@/lib/ratelimit';
+
+export async function middleware(request: NextRequest) {
+  if (request.nextUrl.pathname.startsWith('/api/')) {
+    const ip = request.headers.get('x-forwarded-for') ?? request.ip ?? '127.0.0.1';
+    const identifier = ip;
+
+    const limiter = request.nextUrl.pathname.startsWith('/api/auth/login')
+      ? rateLimiters.login
+      : rateLimiters.public;
+
+    const { success, limit, remaining, reset } = await limiter.limit(identifier);
+
+    if (!success) {
+      return NextResponse.json(
+        { error: 'Too many requests', retryAfter: Math.ceil((reset - Date.now()) / 1000) },
+        {
+          status: 429,
+          headers: {
+            'X-RateLimit-Limit': limit.toString(),
+            'X-RateLimit-Remaining': '0',
+            'X-RateLimit-Reset': reset.toString(),
+            'Retry-After': Math.ceil((reset - Date.now()) / 1000).toString(),
+          },
+        },
+      );
+    }
+
+    const response = NextResponse.next();
+    response.headers.set('X-RateLimit-Limit', limit.toString());
+    response.headers.set('X-RateLimit-Remaining', remaining.toString());
+    response.headers.set('X-RateLimit-Reset', reset.toString());
+    return response;
+  }
+}
+
+export const config = { matcher: '/api/:path*' };
+```
+
+---
+
+### 2. Tiered Rate Limits for SaaS
+
+```typescript
+// lib/tiered-ratelimit.ts
+import { Ratelimit } from '@upstash/ratelimit';
+
+type PlanTier = 'free' | 'pro' | 'enterprise';
+
+const PLAN_LIMITS: Record<PlanTier, { requests: number; window: string }> = {
+  free:       { requests: 100,    window: '1h' },
+  pro:        { requests: 5000,   window: '1h' },
+  enterprise: { requests: 50000,  window: '1h' },
+};
+
+export function getRateLimiterForPlan(plan: PlanTier): Ratelimit {
+  const config = PLAN_LIMITS[plan];
+  return new Ratelimit({
+    redis,
+    limiter: Ratelimit.slidingWindow(config.requests, config.window as any),
+    prefix: `rl:api:${plan}`,
+  });
+}
+
+// Usage in API route
+export async function GET(request: Request) {
+  const user = await getAuthUser(request);
+  const limiter = getRateLimiterForPlan(user.plan);
+  const { success, remaining } = await limiter.limit(user.id);
+
+  if (!success) {
+    return Response.json({
+      error: 'Rate limit exceeded',
+      upgrade: user.plan !== 'enterprise' ? 'https://app.example.com/pricing' : undefined,
+    }, { status: 429 });
+  }
+
+  // ...handle request
+}
+```
+
+---
+
+### 3. Bot Protection (Cloudflare Turnstile)
+
+```tsx
+// components/turnstile.tsx
+'use client';
+
+import { Turnstile } from '@marsidev/react-turnstile';
+
+interface TurnstileWidgetProps {
+  onVerify: (token: string) => void;
+}
+
+export function TurnstileWidget({ onVerify }: TurnstileWidgetProps) {
+  return (
+    <Turnstile
+      siteKey={process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY!}
+      onSuccess={onVerify}
+      options={{ theme: 'auto', size: 'flexible' }}
+    />
+  );
+}
+```
+
+```typescript
+// Server-side verification
+export async function verifyTurnstileToken(token: string, ip?: string): Promise<boolean> {
+  const response = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      secret: process.env.TURNSTILE_SECRET_KEY,
+      response: token,
+      remoteip: ip,
+    }),
+  });
+
+  const data = await response.json();
+  return data.success === true;
+}
+```
+
+---
+
+### 4. Brute-Force Login Prevention
+
+```typescript
+// lib/login-protection.ts
+const MAX_ATTEMPTS = 5;
+const LOCKOUT_DURATION = 15 * 60; // 15 minutes in seconds
+const PROGRESSIVE_DELAYS = [0, 1000, 2000, 4000, 8000]; // Progressive delay per attempt
+
+export async function checkLoginAttempt(email: string, ip: string): Promise<{
+  allowed: boolean;
+  remainingAttempts: number;
+  lockoutEndsAt?: Date;
+}> {
+  const key = `login-attempts:${email}:${ip}`;
+  const attempts = await redis.incr(key);
+
+  if (attempts === 1) {
+    await redis.expire(key, LOCKOUT_DURATION);
+  }
+
+  if (attempts > MAX_ATTEMPTS) {
+    const ttl = await redis.ttl(key);
+    return {
+      allowed: false,
+      remainingAttempts: 0,
+      lockoutEndsAt: new Date(Date.now() + ttl * 1000),
+    };
+  }
+
+  // Progressive delay
+  const delay = PROGRESSIVE_DELAYS[Math.min(attempts - 1, PROGRESSIVE_DELAYS.length - 1)];
+  if (delay > 0) await new Promise(r => setTimeout(r, delay));
+
+  return { allowed: true, remainingAttempts: MAX_ATTEMPTS - attempts };
+}
+
+export async function clearLoginAttempts(email: string, ip: string): Promise<void> {
+  await redis.del(`login-attempts:${email}:${ip}`);
+}
+```
+
+---
+
+### 5. API Key Management
+
+```typescript
+// lib/api-keys.ts
+import { nanoid } from 'nanoid';
+import { hash, verify } from '@node-rs/argon2';
+
+export async function createApiKey(userId: string, name: string) {
+  const rawKey = `sk_live_${nanoid(32)}`;
+  const prefix = rawKey.slice(0, 12); // Show prefix for identification
+  const hashedKey = await hash(rawKey);
+
+  await db.insert(apiKeys).values({
+    userId,
+    name,
+    prefix,
+    hashedKey,
+    lastUsedAt: null,
+  });
+
+  // Return raw key only once — cannot be retrieved later
+  return { key: rawKey, prefix };
+}
+
+export async function validateApiKey(rawKey: string) {
+  const prefix = rawKey.slice(0, 12);
+  const candidates = await db.query.apiKeys.findMany({
+    where: and(
+      eq(apiKeys.prefix, prefix),
+      eq(apiKeys.isRevoked, false),
+    ),
+  });
+
+  for (const candidate of candidates) {
+    if (await verify(candidate.hashedKey, rawKey)) {
+      // Update last used timestamp
+      await db.update(apiKeys)
+        .set({ lastUsedAt: new Date() })
+        .where(eq(apiKeys.id, candidate.id));
+      return candidate;
+    }
+  }
+
+  return null;
+}
+```
+
+---
+
+### Response Headers Specification
+
+| Header | Purpose | Example |
+|---|---|---|
+| `X-RateLimit-Limit` | Max requests allowed | `100` |
+| `X-RateLimit-Remaining` | Remaining requests in window | `87` |
+| `X-RateLimit-Reset` | Unix timestamp when window resets | `1723382400` |
+| `Retry-After` | Seconds until retry is allowed (on 429) | `60` |
+
+---
+
+### Common Pitfalls to Avoid
+
+| Anti-Pattern | Problem | Correct Approach |
+|---|---|---|
+| Rate limiting by IP only | Shared IPs affect multiple users | Combine IP + user ID + API key |
+| No rate limit on auth endpoints | Brute-force attacks | Strict limits: 5 attempts / 15 min |
+| Fixed window rate limiting | 2x burst at window boundary | Use sliding window algorithm |
+| No 429 response headers | Clients can't implement backoff | Always include Retry-After header |
+| CAPTCHA on every request | Terrible UX, accessibility issues | Only trigger after suspicious behavior |
+| Rate limit in application only | Still hits your server | Add edge-level protection (Cloudflare WAF) |
+
+---
+
+### Integration with Other Skills
+
+- `authentication-identity-expert` — Brute-force prevention on login/signup endpoints
+- `api-design-expert` — Rate limit headers, API key patterns
+- `js-backend-expert` — Express/Fastify/Hono middleware integration
+- `saas-billing` — Tiered rate limits per subscription plan
+- `production-ready-hardener` — Pre-launch security audit
+- `cloud-hosting-expert` — Edge-level WAF and DDoS protection
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Deskripsi
+Panduan tingkat produksi untuk melindungi API dan aplikasi web dari penyalahgunaan, penggunaan berlebihan, dan serangan. Mencakup **algoritma rate limiting** (Token Bucket, Sliding Window), **Upstash Ratelimit**, **perlindungan bot** (Cloudflare Turnstile, hCaptcha), **mitigasi DDoS** di edge, **pencegahan brute-force login**, **manajemen API key & kuota penggunaan**, dan **header respons** (X-RateLimit, Retry-After).
+
+### Kondisi Pemicu
+Aktifkan skill ini ketika:
+- Mengimplementasikan rate limiting API untuk endpoint publik atau terautentikasi.
+- Menambahkan perlindungan bot (CAPTCHA) ke formulir.
+- Menyiapkan perlindungan DDoS di edge.
+- Mencegah serangan brute-force pada endpoint autentikasi.
+- Mengimplementasikan penerbitan API key dan kuota penggunaan untuk SaaS.
+
+### Integrasi dengan Skill Lain
+
+- `authentication-identity-expert` — Pencegahan brute-force pada endpoint login/signup
+- `api-design-expert` — Header rate limit, pola API key
+- `js-backend-expert` — Integrasi middleware Express/Fastify/Hono
+- `saas-billing` — Rate limit bertingkat per paket langganan
+- `production-ready-hardener` — Audit keamanan pra-peluncuran
+- `cloud-hosting-expert` — Perlindungan WAF dan DDoS di edge

package/skills/realtime-collaboration-expert/SKILL.md

@@ -1,45 +1,45 @@
----
-name: realtime-collaboration-expert
-description: "Expert guide for building real-time collaboration features using WebSockets, WebRTC, CRDTs (Yjs, Automerge), and Liveblocks / Panduan ahli untuk fitur kolaborasi real-time."
-author: "Antigravity"
----
-
-# Real-Time Collaboration Expert / Ahli Kolaborasi Real-Time
-
-[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
-
----
-
-<a name="english"></a>
-## English
-
-### Description
-Expert guide for implementing multiplayer, real-time collaboration features in web applications. Covers Conflict-free Replicated Data Types (CRDTs) like Yjs/Automerge, WebSockets, WebRTC, and Managed services like Liveblocks or Pusher.
-
-### Instructions
-- **CRDTs for State**: Use CRDTs (e.g., `yjs` or `automerge`) instead of Operational Transformation (OT) for handling distributed state and concurrent document editing smoothly.
-- **Connection Resiliency**: Always implement automatic reconnection logic with exponential backoff for WebSockets. Handle offline states gracefully by syncing local changes once reconnected.
-- **Presence & Awareness**: Implement presence indicators (who is online, cursor positions) separated from the core document state to reduce bandwidth and storage overhead.
-- **Security in Real-time**: Authenticate and authorize every WebSocket connection upon establishment and validate all incoming socket messages to prevent malicious payloads.
-- **Scale**: Be mindful of message broadcasting limits. Use Redis Pub/Sub or similar message brokers when scaling WebSocket servers across multiple instances.
-
-### Trigger Conditions
-Active whenever the user is building multiplayer features, live cursors, document co-editing, real-time chats, or working with WebSockets, Yjs, or WebRTC.
-
----
-
-<a name="bahasa-indonesia"></a>
-## Bahasa Indonesia
-
-### Deskripsi
-Panduan ahli untuk mengimplementasikan fitur kolaborasi real-time dan *multiplayer* pada aplikasi web. Mencakup Conflict-free Replicated Data Types (CRDTs) seperti Yjs/Automerge, WebSockets, WebRTC, dan layanan terkelola seperti Liveblocks atau Pusher.
-
-### Instruksi
-- **CRDT untuk State**: Gunakan CRDT (misalnya `yjs` atau `automerge`) daripada Operational Transformation (OT) untuk menangani *state* terdistribusi dan pengeditan dokumen secara bersamaan dengan lancar.
-- **Ketahanan Koneksi**: Selalu terapkan logika penyambungan ulang otomatis dengan *exponential backoff* untuk WebSockets. Tangani *offline state* dengan baik dengan menyinkronkan perubahan lokal setelah tersambung kembali.
-- **Presence & Awareness**: Terapkan indikator kehadiran (siapa yang sedang online, posisi kursor) yang dipisahkan dari status dokumen inti untuk mengurangi *overhead* bandwidth dan penyimpanan.
-- **Keamanan Real-time**: Lakukan autentikasi dan otorisasi setiap koneksi WebSocket pada saat tersambung dan validasi semua pesan *socket* yang masuk untuk mencegah *payload* berbahaya.
-- **Skalabilitas**: Perhatikan batas penyiaran (broadcasting) pesan. Gunakan Redis Pub/Sub atau *message broker* serupa saat meningkatkan (scaling) server WebSocket di beberapa instans.
-
-### Kondisi Pemicu
-Aktif setiap kali pengguna sedang membangun fitur *multiplayer*, kursor langsung (live cursors), pengeditan dokumen bersama, obrolan real-time, atau bekerja dengan WebSockets, Yjs, atau WebRTC.
+---
+name: realtime-collaboration-expert
+description: "Expert guide for building real-time collaboration features using WebSockets, WebRTC, CRDTs (Yjs, Automerge), and Liveblocks / Panduan ahli untuk fitur kolaborasi real-time."
+author: "Antigravity"
+---
+
+# Real-Time Collaboration Expert / Ahli Kolaborasi Real-Time
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Description
+Expert guide for implementing multiplayer, real-time collaboration features in web applications. Covers Conflict-free Replicated Data Types (CRDTs) like Yjs/Automerge, WebSockets, WebRTC, and Managed services like Liveblocks or Pusher.
+
+### Instructions
+- **CRDTs for State**: Use CRDTs (e.g., `yjs` or `automerge`) instead of Operational Transformation (OT) for handling distributed state and concurrent document editing smoothly.
+- **Connection Resiliency**: Always implement automatic reconnection logic with exponential backoff for WebSockets. Handle offline states gracefully by syncing local changes once reconnected.
+- **Presence & Awareness**: Implement presence indicators (who is online, cursor positions) separated from the core document state to reduce bandwidth and storage overhead.
+- **Security in Real-time**: Authenticate and authorize every WebSocket connection upon establishment and validate all incoming socket messages to prevent malicious payloads.
+- **Scale**: Be mindful of message broadcasting limits. Use Redis Pub/Sub or similar message brokers when scaling WebSocket servers across multiple instances.
+
+### Trigger Conditions
+Active whenever the user is building multiplayer features, live cursors, document co-editing, real-time chats, or working with WebSockets, Yjs, or WebRTC.
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Deskripsi
+Panduan ahli untuk mengimplementasikan fitur kolaborasi real-time dan *multiplayer* pada aplikasi web. Mencakup Conflict-free Replicated Data Types (CRDTs) seperti Yjs/Automerge, WebSockets, WebRTC, dan layanan terkelola seperti Liveblocks atau Pusher.
+
+### Instruksi
+- **CRDT untuk State**: Gunakan CRDT (misalnya `yjs` atau `automerge`) daripada Operational Transformation (OT) untuk menangani *state* terdistribusi dan pengeditan dokumen secara bersamaan dengan lancar.
+- **Ketahanan Koneksi**: Selalu terapkan logika penyambungan ulang otomatis dengan *exponential backoff* untuk WebSockets. Tangani *offline state* dengan baik dengan menyinkronkan perubahan lokal setelah tersambung kembali.
+- **Presence & Awareness**: Terapkan indikator kehadiran (siapa yang sedang online, posisi kursor) yang dipisahkan dari status dokumen inti untuk mengurangi *overhead* bandwidth dan penyimpanan.
+- **Keamanan Real-time**: Lakukan autentikasi dan otorisasi setiap koneksi WebSocket pada saat tersambung dan validasi semua pesan *socket* yang masuk untuk mencegah *payload* berbahaya.
+- **Skalabilitas**: Perhatikan batas penyiaran (broadcasting) pesan. Gunakan Redis Pub/Sub atau *message broker* serupa saat meningkatkan (scaling) server WebSocket di beberapa instans.
+
+### Kondisi Pemicu
+Aktif setiap kali pengguna sedang membangun fitur *multiplayer*, kursor langsung (live cursors), pengeditan dokumen bersama, obrolan real-time, atau bekerja dengan WebSockets, Yjs, atau WebRTC.