keys-for-all/docs/VUKeyWebPortal.md

# VU Key Web Portal

## Overview

Web application for users to manage their VoiceUwu keys - login, view purchases, share keys with others, donate keys, and purchase additional keys. This is the customer-facing portal that complements the keyserver backend.

## Core Features

### 1. User Authentication
- Email/password login
- OAuth integration (Google, Apple Sign-In)
- Password reset functionality
- Account creation during first purchase

### 2. Key Management Dashboard
- View all owned keys
- Key activation status
- Purchase history with receipts
- Key expiration dates (if applicable)

### 3. Key Sharing
- Share keys with specific email addresses
- Generate shareable links with expiration
- Revoke shared access
- View who has access to shared keys

### 4. Key Donation
- Donate keys to community pool
- Specify donation conditions (regions, user types)
- View donation history and impact
- Anonymous donation options

### 5. Key Purchasing
- Browse available key packages
- Stripe and PayPal checkout integration
- Bulk purchase discounts
- Gift key purchases for others

## User Flows

### Login Flow
1. User visits portal
2. Login with email/password or OAuth
3. Redirect to dashboard
4. Auto-sync keys from keyserver

### Key Management Flow
1. Dashboard shows all owned keys
2. Click key to view details (purchase date, platform, status)
3. Options to share, donate, or view usage

### Key Sharing Flow
1. Select key to share
2. Enter recipient email or generate link
3. Set sharing permissions and expiration
4. Recipient gets notification/link
5. Shared key appears in recipient's dashboard

### Key Donation Flow
1. Select keys to donate
2. Choose donation type (community pool, specific criteria)
3. Confirm donation
4. Keys transferred to donation system
5. Donation receipt and impact tracking

### Purchase Flow
1. Browse key packages
2. Select quantity and type
3. Stripe/PayPal checkout
4. Payment processed via keyserver
5. Keys immediately available in dashboard

## API Endpoints

### Authentication
```
POST /auth/login                 # Email/password login
POST /auth/oauth/google          # Google OAuth
POST /auth/oauth/apple           # Apple Sign-In
POST /auth/register              # Create account
POST /auth/reset-password        # Password reset
POST /auth/logout                # Logout
```

### User Management
```
GET  /user/profile               # Get user profile
PUT  /user/profile               # Update profile
GET  /user/keys                  # Get user's keys
GET  /user/purchases             # Purchase history
```

### Key Operations
```
POST /keys/share                 # Share key with user
POST /keys/share/link            # Generate shareable link
DELETE /keys/share/:id           # Revoke sharing
GET  /keys/shared-with-me        # Keys shared with user
POST /keys/donate                # Donate keys
GET  /keys/donations             # Donation history
```

### Purchasing
```
GET  /store/packages             # Available key packages
POST /store/purchase/stripe      # Purchase with Stripe
POST /store/purchase/paypal      # Purchase with PayPal
POST /store/gift                 # Gift keys to others
```

## Database Schema

### Users Table
```sql
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255),
    google_id VARCHAR(255),
    apple_id VARCHAR(255),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
```

### User Keys Table
```sql
CREATE TABLE user_keys (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    key_id VARCHAR(255) NOT NULL,
    purchase_platform VARCHAR(50),
    purchase_transaction VARCHAR(255),
    purchased_at TIMESTAMP DEFAULT NOW(),
    expires_at TIMESTAMP,
    status VARCHAR(20) DEFAULT 'active'
);
```

### Key Shares Table
```sql
CREATE TABLE key_shares (
    id SERIAL PRIMARY KEY,
    key_id VARCHAR(255) NOT NULL,
    owner_id INTEGER REFERENCES users(id),
    shared_with_id INTEGER REFERENCES users(id),
    shared_with_email VARCHAR(255),
    share_link_token VARCHAR(255),
    expires_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW(),
    revoked_at TIMESTAMP
);
```

