gandi

全面的 Gandi 域名注册商集成，用于域名和 DNS 管理。注册和管理域、创建/更新/删除 DNS 记录（A、AAAA、CNAME、MX、TXT、SRV 等）、配置电子邮件转发和别名、检查 SSL 证书状态、创建 DNS 快照以安全回滚、批量更新区域文件以及监控域过期。支持多域管理、区域文件导入/导出以及自动DNS备份。包括带有安全控制的只读操作和破坏性操作。

## 概述（中文）

全面的 Gandi 域名注册商集成，用于域名和 DNS 管理。注册和管理域、创建/更新/删除 DNS 记录（A、AAAA、CNAME、MX、TXT、SRV 等）、配置电子邮件转发和别名、检查 SSL 证书状态、创建 DNS 快照以安全回滚、批量更新区域文件以及监控域过期。支持多域管理、区域文件导入/导出以及自动DNS备份。包括带有安全控制的只读操作和破坏性操作。

## 原文

# Gandi Domain Registrar Skill

Comprehensive Gandi domain registrar integration for Moltbot.

**Status:** ✅ Phase 2 Complete - DNS modification & snapshots functional

## ⚠️ Security Warning

**This skill can perform DESTRUCTIVE operations on your Gandi account:**

- **DNS Modification:** Add, update, or delete DNS records (can break websites/email)
- **Email Management:** Create, modify, or delete email forwards (can intercept emails)
- **Domain Registration:** Register domains (creates financial transactions)
- **Bulk Operations:** Replace all DNS records at once (cannot be undone except via snapshots)

**Before running ANY script:**
1. Review the script code to understand what it does
2. Create DNS snapshots before bulk changes (`create-snapshot.js`)
3. Use read-only Personal Access Tokens where possible
4. Test on non-production domains first
5. Understand that some operations cannot be undone

**Destructive scripts** (⚠️ modify or delete data):
- `add-dns-record.js`, `delete-dns-record.js`, `update-dns-bulk.js`
- `add-email-forward.js`, `update-email-forward.js`, `delete-email-forward.js`
- `restore-snapshot.js` (replaces current DNS)

**Read-only scripts** (✅ safe, no modifications):
- `list-domains.js`, `list-dns.js`, `list-snapshots.js`
- `list-email-forwards.js`, `check-domain.js`, `check-ssl.js`

📖 **For complete script documentation:** See [SCRIPTS.md](SCRIPTS.md) for detailed information about:
- What each script does
- Network operations and API calls
- Security implications
- Undo/recovery procedures
- Audit workflow recommendations

## Current Capabilities

