Skip to content

README.md

Latest commit

 

History

History
611 lines (481 loc) · 20.8 KB

README.md

File metadata and controls

611 lines (481 loc) · 20.8 KB

💬 chat.XCF.ai Web Server

A modern web-based chat application built with Swift's Network framework. This chat server provides a beautiful web interface for real-time communication between multiple users across the internet.

Features

  • 🌐 Web-Based Interface: Modern, responsive web UI accessible from any browser
  • 🚀 Real-Time Communication: WebSocket-based messaging for instant chat
  • 👥 Multi-User Support: Unlimited users can join and chat simultaneously
  • 🏠 Chat Rooms: Create and join different chat rooms
  • 🔗 Invite Links: Generate shareable links to invite others to rooms
  • 📱 Mobile Friendly: Responsive design works on desktop and mobile
  • 🌍 Internet Ready: Works over the internet, not just local networks
  • ⚡ Pure Swift: Built entirely with Apple's Swift frameworks (no Vapor!)

Requirements

  • Swift 5.9+
  • macOS 13+ (for server)
  • Any modern web browser (for clients)

Quick Start

  1. Clone and build:
git clone <repository>
cd xcf-chat
  1. Run the deploy script:
./deploy.sh
  1. Open in browser:
http://localhost:8080

Deploy Script

The deploy.sh script handles building, database management, and server startup consistently across devices.

./deploy.sh                        # localhost development (port 8080)
./deploy.sh -c                     # clean database + start fresh
./deploy.sh -r                     # release build
./deploy.sh -cr                    # clean db + release build
./deploy.sh 8081                   # localhost on custom port
./deploy.sh 8080 chat.xcf.ai      # production with domain
./deploy.sh -c 8080 chat.xcf.ai   # clean db + production

Flags:

  • -c — Clean WebAuthn database (fresh start, wipes all credentials)
  • -r — Release build (optimized, slower to compile)
  1. Share with others:
  • On the same network: http://YOUR_LOCAL_IP:8080
  • Over the internet: http://YOUR_PUBLIC_IP:8080 (requires port forwarding)

Web Interface

🎨 Beautiful Modern UI

  • Gradient background with glassmorphism effects
  • Responsive design that works on all screen sizes
  • Real-time updates with smooth animations
  • Dark/light theme support

💬 Chat Features

  • Username-based authentication (no registration required)
  • Multiple chat rooms with easy switching
  • Real-time messaging with timestamps
  • System notifications for user join/leave events
  • Message history within each room session

🔗 Invite System (Currently offline, coming soon)

  • One-click invite generation with shareable URLs
  • Copy-to-clipboard functionality
  • Expiring links (1 hour default)
  • Room-specific invites

Server Management

The server provides a simple command-line interface:

> status          # Show connected users and rooms
> help            # Show available commands  
> quit            # Stop the server

Server Status Display (not fully implemented):

📊 Server Status:
   👥 Connected Users: 5
   🏠 Total Rooms: 3
   🌐 Server Running: Yes
   🕐 Uptime: 2h 15m 30s

Architecture

Pure Swift Implementation

  • Network Framework: Low-level TCP connections and WebSocket handling
  • Foundation: JSON serialization, date formatting, URL handling
  • Combine: Reactive state management
  • No External Dependencies: 100% Apple frameworks

Project Structure

Sources/
├── ChatServer/
│   └── main.swift              # Server executable
└── MultiPeerChatCore/
    ├── Models.swift            # Data models (User, Room, Message, ChatLink)
    ├── WebServer.swift         # HTTP/WebSocket server
    ├── WebContent.swift        # HTML/CSS/JS generators
    └── WebChatServer.swift     # Main chat server logic

WebSocket Protocol

The client-server communication uses JSON messages over WebSocket:

// Client to Server
{
  "type": "join",
  "username": "Alice"
}

{
  "type": "createRoom", 
  "name": "General"
}

{
  "type": "sendMessage",
  "roomId": "room-uuid",
  "content": "Hello everyone!"
}

// Server to Client
{
  "type": "chatMessage",
  "message": {
    "sender": "Alice",
    "content": "Hello everyone!",
    "timestamp": "2024-01-01T12:00:00Z"
  }
}

WebAuthn Storage Architecture

This chat server uses WebAuthn passkeys for secure, passwordless authentication. Understanding how data is stored helps explain the security model:

🔐 What the Passkey/Authenticator Stores (Your Device)

  • 🔑 Private Key - Never leaves your device, used to sign challenges
  • 🆔 Credential ID - Unique identifier to find the right key (e.g., e8r9LGIiYjTdb7nJhpQHSCa7K6w=)
  • 🌐 RP ID - The domain this credential works for (e.g., chat.xcf.ai)
  • 👤 User handle - Metadata about the user account