### Key Donations Table
```sql
CREATE TABLE key_donations (
    id SERIAL PRIMARY KEY,
    key_id VARCHAR(255) NOT NULL,
    donor_id INTEGER REFERENCES users(id),
    donation_type VARCHAR(50),
    criteria JSONB,
    donated_at TIMESTAMP DEFAULT NOW(),
    claimed_by INTEGER REFERENCES users(id),
    claimed_at TIMESTAMP
);
```

## Frontend Components

### Dashboard Component
```typescript
interface DashboardProps {
    user: User;
    keys: UserKey[];
    purchases: Purchase[];
}

function Dashboard({ user, keys, purchases }: DashboardProps) {
    return (
        <div className="dashboard">
            <KeySummary keys={keys} />
            <RecentPurchases purchases={purchases} />
            <QuickActions />
        </div>
    );
}
```

### Key Management Component
```typescript
interface KeyCardProps {
    key: UserKey;
    onShare: (keyId: string) => void;
    onDonate: (keyId: string) => void;
}

function KeyCard({ key, onShare, onDonate }: KeyCardProps) {
    return (
        <div className="key-card">
            <KeyDetails key={key} />
            <KeyActions 
                onShare={() => onShare(key.id)}
                onDonate={() => onDonate(key.id)}
            />
        </div>
    );
}
```

### Sharing Modal Component
```typescript
interface ShareModalProps {
    keyId: string;
    onShare: (email: string, expiration?: Date) => void;
    onGenerateLink: (expiration?: Date) => void;
}

function ShareModal({ keyId, onShare, onGenerateLink }: ShareModalProps) {
    return (
        <Modal>
            <ShareByEmail onSubmit={onShare} />
            <ShareByLink onGenerate={onGenerateLink} />
        </Modal>
    );
}
```

### Purchase Component
```typescript
interface PurchaseFormProps {
    packages: KeyPackage[];
    onPurchase: (packageId: string, quantity: number) => void;
}

function PurchaseForm({ packages, onPurchase }: PurchaseFormProps) {
    return (
        <div className="purchase-form">
            <PackageSelector packages={packages} />
            <PaymentMethods />
            <CheckoutButton onClick={onPurchase} />
        </div>
    );
}
```

## Security Features

### Authentication
- JWT tokens for session management
- Secure password hashing (bcrypt)
- OAuth token validation
- Rate limiting on auth endpoints

### Authorization
- User can only access their own keys
- Sharing permissions validated
- Donation permissions verified
- Purchase ownership confirmed

### Data Protection
- HTTPS everywhere
- Input validation and sanitization
- SQL injection prevention
- XSS protection
- CSRF tokens

## Integration with Keyserver

### Sync Process
1. User logs into web portal
2. Portal calls keyserver to get user's keys
3. Keys displayed in dashboard
4. Any portal actions (share/donate) update keyserver
5. Mobile apps sync from keyserver

### Purchase Integration
1. User completes payment in portal
2. Portal calls keyserver purchase endpoint
3. Keyserver validates payment and generates keys
4. Keys immediately available across all platforms

## Deployment Requirements

### Frontend (React/Next.js)
- Static site deployment (Vercel, Netlify)
- Environment variables for API URLs
- OAuth client credentials

### Backend (Node.js/Express)
- Database connection (PostgreSQL)
- Redis for session storage
- Stripe/PayPal API keys
- OAuth app credentials
- JWT secret keys

### Infrastructure
- CDN for static assets
- Database backups
- SSL certificates
- Monitoring and logging

## Development Workflow

1. **Setup**: Clone repo, install dependencies
2. **Database**: Run migrations, seed test data
3. **Environment**: Configure OAuth and payment APIs
4. **Development**: Start dev servers (frontend + backend)
5. **Testing**: Unit tests, integration tests, E2E tests
6. **Deployment**: CI/CD pipeline to staging/production

## Minimal MVP Features

For initial release, prioritize:

1. **Email login** (skip OAuth initially)
2. **Key dashboard** (view only)
3. **Basic sharing** (email-based)
4. **Simple donation** (community pool)
5. **Stripe purchase** (skip PayPal initially)

Advanced features (sharing links, expiration, gift purchases) can be added post-MVP.