paskia 0.9.1__tar.gz → 0.10.2__tar.gz

{paskia-0.9.1 → paskia-0.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paskia
-Version: 0.9.1
+Version: 0.10.2
 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
@@ -31,6 +31,8 @@ Description-Content-Type: text/markdown
 
 # Paskia
 
+![Screenshot](https://git.zi.fi/leovasanko/paskia/raw/main/docs/screenshots/forbidden-light.webp)
+
 An easy to install passkey-based authentication service that protects any web application with strong passwordless login.
 
 ## What is Paskia?
@@ -58,12 +60,12 @@ Single Sign-On (SSO): Users register once and authenticate across all applicatio
 Install [UV](https://docs.astral.sh/uv/getting-started/installation/) and run:
 
 ```fish
-uvx paskia serve --rp-id example.com
+uvx paskia --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.
+On the first run it downloads the software and prints a registration link for the Admin. The server starts on [localhost:4401](http://localhost:4401), serving authentication for `*.example.com`. For local testing, leave out `--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 production you 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`:
 
@@ -73,19 +75,20 @@ uv tool install paskia
 
 ## Configuration
 
-There is no config file. Pass only the options on CLI:
+There is no config file. All settings are passed as CLI options:
 
 ```text
-paskia serve [options]
+paskia [options]
+paskia reset [user]     # Generate passkey reset link
 ```
 
 | 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.|
+| -l, --listen *endpoint* | Listen address: *host*:*port*, :*port* (all interfaces), or */path.sock* | **localhost:4401** |
+| --rp-id *domain* | Main/top domain for passkeys | **localhost** |
+| --rp-name *"text"* | Name shown during passkey registration | Same as rp-id |
+| --origin *url* | Restrict allowed origins for WebSocket auth (repeatable) | All under rp-id |
+| --auth-host *url* | Dedicated authentication site, e.g. **auth.example.com** | Use **/auth/** path on each site |
 
 ## Further Documentation
 

{paskia-0.9.1 → paskia-0.10.2}/README.md

@@ -1,5 +1,7 @@
 # Paskia
 
+![Screenshot](https://git.zi.fi/leovasanko/paskia/raw/main/docs/screenshots/forbidden-light.webp)
+
 An easy to install passkey-based authentication service that protects any web application with strong passwordless login.
 
 ## What is Paskia?
@@ -27,12 +29,12 @@ Single Sign-On (SSO): Users register once and authenticate across all applicatio
 Install [UV](https://docs.astral.sh/uv/getting-started/installation/) and run:
 
 ```fish
-uvx paskia serve --rp-id example.com
+uvx paskia --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.
+On the first run it downloads the software and prints a registration link for the Admin. The server starts on [localhost:4401](http://localhost:4401), serving authentication for `*.example.com`. For local testing, leave out `--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 production you 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`:
 
@@ -42,19 +44,20 @@ uv tool install paskia
 
 ## Configuration
 
-There is no config file. Pass only the options on CLI:
+There is no config file. All settings are passed as CLI options:
 
 ```text
-paskia serve [options]
+paskia [options]
+paskia reset [user]     # Generate passkey reset link
 ```
 
 | 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.|
+| -l, --listen *endpoint* | Listen address: *host*:*port*, :*port* (all interfaces), or */path.sock* | **localhost:4401** |
+| --rp-id *domain* | Main/top domain for passkeys | **localhost** |
+| --rp-name *"text"* | Name shown during passkey registration | Same as rp-id |
+| --origin *url* | Restrict allowed origins for WebSocket auth (repeatable) | All under rp-id |
+| --auth-host *url* | Dedicated authentication site, e.g. **auth.example.com** | Use **/auth/** path on each site |
 
 ## Further Documentation
 

{paskia-0.9.1 → paskia-0.10.2}/paskia/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.9.1'
-__version_tuple__ = version_tuple = (0, 9, 1)
+__version__ = version = '0.10.2'
+__version_tuple__ = version_tuple = (0, 10, 2)
 
 __commit_id__ = commit_id = None

{paskia-0.9.1 → paskia-0.10.2}/paskia/bootstrap.py

@@ -15,18 +15,18 @@ from paskia.util import hostutil, passphrase
 logger = logging.getLogger(__name__)
 
 # Shared log message template for admin reset links
-ADMIN_RESET_MESSAGE = """\
-%s
-
+ADMIN_RESET_MESSAGE = """
 👤 Admin  %s
    - Use this link to register a Passkey for the admin user!
 """
 
 
-def _log_reset_link(message: str, passphrase: str) -> str:
+def _log_reset_link(passphrase: str, message: str | None = None) -> str:
     """Log a reset link message and return the URL."""
     reset_link = hostutil.reset_link_url(passphrase)
-    logger.info(ADMIN_RESET_MESSAGE, message, reset_link)
+    if message:
+        logger.info(message)
+    logger.info(ADMIN_RESET_MESSAGE, reset_link)
     return reset_link
 
 
@@ -41,7 +41,7 @@ async def bootstrap_system() -> None:
     reset_passphrase = db.bootstrap()
 
     # Log the reset link (this is separate from the transaction log)
-    _log_reset_link("✅ Bootstrap completed!", reset_passphrase)
+    _log_reset_link(reset_passphrase, "✅ Bootstrap completed!")
 
 
 async def check_admin_credentials() -> bool:
@@ -72,6 +72,7 @@ async def check_admin_credentials() -> bool:
 
         if not db.get_user_credential_ids(admin_user.uuid):
             # Admin exists but has no credentials, create reset link
+            logger.info("⚠️  Admin user has no credentials!")
 
             token = passphrase.generate()
             expiry = authsession.reset_expires()
@@ -81,7 +82,7 @@ async def check_admin_credentials() -> bool:
                 expiry=expiry,
                 token_type="admin registration",
             )
-            _log_reset_link("⚠️  Admin user has no credentials!", token)
+            _log_reset_link(token)
             return True
 
         return False

{paskia-0.9.1 → paskia-0.10.2}/paskia/db/__init__.py

@@ -64,6 +64,7 @@ from paskia.db.operations import (
     update_user_display_name,
     update_user_role,
     update_user_role_in_organization,
+    update_user_theme,
 )
 from paskia.db.structs import (
     DB,
@@ -147,4 +148,5 @@ __all__ = [
     "update_user_display_name",
     "update_user_role",
     "update_user_role_in_organization",
+    "update_user_theme",
 ]

{paskia-0.9.1 → paskia-0.10.2}/paskia/db/background.py

@@ -74,21 +74,18 @@ async def start_background():
                     _logger.debug("Background task in different event loop, restarting")
                     _background_task = None
                 else:
-                    # Task is running in the same event loop - this is an error
-                    raise RuntimeError(
-                        "Background task is already running. "
-                        "start_background() must not be called multiple times in the same event loop."
+                    # Task is already running in same loop - idempotent, just return
+                    # This happens with dual IPv4+IPv6 endpoints sharing the same process
+                    _logger.debug(
+                        "Background task already running in same loop, skipping"
                     )
-            except RuntimeError:
-                raise  # Re-raise RuntimeError from above
+                    return
             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():

{paskia-0.9.1 → paskia-0.10.2}/paskia/db/jsonl.py

@@ -198,7 +198,6 @@ class JsonlStore:
         if not diff:
             return
         self._pending_changes.append(create_change_record(action, version, diff, user))
-        self._previous_builtins = copy.deepcopy(current)
 
         # Log the change with user display name if available
         user_display = None
@@ -210,7 +209,8 @@ class JsonlStore:
             except (ValueError, KeyError):
                 user_display = user
 
-        log_change(action, diff, user_display)
+        log_change(action, diff, user_display, self._previous_builtins)
+        self._previous_builtins = copy.deepcopy(current)
 
     @contextmanager
     def transaction(

{paskia-0.9.1 → paskia-0.10.2}/paskia/db/logging.py

@@ -26,8 +26,7 @@ _RESET = "\033[0m"
 _DIM = "\033[2m"
 _PATH_PREFIX = "\033[1;30m"  # Dark grey for path prefix (like host in access log)
 _PATH_FINAL = "\033[0m"  # Default for final element (like path in access log)
-_REPLACE = "\033[0;33m"  # Yellow for replacements
-_DELETE = "\033[0;31m"  # Red for deletions
+_DELETE = "\033[1;31m"  # Red for deletions
 _ADD = "\033[0;32m"  # Green for additions
 _ACTION = "\033[1;34m"  # Bold blue for action name
 _USER = "\033[0;34m"  # Blue for user display
@@ -93,18 +92,34 @@ def _format_path(path: list[str], use_color: bool) -> str:
     return f"{_PATH_PREFIX}{prefix}.{_RESET}{_PATH_FINAL}{final}{_RESET}"
 
 
+def _get_nested(data: dict | None, path: list[str]) -> Any:
+    """Get a nested value from a dict by path, or None if not found."""
+    if data is None:
+        return None
+    current = data
+    for key in path:
+        if not isinstance(current, dict) or key not in current:
+            return None
+        current = current[key]
+    return current
+
+
 def _collect_changes(
-    diff: dict, path: list[str], changes: list[tuple[str, list[str], Any, Any | None]]
+    diff: dict,
+    path: list[str],
+    changes: list[tuple[str, list[str], Any]],
+    previous: dict | None,
 ) -> None:
     """
     Recursively collect changes from a diff into a flat list.
 
-    Each change is a tuple of (change_type, path, new_value, old_value).
-    change_type is one of: 'set', 'replace', 'delete'
+    Each change is a tuple of (change_type, path, new_value).
+    change_type is one of: 'add', 'update', 'delete'
     """
     if not isinstance(diff, dict):
-        # Leaf value - this is a set operation
-        changes.append(("set", path, diff, None))
+        # Leaf value - check if it existed before
+        existed = _get_nested(previous, path) is not None
+        changes.append(("update" if existed else "add", path, diff))
         return
 
     for key, value in diff.items():
@@ -112,72 +127,136 @@ def _collect_changes(
             # $delete contains a list of keys to delete
             if isinstance(value, list):
                 for deleted_key in value:
-                    changes.append(("delete", path + [str(deleted_key)], None, None))
+                    changes.append(("delete", path + [str(deleted_key)], None))
             else:
-                changes.append(("delete", path + [str(value)], None, None))
+                changes.append(("delete", path + [str(value)], None))
 
         elif key == "$replace":
-            # $replace contains the new value for this path
+            # $replace replaces the entire collection at this path
+            # We need to track what was added and what was deleted
+            old_collection = _get_nested(previous, path)
+            old_keys = (
+                set(old_collection.keys())
+                if isinstance(old_collection, dict)
+                else set()
+            )
+            new_keys = set(value.keys()) if isinstance(value, dict) else set()
+
+            # Items that existed before but not in new = deleted
+            for deleted_key in old_keys - new_keys:
+                changes.append(("delete", path + [str(deleted_key)], None))
+
+            # Items in new collection
             if isinstance(value, dict):
-                # Replacing with a dict - show each key as a replacement
                 for rkey, rval in value.items():
-                    changes.append(("replace", path + [str(rkey)], rval, None))
-                if not value:
-                    # Empty replacement - clearing the collection
-                    changes.append(("replace", path, {}, None))
-            else:
-                changes.append(("replace", path, value, None))
+                    existed = rkey in old_keys
+                    changes.append(
+                        ("update" if existed else "add", path + [str(rkey)], rval)
+                    )
+            elif value or not old_keys:
+                # Non-dict replacement or empty replacement with nothing before
+                changes.append(
+                    ("update" if old_collection is not None else "add", path, value)
+                )
 
         elif key.startswith("$"):
             # Other special operations (future-proofing)
-            changes.append(("set", path, {key: value}, None))
+            changes.append(("add", path, {key: value}))
 
         else:
-            # Regular nested key
-            _collect_changes(value, path + [str(key)], changes)
+            # Regular nested key - check if this item existed before
+            new_path = path + [str(key)]
+            existed = _get_nested(previous, new_path) is not None
+            if existed:
+                # Item exists - recurse to show specific field changes
+                _collect_changes(value, new_path, changes, previous)
+            else:
+                # New item - record as add with full value, don't recurse
+                changes.append(("add", new_path, value))
 
 
-def _format_change_line(
+def _format_change_lines(
     change_type: str, path: list[str], value: Any, use_color: bool
-) -> str:
-    """Format a single change as a one-line string."""
-    path_str = _format_path(path, use_color)
-    value_str = _format_value(value, use_color)
-
+) -> list[str]:
+    """Format a single change as one or more lines."""
     if change_type == "delete":
-        if use_color:
-            return f"  ❌  {path_str}"
-        return f"  - {path_str}"
-
-    if change_type == "replace":
-        if use_color:
-            return f"  {_REPLACE}⟳{_RESET} {path_str} {_DIM}={_RESET} {value_str}"
-        return f"  ~ {path_str} = {value_str}"
-
-    # Default: set/add
+        if not use_color:
+            return [f"  {'.'.join(path)} ✗"]
+        if len(path) == 1:
+            return [f"  {_DELETE}{path[0]} ✗{_RESET}"]
+        prefix = ".".join(path[:-1])
+        final = path[-1]
+        return [f"  {_PATH_PREFIX}{prefix}.{_RESET}{_DELETE}{final} ✗{_RESET}"]
+
+    if change_type == "add":
+        # New item being created - only final element in green
+        # For dict values, show children on separate indented lines
+        if isinstance(value, dict) and value:
+            lines = []
+            # First line: path with green final element and grey =
+            if not use_color:
+                lines.append(f"  {'.'.join(path)} =")
+            elif len(path) == 1:
+                lines.append(f"  {_ADD}{path[0]}{_RESET} {_DIM}={_RESET}")
+            else:
+                prefix = ".".join(path[:-1])
+                final = path[-1]
+                lines.append(
+                    f"  {_PATH_PREFIX}{prefix}.{_RESET}{_ADD}{final}{_RESET} {_DIM}={_RESET}"
+                )
+            # Child lines: indented key: value, with aligned values
+            max_key_len = max(len(k) for k in value.keys())
+            field_width = max(max_key_len, 12)  # minimum 12 chars
+            for k, v in value.items():
+                v_str = _format_value(v, use_color)
+                padding = " " * (field_width - len(k))
+                if use_color:
+                    lines.append(f"    {k}{_DIM}:{_RESET}{padding} {v_str}")
+                else:
+                    lines.append(f"    {k}:{padding} {v_str}")
+            return lines
+        else:
+            value_str = _format_value(value, use_color)
+            if not use_color:
+                return [f"  {'.'.join(path)} = {value_str}"]
+            if len(path) == 1:
+                return [f"  {_ADD}{path[0]}{_RESET} {_DIM}={_RESET} {value_str}"]
+            prefix = ".".join(path[:-1])
+            final = path[-1]
+            return [
+                f"  {_PATH_PREFIX}{prefix}.{_RESET}{_ADD}{final}{_RESET} {_DIM}={_RESET} {value_str}"
+            ]
+
+    # update: Existing item being updated - normal path colors
+    value_str = _format_value(value, use_color)
+    path_str = _format_path(path, use_color)
     if use_color:
-        return f"  {_ADD}+{_RESET} {path_str} {_DIM}={_RESET} {value_str}"
-    return f"  + {path_str} = {value_str}"
+        return [f"  {path_str} {_DIM}={_RESET} {value_str}"]
+    return [f"  {path_str} = {value_str}"]
 
 
-def format_diff(diff: dict) -> list[str]:
+def format_diff(diff: dict, previous: dict | None = None) -> list[str]:
     """
     Format a JSON diff as human-readable lines.
 
+    Args:
+        diff: The JSON diff dict
+        previous: The previous state dict (for determining add vs update)
+
     Returns a list of formatted lines (without newlines).
     Single changes return one line, multiple changes return multiple lines.
     """
     use_color = _use_color()
-    changes: list[tuple[str, list[str], Any, Any | None]] = []
-    _collect_changes(diff, [], changes)
+    changes: list[tuple[str, list[str], Any]] = []
+    _collect_changes(diff, [], changes, previous)
 
     if not changes:
         return []
 
     # Format each change
     lines = []
-    for change_type, path, value, _ in changes:
-        lines.append(_format_change_line(change_type, path, value, use_color))
+    for change_type, path, value in changes:
+        lines.extend(_format_change_lines(change_type, path, value, use_color))
 
     return lines
 
@@ -198,7 +277,12 @@ def format_action_header(action: str, user_display: str | None = None) -> str:
         return action
 
 
-def log_change(action: str, diff: dict, user_display: str | None = None) -> None:
+def log_change(
+    action: str,
+    diff: dict,
+    user_display: str | None = None,
+    previous: dict | None = None,
+) -> None:
     """
     Log a database change with pretty-printed diff.
 
@@ -206,9 +290,10 @@ def log_change(action: str, diff: dict, user_display: str | None = None) -> None
         action: The action name (e.g., "login", "admin:delete_user")
         diff: The JSON diff dict
         user_display: Optional display name of the user who performed the action
+        previous: The previous state dict (for determining add vs update)
     """
     header = format_action_header(action, user_display)
-    diff_lines = format_diff(diff)
+    diff_lines = format_diff(diff, previous)
 
     if not diff_lines:
         logger.info(header)

{paskia-0.9.1 → paskia-0.10.2}/paskia/db/operations.py

@@ -352,6 +352,23 @@ def update_user_display_name(
         _db.users[uuid].display_name = display_name
 
 
+def update_user_theme(
+    uuid: UUID,
+    theme: str,
+    *,
+    ctx: SessionContext | None = None,
+) -> None:
+    """Update user theme preference ('' for auto, 'light', 'dark')."""
+    if isinstance(uuid, str):
+        uuid = UUID(uuid)
+    if uuid not in _db.users:
+        raise ValueError(f"User {uuid} not found")
+    if theme not in ("", "light", "dark"):
+        raise ValueError(f"Invalid theme: {theme}")
+    with _db.transaction("update_user_theme", ctx):
+        _db.users[uuid].theme = theme
+
+
 def update_user_role(
     uuid: UUID,
     role_uuid: UUID,
@@ -517,16 +534,18 @@ def set_session_host(key: str, host: str, *, ctx: SessionContext | None = None)
     update_session(key, host=host, ctx=ctx)
 
 
-def delete_session(key: str, *, ctx: SessionContext | None = None) -> None:
+def delete_session(
+    key: str, *, ctx: SessionContext | None = None, action: str = "delete_session"
+) -> None:
     """Delete a session.
 
     The acting user should be logged via ctx.
-    For user logout, pass ctx of the user's session.
+    For user logout, pass ctx of the user's session and action="logout".
     For admin terminating a session, pass admin's ctx.
     """
     if key not in _db.sessions:
         raise ValueError("Session not found")
-    with _db.transaction("delete_session", ctx):
+    with _db.transaction(action, ctx):
         del _db.sessions[key]
 
 
@@ -554,6 +573,7 @@ def create_reset_token(
     token_type: str,
     *,
     ctx: SessionContext | None = None,
+    user: str | None = None,
 ) -> None:
     """Create a reset token from a passphrase.
 
@@ -561,13 +581,14 @@ def create_reset_token(
     For self-service (user creating own recovery link), pass user's ctx.
     For admin operations, pass admin's ctx.
     For system operations (bootstrap), pass neither to log no user.
+    For API operations where ctx is not available but user is known, pass user.
     """
     key = _reset_key(passphrase)
     if key in _db.reset_tokens:
         raise ValueError("Reset token already exists")
     if user_uuid not in _db.users:
         raise ValueError(f"User {user_uuid} not found")
-    with _db.transaction("create_reset_token", ctx):
+    with _db.transaction("create_reset_token", ctx, user=user):
         _db.reset_tokens[key] = ResetToken(
             user_uuid=user_uuid, expiry=expiry, token_type=token_type
         )

{paskia-0.9.1 → paskia-0.10.2}/paskia/db/structs.py

@@ -147,10 +147,10 @@ class Role(msgspec.Struct, dict=True, omit_defaults=True):
         return role
 
 
-class User(msgspec.Struct, dict=True):
+class User(msgspec.Struct, dict=True, omit_defaults=True):
     """User data structure.
 
-    Mutable fields: display_name, role_uuid, last_seen, visits
+    Mutable fields: display_name, role_uuid, last_seen, visits, theme
     Immutable fields: created_at (set at creation, never modified)
     uuid is derived from created_at using uuid7.
     """
@@ -160,6 +160,7 @@ class User(msgspec.Struct, dict=True):
     created_at: datetime
     last_seen: datetime | None = None
     visits: int = 0
+    theme: str = ""  # "" or "auto" = OS default, "light", "dark"
 
     def __post_init__(self):
         if not hasattr(self, "uuid"):