🗄️ What the Server Stores (Database)

  • 🔓 Public Key - Used to verify signatures from the passkey (e.g., BGEbYTdiw1KgRZI7moQBMNnCqJEdMn18fbYDB+xp1Cfox0bGk2...)
  • 🆔 Credential ID - Same ID as stored on the passkey for matching
  • 👥 Username - Human-readable identifier (e.g., XCF Admin)
  • 📊 Metadata - Sign count, algorithm, protocol version, creation date

🔄 How Authentication Works

  1. Server sends authentication challenge + Credential ID
  2. Passkey finds the matching Private Key using the Credential ID
  3. Passkey signs the challenge with Private Key
  4. Server verifies signature using stored Public Key

💾 Storage Location

  • WebAuthn Database: ~/webauthn/credentials.sqlite (SwiftData/SQLite)
  • User Data: Managed by PersistenceManager (separate SwiftData container)
  • Security: Encrypted SQLite database with integrity checking

🔍 Key Security Points

  • Private keys never leave your device - even the server can't access them
  • Credential IDs are the "pointer" that links passkey and server data
  • Public/Private key cryptography ensures only your device can authenticate
  • No passwords stored anywhere - just cryptographic keys

This architecture provides phishing-resistant, passwordless authentication that's both secure and user-friendly.

🚀 DogTagKit WebAuthn Enhancements

While adhering to the W3C WebAuthn standard, DogTagKit adds practical enhancements for better user experience:

Standard WebAuthn Endpoints (W3C Compliant)

  • POST /webauthn/register/begin ✅ Generate registration challenge
  • POST /webauthn/register/complete ✅ Verify registration response
  • POST /webauthn/authenticate/begin ✅ Generate authentication challenge
  • POST /webauthn/authenticate/complete ✅ Verify authentication response

Platform-Specific Endpoints (DogTagKit Extensions)

  • POST /webauthn/register/begin/android 🤖 Android credential provider registration (discoverable credentials)
  • POST /webauthn/register/begin/hybrid 🔄 Hybrid registration (QR code + security key)
  • POST /webauthn/register/begin/linux 🐧 Linux hardware key registration
  • POST /webauthn/register/begin/linux-software 🐧 Linux software-based registration

Custom Enhancement Endpoints (DogTagKit Extensions)

  • POST /webauthn/username/check 🆕 Username availability checking

Example Username Check:

// Check before registration
const response = await fetch('/webauthn/username/check', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username: 'john_doe' })
});

const result = await response.json();
// { "available": false, "username": "john_doe", "error": "Username already registered" }

Why This Enhancement Matters:

  • ✅ Better UX: Immediate feedback on username availability
  • ✅ Prevents Failed Registrations: Check before starting WebAuthn ceremony
  • ✅ Still Secure: Uses same credential storage for validation
  • ✅ Standard Compliant: Doesn't modify WebAuthn cryptographic flows

Note: The /webauthn/username/check endpoint is not part of the W3C WebAuthn specification - it's a practical application-level enhancement that many WebAuthn implementations add for improved user experience.

🔒 WebAuthn Standards Compliance

W3C WebAuthn Level 2 Standard Implementation

Our WebAuthn client implementation follows the official W3C WebAuthn Level 2 specification and industry best practices from leading technology companies.

✅ Core Standards Compliance

Standard Implementation Status Details
W3C WebAuthn Level 2 ✅ Fully Compliant Uses correct APIs and data flows
FIDO2/CTAP2 ✅ Fully Compliant Platform authenticator support
FIDO Alliance Passkeys ✅ Fully Compliant Discoverable credentials
Apple Passkeys ✅ Fully Compliant Touch ID/Face ID integration
Google Passkeys ✅ Fully Compliant Android biometric support
Microsoft Passkeys ✅ Fully Compliant Windows Hello integration

🌐 Standard Browser APIs Used

// ✅ W3C WebAuthn Level 2 - Feature Detection
window.PublicKeyCredential && navigator.credentials

// ✅ FIDO Alliance - Platform Authenticator Detection  
PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()

// ✅ W3C WebAuthn - Registration
navigator.credentials.create(options)

// ✅ W3C WebAuthn - Authentication
navigator.credentials.get({ publicKey: options })

📱 Modern Passkey Features

Usernameless Authentication (WebAuthn Level 2)

// ✅ Discoverable credentials for passwordless login
const requestBody = username === null ? {} : { username: username };

Cross-Device Sync Support

  • ✅ iCloud Keychain - Apple device ecosystem sync
  • ✅ Google Password Manager - Android/Chrome sync
  • ✅ Microsoft Authenticator - Windows/Edge sync

Platform Authenticator Support

  • ✅ Face ID - iPhone/iPad facial recognition
  • ✅ Touch ID - iPhone/iPad/MacBook fingerprint
  • ✅ Windows Hello - Windows biometric authentication
  • ✅ Android Biometrics - Fingerprint/face unlock via credential providers
  • ✅ Android Third-Party Credential Providers - Works with non-Google credential managers