### Phase 1 (Complete)
- ✅ Personal Access Token authentication
- ✅ List domains in your account
- ✅ Get domain details (expiration, status, services)
- ✅ List DNS records for domains
- ✅ View domain and DNS information
- ✅ **Domain availability checking** ([#4](https://github.com/chrisagiddings/moltbot-gandi-skill/issues/4))
- ✅ **Smart domain suggestions with variations** ([#4](https://github.com/chrisagiddings/moltbot-gandi-skill/issues/4))
- ✅ SSL certificate status checker
- ✅ Error handling and validation

### Phase 2 (Complete)
- ✅ **Add/update DNS records** (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, PTR)
- ✅ **Delete DNS records**
- ✅ **Bulk DNS operations** (replace all records at once)
- ✅ **DNS zone snapshots** (create, list, restore)
- ✅ **Email forwarding** (create, list, update, delete forwards including catch-all)
- ✅ **Record validation** (automatic validation for each record type)
- ✅ **Safety features** (automatic snapshots before bulk changes, confirmation prompts)

## Coming Soon (Phase 3+)

- Domain registration
- Multi-organization support ([#1](https://github.com/chrisagiddings/moltbot-gandi-skill/issues/1))
- Gateway Console configuration ([#3](https://github.com/chrisagiddings/moltbot-gandi-skill/issues/3))
- Domain renewal management
- DNSSEC configuration
- Certificate management
- Email mailbox management (beyond forwarding)

## Setup

### Step 1: Create Personal Access Token

**⚠️ Security Recommendation:** Use the **minimum required scopes** for your use case.

1. Go to [Gandi Admin → Personal Access Tokens](https://admin.gandi.net/organizations/account/pat)
2. Click **"Create a token"**
3. Select your organization
4. Choose scopes:
   
   **Read-Only (Recommended for viewing only):**
   - ✅ Domain: read (required for listing domains)
   - ✅ LiveDNS: read (required for viewing DNS records)
   - ✅ Email: read (required for viewing email forwards)
   
   **Write Access (Required for modifications - use with caution):**
   - ⚠️ LiveDNS: write (enables DNS modification, deletion, bulk operations)
   - ⚠️ Email: write (enables email forward creation, updates, deletions)

5. Copy the token (you won't see it again!)

**Security Best Practices:**
- Create separate tokens for read-only vs. write operations
- Use read-only tokens for routine checks/monitoring
- Only use write tokens when actively making changes
- Rotate tokens regularly (every 90 days recommended)
- Delete unused tokens immediately
- **Never share or commit tokens to version control**

### Step 2: Store Token

Scripts check for credentials in priority order:
1. **`GANDI_API_TOKEN` environment variable** (checked first)
2. **`~/.config/gandi/api_token` file** (fallback if env var not set)

**Choose the method that fits your workflow:**

#### Option A: Environment Variable (Recommended for CI/CD)

```bash
# Set environment variable (replace YOUR_PAT with actual token)
export GANDI_API_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN"

# Add to shell profile for persistence (~/.bashrc, ~/.zshrc, etc.)
echo 'export GANDI_API_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN"' >> ~/.bashrc
```

**Benefits:**
- ✅ CI/CD friendly (standard pattern for automation)
- ✅ Container-ready (no file mounts needed)
- ✅ Works with secret management tools (1Password, Vault, etc.)
- ✅ Easy to switch between multiple tokens

#### Option B: File-based (Recommended for local development)

```bash
# Create config directory
mkdir -p ~/.config/gandi

# Store your token (replace YOUR_PAT with actual token)
echo "YOUR_PERSONAL_ACCESS_TOKEN" > ~/.config/gandi/api_token

# Secure the file (owner read-only)
chmod 600 ~/.config/gandi/api_token
```

**Benefits:**
- ✅ Token persists across shell sessions
- ✅ Secure file permissions (0600 = owner read-only)
- ✅ No risk of exposing token in process list
- ✅ Works offline (no external dependencies)

### Step 3: Install Dependencies

**Required:** Node.js >= 18.0.0

```bash
cd gandi-skill/scripts

# Install npm dependencies
npm install

# Verify installation
npm list --depth=0
```

**Expected packages:**
- axios (HTTP client for Gandi API)
- Any other dependencies listed in package.json

**Troubleshooting:**
- If `node` or `npm` not found: Install Node.js from [nodejs.org](https://nodejs.org/)
- If permission errors: Don't use `sudo` - fix npm permissions or use nvm
- If package errors: Delete `node_modules/` and `package-lock.json`, then `npm install` again

### Step 4: Test Authentication

```bash
cd gandi-skill/scripts
node test-auth.js
```

Expected output:
```
✅ Authentication successful!

Your organizations:
  1. Personal Account (uuid-here)
     Type: individual

🎉 You're ready to use the Gandi skill!
```

### Step 5: Setup Contact Information (Optional, for Domain Registration)

If you plan to register domains, save your contact information once for reuse:

```bash
cd gandi-skill/scripts
node setup-contact.js
```

**The script will prompt for:**
- Name (first and last)
- Email address
- Phone number (international format: +1.5551234567)
- Street address
- City
- State/Province (for US: 2-letter code like OH, automatically formatted to US-OH)
- ZIP/Postal code
- Country (2-letter code: US, FR, etc.)
- Type (individual or company)
- **Privacy preference:** Retain or auto-purge contact after registration

**Contact information is saved to:**
- `~/.config/gandi/contact.json`
- Permissions: 600 (owner read-write only)
- Outside the skill directory (never committed to git)

**Privacy Options:**

1. **RETAIN (default):** Keep contact saved for future registrations
   - Best for frequent domain registrations
   - Setup once, use forever
   - Delete manually anytime with `delete-contact.js`

2. **PURGE:** Auto-delete contact after each registration
   - Best for privacy-conscious users
   - Contact info only exists during registration
   - Must re-enter for next registration

**Managing saved contact:**
```bash
# View current contact
node view-contact.js

# Update contact info or privacy preference
node setup-contact.js

# Delete saved contact manually
node delete-contact.js

# Delete without confirmation
node delete-contact.js --force
```

**One-time purge override:**
```bash
# Register and delete contact (even if