PasskeyBackend

💧 A demo backend for passkey authentication built with Vapor and WebAuthn for native Apple platforms (macOS/iOS).

Companion App: See PasskeyDemo for a complete macOS client implementation using this backend.

Features

• Passkey Authentication: WebAuthn-based passwordless authentication
• Email-Based Registration: Simple user registration using email addresses
• PRF Extension Support: Store and retrieve PRF salts for encryption key derivation
• Session-Based Auth: Secure session management for authenticated users
• Native App Compatible: Designed for AuthenticationServices framework (ASAuthorizationController)
• Database Management: Fluent ORM with SQLite (demo) or production databases

Setup

Prerequisites

• Swift 6.0+
• macOS 13.0+ (for development)
• A hosting platform (Fly.io, Heroku, etc.) for deployment

Local Development

1. Clone the repository:

   git clone https://github.com/peterspath/PasskeyBackend.git
   cd PasskeyBackend

2. Build the project:

   swift build

3. Run the server:

   swift run

   The server will start on http://0.0.0.0:8080

4. Test the endpoints (optional):

   curl http://localhost:8080
   # Should return: "It works!"

Deployment

Fly.io Deployment

1. Install Fly CLI:

   brew install flyctl

2. Login to Fly.io:

   fly auth login

3. Deploy the app:

   fly deploy

4. Set your domain: Update the domain in WebAuthnController.swift:15 to match your Fly.io app URL:

   let domainName = "your-app.fly.dev"

5. Update AASA file: IMPORTANT - Update the apple-app-site-association file in routes.swift:13 with your app's Team ID and Bundle ID:

   "apps": [ "TEAMID.your.bundle.identifier" ]

   Find your Team ID in Apple Developer portal and use your app's Bundle ID from Xcode.

Other Platforms

The project includes a Dockerfile and can be deployed to any platform that supports Docker containers:

• Heroku
• AWS ECS
• Google Cloud Run
• DigitalOcean App Platform

Database Migration

Migrations run automatically on startup. The database will be created at db.sqlite in the working directory.

For production, configure a PostgreSQL or MySQL database in configure.swift:16.

Client Implementation Notes

This backend is designed to work with native macOS/iOS apps using the AuthenticationServices framework:

1. Import AuthenticationServices in your app
2. Use ASAuthorizationPlatformPublicKeyCredentialProvider for passkey operations
3. Convert the Apple-specific credential types to WebAuthn standard format before sending to the backend
4. The backend expects credentials in the standard WebAuthn RegistrationCredential and AuthenticationCredential format

PRF (Pseudo-Random Function) Extension

The backend supports storing a PRF salt for each user, which can be used with the WebAuthn PRF extension for encryption key derivation:

• Send an optional prfSalt (Base64-encoded) during registration
• The salt is returned during login for client-side key derivation
• If not provided during registration, it can be updated on the first login that includes a salt
• This enables deterministic encryption keys derived from passkey authentication

Demo Limitations

This is a demonstration project and should not be used in production without additional security measures:

• In-memory sessions - Sessions are stored in memory and will be lost on server restart. Use Redis or a persistent session store for production.
• SQLite database - Not recommended for production. Use PostgreSQL, MySQL, or another production database.
• No rate limiting - Production deployments should implement rate limiting on authentication endpoints.
• Basic error handling - Production apps need more comprehensive error handling and logging.
• No HTTPS enforcement - Ensure HTTPS is enforced in production (handled by your hosting platform).
• Session security - Configure secure session cookies with httpOnly, secure, and sameSite flags in production.

Resources

• Vapor Website
• Vapor Documentation
• WebAuthn Specification
• PRF Extension Spec
• webauthn-swift
• Apple AuthenticationServices Documentation
• FIDO Alliance

License

BSD 3-Clause License - See LICENSE.md for details