feat(middleware): add basic auth and improve error handling 🔒

- Add BasicAuth middleware with user authentication
- Add error handling documentation to context object
- Add handleError method to Context class
- Add MDN reference link to CORS documentation
- Export BasicAuth in middleware index
- Refactor CORS middleware to use handleError with try-catch
- Refactor Handler to use ctx.handleError instead of handleResponse
- Refactor WebSocket middleware to use handleError
- Update documentation navigation and menu labels
- Update README with Basic Auth middleware entry

Author: NeaByteLab

README.md

@@ -30,10 +30,11 @@ Follow our [installing guide](https://docs-deserve.neabyte.com/en/getting-starte
   - [Request Handling](https://docs-deserve.neabyte.com/en/core-concepts/request-handling) - Enhanced request object with automatic parsing
 
 - **Middleware**
-  - [Global Middleware](https://docs-deserve.neabyte.com/en/middleware/global) - Cross-cutting functionality
-  - [Route-Specific Middleware](https://docs-deserve.neabyte.com/en/middleware/route-specific) - Targeted middleware for specific routes
-  - [CORS Middleware](https://docs-deserve.neabyte.com/en/middleware/cors) - Cross-origin request handling
-  - [WebSocket Middleware](https://docs-deserve.neabyte.com/en/middleware/websocket) - Real-time bidirectional communication
+  - [Use Global](https://docs-deserve.neabyte.com/en/middleware/global) - Cross-cutting functionality
+  - [Use Route-Specific](https://docs-deserve.neabyte.com/en/middleware/route-specific) - Targeted middleware for specific routes
+  - [Basic Auth](https://docs-deserve.neabyte.com/en/middleware/basic-auth) - HTTP Basic Authentication
+  - [CORS](https://docs-deserve.neabyte.com/en/middleware/cors) - Cross-origin request handling
+  - [WebSocket](https://docs-deserve.neabyte.com/en/middleware/websocket) - Real-time bidirectional communication
 
 - **Response Utilities**
   - [JSON Format](https://docs-deserve.neabyte.com/en/response/json) - Create JSON responses easily

docs/.vitepress/config.ts

@@ -94,10 +94,11 @@ export default withMermaid(
                 text: 'Middleware',
                 collapsed: true,
                 items: [
-                  { text: 'Global Middleware', link: '/en/middleware/global' },
-                  { text: 'Route-Specific Middleware', link: '/en/middleware/route-specific' },
-                  { text: 'CORS Middleware', link: '/en/middleware/cors' },
-                  { text: 'WebSocket Middleware', link: '/en/middleware/websocket' }
+                  { text: 'Use Global', link: '/en/middleware/global' },
+                  { text: 'Use Route-Specific', link: '/en/middleware/route-specific' },
+                  { text: 'Basic Auth (Unreleased)', link: '/en/middleware/basic-auth' },
+                  { text: 'CORS', link: '/en/middleware/cors' },
+                  { text: 'WebSocket', link: '/en/middleware/websocket' }
                 ]
               },
               {
@@ -162,10 +163,11 @@ export default withMermaid(
                 text: 'Middleware',
                 collapsed: true,
                 items: [
-                  { text: 'Global Middleware', link: '/en/middleware/global' },
-                  { text: 'Route-Specific Middleware', link: '/en/middleware/route-specific' },
-                  { text: 'CORS Middleware', link: '/en/middleware/cors' },
-                  { text: 'WebSocket Middleware', link: '/en/middleware/websocket' }
+                  { text: 'Use Global', link: '/en/middleware/global' },
+                  { text: 'Use Route-Specific', link: '/en/middleware/route-specific' },
+                  { text: 'Basic Auth', link: '/en/middleware/basic-auth' },
+                  { text: 'CORS', link: '/en/middleware/cors' },
+                  { text: 'WebSocket', link: '/en/middleware/websocket' }
                 ]
               },
               {
@@ -270,10 +272,11 @@ export default withMermaid(
                 text: 'Middleware',
                 collapsed: true,
                 items: [
-                  { text: 'Middleware Global', link: '/id/middleware/global' },
-                  { text: 'Middleware Spesifik Rute', link: '/id/middleware/route-specific' },
-                  { text: 'Middleware CORS', link: '/id/middleware/cors' },
-                  { text: 'Middleware WebSocket', link: '/id/middleware/websocket' }
+                  { text: 'Gunakan Global', link: '/id/middleware/global' },
+                  { text: 'Gunakan Route-Spesific', link: '/id/middleware/route-specific' },
+                  { text: 'Basic Auth', link: '/id/middleware/basic-auth' },
+                  { text: 'CORS', link: '/id/middleware/cors' },
+                  { text: 'WebSocket', link: '/id/middleware/websocket' }
                 ]
               },
               {

docs/en/core-concepts/context-object.md

@@ -76,6 +76,7 @@ Send responses using `ctx.send`:
 - `ctx.send.data()` - In-memory data downloads
 - `ctx.send.redirect()` - Redirects
 - `ctx.send.custom()` - Custom responses
+- `ctx.handleError()` - Error handling (unreleased)
 
 You can also use `ctx.redirect()` directly as a convenience method:
 
@@ -141,6 +142,47 @@ export function GET(ctx: Context): Response {
 }
 ```
 
+## Error Handling
+
+> [!WARNING]
+> This feature is available in the development version but not yet released.
+
+Handle errors consistently using `ctx.handleError()`:
+
+```typescript
+export function GET(ctx: Context): Response {
+  try {
+    if (!isAuthorized) {
+      return ctx.handleError(401, new Error('Unauthorized'))
+    }
+    return ctx.send.json({ data: 'success' })
+  } catch (error) {
+    return ctx.handleError(500, error as Error)
+  }
+}
+```
+
+### How It Works
+
+`ctx.handleError()` respects your global error handler set with `router.catch()`:
+
+- **If `router.catch()` is defined** - Uses your custom error handler
+- **If no error handler** - Returns a simple response with the status code
+
+### Use in Middleware
+
+Middleware can use `ctx.handleError()` to trigger error handling:
+
+```typescript
+router.use(async (ctx, next) => {
+  if (!isValid) {
+    return ctx.handleError(401, new Error('Unauthorized'))
+    // This will use router.catch() if defined
+  }
+  return await next()
+})
+```
+
 ## Context Lifecycle
 
 1. **Request arrives** - Deserve creates Context with Request and URL

docs/en/middleware/basic-auth.md

@@ -0,0 +1,96 @@
+# Basic Auth Middleware
+
+> **Reference**: [MDN HTTP Authentication Guide](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Authentication)
+
+> [!WARNING]
+> This feature is available in the development version but not yet released.
+
+HTTP Basic Authentication middleware for protecting routes with username and password authentication. Simple, secure, and easy to configure.
+
+## Basic Usage
+
+Protect routes with Basic Auth using `Mware.basicAuth()`:
+
+```typescript
+import { Router, Mware } from '@neabyte/deserve'
+
+const router = new Router()
+
+router.use(
+  Mware.basicAuth({
+    users: [
+      { username: 'admin', password: 'secret' },
+      { username: 'user', password: 'pass' }
+    ]
+  })
+)
+
+router.serve(8000)
+```
+
+## Route-Specific Protection
+
+Apply Basic Auth only to specific routes:
+
+```typescript
+// Protect only /api routes
+router.use(
+  '/api',
+  Mware.basicAuth({
+    users: [{ username: 'admin', password: 'secret' }]
+  })
+)
+
+// Protect admin routes with different credentials
+router.use(
+  '/admin',
+  Mware.basicAuth({
+    users: [{ username: 'admin', password: 'admin123' }]
+  })
+)
+```
+
+## Multiple Users
+
+Support multiple user accounts:
+
+```typescript
+router.use(
+  Mware.basicAuth({
+    users: [
+      { username: 'admin', password: 'admin123' },
+      { username: 'user', password: 'user123' },
+      { username: 'guest', password: 'guest123' }
+    ]
+  })
+)
+```
+
+## Error Handling
+
+Basic Auth automatically uses `router.catch()` if defined:
+
+```typescript
+router.catch((ctx, { statusCode, error }) => {
+  if (statusCode === 401) {
+    return ctx.send.json(
+      { error: 'Authentication required', message: error?.message ?? 'Unauthorized' },
+      { status: 401 }
+    )
+  }
+  return ctx.send.json({
+    error: error?.message ?? 'Unknown error'
+  }, { status: statusCode })
+})
+
+router.use(Mware.basicAuth({ users: [...] }))
+```
+
+## Browser Authentication
+
+Browsers will automatically prompt for credentials when accessing protected routes:
+
+```
+Username: admin
+Password: ******
+```

docs/en/middleware/cors.md

@@ -1,5 +1,7 @@
 # CORS Middleware
 
+> **Reference**: [MDN HTTP CORS Guide](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS)
+
 CORS (Cross-Origin Resource Sharing) middleware handles cross-origin requests by adding appropriate headers and handling preflight OPTIONS requests.
 
 ## Basic Usage

docs/id/core-concepts/context-object.md

@@ -76,6 +76,7 @@ Kirim response menggunakan `ctx.send`:
 - `ctx.send.data()` - Unduhan data in-memory
 - `ctx.send.redirect()` - Redirect
 - `ctx.send.custom()` - Response custom
+- `ctx.handleError()` - Error handling (belum dirilis)
 
 Anda juga dapat menggunakan `ctx.redirect()` secara langsung sebagai method convenience:
 
@@ -141,6 +142,47 @@ export function GET(ctx: Context): Response {
 }
 ```
 
+## Penanganan Error
+
+> [!WARNING]
+> Fitur ini tersedia di versi development tetapi belum dirilis.
+
+Tangani error secara konsisten menggunakan `ctx.handleError()`:
+
+```typescript
+export function GET(ctx: Context): Response {
+  try {
+    if (!isAuthorized) {
+      return ctx.handleError(401, new Error('Unauthorized'))
+    }
+    return ctx.send.json({ data: 'success' })
+  } catch (error) {
+    return ctx.handleError(500, error as Error)
+  }
+}
+```
+
+### Cara Kerja
+
+`ctx.handleError()` menghormati error handler global yang diatur dengan `router.catch()`:
+
+- **Jika `router.catch()` didefinisikan** - Menggunakan error handler kustom Anda
+- **Jika tidak ada error handler** - Mengembalikan response sederhana dengan status code
+
+### Gunakan di Middleware
+
+Middleware dapat menggunakan `ctx.handleError()` untuk memicu error handling:
+
+```typescript
+router.use(async (ctx, next) => {
+  if (!isValid) {
+    return ctx.handleError(401, new Error('Unauthorized'))
+    // Ini akan menggunakan router.catch() jika didefinisikan
+  }
+  return await next()
+})
+```
+
 ## Lifecycle Context
 
 1. **Request datang** - Deserve membuat Context dengan Request dan URL

docs/id/middleware/basic-auth.md

@@ -0,0 +1,97 @@
+# Middleware Basic Auth
+
+> **Referensi**: [MDN HTTP Authentication Guide](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Authentication)
+
+> [!WARNING]
+> Fitur ini tersedia di versi development tetapi belum dirilis.
+
+Middleware HTTP Basic Authentication untuk melindungi route dengan autentikasi username dan password. Sederhana, aman, dan mudah dikonfigurasi.
+
+## Penggunaan Dasar
+
+Lindungi route dengan Basic Auth menggunakan `Mware.basicAuth()`:
+
+```typescript
+import { Router, Mware } from '@neabyte/deserve'
+
+const router = new Router()
+
+router.use(
+  Mware.basicAuth({
+    users: [
+      { username: 'admin', password: 'secret' },
+      { username: 'user', password: 'pass' }
+    ]
+  })
+)
+
+router.serve(8000)
+```
+
+## Proteksi Route-Spesifik
+
+Terapkan Basic Auth hanya pada route tertentu:
+
+```typescript
+// Lindungi hanya route /api
+router.use(
+  '/api',
+  Mware.basicAuth({
+    users: [{ username: 'admin', password: 'secret' }]
+  })
+)
+
+// Lindungi route admin dengan kredensial berbeda
+router.use(
+  '/admin',
+  Mware.basicAuth({
+    users: [{ username: 'admin', password: 'admin123' }]
+  })
+)
+```
+
+## Multiple Users
+
+Mendukung beberapa akun pengguna:
+
+```typescript
+router.use(
+  Mware.basicAuth({
+    users: [
+      { username: 'admin', password: 'admin123' },
+      { username: 'user', password: 'user123' },
+      { username: 'guest', password: 'guest123' }
+    ]
+  })
+)
+```
+
+## Penanganan Error
+
+Basic Auth secara otomatis menggunakan `router.catch()` jika didefinisikan:
+
+```typescript
+router.catch((ctx, { statusCode, error }) => {
+  if (statusCode === 401) {
+    return ctx.send.json(
+      { error: 'Autentikasi diperlukan', message: error?.message ?? 'Unauthorized' },
+      { status: 401 }
+    )
+  }
+  return ctx.send.json({
+    error: error?.message ?? 'Error tidak diketahui'
+  }, { status: statusCode })
+})
+
+router.use(Mware.basicAuth({ users: [...] }))
+```
+
+## Autentikasi Browser
+
+Browser akan secara otomatis meminta kredensial saat mengakses route yang dilindungi:
+
+```
+Username: admin
+Password: ******
+```
+

docs/id/middleware/cors.md

@@ -1,5 +1,7 @@
 # Middleware CORS
 
+> **Referensi**: [MDN HTTP CORS Guide](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS)
+
 Middleware CORS (Cross-Origin Resource Sharing) menangani cross-origin requests dengan menambahkan header yang sesuai dan menangani preflight OPTIONS requests.
 
 ## Penggunaan Dasar