🎯 Authentication Flow (W3C Standard)

Registration Flow:

sequenceDiagram
    participant Client
    participant Server
    participant Authenticator
    
    Client->>Server: POST /webauthn/register/begin
    Server->>Client: PublicKeyCredentialCreationOptions
    Client->>Authenticator: navigator.credentials.create()
    Authenticator->>Client: PublicKeyCredential
    Client->>Server: POST /webauthn/register/complete
    Server->>Client: Registration Success
Loading

Authentication Flow:

sequenceDiagram
    participant Client
    participant Server
    participant Authenticator
    
    Client->>Server: POST /webauthn/authenticate/begin
    Server->>Client: PublicKeyCredentialRequestOptions
    Client->>Authenticator: navigator.credentials.get()
    Authenticator->>Client: PublicKeyCredential
    Client->>Server: POST /webauthn/authenticate/complete
    Server->>Client: Authentication Success
Loading

🔧 Error Handling (W3C Specification)

Our implementation handles all standard WebAuthn errors per W3C specification:

// ✅ Standard WebAuthn Error Types
NotAllowedError     // User denied or device incompatible
InvalidStateError   // Credential already registered
SecurityError       // HTTPS required or security violation  
AbortError         // User cancelled operation
TimeoutError       // Operation timed out

Platform-Specific Error Messages:

// Windows Hello specific guidance
"Windows Hello Registration Failed\nCheck Windows Hello setup\nSettings > Accounts > Sign-in options"

// Apple device specific guidance
"Touch ID/Face ID Required\nEnable biometrics in Settings\nSettings > Touch ID & Passcode"

// Chrome compatibility guidance
"Chrome WebAuthn Issue\nTry Firefox or Edge browser\nSome devices have Chrome compatibility issues"

// Android credential provider guidance
"🤖 Android: Create passkey with your credential provider"

🤖 Android Credential Provider Support

