hivemind-sqlite-database 0.0.3a1__tar.gz → 0.3.0a3__tar.gz

hivemind_sqlite_database-0.3.0a3/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: hivemind-sqlite-database
+Version: 0.3.0a3
+Summary: sqlite database plugin for hivemind-core
+Author-email: jarbasAi <jarbasai@mailfence.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/JarbasHiveMind/hivemind-sqlite-database
+Requires-Python: >=3.9
+License-File: LICENSE.md
+Requires-Dist: hivemind-plugin-manager<1.0.0,>=0.5.0
+Requires-Dist: hivemind-bus-client
+Requires-Dist: ovos-utils
+Provides-Extra: cipher
+Requires-Dist: sqlcipher3; extra == "cipher"
+Dynamic: license-file

hivemind_sqlite_database-0.3.0a3/README.md

@@ -0,0 +1,76 @@
+# HiveMind SQLite Database
+
+SQLite database plugin for [hivemind-core](https://github.com/JarbasHiveMind/HiveMind-core).
+
+Implements the `AbstractDB` interface via `hivemind-plugin-manager` and stores HiveMind
+client records (API keys, crypto keys, access-control lists) in a local SQLite file.
+
+## Installation
+
+```bash
+pip install hivemind-sqlite-database
+```
+
+### With encryption support (SQLCipher)
+
+```bash
+# 1. Install the SQLCipher system library
+#    Debian/Ubuntu:
+sudo apt install libsqlcipher0
+
+# 2. Install the Python binding via the optional extra
+pip install "hivemind-sqlite-database[cipher]"
+```
+
+> The `sqlcipher3` wheel on PyPI ships its own libsqlcipher for x86_64 Linux, so the
+> `apt` step may be optional on that platform.  On ARM or Alpine you must build from
+> source and will need the system library.
+
+## Usage
+
+### Plain (unencrypted) database — default
+
+```python
+from hivemind_sqlite_database import SQLiteDB
+
+db = SQLiteDB()           # stores data in XDG_DATA_HOME/hivemind-core/clients.db
+```
+
+### Encrypted database (SQLCipher / AES-256)
+
+```python
+from hivemind_sqlite_database import SQLiteDB
+
+db = SQLiteDB(password="your-strong-passphrase")
+```
+
+Pass the same `password` every time you open the database.  The encryption is
+transparent — all existing methods (`add_item`, `search_by_value`, etc.) work
+identically.
+
+> **Data-loss warning**: There is no password recovery.  If you lose the passphrase
+> the database is permanently unrecoverable.  Back up your passphrase securely.
+
+### hivemind-core configuration
+
+```json
+{
+  "database": {
+    "module": "hivemind-sqlite-db-plugin",
+    "hivemind-sqlite-db-plugin": {
+      "name": "clients",
+      "subfolder": "hivemind-core",
+      "password": "your-strong-passphrase"
+    }
+  }
+}
+```
+
+Leave `"password"` out (or set it to `null`) to use an unencrypted database.
+
+## Notes
+
+- An encrypted database cannot be opened by the plain `sqlite3` CLI or stdlib module.
+- A plaintext database cannot be opened as encrypted.  There is no automatic migration.
+- The `password` field maps directly to SQLCipher's `PRAGMA key`.
+- WAL journal mode is enabled for both encrypted and unencrypted databases.

hivemind_sqlite_database-0.3.0a3/hivemind_sqlite_database/__init__.py

@@ -0,0 +1,244 @@
+import json
+import os.path
+import sqlite3
+import threading
+from typing import List, Optional, Union, Iterable
+
+from ovos_utils.log import LOG
+from ovos_utils.xdg_utils import xdg_data_home
+
+from hivemind_plugin_manager.database import Client, AbstractDB
+
+from dataclasses import dataclass
+
+
+_VALID_COLUMNS = frozenset({
+    "client_id", "api_key", "name", "description", "is_admin",
+    "last_seen", "intent_blacklist", "skill_blacklist", "message_blacklist",
+    "allowed_types", "crypto_key", "password",
+    "can_broadcast", "can_escalate", "can_propagate", "metadata",
+})
+
+
+@dataclass
+class SQLiteDB(AbstractDB):
+    """Database implementation using SQLite."""
+    name: str = "clients"
+    subfolder: str = "hivemind-core"
+    password: Optional[str] = None
+
+    def __post_init__(self):
+        """
+        Initialize the SQLiteDB connection.
+
+        When *password* is set the database is opened via ``sqlcipher3`` and
+        encrypted with AES-256 (SQLCipher).  The system library
+        ``libsqlcipher0`` must be installed and ``sqlcipher3`` must be
+        available (``pip install hivemind-sqlite-database[cipher]``).
+
+        When *password* is ``None`` (default) the standard ``sqlite3`` module
+        is used and the database file is unencrypted.
+        """
+        db_path = os.path.join(xdg_data_home(), self.subfolder, self.name + ".db")
+        LOG.debug(f"sqlite database path: {db_path}")
+        os.makedirs(os.path.dirname(db_path), exist_ok=True)
+
+        if self.password is not None:
+            if self.password == "":
+                raise ValueError("password must be non-empty when encryption is enabled")
+            try:
+                import sqlcipher3 as _sqlcipher
+            except ImportError:
+                raise ImportError(
+                    "sqlcipher3 is required to open an encrypted SQLite database. "
+                    "Install the system library (e.g. 'apt install libsqlcipher-dev') "
+                    "then: pip install hivemind-sqlite-database[cipher]"
+                )
+            self.conn = _sqlcipher.connect(db_path, check_same_thread=False)
+            self.conn.row_factory = _sqlcipher.Row
+            escaped_password = self.password.replace("'", "''")
+            self.conn.execute(f"PRAGMA key='{escaped_password}'")
+        else:
+            self.conn = sqlite3.connect(db_path, check_same_thread=False)
+            self.conn.row_factory = sqlite3.Row
+
+        self.conn.execute("PRAGMA journal_mode=WAL")
+        self._write_lock = threading.Lock()
+        self._initialize_database()
+
+    def _initialize_database(self):
+        """Initialize the database schema."""
+        with self.conn:
+            # crypto key is always 16 chars
+            # name description and api_key shouldnt be allowed to go over 255
+            self.conn.execute("""
+                CREATE TABLE IF NOT EXISTS clients (
+                    client_id INTEGER PRIMARY KEY,
+                    api_key VARCHAR(255) NOT NULL,
+                    name VARCHAR(255),
+                    description VARCHAR(255),
+                    is_admin BOOLEAN DEFAULT FALSE,
+                    last_seen REAL DEFAULT -1,
+                    intent_blacklist TEXT,
+                    skill_blacklist TEXT,
+                    message_blacklist TEXT,
+                    allowed_types TEXT,
+                    crypto_key VARCHAR(16),
+                    password TEXT,
+                    can_broadcast BOOLEAN DEFAULT TRUE,
+                    can_escalate BOOLEAN DEFAULT TRUE,
+                    can_propagate BOOLEAN DEFAULT TRUE,
+                    metadata TEXT
+                )
+            """)
+            columns = {
+                row["name"]
+                for row in self.conn.execute("PRAGMA table_info(clients)").fetchall()
+            }
+            if "metadata" not in columns:
+                self.conn.execute("ALTER TABLE clients ADD COLUMN metadata TEXT")
+
+    def add_item(self, client: Client) -> bool:
+        """
+        Add a client to the SQLite database.
+
+        Args:
+            client: The client to be added.
+
+        Returns:
+            True if the addition was successful, False otherwise.
+        """
+        try:
+            metadata_json = self._metadata_to_json(client.metadata or {})
+            with self._write_lock, self.conn:
+                self.conn.execute("""
+                    INSERT OR REPLACE INTO clients (
+                        client_id, api_key, name, description, is_admin,
+                        last_seen, intent_blacklist, skill_blacklist,
+                        message_blacklist, allowed_types, crypto_key, password,
+                        can_broadcast, can_escalate, can_propagate, metadata
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """, (
+                    client.client_id, client.api_key, client.name, client.description,
+                    client.is_admin, client.last_seen,
+                    json.dumps(client.intent_blacklist),
+                    json.dumps(client.skill_blacklist),
+                    json.dumps(client.message_blacklist),
+                    json.dumps(client.allowed_types),
+                    client.crypto_key, client.password,
+                    client.can_broadcast, client.can_escalate, client.can_propagate,
+                    metadata_json,
+                ))
+            return True
+        except sqlite3.Error as e:
+            LOG.error(f"Failed to add client to SQLite: {e}")
+            return False
+
+    def search_by_value(self, key: str, val: Union[str, bool, int, float]) -> List[Client]:
+        """
+        Search for clients by a specific key-value pair in the SQLite database.
+
+        Args:
+            key: The key to search by.
+            val: The value to search for.
+
+        Returns:
+            A list of clients that match the search criteria.
+        """
+        if key not in _VALID_COLUMNS:
+            LOG.error(f"Invalid search key: {key!r}")
+            return []
+        try:
+            with self.conn:
+                cur = self.conn.execute(f"SELECT * FROM clients WHERE {key} = ?", (val,))
+                rows = cur.fetchall()
+                return [self._row_to_client(row) for row in rows]
+        except sqlite3.Error as e:
+            LOG.error(f"Failed to search clients in SQLite: {e}")
+            return []
+
+    def __len__(self) -> int:
+        """Get the number of clients in the database."""
+        try:
+            cur = self.conn.execute("SELECT COUNT(*) FROM clients")
+            return cur.fetchone()[0]
+        except sqlite3.Error as e:
+            LOG.error(f"Failed to count clients in SQLite: {e}")
+            return 0
+
+    def __iter__(self) -> Iterable['Client']:
+        """
+        Iterate over all clients in the SQLite database.
+
+        Returns:
+            An iterator over the clients in the database.
+        """
+        cur = self.conn.execute("SELECT * FROM clients")
+        for row in cur:
+            yield self._row_to_client(row)
+
+    def commit(self) -> bool:
+        """Commit changes to the SQLite database."""
+        try:
+            with self._write_lock:
+                self.conn.commit()
+            return True
+        except sqlite3.Error as e:
+            LOG.error(f"Failed to commit SQLite database: {e}")
+            return False
+
+    @staticmethod
+    def _row_to_client(row: sqlite3.Row) -> Client:
+        """Convert a database row to a Client instance."""
+        kwargs = {
+            "client_id": int(row["client_id"]),
+            "api_key": row["api_key"],
+            "name": row["name"],
+            "description": row["description"],
+            "is_admin": bool(row["is_admin"]),
+            "last_seen": row["last_seen"],
+            "intent_blacklist": json.loads(row["intent_blacklist"] or "[]"),
+            "skill_blacklist": json.loads(row["skill_blacklist"] or "[]"),
+            "message_blacklist": json.loads(row["message_blacklist"] or "[]"),
+            "allowed_types": json.loads(row["allowed_types"] or "[]"),
+            "crypto_key": row["crypto_key"],
+            "password": row["password"],
+            "can_broadcast": bool(row["can_broadcast"]),
+            "can_escalate": bool(row["can_escalate"]),
+            "can_propagate": bool(row["can_propagate"]),
+            "metadata": SQLiteDB._metadata_from_row(row),
+        }
+        return Client(**kwargs)
+
+    @staticmethod
+    def _metadata_to_json(metadata: object) -> str:
+        """Serialize ``Client.metadata`` for storage in the ``metadata`` column.
+
+        ``metadata`` is documented as a free-form dict; we use ``default=str``
+        so callers can stash convenience values like ``datetime`` or ``UUID``
+        without crashing on insert. Note that these come back as strings on
+        read — the column is opaque JSON, not a typed map. Returns ``"{}"``
+        for non-dict input and on any (unexpected) serialisation failure
+        rather than corrupting the row.
+        """
+        if not isinstance(metadata, dict):
+            return "{}"
+        try:
+            return json.dumps(metadata, default=str)
+        except (TypeError, ValueError):
+            return "{}"
+
+    @staticmethod
+    def _metadata_from_row(row: sqlite3.Row) -> dict:
+        """Decode the ``metadata`` column into a dict, swallowing garbage.
+
+        Returns ``{}`` for NULL, malformed JSON, or valid-JSON-that-isn't-an-object.
+        Lets a single bad row not poison iteration over the table.
+        """
+        if "metadata" not in row.keys() or not row["metadata"]:
+            return {}
+        try:
+            metadata = json.loads(row["metadata"])
+        except (TypeError, ValueError):
+            return {}
+        return metadata if isinstance(metadata, dict) else {}

hivemind_sqlite_database-0.3.0a3/hivemind_sqlite_database/version.py

@@ -0,0 +1,8 @@
+# START_VERSION_BLOCK
+VERSION_MAJOR = 0
+VERSION_MINOR = 3
+VERSION_BUILD = 0
+VERSION_ALPHA = 3
+# END_VERSION_BLOCK
+
+__version__ = f"{VERSION_MAJOR}.{VERSION_MINOR}.{VERSION_BUILD}" + (f"a{VERSION_ALPHA}" if VERSION_ALPHA else "")

hivemind_sqlite_database-0.3.0a3/hivemind_sqlite_database.egg-info/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: hivemind-sqlite-database
+Version: 0.3.0a3
+Summary: sqlite database plugin for hivemind-core
+Author-email: jarbasAi <jarbasai@mailfence.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/JarbasHiveMind/hivemind-sqlite-database
+Requires-Python: >=3.9
+License-File: LICENSE.md
+Requires-Dist: hivemind-plugin-manager<1.0.0,>=0.5.0
+Requires-Dist: hivemind-bus-client
+Requires-Dist: ovos-utils
+Provides-Extra: cipher
+Requires-Dist: sqlcipher3; extra == "cipher"
+Dynamic: license-file

{hivemind-sqlite-database-0.0.3a1 → hivemind_sqlite_database-0.3.0a3}/hivemind_sqlite_database.egg-info/SOURCES.txt

@@ -1,6 +1,6 @@
 LICENSE.md
 README.md
-setup.py
+pyproject.toml
 hivemind_sqlite_database/__init__.py
 hivemind_sqlite_database/version.py
 hivemind_sqlite_database.egg-info/PKG-INFO
@@ -8,4 +8,5 @@ hivemind_sqlite_database.egg-info/SOURCES.txt
 hivemind_sqlite_database.egg-info/dependency_links.txt
 hivemind_sqlite_database.egg-info/entry_points.txt
 hivemind_sqlite_database.egg-info/requires.txt
-hivemind_sqlite_database.egg-info/top_level.txt
+hivemind_sqlite_database.egg-info/top_level.txt
+tests/test_sqlitedb.py

hivemind_sqlite_database-0.3.0a3/hivemind_sqlite_database.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[hivemind.database]
+hivemind-sqlite-db-plugin = hivemind_sqlite_database:SQLiteDB

hivemind_sqlite_database-0.3.0a3/hivemind_sqlite_database.egg-info/requires.txt

@@ -0,0 +1,6 @@
+hivemind-plugin-manager<1.0.0,>=0.5.0
+hivemind-bus-client
+ovos-utils
+
+[cipher]
+sqlcipher3

hivemind_sqlite_database-0.3.0a3/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hivemind-sqlite-database"
+dynamic = ["version"]
+description = "sqlite database plugin for hivemind-core"
+license = { text = "Apache-2.0" }
+authors = [{ name = "jarbasAi", email = "jarbasai@mailfence.com" }]
+requires-python = ">=3.9"
+dependencies = [
+    "hivemind-plugin-manager>=0.5.0,<1.0.0",
+    "hivemind-bus-client",
+    "ovos-utils",
+]
+
+
+[project.optional-dependencies]
+cipher = ["sqlcipher3"]
+
+[project.urls]
+Homepage = "https://github.com/JarbasHiveMind/hivemind-sqlite-database"
+
+[project.entry-points."hivemind.database"]
+"hivemind-sqlite-db-plugin" = "hivemind_sqlite_database:SQLiteDB"
+
+[tool.setuptools.dynamic]
+version = {attr = "hivemind_sqlite_database.version.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["hivemind_sqlite_database*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

hivemind_sqlite_database-0.3.0a3/tests/test_sqlitedb.py

@@ -0,0 +1,536 @@
+"""
+Tests for SQLiteDB using an in-memory database.
+No external services required.
+"""
+import sqlite3
+import tempfile
+import threading
+import os
+import unittest
+
+from hivemind_plugin_manager.database import Client
+from hivemind_sqlite_database import SQLiteDB
+
+
+def make_db() -> SQLiteDB:
+    """Return a fresh in-memory SQLiteDB instance."""
+    db = object.__new__(SQLiteDB)
+    db.name = "clients"
+    db.subfolder = "hivemind-core"
+    db.conn = sqlite3.connect(":memory:", check_same_thread=False)
+    db.conn.row_factory = sqlite3.Row
+    db.conn.execute("PRAGMA journal_mode=WAL")
+    db._write_lock = threading.Lock()
+    db._initialize_database()
+    return db
+
+
+def make_client(client_id: int = 1, api_key: str = "key-abc", **kwargs) -> Client:
+    return Client(client_id=client_id, api_key=api_key, **kwargs)
+
+
+class TestSQLiteDBWAL(unittest.TestCase):
+    def test_wal_mode_pragma_in_source(self):
+        """WAL pragma must be present in __post_init__ source code."""
+        import inspect
+        from hivemind_sqlite_database import SQLiteDB as _DB
+        src = inspect.getsource(_DB.__post_init__)
+        self.assertIn("journal_mode=WAL", src)
+
+    def test_wal_mode_active_on_file_db(self):
+        """WAL mode is confirmed active on a real file-based SQLite DB."""
+        with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+            path = f.name
+        try:
+            conn = sqlite3.connect(path, check_same_thread=False)
+            conn.row_factory = sqlite3.Row
+            conn.execute("PRAGMA journal_mode=WAL")
+            cur = conn.execute("PRAGMA journal_mode")
+            mode = cur.fetchone()[0]
+            conn.close()
+            self.assertEqual(mode, "wal")
+        finally:
+            os.unlink(path)
+
+
+class TestSQLiteDBLen(unittest.TestCase):
+    def test_empty_db_has_len_zero(self):
+        db = make_db()
+        self.assertEqual(len(db), 0)
+
+    def test_len_increments_after_add(self):
+        db = make_db()
+        db.add_item(make_client(1, "k1"))
+        db.add_item(make_client(2, "k2"))
+        self.assertEqual(len(db), 2)
+
+    def test_len_includes_revoked_entries(self):
+        db = make_db()
+        c = make_client(1, "k1")
+        db.add_item(c)
+        db.delete_item(c)
+        self.assertEqual(len(db), 1)
+
+    def test_len_returns_zero_on_error(self):
+        db = make_db()
+        db.add_item(make_client(1, "k1"))
+        db.conn.close()
+        self.assertEqual(len(db), 0)
+
+
+class TestSQLiteDBAddItem(unittest.TestCase):
+    def test_add_returns_true_on_success(self):
+        db = make_db()
+        result = db.add_item(make_client(1, "key"))
+        self.assertTrue(result)
+
+    def test_add_upserts_existing_client_id(self):
+        db = make_db()
+        db.add_item(make_client(1, "original"))
+        db.add_item(make_client(1, "updated"))
+        results = db.search_by_value("api_key", "updated")
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0].api_key, "updated")
+        # original key is gone
+        self.assertEqual(db.search_by_value("api_key", "original"), [])
+
+    def test_add_returns_false_on_error(self):
+        db = make_db()
+        db.conn.close()  # closing the connection causes sqlite3.Error on next operation
+        result = db.add_item(make_client(1, "key"))
+        self.assertFalse(result)
+
+
+class TestSQLiteDBDeleteItem(unittest.TestCase):
+    def test_delete_sets_api_key_to_revoked(self):
+        db = make_db()
+        c = make_client(1, "live-key")
+        db.add_item(c)
+        db.delete_item(c)
+        results = db.search_by_value("api_key", "revoked")
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0].client_id, 1)
+
+    def test_delete_does_not_remove_row(self):
+        db = make_db()
+        c = make_client(1, "live-key")
+        db.add_item(c)
+        db.delete_item(c)
+        self.assertEqual(len(db), 1)
+
+    def test_original_key_no_longer_searchable_after_delete(self):
+        db = make_db()
+        c = make_client(1, "live-key")
+        db.add_item(c)
+        db.delete_item(c)
+        self.assertEqual(db.search_by_value("api_key", "live-key"), [])
+
+
+class TestSQLiteDBSearchByValue(unittest.TestCase):
+    def test_search_by_api_key_returns_client(self):
+        db = make_db()
+        db.add_item(make_client(1, "my-key"))
+        results = db.search_by_value("api_key", "my-key")
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0].api_key, "my-key")
+
+    def test_search_returns_empty_list_on_no_match(self):
+        db = make_db()
+        db.add_item(make_client(1, "real-key"))
+        self.assertEqual(db.search_by_value("api_key", "ghost"), [])
+
+    def test_search_by_is_admin_true(self):
+        db = make_db()
+        db.add_item(make_client(1, "admin-key", is_admin=True))
+        db.add_item(make_client(2, "user-key", is_admin=False))
+        results = db.search_by_value("is_admin", True)
+        self.assertEqual(len(results), 1)
+        self.assertTrue(results[0].is_admin)
+
+    def test_search_by_is_admin_false(self):
+        db = make_db()
+        db.add_item(make_client(1, "admin-key", is_admin=True))
+        db.add_item(make_client(2, "user-key", is_admin=False))
+        results = db.search_by_value("is_admin", False)
+        self.assertEqual(len(results), 1)
+        self.assertFalse(results[0].is_admin)
+
+    def test_search_by_name(self):
+        db = make_db()
+        db.add_item(make_client(1, "k1", name="alice"))
+        db.add_item(make_client(2, "k2", name="bob"))
+        results = db.search_by_value("name", "alice")
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0].name, "alice")
+
+    def test_search_by_nonexistent_name_returns_empty(self):
+        db = make_db()
+        db.add_item(make_client(1, "k1", name="alice"))
+        self.assertEqual(db.search_by_value("name", "ghost"), [])
+
+    def test_search_returns_empty_on_sqlite_error(self):
+        db = make_db()
+        db.add_item(make_client(1, "k1"))
+        db.conn.close()
+        results = db.search_by_value("api_key", "k1")
+        self.assertEqual(results, [])
+
+    def test_search_rejects_invalid_column_name(self):
+        db = make_db()
+        db.add_item(make_client(1, "k1"))
+        results = db.search_by_value("1=1; DROP TABLE clients; --", "x")
+        self.assertEqual(results, [])
+        # table must still exist
+        self.assertEqual(len(db), 1)
+
+    def test_search_rejects_unknown_column(self):
+        db = make_db()
+        results = db.search_by_value("nonexistent_column", "value")
+        self.assertEqual(results, [])
+
+
+class TestSQLiteDBIter(unittest.TestCase):
+    def test_iter_yields_all_rows(self):
+        db = make_db()
+        db.add_item(make_client(1, "k1"))
+        db.add_item(make_client(2, "k2"))
+        all_clients = list(db)
+        self.assertEqual(len(all_clients), 2)
+
+    def test_iter_includes_revoked_entries(self):
+        db = make_db()
+        c = make_client(1, "k1")
+        db.add_item(c)
+        db.delete_item(c)
+        all_clients = list(db)
+        self.assertEqual(len(all_clients), 1)
+        self.assertEqual(all_clients[0].api_key, "revoked")
+
+    def test_iter_yields_client_instances(self):
+        db = make_db()
+        db.add_item(make_client(1, "k1"))
+        for client in db:
+            self.assertIsInstance(client, Client)
+
+
+class TestSQLiteDBRoundTrip(unittest.TestCase):
+    def test_list_fields_survive_round_trip(self):
+        db = make_db()
+        intent_bl = ["skill:action1", "skill:action2"]
+        allowed = ["recognizer_loop:utterance", "speak:b64_audio"]
+        c = make_client(1, "k1",
+                        intent_blacklist=intent_bl,
+                        allowed_types=allowed)
+        db.add_item(c)
+        results = db.search_by_value("api_key", "k1")
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0].intent_blacklist, intent_bl)
+        self.assertEqual(results[0].allowed_types, allowed)
+
+    def test_boolean_fields_remain_bool_after_round_trip(self):
+        db = make_db()
+        db.add_item(make_client(1, "k1", is_admin=True, can_broadcast=False))
+        results = db.search_by_value("api_key", "k1")
+        self.assertIs(type(results[0].is_admin), bool)
+        self.assertTrue(results[0].is_admin)
+        self.assertIs(type(results[0].can_broadcast), bool)
+        self.assertFalse(results[0].can_broadcast)
+
+    def test_metadata_survives_round_trip(self):
+        db = make_db()
+        db.add_item(
+            make_client(
+                1,
+                "k1",
+                metadata={"owner_id": "owner-123"},
+            )
+        )
+
+        results = db.search_by_value("api_key", "k1")
+
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0].metadata, {"owner_id": "owner-123"})
+
+    def test_metadata_can_be_searched(self):
+        db = make_db()
+        db.add_item(
+            make_client(
+                1,
+                "k1",
+                metadata={"owner_id": "owner-123"},
+            )
+        )
+
+        results = db.search_by_value("metadata", '{"owner_id": "owner-123"}')
+
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0].api_key, "k1")
+
+    def test_initialize_database_migrates_legacy_clients_table(self):
+        db = object.__new__(SQLiteDB)
+        db.name = "clients"
+        db.subfolder = "hivemind-core"
+        db.conn = sqlite3.connect(":memory:", check_same_thread=False)
+        db.conn.row_factory = sqlite3.Row
+        db._write_lock = threading.Lock()
+        with db.conn:
+            db.conn.execute("""
+                CREATE TABLE clients (
+                    client_id INTEGER PRIMARY KEY,
+                    api_key VARCHAR(255) NOT NULL,
+                    name VARCHAR(255),
+                    description VARCHAR(255),
+                    is_admin BOOLEAN DEFAULT FALSE,
+                    last_seen REAL DEFAULT -1,
+                    intent_blacklist TEXT,
+                    skill_blacklist TEXT,
+                    message_blacklist TEXT,
+                    allowed_types TEXT,
+                    crypto_key VARCHAR(16),
+                    password TEXT,
+                    can_broadcast BOOLEAN DEFAULT TRUE,
+                    can_escalate BOOLEAN DEFAULT TRUE,
+                    can_propagate BOOLEAN DEFAULT TRUE
+                )
+            """)
+            db.conn.execute("INSERT INTO clients (client_id, api_key) VALUES (1, 'k1')")
+
+        db._initialize_database()
+
+        columns = {
+            row["name"]
+            for row in db.conn.execute("PRAGMA table_info(clients)").fetchall()
+        }
+        self.assertIn("metadata", columns)
+        client = db.search_by_value("api_key", "k1")[0]
+        self.assertEqual(client.metadata, {})
+
+    def test_metadata_nested_dict_round_trip(self):
+        db = make_db()
+        meta = {
+            "owner": {"id": "owner-1", "tags": ["a", "b"]},
+            "counts": {"x": 1, "y": 2},
+        }
+        db.add_item(make_client(1, "k1", metadata=meta))
+        results = db.search_by_value("api_key", "k1")
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0].metadata, meta)
+
+    def test_metadata_non_ascii_round_trip(self):
+        db = make_db()
+        meta = {"name": "Zé Ninguém", "emoji": "🚀", "ru": "Привет"}
+        db.add_item(make_client(1, "k1", metadata=meta))
+        results = db.search_by_value("api_key", "k1")
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0].metadata, meta)
+
+    def test_metadata_survives_iteration(self):
+        db = make_db()
+        db.add_item(
+            make_client(
+                1,
+                "k1",
+                metadata={"owner_id": "owner-123"},
+            )
+        )
+
+        clients = list(db)
+
+        self.assertEqual(len(clients), 1)
+        self.assertEqual(clients[0].metadata, {"owner_id": "owner-123"})
+
+    def test_metadata_defaults_to_empty_dict_when_not_provided(self):
+        db = make_db()
+        db.add_item(make_client(1, "k1"))
+        results = db.search_by_value("api_key", "k1")
+        self.assertEqual(results[0].metadata, {})
+
+    def test_metadata_overwritten_on_reinsert_with_same_client_id(self):
+        db = make_db()
+        db.add_item(make_client(1, "k1", metadata={"v": 1}))
+        db.add_item(make_client(1, "k1", metadata={"v": 2, "extra": "x"}))
+        results = db.search_by_value("api_key", "k1")
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0].metadata, {"v": 2, "extra": "x"})
+
+    def test_metadata_to_json_returns_empty_for_non_dict(self):
+        self.assertEqual(SQLiteDB._metadata_to_json("not a dict"), "{}")
+        self.assertEqual(SQLiteDB._metadata_to_json(None), "{}")
+        self.assertEqual(SQLiteDB._metadata_to_json(42), "{}")
+
+    def test_metadata_from_row_returns_empty_for_garbage_or_missing(self):
+        db = make_db()
+        # legacy-style row with explicit NULL metadata
+        db.add_item(make_client(1, "k1"))
+        with db.conn:
+            db.conn.execute("UPDATE clients SET metadata = NULL WHERE client_id = 1")
+        results = db.search_by_value("api_key", "k1")
+        self.assertEqual(results[0].metadata, {})
+        # garbage JSON in the metadata column → coerce to {}
+        with db.conn:
+            db.conn.execute("UPDATE clients SET metadata = 'not json{' WHERE client_id = 1")
+        results = db.search_by_value("api_key", "k1")
+        self.assertEqual(results[0].metadata, {})
+        # valid JSON but not an object → coerce to {}
+        with db.conn:
+            db.conn.execute("UPDATE clients SET metadata = '[1,2,3]' WHERE client_id = 1")
+        results = db.search_by_value("api_key", "k1")
+        self.assertEqual(results[0].metadata, {})
+
+    def test_full_client_fields_preserved(self):
+        db = make_db()
+        c = make_client(
+            client_id=42,
+            api_key="full-key",
+            name="test-client",
+            description="a test",
+            is_admin=False,
+            last_seen=1234567890.0,
+            intent_blacklist=["a:b"],
+            skill_blacklist=["c:d"],
+            message_blacklist=["e:f"],
+            allowed_types=["recognizer_loop:utterance"],
+            crypto_key="1234567890123456",
+            password="secret",
+            can_broadcast=True,
+            can_escalate=False,
+            can_propagate=True,
+            metadata={"owner_id": "owner-123"},
+        )
+        db.add_item(c)
+        results = db.search_by_value("api_key", "full-key")
+        self.assertEqual(len(results), 1)
+        r = results[0]
+        self.assertEqual(r.client_id, 42)
+        self.assertEqual(r.name, "test-client")
+        self.assertEqual(r.description, "a test")
+        self.assertFalse(r.is_admin)
+        self.assertEqual(r.last_seen, 1234567890.0)
+        self.assertEqual(r.crypto_key, "1234567890123456")
+        self.assertEqual(r.password, "secret")
+        self.assertFalse(r.can_escalate)
+        self.assertEqual(r.metadata, {"owner_id": "owner-123"})
+
+
+class TestSQLiteDBCommit(unittest.TestCase):
+    def test_commit_returns_true(self):
+        db = make_db()
+        self.assertTrue(db.commit())
+
+    def test_commit_returns_false_on_error(self):
+        db = make_db()
+        db.conn.close()
+        result = db.commit()
+        self.assertFalse(result)
+
+
+class TestSQLiteDBUpdateAndReplace(unittest.TestCase):
+    def test_update_item_changes_fields(self):
+        db = make_db()
+        db.add_item(make_client(1, "k1", name="old"))
+        updated = make_client(1, "k1", name="new")
+        db.update_item(updated)
+        results = db.search_by_value("name", "new")
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0].name, "new")
+
+    def test_replace_item(self):
+        db = make_db()
+        old = make_client(1, "old-key")
+        new = make_client(2, "new-key")
+        db.add_item(old)
+        db.replace_item(old, new)
+        self.assertEqual(db.search_by_value("api_key", "new-key")[0].client_id, 2)
+        # old entry is revoked, not gone
+        self.assertEqual(db.search_by_value("api_key", "revoked")[0].client_id, 1)
+
+
+try:
+    import sqlcipher3 as _sqlcipher3  # noqa: F401
+    _SQLCIPHER_AVAILABLE = True
+except ImportError:
+    _SQLCIPHER_AVAILABLE = False
+
+
+@unittest.skipUnless(_SQLCIPHER_AVAILABLE, "sqlcipher3 not installed")
+class TestSQLiteDBEncrypted(unittest.TestCase):
+    """Tests for the SQLCipher-encrypted path.  Skipped when sqlcipher3 is absent."""
+
+    def _make_encrypted_db(self, path: str, password: str = "hunter2") -> SQLiteDB:
+        import unittest.mock as mock
+        db = SQLiteDB.__new__(SQLiteDB)
+        db.name = os.path.splitext(os.path.basename(path))[0]
+        db.subfolder = ""
+        db.password = password
+        with mock.patch(
+            "hivemind_sqlite_database.xdg_data_home",
+            return_value=os.path.dirname(path),
+        ):
+            db.__post_init__()
+        return db
+
+    def test_encrypted_file_unreadable_by_stdlib_sqlite3(self):
+        """A file created with a password must be opaque to plain sqlite3."""
+        with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+            path = f.name
+        os.unlink(path)
+        try:
+            db = self._make_encrypted_db(path, password="secret123")
+            db.add_item(make_client(1, "enc-key"))
+            db.commit()
+            # stdlib sqlite3 should not be able to read it
+            plain_conn = sqlite3.connect(path)
+            with self.assertRaises(sqlite3.DatabaseError):
+                plain_conn.execute("SELECT * FROM clients").fetchall()
+            plain_conn.close()
+        finally:
+            if os.path.exists(path):
+                os.unlink(path)
+
+    def test_encrypted_round_trip(self):
+        """add_item then search_by_value works through the encryption layer."""
+        with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+            path = f.name
+        os.unlink(path)
+        try:
+            db = self._make_encrypted_db(path, password="roundtrip")
+            db.add_item(make_client(1, "enc-api-key", name="alice"))
+            db.commit()
+            # Reopen with same password
+            db2 = self._make_encrypted_db(path, password="roundtrip")
+            results = db2.search_by_value("api_key", "enc-api-key")
+            self.assertEqual(len(results), 1)
+            self.assertEqual(results[0].name, "alice")
+        finally:
+            if os.path.exists(path):
+                os.unlink(path)
+
+    def test_sqlitedb_password_kwarg_raises_importerror_without_sqlcipher3(self):
+        """Confirmed separately in test_sqlitedb_no_sqlcipher.py; skip here."""
+        pass
+
+
+class TestSQLiteDBMissingCipher(unittest.TestCase):
+    """Verify ImportError is raised when sqlcipher3 is absent and password is given."""
+
+    def test_importerror_when_sqlcipher3_missing(self):
+        import sys
+        import unittest.mock as mock
+
+        # Simulate sqlcipher3 not being installed
+        with mock.patch.dict(sys.modules, {"sqlcipher3": None}):
+            with tempfile.TemporaryDirectory() as tmpdir:
+                with self.assertRaises(ImportError) as ctx:
+                    db = SQLiteDB.__new__(SQLiteDB)
+                    db.name = "test"
+                    db.subfolder = tmpdir
+                    db.password = "secret"
+                    # Patch xdg_data_home so db_path resolves inside tmpdir
+                    with mock.patch("hivemind_sqlite_database.xdg_data_home",
+                                    return_value=tmpdir):
+                        db.__post_init__()
+                self.assertIn("sqlcipher3", str(ctx.exception))
+
+
+if __name__ == "__main__":
+    unittest.main()

