From 8b98cb6325a242b55d47cf8f6cb49157bbb792be Mon Sep 17 00:00:00 2001 From: Leo Vasanko Date: Fri, 5 Dec 2025 16:15:50 +0000 Subject: [PATCH] Updated documentation. --- README.md | 145 ++++++++++++-------------------------------- examples/index.html | 4 +- pyproject.toml | 3 +- 3 files changed, 43 insertions(+), 109 deletions(-) diff --git a/README.md b/README.md index 4f7f00c..de8be6a 100644 --- a/README.md +++ b/README.md @@ -1,128 +1,61 @@ # Paskia -A minimal FastAPI WebAuthn server with WebSocket support for passkey registration. This project demonstrates WebAuthn registration flow with Resident Keys (discoverable credentials) using modern Python tooling. +An easy to install passkey-based authentication service that protects any web application with strong passwordless login. -## Features +## What is Paskia? -- ๐Ÿ” WebAuthn registration with Resident Keys support -- ๐Ÿ”Œ WebSocket-based communication for real-time interaction -- ๐Ÿš€ Modern Python packaging with `pyproject.toml` -- ๐ŸŽจ Clean, responsive HTML interface using @simplewebauthn/browser -- ๐Ÿ“ฆ No database required - challenges stored locally per connection -- ๐Ÿ› ๏ธ Development tools: `ruff` for linting and formatting -- ๐Ÿงน Clean architecture with local challenge management +- Easy to use fully featured auth&auth system (login and permissions) +- Organization and role-based access control (optional) + * Org admins control their users and roles + * Master admin can create multiple independent orgs + * Master admin makes permissions available for orgs to assign +- User Profile and Administration by API and web interface. +under `/auth/` or `auth.example.com` +- Reset tokens and additional device linking via QR code or codewords. +- Pure Python, FastAPI, packaged with prebuilt Vue frontend -## Docs +Two interfaces: +- API fetch: auth checks and login without leaving your app +- Forward-auth proxy: protect any unprotected site or service (Caddy, Nginx) -- Caddy integration: see `CADDY.md` for short, copy-paste snippets to secure your site with Caddy. +The API mode is useful for applications that can be customized to run with Paskia. Forward auth can also protect your javascript and other assets. Each provides fine-grained permission control and reauthentication requests where needed, and both can be mixed where needed. -## Requirements - -- Python 3.9+ -- A WebAuthn-compatible authenticator (security key, biometric device, etc.) +Single Sign-On (SSO): Users register once and authenticate across all applications under your domain name (configured rp-id). ## Quick Start -### Install (editable dev mode) +Install [UV](https://docs.astral.sh/uv/getting-started/installation/) and run: ```fish -uv pip install -e .[dev] +uvx paskia serve --rp-id example.com ``` -### Run (new CLI) +On the first run it downloads the software and prints a registration link for the Admin. Consider `uv tool install paskia` for a permanent install of `paskia` CLI. -`paskia` now provides subcommands: +The server will start up on [localhost:4401](http://localhost:4401) "for authentication required", serving for `*.example.com`. + +If you are going to be connecting `localhost` directly, for testing, leave out the rp-id. Otherwise you will need a web server such as [Caddy](https://caddyserver.com/) to serve HTTPS on your actual domain names and proxy requests to Paskia and your backend apps. + +## Configuration + +There is no config file. Pass only the options on CLI: ```text -paskia serve [host:port] [--options] +paskia serve [options] ``` -Examples (fish shell shown): +Options (all optional): -```fish -# Production style (no reload) -paskia serve -paskia serve 0.0.0.0:8080 --rp-id example.com --origin https://example.com +- Listen address (one of): + * `[host]:port`: Address and port (default: `localhost:4401`) + * `unix:/path.sock`: Unix socket +- `--rp-id `: Domain name for authentication (required for production) +- `--rp-name ""`: Name of your company or site (default: same as rp-id) +- `--origin `: Explicit single site (default: `https://`) +- `--auth-host `: Dedicated authentication site (e.g., `auth.example.com`) -# Development (auto-reload via scripts/dev.py) -python scripts/dev.py # localhost:4401 -python scripts/dev.py :5500 # localhost on port 5500 -python scripts/dev.py 127.0.0.1 # host only, default port 4401 -``` +## Documentation -Available options (both subcommands): - -```text ---rp-id Relying Party ID (default: localhost) ---rp-name Relying Party name (default: same as rp-id) ---origin Explicit origin (default: https://) -``` - -### Legacy Invocation - -If you previously used `python -m paskia.fastapi --dev --host ...`, switch to the new form above. The old flags `--host`, `--port`, and `--dev` are replaced by using `scripts/dev.py` for development mode. - -## Usage (Web) - -1. Start the server with one of the commands above -2. Open your browser to `http://localhost:4401/auth/` (or your chosen host/port) -3. Enter a username (or use the default) -4. Click "Register Passkey" -5. Follow your authenticator's prompts - -Real-time status updates stream over WebSocket. - -## Development - -### Code Quality - -```fish -# Run linting and formatting with ruff -uv run ruff check . -uv run ruff format . - -# Or with hatch -hatch run ruff check . -hatch run ruff format . -``` - -### Project Structure - -``` -paskia/ -โ”œโ”€โ”€ paskia/ -โ”‚ โ”œโ”€โ”€ __init__.py -โ”‚ โ””โ”€โ”€ main.py # FastAPI server with WebSocket support -โ”œโ”€โ”€ static/ -โ”‚ โ””โ”€โ”€ index.html # Frontend interface -โ”œโ”€โ”€ pyproject.toml # Modern Python packaging configuration -โ””โ”€โ”€ README.md -``` - -## Technical Details - -### WebAuthn Configuration - -- **Relying Party ID**: `localhost` (for development) -- **Resident Keys**: Required (enables discoverable credentials) -- **User Verification**: Preferred -- **Supported Algorithms**: ECDSA-SHA256, RSASSA-PKCS1-v1_5-SHA256 - -### WebSocket Message Flow - -1. Client connects to `/ws/{client_id}` -2. Client sends `registration_challenge` message -3. Server responds with `registration_challenge_response` -4. Client completes WebAuthn ceremony and sends `registration_response` -5. Server verifies and responds with `registration_success` or `error` - -### Security Notes - -- This is a minimal demo - challenges are stored locally per WebSocket connection -- For production use, implement proper user storage and session management -- Consider using Redis or similar for challenge storage in production with multiple server instances -- Ensure HTTPS in production environments - -## License - -MIT License - feel free to use this as a starting point for your own WebAuthn implementations! +- `API.md`: Complete HTTP and WebSocket API reference +- `Caddy.md`: Caddy configuration examples +- `Headers.md`: HTTP headers passed to protected applications diff --git a/examples/index.html b/examples/index.html index 42862eb..fa61440 100644 --- a/examples/index.html +++ b/examples/index.html @@ -33,8 +33,8 @@
-

๐Ÿ” Paskia

-

Development server demonstration page.

+

๐Ÿ” Paskia - Development Server

+

The following features are available after you have registered your Admin account and logged in. You should also use the Admin Site to create non-privileged users to see the Forbidden dialog caused by missing permissions.

diff --git a/pyproject.toml b/pyproject.toml index 0adec72..a49b7e2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,8 @@ build-backend = "hatchling.build" [project] name = "paskia" dynamic = ["version"] -description = "Passkey Authentication for Web Services" +description = "Passkey Auth made easy: all sites and APIs can be guarded even without any changes on the protected site." +keywords = [ "forward_auth", "auth_request", "FastAPI" ] authors = [ {name = "Leo Vasanko"}, ]