docs(auth-security): add documentation for authentication flows, best practices, and token strategy

Author: tyronejosee

docs/auth-security/auth-flows.md

@@ -0,0 +1,53 @@
+# Authentication Flows
+
+This application uses [Supabase Auth](https://supabase.com/docs/guides/auth) as the authentication layer, integrated via the Supabase JavaScript SDK.
+
+We support:
+
+- OAuth with GitHub and Google
+- Session management via Supabase's client session
+
+## OAuth Providers
+
+Currently enabled providers:
+
+- **GitHub**
+- **Google**
+
+These providers are configured directly in the Supabase project settings, under **Authentication > Providers**.
+
+## Frontend Flow (OAuth)
+
+1. User clicks "Login with Google" or "Login with GitHub".
+2. Supabase SDK triggers OAuth redirect:
+
+   ```javascript
+   const { data, error } = await supabase.auth.signInWithOAuth({
+     provider: "google", // or 'github'
+   });
+   ```
+
+3. After the OAuth handshake, the user is redirected back to the app with a valid session.
+4. The session is automatically persisted in local storage and available via:
+
+   ```javascript
+   const {
+     data: { session },
+   } = await supabase.auth.getSession();
+   ```
+
+## Session Handling
+
+- Sessions are auto-refreshed via the SDK.
+- On each load, use `supabase.auth.getSession()` to verify and hydrate the current session state.
+- Auth state changes can be subscribed to:
+
+  ```javascript
+  supabase.auth.onAuthStateChange((event, session) => {
+    // handle login, logout, token refresh
+  });
+  ```
+
+## Server-Side Session
+
+For SSR or protected API routes, the JWT in the Supabase session must be verified. This is optional if the app is frontend-only.

docs/auth-security/best-practices.md

@@ -0,0 +1,19 @@
+# Auth & Security Best Practices
+
+- ✅ Always use `NEXT_PUBLIC_SUPABASE_` for keys meant to be exposed in frontend.
+- ✅ Use environment variables to avoid leaking secrets in the repo.
+- ✅ Handle auth errors explicitly and show user-friendly messages.
+- ✅ Validate sessions on page load and redirect unauthorized users to login.
+- ✅ Use Supabase's RLS (Row Level Security) to protect data access on the backend.
+- ✅ Secure protected API routes by validating the JWT if applicable.
+- ✅ Avoid relying only on `localStorage` for critical auth checks (can be manipulated).
+
+## Recommended Setup
+
+```typescript
+// lib/supabase/client.ts
+export const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+);
+```

docs/auth-security/github.md

@@ -0,0 +1,40 @@
+# Token Strategy
+
+## Storage
+
+- Supabase handles tokens internally.
+- Access token and refresh token are stored in `localStorage` by default.
+- You can configure session persistence as `"session"` or `"none"`:
+
+  ```ts
+  createClient(SUPABASE_URL, SUPABASE_KEY, {
+    auth: {
+      storage: localStorage,
+      autoRefreshToken: true,
+      persistSession: true,
+    },
+  });
+  ```
+
+```
+
+```
+
+## Environment Variables
+
+All environment-specific secrets are stored in `.env` or `.env.local`:
+
+```env
+NEXT_PUBLIC_SUPABASE_URL=https://xyzcompany.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1...
+```
+
+⚠️ Never expose the `service_role` key on the frontend — only use `anon` keys client-side.
+
+---
+
+## 📁 `docs/auth-security/best-practices.md`
+
+```md
+
+```