pixlstash 1.6.0.dev1__tar.gz → 1.6.0.dev2__tar.gz

{pixlstash-1.6.0.dev1/pixlstash.egg-info → pixlstash-1.6.0.dev2}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: pixlstash
-Version: 1.6.0.dev1
+Version: 1.6.0.dev2
 Summary: Self-hosted picture library with AI tagging, semantic search, and a clean web UI
-Author: Gaute Lindkvist
+Author-email: Gaute Lindkvist <lindkvis@gmail.com>
 License-Expression: GPL-3.0-only AND MIT
 Project-URL: Homepage, https://pikselkroken.github.io/pixlstash
 Project-URL: Repository, https://github.com/pikselkroken/pixlstash
@@ -110,6 +110,13 @@ PixlStash runs on your machine and serves the UI at a local (or Internet-facing)
   </a>
 </p>
 
+PixlStash is available as a **native desktop app for Windows, macOS, and Linux**
+(no Python or browser tab required), as a Windows installer, a Docker image, or a
+pip package. The desktop app ships a ready-to-run CPU runtime (Metal on Apple
+Silicon), so it works offline out of the box, and auto-detects your hardware to
+offer optional GPU acceleration (NVIDIA CUDA / AMD ROCm), which it installs on
+demand straight from PyPI / PyTorch.
+
 Detailed installation instructions on <a href="http://pixlstash.dev/install.html">pixlstash.dev</a>.
 
 
@@ -121,6 +128,11 @@ On first run, PixlStash creates a user config directory and stores:
 - Database
 - Imported media files
 
+The **desktop app** uses this same platform user data directory, so a desktop
+install shares its library with a pip or Docker install on the same machine. If
+you add GPU acceleration, the desktop app stores the downloaded GPU wheels under
+the app's own user-data directory.
+
 > **Model downloads:** On first startup, PixlStash automatically downloads the AI models required for tagging, captioning, and quality scoring. This includes several hundred MB of model weights. Downloads are stored in the platform user data directory:
 >
 > | OS | Path |
@@ -317,10 +329,36 @@ Import Folders UI/API, not in `server-config.json`.
 
 ### Processing
 
