kinemotion 0.61.0__tar.gz → 0.63.0__tar.gz

kinemotion-0.63.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.63.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.63.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.63.0}/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## kinemotion-v0.63.0 (2025-12-15)
+
+### Feat
+
+- use email as unique identifier for users and storage organization
+
+### Fix
+
+- enhance database debugging with detailed connection logging
+- revert httpx client configuration that broke Supabase compatibility
+
+## 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.63.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.61.0
+Version: 0.63.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.63.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.63.0}/backend/src/kinemotion_backend/database.py

@@ -17,11 +17,14 @@ class DatabaseClient:
         self.supabase_url = os.getenv("SUPABASE_URL", "")
 
         # Prefer modern keys, fall back to legacy for compatibility
+        # Check which key source is being used for debugging
+        supabase_publishable_key = os.getenv("SUPABASE_PUBLISHABLE_KEY")
+        supabase_secret_key = os.getenv("SUPABASE_SECRET_KEY")
+        supabase_anon_key = os.getenv("SUPABASE_ANON_KEY")
+        supabase_key = os.getenv("SUPABASE_KEY")
+
         self.supabase_key = (
-            os.getenv("SUPABASE_PUBLISHABLE_KEY")
-            or os.getenv("SUPABASE_SECRET_KEY")
-            or os.getenv("SUPABASE_ANON_KEY")
-            or os.getenv("SUPABASE_KEY")
+            supabase_publishable_key or supabase_secret_key or supabase_anon_key or supabase_key
         )
 
         if not self.supabase_url:
@@ -34,8 +37,23 @@ class DatabaseClient:
                 "SUPABASE_ANON_KEY, or SUPABASE_KEY"
             )
 
+        # Log which key source is being used (without exposing the actual key)
+        key_source = "unknown"
+        if supabase_publishable_key:
+            key_source = "SUPABASE_PUBLISHABLE_KEY"
+        elif supabase_secret_key:
+            key_source = "SUPABASE_SECRET_KEY"
+        elif supabase_anon_key:
+            key_source = "SUPABASE_ANON_KEY"
+        elif supabase_key:
+            key_source = "SUPABASE_KEY"
+
         self.client: Client = create_client(self.supabase_url, self.supabase_key)
-        logger.info("database_client_initialized", supabase_url=self.supabase_url)
+        logger.info(
+            "database_client_initialized",
+            supabase_url=self.supabase_url,
+            key_source=key_source,
+        )
 
     async def create_analysis_session(
         self,

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

@@ -50,28 +50,26 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
             client_ip=request.client.host if request.client else "unknown",
         )
 
-        # Extract and validate user ID from Authorization header
+        # Extract and validate user email from Authorization header
         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
 
-                # Bind user info to logging context (auth_duration_ms only in auth event)
+                # Bind user email to logging context
                 structlog.contextvars.bind_contextvars(
-                    user_id=user_id,
-                    user_email=user_email,
+                    email=user_email,
                 )
 
                 # Store in request state for use in endpoints
-                request.state.user_id = user_id
-                request.state.user_email = user_email
+                request.state.email = user_email
 
                 logger.info(
                     "user_authenticated",
+                    email=user_email,
                     auth_duration_ms=round(auth_duration_ms, 2),
                 )
             except Exception as e:

{kinemotion-0.61.0 → kinemotion-0.63.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_email_for_analysis(
+    request: Request,
+    x_test_password: str | None = Header(None),  # noqa: B008
+) -> str:
+    """Extract user email 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 email (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_email = os.getenv("TEST_EMAIL", "test@example.com")
+        logger.info("analysis_test_password_used", email=test_email)
+        return test_email
+
+    # 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()
+        email = auth.get_user_email(token)
+        return email
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("user_email_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
+    email: str = Depends(get_user_email_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")
+        email: Authenticated user email (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,
+            email=email,
         )
 
         # 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=email,
         )
 
         # Log analysis completion

{kinemotion-0.61.0 → kinemotion-0.63.0}/backend/src/kinemotion_backend/routes/health.py

@@ -35,11 +35,23 @@ async def health_check() -> dict[str, str | bool]:
         from kinemotion_backend.database import get_database_client
 
         db_client = get_database_client()
-        # Test database with a simple query
-        db_client.client.table("analysis_sessions").select("id").limit(1).execute()
+        # Try to access analysis_sessions table with select limit to test connectivity
+        # This will return data if accessible, or raise if table doesn't exist or RLS blocks it
+        response = db_client.client.table("analysis_sessions").select("id").limit(1).execute()
+        # If we get here, the database connection worked
+        # Note: response.data could be empty if table is empty, but that's still success
         database_connected = True
+        logger.info(
+            "database_health_check_succeeded",
+            rows_returned=len(response.data or []),
+        )
     except Exception as db_error:
-        logger.warning("database_health_check_failed", error=str(db_error))
+        logger.warning(
+            "database_health_check_failed",
+            error=str(db_error),
+            error_type=type(db_error).__name__,
+            exc_info=True,
+        )
 
     return {
         "status": "healthy",