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

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

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

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

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

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

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

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

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.