= FIDO2/WebAuthn Test Platform and Developer Tools

image:https://img.shields.io/github/actions/workflow/status/FeitianTech/postquantum-webauthn-platform/ci.yml?label=CI&logo=github[CI,link="https://github.com/FeitianTech/postquantum-webauthn-platform/actions/workflows/ci.yml"]
image:https://img.shields.io/github/actions/workflow/status/FeitianTech/postquantum-webauthn-platform/ci.yml?label=Build&logo=github[Build,link="https://github.com/FeitianTech/postquantum-webauthn-platform/actions/workflows/ci.yml"]
image:https://img.shields.io/github/commit-activity/m/FeitianTech/postquantum-webauthn-platform?label=Commit%20Activity&logo=github[Commit Activity,link="https://github.com/FeitianTech/postquantum-webauthn-platform/pulse"]
image:https://img.shields.io/github/last-commit/FeitianTech/postquantum-webauthn-platform?label=Last%20Commit&logo=git[Last Commit,link="https://github.com/FeitianTech/postquantum-webauthn-platform/commits"]

**Production Deployment:** https://webauthndev.ftsafe.com

This project provides an end-to-end platform for exploring WebAuthn user flows secured by post-quantum cryptography. The hosted demo and local setup instructions help you register authenticators, run authentication process, and compare PQC signature suites in a realistic WebAuthn environment. Decoder is integrated for decoding attestation objects, WebAuthn type CBOR responses, authenticator metadata, etc. A FIDO MDS explorer is also built for direct retrieval of authenticator metadata information, and conducting root certificate verification. 
 
## Local Setup

**Scope**
- Includes: Python, virtual environment, Flask, python-fido2, and Post-Quantum Crypto (PQC) algorithms.
- Currently supporting ML-DSA 44/65/87 for PQC

> **Note for Developers:**  
> Setting up and building all local dependencies (Python environment, Flask/FIDO2/Cryptography, PQC libraries, liboqs builds, HTTPS certificates, etc.) requires significant configuration time and toolchain setup.
> For most use cases, it is far more efficient to use the deployed platform directly instead of running on local environment.


## Supported Platforms

- Windows 10/11 (64-bit)  
- macOS (Intel or Apple Silicon)  

A modern browser with WebAuthn support is required:
- Edge, Chrome, Safari, Firefox


## 1. Prerequisites

- **Git**: (https://git-scm.com/)  
- **Python 3.12+ ** with pip (https://www.python.org/downloads/)


## 2. Clone the Repository

```bash
git clone https://github.com/FeitianTech/postquantum-webauthn-platform.git
cd postquantum-webauthn-platform
```


## 3. Setup — pip + venv

### Windows (PowerShell)

```powershell
# Create and activate a virtual environment
py -3.12 -m venv .venv
.\.venv\scripts\activate

# Upgrade pip and install runtime dependencies
python -m pip install --upgrade pip
pip install -r requirements.txt

# Optional: PC/SC smart card extras
pip install "fido2[pcsc]"
```

### macOS

```bash
# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Upgrade pip and install runtime dependencies
python -m pip install --upgrade pip
pip install -r requirements.txt

# Optional: PC/SC smart card extras
pip install "fido2[pcsc]"
```

## PQC Setup

### 1. Activate Your Python Virtual Environment

**Windows (PowerShell):**
```powershell
.\.venv\scripts\activate
```

**macOS:**
```bash
source .venv/bin/activate
```

### 2. Install PQC Cryptography Libraries

**Using pip / virtualenv**
```bash
pip install ".[pqc]"
python -c "import oqs"
```
### 3. Install Open Quantum Safe (OQS) Libraries

#### Install `liboqs`

##### Windows

```powershell
# Clone liboqs
git clone --branch main https://github.com/open-quantum-safe/liboqs.git
cd liboqs

# Configure build
cmake -S . -B build -DOQS_BUILD_SHARED_LIBS=ON -DOQS_USE_OPENSSL=OFF

# Build in Release mode
cmake --build build --config Release
```
Output: build\bin\Release\oqs.dll

Copy the DLL into your Python venv so oqs can find it:

```
copy build\bin\Release\oqs.dll C:\path\to\your\venv\Lib\site-packages\oqs\
```

Or add the folder to your PATH.

##### macOS
```
# Clone liboqs
git clone --branch main https://github.com/open-quantum-safe/liboqs.git
cd liboqs

# Configure build
cmake -S . -B build -DOQS_BUILD_SHARED_LIBS=ON -DOQS_USE_OPENSSL=OFF

# Build in Release mode
cmake --build build --config Release

# Install the library (requires sudo)
sudo cmake --install build
```

#### 4. Install liboqs-python

Make sure you already built and installed **liboqs** (the C library).  
Now, clone and install the Python wrapper:

```bash
# Go to home directory
cd ~

# Clone liboqs-python
git clone https://github.com/open-quantum-safe/liboqs-python.git
cd liboqs-python

# Install into your active virtual environment
pip install .
```

#### 5. Verify Installation

From your **project root** (where your `.venv` is located):

```bash
cd ~/postquantum-webauthn-platform
python -c "import oqs; print(oqs.get_version()); print(oqs.get_enabled_sigs())"
```

If installed correctly, you should see something like: 
```
0.14.0-dev
['ML-DSA-44', 'ML-DSA-65', 'ML-DSA-87', ...]
```
This indicates the version number and supported algorithms. Make sure every PQC algorithm that you plan to use appears in the list above.


## mkcert Setup for Local HTTPS

### 1. Install mkcert

#### Windows
```bash
# Install Chocolatey
Set-ExecutionPolicy Bypass -Scope Process -Force; `
  [System.Net.ServicePointManager]::SecurityProtocol = `
  [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; `
  iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
# Install mkcert via Chocolatey
choco install mkcert -y
```

#### macOS
```bash
brew install mkcert
brew install nss   # required for Firefox users
mkcert -install
```


### 2. Generate Certificates

**Windows (PowerShell)**
```powershell
cd C:\path\to\your\project
mkcert demo.ftsafe.demo
```

**macOS (Terminal)**
```bash
cd /path/to/your/project
mkcert demo.ftsafe.demo
```

Important:
- WebAuthn only works on secure contexts (HTTPS or localhost).
- Rename files to:
  - `demo.ftsafe.demo.pem`
  - `demo.ftsafe.demo-key.pem`
  Otherwise, the program will fail to run.


## Quickstart

### 1. Create and Activate Virtual Environment

**Windows (PowerShell)**
```powershell
py -3 -m venv .venv
.\.venv\scripts\activate
```

**macOS**
```bash
python3 -m venv .venv
source .venv/bin/activate
```


### 2. Run the Server

```bash
python server/server/app.py
```

The first launch writes a Flask session secret to `instance/session-secret.key`. Keep that file alongside the application so
multiple restarts reuse the same secret; delete it if you need to rotate the key.

Expected output:
```
Running on https://demo.ftsafe.demo:5000/
```

Click the link to open the test app in your browser.