paskia 0.7.1__py3-none-any.whl

paskia/sansio.py

@@ -0,0 +1,263 @@
+"""
+WebAuthn handler class that combines registration and authentication functionality.
+
+This module provides a unified interface for WebAuthn operations including:
+- Registration challenge generation and verification
+- Authentication challenge generation and verification
+- Credential validation
+"""
+
+import json
+from datetime import datetime, timezone
+from urllib.parse import urlparse
+from uuid import UUID
+
+import uuid7
+from webauthn import (
+    generate_authentication_options,
+    generate_registration_options,
+    verify_authentication_response,
+    verify_registration_response,
+)
+from webauthn.authentication.verify_authentication_response import (
+    VerifiedAuthentication,
+)
+from webauthn.helpers import (
+    options_to_json,
+    parse_authentication_credential_json,
+    parse_registration_credential_json,
+)
+from webauthn.helpers.cose import COSEAlgorithmIdentifier
+from webauthn.helpers.structs import (
+    AttestationConveyancePreference,
+    AuthenticationCredential,
+    AuthenticatorSelectionCriteria,
+    PublicKeyCredentialDescriptor,
+    ResidentKeyRequirement,
+    UserVerificationRequirement,
+)
+
+from paskia.db import Credential
+
+
+class Passkey:
+    """WebAuthn handler for registration and authentication operations."""
+
+    def __init__(
+        self,
+        rp_id: str,
+        rp_name: str | None = None,
+        origins: list[str] | None = None,
+        supported_pub_key_algs: list[COSEAlgorithmIdentifier] | None = None,
+    ):
+        """
+        Initialize the WebAuthn handler.
+
+        Args:
+            rp_id: Your security domain (e.g. "example.com")
+            rp_name: The relying party display name (e.g. "Example App"). May be shown in authenticators.
+            origins: List of allowed origin URLs (e.g. ["https://app.example.com", "https://auth.example.com"]).
+                    Each must be a subdomain or same as rp_id. If not provided, any subdomain of rp_id is allowed.
+            supported_pub_key_algs: List of supported COSE algorithms (default is EDDSA, ECDSA_SHA_256, RSASSA_PKCS1_v1_5_SHA_256).
+
+        Raises:
+            ValueError: If any origin domain doesn't match or isn't a subdomain of rp_id.
+        """
+        self.rp_id = rp_id
+        self.rp_name = rp_name or rp_id
+        self.allowed_origins: set[str] | None = None
+        if origins:
+            # Validate and deduplicate origins into a set for O(1) lookups
+            for o in origins:
+                self._validate_origin(o, rp_id)
+            self.allowed_origins = set(origins)
+        self.supported_pub_key_algs = supported_pub_key_algs or [
+            COSEAlgorithmIdentifier.EDDSA,
+            COSEAlgorithmIdentifier.ECDSA_SHA_256,
+            COSEAlgorithmIdentifier.RSASSA_PKCS1_v1_5_SHA_256,
+        ]
+
+    def _validate_origin(self, origin: str, rp_id: str) -> None:
+        """Validate an origin URL against the rp_id."""
+        hostname = urlparse(origin).hostname
+        if not hostname:
+            raise ValueError(f"Invalid origin URL: no hostname found in '{origin}'")
+
+        if hostname == rp_id or hostname.endswith(f".{rp_id}"):
+            return
+
+        raise ValueError(
+            f"Origin domain '{hostname}' must be the same as or a subdomain of rp_id '{rp_id}'"
+        )
+
+    def validate_origin(self, origin: str) -> str:
+        """Validate that origin is allowed and return it.
+
+        Args:
+            origin: The origin URL to validate (from WebSocket request header)
+
+        Returns:
+            The validated origin URL
+
+        Raises:
+            ValueError: If origin is not in the allowed list (when origins are configured)
+                       or if origin is not a valid subdomain of rp_id
+        """
+        self._validate_origin(origin, self.rp_id)
+        if self.allowed_origins is not None and origin not in self.allowed_origins:
+            raise ValueError(f"Origin '{origin}' is not in the allowed origins list")
+        return origin
+
+    ### Registration Methods ###
+
+    def reg_generate_options(
+        self,
+        user_id: UUID,
+        user_name: str,
+        credential_ids: list[bytes] | None = None,
+        origin: str | None = None,
+        **regopts,
+    ) -> tuple[dict, bytes]:
+        """
+        Generate registration options for WebAuthn registration.
+
+        Args:
+            user_id: The user ID as bytes
+            user_name: The username
+            credential_ids: For an already authenticated user, a list of credential IDs
+                associated with the account. This prevents accidentally adding another
+                credential on an authenticator that already has one of the listed IDs.
+            origin: The origin URL of the application (e.g. "https://app.example.com"). Must be a subdomain or same as rp_id, with port and scheme but no path included.
+            regopts: Additional arguments to generate_registration_options.
+
+        Returns:
+            JSON dict containing options to be sent to client,
+            challenge bytes to keep during the registration process.
+        """
+        options = generate_registration_options(
+            rp_id=self.rp_id,
+            rp_name=self.rp_name,
+            user_id=user_id.bytes,
+            user_name=user_name,
+            attestation=AttestationConveyancePreference.DIRECT,
+            authenticator_selection=AuthenticatorSelectionCriteria(
+                resident_key=ResidentKeyRequirement.REQUIRED,
+                user_verification=UserVerificationRequirement.PREFERRED,
+            ),
+            exclude_credentials=_convert_credential_ids(credential_ids),
+            supported_pub_key_algs=self.supported_pub_key_algs,
+            **regopts,
+        )
+        return json.loads(options_to_json(options)), options.challenge
+
+    def reg_verify(
+        self,
+        response_json: dict | str,
+        expected_challenge: bytes,
+        user_uuid: UUID,
+        origin: str,
+    ) -> Credential:
+        """
+        Verify registration response.
+
+        Args:
+            response_json: The credential response from the client
+            expected_challenge: The expected challenge bytes
+            user_uuid: The user's UUID
+            origin: The origin URL (required, must be pre-validated)
+
+        Returns:
+            Registration verification result
+        """
+        credential = parse_registration_credential_json(response_json)
+        registration = verify_registration_response(
+            credential=credential,
+            expected_challenge=expected_challenge,
+            expected_origin=origin,
+            expected_rp_id=self.rp_id,
+        )
+        return Credential(
+            uuid=uuid7.create(),
+            credential_id=credential.raw_id,
+            user_uuid=user_uuid,
+            aaguid=UUID(registration.aaguid),
+            public_key=registration.credential_public_key,
+            sign_count=registration.sign_count,
+            created_at=datetime.now(timezone.utc),
+        )
+
+    ### Authentication Methods ###
+
+    def auth_generate_options(
+        self,
+        *,
+        user_verification_required=False,
+        credential_ids: list[bytes] | None = None,
+        **authopts,
+    ) -> tuple[dict, bytes]:
+        """
+        Generate authentication options for WebAuthn authentication.
+
+        Args:
+            user_verification_required: The user will have to re-enter PIN or use biometrics for this operation. Useful when accessing security settings etc.
+            credential_ids: For an already known user, a list of credential IDs associated with the account (less prompts during authentication).
+            authopts: Additional arguments to generate_authentication_options.
+
+        Returns:
+            Tuple of (JSON dict to be sent to client, challenge bytes to store)
+        """
+        options = generate_authentication_options(
+            rp_id=self.rp_id,
+            user_verification=(
+                UserVerificationRequirement.REQUIRED
+                if user_verification_required
+                else UserVerificationRequirement.DISCOURAGED
+            ),
+            allow_credentials=_convert_credential_ids(credential_ids),
+            **authopts,
+        )
+        return json.loads(options_to_json(options)), options.challenge
+
+    def auth_parse(self, response: dict | str) -> AuthenticationCredential:
+        return parse_authentication_credential_json(response)
+
+    def auth_verify(
+        self,
+        credential: AuthenticationCredential,
+        expected_challenge: bytes,
+        stored_cred: Credential,
+        origin: str,
+    ) -> VerifiedAuthentication:
+        """
+        Verify authentication response against locally stored credential data.
+
+        Args:
+            credential: The authentication credential response from the client
+            expected_challenge: The earlier generated challenge bytes
+            stored_cred: The server stored credential record (modified by this function)
+            origin: The origin URL (required, must be pre-validated)
+        """
+        # Verify the authentication response
+        verification = verify_authentication_response(
+            credential=credential,
+            expected_challenge=expected_challenge,
+            expected_origin=origin,
+            expected_rp_id=self.rp_id,
+            credential_public_key=stored_cred.public_key,
+            credential_current_sign_count=stored_cred.sign_count,
+        )
+        stored_cred.sign_count = verification.new_sign_count
+        now = datetime.now(timezone.utc)
+        stored_cred.last_used = now
+        if verification.user_verified:
+            stored_cred.last_verified = now
+        return verification
+
+
+def _convert_credential_ids(
+    credential_ids: list[bytes] | None,
+) -> list[PublicKeyCredentialDescriptor] | None:
+    """A helper to convert a list of credential IDs to PublicKeyCredentialDescriptor objects, or pass through None."""
+    if credential_ids is None:
+        return None
+    return [PublicKeyCredentialDescriptor(id) for id in credential_ids]

