keepassxc-browser-api 0.1.0__py3-none-any.whl

keepassxc_browser_api/__init__.py

@@ -0,0 +1,23 @@
+"""KeePassXC Browser API library.
+
+A Python library for communicating with KeePassXC via the browser extension
+protocol (NaCl-encrypted JSON over a Unix socket).
+"""
+
+from __future__ import annotations
+
+from .client import BrowserClient
+from .config import Association, BrowserConfig
+from .exceptions import AssociationError, KeePassXCError, NotAssociatedError
+from .models import Entry, Group
+
+__all__ = [
+    "BrowserClient",
+    "BrowserConfig",
+    "Association",
+    "Entry",
+    "Group",
+    "KeePassXCError",
+    "AssociationError",
+    "NotAssociatedError",
+]

keepassxc_browser_api/client.py

@@ -0,0 +1,735 @@
+"""KeePassXC browser extension protocol client.
+
+Implements the NaCl-encrypted protocol used by the KeePassXC browser extension
+to communicate with the KeePassXC application.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import os
+import socket
+import tempfile
+import time
+
+import nacl.exceptions
+import nacl.public
+import nacl.utils
+
+from .config import Association, BrowserConfig
+from .exceptions import AssociationError, NotAssociatedError, ProtocolError
+from .models import Entry, Group
+
+logger = logging.getLogger(__name__)
+
+CLIENT_ID = "keepassxc-browser-api"
+
+
+def _get_keepassxc_socket_path() -> str:
+    """Get the KeePassXC browser extension socket path (platform-aware)."""
+    # Linux: XDG_RUNTIME_DIR based path used by Flatpak / native installs
+    xdg_runtime = os.environ.get("XDG_RUNTIME_DIR", "")
+    if xdg_runtime:
+        flatpak_path = os.path.join(
+            xdg_runtime, "app", "org.keepassxc.KeePassXC",
+            "org.keepassxc.KeePassXC.BrowserServer",
+        )
+        if os.path.exists(flatpak_path):
+            return flatpak_path
+        native_path = os.path.join(xdg_runtime, "org.keepassxc.KeePassXC.BrowserServer")
+        if os.path.exists(native_path):
+            return native_path
+    # macOS / fallback
+    return os.path.join(tempfile.gettempdir(), "org.keepassxc.KeePassXC.BrowserServer")
+
+
+def _b64encode(data: bytes) -> str:
+    return base64.b64encode(data).decode("ascii")
+
+
+def _b64decode(data: str) -> bytes:
+    return base64.b64decode(data)
+
+
+def _increment_nonce(nonce: bytes) -> bytes:
+    """Increment a nonce by 1 (little-endian), matching sodium_increment().
+
+    Processes all bytes regardless of carry to avoid timing side-channels.
+    """
+    n = bytearray(nonce)
+    carry = 1
+    for i in range(len(n)):
+        val = n[i] + carry
+        n[i] = val & 0xFF
+        carry = val >> 8
+    return bytes(n)
+
+
+class BrowserClient:
+    """Client for the KeePassXC browser extension protocol.
+
+    Typical usage::
+
+        config = BrowserConfig.load()
+        client = BrowserClient(config)
+
+        # First-time setup (requires user approval in KeePassXC)
+        client.setup()
+        config.save()
+
+        # Ensure DB is unlocked (triggers TouchID/biometrics if locked)
+        client.ensure_unlocked()
+
+        # Use the API (auto-connects if needed)
+        entries = client.get_logins("https://example.com")
+
+        # Or use as a context manager
+        with BrowserClient(config) as client:
+            entries = client.get_logins("https://example.com")
+    """
+
+    def __init__(self, config: BrowserConfig):
+        self.config = config
+        self._socket: socket.socket | None = None
+        self._server_public_key: nacl.public.PublicKey | None = None
+
+        if config.client_public_key and config.client_secret_key:
+            sk_bytes = _b64decode(config.client_secret_key)
+            self._secret_key = nacl.public.PrivateKey(sk_bytes)
+            self._public_key = self._secret_key.public_key
+        else:
+            self._secret_key = nacl.public.PrivateKey.generate()
+            self._public_key = self._secret_key.public_key
+            config.client_public_key = _b64encode(bytes(self._public_key))
+            config.client_secret_key = _b64encode(bytes(self._secret_key))
+
+    def __enter__(self) -> BrowserClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.disconnect()
+
+    # ------------------------------------------------------------------
+    # Connection management
+    # ------------------------------------------------------------------
+
+    def connect(self) -> bool:
+        """Connect to KeePassXC browser extension socket.
+
+        Returns True on success, False if KeePassXC is not running.
+        """
+        path = _get_keepassxc_socket_path()
+        try:
+            self._socket = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+            self._socket.settimeout(5.0)
+            self._socket.connect(path)
+            logger.debug("Connected to KeePassXC at %s", path)
+            return True
+        except OSError as e:
+            logger.error("Cannot connect to KeePassXC browser socket at %s: %s", path, e)
+            self._socket = None
+            return False
+
+    def disconnect(self) -> None:
+        """Close the connection and clear session state."""
+        if self._socket:
+            try:
+                self._socket.close()
+            except OSError:
+                pass
+            self._socket = None
+            self._server_public_key = None
+
+    def _ensure_session(self) -> bool:
+        """Ensure there is an active connection with completed key exchange.
+
+        Automatically connects and exchanges public keys if needed.
+        Returns True if the session is ready, False on failure.
+        """
+        if self._socket and self._server_public_key:
+            return True
+        if not self._socket:
+            if not self.connect():
+                return False
+        if not self._server_public_key:
+            if not self.change_public_keys():
+                return False
+        return True
+
+    # ------------------------------------------------------------------
+    # Low-level messaging
+    # ------------------------------------------------------------------
+
+    def _send_json(self, msg: dict) -> dict | None:
+        """Send a JSON message and read the JSON response."""
+        if not self._socket:
+            return None
+
+        msg["clientID"] = CLIENT_ID
+
+        data = json.dumps(msg).encode("utf-8")
+        try:
+            self._socket.sendall(data)
+        except OSError as e:
+            logger.error("Failed to send message: %s", e)
+            return None
+
+        try:
+            self._socket.settimeout(self.config.unlock_timeout)
+            response_data = self._socket.recv(1024 * 1024)
+            if not response_data:
+                return None
+            return json.loads(response_data)
+        except (OSError, json.JSONDecodeError) as e:
+            logger.error("Failed to read response: %s", e)
+            return None
+
+    def _encrypt(self, message: dict, nonce: bytes) -> str:
+        """Encrypt a JSON message using NaCl crypto_box."""
+        if not self._server_public_key:
+            raise ProtocolError("No server public key (call change_public_keys first)")
+
+        box = nacl.public.Box(self._secret_key, self._server_public_key)
+        plaintext = json.dumps(message).encode("utf-8")
+        encrypted = box.encrypt(plaintext, nonce)
+        return _b64encode(encrypted.ciphertext)
+
+    def _decrypt(self, encrypted_b64: str, nonce: bytes) -> dict | None:
+        """Decrypt a NaCl-encrypted response."""
+        if not self._server_public_key:
+            return None
+
+        box = nacl.public.Box(self._secret_key, self._server_public_key)
+        try:
+            ciphertext = _b64decode(encrypted_b64)
+            plaintext = box.decrypt(ciphertext, nonce)
+            return json.loads(plaintext)
+        except (nacl.exceptions.CryptoError, json.JSONDecodeError, ValueError) as e:
+            logger.error("Failed to decrypt message: %s", e)
+            return None
+
+    def _send_encrypted(self, action: str, inner: dict, *, timeout: float | None = None) -> dict | None:
+        """Send an encrypted action message and return the decrypted response.
+
+        Automatically connects and performs key exchange if needed.
+        Returns the decrypted inner dict, or None on failure.
+        """
+        if not self._ensure_session():
+            return None
+        nonce = nacl.utils.random(nacl.public.Box.NONCE_SIZE)
+        encrypted = self._encrypt(inner, nonce)
+        msg = {
+            "action": action,
+            "message": encrypted,
+            "nonce": _b64encode(nonce),
+        }
+
+        if timeout is not None and self._socket:
+            old_timeout = self._socket.gettimeout()
+            self._socket.settimeout(timeout)
+
+        response = self._send_json(msg)
+
+        if timeout is not None and self._socket:
+            self._socket.settimeout(old_timeout)
+
+        if not response:
+            return None
+        if "errorCode" in response:
+            logger.debug("Error response for %s: %s (code %s)", action, response.get("error"), response.get("errorCode"))
+            return None
+
+        resp_nonce_b64 = response.get("nonce", "")
+        resp_message = response.get("message", "")
+        if not resp_nonce_b64 or not resp_message:
+            logger.error("Missing nonce or message in response for %s", action)
+            return None
+
+        resp_nonce = _b64decode(resp_nonce_b64)
+        return self._decrypt(resp_message, resp_nonce)
+
+    # ------------------------------------------------------------------
+    # Protocol: key exchange & association
+    # ------------------------------------------------------------------
+
+    def change_public_keys(self) -> bool:
+        """Perform NaCl key exchange with KeePassXC."""
+        nonce = nacl.utils.random(nacl.public.Box.NONCE_SIZE)
+        msg = {
+            "action": "change-public-keys",
+            "publicKey": _b64encode(bytes(self._public_key)),
+            "nonce": _b64encode(nonce),
+        }
+
+        response = self._send_json(msg)
+        if not response:
+            logger.error("No response to change-public-keys")
+            return False
+
+        if "errorCode" in response:
+            logger.error("Key exchange failed: %s", response.get("error"))
+            return False
+
+        server_pk_b64 = response.get("publicKey")
+        if not server_pk_b64:
+            logger.error("No server public key in response")
+            return False
+
+        self._server_public_key = nacl.public.PublicKey(_b64decode(server_pk_b64))
+        logger.debug("Key exchange successful")
+        return True
+
+    def associate(self) -> Association | None:
+        """Associate with KeePassXC (one-time, requires user approval in KeePassXC).
+
+        Returns the Association on success, or None on failure.
+        """
+        id_key = nacl.public.PrivateKey.generate()
+        id_public_key = id_key.public_key
+
+        nonce = nacl.utils.random(nacl.public.Box.NONCE_SIZE)
+        inner = {
+            "action": "associate",
+            "key": _b64encode(bytes(self._public_key)),
+            "idKey": _b64encode(bytes(id_public_key)),
+        }
+        encrypted = self._encrypt(inner, nonce)
+        msg = {
+            "action": "associate",
+            "message": encrypted,
+            "nonce": _b64encode(nonce),
+        }
+
+        old_timeout = self._socket.gettimeout() if self._socket else 30
+        if self._socket:
+            self._socket.settimeout(120)
+
+        response = self._send_json(msg)
+
+        if self._socket:
+            self._socket.settimeout(old_timeout)
+
+        if not response or "errorCode" in response:
+            err = response.get("error") if response else "no response"
+            raise AssociationError(f"Association failed: {err}")
+
+        resp_nonce = _b64decode(response.get("nonce", ""))
+        resp_message = response.get("message", "")
+        if not resp_message:
+            raise AssociationError("No encrypted message in associate response")
+
+        decrypted = self._decrypt(resp_message, resp_nonce)
+        if not decrypted:
+            raise AssociationError("Failed to decrypt associate response")
+
+        assoc_id = decrypted.get("id")
+        db_hash = decrypted.get("hash")
+        if not assoc_id:
+            raise AssociationError("No association ID in response")
+
+        association = Association(
+            id=assoc_id,
+            id_key=_b64encode(bytes(id_public_key)),
+            key=_b64encode(bytes(id_key)),
+        )
+
+        if db_hash:
+            self.config.associations[db_hash] = association
+
+        logger.info("Associated with KeePassXC (id=%s)", assoc_id)
+        return association
+
+    def test_associate(self, association: Association) -> bool:
+        """Test if an existing association is still valid."""
+        inner = {
+            "action": "test-associate",
+            "id": association.id,
+            "key": association.id_key,
+        }
+        result = self._send_encrypted("test-associate", inner)
+        return result is not None
+
+    def _get_connection_keys(self) -> list[dict]:
+        """Build the keys array from stored associations for authenticated requests."""
+        return [
+            {"id": assoc.id, "key": assoc.id_key}
+            for assoc in self.config.associations.values()
+        ]
+
+    # ------------------------------------------------------------------
+    # Protocol: database hash / unlock
+    # ------------------------------------------------------------------
+
+    def _send_get_databasehash(self, trigger_unlock: bool = False) -> dict | None:
+        """Send a get-databasehash request. Returns raw response dict."""
+        nonce = nacl.utils.random(nacl.public.Box.NONCE_SIZE)
+        inner = {"action": "get-databasehash"}
+        encrypted = self._encrypt(inner, nonce)
+        msg = {
+            "action": "get-databasehash",
+            "message": encrypted,
+            "nonce": _b64encode(nonce),
+        }
+        if trigger_unlock:
+            msg["triggerUnlock"] = "true"
+        return self._send_json(msg)
+
+    def trigger_unlock(self) -> bool:
+        """Trigger KeePassXC database unlock (biometrics/TouchID).
+
+        Sends get-databasehash with triggerUnlock=true (non-blocking), then
+        polls until the DB is unlocked or the timeout expires.
+
+        Returns True if the database is now unlocked.
+        """
+        logger.debug("Sending get-databasehash with triggerUnlock=true")
+        response = self._send_get_databasehash(trigger_unlock=True)
+
+        if not response:
+            logger.error("No response to unlock trigger")
+            return False
+
+        if "errorCode" not in response:
+            logger.info("Database was already unlocked")
+            return True
+
+        error_code = response.get("errorCode")
+        if error_code != "1":
+            logger.error("Unlock failed: %s (code %s)", response.get("error"), error_code)
+            return False
+
+        logger.info("Unlock dialog triggered, waiting for user to authenticate...")
+        deadline = time.monotonic() + self.config.unlock_timeout
+        poll_interval = 1.0
+
+        while time.monotonic() < deadline:
+            time.sleep(poll_interval)
+
+            self.disconnect()
+            if not self.connect():
+                continue
+            if not self.change_public_keys():
+                continue
+
+            response = self._send_get_databasehash(trigger_unlock=False)
+            if not response:
+                continue
+
+            if "errorCode" not in response:
+                logger.info("Database unlocked successfully")
+                return True
+
+            logger.debug("Still locked, polling...")
+
+        logger.warning("Timeout waiting for database unlock")
+        return False
+
+    def ensure_unlocked(self) -> bool:
+        """Connect and ensure the database is unlocked.
+
+        Handles the full flow: connect → key exchange → trigger unlock.
+        Returns True if the database is now unlocked.
+
+        Raises NotAssociatedError if no associations are configured.
+        """
+        if not self.config.associations:
+            raise NotAssociatedError("No associations configured. Run setup() first.")
+
+        if not self.connect():
+            return False
+
+        try:
+            if not self.change_public_keys():
+                return False
+            return self.trigger_unlock()
+        finally:
+            self.disconnect()
+
+    def setup(self) -> bool:
+        """Perform initial setup: connect, key exchange, and associate.
+
+        The user must approve the association in the KeePassXC window.
+        Returns True on success.
+
+        Raises AssociationError if the user denies or an error occurs.
+        """
+        if not self.connect():
+            return False
+
+        try:
+            if not self.change_public_keys():
+                return False
+
+            print("Requesting association with KeePassXC...")
+            print("Please approve the association in the KeePassXC window.")
+
+            association = self.associate()
+            if not association:
+                return False
+
+            print(f"Association successful! ID: {association.id}")
+            return True
+        finally:
+            self.disconnect()
+
+    # ------------------------------------------------------------------
+    # API: read operations
+    # ------------------------------------------------------------------
+
+    def get_logins(
+        self,
+        url: str,
+        submit_url: str = "",
+        http_auth: bool = False,
+    ) -> list[Entry]:
+        """Return entries matching the given URL.
+
+        KeePassXC matches entries whose URL field matches ``url``.
+
+        Args:
+            url: The site URL to look up (e.g. "https://example.com").
+            submit_url: Optional form submission URL for more precise matching.
+            http_auth: Set True to search HTTP Basic Auth entries.
+
+        Returns:
+            List of matching entries.
+        """
+        inner: dict = {
+            "action": "get-logins",
+            "url": url,
+            "keys": self._get_connection_keys(),
+        }
+        if submit_url:
+            inner["submitUrl"] = submit_url
+        if http_auth:
+            inner["httpAuth"] = "true"
+
+        decrypted = self._send_encrypted("get-logins", inner)
+        if not decrypted:
+            return []
+
+        return [Entry.from_dict(e) for e in decrypted.get("entries", [])]
+
+    def get_database_entries(self) -> list[Entry]:
+        """Return all entries in the database.
+
+        Returns:
+            List of all entries.
+        """
+        inner = {
+            "action": "get-database-entries",
+            "keys": self._get_connection_keys(),
+        }
+        decrypted = self._send_encrypted("get-database-entries", inner)
+        if not decrypted:
+            return []
+
+        return [Entry.from_dict(e) for e in decrypted.get("entries", [])]
+
+    def get_database_groups(self) -> list[Group]:
+        """Return all groups in the database as a tree.
+
+        Returns:
+            List of root groups; each group has a ``children`` attribute.
+        """
+        inner = {"action": "get-database-groups"}
+        decrypted = self._send_encrypted("get-database-groups", inner)
+        if not decrypted:
+            return []
+
+        groups_data = decrypted.get("groups", {})
+        # KeePassXC returns {"groups": {"groups": [...]}}
+        if isinstance(groups_data, dict):
+            groups_data = groups_data.get("groups", [])
+
+        return [Group.from_dict(g) for g in groups_data]
+
+    def get_totp(self, uuid: str) -> str | None:
+        """Return the current TOTP code for an entry.
+
+        Args:
+            uuid: The entry UUID.
+
+        Returns:
+            TOTP code string, or None if the entry has no TOTP configured.
+        """
+        inner = {
+            "action": "get-totp",
+            "uuid": uuid,
+        }
+        decrypted = self._send_encrypted("get-totp", inner)
+        if not decrypted:
+            return None
+        return decrypted.get("totp") or None
+
+    # ------------------------------------------------------------------
+    # API: write operations
+    # ------------------------------------------------------------------
+
+    def set_login(
+        self,
+        url: str,
+        username: str,
+        password: str,
+        *,
+        title: str = "",
+        submit_url: str = "",
+        uuid: str = "",
+        group: str = "",
+        group_uuid: str = "",
+        download_favicon: bool = False,
+    ) -> bool:
+        """Create or update a login entry.
+
+        Pass ``uuid`` to update an existing entry; omit to create a new one.
+
+        Args:
+            url: The URL to associate with this entry.
+            username: The username/login field.
+            password: The password field.
+            title: Optional entry title (defaults to the URL hostname in KeePassXC).
+            submit_url: Optional form submit URL.
+            uuid: Existing entry UUID for updates.
+            group: Target group name for new entries.
+            group_uuid: Target group UUID for new entries.
+            download_favicon: Ask KeePassXC to download the site's favicon.
+
+        Returns:
+            True on success.
+        """
+        inner: dict = {
+            "action": "set-login",
+            "url": url,
+            "login": username,
+            "password": password,
+            "keys": self._get_connection_keys(),
+        }
+        if title:
+            inner["id"] = title
+        if submit_url:
+            inner["submitUrl"] = submit_url
+        if uuid:
+            inner["uuid"] = uuid
+        if group:
+            inner["group"] = group
+        if group_uuid:
+            inner["groupUuid"] = group_uuid
+        if download_favicon:
+            inner["downloadFavicon"] = "true"
+
+        decrypted = self._send_encrypted("set-login", inner)
+        return decrypted is not None
+
+    def create_group(self, name: str, parent_group_uuid: str = "") -> Group | None:
+        """Create a new group in the database.
+
+        Args:
+            name: Group name.
+            parent_group_uuid: UUID of the parent group. If empty, creates at root.
+
+        Returns:
+            The newly created Group, or None on failure.
+        """
+        inner: dict = {
+            "action": "create-new-group",
+            "groupName": name,
+        }
+        if parent_group_uuid:
+            inner["groupUuid"] = parent_group_uuid
+
+        decrypted = self._send_encrypted("create-new-group", inner)
+        if not decrypted:
+            return None
+
+        return Group(
+            uuid=decrypted.get("uuid", ""),
+            name=decrypted.get("name", name),
+        )
+
+    def delete_entry(self, uuid: str) -> bool:
+        """Delete an entry by UUID.
+
+        Args:
+            uuid: The entry UUID to delete.
+
+        Returns:
+            True on success.
+        """
+        inner = {
+            "action": "delete-entry",
+            "uuid": uuid,
+        }
+        decrypted = self._send_encrypted("delete-entry", inner)
+        return decrypted is not None
+
+    def lock_database(self) -> bool:
+        """Lock the KeePassXC database.
+
+        Returns:
+            True if the lock command was accepted.
+        """
+        inner = {"action": "lock-database"}
+        decrypted = self._send_encrypted("lock-database", inner)
+        return decrypted is not None
+
+    def request_autotype(self, search: str = "") -> bool:
+        """Trigger KeePassXC's global auto-type for the active window.
+
+        KeePassXC will show an entry picker if multiple matches are found,
+        or auto-fill immediately when there is exactly one match.
+
+        Does not require an existing association.
+
+        Args:
+            search: Optional search string (e.g. domain) to pre-filter entries.
+                    KeePassXC ignores strings longer than 256 characters.
+
+        Returns:
+            True if KeePassXC accepted the request.
+        """
+        inner: dict = {"action": "request-autotype"}
+        if search:
+            inner["search"] = search
+        decrypted = self._send_encrypted("request-autotype", inner)
+        return decrypted is not None
+
+    def generate_password(self) -> str | None:
+        """Ask KeePassXC to generate a password.
+
+        KeePassXC uses its own configured generator settings; there are no
+        client-side parameters — the password profile is configured in the
+        KeePassXC application settings.
+
+        Note: Unlike other actions, the request is sent unencrypted but the
+        response is encrypted using the session keys.
+
+        Returns:
+            Generated password string, or None on failure.
+        """
+        if not self._ensure_session():
+            return None
+        nonce = nacl.utils.random(nacl.public.Box.NONCE_SIZE)
+        msg = {
+            "action": "generate-password",
+            "nonce": _b64encode(nonce),
+        }
+        response = self._send_json(msg)
+        if not response or "errorCode" in response:
+            return None
+
+        resp_nonce_b64 = response.get("nonce", "")
+        resp_message = response.get("message", "")
+        if not resp_message or not resp_nonce_b64:
+            return None
+
+        resp_nonce = _b64decode(resp_nonce_b64)
+        decrypted = self._decrypt(resp_message, resp_nonce)
+        if not decrypted:
+            return None
+
+        entries = decrypted.get("entries", [])
+        if entries and isinstance(entries, list):
+            return entries[0].get("password") or None
+        return decrypted.get("password") or None

keepassxc_browser_api/config.py

@@ -0,0 +1,101 @@
+"""Persistent configuration for the KeePassXC browser API library."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import stat
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+DEFAULT_CONFIG_DIR = Path.home() / ".keepassxc"
+DEFAULT_CONFIG_PATH = DEFAULT_CONFIG_DIR / "browser-api.json"
+
+DEFAULT_UNLOCK_TIMEOUT = 30
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Association:
+    """Stored association with a KeePassXC database."""
+
+    id: str
+    id_key: str  # base64-encoded identity public key
+    key: str     # base64-encoded identity secret key
+
+    def to_dict(self) -> dict:
+        return {"id": self.id, "id_key": self.id_key, "key": self.key}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> Association:
+        return cls(id=d["id"], id_key=d["id_key"], key=d["key"])
+
+
+@dataclass
+class BrowserConfig:
+    """Configuration for the KeePassXC browser API connection.
+
+    Shared between keepassxc-cli and keepassxc-ssh-agent so that a single
+    association covers both tools.
+    """
+
+    unlock_timeout: int = DEFAULT_UNLOCK_TIMEOUT
+    # NaCl keypair for browser protocol communication (base64-encoded)
+    client_public_key: str = ""
+    client_secret_key: str = ""
+    # Per-database associations (keyed by database hash)
+    associations: dict[str, Association] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            "unlock_timeout": self.unlock_timeout,
+            "client_public_key": self.client_public_key,
+            "client_secret_key": self.client_secret_key,
+            "associations": {k: v.to_dict() for k, v in self.associations.items()},
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> BrowserConfig:
+        associations = {}
+        for k, v in d.get("associations", {}).items():
+            associations[k] = Association.from_dict(v)
+        return cls(
+            unlock_timeout=d.get("unlock_timeout", DEFAULT_UNLOCK_TIMEOUT),
+            client_public_key=d.get("client_public_key", ""),
+            client_secret_key=d.get("client_secret_key", ""),
+            associations=associations,
+        )
+
+    def save(self, path: Path | None = None) -> None:
+        path = path or DEFAULT_CONFIG_PATH
+        path.parent.mkdir(parents=True, exist_ok=True)
+        os.chmod(str(path.parent), stat.S_IRWXU)
+        # Write to a temp file with 0600 permissions, then atomically rename
+        # to avoid a race window where secrets are world-readable.
+        tmp_path = path.with_suffix(".tmp")
+        fd = os.open(str(tmp_path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        try:
+            with os.fdopen(fd, "w") as f:
+                json.dump(self.to_dict(), f, indent=2)
+        except BaseException:
+            os.unlink(tmp_path)
+            raise
+        os.replace(tmp_path, path)
+
+    @classmethod
+    def load(cls, path: Path | None = None) -> BrowserConfig:
+        path = path or DEFAULT_CONFIG_PATH
+        if not path.exists():
+            return cls()
+        mode = path.stat().st_mode
+        if mode & 0o077:
+            logger.warning(
+                "Config file %s has insecure permissions %o; expected 0600. "
+                "Fix with: chmod 600 %s",
+                path, mode & 0o777, path,
+            )
+        with open(path) as f:
+            return cls.from_dict(json.load(f))

keepassxc_browser_api/exceptions.py

@@ -0,0 +1,27 @@
+"""Custom exceptions for the KeePassXC browser API library."""
+
+from __future__ import annotations
+
+
+class KeePassXCError(Exception):
+    """Base exception for all KeePassXC browser API errors."""
+
+
+class ConnectionError(KeePassXCError):
+    """Could not connect to KeePassXC."""
+
+
+class AssociationError(KeePassXCError):
+    """Association with KeePassXC failed or was denied."""
+
+
+class NotAssociatedError(KeePassXCError):
+    """No valid association exists. Run setup() first."""
+
+
+class DatabaseLockedError(KeePassXCError):
+    """The KeePassXC database is locked and could not be unlocked."""
+
+
+class ProtocolError(KeePassXCError):
+    """Unexpected response from KeePassXC (encryption, JSON, protocol errors)."""

keepassxc_browser_api/models.py

@@ -0,0 +1,77 @@
+"""Data models for KeePassXC browser API responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Entry:
+    """A KeePassXC database entry."""
+
+    uuid: str
+    name: str
+    login: str
+    password: str
+    totp: str = ""
+    group: str = ""
+    group_uuid: str = ""
+    # Additional string fields (e.g. Notes, custom fields)
+    string_fields: list[dict[str, str]] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> Entry:
+        return cls(
+            uuid=d.get("uuid", ""),
+            name=d.get("name", ""),
+            login=d.get("login", ""),
+            password=d.get("password", ""),
+            totp=d.get("totp", ""),
+            group=d.get("group", ""),
+            group_uuid=d.get("groupUuid", ""),
+            string_fields=d.get("stringFields", []),
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "uuid": self.uuid,
+            "name": self.name,
+            "login": self.login,
+            "password": self.password,
+            "totp": self.totp,
+            "group": self.group,
+            "groupUuid": self.group_uuid,
+            "stringFields": self.string_fields,
+        }
+
+
+@dataclass
+class Group:
+    """A KeePassXC database group."""
+
+    uuid: str
+    name: str
+    children: list[Group] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> Group:
+        children = [Group.from_dict(c) for c in d.get("children", [])]
+        return cls(
+            uuid=d.get("uuid", ""),
+            name=d.get("name", ""),
+            children=children,
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "uuid": self.uuid,
+            "name": self.name,
+            "children": [c.to_dict() for c in self.children],
+        }
+
+    def flat_list(self) -> list[Group]:
+        """Return a flat list of this group and all descendants."""
+        result = [self]
+        for child in self.children:
+            result.extend(child.flat_list())
+        return result

keepassxc_browser_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: keepassxc-browser-api
+Version: 0.1.0
+Summary: Python library for the KeePassXC browser extension protocol
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyNaCl==1.6.2
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# KeePassXC Browser API
+
+Python library for communicating with [KeePassXC](https://keepassxc.org/) via the browser extension protocol (NaCl-encrypted JSON over a Unix socket).
+
+## Features
+
+- NaCl-encrypted communication with KeePassXC
+- One-time association flow (user approves in KeePassXC window)
+- Biometric unlock (TouchID / system unlock) via `triggerUnlock`
+- Full browser API support: read entries, write entries, manage groups, TOTP, password generation, lock database
+- Cross-platform: macOS and Linux
+- Shared config (`~/.keepassxc/browser-api.json`) — associate once, use with all tools
+
+## Installation
+
+```shell
+pip install keepassxc-browser-api
+```
+
+## Quick start
+
+```python
+from keepassxc_browser_api import BrowserClient, BrowserConfig
+
+config = BrowserConfig.load()
+client = BrowserClient(config)
+
+# First time: associate with KeePassXC (requires user approval)
+if not config.associations:
+    client.setup()
+    config.save()
+
+# Ensure DB is unlocked (triggers TouchID/biometrics if locked)
+client.ensure_unlocked()
+
+# API methods auto-connect when needed
+entries = client.get_logins("https://example.com")
+for e in entries:
+    print(e.name, e.login)
+
+# Clean up when done
+client.disconnect()
+```
+
+Or use the context manager for automatic cleanup:
+
+```python
+with BrowserClient(config) as client:
+    entries = client.get_logins("https://example.com")
+    totp = client.get_totp(entries[0].uuid)
+```
+
+## API
+
+### `BrowserClient`
+
+| Method | Description |
+|---|---|
+| `setup()` | First-time association (user approves in KeePassXC) |
+| `ensure_unlocked()` | Connect and unlock (triggers TouchID if locked) |
+| `get_logins(url, ...)` | Find entries matching a URL |
+| `set_login(url, username, password, ...)` | Create or update an entry |
+| `get_database_entries()` | Return all entries |
+| `get_database_groups()` | Return all groups (tree) |
+| `create_group(name, parent_uuid)` | Create a new group |
+| `get_totp(uuid)` | Get TOTP code for an entry |
+| `delete_entry(uuid)` | Delete an entry |
+| `lock_database()` | Lock the database |
+| `generate_password()` | Generate a password (uses KeePassXC settings) |
+| `request_autotype(search)` | Trigger KeePassXC global auto-type |
+
+> **Note**: `passkeys-get` and `passkeys-register` are not implemented. They require complex WebAuthn/CBOR data structures and are only available in KeePassXC builds compiled with `WITH_XC_BROWSER_PASSKEYS`.
+
+### `BrowserConfig`
+
+Configuration stored at `~/.keepassxc/browser-api.json` (mode 0600).
+
+```python
+config = BrowserConfig.load()        # Load from default path
+config = BrowserConfig.load(path)    # Load from custom path
+config.save()                        # Save to default path
+config.save(path)                    # Save to custom path
+```
+
+## Protocol documentation
+
+For a detailed description of the KeePassXC browser extension protocol (wire format, encryption, all actions, error codes), see **[PROTOCOL.md](PROTOCOL.md)**.
+
+## Development
+
+```shell
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=keepassxc_browser_api
+
+# Lint
+ruff check --ignore=E501 --exclude=__init__.py ./keepassxc_browser_api
+```

keepassxc_browser_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+keepassxc_browser_api/__init__.py,sha256=xfhR4r7opKml-2d1D9AlOUdFyjVpZJrXIHh8FRHFO_0,568
+keepassxc_browser_api/client.py,sha256=omIcmjhrsm0SZmjb4uuB4zsbhJgDmogs6MOtjYR3Tfw,24789
+keepassxc_browser_api/config.py,sha256=I-wmrgc-oCgcupLDf0vFXefXMDhsg6bQFElAuo9mLag,3369
+keepassxc_browser_api/exceptions.py,sha256=tdzRxxtDzAGYL_M6A6bd5emu_bTp7sLzlroxHb1LVcU,719
+keepassxc_browser_api/models.py,sha256=9qVZuB55Vkae0g76HQrP8Qr0Wdis9euf6axd_Wtxk5Y,2049
+keepassxc_browser_api-0.1.0.dist-info/licenses/LICENSE,sha256=i7l1iI-cTPEtMrRCNzPD2_ZMZV0LQna7gPvYG0lVoCs,1061
+keepassxc_browser_api-0.1.0.dist-info/METADATA,sha256=NG6jAWuorE46RxvAk_D9rGo6Eq9dqu-wKIy1mV7wIt8,3617
+keepassxc_browser_api-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+keepassxc_browser_api-0.1.0.dist-info/top_level.txt,sha256=zu-vCqfTZLbp3CdEEG5TwPqS9wOvo_uP45q9uT8Ir5s,22
+keepassxc_browser_api-0.1.0.dist-info/RECORD,,

keepassxc_browser_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

keepassxc_browser_api-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nils
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

keepassxc_browser_api-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+keepassxc_browser_api