paskia 0.7.1__tar.gz → 0.8.0__tar.gz

{paskia-0.7.1 → paskia-0.8.0}/.gitignore

@@ -5,6 +5,7 @@ dist/
 *.lock
 package-lock.json
 paskia.sqlite
+paskia.jsonl
 /paskia/frontend-build
 /paskia/_version.py
 coverage-html/

paskia-0.8.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: paskia
+Version: 0.8.0
+Summary: Passkey Auth made easy: all sites and APIs can be guarded even without any changes on the protected site.
+Project-URL: Homepage, https://git.zi.fi/LeoVasanko/paskia
+Project-URL: Repository, https://github.com/LeoVasanko/paskia
+Author: Leo Vasanko
+Keywords: FastAPI,auth_request,forward_auth
+Requires-Python: >=3.10
+Requires-Dist: aiofiles>=25.1.0
+Requires-Dist: base64url>=1.0.0
+Requires-Dist: fastapi[standard]>=0.104.1
+Requires-Dist: jsondiff>=2.2.1
+Requires-Dist: msgspec>=0.20.0
+Requires-Dist: pyjwt>=2.8.0
+Requires-Dist: user-agents>=2.2.0
+Requires-Dist: uuid7-standard>=1.0.0
+Requires-Dist: webauthn>=1.11.1
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: coverage[toml]>=7.0.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: migrate
+Requires-Dist: aiosqlite>=0.19.0; extra == 'migrate'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == 'migrate'
+Description-Content-Type: text/markdown
+
+# Paskia
+
+An easy to install passkey-based authentication service that protects any web application with strong passwordless login.
+
+## What is Paskia?
+
+- 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
+
+Two interfaces:
+- API fetch: auth checks and login without leaving your app
+- Forward-auth proxy: protect any unprotected site or service (Caddy, Nginx)
+
+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.
+
+Single Sign-On (SSO): Users register once and authenticate across all applications under your domain name (configured rp-id).
+
+## Quick Start
+
+Install [UV](https://docs.astral.sh/uv/getting-started/installation/) and run:
+
+```fish
+uvx paskia serve --rp-id example.com
+```
+
+On the first run it downloads the software and prints a registration link for the Admin.  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 (see documentation below).
+
+For a permanent install of `paskia` CLI command, not needing `uvx`:
+
+```fish
+uv tool install paskia
+```
+
+## Configuration
+
+There is no config file. Pass only the options on CLI:
+
+```text
+paskia serve [options]
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| Listen address | One of *host***:***port* (default all hosts, port 4401) or **unix:***path***/paskia.socket** (Unix socket) | **localhost:4401** |
+| --rp-id *domain* | Main/top domain | **localhost** |
+| --rp-name *"text"* | Name of your company or site | Same as rp-id |
+| --origin *url* | Explicitly list the domain names served | **https://**_rp-id_ |
+| --auth-host *domain* | Dedicated authentication site (e.g., **auth.example.com**) | **Unspecified:** we use **/auth/** on **every** site under rp-id.|
+
+## Further Documentation
+
+- [Caddy configuration](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/Caddy.md)
+- [Trusted Headers for Backend Apps](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/Headers.md)
+- [Frontend integration](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/Integration.md)
+- [Paskia API](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/API.md)

{paskia-0.7.1 → paskia-0.8.0}/README.md

@@ -30,16 +30,9 @@ Install [UV](https://docs.astral.sh/uv/getting-started/installation/) and run:
 uvx paskia serve --rp-id example.com
 ```
 
-On the first run it downloads the software and prints a registration link for the Admin. If you are going to be connecting `localhost` directly, for testing, leave out the rp-id.
+On the first run it downloads the software and prints a registration link for the Admin.  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.
 
-The server will start up on [localhost:4401](http://localhost:4401) "for authentication required", serving for `*.example.com`.
-
-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.
-
-A quick example without any config file:
-```fish
-sudo caddy reverse-proxy --from example.com --to :4401
-```
+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 (see documentation below).
 
 For a permanent install of `paskia` CLI command, not needing `uvx`:
 
@@ -55,18 +48,17 @@ There is no config file. Pass only the options on CLI:
 paskia serve [options]
 ```
 
-Optional options:
-
-- Listen address (one of):
-    * `[host]:port`: Address and port (default: `localhost:4401`)
-    * `unix:/path.sock`: Unix socket
-- `--rp-id <domain>`: Main domain (required for production)
-- `--rp-name "<text>"`: Name of your company or site (default: same as rp-id)
-- `--origin <url>`: Explicit single site (default: `https://<rp-id>`)
-- `--auth-host <domain>`: Dedicated authentication site (e.g., `auth.example.com`)
+| Option | Description | Default |
+|--------|-------------|---------|
+| Listen address | One of *host***:***port* (default all hosts, port 4401) or **unix:***path***/paskia.socket** (Unix socket) | **localhost:4401** |
+| --rp-id *domain* | Main/top domain | **localhost** |
+| --rp-name *"text"* | Name of your company or site | Same as rp-id |
+| --origin *url* | Explicitly list the domain names served | **https://**_rp-id_ |
+| --auth-host *domain* | Dedicated authentication site (e.g., **auth.example.com**) | **Unspecified:** we use **/auth/** on **every** site under rp-id.|
 
-## Documentation
+## Further Documentation
 
-- `API.md`: Complete HTTP and WebSocket API reference
-- `Caddy.md`: Caddy configuration examples
-- `Headers.md`: HTTP headers passed to protected applications
+- [Caddy configuration](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/Caddy.md)
+- [Trusted Headers for Backend Apps](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/Headers.md)
+- [Frontend integration](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/Integration.md)
+- [Paskia API](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/API.md)

paskia-0.8.0/coverage-html/.gitignore

@@ -0,0 +1,2 @@
+# Created by coverage.py
+*

paskia-0.8.0/docs/API.md

@@ -0,0 +1,64 @@
+# Paskia API
+
+For integrating Paskia with your app frontend, see [integration](Integration.md).
+
+## Web Interface
+
+| Method | Path | What it is for | Notes |
+|---:|---|---|---|
+| GET | `/auth/` | User profile page | |
+| GET | `/auth/admin/` | Admin panel | Requires auth:admin (master) or org admin permissions. |
+| GET | `/auth/{token}` | Reset / add credential URL (QR code link) | E.g. `/auth/fun.cotton.fresh.xray.lava` |
+
+### Public JSON API: `/auth/api/*`
+
+| Method | Path | Used for | Notes |
+|---:|---|---|---|
+| GET | `/auth/api/settings` | Paskia configuration | Returns RP info + base paths + session cookie name |
+| POST | `/auth/api/user-info` | Full user profile | Basic information, credentials, sessions, permissions |
+| POST | `/auth/api/logout` | Terminate session and delete session cookie | Signs out of the current site |
+| POST | `/auth/api/validate` | Validate and renew session cookie | Optional query: `perm=` (repeatable), `max_age=` |
+| GET | `/auth/api/forward` | Validate access (Caddy/Nginx) | 204 on success; 401/403 otherwise (HTML if requested) |
+
+The `validate` and `forward` endpoints take query arguments `perm=` and `max_age=` for specific requirements on the validation of the current session.
+
+### User JSON API: `/auth/api/user/*`
+
+| Method | Path | Used for | Notes |
+|---:|---|---|---|
+| PUT | `/auth/api/user/display-name` | Update the user’s display name | Body: JSON `{ "display_name": "..." }` |
+| POST | `/auth/api/user/logout-all` | Terminate all user sessions | Clears current host cookie |
+| DELETE | `/auth/api/user/session/{session_id}` | Terminate one session | Session IDs are server-issued |
+| DELETE | `/auth/api/user/credential/{uuid}` | Delete a credential | Requires recent authentication |
+| POST | `/auth/api/user/create-link` | Create a device-add link | Requires recent authentication |
+
+These are used mostly from the user profile panel and modify the current user.
+
+### Admin API: `/auth/api/admin/*`
+
+Normally only used via admin panel, requires auth admin permissions and can modify any users, orgs and permissions the session has access to.
+
+E.g. Org admin cannot see anything of the other orgs that he has no admin access to. Master admin `auth:admin` can see everything and create and manage orgs.
+
+### WebSockets: `/auth/ws/*`
+
+| Path | Used for | Notes |
+|---|---|---|
+| `WS /auth/ws/authenticate` | Passkey authentication | Returns a session token |
+| `WS /auth/ws/register` | Register a new credential | Adding another passkey to current user or via reset token |
+| `WS /auth/ws/remote-auth/request` | Start a cross-device login/registration request | Used from unauthenticated client |
+| `WS /auth/ws/remote-auth/permit` | Approve/deny a pairing code | Used to accept the request, if same words are entered |
+
+These are for internal use only, but are documented here because they are the core piece in all passkey operations.
+
+### Auth host mode (`--auth-host`)
+
+#### On the auth host:
+- The Web UI is served at site root (e.g. admin UI at `/admin/`), and the `/auth/...` equivalents (e.g. `/auth/admin/`) redirect to the root paths.
+- All of the API stays under `/auth/api/*`
+- Auth WebSockets remain at `/auth/ws/*` but take connections from other hosts to issue sessions for each of those.
+
+#### On non-auth hosts:
+- `/auth/` shows only minimal profile and allows logging out of the current site
+- `/auth/api/*` is served normally.
+- `/auth/api/user/*`, `/auth/api/admin/*`, and `/auth/ws/*` don't exist.

paskia-0.8.0/docs/Caddy.md

@@ -0,0 +1,79 @@
+# Paskia Caddy Configuration
+
+[Caddy](https://caddyserver.com/) is a modern web server that makes setting up web services easy. We provide a few Caddy snippets that make the configuration even easier, although the `forward_auth` directive of Caddy can be used directly as well. Place the [auth folder](../caddy/auth) with the snippets `require` and `setup` where your config file is (e.g. `/etc/caddy/auth`)
+
+What these snippets do
+- `setup`: Mount the auth UI at `/auth/` proxying to `:4401`
+- `require`: Use `/auth/api/forward` for access control
+- Render a login page or a permission denied page if needed (without changing URL)
+
+Your backend may not use authentication at all, or it can make use of the user information passed via `Remote-*` headers by the authentication system, see [trusted headers](Headers.md) for details.
+
+We assume the normal unprotected **Caddyfile** for your site looks like this:
+
+```caddyfile
+app.example.com {
+    @public path /.well-known/* /favicon.ico
+    handle @public {
+        root * /var/www/
+        file_server
+    }
+
+    handle {
+        reverse_proxy :3000  # Your app backend
+    }
+}
+```
+
+Note: We use the `handle @name` approach rather than `handle_path` to keep the path unaltered. Unlike bare directives, these blocks will be tried in sequence and each can contain what you'd typically put in your site definition (by default `reverse_proxy` takes precedence and nothing reaches the static files).
+
+We will adapt from this to protect your app.
+
+### Protect your site (auth/setup, auth/require)
+
+```caddyfile
+app.example.com {
+    import auth/setup
+
+    @public path /.well-known/* /favicon.ico
+    handle @public {
+        root * /var/www/
+        file_server
+    }
+
+    @reports path /reports
+    handle @reports {
+        import auth/require perm=myapp:reports
+        reverse_proxy :3000
+    }
+
+    handle {
+        import auth/require max-age=12h
+        reverse_proxy :3000
+    }
+}
+```
+
+The above setup allows unauthenticated access to certain files, then implements two different access controls for your backend app depending on which path is accessed. Note that the perm and max-age options may be combined, e.g. `perm=myapp:admin&max-age=5min` on a very sensitive endpoint. This will require additional authentication if the passkey hasn't been used in the last 5 minutes (automatic session renewals don't affect this). Use `""` if you only want the user to be authenticated with no time or perm requirements.
+
+### Dedicated Authentication Site
+
+When you setup a separate subdomain for the authentication site, just add to your config another section for the auth host:
+
+```caddyfile
+auth.example.com {
+    reverse_proxy :4401
+}
+```
+
+Remember to specify `paskia serve --auth-host auth.example.com` to restrict the authentication services to this domain.
+
+Note that we still reserve `/auth/` on each site for logout page and any APIs your application may require, while full user profile and global options are only available on the auth host.
+
+Paskia does not require CORS configuration, but it can access the authentication and registration of auth host WS API from the other sites as WebSockets don't require any CORS.
+
+### Override the paskia backend address (AUTH_UPSTREAM)
+
+By default, the auth service is contacted at localhost port 4401. You can point Caddy to a different address by setting the `AUTH_UPSTREAM` environment variable for Caddy.
+
+If unset, the snippets use `:4401` by default.

paskia-0.8.0/docs/Headers.md

@@ -0,0 +1,23 @@
+# Paskia Trusted Headers for Backend Apps
+
+| HTTP Header | Meaning | Example |
+|---|---|---|
+| `Remote-User` | Authenticated user UUID | **01c03276-b8f0-**… (string) |
+| `Remote-Name` | User display name | **John Doe** |
+| `Remote-Org` | Organization UUID | Identifier for user's org (string) |
+| `Remote-Org-Name` | Organization display name | **The Company Ltd.** |
+| `Remote-Role` | Role UUID | Identifier for user's role (string) |
+| `Remote-Role-Name` | Role display name | **Employee** |
+| `Remote-Groups` | Permissions the user has, comma separated | **auth:admin,yourapp:reports** |
+| `Remote-Session-Expires` | Session expiry timestamp (ISO 8601 UTC) | **2030-12-31T23:59:59Z** |
+| `Remote-Credential` | Credential UUID | Identifier for the sign-in passkey (string) |
+
+Similar headers are also used by other authentication systems like [Authelia](https://www.authelia.com/integration/trusted-header-sso/introduction/) to signal the backend application information about the signed in user.
+
+When a request is allowed, the auth service adds these headers by the forward-auth mechanism before proxying to your app as **request headers**. Your app can use them for user context to show on UI, or for its own authentication needs (e.g. prevent different orgs messing up with each other's data, logging which user performed an action).
+
+Only the UUID values should be used for identification needs, because they never change, even when things are renamed (display names change), and are never reused (created on authentication server). They are UUIDv7 so you can also extract the creation timestamp from them.
+
+Any `Remote-*` headers from clients are stripped by our [Caddy configuration](Caddy.md) to avoid dealing with any fake headers.
+
+Note: the headers are intended primarily for the backend, while either frontend or backend (passing the session cookie) can request `/auth/api/user-info` for more complete information, and that is the recommended way to do it in the frontend. See [integration](Integration.md) for more.

paskia-0.8.0/docs/Integration.md

@@ -0,0 +1,43 @@
+# Integrating Paskia with your App
+
+Protect API routes with forward-auth (see [Caddy configuration](Caddy.md)). Optionally protect your app assets and not just the API.
+
+Catch response status 401/403 in fetch calls to protected endpoints and implement authentication flow in this case. The response is JSON and contains `detail` (an error message describing what is needed) and `auth.iframe` (a URL). Render that URL in an iframe and retry the request after authentication (see below).
+
+While the app is in (active) use, call `/auth/api/validate` occasionally to keep the session alive (session lifetime is 24h), otherwise the user will have to login every day. Max-age limits are unaffected by this and can be used on endpoints needing to reauthenticate with passkey more frequently.
+
+Fetch `/auth/api/user-info` to display user/session details, or link to `/auth/` if you prefer using the built-in profile UI and not having to do anything more.
+
+## Authentication Flow (iframe)
+
+```js
+// Show an authentication dialog
+const iframe = document.createElement('iframe')
+iframe.src = auth.url   // from 401/403 response JSON
+iframe.style.cssText = `
+  position: fixed;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  border: 0;
+  z-index: 9999;
+  background: transparent;
+  backdrop-filter: blur(0.1rem) brightness(0.7);
+`
+document.body.appendChild(iframe)
+
+// Wait until user is finished with the dialog
+const handler = ev => {
+  if (ev.origin !== location.origin) return
+  iframe.remove()
+  removeEventListener('message', handler)
+  if (ev.data?.type === 'auth-success') retry_original_fetch()
+}
+addEventListener('message', handler)
+```
+
+This describes the frontend flow for handling 401/403 responses from endpoints protected by Paskia forward-auth, without ever exiting your app.
+
+When a protected request fails, the backend returns 401 (needs auth / reauth) or 403 (missing permission). For API requests, the response is JSON that includes an iframe URL. Your app should render that URL in a full-screen iframe overlay, and retry the request after the iframe reports success. If it reports `auth-cancel`, don't try again. The backdrop for the dialog is a stylistic choice, and you can style the background shown with the dialog any way you wish, and consider using CSS file with the iframe rather than inline styles as used in the example.
+
+Following this flow the user gets authenticated properly and after that your app keeps running as if nothing ever happened.