paskia/util/frontend.py

@@ -0,0 +1,75 @@
+import asyncio
+import mimetypes
+import os
+from importlib import resources
+from pathlib import Path
+
+import httpx
+
+__all__ = ["path", "file", "read", "is_dev_mode"]
+
+
+def _get_dev_server() -> str | None:
+    """Get the dev server URL from environment, or None if not in dev mode."""
+    return os.environ.get("PASKIA_DEVMODE") or None
+
+
+def _resolve_static_dir() -> Path:
+    # Try packaged path via importlib.resources (works for wheel/installed).
+    try:  # pragma: no cover - trivial path resolution
+        pkg_dir = resources.files("paskia") / "frontend-build"
+        fs_path = Path(str(pkg_dir))
+        if fs_path.is_dir():
+            return fs_path
+    except Exception:  # pragma: no cover - defensive
+        pass
+    # Fallback for editable/development before build.
+    return Path(__file__).parent.parent / "frontend-build"
+
+
+path: Path = _resolve_static_dir()
+
+
+def file(*parts: str) -> Path:
+    """Return a child path under the static root."""
+    return path.joinpath(*parts)
+
+
+def is_dev_mode() -> bool:
+    """Check if we're running in dev mode (Vite frontend server)."""
+    return bool(_get_dev_server())
+
+
+async def read(filepath: str) -> tuple[bytes, int, dict[str, str]]:
+    """Read file content and return response tuple.
+
+    In dev mode, fetches from the Vite dev server.
+    In production, reads from the static build directory.
+
+    Args:
+        filepath: Path relative to frontend root, e.g. "/auth/index.html"
+
+    Returns:
+        Tuple of (content, status_code, headers) suitable for
+        FastAPI Response(*args) or Sanic raw response.
+    """
+    if is_dev_mode():
+        dev_server = _get_dev_server()
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(f"{dev_server}{filepath}")
+            resp.raise_for_status()
+            mime = resp.headers.get("content-type", "application/octet-stream")
+            # Strip charset suffix if present
+            mime = mime.split(";")[0].strip()
+            return resp.content, resp.status_code, {"content-type": mime}
+    else:
+        # Production: read from static build
+        file_path = path / filepath.lstrip("/")
+        content = await _read_file_async(file_path)
+        mime, _ = mimetypes.guess_type(str(file_path))
+        return content, 200, {"content-type": mime or "application/octet-stream"}
+
+
+async def _read_file_async(file_path: Path) -> bytes:
+    """Read file asynchronously using asyncio.to_thread."""
+    return await asyncio.to_thread(file_path.read_bytes)

