# Simple AI Gateway Tool

A policy-enforced gateway that mediates AI agent access to external systems such as Jira, Jenkins, and databases. The AI acts as a requesting client: every action must pass through server-side policy evaluation, authorization, and audit before reaching the target system.

**Stack:** Java 21, Spring Boot, Gradle, Docker

For architectural decisions and rationale, see [ARCHITECTURAL-FACTS.md](ARCHITECTURAL-FACTS.md).

## Quick Start

### Prerequisites

- Java 21 (build)
- Docker & Docker Compose (run)

### Build & Run

```bash
./start.sh
```

This builds the bootJar, starts the gateway in Docker, and verifies it's healthy at `http://localhost:8080`.

To stop:

```bash
./stop.sh
```

### Manual Build

```bash
./gradlew :app-monolith:bootJar --no-daemon
docker compose up --build -d
```

## How It Works

```
AI Client / Agent   -->  POST /api/gateway/execute  -->  Gateway
                                                          |
                                          Authorization --+
                                          JWT Auth -------+
                                          Fraud Detection +
                                          Policy Engine --+
                                          Audit ----------+
                                                          |
                                                     Tool Provider (Jira / Jenkins / DB)
```

1. The AI authenticates via `/api/auth/token` and receives a scoped JWT
2. Every tool invocation goes through `/api/gateway/execute`
3. The gateway evaluates policies (deny-overrides), checks authorization, runs fraud detection, and logs an audit entry
4. Only if all checks pass does the request reach the tool provider

## Tool Surface

The gateway currently exposes these tool operations through its HTTP interface:

| Tool | Description |
|------|-------------|
| `jira.getTicket` / `jira.createTicket` | Read and create Jira tickets |
| `jenkins.deploy` | Trigger Jenkins deployments |
| `db.queryReadonly` | Execute read-only DB queries |
| `db.runLiquibase` | Run Liquibase migrations |
| `db.executeScript` | Execute DB scripts (intentionally blocked by policy in the default config) |

## Demo Scenes

The `scenes/` directory contains a guided walkthrough. Each scene demonstrates a specific policy behavior. Run them in order: scene 00 sets up authentication, then each subsequent scene builds on the previous.

### Setup

| # | Scene | File |
|---|-------|------|
| 00 | Setup: Authenticate & Start Gateway | [00-setup.md](scenes/00-setup.md) |

### Policy Decisions

| # | Scene | Expected Decision |
|---|-------|-------------------|
| 01 | Read-only database query | ALLOW |
| 02 | Production deployment (requires approval) | REQUIRE_APPROVAL |
| 03 | Scope mismatch (insufficient permissions) | DENY |
| 04 | Blocked tool (db.executeScript) | DENY |
| 05 | Rate limit exceeded | DENY |
| 06 | Outside time window (business hours) | DENY |
| 07 | Argument validation (project not in allowlist) | DENY |

### Fraud Detection

| # | Scene | Attack Vector |
|---|-------|---------------|
| 08 | SQL injection in query arguments | [08-fraud-sql-injection.md](scenes/08-fraud-sql-injection.md) |
| 09 | Prompt injection in tool arguments | [09-fraud-prompt-injection.md](scenes/09-fraud-prompt-injection.md) |
| 10 | Repeated denial pattern (hammering) | [10-fraud-repeated-denial.md](scenes/10-fraud-repeated-denial.md) |

### Observability

| # | Scene | What It Shows |
|---|-------|---------------|
| 11 | Audit trail query | [11-audit-trail.md](scenes/11-audit-trail.md) |
| 12 | Hot-reload policies without restart | [12-hot-reload-policies.md](scenes/12-hot-reload-policies.md) |

## Policy Configuration

Policies live in `files/config/policies.yaml`. The format uses a Kubernetes-style manifest with 6 rule types: `scope`, `environment`, `argument_allowlist`, `time_window`, `rate_limit`, `block`.

Policies support hot-reload — edit the file and the gateway picks up changes without restart (see scene 12).

## Project Structure

```
app-monolith/                    # Composition root (Spring Boot app)
adapter-http-gateway/            # HTTP orchestration (/api/gateway/*)
adapter-http-security-infra/     # JWT auth & Spring Security
gateway-module-policy/           # Policy engine (6 rule evaluators)
gateway-module-authorization/    # Scope-to-permission mapping
gateway-module-audit/            # Audit trail (NDJSON, TSDB-ready)
gateway-module-fraud-detection/  # SQL injection, prompt injection, pattern detection
gateway-module-tool-registry/    # Tool autodiscovery
gateway-providers/               # Jira, Jenkins, Database providers
scenes/                          # Guided demo walkthrough
files/config/                    # policies.yaml
```