feat(auth): Add authentication middleware

.docs/architecture.md

@@ -25,10 +25,10 @@ The SecNex API Gateway follows a modular architecture with clear separation of c
 │                      Route Handler                         │
 │  ┌──────────────────────────────────────────────────────┐  │
 │  │            Per-Route Middleware Chain                │  │
-│  │  ┌────────────┐  ┌──────────────┐                    │  │
-│  │  │ Strip      │→ │ Reverse      │                    │  │
-│  │  │ Prefix     │  │ Proxy        │                    │  │
-│  │  └────────────┘  └──────────────┘                    │  │
+│  │  ┌────────────┐  ┌────────────┐  ┌──────────────┐    │  │
+│  │  │ Auth       │→ │ Strip      │→ │ Reverse      │    │  │
+│  │  │ Middleware │  │ Prefix     │  │ Proxy        │    │  │
+│  │  └────────────┘  └────────────┘  └──────────────┘    │  │
 │  └──────────────────────────────────────────────────────┘  │
 └─────────────────────────┬──────────────────────────────────┘
                           │
@@ -54,11 +54,12 @@ app/
 │   └── database.go      # Database configuration
 ├── server/              # Core server components
 │   ├── gateway.go       # Main gateway server
-│   ├── routes.go        # Route registration
+│   ├── routes.go        # Route registration & middleware chain
 │   ├── api.go           # API definitions
 │   ├── host.go          # Host definitions
 │   └── target.go        # Target (backend) definitions
 ├── middlewares/         # HTTP middleware
+│   ├── auth.go          # Authentication middleware
 │   ├── host.go          # Host logging middleware
 │   └── logger.go        # Structured logging middleware
 └── utils/               # Utility functions
@@ -79,7 +80,7 @@ The Gateway is the main server component that:
 
 The Routes component handles:
 - Creating route handlers from configuration
-- Applying strip prefix middleware
+- Applying per-route middleware chain (Auth → StripPrefix)
 - Registering routes with chi router (method-agnostic)
 - Connecting routes to API backends
 
@@ -101,9 +102,17 @@ Host definitions for:
 
 Target (backend) definitions that:
 - Store backend service URLs
-- Create `httputil.ReverseProxy` instances
+- Create `httputil.NewSingleHostReverseProxy` instances
 - Handle proxy configuration
 
+#### Auth Middleware (`middlewares/auth.go`)
+
+Authentication middleware that:
+- Validates presence of configured auth header (e.g., `X-Api-Key`, `Authorization`)
+- Supports path-based filtering via include/exclude patterns
+- Removes auth header before forwarding to backend
+- Provides extensive DEBUG logging for troubleshooting
+
 ## Middleware Chain
 
 ### Global Middleware
@@ -119,19 +128,71 @@ Applied to all requests via chi middleware:
 
 ### Per-Route Middleware
 
-Applied to each route handler:
+Applied in order to each route handler:
 
-1. **StripPrefix** - Removes specified prefix from request path before proxying
+1. **Auth** (if enabled) - Validates authentication header with path filtering
+2. **StripPrefix** (if enabled) - Removes specified prefix from request path before proxying
 
 ## Request Flow
 
 1. **Client Request** → Gateway receives HTTP request
 2. **Global Middleware** → Request ID, Real IP, Host logging, Logger applied
 3. **Route Matching** → Chi matches route pattern (e.g., `/api/v1/*`)
-4. **Per-Route Middleware** → StripPrefix (if enabled)
+4. **Per-Route Middleware** → Auth → StripPrefix (if enabled)
 5. **Reverse Proxy** → Request forwarded to backend API
 6. **Response** → Backend response returned to client
 
+## Authentication Flow
+
+The authentication middleware supports flexible path-based filtering:
+
+```
+┌─────────────────────────────────────┐
+│    Include and Exclude both empty?   │
+└──────────────────┬──────────────────┘
+                   │ Yes
+         ┌─────────┴─────────┐
+         │  Auth required    │
+         │  for ALL paths    │
+         └───────────────────┘
+
+                   │ No
+         ┌─────────┴─────────┐
+         ▼                   │
+┌───────────────────┐        │
+│ Only Include set? │        │
+└─────────┬─────────┘        │
+    │ Yes    │ No            │
+    ▼        ▼               │
+┌────────┐ ┌────────────────┐│
+│ Auth   │ │ Exclude set?   ││
+│ ONLY   │ └───────┬────────┘│
+│ for    │         │ No      │
+│ Include│    ┌────┴────┐    │
+│ paths  │    │ Auth    │    │
+└────────┘    │ for ALL │    │
+              └────┬────┘    │
+                   │ Yes      │
+         ┌─────────┴─────────┐│
+         │ Auth EXCEPT       ││
+         │ matching Exclude  ││
+         └───────────────────┘│
+                              │
+                              ▼
+                       Check Auth Header
+```
+
+**Path Filtering Logic:**
+1. **Both include and exclude empty** → Auth required for ALL paths
+2. **Only include set** → Auth required ONLY for paths matching include patterns
+3. **Only exclude set** → Auth required for ALL paths EXCEPT those matching exclude patterns
+4. **Both set** → Include takes precedence (same as #2)
+
+**Wildcard Pattern Matching:**
+- `*` matches any path
+- `/api/*` matches `/api/` and any subpath
+- `/api/v1/public/test/*` matches the prefix and any subpath
+
 ## Configuration Flow
 
 1. Load `gateway.yaml` via `config.NewFile()`
@@ -139,10 +200,10 @@ Applied to each route handler:
 3. Create Hosts from configuration
 4. Create Targets from configuration
 5. Create APIs (linking Hosts to Targets)
-6. Create Routes (linking Routes to APIs)
+6. Create Routes (linking Routes to APIs with Auth config)
 7. Initialize Gateway with all components
 8. Configure proxy directors
-9. Register routes with chi router
+9. Register routes with chi router (including Auth middleware)
 10. Start HTTP server
 
 ## Logging
@@ -151,6 +212,7 @@ The gateway uses structured JSON logging via `masterlog`:
 
 - **HTTP Request Logging** - method, path, status, duration, host, IP
 - **Gateway Events** - startup, route registration, proxy configuration
+- **Auth Debug Logs** - detailed auth decision logging when DEBUG level enabled
 - **Sensitive Field Pseudonymization** - user_id, email, ip fields are pseudonymized
 
 Example log output:
@@ -166,3 +228,15 @@ Example log output:
   "ip": "127.0.0.1:52342"
 }
 ```
+
+Auth debug logs (when DEBUG level enabled):
+```json
+{
+  "level": "debug",
+  "msg": "AuthMiddleware: Checking if path requires auth",
+  "path": "/api/v1/users",
+  "requires_auth": true,
+  "include": [],
+  "exclude": ["/api/v1/public/*"]
+}
+```