paskia/util/hostutil.py

@@ -0,0 +1,76 @@
+"""Utilities for determining the auth UI host and base URLs."""
+
+import json
+import os
+from functools import lru_cache
+from urllib.parse import urlsplit
+
+
+@lru_cache(maxsize=1)
+def _load_config() -> dict:
+    """Load PASKIA_CONFIG JSON."""
+    config_json = os.getenv("PASKIA_CONFIG")
+    if not config_json:
+        return {}
+    return json.loads(config_json)
+
+
+def is_root_mode() -> bool:
+    return _load_config().get("auth_host") is not None
+
+
+def dedicated_auth_host() -> str | None:
+    """Return configured auth_host netloc, or None."""
+    auth_host = _load_config().get("auth_host")
+    if not auth_host:
+        return None
+    from urllib.parse import urlparse
+
+    parsed = urlparse(auth_host if "://" in auth_host else f"//{auth_host}")
+    return parsed.netloc or parsed.path or None
+
+
+def ui_base_path() -> str:
+    return "/" if is_root_mode() else "/auth/"
+
+
+def auth_site_url() -> str:
+    """Return the base URL for the auth site UI (computed at startup)."""
+    cfg = _load_config()
+    return cfg.get("site_url", "https://localhost") + cfg.get("site_path", "/auth/")
+
+
+def reset_link_url(token: str) -> str:
+    """Generate a reset link URL for the given token."""
+    return f"{auth_site_url()}{token}"
+
+
+def normalize_origin(origin: str) -> str:
+    """Normalize an origin URL by adding https:// if no scheme is present."""
+    if "://" not in origin:
+        return f"https://{origin}"
+    return origin
+
+
+def reload_config() -> None:
+    _load_config.cache_clear()
+
+
+def normalize_host(raw_host: str | None) -> str | None:
+    """Normalize a Host header preserving port (exact match required)."""
+    if not raw_host:
+        return None
+    candidate = raw_host.strip()
+    if not candidate:
+        return None
+    # urlsplit to parse (add // for scheme-less); prefer netloc to retain port.
+    parsed = urlsplit(candidate if "//" in candidate else f"//{candidate}")
+    netloc = parsed.netloc or parsed.path or ""
+    # Strip IPv6 brackets around host part but retain port suffix.
+    if netloc.startswith("["):
+        # format: [ipv6]:port or [ipv6]
+        if "]" in netloc:
+            host_part, _, rest = netloc.partition("]")
+            port_part = rest.lstrip(":")
+            netloc = host_part.strip("[]") + (f":{port_part}" if port_part else "")
+    return netloc.lower() or None

