vibes-plug 1.0.0 → 2.5.0

package/skills/authentication-identity-expert/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: authentication-identity-expert
 description: "Expert guide for implementing secure authentication, authorization (RBAC/ABAC), OAuth2, and identity management (Clerk, Auth.js, Supabase Auth) / Panduan ahli untuk autentikasi dan otorisasi."
-author: "Antigravity"
+author: vibes-plug-swarm
 ---
 
-# Authentication & Identity Expert / Ahli Autentikasi & Identitas
+# Authentication & Identity Expert (2026 Edition)
 
 [English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
 
@@ -14,17 +14,217 @@ author: "Antigravity"
 ## English
 
 ### Description
-Expert guide for implementing robust and secure authentication and authorization systems in web and mobile applications. Covers JWT, Session management, OAuth2 providers, Identity as a Service (Clerk, Supabase Auth, Auth0), and Role/Attribute-Based Access Control (RBAC/ABAC).
-
-### Instructions
-- **Never Roll Your Own Crypto**: Always use established libraries (like `bcrypt` or `argon2`) for hashing passwords if not using an Identity Provider.
-- **Session & Token Management**: Keep JWT lifetimes short (e.g., 15 minutes) and use secure, HttpOnly, SameSite cookies for refresh tokens to prevent XSS attacks.
-- **OAuth2 & SSO Integration**: When implementing OAuth, strictly validate the `state` parameter to mitigate CSRF attacks during the callback phase.
-- **Authorization (RBAC/ABAC)**: Enforce authorization checks at the server level (API routes, database queries), not just on the UI layer. Never expose sensitive data based on client-side roles alone.
-- **MFA (Multi-Factor Authentication)**: Recommend and implement MFA/2FA for administrative or high-privilege accounts.
+Production-grade guide for implementing secure authentication, authorization, and identity management in modern web and mobile applications. Covers **Clerk**, **Supabase Auth**, **Auth.js v5**, **Better Auth**, JWT patterns, OAuth 2.1, PKCE flows, RBAC/ABAC, passkeys (WebAuthn), and MFA implementation for React 19 / Next.js 15 stacks.
 
 ### Trigger Conditions
-Active whenever the user is working on login/signup flows, session management, OAuth integration, role-based access control, or integrating Auth.js, Clerk, Supabase Auth, or Auth0.
+- Working on login/signup flows, session management, or OAuth integration.
+- Integrating **Clerk**, **Supabase Auth**, **Auth.js v5**, **Better Auth**, or **Auth0**.
+- Implementing **Role-Based Access Control (RBAC)** or **Attribute-Based Access Control (ABAC)**.
+- Setting up **WebAuthn/Passkeys**, **MFA/2FA**, or **SSO**.
+- Securing Next.js App Router routes with middleware-based auth guards.
+- Implementing **OAuth 2.1** flows with PKCE for SPAs or mobile apps.
+
+---
+
+### Identity Provider Selection Guide (2026)
+
+| Provider | Best For | Key Strength |
+|---|---|---|
+| **Clerk** | SaaS, B2B apps | Built-in organizations, roles, MFA, UI components |
+| **Supabase Auth** | Supabase-powered apps | RLS integration, social login, SSO |
+| **Auth.js v5** | Next.js self-hosted | Flexible adapters, edge-compatible |
+| **Better Auth** | TypeScript-first self-hosted | Modern DX, built-in 2FA, org management |
+| **Auth0** | Enterprise, compliance | Enterprise SSO, compliance (SOC2, HIPAA) |
+
+**Recommendation**: Use **Clerk** for most new SaaS apps (best DX). Use **Supabase Auth** if you're already using Supabase. Use **Better Auth** for full control without vendor lock-in.
+
+---
+
+### Core Security Principles
+
+#### 1. Never Roll Your Own Crypto
+- Use `argon2id` (preferred) or `bcrypt` for password hashing — **never MD5, SHA1, or plain SHA256**.
+- Use battle-tested libraries: `@node-rs/argon2`, `bcryptjs`.
+- Minimum: bcrypt cost factor ≥12, argon2id memory ≥64MB.
+
+#### 2. JWT Best Practices
+```typescript
+// ✅ Short-lived access tokens + HttpOnly refresh tokens
+const ACCESS_TOKEN_EXPIRY = '15m';   // 15 minutes
+const REFRESH_TOKEN_EXPIRY = '7d';   // 7 days
+
+// ✅ Store refresh tokens in HttpOnly, Secure, SameSite=Strict cookies
+res.cookie('refresh_token', token, {
+  httpOnly: true,
+  secure: true,
+  sameSite: 'strict',
+  maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days in ms
+});
+
+// ❌ Never store tokens in localStorage (XSS vulnerable)
+// ❌ Never put sensitive data in JWT payload (it's base64 decoded, not encrypted)
+```
+
+#### 3. OAuth 2.1 + PKCE (For SPAs & Mobile)
+```typescript
+// PKCE flow — required for public clients in OAuth 2.1
+import { generateCodeVerifier, generateCodeChallenge } from 'oslo/oauth2';
+
+const codeVerifier = generateCodeVerifier(); // 43-128 char random string
+const codeChallenge = await generateCodeChallenge(codeVerifier); // SHA-256 hash
+
+// Store codeVerifier in sessionStorage (NOT localStorage) during redirect
+sessionStorage.setItem('pkce_verifier', codeVerifier);
+
+// Auth URL includes challenge
+const authUrl = new URL('https://provider.com/oauth/authorize');
+authUrl.searchParams.set('code_challenge', codeChallenge);
+authUrl.searchParams.set('code_challenge_method', 'S256');
+authUrl.searchParams.set('state', cryptoRandomState); // CSRF protection
+```
+
+#### 4. Clerk — Next.js 15 Integration
+```typescript
+// middleware.ts — protect routes at the edge
+import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+const isPublicRoute = createRouteMatcher([
+  '/', '/sign-in(.*)', '/sign-up(.*)', '/api/webhooks(.*)',
+]);
+
+export default clerkMiddleware(async (auth, req) => {
+  if (!isPublicRoute(req)) {
+    await auth.protect(); // Redirects to sign-in if unauthenticated
+  }
+});
+
+export const config = {
+  matcher: ['/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)', '/(api|trpc)(.*)'],
+};
+```
+
+```typescript
+// Server Component — get user on the server
+import { auth, currentUser } from '@clerk/nextjs/server';
+
+export default async function DashboardPage() {
+  const { userId, orgId, orgRole } = await auth();
+  if (!userId) redirect('/sign-in');
+
+  const user = await currentUser();
+  return <div>Welcome, {user?.firstName}!</div>;
+}
+```
+
+#### 5. Supabase Auth — RLS Integration
+```typescript
+// Create Supabase client with user session
+import { createServerClient } from '@supabase/ssr';
+
+export async function createSupabaseServerClient(cookieStore: ReadonlyRequestCookies) {
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll: () => cookieStore.getAll(),
+        setAll: (cookies) => cookies.forEach(({ name, value, options }) =>
+          cookieStore.set(name, value, options)
+        ),
+      },
+    }
+  );
+}
+
+// RLS in PostgreSQL — users can only access their own rows
+-- CREATE POLICY "Users can only see own data" ON profiles
+-- FOR ALL USING (auth.uid() = user_id);
+```
+
+#### 6. Auth.js v5 (Next.js App Router)
+```typescript
+// auth.ts
+import NextAuth from 'next-auth';
+import GitHub from 'next-auth/providers/github';
+import { DrizzleAdapter } from '@auth/drizzle-adapter';
+import { db } from '@/db';
+
+export const { handlers, auth, signIn, signOut } = NextAuth({
+  adapter: DrizzleAdapter(db),
+  providers: [
+    GitHub,
+    // Add more providers...
+  ],
+  session: { strategy: 'database' }, // or 'jwt'
+  callbacks: {
+    authorized({ auth, request: { nextUrl } }) {
+      const isLoggedIn = !!auth?.user;
+      const isProtected = nextUrl.pathname.startsWith('/dashboard');
+      if (isProtected && !isLoggedIn) return false;
+      return true;
+    },
+  },
+});
+```
+
+#### 7. RBAC — Role-Based Access Control (Server-Side)
+```typescript
+// ✅ Always enforce roles server-side — never rely on client UI alone
+type Role = 'viewer' | 'editor' | 'admin' | 'super_admin';
+
+const permissions: Record<Role, string[]> = {
+  viewer: ['read:posts'],
+  editor: ['read:posts', 'write:posts', 'delete:own_posts'],
+  admin: ['read:posts', 'write:posts', 'delete:any_post', 'manage:users'],
+  super_admin: ['*'], // All permissions
+};
+
+function hasPermission(userRole: Role, required: string): boolean {
+  const allowed = permissions[userRole];
+  return allowed.includes('*') || allowed.includes(required);
+}
+
+// In Server Action / API Route
+const { userId } = await auth();
+const user = await db.query.users.findFirst({ where: eq(users.id, userId) });
+
+if (!hasPermission(user.role, 'delete:any_post')) {
+  throw new Error('Forbidden');
+}
+```
+
+#### 8. WebAuthn / Passkeys (2026 Standard)
+```typescript
+// Using SimpleWebAuthn library
+import { generateRegistrationOptions, verifyRegistrationResponse } from '@simplewebauthn/server';
+
+// Registration — generate challenge
+const options = await generateRegistrationOptions({
+  rpName: 'My App',
+  rpID: 'myapp.com',
+  userName: user.email,
+  attestationType: 'none',
+  authenticatorSelection: {
+    residentKey: 'preferred',   // Enables passkeys
+    userVerification: 'preferred',
+  },
+});
+
+// Store challenge in session, send options to client
+await redis.setex(`webauthn:${userId}`, 60, JSON.stringify(options.challenge));
+```
+
+### Security Checklist
+- [ ] Passwords hashed with argon2id (cost ≥64MB) or bcrypt (cost ≥12).
+- [ ] JWT access tokens expire in ≤15 minutes; refresh in HttpOnly cookies.
+- [ ] OAuth state parameter validated on callback (CSRF protection).
+- [ ] PKCE enforced for all public OAuth clients.
+- [ ] All authorization checks enforced server-side (not UI-only).
+- [ ] Admin routes protected by both auth middleware AND role check.
+- [ ] MFA offered (TOTP/WebAuthn) for privileged accounts.
+- [ ] Refresh token rotation on every use (detect theft).
+- [ ] Rate limiting on login/signup endpoints (prevent brute force).
+- [ ] Account lockout after N failed attempts.
 
 ---
 
@@ -32,14 +232,45 @@ Active whenever the user is working on login/signup flows, session management, O
 ## Bahasa Indonesia
 
 ### Deskripsi
-Panduan ahli untuk mengimplementasikan sistem autentikasi dan otorisasi yang aman dan tangguh pada aplikasi web dan mobile. Mencakup JWT, manajemen Sesi, penyedia OAuth2, Identity as a Service (Clerk, Supabase Auth, Auth0), dan Role/Attribute-Based Access Control (RBAC/ABAC).
-
-### Instruksi
-- **Jangan Membuat Kriptografi Sendiri**: Selalu gunakan library standar (seperti `bcrypt` atau `argon2`) untuk hashing password jika tidak menggunakan penyedia identitas (IdP).
-- **Manajemen Sesi & Token**: Jaga masa aktif JWT tetap singkat (misal: 15 menit) dan gunakan cookie *HttpOnly, SameSite* yang aman untuk token *refresh* guna mencegah serangan XSS.
-- **Integrasi OAuth2 & SSO**: Saat mengimplementasikan OAuth, validasi parameter `state` secara ketat untuk memitigasi serangan CSRF selama fase callback.
-- **Otorisasi (RBAC/ABAC)**: Terapkan pengecekan otorisasi pada level server (API route, query database), bukan hanya pada lapisan UI. Jangan pernah mengekspos data sensitif hanya berdasarkan *role* di sisi klien.
-- **MFA (Multi-Factor Authentication)**: Rekomendasikan dan implementasikan MFA/2FA untuk akun administratif atau hak akses tinggi.
+Panduan tingkat produksi untuk mengimplementasikan autentikasi, otorisasi, dan manajemen identitas yang aman pada aplikasi web dan mobile modern. Mencakup **Clerk**, **Supabase Auth**, **Auth.js v5**, **Better Auth**, pola JWT, OAuth 2.1, alur PKCE, RBAC/ABAC, passkey (WebAuthn), dan implementasi MFA untuk stack React 19 / Next.js 15.
 
 ### Kondisi Pemicu
-Aktif setiap kali pengguna sedang mengerjakan alur login/signup, manajemen sesi, integrasi OAuth, role-based access control, atau mengintegrasikan Auth.js, Clerk, Supabase Auth, atau Auth0.
+- Mengerjakan alur login/signup, manajemen sesi, atau integrasi OAuth.
+- Mengintegrasikan Clerk, Supabase Auth, Auth.js v5, Better Auth, atau Auth0.
+- Mengimplementasikan RBAC (Role-Based Access Control) atau ABAC.
+- Menyiapkan WebAuthn/Passkeys, MFA/2FA, atau SSO.
+- Mengamankan rute Next.js App Router dengan auth guard berbasis middleware.
+
+### Panduan Teknis
+
+#### 1. Prinsip Keamanan Inti
+- **Jangan buat kriptografi sendiri**: Gunakan `argon2id` atau `bcrypt` untuk hashing password.
+- **JWT berumur pendek**: Access token ≤15 menit, refresh token di HttpOnly cookie.
+- **PKCE wajib** untuk semua public OAuth client (SPA, mobile).
+- **Validasi state OAuth** di callback untuk proteksi CSRF.
+
+#### 2. Pemilihan Identity Provider
+- **Clerk**: Terbaik untuk SaaS baru — DX terbaik, komponen UI siap pakai, manajemen organisasi.
+- **Supabase Auth**: Ideal jika sudah pakai Supabase — integrasi langsung dengan RLS.
+- **Auth.js v5**: Self-hosted, fleksibel, edge-compatible untuk Next.js.
+- **Better Auth**: TypeScript-first, kontrol penuh tanpa vendor lock-in.
+
+#### 3. RBAC di Sisi Server
+Selalu terapkan pengecekan role di server (Server Action, API route, middleware) — **jangan hanya di UI**. Gunakan tabel permission yang memetakan setiap role ke daftar aksi yang diizinkan.
+
+#### 4. WebAuthn / Passkeys
+Gunakan library `@simplewebauthn/server` untuk registrasi dan verifikasi passkey. Simpan challenge di Redis dengan TTL pendek (60 detik) untuk mencegah replay attack.
+
+#### 5. Checklist Keamanan
+- Password di-hash dengan argon2id atau bcrypt.
+- JWT access token expire ≤15 menit; refresh di HttpOnly cookie.
+- State OAuth divalidasi saat callback.
+- PKCE diterapkan untuk semua klien publik OAuth.
+- Pengecekan otorisasi dilakukan di server, bukan hanya UI.
+- MFA ditawarkan untuk akun privileged.
+- Rate limiting di endpoint login/signup.
+- Rotasi refresh token setiap kali digunakan.
+
+
+## Orchestration & Integration
+- Connects to other backend skills as part of the orchestration flow.