initial commit

API_SERVICE.md

@@ -0,0 +1,97 @@
+# Signature Validation API Service
+
+This is a lightweight Python service that provides signature validation for the PHP application.
+
+## Why a separate service?
+
+The `bibapi` library is Python-only and provides access to your library catalog. Rather than rewriting this in PHP, we keep a small Python service running just for signature validation.
+
+## Running the Service
+
+### Option 1: Direct Python
+```bash
+python api_service.py
+```
+
+### Option 2: With uvicorn
+```bash
+uvicorn api_service:app --host 0.0.0.0 --port 8001
+```
+
+### Option 3: Docker (if you can run containers internally)
+```dockerfile
+FROM python:3.13-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY api_service.py .
+EXPOSE 8001
+CMD ["uvicorn", "api_service:app", "--host", "0.0.0.0", "--port", "8001"]
+```
+
+```bash
+docker build -t signature-api .
+docker run -d -p 8001:8001 signature-api
+```
+
+## Configuration
+
+Set the API endpoint in your PHP config. Update `php/config.php`:
+
+```php
+// Signature validation API endpoint (optional)
+define('SIGNATURE_API_URL', getenv('SIGNATURE_API_URL') ?: 'http://localhost:8001');
+```
+
+## Testing
+
+```bash
+# Health check
+curl http://localhost:8001/health
+
+# Validate a signature
+curl "http://localhost:8001/api/validate-signature?signature=ABC123"
+```
+
+## Production Deployment
+
+1. **Same server**: Run on a different port (8001) alongside your PHP application
+2. **Separate server**: Run on internal network, update `SIGNATURE_API_URL` in PHP config
+3. **Systemd service** (Linux):
+
+Create `/etc/systemd/system/signature-api.service`:
+```ini
+[Unit]
+Description=Signature Validation API
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+WorkingDirectory=/var/www/signature-api
+Environment="PATH=/var/www/signature-api/.venv/bin"
+ExecStart=/var/www/signature-api/.venv/bin/uvicorn api_service:app --host 0.0.0.0 --port 8001
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Then:
+```bash
+sudo systemctl enable signature-api
+sudo systemctl start signature-api
+```
+
+## Security
+
+- In production, update CORS `allow_origins` to only your PHP server domain
+- Consider adding API key authentication if exposed to public network
+- Run behind reverse proxy (nginx/Apache) with SSL
+
+## Notes
+
+- The service is stateless and lightweight
+- No data persistence required
+- Can be scaled horizontally if needed
+- Falls back gracefully if unavailable (ELSA form fields just won't have validation hints)