hivemind-sqlite-database-0.0.3a1/PKG-INFO

@@ -1,10 +0,0 @@
-Metadata-Version: 1.0
-Name: hivemind-sqlite-database
-Version: 0.0.3a1
-Summary: sqlite database plugin for hivemind-core
-Home-page: https://github.com/JarbasHiveMind/hivemind-sqlite-database
-Author: jarbasAi
-Author-email: jarbasai@mailfence.com
-License: Apache-2.0
-Description: UNKNOWN
-Platform: UNKNOWN

hivemind-sqlite-database-0.0.3a1/README.md

@@ -1 +0,0 @@
-# HiveMind SQLite Database

hivemind-sqlite-database-0.0.3a1/hivemind_sqlite_database/__init__.py

@@ -1,155 +0,0 @@
-import json
-import os.path
-import sqlite3
-from typing import List, Union, Iterable
-
-from ovos_utils.log import LOG
-from ovos_utils.xdg_utils import xdg_data_home
-
-from hivemind_plugin_manager.database import Client, AbstractDB
-
-from dataclasses import dataclass
-
-
-@dataclass
-class SQLiteDB(AbstractDB):
-    """Database implementation using SQLite."""
-    name: str = "clients"
-    subfolder: str = "hivemind-core"
-
-    def __post_init__(self):
-        """
-        Initialize the SQLiteDB connection.
-        """
-        db_path = os.path.join(xdg_data_home(), self.subfolder, self.name + ".db")
-        LOG.debug(f"sqlite database path: {db_path}")
-        os.makedirs(os.path.dirname(db_path), exist_ok=True)
-
-        self.conn = sqlite3.connect(db_path)
-        self.conn.row_factory = sqlite3.Row
-        self._initialize_database()
-
-    def _initialize_database(self):
-        """Initialize the database schema."""
-        with self.conn:
-            # crypto key is always 16 chars
-            # name description and api_key shouldnt be allowed to go over 255
-            self.conn.execute("""
-                CREATE TABLE IF NOT EXISTS clients (
-                    client_id INTEGER PRIMARY KEY,
-                    api_key VARCHAR(255) NOT NULL,
-                    name VARCHAR(255),
-                    description VARCHAR(255),
-                    is_admin BOOLEAN DEFAULT FALSE,
-                    last_seen REAL DEFAULT -1,
-                    intent_blacklist TEXT,
-                    skill_blacklist TEXT,
-                    message_blacklist TEXT,
-                    allowed_types TEXT,
-                    crypto_key VARCHAR(16),
-                    password TEXT,
-                    can_broadcast BOOLEAN DEFAULT TRUE,
-                    can_escalate BOOLEAN DEFAULT TRUE,
-                    can_propagate BOOLEAN DEFAULT TRUE
-                )
-            """)
-
-    def add_item(self, client: Client) -> bool:
-        """
-        Add a client to the SQLite database.
-
-        Args:
-            client: The client to be added.
-
-        Returns:
-            True if the addition was successful, False otherwise.
-        """
-        try:
-            with self.conn:
-                self.conn.execute("""
-                    INSERT OR REPLACE INTO clients (
-                        client_id, api_key, name, description, is_admin,
-                        last_seen, intent_blacklist, skill_blacklist,
-                        message_blacklist, allowed_types, crypto_key, password,
-                        can_broadcast, can_escalate, can_propagate
-                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                """, (
-                    client.client_id, client.api_key, client.name, client.description,
-                    client.is_admin, client.last_seen,
-                    json.dumps(client.intent_blacklist),
-                    json.dumps(client.skill_blacklist),
-                    json.dumps(client.message_blacklist),
-                    json.dumps(client.allowed_types),
-                    client.crypto_key, client.password,
-                    client.can_broadcast, client.can_escalate, client.can_propagate
-                ))
-            return True
-        except sqlite3.Error as e:
-            LOG.error(f"Failed to add client to SQLite: {e}")
-            return False
-
-    def search_by_value(self, key: str, val: Union[str, bool, int, float]) -> List[Client]:
-        """
-        Search for clients by a specific key-value pair in the SQLite database.
-
-        Args:
-            key: The key to search by.
-            val: The value to search for.
-
-        Returns:
-            A list of clients that match the search criteria.
-        """
-        try:
-            with self.conn:
-                cur = self.conn.execute(f"SELECT * FROM clients WHERE {key} = ?", (val,))
-                rows = cur.fetchall()
-                return [self._row_to_client(row) for row in rows]
-        except sqlite3.Error as e:
-            LOG.error(f"Failed to search clients in SQLite: {e}")
-            return []
-
-    def __len__(self) -> int:
-        """Get the number of clients in the database."""
-        cur = self.conn.execute("SELECT COUNT(*) FROM clients")
-        return cur.fetchone()[0]
-
-    def __iter__(self) -> Iterable['Client']:
-        """
-        Iterate over all clients in the SQLite database.
-
-        Returns:
-            An iterator over the clients in the database.
-        """
-        cur = self.conn.execute("SELECT * FROM clients")
-        for row in cur:
-            yield self._row_to_client(row)
-
-    def commit(self) -> bool:
-        """Commit changes to the SQLite database."""
-        try:
-            self.conn.commit()
-            return True
-        except sqlite3.Error as e:
-            LOG.error(f"Failed to commit SQLite database: {e}")
-            return False
-
-    @staticmethod
-    def _row_to_client(row: sqlite3.Row) -> Client:
-        """Convert a database row to a Client instance."""
-        return Client(
-            client_id=int(row["client_id"]),
-            api_key=row["api_key"],
-            name=row["name"],
-            description=row["description"],
-            is_admin=row["is_admin"] or False,
-            last_seen=row["last_seen"],
-            intent_blacklist=json.loads(row["intent_blacklist"] or "[]"),
-            skill_blacklist=json.loads(row["skill_blacklist"] or "[]"),
-            message_blacklist=json.loads(row["message_blacklist"] or "[]"),
-            allowed_types=json.loads(row["allowed_types"] or "[]"),
-            crypto_key=row["crypto_key"],
-            password=row["password"],
-            can_broadcast=row["can_broadcast"],
-            can_escalate=row["can_escalate"],
-            can_propagate=row["can_propagate"]
-        )

