hitoshura25/mpo-api-authn-server repository overview

⁠MPO WebAuthn Authentication Server

A production-ready WebAuthn (FIDO2/Passkeys) authentication server built with KTor and comprehensive security testing.

⁠🏗️ Multi-Module Project Structure

This project follows a multi-module architecture for clear separation of concerns:

• webauthn-server/ - Main WebAuthn KTor server with production features
• webauthn-test-credentials-service/ - HTTP service for cross-platform testing credentials
• webauthn-test-lib/ - Shared WebAuthn test utilities library
• android-test-client/ - Android client with generated API library
• test-client/ - Web-based Playwright E2E tests

⁠🚀 Quick Start

⁠Prerequisites

• Java 21+
• Docker & Docker Compose
• Node.js 18+ (for web tests)

⁠Running the Server

# Start with Docker (recommended)
cd webauthn-server
./start-dev.sh

# Or run directly (requires local Redis/PostgreSQL)
./gradlew :webauthn-server:run

⁠Running Tests

# Server tests
./gradlew :webauthn-server:test

# Android client tests  
cd android-test-client && ./gradlew test

# Web E2E tests (requires server running)
cd test-client
npm install
npm test

⁠🌐 Port Assignments

• WebAuthn Server: 8080 (main API)
• WebAuthn Test Service: 8081 (cross-platform credential generation)
• Test Client: 8082 (E2E test web frontend)
• PostgreSQL: 5432
• Redis: 6379
• Jaeger UI: 16686

⁠🔐 Security Features

• WebAuthn 2.0/FIDO2 compliance using Yubico library
• Username enumeration protection - Authentication start doesn't reveal user existence
• Replay attack prevention - Challenge/response validation
• Cross-origin protection - Proper RP ID validation
• Comprehensive vulnerability testing - 7 security test categories

⁠📱 Client Generation

Generate client libraries for multiple platforms:

# Generate Android client
./gradlew :webauthn-server:copyGeneratedClientToLibrary

# Generate all clients (when implemented)
./gradlew :webauthn-server:generateAllClients

⁠🧪 Testing Architecture

The project uses a layered testing approach with different access patterns:

⁠Testing Layers

1. webauthn-test-lib - Shared credential generation library
2. webauthn-test-credentials-service - HTTP API wrapper (port 8081)
3. Integration tests - Use shared library directly for performance

⁠Cross-Platform Testing

Start the test service for external clients:

# Start test service
./gradlew :webauthn-test-credentials-service:run

# Test endpoints available at http://localhost:8081
# - POST /test/generate-registration-credential
# - POST /test/generate-authentication-credential
# - POST /test/clear
# - GET /test/sessions

Architecture Decisions:

• webauthn-server integration tests: Use shared library directly for performance and reliability
• Android client tests: Use HTTP API calls to webauthn-test-credentials-service for realistic cross-platform testing

⁠📊 Monitoring & Observability

• OpenTelemetry tracing with OTLP export
• Micrometer metrics with Prometheus export
• Automated vulnerability monitoring - Weekly scans with PR generation
• Code coverage reports with Kover

⁠🏛️ Architecture

⁠Storage

• PostgreSQL - Credential storage with quantum-safe encryption
• Redis - Session and challenge storage
• HikariCP - Connection pooling
• Flyway - Database migrations

⁠Security

• Post-quantum cryptography preparation with BouncyCastle
• Koin dependency injection for testability
• CBOR encoding for WebAuthn data structures

⁠API

• OpenAPI 3.0 specification with Swagger UI
• Jackson JSON processing with Kotlin support
• CORS configuration for web clients

⁠📚 Documentation

• Security Analysis⁠ - Vulnerability testing details
• Client Generation⁠ - Multi-platform client setup
• MCP Development⁠ - Claude Code integration
• GitHub Packages⁠ - Publishing setup

⁠🛠️ Development

⁠Module Commands

# Main server
./gradlew :webauthn-server:test
./gradlew :webauthn-server:run
./gradlew :webauthn-server:koverHtmlReport

# Test service  
./gradlew :webauthn-test-credentials-service:build
./gradlew :webauthn-test-credentials-service:run

# Shared test library
./gradlew :webauthn-test-lib:build

# Android client
cd android-test-client && ./gradlew test
cd android-test-client && ./gradlew client-library:publish

⁠Docker Development

# Start all dependencies
cd webauthn-server  
./start-dev.sh

# View logs
docker-compose logs -f

# Stop services
docker-compose down

⁠🤝 Contributing

1. Follow security-first development practices
2. All WebAuthn changes require security test coverage
3. Use git mv for file moves to preserve history
4. Generate clients after API changes
5. Update documentation for structural changes

⁠📄 License

[Add your license here]