vecforge 0.2.0__py3-none-any.whl

vecforge/security/encryption.py

@@ -0,0 +1,84 @@
+# VecForge — Universal Local-First Vector Database
+# Copyright (c) 2026 Suneel Bose K · ArcGX TechLabs Private Limited
+# Built by Suneel Bose K (Founder & CEO, ArcGX TechLabs)
+#
+# Licensed under the Business Source License 1.1 (BSL 1.1)
+# Free for personal, research, open-source, and non-commercial use.
+# Commercial use requires a separate license from ArcGX TechLabs.
+# See LICENSE file in the project root or contact: suneelbose@arcgx.in
+
+"""
+SQLCipher AES-256 key management for VecForge.
+
+Handles encryption key validation, SQLCipher PRAGMA setup, and
+graceful fallback when SQLCipher C library is not available.
+
+Built by Suneel Bose K · ArcGX TechLabs Private Limited.
+"""
+
+from __future__ import annotations
+
+import logging
+import warnings
+
+logger = logging.getLogger(__name__)
+
+
+def check_sqlcipher_available() -> bool:
+    """Check if SQLCipher is available on this system.
+
+    Returns:
+        True if sqlcipher3 can be imported, False otherwise.
+
+    Performance:
+        Time: O(1)
+    """
+    try:
+        import sqlcipher3  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+def validate_encryption_key(key: str | None) -> str | None:
+    """Validate and normalize an encryption key.
+
+    Args:
+        key: User-provided encryption key or None.
+
+    Returns:
+        Validated key string, or None if no encryption.
+
+    Raises:
+        ValueError: If key is empty or too short.
+
+    Performance:
+        Time: O(1)
+
+    Example:
+        >>> validate_encryption_key("my-secure-key-here")
+        'my-secure-key-here'
+        >>> validate_encryption_key("")
+        ValueError: Encryption key must be at least 8 characters...
+    """
+    if key is None:
+        return None
+
+    if not key or len(key) < 8:
+        raise ValueError(
+            "Encryption key must be at least 8 characters long.\n"
+            "Use a strong key: os.environ['VECFORGE_KEY']\n"
+            "VecForge by Suneel Bose K · ArcGX TechLabs — docs: vecforge.arcgx.in"
+        )
+
+    if not check_sqlcipher_available():
+        warnings.warn(
+            "SQLCipher is not installed — data will NOT be encrypted.\n"
+            "Install sqlcipher3 for AES-256 encryption: pip install sqlcipher3\n"
+            "VecForge by Suneel Bose K · ArcGX TechLabs",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    return key

vecforge/security/namespaces.py

@@ -0,0 +1,127 @@
+# VecForge — Universal Local-First Vector Database
+# Copyright (c) 2026 Suneel Bose K · ArcGX TechLabs Private Limited
+# Built by Suneel Bose K (Founder & CEO, ArcGX TechLabs)
+#
+# Licensed under the Business Source License 1.1 (BSL 1.1)
+# Free for personal, research, open-source, and non-commercial use.
+# Commercial use requires a separate license from ArcGX TechLabs.
+# See LICENSE file in the project root or contact: suneelbose@arcgx.in
+
+"""
+Multi-tenant namespace isolation for VecForge.
+
+Ensures that data operations are always scoped to a namespace,
+preventing cross-tenant data leaks.
+
+Built by Suneel Bose K · ArcGX TechLabs Private Limited.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from vecforge.core.storage import StorageBackend
+from vecforge.exceptions import NamespaceNotFoundError
+
+logger = logging.getLogger(__name__)
+
+
+class NamespaceManager:
+    """Multi-tenant namespace manager.
+
+    Every data operation flows through the namespace manager to
+    guarantee tenant isolation. The 'default' namespace always exists.
+
+    Built by Suneel Bose K · ArcGX TechLabs Private Limited.
+
+    Args:
+        storage: StorageBackend instance.
+
+    Performance:
+        Namespace check: O(1) with cached list
+        Create/list: O(K) where K = number of namespaces
+
+    Example:
+        >>> nsm = NamespaceManager(storage)
+        >>> nsm.create("ward_7")
+        >>> nsm.validate("ward_7")  # OK
+        >>> nsm.validate("ward_99")  # raises NamespaceNotFoundError
+    """
+
+    def __init__(self, storage: StorageBackend) -> None:
+        self._storage = storage
+        self._cache: set[str] | None = None
+
+    def _refresh_cache(self) -> None:
+        """Refresh the namespace cache from storage.
+
+        Performance:
+            Time: O(K) where K = number of namespaces
+        """
+        self._cache = set(self._storage.list_namespaces())
+
+    def validate(self, namespace: str) -> None:
+        """Validate that a namespace exists.
+
+        Args:
+            namespace: Namespace name to validate.
+
+        Raises:
+            NamespaceNotFoundError: If namespace does not exist.
+
+        Performance:
+            Time: O(1) with cache
+        """
+        if self._cache is None:
+            self._refresh_cache()
+
+        assert self._cache is not None
+        if namespace not in self._cache:
+            # why: Refresh cache in case namespace was created elsewhere
+            self._refresh_cache()
+            if namespace not in self._cache:
+                raise NamespaceNotFoundError(namespace, sorted(self._cache))
+
+    def create(self, name: str) -> None:
+        """Create a new namespace.
+
+        Args:
+            name: Namespace name.
+
+        Performance:
+            Time: O(1)
+        """
+        self._storage.create_namespace(name)
+        if self._cache is not None:
+            self._cache.add(name)
+        logger.info("Created namespace: %s", name)
+
+    def list_all(self) -> list[str]:
+        """List all namespace names.
+
+        Returns:
+            Sorted list of namespace names.
+
+        Performance:
+            Time: O(K log K)
+        """
+        self._refresh_cache()
+        assert self._cache is not None
+        return sorted(self._cache)
+
+    def exists(self, namespace: str) -> bool:
+        """Check if a namespace exists.
+
+        Args:
+            namespace: Namespace name.
+
+        Returns:
+            True if namespace exists.
+
+        Performance:
+            Time: O(1) with cache
+        """
+        if self._cache is None:
+            self._refresh_cache()
+        assert self._cache is not None
+        return namespace in self._cache

vecforge/security/rbac.py

@@ -0,0 +1,172 @@
+# VecForge — Universal Local-First Vector Database
+# Copyright (c) 2026 Suneel Bose K · ArcGX TechLabs Private Limited
+# Built by Suneel Bose K (Founder & CEO, ArcGX TechLabs)
+#
+# Licensed under the Business Source License 1.1 (BSL 1.1)
+# Free for personal, research, open-source, and non-commercial use.
+# Commercial use requires a separate license from ArcGX TechLabs.
+# See LICENSE file in the project root or contact: suneelbose@arcgx.in
+
+"""
+Role-based access control (RBAC) for VecForge.
+
+Provides API key → role mapping with permission enforcement.
+Every write operation must check permissions before executing.
+
+Built by Suneel Bose K · ArcGX TechLabs Private Limited.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from vecforge.exceptions import VecForgePermissionError
+
+logger = logging.getLogger(__name__)
+
+# security: Role hierarchy — higher roles inherit all lower permissions
+_ROLE_PERMISSIONS: dict[str, set[str]] = {
+    "admin": {"read", "write", "delete", "create_namespace", "manage_keys", "backup"},
+    "read-write": {"read", "write", "delete"},
+    "read-only": {"read"},
+}
+
+# why: Default role when no API key is provided — full access for local use
+_DEFAULT_ROLE = "admin"
+
+
+class RBACManager:
+    """Role-based access control manager.
+
+    Maps API keys to roles and enforces permission checks. When no
+    API key is provided, defaults to admin role (local-first trust).
+
+    Built by Suneel Bose K · ArcGX TechLabs Private Limited.
+
+    Args:
+        api_key: Current user's API key. None = local admin.
+        key_roles: Mapping of API key → role name.
+
+    Performance:
+        Permission check: O(1)
+
+    Example:
+        >>> rbac = RBACManager(api_key="key123", key_roles={"key123": "read-only"})
+        >>> rbac.require("read")   # OK
+        >>> rbac.require("write")  # raises VecForgePermissionError
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        key_roles: dict[str, str] | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._key_roles = key_roles or {}
+        self._current_role = self._resolve_role()
+
+    def _resolve_role(self) -> str:
+        """Resolve the current user's role from their API key.
+
+        Returns:
+            Role name string.
+
+        Performance:
+            Time: O(1)
+        """
+        if self._api_key is None:
+            # why: No API key = local use = admin privileges
+            return _DEFAULT_ROLE
+
+        role = self._key_roles.get(self._api_key, "read-only")
+        if role not in _ROLE_PERMISSIONS:
+            logger.warning(
+                "Unknown role '%s' for key '%s' — defaulting to read-only",
+                role,
+                self._api_key[:8] + "...",
+            )
+            role = "read-only"
+
+        return role
+
+    @property
+    def current_role(self) -> str:
+        """Return the current user's role.
+
+        Performance:
+            Time: O(1)
+        """
+        return self._current_role
+
+    @property
+    def key_id(self) -> str:
+        """Return a safe identifier for the current key (for audit logs).
+
+        Performance:
+            Time: O(1)
+        """
+        if self._api_key is None:
+            return "local-admin"
+        # security: Never log full API keys
+        return self._api_key[:8] + "..." if len(self._api_key) > 8 else "***"
+
+    def require(self, permission: str) -> None:
+        """Check if current role has the required permission.
+
+        Args:
+            permission: Required permission (read, write, delete, etc.).
+
+        Raises:
+            VecForgePermissionError: If current role lacks the permission.
+
+        Performance:
+            Time: O(1)
+
+        Example:
+            >>> rbac.require("write")  # raises if read-only
+        """
+        permissions = _ROLE_PERMISSIONS.get(self._current_role, set())
+        if permission not in permissions:
+            raise VecForgePermissionError(permission, self._current_role)
+
+    def has_permission(self, permission: str) -> bool:
+        """Check if current role has a permission without raising.
+
+        Args:
+            permission: Permission to check.
+
+        Returns:
+            True if permission is granted, False otherwise.
+
+        Performance:
+            Time: O(1)
+        """
+        permissions = _ROLE_PERMISSIONS.get(self._current_role, set())
+        return permission in permissions
+
+    def register_key(self, api_key: str, role: str) -> None:
+        """Register a new API key with a role.
+
+        Args:
+            api_key: The API key to register.
+            role: Role to assign (admin, read-write, read-only).
+
+        Raises:
+            VecForgePermissionError: If current user is not admin.
+            ValueError: If role is not valid.
+
+        Performance:
+            Time: O(1)
+        """
+        # security: Only admins can register new keys
+        self.require("manage_keys")
+
+        if role not in _ROLE_PERMISSIONS:
+            raise ValueError(
+                f"Invalid role '{role}'.\n"
+                f"Valid roles: {', '.join(_ROLE_PERMISSIONS.keys())}\n"
+                f"VecForge by Suneel Bose K · ArcGX TechLabs"
+            )
+
+        self._key_roles[api_key] = role
+        logger.info("Registered key %s... with role '%s'", api_key[:8], role)

vecforge/security/snapshots.py

@@ -0,0 +1,135 @@
+# VecForge — Universal Local-First Vector Database
+# Copyright (c) 2026 Suneel Bose K · ArcGX TechLabs Private Limited
+# Built by Suneel Bose K (Founder & CEO, ArcGX TechLabs)
+#
+# Licensed under the Business Source License 1.1 (BSL 1.1)
+# Free for personal, research, open-source, and non-commercial use.
+# Commercial use requires a separate license from ArcGX TechLabs.
+# See LICENSE file in the project root or contact: suneelbose@arcgx.in
+
+"""
+Backup and restore snapshots for VecForge vaults.
+
+Creates complete vault snapshots preserving encryption state and
+all data. Supports point-in-time recovery.
+
+Built by Suneel Bose K · ArcGX TechLabs Private Limited.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import time
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class SnapshotManager:
+    """Vault backup and restore manager.
+
+    Creates full snapshots of the vault database file. Encryption
+    state is preserved — encrypted vaults remain encrypted in snapshots.
+
+    Built by Suneel Bose K · ArcGX TechLabs Private Limited.
+
+    Args:
+        vault_path: Path to the vault database file.
+
+    Performance:
+        Snapshot: O(file_size) — full file copy
+        Restore: O(file_size) — full file copy
+
+    Example:
+        >>> snap = SnapshotManager("my_vault.db")
+        >>> snap.create_snapshot("backups/")
+        'backups/my_vault_20240101_120000.db'
+        >>> snap.restore_snapshot("backups/my_vault_20240101_120000.db")
+    """
+
+    def __init__(self, vault_path: str) -> None:
+        self._vault_path = Path(vault_path)
+
+    def create_snapshot(self, backup_dir: str) -> str:
+        """Create a timestamped snapshot of the vault.
+
+        Args:
+            backup_dir: Directory to store the snapshot file.
+
+        Returns:
+            Path to the created snapshot file.
+
+        Raises:
+            FileNotFoundError: If vault file does not exist.
+
+        Performance:
+            Time: O(file_size)
+        """
+        if not self._vault_path.exists():
+            raise FileNotFoundError(
+                f"Vault file not found: {self._vault_path}\n"
+                f"VecForge by Suneel Bose K · ArcGX TechLabs"
+            )
+
+        backup_path = Path(backup_dir)
+        backup_path.mkdir(parents=True, exist_ok=True)
+
+        timestamp = time.strftime("%Y%m%d_%H%M%S")
+        stem = self._vault_path.stem
+        suffix = self._vault_path.suffix
+        snapshot_name = f"{stem}_{timestamp}{suffix}"
+        snapshot_path = backup_path / snapshot_name
+
+        shutil.copy2(str(self._vault_path), str(snapshot_path))
+        logger.info("Snapshot created: %s", snapshot_path)
+
+        return str(snapshot_path)
+
+    def restore_snapshot(self, snapshot_path: str) -> None:
+        """Restore vault from a snapshot.
+
+        Args:
+            snapshot_path: Path to the snapshot file to restore.
+
+        Raises:
+            FileNotFoundError: If snapshot file does not exist.
+
+        Performance:
+            Time: O(file_size)
+        """
+        source = Path(snapshot_path)
+        if not source.exists():
+            raise FileNotFoundError(
+                f"Snapshot file not found: {snapshot_path}\n"
+                f"VecForge by Suneel Bose K · ArcGX TechLabs"
+            )
+
+        shutil.copy2(str(source), str(self._vault_path))
+        logger.info("Vault restored from: %s", snapshot_path)
+
+    def list_snapshots(self, backup_dir: str) -> list[str]:
+        """List available snapshots in a backup directory.
+
+        Args:
+            backup_dir: Directory containing snapshots.
+
+        Returns:
+            Sorted list of snapshot file paths (newest first).
+
+        Performance:
+            Time: O(S log S) where S = number of snapshots
+        """
+        backup_path = Path(backup_dir)
+        if not backup_path.exists():
+            return []
+
+        stem = self._vault_path.stem
+        suffix = self._vault_path.suffix
+        pattern = f"{stem}_*{suffix}"
+
+        snapshots = sorted(
+            [str(p) for p in backup_path.glob(pattern)],
+            reverse=True,
+        )
+        return snapshots

vecforge/server/__init__.py

@@ -0,0 +1,3 @@
+# VecForge — Universal Local-First Vector Database
+# Copyright (c) 2026 Suneel Bose K · ArcGX TechLabs Private Limited
+# Licensed under BSL 1.1 — see LICENSE for details.

vecforge/server/app.py

@@ -0,0 +1,54 @@
+# VecForge — Universal Local-First Vector Database
+# Copyright (c) 2026 Suneel Bose K · ArcGX TechLabs Private Limited
+# Built by Suneel Bose K (Founder & CEO, ArcGX TechLabs)
+#
+# Licensed under the Business Source License 1.1 (BSL 1.1)
+# Free for personal, research, open-source, and non-commercial use.
+# Commercial use requires a separate license from ArcGX TechLabs.
+# See LICENSE file in the project root or contact: suneelbose@arcgx.in
+
+"""
+FastAPI REST server for VecForge.
+
+Provides a REST API for vault operations. Designed for local-first
+deployment — no cloud dependency required.
+
+Built by Suneel Bose K · ArcGX TechLabs Private Limited.
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from vecforge.server.routes import create_router
+
+
+def create_app(vault_path: str = ":memory:") -> FastAPI:
+    """Create the FastAPI application.
+
+    Args:
+        vault_path: Path to the vault database.
+
+    Returns:
+        FastAPI application instance.
+
+    Example:
+        >>> app = create_app("my_vault.db")
+        >>> # Run with: uvicorn vecforge.server.app:app
+    """
+    app = FastAPI(
+        title="VecForge API",
+        description=(
+            "VecForge — Universal Local-First Vector Database REST API.\n\n"
+            "Built by Suneel Bose K · ArcGX TechLabs Private Limited.\n"
+            "Licensed under BSL 1.1."
+        ),
+        version="0.2.0",
+        docs_url="/docs",
+        redoc_url="/redoc",
+    )
+
+    router = create_router(vault_path)
+    app.include_router(router)
+
+    return app