chore(release): 1.8.1

close #210

.env.ci

@@ -0,0 +1,9 @@
+APP_PORT=4010
+DB_TYPE=sqlite
+DB_HOST=unused
+DB_PORT=unused
+DB_USER=unused
+DB_PASSWORD=bla
+DB_NAME=./test.sqlite
+NODE_ENV=dev
+POSTALCODE_COUNTRYCODE=DE

.env.example

@@ -1,8 +1,14 @@
 APP_PORT=4010
-DB_TYPE=bla
+DB_TYPE=sqlite
 DB_HOST=bla
 DB_PORT=bla
 DB_USER=bla
 DB_PASSWORD=bla
-DB_NAME=bla
-NODE_ENV=production
+DB_NAME=./test.sqlite
+NODE_ENV=production
+POSTALCODE_COUNTRYCODE=DE
+SEED_TEST_DATA=false
+SELFSERVICE_URL=bla
+STATION_TOKEN_SECRET=<replace-with-random-secret-min-32-chars>
+NATS_URL=nats://localhost:4222
+NATS_PREWARM=false

.gitea/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Build release images
+on:
+  push:
+    tags:
+      - "*.*.*"
+
+jobs:
+  build-container:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun licenses:export
+      - name: Login to registry
+        uses: docker/login-action@v3
+        with:
+          registry: registry.odit.services
+          username: ${{ vars.REGISTRY_USERNAME }}
+          password: ${{ secrets.REGISTRY_PASSWORD }}
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          push: true
+          tags: |
+            ${{ vars.REGISTRY }}/lfk/backend:${{ github.ref_name }}
+          platforms: linux/amd64,linux/arm64

.gitignore

@@ -126,9 +126,17 @@ dist
 .yarn/build-state.yml
 .yarn/install-state.gz
 .pnp.*
+
+# Old package manager lockfiles (Bun migration - keep bun.lock)
 yarn.lock
 package-lock.json
+pnpm-lock.yaml
+
 build
 
 *.sqlite
-docs
+*.sqlite-jurnal
+/docs
+lib
+/oss-attribution
+*.tmp

.vscode/settings.json

@@ -9,8 +9,7 @@
     "[typescript]": {
         "editor.defaultFormatter": "vscode.typescript-language-features",
         "editor.codeActionsOnSave": {
-            "source.organizeImports": true,
-            // "source.fixAll": true
+            "source.organizeImports": "explicit"
         }
     },
     "javascript.preferences.quoteStyle": "single",

AGENTS.md

@@ -0,0 +1,282 @@
+# AGENTS.md — LfK Backend
+
+Guidance for agentic coding agents working in this repository.
+
+---
+
+## Project Overview
+
+Express + [`routing-controllers`](https://github.com/typestack/routing-controllers) REST API written in TypeScript. Uses TypeORM for database access (SQLite in dev/test, PostgreSQL or MySQL in production). OpenAPI docs are auto-generated from decorators at startup.
+
+**Runtime & Package Manager**: Bun (replaces Node.js + npm/pnpm).
+
+---
+
+## Build / Run / Test Commands
+
+### Development
+
+```sh
+bun run dev           # Start dev server with auto-reload (uses Bun's --watch)
+```
+
+**Auto-reload**: The `dev` script uses Bun's built-in `--watch` flag, which automatically restarts the server when TypeScript files in `src/` change. Bun runs TypeScript directly - no build step needed.
+
+**Performance**: Bun delivers 8-15% better latency under concurrent load compared to Node.js. See `BUN_BENCHMARK_RESULTS.md` for details.
+
+### Build
+
+```sh
+bun run build         # rimraf dist && tsc && copy static assets → dist/
+```
+
+**Note**: The build script exists for legacy compatibility and type-checking, but is **not required** for development or production. Bun runs TypeScript source files directly.
+
+### Production
+
+```sh
+bun start             # bun src/app.ts (runs TypeScript directly)
+```
+
+### Tests
+
+Tests are **integration tests** that hit a live running server via HTTP. The server must be started before Jest is invoked.
+
+```sh
+# Full CI test flow (generates .env, starts server, runs jest):
+bun run test:ci
+
+# Run Jest directly (server must already be running):
+bun test
+
+# Watch mode:
+bun run test:watch
+
+# Run a single test file:
+bunx jest src/tests/runners/runner_add.spec.ts
+
+# Run tests matching a name pattern:
+bunx jest --testNamePattern="POST /api/runners"
+
+# Run all tests in a subdirectory:
+bunx jest src/tests/runners/
+```
+
+# Run all tests in a subdirectory:
+bunx jest src/tests/runners/
+```
+
+> **Important:** `bun test` alone will fail unless the dev server is already running on `http://localhost:<config.internal_port>`. In CI, `start-server-and-test` handles this automatically via `bun run test:ci`.
+
+### Other Utilities
+
+```sh
+bun run seed                 # Sync DB schema and run seeders
+bun run openapi:export       # Export OpenAPI spec to file
+bun run docs                 # Generate TypeDoc documentation
+bun run licenses:export      # Export third-party license report
+```
+
+---
+
+## TypeScript Configuration
+
+- **Target:** ES2020, **Module:** CommonJS
+- **`strict: false`** — TypeScript strictness is disabled; types are used but not exhaustively enforced
+- **`experimentalDecorators: true`** and **`emitDecoratorMetadata: true`** — required by `routing-controllers`, `TypeORM`, and `class-validator`
+- Spec files (`**/*.spec.ts`) are excluded from compilation
+- Source root: `src/`, output: `dist/`
+
+---
+
+## Code Style Guidelines
+
+### No Linter / Formatter Configured
+
+There is no ESLint or Prettier configuration. Follow the patterns already established in the codebase rather than introducing new tooling.
+
+### Imports
+
+- Use named imports for decorator packages: `import { Get, JsonController, Param } from 'routing-controllers'`
+- Use named imports for TypeORM: `import { Column, Entity, getConnectionManager } from 'typeorm'`
+- Use named imports for class-validator: `import { IsInt, IsOptional, IsString } from 'class-validator'`
+- Use `import * as X from 'module'` for modules without clean default exports (e.g., `import * as jwt from 'jsonwebtoken'`)
+- Use default imports for simple modules (e.g., `import cookie from 'cookie'`)
+- `reflect-metadata` is imported once at the top of `src/app.ts` — do not re-import it
+- No barrel/index re-export files; import source files directly by path
+
+### Naming Conventions
+
+| Construct | Convention | Example |
+|---|---|---|
+| Classes | `PascalCase` | `RunnerController`, `CreateRunner` |
+| Files | `PascalCase.ts` matching class name | `RunnerController.ts` |
+| Local variables | `camelCase` (some `snake_case` in tests) | `accessToken`, `access_token` |
+| DB entity fields | `snake_case` preferred | `created_at`, `updated_at` |
+| Controller methods | REST-conventional | `getAll`, `getOne`, `post`, `put`, `remove` |
+| Custom errors | `{Entity}{Issue}Error` | `RunnerNotFoundError`, `RunnerIdsNotMatchingError` |
+| Response DTOs | `Response{Entity}` | `ResponseRunner`, `ResponseAuth` |
+| Create DTOs | `Create{Entity}` | `CreateRunner` |
+| Update DTOs | `Update{Entity}` | `UpdateRunner` |
+| Enums | `PascalCase` | `ResponseObjectType`, `PermissionAction` |
+
+### Formatting
+
+- 4-space indentation (observed throughout the codebase)
+- Single quotes for string literals in most files
+- No trailing semicolons style inconsistency — follow what's already in the file you're editing
+
+### Types
+
+- Add TypeScript types to all function parameters and return values
+- Use `class-validator` decorators (`@IsString`, `@IsInt`, `@IsOptional`, `@IsUUID`, etc.) on every DTO and response class field — these drive both runtime validation and OpenAPI schema generation
+- Use abstract classes for shared entity base types (e.g., `abstract class Participant`)
+- Use interfaces for response contracts (e.g., `interface IResponse`)
+- Use enums for typed string/number constants
+- Avoid `any` where possible; when unavoidable, keep it localised
+- `strict` is off — but still annotate types explicitly rather than relying on inference
+
+### Controller Pattern
+
+```typescript
+import { Authorized, Body, Delete, Get, JsonController, Param, Post, Put } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+
+@JsonController('/runners')
+@Authorized()
+export class RunnerController {
+    @Get('/')
+    @OpenAPI({ description: 'Returns all runners' })
+    @ResponseSchema(ResponseRunner, { isArray: true })
+    async getAll() { ... }
+
+    @Get('/:id')
+    @ResponseSchema(ResponseRunner)
+    async getOne(@Param('id') id: number) { ... }
+
+    @Post('/')
+    @ResponseSchema(ResponseRunner)
+    async post(@Body({ validate: true }) createRunner: CreateRunner) { ... }
+
+    @Put('/:id')
+    @ResponseSchema(ResponseRunner)
+    async put(@Param('id') id: number, @Body({ validate: true }) updateRunner: UpdateRunner) { ... }
+
+    @Delete('/:id')
+    @ResponseSchema(ResponseRunner)
+    async remove(@Param('id') id: number) { ... }
+}
+```
+
+### Error Handling
+
+- Define custom error classes in `src/errors/` extending `routing-controllers` error types (`NotFoundError`, `NotAcceptableError`, etc.)
+- Every custom error class must include `@IsString()` decorated `name` and `message` fields for OpenAPI schema generation
+- Throw custom errors directly in controllers: `throw new RunnerNotFoundError()`
+- Use try/catch in controllers and re-throw meaningful errors; do not swallow errors silently
+- The global `ErrorHandler` middleware (registered in `src/middlewares/`) catches all unhandled errors and serialises them as JSON — do not duplicate this logic in controllers
+- Auth errors are thrown from `src/middlewares/authchecker.ts`, not from individual controllers
+
+### Entity Pattern (TypeORM)
+
+- Entities live in `src/models/entities/`
+- Decorate every entity with `@Entity()` and every column with the appropriate `@Column`, `@PrimaryGeneratedColumn`, etc.
+- Use `@CreateDateColumn()` / `@UpdateDateColumn()` for timestamp fields
+- Use table inheritance (`@TableInheritance` + `@ChildEntity`) for polymorphic entities
+- Access repositories via `getConnectionManager().get().getRepository(EntityClass)` — do not inject repositories as constructor dependencies
+- Database schema is synchronised automatically on startup (`connection.synchronize()`) — no manual migration files
+
+### DTO Pattern (Create / Update)
+
+- Create DTOs in `src/models/actions/create/` and `src/models/actions/update/`
+- Use `class-validator` decorators for every field
+- `@IsOptional()` for fields that are not required on update; all fields on create DTOs should be mandatory unless explicitly optional in the API contract
+- Response DTOs live in `src/models/responses/` and follow the `Response{Entity}` naming pattern
+
+---
+
+## Test Style Guidelines
+
+> **IMPORTANT: Do not run existing tests and do not create new tests.** The existing test suite in `src/tests/` is outdated and no longer reflects the current state of the codebase. Ignore all test files when working in this repository. Do not write new tests for any changes or additions.
+
+All tests are integration tests in `src/tests/` organised by domain entity:
+
+```
+src/tests/
+  auth/
+    auth_login.spec.ts
+    auth_refresh.spec.ts
+  runners/
+    runner_add.spec.ts
+    runner_get.spec.ts
+    runner_update.spec.ts
+    runner_delete.spec.ts
+  ...
+```
+
+### Test File Template
+
+```typescript
+import axios from 'axios';
+import { config } from '../../config';
+const base = "http://localhost:" + config.internal_port;
+
+let access_token: string;
+let axios_config: object;
+
+beforeAll(async () => {
+    jest.setTimeout(20000);
+    const res = await axios.post(base + '/api/auth/login', { username: "demo", password: "demo" });
+    access_token = res.data["access_token"];
+    axios_config = {
+        headers: { "authorization": "Bearer " + access_token },
+        validateStatus: undefined   // prevents axios from throwing on non-2xx responses
+    };
+});
+
+describe('POST /api/runners working', () => {
+    it('creating a runner with required params should return 200', async () => {
+        const res = await axios.post(base + '/api/runners', { ... }, axios_config);
+        expect(res.status).toEqual(200);
+        expect(res.headers['content-type']).toContain("application/json");
+    });
+});
+
+describe('POST /api/runners failing', () => {
+    it('creating a runner without required params should return 400', async () => {
+        const res = await axios.post(base + '/api/runners', {}, axios_config);
+        expect(res.status).toEqual(400);
+    });
+});
+```
+
+- Always set `validateStatus: undefined` in `axios_config` to prevent axios throwing on error responses
+- Group tests by HTTP verb + route in `describe()` blocks; separate "working" and "failing" cases
+- Use `jest.setTimeout(20000)` in `beforeAll` for slow integration tests
+- Assert both `res.status` and `res.headers['content-type']` on success paths
+
+---
+
+## Environment Configuration
+
+- Copy `.env.example` to `.env` and fill in values before running locally
+- Database type is set via `DB_TYPE` env var (`sqlite`, `postgres`, or `mysql`)
+- Server port is set via `INTERNAL_PORT` (accessed as `config.internal_port` in code)
+- All config values are validated at startup in `src/config.ts`
+- CI env is generated by `bun run test:ci:generate_env` (`scripts/create_testenv.ts`)
+
+### NATS Configuration
+
+The backend uses **NATS JetStream** as a KV cache for scan intake performance optimization.
+
+- `NATS_URL` — connection URL for NATS server (default: `nats://localhost:4222`)
+- `NATS_PREWARM` — if `true`, preloads all runner state into the KV cache at startup to eliminate DB reads from the first scan onward (default: `false`)
+
+**KV buckets** (auto-created by `NatsClient` at startup):
+- `station_state` — station token cache (1-hour TTL)
+- `card_state` — card→runner mapping cache (1-hour TTL)
+- `runner_state` — runner display name, total distance, latest scan timestamp (no TTL, CAS-based updates)
+
+**Development**: NATS runs in Docker via `docker-compose.yml` (port 4222). The JetStream volume is persisted to `./nats-data/` to survive container restarts.
+
+**Station intake hot path**: `POST /api/scans/trackscans` from scan stations uses a KV-first flow that eliminates DB reads on cache hits and prevents race conditions via compare-and-swap (CAS) updates. See `SCAN_NATS_PLAN.md` for full architecture details.

Dockerfile

@@ -1,6 +1,23 @@
-FROM node:alpine
+# Typescript Build
+FROM registry.odit.services/hub/oven/bun:1.3.9-alpine AS build
 WORKDIR /app
-COPY ./package.json ./
-RUN yarn
-COPY ./ ./
-ENTRYPOINT [ "yarn","dev" ]
+
+COPY package.json bun.lockb* ./
+RUN bun install --frozen-lockfile
+
+COPY tsconfig.json ormconfig.js bunfig.toml ./
+COPY src ./src
+RUN bun run build \
+    && rm -rf /app/node_modules \
+    && bun install --production --frozen-lockfile
+
+# final image
+FROM registry.odit.services/hub/oven/bun:1.3.9-alpine AS final
+WORKDIR /app
+COPY --from=build /app/package.json /app/package.json
+COPY --from=build /app/bun.lockb* /app/
+COPY --from=build /app/ormconfig.js /app/ormconfig.js
+COPY --from=build /app/bunfig.toml /app/bunfig.toml
+COPY --from=build /app/dist /app/dist
+COPY --from=build /app/node_modules /app/node_modules
+ENTRYPOINT ["bun", "/app/dist/app.js"]

PERFORMANCE_IDEAS.md

@@ -0,0 +1,589 @@
+# Performance Optimization Ideas for LfK Backend
+
+This document outlines potential performance improvements for the LfK backend API, organized by impact and complexity.
+
+---
+
+## ✅ Already Implemented
+
+### 1. Bun Runtime Migration
+**Status**: Complete  
+**Impact**: 8-15% latency improvement  
+**Details**: Migrated from Node.js to Bun runtime, achieving:
+- Parallel throughput: +8.3% (306 → 331 scans/sec)
+- Parallel p50 latency: -9.5% (21ms → 19ms)
+
+### 2. NATS KV Cache for Scan Intake
+**Status**: Complete (based on code analysis)  
+**Impact**: Significant reduction in DB reads for hot path  
+**Details**: `ScanController.stationIntake()` uses NATS JetStream KV store to cache:
+- Station tokens (1-hour TTL)
+- Card→Runner mappings (1-hour TTL)
+- Runner state (no TTL, CAS-based updates)
+- Eliminates DB reads on cache hits
+- Prevents race conditions via compare-and-swap (CAS)
+
+---
+
+## 🚀 High Impact, Low-Medium Complexity
+
+### 3. Add Database Indexes
+**Priority**: HIGH  
+**Complexity**: Low  
+**Estimated Impact**: 30-70% query time reduction
+
+**Problem**: TypeORM synchronize() doesn't automatically create indexes on foreign keys or commonly queried fields.
+
+**Observations**:
+- Heavy use of `find()` with complex nested relations (e.g., `['runner', 'track', 'runner.scans', 'runner.group', 'runner.scans.track']`)
+- No explicit `@Index()` decorators found in entity files
+- Frequent filtering by foreign keys (runner_id, track_id, station_id, card_id)
+
+**Recommended Indexes**:
+
+```typescript
+// src/models/entities/Scan.ts
+@Index(['runner', 'timestamp'])  // For runner scan history queries
+@Index(['station', 'timestamp'])  // For station-based queries
+@Index(['card'])                  // For card lookup
+
+// src/models/entities/Runner.ts
+@Index(['email'])                 // For authentication/lookup
+@Index(['group'])                 // For group-based queries
+
+// src/models/entities/RunnerCard.ts
+@Index(['runner'])                // For card→runner lookups
+@Index(['code'])                  // For barcode scans
+
+// src/models/entities/Donation.ts
+@Index(['runner'])                // For runner donations
+@Index(['donor'])                 // For donor contributions
+```
+
+**Implementation Steps**:
+1. Audit all entities and add `@Index()` decorators
+2. Test query performance with `EXPLAIN` before/after
+3. Monitor index usage with database tools
+4. Consider composite indexes for frequently combined filters
+
+**Expected Results**:
+- 50-70% faster JOIN operations
+- 30-50% faster foreign key lookups
+- Reduced database CPU usage
+
+---
+
+### 4. Implement Query Result Caching
+**Priority**: HIGH  
+**Complexity**: Medium  
+**Estimated Impact**: 50-90% latency reduction for repeated queries
+
+**Problem**: Stats endpoints and frequently accessed data (org totals, team rankings, runner lists) are recalculated on every request.
+
+**Observations**:
+- `StatsController` methods load entire datasets with deep relations:
+  - `getRunnerStats()`: loads all runners with scans, groups, donations
+  - `getTeamStats()`: loads all teams with nested runner data
+  - `getOrgStats()`: loads all orgs with teams, runners, scans
+- Many `find()` calls without any caching layer
+- Data changes infrequently (only during scan intake)
+
+**Solution Options**:
+
+**Option A: NATS KV Cache (Recommended)**
+```typescript
+// src/nats/StatsKV.ts
+export async function getOrgStatsCache(): Promise<ResponseOrgStats[] | null> {
+    const kv = await NatsClient.getKV('stats_cache', { ttl: 60 * 1000 }); // 60s TTL
+    const entry = await kv.get('org_stats');
+    return entry ? JSON.parse(entry.string()) : null;
+}
+
+export async function setOrgStatsCache(stats: ResponseOrgStats[]): Promise<void> {
+    const kv = await NatsClient.getKV('stats_cache', { ttl: 60 * 1000 });
+    await kv.put('org_stats', JSON.stringify(stats));
+}
+
+// Invalidate on scan creation
+// src/controllers/ScanController.ts (after line 173)
+await invalidateStatsCache(); // Clear stats on new scan
+```
+
+**Option B: In-Memory Cache with TTL**
+```typescript
+// src/cache/MemoryCache.ts
+import NodeCache from 'node-cache';
+
+const cache = new NodeCache({ stdTTL: 60 }); // 60s TTL
+
+export function getCached<T>(key: string): T | undefined {
+    return cache.get<T>(key);
+}
+
+export function setCached<T>(key: string, value: T, ttl?: number): void {
+    cache.set(key, value, ttl);
+}
+
+export function invalidatePattern(pattern: string): void {
+    const keys = cache.keys().filter(k => k.includes(pattern));
+    cache.del(keys);
+}
+```
+
+**Option C: Redis Cache** (if Redis is already in stack)
+
+**Recommended Cache Strategy**:
+- **TTL**: 30-60 seconds for stats endpoints
+- **Invalidation**: On scan creation, runner updates, donation changes
+- **Keys**: `stats:org`, `stats:team:${id}`, `stats:runner:${id}`
+- **Warm on startup**: Pre-populate cache for critical endpoints
+
+**Expected Results**:
+- 80-90% latency reduction for stats endpoints (from ~500ms to ~50ms)
+- 70-80% reduction in database load
+- Improved user experience for dashboards and leaderboards
+
+---
+
+### 5. Lazy Load Relations & DTOs
+**Priority**: HIGH  
+**Complexity**: Medium  
+**Estimated Impact**: 40-60% query time reduction
+
+**Problem**: Many queries eagerly load deeply nested relations that aren't always needed.
+
+**Observations**:
+```typescript
+// Current: Loads everything
+scan = await this.scanRepository.findOne(
+    { id: scan.id }, 
+    { relations: ['runner', 'track', 'runner.scans', 'runner.group', 
+                  'runner.scans.track', 'card', 'station'] }
+);
+```
+
+**Solutions**:
+
+**A. Create Lightweight Response DTOs**
+```typescript
+// src/models/responses/ResponseScanLight.ts
+export class ResponseScanLight {
+    @IsInt() id: number;
+    @IsInt() distance: number;
+    @IsInt() timestamp: number;
+    @IsBoolean() valid: boolean;
+    // Omit nested runner.scans, runner.group, etc.
+}
+
+// Use for list views
+@Get()
+@ResponseSchema(ResponseScanLight, { isArray: true })
+async getAll() {
+    const scans = await this.scanRepository.find({ 
+        relations: ['runner', 'track'] // Minimal relations
+    });
+    return scans.map(s => new ResponseScanLight(s));
+}
+
+// Keep detailed DTO for single-item views
+@Get('/:id')
+@ResponseSchema(ResponseScan) // Full details
+async getOne(@Param('id') id: number) { ... }
+```
+
+**B. Use Query Builder for Selective Loading**
+```typescript
+// Instead of loading all scans with runner relations:
+const scans = await this.scanRepository
+    .createQueryBuilder('scan')
+    .leftJoinAndSelect('scan.runner', 'runner')
+    .leftJoinAndSelect('scan.track', 'track')
+    .select([
+        'scan.id', 'scan.distance', 'scan.timestamp', 'scan.valid',
+        'runner.id', 'runner.firstname', 'runner.lastname',
+        'track.id', 'track.name'
+    ])
+    .where('scan.id = :id', { id })
+    .getOne();
+```
+
+**C. Implement GraphQL-style Field Selection**
+```typescript
+@Get()
+async getAll(@QueryParam('fields') fields?: string) {
+    const relations = [];
+    if (fields?.includes('runner')) relations.push('runner');
+    if (fields?.includes('track')) relations.push('track');
+    return this.scanRepository.find({ relations });
+}
+```
+
+**Expected Results**:
+- 40-60% faster list queries
+- 50-70% reduction in data transfer size
+- Reduced JOIN complexity and memory usage
+
+---
+
+### 6. Pagination Optimization
+**Priority**: MEDIUM  
+**Complexity**: Low  
+**Estimated Impact**: 20-40% improvement for large result sets
+
+**Problem**: Current pagination uses `skip/take` which becomes slow with large offsets.
+
+**Current Implementation**:
+```typescript
+// Inefficient for large page numbers (e.g., page=1000)
+scans = await this.scanRepository.find({ 
+    skip: page * page_size,  // Scans 100,000 rows to skip them
+    take: page_size 
+});
+```
+
+**Solutions**:
+
+**A. Cursor-Based Pagination (Recommended)**
+```typescript
+@Get()
+async getAll(
+    @QueryParam('cursor') cursor?: number,  // Last ID from previous page
+    @QueryParam('page_size') page_size: number = 100
+) {
+    const query = this.scanRepository.createQueryBuilder('scan')
+        .orderBy('scan.id', 'ASC')
+        .take(page_size + 1); // Get 1 extra to determine if more pages exist
+    
+    if (cursor) {
+        query.where('scan.id > :cursor', { cursor });
+    }
+    
+    const scans = await query.getMany();
+    const hasMore = scans.length > page_size;
+    const results = scans.slice(0, page_size);
+    const nextCursor = hasMore ? results[results.length - 1].id : null;
+    
+    return {
+        data: results.map(s => s.toResponse()),
+        pagination: { nextCursor, hasMore }
+    };
+}
+```
+
+**B. Add Total Count Caching**
+```typescript
+// Cache total counts to avoid expensive COUNT(*) queries
+const totalCache = new Map<string, { count: number, expires: number }>();
+
+async function getTotalCount(repo: Repository<any>): Promise<number> {
+    const cacheKey = repo.metadata.tableName;
+    const cached = totalCache.get(cacheKey);
+    
+    if (cached && cached.expires > Date.now()) {
+        return cached.count;
+    }
+    
+    const count = await repo.count();
+    totalCache.set(cacheKey, { count, expires: Date.now() + 60000 }); // 60s TTL
+    return count;
+}
+```
+
+**Expected Results**:
+- 60-80% faster pagination for large page numbers
+- Consistent query performance regardless of offset
+- Better mobile app experience with cursor-based loading
+
+---
+
+## 🔧 Medium Impact, Medium Complexity
+
+### 7. Database Connection Pooling Optimization
+**Priority**: MEDIUM  
+**Complexity**: Medium  
+**Estimated Impact**: 10-20% improvement under load
+
+**Current**: Default TypeORM connection pooling (likely 10 connections)
+
+**Recommendations**:
+```typescript
+// ormconfig.js
+module.exports = {
+    // ... existing config
+    extra: {
+        // PostgreSQL specific
+        max: 20,                    // Max pool size (adjust based on load)
+        min: 5,                     // Min pool size
+        idleTimeoutMillis: 30000,   // Close idle connections after 30s
+        connectionTimeoutMillis: 2000,
+        
+        // MySQL specific
+        connectionLimit: 20,
+        waitForConnections: true,
+        queueLimit: 0
+    },
+    
+    // Enable query logging in dev to identify slow queries
+    logging: process.env.NODE_ENV !== 'production' ? ['query', 'error'] : ['error'],
+    maxQueryExecutionTime: 1000, // Log queries taking >1s
+};
+```
+
+**Monitor**:
+- Connection pool exhaustion
+- Query execution times
+- Active connection count
+
+---
+
+### 8. Bulk Operations for Import
+**Priority**: MEDIUM  
+**Complexity**: Medium  
+**Estimated Impact**: 50-80% faster imports
+
+**Problem**: Import endpoints likely save entities one-by-one in loops.
+
+**Solution**:
+```typescript
+// Instead of:
+for (const runnerData of importData) {
+    const runner = await createRunner.toEntity();
+    await this.runnerRepository.save(runner); // N queries
+}
+
+// Use bulk insert:
+const runners = await Promise.all(
+    importData.map(data => createRunner.toEntity())
+);
+await this.runnerRepository.save(runners); // 1 query
+
+// Or use raw query for massive imports:
+await getConnection()
+    .createQueryBuilder()
+    .insert()
+    .into(Runner)
+    .values(runners)
+    .execute();
+```
+
+---
+
+### 9. Response Compression
+**Priority**: MEDIUM  
+**Complexity**: Low  
+**Estimated Impact**: 60-80% reduction in response size
+
+**Implementation**:
+```typescript
+// src/app.ts
+import compression from 'compression';
+
+const app = createExpressServer({ ... });
+app.use(compression({
+    level: 6,           // Compression level (1-9)
+    threshold: 1024,    // Only compress responses >1KB
+    filter: (req, res) => {
+        if (req.headers['x-no-compression']) return false;
+        return compression.filter(req, res);
+    }
+}));
+```
+
+**Benefits**:
+- 70-80% smaller JSON responses
+- Faster transfer times on slow networks
+- Reduced bandwidth costs
+
+**Dependencies**: `bun add compression @types/compression`
+
+---
+
+## 🎯 Lower Priority / High Complexity
+
+### 10. Implement Read Replicas
+**Priority**: LOW (requires infrastructure)  
+**Complexity**: High  
+**Estimated Impact**: 30-50% read query improvement
+
+**When to Consider**:
+- Database CPU consistently >70%
+- Read-heavy workload (already true for stats endpoints)
+- Running PostgreSQL/MySQL in production
+
+**Implementation**:
+```typescript
+// ormconfig.js
+module.exports = {
+    type: 'postgres',
+    replication: {
+        master: {
+            host: process.env.DB_WRITE_HOST,
+            port: 5432,
+            username: process.env.DB_USER,
+            password: process.env.DB_PASSWORD,
+            database: process.env.DB_NAME,
+        },
+        slaves: [
+            {
+                host: process.env.DB_READ_REPLICA_1,
+                port: 5432,
+                username: process.env.DB_USER,
+                password: process.env.DB_PASSWORD,
+                database: process.env.DB_NAME,
+            }
+        ]
+    }
+};
+```
+
+---
+
+### 11. Move to Serverless/Edge Functions
+**Priority**: LOW (architectural change)  
+**Complexity**: Very High  
+**Estimated Impact**: Variable (depends on workload)
+
+**Considerations**:
+- Good for: Infrequent workloads, global distribution
+- Bad for: High-frequency scan intake (cold starts)
+- May conflict with TypeORM's connection model
+
+---
+
+### 12. GraphQL API Layer
+**Priority**: LOW (major refactor)  
+**Complexity**: Very High  
+**Estimated Impact**: 30-50% for complex queries
+
+**Benefits**:
+- Clients request only needed fields
+- Single request for complex nested data
+- Better mobile app performance
+
+**Trade-offs**:
+- Complete rewrite of controller layer
+- Learning curve for frontend teams
+- More complex caching strategy
+
+---
+
+## 📊 Recommended Implementation Order
+
+**Phase 1: Quick Wins** (1-2 weeks)
+1. Add database indexes → Controllers still work, immediate improvement
+2. Enable response compression → One-line change in `app.ts`
+3. Implement cursor-based pagination → Better mobile UX
+
+**Phase 2: Caching Layer** (2-3 weeks)
+4. Add NATS KV cache for stats endpoints
+5. Create lightweight response DTOs for list views
+6. Cache total counts for pagination
+
+**Phase 3: Query Optimization** (2-3 weeks)
+7. Refactor controllers to use query builder with selective loading
+8. Optimize database connection pooling
+9. Implement bulk operations for imports
+
+**Phase 4: Infrastructure** (ongoing)
+10. Monitor query performance and add more indexes as needed
+11. Consider read replicas when database becomes bottleneck
+
+---
+
+## 🔍 Performance Monitoring Recommendations
+
+### Add Metrics Endpoint
+```typescript
+// src/controllers/MetricsController.ts
+import { performance } from 'perf_hooks';
+
+const requestMetrics = {
+    totalRequests: 0,
+    avgLatency: 0,
+    p95Latency: 0,
+    dbQueryCount: 0,
+    cacheHitRate: 0,
+};
+
+@JsonController('/metrics')
+export class MetricsController {
+    @Get()
+    @Authorized('ADMIN') // Restrict to admins
+    async getMetrics() {
+        return requestMetrics;
+    }
+}
+```
+
+### Enable Query Logging
+```typescript
+// ormconfig.js
+logging: ['query', 'error'],
+maxQueryExecutionTime: 1000, // Warn on queries >1s
+```
+
+### Add Request Timing Middleware
+```typescript
+// src/middlewares/TimingMiddleware.ts
+export function timingMiddleware(req: Request, res: Response, next: NextFunction) {
+    const start = performance.now();
+    
+    res.on('finish', () => {
+        const duration = performance.now() - start;
+        if (duration > 1000) {
+            consola.warn(`Slow request: ${req.method} ${req.path} took ${duration}ms`);
+        }
+    });
+    
+    next();
+}
+```
+
+---
+
+## 📝 Performance Testing Commands
+
+```bash
+# Run baseline benchmark
+bun run benchmark > baseline.txt
+
+# After implementing changes, compare
+bun run benchmark > optimized.txt
+diff baseline.txt optimized.txt
+
+# Load testing with artillery (if added)
+artillery quick --count 100 --num 10 http://localhost:4010/api/runners
+
+# Database query profiling (PostgreSQL)
+EXPLAIN ANALYZE SELECT * FROM scan WHERE runner_id = 1;
+
+# Check database indexes
+SELECT * FROM pg_indexes WHERE tablename = 'scan';
+
+# Monitor NATS cache hit rate
+# (Add custom logging in NATS KV functions)
+```
+
+---
+
+## 🎓 Key Principles
+
+1. **Measure first**: Always benchmark before and after changes
+2. **Start with indexes**: Biggest impact, lowest risk
+3. **Cache strategically**: Stats endpoints benefit most
+4. **Lazy load by default**: Only eager load when absolutely needed
+5. **Monitor in production**: Use APM tools (New Relic, DataDog, etc.)
+
+---
+
+## 📚 Additional Resources
+
+- [TypeORM Performance Tips](https://typeorm.io/performance)
+- [PostgreSQL Index Best Practices](https://www.postgresql.org/docs/current/indexes.html)
+- [Bun Performance Benchmarks](https://bun.sh/docs/runtime/performance)
+- [NATS JetStream KV Guide](https://docs.nats.io/nats-concepts/jetstream/key-value-store)
+
+---
+
+**Last Updated**: 2026-02-20  
+**Status**: Ready for review and prioritization

README.md

@@ -2,60 +2,140 @@
 
 Backend Server
 
-## Dev Setup 🛠
+## Prerequisites
 
-### Local w/ sqlite
-
-1. Create a .env file in the project root containing:
-   ```
-    APP_PORT=4010
-    DB_TYPE=sqlite
-    DB_HOST=bla
-    DB_PORT=bla
-    DB_USER=bla
-    DB_PASSWORD=bla
-    DB_NAME=./test.sqlite
-   ```
-2. Install Dependencies
-   ```bash
-   yarn
-   ```
-3. Start the server
-   ```bash
-   yarn dev
-   ```
-
-### Generate Docs
-```
-yarn docs
-```
-
-### Docker w/ postgres 🐳
+This project uses **Bun** as the runtime and package manager. Install Bun first:
 
 ```bash
-docker-compose up --build
+# macOS/Linux
+curl -fsSL https://bun.sh/install | bash
+
+# Windows
+powershell -c "irm bun.sh/install.ps1 | iex"
 ```
 
+Or visit [bun.sh](https://bun.sh) for other installation methods.
+
+## Quickstart 🐳
+> Use this to run the backend with a PostgreSQL db in Docker
+
+1. Clone the repo or copy the docker-compose
+2. Run in the folder that contains the docker-compose file: `docker-compose up -d`
+3. Visit http://127.0.0.1:4010/api/docs to check if the server is running
+4. You can now use the default admin user (`demo:demo`)
+
+## Dev Setup 🛠
+> Local dev setup utilizing SQLite3 as the database and NATS for caching.
+
+1. Rename the `.env.example` file to `.env` (you can adjust app port and other settings if needed)
+2. Start NATS (required for KV cache):
+```bash
+docker-compose up -d nats
+```
+3. Install dependencies:
+```bash
+bun install
+```
+4. Start the server:
+```bash
+bun run dev
+```
+
+**Note**: Bun cannot run TypeScript source files directly due to circular TypeORM dependencies. The `dev` script automatically builds and runs the compiled output. For hot-reload during development, you may need to rebuild manually after code changes.
+
+### Run Tests
+```bash
+# Run tests once (server has to be running)
+bun test
+
+# Run test in watch mode (reruns on change)
+bun run test:watch
+
+# Run test in CI mode (automatically starts the dev server)
+bun run test:ci
+```
+
+### Run Benchmarks
+```bash
+# Start the server first
+bun run dev
+
+# In another terminal:
+bun run benchmark
+```
+
+### Generate Docs
+```bash
+bun run docs
+```
+
+### Other Commands
+```bash
+# Build for production
+bun run build
+
+# Start production server
+bun start
+
+# Seed database with test data
+bun run seed
+
+# Export OpenAPI spec
+bun run openapi:export
+
+# Generate license report
+bun run licenses:export
+
+# Generate changelog
+bun run changelog:export
+```
+
+## ENV Vars
+> You can provide them via .env file or docker env vars.
+> You can use the `test:ci:generate_env` package script to generate an example env (uses placeholder data for test server and ignores the errors).
+
+| Name                      | Type               | Default                    | Description                                                                                                      |
+| ------------------------- | ------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| APP_PORT                  | Number             | 4010                       | The port the backend server listens on. Is optional.                                                            |
+| DB_TYPE                   | String             | N/A                        | The type of the db you want to use. Supported by TypeORM. Possible: `sqlite`, `mysql`, `postgresql`              |
+| DB_HOST                   | String             | N/A                        | The db's host IP address/FQDN or file path for sqlite                                                           |
+| DB_PORT                   | String             | N/A                        | The db's port                                                                                                    |
+| DB_USER                   | String             | N/A                        | The user for accessing the db                                                                                    |
+| DB_PASSWORD               | String             | N/A                        | The user's password for accessing the db                                                                         |
+| DB_NAME                   | String             | N/A                        | The db's name                                                                                                    |
+| NODE_ENV                  | String             | dev                        | The app's env - influences debug info. When set to "test", mailing errors get ignored.                          |
+| POSTALCODE_COUNTRYCODE    | String/CountryCode | N/A                        | The country code used to validate address postal codes                                                           |
+| PHONE_COUNTRYCODE         | String/CountryCode | null (international)       | The country code used to validate phone numbers                                                                  |
+| SEED_TEST_DATA            | Boolean            | false                      | If you want the app to seed example data, set this to true                                                       |
+| STATION_TOKEN_SECRET      | String             | N/A                        | Secret key for HMAC-SHA256 station token generation (min 32 chars). **Required.**                               |
+| NATS_URL                  | String(URL)        | nats://localhost:4222      | NATS server connection URL for KV cache                                                                          |
+| NATS_PREWARM              | Boolean            | false                      | Preload all runner state into NATS cache at startup (eliminates DB reads on first scan)                         |
+| MAILER_URL                | String(URL)        | N/A                        | The mailer's base URL (no trailing slash)                                                                       |
+| MAILER_KEY                | String             | N/A                        | The mailer's API key                                                                                             |
+| SELFSERVICE_URL           | String(URL)        | N/A                        | The link to selfservice (no trailing slash)                                                                      |
+| IMPRINT_URL               | String(URL)        | /imprint                   | The link to an imprint page for the system (defaults to the frontend's imprint)                                 |
+| PRIVACY_URL               | String(URL)        | /privacy                   | The link to a privacy page for the system (defaults to the frontend's privacy page)                             |
+
+
 ## Recommended Editor
 
 [Visual Studio Code](https://code.visualstudio.com/)
 
 ### Recommended Extensions
 
-- will be automatically recommended via ./vscode/extensions.json
+* will be automatically recommended via ./vscode/extensions.json
 
-## Branches
-- main: Protected "release" branch
-- dev: Current dev branch for merging the different features - only push for merges or minor changes!
-- feature/xyz: Feature branches - `feature/issueid-title`
-- bugfix/xyz: Branches for bugfixes - `bugfix/issueid-title` (no id for readme changes needed)
-
-
-## File Structure
-
-- src/models/\* - database models (typeorm entities)
-- src/controllers/\* - routing-controllers
-- src/loaders/\* - loaders for the different init steps of the api server
-- src/routes/\* - express routes for everything we don't do via routing-controllers (shouldn't be much)
-- src/middlewares/\* - express middlewares (mainly auth r/n)
-- src/errors/* - our custom (http) errors
+## Staging
+### Branches & Tags
+* vX.Y.Z: Release tags created from the main branch
+   * The version numbers follow the semver standard
+   * A new release tag automaticly triggers the release ci pipeline
+* main: Protected "release" branch
+   * The latest tag of the docker image get's build from this
+* dev: Current dev branch for merging the different feature branches and bugfixes
+   * New releases get created as tags from this   
+   * The dev tag of the docker image get's build from this
+   * Only push minor changes to this branch!
+   * To merge a feature branch into this please create a pull request
+* feature/xyz: Feature branches - naming scheme: `feature/issueid-title`
+* bugfix/xyz: Branches for bugfixes - naming scheme:`bugfix/issueid-title`

bunfig.toml

@@ -0,0 +1,6 @@
+# Bun configuration
+# See: https://bun.sh/docs/runtime/bunfig
+
+[runtime]
+# Enable Node.js compatibility mode
+bun = true

docker-compose.yml

@@ -1,23 +1,46 @@
-version: "3"
 services:
-  backend_server:
-    build: .
+  nats:
+    image: mirror.gcr.io/library/nats:alpine
+    command: ["--jetstream", "--store_dir", "/data"]
     ports:
-      - 4010:4010
-    environment:
-      APP_PORT: 4010
-      DB_TYPE: postgres
-      DB_HOST: backend_db
-      DB_PORT: 5432 
-      DB_USER: lfk
-      DB_PASSWORD: changeme
-      DB_NAME: lfk
-      NODE_ENV: production
-  backend_db:
-    image: postgres:11-alpine
-    environment:
-      POSTGRES_DB: lfk
-      POSTGRES_PASSWORD: changeme
-      POSTGRES_USER: lfk
-    ports:
-      - 5432:5432
+      - "4222:4222"
+      - "8222:8222"
+    volumes:
+      - nats_data:/data
+
+  # backend_server:
+  #   build: .
+  #   ports:
+  #     - 4010:4010
+  #   environment:
+  #     APP_PORT: 4010
+  #     DB_TYPE: sqlite
+  #     DB_HOST: bla
+  #     DB_PORT: bla
+  #     DB_USER: bla
+  #     DB_PASSWORD: bla
+  #     DB_NAME: ./db.sqlite
+  #     NODE_ENV: production
+  #     POSTALCODE_COUNTRYCODE: DE
+  #     SEED_TEST_DATA: "true"
+  #     MAILER_URL: https://dev.lauf-fuer-kaya.de/mailer
+  #     MAILER_KEY: asdasd
+      # APP_PORT: 4010
+      # DB_TYPE: postgres
+      # DB_HOST: backend_db
+      # DB_PORT: 5432
+      # DB_USER: lfk
+      # DB_PASSWORD: changeme
+      # DB_NAME: lfk
+      # NODE_ENV: production
+  # backend_db:
+  #   image: postgres:11-alpine
+  #   environment:
+  #     POSTGRES_DB: lfk
+  #     POSTGRES_PASSWORD: changeme
+  #     POSTGRES_USER: lfk
+  #   ports:
+  #     - 5432:5432
+
+volumes:
+  nats_data:

jest.config.js

@@ -0,0 +1,4 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+};

ormconfig.js

@@ -1,12 +1,11 @@
-import { config } from 'dotenv-safe';
-config();
-
-export default {
+module.exports = {
 	type: process.env.DB_TYPE,
 	host: process.env.DB_HOST,
 	port: process.env.DB_PORT,
 	username: process.env.DB_USER,
 	password: process.env.DB_PASSWORD,
 	database: process.env.DB_NAME,
-	entities: ["src/models/entities/*.ts"]
+	// Run directly from TypeScript source (Bun workflow)
+	entities: ["src/models/entities/**/*.ts"],
+	seeds: ["src/seeds/**/*.ts"]
 };

package.json

@@ -1,6 +1,6 @@
 {
-  "name": "@lfk/backend",
-  "version": "1.0.0",
+  "name": "@odit/lfk-backend",
+  "version": "1.8.1",
   "main": "src/app.ts",
   "repository": "https://git.odit.services/lfk/backend",
   "author": {
@@ -22,46 +22,84 @@
   ],
   "license": "CC-BY-NC-SA-4.0",
   "dependencies": {
-    "argon2": "^0.27.0",
-    "body-parser": "^1.19.0",
-    "class-transformer": "^0.3.1",
-    "class-validator": "^0.12.2",
-    "class-validator-jsonschema": "^2.0.3",
-    "consola": "^2.15.0",
-    "cors": "^2.8.5",
-    "express": "^4.17.1",
-    "helmet": "^4.2.0",
-    "jsonwebtoken": "^8.5.1",
-    "multer": "^1.4.2",
-    "mysql": "^2.18.1",
-    "pg": "^8.5.1",
-    "reflect-metadata": "^0.1.13",
-    "routing-controllers": "^0.9.0-alpha.6",
-    "routing-controllers-openapi": "^2.1.0",
-    "swagger-ui-express": "^4.1.5",
-    "typeorm": "^0.2.29",
-    "typeorm-routing-controllers-extensions": "^0.2.0",
-    "uuid": "^8.3.1"
+    "@odit/class-validator-jsonschema": "2.1.1",
+    "axios": "0.21.1",
+    "body-parser": "1.19.0",
+    "check-password-strength": "2.0.2",
+    "class-transformer": "0.3.1",
+    "class-validator": "0.13.0",
+    "consola": "2.15.0",
+    "cookie": "0.4.1",
+    "cookie-parser": "1.4.5",
+    "cors": "2.8.5",
+    "csvtojson": "2.0.10",
+    "express": "4.17.1",
+    "jsonwebtoken": "8.5.1",
+    "libphonenumber-js": "1.9.9",
+    "mysql": "2.18.1",
+    "nats": "^2.29.3",
+    "pg": "8.5.1",
+    "reflect-metadata": "0.1.13",
+    "routing-controllers": "0.9.0-alpha.6",
+    "routing-controllers-openapi": "2.2.0",
+    "sqlite3": "5.1.7",
+    "typeorm": "0.2.30",
+    "typeorm-routing-controllers-extensions": "0.2.0",
+    "typeorm-seeding": "1.6.1",
+    "validator": "13.5.2"
   },
   "devDependencies": {
-    "@types/cors": "^2.8.8",
-    "@types/dotenv-safe": "^8.1.1",
-    "@types/express": "^4.17.9",
-    "@types/jsonwebtoken": "^8.5.0",
-    "@types/multer": "^1.4.4",
-    "@types/node": "^14.14.9",
-    "@types/swagger-ui-express": "^4.1.2",
-    "@types/uuid": "^8.3.0",
-    "dotenv-safe": "^8.2.0",
-    "nodemon": "^2.0.6",
-    "sqlite3": "^5.0.0",
-    "ts-node": "^9.0.0",
-    "typedoc": "^0.19.2",
-    "typescript": "^4.1.2"
+    "@faker-js/faker": "7.6.0",
+    "@odit/license-exporter": "0.0.9",
+    "@types/cors": "2.8.19",
+    "@types/csvtojson": "1.1.5",
+    "@types/express": "5.0.6",
+    "@types/jest": "30.0.0",
+    "@types/jsonwebtoken": "9.0.10",
+    "@types/node": "25.3.0",
+    "auto-changelog": "2.4.0",
+    "cp-cli": "2.0.0",
+    "jest": "26.6.3",
+    "release-it": "14.2.2",
+    "rimraf": "^6.1.3",
+    "start-server-and-test": "1.11.7",
+    "ts-jest": "26.5.0",
+    "typedoc": "0.20.19",
+    "typescript": "5.9.3"
   },
   "scripts": {
-    "dev": "nodemon src/app.ts",
-    "build": "tsc",
-    "docs": "typedoc --out docs src"
+    "dev": "bun --watch src/app.ts",
+    "start": "bun src/app.ts",
+    "build": "rimraf ./dist && tsc && cp-cli ./src/static ./dist/static",
+    "docs": "typedoc --out docs src",
+    "test": "jest",
+    "test:watch": "jest --watchAll",
+    "test:ci:generate_env": "bun scripts/create_testenv.ts",
+    "test:ci:run": "start-server-and-test dev http://localhost:4010/api/docs/openapi.json test",
+    "test:ci": "bun run test:ci:generate_env && bun run test:ci:run",
+    "benchmark": "bun scripts/benchmark_scan_intake.ts",
+    "seed": "bun ./node_modules/typeorm/cli.js schema:sync && bun ./node_modules/typeorm-seeding/dist/cli.js seed",
+    "openapi:export": "bun scripts/openapi_export.ts",
+    "licenses:export": "license-exporter --markdown",
+    "changelog:export": "auto-changelog --commit-limit false -p -u --hide-credit",
+    "release": "release-it --only-version"
+  },
+  "release-it": {
+    "git": {
+      "commit": true,
+      "requireCleanWorkingDir": false,
+      "commitMessage": "chore(release): ${version}",
+      "requireBranch": "dev",
+      "push": true,
+      "tag": true,
+      "tagName": "${version}",
+      "tagAnnotation": "${version}"
+    },
+    "npm": {
+      "publish": false
+    },
+    "hooks": {
+      "after:bump": "bun run changelog:export && bun run licenses:export && git add CHANGELOG.md && git add licenses.md"
+    }
   }
-}
+}

pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+onlyBuiltDependencies:
+  - sqlite3

scripts/benchmark_scan_intake.ts

@@ -0,0 +1,367 @@
+/**
+ * Scan Intake Benchmark Script
+ *
+ * Measures TrackScan creation performance before and after each optimisation phase.
+ * Run against a live dev server: bun run dev
+ *
+ * Usage:
+ *   bun run benchmark
+ *   bun scripts/benchmark_scan_intake.ts --base http://localhost:4010
+ *
+ * What it measures:
+ *   1. Single sequential scans      — baseline latency per request (p50/p95/p99/max)
+ *   2. Parallel scans (10 stations) — simulates 10 concurrent stations each submitting
+ *                                     one scan at a time at the expected event rate
+ *                                     (~1 scan/3s per station = ~3.3 scans/s total)
+ *
+ * The script self-provisions all required data (org, runners, cards, track, stations)
+ * and cleans up after itself. It authenticates via the station token, matching the
+ * real production auth path exactly.
+ *
+ * Output is printed to stdout in a copy-paste-friendly table format so results can
+ * be compared across phases.
+ */
+
+import axios, { AxiosInstance } from 'axios';
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const BASE = (() => {
+    const idx = process.argv.indexOf('--base');
+    return idx !== -1 ? process.argv[idx + 1] : 'http://localhost:4010';
+})();
+
+const API = `${BASE}/api`;
+
+// Number of simulated scan stations
+const STATION_COUNT = 10;
+
+// Sequential benchmark: total number of scans to send, one at a time
+const SEQUENTIAL_SCAN_COUNT = 50;
+
+// Parallel benchmark: number of rounds. Each round fires STATION_COUNT scans concurrently.
+// 20 rounds × 10 stations = 200 total scans, matching the expected event throughput pattern.
+const PARALLEL_ROUNDS = 20;
+
+// Minimum lap time on the test track (seconds). Set low so most scans are valid.
+// The benchmark measures submission speed, not business logic.
+const TRACK_MINIMUM_LAP_TIME = 1;
+
+// Track distance (metres)
+const TRACK_DISTANCE = 400;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface StationHandle {
+    id: number;
+    key: string;         // cleartext token, used as Bearer token
+    cardCode: number;    // EAN-13 barcode of the card assigned to this station's runner
+    axiosInstance: AxiosInstance;
+}
+
+interface Percentiles {
+    p50: number;
+    p95: number;
+    p99: number;
+    max: number;
+    min: number;
+    mean: number;
+}
+
+interface BenchmarkResult {
+    label: string;
+    totalScans: number;
+    totalTimeMs: number;
+    scansPerSecond: number;
+    latencies: Percentiles;
+    errors: number;
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+
+const adminClient = axios.create({
+    baseURL: API,
+    validateStatus: () => true,
+});
+
+async function adminLogin(): Promise<string> {
+    const res = await adminClient.post('/auth/login', { username: 'demo', password: 'demo' });
+    if (res.status !== 200) {
+        throw new Error(`Login failed: ${res.status} ${JSON.stringify(res.data)}`);
+    }
+    return res.data.access_token;
+}
+
+function authedClient(token: string): AxiosInstance {
+    return axios.create({
+        baseURL: API,
+        validateStatus: () => true,
+        headers: { authorization: `Bearer ${token}` },
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Data provisioning
+// ---------------------------------------------------------------------------
+
+async function provision(adminToken: string): Promise<{
+    stations: StationHandle[];
+    trackId: number;
+    orgId: number;
+    cleanup: () => Promise<void>;
+}> {
+    const client = authedClient(adminToken);
+    const createdIds: { type: string; id: number }[] = [];
+
+    const create = async (path: string, body: object): Promise<any> => {
+        const res = await client.post(path, body);
+        if (res.status !== 200) {
+            throw new Error(`POST ${path} failed: ${res.status} ${JSON.stringify(res.data)}`);
+        }
+        return res.data;
+    };
+
+    process.stdout.write('Provisioning test data... ');
+
+    // Organisation
+    const org = await create('/organizations', { name: 'benchmark-org' });
+    createdIds.push({ type: 'organizations', id: org.id });
+
+    // Track with a low minimumLapTime so re-scans within the benchmark are mostly valid
+    const track = await create('/tracks', {
+        name: 'benchmark-track',
+        distance: TRACK_DISTANCE,
+        minimumLapTime: TRACK_MINIMUM_LAP_TIME,
+    });
+    createdIds.push({ type: 'tracks', id: track.id });
+
+    // One runner + card + station per simulated scan station
+    const stations: StationHandle[] = [];
+
+    for (let i = 0; i < STATION_COUNT; i++) {
+        const runner = await create('/runners', {
+            firstname: `Bench`,
+            lastname: `Runner${i}`,
+            group: org.id,
+        });
+        createdIds.push({ type: 'runners', id: runner.id });
+
+        const card = await create('/cards', { runner: runner.id });
+        createdIds.push({ type: 'cards', id: card.id });
+
+        const station = await create('/stations', {
+            track: track.id,
+            description: `bench-station-${i}`,
+        });
+        createdIds.push({ type: 'stations', id: station.id });
+
+        stations.push({
+            id: station.id,
+            key: station.key,
+            cardCode: card.id,   // the test spec uses card.id directly as the barcode value
+            axiosInstance: axios.create({
+                baseURL: API,
+                validateStatus: () => true,
+                headers: { authorization: `Bearer ${station.key}` },
+            }),
+        });
+    }
+
+    console.log(`done. (${STATION_COUNT} stations, ${STATION_COUNT} runners, ${STATION_COUNT} cards)`);
+
+    const cleanup = async () => {
+        process.stdout.write('Cleaning up test data... ');
+        // Delete in reverse-dependency order
+        for (const item of [...createdIds].reverse()) {
+            await client.delete(`/${item.type}/${item.id}?force=true`);
+        }
+        console.log('done.');
+    };
+
+    return { stations, trackId: track.id, orgId: org.id, cleanup };
+}
+
+// ---------------------------------------------------------------------------
+// Single scan submission (returns latency in ms)
+// ---------------------------------------------------------------------------
+
+async function submitScan(station: StationHandle): Promise<{ latencyMs: number; ok: boolean }> {
+    const start = performance.now();
+    const res = await station.axiosInstance.post('/scans/trackscans', {
+        card: station.cardCode,
+        station: station.id,
+    });
+    const latencyMs = performance.now() - start;
+    const ok = res.status === 200;
+    return { latencyMs, ok };
+}
+
+// ---------------------------------------------------------------------------
+// Statistics
+// ---------------------------------------------------------------------------
+
+function percentiles(latencies: number[]): Percentiles {
+    const sorted = [...latencies].sort((a, b) => a - b);
+    const at = (pct: number) => sorted[Math.floor((pct / 100) * sorted.length)] ?? sorted[sorted.length - 1];
+    const mean = sorted.reduce((s, v) => s + v, 0) / sorted.length;
+    return {
+        p50: Math.round(at(50)),
+        p95: Math.round(at(95)),
+        p99: Math.round(at(99)),
+        max: Math.round(sorted[sorted.length - 1]),
+        min: Math.round(sorted[0]),
+        mean: Math.round(mean),
+    };
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark 1 — Sequential (single station, one scan at a time)
+// ---------------------------------------------------------------------------
+
+async function benchmarkSequential(station: StationHandle): Promise<BenchmarkResult> {
+    const latencies: number[] = [];
+    let errors = 0;
+
+    process.stdout.write(`  Running ${SEQUENTIAL_SCAN_COUNT} sequential scans`);
+    const wallStart = performance.now();
+
+    for (let i = 0; i < SEQUENTIAL_SCAN_COUNT; i++) {
+        const { latencyMs, ok } = await submitScan(station);
+        latencies.push(latencyMs);
+        if (!ok) errors++;
+        if ((i + 1) % 10 === 0) process.stdout.write('.');
+    }
+
+    const totalTimeMs = performance.now() - wallStart;
+    console.log(' done.');
+
+    return {
+        label: 'Sequential (1 station)',
+        totalScans: SEQUENTIAL_SCAN_COUNT,
+        totalTimeMs,
+        scansPerSecond: (SEQUENTIAL_SCAN_COUNT / totalTimeMs) * 1000,
+        latencies: percentiles(latencies),
+        errors,
+    };
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark 2 — Parallel (10 stations, concurrent rounds)
+//
+// Models the real event scenario: every ~3 seconds each station submits one scan.
+// We don't actually sleep between rounds — we fire each round as fast as the
+// previous one completes, which gives us the worst-case sustained throughput
+// (all stations submitting at maximum rate simultaneously).
+// ---------------------------------------------------------------------------
+
+async function benchmarkParallel(stations: StationHandle[]): Promise<BenchmarkResult> {
+    const latencies: number[] = [];
+    let errors = 0;
+
+    process.stdout.write(`  Running ${PARALLEL_ROUNDS} rounds × ${STATION_COUNT} concurrent stations`);
+    const wallStart = performance.now();
+
+    for (let round = 0; round < PARALLEL_ROUNDS; round++) {
+        const results = await Promise.all(stations.map(s => submitScan(s)));
+        for (const { latencyMs, ok } of results) {
+            latencies.push(latencyMs);
+            if (!ok) errors++;
+        }
+        if ((round + 1) % 4 === 0) process.stdout.write('.');
+    }
+
+    const totalTimeMs = performance.now() - wallStart;
+    const totalScans = PARALLEL_ROUNDS * STATION_COUNT;
+    console.log(' done.');
+
+    return {
+        label: `Parallel (${STATION_COUNT} stations concurrent)`,
+        totalScans,
+        totalTimeMs,
+        scansPerSecond: (totalScans / totalTimeMs) * 1000,
+        latencies: percentiles(latencies),
+        errors,
+    };
+}
+
+// ---------------------------------------------------------------------------
+// Output formatting
+// ---------------------------------------------------------------------------
+
+function printResult(result: BenchmarkResult) {
+    const { label, totalScans, totalTimeMs, scansPerSecond, latencies, errors } = result;
+    console.log(`\n  ${label}`);
+    console.log(`  ${'─'.repeat(52)}`);
+    console.log(`  Total scans   : ${totalScans}`);
+    console.log(`  Total time    : ${totalTimeMs.toFixed(0)} ms`);
+    console.log(`  Throughput    : ${scansPerSecond.toFixed(2)} scans/sec`);
+    console.log(`  Latency min   : ${latencies.min} ms`);
+    console.log(`  Latency mean  : ${latencies.mean} ms`);
+    console.log(`  Latency p50   : ${latencies.p50} ms`);
+    console.log(`  Latency p95   : ${latencies.p95} ms`);
+    console.log(`  Latency p99   : ${latencies.p99} ms`);
+    console.log(`  Latency max   : ${latencies.max} ms`);
+    console.log(`  Errors        : ${errors}`);
+}
+
+function printSummary(results: BenchmarkResult[]) {
+    const now = new Date().toISOString();
+    console.log('\n');
+    console.log('═'.repeat(60));
+    console.log(`  SCAN INTAKE BENCHMARK RESULTS — ${now}`);
+    console.log(`  Server: ${BASE}`);
+    console.log('═'.repeat(60));
+    for (const r of results) {
+        printResult(r);
+    }
+    console.log('\n' + '═'.repeat(60));
+    console.log('  Copy the block above to compare across phases.');
+    console.log('═'.repeat(60) + '\n');
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+async function main() {
+    console.log(`\nScan Intake Benchmark — target: ${BASE}\n`);
+
+    let adminToken: string;
+    try {
+        adminToken = await adminLogin();
+    } catch (err) {
+        console.error(`Could not authenticate. Is the server running at ${BASE}?\n`, err.message);
+        process.exit(1);
+    }
+
+    const { stations, cleanup } = await provision(adminToken);
+
+    const results: BenchmarkResult[] = [];
+
+    try {
+        console.log('\nBenchmark 1 — Sequential');
+        results.push(await benchmarkSequential(stations[0]));
+
+        // Brief pause between benchmarks so the sequential scans don't skew
+        // the parallel benchmark's first-scan latency (minimumLapTime window)
+        await new Promise(r => setTimeout(r, (TRACK_MINIMUM_LAP_TIME + 1) * 1000));
+
+        console.log('\nBenchmark 2 — Parallel');
+        results.push(await benchmarkParallel(stations));
+    } finally {
+        await cleanup();
+    }
+
+    printSummary(results);
+}
+
+main().catch(err => {
+    console.error('Benchmark failed:', err);
+    process.exit(1);
+});

scripts/create_testenv.ts

@@ -0,0 +1,24 @@
+import consola from "consola";
+import fs from "fs";
+
+
+const env = `
+APP_PORT=4010
+DB_TYPE=sqlite
+DB_HOST=bla
+DB_PORT=bla
+DB_USER=bla
+DB_PASSWORD=bla
+DB_NAME=./test.sqlite
+NODE_ENV=test
+POSTALCODE_COUNTRYCODE=DE
+SEED_TEST_DATA=true
+MAILER_URL=https://dev.lauf-fuer-kaya.de/mailer
+MAILER_KEY=asdasd`;
+
+try {
+    fs.writeFileSync("./.env", env, { encoding: "utf-8" });
+    consola.success("Exported ci env to .env");
+} catch (error) {
+    consola.error("Couldn't export the ci env");
+}

scripts/openapi_export.ts

@@ -0,0 +1,34 @@
+import { validationMetadatasToSchemas } from '@odit/class-validator-jsonschema';
+import consola from "consola";
+import fs from "fs";
+import "reflect-metadata";
+import { createExpressServer, getMetadataArgsStorage } from "routing-controllers";
+import { generateSpec } from '../src/apispec';
+import { config } from '../src/config';
+import authchecker from "../src/middlewares/authchecker";
+import { ErrorHandler } from '../src/middlewares/ErrorHandler';
+
+const CONTROLLERS_FILE_EXTENSION = process.env.NODE_ENV === 'production' ? 'js' : 'ts';
+createExpressServer({
+    authorizationChecker: authchecker,
+    middlewares: [ErrorHandler],
+    development: config.development,
+    cors: true,
+    routePrefix: "/api",
+    controllers: [`${__dirname}/../src/controllers/*.${CONTROLLERS_FILE_EXTENSION}`],
+});
+
+const storage = getMetadataArgsStorage();
+const schemas = validationMetadatasToSchemas({
+    refPointerPrefix: "#/components/schemas/",
+});
+
+//Spec creation based on the previously created schemas
+const spec = generateSpec(storage, schemas);
+
+try {
+    fs.writeFileSync("./openapi.json", JSON.stringify(spec), { encoding: "utf-8" });
+    consola.success("Exported openapi spec to openapi.json");
+} catch (error) {
+    consola.error("Couldn't export the openapi spec");
+}

src/apispec.ts

@@ -0,0 +1,51 @@
+import { MetadataArgsStorage } from 'routing-controllers';
+import { routingControllersToSpec } from 'routing-controllers-openapi';
+import { config } from './config';
+
+/**
+ * This function generates a the openapi spec from route metadata and type schemas.
+ * @param storage MetadataArgsStorage object generated by routing-controllers.
+ * @param schemas MetadataArgsStorage object generated by class-validator-jsonschema.
+ */
+export function generateSpec(storage: MetadataArgsStorage, schemas) {
+    return routingControllersToSpec(
+        storage,
+        {
+            routePrefix: "/api"
+        },
+        {
+            components: {
+                schemas,
+                "securitySchemes": {
+                    "AuthToken": {
+                        "type": "http",
+                        "scheme": "bearer",
+                        "bearerFormat": "JWT",
+                        description: "A JWT based access token. Use /api/auth/login or /api/auth/refresh to get one."
+                    },
+                    "RefreshTokenCookie": {
+                        "type": "apiKey",
+                        "in": "cookie",
+                        "name": "lfk_backend__refresh_token",
+                        description: "A cookie containing a JWT based refreh token. Attention: Doesn't work in swagger-ui. Use /api/auth/login or /api/auth/refresh to get one."
+                    },
+                    "StatsApiToken": {
+                        "type": "http",
+                        "scheme": "bearer",
+                        description: "Api token that can be obtained by creating a new stats client (post to /api/statsclients). Only valid for obtaining stats."
+                    },
+                    "StationApiToken": {
+                        "type": "http",
+                        "scheme": "bearer",
+                        description: "Api token that can be obtained by creating a new scan station (post to /api/stations). Only valid for creating scans."
+                    }
+                }
+            },
+            info: {
+                description: `The the backend API for the LfK! runner system. <br>[Imprint](${config.imprint_url}) & [Privacy](${config.privacy_url})`,
+                title: "LfK! Backend API",
+                version: config.version
+            },
+        }
+    );
+}

src/app.ts

@@ -1,29 +1,79 @@
 import consola from "consola";
-import * as dotenvSafe from "dotenv-safe";
 import "reflect-metadata";
 import { createExpressServer } from "routing-controllers";
-import authchecker from "./authchecker";
+import { config, e as errors } from './config';
 import loaders from "./loaders/index";
+import authchecker from "./middlewares/authchecker";
 import { ErrorHandler } from './middlewares/ErrorHandler';
+import UserChecker from './middlewares/UserChecker';
 
-dotenvSafe.config();
-const PORT = process.env.APP_PORT || 4010;
+// Import all controllers directly to avoid Bun + routing-controllers glob/require issues
+import { AuthController } from './controllers/AuthController';
+import { DonationController } from './controllers/DonationController';
+import { DonorController } from './controllers/DonorController';
+import { GroupContactController } from './controllers/GroupContactController';
+import { ImportController } from './controllers/ImportController';
+import { MeController } from './controllers/MeController';
+import { PermissionController } from './controllers/PermissionController';
+import { RunnerCardController } from './controllers/RunnerCardController';
+import { RunnerController } from './controllers/RunnerController';
+import { RunnerOrganizationController } from './controllers/RunnerOrganizationController';
+import { RunnerSelfServiceController } from './controllers/RunnerSelfServiceController';
+import { RunnerTeamController } from './controllers/RunnerTeamController';
+import { ScanController } from './controllers/ScanController';
+import { ScanStationController } from './controllers/ScanStationController';
+import { StatsClientController } from './controllers/StatsClientController';
+import { StatsController } from './controllers/StatsController';
+import { StatusController } from './controllers/StatusController';
+import { TrackController } from './controllers/TrackController';
+import { UserController } from './controllers/UserController';
+import { UserGroupController } from './controllers/UserGroupController';
 
 const app = createExpressServer({
   authorizationChecker: authchecker,
+  currentUserChecker: UserChecker,
   middlewares: [ErrorHandler],
-  development: process.env.NODE_ENV === "production",
+  development: config.development,
   cors: true,
   routePrefix: "/api",
-  controllers: [__dirname + "/controllers/*.ts"],
+  controllers: [
+    AuthController,
+    DonationController,
+    DonorController,
+    GroupContactController,
+    ImportController,
+    MeController,
+    PermissionController,
+    RunnerCardController,
+    RunnerController,
+    RunnerOrganizationController,
+    RunnerSelfServiceController,
+    RunnerTeamController,
+    ScanController,
+    ScanStationController,
+    StatsClientController,
+    StatsController,
+    StatusController,
+    TrackController,
+    UserController,
+    UserGroupController,
+  ],
 });
 
 async function main() {
   await loaders(app);
-  app.listen(PORT, () => {
+  if (config.testing) {
+    consola.info("🛠[config]: Discovered testing env. Mailing errors will get ignored!")
+  }
+  app.listen(config.internal_port, () => {
     consola.success(
-      `⚡️[server]: Server is running at http://localhost:${PORT}`
+      `⚡️[server]: Server is running at http://localhost:${config.internal_port}`
     );
   });
 }
-main();
+if (errors === 0) {
+  main();
+} else {
+  consola.error("error");
+  // something's wrong
+}

src/authchecker.ts

@@ -1,51 +0,0 @@
-import * as jwt from "jsonwebtoken";
-import { Action } from "routing-controllers";
-import { getConnectionManager } from 'typeorm';
-import { IllegalJWTError, NoPermissionError, UserNonexistantOrRefreshtokenInvalidError } from './errors/AuthError';
-import { User } from './models/entities/User';
-// -----------
-const authchecker = async (action: Action, permissions: string | string[]) => {
-    let required_permissions = undefined
-    if (typeof permissions === "string") {
-        required_permissions = [permissions]
-    } else {
-        required_permissions = permissions
-    }
-    // const token = action.request.headers["authorization"];
-    const provided_token = action.request.query["auth"];
-    let jwtPayload = undefined
-    try {
-        jwtPayload = <any>jwt.verify(provided_token, "securekey");
-    } catch (error) {
-        console.log(error);
-        throw new IllegalJWTError()
-    }
-    const count = await getConnectionManager().get().getRepository(User).count({ id: jwtPayload["userdetails"]["id"], refreshTokenCount: jwtPayload["userdetails"]["refreshTokenCount"] })
-    if (count !== 1) {
-        throw new UserNonexistantOrRefreshtokenInvalidError()
-    }
-    if (jwtPayload.permissions) {
-        action.response.local = {}
-        action.response.local.jwtPayload = jwtPayload.permissions
-        required_permissions.forEach(r => {
-            const permission_key = r.split(":")[0]
-            const actual_accesslevel_for_permission = jwtPayload.permissions[permission_key]
-            const permission_access_level = r.split(":")[1]
-            if (actual_accesslevel_for_permission.includes(permission_access_level)) {
-                return true;
-            } else {
-                throw new NoPermissionError()
-            }
-        });
-    } else {
-        throw new NoPermissionError()
-    }
-    // 
-    try {
-        jwt.verify(provided_token, process.env.JWT_SECRET || "secretjwtsecret");
-        return true
-    } catch (error) {
-        return false
-    }
-}
-export default authchecker

src/config.ts

@@ -0,0 +1,59 @@
+import consola from 'consola';
+import { CountryCode } from 'libphonenumber-js';
+import ValidatorJS from 'validator';
+
+export const config = {
+    internal_port: parseInt(process.env.APP_PORT) || 4010,
+    development: process.env.NODE_ENV === "production",
+    testing: process.env.NODE_ENV === "test",
+    jwt_secret: process.env.JWT_SECRET || "secretjwtsecret",
+    station_token_secret: process.env.STATION_TOKEN_SECRET || "",
+    nats_url: process.env.NATS_URL || "nats://localhost:4222",
+    nats_prewarm: process.env.NATS_PREWARM === "true",
+    phone_validation_countrycode: getPhoneCodeLocale(),
+    postalcode_validation_countrycode: getPostalCodeLocale(),
+    version: process.env.VERSION || require('../package.json').version,
+    seedTestData: getDataSeeding(),
+    app_url: process.env.APP_URL || "http://localhost:8080",
+    privacy_url: process.env.PRIVACY_URL || "/privacy",
+    imprint_url: process.env.IMPRINT_URL || "/imprint",
+    mailer_url: process.env.MAILER_URL || "",
+    mailer_key: process.env.MAILER_KEY || ""
+}
+let errors = 0
+if (typeof config.internal_port !== "number") {
+    consola.error("Error: APP_PORT is not a number")
+    errors++
+}
+if (typeof config.development !== "boolean") {
+    consola.error("Error: NODE_ENV is not a boolean")
+    errors++
+}
+if (config.mailer_url == "" || config.mailer_key == "") {
+    consola.error("Error: invalid mailer config")
+    errors++;
+}
+if (config.station_token_secret.length < 32) {
+    consola.error("Error: STATION_TOKEN_SECRET must be set and at least 32 characters long")
+    errors++;
+}
+function getPhoneCodeLocale(): CountryCode {
+    return (process.env.PHONE_COUNTRYCODE as CountryCode);
+}
+function getPostalCodeLocale(): any {
+    try {
+        const stringArray: String[] = ValidatorJS.isPostalCodeLocales;
+        let index = stringArray.indexOf(process.env.POSTALCODE_COUNTRYCODE);
+        return ValidatorJS.isPostalCodeLocales[index];
+    } catch (error) {
+        return null;
+    }
+}
+function getDataSeeding(): Boolean {
+    try {
+        return JSON.parse(process.env.SEED_TEST_DATA);
+    } catch (error) {
+        return false;
+    }
+}
+export let e = errors

src/controllers/AuthController.ts

@@ -1,68 +1,106 @@
-import { Body, JsonController, Post } from 'routing-controllers';
-import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
-import { IllegalJWTError, InvalidCredentialsError, JwtNotProvidedError, PasswordNeededError, RefreshTokenCountInvalidError, UsernameOrEmailNeededError } from '../errors/AuthError';
-import { UserNotFoundError } from '../errors/UserErrors';
-import { CreateAuth } from '../models/actions/CreateAuth';
-import { HandleLogout } from '../models/actions/HandleLogout';
-import { RefreshAuth } from '../models/actions/RefreshAuth';
-import { Auth } from '../models/responses/ResponseAuth';
-import { Logout } from '../models/responses/ResponseLogout';
-
-@JsonController('/auth')
-export class AuthController {
-	constructor() {
-	}
-
-	@Post("/login")
-	@ResponseSchema(Auth)
-	@ResponseSchema(InvalidCredentialsError)
-	@ResponseSchema(UserNotFoundError)
-	@ResponseSchema(UsernameOrEmailNeededError)
-	@ResponseSchema(PasswordNeededError)
-	@ResponseSchema(InvalidCredentialsError)
-	@OpenAPI({ description: 'Create a new access token object' })
-	async login(@Body({ validate: true }) createAuth: CreateAuth) {
-		let auth;
-		try {
-			auth = await createAuth.toAuth();
-		} catch (error) {
-			return error;
-		}
-		return auth
-	}
-
-	@Post("/logout")
-	@ResponseSchema(Logout)
-	@ResponseSchema(InvalidCredentialsError)
-	@ResponseSchema(UserNotFoundError)
-	@ResponseSchema(UsernameOrEmailNeededError)
-	@ResponseSchema(PasswordNeededError)
-	@ResponseSchema(InvalidCredentialsError)
-	@OpenAPI({ description: 'Create a new access token object' })
-	async logout(@Body({ validate: true }) handleLogout: HandleLogout) {
-		let logout;
-		try {
-			logout = await handleLogout.logout()
-		} catch (error) {
-			return error;
-		}
-		return logout
-	}
-
-	@Post("/refresh")
-	@ResponseSchema(Auth)
-	@ResponseSchema(JwtNotProvidedError)
-	@ResponseSchema(IllegalJWTError)
-	@ResponseSchema(UserNotFoundError)
-	@ResponseSchema(RefreshTokenCountInvalidError)
-	@OpenAPI({ description: 'refresh a access token' })
-	async refresh(@Body({ validate: true }) refreshAuth: RefreshAuth) {
-		let auth;
-		try {
-			auth = await refreshAuth.toAuth();
-		} catch (error) {
-			return error;
-		}
-		return auth
-	}
-}
+import { Body, CookieParam, JsonController, Param, Post, QueryParam, Req, Res } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { IllegalJWTError, InvalidCredentialsError, JwtNotProvidedError, PasswordNeededError, RefreshTokenCountInvalidError, UsernameOrEmailNeededError } from '../errors/AuthError';
+import { MailSendingError } from '../errors/MailErrors';
+import { UserNotFoundError } from '../errors/UserErrors';
+import { Mailer } from '../mailer';
+import { CreateAuth } from '../models/actions/create/CreateAuth';
+import { CreateResetToken } from '../models/actions/create/CreateResetToken';
+import { HandleLogout } from '../models/actions/HandleLogout';
+import { RefreshAuth } from '../models/actions/RefreshAuth';
+import { ResetPassword } from '../models/actions/ResetPassword';
+import { ResponseAuth } from '../models/responses/ResponseAuth';
+import { ResponseEmpty } from '../models/responses/ResponseEmpty';
+import { Logout } from '../models/responses/ResponseLogout';
+
+@JsonController('/auth')
+export class AuthController {
+
+	@Post("/login")
+	@ResponseSchema(ResponseAuth)
+	@ResponseSchema(InvalidCredentialsError)
+	@ResponseSchema(UserNotFoundError)
+	@ResponseSchema(UsernameOrEmailNeededError)
+	@ResponseSchema(PasswordNeededError)
+	@ResponseSchema(InvalidCredentialsError)
+	@OpenAPI({ description: 'Login with your username/email and password. <br> You will receive: \n * access token (use it as a bearer token) \n * refresh token (will also be sent as a cookie)' })
+	async login(@Body({ validate: true }) createAuth: CreateAuth, @Res() response: any) {
+		let auth;
+		try {
+			auth = await createAuth.toAuth();
+			response.cookie('lfk_backend__refresh_token', auth.refresh_token, { expires: new Date(auth.refresh_token_expires_at * 1000), httpOnly: true });
+			response.cookie('lfk_backend__refresh_token_expires_at', auth.refresh_token_expires_at, { expires: new Date(auth.refresh_token_expires_at * 1000), httpOnly: true });
+			return response.send(auth)
+		} catch (error) {
+			throw error;
+		}
+	}
+
+	@Post("/logout")
+	@ResponseSchema(Logout)
+	@ResponseSchema(InvalidCredentialsError)
+	@ResponseSchema(UserNotFoundError)
+	@ResponseSchema(UsernameOrEmailNeededError)
+	@ResponseSchema(PasswordNeededError)
+	@ResponseSchema(InvalidCredentialsError)
+	@OpenAPI({ description: 'Logout using your refresh token. <br> This instantly invalidates all your access and refresh tokens.', security: [{ "RefreshTokenCookie": [] }] })
+	async logout(@Body({ validate: true }) handleLogout: HandleLogout, @CookieParam("lfk_backend__refresh_token") refresh_token: string, @Res() response: any) {
+		if (refresh_token && refresh_token.length != 0 && handleLogout.token == undefined) {
+			handleLogout.token = refresh_token;
+		}
+
+		let logout;
+		try {
+			logout = await handleLogout.logout()
+			await response.cookie('lfk_backend__refresh_token', "expired", { expires: new Date(Date.now()), httpOnly: true });
+			response.cookie('lfk_backend__refresh_token_expires_at', "expired", { expires: new Date(Date.now()), httpOnly: true });
+		} catch (error) {
+			throw error;
+		}
+		return response.send(logout)
+	}
+
+	@Post("/refresh")
+	@ResponseSchema(ResponseAuth)
+	@ResponseSchema(JwtNotProvidedError)
+	@ResponseSchema(IllegalJWTError)
+	@ResponseSchema(UserNotFoundError)
+	@ResponseSchema(RefreshTokenCountInvalidError)
+	@OpenAPI({ description: 'Refresh your access and refresh tokens using a valid refresh token. <br> You will receive: \n * access token (use it as a bearer token) \n * refresh token (will also be sent as a cookie)', security: [{ "RefreshTokenCookie": [] }] })
+	async refresh(@Body({ validate: true }) refreshAuth: RefreshAuth, @CookieParam("lfk_backend__refresh_token") refresh_token: string, @Res() response: any, @Req() req: any) {
+		if (refresh_token && refresh_token.length != 0 && refreshAuth.token == undefined) {
+			refreshAuth.token = refresh_token;
+		}
+		let auth;
+		try {
+			auth = await refreshAuth.toAuth();
+			response.cookie('lfk_backend__refresh_token', auth.refresh_token, { expires: new Date(auth.refresh_token_expires_at * 1000), httpOnly: true });
+			response.cookie('lfk_backend__refresh_token_expires_at', auth.refresh_token_expires_at, { expires: new Date(auth.refresh_token_expires_at * 1000), httpOnly: true });
+		} catch (error) {
+			throw error;
+		}
+		return response.send(auth)
+	}
+
+	@Post("/reset")
+	@ResponseSchema(ResponseEmpty, { statusCode: 200 })
+	@ResponseSchema(UserNotFoundError, { statusCode: 404 })
+	@ResponseSchema(UsernameOrEmailNeededError, { statusCode: 406 })
+	@ResponseSchema(MailSendingError, { statusCode: 500 })
+	@OpenAPI({ description: "Request a password reset token. <br> This will provide you with a reset token that you can use by posting to /api/auth/reset/{token}." })
+	async getResetToken(@Body({ validate: true }) passwordReset: CreateResetToken, @QueryParam("locale") locale: string = "en") {
+		const reset_token: string = await passwordReset.toResetToken();
+		await Mailer.sendResetMail(passwordReset.email, reset_token, locale);
+		return new ResponseEmpty();
+	}
+
+	@Post("/reset/:token")
+	@ResponseSchema(ResponseAuth)
+	@ResponseSchema(UserNotFoundError)
+	@ResponseSchema(UsernameOrEmailNeededError)
+	@OpenAPI({ description: "Reset a user's utilising a valid password reset token. <br> This will set the user's password to the one you provided in the body. <br> To get a reset token post to /api/auth/reset with your username." })
+	async resetPassword(@Param("token") token: string, @Body({ validate: true }) passwordReset: ResetPassword) {
+		passwordReset.resetToken = token;
+		return await passwordReset.resetPassword();
+	}
+}

src/controllers/DonationController.ts

@@ -0,0 +1,167 @@
+import { Authorized, Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put, QueryParam } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { Repository, getConnectionManager } from 'typeorm';
+import { DonationIdsNotMatchingError, DonationNotFoundError } from '../errors/DonationErrors';
+import { DonorNotFoundError } from '../errors/DonorErrors';
+import { RunnerNotFoundError } from '../errors/RunnerErrors';
+import { CreateAnonymousDonation } from '../models/actions/create/CreateAnonymousDonation';
+import { CreateDistanceDonation } from '../models/actions/create/CreateDistanceDonation';
+import { CreateFixedDonation } from '../models/actions/create/CreateFixedDonation';
+import { UpdateDistanceDonation } from '../models/actions/update/UpdateDistanceDonation';
+import { UpdateFixedDonation } from '../models/actions/update/UpdateFixedDonation';
+import { DistanceDonation } from '../models/entities/DistanceDonation';
+import { Donation } from '../models/entities/Donation';
+import { FixedDonation } from '../models/entities/FixedDonation';
+import { ResponseAnonymousDonation } from '../models/responses/ResponseAnonymousDonation';
+import { ResponseDistanceDonation } from '../models/responses/ResponseDistanceDonation';
+import { ResponseDonation } from '../models/responses/ResponseDonation';
+import { ResponseEmpty } from '../models/responses/ResponseEmpty';
+
+@JsonController('/donations')
+@OpenAPI({ security: [{ "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+export class DonationController {
+	private donationRepository: Repository<Donation>;
+	private distanceDonationRepository: Repository<DistanceDonation>;
+	private fixedDonationRepository: Repository<FixedDonation>;
+
+	/**
+	 * Gets the repository of this controller's model/entity.
+	 */
+	constructor() {
+		this.donationRepository = getConnectionManager().get().getRepository(Donation);
+		this.distanceDonationRepository = getConnectionManager().get().getRepository(DistanceDonation);
+		this.fixedDonationRepository = getConnectionManager().get().getRepository(FixedDonation);
+	}
+
+	@Get()
+	@Authorized("DONATION:GET")
+	@ResponseSchema(ResponseDonation, { isArray: true })
+	@ResponseSchema(ResponseDistanceDonation, { isArray: true })
+	@ResponseSchema(ResponseAnonymousDonation, { isArray: true })
+	@OpenAPI({ description: 'Lists all donations (fixed or distance based) from all donors. <br> This includes the donations\'s runner\'s distance ran(if distance donation).' })
+	async getAll(@QueryParam("page", { required: false }) page: number, @QueryParam("page_size", { required: false }) page_size: number = 100) {
+		let responseDonations: ResponseDonation[] = new Array<ResponseDonation>();
+		let donations: Array<Donation>;
+
+		if (page != undefined) {
+			donations = await this.donationRepository.find({ relations: ['runner', 'donor', 'runner.scans', 'runner.scans.track'], skip: page * page_size, take: page_size });
+		} else {
+			donations = await this.donationRepository.find({ relations: ['runner', 'donor', 'runner.scans', 'runner.scans.track'] });
+		}
+
+		donations.forEach(donation => {
+			responseDonations.push(donation.toResponse());
+		});
+		return responseDonations;
+	}
+
+	@Get('/:id')
+	@Authorized("DONATION:GET")
+	@ResponseSchema(ResponseDonation)
+	@ResponseSchema(ResponseDistanceDonation)
+	@ResponseSchema(ResponseAnonymousDonation)
+	@ResponseSchema(DonationNotFoundError, { statusCode: 404 })
+	@OnUndefined(DonationNotFoundError)
+	@OpenAPI({ description: 'Lists all information about the donation whose id got provided. This includes the donation\'s runner\'s distance ran (if distance donation).' })
+	async getOne(@Param('id') id: number) {
+		let donation = await this.donationRepository.findOne({ id: id }, { relations: ['runner', 'donor', 'runner.scans', 'runner.scans.track'] })
+		if (!donation) { throw new DonationNotFoundError(); }
+		return donation.toResponse();
+	}
+
+	@Post('/fixed')
+	@Authorized("DONATION:CREATE")
+	@ResponseSchema(ResponseDonation)
+	@ResponseSchema(DonorNotFoundError, { statusCode: 404 })
+	@OpenAPI({ description: 'Create a fixed donation (not distance donation - use /donations/distance instead). <br> Please rmemember to provide the donation\'s donors\'s id and amount.' })
+	async postFixed(@Body({ validate: true }) createDonation: CreateFixedDonation) {
+		let donation = await createDonation.toEntity();
+		donation = await this.fixedDonationRepository.save(donation);
+		return (await this.donationRepository.findOne({ id: donation.id }, { relations: ['donor'] })).toResponse();
+	}
+
+	@Post('/anonymous')
+	@Authorized("DONATION:CREATE")
+	@ResponseSchema(ResponseDonation)
+	@ResponseSchema(DonorNotFoundError, { statusCode: 404 })
+	@OpenAPI({ description: 'Create a anonymous donation' })
+	async postAnonymous(@Body({ validate: true }) createDonation: CreateAnonymousDonation) {
+		let donation = await createDonation.toEntity();
+		donation = await this.fixedDonationRepository.save(donation);
+		return (await this.donationRepository.findOne({ id: donation.id })).toResponse();
+	}
+
+	@Post('/distance')
+	@Authorized("DONATION:CREATE")
+	@ResponseSchema(ResponseDistanceDonation)
+	@ResponseSchema(DonorNotFoundError, { statusCode: 404 })
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@OpenAPI({ description: 'Create a distance donation (not fixed donation - use /donations/fixed instead). <br> Please rmemember to provide the donation\'s donors\'s and runner\s ids and amount per distance (kilometer).' })
+	async postDistance(@Body({ validate: true }) createDonation: CreateDistanceDonation) {
+		let donation = await createDonation.toEntity();
+		donation = await this.distanceDonationRepository.save(donation);
+		return (await this.distanceDonationRepository.findOne({ id: donation.id }, { relations: ['runner', 'donor', 'runner.scans', 'runner.scans.track'] })).toResponse();
+	}
+
+	@Put('/fixed/:id')
+	@Authorized("DONATION:UPDATE")
+	@ResponseSchema(ResponseDonation)
+	@ResponseSchema(DonationNotFoundError, { statusCode: 404 })
+	@ResponseSchema(DonorNotFoundError, { statusCode: 404 })
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@ResponseSchema(DonationIdsNotMatchingError, { statusCode: 406 })
+	@OpenAPI({ description: "Update the fixed donation (not distance donation - use /donations/distance instead) whose id you provided. <br> Please remember that ids can't be changed and amounts must be positive." })
+	async putFixed(@Param('id') id: number, @Body({ validate: true }) donation: UpdateFixedDonation) {
+		let oldDonation = await this.fixedDonationRepository.findOne({ id: id });
+
+		if (!oldDonation) {
+			throw new DonationNotFoundError();
+		}
+
+		if (oldDonation.id != donation.id) {
+			throw new DonationIdsNotMatchingError();
+		}
+
+		await this.fixedDonationRepository.save(await donation.update(oldDonation));
+		return (await this.donationRepository.findOne({ id: donation.id }, { relations: ['donor'] })).toResponse();
+	}
+
+	@Put('/distance/:id')
+	@Authorized("DONATION:UPDATE")
+	@ResponseSchema(ResponseDonation)
+	@ResponseSchema(DonationNotFoundError, { statusCode: 404 })
+	@ResponseSchema(DonorNotFoundError, { statusCode: 404 })
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@ResponseSchema(DonationIdsNotMatchingError, { statusCode: 406 })
+	@OpenAPI({ description: "Update the distance donation (not fixed donation - use /donations/fixed instead) whose id you provided. <br> Please remember that ids can't be changed and amountPerDistance must be positive." })
+	async putDistance(@Param('id') id: number, @Body({ validate: true }) donation: UpdateDistanceDonation) {
+		let oldDonation = await this.distanceDonationRepository.findOne({ id: id });
+
+		if (!oldDonation) {
+			throw new DonationNotFoundError();
+		}
+
+		if (oldDonation.id != donation.id) {
+			throw new DonationIdsNotMatchingError();
+		}
+
+		await this.distanceDonationRepository.save(await donation.update(oldDonation));
+		return (await this.distanceDonationRepository.findOne({ id: donation.id }, { relations: ['runner', 'donor', 'runner.scans', 'runner.scans.track'] })).toResponse();
+	}
+
+	@Delete('/:id')
+	@Authorized("DONATION:DELETE")
+	@ResponseSchema(ResponseDonation)
+	@ResponseSchema(ResponseDistanceDonation)
+	@ResponseSchema(ResponseEmpty, { statusCode: 204 })
+	@OnUndefined(204)
+	@OpenAPI({ description: 'Delete the donation whose id you provided. <br> If no donation with this id exists it will just return 204(no content).' })
+	async remove(@Param("id") id: number, @QueryParam("force") force: boolean) {
+		let donation = await this.donationRepository.findOne({ id: id });
+		if (!donation) { return null; }
+		const responseScan = await this.donationRepository.findOne({ id: donation.id }, { relations: ['runner', 'donor', 'runner.scans', 'runner.scans.track'] });
+
+		await this.donationRepository.delete(donation);
+		return responseScan.toResponse();
+	}
+}

src/controllers/DonorController.ts

@@ -0,0 +1,120 @@
+import { Authorized, Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put, QueryParam } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { Repository, getConnectionManager } from 'typeorm';
+import { DonorHasDonationsError, DonorIdsNotMatchingError, DonorNotFoundError } from '../errors/DonorErrors';
+import { CreateDonor } from '../models/actions/create/CreateDonor';
+import { UpdateDonor } from '../models/actions/update/UpdateDonor';
+import { Donor } from '../models/entities/Donor';
+import { ResponseDonor } from '../models/responses/ResponseDonor';
+import { ResponseEmpty } from '../models/responses/ResponseEmpty';
+import { DonationController } from './DonationController';
+
+@JsonController('/donors')
+@OpenAPI({ security: [{ "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+export class DonorController {
+	private donorRepository: Repository<Donor>;
+
+	/**
+	 * Gets the repository of this controller's model/entity.
+	 */
+	constructor() {
+		this.donorRepository = getConnectionManager().get().getRepository(Donor);
+	}
+
+	@Get()
+	@Authorized("DONOR:GET")
+	@ResponseSchema(ResponseDonor, { isArray: true })
+	@OpenAPI({ description: 'Lists all donor. <br> This includes the donor\'s current donation amount.' })
+	async getAll(@QueryParam("page", { required: false }) page: number, @QueryParam("page_size", { required: false }) page_size: number = 100) {
+		let responseDonors: ResponseDonor[] = new Array<ResponseDonor>();
+		let donors: Array<Donor>;
+
+		if (page != undefined) {
+			donors = await this.donorRepository.find({ relations: ['donations', 'donations.runner', 'donations.runner.scans', 'donations.runner.scans.track'], skip: page * page_size, take: page_size });
+		} else {
+			donors = await this.donorRepository.find({ relations: ['donations', 'donations.runner', 'donations.runner.scans', 'donations.runner.scans.track'] });
+		}
+
+		donors.forEach(donor => {
+			responseDonors.push(new ResponseDonor(donor));
+		});
+		return responseDonors;
+	}
+
+	@Get('/:id')
+	@Authorized("DONOR:GET")
+	@ResponseSchema(ResponseDonor)
+	@ResponseSchema(DonorNotFoundError, { statusCode: 404 })
+	@OnUndefined(DonorNotFoundError)
+	@OpenAPI({ description: 'Lists all information about the donor whose id got provided. <br> This includes the donor\'s current donation amount.' })
+	async getOne(@Param('id') id: number) {
+		let donor = await this.donorRepository.findOne({ id: id }, { relations: ['donations', 'donations.runner', 'donations.runner.scans', 'donations.runner.scans.track'] })
+		if (!donor) { throw new DonorNotFoundError(); }
+		return new ResponseDonor(donor);
+	}
+
+	@Post()
+	@Authorized("DONOR:CREATE")
+	@ResponseSchema(ResponseDonor)
+	@OpenAPI({ description: 'Create a new donor.' })
+	async post(@Body({ validate: true }) createRunner: CreateDonor) {
+		let donor;
+		try {
+			donor = await createRunner.toEntity();
+		} catch (error) {
+			throw error;
+		}
+
+		donor = await this.donorRepository.save(donor)
+		return new ResponseDonor(await this.donorRepository.findOne(donor, { relations: ['donations', 'donations.runner', 'donations.runner.scans', 'donations.runner.scans.track'] }));
+	}
+
+	@Put('/:id')
+	@Authorized("DONOR:UPDATE")
+	@ResponseSchema(ResponseDonor)
+	@ResponseSchema(DonorNotFoundError, { statusCode: 404 })
+	@ResponseSchema(DonorIdsNotMatchingError, { statusCode: 406 })
+	@OpenAPI({ description: "Update the donor whose id you provided. <br> Please remember that ids can't be changed." })
+	async put(@Param('id') id: number, @Body({ validate: true }) donor: UpdateDonor) {
+		let oldDonor = await this.donorRepository.findOne({ id: id });
+
+		if (!oldDonor) {
+			throw new DonorNotFoundError();
+		}
+
+		if (oldDonor.id != donor.id) {
+			throw new DonorIdsNotMatchingError();
+		}
+
+		await this.donorRepository.save(await donor.update(oldDonor));
+		return new ResponseDonor(await this.donorRepository.findOne({ id: id }, { relations: ['donations', 'donations.runner', 'donations.runner.scans', 'donations.runner.scans.track'] }));
+	}
+
+	@Delete('/:id')
+	@Authorized("DONOR:DELETE")
+	@ResponseSchema(ResponseDonor)
+	@ResponseSchema(ResponseEmpty, { statusCode: 204 })
+	@OnUndefined(204)
+	@OpenAPI({ description: 'Delete the donor whose id you provided. <br> If no donor with this id exists it will just return 204(no content). <br> If the donor still has donations associated this will fail, please provide the query param ?force=true to delete the donor with all associated donations.' })
+	async remove(@Param("id") id: number, @QueryParam("force") force: boolean) {
+		let donor = await this.donorRepository.findOne({ id: id });
+		if (!donor) { return null; }
+		const responseDonor = await this.donorRepository.findOne(donor, { relations: ['donations', 'donations.runner', 'donations.runner.scans', 'donations.runner.scans.track'] });
+
+		if (!donor) {
+			throw new DonorNotFoundError();
+		}
+
+		const donorDonations = (await this.donorRepository.findOne({ id: donor.id }, { relations: ["donations"] })).donations;
+		if (donorDonations.length > 0 && !force) {
+			throw new DonorHasDonationsError();
+		}
+		const donationController = new DonationController();
+		for (let donation of donorDonations) {
+			await donationController.remove(donation.id, force);
+		}
+
+		await this.donorRepository.delete(donor);
+		return new ResponseDonor(responseDonor);
+	}
+}

src/controllers/GroupContactController.ts

@@ -0,0 +1,114 @@
+import { Authorized, Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put, QueryParam } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { Repository, getConnection, getConnectionManager } from 'typeorm';
+import { GroupContactIdsNotMatchingError, GroupContactNotFoundError } from '../errors/GroupContactErrors';
+import { RunnerGroupNotFoundError } from '../errors/RunnerGroupErrors';
+import { CreateGroupContact } from '../models/actions/create/CreateGroupContact';
+import { UpdateGroupContact } from '../models/actions/update/UpdateGroupContact';
+import { GroupContact } from '../models/entities/GroupContact';
+import { RunnerGroup } from '../models/entities/RunnerGroup';
+import { ResponseEmpty } from '../models/responses/ResponseEmpty';
+import { ResponseGroupContact } from '../models/responses/ResponseGroupContact';
+
+@JsonController('/contacts')
+@OpenAPI({ security: [{ "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+export class GroupContactController {
+	private contactRepository: Repository<GroupContact>;
+
+	/**
+	 * Gets the repository of this controller's model/entity.
+	 */
+	constructor() {
+		this.contactRepository = getConnectionManager().get().getRepository(GroupContact);
+	}
+
+	@Get()
+	@Authorized("CONTACT:GET")
+	@ResponseSchema(ResponseGroupContact, { isArray: true })
+	@OpenAPI({ description: 'Lists all contacts. <br> This includes the contact\'s associated groups.' })
+	async getAll(@QueryParam("page", { required: false }) page: number, @QueryParam("page_size", { required: false }) page_size: number = 100) {
+		let responseContacts: ResponseGroupContact[] = new Array<ResponseGroupContact>();
+		let contacts: Array<GroupContact>;
+
+		if (page != undefined) {
+			contacts = await this.contactRepository.find({ relations: ['groups', 'groups.parentGroup'], skip: page * page_size, take: page_size });
+		} else {
+			contacts = await this.contactRepository.find({ relations: ['groups', 'groups.parentGroup'] });
+		}
+
+		contacts.forEach(contact => {
+			responseContacts.push(contact.toResponse());
+		});
+		return responseContacts;
+	}
+
+	@Get('/:id')
+	@Authorized("CONTACT:GET")
+	@ResponseSchema(ResponseGroupContact)
+	@ResponseSchema(GroupContactNotFoundError, { statusCode: 404 })
+	@OnUndefined(GroupContactNotFoundError)
+	@OpenAPI({ description: 'Lists all information about the contact whose id got provided. <br> This includes the contact\'s associated groups.' })
+	async getOne(@Param('id') id: number) {
+		let contact = await this.contactRepository.findOne({ id: id }, { relations: ['groups', 'groups.parentGroup'] })
+		if (!contact) { throw new GroupContactNotFoundError(); }
+		return contact.toResponse();
+	}
+
+	@Post()
+	@Authorized("CONTACT:CREATE")
+	@ResponseSchema(ResponseGroupContact)
+	@ResponseSchema(RunnerGroupNotFoundError, { statusCode: 404 })
+	@OpenAPI({ description: 'Create a new contact.' })
+	async post(@Body({ validate: true }) createContact: CreateGroupContact) {
+		let contact;
+		try {
+			contact = await createContact.toEntity();
+		} catch (error) {
+			throw error;
+		}
+
+		contact = await this.contactRepository.save(contact)
+		return (await this.contactRepository.findOne({ id: contact.id }, { relations: ['groups', 'groups.parentGroup'] })).toResponse();
+	}
+
+	@Put('/:id')
+	@Authorized("CONTACT:UPDATE")
+	@ResponseSchema(ResponseGroupContact)
+	@ResponseSchema(GroupContactNotFoundError, { statusCode: 404 })
+	@ResponseSchema(GroupContactIdsNotMatchingError, { statusCode: 406 })
+	@ResponseSchema(RunnerGroupNotFoundError, { statusCode: 404 })
+	@OpenAPI({ description: "Update the contact whose id you provided. <br> Please remember that ids can't be changed." })
+	async put(@Param('id') id: number, @Body({ validate: true }) contact: UpdateGroupContact) {
+		let oldContact = await this.contactRepository.findOne({ id: id });
+
+		if (!oldContact) {
+			throw new GroupContactNotFoundError();
+		}
+
+		if (oldContact.id != contact.id) {
+			throw new GroupContactIdsNotMatchingError();
+		}
+
+		await this.contactRepository.save(await contact.update(oldContact));
+		return (await this.contactRepository.findOne({ id: contact.id }, { relations: ['groups', 'groups.parentGroup'] })).toResponse();
+	}
+
+	@Delete('/:id')
+	@Authorized("CONTACT:DELETE")
+	@ResponseSchema(ResponseGroupContact)
+	@ResponseSchema(ResponseEmpty, { statusCode: 204 })
+	@OnUndefined(204)
+	@OpenAPI({ description: 'Delete the contact whose id you provided. <br> If no contact with this id exists it will just return 204(no content). <br> This won\'t delete any groups associated with the contact.' })
+	async remove(@Param("id") id: number, @QueryParam("force") force: boolean) {
+		let contact = await this.contactRepository.findOne({ id: id });
+		if (!contact) { return null; }
+		const responseContact = await this.contactRepository.findOne(contact, { relations: ['groups', 'groups.parentGroup'] });
+		for (let group of responseContact.groups) {
+			group.contact = null;
+			await getConnection().getRepository(RunnerGroup).save(group);
+		}
+
+		await this.contactRepository.delete(contact);
+		return responseContact.toResponse();
+	}
+}

src/controllers/ImportController.ts

@@ -0,0 +1,102 @@
+import csv from 'csvtojson';
+import { Authorized, Body, ContentType, Controller, Param, Post, QueryParam, Req, UseBefore } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { RunnerGroupNeededError } from '../errors/RunnerErrors';
+import { RunnerGroupNotFoundError } from '../errors/RunnerGroupErrors';
+import RawBodyMiddleware from '../middlewares/RawBody';
+import { ImportRunner } from '../models/actions/ImportRunner';
+import { ResponseRunner } from '../models/responses/ResponseRunner';
+import { RunnerController } from './RunnerController';
+
+@Controller()
+@Authorized(["RUNNER:IMPORT", "TEAM:IMPORT"])
+@OpenAPI({ security: [{ "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+export class ImportController {
+    private runnerController: RunnerController;
+
+    /**
+     * Gets the repository of this controller's model/entity.
+     */
+    constructor() {
+        this.runnerController = new RunnerController();
+    }
+
+    @Post('/runners/import')
+    @ContentType("application/json")
+    @ResponseSchema(ResponseRunner, { isArray: true, statusCode: 200 })
+    @ResponseSchema(RunnerGroupNotFoundError, { statusCode: 404 })
+    @ResponseSchema(RunnerGroupNeededError, { statusCode: 406 })
+    @OpenAPI({ description: "Create new runners from json and insert them into the provided group. <br> If teams/classes are provided alongside the runner's name they'll automaticly be created under the provided org and the runners will be inserted into the teams instead." })
+    async postJSON(@Body({ validate: true, type: ImportRunner }) importRunners: ImportRunner[], @QueryParam("group") groupID: number) {
+        if (!groupID) { throw new RunnerGroupNeededError(); }
+        let responseRunners: ResponseRunner[] = new Array<ResponseRunner>();
+        for await (let runner of importRunners) {
+            responseRunners.push(await this.runnerController.post(await runner.toCreateRunner(groupID)));
+        }
+        return responseRunners;
+    }
+
+    @Post('/organizations/:id/import')
+    @ContentType("application/json")
+    @ResponseSchema(ResponseRunner, { isArray: true, statusCode: 200 })
+    @ResponseSchema(RunnerGroupNotFoundError, { statusCode: 404 })
+    @ResponseSchema(RunnerGroupNeededError, { statusCode: 406 })
+    @OpenAPI({ description: "Create new runners from json and insert them into the provided org. <br> If teams/classes are provided alongside the runner's name they'll automaticly be created under the provided org and the runners will be inserted into the teams instead." })
+    async postOrgsJSON(@Body({ validate: true, type: ImportRunner }) importRunners: ImportRunner[], @Param('id') id: number) {
+        return await this.postJSON(importRunners, id)
+    }
+
+    @Post('/teams/:id/import')
+    @ContentType("application/json")
+    @ResponseSchema(ResponseRunner, { isArray: true, statusCode: 200 })
+    @ResponseSchema(RunnerGroupNotFoundError, { statusCode: 404 })
+    @ResponseSchema(RunnerGroupNeededError, { statusCode: 406 })
+    @OpenAPI({ description: "Create new runners from json and insert them into the provided team" })
+    async postTeamsJSON(@Body({ validate: true, type: ImportRunner }) importRunners: ImportRunner[], @Param('id') id: number) {
+        return await this.postJSON(importRunners, id)
+    }
+
+    @Post('/runners/import/csv')
+    @ContentType("application/json")
+    @UseBefore(RawBodyMiddleware)
+    @ResponseSchema(ResponseRunner, { isArray: true, statusCode: 200 })
+    @ResponseSchema(RunnerGroupNotFoundError, { statusCode: 404 })
+    @ResponseSchema(RunnerGroupNeededError, { statusCode: 406 })
+    @OpenAPI({ description: "Create new runners from csv and insert them into the provided group. <br> If teams/classes are provided alongside the runner's name they'll automaticly be created under the provided org and the runners will be inserted into the teams instead." })
+    async postCSV(@Req() request: any, @QueryParam("group") groupID: number) {
+        let csvParse = await csv({ delimiter: [",", ";"], trim: true }).fromString(request.rawBody.toString());
+        let importRunners: ImportRunner[] = new Array<ImportRunner>();
+        for await (let runner of csvParse) {
+            let newImportRunner = new ImportRunner();
+            newImportRunner.firstname = runner.firstname;
+            newImportRunner.middlename = runner.middlename;
+            newImportRunner.lastname = runner.lastname;
+            if (runner.class === undefined) { newImportRunner.team = runner.team; }
+            else { newImportRunner.class = runner.class; }
+            importRunners.push(newImportRunner);
+        }
+        return await this.postJSON(importRunners, groupID);
+    }
+
+    @Post('/organizations/:id/import/csv')
+    @ContentType("application/json")
+    @UseBefore(RawBodyMiddleware)
+    @ResponseSchema(ResponseRunner, { isArray: true, statusCode: 200 })
+    @ResponseSchema(RunnerGroupNotFoundError, { statusCode: 404 })
+    @ResponseSchema(RunnerGroupNeededError, { statusCode: 406 })
+    @OpenAPI({ description: "Create new runners from csv and insert them into the provided org. <br> If teams/classes are provided alongside the runner's name they'll automaticly be created under the provided org and the runners will be inserted into the teams instead." })
+    async postOrgsCSV(@Req() request: any, @Param("id") id: number) {
+        return await this.postCSV(request, id);
+    }
+
+    @Post('/teams/:id/import/csv')
+    @ContentType("application/json")
+    @UseBefore(RawBodyMiddleware)
+    @ResponseSchema(ResponseRunner, { isArray: true, statusCode: 200 })
+    @ResponseSchema(RunnerGroupNotFoundError, { statusCode: 404 })
+    @ResponseSchema(RunnerGroupNeededError, { statusCode: 406 })
+    @OpenAPI({ description: "Create new runners from csv and insert them into the provided team" })
+    async postTeamsCSV(@Req() request: any, @Param("id") id: number) {
+        return await this.postCSV(request, id);
+    }
+}

src/controllers/MeController.ts

@@ -0,0 +1,90 @@
+import { Body, CurrentUser, Delete, Get, JsonController, OnUndefined, Put, QueryParam } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { getConnectionManager, Repository } from 'typeorm';
+import { PasswordMustContainLowercaseLetterError, PasswordMustContainNumberError, PasswordMustContainUppercaseLetterError, PasswordTooShortError, UserDeletionNotConfirmedError, UserIdsNotMatchingError, UsernameContainsIllegalCharacterError, UserNotFoundError } from '../errors/UserErrors';
+import { UpdateUser } from '../models/actions/update/UpdateUser';
+import { User } from '../models/entities/User';
+import { ResponseUser } from '../models/responses/ResponseUser';
+import { ResponseUserPermissions } from '../models/responses/ResponseUserPermissions';
+import { PermissionController } from './PermissionController';
+
+
+@JsonController('/users/me')
+@OpenAPI({ security: [{ "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+export class MeController {
+	private userRepository: Repository<User>;
+
+	/**
+	 * Gets the repository of this controller's model/entity.
+	 */
+	constructor() {
+		this.userRepository = getConnectionManager().get().getRepository(User);
+	}
+
+	@Get('/')
+	@ResponseSchema(ResponseUser)
+	@ResponseSchema(UserNotFoundError, { statusCode: 404 })
+	@OnUndefined(UserNotFoundError)
+	@OpenAPI({ description: 'Lists all information about yourself.' })
+	async get(@CurrentUser() currentUser: User) {
+		let user = await this.userRepository.findOne({ id: currentUser.id }, { relations: ['permissions', 'groups', 'groups.permissions', 'permissions.principal', 'groups.permissions.principal'] })
+		if (!user) { throw new UserNotFoundError(); }
+		return new ResponseUser(user);
+	}
+
+	@Get('/permissions')
+	@ResponseSchema(ResponseUserPermissions)
+	@ResponseSchema(UserNotFoundError, { statusCode: 404 })
+	@OnUndefined(UserNotFoundError)
+	@OpenAPI({ description: 'Lists all permissions granted to the you sorted into directly granted and inherited as permission response objects.' })
+	async getPermissions(@CurrentUser() currentUser: User) {
+		let user = await this.userRepository.findOne({ id: currentUser.id }, { relations: ['permissions', 'groups', 'groups.permissions', 'permissions.principal', 'groups.permissions.principal'] })
+		if (!user) { throw new UserNotFoundError(); }
+		return new ResponseUserPermissions(user);
+	}
+
+	@Put('/')
+	@ResponseSchema(ResponseUser)
+	@ResponseSchema(UserNotFoundError, { statusCode: 404 })
+	@ResponseSchema(UserIdsNotMatchingError, { statusCode: 406 })
+	@ResponseSchema(UsernameContainsIllegalCharacterError, { statusCode: 406 })
+	@ResponseSchema(PasswordMustContainUppercaseLetterError, { statusCode: 406 })
+	@ResponseSchema(PasswordMustContainLowercaseLetterError, { statusCode: 406 })
+	@ResponseSchema(PasswordMustContainNumberError, { statusCode: 406 })
+	@ResponseSchema(PasswordTooShortError, { statusCode: 406 })
+	@OpenAPI({ description: "Update the yourself. <br> You can't edit your own permissions or group memberships here - Please use the /api/users/:id enpoint instead. <br> Please remember that ids can't be changed." })
+	async put(@CurrentUser() currentUser: User, @Body({ validate: true }) updateUser: UpdateUser) {
+		let oldUser = await this.userRepository.findOne({ id: currentUser.id }, { relations: ['groups'] });
+		updateUser.groups = oldUser.groups.map(g => g.id);
+
+		if (!oldUser) {
+			throw new UserNotFoundError();
+		}
+
+		if (oldUser.id != updateUser.id) {
+			throw new UserIdsNotMatchingError();
+		}
+		await this.userRepository.save(await updateUser.update(oldUser));
+
+		return new ResponseUser(await this.userRepository.findOne({ id: currentUser.id }, { relations: ['permissions', 'groups', 'groups.permissions'] }));
+	}
+
+	@Delete('/')
+	@ResponseSchema(ResponseUser)
+	@ResponseSchema(UserNotFoundError, { statusCode: 404 })
+	@ResponseSchema(UserDeletionNotConfirmedError, { statusCode: 406 })
+	@OpenAPI({ description: 'Delete yourself. <br> You have to confirm your decision by providing the ?force=true query param. <br> If there are any permissions directly granted to you they will get deleted as well.' })
+	async remove(@CurrentUser() currentUser: User, @QueryParam("force") force: boolean) {
+		if (!force) { throw new UserDeletionNotConfirmedError; }
+		if (!currentUser) { return UserNotFoundError; }
+		const responseUser = await this.userRepository.findOne({ id: currentUser.id }, { relations: ['permissions', 'groups', 'groups.permissions'] });;
+
+		const permissionControler = new PermissionController();
+		for (let permission of responseUser.permissions) {
+			await permissionControler.remove(permission.id, true);
+		}
+
+		await this.userRepository.delete(currentUser);
+		return new ResponseUser(responseUser);
+	}
+}

src/controllers/PermissionController.ts

@@ -0,0 +1,125 @@
+import { Authorized, Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put, QueryParam } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { Repository, getConnectionManager } from 'typeorm';
+import { PermissionIdsNotMatchingError, PermissionNeedsPrincipalError, PermissionNotFoundError } from '../errors/PermissionErrors';
+import { PrincipalNotFoundError } from '../errors/PrincipalErrors';
+import { CreatePermission } from '../models/actions/create/CreatePermission';
+import { UpdatePermission } from '../models/actions/update/UpdatePermission';
+import { Permission } from '../models/entities/Permission';
+import { ResponseEmpty } from '../models/responses/ResponseEmpty';
+import { ResponsePermission } from '../models/responses/ResponsePermission';
+import { ResponsePrincipal } from '../models/responses/ResponsePrincipal';
+
+
+@JsonController('/permissions')
+@OpenAPI({ security: [{ "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+export class PermissionController {
+    private permissionRepository: Repository<Permission>;
+
+    /**
+     * Gets the repository of this controller's model/entity.
+     */
+    constructor() {
+        this.permissionRepository = getConnectionManager().get().getRepository(Permission);
+    }
+
+    @Get()
+    @Authorized("PERMISSION:GET")
+    @ResponseSchema(ResponsePermission, { isArray: true })
+    @OpenAPI({ description: 'Lists all permissions for all users and groups.' })
+    async getAll(@QueryParam("page", { required: false }) page: number, @QueryParam("page_size", { required: false }) page_size: number = 100) {
+        let responsePermissions: ResponsePermission[] = new Array<ResponsePermission>();
+        let permissions: Array<Permission>;
+
+        if (page != undefined) {
+            permissions = await this.permissionRepository.find({ relations: ['principal'], skip: page * page_size, take: page_size });
+        } else {
+            permissions = await this.permissionRepository.find({ relations: ['principal'] });
+        }
+
+        permissions.forEach(permission => {
+            responsePermissions.push(new ResponsePermission(permission));
+        });
+        return responsePermissions;
+    }
+
+
+    @Get('/:id')
+    @Authorized("PERMISSION:GET")
+    @ResponseSchema(ResponsePermission)
+    @ResponseSchema(PermissionNotFoundError, { statusCode: 404 })
+    @OnUndefined(PermissionNotFoundError)
+    @OpenAPI({ description: 'Lists all information about the permission whose id got provided.' })
+    async getOne(@Param('id') id: number) {
+        let permission = await this.permissionRepository.findOne({ id: id }, { relations: ['principal'] });
+        if (!permission) { throw new PermissionNotFoundError(); }
+        return new ResponsePermission(permission);
+    }
+
+
+    @Post()
+    @Authorized("PERMISSION:CREATE")
+    @ResponseSchema(ResponsePermission)
+    @ResponseSchema(PrincipalNotFoundError, { statusCode: 404 })
+    @OpenAPI({ description: 'Create a new permission for a existing principal(user/group). <br> If a permission with this target, action and prinicpal already exists that permission will be returned instead of creating a new one.' })
+    async post(@Body({ validate: true }) createPermission: CreatePermission) {
+        let permission;
+        try {
+            permission = await createPermission.toEntity();
+        } catch (error) {
+            throw error;
+        }
+        let existingPermission = await this.permissionRepository.findOne({ target: permission.target, action: permission.action, principal: permission.principal }, { relations: ['principal'] });
+        if (existingPermission) { return new ResponsePermission(existingPermission); }
+
+        permission = await this.permissionRepository.save(permission);
+        permission = await this.permissionRepository.findOne(permission, { relations: ['principal'] });
+
+        return new ResponsePermission(permission);
+    }
+
+
+    @Put('/:id')
+    @Authorized("PERMISSION:UPDATE")
+    @ResponseSchema(ResponsePrincipal)
+    @ResponseSchema(PermissionNotFoundError, { statusCode: 404 })
+    @ResponseSchema(PrincipalNotFoundError, { statusCode: 404 })
+    @ResponseSchema(PermissionIdsNotMatchingError, { statusCode: 406 })
+    @ResponseSchema(PermissionNeedsPrincipalError, { statusCode: 406 })
+    @OpenAPI({ description: "Update a permission object. <br> If updateing the permission object would result in duplicate permission (same target, action and principal) this permission will get deleted and the existing permission will be returned. <br> Please remember that ids can't be changed." })
+    async put(@Param('id') id: number, @Body({ validate: true }) permission: UpdatePermission) {
+        let oldPermission = await this.permissionRepository.findOne({ id: id }, { relations: ['principal'] });
+
+        if (!oldPermission) {
+            throw new PermissionNotFoundError();
+        }
+
+        if (oldPermission.id != permission.id) {
+            throw new PermissionIdsNotMatchingError();
+        }
+        let existingPermission = await this.permissionRepository.findOne({ target: permission.target, action: permission.action, principal: await permission.getPrincipal() }, { relations: ['principal'] });
+        if (existingPermission) {
+            await this.remove(permission.id, true);
+            return new ResponsePermission(existingPermission);
+        }
+
+        await this.permissionRepository.save(await permission.update(oldPermission));
+
+        return new ResponsePermission(await this.permissionRepository.findOne({ id: permission.id }, { relations: ['principal'] }));
+    }
+
+    @Delete('/:id')
+    @Authorized("PERMISSION:DELETE")
+    @ResponseSchema(ResponsePermission)
+    @ResponseSchema(ResponseEmpty, { statusCode: 204 })
+    @OnUndefined(204)
+    @OpenAPI({ description: 'Deletes the permission whose id you provide. <br> If no permission with this id exists it will just return 204(no content).' })
+    async remove(@Param("id") id: number, @QueryParam("force") force: boolean) {
+        let permission = await this.permissionRepository.findOne({ id: id }, { relations: ['principal'] });
+        if (!permission) { return null; }
+
+        const responsePermission = new ResponsePermission(permission);
+        await this.permissionRepository.delete(permission);
+        return responsePermission;
+    }
+}

src/controllers/RunnerCardController.ts

@@ -0,0 +1,164 @@
+import { Authorized, Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put, QueryParam } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { Repository, getConnectionManager } from 'typeorm';
+import { RunnerCardHasScansError, RunnerCardIdsNotMatchingError, RunnerCardNotFoundError } from '../errors/RunnerCardErrors';
+import { RunnerNotFoundError } from '../errors/RunnerErrors';
+import { deleteCardEntry } from '../nats/CardKV';
+import { CreateRunnerCard } from '../models/actions/create/CreateRunnerCard';
+import { UpdateRunnerCard } from '../models/actions/update/UpdateRunnerCard';
+import { UpdateRunnerCardByCode } from '../models/actions/update/UpdateRunnerCardByCode';
+import { RunnerCard } from '../models/entities/RunnerCard';
+import { ResponseEmpty } from '../models/responses/ResponseEmpty';
+import { ResponseRunnerCard } from '../models/responses/ResponseRunnerCard';
+import { ScanController } from './ScanController';
+
+@JsonController('/cards')
+@OpenAPI({ security: [{ "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+export class RunnerCardController {
+	private cardRepository: Repository<RunnerCard>;
+
+	/**
+	 * Gets the repository of this controller's model/entity.
+	 */
+	constructor() {
+		this.cardRepository = getConnectionManager().get().getRepository(RunnerCard);
+	}
+
+	@Get()
+	@Authorized("CARD:GET")
+	@ResponseSchema(ResponseRunnerCard, { isArray: true })
+	@OpenAPI({ description: 'Lists all card.' })
+	async getAll(@QueryParam("page", { required: false }) page: number, @QueryParam("page_size", { required: false }) page_size: number = 100) {
+		let responseCards: ResponseRunnerCard[] = new Array<ResponseRunnerCard>();
+		let cards: Array<RunnerCard>;
+
+		if (page != undefined) {
+			cards = await this.cardRepository.find({ relations: ['runner', 'runner.group', 'runner.group.parentGroup'], skip: page * page_size, take: page_size });
+		} else {
+			cards = await this.cardRepository.find({ relations: ['runner', 'runner.group', 'runner.group.parentGroup'] });
+		}
+
+		cards.forEach(card => {
+			responseCards.push(new ResponseRunnerCard(card));
+		});
+		return responseCards;
+	}
+
+	@Get('/:id')
+	@Authorized("CARD:GET")
+	@ResponseSchema(ResponseRunnerCard)
+	@ResponseSchema(RunnerCardNotFoundError, { statusCode: 404 })
+	@OnUndefined(RunnerCardNotFoundError)
+	@OpenAPI({ description: "Lists all information about the card whose id got provided." })
+	async getOne(@Param('id') id: number) {
+		let card = await this.cardRepository.findOne({ id: id }, { relations: ['runner', 'runner.group', 'runner.group.parentGroup'] });
+		if (!card) { throw new RunnerCardNotFoundError(); }
+		return card.toResponse();
+	}
+
+	@Post('/bulk')
+	@Authorized("CARD:CREATE")
+	@ResponseSchema(ResponseEmpty, { statusCode: 200 })
+	@OpenAPI({ description: "Create blank cards in bulk. <br> Just provide the count as a query param and wait for the 200 response. <br> You can provide the 'returnCards' query param if you want to receive the RESPONSERUNNERCARD objects in the response." })
+	async postBlancoBulk(@QueryParam("count") count: number, @QueryParam("returnCards") returnCards: boolean = false) {
+		let createPromises = new Array<any>();
+		for (let index = 0; index < count; index++) {
+			createPromises.push(this.cardRepository.save({ runner: null, enabled: true }))
+		}
+
+		const cards = await Promise.all(createPromises);
+
+		if (returnCards) {
+			let responseCards: ResponseRunnerCard[] = new Array<ResponseRunnerCard>();
+			for await (let card of cards) {
+				let dbCard = await this.cardRepository.findOne({ id: card.id });
+				responseCards.push(new ResponseRunnerCard(dbCard));
+			}
+			return responseCards;
+		}
+		let response = new ResponseEmpty();
+		response.response = `Created ${count} new blanco cards.`
+		return response;
+	}
+
+	@Post()
+	@Authorized("CARD:CREATE")
+	@ResponseSchema(ResponseRunnerCard)
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@OpenAPI({ description: "Create a new card. <br> You can provide a associated runner by id but you don't have to." })
+	async post(@Body({ validate: true }) createCard: CreateRunnerCard) {
+		let card = await createCard.toEntity();
+		card = await this.cardRepository.save(card);
+		return (await this.cardRepository.findOne({ id: card.id }, { relations: ['runner', 'runner.group', 'runner.group.parentGroup'] })).toResponse();
+	}
+
+	@Put('/:id')
+	@Authorized("CARD:UPDATE")
+	@ResponseSchema(ResponseRunnerCard)
+	@ResponseSchema(RunnerCardNotFoundError, { statusCode: 404 })
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@ResponseSchema(RunnerCardIdsNotMatchingError, { statusCode: 406 })
+	@OpenAPI({ description: "Update the card whose id you provided. <br> Scans created via this card will still be associated with the old runner. <br> Please remember that ids can't be changed." })
+	async put(@Param('id') id: number, @Body({ validate: true }) card: UpdateRunnerCard) {
+		let oldCard = await this.cardRepository.findOne({ id: id });
+
+		if (!oldCard) {
+			throw new RunnerCardNotFoundError();
+		}
+
+		if (oldCard.id != card.id) {
+			throw new RunnerCardIdsNotMatchingError();
+		}
+
+		await this.cardRepository.save(await card.update(oldCard));
+		await deleteCardEntry(id);
+		return (await this.cardRepository.findOne({ id: id }, { relations: ['runner', 'runner.group', 'runner.group.parentGroup'] })).toResponse();
+	}
+
+	@Put('/:code')
+	@Authorized("CARD:UPDATE")
+	@ResponseSchema(ResponseRunnerCard)
+	@ResponseSchema(RunnerCardNotFoundError, { statusCode: 404 })
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@ResponseSchema(RunnerCardIdsNotMatchingError, { statusCode: 406 })
+	@OpenAPI({ description: "Update the card whose code you provided." })
+	async putByCode(@Param('code') code: string, @Body({ validate: true }) card: UpdateRunnerCardByCode) {
+		let oldCard = await this.cardRepository.findOne({ code: code });
+
+		if (!oldCard) {
+			throw new RunnerCardNotFoundError();
+		}
+
+		if (oldCard.code != card.code) {
+			throw new RunnerCardIdsNotMatchingError();
+		}
+
+		await this.cardRepository.save(await card.update(oldCard));
+		return (await this.cardRepository.findOne({ code: code }, { relations: ['runner', 'runner.group', 'runner.group.parentGroup'] })).toResponse();
+	}
+
+	@Delete('/:id')
+	@Authorized("CARD:DELETE")
+	@ResponseSchema(ResponseRunnerCard)
+	@ResponseSchema(ResponseEmpty, { statusCode: 204 })
+	@ResponseSchema(RunnerCardHasScansError, { statusCode: 406 })
+	@OnUndefined(204)
+	@OpenAPI({ description: "Delete the card whose id you provided. <br> If no card with this id exists it will just return 204(no content). <br> If the card still has scans associated you have to provide the force=true query param (warning: this deletes all scans associated with by this card - please disable it instead or just remove the runner association)." })
+	async remove(@Param("id") id: number, @QueryParam("force") force: boolean) {
+		let card = await this.cardRepository.findOne({ id: id });
+		if (!card) { return null; }
+
+		const cardScans = (await this.cardRepository.findOne({ id: id }, { relations: ["scans"] })).scans;
+		if (cardScans.length != 0 && !force) {
+			throw new RunnerCardHasScansError();
+		}
+		const scanController = new ScanController;
+		for (let scan of cardScans) {
+			await scanController.remove(scan.id, force);
+		}
+
+		await deleteCardEntry(id);
+		await this.cardRepository.delete(card);
+		return card.toResponse();
+	}
+}

src/controllers/RunnerController.ts

@@ -1,97 +1,174 @@
-import { Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put, QueryParam } from 'routing-controllers';
+import { Authorized, Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put, QueryParam } from 'routing-controllers';
 import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
-import { getConnectionManager, Repository } from 'typeorm';
-import { EntityFromBody, EntityFromParam } from 'typeorm-routing-controllers-extensions';
-import { RunnerGroupNeededError, RunnerIdsNotMatchingError, RunnerNotFoundError } from '../errors/RunnerErrors';
+import { Repository, getConnectionManager } from 'typeorm';
+import { RunnerGroupNeededError, RunnerHasDistanceDonationsError, RunnerIdsNotMatchingError, RunnerNotFoundError } from '../errors/RunnerErrors';
 import { RunnerGroupNotFoundError } from '../errors/RunnerGroupErrors';
-import { CreateRunner } from '../models/actions/CreateRunner';
+import { deleteRunnerEntry } from '../nats/RunnerKV';
+import { CreateRunner } from '../models/actions/create/CreateRunner';
+import { UpdateRunner } from '../models/actions/update/UpdateRunner';
 import { Runner } from '../models/entities/Runner';
+import { ResponseEmpty } from '../models/responses/ResponseEmpty';
 import { ResponseRunner } from '../models/responses/ResponseRunner';
-
-@JsonController('/runners')
-//@Authorized('RUNNERS:read')
-export class RunnerController {
-	private runnerRepository: Repository<Runner>;
-
-	/**
-	 * Gets the repository of this controller's model/entity.
-	 */
-	constructor() {
-		this.runnerRepository = getConnectionManager().get().getRepository(Runner);
-	}
-
-	@Get()
-	@ResponseSchema(ResponseRunner, { isArray: true })
-	@OpenAPI({ description: 'Lists all runners.' })
-	async getAll() {
-		let responseRunners: ResponseRunner[] = new Array<ResponseRunner>();
-		const runners = await this.runnerRepository.find({ relations: ['scans', 'group'] });
-		console.log(runners);
-		runners.forEach(runner => {
-			responseRunners.push(new ResponseRunner(runner));
-		});
-		return responseRunners;
-	}
-
-	@Get('/:id')
-	@ResponseSchema(ResponseRunner)
-	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
-	@OnUndefined(RunnerNotFoundError)
-	@OpenAPI({ description: 'Returns a runner of a specified id (if it exists)' })
-	async getOne(@Param('id') id: number) {
-		return new ResponseRunner(await this.runnerRepository.findOne({ id: id }, { relations: ['scans', 'group'] }));
-	}
-
-	@Post()
-	@ResponseSchema(ResponseRunner)
-	@ResponseSchema(RunnerGroupNeededError)
-	@ResponseSchema(RunnerGroupNotFoundError)
-	@OpenAPI({ description: 'Create a new runner object (id will be generated automagicly).' })
-	async post(@Body({ validate: true }) createRunner: CreateRunner) {
-		let runner;
-		try {
-			runner = await createRunner.toRunner();
-		} catch (error) {
-			return error;
-		}
-
-		runner = await this.runnerRepository.save(runner)
-		return new ResponseRunner(await this.runnerRepository.findOne(runner, { relations: ['scans', 'group'] }));
-	}
-
-	@Put('/:id')
-	@ResponseSchema(ResponseRunner)
-	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
-	@ResponseSchema(RunnerIdsNotMatchingError, { statusCode: 406 })
-	@OpenAPI({ description: "Update a runner object (id can't be changed)." })
-	async put(@Param('id') id: number, @EntityFromBody() runner: Runner) {
-		let oldRunner = await this.runnerRepository.findOne({ id: id }, { relations: ['scans', 'group'] });
-
-		if (!oldRunner) {
-			throw new RunnerNotFoundError();
-		}
-
-		if (oldRunner.id != runner.id) {
-			throw new RunnerIdsNotMatchingError();
-		}
-
-		await this.runnerRepository.update(oldRunner, runner);
-		return new ResponseRunner(runner);
-	}
-
-	@Delete('/:id')
-	@ResponseSchema(ResponseRunner)
-	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
-	@OpenAPI({ description: 'Delete a specified runner (if it exists).' })
-	async remove(@EntityFromParam('id') runner: Runner, @QueryParam("force") force: boolean) {
-		if (!runner) { throw new RunnerNotFoundError(); }
-		const responseRunner = await this.runnerRepository.findOne(runner, { relations: ['scans', 'group'] });
-
-		if (!runner) {
-			throw new RunnerNotFoundError();
-		}
-
-		await this.runnerRepository.delete(runner);
-		return new ResponseRunner(responseRunner);
-	}
-}
+import { ResponseScan } from '../models/responses/ResponseScan';
+import { ResponseTrackScan } from '../models/responses/ResponseTrackScan';
+import { DonationController } from './DonationController';
+import { RunnerCardController } from './RunnerCardController';
+import { ScanController } from './ScanController';
+
+@JsonController('/runners')
+@OpenAPI({ security: [{ "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+export class RunnerController {
+	private runnerRepository: Repository<Runner>;
+
+	/**
+	 * Gets the repository of this controller's model/entity.
+	 */
+	constructor() {
+		this.runnerRepository = getConnectionManager().get().getRepository(Runner);
+	}
+
+	@Get()
+	@Authorized("RUNNER:GET")
+	@ResponseSchema(ResponseRunner, { isArray: true })
+	@OpenAPI({ description: 'Lists all runners from all teams/orgs. <br> This includes the runner\'s group and distance ran.' })
+	async getAll(@QueryParam("page", { required: false }) page: number, @QueryParam("page_size", { required: false }) page_size: number = 100, @QueryParam("created_via", { required: false }) created_via: string = "all", @QueryParam("selfservice_links", { required: false }) selfservice_links: boolean = false) {
+		let responseRunners: ResponseRunner[] = new Array<ResponseRunner>();
+		let runners: Array<Runner>;
+
+		console.log("call to RunnerController.getAll() with page: " + page + " and page_size: " + page_size + " and created_via: " + created_via + " and selfservice_links: " + selfservice_links);
+		if (page != undefined) {
+			runners = await this.runnerRepository.find({ relations: ['scans', 'group', 'group.parentGroup', 'scans.track'], skip: page * page_size, take: page_size });
+		} else {
+			runners = await this.runnerRepository.find({ relations: ['scans', 'group', 'group.parentGroup', 'scans.track'] });
+		}
+
+		runners.forEach(runner => {
+			if (created_via === "all") {
+				responseRunners.push(new ResponseRunner(runner, selfservice_links));
+			} else {
+				if (runner.created_via === created_via) {
+					responseRunners.push(new ResponseRunner(runner, selfservice_links));
+				}
+			}
+		});
+		return responseRunners;
+	}
+
+	@Get('/:id')
+	@Authorized("RUNNER:GET")
+	@ResponseSchema(ResponseRunner)
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@OnUndefined(RunnerNotFoundError)
+	@OpenAPI({ description: 'Lists all information about the runner whose id got provided.' })
+	async getOne(@Param('id') id: number) {
+		let runner = await this.runnerRepository.findOne({ id: id }, { relations: ['scans', 'group', 'group.parentGroup', 'scans.track', 'cards', 'distanceDonations'] })
+		if (!runner) { throw new RunnerNotFoundError(); }
+		return new ResponseRunner(runner, true);
+	}
+
+	@Get('/:id/scans')
+	@Authorized(["RUNNER:GET", "SCAN:GET"])
+	@ResponseSchema(ResponseScan, { isArray: true })
+	@ResponseSchema(ResponseTrackScan, { isArray: true })
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@OpenAPI({ description: 'Lists all scans of the runner whose id got provided. <br> If you only want the valid scans just add the ?onlyValid=true query param.' })
+	async getScans(@Param('id') id: number, onlyValid?: boolean) {
+		let responseScans: ResponseScan[] = new Array<ResponseScan>();
+		let runner = await this.runnerRepository.findOne({ id: id }, { relations: ['scans', 'scans.track', 'scans.station', 'scans.runner'] })
+		if (!runner) { throw new RunnerNotFoundError(); }
+
+		if (!onlyValid) {
+			for (let scan of runner.scans) {
+				responseScans.push(scan.toResponse());
+			}
+		}
+		else {
+			for (let scan of runner.validScans) {
+				responseScans.push(scan.toResponse());
+			}
+		}
+
+		return responseScans;
+	}
+
+	@Post()
+	@Authorized("RUNNER:CREATE")
+	@ResponseSchema(ResponseRunner)
+	@ResponseSchema(RunnerGroupNeededError)
+	@ResponseSchema(RunnerGroupNotFoundError)
+	@OpenAPI({ description: 'Create a new runner. <br> Please remeber to provide the runner\'s group\'s id.' })
+	async post(@Body({ validate: true }) createRunner: CreateRunner) {
+		let runner;
+		try {
+			runner = await createRunner.toEntity();
+		} catch (error) {
+			throw error;
+		}
+
+		runner = await this.runnerRepository.save(runner)
+		return new ResponseRunner(await this.runnerRepository.findOne(runner, { relations: ['scans', 'group', 'group.parentGroup', 'scans.track', 'cards'] }), true);
+	}
+
+	@Put('/:id')
+	@Authorized("RUNNER:UPDATE")
+	@ResponseSchema(ResponseRunner)
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@ResponseSchema(RunnerIdsNotMatchingError, { statusCode: 406 })
+	@OpenAPI({ description: "Update the runner whose id you provided. <br> Please remember that ids can't be changed." })
+	async put(@Param('id') id: number, @Body({ validate: true }) runner: UpdateRunner) {
+		let oldRunner = await this.runnerRepository.findOne({ id: id }, { relations: ['group'] });
+
+		if (!oldRunner) {
+			throw new RunnerNotFoundError();
+		}
+
+		if (oldRunner.id != runner.id) {
+			throw new RunnerIdsNotMatchingError();
+		}
+
+		await this.runnerRepository.save(await runner.update(oldRunner));
+		await deleteRunnerEntry(id);
+		return new ResponseRunner(await this.runnerRepository.findOne({ id: id }, { relations: ['scans', 'group', 'group.parentGroup', 'scans.track', 'cards'] }), true);
+	}
+
+	@Delete('/:id')
+	@Authorized("RUNNER:DELETE")
+	@ResponseSchema(ResponseRunner)
+	@ResponseSchema(ResponseEmpty, { statusCode: 204 })
+	@ResponseSchema(RunnerHasDistanceDonationsError, { statusCode: 406 })
+	@OnUndefined(204)
+	@OpenAPI({ description: 'Delete the runner whose id you provided. <br> This will also delete all scans and cards associated with the runner. <br> If no runner with this id exists it will just return 204(no content).' })
+	async remove(@Param("id") id: number, @QueryParam("force") force: boolean) {
+		let runner = await this.runnerRepository.findOne({ id: id });
+		if (!runner) { return null; }
+		const responseRunner = await this.runnerRepository.findOne(runner);
+
+		if (!runner) {
+			throw new RunnerNotFoundError();
+		}
+
+		const runnerDonations = (await this.runnerRepository.findOne({ id: runner.id }, { relations: ["distanceDonations"] })).distanceDonations;
+		if (runnerDonations.length > 0 && !force) {
+			throw new RunnerHasDistanceDonationsError();
+		}
+		const donationController = new DonationController();
+		for (let donation of runnerDonations) {
+			await donationController.remove(donation.id, force);
+		}
+
+		const runnerCards = (await this.runnerRepository.findOne({ id: runner.id }, { relations: ["cards"] })).cards;
+		const cardController = new RunnerCardController;
+		for (let card of runnerCards) {
+			await cardController.remove(card.id, force);
+		}
+
+		const runnerScans = (await this.runnerRepository.findOne({ id: runner.id }, { relations: ["scans"] })).scans;
+		const scanController = new ScanController;
+		for (let scan of runnerScans) {
+			await scanController.remove(scan.id, force);
+		}
+
+		await this.runnerRepository.delete(runner);
+		return new ResponseRunner(responseRunner);
+	}
+}

src/controllers/RunnerOrganisationController.ts

@@ -1,119 +0,0 @@
-import { Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put, QueryParam } from 'routing-controllers';
-import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
-import { getConnectionManager, Repository } from 'typeorm';
-import { EntityFromBody, EntityFromParam } from 'typeorm-routing-controllers-extensions';
-import { RunnerOrganisationHasRunnersError, RunnerOrganisationHasTeamsError, RunnerOrganisationIdsNotMatchingError, RunnerOrganisationNotFoundError } from '../errors/RunnerOrganisationErrors';
-import { CreateRunnerOrganisation } from '../models/actions/CreateRunnerOrganisation';
-import { RunnerOrganisation } from '../models/entities/RunnerOrganisation';
-import { ResponseRunnerOrganisation } from '../models/responses/ResponseRunnerOrganisation';
-import { RunnerController } from './RunnerController';
-import { RunnerTeamController } from './RunnerTeamController';
-
-
-@JsonController('/organisation')
-//@Authorized('RUNNERS:read')
-export class RunnerOrganisationController {
-	private runnerOrganisationRepository: Repository<RunnerOrganisation>;
-
-	/**
-	 * Gets the repository of this controller's model/entity.
-	 */
-	constructor() {
-		this.runnerOrganisationRepository = getConnectionManager().get().getRepository(RunnerOrganisation);
-	}
-
-	@Get()
-	@ResponseSchema(ResponseRunnerOrganisation, { isArray: true })
-	@OpenAPI({ description: 'Lists all runnerOrganisations.' })
-	async getAll() {
-		let responseTeams: ResponseRunnerOrganisation[] = new Array<ResponseRunnerOrganisation>();
-		const runners = await this.runnerOrganisationRepository.find({ relations: ['address', 'contact', 'teams'] });
-		console.log(runners);
-		runners.forEach(runner => {
-			responseTeams.push(new ResponseRunnerOrganisation(runner));
-		});
-		return responseTeams;
-	}
-
-	@Get('/:id')
-	@ResponseSchema(ResponseRunnerOrganisation)
-	@ResponseSchema(RunnerOrganisationNotFoundError, { statusCode: 404 })
-	@OnUndefined(RunnerOrganisationNotFoundError)
-	@OpenAPI({ description: 'Returns a runnerOrganisation of a specified id (if it exists)' })
-	async getOne(@Param('id') id: number) {
-		return new ResponseRunnerOrganisation(await this.runnerOrganisationRepository.findOne({ id: id }, { relations: ['address', 'contact', 'teams'] }));
-	}
-
-	@Post()
-	@ResponseSchema(ResponseRunnerOrganisation)
-	@OpenAPI({ description: 'Create a new runnerOrganisation object (id will be generated automagicly).' })
-	async post(@Body({ validate: true }) createRunnerOrganisation: CreateRunnerOrganisation) {
-		let runnerOrganisation;
-		try {
-			runnerOrganisation = await createRunnerOrganisation.toRunnerOrganisation();
-		} catch (error) {
-			return error;
-		}
-
-		runnerOrganisation = await this.runnerOrganisationRepository.save(runnerOrganisation);
-
-		return new ResponseRunnerOrganisation(await this.runnerOrganisationRepository.findOne(runnerOrganisation, { relations: ['address', 'contact', 'teams'] }));
-	}
-
-	@Put('/:id')
-	@ResponseSchema(ResponseRunnerOrganisation)
-	@ResponseSchema(RunnerOrganisationNotFoundError, { statusCode: 404 })
-	@ResponseSchema(RunnerOrganisationIdsNotMatchingError, { statusCode: 406 })
-	@OpenAPI({ description: "Update a runnerOrganisation object (id can't be changed)." })
-	async put(@Param('id') id: number, @EntityFromBody() runnerOrganisation: RunnerOrganisation) {
-		let oldRunnerOrganisation = await this.runnerOrganisationRepository.findOne({ id: id }, { relations: ['address', 'contact', 'teams'] });
-
-		if (!oldRunnerOrganisation) {
-			throw new RunnerOrganisationNotFoundError();
-		}
-
-		if (oldRunnerOrganisation.id != runnerOrganisation.id) {
-			throw new RunnerOrganisationIdsNotMatchingError();
-		}
-
-		await this.runnerOrganisationRepository.update(oldRunnerOrganisation, runnerOrganisation);
-
-		runnerOrganisation = await this.runnerOrganisationRepository.findOne(runnerOrganisation, { relations: ['address', 'contact', 'teams'] });
-		return new ResponseRunnerOrganisation(runnerOrganisation);
-	}
-
-	@Delete('/:id')
-	@ResponseSchema(ResponseRunnerOrganisation)
-	@ResponseSchema(RunnerOrganisationNotFoundError, { statusCode: 404 })
-	@ResponseSchema(RunnerOrganisationHasTeamsError, { statusCode: 406 })
-	@ResponseSchema(RunnerOrganisationHasRunnersError, { statusCode: 406 })
-	@OpenAPI({ description: 'Delete a specified runnerOrganisation (if it exists).' })
-	async remove(@EntityFromParam('id') organisation: RunnerOrganisation, @QueryParam("force") force: boolean) {
-		if (!organisation) { throw new RunnerOrganisationNotFoundError() }
-		let runnerOrganisation = await this.runnerOrganisationRepository.findOne(organisation, { relations: ['address', 'contact', 'runners', 'teams'] });
-
-		if (!force) {
-			if (runnerOrganisation.teams.length != 0) {
-				throw new RunnerOrganisationHasTeamsError();
-			}
-		}
-		const teamController = new RunnerTeamController()
-		for (let team of runnerOrganisation.teams) {
-			await teamController.remove(team, true);
-		}
-
-		if (!force) {
-			if (runnerOrganisation.runners.length != 0) {
-				throw new RunnerOrganisationHasRunnersError();
-			}
-		}
-		const runnerController = new RunnerController()
-		for (let runner of runnerOrganisation.runners) {
-			await runnerController.remove(runner, true);
-		}
-
-		const responseOrganisation = new ResponseRunnerOrganisation(runnerOrganisation);
-		await this.runnerOrganisationRepository.delete(organisation);
-		return responseOrganisation;
-	}
-}

src/controllers/RunnerOrganizationController.ts

@@ -0,0 +1,156 @@
+import { Authorized, BadRequestError, Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put, QueryParam } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { Repository, getConnectionManager } from 'typeorm';
+import { RunnerOrganizationHasRunnersError, RunnerOrganizationHasTeamsError, RunnerOrganizationIdsNotMatchingError, RunnerOrganizationNotFoundError } from '../errors/RunnerOrganizationErrors';
+import { CreateRunnerOrganization } from '../models/actions/create/CreateRunnerOrganization';
+import { UpdateRunnerOrganization } from '../models/actions/update/UpdateRunnerOrganization';
+import { Runner } from '../models/entities/Runner';
+import { RunnerOrganization } from '../models/entities/RunnerOrganization';
+import { ResponseEmpty } from '../models/responses/ResponseEmpty';
+import { ResponseRunner } from '../models/responses/ResponseRunner';
+import { ResponseRunnerOrganization } from '../models/responses/ResponseRunnerOrganization';
+import { RunnerController } from './RunnerController';
+import { RunnerTeamController } from './RunnerTeamController';
+
+
+@JsonController('/organizations')
+@OpenAPI({ security: [{ "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+export class RunnerOrganizationController {
+	private runnerOrganizationRepository: Repository<RunnerOrganization>;
+
+	/**
+	 * Gets the repository of this controller's model/entity.
+	 */
+	constructor() {
+		this.runnerOrganizationRepository = getConnectionManager().get().getRepository(RunnerOrganization);
+	}
+
+	@Get()
+	@Authorized("ORGANIZATION:GET")
+	@ResponseSchema(ResponseRunnerOrganization, { isArray: true })
+	@OpenAPI({ description: 'Lists all organizations. <br> This includes their address, contact and teams (if existing/associated).' })
+	async getAll(@QueryParam("page", { required: false }) page: number, @QueryParam("page_size", { required: false }) page_size: number = 100) {
+		let responseOrgs: ResponseRunnerOrganization[] = new Array<ResponseRunnerOrganization>();
+		let orgs: Array<RunnerOrganization>;
+
+		if (page != undefined) {
+			orgs = await this.runnerOrganizationRepository.find({ relations: ['contact', 'teams'], skip: page * page_size, take: page_size });
+		} else {
+			orgs = await this.runnerOrganizationRepository.find({ relations: ['contact', 'teams'] });
+		}
+
+		orgs.forEach(org => {
+			responseOrgs.push(new ResponseRunnerOrganization(org));
+		});
+		return responseOrgs;
+	}
+
+	@Get('/:id')
+	@Authorized("ORGANIZATION:GET")
+	@ResponseSchema(ResponseRunnerOrganization)
+	@ResponseSchema(RunnerOrganizationNotFoundError, { statusCode: 404 })
+	@OnUndefined(RunnerOrganizationNotFoundError)
+	@OpenAPI({ description: 'Lists all information about the organization whose id got provided.' })
+	async getOne(@Param('id') id: number) {
+		let runnerOrg = await this.runnerOrganizationRepository.findOne({ id: id }, { relations: ['contact', 'teams', 'teams.runners', 'teams.runners.scans', 'teams.runners.scans.track', 'runners', 'runners.scans', 'runners.scans.track'] });
+		if (!runnerOrg) { throw new RunnerOrganizationNotFoundError(); }
+		return new ResponseRunnerOrganization(runnerOrg);
+	}
+
+	@Get('/:id/runners')
+	@Authorized(["RUNNER:GET", "SCAN:GET"])
+	@ResponseSchema(ResponseRunner, { isArray: true })
+	@ResponseSchema(RunnerOrganizationNotFoundError, { statusCode: 404 })
+	@OpenAPI({ description: 'Lists all runners from this org and it\'s teams (if you don\'t provide the ?onlyDirect=true param). <br> This includes the runner\'s group and distance ran.' })
+	async getRunners(@Param('id') id: number, @QueryParam('onlyDirect') onlyDirect: boolean, @QueryParam("selfservice_links", { required: false }) selfservice_links: boolean = false) {
+		let responseRunners: ResponseRunner[] = new Array<ResponseRunner>();
+		let runners: Runner[];
+		if (!onlyDirect) { runners = (await this.runnerOrganizationRepository.findOne({ id: id }, { relations: ['runners', 'runners.group', 'runners.group.parentGroup', 'runners.scans', 'runners.scans.track', 'teams', 'teams.runners', 'teams.runners.group', 'teams.runners.group.parentGroup', 'teams.runners.scans', 'teams.runners.scans.track'] })).allRunners; }
+		else { runners = (await this.runnerOrganizationRepository.findOne({ id: id }, { relations: ['runners', 'runners.group', 'runners.group.parentGroup', 'runners.scans', 'runners.scans.track'] })).runners; }
+		runners.forEach(runner => {
+			responseRunners.push(new ResponseRunner(runner, selfservice_links));
+		});
+		return responseRunners;
+	}
+
+	@Post()
+	@Authorized("ORGANIZATION:CREATE")
+	@ResponseSchema(ResponseRunnerOrganization)
+	@OpenAPI({ description: 'Create a new organsisation.' })
+	async post(@Body({ validate: true }) createRunnerOrganization: CreateRunnerOrganization) {
+		let runnerOrganization;
+		try {
+			runnerOrganization = await createRunnerOrganization.toEntity();
+		} catch (error) {
+			throw error;
+		}
+
+		runnerOrganization = await this.runnerOrganizationRepository.save(runnerOrganization);
+
+		return new ResponseRunnerOrganization(await this.runnerOrganizationRepository.findOne(runnerOrganization, { relations: ['contact', 'teams'] }));
+	}
+
+	@Put('/:id')
+	@Authorized("ORGANIZATION:UPDATE")
+	@ResponseSchema(ResponseRunnerOrganization)
+	@ResponseSchema(RunnerOrganizationNotFoundError, { statusCode: 404 })
+	@ResponseSchema(RunnerOrganizationIdsNotMatchingError, { statusCode: 406 })
+	@OpenAPI({ description: "Update the organization whose id you provided. <br> Please remember that ids can't be changed." })
+	async put(@Param('id') id: number, @Body({ validate: true }) updateOrganization: UpdateRunnerOrganization) {
+		let oldRunnerOrganization = await this.runnerOrganizationRepository.findOne({ id: id });
+
+		if (!oldRunnerOrganization) {
+			throw new RunnerOrganizationNotFoundError();
+		}
+
+		if (oldRunnerOrganization.id != updateOrganization.id) {
+			throw new RunnerOrganizationIdsNotMatchingError();
+		}
+
+		await this.runnerOrganizationRepository.save(await updateOrganization.update(oldRunnerOrganization));
+
+		return new ResponseRunnerOrganization(await this.runnerOrganizationRepository.findOne(id, { relations: ['contact', 'teams'] }));
+	}
+
+	@Delete('/:id')
+	@Authorized("ORGANIZATION:DELETE")
+	@ResponseSchema(ResponseRunnerOrganization)
+	@ResponseSchema(ResponseEmpty, { statusCode: 204 })
+	@ResponseSchema(RunnerOrganizationHasTeamsError, { statusCode: 406 })
+	@ResponseSchema(RunnerOrganizationHasRunnersError, { statusCode: 406 })
+	@OnUndefined(204)
+	@OpenAPI({ description: 'Delete the organsisation whose id you provided. <br> If the organization still has runners and/or teams associated this will fail. <br> To delete the organization with all associated runners and teams set the force QueryParam to true (cascading deletion might take a while). <br> This won\'t delete the associated contact. <br> If no organization with this id exists it will just return 204(no content).' })
+	async remove(@Param("id") id: number, @QueryParam("force") force: boolean) {
+		if (id == 1) {
+			throw new BadRequestError("You can't delete the citizen runner org.");
+		}
+
+		let organization = await this.runnerOrganizationRepository.findOne({ id: id });
+		if (!organization) { return null; }
+		let runnerOrganization = await this.runnerOrganizationRepository.findOne(organization, { relations: ['contact', 'runners', 'teams'] });
+
+		if (!force) {
+			if (runnerOrganization.teams.length != 0) {
+				throw new RunnerOrganizationHasTeamsError();
+			}
+		}
+		const teamController = new RunnerTeamController()
+		for (let team of runnerOrganization.teams) {
+			await teamController.remove(team.id, true);
+		}
+
+		if (!force) {
+			if (runnerOrganization.runners.length != 0) {
+				throw new RunnerOrganizationHasRunnersError();
+			}
+		}
+		const runnerController = new RunnerController()
+		for (let runner of runnerOrganization.runners) {
+			await runnerController.remove(runner.id, true);
+		}
+
+		const responseOrganization = new ResponseRunnerOrganization(runnerOrganization);
+		await this.runnerOrganizationRepository.delete(organization);
+		return responseOrganization;
+	}
+}

src/controllers/RunnerSelfServiceController.ts

@@ -0,0 +1,244 @@
+import type { Request } from "express";
+import * as jwt from "jsonwebtoken";
+import { BadRequestError, Body, Delete, Get, JsonController, OnUndefined, Param, Post, QueryParam, Req, UseBefore } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { getConnectionManager, Repository } from 'typeorm';
+import { config } from '../config';
+import { InvalidCredentialsError, JwtNotProvidedError } from '../errors/AuthError';
+import { MailSendingError } from '../errors/MailErrors';
+import { RunnerEmailNeededError, RunnerHasDistanceDonationsError, RunnerNotFoundError, RunnerSelfserviceTimeoutError } from '../errors/RunnerErrors';
+import { RunnerOrganizationNotFoundError } from '../errors/RunnerOrganizationErrors';
+import { ScanStationNotFoundError } from '../errors/ScanStationErrors';
+import { JwtCreator } from '../jwtcreator';
+import { Mailer } from '../mailer';
+import ScanAuth from '../middlewares/ScanAuth';
+import { CreateSelfServiceCitizenRunner } from '../models/actions/create/CreateSelfServiceCitizenRunner';
+import { CreateSelfServiceRunner } from '../models/actions/create/CreateSelfServiceRunner';
+import { Runner } from '../models/entities/Runner';
+import { RunnerGroup } from '../models/entities/RunnerGroup';
+import { RunnerOrganization } from '../models/entities/RunnerOrganization';
+import { ScanStation } from '../models/entities/ScanStation';
+import { ResponseEmpty } from '../models/responses/ResponseEmpty';
+import { ResponseScanStation } from '../models/responses/ResponseScanStation';
+import { ResponseSelfServiceOrganisation } from '../models/responses/ResponseSelfServiceOrganisation';
+import { ResponseSelfServiceRunner } from '../models/responses/ResponseSelfServiceRunner';
+import { ResponseSelfServiceScan } from '../models/responses/ResponseSelfServiceScan';
+import { DonationController } from './DonationController';
+import { RunnerCardController } from './RunnerCardController';
+import { ScanController } from './ScanController';
+
+@JsonController()
+export class RunnerSelfServiceController {
+	private runnerRepository: Repository<Runner>;
+	private orgRepository: Repository<RunnerOrganization>;
+	private stationRepository: Repository<ScanStation>;
+
+	/**
+	 * Gets the repository of this controller's model/entity.
+	 */
+	constructor() {
+		this.runnerRepository = getConnectionManager().get().getRepository(Runner);
+		this.orgRepository = getConnectionManager().get().getRepository(RunnerOrganization);
+		this.stationRepository = getConnectionManager().get().getRepository(ScanStation);
+	}
+
+	@Get('/runners/me/:jwt')
+	@ResponseSchema(ResponseSelfServiceRunner)
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@OnUndefined(RunnerNotFoundError)
+	@OpenAPI({ description: 'Lists all information about yourself. <br> Please provide your runner jwt(that code we gave you during registration) for auth. <br> If you lost your jwt/personalized link please use the forgot endpoint.' })
+	async get(@Param('jwt') token: string) {
+		return (new ResponseSelfServiceRunner(await this.getRunner(token)));
+	}
+
+	@Delete('/runners/me/:jwt')
+	@ResponseSchema(ResponseSelfServiceRunner)
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@OnUndefined(RunnerNotFoundError)
+	@OpenAPI({ description: 'Deletes all information about yourself. <br> Please provide your runner jwt(that code we gave you during registration) for auth. <br> If you lost your jwt/personalized link please use the forgot endpoint.' })
+	async remove(@Param('jwt') token: string, @QueryParam("force") force: boolean) {
+		const responseRunner = await this.getRunner(token);
+		let runner = await this.runnerRepository.findOne({ id: responseRunner.id });
+
+		if (!runner) { return null; }
+		if (!runner) {
+			throw new RunnerNotFoundError();
+		}
+
+		const runnerDonations = (await this.runnerRepository.findOne({ id: runner.id }, { relations: ["distanceDonations"] })).distanceDonations;
+		if (runnerDonations.length > 0 && !force) {
+			throw new RunnerHasDistanceDonationsError();
+		}
+		const donationController = new DonationController();
+		for (let donation of runnerDonations) {
+			await donationController.remove(donation.id, force);
+		}
+
+		const runnerCards = (await this.runnerRepository.findOne({ id: runner.id }, { relations: ["cards"] })).cards;
+		const cardController = new RunnerCardController;
+		for (let card of runnerCards) {
+			await cardController.remove(card.id, force);
+		}
+
+		const runnerScans = (await this.runnerRepository.findOne({ id: runner.id }, { relations: ["scans"] })).scans;
+		const scanController = new ScanController;
+		for (let scan of runnerScans) {
+			await scanController.remove(scan.id, force);
+		}
+
+		await this.runnerRepository.delete(runner);
+		return new ResponseSelfServiceRunner(responseRunner);
+	}
+
+	@Get('/runners/me/:jwt/scans')
+	@ResponseSchema(ResponseSelfServiceScan, { isArray: true })
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@OnUndefined(RunnerNotFoundError)
+	@OpenAPI({ description: 'Lists all your (runner) scans. <br> Please provide your runner jwt(that code we gave you during registration) for auth. <br> If you lost your jwt/personalized link please contact support.' })
+	async getScans(@Param('jwt') token: string) {
+		const scans = (await this.getRunner(token)).scans;
+		let responseScans = new Array<ResponseSelfServiceScan>()
+		for (let scan of scans) {
+			responseScans.push(new ResponseSelfServiceScan(scan));
+		}
+		return responseScans;
+	}
+
+	@Get('/stations/me')
+	@UseBefore(ScanAuth)
+	@ResponseSchema(ResponseScanStation)
+	@ResponseSchema(ScanStationNotFoundError, { statusCode: 404 })
+	@OnUndefined(ScanStationNotFoundError)
+	@OpenAPI({ description: 'Lists basic information about the station whose token got provided. <br> This includes it\'s associated track.', security: [{ "StationApiToken": [] }] })
+	async getStationMe(@Req() req: Request) {
+		let scan = await this.stationRepository.findOne({ id: parseInt(req.headers["station_id"].toString()) }, { relations: ['track'] })
+		if (!scan) { throw new ScanStationNotFoundError(); }
+		return scan.toResponse();
+	}
+
+	@Post('/runners/login')
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@OnUndefined(ResponseEmpty)
+	@OpenAPI({ description: 'Use this endpoint to reuqest a new selfservice magic-login-link to be sent to your mail address (rate limited to one mail every 15mins).' })
+	async requestNewToken(@QueryParam('mail') mail: string, @QueryParam("locale") locale: string = "en") {
+		if (!mail) {
+			throw new RunnerNotFoundError();
+		}
+		const runner = await this.runnerRepository.findOne({ email: mail });
+		if (!runner) { throw new RunnerNotFoundError(); }
+
+		if (runner.resetRequestedTimestamp > (Math.floor(Date.now() / 1000) - 30)) { throw new RunnerSelfserviceTimeoutError(); }
+		const token = JwtCreator.createSelfService(runner);
+
+		try {
+			await Mailer.sendSelfserviceForgottenMail(runner.email, runner.id, runner.firstname, runner.middlename, runner.lastname, token, locale)
+		} catch (error) {
+			throw new MailSendingError();
+		}
+
+		runner.resetRequestedTimestamp = Math.floor(Date.now() / 1000);
+		await this.runnerRepository.save(runner);
+
+		return { token };
+	}
+
+	@Post('/runners/register')
+	@ResponseSchema(ResponseSelfServiceRunner)
+	@ResponseSchema(RunnerEmailNeededError, { statusCode: 406 })
+	@OpenAPI({ description: 'Create a new selfservice runner in the citizen org. <br> This endpoint shoud be used to allow "everyday citizen" to register themselves. <br> You have to provide a mail address, b/c the future we\'ll implement email verification.' })
+	async registerRunner(@Body({ validate: true }) createRunner: CreateSelfServiceCitizenRunner, @QueryParam("locale") locale: string = "en") {
+		let runner = await createRunner.toEntity();
+		if (await this.getRunnerExistsByMail(runner.email)) {
+			throw new BadRequestError("E-Mail already registered")
+		}
+		runner = await this.runnerRepository.save(runner);
+
+		let response = new ResponseSelfServiceRunner(await this.runnerRepository.findOne(runner, { relations: ['scans', 'group', 'group.parentGroup', 'scans.track', 'cards', 'distanceDonations', 'distanceDonations.donor', 'distanceDonations.runner', 'distanceDonations.runner.scans', 'distanceDonations.runner.scans.track'] }));
+		response.token = JwtCreator.createSelfService(runner);
+
+		try {
+			await Mailer.sendSelfserviceWelcomeMail(runner.email, runner.id, runner.firstname, runner.middlename, runner.lastname, response.token, locale)
+		} catch (error) {
+			throw new MailSendingError();
+		}
+
+		return response;
+	}
+
+	@Post('/runners/register/:token')
+	@ResponseSchema(ResponseSelfServiceRunner)
+	@ResponseSchema(RunnerOrganizationNotFoundError, { statusCode: 404 })
+	@OpenAPI({ description: 'Create a new selfservice runner in a provided org. <br> The orgs get provided and authorized via api tokens that can be optained via the /organizations endpoint.' })
+	async registerOrganizationRunner(@Param('token') token: string, @Body({ validate: true }) createRunner: CreateSelfServiceRunner, @QueryParam("locale") locale: string = "en") {
+		const org = await this.getOrgansisation(token);
+
+		let runner = await createRunner.toEntity(org);
+		if (await this.getRunnerExistsByMail(runner.email)) {
+			throw new BadRequestError("E-Mail already registered")
+		}
+		runner = await this.runnerRepository.save(runner);
+
+		let response = new ResponseSelfServiceRunner(await this.runnerRepository.findOne(runner, { relations: ['scans', 'group', 'group.parentGroup', 'scans.track', 'cards', 'distanceDonations', 'distanceDonations.donor', 'distanceDonations.runner', 'distanceDonations.runner.scans', 'distanceDonations.runner.scans.track'] }));
+		response.token = JwtCreator.createSelfService(runner);
+
+		try {
+			await Mailer.sendSelfserviceWelcomeMail(runner.email, runner.id, runner.firstname, runner.middlename, runner.lastname, response.token, locale)
+		} catch (error) {
+			throw new MailSendingError();
+		}
+
+		return response;
+	}
+
+	@Get('/organizations/selfservice/:token')
+	@ResponseSchema(ResponseSelfServiceOrganisation, { isArray: false })
+	@ResponseSchema(RunnerOrganizationNotFoundError, { statusCode: 404 })
+	@OpenAPI({ description: 'Get the basic info and teams for a org.' })
+	async getSelfserviceOrg(@Param('token') token: string) {
+		const orgid = (await this.getOrgansisation(token)).id;
+		const org = await this.orgRepository.findOne({ id: orgid }, { relations: ['teams'] })
+
+		return new ResponseSelfServiceOrganisation(<RunnerOrganization>org);
+	}
+
+	/**
+	 * Get's a runner by a provided jwt token.
+	 * @param token The runner jwt provided by the runner to identitfy themselves.
+	 */
+	private async getRunner(token: string): Promise<Runner> {
+		if (token == "") { throw new JwtNotProvidedError(); }
+		let jwtPayload = undefined
+		try {
+			jwtPayload = <any>jwt.verify(token, config.jwt_secret);
+		} catch (error) {
+			throw new InvalidCredentialsError();
+		}
+
+		const runner = await this.runnerRepository.findOne({ id: jwtPayload["id"] }, { relations: ['scans', 'group', 'group.parentGroup', 'scans.track', 'cards', 'distanceDonations', 'distanceDonations.donor', 'distanceDonations.runner', 'distanceDonations.runner.scans', 'distanceDonations.runner.scans.track'] });
+		if (!runner) { throw new RunnerNotFoundError() }
+		return runner;
+	}
+
+	/**
+	 * Get's a runner org by a provided registration api key.
+	 * @param token The organization's registration api token.
+	 */
+	private async getOrgansisation(token: string): Promise<RunnerGroup> {
+		token = Buffer.from(token, 'base64').toString('utf8');
+
+		const organization = await this.orgRepository.findOne({ key: token });
+		if (!organization) { throw new RunnerOrganizationNotFoundError; }
+
+		return organization;
+	}
+
+	/**
+	 * Checks if a runner already exists
+	 * @param email The runner's email address
+	 * @returns Boolean (true if exists, false if not)
+	 */
+	private async getRunnerExistsByMail(email: string): Promise<boolean> {
+		const runner = await this.runnerRepository.findOne({ email });
+		return runner != undefined
+	}
+}

src/controllers/RunnerTeamController.ts

@@ -1,108 +1,138 @@
-import { Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put, QueryParam } from 'routing-controllers';
-import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
-import { getConnectionManager, Repository } from 'typeorm';
-import { EntityFromBody, EntityFromParam } from 'typeorm-routing-controllers-extensions';
-import { RunnerTeamHasRunnersError, RunnerTeamIdsNotMatchingError, RunnerTeamNotFoundError } from '../errors/RunnerTeamErrors';
-import { CreateRunnerTeam } from '../models/actions/CreateRunnerTeam';
-import { RunnerTeam } from '../models/entities/RunnerTeam';
-import { ResponseRunnerTeam } from '../models/responses/ResponseRunnerTeam';
-import { RunnerController } from './RunnerController';
-
-
-@JsonController('/teams')
-//@Authorized('RUNNERS:read')
-export class RunnerTeamController {
-	private runnerTeamRepository: Repository<RunnerTeam>;
-
-	/**
-	 * Gets the repository of this controller's model/entity.
-	 */
-	constructor() {
-		this.runnerTeamRepository = getConnectionManager().get().getRepository(RunnerTeam);
-	}
-
-	@Get()
-	@ResponseSchema(ResponseRunnerTeam, { isArray: true })
-	@OpenAPI({ description: 'Lists all runnerTeams.' })
-	async getAll() {
-		let responseTeams: ResponseRunnerTeam[] = new Array<ResponseRunnerTeam>();
-		const runners = await this.runnerTeamRepository.find({ relations: ['parentGroup', 'contact'] });
-		console.log(runners);
-		runners.forEach(runner => {
-			responseTeams.push(new ResponseRunnerTeam(runner));
-		});
-		return responseTeams;
-	}
-
-	@Get('/:id')
-	@ResponseSchema(ResponseRunnerTeam)
-	@ResponseSchema(RunnerTeamNotFoundError, { statusCode: 404 })
-	@OnUndefined(RunnerTeamNotFoundError)
-	@OpenAPI({ description: 'Returns a runnerTeam of a specified id (if it exists)' })
-	async getOne(@Param('id') id: number) {
-		return new ResponseRunnerTeam(await this.runnerTeamRepository.findOne({ id: id }, { relations: ['parentGroup', 'contact'] }));
-	}
-
-	@Post()
-	@ResponseSchema(ResponseRunnerTeam)
-	@OpenAPI({ description: 'Create a new runnerTeam object (id will be generated automagicly).' })
-	async post(@Body({ validate: true }) createRunnerTeam: CreateRunnerTeam) {
-		let runnerTeam;
-		try {
-			runnerTeam = await createRunnerTeam.toRunnerTeam();
-		} catch (error) {
-			return error;
-		}
-
-		runnerTeam = await this.runnerTeamRepository.save(runnerTeam);
-		runnerTeam = await this.runnerTeamRepository.findOne(runnerTeam, { relations: ['parentGroup', 'contact'] });
-
-		return new ResponseRunnerTeam(runnerTeam);
-	}
-
-	@Put('/:id')
-	@ResponseSchema(ResponseRunnerTeam)
-	@ResponseSchema(RunnerTeamNotFoundError, { statusCode: 404 })
-	@ResponseSchema(RunnerTeamIdsNotMatchingError, { statusCode: 406 })
-	@OpenAPI({ description: "Update a runnerTeam object (id can't be changed)." })
-	async put(@Param('id') id: number, @EntityFromBody() runnerTeam: RunnerTeam) {
-		let oldRunnerTeam = await this.runnerTeamRepository.findOne({ id: id }, { relations: ['parentGroup', 'contact'] });
-
-		if (!oldRunnerTeam) {
-			throw new RunnerTeamNotFoundError();
-		}
-
-		if (oldRunnerTeam.id != runnerTeam.id) {
-			throw new RunnerTeamIdsNotMatchingError();
-		}
-
-		await this.runnerTeamRepository.update(oldRunnerTeam, runnerTeam);
-
-		runnerTeam = await this.runnerTeamRepository.findOne(runnerTeam, { relations: ['parentGroup', 'contact'] });
-		return new ResponseRunnerTeam(runnerTeam);
-	}
-
-	@Delete('/:id')
-	@ResponseSchema(ResponseRunnerTeam)
-	@ResponseSchema(RunnerTeamNotFoundError, { statusCode: 404 })
-	@ResponseSchema(RunnerTeamHasRunnersError, { statusCode: 406 })
-	@OpenAPI({ description: 'Delete a specified runnerTeam (if it exists).' })
-	async remove(@EntityFromParam('id') team: RunnerTeam, @QueryParam("force") force: boolean) {
-		if (!team) { throw new RunnerTeamNotFoundError(); }
-		let runnerTeam = await this.runnerTeamRepository.findOne(team, { relations: ['parentGroup', 'contact', 'runners'] });
-
-		if (!force) {
-			if (runnerTeam.runners.length != 0) {
-				throw new RunnerTeamHasRunnersError();
-			}
-		}
-		const runnerController = new RunnerController()
-		for (let runner of runnerTeam.runners) {
-			await runnerController.remove(runner, true);
-		}
-
-		const responseTeam = new ResponseRunnerTeam(runnerTeam);
-		await this.runnerTeamRepository.delete(team);
-		return responseTeam;
-	}
-}
+import { Authorized, Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put, QueryParam } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { Repository, getConnectionManager } from 'typeorm';
+import { RunnerTeamHasRunnersError, RunnerTeamIdsNotMatchingError, RunnerTeamNotFoundError } from '../errors/RunnerTeamErrors';
+import { CreateRunnerTeam } from '../models/actions/create/CreateRunnerTeam';
+import { UpdateRunnerTeam } from '../models/actions/update/UpdateRunnerTeam';
+import { RunnerTeam } from '../models/entities/RunnerTeam';
+import { ResponseEmpty } from '../models/responses/ResponseEmpty';
+import { ResponseRunner } from '../models/responses/ResponseRunner';
+import { ResponseRunnerTeam } from '../models/responses/ResponseRunnerTeam';
+import { RunnerController } from './RunnerController';
+
+
+@JsonController('/teams')
+@OpenAPI({ security: [{ "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+export class RunnerTeamController {
+	private runnerTeamRepository: Repository<RunnerTeam>;
+
+	/**
+	 * Gets the repository of this controller's model/entity.
+	 */
+	constructor() {
+		this.runnerTeamRepository = getConnectionManager().get().getRepository(RunnerTeam);
+	}
+
+	@Get()
+	@Authorized("TEAM:GET")
+	@ResponseSchema(ResponseRunnerTeam, { isArray: true })
+	@OpenAPI({ description: 'Lists all teams. <br> This includes their parent organization and contact (if existing/associated).' })
+	async getAll(@QueryParam("page", { required: false }) page: number, @QueryParam("page_size", { required: false }) page_size: number = 100) {
+		let responseTeams: ResponseRunnerTeam[] = new Array<ResponseRunnerTeam>();
+		let teams: Array<RunnerTeam>;
+
+		if (page != undefined) {
+			teams = await this.runnerTeamRepository.find({ relations: ['parentGroup', 'contact'], skip: page * page_size, take: page_size });
+		} else {
+			teams = await this.runnerTeamRepository.find({ relations: ['parentGroup', 'contact'] });
+		}
+
+		teams.forEach(team => {
+			responseTeams.push(new ResponseRunnerTeam(team));
+		});
+		return responseTeams;
+	}
+
+	@Get('/:id')
+	@Authorized("TEAM:GET")
+	@ResponseSchema(ResponseRunnerTeam)
+	@ResponseSchema(RunnerTeamNotFoundError, { statusCode: 404 })
+	@OnUndefined(RunnerTeamNotFoundError)
+	@OpenAPI({ description: 'Lists all information about the team whose id got provided.' })
+	async getOne(@Param('id') id: number) {
+		let runnerTeam = await this.runnerTeamRepository.findOne({ id: id }, { relations: ['parentGroup', 'contact', 'runners', 'runners.scans', 'runners.scans.track'] });
+		if (!runnerTeam) { throw new RunnerTeamNotFoundError(); }
+		return new ResponseRunnerTeam(runnerTeam);
+	}
+
+	@Get('/:id/runners')
+	@Authorized(["RUNNER:GET", "SCAN:GET"])
+	@ResponseSchema(ResponseRunner, { isArray: true })
+	@ResponseSchema(RunnerTeamNotFoundError, { statusCode: 404 })
+	@OpenAPI({ description: 'Lists all runners from this team. <br> This includes the runner\'s group and distance ran.' })
+	async getRunners(@Param('id') id: number, @QueryParam("selfservice_links", { required: false }) selfservice_links: boolean = false) {
+		let responseRunners: ResponseRunner[] = new Array<ResponseRunner>();
+		const runners = (await this.runnerTeamRepository.findOne({ id: id }, { relations: ['runners', 'runners.group', 'runners.group.parentGroup', 'runners.scans', 'runners.scans.track'] })).runners;
+		runners.forEach(runner => {
+			responseRunners.push(new ResponseRunner(runner, selfservice_links));
+		});
+		return responseRunners;
+	}
+
+	@Post()
+	@Authorized("TEAM:CREATE")
+	@ResponseSchema(ResponseRunnerTeam)
+	@OpenAPI({ description: 'Create a new organsisation. <br> Please remember to provide it\'s parent group\'s id.' })
+	async post(@Body({ validate: true }) createRunnerTeam: CreateRunnerTeam) {
+		let runnerTeam;
+		try {
+			runnerTeam = await createRunnerTeam.toEntity();
+		} catch (error) {
+			throw error;
+		}
+
+		runnerTeam = await this.runnerTeamRepository.save(runnerTeam);
+		runnerTeam = await this.runnerTeamRepository.findOne(runnerTeam, { relations: ['parentGroup', 'contact'] });
+
+		return new ResponseRunnerTeam(runnerTeam);
+	}
+
+	@Put('/:id')
+	@Authorized("TEAM:UPDATE")
+	@ResponseSchema(ResponseRunnerTeam)
+	@ResponseSchema(RunnerTeamNotFoundError, { statusCode: 404 })
+	@ResponseSchema(RunnerTeamIdsNotMatchingError, { statusCode: 406 })
+	@OpenAPI({ description: "Update the team whose id you provided. <br> Please remember that ids can't be changed." })
+	async put(@Param('id') id: number, @Body({ validate: true }) runnerTeam: UpdateRunnerTeam) {
+		let oldRunnerTeam = await this.runnerTeamRepository.findOne({ id: id }, { relations: ['parentGroup', 'contact'] });
+
+		if (!oldRunnerTeam) {
+			throw new RunnerTeamNotFoundError();
+		}
+
+		if (oldRunnerTeam.id != runnerTeam.id) {
+			throw new RunnerTeamIdsNotMatchingError();
+		}
+
+		await this.runnerTeamRepository.save(await runnerTeam.update(oldRunnerTeam));
+
+		return new ResponseRunnerTeam(await this.runnerTeamRepository.findOne({ id: runnerTeam.id }, { relations: ['parentGroup', 'contact'] }));
+	}
+
+	@Delete('/:id')
+	@Authorized("TEAM:DELETE")
+	@ResponseSchema(ResponseRunnerTeam)
+	@ResponseSchema(ResponseEmpty, { statusCode: 204 })
+	@ResponseSchema(RunnerTeamHasRunnersError, { statusCode: 406 })
+	@OnUndefined(204)
+	@OpenAPI({ description: 'Delete the team whose id you provided. <br> If the team still has runners associated this will fail. <br> To delete the team with all associated runners set the force QueryParam to true (cascading deletion might take a while). <br> This won\'t delete the associated contact.<br> If no team with this id exists it will just return 204(no content).' })
+	async remove(@Param("id") id: number, @QueryParam("force") force: boolean) {
+		let team = await this.runnerTeamRepository.findOne({ id: id });
+		if (!team) { return null; }
+		let runnerTeam = await this.runnerTeamRepository.findOne(team, { relations: ['runners'] });
+
+		if (!force) {
+			if (runnerTeam.runners.length != 0) {
+				throw new RunnerTeamHasRunnersError();
+			}
+		}
+		const runnerController = new RunnerController()
+		for (let runner of runnerTeam.runners) {
+			await runnerController.remove(runner.id, true);
+		}
+
+		const responseTeam = new ResponseRunnerTeam(runnerTeam);
+		await this.runnerTeamRepository.delete(team);
+		return responseTeam;
+	}
+}

src/controllers/ScanController.ts

@@ -0,0 +1,254 @@
+import type { Request } from "express";
+import { Authorized, Body, Delete, Get, HttpError, JsonController, OnUndefined, Param, Post, Put, QueryParam, Req, UseBefore } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { Repository, getConnection, getConnectionManager } from 'typeorm';
+import { RunnerNotFoundError } from '../errors/RunnerErrors';
+import { ScanIdsNotMatchingError, ScanNotFoundError } from '../errors/ScanErrors';
+import { ScanStationNotFoundError } from '../errors/ScanStationErrors';
+import ScanAuth from '../middlewares/ScanAuth';
+import { deleteCardEntry, getCardEntry, setCardEntry } from '../nats/CardKV';
+import { deleteRunnerEntry, getRunnerEntry, RunnerKVEntry, setRunnerEntry, warmRunner } from '../nats/RunnerKV';
+import { getStationEntryById } from '../nats/StationKV';
+import { CreateScan } from '../models/actions/create/CreateScan';
+import { CreateTrackScan } from '../models/actions/create/CreateTrackScan';
+import { UpdateScan } from '../models/actions/update/UpdateScan';
+import { UpdateTrackScan } from '../models/actions/update/UpdateTrackScan';
+import { RunnerCard } from '../models/entities/RunnerCard';
+import { Scan } from '../models/entities/Scan';
+import { TrackScan } from '../models/entities/TrackScan';
+import { ResponseEmpty } from '../models/responses/ResponseEmpty';
+import { ResponseScan } from '../models/responses/ResponseScan';
+import { ResponseScanIntake, ResponseScanIntakeRunner } from '../models/responses/ResponseScanIntake';
+import { ResponseTrackScan } from '../models/responses/ResponseTrackScan';
+@JsonController('/scans')
+@OpenAPI({ security: [{ "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+export class ScanController {
+	private scanRepository: Repository<Scan>;
+	private trackScanRepository: Repository<TrackScan>;
+
+	/**
+	 * Gets the repository of this controller's model/entity.
+	 */
+	constructor() {
+		this.scanRepository = getConnectionManager().get().getRepository(Scan);
+		this.trackScanRepository = getConnectionManager().get().getRepository(TrackScan);
+	}
+
+	@Get()
+	@Authorized("SCAN:GET")
+	@ResponseSchema(ResponseScan, { isArray: true })
+	@ResponseSchema(ResponseTrackScan, { isArray: true })
+	@OpenAPI({ description: 'Lists all scans (normal or track) from all runners. <br> This includes the scan\'s runner\'s distance ran.' })
+	async getAll(@QueryParam("page", { required: false }) page: number, @QueryParam("page_size", { required: false }) page_size: number = 100) {
+		let responseScans: ResponseScan[] = new Array<ResponseScan>();
+		let scans: Array<Scan>;
+
+		if (page != undefined) {
+			scans = await this.scanRepository.find({ relations: ['runner', 'track'], skip: page * page_size, take: page_size });
+		} else {
+			scans = await this.scanRepository.find({ relations: ['runner', 'track'] });
+		}
+
+		scans.forEach(scan => {
+			responseScans.push(scan.toResponse());
+		});
+		return responseScans;
+	}
+
+	@Get('/:id')
+	@Authorized("SCAN:GET")
+	@ResponseSchema(ResponseScan)
+	@ResponseSchema(ResponseTrackScan)
+	@ResponseSchema(ScanNotFoundError, { statusCode: 404 })
+	@OnUndefined(ScanNotFoundError)
+	@OpenAPI({ description: 'Lists all information about the scan whose id got provided. This includes the scan\'s runner\'s distance ran.' })
+	async getOne(@Param('id') id: number) {
+		let scan = await this.scanRepository.findOne({ id: id }, { relations: ['runner', 'track', 'runner.group', 'card', 'station'] })
+		if (!scan) { throw new ScanNotFoundError(); }
+		return scan.toResponse();
+	}
+
+	@Post()
+	@UseBefore(ScanAuth)
+	@ResponseSchema(ResponseScan)
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@OpenAPI({ description: 'Create a new scan (not track scan - use /scans/trackscans instead). <br> Please rmemember to provide the scan\'s runner\'s id and distance.', security: [{ "StationApiToken": [] }, { "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+	async post(@Body({ validate: true }) createScan: CreateScan) {
+		let scan = await createScan.toEntity();
+		scan = await this.scanRepository.save(scan);
+		return (await this.scanRepository.findOne({ id: scan.id }, { relations: ['runner', 'track', 'runner.scans', 'runner.group', 'runner.scans.track', 'card', 'station'] })).toResponse();
+	}
+
+	@Post("/trackscans")
+	@UseBefore(ScanAuth)
+	@ResponseSchema(ResponseTrackScan)
+	@ResponseSchema(ResponseScanIntake)
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@OpenAPI({ description: 'Create a new track scan (for "normal" scans use /scans instead). <br> Please remember that to provide the scan\'s card\'s station\'s id.', security: [{ "StationApiToken": [] }, { "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+	async postTrackScans(@Body({ validate: true }) createScan: CreateTrackScan, @Req() req: Request) {
+		// Station token path — KV-backed intake flow
+		if (req.isStationAuth) {
+			return this.stationIntake(createScan.card, req.stationId);
+		}
+		// JWT path — existing full flow, unchanged
+		createScan.station = createScan.station;
+		let scan = await createScan.toEntity();
+		scan = await this.trackScanRepository.save(scan);
+		return (await this.scanRepository.findOne({ id: scan.id }, { relations: ['runner', 'track', 'runner.scans', 'runner.group', 'runner.scans.track', 'card', 'station'] })).toResponse();
+	}
+
+	/**
+	 * KV-backed hot path for scan station submissions.
+	 * Zero DB reads on a fully warm cache. Fixes the race condition via CAS on the runner KV entry.
+	 */
+	private async stationIntake(rawCard: number, stationId: number): Promise<ResponseScanIntake> {
+		const MAX_RETRIES = 3;
+		const cardId = rawCard % 200000000000;
+
+		// --- Station (already verified by ScanAuth, just need track data) ---
+		const stationEntry = await getStationEntryById(stationId);
+		// stationEntry is always populated here — ScanAuth wrote it on the cold path
+		const trackDistance = stationEntry.trackDistance;
+		const minimumLapTime = stationEntry.minimumLapTime;
+
+		// --- Card ---
+		let cardEntry = await getCardEntry(cardId);
+		if (!cardEntry) {
+			// Cold path: load from DB and cache
+			const card = await getConnection().getRepository(RunnerCard).findOne({ id: cardId }, { relations: ['runner'] });
+			if (!card) throw new ScanNotFoundError();
+			if (!card.runner) throw new RunnerNotFoundError();
+			cardEntry = {
+				runnerId: card.runner.id,
+				runnerDisplayName: `${card.runner.firstname} ${card.runner.lastname}`,
+				enabled: card.enabled,
+			};
+			await setCardEntry(cardId, cardEntry);
+		}
+		if (!cardEntry.enabled) throw new HttpError(400, 'Card is disabled.');
+		const runnerId = cardEntry.runnerId;
+
+		// --- Runner state + CAS update (fixes race condition) ---
+		const now = Math.round(Date.now() / 1000);
+		let retries = 0;
+		let response: ResponseScanIntake;
+
+		while (retries < MAX_RETRIES) {
+			// Get current runner state (warm or cold)
+			let result = await getRunnerEntry(runnerId);
+			if (!result) {
+				const warmed = await warmRunner(runnerId);
+				result = { entry: warmed, revision: undefined };
+			}
+			const { entry, revision } = result;
+
+			// Compute
+			const lapTime = entry.latestTimestamp === 0 ? 0 : now - entry.latestTimestamp;
+			const valid = minimumLapTime === 0 || lapTime > minimumLapTime;
+			const newDistance = entry.totalDistance + (valid ? trackDistance : 0);
+			const newTimestamp = valid ? now : entry.latestTimestamp;
+
+			const updated: RunnerKVEntry = {
+				displayName: entry.displayName,
+				totalDistance: newDistance,
+				latestTimestamp: newTimestamp,
+			};
+
+			// CAS write — if revision is undefined (warmed this request), plain put
+			const success = await setRunnerEntry(runnerId, updated, revision);
+			if (!success) {
+				retries++;
+				continue;
+			}
+
+			// DB insert — synchronous, keeps DB as source of truth
+			const newScan = new TrackScan();
+			newScan.runner = { id: runnerId } as any;
+			newScan.card = { id: cardId } as any;
+			newScan.station = { id: stationId } as any;
+			newScan.track = { id: stationEntry.trackId } as any;
+			newScan.timestamp = now;
+			newScan.lapTime = lapTime;
+			newScan.valid = valid;
+			await this.trackScanRepository.save(newScan);
+
+			const runnerInfo = new ResponseScanIntakeRunner();
+			runnerInfo.displayName = entry.displayName;
+			runnerInfo.totalDistance = newDistance;
+
+			response = new ResponseScanIntake();
+			response.accepted = true;
+			response.valid = valid;
+			response.lapTime = lapTime;
+			response.runner = runnerInfo;
+
+			return response;
+		}
+
+		throw new HttpError(409, 'Scan rejected: too many concurrent scans for this runner. Please retry.');
+	}
+
+	@Put('/:id')
+	@Authorized("SCAN:UPDATE")
+	@ResponseSchema(ResponseScan)
+	@ResponseSchema(ScanNotFoundError, { statusCode: 404 })
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@ResponseSchema(ScanIdsNotMatchingError, { statusCode: 406 })
+	@OpenAPI({ description: "Update the scan (not track scan use /scans/trackscans/:id instead) whose id you provided. <br> Please remember that ids can't be changed and distances must be positive." })
+	async put(@Param('id') id: number, @Body({ validate: true }) scan: UpdateScan) {
+		let oldScan = await this.scanRepository.findOne({ id: id }, { relations: ['runner'] });
+
+		if (!oldScan) {
+			throw new ScanNotFoundError();
+		}
+
+		if (oldScan.id != scan.id) {
+			throw new ScanIdsNotMatchingError();
+		}
+
+		const runnerId = oldScan.runner?.id;
+		await this.scanRepository.save(await scan.update(oldScan));
+		if (runnerId) await deleteRunnerEntry(runnerId);
+		return (await this.scanRepository.findOne({ id: id }, { relations: ['runner', 'track', 'runner.scans', 'runner.group', 'runner.scans.track', 'card', 'station'] })).toResponse();
+	}
+
+	@Put('/trackscans/:id')
+	@Authorized("SCAN:UPDATE")
+	@ResponseSchema(ResponseTrackScan)
+	@ResponseSchema(ScanNotFoundError, { statusCode: 404 })
+	@ResponseSchema(RunnerNotFoundError, { statusCode: 404 })
+	@ResponseSchema(ScanStationNotFoundError, { statusCode: 404 })
+	@ResponseSchema(ScanIdsNotMatchingError, { statusCode: 406 })
+	@OpenAPI({ description: 'Update the track scan (not "normal" scan use /scans/trackscans/:id instead) whose id you provided. <br> Please remember that only the validity, runner and track can be changed.' })
+	async putTrackScan(@Param('id') id: number, @Body({ validate: true }) scan: UpdateTrackScan) {
+		let oldScan = await this.trackScanRepository.findOne({ id: id }, { relations: ['runner'] });
+
+		if (!oldScan) {
+			throw new ScanNotFoundError();
+		}
+
+		if (oldScan.id != scan.id) {
+			throw new ScanIdsNotMatchingError();
+		}
+
+		const runnerId = oldScan.runner?.id;
+		await this.trackScanRepository.save(await scan.update(oldScan));
+		if (runnerId) await deleteRunnerEntry(runnerId);
+		return (await this.scanRepository.findOne({ id: id }, { relations: ['runner', 'track', 'runner.scans', 'runner.group', 'runner.scans.track', 'card', 'station'] })).toResponse();
+	}
+
+	@Delete('/:id')
+	@Authorized("SCAN:DELETE")
+	@ResponseSchema(ResponseScan)
+	@ResponseSchema(ResponseEmpty, { statusCode: 204 })
+	@OnUndefined(204)
+	@OpenAPI({ description: 'Delete the scan whose id you provided. <br> If no scan with this id exists it will just return 204(no content).' })
+	async remove(@Param("id") id: number, @QueryParam("force") force: boolean) {
+		let scan = await this.scanRepository.findOne({ id: id });
+		if (!scan) { return null; }
+		const responseScan = await this.scanRepository.findOne({ id: scan.id }, { relations: ['runner', 'track', 'runner.scans', 'runner.group', 'runner.scans.track', 'card', 'station'] });
+
+		await this.scanRepository.delete(scan);
+		return responseScan.toResponse();
+	}
+}

src/controllers/ScanStationController.ts

@@ -0,0 +1,118 @@
+import { Authorized, Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put, QueryParam } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { Repository, getConnectionManager } from 'typeorm';
+import { ScanStationHasScansError, ScanStationIdsNotMatchingError, ScanStationNotFoundError } from '../errors/ScanStationErrors';
+import { TrackNotFoundError } from '../errors/TrackErrors';
+import { deleteStationEntry } from '../nats/StationKV';
+import { CreateScanStation } from '../models/actions/create/CreateScanStation';
+import { UpdateScanStation } from '../models/actions/update/UpdateScanStation';
+import { ScanStation } from '../models/entities/ScanStation';
+import { ResponseEmpty } from '../models/responses/ResponseEmpty';
+import { ResponseScanStation } from '../models/responses/ResponseScanStation';
+import { ScanController } from './ScanController';
+
+@JsonController('/stations')
+@OpenAPI({ security: [{ "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+export class ScanStationController {
+	private stationRepository: Repository<ScanStation>;
+
+	/**
+	 * Gets the repository of this controller's model/entity.
+	 */
+	constructor() {
+		this.stationRepository = getConnectionManager().get().getRepository(ScanStation);
+	}
+
+	@Get()
+	@Authorized("STATION:GET")
+	@ResponseSchema(ResponseScanStation, { isArray: true })
+	@OpenAPI({ description: 'Lists all stations. <br> This includes their associated tracks.' })
+	async getAll(@QueryParam("page", { required: false }) page: number, @QueryParam("page_size", { required: false }) page_size: number = 100) {
+		let responseStations: ResponseScanStation[] = new Array<ResponseScanStation>();
+		let stations: Array<ScanStation>;
+
+		if (page != undefined) {
+			stations = await this.stationRepository.find({ relations: ['track'], skip: page * page_size, take: page_size });
+		} else {
+			stations = await this.stationRepository.find({ relations: ['track'] });
+		}
+
+		stations.forEach(station => {
+			responseStations.push(station.toResponse());
+		});
+		return responseStations;
+	}
+
+	@Get('/:id')
+	@Authorized("STATION:GET")
+	@ResponseSchema(ResponseScanStation)
+	@ResponseSchema(ScanStationNotFoundError, { statusCode: 404 })
+	@OnUndefined(ScanStationNotFoundError)
+	@OpenAPI({ description: 'Lists all information about the station whose id got provided. <br> This includes it\'s associated track.' })
+	async getOne(@Param('id') id: number) {
+		let scan = await this.stationRepository.findOne({ id: id }, { relations: ['track'] })
+		if (!scan) { throw new ScanStationNotFoundError(); }
+		return scan.toResponse();
+	}
+
+	@Post()
+	@Authorized("STATION:CREATE")
+	@ResponseSchema(ResponseScanStation)
+	@ResponseSchema(TrackNotFoundError, { statusCode: 404 })
+	@OpenAPI({ description: 'Create a new station. <br> Please remeber to provide the station\'s track\'s id. <br> Please also remember that the station key is only visibe on creation.' })
+	async post(@Body({ validate: true }) createStation: CreateScanStation) {
+		let newStation = await createStation.toEntity();
+		const station = await this.stationRepository.save(newStation);
+		let responseStation = (await this.stationRepository.findOne({ id: station.id }, { relations: ['track'] })).toResponse();
+		responseStation.key = newStation.cleartextkey;
+		return responseStation;
+	}
+
+	@Put('/:id')
+	@Authorized("STATION:UPDATE")
+	@ResponseSchema(ResponseScanStation)
+	@ResponseSchema(ScanStationNotFoundError, { statusCode: 404 })
+	@ResponseSchema(ScanStationIdsNotMatchingError, { statusCode: 406 })
+	@OpenAPI({ description: "Update the station whose id you provided. <br> Please remember that only the description and enabled state can be changed." })
+	async put(@Param('id') id: number, @Body({ validate: true }) station: UpdateScanStation) {
+		let oldStation = await this.stationRepository.findOne({ id: id });
+
+		if (!oldStation) {
+			throw new ScanStationNotFoundError();
+		}
+
+		if (oldStation.id != station.id) {
+			throw new ScanStationIdsNotMatchingError();
+		}
+
+		await this.stationRepository.save(await station.update(oldStation));
+		await deleteStationEntry(oldStation.prefix);
+		return (await this.stationRepository.findOne({ id: id }, { relations: ['track'] })).toResponse();
+	}
+
+	@Delete('/:id')
+	@Authorized("STATION:DELETE")
+	@ResponseSchema(ResponseScanStation)
+	@ResponseSchema(ResponseEmpty, { statusCode: 204 })
+	@ResponseSchema(ScanStationHasScansError, { statusCode: 406 })
+	@OnUndefined(204)
+	@OpenAPI({ description: 'Delete the station whose id you provided. <br> If no station with this id exists it will just return 204(no content). <br> If the station still has scans associated you have to provide the force=true query param (warning: this deletes all scans associated with/created by this station - please disable it instead).' })
+	async remove(@Param("id") id: number, @QueryParam("force") force: boolean) {
+		let station = await this.stationRepository.findOne({ id: id });
+		if (!station) { return null; }
+
+		const stationScans = (await this.stationRepository.findOne({ id: station.id }, { relations: ["scans"] })).scans;
+		if (stationScans.length != 0 && !force) {
+			throw new ScanStationHasScansError();
+		}
+		const scanController = new ScanController;
+		for (let scan of stationScans) {
+			await scanController.remove(scan.id, force);
+		}
+
+		const responseStation = await this.stationRepository.findOne({ id: station.id }, { relations: ["track"] });
+		await deleteStationEntry(station.prefix);
+		await this.stationRepository.delete(station);
+		return responseStation.toResponse();
+	}
+}

src/controllers/StatsClientController.ts

@@ -0,0 +1,82 @@
+import { Authorized, Body, Delete, Get, JsonController, OnUndefined, Param, Post, QueryParam } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { Repository, getConnectionManager } from 'typeorm';
+import { StatsClientNotFoundError } from '../errors/StatsClientErrors';
+import { TrackNotFoundError } from "../errors/TrackErrors";
+import { CreateStatsClient } from '../models/actions/create/CreateStatsClient';
+import { StatsClient } from '../models/entities/StatsClient';
+import { ResponseEmpty } from '../models/responses/ResponseEmpty';
+import { ResponseStatsClient } from '../models/responses/ResponseStatsClient';
+
+@JsonController('/statsclients')
+@OpenAPI({ security: [{ "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+export class StatsClientController {
+	private clientRepository: Repository<StatsClient>;
+
+	/**
+	 * Gets the repository of this controller's model/entity.
+	 */
+	constructor() {
+		this.clientRepository = getConnectionManager().get().getRepository(StatsClient);
+	}
+
+	@Get()
+	@Authorized("STATSCLIENT:GET")
+	@ResponseSchema(ResponseStatsClient, { isArray: true })
+	@OpenAPI({ description: 'Lists all stats clients. Please remember that the key can only be viewed on creation.' })
+	async getAll(@QueryParam("page", { required: false }) page: number, @QueryParam("page_size", { required: false }) page_size: number = 100) {
+		let responseClients: ResponseStatsClient[] = new Array<ResponseStatsClient>();
+		let clients: Array<StatsClient>;
+
+		if (page != undefined) {
+			clients = await this.clientRepository.find({ skip: page * page_size, take: page_size });
+		} else {
+			clients = await this.clientRepository.find();
+		}
+
+		clients.forEach(clients => {
+			responseClients.push(new ResponseStatsClient(clients));
+		});
+		return responseClients;
+	}
+
+	@Get('/:id')
+	@Authorized("STATSCLIENT:GET")
+	@ResponseSchema(ResponseStatsClient)
+	@ResponseSchema(StatsClientNotFoundError, { statusCode: 404 })
+	@OnUndefined(StatsClientNotFoundError)
+	@OpenAPI({ description: "Lists all information about the stats client whose id got provided. Please remember that the key can only be viewed on creation." })
+	async getOne(@Param('id') id: number) {
+		let client = await this.clientRepository.findOne({ id: id });
+		if (!client) { throw new TrackNotFoundError(); }
+		return new ResponseStatsClient(client);
+	}
+
+	@Post()
+	@Authorized("STATSCLIENT:CREATE")
+	@ResponseSchema(ResponseStatsClient)
+	@OpenAPI({ description: "Create a new stats client. <br> Please remember that the client\'s key will be generated automaticly and that it can only be viewed on creation." })
+	async post(
+		@Body({ validate: true })
+		client: CreateStatsClient
+	) {
+		let newClient = await this.clientRepository.save(await client.toEntity());
+		let responseClient = new ResponseStatsClient(newClient);
+		responseClient.key = newClient.cleartextkey;
+		return responseClient;
+	}
+
+	@Delete('/:id')
+	@Authorized("STATSCLIENT:DELETE")
+	@ResponseSchema(ResponseStatsClient)
+	@ResponseSchema(ResponseEmpty, { statusCode: 204 })
+	@OnUndefined(204)
+	@OpenAPI({ description: "Delete the stats client whose id you provided. <br> If no client with this id exists it will just return 204(no content)." })
+	async remove(@Param("id") id: number, @QueryParam("force") force: boolean) {
+		let client = await this.clientRepository.findOne({ id: id });
+		if (!client) { return null; }
+
+		await this.clientRepository.delete(client);
+		return new ResponseStatsClient(client);
+	}
+}

src/controllers/StatsController.ts

@@ -0,0 +1,277 @@
+import { Get, JsonController, QueryParam, UseBefore } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { getConnection } from 'typeorm';
+import StatsAuth from '../middlewares/StatsAuth';
+import { Donation } from '../models/entities/Donation';
+import { Donor } from '../models/entities/Donor';
+import { Runner } from '../models/entities/Runner';
+import { RunnerOrganization } from '../models/entities/RunnerOrganization';
+import { RunnerTeam } from '../models/entities/RunnerTeam';
+import { Scan } from '../models/entities/Scan';
+import { TrackScan } from '../models/entities/TrackScan';
+import { User } from '../models/entities/User';
+import { ResponseStats } from '../models/responses/ResponseStats';
+import { ResponseStatsOrgnisation } from '../models/responses/ResponseStatsOrganization';
+import { ResponseStatsRunner } from '../models/responses/ResponseStatsRunner';
+import { ResponseStatsTeam } from '../models/responses/ResponseStatsTeam';
+import { getStatsCache, setStatsCache } from '../nats/StatsKV';
+
+@JsonController('/stats')
+export class StatsController {
+
+    @Get()
+    @ResponseSchema(ResponseStats)
+    @OpenAPI({ description: "A very basic stats endpoint providing basic counters for a dashboard or simmilar" })
+    async get() {
+        // Try cache first
+        const cached = await getStatsCache<ResponseStats>('overview');
+        if (cached) {
+            return cached;
+        }
+
+        // Cache miss - compute fresh stats
+        const connection = getConnection();
+        const runnersViaSelfservice = await connection.getRepository(Runner).count({ where: { created_via: "selfservice" } });
+        const runnersViaKiosk = await connection.getRepository(Runner).count({ where: { created_via: "kiosk" } });
+        const runners = await connection.getRepository(Runner).count();
+        const teams = await connection.getRepository(RunnerTeam).count();
+        const orgs = await connection.getRepository(RunnerOrganization).count();
+        const users = await connection.getRepository(User).count();
+        const scans = await connection.getRepository(Scan).count({ where: { valid: true } });
+
+        const distance_query = await connection.getRepository(Scan).createQueryBuilder('scan')
+            .leftJoinAndSelect("scan.track", "track").where("scan.valid = TRUE")
+            .select("SUM(track.distance)", "sum_track").addSelect("SUM(_distance)", "sum_distance")
+            .getRawOne();
+        let distace = parseInt(distance_query.sum_track)
+        if (distance_query.sum_distance) {
+            distace += parseInt(distance_query.sum_distance)
+        }
+
+        let donations = await connection.getRepository(Donation).find({ relations: ['runner', 'runner.scans', 'runner.scans.track'] });
+        const donors = await connection.getRepository(Donor).count();
+
+        const result = new ResponseStats(runnersViaSelfservice, runners, teams, orgs, users, scans, donations, distace, donors, runnersViaKiosk);
+
+        // Store in cache for 60 seconds
+        await setStatsCache('overview', result);
+
+        return result;
+    }
+
+    @Get("/runners/distance")
+    @UseBefore(StatsAuth)
+    @ResponseSchema(ResponseStatsRunner, { isArray: true })
+    @OpenAPI({ description: "Returns the top ten runners by distance.", security: [{ "StatsApiToken": [] }, { "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+    async getTopRunnersByDistance() {
+        // Try cache first
+        const cached = await getStatsCache<ResponseStatsRunner[]>('runners.distance');
+        if (cached) {
+            return cached;
+        }
+
+        // Cache miss - compute fresh stats
+        let runners = await getConnection().getRepository(Runner).find({ relations: ['scans', 'group', 'distanceDonations', 'scans.track'] });
+        if (!runners || runners.length == 0) {
+            return [];
+        }
+        let topRunners = runners.sort((runner1, runner2) => runner2.distance - runner1.distance).slice(0, 10);
+        let responseRunners: ResponseStatsRunner[] = new Array<ResponseStatsRunner>();
+        topRunners.forEach(runner => {
+            responseRunners.push(new ResponseStatsRunner(runner));
+        });
+
+        // Store in cache for 60 seconds
+        await setStatsCache('runners.distance', responseRunners);
+
+        return responseRunners;
+    }
+
+    @Get("/runners/donations")
+    @UseBefore(StatsAuth)
+    @ResponseSchema(ResponseStatsRunner, { isArray: true })
+    @OpenAPI({ description: "Returns the top ten runners by donations.", security: [{ "StatsApiToken": [] }, { "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+    async getTopRunnersByDonations() {
+        // Try cache first
+        const cached = await getStatsCache<ResponseStatsRunner[]>('runners.donations');
+        if (cached) {
+            return cached;
+        }
+
+        // Cache miss - compute fresh stats
+        let runners = await getConnection().getRepository(Runner).find({ relations: ['group', 'distanceDonations', 'distanceDonations.runner', 'distanceDonations.runner.scans', 'distanceDonations.runner.scans.track'] });
+        if (!runners || runners.length == 0) {
+            return [];
+        }
+        let topRunners = runners.sort((runner1, runner2) => runner2.distanceDonationAmount - runner1.distanceDonationAmount).slice(0, 10);
+        let responseRunners: ResponseStatsRunner[] = new Array<ResponseStatsRunner>();
+        topRunners.forEach(runner => {
+            responseRunners.push(new ResponseStatsRunner(runner));
+        });
+
+        // Store in cache for 60 seconds
+        await setStatsCache('runners.donations', responseRunners);
+
+        return responseRunners;
+    }
+
+    @Get("/runners/laptime")
+    @UseBefore(StatsAuth)
+    @ResponseSchema(ResponseStatsRunner, { isArray: true })
+    @OpenAPI({ description: "Returns the top ten runners by fastest laptime on your selected track (track by id).", security: [{ "StatsApiToken": [] }, { "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+    async getTopRunnersByLaptime(@QueryParam("track") track: number) {
+        // Try cache first (cache key includes track id, using dots for NATS KV compatibility)
+        const cacheKey = `runners.laptime.${track}`;
+        const cached = await getStatsCache<ResponseStatsRunner[]>(cacheKey);
+        if (cached) {
+            return cached;
+        }
+
+        // Cache miss - compute fresh stats
+        let scans = await getConnection().getRepository(TrackScan).find({ relations: ['track', 'runner', 'runner.group', 'runner.scans', 'runner.scans.track', 'runner.distanceDonations'] });
+        if (!scans || scans.length == 0) {
+            return [];
+        }
+        scans = scans.filter((s) => { return s.track.id == track && s.valid == true && s.lapTime != 0 }).sort((scan1, scan2) => scan1.lapTime - scan2.lapTime);
+
+        let topScans = new Array<TrackScan>();
+        let knownRunners = new Array<number>();
+        for (let i = 0; i < scans.length && topScans.length < 10; i++) {
+            const element = scans[i];
+            if (!knownRunners.includes(element.runner.id)) {
+                topScans.push(element);
+                knownRunners.push(element.runner.id);
+            }
+        }
+
+        let responseRunners: ResponseStatsRunner[] = new Array<ResponseStatsRunner>();
+        topScans.forEach(scan => {
+            responseRunners.push(new ResponseStatsRunner(scan.runner, scan.lapTime));
+        });
+
+        // Store in cache for 60 seconds
+        await setStatsCache(cacheKey, responseRunners);
+
+        return responseRunners;
+    }
+
+    @Get("/scans")
+    @UseBefore(StatsAuth)
+    @ResponseSchema(ResponseStatsRunner, { isArray: true })
+    @OpenAPI({ description: "Returns the top ten fastest track times (with their runner and the runner's group).", security: [{ "StatsApiToken": [] }, { "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+    async getTopRunnersByTrackTime() {
+        throw new Error("Not implemented yet.")
+    }
+
+    @Get("/teams/distance")
+    @UseBefore(StatsAuth)
+    @ResponseSchema(ResponseStatsTeam, { isArray: true })
+    @OpenAPI({ description: "Returns the top ten teams by distance.", security: [{ "StatsApiToken": [] }, { "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+    async getTopTeamsByDistance() {
+        // Try cache first
+        const cached = await getStatsCache<ResponseStatsTeam[]>('teams.distance');
+        if (cached) {
+            return cached;
+        }
+
+        // Cache miss - compute fresh stats
+        let teams = await getConnection().getRepository(RunnerTeam).find({ relations: ['parentGroup', 'runners', 'runners.scans', 'runners.scans.track'] });
+        if (!teams || teams.length == 0) {
+            return [];
+        }
+        let topTeams = teams.sort((team1, team2) => team2.distance - team1.distance).slice(0, 10);
+        let responseTeams: ResponseStatsTeam[] = new Array<ResponseStatsTeam>();
+        topTeams.forEach(team => {
+            responseTeams.push(new ResponseStatsTeam(team));
+        });
+
+        // Store in cache for 60 seconds
+        await setStatsCache('teams.distance', responseTeams);
+
+        return responseTeams;
+    }
+
+    @Get("/teams/donations")
+    @UseBefore(StatsAuth)
+    @ResponseSchema(ResponseStatsTeam, { isArray: true })
+    @OpenAPI({ description: "Returns the top ten teams by donations.", security: [{ "StatsApiToken": [] }, { "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+    async getTopTeamsByDonations() {
+        // Try cache first
+        const cached = await getStatsCache<ResponseStatsTeam[]>('teams.donations');
+        if (cached) {
+            return cached;
+        }
+
+        // Cache miss - compute fresh stats
+        let teams = await getConnection().getRepository(RunnerTeam).find({ relations: ['parentGroup', 'runners', 'runners.scans', 'runners.distanceDonations', 'runners.scans.track'] });
+        if (!teams || teams.length == 0) {
+            return [];
+        }
+        let topTeams = teams.sort((team1, team2) => team2.distanceDonationAmount - team1.distanceDonationAmount).slice(0, 10);
+        let responseTeams: ResponseStatsTeam[] = new Array<ResponseStatsTeam>();
+        topTeams.forEach(team => {
+            responseTeams.push(new ResponseStatsTeam(team));
+        });
+
+        // Store in cache for 60 seconds
+        await setStatsCache('teams.donations', responseTeams);
+
+        return responseTeams;
+    }
+
+    @Get("/organizations/distance")
+    @UseBefore(StatsAuth)
+    @ResponseSchema(ResponseStatsOrgnisation, { isArray: true })
+    @OpenAPI({ description: "Returns the top ten organizations by distance.", security: [{ "StatsApiToken": [] }, { "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+    async getTopOrgsByDistance() {
+        // Try cache first
+        const cached = await getStatsCache<ResponseStatsOrgnisation[]>('organizations.distance');
+        if (cached) {
+            return cached;
+        }
+
+        // Cache miss - compute fresh stats
+        let orgs = await getConnection().getRepository(RunnerOrganization).find({ relations: ['runners', 'runners.scans', 'runners.distanceDonations', 'runners.scans.track', 'teams', 'teams.runners', 'teams.runners.scans', 'teams.runners.distanceDonations', 'teams.runners.scans.track'] });
+        if (!orgs || orgs.length == 0) {
+            return [];
+        }
+        let topOrgs = orgs.sort((org1, org2) => org2.distance - org1.distance).slice(0, 10);
+        let responseOrgs: ResponseStatsOrgnisation[] = new Array<ResponseStatsOrgnisation>();
+        topOrgs.forEach(org => {
+            responseOrgs.push(new ResponseStatsOrgnisation(org));
+        });
+
+        // Store in cache for 60 seconds
+        await setStatsCache('organizations.distance', responseOrgs);
+
+        return responseOrgs;
+    }
+
+    @Get("/organizations/donations")
+    @UseBefore(StatsAuth)
+    @ResponseSchema(ResponseStatsOrgnisation, { isArray: true })
+    @OpenAPI({ description: "Returns the top ten organizations by donations.", security: [{ "StatsApiToken": [] }, { "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+    async getTopOrgsByDonations() {
+        // Try cache first
+        const cached = await getStatsCache<ResponseStatsOrgnisation[]>('organizations.donations');
+        if (cached) {
+            return cached;
+        }
+
+        // Cache miss - compute fresh stats
+        let orgs = await getConnection().getRepository(RunnerOrganization).find({ relations: ['runners', 'runners.distanceDonations', 'runners.distanceDonations.runner', 'runners.distanceDonations.runner.scans', 'runners.distanceDonations.runner.scans.track', 'teams', 'teams.runners', 'teams.runners.distanceDonations', 'teams.runners.distanceDonations.runner', 'teams.runners.distanceDonations.runner.scans', 'teams.runners.distanceDonations.runner.scans.track'] });
+        if (!orgs || orgs.length == 0) {
+            return [];
+        }
+        let topOrgs = orgs.sort((org1, org2) => org2.distanceDonationAmount - org1.distanceDonationAmount).slice(0, 10);
+        let responseOrgs: ResponseStatsOrgnisation[] = new Array<ResponseStatsOrgnisation>();
+        topOrgs.forEach(org => {
+            responseOrgs.push(new ResponseStatsOrgnisation(org));
+        });
+
+        // Store in cache for 60 seconds
+        await setStatsCache('organizations.donations', responseOrgs);
+
+        return responseOrgs;
+    }
+}

src/controllers/StatusController.ts

@@ -0,0 +1,31 @@
+import { Get, JsonController } from 'routing-controllers';
+import { OpenAPI } from 'routing-controllers-openapi';
+import { getConnection } from 'typeorm';
+import { config } from '../config';
+
+@JsonController()
+export class StatusController {
+
+    @Get('/status')
+    @OpenAPI({ description: "A very basic status/health endpoint that just checks if the database connection is available. <br> The available information depth will be expanded later." })
+    get() {
+        let connection;
+        try {
+            connection = getConnection();
+        } catch {
+            throw new Error("sth is wrong, i can feel it....");
+        }
+        return {
+            "controllers": "✔",
+            "database connection": "✔"
+        };
+    }
+
+    @Get('/version')
+    @OpenAPI({ description: "A very basic endpoint that just returns the curent package version." })
+    getVersion() {
+        return {
+            "version": config.version
+        }
+    }
+}

src/controllers/TrackController.ts

@@ -1,14 +1,16 @@
-import { Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put } from 'routing-controllers';
+import { Authorized, Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put, QueryParam } from 'routing-controllers';
 import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
-import { getConnectionManager, Repository } from 'typeorm';
-import { EntityFromBody, EntityFromParam } from 'typeorm-routing-controllers-extensions';
-import { TrackIdsNotMatchingError, TrackNotFoundError } from "../errors/TrackErrors";
-import { CreateTrack } from '../models/actions/CreateTrack';
+import { Repository, getConnectionManager } from 'typeorm';
+import { TrackHasScanStationsError, TrackIdsNotMatchingError, TrackLapTimeCantBeNegativeError, TrackNotFoundError } from "../errors/TrackErrors";
+import { CreateTrack } from '../models/actions/create/CreateTrack';
+import { UpdateTrack } from '../models/actions/update/UpdateTrack';
 import { Track } from '../models/entities/Track';
+import { ResponseEmpty } from '../models/responses/ResponseEmpty';
 import { ResponseTrack } from '../models/responses/ResponseTrack';
+import { ScanStationController } from './ScanStationController';
 
 @JsonController('/tracks')
-//@Authorized("TRACKS:read")
+@OpenAPI({ security: [{ "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
 export class TrackController {
 	private trackRepository: Repository<Track>;
 
@@ -20,11 +22,20 @@ export class TrackController {
 	}
 
 	@Get()
+	@Authorized("TRACK:GET")
 	@ResponseSchema(ResponseTrack, { isArray: true })
-	@OpenAPI({ description: "Lists all tracks." })
-	async getAll() {
+	@OpenAPI({ description: 'Lists all tracks.' })
+	async getAll(@QueryParam("page", { required: false }) page: number, @QueryParam("page_size", { required: false }) page_size: number = 100) {
 		let responseTracks: ResponseTrack[] = new Array<ResponseTrack>();
-		const tracks = await this.trackRepository.find();
+		let tracks: Array<Track>;
+
+		if (page != undefined) {
+			tracks = await this.trackRepository.find({ skip: page * page_size, take: page_size });
+		}
+		else {
+			tracks = await this.trackRepository.find();
+		}
+
 		tracks.forEach(track => {
 			responseTracks.push(new ResponseTrack(track));
 		});
@@ -32,50 +43,69 @@ export class TrackController {
 	}
 
 	@Get('/:id')
+	@Authorized("TRACK:GET")
 	@ResponseSchema(ResponseTrack)
 	@ResponseSchema(TrackNotFoundError, { statusCode: 404 })
 	@OnUndefined(TrackNotFoundError)
-	@OpenAPI({ description: "Returns a track of a specified id (if it exists)" })
+	@OpenAPI({ description: "Lists all information about the track whose id got provided." })
 	async getOne(@Param('id') id: number) {
-		return new ResponseTrack(await this.trackRepository.findOne({ id: id }));
+		let track = await this.trackRepository.findOne({ id: id });
+		if (!track) { throw new TrackNotFoundError(); }
+		return new ResponseTrack(track);
 	}
 
 	@Post()
+	@Authorized("TRACK:CREATE")
 	@ResponseSchema(ResponseTrack)
-	@OpenAPI({ description: "Create a new track object (id will be generated automagicly)." })
+	@ResponseSchema(TrackLapTimeCantBeNegativeError, { statusCode: 406 })
+	@OpenAPI({ description: "Create a new track. <br> Please remember that the track\'s distance must be greater than 0." })
 	async post(
 		@Body({ validate: true })
 		track: CreateTrack
 	) {
-		return new ResponseTrack(await this.trackRepository.save(track.toTrack()));
+		return new ResponseTrack(await this.trackRepository.save(await track.toEntity()));
 	}
 
 	@Put('/:id')
+	@Authorized("TRACK:UPDATE")
 	@ResponseSchema(ResponseTrack)
 	@ResponseSchema(TrackNotFoundError, { statusCode: 404 })
 	@ResponseSchema(TrackIdsNotMatchingError, { statusCode: 406 })
-	@OpenAPI({ description: "Update a track object (id can't be changed)." })
-	async put(@Param('id') id: number, @EntityFromBody() track: Track) {
+	@ResponseSchema(TrackLapTimeCantBeNegativeError, { statusCode: 406 })
+	@OpenAPI({ description: "Update the track whose id you provided. <br> Please remember that ids can't be changed." })
+	async put(@Param('id') id: number, @Body({ validate: true }) updateTrack: UpdateTrack) {
 		let oldTrack = await this.trackRepository.findOne({ id: id });
 
 		if (!oldTrack) {
 			throw new TrackNotFoundError();
 		}
 
-		if (oldTrack.id != track.id) {
+		if (oldTrack.id != updateTrack.id) {
 			throw new TrackIdsNotMatchingError();
 		}
+		await this.trackRepository.save(await updateTrack.update(oldTrack));
 
-		await this.trackRepository.update(oldTrack, track);
-		return new ResponseTrack(track);
+		return new ResponseTrack(await this.trackRepository.findOne({ id: id }));
 	}
 
 	@Delete('/:id')
+	@Authorized("TRACK:DELETE")
 	@ResponseSchema(ResponseTrack)
-	@ResponseSchema(TrackNotFoundError, { statusCode: 404 })
-	@OpenAPI({ description: "Delete a specified track (if it exists)." })
-	async remove(@EntityFromParam('id') track: Track) {
-		if (!track) { throw new TrackNotFoundError(); }
+	@ResponseSchema(ResponseEmpty, { statusCode: 204 })
+	@OnUndefined(204)
+	@OpenAPI({ description: "Delete the track whose id you provided. <br> If no track with this id exists it will just return 204(no content)." })
+	async remove(@Param("id") id: number, @QueryParam("force") force: boolean) {
+		let track = await this.trackRepository.findOne({ id: id });
+		if (!track) { return null; }
+
+		const trackStations = (await this.trackRepository.findOne({ id: id }, { relations: ["stations"] })).stations;
+		if (trackStations.length != 0 && !force) {
+			throw new TrackHasScanStationsError();
+		}
+		const stationController = new ScanStationController;
+		for (let station of trackStations) {
+			await stationController.remove(station.id, force);
+		}
 
 		await this.trackRepository.delete(track);
 		return new ResponseTrack(track);

src/controllers/UserController.ts

@@ -1,85 +1,141 @@
-import { Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put } from 'routing-controllers';
-import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
-import { getConnectionManager, Repository } from 'typeorm';
-import { EntityFromBody, EntityFromParam } from 'typeorm-routing-controllers-extensions';
-import { UserIdsNotMatchingError, UserNotFoundError } from '../errors/UserErrors';
-import { UserGroupNotFoundError } from '../errors/UserGroupErrors';
-import { CreateUser } from '../models/actions/CreateUser';
-import { User } from '../models/entities/User';
-
-
-@JsonController('/users')
-export class UserController {
-	private userRepository: Repository<User>;
-
-	/**
-	 * Gets the repository of this controller's model/entity.
-	 */
-	constructor() {
-		this.userRepository = getConnectionManager().get().getRepository(User);
-	}
-
-	@Get()
-	@ResponseSchema(User, { isArray: true })
-	@OpenAPI({ description: 'Lists all users.' })
-	getAll() {
-		return this.userRepository.find();
-	}
-
-	@Get('/:id')
-	@ResponseSchema(User)
-	@ResponseSchema(UserNotFoundError, { statusCode: 404 })
-	@OnUndefined(UserNotFoundError)
-	@OpenAPI({ description: 'Returns a user of a specified id (if it exists)' })
-	getOne(@Param('id') id: number) {
-		return this.userRepository.findOne({ id: id });
-	}
-
-	@Post()
-	@ResponseSchema(User)
-	@ResponseSchema(UserGroupNotFoundError)
-	@OpenAPI({ description: 'Create a new user object (id will be generated automagicly).' })
-	async post(@Body({ validate: true }) createUser: CreateUser) {
-		let user;
-		try {
-			user = await createUser.toUser();
-		} catch (error) {
-			return error;
-		}
-
-		return this.userRepository.save(user);
-	}
-
-	@Put('/:id')
-	@ResponseSchema(User)
-	@ResponseSchema(UserNotFoundError, { statusCode: 404 })
-	@ResponseSchema(UserIdsNotMatchingError, { statusCode: 406 })
-	@OpenAPI({ description: "Update a user object (id can't be changed)." })
-	async put(@Param('id') id: number, @EntityFromBody() user: User) {
-		let oldUser = await this.userRepository.findOne({ id: id });
-
-		if (!oldUser) {
-			throw new UserNotFoundError();
-		}
-
-		if (oldUser.id != user.id) {
-			throw new UserIdsNotMatchingError();
-		}
-
-		await this.userRepository.update(oldUser, user);
-		return user;
-	}
-
-	@Delete('/:id')
-	@ResponseSchema(User)
-	@ResponseSchema(UserNotFoundError, { statusCode: 404 })
-	@OpenAPI({ description: 'Delete a specified runner (if it exists).' })
-	async remove(@EntityFromParam('id') user: User) {
-		if (!user) {
-			throw new UserNotFoundError();
-		}
-
-		await this.userRepository.delete(user);
-		return user;
-	}
-}
+import { Authorized, Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put, QueryParam } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { Repository, getConnectionManager } from 'typeorm';
+import { PasswordMustContainLowercaseLetterError, PasswordMustContainNumberError, PasswordMustContainUppercaseLetterError, PasswordTooShortError, UserDeletionNotConfirmedError, UserIdsNotMatchingError, UserNotFoundError, UsernameContainsIllegalCharacterError } from '../errors/UserErrors';
+import { UserGroupNotFoundError } from '../errors/UserGroupErrors';
+import { CreateUser } from '../models/actions/create/CreateUser';
+import { UpdateUser } from '../models/actions/update/UpdateUser';
+import { User } from '../models/entities/User';
+import { ResponseEmpty } from '../models/responses/ResponseEmpty';
+import { ResponseUser } from '../models/responses/ResponseUser';
+import { ResponseUserPermissions } from '../models/responses/ResponseUserPermissions';
+import { PermissionController } from './PermissionController';
+
+
+@JsonController('/users')
+@OpenAPI({ security: [{ "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+export class UserController {
+	private userRepository: Repository<User>;
+
+	/**
+	 * Gets the repository of this controller's model/entity.
+	 */
+	constructor() {
+		this.userRepository = getConnectionManager().get().getRepository(User);
+	}
+
+	@Get()
+	@Authorized("USER:GET")
+	@ResponseSchema(ResponseUser, { isArray: true })
+	@OpenAPI({ description: 'Lists all users. <br> This includes their groups and permissions granted to them.' })
+	async getAll(@QueryParam("page", { required: false }) page: number, @QueryParam("page_size", { required: false }) page_size: number = 100) {
+		let responseUsers: ResponseUser[] = new Array<ResponseUser>();
+		let users: Array<User>;
+
+		if (page != undefined) {
+			users = await this.userRepository.find({ relations: ['permissions', 'groups', 'groups.permissions'], skip: page * page_size, take: page_size });
+		}
+		else {
+			users = await this.userRepository.find({ relations: ['permissions', 'groups', 'groups.permissions'] });
+		}
+
+		users.forEach(user => {
+			responseUsers.push(new ResponseUser(user));
+		});
+		return responseUsers;
+	}
+
+	@Get('/:id')
+	@Authorized("USER:GET")
+	@ResponseSchema(ResponseUser)
+	@ResponseSchema(UserNotFoundError, { statusCode: 404 })
+	@OnUndefined(UserNotFoundError)
+	@OpenAPI({ description: 'Lists all information about the user whose id got provided. <br> Please remember that all permissions granted to the user will show up here.' })
+	async getOne(@Param('id') id: number) {
+		let user = await this.userRepository.findOne({ id: id }, { relations: ['permissions', 'groups', 'groups.permissions'] })
+		if (!user) { throw new UserNotFoundError(); }
+		return new ResponseUser(user);
+	}
+
+	@Get('/:id/permissions')
+	@Authorized("USER:GET")
+	@ResponseSchema(ResponseUser)
+	@ResponseSchema(UserNotFoundError, { statusCode: 404 })
+	@OnUndefined(UserNotFoundError)
+	@OpenAPI({ description: 'Lists all permissions granted to the user sorted into directly granted and inherited as permission response objects.' })
+	async getPermissions(@Param('id') id: number) {
+		let user = await this.userRepository.findOne({ id: id }, { relations: ['permissions', 'groups', 'groups.permissions', 'permissions.principal', 'groups.permissions.principal'] })
+		if (!user) { throw new UserNotFoundError(); }
+		return new ResponseUserPermissions(user);
+	}
+
+	@Post()
+	@Authorized("USER:CREATE")
+	@ResponseSchema(ResponseUser)
+	@ResponseSchema(UserGroupNotFoundError, { statusCode: 404 })
+	@ResponseSchema(UsernameContainsIllegalCharacterError, { statusCode: 406 })
+	@ResponseSchema(PasswordMustContainUppercaseLetterError, { statusCode: 406 })
+	@ResponseSchema(PasswordMustContainLowercaseLetterError, { statusCode: 406 })
+	@ResponseSchema(PasswordMustContainNumberError, { statusCode: 406 })
+	@ResponseSchema(PasswordTooShortError, { statusCode: 406 })
+	@OpenAPI({ description: 'Create a new user. <br> If you want to grant permissions to the user you have to create them seperately by posting to /api/permissions after creating the user.' })
+	async post(@Body({ validate: true }) createUser: CreateUser) {
+		let user;
+		try {
+			user = await createUser.toEntity();
+		} catch (error) {
+			throw error;
+		}
+
+		user = await this.userRepository.save(user)
+		return new ResponseUser(await this.userRepository.findOne({ id: user.id }, { relations: ['permissions', 'groups', 'groups.permissions'] }));
+	}
+
+	@Put('/:id')
+	@Authorized("USER:UPDATE")
+	@ResponseSchema(ResponseUser)
+	@ResponseSchema(UserNotFoundError, { statusCode: 404 })
+	@ResponseSchema(UserIdsNotMatchingError, { statusCode: 406 })
+	@ResponseSchema(UsernameContainsIllegalCharacterError, { statusCode: 406 })
+	@ResponseSchema(PasswordMustContainUppercaseLetterError, { statusCode: 406 })
+	@ResponseSchema(PasswordMustContainLowercaseLetterError, { statusCode: 406 })
+	@ResponseSchema(PasswordMustContainNumberError, { statusCode: 406 })
+	@ResponseSchema(PasswordTooShortError, { statusCode: 406 })
+	@OpenAPI({ description: "Update the user whose id you provided. <br> To change the permissions directly granted to the user please use /api/permissions instead. <br> Please remember that ids can't be changed." })
+	async put(@Param('id') id: number, @Body({ validate: true }) updateUser: UpdateUser) {
+		let oldUser = await this.userRepository.findOne({ id: id });
+
+		if (!oldUser) {
+			throw new UserNotFoundError();
+		}
+
+		if (oldUser.id != updateUser.id) {
+			throw new UserIdsNotMatchingError();
+		}
+		await this.userRepository.save(await updateUser.update(oldUser));
+
+		return new ResponseUser(await this.userRepository.findOne({ id: id }, { relations: ['permissions', 'groups', 'groups.permissions'] }));
+	}
+
+	@Delete('/:id')
+	@Authorized("USER:DELETE")
+	@ResponseSchema(ResponseUser)
+	@ResponseSchema(ResponseEmpty, { statusCode: 204 })
+	@ResponseSchema(UserDeletionNotConfirmedError, { statusCode: 406 })
+	@OnUndefined(204)
+	@OpenAPI({ description: 'Delete the user whose id you provided. <br> You have to confirm your decision by providing the ?force=true query param. <br> If there are any permissions directly granted to the user they will get deleted as well. <br> If no user with this id exists it will just return 204(no content).' })
+	async remove(@Param("id") id: number, @QueryParam("force") force: boolean) {
+		if (!force) { throw new UserDeletionNotConfirmedError; }
+		let user = await this.userRepository.findOne({ id: id });
+		if (!user) { return null; }
+		const responseUser = await this.userRepository.findOne({ id: id }, { relations: ['permissions', 'groups', 'groups.permissions'] });;
+
+		const permissionControler = new PermissionController();
+		for (let permission of responseUser.permissions) {
+			await permissionControler.remove(permission.id, true);
+		}
+
+		await this.userRepository.delete(user);
+		return new ResponseUser(responseUser);
+	}
+}

src/controllers/UserGroupController.ts

@@ -1,84 +1,125 @@
-import { Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put } from 'routing-controllers';
-import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
-import { getConnectionManager, Repository } from 'typeorm';
-import { EntityFromBody, EntityFromParam } from 'typeorm-routing-controllers-extensions';
-import { UserGroupIdsNotMatchingError, UserGroupNotFoundError } from '../errors/UserGroupErrors';
-import { CreateUserGroup } from '../models/actions/CreateUserGroup';
-import { UserGroup } from '../models/entities/UserGroup';
-
-
-@JsonController('/usergroups')
-export class UserGroupController {
-	private userGroupsRepository: Repository<UserGroup>;
-
-	/**
-	 * Gets the repository of this controller's model/entity.
-	 */
-	constructor() {
-		this.userGroupsRepository = getConnectionManager().get().getRepository(UserGroup);
-	}
-
-	@Get()
-	@ResponseSchema(UserGroup, { isArray: true })
-	@OpenAPI({ description: 'Lists all usergroups.' })
-	getAll() {
-		return this.userGroupsRepository.find();
-	}
-
-	@Get('/:id')
-	@ResponseSchema(UserGroup)
-	@ResponseSchema(UserGroupNotFoundError, { statusCode: 404 })
-	@OnUndefined(UserGroupNotFoundError)
-	@OpenAPI({ description: 'Returns a usergroup of a specified id (if it exists)' })
-	getOne(@Param('id') id: number) {
-		return this.userGroupsRepository.findOne({ id: id });
-	}
-
-	@Post()
-	@ResponseSchema(UserGroup)
-	@ResponseSchema(UserGroupNotFoundError)
-	@OpenAPI({ description: 'Create a new usergroup object (id will be generated automagicly).' })
-	async post(@Body({ validate: true }) createUserGroup: CreateUserGroup) {
-		let userGroup;
-		try {
-			userGroup = await createUserGroup.toUserGroup();
-		} catch (error) {
-			return error;
-		}
-
-		return this.userGroupsRepository.save(userGroup);
-	}
-
-	@Put('/:id')
-	@ResponseSchema(UserGroup)
-	@ResponseSchema(UserGroupNotFoundError, { statusCode: 404 })
-	@ResponseSchema(UserGroupIdsNotMatchingError, { statusCode: 406 })
-	@OpenAPI({ description: "Update a usergroup object (id can't be changed)." })
-	async put(@Param('id') id: number, @EntityFromBody() userGroup: UserGroup) {
-		let oldUserGroup = await this.userGroupsRepository.findOne({ id: id });
-
-		if (!oldUserGroup) {
-			throw new UserGroupNotFoundError()
-		}
-
-		if (oldUserGroup.id != userGroup.id) {
-			throw new UserGroupIdsNotMatchingError();
-		}
-
-		await this.userGroupsRepository.update(oldUserGroup, userGroup);
-		return userGroup;
-	}
-
-	@Delete('/:id')
-	@ResponseSchema(UserGroup)
-	@ResponseSchema(UserGroupNotFoundError, { statusCode: 404 })
-	@OpenAPI({ description: 'Delete a specified usergroup (if it exists).' })
-	async remove(@EntityFromParam('id') group: UserGroup) {
-		if (!group) {
-			throw new UserGroupNotFoundError();
-		}
-
-		await this.userGroupsRepository.delete(group);
-		return group;
-	}
-}
+import { Authorized, Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put, QueryParam } from 'routing-controllers';
+import { OpenAPI, ResponseSchema } from 'routing-controllers-openapi';
+import { Repository, getConnectionManager } from 'typeorm';
+import { UserGroupIdsNotMatchingError, UserGroupNotFoundError } from '../errors/UserGroupErrors';
+import { CreateUserGroup } from '../models/actions/create/CreateUserGroup';
+import { UpdateUserGroup } from '../models/actions/update/UpdateUserGroup';
+import { UserGroup } from '../models/entities/UserGroup';
+import { ResponseEmpty } from '../models/responses/ResponseEmpty';
+import { ResponseUserGroup } from '../models/responses/ResponseUserGroup';
+import { ResponseUserGroupPermissions } from '../models/responses/ResponseUserGroupPermissions';
+import { PermissionController } from './PermissionController';
+
+
+@JsonController('/usergroups')
+@OpenAPI({ security: [{ "AuthToken": [] }, { "RefreshTokenCookie": [] }] })
+export class UserGroupController {
+	private userGroupsRepository: Repository<UserGroup>;
+
+	/**
+	 * Gets the repository of this controller's model/entity.
+	 */
+	constructor() {
+		this.userGroupsRepository = getConnectionManager().get().getRepository(UserGroup);
+	}
+
+	@Get()
+	@Authorized("USERGROUP:GET")
+	@ResponseSchema(ResponseUserGroup, { isArray: true })
+	@OpenAPI({ description: 'Lists all groups. <br> The information provided might change while the project continues to evolve.' })
+	async getAll(@QueryParam("page", { required: false }) page: number, @QueryParam("page_size", { required: false }) page_size: number = 100) {
+		let responseGroups: ResponseUserGroup[] = new Array<ResponseUserGroup>();
+		let groups: Array<UserGroup>;
+
+		if (page != undefined) {
+			groups = await this.userGroupsRepository.find({ relations: ['permissions'], skip: page * page_size, take: page_size });
+		} else {
+			groups = await this.userGroupsRepository.find({ relations: ['permissions'] });
+		}
+
+		groups.forEach(group => {
+			responseGroups.push(group.toResponse());
+		});
+		return responseGroups;
+	}
+
+	@Get('/:id')
+	@Authorized("USERGROUP:GET")
+	@ResponseSchema(ResponseUserGroup)
+	@ResponseSchema(UserGroupNotFoundError, { statusCode: 404 })
+	@OnUndefined(UserGroupNotFoundError)
+	@OpenAPI({ description: 'Lists all information about the group whose id got provided. <br> The information provided might change while the project continues to evolve.' })
+	async getOne(@Param('id') id: number) {
+		return await (await (this.userGroupsRepository.findOne({ id: id }, { relations: ["permissions"] }))).toResponse();
+	}
+
+	@Get('/:id/permissions')
+	@Authorized("USERGROUP:GET")
+	@ResponseSchema(ResponseUserGroupPermissions)
+	@ResponseSchema(UserGroupNotFoundError, { statusCode: 404 })
+	@OnUndefined(UserGroupNotFoundError)
+	@OpenAPI({ description: 'Lists all permissions granted to the group as permission response objects.' })
+	async getPermissions(@Param('id') id: number) {
+		let group = await this.userGroupsRepository.findOne({ id: id }, { relations: ['permissions', 'permissions.principal'] })
+		if (!group) { throw new UserGroupNotFoundError(); }
+		return new ResponseUserGroupPermissions(group);
+	}
+
+	@Post()
+	@Authorized("USERGROUP:CREATE")
+	@ResponseSchema(UserGroup)
+	@ResponseSchema(UserGroupNotFoundError)
+	@OpenAPI({ description: 'Create a new group. <br> If you want to grant permissions to the group you have to create them seperately by posting to /api/permissions after creating the group.' })
+	async post(@Body({ validate: true }) createUserGroup: CreateUserGroup) {
+		let userGroup;
+		try {
+			userGroup = await createUserGroup.toEntity();
+		} catch (error) {
+			throw error;
+		}
+
+		userGroup = await this.userGroupsRepository.save(userGroup);
+		return (await (this.userGroupsRepository.findOne({ id: userGroup.id }, { relations: ["permissions"] }))).toResponse();
+	}
+
+	@Put('/:id')
+	@Authorized("USERGROUP:UPDATE")
+	@ResponseSchema(UserGroup)
+	@ResponseSchema(UserGroupNotFoundError, { statusCode: 404 })
+	@ResponseSchema(UserGroupIdsNotMatchingError, { statusCode: 406 })
+	@OpenAPI({ description: "Update the group whose id you provided. <br> To change the permissions granted to the group please use /api/permissions instead. <br> Please remember that ids can't be changed." })
+	async put(@Param('id') id: number, @Body({ validate: true }) updateGroup: UpdateUserGroup) {
+		let oldGroup = await this.userGroupsRepository.findOne({ id: id });
+
+		if (!oldGroup) {
+			throw new UserGroupNotFoundError();
+		}
+
+		if (oldGroup.id != updateGroup.id) {
+			throw new UserGroupIdsNotMatchingError();
+		}
+		await this.userGroupsRepository.save(await updateGroup.update(oldGroup));
+
+		return (await this.userGroupsRepository.findOne({ id: id }, { relations: ['permissions'] })).toResponse();
+	}
+
+	@Delete('/:id')
+	@Authorized("USERGROUP:DELETE")
+	@ResponseSchema(ResponseUserGroup)
+	@ResponseSchema(ResponseEmpty, { statusCode: 204 })
+	@OnUndefined(204)
+	@OpenAPI({ description: 'Delete the group whose id you provided. <br> If there are any permissions directly granted to the group they will get deleted as well. <br> Users associated with this group won\'t get deleted - just deassociated. <br> If no group with this id exists it will just return 204(no content).' })
+	async remove(@Param("id") id: number, @QueryParam("force") force: boolean) {
+		let group = await this.userGroupsRepository.findOne({ id: id });
+		if (!group) { return null; }
+		const responseGroup = await this.userGroupsRepository.findOne({ id: id }, { relations: ['permissions'] });
+
+		const permissionController = new PermissionController();
+		for (let permission of responseGroup.permissions) {
+			await permissionController.remove(permission.id, true);
+		}
+
+		await this.userGroupsRepository.delete(group);
+		return new ResponseUserGroup(responseGroup);
+	}
+}

src/errors/AddressErrors.ts

@@ -1,24 +1,57 @@
 import { IsString } from 'class-validator';
-import { NotAcceptableError, NotFoundError } from 'routing-controllers';
+import { BadRequestError } from 'routing-controllers';
 
 /**
- * Error to throw, when to provided address doesn't belong to the accepted types.
+ * Error to throw when an address's postal code fails validation.
  */
-export class AddressWrongTypeError extends NotAcceptableError {
+export class AddressPostalCodeInvalidError extends BadRequestError {
 	@IsString()
-	name = "AddressWrongTypeError"
+	name = "AddressPostalCodeInvalidError"
 
 	@IsString()
-	message = "The address must be an existing adress's id. \n You provided a object of another type."
+	message = "The postal code you provided is invalid. \n Please check if your postal code follows the postal code validation guidelines."
 }
 
 /**
- * Error to throw, when a non-existant address get's loaded.
+ * Error to throw when an non-empty address's first line isn't set.
  */
-export class AddressNotFoundError extends NotFoundError {
+export class AddressFirstLineEmptyError extends BadRequestError {
 	@IsString()
-	name = "AddressNotFoundError"
+	name = "AddressFirstLineEmptyError"
 
 	@IsString()
-	message = "The address you provided couldn't be located in the system. \n Please check your request."
+	message = "You provided a empty first address line. \n If you want an empty address please set all propertys to null. \n For non-empty addresses the following fields have to be set: address1, postalcode, city, country"
+}
+
+/**
+ * Error to throw when an non-empty address's postal code isn't set.
+ */
+export class AddressPostalCodeEmptyError extends BadRequestError {
+	@IsString()
+	name = "AddressPostalCodeEmptyError"
+
+	@IsString()
+	message = "You provided a empty postal code. \n If you want an empty address please set all propertys to null. \n For non-empty addresses the following fields have to be set: address1, postalcode, city, country"
+}
+
+/**
+ * Error to throw when an non-empty address's city isn't set.
+ */
+export class AddressCityEmptyError extends BadRequestError {
+	@IsString()
+	name = "AddressCityEmptyError"
+
+	@IsString()
+	message = "You provided a empty city. \n If you want an empty address please set all propertys to null. \n For non-empty addresses the following fields have to be set: address1, postalcode, city, country"
+}
+
+/**
+ * Error to throw when an non-empty address's country isn't set.
+ */
+export class AddressCountryEmptyError extends BadRequestError {
+	@IsString()
+	name = "AddressCountryEmptyError"
+
+	@IsString()
+	message = "You provided a empty country. \n If you want an empty address please set all propertys to null. \n For non-empty addresses the following fields have to be set: address1, postalcode, city, country"
 }

src/errors/AuthError.ts

@@ -1,63 +1,57 @@
 import { IsString } from 'class-validator';
 import { ForbiddenError, NotAcceptableError, NotFoundError, UnauthorizedError } from 'routing-controllers';
 
-/**
- * Error to throw when a jwt is expired.
- */
-export class ExpiredJWTError extends UnauthorizedError {
-	@IsString()
-	name = "ExpiredJWTError"
-
-	@IsString()
-	message = "your provided jwt is expired"
-}
-
 /**
  * Error to throw when a jwt could not be parsed.
+ * For example: Wrong signature or expired.
  */
 export class IllegalJWTError extends UnauthorizedError {
 	@IsString()
 	name = "IllegalJWTError"
 
 	@IsString()
-	message = "your provided jwt could not be parsed"
+	message = "Your provided jwt could not be parsed."
 }
 
 /**
  * Error to throw when user is nonexistant or refreshtoken is invalid.
+ * This can happen if someone provides a JWT with a invalid user id or the refreshTokenCount of the user is higher that the provided jwt's is.
  */
 export class UserNonexistantOrRefreshtokenInvalidError extends UnauthorizedError {
 	@IsString()
 	name = "UserNonexistantOrRefreshtokenInvalidError"
 
 	@IsString()
-	message = "user is nonexistant or refreshtoken is invalid"
+	message = "User is nonexistant or refreshtoken is invalid."
 }
 
 /**
  * Error to throw when provided credentials are invalid.
+ * We don't have seperate errors for username/mail and passwords to protect against guessing attacks.
  */
 export class InvalidCredentialsError extends UnauthorizedError {
 	@IsString()
 	name = "InvalidCredentialsError"
 
 	@IsString()
-	message = "your provided credentials are invalid"
+	message = "Your provided credentials are invalid."
 }
 
 /**
  * Error to throw when a jwt does not have permission for this route/action.
+ * Mainly used be the @Authorized decorator (via the authchecker).
  */
 export class NoPermissionError extends ForbiddenError {
 	@IsString()
 	name = "NoPermissionError"
 
 	@IsString()
-	message = "your provided jwt does not have permission for this route/ action"
+	message = "Your provided jwt does not have permission for this route/ action."
 }
 
 /**
  * Error to throw when no username and no email is set.
+ * Because we have to identify users somehow.
  */
 export class UsernameOrEmailNeededError extends NotAcceptableError {
 	@IsString()
@@ -68,56 +62,79 @@ export class UsernameOrEmailNeededError extends NotAcceptableError {
 }
 
 /**
- * Error to throw when no password is provided.
+ * Error to throw when no password is provided for a new user.
+ * Passwords are the minimum we need for user security.
  */
 export class PasswordNeededError extends NotAcceptableError {
 	@IsString()
 	name = "PasswordNeededError"
 
 	@IsString()
-	message = "no password is provided - you need to provide it"
+	message = "No password is provided - you need to provide it."
 }
 
 /**
- * Error to throw when no user could be found mating the provided credential.
+ * Error to throw when no user could be found for a certain query.
  */
 export class UserNotFoundError extends NotFoundError {
 	@IsString()
 	name = "UserNotFoundError"
 
 	@IsString()
-	message = "no user could be found for provided credential"
+	message = "The user you provided couldn't be located in the system. \n Please check your request."
 }
 
 /**
- * Error to throw when no jwt token was provided (but one had to be).
+ * Error to throw when no jwt was provided (but one had to be).
  */
 export class JwtNotProvidedError extends NotAcceptableError {
 	@IsString()
 	name = "JwtNotProvidedError"
 
 	@IsString()
-	message = "no jwt token was provided"
+	message = "No jwt was provided."
 }
 
 /**
- * Error to throw when user was not found or refresh token count was invalid.
+ * Error to throw when user was not found or the jwt's refresh token count was invalid.
  */
 export class UserNotFoundOrRefreshTokenCountInvalidError extends NotAcceptableError {
 	@IsString()
 	name = "UserNotFoundOrRefreshTokenCountInvalidError"
 
 	@IsString()
-	message = "user was not found or refresh token count was invalid"
+	message = "User was not found or the refresh token count is invalid."
 }
 
 /**
- * Error to thow when refresh token count was invalid
+ * Error to throw when refresh token count was invalid
  */
 export class RefreshTokenCountInvalidError extends NotAcceptableError {
 	@IsString()
 	name = "RefreshTokenCountInvalidError"
 
 	@IsString()
-	message = "refresh token count was invalid"
+	message = "Refresh token count is invalid."
+}
+
+/**
+ * Error to throw when someone tries to reset a user's password more than once in 15 minutes.
+ */
+export class ResetAlreadyRequestedError extends NotAcceptableError {
+	@IsString()
+	name = "ResetAlreadyRequestedError"
+
+	@IsString()
+	message = "You already requested a password reset in the last 15 minutes. \n Please wait until the old reset code expires before requesting a new one."
+}
+
+/**
+ * Error to throw when someone tries a disabled user's password or login as a disabled user.
+ */
+export class UserDisabledError extends NotAcceptableError {
+	@IsString()
+	name = "UserDisabledError"
+
+	@IsString()
+	message = "This user is currently disabled. \n Please contact your administrator if this is a mistake."
 }

src/errors/DonationErrors.ts

@@ -0,0 +1,25 @@
+import { IsString } from 'class-validator';
+import { NotAcceptableError, NotFoundError } from 'routing-controllers';
+
+/**
+ * Error to throw when a Donation couldn't be found.
+ */
+export class DonationNotFoundError extends NotFoundError {
+	@IsString()
+	name = "DonationNotFoundError"
+
+	@IsString()
+	message = "Donation not found!"
+}
+
+/**
+ * Error to throw when two Donations' ids don't match.
+ * Usually occurs when a user tries to change a Donation's id.
+ */
+export class DonationIdsNotMatchingError extends NotAcceptableError {
+	@IsString()
+	name = "DonationIdsNotMatchingError"
+
+	@IsString()
+	message = "The ids don't match! \n And if you wanted to change a Donation's id: This isn't allowed!"
+}

src/errors/DonorErrors.ts

@@ -0,0 +1,47 @@
+import { IsString } from 'class-validator';
+import { NotAcceptableError, NotFoundError } from 'routing-controllers';
+
+/**
+ * Error to throw when a donor couldn't be found.
+ */
+export class DonorNotFoundError extends NotFoundError {
+	@IsString()
+	name = "DonorNotFoundError"
+
+	@IsString()
+	message = "Donor not found!"
+}
+
+/**
+ * Error to throw when two donors' ids don't match.
+ * Usually occurs when a user tries to change a donor's id.
+ */
+export class DonorIdsNotMatchingError extends NotAcceptableError {
+	@IsString()
+	name = "DonorIdsNotMatchingError"
+
+	@IsString()
+	message = "The ids don't match! \n And if you wanted to change a donor's id: This isn't allowed!"
+}
+
+/**
+ * Error to throw when a donor needs a receipt, but no address is associated with them.
+ */
+export class DonorReceiptAddressNeededError extends NotAcceptableError {
+	@IsString()
+	name = "DonorReceiptAddressNeededError"
+
+	@IsString()
+	message = "An address is needed to create a receipt for a donor. \n You didn't provide one."
+}
+
+/**
+* Error to throw when a donor still has donations associated.
+*/
+export class DonorHasDonationsError extends NotAcceptableError {
+	@IsString()
+	name = "DonorHasDonationsError"
+
+	@IsString()
+	message = "This donor still has donations associated with it. \n If you want to delete this donor with all it's donations and teams add `?force` to your query."
+}

src/errors/GroupContactErrors.ts

@@ -2,18 +2,7 @@ import { IsString } from 'class-validator';
 import { NotAcceptableError, NotFoundError } from 'routing-controllers';
 
 /**
- * Error to throw, when a provided groupContact doesn't belong to the accepted types.
- */
-export class GroupContactWrongTypeError extends NotAcceptableError {
-	@IsString()
-	name = "GroupContactWrongTypeError"
-
-	@IsString()
-	message = "The groupContact must be an existing groupContact's id. \n You provided a object of another type."
-}
-
-/**
- * Error to throw, when a non-existant groupContact get's loaded.
+ * Error to throw, when a non-existent contact get's requested.
  */
 export class GroupContactNotFoundError extends NotFoundError {
 	@IsString()
@@ -21,4 +10,16 @@ export class GroupContactNotFoundError extends NotFoundError {
 
 	@IsString()
 	message = "The groupContact you provided couldn't be located in the system. \n Please check your request."
-}
+}
+
+/**
+ * Error to throw when two contacts' ids don't match.
+ * Usually occurs when a user tries to change a contact's id.
+ */
+export class GroupContactIdsNotMatchingError extends NotAcceptableError {
+	@IsString()
+	name = "GroupContactIdsNotMatchingError"
+
+	@IsString()
+	message = "The ids don't match! \n And if you wanted to change a contact's id: This isn't allowed!"
+}

src/errors/MailErrors.ts

@@ -0,0 +1,17 @@
+import { IsString } from 'class-validator';
+import { InternalServerError } from 'routing-controllers';
+
+/**
+ * Error to throw when a permission couldn't be found.
+ */
+export class MailSendingError extends InternalServerError {
+    @IsString()
+    name = "MailSendingError"
+
+    @IsString()
+    message = "We had a problem sending the mail!"
+
+    constructor() {
+        super("We had a problem sending the mail!");
+    }
+}

src/errors/PermissionErrors.ts

@@ -0,0 +1,36 @@
+import { IsString } from 'class-validator';
+import { NotAcceptableError, NotFoundError } from 'routing-controllers';
+
+/**
+ * Error to throw when a permission couldn't be found.
+ */
+export class PermissionNotFoundError extends NotFoundError {
+	@IsString()
+	name = "PermissionNotFoundError"
+
+	@IsString()
+	message = "Permission not found!"
+}
+
+/**
+ * Error to throw when two permissions' ids don't match.
+ * Usually occurs when a user tries to change a permission's id.
+ */
+export class PermissionIdsNotMatchingError extends NotAcceptableError {
+	@IsString()
+	name = "PermissionIdsNotMatchingError"
+
+	@IsString()
+	message = "The ids don't match! \n And if you wanted to change a permission's id: This isn't allowed!"
+}
+
+/**
+ * Error to throw when a permission gets provided without a principal.
+ */
+export class PermissionNeedsPrincipalError extends NotAcceptableError {
+	@IsString()
+	name = "PermissionNeedsPrincipalError"
+
+	@IsString()
+	message = "You provided no principal for this permission."
+}

src/errors/PrincipalErrors.ts

@@ -0,0 +1,24 @@
+import { IsString } from 'class-validator';
+import { NotAcceptableError, NotFoundError } from 'routing-controllers';
+
+/**
+ * Error to throw when a user couldn't be found.
+ */
+export class PrincipalNotFoundError extends NotFoundError {
+	@IsString()
+	name = "PrincipalNotFoundError"
+
+	@IsString()
+	message = "Principal not found!"
+}
+
+/**
+ * Error to throw, when a provided runner organization doesn't belong to the accepted types.
+ */
+export class PrincipalWrongTypeError extends NotAcceptableError {
+	@IsString()
+	name = "PrincipalWrongTypeError"
+
+	@IsString()
+	message = "The principal must have an existing principal's id. \n You provided a object of another type."
+}

src/errors/RunnerCardErrors.ts

@@ -0,0 +1,48 @@
+import { IsString } from 'class-validator';
+import { NotAcceptableError, NotFoundError } from 'routing-controllers';
+
+/**
+ * Error to throw when a card couldn't be found.
+ */
+export class RunnerCardNotFoundError extends NotFoundError {
+	@IsString()
+	name = "RunnerCardNotFoundError"
+
+	@IsString()
+	message = "Card not found!"
+}
+
+/**
+ * Error to throw when two cards' ids don't match.
+ * Usually occurs when a user tries to change a card's id.
+ */
+export class RunnerCardIdsNotMatchingError extends NotAcceptableError {
+	@IsString()
+	name = "RunnerCardIdsNotMatchingError"
+
+	@IsString()
+	message = "The ids don't match! \n And if you wanted to change a cards's id: This isn't allowed"
+}
+
+/**
+ * Error to throw when a card still has scans associated.
+ */
+export class RunnerCardHasScansError extends NotAcceptableError {
+	@IsString()
+	name = "RunnerCardHasScansError"
+
+	@IsString()
+	message = "This card still has scans associated with it. \n If you want to delete this card with all it's scans add `?force` to your query. \n Otherwise please consider just disabling it."
+}
+
+/**
+ * Error to throw when a card's id is too big to generate a ean-13 barcode for it.
+ * This error should never reach a end user.
+ */
+export class RunnerCardIdOutOfRangeError extends Error {
+	@IsString()
+	name = "RunnerCardIdOutOfRangeError"
+
+	@IsString()
+	message = "The card's id is too big to fit into a ean-13 barcode. \n This has a very low probability of happening but means that you might want to switch your barcode format for something that can accept numbers over 9999999999."
+}

src/errors/RunnerErrors.ts

@@ -3,7 +3,6 @@ import { NotAcceptableError, NotFoundError } from 'routing-controllers';
 
 /**
  * Error to throw when a runner couldn't be found.
- * Implemented this ways to work with the json-schema conversion for openapi.
  */
 export class RunnerNotFoundError extends NotFoundError {
 	@IsString()
@@ -16,14 +15,13 @@ export class RunnerNotFoundError extends NotFoundError {
 /**
  * Error to throw when two runners' ids don't match.
  * Usually occurs when a user tries to change a runner's id.
- * Implemented this ways to work with the json-schema conversion for openapi.
  */
 export class RunnerIdsNotMatchingError extends NotAcceptableError {
 	@IsString()
 	name = "RunnerIdsNotMatchingError"
 
 	@IsString()
-	message = "The id's don't match!! \n And if you wanted to change a runner's id: This isn't allowed"
+	message = "The ids don't match! \n And if you wanted to change a runner's id: This isn't allowed!"
 }
 
 /**
@@ -34,5 +32,38 @@ export class RunnerGroupNeededError extends NotAcceptableError {
 	name = "RunnerGroupNeededError"
 
 	@IsString()
-	message = "Runner's need to be part of one group (team or organisiation)! \n You provided neither."
+	message = "Runner's need to be part of one group (team or organization)! \n You provided neither."
+}
+
+/**
+ * Error to throw when a citizen runner has no mail-address.
+ */
+export class RunnerEmailNeededError extends NotAcceptableError {
+	@IsString()
+	name = "RunnerEmailNeededError"
+
+	@IsString()
+	message = "Citizenrunners have to provide an email address for verification and contacting."
+}
+
+/**
+ * Error to throw when a runner already requested a new selfservice link in the last 30s.
+ */
+export class RunnerSelfserviceTimeoutError extends NotAcceptableError {
+	@IsString()
+	name = "RunnerSelfserviceTimeoutError"
+
+	@IsString()
+	message = "You can only reqest a new token every 30s."
+}
+
+/**
+* Error to throw when a runner still has distance donations associated.
+*/
+export class RunnerHasDistanceDonationsError extends NotAcceptableError {
+	@IsString()
+	name = "RunnerHasDistanceDonationsError"
+
+	@IsString()
+	message = "This runner still has distance donations associated with it. \n If you want to delete this runner with all it's donations and teams add `?force` to your query."
 }

src/errors/RunnerGroupErrors.ts

@@ -3,7 +3,6 @@ import { NotFoundError } from 'routing-controllers';
 
 /**
  * Error to throw when a runner group couldn't be found.
- * Implemented this ways to work with the json-schema conversion for openapi.
  */
 export class RunnerGroupNotFoundError extends NotFoundError {
 	@IsString()

src/errors/RunnerOrganisationErrors.ts

@@ -1,62 +0,0 @@
-import { IsString } from 'class-validator';
-import { NotAcceptableError, NotFoundError } from 'routing-controllers';
-
-/**
- * Error to throw when a runner organisation couldn't be found.
- * Implemented this ways to work with the json-schema conversion for openapi.
- */
-export class RunnerOrganisationNotFoundError extends NotFoundError {
-	@IsString()
-	name = "RunnerOrganisationNotFoundError"
-
-	@IsString()
-	message = "RunnerOrganisation not found!"
-}
-
-/**
- * Error to throw when two runner organisations' ids don't match.
- * Usually occurs when a user tries to change a runner's id.
- * Implemented this way to work with the json-schema conversion for openapi.
- */
-export class RunnerOrganisationIdsNotMatchingError extends NotAcceptableError {
-	@IsString()
-	name = "RunnerOrganisationIdsNotMatchingError"
-
-	@IsString()
-	message = "The id's don't match!! \n And if you wanted to change a runner's id: This isn't allowed"
-}
-
-/**
- * Error to throw when a organisation still has runners associated.
- * Implemented this waysto work with the json-schema conversion for openapi.
- */
-export class RunnerOrganisationHasRunnersError extends NotAcceptableError {
-	@IsString()
-	name = "RunnerOrganisationHasRunnersError"
-
-	@IsString()
-	message = "This organisation still has runners associated with it. \n If you want to delete this organisation with all it's runners and teams ass `?force` to your query."
-}
-
-/**
- * Error to throw when a organisation still has runners associated.
- * Implemented this waysto work with the json-schema conversion for openapi.
- */
-export class RunnerOrganisationHasTeamsError extends NotAcceptableError {
-	@IsString()
-	name = "RunnerOrganisationHasTeamsError"
-
-	@IsString()
-	message = "This organisation still has teams associated with it. \n If you want to delete this organisation with all it's runners and teams ass `?force` to your query."
-}
-
-/**
- * Error to throw, when a provided runnerOrganisation doesn't belong to the accepted types.
- */
-export class RunnerOrganisationWrongTypeError extends NotAcceptableError {
-	@IsString()
-	name = "RunnerOrganisationWrongTypeError"
-
-	@IsString()
-	message = "The runner organisation must be an existing organisation's id. \n You provided a object of another type."
-}

src/errors/RunnerOrganizationErrors.ts

@@ -0,0 +1,58 @@
+import { IsString } from 'class-validator';
+import { NotAcceptableError, NotFoundError } from 'routing-controllers';
+
+/**
+ * Error to throw when a runner organization couldn't be found.
+ */
+export class RunnerOrganizationNotFoundError extends NotFoundError {
+	@IsString()
+	name = "RunnerOrganizationNotFoundError"
+
+	@IsString()
+	message = "RunnerOrganization not found!"
+}
+
+/**
+ * Error to throw when two runner organization's ids don't match.
+ * Usually occurs when a user tries to change a runner organization's id.
+ */
+export class RunnerOrganizationIdsNotMatchingError extends NotAcceptableError {
+	@IsString()
+	name = "RunnerOrganizationIdsNotMatchingError"
+
+	@IsString()
+	message = "The ids don't match! \n And if you wanted to change a runner organization's id: This isn't allowed!"
+}
+
+/**
+ * Error to throw when a organization still has runners associated.
+ */
+export class RunnerOrganizationHasRunnersError extends NotAcceptableError {
+	@IsString()
+	name = "RunnerOrganizationHasRunnersError"
+
+	@IsString()
+	message = "This organization still has runners associated with it. \n If you want to delete this organization with all it's runners and teams add `?force` to your query."
+}
+
+/**
+ * Error to throw when a organization still has teams associated.
+ */
+export class RunnerOrganizationHasTeamsError extends NotAcceptableError {
+	@IsString()
+	name = "RunnerOrganizationHasTeamsError"
+
+	@IsString()
+	message = "This organization still has teams associated with it. \n If you want to delete this organization with all it's runners and teams add `?force` to your query."
+}
+
+/**
+ * Error to throw, when a provided runnerOrganization doesn't belong to the accepted types.
+ */
+export class RunnerOrganizationWrongTypeError extends NotAcceptableError {
+	@IsString()
+	name = "RunnerOrganizationWrongTypeError"
+
+	@IsString()
+	message = "The runner organization must be an existing organization's id. \n You provided a object of another type."
+}

src/errors/RunnerTeamErrors.ts

@@ -3,7 +3,6 @@ import { NotAcceptableError, NotFoundError } from 'routing-controllers';
 
 /**
  * Error to throw when a runner team couldn't be found.
- * Implemented this ways to work with the json-schema conversion for openapi.
  */
 export class RunnerTeamNotFoundError extends NotFoundError {
 	@IsString()
@@ -15,37 +14,34 @@ export class RunnerTeamNotFoundError extends NotFoundError {
 
 /**
  * Error to throw when two runner teams' ids don't match.
- * Usually occurs when a user tries to change a runner's id.
- * Implemented this way to work with the json-schema conversion for openapi.
+ * Usually occurs when a user tries to change a runner team's id.
  */
 export class RunnerTeamIdsNotMatchingError extends NotAcceptableError {
 	@IsString()
 	name = "RunnerTeamIdsNotMatchingError"
 
 	@IsString()
-	message = "The id's don't match!! \n And if you wanted to change a runner's id: This isn't allowed"
+	message = "The ids don't match! \n And if you wanted to change a runner's id: This isn't allowed!"
 }
 
 /**
  * Error to throw when a team still has runners associated.
- * Implemented this waysto work with the json-schema conversion for openapi.
  */
 export class RunnerTeamHasRunnersError extends NotAcceptableError {
 	@IsString()
 	name = "RunnerTeamHasRunnersError"
 
 	@IsString()
-	message = "This team still has runners associated with it. \n If you want to delete this team with all it's runners and teams ass `?force` to your query."
+	message = "This team still has runners associated with it. \n If you want to delete this team with all it's runners and teams add `?force` to your query."
 }
 
 /**
  * Error to throw when a team still has runners associated.
- * Implemented this waysto work with the json-schema conversion for openapi.
  */
 export class RunnerTeamNeedsParentError extends NotAcceptableError {
 	@IsString()
 	name = "RunnerTeamNeedsParentError"
 
 	@IsString()
-	message = "You provided no runner organisation as this team's parent group."
+	message = "You provided no runner organization as this team's parent group."
 }

src/errors/ScanErrors.ts

@@ -0,0 +1,25 @@
+import { IsString } from 'class-validator';
+import { NotAcceptableError, NotFoundError } from 'routing-controllers';
+
+/**
+ * Error to throw when a Scan couldn't be found.
+ */
+export class ScanNotFoundError extends NotFoundError {
+	@IsString()
+	name = "ScanNotFoundError"
+
+	@IsString()
+	message = "Scan not found!"
+}
+
+/**
+ * Error to throw when two Scans' ids don't match.
+ * Usually occurs when a user tries to change a Scan's id.
+ */
+export class ScanIdsNotMatchingError extends NotAcceptableError {
+	@IsString()
+	name = "ScanIdsNotMatchingError"
+
+	@IsString()
+	message = "The ids don't match! \n And if you wanted to change a Scan's id: This isn't allowed!"
+}

src/errors/ScanStationErrors.ts

@@ -0,0 +1,36 @@
+import { IsString } from 'class-validator';
+import { NotAcceptableError, NotFoundError } from 'routing-controllers';
+
+/**
+ * Error to throw, when a non-existent scan station get's loaded.
+ */
+export class ScanStationNotFoundError extends NotFoundError {
+	@IsString()
+	name = "ScanStationNotFoundError"
+
+	@IsString()
+	message = "The scan station you provided couldn't be located in the system. \n Please check your request."
+}
+
+/**
+ * Error to throw when two scan stations' ids don't match.
+ * Usually occurs when a user tries to change a scan station's id.
+ */
+export class ScanStationIdsNotMatchingError extends NotAcceptableError {
+	@IsString()
+	name = "ScanStationIdsNotMatchingError"
+
+	@IsString()
+	message = "The ids don't match! \n And if you wanted to change a scan station's id: This isn't allowed!"
+}
+
+/**
+ * Error to throw when a station still has scans associated.
+ */
+export class ScanStationHasScansError extends NotAcceptableError {
+	@IsString()
+	name = "ScanStationHasScansError"
+
+	@IsString()
+	message = "This station still has scans associated with it. \n If you want to delete this station with all it's scans add `?force` to your query."
+}

src/errors/StatsClientErrors.ts

@@ -0,0 +1,25 @@
+import { IsString } from 'class-validator';
+import { NotAcceptableError, NotFoundError } from 'routing-controllers';
+
+/**
+ * Error to throw, when a non-existent stats client get's loaded.
+ */
+export class StatsClientNotFoundError extends NotFoundError {
+	@IsString()
+	name = "StatsClientNotFoundError"
+
+	@IsString()
+	message = "The stats client you provided couldn't be located in the system. \n Please check your request."
+}
+
+/**
+ * Error to throw when two stats clients' ids don't match.
+ * Usually occurs when a user tries to change a stats client's id.
+ */
+export class StatsClientIdsNotMatchingError extends NotAcceptableError {
+	@IsString()
+	name = "StatsClientIdsNotMatchingError"
+
+	@IsString()
+	message = "The ids don't match! \n And if you wanted to change a stats client's id: This isn't allowed!"
+}

src/errors/TrackErrors.ts

@@ -1,9 +1,8 @@
-import { JsonController, Param, Body, Get, Post, Put, Delete, NotFoundError, OnUndefined, NotAcceptableError } from 'routing-controllers';
-import { IsInt, IsNotEmpty, IsPositive, IsString } from 'class-validator';
+import { IsString } from 'class-validator';
+import { NotAcceptableError, NotFoundError } from 'routing-controllers';
 
 /**
  * Error to throw when a track couldn't be found.
- * Implemented this ways to work with the json-schema conversion for openapi.
  */
 export class TrackNotFoundError extends NotFoundError {
 	@IsString()
@@ -16,12 +15,30 @@ export class TrackNotFoundError extends NotFoundError {
 /**
  * Error to throw when two tracks' ids don't match.
  * Usually occurs when a user tries to change a track's id.
- * Implemented this ways to work with the json-schema conversion for openapi.
  */
 export class TrackIdsNotMatchingError extends NotAcceptableError {
 	@IsString()
 	name = "TrackIdsNotMatchingError"
 
 	@IsString()
-	message = "The id's don't match!! \n And if you wanted to change a track's id: This isn't allowed"
+	message = "The ids don't match! \n And if you wanted to change a track's id: This isn't allowed"
+}
+
+/**
+ * Error to throw when a track's lap time is set to a negative value.
+ */
+export class TrackLapTimeCantBeNegativeError extends NotAcceptableError {
+	@IsString()
+	name = "TrackLapTimeCantBeNegativeError"
+
+	@IsString()
+	message = "The minimum lap time you provided is negative - That isn't possible. \n If you wanted to disable it: Just set it to 0/null."
+}
+
+export class TrackHasScanStationsError extends NotAcceptableError {
+	@IsString()
+	name = "TrackHasScanStationsError"
+
+	@IsString()
+	message = "This track still has stations associated with it. \n If you want to delete this track with all it's stations and scans add `?force` to your query."
 }

src/errors/UserErrors.ts

@@ -3,14 +3,39 @@ import { NotAcceptableError, NotFoundError } from 'routing-controllers';
 
 
 /**
- * Error to throw when no username or email is set
+ * Error to throw when no username or email is set.
+ * We somehow need to identify you on login.
  */
 export class UsernameOrEmailNeededError extends NotFoundError {
 	@IsString()
 	name = "UsernameOrEmailNeededError"
 
 	@IsString()
-	message = "no username or email is set!"
+	message = "No username or email is set!"
+}
+
+/**
+ * Error to throw when no username contains illegal characters.
+ * Right now the only one is "@" but this could change in the future.
+ */
+export class UsernameContainsIllegalCharacterError extends NotAcceptableError {
+	@IsString()
+	name = "UsernameContainsIllegalCharacterError"
+
+	@IsString()
+	message = "The provided username contains illegal characters! \n Right now the following characters are considered illegal: '@'"
+}
+
+/**
+ * Error to throw when no email is set.
+ * We somehow need to identify you :)
+ */
+export class UserEmailNeededError extends NotFoundError {
+	@IsString()
+	name = "UserEmailNeededError"
+
+	@IsString()
+	message = "No email is set! \n You have to provide email addresses for users (used for password reset among others)."
 }
 
 /**
@@ -33,5 +58,46 @@ export class UserIdsNotMatchingError extends NotAcceptableError {
 	name = "UserIdsNotMatchingError"
 
 	@IsString()
-	message = "The id's don't match!! \n And if you wanted to change a user's id: This isn't allowed"
+	message = "The ids don't match!! \n And if you wanted to change a user's id: This isn't allowed!"
+}
+
+/**
+ * Error to throw when two users' ids don't match.
+ * Usually occurs when a user tries to change a user's id.
+ */
+export class UserDeletionNotConfirmedError extends NotAcceptableError {
+	@IsString()
+	name = "UserDeletionNotConfirmedError"
+
+	@IsString()
+	message = "You are trying to delete a user! \n If you're sure about doing this: provide the ?force=true query param."
+}
+
+export class PasswordMustContainUppercaseLetterError extends NotAcceptableError {
+	@IsString()
+	name = "PasswordMustContainUppercaseLetterError"
+
+	@IsString()
+	message = "Passwords must contain at least one uppercase letter."
+}
+export class PasswordMustContainLowercaseLetterError extends NotAcceptableError {
+	@IsString()
+	name = "PasswordMustContainLowercaseLetterError"
+
+	@IsString()
+	message = "Passwords must contain at least one lowercase letter."
+}
+export class PasswordMustContainNumberError extends NotAcceptableError {
+	@IsString()
+	name = "PasswordMustContainNumberError"
+
+	@IsString()
+	message = "Passwords must contain at least one number."
+}
+export class PasswordTooShortError extends NotAcceptableError {
+	@IsString()
+	name = "PasswordTooShortError"
+
+	@IsString()
+	message = "Passwords must be at least ten characters long."
 }

src/errors/UserGroupErrors.ts

@@ -2,18 +2,18 @@ import { IsString } from 'class-validator';
 import { NotAcceptableError, NotFoundError } from 'routing-controllers';
 
 /**
- * Error to throw when no groupname is set
+ * Error to throw when no group name is set.
  */
 export class GroupNameNeededError extends NotFoundError {
 	@IsString()
 	name = "GroupNameNeededError"
 
 	@IsString()
-	message = "no groupname is set!"
+	message = "No name is set for this group!"
 }
 
 /**
- * Error to throw when a usergroup couldn't be found.
+ * Error to throw when a user group couldn't be found.
  */
 export class UserGroupNotFoundError extends NotFoundError {
 	@IsString()
@@ -24,13 +24,13 @@ export class UserGroupNotFoundError extends NotFoundError {
 }
 
 /**
- * Error to throw when two usergroups' ids don't match.
- * Usually occurs when a user tries to change a usergroups's id.
+ * Error to throw when two user groups' ids don't match.
+ * Usually occurs when a user tries to change a user groups's id.
  */
 export class UserGroupIdsNotMatchingError extends NotAcceptableError {
 	@IsString()
 	name = "UserGroupIdsNotMatchingError"
 
 	@IsString()
-	message = "The id's don't match!! \n If you wanted to change a usergroup's id: This isn't allowed"
+	message = "The ids don't match!! \n If you wanted to change a user group's id: This isn't allowed!"
 }

src/jwtcreator.ts

@@ -0,0 +1,125 @@
+import { IsBoolean, IsEmail, IsInt, IsNotEmpty, IsOptional, IsString, IsUUID } from 'class-validator';
+import * as jsonwebtoken from "jsonwebtoken";
+import { config } from './config';
+import { Runner } from './models/entities/Runner';
+import { User } from './models/entities/User';
+
+/**
+ * This class is responsible for all things JWT creation.
+ */
+export class JwtCreator {
+    /**
+     * Creates a new refresh token for a given user
+     * @param user User entity that the refresh token shall be created for
+     * @param expiry_timestamp Timestamp for the token expiry. Will be generated if not provided.
+     */
+    public static createRefresh(user: User, expiry_timestamp?: number) {
+        if (!expiry_timestamp) { expiry_timestamp = Math.floor(Date.now() / 1000) + 10 * 36000; }
+        return jsonwebtoken.sign({
+            refreshTokenCount: user.refreshTokenCount,
+            id: user.id,
+            exp: expiry_timestamp
+        }, config.jwt_secret)
+    }
+
+    /**
+     * Creates a new access token for a given user
+     * @param user User entity that the access token shall be created for
+     * @param expiry_timestamp Timestamp for the token expiry. Will be generated if not provided.
+     */
+    public static createAccess(user: User, expiry_timestamp?: number) {
+        if (!expiry_timestamp) { expiry_timestamp = Math.floor(Date.now() / 1000) + 10 * 36000; }
+        return jsonwebtoken.sign({
+            userdetails: new JwtUser(user),
+            exp: expiry_timestamp
+        }, config.jwt_secret)
+    }
+
+    /**
+     * Creates a new selfservice token for a given runner.
+     * @param runner Runner entity that the access token shall be created for.
+     * @param expiry_timestamp Timestamp for the token expiry. Will be set about 9999 years if none provided.
+     */
+    public static createSelfService(runner: Runner, expiry_timestamp?: number) {
+        if (!expiry_timestamp) { expiry_timestamp = Math.floor(Date.now() / 1000) + 36000 * 60 * 24 * 365 * 9999; }
+        return jsonwebtoken.sign({
+            id: runner.id,
+            exp: expiry_timestamp
+        }, config.jwt_secret)
+    }
+
+    /**
+     * Creates a new password reset token for a given user.
+     * The token is valid for 15 minutes or 1 use - whatever comes first.
+     * @param user User entity that the password reset token shall be created for
+     */
+    public static createReset(user: User) {
+        let expiry_timestamp = Math.floor(Date.now() / 1000) + 15 * 60;
+        return jsonwebtoken.sign({
+            id: user.id,
+            refreshTokenCount: user.refreshTokenCount,
+            exp: expiry_timestamp
+        }, config.jwt_secret)
+    }
+}
+
+/**
+ * Special variant of the user class that 
+ */
+export class JwtUser {
+    @IsInt()
+    id: number;
+
+    @IsUUID(4)
+    uuid: string;
+
+    @IsOptional()
+    @IsEmail()
+    email?: string;
+
+    @IsOptional()
+    @IsString()
+    username?: string;
+
+    @IsString()
+    @IsNotEmpty()
+    firstname: string;
+
+    @IsString()
+    @IsOptional()
+    middlename?: string;
+
+    @IsString()
+    @IsNotEmpty()
+    lastname: string;
+
+    permissions: string[];
+
+    @IsBoolean()
+    enabled: boolean;
+
+    @IsInt()
+    @IsNotEmpty()
+    refreshTokenCount?: number;
+
+    @IsString()
+    @IsOptional()
+    profilePic?: string;
+
+    /**
+     * Creates a new instance of this class based on a provided user entity.
+     * @param user User entity that shall be encapsulated in a jwt.
+     */
+    public constructor(user: User) {
+        this.id = user.id;
+        this.firstname = user.firstname;
+        this.middlename = user.middlename;
+        this.lastname = user.lastname;
+        this.username = user.username;
+        this.email = user.email;
+        this.refreshTokenCount = user.refreshTokenCount;
+        this.uuid = user.uuid;
+        this.profilePic = user.profilePic;
+        this.permissions = user.allPermissions;
+    }
+}

src/loaders/database.ts

@@ -1,7 +1,37 @@
 import { createConnection } from "typeorm";
-
+import { runSeeder } from 'typeorm-seeding';
+import consola from 'consola';
+import { config } from '../config';
+import { ConfigFlag } from '../models/entities/ConfigFlags';
+import SeedPublicOrg from '../seeds/SeedPublicOrg';
+import SeedTestRunners from '../seeds/SeedTestRunners';
+import SeedUsers from '../seeds/SeedUsers';
+/**
+ * Loader for the database that creates the database connection and initializes the database tabels.
+ * It also triggers the seeding process if no users got detected in the database.
+ */
 export default async () => {
     const connection = await createConnection();
-    connection.synchronize();
+    
+    // Log discovered entities for debugging
+    consola.info(`TypeORM discovered ${connection.entityMetadatas.length} entities:`);
+    consola.info(connection.entityMetadatas.map(m => m.name).sort().join(', '));
+    
+    await connection.synchronize();
+
+    //The data seeding part
+    if (!(await connection.getRepository(ConfigFlag).findOne({ option: "seeded:user", value: "true" }))) {
+        await runSeeder(SeedUsers);
+        await connection.getRepository(ConfigFlag).save({ option: "seeded:user", value: "true" });
+    }
+    if (!(await connection.getRepository(ConfigFlag).findOne({ option: "seeded:citizenorg", value: "true" }))) {
+        await runSeeder(SeedPublicOrg);
+        await connection.getRepository(ConfigFlag).save({ option: "seeded:citizenorg", value: "true" });
+    }
+    if (!(await connection.getRepository(ConfigFlag).findOne({ option: "seeded:testdata", value: "true" })) && config.seedTestData == true) {
+        await runSeeder(SeedTestRunners);
+        await connection.getRepository(ConfigFlag).save({ option: "seeded:testdata", value: "true" });
+    }
+
     return connection;
 };

src/loaders/express.ts

@@ -1,8 +1,13 @@
+import cookieParser from "cookie-parser";
 import { Application } from "express";
-import bodyParser from 'body-parser';
-import cors from 'cors';
-
+/**
+ * Loader for express related configurations.
+ * Configures proxy trusts, globally used middlewares and other express features.
+ */
 export default async (app: Application) => {
 	app.enable('trust proxy');
+	app.disable('x-powered-by');
+	app.disable('x-served-by');
+	app.use(cookieParser());
 	return app;
 };

src/loaders/index.ts

@@ -1,10 +1,28 @@
+import { Application } from "express";
+import consola from "consola";
+import { config } from "../config";
+import NatsClient from "../nats/NatsClient";
+import { warmAll } from "../nats/RunnerKV";
+import databaseLoader from "./database";
 import expressLoader from "./express";
 import openapiLoader from "./openapi";
-import databaseLoader from "./database";
-import { Application } from "express";
 
+/**
+ * Index Loader that executes the other loaders in the right order.
+ * This basicly exists for abstraction and a overall better dev experience.
+ */
 export default async (app: Application) => {
     await databaseLoader();
+    await NatsClient.connect();
+    
+    if (config.nats_prewarm) {
+        consola.info("Prewarming NATS runner cache...");
+        const startTime = Date.now();
+        await warmAll();
+        const duration = Date.now() - startTime;
+        consola.success(`NATS runner cache prewarmed in ${duration}ms`);
+    }
+    
     await openapiLoader(app);
     await expressLoader(app);
     return app;

src/loaders/openapi.ts

@@ -1,47 +1,24 @@
-import { validationMetadatasToSchemas } from "class-validator-jsonschema";
-import { Application } from "express";
+import { validationMetadatasToSchemas } from "@odit/class-validator-jsonschema";
+import express, { Application } from "express";
+import path from 'path';
 import { getMetadataArgsStorage } from "routing-controllers";
-import { routingControllersToSpec } from "routing-controllers-openapi";
-import * as swaggerUiExpress from "swagger-ui-express";
+import { generateSpec } from '../apispec';
 
+/**
+ * Loader for everything openapi related - from creating the schema to serving it via a static route and swaggerUiExpress.
+ * All auth schema related stuff also has to be configured here
+ */
 export default async (app: Application) => {
   const storage = getMetadataArgsStorage();
   const schemas = validationMetadatasToSchemas({
     refPointerPrefix: "#/components/schemas/",
   });
-  const spec = routingControllersToSpec(
-    storage,
-    {
-      routePrefix: "/api"
-    },
-    {
-      components: {
-        schemas,
-        "securitySchemes": {
-          "AuthToken": {
-            "type": "http",
-            "scheme": "bearer",
-            "bearerFormat": "JWT"
-          }
-        }
-      },
-      info: {
-        description: "The the backend API for the LfK! runner system.",
-        title: "LfK! Backend API",
-        version: "1.0.0",
-      },
-    }
-  );
-  const options = {
-    explorer: true,
-  };
-  app.use(
-    "/api/docs",
-    swaggerUiExpress.serve,
-    swaggerUiExpress.setup(spec, options)
-  );
-  app.get(["/api/openapi.json", "/api/swagger.json"], (req, res) => {
+
+  //Spec creation based on the previously created schemas
+  const spec = generateSpec(storage, schemas);
+  app.get(["/api/docs/openapi.json", "/api/docs/swagger.json"], (req, res) => {
     res.json(spec);
   });
+  app.use('/api/docs', express.static(path.join(__dirname, '../static/docs'), { index: "index.html", extensions: ['html'] }));
   return app;
 };

src/mailer.ts

@@ -0,0 +1,118 @@
+import axios from 'axios';
+import { config } from './config';
+import { MailSendingError } from './errors/MailErrors';
+
+/**
+ * This class is responsible for all things mail sending.
+ * This uses axios to communicate with the mailer api (https://git.odit.services/lfk/mailer).
+ */
+export class Mailer {
+    public static base: string = config.mailer_url;
+    public static key: string = config.mailer_key;
+    public static testing: boolean = config.testing;
+
+    /**
+     * Function for sending a password reset mail.
+     * @param to_address The address the mail will be sent to. Should always get pulled from a user object.
+     * @param token The requested password reset token - will be combined with the app_url to generate a password reset link.
+     */
+    public static async sendResetMail(to_address: string, token: string, locale: string = "en") {
+        try {
+            await axios.request({
+                method: 'POST',
+                url: `${Mailer.base}/api/v1/email`,
+                headers: {
+                    authorization: `Bearer ${Mailer.key}`,
+                    'content-type': 'application/json'
+                },
+                data: {
+                    to: to_address,
+                    templateName: 'password-reset',
+                    language: locale,
+                    data: { token: token }
+                }
+            });
+        } catch (error) {
+            if (Mailer.testing) { return true; }
+            throw new MailSendingError();
+        }
+    }
+
+    /**
+     * Function for sending a runner selfservice welcome mail.
+     * @param to_address The address the mail will be sent to. Should always get pulled from a runner object.
+     * @param token The requested selfservice token - will be combined with the app_url to generate a selfservice profile link.
+    */
+    public static async sendSelfserviceWelcomeMail(to_address: string, runner_id: number, firstname: string, middlename: string, lastname: string, token: string, locale: string = "en") {
+        try {
+            await axios.request({
+                method: 'POST',
+                url: `${Mailer.base}/api/v1/email`,
+                headers: {
+                    authorization: `Bearer ${Mailer.key}`,
+                    'content-type': 'application/json'
+                },
+                data: {
+                    to: to_address,
+                    templateName: 'welcome',
+                    language: locale,
+                    data: {
+                        name: `${firstname} ${middlename} ${lastname}`,
+                        barcode_content: `${runner_id}`,
+                        link: `${process.env.SELFSERVICE_URL}/profile/${token}`
+                    }
+                }
+            });
+        } catch (error) {
+            if (Mailer.testing) { return true; }
+            throw new MailSendingError();
+        }
+    }
+
+    /**
+     * Function for sending a runner selfservice link forgotten mail.
+     * @param to_address The address the mail will be sent to. Should always get pulled from a runner object.
+     * @param token The requested selfservice token - will be combined with the app_url to generate a selfservice profile link.
+    */
+    public static async sendSelfserviceForgottenMail(to_address: string, runner_id: number, firstname: string, middlename: string, lastname: string, token: string, locale: string = "en") {
+        try {
+            console.log("Mail request", {
+                to: to_address,
+                templateName: 'welcome',
+                language: locale,
+                data: {
+                    to: to_address,
+                    templateName: 'welcome',
+                    language: locale,
+                    data: {
+                        name: `${firstname} ${middlename} ${lastname}`,
+                        barcode_content: `${runner_id}`,
+                        link: `${process.env.SELFSERVICE_URL}/profile/${token}`
+                    }
+                }
+            })
+            await axios.request({
+                method: 'POST',
+                url: `${Mailer.base}/api/v1/email`,
+                headers: {
+                    authorization: `Bearer ${Mailer.key}`,
+                    'content-type': 'application/json'
+                },
+                data: {
+                    to: to_address,
+                    templateName: 'welcome',
+                    language: locale,
+                    data: {
+                        name: `${firstname} ${middlename} ${lastname}`,
+                        barcode_content: `${runner_id}`,
+                        link: `${process.env.SELFSERVICE_URL}/profile/${token}`
+                    }
+                }
+            });
+        } catch (error) {
+            if (Mailer.testing) { return true; }
+            console.error("Error while sending selfservice forgotten mail:", error.message);
+            throw new MailSendingError();
+        }
+    }
+}

src/middlewares/ErrorHandler.ts

@@ -1,20 +1,14 @@
-import {
-    Middleware,
-    ExpressErrorMiddlewareInterface
-} from "routing-controllers";
+import { ExpressErrorMiddlewareInterface, Middleware } from "routing-controllers";
 
+/**
+ * Our Error handling middlware that returns our custom httperrors to the user.
+ */
 @Middleware({ type: "after" })
 export class ErrorHandler implements ExpressErrorMiddlewareInterface {
-    public error(
-        error: any,
-        request: any,
-        response: any,
-        next: (err: any) => any
-    ) {
+    public error(error: any, request: any, response: any, next: (err: any) => any) {
         if (response.headersSent) {
             return;
         }
-
         response.json(error);
     }
 }

src/middlewares/RawBody.ts

@@ -0,0 +1,23 @@
+import { Request, Response } from 'express';
+
+/**
+ * Custom express middleware that appends the raw body to the request object.
+ * Mainly used for parsing csvs from bodies.
+ */
+
+const RawBodyMiddleware = (req: Request, res: Response, next: () => void) => {
+    const body = []
+    req.on('data', chunk => {
+        body.push(chunk)
+    })
+    req.on('end', () => {
+        const rawBody = Buffer.concat(body)
+        req['rawBody'] = rawBody
+        next()
+    })
+    req.on('error', () => {
+        res.sendStatus(400)
+    })
+}
+
+export default RawBodyMiddleware

src/middlewares/ScanAuth.ts

@@ -0,0 +1,129 @@
+import crypto from 'crypto';
+import { Request, Response } from 'express';
+import { getConnectionManager } from 'typeorm';
+import { config } from '../config';
+import { deleteStationEntry, getStationEntry, setStationEntry, StationKVEntry } from '../nats/StationKV';
+import { ScanStation } from '../models/entities/ScanStation';
+import authchecker from './authchecker';
+
+/**
+ * Computes the HMAC-SHA256 of the provided token using the station token secret.
+ */
+function computeHmac(token: string): string {
+    return crypto.createHmac('sha256', config.station_token_secret).update(token).digest('hex');
+}
+
+/**
+ * Constant-time comparison of two hex HMAC strings.
+ * Returns true if they match.
+ */
+function verifyHmac(provided_token: string, storedHash: string): boolean {
+    const expectedHash = computeHmac(provided_token);
+    const expectedBuf = Buffer.from(expectedHash);
+    const storedBuf = Buffer.from(storedHash);
+    return expectedBuf.length === storedBuf.length && crypto.timingSafeEqual(expectedBuf, storedBuf);
+}
+
+/**
+ * This middleware handles the authentication of scan station api tokens.
+ * The tokens have to be provided via Bearer authorization header.
+ *
+ * Auth flow:
+ *   1. Extract prefix from token (PREFIX.KEY format)
+ *   2. Try NATS KV cache lookup by prefix — warm path: HMAC verify, no DB
+ *   3. On cache miss: DB lookup → HMAC verify → write to KV cache
+ *   4. On no station match at all: fall back to JWT auth (SCAN:CREATE permission)
+ *
+ * On success sets req.isStationAuth = true and req.stationId on the request object.
+ * These are internal server-side properties — not HTTP headers, not spoofable by clients.
+ *
+ * You have to manually use this middleware via @UseBefore(ScanAuth) instead of using @Authorized().
+ * @param req Express request object.
+ * @param res Express response object.
+ * @param next Next function to call on success.
+ */
+const ScanAuth = async (req: Request, res: Response, next: () => void) => {
+    let provided_token: string = req.headers['authorization'];
+    if (!provided_token) {
+        res.status(401).send({ http_code: 401, short: 'no_token', message: 'No api token provided.' });
+        return;
+    }
+
+    provided_token = provided_token.replace('Bearer ', '');
+
+    const prefix = provided_token.split('.')[0];
+    if (!prefix) {
+        res.status(401).send({ http_code: 401, short: 'invalid_token', message: 'Api token non-existent or invalid syntax.' });
+        return;
+    }
+
+    // --- KV cache lookup (warm path) ---
+    const cached = await getStationEntry(prefix);
+    if (cached) {
+        if (!cached.enabled) {
+            res.status(401).send({ http_code: 401, short: 'station_disabled', message: 'Station is disabled.' });
+            return;
+        }
+        if (!verifyHmac(provided_token, cached.tokenHash)) {
+            res.status(401).send({ http_code: 401, short: 'invalid_token', message: 'Api token non-existent or invalid syntax.' });
+            return;
+        }
+        req.isStationAuth = true;
+        req.stationId = cached.id;
+        next();
+        return;
+    }
+
+    // --- DB lookup (cold path) ---
+    const station = await getConnectionManager().get().getRepository(ScanStation).findOne({ prefix }, { relations: ['track'] });
+
+    if (!station) {
+        // No station with this prefix — fall back to JWT auth
+        let user_authorized = false;
+        try {
+            const action = { request: req, response: res, context: null, next };
+            user_authorized = await authchecker(action, ['SCAN:CREATE']);
+        } finally {
+            if (!user_authorized) {
+                res.status(401).send({ http_code: 401, short: 'invalid_token', message: 'Api token non-existent or invalid syntax.' });
+                return;
+            }
+            next();
+        }
+        return;
+    }
+
+    // Station found — verify token before caching
+    const tokenHash = computeHmac(provided_token);
+    const storedBuf = Buffer.from(station.key);
+    const computedBuf = Buffer.from(tokenHash);
+    const valid = computedBuf.length === storedBuf.length && crypto.timingSafeEqual(computedBuf, storedBuf);
+
+    if (!valid) {
+        res.status(401).send({ http_code: 401, short: 'invalid_token', message: 'Api token non-existent or invalid syntax.' });
+        return;
+    }
+
+    if (!station.enabled) {
+        res.status(401).send({ http_code: 401, short: 'station_disabled', message: 'Station is disabled.' });
+        return;
+    }
+
+    // Write to KV cache for subsequent requests
+    const entry: StationKVEntry = {
+        id: station.id,
+        enabled: station.enabled,
+        tokenHash,
+        trackId: station.track.id,
+        trackDistance: station.track.distance,
+        minimumLapTime: station.track.minimumLapTime ?? 0,
+    };
+    await setStationEntry(prefix, entry);
+
+    req.isStationAuth = true;
+    req.stationId = station.id;
+    next();
+};
+
+export default ScanAuth;
+export { deleteStationEntry };

src/middlewares/StatsAuth.ts

@@ -0,0 +1,66 @@
+import * as Bun from 'bun';
+import { Request, Response } from 'express';
+import { getConnectionManager } from 'typeorm';
+import { StatsClient } from '../models/entities/StatsClient';
+import authchecker from './authchecker';
+
+/**
+ * This middleware handles the authentication of stats client api tokens.
+ * The tokens have to be provided via Bearer authorization header.
+ * You have to manually use this middleware via @UseBefore(StatsAuth) instead of using @Authorized().
+ * @param req Express request object.
+ * @param res Express response object.
+ * @param next Next function to call on success.
+ */
+const StatsAuth = async (req: Request, res: Response, next: () => void) => {
+    let provided_token: string = req.headers["authorization"];
+    if (provided_token == "" || provided_token === undefined || provided_token === null) {
+        res.status(401).send("No api token provided.");
+        return;
+    }
+
+    try {
+        provided_token = provided_token.replace("Bearer ", "");
+    } catch (error) {
+        res.status(401).send("No valid jwt or api token provided.");
+        return;
+    }
+
+    let prefix = "";
+    try {
+        prefix = provided_token.split(".")[0];
+    }
+    finally {
+        if (prefix == "" || prefix == undefined || prefix == null) {
+            res.status(401).send("Api token non-existant or invalid syntax.");
+            return;
+        }
+    }
+
+    const client = await getConnectionManager().get().getRepository(StatsClient).findOne({ prefix: prefix });
+    if (!client) {
+        let user_authorized = false;
+        try {
+            let action = { request: req, response: res, context: null, next: next }
+            user_authorized = await authchecker(action, ["RUNNER:GET", "TEAM:GET", "ORGANIZATION:GET"]);
+        }
+        finally {
+            if (user_authorized == false) {
+                res.status(401).send("Api token non-existant or invalid syntax.");
+                return;
+            }
+            else {
+                next();
+            }
+        }
+    }
+    else {
+        if (!(await Bun.password.verify(provided_token, client.key))) {
+            res.status(401).send("Api token invalid.");
+            return;
+        }
+
+        next();
+    }
+}
+export default StatsAuth;

src/middlewares/UserChecker.ts

@@ -0,0 +1,58 @@
+import cookie from "cookie";
+import * as jwt from "jsonwebtoken";
+import { Action } from 'routing-controllers';
+import { getConnectionManager } from 'typeorm';
+import { config } from '../config';
+import { IllegalJWTError, UserDisabledError, UserNonexistantOrRefreshtokenInvalidError } from '../errors/AuthError';
+import { JwtCreator, JwtUser } from '../jwtcreator';
+import { User } from '../models/entities/User';
+
+/**
+ * TODO:
+ */
+const UserChecker = async (action: Action) => {
+    let jwtPayload = undefined
+    try {
+        let provided_token = "" + action.request.headers["authorization"].replace("Bearer ", "");
+        jwtPayload = <any>jwt.verify(provided_token, config.jwt_secret);
+        jwtPayload = jwtPayload["userdetails"];
+    } catch (error) {
+        jwtPayload = await refresh(action);
+    }
+
+    const user = await getConnectionManager().get().getRepository(User).findOne({ id: jwtPayload["id"], refreshTokenCount: jwtPayload["refreshTokenCount"] })
+    if (!user) { throw new UserNonexistantOrRefreshtokenInvalidError() }
+    if (user.enabled == false) { throw new UserDisabledError(); }
+    return user;
+};
+
+/**
+ * Handles soft-refreshing of access-tokens.
+ * @param action Routing-Controllers action object that provides request and response objects among other stuff.
+ */
+const refresh = async (action: Action) => {
+    let refresh_token = undefined;
+    try {
+        refresh_token = cookie.parse(action.request.headers["cookie"])["lfk_backend__refresh_token"];
+    }
+    catch {
+        throw new IllegalJWTError();
+    }
+
+    let jwtPayload = undefined;
+    try {
+        jwtPayload = <any>jwt.verify(refresh_token, config.jwt_secret);
+    } catch (error) {
+        throw new IllegalJWTError();
+    }
+
+    const user = await getConnectionManager().get().getRepository(User).findOne({ id: jwtPayload["id"], refreshTokenCount: jwtPayload["refreshTokenCount"] }, { relations: ['permissions', 'groups', 'groups.permissions'] })
+    if (!user) { throw new UserNonexistantOrRefreshtokenInvalidError() }
+    if (user.enabled == false) { throw new UserDisabledError(); }
+
+    let newAccess = JwtCreator.createAccess(user);
+    action.response.header("authorization", "Bearer " + newAccess);
+
+    return await new JwtUser(user);
+}
+export default UserChecker;

src/middlewares/authchecker.ts

@@ -0,0 +1,74 @@
+import cookie from "cookie";
+import * as jwt from "jsonwebtoken";
+import { Action } from "routing-controllers";
+import { getConnectionManager } from 'typeorm';
+import { config } from '../config';
+import { IllegalJWTError, NoPermissionError, UserDisabledError, UserNonexistantOrRefreshtokenInvalidError } from '../errors/AuthError';
+import { JwtCreator, JwtUser } from '../jwtcreator';
+import { User } from '../models/entities/User';
+
+/**
+ * Handles authentication via jwt's (Bearer authorization header) for all api endpoints using the @Authorized decorator.
+ * @param action Routing-Controllers action object that provides request and response objects among other stuff.
+ * @param permissions The permissions that the endpoint using @Authorized requires.
+ */
+const authchecker = async (action: Action, permissions: string[] | string) => {
+    let required_permissions = undefined;
+    if (typeof permissions === "string") {
+        required_permissions = [permissions]
+    } else {
+        required_permissions = permissions
+    }
+
+    let jwtPayload = undefined
+    try {
+        let provided_token = "" + action.request.headers["authorization"].replace("Bearer ", "");
+        jwtPayload = <any>jwt.verify(provided_token, config.jwt_secret);
+        jwtPayload = jwtPayload["userdetails"];
+    } catch (error) {
+        jwtPayload = await refresh(action);
+    }
+
+    const user = await getConnectionManager().get().getRepository(User).findOne({ id: jwtPayload["id"], refreshTokenCount: jwtPayload["refreshTokenCount"] }, { relations: ['permissions'] })
+    if (!user) { throw new UserNonexistantOrRefreshtokenInvalidError() }
+    if (user.enabled == false) { throw new UserDisabledError(); }
+    if (!jwtPayload["permissions"]) { throw new NoPermissionError(); }
+
+    action.response.local = {}
+    action.response.local.jwtPayload = jwtPayload;
+    for (let required_permission of required_permissions) {
+        if (!(jwtPayload["permissions"].includes(required_permission))) { return false; }
+    }
+    return true;
+}
+
+/**
+ * Handles soft-refreshing of access-tokens.
+ * @param action Routing-Controllers action object that provides request and response objects among other stuff.
+ */
+const refresh = async (action: Action) => {
+    let refresh_token = undefined;
+    try {
+        refresh_token = cookie.parse(action.request.headers["cookie"])["lfk_backend__refresh_token"];
+    }
+    catch {
+        throw new IllegalJWTError();
+    }
+
+    let jwtPayload = undefined;
+    try {
+        jwtPayload = <any>jwt.verify(refresh_token, config.jwt_secret);
+    } catch (error) {
+        throw new IllegalJWTError();
+    }
+
+    const user = await getConnectionManager().get().getRepository(User).findOne({ id: jwtPayload["id"], refreshTokenCount: jwtPayload["refreshTokenCount"] }, { relations: ['permissions', 'groups', 'groups.permissions'] })
+    if (!user) { throw new UserNonexistantOrRefreshtokenInvalidError() }
+    if (user.enabled == false) { throw new UserDisabledError(); }
+
+    let newAccess = JwtCreator.createAccess(user);
+    action.response.header("authorization", "Bearer " + newAccess);
+
+    return await new JwtUser(user);
+}
+export default authchecker

src/models/actions/CreateAddress.ts

@@ -1,64 +0,0 @@
-import { IsNotEmpty, IsOptional, IsPostalCode, IsString } from 'class-validator';
-import { Address } from '../entities/Address';
-
-export class CreateAddress {
-    /**
-   * The address's description.
-   */
-    @IsString()
-    @IsOptional()
-    description?: string;
-
-    /**
-     * The address's first line.
-     * Containing the street and house number.
-     */
-    @IsString()
-    @IsNotEmpty()
-    address1: string;
-
-    /**
-     * The address's second line.
-     * Containing optional information.
-     */
-    @IsString()
-    @IsOptional()
-    address2?: string;
-
-    /**
-     * The address's postal code.
-     */
-    @IsString()
-    @IsNotEmpty()
-    @IsPostalCode("DE")
-    postalcode: string;
-
-    /**
-     * The address's city.
-     */
-    @IsString()
-    @IsNotEmpty()
-    city: string;
-
-    /**
-     * The address's country.
-     */
-    @IsString()
-    @IsNotEmpty()
-    country: string;
-
-    /**
-     * Creates a Address object based on this.
-     */
-    public toAddress(): Address {
-        let newAddress: Address = new Address();
-
-        newAddress.address1 = this.address1;
-        newAddress.address2 = this.address2;
-        newAddress.postalcode = this.postalcode;
-        newAddress.city = this.city;
-        newAddress.country = this.country;
-
-        return newAddress;
-    }
-}

src/models/actions/CreateAuth.ts

@@ -1,57 +0,0 @@
-import * as argon2 from "argon2";
-import { IsEmail, IsOptional, IsString } from 'class-validator';
-import * as jsonwebtoken from 'jsonwebtoken';
-import { getConnectionManager } from 'typeorm';
-import { InvalidCredentialsError, PasswordNeededError, UserNotFoundError } from '../../errors/AuthError';
-import { UsernameOrEmailNeededError } from '../../errors/UserErrors';
-import { User } from '../entities/User';
-import { Auth } from '../responses/ResponseAuth';
-
-export class CreateAuth {
-    @IsOptional()
-    @IsString()
-    username?: string;
-    @IsString()
-    password: string;
-    @IsOptional()
-    @IsEmail()
-    @IsString()
-    email?: string;
-
-    public async toAuth(): Promise<Auth> {
-        let newAuth: Auth = new Auth();
-
-        if (this.email === undefined && this.username === undefined) {
-            throw new UsernameOrEmailNeededError();
-        }
-        if (!this.password) {
-            throw new PasswordNeededError()
-        }
-        const found_users = await getConnectionManager().get().getRepository(User).find({ where: [{ username: this.username }, { email: this.email }] });
-        if (found_users.length === 0) {
-            throw new UserNotFoundError()
-        } else {
-            const found_user = found_users[0]
-            if (await argon2.verify(found_user.password, this.password + found_user.uuid)) {
-                const timestamp_accesstoken_expiry = Math.floor(Date.now() / 1000) + 5 * 60
-                delete found_user.password;
-                newAuth.access_token = jsonwebtoken.sign({
-                    userdetails: found_user,
-                    exp: timestamp_accesstoken_expiry
-                }, "securekey")
-                newAuth.access_token_expires_at = timestamp_accesstoken_expiry
-                // 
-                const timestamp_refresh_expiry = Math.floor(Date.now() / 1000) + 10 * 36000
-                newAuth.refresh_token = jsonwebtoken.sign({
-                    refreshtokencount: found_user.refreshTokenCount,
-                    userid: found_user.id,
-                    exp: timestamp_refresh_expiry
-                }, "securekey")
-                newAuth.refresh_token_expires_at = timestamp_refresh_expiry
-            } else {
-                throw new InvalidCredentialsError()
-            }
-        }
-        return newAuth;
-    }
-}

src/models/actions/CreateGroupContact.ts

@@ -1,83 +0,0 @@
-import { IsEmail, IsInt, IsNotEmpty, IsOptional, IsPhoneNumber, IsString } from 'class-validator';
-import { getConnectionManager } from 'typeorm';
-import { AddressNotFoundError, AddressWrongTypeError } from '../../errors/AddressErrors';
-import { Address } from '../entities/Address';
-import { GroupContact } from '../entities/GroupContact';
-
-export class CreateGroupContact {
-    /**
-       * The contact's first name.
-       */
-    @IsNotEmpty()
-    @IsString()
-    firstname: string;
-
-    /**
-     * The contact's middle name.
-     * Optional
-     */
-    @IsOptional()
-    @IsString()
-    middlename?: string;
-
-    /**
-     * The contact's last name.
-     */
-    @IsNotEmpty()
-    @IsString()
-    lastname: string;
-
-    /**
-     * The contact's address.
-     * Optional
-     */
-    @IsInt()
-    @IsOptional()
-    address?: number;
-
-    /**
-     * The contact's phone number.
-     * Optional
-     */
-    @IsOptional()
-    @IsPhoneNumber("DE")
-    phone?: string;
-
-    /**
-     * The contact's email address.
-     * Optional
-     */
-    @IsOptional()
-    @IsEmail()
-    email?: string;
-
-    /**
-     * Get's this participant's address from this.address.
-     */
-    public async getAddress(): Promise<Address> {
-        if (this.address === undefined) {
-            return null;
-        }
-        if (!isNaN(this.address)) {
-            let address = await getConnectionManager().get().getRepository(Address).findOne({ id: this.address });
-            if (!address) { throw new AddressNotFoundError; }
-            return address;
-        }
-
-        throw new AddressWrongTypeError;
-    }
-
-    /**
-     * Creates a Address object based on this.
-     */
-    public async toGroupContact(): Promise<GroupContact> {
-        let contact: GroupContact = new GroupContact();
-        contact.firstname = this.firstname;
-        contact.middlename = this.middlename;
-        contact.lastname = this.lastname;
-        contact.email = this.email;
-        contact.phone = this.phone;
-        contact.address = await this.getAddress();
-        return null;
-    }
-}

src/models/actions/CreateParticipant.ts

@@ -1,71 +0,0 @@
-import { IsEmail, IsInt, IsNotEmpty, IsOptional, IsPhoneNumber, IsString } from 'class-validator';
-import { getConnectionManager } from 'typeorm';
-import { AddressNotFoundError, AddressWrongTypeError } from '../../errors/AddressErrors';
-import { Address } from '../entities/Address';
-
-export abstract class CreateParticipant {
-    /**
-     * The new participant's first name.
-     */
-    @IsString()
-    @IsNotEmpty()
-    firstname: string;
-
-    /**
-     * The new participant's middle name.
-     * Optional.
-     */
-    @IsString()
-    @IsNotEmpty()
-    middlename?: string;
-
-    /**
-     * The new participant's last name.
-     */
-    @IsString()
-    @IsNotEmpty()
-    lastname: string;
-
-    /**
-     * The new participant's phone number.
-     * Optional.
-     */
-    @IsString()
-    @IsOptional()
-    @IsPhoneNumber("ZZ")
-    phone?: string;
-
-    /**
-     * The new participant's e-mail address.
-     * Optional.
-     */
-    @IsString()
-    @IsOptional()
-    @IsEmail()
-    email?: string;
-
-    /**
-     * The new participant's address.
-     * Must be of type number (address id), createAddress (new address) or address (existing address)
-     * Optional.
-     */
-    @IsInt()
-    @IsOptional()
-    address?: number;
-
-    /**
-     * Get's this participant's address from this.address.
-     */
-    public async getAddress(): Promise<Address> {
-        if (this.address === undefined) {
-            return null;
-        }
-        if (!isNaN(this.address)) {
-            let address = await getConnectionManager().get().getRepository(Address).findOne({ id: this.address });
-            if (!address) { throw new AddressNotFoundError; }
-            return address;
-        }
-
-        throw new AddressWrongTypeError;
-    }
-}

src/models/actions/CreateRunnerGroup.ts

@@ -1,37 +0,0 @@
-import { IsInt, IsNotEmpty, IsOptional, IsString } from 'class-validator';
-import { getConnectionManager } from 'typeorm';
-import { GroupContactNotFoundError, GroupContactWrongTypeError } from '../../errors/GroupContactErrors';
-import { GroupContact } from '../entities/GroupContact';
-
-export abstract class CreateRunnerGroup {
-    /**
-     * The group's name.
-     */
-    @IsNotEmpty()
-    @IsString()
-    name: string;
-
-    /**
-     * The group's contact.
-     * Optional
-     */
-    @IsInt()
-    @IsOptional()
-    contact?: number;
-
-    /**
-     * Deals with the contact for groups this.
-     */
-    public async getContact(): Promise<GroupContact> {
-        if (this.contact === undefined) {
-            return null;
-        }
-        if (!isNaN(this.contact)) {
-            let address = await getConnectionManager().get().getRepository(GroupContact).findOne({ id: this.contact });
-            if (!address) { throw new GroupContactNotFoundError; }
-            return address;
-        }
-
-        throw new GroupContactWrongTypeError;
-    }
-}

src/models/actions/CreateRunnerOrganisation.ts

@@ -1,46 +0,0 @@
-import { IsInt, IsOptional } from 'class-validator';
-import { getConnectionManager } from 'typeorm';
-import { AddressNotFoundError, AddressWrongTypeError } from '../../errors/AddressErrors';
-import { Address } from '../entities/Address';
-import { RunnerOrganisation } from '../entities/RunnerOrganisation';
-import { CreateRunnerGroup } from './CreateRunnerGroup';
-
-export class CreateRunnerOrganisation extends CreateRunnerGroup {
-    /**
-     * The new organisation's address.
-     * Must be of type number (address id), createAddress (new address) or address (existing address)
-     * Optional.
-     */
-    @IsInt()
-    @IsOptional()
-    address?: number;
-
-    /**
-     * Creates a Participant entity from this.
-     */
-    public async getAddress(): Promise<Address> {
-        if (this.address === undefined) {
-            return null;
-        }
-        if (!isNaN(this.address)) {
-            let address = await getConnectionManager().get().getRepository(Address).findOne({ id: this.address });
-            if (!address) { throw new AddressNotFoundError; }
-            return address;
-        }
-
-        throw new AddressWrongTypeError;
-    }
-
-    /**
-     * Creates a RunnerOrganisation entity from this.
-     */
-    public async toRunnerOrganisation(): Promise<RunnerOrganisation> {
-        let newRunnerOrganisation: RunnerOrganisation = new RunnerOrganisation();
-
-        newRunnerOrganisation.name = this.name;
-        newRunnerOrganisation.contact = await this.getContact();
-        newRunnerOrganisation.address = await this.getAddress();
-
-        return newRunnerOrganisation;
-    }
-}

src/models/actions/CreateRunnerTeam.ts

@@ -1,43 +0,0 @@
-import { IsInt, IsNotEmpty } from 'class-validator';
-import { getConnectionManager } from 'typeorm';
-import { RunnerOrganisationNotFoundError, RunnerOrganisationWrongTypeError } from '../../errors/RunnerOrganisationErrors';
-import { RunnerTeamNeedsParentError } from '../../errors/RunnerTeamErrors';
-import { RunnerOrganisation } from '../entities/RunnerOrganisation';
-import { RunnerTeam } from '../entities/RunnerTeam';
-import { CreateRunnerGroup } from './CreateRunnerGroup';
-
-export class CreateRunnerTeam extends CreateRunnerGroup {
-
-    /**
-     * The team's parent group (organisation).
-     */
-    @IsInt()
-    @IsNotEmpty()
-    parentGroup: number;
-
-    public async getParent(): Promise<RunnerOrganisation> {
-        if (this.parentGroup === undefined) {
-            throw new RunnerTeamNeedsParentError();
-        }
-        if (!isNaN(this.parentGroup)) {
-            let parentGroup = await getConnectionManager().get().getRepository(RunnerOrganisation).findOne({ id: this.parentGroup });
-            if (!parentGroup) { throw new RunnerOrganisationNotFoundError();; }
-            return parentGroup;
-        }
-
-        throw new RunnerOrganisationWrongTypeError;
-    }
-
-    /**
-     * Creates a RunnerTeam entity from this.
-     */
-    public async toRunnerTeam(): Promise<RunnerTeam> {
-        let newRunnerTeam: RunnerTeam = new RunnerTeam();
-
-        newRunnerTeam.name = this.name;
-        newRunnerTeam.parentGroup = await this.getParent();
-        newRunnerTeam.contact = await this.getContact()
-
-        return newRunnerTeam;
-    }
-}

src/models/actions/CreateTrack.ts

@@ -1,30 +0,0 @@
-import { IsInt, IsNotEmpty, IsPositive, IsString } from 'class-validator';
-import { Track } from '../entities/Track';
-
-export class CreateTrack {
-    /**
-     * The track's name.
-     */
-    @IsString()
-    @IsNotEmpty()
-    name: string;
-
-    /**
-     * The track's distance in meters (must be greater 0).
-     */
-    @IsInt()
-    @IsPositive()
-    distance: number;
-
-    /**
-     * Converts a Track object based on this.
-     */
-    public toTrack(): Track {
-        let newTrack: Track = new Track();
-
-        newTrack.name = this.name;
-        newTrack.distance = this.distance;
-
-        return newTrack;
-    }
-}

src/models/actions/CreateUser.ts

@@ -1,119 +0,0 @@
-import * as argon2 from "argon2";
-import { IsEmail, IsOptional, IsPhoneNumber, IsString } from 'class-validator';
-import { getConnectionManager } from 'typeorm';
-import * as uuid from 'uuid';
-import { UsernameOrEmailNeededError } from '../../errors/UserErrors';
-import { UserGroupNotFoundError } from '../../errors/UserGroupErrors';
-import { User } from '../entities/User';
-import { UserGroup } from '../entities/UserGroup';
-
-export class CreateUser {
-    /**
-     * The new user's first name.
-     */
-    @IsString()
-    firstname: string;
-
-    /**
-     * The new user's middle name.
-     * Optinal.
-     */
-    @IsString()
-    @IsOptional()
-    middlename?: string;
-
-    /**
-     * The new user's last name.
-     */
-    @IsString()
-    lastname: string;
-
-    /**
-     * The new user's username.
-     * You have to provide at least one of: {email, username}.
-     */
-    @IsOptional()
-    @IsString()
-    username?: string;
-
-    /**
-     * The new user's email address.
-     * You have to provide at least one of: {email, username}.
-     */
-    @IsEmail()
-    @IsString()
-    @IsOptional()
-    email?: string;
-
-    /**
-     * The new user's phone number.
-     * Optional
-     */
-    @IsPhoneNumber("ZZ")
-    @IsOptional()
-    phone?: string;
-
-    /**
-     * The new user's password.
-     * This will of course not be saved in plaintext :)
-     */
-    @IsString()
-    password: string;
-
-    /**
-     * The new user's groups' id(s).
-     * You can provide either one groupId or an array of groupIDs.
-     * Optional.
-     */
-    @IsOptional()
-    groupId?: number[] | number
-
-    //TODO: ProfilePics
-
-    /**
-     * Converts this to a User Entity.
-     */
-    public async toUser(): Promise<User> {
-        let newUser: User = new User();
-
-        if (this.email === undefined && this.username === undefined) {
-            throw new UsernameOrEmailNeededError();
-        }
-
-        if (this.groupId) {
-            if (!Array.isArray(this.groupId)) {
-                this.groupId = [this.groupId]
-            }
-            const groupIDs: number[] = this.groupId
-            let errors = 0
-            const validateusergroups = async () => {
-                let foundgroups = []
-                for (const g of groupIDs) {
-                    const found = await getConnectionManager().get().getRepository(UserGroup).find({ id: g });
-                    if (found.length === 0) {
-                        errors++
-                    } else {
-                        foundgroups.push(found[0])
-                    }
-                }
-                newUser.groups = foundgroups
-            }
-            await validateusergroups()
-            if (errors !== 0) {
-                throw new UserGroupNotFoundError();
-            }
-        }
-
-        newUser.email = this.email
-        newUser.username = this.username
-        newUser.firstname = this.firstname
-        newUser.middlename = this.middlename
-        newUser.lastname = this.lastname
-        newUser.uuid = uuid.v4()
-        newUser.phone = this.phone
-        newUser.password = await argon2.hash(this.password + newUser.uuid);
-        //TODO: ProfilePics
-
-        return newUser;
-    }
-}

src/models/actions/HandleLogout.ts

@@ -1,14 +1,28 @@
-import { IsString } from 'class-validator';
+import { IsOptional, IsString } from 'class-validator';
 import * as jsonwebtoken from 'jsonwebtoken';
 import { getConnectionManager } from 'typeorm';
+import { config } from '../../config';
 import { IllegalJWTError, JwtNotProvidedError, RefreshTokenCountInvalidError, UserNotFoundError } from '../../errors/AuthError';
 import { User } from '../entities/User';
 import { Logout } from '../responses/ResponseLogout';
 
+/**
+ * This class handels a user logging out of the system.
+ * Of course it check's the user's provided credential (token) before logging him out.
+ */
 export class HandleLogout {
+    /**
+     * A stringyfied jwt access token.
+     * Will get checked for validity.
+     */
     @IsString()
-    token: string;
+    @IsOptional()
+    token?: string;
 
+    /**
+     * Logs the user out.
+     * This gets achived by increasing the user's refresh token count, thereby invalidateing all currently existing jwts for that user.
+     */
     public async logout(): Promise<Logout> {
         let logout: Logout = new Logout();
         if (!this.token || this.token === undefined) {
@@ -16,16 +30,16 @@ export class HandleLogout {
         }
         let decoded;
         try {
-            decoded = jsonwebtoken.verify(this.token, 'securekey')
+            decoded = jsonwebtoken.verify(this.token, config.jwt_secret)
         } catch (error) {
             throw new IllegalJWTError()
         }
         logout.timestamp = Math.floor(Date.now() / 1000)
-        let found_user: User = await getConnectionManager().get().getRepository(User).findOne({ id: decoded["userid"] });
+        let found_user: User = await getConnectionManager().get().getRepository(User).findOne({ id: decoded["id"] });
         if (!found_user) {
             throw new UserNotFoundError()
         }
-        if (found_user.refreshTokenCount !== decoded["refreshtokencount"]) {
+        if (found_user.refreshTokenCount !== decoded["refreshTokenCount"]) {
             throw new RefreshTokenCountInvalidError()
         }
         found_user.refreshTokenCount++;

src/models/actions/ImportRunner.ts

@@ -0,0 +1,97 @@
+import { IsNotEmpty, IsOptional, IsString } from 'class-validator';
+import { getConnectionManager } from 'typeorm';
+import { RunnerGroupNeededError } from '../../errors/RunnerErrors';
+import { RunnerOrganizationNotFoundError } from '../../errors/RunnerOrganizationErrors';
+import { RunnerGroup } from '../entities/RunnerGroup';
+import { RunnerOrganization } from '../entities/RunnerOrganization';
+import { RunnerTeam } from '../entities/RunnerTeam';
+import { CreateRunner } from './create/CreateRunner';
+
+/**
+ * Special class used to import runners from csv files - or json arrays created from csv to be exact.
+ * Why you ask? Because the past has shown us that a non excel/csv based workflow is too much for most schools.
+ */
+export class ImportRunner {
+
+    /**
+     * The new runner's first name.
+     */
+    @IsString()
+    @IsNotEmpty()
+    firstname: string;
+
+    /**
+     * The new runner's middle name.
+     */
+    @IsString()
+    @IsOptional()
+    middlename?: string;
+
+    /**
+     * The new runner's last name.
+     */
+    @IsString()
+    @IsNotEmpty()
+    lastname: string;
+
+    /**
+     * The new runner's team's name (if not provided otherwise).
+     * The team will automaticly get generated if it doesn't exist in this org yet.
+     */
+    @IsString()
+    @IsOptional()
+    team?: string;
+
+    /**
+     * Just an alias for team, because this is usually only used for importing data from schools.
+     */
+    @IsOptional()
+    @IsString()
+    public set class(value: string) {
+        this.team = value;
+    }
+
+    /**
+     * Creates a CreateRunner object based on this.
+     * @param groupID Either the id of the new runner's group or the id of the org that the new runner's team is a part of.
+     */
+    public async toCreateRunner(groupID: number): Promise<CreateRunner> {
+        let newRunner: CreateRunner = new CreateRunner();
+
+        newRunner.firstname = this.firstname;
+        newRunner.middlename = this.middlename;
+        newRunner.lastname = this.lastname;
+        newRunner.group = (await this.getGroup(groupID)).id;
+
+        return newRunner;
+    }
+
+    /**
+     * Get's the new runners group.
+     * @param groupID Either the id of the new runner's group or the id of the org that the new runner's team is a part of.
+     */
+    public async getGroup(groupID: number): Promise<RunnerGroup> {
+        if (this.team === undefined && groupID === undefined) {
+            throw new RunnerGroupNeededError();
+        }
+
+        let team = await getConnectionManager().get().getRepository(RunnerTeam).findOne({ id: groupID });
+        if (team) { return team; }
+
+        let org = await getConnectionManager().get().getRepository(RunnerOrganization).findOne({ id: groupID });
+        if (!org) {
+            throw new RunnerOrganizationNotFoundError();
+        }
+        if (this.team === undefined) { return org; }
+
+        team = await getConnectionManager().get().getRepository(RunnerTeam).findOne({ name: this.team, parentGroup: org });
+        if (!team) {
+            let newRunnerTeam: RunnerTeam = new RunnerTeam();
+            newRunnerTeam.name = this.team;
+            newRunnerTeam.parentGroup = org;
+            team = await getConnectionManager().get().getRepository(RunnerTeam).save(newRunnerTeam);
+        }
+
+        return team;
+    }
+}

src/models/actions/RefreshAuth.ts

@@ -1,49 +1,56 @@
-import { IsString } from 'class-validator';
+import { IsOptional, IsString } from 'class-validator';
 import * as jsonwebtoken from 'jsonwebtoken';
 import { getConnectionManager } from 'typeorm';
-import { IllegalJWTError, JwtNotProvidedError, RefreshTokenCountInvalidError, UserNotFoundError } from '../../errors/AuthError';
+import { config } from '../../config';
+import { IllegalJWTError, JwtNotProvidedError, RefreshTokenCountInvalidError, UserDisabledError, UserNotFoundError } from '../../errors/AuthError';
+import { JwtCreator } from "../../jwtcreator";
 import { User } from '../entities/User';
-import { Auth } from '../responses/ResponseAuth';
+import { ResponseAuth } from '../responses/ResponseAuth';
 
+/**
+ * This class is used to create refreshed auth credentials.
+ * To be a little bit more exact: Is takes in a refresh token and creates a new access and refresh token for it's user.
+ * It of course checks for user existance, jwt validity and so on.
+ */
 export class RefreshAuth {
+    /**
+     * A stringyfied jwt refresh token.
+     * Will get checked for validity.
+     */
     @IsString()
-    token: string;
+    @IsOptional()
+    token?: string;
 
-    public async toAuth(): Promise<Auth> {
-        let newAuth: Auth = new Auth();
+    /**
+     * Creates a new auth object based on this.
+     */
+    public async toAuth(): Promise<ResponseAuth> {
+        let newAuth: ResponseAuth = new ResponseAuth();
         if (!this.token || this.token === undefined) {
             throw new JwtNotProvidedError()
         }
         let decoded
         try {
-            decoded = jsonwebtoken.verify(this.token, 'securekey')
+            decoded = jsonwebtoken.verify(this.token, config.jwt_secret)
         } catch (error) {
             throw new IllegalJWTError()
         }
-        const found_user = await getConnectionManager().get().getRepository(User).findOne({ id: decoded["userid"] });
+        const found_user = await getConnectionManager().get().getRepository(User).findOne({ id: decoded["id"] }, { relations: ['groups', 'permissions', 'groups.permissions'] });
         if (!found_user) {
             throw new UserNotFoundError()
         }
-        if (found_user.refreshTokenCount !== decoded["refreshtokencount"]) {
+        if (found_user.enabled == false) { throw new UserDisabledError(); }
+        if (found_user.refreshTokenCount !== decoded["refreshTokenCount"]) {
             throw new RefreshTokenCountInvalidError()
         }
-        delete found_user.password;
+        //Create the auth token
         const timestamp_accesstoken_expiry = Math.floor(Date.now() / 1000) + 5 * 60
-        delete found_user.password;
-        newAuth.access_token = jsonwebtoken.sign({
-            userdetails: found_user,
-            exp: timestamp_accesstoken_expiry
-        }, "securekey")
+        newAuth.access_token = JwtCreator.createAccess(found_user, timestamp_accesstoken_expiry);
         newAuth.access_token_expires_at = timestamp_accesstoken_expiry
-        // 
+        //Create the refresh token
         const timestamp_refresh_expiry = Math.floor(Date.now() / 1000) + 10 * 36000
-        newAuth.refresh_token = jsonwebtoken.sign({
-            refreshtokencount: found_user.refreshTokenCount,
-            userid: found_user.id,
-            exp: timestamp_refresh_expiry
-        }, "securekey")
-        newAuth.refresh_token_expires_at = timestamp_refresh_expiry
-
+        newAuth.refresh_token = JwtCreator.createRefresh(found_user, timestamp_refresh_expiry);
+        newAuth.refresh_token_expires_at = timestamp_refresh_expiry;
         return newAuth;
     }
 }

src/models/actions/ResetPassword.ts

@@ -0,0 +1,57 @@
+import * as Bun from 'bun';
+import { IsNotEmpty, IsOptional, IsString } from 'class-validator';
+import * as jsonwebtoken from 'jsonwebtoken';
+import { getConnectionManager } from 'typeorm';
+import { config } from '../../config';
+import { IllegalJWTError, JwtNotProvidedError, PasswordNeededError, RefreshTokenCountInvalidError, UserNotFoundError } from '../../errors/AuthError';
+import { User } from '../entities/User';
+
+/**
+ * This class can be used to reset a user's password.
+ * To set a new password the user needs to provide a valid password reset token.
+ */
+export class ResetPassword {
+    /**
+     * The reset token on which the password reset will be based.
+     */
+    @IsOptional()
+    @IsString()
+    resetToken?: string;
+
+    /**
+     * The user's new password
+     */
+    @IsNotEmpty()
+    @IsString()
+    password: string;
+
+
+    /**
+     * Create a password reset token based on this.
+     */
+    public async resetPassword(): Promise<any> {
+        if (!this.resetToken || this.resetToken === undefined) {
+            throw new JwtNotProvidedError()
+        }
+        if (!this.password || this.password === undefined) {
+            throw new PasswordNeededError()
+        }
+
+        let decoded;
+        try {
+            decoded = jsonwebtoken.verify(this.resetToken, config.jwt_secret)
+        } catch (error) {
+            throw new IllegalJWTError()
+        }
+
+        const found_user = await getConnectionManager().get().getRepository(User).findOne({ id: decoded["id"] });
+        if (!found_user) { throw new UserNotFoundError(); }
+        if (found_user.refreshTokenCount !== decoded["refreshTokenCount"]) { throw new RefreshTokenCountInvalidError(); }
+
+        found_user.refreshTokenCount = found_user.refreshTokenCount + 1;
+        found_user.password = await Bun.password.hash(this.password + found_user.uuid);
+        await getConnectionManager().get().getRepository(User).save(found_user);
+
+        return "password reset successfull";
+    }
+}

src/models/actions/create/CreateAnonymousDonation.ts

@@ -0,0 +1,29 @@
+import { IsInt, IsPositive } from 'class-validator';
+import { FixedDonation } from '../../entities/FixedDonation';
+import { CreateDonation } from './CreateDonation';
+
+/**
+ * This class is used to create a new FixedDonation entity from a json body (post request).
+ */
+export class CreateAnonymousDonation extends CreateDonation {
+
+    /**
+     * The donation's amount.
+     * The unit is your currency's smallest unit (default: euro cent).
+     */
+    @IsInt()
+    @IsPositive()
+    amount: number;
+
+    /**
+     * Creates a new FixedDonation entity from this.
+     */
+    public async toEntity(): Promise<FixedDonation> {
+        let newDonation = new FixedDonation;
+
+        newDonation.amount = this.amount;
+        newDonation.paidAmount = this.amount;
+
+        return newDonation;
+    }
+}

src/models/actions/create/CreateAuth.ts

@@ -0,0 +1,73 @@
+import * as Bun from 'bun';
+import { IsEmail, IsNotEmpty, IsOptional, IsString } from 'class-validator';
+import { getConnectionManager } from 'typeorm';
+import { InvalidCredentialsError, PasswordNeededError, UserDisabledError, UserNotFoundError } from '../../../errors/AuthError';
+import { UsernameOrEmailNeededError } from '../../../errors/UserErrors';
+import { JwtCreator } from '../../../jwtcreator';
+import { User } from '../../entities/User';
+import { ResponseAuth } from '../../responses/ResponseAuth';
+
+/**
+ * This class is used to create auth credentials based on user credentials provided in a json body (post request).
+ * To be a little bit more exact: Is takes in a username/email + password and creates a new access and refresh token for the user.
+ * It of course checks for user existance, password validity and so on.
+ */
+export class CreateAuth {
+    /**
+     * The username of the user that want's to login.
+     * Either username or email have to be provided.
+     */
+    @IsOptional()
+    @IsString()
+    username?: string;
+
+    /**
+     * The email address of the user that want's to login.
+     * Either username or email have to be provided.
+     */
+    @IsOptional()
+    @IsEmail()
+    @IsString()
+    email?: string;
+
+    /**
+     * The user's password.
+     * Will be checked against an argon2 hash.
+     */
+    @IsNotEmpty()
+    @IsString()
+    password: string;
+
+
+    /**
+     * Creates a new auth object based on this.
+     */
+    public async toAuth(): Promise<ResponseAuth> {
+        let newAuth: ResponseAuth = new ResponseAuth();
+
+        if (this.email === undefined && this.username === undefined) {
+            throw new UsernameOrEmailNeededError();
+        }
+        if (!this.password) {
+            throw new PasswordNeededError();
+        }
+        const found_user = await getConnectionManager().get().getRepository(User).findOne({ relations: ['groups', 'permissions', 'groups.permissions'], where: [{ username: this.username }, { email: this.email }] });
+        if (!found_user) {
+            throw new UserNotFoundError();
+        }
+        if (found_user.enabled == false) { throw new UserDisabledError(); }
+        if (!(await Bun.password.verify(this.password + found_user.uuid, found_user.password))) {
+            throw new InvalidCredentialsError();
+        }
+
+        //Create the access token
+        const timestamp_accesstoken_expiry = Math.floor(Date.now() / 1000) + 24 * 60 * 60
+        newAuth.access_token = JwtCreator.createAccess(found_user, timestamp_accesstoken_expiry);
+        newAuth.access_token_expires_at = timestamp_accesstoken_expiry
+        //Create the refresh token
+        const timestamp_refresh_expiry = Math.floor(Date.now() / 1000) + 7 * 24 * 60 * 60
+        newAuth.refresh_token = JwtCreator.createRefresh(found_user, timestamp_refresh_expiry);
+        newAuth.refresh_token_expires_at = timestamp_refresh_expiry
+        return newAuth;
+    }
+}

src/models/actions/create/CreateDistanceDonation.ts

@@ -0,0 +1,68 @@
+import { IsInt, IsOptional, IsPositive } from 'class-validator';
+import { getConnection } from 'typeorm';
+import { RunnerNotFoundError } from '../../../errors/RunnerErrors';
+import { DistanceDonation } from '../../entities/DistanceDonation';
+import { Runner } from '../../entities/Runner';
+import { CreateDonation } from './CreateDonation';
+
+/**
+ * This class is used to create a new FixedDonation entity from a json body (post request).
+ */
+export class CreateDistanceDonation extends CreateDonation {
+
+    /**
+     * The donation's associated donor's id.
+     * This is important to link donations to donors.
+     */
+    @IsInt()
+    @IsPositive()
+    donor: number;
+
+    /**
+     * The donation's paid amount in the smalles unit of your currency (default: euro cent).
+     */
+    @IsInt()
+    @IsOptional()
+    paidAmount?: number;
+
+    /**
+     * The donation's associated runner's id.
+     * This is important to link the runner's distance ran to the donation.
+     */
+    @IsInt()
+    @IsPositive()
+    runner: number;
+
+    /**
+     * The donation's amount per distance (full kilometer aka 1000 meters).
+     * The unit is your currency's smallest unit (default: euro cent).
+     */
+    @IsInt()
+    @IsPositive()
+    amountPerDistance: number;
+
+    /**
+     * Creates a new FixedDonation entity from this.
+     */
+    public async toEntity(): Promise<DistanceDonation> {
+        let newDonation = new DistanceDonation;
+
+        newDonation.amountPerDistance = this.amountPerDistance;
+        newDonation.paidAmount = this.paidAmount;
+        newDonation.donor = await this.getDonor();
+        newDonation.runner = await this.getRunner();
+
+        return newDonation;
+    }
+
+    /**
+     * Gets a runner based on the runner id provided via this.runner.
+     */
+    public async getRunner(): Promise<Runner> {
+        const runner = await getConnection().getRepository(Runner).findOne({ id: this.runner });
+        if (!runner) {
+            throw new RunnerNotFoundError();
+        }
+        return runner;
+    }
+}

src/models/actions/create/CreateDonation.ts

@@ -0,0 +1,30 @@
+import { IsInt, IsOptional } from 'class-validator';
+import { getConnection } from 'typeorm';
+import { Donation } from '../../entities/Donation';
+import { Donor } from '../../entities/Donor';
+
+/**
+ * This class is used to create a new Donation entity from a json body (post request).
+ */
+export abstract class CreateDonation {
+    @IsInt()
+    @IsOptional()
+    donor: number;
+
+    @IsInt()
+    @IsOptional()
+    paidAmount?: number;
+
+    /**
+     * Creates a new Donation entity from this.
+     */
+    public abstract toEntity(): Promise<Donation>;
+
+    /**
+     * Gets a donor based on the donor id provided via this.donor.
+     */
+    public async getDonor(): Promise<Donor> {
+        const donor = await getConnection().getRepository(Donor).findOne({ id: this.donor });
+        return donor;
+    }
+}

src/models/actions/create/CreateDonor.ts

@@ -0,0 +1,39 @@
+import { IsBoolean, IsOptional } from 'class-validator';
+import { DonorReceiptAddressNeededError } from '../../../errors/DonorErrors';
+import { Address } from '../../entities/Address';
+import { Donor } from '../../entities/Donor';
+import { CreateParticipant } from './CreateParticipant';
+
+/**
+ * This classed is used to create a new Donor entity from a json body (post request).
+ */
+export class CreateDonor extends CreateParticipant {
+
+    /**
+     * Does this donor need a receipt?
+     */
+    @IsBoolean()
+    @IsOptional()
+    receiptNeeded?: boolean = false;
+
+    /**
+     * Creates a new Donor entity from this.
+     */
+    public async toEntity(): Promise<Donor> {
+        let newDonor: Donor = new Donor();
+
+        newDonor.firstname = this.firstname;
+        newDonor.middlename = this.middlename;
+        newDonor.lastname = this.lastname;
+        newDonor.phone = this.phone;
+        newDonor.email = this.email;
+        newDonor.receiptNeeded = this.receiptNeeded;
+        newDonor.address = this.address;
+        Address.validate(newDonor.address);
+        if (this.receiptNeeded == true && Address.isValidAddress(newDonor.address) == false) {
+            throw new DonorReceiptAddressNeededError()
+        }
+
+        return newDonor;
+    }
+}

src/models/actions/create/CreateFixedDonation.ts

@@ -0,0 +1,44 @@
+import { IsInt, IsPositive } from 'class-validator';
+import { FixedDonation } from '../../entities/FixedDonation';
+import { CreateDonation } from './CreateDonation';
+
+/**
+ * This class is used to create a new FixedDonation entity from a json body (post request).
+ */
+export class CreateFixedDonation extends CreateDonation {
+
+    /**
+     * The donation's associated donor's id.
+     * This is important to link donations to donors.
+     */
+    @IsInt()
+    @IsPositive()
+    donor: number;
+
+    /**
+     * The donation's paid amount in the smalles unit of your currency (default: euro cent).
+     */
+    @IsInt()
+    paidAmount?: number;
+
+    /**
+     * The donation's amount.
+     * The unit is your currency's smallest unit (default: euro cent).
+     */
+    @IsInt()
+    @IsPositive()
+    amount: number;
+
+    /**
+     * Creates a new FixedDonation entity from this.
+     */
+    public async toEntity(): Promise<FixedDonation> {
+        let newDonation = new FixedDonation;
+
+        newDonation.amount = this.amount;
+        newDonation.paidAmount = this.paidAmount;
+        newDonation.donor = await this.getDonor();
+
+        return newDonation;
+    }
+}

src/models/actions/create/CreateGroupContact.ts

@@ -0,0 +1,97 @@
+import { IsEmail, IsNotEmpty, IsObject, IsOptional, IsPhoneNumber, IsString } from 'class-validator';
+import { getConnectionManager } from 'typeorm';
+import { config } from '../../../config';
+import { RunnerGroupNotFoundError } from '../../../errors/RunnerGroupErrors';
+import { Address } from '../../entities/Address';
+import { GroupContact } from '../../entities/GroupContact';
+import { RunnerGroup } from '../../entities/RunnerGroup';
+
+/**
+ * This classed is used to create a new GroupContact entity from a json body (post request).
+ */
+export class CreateGroupContact {
+    /**
+     * The new contact's first name.
+     */
+    @IsNotEmpty()
+    @IsString()
+    firstname: string;
+
+    /**
+     * The new contact's middle name.
+     */
+    @IsOptional()
+    @IsString()
+    middlename?: string;
+
+    /**
+     * The new contact's last name.
+     */
+    @IsNotEmpty()
+    @IsString()
+    lastname: string;
+
+    /**
+     * The new contact's address.
+     */
+    @IsOptional()
+    @IsObject()
+    address?: Address;
+
+    /**
+     * The contact's phone number.
+     * This will be validated against the configured country phone numer syntax (default: international).
+     */
+    @IsOptional()
+    @IsPhoneNumber(config.phone_validation_countrycode)
+    phone?: string;
+
+    /**
+     * The new contact's email address.
+     */
+    @IsOptional()
+    @IsEmail()
+    email?: string;
+
+    /**
+     * The new contacts's groups' ids.
+     * You can provide either one groupId or an array of groupIDs.
+     */
+    @IsOptional()
+    groups?: number[] | number
+
+
+    /**
+     * Get's all groups for this contact by their id's;
+     */
+    public async getGroups(): Promise<RunnerGroup[]> {
+        if (!this.groups) { return null; }
+        let groups = new Array<RunnerGroup>();
+        if (!Array.isArray(this.groups)) {
+            this.groups = [this.groups]
+        }
+        for (let group of this.groups) {
+            let found = await getConnectionManager().get().getRepository(RunnerGroup).findOne({ id: group });
+            if (!found) { throw new RunnerGroupNotFoundError(); }
+            groups.push(found);
+        }
+        return groups;
+    }
+
+    /**
+     * Creates a new GroupContact entity from this.
+     */
+    public async toEntity(): Promise<GroupContact> {
+        let newContact: GroupContact = new GroupContact();
+        newContact.firstname = this.firstname;
+        newContact.middlename = this.middlename;
+        newContact.lastname = this.lastname;
+        newContact.email = this.email;
+        newContact.phone = this.phone;
+        newContact.address = this.address;
+        Address.validate(newContact.address);
+        newContact.groups = await this.getGroups();
+
+        return newContact;
+    }
+}

src/models/actions/create/CreateParticipant.ts

@@ -0,0 +1,60 @@
+import { IsEmail, IsNotEmpty, IsObject, IsOptional, IsPhoneNumber, IsString } from 'class-validator';
+import { config } from '../../../config';
+import { Address } from '../../entities/Address';
+
+/**
+ * This classed is used to create a new Participant entity from a json body (post request).
+ */
+export abstract class CreateParticipant {
+    /**
+     * The new participant's first name.
+     */
+    @IsString()
+    @IsNotEmpty()
+    firstname: string;
+
+    /**
+     * The new participant's middle name.
+     */
+    @IsString()
+    @IsOptional()
+    middlename?: string;
+
+    /**
+     * The new participant's last name.
+     */
+    @IsString()
+    @IsNotEmpty()
+    lastname: string;
+
+    /**
+     * The new participant's phone number.
+     * This will be validated against the configured country phone numer syntax (default: international).
+     */
+    @IsString()
+    @IsOptional()
+    @IsPhoneNumber(config.phone_validation_countrycode)
+    phone?: string;
+
+    /**
+     * The new participant's e-mail address.
+     */
+    @IsString()
+    @IsOptional()
+    @IsEmail()
+    email?: string;
+
+    /**
+     * The new participant's address.
+     */
+    @IsOptional()
+    @IsObject()
+    address?: Address;
+
+    /**
+     * how the participant got into the system
+     */
+    @IsOptional()
+    @IsString()
+    created_via?: string;
+}