# 🚀 kotlin-api

![Kotlin](https://img.shields.io/badge/Kotlin-2.4.0-7F52FF?logo=kotlin&logoColor=white)
![Spring Boot](https://img.shields.io/badge/Spring_Boot-4.1.0--RC1-6DB33F?logo=springboot&logoColor=white)
![Java](https://img.shields.io/badge/Java-21-ED8B00?logo=openjdk&logoColor=white)
![MongoDB](https://img.shields.io/badge/MongoDB-8.0-47A248?logo=mongodb&logoColor=white)
![Docker](https://img.shields.io/badge/Docker-ready-2496ED?logo=docker&logoColor=white)
![License](https://img.shields.io/badge/license-MIT-blue)

A reactive REST API built with **Kotlin**, **Spring Boot WebFlux**, and **MongoDB** — featuring JWT authentication, role-based access control, and OpenAPI documentation.

---

## 📋 Table of Contents

- [Features](#-features)
- [Tech Stack](#-tech-stack)
- [Getting Started](#-getting-started)
  - [Prerequisites](#prerequisites)
  - [Configuration](#configuration)
  - [Run Locally](#run-locally)
  - [Run with Docker](#run-with-docker)
- [API Reference](#-api-reference)
- [Project Structure](#-project-structure)
- [Documentation](#-documentation)
- [Development](#-development)

---

## ✨ Features

- ⚡ **Reactive** — fully non-blocking with Spring WebFlux & Kotlin coroutines
- 🔐 **JWT authentication** — AES-256-GCM encrypted tokens (JWE), access + refresh token flow
- 🛡️ **Role-based access control** — `ROLE_ADMIN` and standard user roles
- 🔄 **Token lifecycle management** — refresh, revocation, and session tracking
- 📖 **OpenAPI / Swagger UI** — auto-generated, browsable API docs
- 🐳 **Docker-ready** — multi-stage distroless image for minimal attack surface
- ✅ **Code quality** — enforced with ktlint

---

## 🛠 Tech Stack

| Layer | Technology |
|---|---|
| Language | Kotlin 2.4 |
| Framework | Spring Boot 4.1 (WebFlux) |
| Runtime | Java 21 |
| Database | MongoDB 8 (reactive) |
| Security | Spring Security + JJWT (JWE) |
| Docs | SpringDoc OpenAPI 3 |
| Testing | JUnit 5, MockK, embedded MongoDB |
| Linting | ktlint 1.8 |

---

## 🏁 Getting Started

### Prerequisites

- Java 21+
- MongoDB 8 (or Docker)

### Configuration

```bash
cp .env.example .env
```

Edit `.env` and set the required values:

| Variable | Description | Default |
|---|---|---|
| `MONGODB_URI` | MongoDB connection string | `mongodb://localhost:27017/kotlin-api` |
| `JWT_ENCRYPTION_SECRET` | Base64-encoded 32-byte AES secret (**required**) | — |

Generate a secret:
```bash
openssl rand -base64 32 | tr -d '\n'
```

### Run Locally

```bash
./gradlew bootRun
```

The API starts on **http://localhost:8080**.

#### Seed Users

On startup, two users are automatically created if they don't already exist:

| Email | Password | Role |
|---|---|---|
| `user@example.com` | `user12345` | `ROLE_USER` |
| `admin@example.com` | `admin12345` | `ROLE_ADMIN` |

Use these credentials with `POST /v1/auth/login` to get started quickly.

### Run with Docker

```bash
docker compose up --build
```

This spins up both the API and MongoDB with a persistent volume.

---

## 📡 API Reference

All routes are versioned under `/v1`. Interactive docs available at **http://localhost:8080/swagger-ui.html**.

### 🔓 Auth

| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `POST` | `/v1/auth/login` | — | Login, returns access + refresh tokens |
| `POST` | `/v1/auth/refresh` | — | Exchange refresh token for a new access token |
| `POST` | `/v1/auth/logout` | Bearer | Revoke all refresh tokens for the current user |

### 👤 Users

| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `GET` | `/v1/users/me` | Bearer | Get current user info and active sessions |
| `GET` | `/v1/users` | Admin | List all users |

### 🔧 Admin

| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `POST` | `/v1/admin/users` | Admin | Create a new user |

### 💚 Health

| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/v1/health` | API and MongoDB health status |

---

## 📁 Project Structure

```
src/main/kotlin/io/visus/demos/kotlinapi/
├── api/                  # Contracts (request/response DTOs), mappers, versioning
├── config/               # Spring configuration (security, JWT, OpenAPI, MongoDB)
├── controller/           # HTTP layer (Auth, Admin, Users, Health)
├── domain/
│   ├── model/            # Domain models
│   ├── service/          # Business logic interfaces + implementations
│   └── exception/        # Custom exceptions + global error handler
├── infrastructure/
│   ├── security/         # JWT filter, token provider, auth handlers
│   └── user/             # Repository interfaces (MongoDB)
└── seed/                 # Data seeder (dev only)
```

---

## 📚 Documentation

- [Authentication & Security](docs/authentication-and-security.md) — JWE tokens, refresh rotation, theft detection, RBAC, and configuration

---

## 🧑‍💻 Development

```bash
# Run tests
./gradlew test

# Lint
./gradlew ktlintCheck

# Auto-fix lint issues
./gradlew ktlintFormat

# Check for dependency updates
./gradlew dependencyUpdates
```