hivemind-sqlite-database-0.0.3a1/hivemind_sqlite_database/version.py

@@ -1,6 +0,0 @@
-# START_VERSION_BLOCK
-VERSION_MAJOR = 0
-VERSION_MINOR = 0
-VERSION_BUILD = 3
-VERSION_ALPHA = 1
-# END_VERSION_BLOCK

hivemind-sqlite-database-0.0.3a1/hivemind_sqlite_database.egg-info/PKG-INFO

@@ -1,10 +0,0 @@
-Metadata-Version: 1.0
-Name: hivemind-sqlite-database
-Version: 0.0.3a1
-Summary: sqlite database plugin for hivemind-core
-Home-page: https://github.com/JarbasHiveMind/hivemind-sqlite-database
-Author: jarbasAi
-Author-email: jarbasai@mailfence.com
-License: Apache-2.0
-Description: UNKNOWN
-Platform: UNKNOWN

hivemind-sqlite-database-0.0.3a1/hivemind_sqlite_database.egg-info/entry_points.txt

@@ -1,3 +0,0 @@
-[hivemind.database]
-hivemind-sqlite-db-plugin=hivemind_sqlite_database:SQLiteDB
-

hivemind-sqlite-database-0.0.3a1/hivemind_sqlite_database.egg-info/requires.txt

