Passkey Authentication API

A secure, WebAuthn-based authentication system built with NestJS that implements passwordless authentication using passkeys.

Table of Contents

• Prerequisites
• Installation
  • Using Docker
  • Without Docker
• Development Setup
  • HTTPS for localhost
• API Documentation
• Environment Variables

Prerequisites

• Node.js (v20 or higher)
• PostgreSQL (v15 or higher)
• Docker & Docker Compose (for containerized setup)
• mkcert (for local HTTPS setup)

Installation

Using Docker

1. Clone the repository:

git clone https://github.com/tarunvaddeSoul/passkey-auth.git
cd passkey-auth

2. Create .env file:

cp .env.sample .env

3. Start the application:

# Development mode
docker compose up -d

# Apply prisma generate
docker compose exec api npx prisma generate
docker compose exec api npx prisma db push

4. Access the application:

• API: https://localhost:3000
• Swagger Documentation: https://localhost:3000/api

Without Docker

1. Clone the repository:

git clone https://github.com/tarunvaddeSoul/passkey-auth.git
cd passkey-auth

2. Install dependencies:

npm install

3. Set up the database:

# Create a PostgreSQL database
createdb passkey_db

# Apply prisma
npx prisma generate
npx prisma db push

4. Create .env file:

cp .env.example .env

5. Start the application:

# Development mode
npm run start:dev

# Production mode
npm run build
npm run start:prod

Development Setup

HTTPS for localhost

1. Install mkcert:

# macOS
brew install mkcert
mkcert -install

# Ubuntu/Debian
apt install mkcert
mkcert -install

# Windows (using Chocolatey)
choco install mkcert
mkcert -install

2. Generate certificates:

mkcert localhost

3. Update certificate paths in your code:

// main.ts
const httpsOptions = {
  key: fs.readFileSync('./localhost-key.pem'),
  cert: fs.readFileSync('./localhost.pem'),
};

4. Trust the certificates:

# The certificates should be automatically trusted after running mkcert -install
# You can verify by opening https://localhost:3000 in your browser

API Documentation

Once the application is running, visit https://localhost:3000/api for the Swagger documentation.

Authentication Flow

1. Registration
2. Authentication

Environment Variables

# Application
PORT=3000
RP_NAME=Your App Name
RP_ID=localhost
ORIGIN=https://localhost:3000

# Database
POSTGRES_USER=passkey_user
POSTGRES_PASSWORD=your_password
POSTGRES_DB=passkey_db
DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:5432/${POSTGRES_DB}