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

# 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

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

// 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

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

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:

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