paskia/util/htmlutil.py

@@ -0,0 +1,47 @@
+"""Utility functions for HTML manipulation."""
+
+import re
+
+
+def patch_html_data_attrs(html: bytes, **data_attrs: str) -> bytes:
+    """Patch HTML by adding data attributes to the <html> tag.
+
+    If an <html> tag exists, adds data attributes to it.
+    If no <html> tag exists, prepends one with the data attributes.
+
+    Args:
+        html: The HTML content as bytes
+        **data_attrs: Key-value pairs for data attributes (e.g., mode='reauth')
+
+    Returns:
+        Modified HTML as bytes
+
+    Examples:
+        >>> patch_html_data_attrs(b'<html><body>test</body></html>', mode='reauth')
+        b'<html data-mode="reauth"><body>test</body></html>'
+
+        >>> patch_html_data_attrs(b'<body>test</body>', mode='reauth')
+        b'<html data-mode="reauth"><body>test</body>'
+    """
+    if not data_attrs:
+        return html
+
+    html_str = html.decode("utf-8")
+
+    # Build the data attributes string
+    attrs_str = " ".join(f'data-{key}="{value}"' for key, value in data_attrs.items())
+
+    # Check if there's an <html> tag (case-insensitive, may have existing attributes)
+    html_tag_pattern = re.compile(r"<html([^>]*)>", re.IGNORECASE)
+    match = html_tag_pattern.search(html_str)
+
+    if match:
+        # Insert data attributes into existing <html> tag
+        existing_attrs = match.group(1)
+        new_tag = f"<html{existing_attrs} {attrs_str}>"
+        html_str = html_tag_pattern.sub(new_tag, html_str, count=1)
+    else:
+        # Prepend <html> tag with data attributes
+        html_str = f"<html {attrs_str}>" + html_str
+
+    return html_str.encode("utf-8")

