paskia 0.9.1__py3-none-any.whl → 0.10.2__py3-none-any.whl

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("FASTAPI_VUE_FRONTEND_URL") 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,75 @@
+"""Utilities for determining the auth UI host and base URLs."""
+
+import json
+import os
+from functools import lru_cache
+from urllib.parse import urlparse, 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
+
+    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,43 @@
+"""Minimal permission helpers with '*' wildcard support (no DB expansion)."""
+
+from collections.abc import Sequence
+from fnmatch import fnmatchcase
+
+from paskia import db
+from paskia.util.hostutil import normalize_host
+
+__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 _get_effective_scopes(ctx) -> set[str]:
+    """Get effective permission scopes from context.
+
+    Returns scopes from ctx.permissions (filtered by org) if available,
+    otherwise falls back to ctx.role.permissions for backwards compatibility.
+    """
+    if ctx.permissions:
+        return {p.scope for p in ctx.permissions}
+    # Fallback for contexts without effective permissions computed
+    return set(ctx.role.permissions or [])
+
+
+def has_any(ctx, patterns: Sequence[str]) -> bool:
+    return any(_match(_get_effective_scopes(ctx), patterns)) if ctx else False
+
+
+def has_all(ctx, patterns: Sequence[str]) -> bool:
+    return all(_match(_get_effective_scopes(ctx), 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 db.data().session_ctx(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,38 @@
+"""Utility functions for session validation and checking."""
+
+from datetime import UTC, datetime
+
+from paskia.authsession import EXPIRES
+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 time
+    if ctx.credential and ctx.credential.last_used:
+        auth_time = ctx.credential.last_used
+    else:
+        auth_time = ctx.session.expiry - EXPIRES
+
+    time_since_auth = datetime.now(UTC) - auth_time
+    return time_since_auth <= max_age_delta

paskia/util/startupbox.py

@@ -0,0 +1,103 @@
+"""Startup configuration box formatting utilities."""
+
+import os
+import re
+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)
+
+# ANSI color codes
+RESET = "\033[0m"
+YELLOW = "\033[33m"  # Dark yellow
+BRIGHT_YELLOW = "\033[93m"  # Bright yellow
+BRIGHT_WHITE = "\033[1;37m"  # Bold bright white
+
+
+def _visible_len(text: str) -> int:
+    """Calculate visible length of text, ignoring ANSI escape codes."""
+    return len(re.sub(r"\033\[[0-9;]*m", "", text))
+
+
+def line(text: str = "") -> str:
+    """Format a line inside the box with proper padding, truncating if needed."""
+    visible = _visible_len(text)
+    if visible > BOX_WIDTH:
+        text = text[: BOX_WIDTH - 1] + "…"
+        visible = BOX_WIDTH
+    padding = BOX_WIDTH - visible
+    return f"┃ {text}{' ' * padding} ┃\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."""
+    # Key graphic with yellow shading (bright for highlights, dark for body)
+    Y = YELLOW  # Dark yellow for main body
+    B = BRIGHT_YELLOW  # Bright yellow for highlights/edges
+    W = BRIGHT_WHITE  # Bold white for URL
+    R = RESET
+
+    lines = [top()]
+    lines.append(line(f" {B}▄▄▄▄▄{R}"))
+    lines.append(line(f"{B}█{Y}     {B}█{R} Paskia " + __version__))
+    lines.append(line(f"{B}█{Y}     {B}█{Y}▄▄▄▄▄▄▄▄▄▄▄▄{R}"))
+    lines.append(
+        line(
+            f"{B}█{Y}     {B}█{Y}▀▀▀▀{B}█{Y}▀▀{B}█{Y}▀▀{B}█{R}    {W}"
+            + config.site_url
+            + config.site_path
+            + R
+        )
+    )
+    lines.append(line(f" {Y}▀▀▀▀▀{R}"))
+
+    # 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("FASTAPI_VUE_FRONTEND_URL")
+    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))

paskia/util/timeutil.py

