# 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