Good Deeds Backend API

NestJS-basiertes Backend für die Good Deeds Nachbarschaftshilfe-App.

Features

✅ Authentifizierungs-System

• User Registration mit Email-Verifizierung
• Login mit JWT (Access + Refresh Tokens)
• Password-Hashing mit Argon2
• OAuth 2.0 Support (Google, Apple) - vorbereitet
• Password Reset Flow
• Rate Limiting gegen Brute-Force
• Session Management

✅ Security

• HTTPS-only in Production
• Secure Cookie Settings
• CSRF Protection (via JWT)
• Input Validation (class-validator)
• Helmet Security Headers
• SQL Injection Prevention (TypeORM)
• CORS Configuration

✅ API Documentation

• Swagger/OpenAPI UI unter /api/docs
• Vollständige Endpoint-Dokumentation
• Request/Response Schemas

Tech Stack

• Runtime: Node.js 20 LTS
• Framework: NestJS 10.x
• Language: TypeScript 5.x
• Database: PostgreSQL 16 mit TypeORM
• Auth: JWT + Passport.js
• Password Hashing: Argon2
• Validation: class-validator
• Testing: Jest
• API Docs: Swagger/OpenAPI

Getting Started

Prerequisites

• Node.js 20+ installiert
• PostgreSQL 16+ (oder Docker Compose)
• npm/yarn installiert

Installation

# Dependencies installieren
npm install

# Environment konfigurieren
cp .env.example .env
# .env editieren und Werte anpassen

Environment Variables

Wichtige Variablen in .env:

# Database
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=gooddeeds
DATABASE_PASSWORD=your_password
DATABASE_NAME=gooddeeds_db

# JWT
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_ACCESS_TOKEN_EXPIRATION=15m
JWT_REFRESH_TOKEN_EXPIRATION=7d

# Email (für Verification & Password Reset)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-app-password

Database Setup

Option 1: Docker Compose (empfohlen)

# Von root directory
docker-compose up -d postgres

# Automatisch erstellt:
# - PostgreSQL Database
# - PostGIS Extension
# - Users Table

Option 2: Lokale PostgreSQL Installation

# Database erstellen
createdb gooddeeds_db

# Migrations laufen lassen (automatisch beim Start)
npm run start:dev

Running the App

# Development mit Hot-Reload
npm run start:dev

# Production Build
npm run build
npm run start:prod

# Debug Mode
npm run start:debug

Server läuft auf: http://localhost:3000
API Docs: http://localhost:3000/api/docs

API Endpoints

Authentifizierung

Method	Endpoint	Description	Auth Required
POST	/api/v1/auth/register	User registrieren	❌
POST	/api/v1/auth/login	User login	❌
POST	/api/v1/auth/refresh	Access Token erneuern	❌
POST	/api/v1/auth/logout	User logout	✅
POST	/api/v1/auth/verify-email	Email verifizieren	❌
POST	/api/v1/auth/resend-verification	Verifizierungs-Email erneut senden	❌
POST	/api/v1/auth/forgot-password	Password Reset anfordern	❌
POST	/api/v1/auth/reset-password	Passwort zurücksetzen	❌
GET	/api/v1/auth/me	Aktuelles User-Profil	✅

Beispiel Requests

Register:

curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "name": "Max Mustermann"
  }'

Login:

curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!"
  }'

Get Profile (mit JWT):

curl -X GET http://localhost:3000/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Testing

# Unit Tests
npm run test

# Watch Mode
npm run test:watch

# Test Coverage
npm run test:cov

# E2E Tests
npm run test:e2e

Test Coverage:

• ✅ Auth Service (Register, Login, Verification, Password Reset)
• ✅ JWT Strategy
• ✅ Guards & Decorators

Rate Limiting

Konfigurierte Limits:

Endpoint	Limit	Window
Global	100 requests	1 Minute
/auth/register	3 requests	1 Minute
/auth/login	5 requests	1 Minute
/auth/forgot-password	3 requests	5 Minuten
/auth/resend-verification	3 requests	5 Minuten

Security

Siehe SECURITY_AUDIT.md für vollständige Security-Dokumentation.

Key Security Features:

• 🔒 Argon2 Password Hashing
• 🔑 JWT Token Authentication (15min Access + 7d Refresh)
• 📧 Email Verification erforderlich
• 🚫 Rate Limiting gegen Brute-Force
• 🛡️ Helmet Security Headers
• ✅ Input Validation
• 🔐 CSRF Protection
• 🚨 SQL Injection Prevention

Project Structure

apps/backend/
├── src/
│   ├── auth/                    # Authentifizierung
│   │   ├── dto/                 # Data Transfer Objects
│   │   ├── services/            # Auth & Email Services
│   │   ├── strategies/          # JWT Strategy
│   │   ├── auth.controller.ts
│   │   └── auth.module.ts
│   ├── users/                   # User Management
│   │   ├── entities/            # User Entity
│   │   └── users.module.ts
│   ├── common/                  # Shared Code
│   │   ├── guards/              # Auth Guards
│   │   ├── decorators/          # Custom Decorators
│   │   ├── filters/             # Exception Filters
│   │   └── pipes/               # Validation Pipes
│   ├── config/                  # Configuration
│   │   ├── database.config.ts
│   │   └── jwt.config.ts
│   ├── database/
│   │   └── migrations/          # Database Migrations
│   ├── app.module.ts
│   └── main.ts
├── test/                        # E2E Tests
├── .env.example
├── nest-cli.json
├── package.json
├── tsconfig.json
├── README.md
└── SECURITY_AUDIT.md

Database Schema

User Entity:

{
  id: UUID (Primary Key)
  email: string (unique, indexed)
  passwordHash: string (Argon2)
  name: string
  avatarUrl: string?
  location: geography(POINT)?
  pointsBalance: number (default: 0)
  oauthProvider: 'google' | 'apple' | null
  oauthId: string?
  emailVerified: boolean (default: false)
  emailVerificationToken: string?
  passwordResetToken: string?
  refreshTokenHash: string?
  isActive: boolean (default: true)
  isBanned: boolean (default: false)
  lastLogin: timestamp?
  createdAt: timestamp
  updatedAt: timestamp
}

Next Steps

• [ ] OAuth Integration (Google, Apple)
• [ ] Tasks Module (Aufgaben erstellen/annehmen)
• [ ] Points Module (Punktesystem)
• [ ] Partners Module (Werbepartner)
• [ ] Redemptions Module (Rabatte einlösen)
• [ ] Notifications (Push Notifications)
• [ ] Admin Panel

Support & Contact

Bei Fragen oder Problemen:

• Issues: GitHub Issues
• Email: tech@gooddeeds.app

License

Private - Good Deeds App © 2026