-| Key                              | Default | Description                                          |
-| -------------------------------- | ------- | ---------------------------------------------------- |
-| `default_device`                 | `"cpu"` | Device used for AI processing (`"cpu"` or `"cuda"`). |
-| `generate_thumbnails_on_startup` | `true`  | Generate missing thumbnails when the server starts.  |
+| Key                              | Default        | Description                                                                                                  |
+| -------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------- |
+| `default_device`                 | `"cpu"`        | Device used for AI processing (`"cpu"` or `"cuda"`).                                                        |
+| `insightface_model_pack`         | `"buffalo_l"`  | InsightFace model pack used by the face detection / recognition pipeline. One of `"buffalo_l"` or `"auraface"`. |
+| `generate_thumbnails_on_startup` | `true`         | Generate missing thumbnails when the server starts.                                                         |
+
+#### Face model pack and licensing
+
+`insightface_model_pack` selects which InsightFace model pack powers face
+detection and face recognition. The licensing decision is yours;
+PixlStash simply makes the choice available.
+
+- **`buffalo_l`** (default): the standard InsightFace pack. Its recognition
+  weights are trained on the WebFace600K dataset, which is licensed for
+  **non-commercial research use only**. This is the right choice for personal
+  and research use, and it downloads automatically on first use.
+- **`auraface`**: the [`fal/AuraFace-v1`](https://huggingface.co/fal/AuraFace-v1)
+  pack, whose weights are **Apache-2.0 licensed** and therefore suitable if you
+  need to use face features in a **commercial** setting. It uses the same
+  SCRFD-10G face detector as `buffalo_l`, so switching only changes the
+  recognition embedding. When selected, PixlStash downloads the pack from a
+  pinned HuggingFace revision into `~/.insightface/models/auraface/` on first
+  use. If the automatic download fails (for example, no network access), you can
+  place the pack's `.onnx` files in that directory manually and restart.
+
+Changing this setting on an existing library does **not** delete your faces or
+your manual character assignments. PixlStash detects faces whose embeddings came
+from a different pack and refreshes those embeddings in place, in the background,
+keeping each face's identity intact. New imports are always processed first, so a
+refresh sweep never starves brand-new pictures.
 
 To remove stale database records for missing source files at startup, run:
 
@@ -345,6 +383,7 @@ python -m pixlstash.app --cleanup-missing-pictures
   "require_ssl": false,
   "image_root": "/home/user/.config/pixlstash/images",
   "default_device": "cpu",
+  "insightface_model_pack": "buffalo_l",
   "generate_thumbnails_on_startup": true
 }
 ```

{pixlstash-1.6.0.dev1 → pixlstash-1.6.0.dev2}/README.md

@@ -36,6 +36,13 @@ PixlStash runs on your machine and serves the UI at a local (or Internet-facing)
   </a>
 </p>
 
+PixlStash is available as a **native desktop app for Windows, macOS, and Linux**
+(no Python or browser tab required), as a Windows installer, a Docker image, or a
+pip package. The desktop app ships a ready-to-run CPU runtime (Metal on Apple
+Silicon), so it works offline out of the box, and auto-detects your hardware to
+offer optional GPU acceleration (NVIDIA CUDA / AMD ROCm), which it installs on
+demand straight from PyPI / PyTorch.
+
 Detailed installation instructions on <a href="http://pixlstash.dev/install.html">pixlstash.dev</a>.
 
 
@@ -47,6 +54,11 @@ On first run, PixlStash creates a user config directory and stores:
 - Database
 - Imported media files
 
+The **desktop app** uses this same platform user data directory, so a desktop
+install shares its library with a pip or Docker install on the same machine. If
+you add GPU acceleration, the desktop app stores the downloaded GPU wheels under
+the app's own user-data directory.
+
 > **Model downloads:** On first startup, PixlStash automatically downloads the AI models required for tagging, captioning, and quality scoring. This includes several hundred MB of model weights. Downloads are stored in the platform user data directory:
 >
 > | OS | Path |
@@ -243,10 +255,36 @@ Import Folders UI/API, not in `server-config.json`.
 
 ### Processing
 
-| Key                              | Default | Description                                          |
-| -------------------------------- | ------- | ---------------------------------------------------- |
-| `default_device`                 | `"cpu"` | Device used for AI processing (`"cpu"` or `"cuda"`). |
-| `generate_thumbnails_on_startup` | `true`  | Generate missing thumbnails when the server starts.  |
+| Key                              | Default        | Description                                                                                                  |
+| -------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------- |
+| `default_device`                 | `"cpu"`        | Device used for AI processing (`"cpu"` or `"cuda"`).                                                        |
+| `insightface_model_pack`         | `"buffalo_l"`  | InsightFace model pack used by the face detection / recognition pipeline. One of `"buffalo_l"` or `"auraface"`. |
+| `generate_thumbnails_on_startup` | `true`         | Generate missing thumbnails when the server starts.                                                         |
+
+#### Face model pack and licensing
+
+`insightface_model_pack` selects which InsightFace model pack powers face
+detection and face recognition. The licensing decision is yours;
+PixlStash simply makes the choice available.
+
+- **`buffalo_l`** (default): the standard InsightFace pack. Its recognition
+  weights are trained on the WebFace600K dataset, which is licensed for
+  **non-commercial research use only**. This is the right choice for personal
+  and research use, and it downloads automatically on first use.
+- **`auraface`**: the [`fal/AuraFace-v1`](https://huggingface.co/fal/AuraFace-v1)
+  pack, whose weights are **Apache-2.0 licensed** and therefore suitable if you
+  need to use face features in a **commercial** setting. It uses the same
+  SCRFD-10G face detector as `buffalo_l`, so switching only changes the
+  recognition embedding. When selected, PixlStash downloads the pack from a
+  pinned HuggingFace revision into `~/.insightface/models/auraface/` on first
+  use. If the automatic download fails (for example, no network access), you can
+  place the pack's `.onnx` files in that directory manually and restart.
+
+Changing this setting on an existing library does **not** delete your faces or
+your manual character assignments. PixlStash detects faces whose embeddings came
+from a different pack and refreshes those embeddings in place, in the background,
+keeping each face's identity intact. New imports are always processed first, so a
+refresh sweep never starves brand-new pictures.
 
 To remove stale database records for missing source files at startup, run:
 
@@ -271,6 +309,7 @@ python -m pixlstash.app --cleanup-missing-pictures
   "require_ssl": false,
   "image_root": "/home/user/.config/pixlstash/images",
   "default_device": "cpu",
+  "insightface_model_pack": "buffalo_l",
   "generate_thumbnails_on_startup": true
 }
 ```