@@ -1 +0,0 @@
-hivemind-plugin-manager<1.0.0,>=0.1.0

hivemind-sqlite-database-0.0.3a1/setup.py

@@ -1,55 +0,0 @@
-import os
-from setuptools import setup
-
-BASEDIR = os.path.abspath(os.path.dirname(__file__))
-
-
-def get_version():
-    """ Find the version of the package"""
-    version_file = os.path.join(BASEDIR, 'hivemind_sqlite_database', 'version.py')
-    major, minor, build, alpha = (None, None, None, None)
-    with open(version_file) as f:
-        for line in f:
-            if 'VERSION_MAJOR' in line:
-                major = line.split('=')[1].strip()
-            elif 'VERSION_MINOR' in line:
-                minor = line.split('=')[1].strip()
-            elif 'VERSION_BUILD' in line:
-                build = line.split('=')[1].strip()
-            elif 'VERSION_ALPHA' in line:
-                alpha = line.split('=')[1].strip()
-
-            if ((major and minor and build and alpha) or
-                    '# END_VERSION_BLOCK' in line):
-                break
-    version = f"{major}.{minor}.{build}"
-    if int(alpha) > 0:
-        version += f"a{alpha}"
-    return version
-
-
-def required(requirements_file):
-    """ Read requirements file and remove comments and empty lines. """
-    with open(os.path.join(BASEDIR, requirements_file), 'r') as f:
-        requirements = f.read().splitlines()
-        if 'MYCROFT_LOOSE_REQUIREMENTS' in os.environ:
-            print('USING LOOSE REQUIREMENTS!')
-            requirements = [r.replace('==', '>=').replace('~=', '>=') for r in requirements]
-        return [pkg for pkg in requirements
-                if pkg.strip() and not pkg.startswith("#")]
-
-
-PLUGIN_ENTRY_POINT = 'hivemind-sqlite-db-plugin=hivemind_sqlite_database:SQLiteDB'
-
-setup(
-    name='hivemind-sqlite-database',
-    version=get_version(),
-    packages=['hivemind_sqlite_database'],
-    url='https://github.com/JarbasHiveMind/hivemind-sqlite-database',
-    license='Apache-2.0',
-    author='jarbasAi',
-    install_requires=required("requirements.txt"),
-    entry_points={'hivemind.database': PLUGIN_ENTRY_POINT},
-    author_email='jarbasai@mailfence.com',
-    description='sqlite database plugin for hivemind-core'
-)