init: Initial commit

CLAUDE.md

@@ -0,0 +1,103 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+SecNex API Gateway is a Go-based API gateway built with chi/v5 routing. It acts as a reverse proxy with configurable security features including authentication and WAF (Web Application Firewall) capabilities.
+
+## Build and Run
+
+```bash
+cd app
+go run main.go
+```
+
+The gateway loads configuration from `gateway.yaml` (sibling to the `app/` directory).
+
+## Architecture
+
+### Directory Structure
+
+```
+app/
+├── main.go           # Entry point
+├── config/           # Configuration loading and types
+├── server/           # Gateway, routes, and proxy setup
+├── middlewares/      # Auth and WAF middleware
+├── handlers/         # Route handlers (currently empty)
+└── res/              # HTTP error responses
+```
+
+### Core Components
+
+**Gateway (`server/gateway.go`)**
+- Main server using chi/v5 router
+- Dynamically enables features via config: `request_id`, `real_ip`, `logger`
+- Registers route handlers and starts HTTP server
+
+**Routes (`server/routes.go`)**
+- Creates handlers for each route configured in `gateway.yaml`
+- For each route:
+  1. Finds the matching API backend target
+  2. Creates a reverse proxy using `httputil.NewSingleHostReverseProxy`
+  3. Optionally strips prefix from the request path
+  4. Applies WAF middleware (method filtering)
+  5. Applies Auth middleware (header-based authentication)
+
+**Proxy (`server/proxy.go`)**
+- Host-based virtual hosting proxy (separate from routes)
+- Maps `proxy.host` to a backend target
+- Currently unused in main.go but available
+
+**Configuration Flow**
+1. `config.NewFileConfig("../gateway.yaml")` loads YAML
+2. `server.NewGateway(cfg)` creates gateway with chi router
+3. `server.NewRoutes(cfg.GetRoutes(), cfg.GetApis())` creates handlers
+4. `gateway.SetRoutes(routes)` registers handlers
+
+### Middleware Chain (per route)
+
+Middlewares are applied in order via decorator pattern in `server/routes.go:createHandlers`:
+1. StripPrefix (if enabled) - removes prefix from path before proxying
+2. WAF - filters by HTTP method (or `["*"]` for all methods)
+3. Auth - validates presence of auth header
+
+### Key Implementation Details
+
+**Auth Middleware** (`middlewares/auth.go`)
+- Checks for presence of configured header (e.g., `X-Api-Key`, `Authorization`)
+- Path-based filtering via `include`/`exclude` patterns:
+  - If `include` is set → only those paths require auth
+  - If `include` is empty → all paths require auth except `exclude` patterns
+- Supports wildcard patterns (`*`) in path matching
+- Deletes the auth header before forwarding to backend
+
+**WAF Configuration** (`middlewares/waf.go`)
+- Currently only implements HTTP method filtering
+- `methods: ["*"]` allows all methods
+- `methods: ["GET"]` only allows GET
+
+**Route Handler Pattern**
+Each route in `gateway.yaml` must have:
+- `id` - must match an API entry
+- `path` - chi route pattern (e.g., `/api/v1/dev/*`)
+- `strip_prefix` - optional prefix removal
+- `security.auth` - optional auth middleware
+- `security.waf` - optional method filtering
+
+### Module Structure
+
+The codebase uses an internal Go module:
+```
+git.secnex.io/secnex/gateway
+```
+
+Internal imports use this path (e.g., `git.secnex.io/secnex/gateway/config`).
+
+### Logging
+
+Uses `git.secnex.io/secnex/masterlog` with:
+- JSON encoder
+- Pseudonymizer for sensitive fields (`user_id`, `email`, `ip`)
+- Debug-level logging enabled in main.go