pargo-auth 0.1.4__tar.gz → 0.1.6__tar.gz

pargo_auth-0.1.6/.github/workflows/deploy.yml

@@ -0,0 +1,54 @@
+name: Deploy Auth Service
+
+on:
+  push:
+    branches: [master, main, feature/auth]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup SSH
+        run: |
+          mkdir -p ~/.ssh
+          chmod 700 ~/.ssh
+          echo "${{ secrets.PARGO_SERVER_DEPLOY_KEY }}" > ~/.ssh/id_ed25519
+          chmod 600 ~/.ssh/id_ed25519
+          ssh-keyscan -H test.pargo.dk >> ~/.ssh/known_hosts
+
+      - name: Create directories
+        run: ssh thor@test.pargo.dk "mkdir -p /opt/pargo-auth"
+
+      - name: Deploy code
+        run: |
+          rsync -avz --delete \
+            --exclude '.git' \
+            --exclude '.github' \
+            --exclude '__pycache__' \
+            --exclude '*.pyc' \
+            --exclude '.env' \
+            --exclude 'dist' \
+            --exclude '*.egg-info' \
+            ./ thor@test.pargo.dk:/opt/pargo-auth/
+
+      - name: Build and restart container
+        run: |
+          ssh thor@test.pargo.dk "cd /opt/pargo-llm-compose && \
+            docker compose build --no-cache pargo-auth && \
+            docker compose up -d pargo-auth"
+
+      - name: Verify deployment
+        run: |
+          echo "=== Container status ==="
+          ssh thor@test.pargo.dk "docker ps | grep pargo-auth || true"
+          echo ""
+          echo "=== Recent logs ==="
+          sleep 5
+          ssh thor@test.pargo.dk "docker logs pargo-auth --tail 20 2>&1 || true"
+          echo ""
+          echo "=== Health check ==="
+          ssh thor@test.pargo.dk "curl -s http://localhost:8040/health || echo 'Health check pending...'"

pargo_auth-0.1.6/DOCUMENTATION/AUTH_SYSTEM.md

