Kite2Server

Kite2Server is a Spring Boot (Java) backend project featuring REST APIs for data management and GPT integration.

Quick Overview

• Java: 17
• Spring Boot: 3.x (Parent in pom.xml 3.1.0)
• Main Class: com.hhn.kite2server.Kite2ServerApplication
• Build Tool: Maven (uses ./mvnw / mvnw.cmd on Windows)

Table of Contents

• Prerequisites
• Build & Start
• Configuration
• Key Modules / Controllers
• Troubleshooting
• Development & Contribution
• Tests
• License

Prerequisites

• JDK 17 installed and added to PATH
• Maven (or the provided wrapper script mvnw / mvnw.cmd)
• PostgreSQL (or a configured database)

Build & Start

On Windows (PowerShell):

# Build
.\mvnw.cmd clean package

# Starten (erzeugte JAR im Ordner target, finalName = Kite2Server)
java -jar .\target\Kite2Server.jar

# Alternativ direkt mit dem Maven Spring Boot Plugin (zum Entwickeln)
.\mvnw.cmd spring-boot:run

On Unix/macOS:

./mvnw clean package
java -jar ./target/Kite2Server.jar

Running Tests:

.\mvnw.cmd test

Configuration

The central configuration is located in src/main/resources/application.yml. Key settings include:

• server.port: Default is 8080
• spring.datasource.*: JDBC URL, username, and password (current values are examples — must be updated)
• openai.api.key / Environment Variables: The project utilizes spring-dotenv. Sensitive keys should be stored in a .env file or set as environment variables. Essential variables:
  • OPENAI_API_KEY (API key for GPT)
  • OPENAI_MODEL (e.g., gpt-4o)
  • API_USERNAME / API_PASSWORD (if applicable)
• SSL Keystore: src/main/resources/keystore/keystore.p12 (optional).

Important: The example passwords in the repository are placeholders. Never commit sensitive data to the repository.

Key Modules / Controllers

The project is structured into packages under com.hhn.kite2server. Important sub-packages and controllers include:

• data: DataController, DataService, DataRepository
• gpt: GptController, GptService, GptConfig

The main entry point is com.hhn.kite2server.Kite2ServerApplication.

Security Configuration & API Authentication

The project implements a multi-layered security approach to protect API endpoints:

1. HMAC Request Validation

• All requests are validated using HMAC-SHA256 signatures
• The validator checks:
  • Timestamp Header: Ensures the request is not older than 5 minutes (MAX_TIMESTAMP_AGE_SECONDS = 300)
  • Signature Header: Validates the HMAC-SHA256 signature calculated from the timestamp and secret key
  • Secret Key: Configured via security.kite.hmac-secret property
• Validation is performed by HmacRequestValidator component

2. Passphrase-based Authentication

• An additional passphrase ("shared secret") is used to prevent unauthorized access to AI features
• The passphrase is configured via security.kite.passphrase property
• Validated by AuthService through direct comparison
• Used to control access to GPT/AI endpoints

3. Temporary Session Tokens

• After successful authentication, clients receive a temporary session token
• Tokens are created via POST /api/auth/session endpoint
• Token validity: 10 minutes (600 seconds)
• Tokens are stored in a ConcurrentHashMap and automatically cleaned up upon expiration
• Managed by TempTokenService

Configuration Requirements

Add the following to your application.yml:

security:
  kite:
    hmac-secret: "your-secret-key-here"
    passphrase: "your-passphrase-here"

Logging & Management

• Actuator: Enabled (exposed endpoints are configurable in application.yml)
• Access Logs: Configured in application.yml via Tomcat accesslog.

Troubleshooting

• Database Connection Failed: Verify spring.datasource.url, username, password, and ensure PostgreSQL is reachable.
• TLS/SSL: To start with SSL, set server.ssl.enabled: true and configure key-store / key-store-password.

Development & Contribution

• Branch Workflow: Use feature branches and submit Pull Requests (PRs) against main.
• Code Format: The project follows standard Java formatting and uses Lombok in several parts of the code.
• Security: Do not commit secrets — use .env files or a CI secret store instead.

Tests

• Unit and integration tests can be executed using ./mvnw test or mvnw.cmd test.

License

The source code is released under the MIT License. For details, see LICENSE_SOFTWARE.txt

Summary: This README provides a quick start guide for building, running, and configuring the project. Ensure you adapt the application.yml and environment variables to your environment, particularly the database and API keys.

---

Kite2Server

Kite2Server ist ein Spring Boot (Java) Backend-Projekt mit REST-APIs für Datenverwaltung und GPT-Integration.

Kurzüberblick

• Java: 17
• Spring Boot: 3.x (Parent im pom.xml 3.1.0)
• Hauptklasse: com.hhn.kite2server.Kite2ServerApplication
• Build Tool: Maven (./mvnw / mvnw.cmd auf Windows)

Inhalt dieser README

• Voraussetzungen
• Build & Start
• Konfiguration
• Wichtige Module / Controller
• Troubleshooting

Voraussetzungen