@@ -0,0 +1,47 @@
+"""Utility functions for parsing time durations."""
+
+import re
+from datetime import timedelta
+
+
+def parse_duration(duration_str: str) -> timedelta:
+    """Parse a duration string into a timedelta.
+
+    Supports units: s, m, min, h, d
+    Examples: "30s", "5m", "5min", "2h", "1d"
+
+    Args:
+        duration_str: A string like "30s", "5m", "2h"
+
+    Returns:
+        A timedelta object
+
+    Raises:
+        ValueError: If the format is invalid
+    """
+    duration_str = duration_str.strip().lower()
+
+    # Pattern matches: number + unit
+    # Units: s (seconds), m/min (minutes), h (hours), d (days)
+    pattern = r"^(\d+(?:\.\d+)?)(s|m|min|h|d)$"
+    match = re.match(pattern, duration_str)
+
+    if not match:
+        raise ValueError(
+            f"Invalid duration format: '{duration_str}'. "
+            "Expected format like '30s', '5m', '5min', '2h', or '1d'"
+        )
+
+    value = float(match.group(1))
+    unit = match.group(2)
+
+    if unit == "s":
+        return timedelta(seconds=value)
+    elif unit in ("m", "min"):
+        return timedelta(minutes=value)
+    elif unit == "h":
+        return timedelta(hours=value)
+    elif unit == "d":
+        return timedelta(days=value)
+    else:
+        raise ValueError(f"Unsupported time unit: {unit}")

paskia/util/useragent.py

@@ -0,0 +1,10 @@
+import user_agents
+
+
+def compact_user_agent(ua: str | None) -> str:
+    if not ua:
+        return "-"
+    u = user_agents.parse(ua)
+    ver = u.browser.version_string.split(".")[0]
+    dev = u.device.family if u.device.family not in ["Other", "Mac"] else ""
+    return f"{u.browser.family}/{ver} {u.os.family} {dev}".strip()

paskia/util/userinfo.py

@@ -0,0 +1,63 @@
+"""User information formatting and retrieval logic."""
+
+from paskia import aaguid, db
+from paskia.authsession import EXPIRES
+from paskia.db import SessionContext
+from paskia.util import hostutil, permutil
+from paskia.util.apistructs import ApiSession
+
+
+def build_session_context(ctx: SessionContext) -> dict:
+    """Build session context dict from SessionContext."""
+    result = {
+        "user": {"uuid": ctx.user.uuid, "display_name": ctx.user.display_name},
+        "org": {"uuid": ctx.org.uuid, "display_name": ctx.org.display_name},
+        "role": {"uuid": ctx.role.uuid, "display_name": ctx.role.display_name},
+        "permissions": [p.scope for p in ctx.permissions],
+    }
+    if ctx.user.theme:
+        result["user"]["theme"] = ctx.user.theme
+    return result
+
+
+async def build_user_info(
+    *,
+    user_uuid,
+    auth: str,
+    session_record,
+    request_host: str | None,
+) -> dict:
+    """Build user info dict for authenticated users."""
+    ctx = await permutil.session_context(auth, request_host)
+    user = db.data().users[user_uuid]
+    normalized_host = hostutil.normalize_host(request_host)
+
+    credentials = sorted(user.credentials, key=lambda c: c.created_at)
+    return {
+        "ctx": build_session_context(ctx),
+        "created_at": ctx.user.created_at,
+        "last_seen": ctx.user.last_seen,
+        "visits": ctx.user.visits,
+        "credentials": [
+            {
+                "credential": c.uuid,
+                "aaguid": c.aaguid,
+                "created_at": c.created_at,
+                "last_used": c.last_used,
+                "last_verified": c.last_verified,
+                "sign_count": c.sign_count,
+                "is_current_session": session_record.credential == c.uuid,
+            }
+            for c in credentials
+        ],
+        "aaguid_info": aaguid.filter(c.aaguid for c in credentials),
+        "sessions": [
+            ApiSession.from_db(
+                s,
+                current_key=auth,
+                normalized_host=normalized_host,
+                expires_delta=EXPIRES,
+            )
+            for s in user.sessions
+        ],
+    }

paskia/util/vitedev.py

@@ -0,0 +1,71 @@
+"""Vite dev server proxy for fetching frontend files during development.
+
+In dev mode (FASTAPI_VUE_FRONTEND_URL set), fetches files from Vite.
+In production, reads from the static build directory.
+
+This complements fastapi_vue.Frontend which handles static file serving
+but doesn't provide server-side fetching of HTML content.
+"""
+
+import asyncio
+import mimetypes
+import os
+from importlib import resources
+from pathlib import Path
+
+import httpx
+
+__all__ = ["read"]
+
+
+def _get_dev_server() -> str | None:
+    """Get the dev server URL from environment, or None if not in dev mode."""
+    return os.environ.get("FASTAPI_VUE_FRONTEND_URL") or None
+
+
+def _resolve_static_dir() -> Path:
+    """Resolve the static files directory."""
+
+    # 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"
+
+
+_static_dir: Path = _resolve_static_dir()
+
+
+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).
+    """
+    dev_server = _get_dev_server()
+    if 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 = _static_dir / filepath.lstrip("/")
+        content = await asyncio.to_thread(file_path.read_bytes)
+        mime, _ = mimetypes.guess_type(str(file_path))
+        return content, 200, {"content-type": mime or "application/octet-stream"}