@@ -0,0 +1,195 @@
+# PARGO Authentication System
+
+This document describes the authentication architecture for PARGO applications.
+
+## Overview
+
+PARGO uses a hybrid authentication approach:
+- **Supabase Auth** (EU-hosted) handles identity/login (Google, Apple, Email/Password)
+- **pargo-auth service** validates JWTs and manages user data in our own Postgres
+- **User data** is stored in Hetzner Postgres, giving us full control
+
+## Architecture
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  Flutter    │────▶│  Supabase   │     │   Hetzner   │
+│    App      │     │    Auth     │     │  Postgres   │
+└─────────────┘     └─────────────┘     └─────────────┘
+       │                   │                   ▲
+       │                   │ JWT               │
+       │                   ▼                   │
+       │            ┌─────────────┐            │
+       └───────────▶│ pargo-auth  │────────────┘
+         API calls  │  service    │  user data
+                    └─────────────┘
+```
+
+## Components
+
+### 1. Supabase Auth (Identity Provider)
+- **URL**: `https://cmnowxzhwrskkixukyif.supabase.co`
+- **Purpose**: Handle login flows, issue JWTs
+- **Providers**: Email/Password, Google, Apple (pending)
+- **We use**: Only authentication, NOT Supabase database
+
+### 2. pargo-auth Service
+- **URL**: `https://prod.pargo.dk/auth/`
+- **Port**: 8040
+- **Purpose**: 
+  - Validate Supabase JWTs
+  - Provide user management API
+  - Store user data in our Postgres
+
+### 3. pargo-auth PyPI Package
+- **Package**: `pargo-auth` on PyPI
+- **Purpose**: JWT verification middleware for other PARGO backends
+- **Usage**: `pip install pargo-auth`
+
+## API Endpoints
+
+### pargo-auth Service
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| GET | `/health` | No | Health check |
+| GET | `/v1/me` | Yes | Get current user profile + settings |
+| PATCH | `/v1/me` | Yes | Update user profile |
+| PATCH | `/v1/me/settings` | Yes | Update user settings |
+
+### Supabase Auth (via SDK)
+
+| Action | SDK Method |
+|--------|------------|
+| Sign up | `supabase.auth.signUp()` |
+| Sign in (email) | `supabase.auth.signInWithPassword()` |
+| Sign in (Google) | `supabase.auth.signInWithOAuth(OAuthProvider.google)` |
+| Sign in (Apple) | `supabase.auth.signInWithOAuth(OAuthProvider.apple)` |
+| Sign out | `supabase.auth.signOut()` |
+| Refresh token | Automatic via SDK |
+
+## Database Schema
+
+User data is stored in Hetzner Postgres under the `auth` schema:
+
+```sql
+-- Main user table
+auth.users (
+    id              UUID PRIMARY KEY,
+    supabase_uid    TEXT UNIQUE NOT NULL,  -- Links to Supabase
+    email           TEXT,
+    email_verified  BOOLEAN,
+    display_name    TEXT,
+    avatar_url      TEXT,
+    preferred_lang  VARCHAR(5) DEFAULT 'da',
+    created_at      TIMESTAMPTZ,
+    updated_at      TIMESTAMPTZ,
+    last_login_at   TIMESTAMPTZ,
+    deleted_at      TIMESTAMPTZ            -- Soft delete
+)
+
+-- User settings
+auth.user_settings (
+    user_id         UUID PRIMARY KEY REFERENCES auth.users(id),
+    push_enabled    BOOLEAN DEFAULT TRUE,
+    email_enabled   BOOLEAN DEFAULT TRUE,
+    map_style       VARCHAR(20) DEFAULT 'standard',
+    settings_json   JSONB DEFAULT '{}'
+)
+
+-- Login providers (Google, Apple, etc.)
+auth.user_identities (
+    id              UUID PRIMARY KEY,
+    user_id         UUID REFERENCES auth.users(id),
+    provider        VARCHAR(50),           -- 'google', 'apple', 'email'
+    provider_uid    TEXT,
+    email           TEXT,
+    created_at      TIMESTAMPTZ
+)
+```
+
+## JWT Structure
+
+Supabase JWTs contain:
+
+```json
+{
+  "sub": "c2de269a-b357-4502-8efb-d92a463dda91",  // Supabase user ID
+  "email": "user@example.com",
+  "app_metadata": {
+    "provider": "google",
+    "providers": ["google"]
+  },
+  "user_metadata": {
+    "full_name": "John Doe",
+    "avatar_url": "https://..."
+  },
+  "exp": 1770096078,
+  "iat": 1770092478
+}
+```
+
+## Using pargo-auth in Other Services
+
+### Installation
+
+```bash
+pip install pargo-auth
+```
+
+### Required Auth
+
+```python
+from pargo_auth import SupabaseAuth, AuthenticatedUser
+from fastapi import Depends
+
+auth = SupabaseAuth()
+
+@app.get("/protected")
+async def protected_route(user: AuthenticatedUser = Depends(auth.get_user)):
+    return {"user_id": user.sub, "email": user.email}
+```
+
+### Optional Auth (for migration)
+
+```python
+@app.get("/public")
+async def public_route(user: AuthenticatedUser | None = Depends(auth.get_user_optional)):
+    if user:
+        return {"authenticated": True, "user_id": user.sub}
+    return {"authenticated": False}
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `SUPABASE_URL` | Supabase project URL | `https://xxx.supabase.co` |
+| `DATABASE_URL` | Postgres connection | `postgresql://user:pass@host:5432/db` |
+| `ENV` | Environment | `prod` or `test` |
+
+### Supabase Dashboard Settings
+
+- **Site URL**: `https://prod.pargo.dk`
+- **Redirect URLs**: `https://prod.pargo.dk/**`
+
+## Security Notes
+
+1. **JWTs are validated server-side** using Supabase's JWKS endpoint
+2. **Tokens expire after 1 hour** - the SDK handles refresh automatically
+3. **User data is in our control** - Supabase only stores auth credentials
+4. **Soft deletes** preserve data for potential recovery
+
+## Current Status
+
+| Provider | Status |
+|----------|--------|
+| Email/Password | ✅ Working |
+| Google OAuth | ✅ Working |
+| Apple Sign In | ⏳ Pending setup |
+
+---
+
+*Last updated: 2026-02-03*

pargo_auth-0.1.6/DOCUMENTATION/Plans/2026-02-03_apple-signin.md