paskia/util/passphrase.py

@@ -0,0 +1,20 @@
+import secrets
+
+from paskia.util.wordlist import words
+
+N_WORDS = 5
+N_WORDS_SHORT = 3
+
+wset = set(words)
+
+
+def generate(n=N_WORDS, sep="."):
+    """Generate a password of random words without repeating any word."""
+    wl = words.copy()
+    return sep.join(wl.pop(secrets.randbelow(len(wl))) for i in range(n))
+
+
+def is_well_formed(passphrase: str, n=N_WORDS, sep=".") -> bool:
+    """Check if the passphrase is well-formed according to the regex pattern."""
+    p = passphrase.split(sep)
+    return len(p) == n and all(w in wset for w in passphrase.split("."))

paskia/util/permutil.py

@@ -0,0 +1,32 @@
+"""Minimal permission helpers with '*' wildcard support (no DB expansion)."""
+
+from collections.abc import Sequence
+from fnmatch import fnmatchcase
+
+from paskia.globals import db
+from paskia.util.hostutil import normalize_host
+from paskia.util.tokens import session_key
+
+__all__ = ["has_any", "has_all", "session_context"]
+
+
+def _match(perms: set[str], patterns: Sequence[str]):
+    return (
+        any(fnmatchcase(p, pat) for p in perms) if "*" in pat else pat in perms
+        for pat in patterns
+    )
+
+
+def has_any(ctx, patterns: Sequence[str]) -> bool:
+    return any(_match(ctx.role.permissions, patterns)) if ctx else False
+
+
+def has_all(ctx, patterns: Sequence[str]) -> bool:
+    return all(_match(ctx.role.permissions, patterns)) if ctx else False
+
+
+async def session_context(auth: str | None, host: str | None = None):
+    if not auth:
+        return None
+    normalized_host = normalize_host(host) if host else None
+    return await db.instance.get_session_context(session_key(auth), normalized_host)

paskia/util/pow.py

@@ -0,0 +1,45 @@
+"""
+Proof of Work utility using PBKDF2-SHA512.
+
+The PoW requires finding nonces where PBKDF2(challenge, nonce) produces
+output with a zero first byte. Each work unit requires finding one such nonce.
+All valid nonces are concatenated into a solution for server verification.
+"""
+
+import hashlib
+import secrets
+
+EASY = 2  # Around 0.25s
+NORMAL = 8  # Around 1s
+HARD = 32  # Around 4s
+
+
+def generate_challenge() -> bytes:
+    """Generate a random 8-byte challenge."""
+    return secrets.token_bytes(8)
+
+
+def verify_pow(challenge: bytes, solution: bytes, work: int = NORMAL) -> None:
+    """Verify a Proof of Work solution.
+
+    Args:
+        challenge: 8-byte server-provided challenge
+        solution: Concatenated 8-byte nonces (8 * work bytes)
+        work: Number of work units expected
+
+    Raises:
+        ValueError: If the solution is invalid
+    """
+    if len(challenge) != 8:
+        raise ValueError("Invalid challenge length")
+
+    if len(solution) != 8 * work:
+        raise ValueError("Invalid solution length")
+
+    # Verify each work unit - check that PBKDF2 output starts with 0x00
+    for i in range(work):
+        nonce = solution[i * 8 : (i + 1) * 8]
+        # Require first byte of PBKDF2-SHA512 to be zero
+        result = hashlib.pbkdf2_hmac("sha512", challenge, nonce, 128, 2)
+        if result[0] or result[1] & 0x07:
+            raise ValueError("Invalid PoW solution")

paskia/util/querysafe.py

@@ -0,0 +1,11 @@
+import re
+
+_SAFE_RE = re.compile(r"^[A-Za-z0-9:._~-]+$")
+
+
+def assert_safe(value: str, *, field: str = "value") -> None:
+    if not isinstance(value, str) or not value or not _SAFE_RE.match(value):
+        raise ValueError(f"{field} must match ^[A-Za-z0-9:._~-]+$")
+
+
+__all__ = ["assert_safe"]

