# Cloudflare API Endpoint Security Configuration

This document details the API endpoints that should be registered in Cloudflare's **Security > Web Assets > Endpoints** for the AMSOIL DLP platform.

## Overview

The AMSOIL DLP platform operates across multiple domains:

| Environment | Domain | Purpose |
|-------------|--------|---------|
| **Production** | `amsoil.aimclear.com` | Main application (dashboard, admin, auth, checkout) |
| **Staging** | `aimclear.biz` | Pre-production testing |
| **Dev Server** | `amsoil-dlp.acdev3.com` | Development environment |
| **Dealer Sites** | `{subdomain}.myamsoil.com` | Dealer landing pages |
| **Dealer Sites** | `{subdomain}.myamsoil.ca` | Dealer landing pages (Canada) |
| **Dealer Sites** | `{subdomain}.shopamsoil.com` | Dealer landing pages (alternate) |
| **Dealer Sites** | `{subdomain}.shopamsoil.ca` | Dealer landing pages (Canada alternate) |

### API Routing Architecture

- **Main app APIs** (`amsoil.aimclear.com`): Dashboard, authentication, checkout, CMS, admin operations
- **Dealer subdomain APIs**: Contact forms and analytics only (use relative URLs, stay on same subdomain)

```
┌─────────────────────────────────────────────────────────────┐
│ Dealer Site: dealer1.myamsoil.com                           │
│   └─ POST /api/contact → dealer1.myamsoil.com/api/contact  │
│   └─ POST /api/stats/events → same subdomain               │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ Main App: amsoil.aimclear.com                               │
│   └─ All other API endpoints (auth, checkout, CMS, etc.)   │
└─────────────────────────────────────────────────────────────┘
```

## Cloudflare Pro Plan Notes

With Cloudflare Pro, the **Web Assets > Endpoints** feature provides:
- Traffic visibility per endpoint
- Abuse detection (unusual traffic patterns)
- Foundation for Business tier rate limiting (if upgraded)

**Hostname Variables**: Use `{hostvar1}` for wildcard subdomains. Cloudflare matches right-to-left:
- `{hostvar1}.myamsoil.com` matches `dealer1.myamsoil.com`, `dealer2.myamsoil.com`, etc.

---

## Part 1: Main Production App Endpoints

**Hostname**: `amsoil.aimclear.com`

### HIGH PRIORITY - External & Authentication

These endpoints are public-facing or handle sensitive authentication flows:

| Method | Path | Risk Level | Notes |
|--------|------|------------|-------|
| `POST` | `/api/webhooks/stripe` | **Critical** | Receives external traffic from Stripe servers |
| `GET` | `/api/auth/[...nextauth]` | **High** | NextAuth OAuth callbacks (Google, Apple) |
| `POST` | `/api/auth/[...nextauth]` | **High** | NextAuth sign-in/sign-out |
| `POST` | `/api/auth/register` | **High** | User registration |
| `GET` | `/api/auth/verify-email` | **High** | Email verification links |
| `POST` | `/api/auth/forgot-password` | **High** | Password reset - brute force target |
| `GET` | `/api/auth/reset-password` | **High** | Password reset token validation |
| `POST` | `/api/auth/reset-password` | **High** | Password reset submission |
| `POST` | `/api/auth/resend-verification` | **High** | Rate limit target |
| `POST` | `/api/register/complete` | **High** | Registration completion |
| `GET` | `/api/check-subdomain` | **Medium** | Subdomain availability - enumeration risk |
| `GET` | `/api/check-dealer` | **Medium** | Dealer lookup |
| `GET` | `/api/health` | **Low** | Health check - often probed by scanners |

### MEDIUM PRIORITY - Checkout & Billing

| Method | Path | Notes |
|--------|------|-------|
| `GET` | `/api/checkout/create-session` | Creates Stripe checkout sessions |
| `POST` | `/api/checkout/upgrade` | Subscription upgrades |
| `GET` | `/api/subscription/portal` | Stripe billing portal redirect |
| `GET` | `/api/subscription/preview-change` | Price preview calculations |
| `POST` | `/api/subscription/downgrade` | Subscription downgrades |
| `POST` | `/api/subscription/sidegrade` | Subscription tier changes |

### MEDIUM PRIORITY - Dealer Dashboard

| Method | Path | Notes |
|--------|------|-------|
| `GET` | `/api/dealer` | Core dealer data retrieval |
| `POST` | `/api/dealer/update` | Profile updates |
| `GET` | `/api/dealer/settings` | Settings retrieval |
| `PUT` | `/api/dealer/settings` | Settings updates |
| `GET` | `/api/dealer/leads` | Lead data access |
| `POST` | `/api/dealers/[id]/publish` | Site publishing (triggers Cloudflare DNS) |

