feat(security): implement security and error handling improvements

* Add input validation for table names, dimensions, and other parameters
* Create custom exception classes for better error handling
* Enhance error messages for clarity and user guidance
* Implement validation utilities for consistent input checks
* Update methods to raise appropriate exceptions on validation failures
* Add comprehensive tests for security features and error handling

Author: atasoglu

SECURITY_IMPROVEMENTS.md

@@ -0,0 +1,126 @@
+# Security & Stability Improvements
+
+This document summarizes the critical security and stability improvements made to sqlite-vec-client.
+
+## Completed Tasks
+
+### Security Enhancements
+
+#### 1. SQL Injection Prevention
+- **Table Name Validation**: Added strict validation for table names using regex pattern `^[a-zA-Z_][a-zA-Z0-9_]*$`
+- **Prevents**: SQL injection attacks through malicious table names
+- **Implementation**: `validation.py::validate_table_name()`
+
+#### 2. Input Validation
+Added comprehensive validation for all user inputs:
+- **Dimension validation**: Must be positive integer
+- **top_k validation**: Must be positive integer
+- **limit validation**: Must be positive integer
+- **offset validation**: Must be non-negative integer
+- **List length matching**: Ensures texts, embeddings, and metadata lists have matching lengths
+
+### Error Handling Improvements
+
+#### 1. Custom Exception Classes
+Created a hierarchy of custom exceptions in `exceptions.py`:
+- `VecClientError`: Base exception for all client errors
+- `ValidationError`: Input validation failures
+- `TableNameError`: Invalid table name errors
+- `TableNotFoundError`: Missing table errors
+- `ConnectionError`: Database connection failures
+- `DimensionMismatchError`: Embedding dimension mismatches
+
+#### 2. Enhanced Error Messages
+All exceptions now provide clear, actionable error messages:
+- Explains what went wrong
+- Suggests how to fix the issue
+- Includes relevant context (e.g., expected vs actual values)
+
+#### 3. Exception Handling in Public Methods
+Added try-catch blocks to all critical operations:
+- `create_connection()`: Catches connection and extension loading errors
+- `similarity_search()`: Catches table not found errors
+- `add()`: Catches table not found errors
+- All methods validate inputs before execution
+
+## New Files
+
+1. **sqlite_vec_client/exceptions.py**: Custom exception classes
+2. **sqlite_vec_client/validation.py**: Input validation utilities
+3. **test_security.py**: Security test suite
+
+## Modified Files
+
+1. **sqlite_vec_client/base.py**:
+   - Added validation calls to all public methods
+   - Enhanced error handling with try-catch blocks
+   - Improved docstrings with Args, Returns, and Raises sections
+
+2. **sqlite_vec_client/__init__.py**:
+   - Exported all custom exceptions for public use
+
+3. **sqlite_vec_client/utils.py**:
+   - Updated to use f-string format specifiers (code quality improvement)
+
+## Testing
+
+Created `test_security.py` with comprehensive tests:
+- Table name validation (including SQL injection attempts)
+- Input parameter validation
+- Table not found error handling
+
+All tests pass successfully.
+
+## Code Quality
+
+- ✅ All code passes `mypy` type checking
+- ✅ All code passes `ruff` linting
+- ✅ Code formatted with `ruff format`
+- ✅ Compatible with Python 3.9+
+
+## Usage Examples
+
+### Catching Specific Exceptions
+
+```python
+from sqlite_vec_client import (
+    SQLiteVecClient,
+    TableNameError,
+    ValidationError,
+    TableNotFoundError,
+)
+
+# Handle invalid table name
+try:
+    client = SQLiteVecClient(table="invalid-name", db_path="db.db")
+except TableNameError as e:
+    print(f"Invalid table name: {e}")
+
+# Handle validation errors
+try:
+    client = SQLiteVecClient(table="docs", db_path="db.db")
+    client.create_table(dim=-1)  # Invalid dimension
+except ValidationError as e:
+    print(f"Validation error: {e}")
+
+# Handle missing table
+try:
+    client = SQLiteVecClient(table="docs", db_path="db.db")
+    client.similarity_search(embedding=[0.1, 0.2, 0.3])
+except TableNotFoundError as e:
+    print(f"Table not found: {e}")
+```
+
+## Security Best Practices
+
+1. **Always validate user input**: All table names and parameters are now validated
+2. **Use parameterized queries**: All SQL queries use `?` placeholders (already implemented)
+3. **Clear error messages**: Users get helpful feedback without exposing internals
+4. **Fail fast**: Invalid inputs are rejected immediately before any database operations
+
+## Next Steps
+
+With the Critical Priority section complete, the project is now ready for:
+- High Priority: Test Suite expansion
+- High Priority: Example scripts
+- High Priority: Documentation improvements

TODO

@@ -3,15 +3,15 @@
 ## 🔴 Critical Priority (Security & Stability)
 
 ### Security
-- [ ] Fix SQL injection vulnerability (table name sanitization)
-- [ ] Add table name validation (alphanumeric and underscore only)
-- [ ] Add input validation (dim, top_k, limit, etc.)
+- [x] Fix SQL injection vulnerability (table name sanitization)
+- [x] Add table name validation (alphanumeric and underscore only)
+- [x] Add input validation (dim, top_k, limit, etc.)
 
 ### Error Handling
-- [ ] Create custom exception classes (VecClientError, TableNotFoundError, etc.)
-- [ ] Add exception handling to all public methods
-- [ ] Write user-friendly error messages
-- [ ] Improve connection error handling
+- [x] Create custom exception classes (VecClientError, TableNotFoundError, etc.)
+- [x] Add exception handling to all public methods
+- [x] Write user-friendly error messages
+- [x] Improve connection error handling
 
 ## 🟡 High Priority (Quality & Reliability)
 

sqlite_vec_client/__init__.py

@@ -4,5 +4,21 @@
 """
 
 from .base import SQLiteVecClient
+from .exceptions import (
+    ConnectionError,
+    DimensionMismatchError,
+    TableNameError,
+    TableNotFoundError,
+    ValidationError,
+    VecClientError,
+)
 
-__all__ = ["SQLiteVecClient"]
+__all__ = [
+    "SQLiteVecClient",
+    "VecClientError",
+    "ValidationError",
+    "TableNameError",
+    "TableNotFoundError",
+    "ConnectionError",
+    "DimensionMismatchError",
+]