# Integration Instructions for api.aethex.cloud

## Quick Start

This package contains everything you need to add domain verification to api.aethex.cloud.

## Files Included

```
integration-package/
├── routes/
│   └── domainRoutes.js          ← API routes
├── utils/
│   └── domainVerification.js    ← Core logic
├── migrations/
│   └── 001_domain_verifications.sql  ← Database schema
└── frontend/
    └── components/              ← React components
        ├── DomainVerification.jsx
        ├── DomainVerification.css
        ├── VerifiedDomainBadge.jsx
        └── VerifiedDomainBadge.css
```

## Step 1: Backend Integration (api.aethex.cloud)

### 1.1 Copy Backend Files

```bash
# In your api.aethex.cloud project root:
cp integration-package/routes/domainRoutes.js ./routes/
cp integration-package/utils/domainVerification.js ./utils/
```

### 1.2 Add Routes to Your Express App

In your `app.js`, `server.js`, or main API file:

```javascript
// Add this import with your other routes
const domainRoutes = require('./routes/domainRoutes');

// Add this route mount (after your other middleware)
app.use('/api/passport/domain', domainRoutes);
```

### 1.3 Install Dependencies (if needed)

```bash
npm install ethers --save
```

### 1.4 Add Environment Variables

Add to your `.env`:

```env
# Blockchain Configuration (for .aethex domain verification)
RPC_ENDPOINT=https://polygon-mainnet.g.alchemy.com/v2/3-qjAZSq7DyEuJQKH3KPm
FREENAME_REGISTRY_ADDRESS=0x... # Add actual contract address when available
```

### 1.5 Run Database Migration

The schema is already on your Supabase database! If you need to run it again:

```bash
# Via Supabase Dashboard:
# Go to: https://supabase.com/dashboard/project/kmdeisowhtsalsekkzqd/editor
# Copy and run SQL from: integration-package/migrations/001_domain_verifications.sql
```

### 1.6 Test the API

```bash
# Test the endpoint
curl https://api.aethex.cloud/api/passport/domain/status \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Expected response:
# {"hasVerifiedDomain": false}
```

## Step 2: Frontend Integration (aethex.tech)

### 2.1 Copy Frontend Components

```bash
# In your aethex.tech frontend project:
cp -r integration-package/frontend/components/* ./src/components/
```

### 2.2 Add to Your Profile/Settings Page

```javascript
import DomainVerification from './components/DomainVerification';
import VerifiedDomainBadge from './components/VerifiedDomainBadge';

// In your profile settings:
<DomainVerification />

// To display verified domain on profile:
<VerifiedDomainBadge 
  verifiedDomain={user.verified_domain}
  verifiedAt={user.domain_verified_at}
/>
```

## Step 3: Verify Everything Works

### Backend Check
```bash
# Should return 200
curl https://api.aethex.cloud/health

# Should return user's verification status
curl https://api.aethex.cloud/api/passport/domain/status \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Frontend Check
1. Go to your profile page on aethex.tech
2. You should see "Verify Your Domain" section
3. Enter a domain you own
4. Follow DNS verification flow

## API Endpoints Added

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/passport/domain/request-verification` | Generate verification token |
| POST | `/api/passport/domain/verify` | Verify domain ownership (DNS or blockchain) |
| GET | `/api/passport/domain/status` | Get user's current verification status |

## Authentication

These routes use your existing authentication middleware. They expect:
- `Authorization: Bearer <JWT_TOKEN>` header
- Middleware that sets `req.user.id` and `req.user.email`

If your auth middleware works differently, update `domainRoutes.js` line 4.

## Database Schema

Tables created:
- `domain_verifications` - Stores verification requests
- `users` table extended with:
  - `verified_domain` (VARCHAR)
  - `domain_verified_at` (TIMESTAMP)

## Troubleshooting

### "Module not found" errors
- Make sure you copied files to the correct directories
- Check your require paths match your project structure

### "Database connection error"
- Verify DATABASE_URL in your api.aethex.cloud .env
- Should be the same Supabase connection string

### "401 Unauthorized"
- Check your auth middleware is running before domain routes
- Verify JWT tokens are being passed correctly

## Support

Questions? Check the main README.md or open an issue.

---

**Ready to integrate?** Start with Step 1.1! 🚀