### MEDIUM PRIORITY - CMS Operations

| Method | Path | Notes |
|--------|------|-------|
| `GET` | `/api/cms/pages` | Page listing |
| `POST` | `/api/cms/pages` | Page creation |
| `GET` | `/api/cms/pages/[id]` | Page retrieval |
| `PUT` | `/api/cms/pages/[id]` | Page updates |
| `DELETE` | `/api/cms/pages/[id]` | Page deletion |
| `GET` | `/api/cms/navigation` | Navigation retrieval |
| `POST` | `/api/cms/navigation` | Navigation creation |
| `PUT` | `/api/cms/navigation` | Navigation updates |
| `POST` | `/api/cms/publish` | CMS publishing |
| `GET` | `/api/cms/links` | Links retrieval |
| `PUT` | `/api/cms/links` | Links updates |

### MEDIUM PRIORITY - Media Upload

| Method | Path | Notes |
|--------|------|-------|
| `GET` | `/api/media` | Media listing |
| `POST` | `/api/media` | Media upload |
| `DELETE` | `/api/media/[id]` | Media deletion |
| `POST` | `/api/upload/image` | Image upload |
| `POST` | `/api/upload/cloudflare` | Cloudflare Images upload |

### LOW PRIORITY - Custom Domains & Analytics

| Method | Path | Notes |
|--------|------|-------|
| `GET` | `/api/dealer/custom-domain` | Domain status check |
| `POST` | `/api/dealer/custom-domain` | Domain registration |
| `DELETE` | `/api/dealer/custom-domain` | Domain removal |
| `POST` | `/api/dealer/custom-domain/verify` | DNS verification |
| `POST` | `/api/dealer/custom-domain/activate` | Domain activation |
| `GET` | `/api/stats/dashboard` | Dashboard analytics |
| `GET` | `/api/stats/cms` | CMS analytics |
| `POST` | `/api/revalidate` | ISR revalidation trigger |

---

## Part 2: Dealer Subdomain Endpoints

These are the **only APIs** accessible from dealer landing pages. They use relative URLs, so requests stay on the dealer's subdomain.

### Contact Form (HIGH PRIORITY - Spam Target)

| Method | Path | Hostname |
|--------|------|----------|
| `POST` | `/api/contact` | `{hostvar1}.myamsoil.com` |
| `POST` | `/api/contact` | `{hostvar1}.myamsoil.ca` |
| `POST` | `/api/contact` | `{hostvar1}.shopamsoil.com` |
| `POST` | `/api/contact` | `{hostvar1}.shopamsoil.ca` |

### Analytics Events (MEDIUM PRIORITY)

| Method | Path | Hostname |
|--------|------|----------|
| `POST` | `/api/stats/events` | `{hostvar1}.myamsoil.com` |
| `POST` | `/api/stats/events` | `{hostvar1}.myamsoil.ca` |
| `POST` | `/api/stats/events` | `{hostvar1}.shopamsoil.com` |
| `POST` | `/api/stats/events` | `{hostvar1}.shopamsoil.ca` |

---

## Part 3: Endpoints NOT to Add

These endpoints should be protected via WAF rules rather than cataloged in Endpoints:

### Dev-Only Endpoints (Block in Production)

| Path | Reason |
|------|--------|
| `/api/dev/*` | Development-only, blocked by `NODE_ENV` check |
| `/api/dev-tools/*` | Development tooling |

**Recommended WAF Rule:**
```
Rule name: Block Dev Endpoints
Expression: (http.request.uri.path contains "/api/dev")
Action: Block
```

### Admin Endpoints (Already Auth-Protected)

| Path | Reason |
|------|--------|
| `/api/admin/*` | Protected by `requireAdmin()` middleware in code |

These endpoints require admin authentication and don't benefit significantly from Cloudflare cataloging at Pro tier.

### Cron/Internal Endpoints (Protect with Secret)

| Path | Reason |
|------|--------|
| `/api/cron/*` | Should only be called by cron system with secret header |
| `/api/internal/*` | Server-to-server communication only |

**Recommended WAF Rule for Cron:**
```
Rule name: Protect Cron Endpoints
Expression: (http.request.uri.path contains "/api/cron/") and (not http.request.headers["x-cron-secret"] eq "YOUR_CRON_SECRET")
Action: Block
```

---

## Quick Reference: Copy-Paste List

### Main App (amsoil.aimclear.com)

