Gandi

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 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)
• ✅ Smart domain suggestions with variations (#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)
• Gateway Console configuration (#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

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)

# 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)

# 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

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

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:

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:

# 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:

# Register and delete contact (even if preference is "retain")
node register-domain.js example.com --purge-contact

Usage Examples

List Your Domains

node list-domains.js

Output shows:

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

List DNS Records

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:

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:
  Extension: com

Smart Domain Suggestions

Find available alternatives with TLD variations and name modifications:

# Check all configured TLDs + variations
node suggest-domains.js example

# Check specific TLDs only
node suggest-domains.js example --tlds com,net,io

# Skip name variations (only check TLDs)
node suggest-domains.js example --no-variations

# Output as JSON
node suggest-domains.js example --json

Name Variation Patterns:

1. Hyphenated: Adds hyphens between word boundaries (example → ex-ample)
2. Abbreviated: Removes vowels (example → exmpl)
3. Prefix: Adds common prefixes (example → get-example, my-example)
4. Suffix: Adds common suffixes (example → example-app, example-hub)
5. Numbers: Appends numbers (example → example2, example3)

Example Output:

🔍 Checking availability for: example

📊 Checking 13 TLDs and generating variations...

═══════════════════════════════════════════════════════
📋 EXACT MATCHES (Different TLDs)
═══════════════════════════════════════════════════════

✅ Available:

  example.net                    12.00 EUR
  example.io                     39.00 EUR
  example.dev                    15.00 EUR

❌ Unavailable:

  example.com                    (unavailable)
  example.org                    (unavailable)

═══════════════════════════════════════════════════════
🎨 NAME VARIATIONS
═══════════════════════════════════════════════════════

Hyphenated:

  ✅ ex-ample.com                12.00 EUR

Prefix:

  ✅ get-example.com             12.00 EUR
  ✅ my-example.com              12.00 EUR

Suffix:

  ✅ example-app.com             12.00 EUR
  ✅ example-io.com              12.00 EUR

═══════════════════════════════════════════════════════
📊 SUMMARY: 8 available domains found
═══════════════════════════════════════════════════════

Configuration

Domain checker configuration is stored in gandi-skill/config/domain-checker-defaults.json.

Structure:

{
  "tlds": {
    "mode": "extend",
    "defaults": ["com", "net", "org", "info", "io", "dev", "app", "ai", "tech"],
    "custom": []
  },
  "variations": {
    "enabled": true,
    "patterns": ["hyphenated", "abbreviated", "prefix", "suffix", "numbers"],
    "prefixes": ["get", "my", "the", "try"],
    "suffixes": ["app", "hub", "io", "ly", "ai", "hq"],
    "maxNumbers": 3
  },
  "rateLimit": {
    "maxConcurrent": 3,
    "delayMs": 200,
    "maxRequestsPerMinute": 100
  },
  "limits": {
    "maxTlds": 5,
    "maxVariations": 10
  }
}

Rate Limiting & Limits:

• maxConcurrent: Maximum concurrent API requests (default: 3)
• delayMs: Delay between requests in milliseconds (default: 200ms)
• maxRequestsPerMinute: Hard limit on requests per minute (default: 100, Gandi allows 1000)
• maxTlds: Maximum TLDs to check in suggest-domains.js (default: 5)
• maxVariations: Maximum name variations to generate (default: 10)

These limits ensure good API citizenship and prevent overwhelming Gandi's API.

TLD Modes:

• "extend": Use defaults + custom TLDs (merged list)
• "replace": Use only custom TLDs (ignore defaults)

Gateway Console Integration:

When Gateway Console support is added (#3), configuration will be available at:

skills:
  entries:
    gandi:
      config:
        domainChecker:
          tlds:
            mode: extend
            defaults: [...]
            custom: [...]
          variations:
            enabled: true
            patterns: [...]

See docs/gateway-config-design.md for complete configuration architecture.

DNS Management (Phase 2)

Add or Update DNS Records

Create or update individual DNS records:

# Add an A record for root domain
node add-dns-record.js example.com @ A 192.168.1.1

# Add www subdomain pointing to root
node add-dns-record.js example.com www CNAME @

# Add MX record for email
node add-dns-record.js example.com @ MX "10 mail.example.com."

# Add TXT record for SPF
node add-dns-record.js example.com @ TXT "v=spf1 include:_spf.google.com ~all"

# Add with custom TTL (5 minutes)
node add-dns-record.js example.com api A 192.168.1.10 300

Supported record types: A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, PTR

Delete DNS Records

Remove specific DNS records:

# Delete old A record
node delete-dns-record.js example.com old A

# Delete with confirmation prompt
node delete-dns-record.js example.com test CNAME

# Delete without confirmation
node delete-dns-record.js example.com old A --force