@@ -0,0 +1,110 @@
+# Plan: Add Apple Sign In Support
+
+## Status: Pending
+
+Apple Sign In is required for iOS App Store compliance (any app with social login must offer Apple).
+
+## Prerequisites
+
+- [ ] Access to Apple Developer account
+- [ ] PARGO app already registered with App ID
+
+## Steps
+
+### 1. Create Services ID in Apple Developer Console
+
+1. Go to [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list)
+2. Click **+** → Select **Services IDs** → Continue
+3. Fill in:
+   - Description: `PARGO Auth`
+   - Identifier: `dk.pargo.auth`
+4. Click **Continue** → **Register**
+
+### 2. Configure Services ID for Sign In with Apple
+
+1. Click on the Services ID you created
+2. Enable **Sign In with Apple**
+3. Click **Configure**
+4. Set:
+   - Primary App ID: Your PARGO app
+   - Domains: `cmnowxzhwrskkixukyif.supabase.co`
+   - Return URLs: `https://cmnowxzhwrskkixukyif.supabase.co/auth/v1/callback`
+5. Click **Save** → **Continue** → **Save**
+
+### 3. Create a Key for Sign In with Apple
+
+1. Go to **Keys** in Apple Developer
+2. Click **+**
+3. Fill in:
+   - Name: `PARGO Supabase Auth`
+4. Enable **Sign In with Apple**
+5. Click **Configure** → Select your Primary App ID → **Save**
+6. Click **Continue** → **Register**
+7. **IMPORTANT**: Download the `.p8` key file immediately (one-time download!)
+8. Note the **Key ID** shown
+
+### 4. Gather Required Information
+
+You'll need these values for Supabase:
+
+| Item | Where to find it | Example |
+|------|------------------|---------|
+| Services ID | Step 1 identifier | `dk.pargo.auth` |
+| Team ID | Top-right of Apple Developer page | `ABC123XYZ` |
+| Key ID | Shown after creating key | `DEFG456` |
+| Private Key | Contents of `.p8` file | `-----BEGIN PRIVATE KEY-----...` |
+
+### 5. Configure Supabase
+
+1. Go to [Supabase Auth Providers](https://supabase.com/dashboard/project/cmnowxzhwrskkixukyif/auth/providers)
+2. Find **Apple** and enable it
+3. Enter:
+   - **Service ID**: `dk.pargo.auth`
+   - **Team ID**: (from Apple Developer)
+   - **Key ID**: (from step 3)
+   - **Private Key**: (paste entire `.p8` contents)
+4. Click **Save**
+
+### 6. Test Apple Sign In
+
+```bash
+# Open this URL in Safari (Apple Sign In works best in Safari)
+open "https://cmnowxzhwrskkixukyif.supabase.co/auth/v1/authorize?provider=apple&redirect_to=https://prod.pargo.dk/auth/v1/me"
+```
+
+### 7. Verify in Database
+
+```bash
+# Check user was created
+ssh thor@prod.pargo.dk "docker exec -i postgres-server psql -U postgres -d pargo_prod -c \"SELECT email, created_at FROM auth.users ORDER BY created_at DESC LIMIT 3;\""
+```
+
+## iOS App Configuration
+
+For native Apple Sign In in Flutter (recommended for better UX):
+
+1. In Xcode, enable **Sign In with Apple** capability
+2. Add to `ios/Runner/Runner.entitlements`:
+   ```xml
+   <key>com.apple.developer.applesignin</key>
+   <array>
+       <string>Default</string>
+   </array>
+   ```
+
+## Notes
+
+- Apple Sign In is **required** by App Store if you have any social login
+- Apple may hide user's real email (relay address like `xxx@privaterelay.appleid.com`)
+- First login returns user's name, subsequent logins may not - store it on first login
+- The `.p8` key file can only be downloaded ONCE - store it securely
+
+## Estimated Time
+
+- Apple Developer setup: 15-20 minutes
+- Supabase configuration: 5 minutes
+- Testing: 10 minutes
+
+---
+
+*Created: 2026-02-03*

pargo_auth-0.1.6/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: pargo-auth
+Version: 0.1.6
+Summary: Shared authentication middleware for PARGO backend services
+Project-URL: Homepage, https://github.com/pargoorg/pargo-auth
+Project-URL: Repository, https://github.com/pargoorg/pargo-auth
+Author-email: PARGO <dev@pargo.dk>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pyjwt>=2.8.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pargo-auth
+
+Authentication and user management for PARGO. This repo serves two purposes:
+
+1. **PyPI Package** (`pargo-auth`) - JWT verification middleware for FastAPI
+2. **User Service** - API for user profile and settings management
+
+## Architecture
+
+```
+pargo-auth/
+├── src/pargo_auth/          # Library (published to PyPI)
+│   ├── middleware.py        # Supabase JWT verification
+│   ├── models.py            # AuthenticatedUser dataclass
+│   └── exceptions.py        # Auth errors
+├── app/                     # Service (deployed to server)
+│   ├── main.py              # FastAPI application
+│   ├── routes/users.py      # /v1/me endpoints
+│   └── services/            # Database operations
+├── docker/Dockerfile        # Service container
+└── pyproject.toml           # Package configuration
+```
+
+---
+
+## Part 1: PyPI Package
+
+The `pargo-auth` package provides JWT verification for any PARGO backend.
+
+### Installation
+
+```bash
+pip install pargo-auth
+```
+
+### Usage
+
+```python
+from fastapi import Depends
+from pargo_auth import get_current_user, AuthenticatedUser
+
+@app.get("/protected")
+async def protected(user: AuthenticatedUser = Depends(get_current_user)):
+    return {"user_id": user.sub, "email": user.email}
+```
+
+### Configuration
+
+Set environment variables:
+
+```bash
+SUPABASE_URL=https://your-project.supabase.co
+ENV=local  # Skip verification in local dev
+```
+
+### AuthenticatedUser
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sub` | `str` | Supabase user ID (stable, canonical identity) |
+| `email` | `str \| None` | User's email |
+| `email_verified` | `bool` | Whether email is verified |
+| `supabase_uid` | `str` | Alias for `sub` |
+| `raw_claims` | `dict \| None` | Full JWT payload |
+
+### Optional Auth
+
+For endpoints that work with or without authentication:
+
+```python
+from pargo_auth import SupabaseAuth
+
+auth = SupabaseAuth()
+
+@app.get("/content")
+async def get_content(user: AuthenticatedUser | None = Depends(auth.get_user_optional)):
+    if user:
+        return {"personalized": True, "user": user.sub}
+    return {"personalized": False}
+```
+
+---
+
+## Part 2: User Service
+
+The service manages user data in Hetzner Postgres (`auth` schema).
+
+### Endpoints
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/v1/me` | Required | Get profile + settings (creates user on first call) |
+| PATCH | `/v1/me` | Required | Update profile |
+| PATCH | `/v1/me/settings` | Required | Update settings |
+| DELETE | `/v1/me` | Required | Soft delete account |
+| GET | `/health` | None | Health check |
+
+### Database Schema
+
+Uses the `auth` schema in Postgres:
+
+- `auth.users` - Core user identity (synced from Supabase JWT)
+- `auth.user_identities` - Login methods (apple, google, email)
+- `auth.user_settings` - App preferences
+- `auth.audit_events` - Security/login event log
+
+### Running Locally
+
+```bash
+# Install dependencies
+pip install -r requirements-service.txt
+pip install -e .
+
+# Set environment
+export SUPABASE_URL=https://your-project.supabase.co
+export DATABASE_URL=postgresql://postgres:password@localhost:5432/pargo_test
+export ENV=local
+
+# Run
+uvicorn app.main:app --reload --port 8040
+```
+
+### Docker
+
+```bash
+docker build -f docker/Dockerfile -t pargo-auth .
+docker run -p 8040:8040 \
+  -e SUPABASE_URL=https://your-project.supabase.co \
+  -e DATABASE_URL=postgresql://... \
+  pargo-auth
+```
+
+### Response Examples
+
+**GET /v1/me**
+
+```json
+{
+  "user": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "supabase_uid": "846eddd7-f5ae-4d72-8082-accde7da68f2",
+    "email": "user@example.com",
+    "email_verified": true,
+    "display_name": "John Doe",
+    "preferred_lang": "da",
+    "created_at": "2026-02-02T10:00:00Z",
+    "last_login_at": "2026-02-02T12:00:00Z"
+  },
+  "settings": {
+    "push_enabled": true,
+    "email_enabled": true,
+    "map_style": "standard",
+    "settings_json": {}
+  }
+}
+```
+
+---
+
+## Development
+
+### Package Development
+
+```bash
+# Install in editable mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+```
+
+### Publishing (automatic)
+
+Push to `main` triggers GitHub Actions:
+1. Bumps version
+2. Publishes to PyPI
+
+---
+
+## Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| `supabase_uid` is canonical ID | JWT `sub` is stable even if email changes |
+| User created on first `/me` call | No separate signup flow needed |
+| Soft delete | GDPR compliance, account recovery possible |
+| Separate settings table | Clean separation, flexible JSONB for future |