Developer Guide

Developer Guide

Table of Contents

1. Development Environment Setup
2. Code Style and Standards
3. Testing Procedures
4. Contribution Workflow
5. Release Process
6. Best Practices

Development Environment Setup

To set up a development environment for the Post-Quantum WebAuthn Platform, follow these steps:

1. Install Python 3.12+ and Git
2. Clone the repository: git clone https://github.com/FeitianTech/postquantum-webauthn-platform.git
3. Create a virtual environment: python3 -m venv .venv
4. Activate the virtual environment: source .venv/bin/activate (Linux/macOS) or .\.venv\scripts\activate (Windows)
5. Install dependencies: pip install -r requirements.txt
6. Install PQC extras: pip install ".[pqc]"

For local HTTPS development, install mkcert and generate certificates for demo.ftsafe.demo. The server expects certificate files named demo.ftsafe.demo.pem and demo.ftsafe.demo-key.pem in the project root.

The Dockerfile provides a complete build environment that includes prebuilt liboqs libraries and all necessary dependencies for post-quantum cryptography. The Docker build process uses a multi-stage approach to separate build dependencies from runtime dependencies, ensuring a minimal production image.

Section sources

• README.adoc
• requirements.txt
• Dockerfile

Code Style and Standards

The project follows standard Python coding conventions with specific requirements for both Python and JavaScript code:

For Python:

• Follow PEP 8 style guidelines
• Use type hints for function parameters and return values
• Include comprehensive docstrings for all public functions and classes
• Use descriptive variable and function names
• Follow the existing codebase patterns for consistency

For JavaScript:

• Use consistent indentation and spacing
• Follow camelCase naming convention for variables and functions
• Include JSDoc comments for complex functions
• Use const/let instead of var
• Follow ES6+ syntax where appropriate

The pyproject.toml file contains Poetry configuration for dependency management and package metadata. The main package version is defined in both pyproject.toml and fido2/init.py, currently at version "1.2.1-dev.0" indicating a development release.

Section sources

• pyproject.toml
• fido2/init.py
• server/pyproject.toml

Testing Procedures

The project uses pytest for testing with a comprehensive test suite organized in the tests/ directory. The test structure separates unit tests from device-specific tests:

• Core functionality tests in the root tests/ directory
• Hardware-in-the-loop tests in tests/device/ directory
• Test configuration in tests/conftest.py

To run tests locally:

pytest

To include device tests:

pytest --run-device-tests

The conftest.py file configures pytest with custom options and implements logic to skip device tests unless explicitly requested. This prevents accidental execution of potentially destructive hardware tests during regular development.

Test files follow the naming convention test_*.py and are organized to mirror the structure of the fido2 package. Each module has corresponding test files that validate its functionality, including edge cases and error conditions.

Section sources

• tests/conftest.py
• tests/test_webauthn.py
• README.adoc

Contribution Workflow

The contribution process follows standard GitHub pull request workflow:

1. Fork the repository and create a feature branch
2. Make changes following the code style guidelines
3. Write or update tests for new functionality
4. Run tests locally to ensure they pass
5. Commit changes with descriptive messages
6. Push to your fork and create a pull request

Pull requests should include:

• Clear description of the changes
• Reference to any related issues
• Explanation of the approach taken
• Any special testing instructions

Code reviews will focus on:

• Code quality and adherence to style guidelines
• Test coverage and correctness
• Documentation completeness
• Performance implications
• Security considerations

The CI/CD pipeline automatically runs on pull requests, executing tests and performing basic validation. Maintainers will review the code and may request changes before merging.

Section sources

• README.adoc
• cloudbuild.yaml
• render.yaml

Release Process

The release process is automated through CI/CD pipelines configured in cloudbuild.yaml and render.yaml:

1. Versioning follows semantic versioning (MAJOR.MINOR.PATCH)
2. Development versions use the format "x.x.x-dev.x"
3. Changelog updates are included in pull requests
4. Releases are built and deployed through automated pipelines

The Google Cloud Build configuration (cloudbuild.yaml) defines a multi-step process:

• Build the Docker image using BuildKit
• Push the image to Google Artifact Registry
• Deploy to Cloud Run with specified resource constraints

The Render configuration (render.yaml) provides an alternative deployment option using Render's platform, with automatic deployment enabled.

Package publishing is managed through Poetry, with configuration in pyproject.toml. The main package can be built and published to PyPI using standard Poetry commands.

Section sources

• pyproject.toml
• cloudbuild.yaml
• render.yaml
• Dockerfile

Best Practices

When working with the Post-Quantum WebAuthn Platform, consider these best practices:

1. Development Environment: Use the Docker setup for consistent environments across development teams
2. Testing: Always run relevant tests before committing changes
3. Code Organization: Follow the existing package structure when adding new functionality
4. Documentation: Update documentation when adding or changing features
5. Performance: Profile PQC operations as they can be computationally intensive
6. Security: Follow secure coding practices, especially for cryptographic operations

For debugging, use the Flask development server with debug mode enabled. The server logs provide detailed information about request processing and errors. When working with PQC algorithms, verify that the required liboqs libraries are properly installed and accessible.

When implementing new features, consider backward compatibility and the impact on existing functionality. For bug fixes, include a test case that reproduces the issue before applying the fix.

Section sources

• README.adoc
• server/server/app.py
• Dockerfile