gandi-skill

---
name: gandi
description: "Comprehensive Gandi domain registrar integration for domain and DNS management. Register and manage domains, create/update/delete DNS records (A, AAAA, CNAME, MX, TXT, SRV, and more), configure email forwarding and aliases, check SSL certificate status, create DNS snapshots for safe rollback, bulk update zone files, and monitor domain expiration. Supports multi-domain management, zone file import/export, and automated DNS backups. Includes both read-only and destructive operations with safety controls."
metadata: {"openclaw":{"disable-model-invocation":true,"capabilities":["dns-modification","email-management","domain-registration","destructive-operations"],"credentials":{"type":"file","location":"~/.config/gandi/api_token","description":"Gandi Personal Access Token (PAT)","permissions":600},"requires":{"bins":["node","npm"]}}}
---

# 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 preference is "retain")
node register-domain.js example.com --purge-contact
```

## Usage Examples

### List Your Domains

```bash
node list-domains.js
```

Output shows:
- Domain names
- Expiration dates
- Auto-renewal status
- Services (LiveDNS, Email, etc.)
- Organization ownership

### List DNS Records

```bash
node list-dns.js example.com
```

Output shows:
- All DNS records grouped by type
- TTL values
- Record names and values
- Nameservers

### Using from Moltbot

Once configured, you can use natural language:

> "List my Gandi domains"

> "Show DNS records for example.com"

> "When does example.com expire?"

> "Is auto-renewal enabled for example.com?"

## Domain Availability Checking

### Check Single Domain

Check if a specific domain is available for registration:

```bash
node check-domain.js example.com
```

**Features:**
- Shows availability status (available/unavailable/pending/error)
- Displays pricing information (registration, renewal, transfer)
- Lists supported features (DNSSEC, LiveDNS, etc.)
- Shows TLD information

**Example Output:**
```
🔍 Checking availability for: example.com

Domain: example.com

✅ Status: AVAILABLE

💰 Pricing:
  1 year: 12.00 EUR (+ 2.40 tax)
  2 years: 24.00 EUR (+ 4.80 tax)

📋 Supported Features:
  • create
  • dnssec
  • livedns

🌐 TLD Information:
  Ex

... (truncated)