paskia/util/sessionutil.py

@@ -0,0 +1,37 @@
+"""Utility functions for session validation and checking."""
+
+from datetime import datetime, timezone
+
+from paskia.db import SessionContext
+from paskia.util.timeutil import parse_duration
+
+
+def check_session_age(ctx: SessionContext, max_age: str | None) -> bool:
+    """Check if a session satisfies the max_age requirement.
+
+    Uses the credential's last_used timestamp to determine authentication age,
+    since session renewal can happen without re-authentication.
+
+    Args:
+        ctx: The session context containing session and credential info
+        max_age: Maximum age string (e.g., "5m", "1h", "30s") or None
+
+    Returns:
+        True if authentication is recent enough or max_age is None, False if too old
+
+    Raises:
+        ValueError: If max_age format is invalid
+    """
+    if not max_age:
+        return True
+
+    max_age_delta = parse_duration(max_age)
+
+    # Use credential's last_used time if available, fall back to session renewed
+    if ctx.credential and ctx.credential.last_used:
+        auth_time = ctx.credential.last_used
+    else:
+        auth_time = ctx.session.renewed
+
+    time_since_auth = datetime.now(timezone.utc) - auth_time
+    return time_since_auth <= max_age_delta

paskia/util/startupbox.py

@@ -0,0 +1,75 @@
+"""Startup configuration box formatting utilities."""
+
+import os
+from sys import stderr
+from typing import TYPE_CHECKING
+
+from paskia._version import __version__
+
+if TYPE_CHECKING:
+    from paskia.config import PaskiaConfig
+
+BOX_WIDTH = 60  # Inner width (excluding box chars)
+
+
+def line(text: str = "") -> str:
+    """Format a line inside the box with proper padding, truncating if needed."""
+    if len(text) > BOX_WIDTH:
+        text = text[: BOX_WIDTH - 1] + "…"
+    return f"┃ {text:<{BOX_WIDTH}} ┃\n"
+
+
+def top() -> str:
+    return "┏" + "━" * (BOX_WIDTH + 2) + "┓\n"
+
+
+def bottom() -> str:
+    return "┗" + "━" * (BOX_WIDTH + 2) + "┛\n"
+
+
+def print_startup_config(config: "PaskiaConfig") -> None:
+    """Print server configuration on startup."""
+    lines = [top()]
+    lines.append(line(" ▄▄▄▄▄"))
+    lines.append(line("█     █ Paskia " + __version__))
+    lines.append(line("█     █▄▄▄▄▄▄▄▄▄▄▄▄"))
+    lines.append(line("█     █▀▀▀▀█▀▀█▀▀█    " + config.site_url + config.site_path))
+    lines.append(line(" ▀▀▀▀▀"))
+
+    # Format auth host section
+    if config.auth_host:
+        lines.append(line(f"Auth Host:      {config.auth_host}"))
+
+    # Show frontend URL if in dev mode
+    devmode = os.environ.get("PASKIA_DEVMODE")
+    if devmode:
+        lines.append(line(f"Dev Frontend:   {devmode}"))
+
+    # Format listen address with scheme
+    if config.uds:
+        listen = f"unix:{config.uds}"
+    elif config.host:
+        listen = f"http://{config.host}:{config.port}"
+    else:
+        listen = f"http://0.0.0.0:{config.port} + [::]:{config.port}"
+    lines.append(line(f"Backend:        {listen}"))
+
+    # Relying Party line (omit name if same as id)
+    rp_id = config.rp_id
+    rp_name = config.rp_name
+    if rp_name and rp_name != rp_id:
+        lines.append(line(f"Relying Party:  {rp_id}  ({rp_name})"))
+    else:
+        lines.append(line(f"Relying Party:  {rp_id}"))
+
+    # Format origins section
+    allowed = config.origins
+    if allowed:
+        lines.append(line("Permitted Origins:"))
+        for origin in sorted(allowed):
+            lines.append(line(f"  - {origin}"))
+    else:
+        lines.append(line(f"Origin:         {rp_id} and all subdomains allowed"))
+
+    lines.append(bottom())
+    stderr.write("".join(lines))