```
# Authentication & Webhooks (HIGH)
POST   /api/webhooks/stripe           amsoil.aimclear.com
GET    /api/auth/[...nextauth]        amsoil.aimclear.com
POST   /api/auth/[...nextauth]        amsoil.aimclear.com
POST   /api/auth/register             amsoil.aimclear.com
GET    /api/auth/verify-email         amsoil.aimclear.com
POST   /api/auth/forgot-password      amsoil.aimclear.com
GET    /api/auth/reset-password       amsoil.aimclear.com
POST   /api/auth/reset-password       amsoil.aimclear.com
POST   /api/auth/resend-verification  amsoil.aimclear.com
POST   /api/register/complete         amsoil.aimclear.com
GET    /api/check-subdomain           amsoil.aimclear.com
GET    /api/check-dealer              amsoil.aimclear.com
GET    /api/health                    amsoil.aimclear.com

# Checkout & Subscriptions (MEDIUM)
GET    /api/checkout/create-session        amsoil.aimclear.com
POST   /api/checkout/upgrade               amsoil.aimclear.com
GET    /api/subscription/portal            amsoil.aimclear.com
GET    /api/subscription/preview-change    amsoil.aimclear.com
POST   /api/subscription/downgrade         amsoil.aimclear.com
POST   /api/subscription/sidegrade         amsoil.aimclear.com

# Dealer Dashboard (MEDIUM)
GET    /api/dealer                    amsoil.aimclear.com
POST   /api/dealer/update             amsoil.aimclear.com
GET    /api/dealer/settings           amsoil.aimclear.com
PUT    /api/dealer/settings           amsoil.aimclear.com
GET    /api/dealer/leads              amsoil.aimclear.com
POST   /api/dealers/[id]/publish      amsoil.aimclear.com

# CMS Operations (MEDIUM)
GET    /api/cms/pages                 amsoil.aimclear.com
POST   /api/cms/pages                 amsoil.aimclear.com
GET    /api/cms/pages/[id]            amsoil.aimclear.com
PUT    /api/cms/pages/[id]            amsoil.aimclear.com
DELETE /api/cms/pages/[id]            amsoil.aimclear.com
GET    /api/cms/navigation            amsoil.aimclear.com
POST   /api/cms/navigation            amsoil.aimclear.com
PUT    /api/cms/navigation            amsoil.aimclear.com
POST   /api/cms/publish               amsoil.aimclear.com
GET    /api/cms/links                 amsoil.aimclear.com
PUT    /api/cms/links                 amsoil.aimclear.com

# Media Upload (MEDIUM)
GET    /api/media                     amsoil.aimclear.com
POST   /api/media                     amsoil.aimclear.com
DELETE /api/media/[id]                amsoil.aimclear.com
POST   /api/upload/image              amsoil.aimclear.com
POST   /api/upload/cloudflare         amsoil.aimclear.com

# Custom Domains & Stats (LOW)
GET    /api/dealer/custom-domain           amsoil.aimclear.com
POST   /api/dealer/custom-domain           amsoil.aimclear.com
DELETE /api/dealer/custom-domain           amsoil.aimclear.com
POST   /api/dealer/custom-domain/verify    amsoil.aimclear.com
POST   /api/dealer/custom-domain/activate  amsoil.aimclear.com
GET    /api/stats/dashboard                amsoil.aimclear.com
GET    /api/stats/cms                      amsoil.aimclear.com
POST   /api/revalidate                     amsoil.aimclear.com
```

### Dealer Subdomains

```
# Contact Forms (HIGH - spam target)
POST   /api/contact        {hostvar1}.myamsoil.com
POST   /api/contact        {hostvar1}.myamsoil.ca
POST   /api/contact        {hostvar1}.shopamsoil.com
POST   /api/contact        {hostvar1}.shopamsoil.ca

# Analytics Events (MEDIUM)
POST   /api/stats/events   {hostvar1}.myamsoil.com
POST   /api/stats/events   {hostvar1}.myamsoil.ca
POST   /api/stats/events   {hostvar1}.shopamsoil.com
POST   /api/stats/events   {hostvar1}.shopamsoil.ca
```

---

## Summary

| Category | Count |
|----------|-------|
| Main App Endpoints | 48 |
| Dealer Subdomain Endpoints | 8 |
| **Total** | **56** |

---

## Related Documentation

- [Cloudflare Production Deployment](./CLOUDFLARE_PRODUCTION_DEPLOYMENT.md) - DNS automation and deployment guide
- [Rate Limiting](./RATE_LIMITING.md) - Application-level rate limiting
- [Operations Checklist](./OPERATIONS_CHECKLIST.md) - Daily/weekly/monthly operations

---

## Changelog

| Date | Change |
|------|--------|
| 2025-12-23 | Initial documentation created |