• JDK 17 installiert und in PATH
• Maven (oder das mitgelieferte Wrapper-Skript mvnw / mvnw.cmd)
• PostgreSQL (oder eine konfigurierte Datenbank)

Build & Start

Auf Windows (Powershell):

# Build
.\mvnw.cmd clean package

# Starten (erzeugte JAR im Ordner target, finalName = Kite2Server)
java -jar .\target\Kite2Server.jar

# Alternativ direkt mit dem Maven Spring Boot Plugin (zum Entwickeln)
.\mvnw.cmd spring-boot:run

Auf Unix/macOS:

./mvnw clean package
java -jar ./target/Kite2Server.jar

Für Tests:

.\mvnw.cmd test

Konfiguration

Zentrale Konfiguration liegt in src/main/resources/application.yml. Wichtige Punkte:

• server.port: Standard 8080
• spring.datasource.*: JDBC URL, Nutzer und Passwort (aktuell Beispielwerte — unbedingt anpassen)
• openai.api.key bzw. Umgebungsvariablen: Das Projekt nutzt spring-dotenv — sensitive Keys sollten in einer .env liegen oder als Umgebungsvariablen gesetzt werden. Wichtige Variablen:
  • OPENAI_API_KEY (API-Key für GPT)
  • OPENAI_MODEL (z. B. gpt-4o)
  • API_USERNAME / API_PASSWORD (falls genutzt)
• SSL-Keystore: src/main/resources/keystore/keystore.p12 (optional; im application.yml als Kommentar vorhanden)

Wichtig: Die im Repository vorhandenen Beispielpasswörter sind Platzhalter. Niemals sensible Daten ins Repo committen.

Wichtige Module / Controller

Das Projekt ist in Pakete unter com.hhn.kite2server strukturiert. Wichtige Subpakete und Controller (nicht vollständig):

• data — DataController, DataService, DataRepository
• gpt — GptController, GptService, GptConfig

Die Hauptklasse ist com.hhn.kite2server.Kite2ServerApplication.

Sicherheitskonfiguration & API-Authentifizierung

Das Projekt implementiert einen mehrschichtigen Sicherheitsansatz zum Schutz der API-Endpunkte:

1. HMAC-Request-Validierung

• Alle Anfragen werden mit HMAC-SHA256-Signaturen validiert
• Der Validator prüft:
  • Timestamp-Header: Stellt sicher, dass die Anfrage nicht älter als 5 Minuten ist (MAX_TIMESTAMP_AGE_SECONDS = 300)
  • Signature-Header: Validiert die HMAC-SHA256-Signatur, die aus Timestamp und Secret-Key berechnet wird
  • Secret Key: Konfiguriert über security.kite.hmac-secret Property
• Die Validierung wird durch die HmacRequestValidator-Komponente durchgeführt

2. Passphrase-basierte Authentifizierung

• Eine zusätzliche Passphrase ("Shared Secret") wird verwendet, um unbefugten Zugriff auf KI-Funktionen zu verhindern
• Die Passphrase wird über security.kite.passphrase Property konfiguriert
• Validiert durch AuthService mittels direktem Vergleich
• Kontrolliert den Zugriff auf GPT/KI-Endpunkte

3. Temporary Session Tokens

• Nach erfolgreicher Authentifizierung erhalten Clients einen temporären Session-Token
• Tokens werden via POST /api/auth/session Endpunkt erstellt
• Token-Gültigkeitsdauer: 10 Minuten (600 Sekunden)
• Tokens werden in einer ConcurrentHashMap gespeichert und automatisch bei Ablauf bereinigt
• Verwaltet durch TempTokenService

Konfigurationsanforderungen

Fügen Sie folgende Einstellungen zu Ihrer application.yml hinzu:

security:
  kite:
    hmac-secret: "your-secret-key-here"
    passphrase: "your-passphrase-here"

Logging & Management

• Actuator ist aktiviert (exposed endpoints konfigurierbar in application.yml)
• Access-Logs sind in application.yml konfiguriert (Tomcat accesslog)

Troubleshooting

• Datenbankverbindung schlägt fehl: Prüfe spring.datasource.url, Nutzer, Passwort und ob Postgres erreichbar ist.
• TLS/SSL: Falls mit SSL gestartet werden soll, server.ssl.enabled: true setzen und key-store/key-store-password konfigurieren.

Entwicklung & Contribution

• Branch-Workflow: Feature-Branches, PRs gegen main.
• Code-Format: Projekt nutzt Standard-Java-Formatierung; Nutzt Lombok in Teilen des Codes.
• Bitte keine Secrets committen — stattdessen .env oder CI-Secret-Store verwenden.

Tests

• Unit- und Integrationstests lassen sich mit ./mvnw test bzw. mvnw.cmd test ausführen.

Lizenz

Der Quellcode steht unter der MIT-Lizenz. Details siehe LICENSE_SOFTWARE.txt

Kurzzusammenfassung: Diese README bietet einen schnellen Einstieg zum Bauen, Starten und Konfigurieren des Projekts. Passe application.yml und Umgebungsvariablen an deine Umgebung an, insbesondere DB- und API-Keys.