kinemotion 0.61.0__tar.gz → 0.62.0__tar.gz

kinemotion-0.62.0/.basic-memory/api/testing-backend-authentication-quick-reference.md

@@ -0,0 +1,158 @@
+---
+title: Testing Backend Authentication - Quick Reference
+type: note
+permalink: api/testing-backend-authentication-quick-reference
+---
+
+# Testing Backend Authentication
+
+## Backdoor Testing (No JWT Required)
+
+### Using curl
+
+```bash
+# Test /analyze endpoint with backdoor
+curl -X POST http://localhost:8000/api/analyze \
+  -H "x-test-password: your-test-password" \
+  -F "file=@video.mp4" \
+  -F "jump_type=cmj" \
+  -F "quality=balanced"
+
+# Test with debug video
+curl -X POST http://localhost:8000/api/analyze \
+  -H "x-test-password: your-test-password" \
+  -F "file=@video.mp4" \
+  -F "jump_type=cmj" \
+  -F "quality=balanced" \
+  -F "debug=true"
+```
+
+### Using Postman
+
+1. Method: `POST`
+2. URL: `http://localhost:8000/api/analyze`
+3. Headers tab:
+   - Add: `x-test-password: your-test-password`
+4. Body tab → form-data:
+   - `file` (type: File) → select video
+   - `jump_type` (type: Text) → `cmj` or `drop_jump`
+   - `quality` (type: Text) → `fast`, `balanced`, or `accurate`
+   - `debug` (type: Text, optional) → `true` or `false`
+
+### Setting Environment Variables
+
+**Local development** (`.env`):
+```bash
+TEST_PASSWORD=my-secret-testing-password
+TEST_USER_ID=test-user-00000000-0000-0000-0000-000000000000
+```
+
+**Cloud Run deployment** (via GitHub Actions or gcloud):
+```bash
+gcloud run services update kinemotion-backend \
+  --region us-central1 \
+  --set-env-vars TEST_PASSWORD=my-secret-password
+```
+
+---
+
+## Production Testing (With JWT)
+
+### Frontend Integration
+
+```typescript
+// 1. Get session after user logs in
+const { session } = useAuth()
+
+// 2. Use token in Authorization header
+const token = session?.access_token
+const response = await fetch(`${backendUrl}/api/analyze`, {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${token}`
+  },
+  body: formData
+})
+```
+
+### Testing with Personal JWT (Advanced)
+
+If you need to test without frontend:
+
+1. Log in to app via frontend
+2. Open browser DevTools Console
+3. Get your token:
+   ```javascript
+   const { data } = await supabase.auth.getSession()
+   console.log(data.session.access_token)
+   ```
+4. Use in curl:
+   ```bash
+   curl -X POST http://localhost:8000/api/analyze \
+     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
+     -F "file=@video.mp4" \
+     -F "jump_type=cmj"
+   ```
+
+---
+
+## Verifying User ID Organization in R2
+
+After successful upload, check R2 bucket:
+
+**Backdoor test** → Should be in:
+```
+uploads/test-user-00000000-0000-0000-0000-000000000000/2025/12/15/...
+```
+
+**Authenticated user** → Should be in:
+```
+uploads/{user_id}/2025/12/15/...
+```
+
+Where `{user_id}` is the Supabase user UUID.
+
+---
+
+## Troubleshooting
+
+### 401 Unauthorized (No backdoor)
+
+**Error**: `Authentication required`
+
+**Causes**:
+- Missing `Authorization` header
+- Invalid JWT token
+- Expired token
+- TEST_PASSWORD not configured
+
+**Solution**:
+- Provide valid JWT token, OR
+- Set TEST_PASSWORD env var and use `x-test-password` header
+
+### 403 Forbidden (Referer Check)
+
+**Error**: `Direct API access not allowed. Use the web interface.`
+
+**Causes**:
+- Missing Referer header
+- Referer from unauthorized origin
+
+**Solution**:
+- Use from frontend (referer set automatically), OR
+- Include `x-test-password` header to bypass (if TEST_PASSWORD set)
+
+### Files in anonymous/ folder
+
+**Cause**: Uploading with TEST_PASSWORD but not setting TEST_USER_ID
+
+**Solution**: Set TEST_USER_ID env var or use authenticated request
+
+---
+
+## Success Indicators
+
+✅ Response includes metrics and URLs (JSON 200)
+✅ Files in R2 under `uploads/{user_id}/...` not `anonymous/`
+✅ Can save feedback to `/api/analysis/sessions` with same auth
+✅ Logs show `user_id` in analysis started/completed entries

kinemotion-0.62.0/.basic-memory/project-management/backend-authentication-architecture-decision.md

@@ -0,0 +1,98 @@
+---
+title: Backend Authentication Architecture Decision
+type: note
+permalink: project-management/backend-authentication-architecture-decision
+---
+
+# Authentication Architecture Options for /analyze Endpoint
+
+## Current State
+- `/analyze` endpoint: **Public (no auth)** → files saved as `anonymous`
+- `/api/analysis/sessions` endpoint: **Requires auth** → 401 errors until SUPABASE_PUBLISHABLE_KEY was set
+- Issue: User IDs never passed to storage, so no user organization in R2
+
+## Option A: Add Authentication to /analyze
+Require JWT token for video analysis upload
+
+### Pros
+- User uploads immediately organized by user ID in R2 (no "anonymous" folder clutter)
+- Single consistent auth model across entire backend
+- Session ID returned from analysis is tied to authenticated user
+- Easier user management and analytics (know who uploaded what)
+- Prevents abuse (rate limiting per user instead of globally)
+- Better for compliance/auditing (track all user actions)
+
+### Cons
+- **Breaks existing workflow**: Frontend must authenticate BEFORE uploading video
+- Frontend must fetch auth token before making `/analyze` request
+- Adds latency to video upload (auth check required)
+- API less flexible (can't generate quick demos without login)
+- Complicates testing/development (need to authenticate first)
+- Reduces discoverability (users must login to try the feature)
+
+---
+
+## Option B: Keep /analyze Public, Return Session ID
+Keep video analysis public but return ephemeral session ID that can be claimed by authenticated user
+
+### Pros
+- **Zero friction user experience**: Upload video immediately without login
+- Users can try the feature without committing to account creation
+- Better for demos and marketing
+- Faster upload (no auth overhead)
+- Reduces initial friction to adoption
+- Guests can analyze videos without creating account
+- Optional: Can send session to email/link for later claiming
+
+### Cons
+- Files stay in `anonymous/` folder (harder to organize)
+- Session IDs need TTL (expire after N hours if not claimed)
+- Need migration logic to move anonymous sessions to user when they login
+- More complex database schema (sessions linked to either user_id or session_id)
+- Harder to enforce rate limiting (per IP instead of per user)
+- Anonymous sessions could fill up storage
+- Audit trail less complete (guest activities not tracked)
+- Two different storage paths to manage
+
+---
+
+## Option C: Both (Recommended)
+Offer both authenticated AND guest analysis
+
+### Pros
+- **Best UX**: Guests can try immediately, authenticated users get benefits
+- Maximizes adoption (low barrier to entry)
+- Users experience value before creating account
+- Authenticated users get proper tracking/organization
+- Can implement "upgrade" flow (guest → user)
+- Flexible for different use cases (demos, research, production)
+- Solves the "try before you buy" problem
+- Future monetization: Basic (guest) vs Premium (registered)
+
+### Cons
+- **Most complex**: Handle both auth and anonymous sessions
+- Two code paths to maintain and test
+- Database migration needed (sessions table needs optional user_id)
+- Storage organization more complicated (both `anonymous/` and `users/{id}/`)
+- Rate limiting needs dual strategy (per-IP for guests, per-user for authenticated)
+- More edge cases to handle and debug
+- Longer development timeline
+
+---
+
+## Recommendation Context
+
+**For MVP (current goal):**
+- Option B (guest-friendly) makes sense if you're trying to get product in coaches' hands quickly
+- Coaches can try without friction
+- You get immediate feedback on use cases
+
+**For Production (coaches paying):**
+- Option C (both) provides best UX
+- Coaches get analytics/tracking when they're part of org
+- Guests can demonstrate to team before purchasing
+
+**Current Blocker:**
+- Fix auth.py to use SUPABASE_PUBLISHABLE_KEY (DONE) ✅
+- This unblocks Option A or C immediately
+- Option B requires no backend changes (already works)

kinemotion-0.62.0/.basic-memory/project-management/backend-authentication-implementation-complete.md

@@ -0,0 +1,137 @@
+---
+title: Backend Authentication Implementation Complete
+type: note
+permalink: project-management/backend-authentication-implementation-complete
+---
+
+# Backend Authentication Implementation
+
+## Changes Made
+
+### 1. Fixed SupabaseAuth to Support Modern Supabase Keys ✅
+**File**: `backend/src/kinemotion_backend/auth.py`
+
+```python
+# Before: Only checked SUPABASE_ANON_KEY
+self.supabase_anon_key = os.getenv("SUPABASE_ANON_KEY", "")
+
+# After: Prefers modern keys, falls back to legacy
+self.supabase_anon_key = (
+    os.getenv("SUPABASE_PUBLISHABLE_KEY")
+    or os.getenv("SUPABASE_ANON_KEY")
+    or ""
+)
+```
+
+This fixes JWT token verification in the `/api/analysis/sessions` endpoint when using modern Supabase API key format (`sb_publishable_...`).
+
+---
+
+### 2. Added Authentication to /analyze Endpoint ✅
+**File**: `backend/src/kinemotion_backend/routes/analysis.py`
+
+- Requires JWT token in `Authorization: Bearer <token>` header
+- Extracts user_id from token
+- Passes user_id to storage service for proper R2 organization
+- **Backdoor for testing**: Accept `x-test-password` header to bypass auth
+
+**New helper function**:
+```python
+async def get_user_id_for_analysis(
+    credentials: HTTPAuthorizationCredentials | None = Depends(security),
+    x_test_password: str | None = Header(None),
+) -> str:
+    # If TEST_PASSWORD matches x-test-password header, use test user ID
+    # Otherwise validate JWT token
+    # Returns user_id in both cases
+```
+
+---
+
+### 3. Added Test Password Backdoor Utility ✅
+**File**: `backend/src/kinemotion_backend/services/validation.py`
+
+```python
+def is_test_password_valid(x_test_password: str | None = None) -> bool:
+    """Check if test password is valid (for debugging backdoor)."""
+    test_password = os.getenv("TEST_PASSWORD")
+    return bool(test_password and x_test_password == test_password)
+```
+
+This centralizes the backdoor check for reuse across endpoints.
+
+---
+
+## How the Authentication Flow Works
+
+### For Production (Authenticated Users)
+1. Frontend user logs in with Supabase auth
+2. Frontend gets JWT token from `session.access_token`
+3. Frontend includes `Authorization: Bearer <token>` header in POST to `/analyze`
+4. Backend validates token using SupabaseAuth
+5. Backend extracts user_id from token
+6. Uploads organized in R2 as `uploads/{user_id}/2025/12/15/...`
+
+### For Testing/Debugging (Backdoor)
+1. Set `TEST_PASSWORD` environment variable on backend
+2. Use curl or Postman with `x-test-password` header matching TEST_PASSWORD
+3. Backend bypasses JWT validation
+4. Uploads organized in R2 as `uploads/test-user-00000000-0000-0000-0000-000000000000/...` (or custom TEST_USER_ID)
+
+**Example curl**:
+```bash
+curl -X POST http://localhost:8000/api/analyze \
+  -H "x-test-password: my-secret-password" \
+  -F "file=@video.mp4" \
+  -F "jump_type=cmj" \
+  -F "quality=balanced"
+```
+
+---
+
+## Files Modified
+
+1. ✅ `backend/src/kinemotion_backend/auth.py` - Support modern Supabase keys
+2. ✅ `backend/src/kinemotion_backend/routes/analysis.py` - Add auth + backdoor
+3. ✅ `backend/src/kinemotion_backend/services/validation.py` - Add backdoor check utility
+4. ✅ `backend/src/kinemotion_backend/services/__init__.py` - Export backdoor utility
+
+---
+
+## Next Steps
+
+1. **Deploy to Cloud Run** with these environment variables:
+   - `SUPABASE_PUBLISHABLE_KEY` (already set)
+   - `SUPABASE_SECRET_KEY` (already set)
+   - `TEST_PASSWORD=your-secret-password` (for backdoor)
+   - `TEST_USER_ID=optional-custom-test-user-id` (defaults to test-user-...)
+
+2. **Update frontend** to send JWT token:
+   ```typescript
+   const token = session?.access_token
+   const response = await fetch(`${backendUrl}/api/analyze`, {
+     method: 'POST',
+     headers: {
+       'Authorization': `Bearer ${token}`
+     },
+     body: formData
+   })
+   ```
+
+3. **Test feedback submission** end-to-end:
+   - Upload video (authenticated)
+   - See upload organized by user_id in R2
+   - Save feedback (uses same auth)
+   - Verify both operations use authenticated user
+
+---
+
+## Architecture Decision
+
+✅ **Option A Selected**: Require authentication on both `/analyze` and `/api/analysis/sessions`
+
+- All user uploads immediately organized by user_id in R2
+- Single consistent auth model across all endpoints
+- Rate limiting per-user (not per-IP)
+- Full audit trail
+- Backdoor for testing/debugging without creating test accounts

{kinemotion-0.61.0 → kinemotion-0.62.0}/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## kinemotion-v0.62.0 (2025-12-15)
+
+### Feat
+
+- implement complete backend authentication with modern Supabase key support
+
+### Fix
+
+- use useAuth hook to get session token for feedback submission
+- use backend API URL for feedback submission
+- use environment variable for backend API URL in database status check
+
 ## kinemotion-v0.61.0 (2025-12-15)
 
 ### Feat

{kinemotion-0.61.0 → kinemotion-0.62.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.61.0
+Version: 0.62.0
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion

{kinemotion-0.61.0 → kinemotion-0.62.0}/backend/src/kinemotion_backend/auth.py

@@ -31,7 +31,10 @@ class SupabaseAuth:
     def __init__(self) -> None:
         """Initialize Supabase authentication."""
         self.supabase_url = os.getenv("SUPABASE_URL", "")
-        self.supabase_anon_key = os.getenv("SUPABASE_ANON_KEY", "")
+        # Prefer modern keys, fall back to legacy for compatibility
+        self.supabase_anon_key = (
+            os.getenv("SUPABASE_PUBLISHABLE_KEY") or os.getenv("SUPABASE_ANON_KEY") or ""
+        )
 
         if not self.supabase_url:
             raise ValueError("SUPABASE_URL must be set")

{kinemotion-0.61.0 → kinemotion-0.62.0}/backend/src/kinemotion_backend/database.py

@@ -3,6 +3,7 @@
 import os
 from typing import Any
 
+import httpx
 import structlog
 from supabase import Client, create_client
 
@@ -34,7 +35,11 @@ class DatabaseClient:
                 "SUPABASE_ANON_KEY, or SUPABASE_KEY"
             )
 
-        self.client: Client = create_client(self.supabase_url, self.supabase_key)
+        # Configure http client with timeout and verify settings to avoid deprecation warnings
+        http_client = httpx.Client(timeout=10.0, verify=True)
+        self.client: Client = create_client(
+            self.supabase_url, self.supabase_key, http_client=http_client
+        )
         logger.info("database_client_initialized", supabase_url=self.supabase_url)
 
     async def create_analysis_session(

{kinemotion-0.61.0 → kinemotion-0.62.0}/backend/src/kinemotion_backend/middleware.py

@@ -54,8 +54,8 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
         auth_header = request.headers.get("authorization")
         if auth_header and auth_header.startswith("Bearer ") and supabase_auth:
             token = auth_header.replace("Bearer ", "")
+            auth_start = time.time()
             try:
-                auth_start = time.time()
                 user_id = supabase_auth.get_user_id(token)
                 user_email = supabase_auth.get_user_email(token)
                 auth_duration_ms = (time.time() - auth_start) * 1000

{kinemotion-0.61.0 → kinemotion-0.62.0}/backend/src/kinemotion_backend/routes/analysis.py

@@ -1,8 +1,19 @@
 """Video analysis routes for kinemotion backend."""
 
+import os
 import time
 
-from fastapi import APIRouter, File, Form, Header, Request, UploadFile
+from fastapi import (
+    APIRouter,
+    Depends,
+    File,
+    Form,
+    Header,
+    HTTPException,
+    Request,
+    UploadFile,
+    status,
+)
 from fastapi.responses import JSONResponse
 
 try:
@@ -13,9 +24,10 @@ except ImportError:
     fastapi_limiter_available = False
     RateLimiter = None  # type: ignore[assignment]
 
+from ..auth import SupabaseAuth
 from ..logging_config import get_logger
 from ..models.responses import AnalysisResponse
-from ..services import AnalysisService, validate_referer
+from ..services import AnalysisService, is_test_password_valid, validate_referer
 from ..utils import NoOpLimiter
 
 logger = get_logger(__name__)
@@ -29,6 +41,51 @@ else:
     limiter = RateLimiter()  # type: ignore[operator]
 
 
+async def get_user_id_for_analysis(
+    request: Request,
+    x_test_password: str | None = Header(None),  # noqa: B008
+) -> str:
+    """Extract user ID from JWT token or use test backdoor.
+
+    Args:
+        request: HTTP request (to access Authorization header)
+        x_test_password: Optional test password for debugging
+
+    Returns:
+        User ID (from token or test backdoor)
+
+    Raises:
+        HTTPException: If authentication fails and test password not provided
+    """
+    # Allow bypass with test password (for curl testing, debugging)
+    if is_test_password_valid(x_test_password):
+        test_user_id = os.getenv("TEST_USER_ID", "test-user-00000000-0000-0000-0000-000000000000")
+        logger.info("analysis_test_password_used", user_id=test_user_id)
+        return test_user_id
+
+    # Otherwise require valid JWT token from Authorization header
+    auth_header = request.headers.get("authorization")
+    if not auth_header or not auth_header.startswith("Bearer "):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication required",
+        )
+
+    token = auth_header.replace("Bearer ", "")
+    try:
+        auth = SupabaseAuth()
+        user_id = auth.get_user_id(token)
+        return user_id
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("user_id_extraction_failed", error=str(e))
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid authentication credentials",
+        ) from e
+
+
 @router.post("/analyze")
 @limiter.limit("3/minute")
 async def analyze_video(
@@ -39,6 +96,7 @@ async def analyze_video(
     debug: str = Form("false"),  # noqa: B008
     referer: str | None = Header(None),  # noqa: B008
     x_test_password: str | None = Header(None),  # noqa: B008
+    user_id: str = Depends(get_user_id_for_analysis),  # noqa: B008
 ) -> JSONResponse:
     """Analyze video and return jump metrics.
 
@@ -46,17 +104,21 @@ async def analyze_video(
     - Drop Jump: Analyzes ground contact and flight time
     - CMJ: Analyzes jump height, countermovement depth, and phases
 
+    Requires authentication via JWT token in Authorization header, or TEST_PASSWORD
+    header for testing/debugging.
+
     Args:
         file: Video file to analyze (multipart/form-data)
         jump_type: Type of jump ("drop_jump" or "cmj")
         quality: Analysis quality preset ("fast", "balanced", or "accurate")
         debug: Debug overlay flag ("true" or "false", default "false")
+        user_id: Authenticated user ID (extracted from JWT or test password)
 
     Returns:
         JSON response with metrics or error details
 
     Raises:
-        HTTPException: If validation or processing fails
+        HTTPException: If authentication or processing fails
     """
     start_time = time.time()
 
@@ -76,6 +138,7 @@ async def analyze_video(
             jump_type=jump_type,
             quality=quality,
             debug=enable_debug,
+            user_id=user_id,
         )
 
         # Perform analysis using service layer
@@ -84,7 +147,7 @@ async def analyze_video(
             jump_type=jump_type,
             quality=quality,
             debug=enable_debug,
-            user_id=None,  # TODO: Extract from auth when available
+            user_id=user_id,
         )
 
         # Log analysis completion

{kinemotion-0.61.0 → kinemotion-0.62.0}/backend/src/kinemotion_backend/services/__init__.py

@@ -2,7 +2,12 @@
 
 from .analysis_service import AnalysisService
 from .storage_service import StorageService
-from .validation import validate_jump_type, validate_referer, validate_video_file
+from .validation import (
+    is_test_password_valid,
+    validate_jump_type,
+    validate_referer,
+    validate_video_file,
+)
 from .video_processor import VideoProcessorService
 
 __all__ = [
@@ -12,4 +17,5 @@ __all__ = [
     "validate_video_file",
     "validate_jump_type",
     "validate_referer",
+    "is_test_password_valid",
 ]

{kinemotion-0.61.0 → kinemotion-0.62.0}/backend/src/kinemotion_backend/services/validation.py

@@ -51,6 +51,19 @@ def validate_jump_type(jump_type: str) -> str:
     return normalized
 
 
+def is_test_password_valid(x_test_password: str | None = None) -> bool:
+    """Check if test password is valid (for debugging backdoor).
+
+    Args:
+        x_test_password: Optional test password header
+
+    Returns:
+        True if test password is configured and matches
+    """
+    test_password = os.getenv("TEST_PASSWORD")
+    return bool(test_password and x_test_password == test_password)
+
+
 def validate_referer(referer: str | None, x_test_password: str | None = None) -> None:
     """Validate request comes from authorized frontend.
 
@@ -66,8 +79,7 @@ def validate_referer(referer: str | None, x_test_password: str | None = None) ->
         return
 
     # Allow bypass with test password (for curl testing, debugging)
-    test_password = os.getenv("TEST_PASSWORD")
-    if test_password and x_test_password == test_password:
+    if is_test_password_valid(x_test_password):
         return  # Bypass referer check
 
     allowed_referers = [

{kinemotion-0.61.0 → kinemotion-0.62.0}/backend/tests/conftest.py

@@ -39,6 +39,9 @@ def setup_test_environment() -> None:
     os.environ["R2_BUCKET_NAME"] = "test-bucket"
     os.environ["SUPABASE_URL"] = "https://test.supabase.co"
     os.environ["SUPABASE_ANON_KEY"] = "test-anon-key"
+    # Test password for /analyze endpoint authentication bypass
+    os.environ["TEST_PASSWORD"] = "test-password-12345"
+    os.environ["TEST_USER_ID"] = "test-user-00000000-0000-0000-0000-000000000000"
 
     yield
 
@@ -51,6 +54,8 @@ def setup_test_environment() -> None:
         "R2_BUCKET_NAME",
         "SUPABASE_URL",
         "SUPABASE_ANON_KEY",
+        "TEST_PASSWORD",
+        "TEST_USER_ID",
     ]
     for key in env_vars:
         os.environ.pop(key, None)
@@ -126,8 +131,11 @@ def app() -> FastAPI:
 
 @pytest.fixture
 def client(app: FastAPI) -> TestClient:
-    """Test client for the FastAPI application."""
-    return TestClient(app)
+    """Test client for the FastAPI application with test authentication."""
+    test_client = TestClient(app)
+    # Add test password header to all requests for authentication bypass
+    test_client.headers["x-test-password"] = "test-password-12345"
+    return test_client
 
 
 @pytest.fixture