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

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/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/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/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/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/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/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/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"):

paskia/fastapi/__main__.py

@@ -7,12 +7,12 @@ from urllib.parse import urlparse
 
 from fastapi_vue.hostutil import parse_endpoint
 from uvicorn import Config, Server
+from uvicorn import run as uvicorn_run
 
 from paskia import globals as _globals
 from paskia.bootstrap import bootstrap_if_needed
 from paskia.config import PaskiaConfig
 from paskia.db.background import flush
-from paskia.fastapi import app as fastapi_app
 from paskia.fastapi import reset as reset_cmd
 from paskia.util import startupbox
 from paskia.util.hostutil import normalize_origin
@@ -21,10 +21,10 @@ DEFAULT_PORT = 4401
 
 EPILOG = """\
 Examples:
-  paskia                      # localhost:4401
-  paskia :8080                # All interfaces, port 8080
-  paskia unix:/tmp/paskia.sock
-  paskia reset [user]         # Generate passkey reset link
+  paskia                           # localhost:4401
+  paskia -l :8080                  # All interfaces, port 8080
+  paskia -l /tmp/paskia.sock       # Unix socket
+  paskia reset [user]              # Generate passkey reset link
 """
 
 
@@ -81,32 +81,40 @@ def main():
         epilog=EPILOG,
     )
 
-    # Primary argument: either host:port or "reset" subcommand
+    # Subcommand for reset
     parser.add_argument(
-        "hostport",
+        "command",
         nargs="?",
-        help=(
-            "Endpoint (default: localhost:4401). Forms: host[:port] | :port | "
-            "[ipv6][:port] | ipv6 | unix:/path.sock | 'reset' for credential reset"
-        ),
+        help="Command: 'reset' for credential reset, or omit to run server",
     )
     parser.add_argument(
         "reset_query",
         nargs="?",
         help="For 'reset' command: user UUID or substring of display name",
     )
+    parser.add_argument(
+        "-l",
+        "--listen",
+        metavar="LISTEN",
+        help=(
+            "Endpoint to listen on (default: localhost:4401). "
+            "Forms: host:port  port  :port  [ipv6]:port  unix:path  /path.sock"
+        ),
+    )
     add_common_options(parser)
 
     args = parser.parse_args()
 
-    # Detect "reset" subcommand (first positional is "reset")
-    is_reset = args.hostport == "reset"
+    # Detect "reset" subcommand
+    is_reset = args.command == "reset"
 
     if is_reset:
         endpoints = []
     else:
+        if args.command is not None:
+            raise SystemExit(f"Unknown command: {args.command}")
         # Parse endpoint using fastapi_vue.hostutil
-        endpoints = parse_endpoint(args.hostport, DEFAULT_PORT)
+        endpoints = parse_endpoint(args.listen, DEFAULT_PORT)
 
     # Extract host/port/uds from first endpoint for config display and site_url
     ep = endpoints[0] if endpoints else {}
@@ -188,7 +196,7 @@ def main():
     devmode = bool(os.environ.get("FASTAPI_VUE_FRONTEND_URL"))
 
     run_kwargs: dict = {
-        "log_level": "info",
+        "log_level": "warning",  # Suppress startup messages; we use custom logging
         "access_log": False,  # We use custom AccessLogMiddleware instead
     }
 
@@ -199,8 +207,6 @@ def main():
             raise SystemExit(f"Dev mode requires localhost:4402, got {host}:{port}")
         run_kwargs["reload"] = True
         run_kwargs["reload_dirs"] = ["paskia"]
-        # Suppress uvicorn startup messages in dev mode
-        run_kwargs["log_level"] = "warning"
 
     async def async_main():
         await _globals.init(
@@ -220,10 +226,18 @@ def main():
             async with asyncio.TaskGroup() as tg:
                 for ep in endpoints:
                     tg.create_task(
-                        Server(Config(app=fastapi_app, **run_kwargs, **ep)).serve()
+                        Server(
+                            Config(app="paskia.fastapi:app", **run_kwargs, **ep)
+                        ).serve()
                     )
+        elif devmode:
+            # Use uvicorn.run for proper reload support (it handles subprocess spawning)
+            ep = endpoints[0]
+            uvicorn_run("paskia.fastapi:app", **run_kwargs, **ep)
         else:
-            server = Server(Config(app=fastapi_app, **run_kwargs, **endpoints[0]))
+            server = Server(
+                Config(app="paskia.fastapi:app", **run_kwargs, **endpoints[0])
+            )
             await server.serve()
 
     try:

paskia/fastapi/admin.py

@@ -127,7 +127,7 @@ async def admin_create_org(
     db.create_org(org, ctx=ctx)
     # Grant requested permissions to the new org
     for perm in permissions:
-        db.add_permission_to_org(str(org.uuid), perm)
+        db.add_permission_to_org(str(org.uuid), perm, ctx=ctx)
 
     return {"uuid": str(org.uuid)}
 
@@ -706,7 +706,7 @@ async def admin_delete_user_session(
     if not target_session or target_session.user_uuid != user_uuid:
         raise HTTPException(status_code=404, detail="Session not found")
 
-    db.delete_session(session_id, ctx=ctx)
+    db.delete_session(session_id, ctx=ctx, action="admin:delete_session")
 
     # Check if admin terminated their own session
     current_terminated = session_id == auth

paskia/fastapi/api.py

@@ -78,7 +78,7 @@ async def validate_token(
     try:
         ctx = await authz.verify(
             auth,
-            perm,
+            " ".join(perm).split(),
             host=request.headers.get("host"),
             max_age=max_age,
         )
@@ -94,6 +94,7 @@ async def validate_token(
                 ip=request.client.host if request.client else "",
                 user_agent=request.headers.get("user-agent") or "",
                 expiry=expires(),
+                ctx=ctx,
             )
             session.set_session_cookie(response, auth)
             renewed = True
@@ -130,7 +131,10 @@ async def forward_authentication(
     """
     try:
         ctx = await authz.verify(
-            auth, perm, host=request.headers.get("host"), max_age=max_age
+            auth,
+            " ".join(perm).split(),
+            host=request.headers.get("host"),
+            max_age=max_age,
         )
         # Build permission scopes for Remote-Groups header
         role_permissions = (
@@ -248,7 +252,7 @@ async def api_logout(request: Request, response: Response, auth=AUTH_COOKIE):
     if not ctx:
         return {"message": "Already logged out"}
     with suppress(Exception):
-        db.delete_session(auth, ctx=ctx)
+        db.delete_session(auth, ctx=ctx, action="logout")
     session.clear_session_cookie(response)
     return {"message": "Logged out successfully"}