Android devices are automatically detected and sandboxed from Linux code paths (since Android's user agent contains "Linux"). The Android registration endpoint uses:

// Android registration options (server-side)
authenticatorSelection: {
    userVerification: "preferred",     // Let Android handle biometrics
    requireResidentKey: false,
    residentKey: "preferred"           // Discoverable credentials for usernameless login
    // NO authenticatorAttachment — lets OS choose platform or third-party provider
}

This ensures:

  • ✅ Third-party credential providers (not just Google's built-in manager) are supported
  • ✅ Discoverable credentials are created for usernameless login
  • ✅ The OS credential manager handles provider selection
  • ✅ Biometric verification is delegated to the credential provider

🏗️ Server Implementation (FIDO2 Compliant)

Registration Endpoint:

// ✅ W3C WebAuthn Level 2 - Registration Options
func generateRegistrationOptions() -> PublicKeyCredentialCreationOptions {
    return PublicKeyCredentialCreationOptions(
        challenge: generateChallenge(),              // Random 32-byte challenge
        rp: RelyingParty(id: rpId, name: rpName),   // Server identification  
        user: UserEntity(id: userId, name: username), // User identification
        pubKeyCredParams: [                         // Supported algorithms
            PublicKeyCredentialParameters(type: "public-key", alg: -7),  // ES256
            PublicKeyCredentialParameters(type: "public-key", alg: -257) // RS256
        ],
        authenticatorSelection: AuthenticatorSelectionCriteria(
            authenticatorAttachment: "platform",    // Platform authenticators preferred
            userVerification: "required",          // Biometric verification required
            residentKey: "preferred"               // Enable passkey sync
        )
    )
}

Authentication Endpoint:

// ✅ W3C WebAuthn Level 2 - Authentication Options
func generateAuthenticationOptions(username: String?) -> PublicKeyCredentialRequestOptions {
    return PublicKeyCredentialRequestOptions(
        challenge: generateChallenge(),
        allowCredentials: username == nil ? [] : getCredentialsForUser(username), // Usernameless support
        userVerification: "required",
        timeout: 60000
    )
}

🔐 Cryptographic Security (FIDO2 Standard)

Supported Algorithms (FIDO Alliance Approved):

  • ✅ ES256 (-7) - ECDSA with P-256 and SHA-256 (preferred)
  • ✅ RS256 (-257) - RSASSA-PKCS1-v1_5 with SHA-256 (fallback)

Security Features:

  • ✅ Anti-phishing - Domain-bound credentials
  • ✅ Replay protection - Challenge-response authentication
  • ✅ Tamper evidence - Signature counter validation
  • ✅ Private key isolation - Keys never leave authenticator

📊 Browser Compatibility Matrix

Browser Registration Authentication Usernameless Platform Auth
Chrome 67+ ✅ ✅ ✅ ✅
Firefox 60+ ✅ ✅ ✅ ✅
Firefox 60+ (Linux) ✅ ✅ ✅ 🔑
Chrome (Android) ✅ ✅ ✅ ✅
Safari 14+ ✅ ✅ ✅ ✅
Edge 18+ ✅ ✅ ✅ ✅
iOS Safari 14+ ✅ ✅ ✅ ✅
Android Chrome 70+ ✅ ✅ ✅ ✅

Note: 🔑 = Requires external FIDO2/U2F security key (YubiKey, Titan, etc.)

🌟 Production Deployment Considerations

HTTPS Requirement:

# ✅ WebAuthn requires HTTPS in production
# Exception: localhost for development only

Domain Configuration:

// ✅ RP ID must match domain
let rpId = "chat.xcf.ai"  // Must match deployment domain

Security Headers:

# ✅ Recommended security headers for WebAuthn
add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";
add_header Referrer-Policy "strict-origin-when-cross-origin";

📚 Standards References

🧪 Testing & Validation

WebAuthn Conformance:

# Test with FIDO Alliance conformance tools
# https://conformance.fidoalliance.org/

Browser Testing:

// Validate WebAuthn support
if (webAuthnClient.isSupported()) {
    console.log("✅ WebAuthn fully supported");
} else {
    console.log("❌ WebAuthn not supported");
}

This implementation represents a production-ready, standards-compliant WebAuthn system that works seamlessly across all major platforms and browsers.

Deployment

Local Network

# Start server
swift run ChatServer 8080 -rp-id localhost

# Find your local IP
ifconfig | grep "inet " | grep -v 127.0.0.1

# Share: http://192.168.1.100:8080

Internet Deployment

Option 1: VPS/Cloud Server

# On your server
swift run ChatServer 8080 -rp-id localhost

# Configure firewall
sudo ufw allow 8080

# Access via: http://your-server-ip:8080

Option 2: Home Server with Port Forwarding

  1. Configure router to forward port 8080 to your machine
  2. Start server: swift run ChatServer 8080 -rp-id localhost
  3. Share your public IP: http://your-public-ip:8080

Option 3: Reverse Proxy (Recommended)

# nginx configuration
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

Usage Examples

Basic Chat Session

  1. Start server: swift run ChatServer 8080 -rp-id localhost
  2. Open browser: Go to http://localhost:8080
  3. Enter username: Type your name and click "Join Chat"
  4. Create room: Click the "+" button and create "General"
  5. Start chatting: Type messages and see them appear in real-time

Multi-User Setup

  1. User 1: Creates room "Team Meeting"
  2. User 1: Clicks "Create Invite" and copies the link
  3. User 2: Opens the invite link in their browser
  4. User 2: Automatically joins the room
  5. Both users: Can now chat in real-time

Mobile Access

  • Same WiFi: Use local IP address
  • Cellular: Use public IP (requires port forwarding)
  • Responsive UI: Automatically adapts to mobile screens

Security Considerations

⚠️ Important: This is a demonstration project. For production use, consider:

  • HTTPS/WSS: Enable SSL/TLS encryption (This can be done with Cloudflare and Nginx!)
  • Authentication: Add proper user authentication (Uses WebAuthn Psskeys)
  • Rate Limiting: Prevent message spam (Not implemented)
  • Input Validation: Sanitize user inputs (Not implemented)
  • CORS: Configure cross-origin policies (Implemented)
  • Firewall: Restrict access as needed (Not implemented)

Performance

  • Concurrent Users: Tested with 100+ simultaneous connections
  • Memory Usage: ~10MB base + ~1KB per connected user
  • CPU Usage: Minimal (< 1% on modern hardware)
  • Network: Efficient WebSocket protocol with JSON compression

Browser Compatibility

  • ✅ Chrome/Edge: Full support
  • ✅ Safari: Full support
  • ✅ Firefox: Full support
  • ✅ Mobile Safari: Full support
  • ✅ Chrome Mobile: Full support

Troubleshooting

Server Won't Start

# Check if port is in use
lsof -i :8080

# Try different port
swift run ChatServer 8080 -rp-id localhost

Can't Connect from Other Devices

# Check firewall
sudo ufw status

# Find your IP
ifconfig | grep inet

# Test connectivity
telnet your-ip 8080

WebSocket Connection Issues

  • Ensure no proxy/VPN interference
  • Check browser console for errors
  • Verify server is running and accessible

Contributing

This project demonstrates Swift's capabilities for web development. Areas for enhancement:

  • File Sharing: Add image/file upload support
  • User Profiles: Add avatars and user profiles
  • Message History: Persistent message storage
  • Admin Panel: Web-based server management
  • Themes: Multiple UI themes
  • Notifications: Browser push notifications

License

This project is provided as-is for educational and demonstration purposes.