{pixlstash-1.6.0.dev1 → pixlstash-1.6.0.dev2}/frontend/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pixlstash-frontend",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pixlstash-frontend",
-      "version": "1.5.0",
+      "version": "1.6.0",
       "dependencies": {
         "@mdi/font": "^7.4.47",
         "axios": "^1.16.0",

{pixlstash-1.6.0.dev1 → pixlstash-1.6.0.dev2}/frontend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pixlstash-frontend",
   "private": true,
-  "version": "1.5.0",
+  "version": "1.6.0",
   "type": "module",
   "scripts": {
     "dev": "vite",

{pixlstash-1.6.0.dev1 → pixlstash-1.6.0.dev2}/pixlstash/auth.py

@@ -1,5 +1,6 @@
 import hashlib
 import ipaddress
+import os
 import re
 import secrets
 import threading
@@ -195,6 +196,12 @@ class AuthService:
         self._server_config_path = server_config_path
         self._logger = logger
         self.active_session_ids: dict[str, int] = {}
+        # The pre-authenticated Electron desktop owner session, if seeded (see
+        # seed_desktop_session). It grants full owner access and is therefore
+        # pinned to local connections only: the desktop window reaches the
+        # backend over loopback, so this session must never authenticate a
+        # request arriving on the optional external listener.
+        self._desktop_session_token: Optional[str] = None
         self.user: Optional[User] = None
         self.password_hash: Optional[str] = None
         self.username: Optional[str] = None
@@ -269,12 +276,22 @@ class AuthService:
             return sum(1 for ts in self._guest_sessions.values() if ts >= active_cutoff)
 
     def ensure_secure_when_required(self, request: Request):
-        if self._server_config.get("require_ssl", False):
-            if request.url.scheme != "https":
-                raise HTTPException(
-                    status_code=403,
-                    detail="HTTPS is required for this operation.",
-                )
+        if not self._server_config.get("require_ssl", False):
+            return
+        if request.url.scheme == "https":
+            return
+        # require_ssl governs the *external* surface only. The Electron desktop
+        # window always reaches the backend over a plain-HTTP loopback connection
+        # by design (require_ssl drives the separate external listener, not this
+        # one), and a standalone HTTPS-only server never serves plaintext at all.
+        # So a local/loopback client must not be forced onto HTTPS — only a
+        # genuinely remote plaintext request is rejected.
+        if is_local_ip(self._get_real_client_ip(request)):
+            return
+        raise HTTPException(
+            status_code=403,
+            detail="HTTPS is required for this operation.",
+        )
 
     def _get_real_client_ip(self, request: Request) -> str:
         trusted = self._server_config.get("trusted_proxies", [])
@@ -340,6 +357,49 @@ class AuthService:
         self.username = user.username if user else None
         return user
 
+    # Env var the Electron desktop shell uses to hand the server a
+    # pre-authenticated owner session token (see seed_desktop_session).
+    DESKTOP_SESSION_ENV = "PIXLSTASH_DESKTOP_SESSION"
+
+    def seed_desktop_session(self) -> Optional[str]:
+        """Register a pre-authenticated owner session for the local desktop app.
+
+        When PixlStash runs inside the Electron desktop shell, the shell
+        generates a high-entropy token once per launch, passes it to the server
+        via the ``PIXLSTASH_DESKTOP_SESSION`` env var, and injects the same value
+        as the ``session_id`` cookie in its own ``BrowserWindow``.  Seeding the
+        token into :attr:`active_session_ids` here means the local window opens
+        straight into the library with no login/registration prompt.
+
+        This affects only the loopback owner: remote browsers and API clients
+        present a *different* cookie/token and continue to authenticate via the
+        normal password login (:meth:`login`) or share tokens.  Returns the
+        seeded token, or ``None`` when no (valid) token was supplied.
+        """
+        token = os.environ.get(self.DESKTOP_SESSION_ENV, "").strip()
+        if not token:
+            return None
+        # Guard against a weak/guessable token leaking owner access.  The shell
+        # always supplies a 32+ char random token; reject anything shorter.
+        if len(token) < 16:
+            self._logger.warning(
+                "Ignoring %s: token too short (expected >=16 chars).",
+                self.DESKTOP_SESSION_ENV,
+            )
+            return None
+        user = self.ensure_user()
+        if not user or user.id is None:
+            self._logger.error(
+                "Could not seed desktop session: failed to ensure an owner user."
+            )
+            return None
+        self.active_session_ids[token] = user.id
+        self._desktop_session_token = token
+        self._logger.info(
+            "Seeded a pre-authenticated desktop session for the local owner."
+        )
+        return token
+
     def set_password_hash(self, hashed_password: str):
         def update_user(session: Session):
             user = session.exec(select(User)).first()
@@ -1239,6 +1299,23 @@ class AuthService:
             session_id = request.cookies.get("session_id")
             user_id = self.active_session_ids.get(session_id) if session_id else None
 
+            # The seeded Electron desktop owner session is loopback-only: the
+            # window talks to the backend over 127.0.0.1, so this high-privilege
+            # session must never grant access on the optional external listener
+            # (even though the cookie is scoped to the loopback origin and so is
+            # not normally sent there — this is the fail-closed backstop). Drop
+            # it for non-local clients and let normal token auth take over.
+            if (
+                user_id is not None
+                and session_id == self._desktop_session_token
+                and not is_local_ip(self._get_real_client_ip(request))
+            ):
+                self._logger.warning(
+                    "Rejected desktop owner session from non-local IP %s.",
+                    self._get_real_client_ip(request),
+                )
+                user_id = None
+
             if user_id is not None:
                 # Cookie session — full owner access, no scope restriction
                 request.state.auth_user_id = user_id

{pixlstash-1.6.0.dev1 → pixlstash-1.6.0.dev2}/pixlstash/db_models/face.py

@@ -38,6 +38,12 @@ class Face(SQLModel, table=True):
     )
     bbox_: Optional[str] = Field(sa_column=Column("bbox", String, default=None))
     features: Optional[bytes] = None
+    # Name of the InsightFace model pack that produced this face's embedding
+    # (e.g. "buffalo_l" or "auraface"). Nullable for rows created before the
+    # column existed; backfilled to "buffalo_l" by the Alembic migration.
+    model_pack: Optional[str] = Field(
+        sa_column=Column("model_pack", String, default=None)
+    )
 
     # Relationships
     picture: Optional["Picture"] = Relationship(