paskia 0.7.2__tar.gz → 0.8.1__tar.gz

{paskia-0.7.2 → paskia-0.8.1}/.gitignore

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

{paskia-0.7.2 → paskia-0.8.1}/PKG-INFO

@@ -1,17 +1,19 @@
 Metadata-Version: 2.4
 Name: paskia
-Version: 0.7.2
+Version: 0.8.1
 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: aiosqlite>=0.19.0
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=25.1.0
 Requires-Dist: base64url>=1.0.0
+Requires-Dist: fastapi-vue>=0.3.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: sqlalchemy[asyncio]>=2.0.0
 Requires-Dist: user-agents>=2.2.0
 Requires-Dist: uuid7-standard>=1.0.0
 Requires-Dist: webauthn>=1.11.1
@@ -22,6 +24,9 @@ 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
@@ -56,16 +61,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`:
 
@@ -81,18 +79,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.7.2 → paskia-0.8.1}/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.7.2 → paskia-0.8.1}/paskia/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.7.2'
-__version_tuple__ = version_tuple = (0, 7, 2)
+__version__ = version = '0.8.1'
+__version_tuple__ = version_tuple = (0, 8, 1)
 
 __commit_id__ = commit_id = None

paskia-0.8.1/paskia/authsession.py

@@ -0,0 +1,75 @@
+"""
+Core session management for WebAuthn authentication.
+
+This module provides generic session management functionality that is
+independent of any web framework:
+- Session creation and validation
+- Token handling and refresh
+- Credential management
+"""
+
+from datetime import datetime, timezone
+from uuid import UUID
+
+from paskia import db
+from paskia.config import SESSION_LIFETIME
+from paskia.db import ResetToken, Session
+from paskia.util import hostutil
+
+EXPIRES = SESSION_LIFETIME
+
+
+def expires() -> datetime:
+    return datetime.now(timezone.utc) + EXPIRES
+
+
+def reset_expires() -> datetime:
+    from .config import RESET_LIFETIME
+
+    return datetime.now(timezone.utc) + RESET_LIFETIME
+
+
+async def get_reset(token: str) -> ResetToken:
+    """Validate a credential reset token."""
+    record = db.get_reset_token(token)
+    if record:
+        return record
+    raise ValueError("This authentication link is no longer valid.")
+
+
+async def get_session(token: str, host: str | None = None) -> Session:
+    """Validate a session token and return session data if valid."""
+    host = hostutil.normalize_host(host)
+    if not host:
+        raise ValueError("Invalid host")
+    session = db.get_session(token)
+    if session:
+        if session.host is None:
+            # First time binding: store exact host:port (or IPv6 form) now.
+            db.set_session_host(session.key, host)
+            session.host = host
+        elif session.host != host:
+            raise ValueError("Session host mismatch")
+        return session
+    raise ValueError("Your session has expired. Please sign in again!")
+
+
+async def refresh_session_token(token: str, *, ip: str, user_agent: str):
+    """Refresh a session extending its expiry."""
+    session_record = db.get_session(token)
+    if not session_record:
+        raise ValueError("Session not found or expired")
+    updated = db.update_session(
+        token,
+        ip=ip,
+        user_agent=user_agent,
+        expiry=expires(),
+    )
+    if not updated:
+        raise ValueError("Session not found or expired")
+
+
+async def delete_credential(credential_uuid: UUID, auth: str, host: str | None = None):
+    """Delete a specific credential for the current user."""
+    s = await get_session(auth, host=host)
+    db.delete_credential(credential_uuid, s.user_uuid)

{paskia-0.7.2 → paskia-0.8.1}/paskia/bootstrap.py

@@ -12,9 +12,9 @@ from datetime import datetime, timezone
 
 import uuid7
 
-from paskia import authsession, globals
+from paskia import authsession, db
 from paskia.db import Org, Permission, Role, User
-from paskia.util import hostutil, passphrase, tokens
+from paskia.util import hostutil, passphrase
 
 
 def _init_logger() -> logging.Logger:
@@ -42,9 +42,9 @@ async def _create_and_log_admin_reset_link(user_uuid, message, session_type) ->
     """Create an admin reset link and log it with the provided message."""
     token = passphrase.generate()
     expiry = authsession.reset_expires()
-    await globals.db.instance.create_reset_token(
+    db.create_reset_token(
         user_uuid=user_uuid,
-        key=tokens.reset_key(token),
+        passphrase=token,
         expiry=expiry,
         token_type=session_type,
     )
@@ -61,25 +61,32 @@ async def bootstrap_system() -> dict:
         dict: Contains information about created entities and reset link
     """
     # Create permission first - will fail if already exists
-    perm0 = Permission(id="auth:admin", display_name="Master Admin")
-    await globals.db.instance.create_permission(perm0)
+    perm0 = Permission(
+        uuid=uuid7.create(), scope="auth:admin", display_name="Master Admin"
+    )
+    db.create_permission(perm0)
+
+    # Create org admin permission - allows managing users within an org
+    perm_org_admin = Permission(
+        uuid=uuid7.create(), scope="auth:org:admin", display_name="Org Admin"
+    )
+    db.create_permission(perm_org_admin)
 
     org = Org(uuid7.create(), "Organization")
-    await globals.db.instance.create_organization(org)
+    db.create_organization(org)
 
-    # After creation, org.permissions now includes the auto-created org admin permission
-    # Allow this org to grant global admin explicitly
-    await globals.db.instance.add_permission_to_organization(str(org.uuid), perm0.id)
+    # Allow this org to grant global admin and org admin permissions
+    db.add_permission_to_organization(str(org.uuid), perm0.scope)
+    db.add_permission_to_organization(str(org.uuid), perm_org_admin.scope)
 
     # Create an Administration role granting both org and global admin
-    # Compose permissions for Administration role: global admin + org admin auto-perm
     role = Role(
         uuid7.create(),
         org.uuid,
         "Administration",
-        permissions=[perm0.id, *org.permissions],
+        permissions=[perm0.scope, perm_org_admin.scope],
     )
-    await globals.db.instance.create_role(role)
+    db.create_role(role)
 
     user = User(
         uuid=uuid7.create(),
@@ -88,7 +95,7 @@ async def bootstrap_system() -> dict:
         created_at=datetime.now(timezone.utc),
         visits=0,
     )
-    await globals.db.instance.create_user(user)
+    db.create_user(user)
 
     # Generate reset link and log it
     reset_link = await _create_and_log_admin_reset_link(
@@ -101,7 +108,11 @@ async def bootstrap_system() -> dict:
         "role": role,
         "permissions": [
             perm0,
-            *[Permission(id=p, display_name="") for p in org.permissions],
+            *[
+                db.get_permission_by_scope(p)
+                for p in org.permissions
+                if db.get_permission_by_scope(p)
+            ],
         ],
         "reset_link": reset_link,
     }
@@ -116,17 +127,13 @@ async def check_admin_credentials() -> bool:
     """
     try:
         # Get permission organizations to find admin users
-        permission_orgs = await globals.db.instance.get_permission_organizations(
-            "auth:admin"
-        )
+        permission_orgs = db.get_permission_organizations("auth:admin")
 
         if not permission_orgs:
             return False
 
         # Get users from the first organization with admin permission
-        org_users = await globals.db.instance.get_organization_users(
-            str(permission_orgs[0].uuid)
-        )
+        org_users = db.get_organization_users(str(permission_orgs[0].uuid))
         admin_users = [user for user, role in org_users if role == "Administration"]
 
         if not admin_users:
@@ -134,9 +141,7 @@ async def check_admin_credentials() -> bool:
 
         # Check first admin user for credentials
         admin_user = admin_users[0]
-        credentials = await globals.db.instance.get_credentials_by_user_uuid(
-            admin_user.uuid
-        )
+        credentials = db.get_credentials_by_user_uuid(admin_user.uuid)
 
         if not credentials:
             # Admin exists but has no credentials, create reset link
@@ -162,7 +167,7 @@ async def bootstrap_if_needed() -> bool:
     """
     try:
         # Check if the admin permission exists - if it does, system is already bootstrapped
-        await globals.db.instance.get_permission("auth:admin")
+        db.get_permission("auth:admin")
         # Permission exists, system is already bootstrapped
         # Check if admin needs credentials (only for already-bootstrapped systems)
         await check_admin_credentials()

{paskia-0.7.2 → paskia-0.8.1}/paskia/config.py

@@ -22,4 +22,3 @@ class PaskiaConfig:
     host: str | None = None
     port: int | None = None
     uds: str | None = None
-    devmode: bool = False

paskia-0.8.1/paskia/db/__init__.py

@@ -0,0 +1,178 @@
+"""
+Database module for WebAuthn passkey authentication.
+
+Read: Access _db._data directly, use build_* to convert to public structs.
+CTX: get_session_context(key) returns SessionContext with effective permissions.
+Write: Functions validate and commit, or raise ValueError.
+
+Usage:
+    from paskia import db
+
+    # Read (after init)
+    user_data = db._db._data.users[user_uuid]
+    user = db.build_user(user_uuid)
+
+    # Context
+    ctx = db.get_session_context(session_key)
+
+    # Write
+    db.create_user(user)
+"""
+
+from paskia.db.background import (
+    start_background,
+    start_cleanup,
+    stop_background,
+    stop_cleanup,
+)
+from paskia.db.operations import (
+    DB,
+    _db,
+    add_permission_to_organization,
+    add_permission_to_role,
+    build_credential,
+    build_org,
+    build_permission,
+    build_reset_token,
+    build_role,
+    build_session,
+    build_user,
+    cleanup_expired,
+    create_credential,
+    create_credential_session,
+    create_organization,
+    create_permission,
+    create_reset_token,
+    create_role,
+    create_session,
+    create_user,
+    delete_credential,
+    delete_organization,
+    delete_permission,
+    delete_reset_token,
+    delete_role,
+    delete_session,
+    delete_sessions_for_user,
+    delete_user,
+    get_credential_by_id,
+    get_credentials_by_user_uuid,
+    get_organization,
+    get_organization_users,
+    get_permission,
+    get_permission_by_scope,
+    get_permission_organizations,
+    get_reset_token,
+    get_role,
+    get_roles_by_organization,
+    get_session,
+    get_session_context,
+    get_user_by_uuid,
+    get_user_organization,
+    init,
+    list_organizations,
+    list_permissions,
+    list_sessions_for_user,
+    login,
+    remove_permission_from_organization,
+    remove_permission_from_role,
+    rename_permission,
+    set_session_host,
+    update_credential_sign_count,
+    update_organization_name,
+    update_permission,
+    update_role_name,
+    update_session,
+    update_user_display_name,
+    update_user_role,
+    update_user_role_in_organization,
+)
+from paskia.db.structs import (
+    Credential,
+    Org,
+    Permission,
+    ResetToken,
+    Role,
+    Session,
+    SessionContext,
+    User,
+)
+
+__all__ = [
+    # Types
+    "Credential",
+    "DB",
+    "Org",
+    "Permission",
+    "ResetToken",
+    "Role",
+    "Session",
+    "SessionContext",
+    "User",
+    # Instance
+    "_db",
+    "init",
+    # Background
+    "start_background",
+    "stop_background",
+    "start_cleanup",
+    "stop_cleanup",
+    # Builders
+    "build_credential",
+    "build_org",
+    "build_permission",
+    "build_reset_token",
+    "build_role",
+    "build_session",
+    "build_user",
+    # Read ops
+    "get_credential_by_id",
+    "get_credentials_by_user_uuid",
+    "get_organization",
+    "get_organization_users",
+    "get_permission",
+    "get_permission_by_scope",
+    "get_permission_organizations",
+    "get_reset_token",
+    "get_role",
+    "get_roles_by_organization",
+    "get_session",
+    "get_session_context",
+    "get_user_by_uuid",
+    "get_user_organization",
+    "list_organizations",
+    "list_permissions",
+    "list_sessions_for_user",
+    # Write ops
+    "add_permission_to_organization",
+    "add_permission_to_role",
+    "cleanup_expired",
+    "create_credential",
+    "create_credential_session",
+    "create_organization",
+    "create_permission",
+    "create_reset_token",
+    "create_role",
+    "create_session",
+    "create_user",
+    "delete_credential",
+    "delete_organization",
+    "delete_permission",
+    "delete_reset_token",
+    "delete_role",
+    "delete_session",
+    "delete_sessions_for_user",
+    "delete_user",
+    "login",
+    "remove_permission_from_organization",
+    "remove_permission_from_role",
+    "rename_permission",
+    "set_session_host",
+    "update_credential_sign_count",
+    "update_organization_name",
+    "update_permission",
+    "update_role_name",
+    "update_session",
+    "update_user_display_name",
+    "update_user_role",
+    "update_user_role_in_organization",
+]

paskia-0.8.1/paskia/db/background.py

@@ -0,0 +1,128 @@
+"""
+Background task for database maintenance.
+
+Periodically flushes pending changes to disk and cleans up expired items.
+"""
+
+import asyncio
+import logging
+from datetime import datetime, timezone
+
+from paskia.db.jsonl import flush_changes
+
+# Flush changes to disk every N seconds
+FLUSH_INTERVAL = 1
+# Cleanup expired items every N seconds (cheap when nothing to remove)
+CLEANUP_INTERVAL = 1
+
+
+_logger = logging.getLogger(__name__)
+_background_task: asyncio.Task | None = None
+
+
+def cleanup() -> None:
+    """Remove expired sessions and reset tokens from the database."""
+    from paskia.db.operations import _db
+
+    if _db is None or _db._data is None:
+        return
+
+    with _db.transaction("expiry"):
+        current_time = datetime.now(timezone.utc)
+
+        # Clean expired sessions
+        to_delete_sessions = [
+            k for k, s in _db._data.sessions.items() if s.expiry < current_time
+        ]
+        for k in to_delete_sessions:
+            del _db._data.sessions[k]
+
+        # Clean expired reset tokens
+        to_delete_tokens = [
+            k for k, t in _db._data.reset_tokens.items() if t.expiry < current_time
+        ]
+        for k in to_delete_tokens:
+            del _db._data.reset_tokens[k]
+
+
+async def flush() -> None:
+    """Write all pending database changes to disk."""
+    from paskia.db.operations import _db
+
+    if _db is None:
+        _logger.warning("flush() called but _db is None")
+        return
+    await flush_changes(_db.db_path, _db._pending_changes)
+
+
+async def _background_loop():
+    """Background task that periodically flushes changes and cleans up."""
+    # Run cleanup immediately on startup to clear old expired items
+    cleanup()
+    await flush()
+
+    last_cleanup = datetime.now(timezone.utc)
+
+    while True:
+        try:
+            await asyncio.sleep(FLUSH_INTERVAL)
+            # Flush pending changes to disk
+            await flush()
+
+            # Run cleanup less frequently
+            now = datetime.now(timezone.utc)
+            if (now - last_cleanup).total_seconds() >= CLEANUP_INTERVAL:
+                cleanup()
+                await flush()  # Flush cleanup changes
+                last_cleanup = now
+        except asyncio.CancelledError:
+            # Final flush before exit
+            await flush()
+            break
+        except Exception:
+            _logger.debug("Error in database background loop", exc_info=True)
+
+
+async def start_background():
+    """Start the background flush/cleanup task."""
+    global _background_task
+
+    # Check if task exists but is no longer running (e.g., after uvicorn reload)
+    if _background_task is not None:
+        if _background_task.done():
+            _logger.debug("Previous background task was done, restarting")
+            _background_task = None
+        else:
+            # Task exists and is running - but might be in a dead event loop
+            try:
+                # Check if task is in current event loop
+                loop = asyncio.get_running_loop()
+                task_loop = _background_task.get_loop()
+                if loop is not task_loop:
+                    _logger.debug("Background task in different event loop, restarting")
+                    _background_task = None
+            except Exception as e:
+                _logger.debug("Error checking background task loop: %s, restarting", e)
+                _background_task = None
+
+    if _background_task is None:
+        _background_task = asyncio.create_task(_background_loop())
+    else:
+        _logger.debug("Background task already running: %s", _background_task)
+
+
+async def stop_background():
+    """Stop the background task and flush any pending changes."""
+    global _background_task
+    if _background_task:
+        _background_task.cancel()
+        try:
+            await _background_task
+        except asyncio.CancelledError:
+            pass
+        _background_task = None
+
+
+# Aliases for backwards compatibility
+start_cleanup = start_background
+stop_cleanup = stop_background