moxie-backend/README.md

# Moxie Backend

Express.js backend API for user management of an AI site, built with ESM syntax, Auth0 authentication, and SQLite database.

## Features

- **Auth0 Authentication**: Secure authentication via Auth0
- **User Management**: Auto-creation of users on first login, profile management
- **Credit System**: Track and manage user credits
- **API Keys**: Generate and manage API keys for programmatic access
- **Payment Webhooks**: Ready for Stripe and PayPal integration
- **Admin Endpoints**: User management for administrators
- **SQLite Database**: Lightweight, file-based storage

## Quick Start

```bash
# Install dependencies
npm install

# Copy environment file and configure
cp .env.example .env
# Edit .env with your Auth0 credentials

# Start the server
npm start

# Start in development mode (with auto-reload)
npm run dev
```

The server runs on port 9991 by default.

## Auth0 Setup

### 1. Create Auth0 Application

1. Go to Auth0 Dashboard > Applications > Applications
2. Create a new "Single Page Application" or "Regular Web Application"
3. Configure the following URLs:
   - **Allowed Callback URLs**: `https://moxiegen.client.guacamolebox.net/api/callback`
   - **Allowed Logout URLs**: `https://moxiegen.client.guacamolebox.net`
   - **Allowed Web Origins**: `https://moxiegen.client.guacamolebox.net`
   - **Application Login URI**: `https://moxiegen.client.guacamolebox.net/login`

### 2. Create Auth0 API (Optional)

For machine-to-machine authentication:
1. Go to Auth0 Dashboard > Applications > APIs
2. Create a new API
3. Set the identifier as your audience
4. Enable RBAC if needed

### 3. Configure Environment Variables

```env
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret
AUTH0_AUDIENCE=https://your-tenant.auth0.com/api/v2/
APP_URL=https://moxiegen.client.guacamolebox.net
```

## API Endpoints

### Auth Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/login` | Redirect to Auth0 login |
| GET | `/api/callback` | Handle Auth0 callback |
| GET | `/api/logout` | Logout and redirect |

### User Endpoints (Requires Auth0 Token)

All authenticated endpoints require `Authorization: Bearer <access_token>` header.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/users/me` | Get current user profile |
| PUT | `/api/users/me` | Update profile |
| DELETE | `/api/users/me` | Deactivate account |
| GET | `/api/users/credits` | Get credits and history |
| GET | `/api/users/api-keys` | List API keys |
| POST | `/api/users/api-keys` | Create new API key |
| DELETE | `/api/users/api-keys/:keyId` | Revoke API key |

### Admin Endpoints (Requires `role: 'admin'`)

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/users` | List all users |
| GET | `/api/users/:userId` | Get user by ID |
| PUT | `/api/users/:userId` | Update user |
| DELETE | `/api/users/:userId` | Delete user |
| POST | `/api/users/:userId/credits` | Adjust user credits |
| PUT | `/api/users/:userId/role` | Change user role |

### Webhook Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/webhooks/stripe` | Stripe webhook handler |
| POST | `/api/webhooks/paypal` | PayPal webhook handler |

## Frontend Integration

### Login Flow

```javascript
// Redirect to Auth0 login
window.location.href = '/api/login';

// Handle callback (tokens in URL params)
const urlParams = new URLSearchParams(window.location.search);
const accessToken = urlParams.get('access_token');
const idToken = urlParams.get('id_token');

// Store token and use for API calls
localStorage.setItem('access_token', accessToken);

// Make authenticated requests
fetch('/api/users/me', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});
```

### Using Auth0 SPA SDK

```javascript
import { Auth0Client } from '@auth0/auth0-spa-js';

const auth0 = new Auth0Client({
  domain: 'your-tenant.auth0.com',
  client_id: 'your-client-id',
  redirect_uri: window.location.origin
});

// Login
await auth0.loginWithRedirect();

// Get token
const token = await auth0.getTokenSilently();

// Use token
fetch('/api/users/me', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});
```

## Database Schema

### Users Table
- `id` - Primary key (UUID)
- `auth0_id` - Auth0 user ID (sub claim)
- `email` - Email address
- `name` - Display name
- `picture` - Profile picture URL
- `role` - User role ('user' or 'admin')
- `credits` - Available credits
- `subscription_status` - Subscription state
- `subscription_tier` - Subscription level
- `stripe_customer_id` - Stripe customer reference
- `paypal_customer_id` - PayPal customer reference
- `is_active` - Account status flag

### API Keys Table
- `id` - Key ID
- `user_id` - Foreign key to users
- `key_hash` - Hashed API key
- `name` - Key name/description
- `is_active` - Key status

### Credit Transactions Table
- `id` - Transaction ID
- `user_id` - Foreign key to users
- `amount` - Credit amount (+/-)
- `type` - 'credit' or 'debit'
- `description` - Transaction description

### Payments Table
- `id` - Payment ID
- `user_id` - Foreign key to users
- `amount` - Payment amount
- `provider` - 'stripe' or 'paypal'
- `status` - Payment status

## Caddy Configuration

```caddyfile
moxiegen.client.guacamolebox.net {
    # Static site
    root * /path/to/static/site
    file_server
    
    # API proxy
    handle /api/* {
        reverse_proxy localhost:9991
    }
}
```

## Making a User Admin

To promote a user to admin role:

1. Find the user ID from the database
2. Use the admin API (requires an existing admin)
3. Or directly update the database:

```sql
UPDATE users SET role = 'admin' WHERE email = 'admin@example.com';
```

## Payment Integration

### Stripe Setup

1. Create a Stripe account and get API keys
2. Add keys to environment variables
3. Create a webhook endpoint in Stripe dashboard pointing to `https://moxiegen.client.guacamolebox.net/api/webhooks/stripe`
4. Copy the webhook signing secret to `STRIPE_WEBHOOK_SECRET`

### PayPal Setup

1. Create a PayPal Developer account
2. Create a REST API application
3. Add credentials to environment variables
4. Configure webhook in PayPal dashboard pointing to `https://moxiegen.client.guacamolebox.net/api/webhooks/paypal`

## License

ISC